StateBlock

O StateBlock é o bloco de estado do Admin: o que fazer quando uma região não tem conteúdo para mostrar. Ele monta o EmptyState do Pro com título, descrição e uma ação, e declara o tom do estado: vazio, erro ou sem permissão. Para carregamento use Skeleton; para um aviso que convive com o conteúdo, use Alert.

import { StateBlock } from "@rastreio-x/ui";

Padrão (vazio)

O tom padrão é empty. O título nomeia o que falta, a descrição diz como preencher e a ação é o próximo passo.

Erro

tone="error" marca o bloco como role="alert". A ação é quase sempre "Tentar de Novo".

Sem permissão

tone="forbidden" explica quem pode ver a tela e como pedir acesso. Não oferece ação que a pessoa não pode executar.

Comparando os tons

Os três tons têm a mesma estrutura e a mesma aparência hoje. A diferença é semântica: error ganha role="alert", e cada tom leva a classe rx-state-block--<tom>, um gancho para estilo futuro. Por isso o texto precisa dizer o estado; não conte com a cor.

Só título

Sem descrição nem ação, para vazios que se resolvem sozinhos, como uma janela de tempo sem eventos.

No Admin

Dentro de um Widget, o bloco ocupa o corpo no lugar da tabela ou da lista.

Anatomia

O bloco é uma peça só, sem mídia de ícone: título (h2), descrição opcional e a área de ação.

Propriedades

Outras props (como data-testid) passam para o EmptyState.

Animações

O StateBlock não anima: o bloco aparece e some sem transição. O selo acima vem do arquivo page.tsx, que também define o ViewTabs (esse sim usa Motion), e não do bloco. Se você animar a entrada, respeite prefers-reduced-motion.

Acessibilidade

• O título é um h2: ajuste a hierarquia da tela para não pular níveis (o h1 é do PageHeader).
• tone="error" aplica role="alert", então a falha é anunciada na hora; os outros tons são texto comum.
• O tom não muda a aparência: título e descrição é que dizem o que houve.
• A ação é um botão ou link normal, com rótulo de verbo.

Boas práticas

• Uma ação por bloco, em Title Case curto.
• Em forbidden, nomeie quem tem acesso; não mostre uma ação bloqueada.
• Use o tom error só para falhas reais; um vazio por filtro é empty.
• Para tabelas, passe o vazio por renderEmptyState do DataGrid.

Relacionados

• EmptyState sobre o qual o bloco é montado.
• Button para a ação.
• Widget que hospeda o bloco.
• Skeleton para o carregamento.