Widget

Painel de métrica, resumo ou tabela, com cabeçalho, conteúdo e rodapé.

O Widget (do HeroUI Pro) agrupa um indicador, um resumo ou uma tabela com título e contexto. É o painel padrão das telas do Admin; a hierarquia vem da superfície e da sombra suave do tema. Para tabelas, coloque um DataGrid dentro do Widget; para um bloco de texto solto, use Card.

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

Padrão

O título e a descrição ficam no cabeçalho; a descrição é um texto curto de contexto (período, fuso, contagem).

Indicador

Com NumberValue o número é formatado pelo locale (pt-BR: milhar com ponto, vírgula decimal) e o TrendChip mostra a variação.

Com rodapé

O rodapé guarda contexto ou uma ação de apoio, como "Ver Extrato" ou "Carregar Mais". A ação principal da tela não vai aqui.

Com legenda

Widget.Legend e Widget.LegendItem nomeiam as séries de um gráfico. A cor vem dos tokens de gráfico (--chart-1 a --chart-5), que nunca representam estado.

Região nomeada

Em telas do Admin o Widget é uma região: role="region" com aria-labelledby apontando para o h2 que fica dentro de Widget.Title (que é um span).

Anatomia

Widget
├── Widget.Content
├── Widget.Description
├── Widget.Footer
├── Widget.Header
├── Widget.Legend
├── Widget.LegendItem
└── Widget.Title

Widget.Header, Widget.Title e Widget.Description: o cabeçalho.
Widget.Content: o corpo; use p-0 para tabelas e listas de borda a borda.
Widget.Footer: o rodapé do painel.
Widget.Legend e Widget.LegendItem: legenda de gráfico.

Propriedades

Raiz (Widget):

Widget
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`render`	`DOMRenderFunction<E, undefined>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`React.JSX.IntrinsicElements[E]['style']`	-	Estilos em linha aplicados ao elemento.

Cabeçalho (Widget.Header):

Widget.Header
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`style`	`React.CSSProperties`	-	Estilos em linha aplicados ao elemento.

Item de legenda (Widget.LegendItem):

Widget.LegendItem
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`color`*	`string`	-	Cor do ponto da legenda: um valor CSS ou uma variável.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`style`	`React.CSSProperties`	-	Estilos em linha aplicados ao elemento.

Animações

Sem movimento
indicativo

O Widget é estático. O recuo do título e o do rodapé seguem o miolo por um ajuste global da fachada (styles.css, camada components), não por tela: não reponha px-* no cabeçalho.

Acessibilidade

O Widget é um div; transforme-o em região com role="region" e aria-labelledby quando for um painel de tela.
Widget.Title é um span: ponha o h2 dentro dele para manter a hierarquia de títulos.
Um KPI dentro de um Widget deve usar KPITitle e KPIValue da fachada, não KPI.Title e KPI.Value (viram dt e dd soltos).
Cor de série de gráfico não carrega estado: acompanhe com texto.

Boas práticas

Faça

Um título curto por widget, em Title Case, e a tabela de borda a borda com p-0.

Evite

Widget dentro de Widget, ou botão de ação principal escondido no rodapé.

Um título curto por widget, em Title Case.
Não coloque um Widget dentro de outro Widget.
KPIGroup className="bg-transparent shadow-none" ao colocar KPIs no miolo: o miolo já é a superfície.
Use o rodapé só para contexto (data de atualização) e ações de apoio.

Relacionados

DataGrid para tabelas dentro do painel.
Card para blocos de texto fora do padrão de painel.
Skeleton para o carregamento do conteúdo do painel.