Stat
Padrão
Vendas em agosto
R$ 246,7K
alta de 20% sobre julho
Com tendência
Vendas em agosto
R$ 246,7K
alta de 20% sobre julho
Subir é ruim
Devoluções
6
alta de 50% sobre julho
A fileira de painel
Vendas
R$ 246,7K
alta de 20% sobre julho
Recebido
R$ 198,3K
alta de 3% sobre julho
Devoluções
6
alta de 50% sobre julho
A variação que não é porcentagem
Vendas
R$ 246,7K
alta de R$ 12,4K sobre julho
Pedidos
1.240
alta de 86 sobre julho
Taxa de devolução
4,2%
alta de 0,8% sobre julho
import { Stat } from '@rivocode/ui'Quando usar
O número de painel: rótulo, valor, variação e tendência, na hierarquia que todo painel reinventa na mão.
O valor chega formatado porque formatar é decisão de domínio: dinheiro sai
abreviado do currencyShort, contagem sai crua, percentual traz o sinal.
delta é a variação, com deltaLabel dizendo contra o quê ("sobre julho").
delta={0} sai neutro: sem seta, na cor do texto secundário, e sem "alta de"
para o leitor de tela, porque não mudar não é subir.
Quando subir é ruim (vencidas, custo, inadimplência), passe
invert: a seta continua apontando para onde o número foi, o que inverte é o
julgamento da cor. A direção também é falada para leitor de tela, não só
pintada.
A tendência entra pelo slot chart, com a Sparkline de @rivocode/ui/chart:
<Stat
label="Vendas em agosto"
value={currencyShort(246_700)}
delta={20}
deltaLabel="sobre julho"
chart={<Sparkline data={TREND} variant="area" trend="auto" className="h-8 w-full" />}
/>
O núcleo não importa a Sparkline de propósito: ela traz o recharts junto, e
um painel sem gráfico não deveria pagar por ele.
O valor e a variação saem em tabular-nums: numa fileira de cartões o
algarismo tem largura fixa, e "R$ 111,1K" não fica mais estreito que
"R$ 999,9K".
O ícone
icon sai solto, à esquerda do rótulo e no tom dele (text-fg-muted, 16px),
sem caixa e sem fundo tingido. Ícone dentro de quadrado de bg-accent-subtle
decora sem informar, e é a marca mais citada de painel gerado: quem chama a
atenção no cartão é o número, e o ícone só diz de que ele é.
<Stat label="Notas emitidas" value="128" icon={<FileText />} delta={12} />
A variação nem sempre é porcentagem
Um delta em reais ou em pontos-base não leva por-cento. deltaFormat é o
mesmo format de Progress, Meter e Slider, nome de formatador da casa ou
função própria:
<Stat label="Vendas" value={currencyShort(246_700)} delta={12_400}
deltaFormat="currencyShort" deltaLabel="sobre julho" />
Sem ele, percent, que é o que sempre saiu. O percent da casa arredonda para
inteiro; para casa decimal, passe a função: deltaFormat={(value) => percent(value, 1)}.
O que chega ao formatador é o módulo do delta: quem carrega o sinal é a
seta, e o "alta de"/"queda de" que o leitor de tela ouve antes do número.
Movimento
O conteúdo do cartão esmaece na montagem (animate-appear, --rc-duration-base), e a moldura fica parada: o número chega, o cartão já estava ali. Os dígitos não contam do zero, de propósito: número que corre até o valor é ilegível enquanto corre, e é ele que a pessoa veio ler.
Quando não usar
Para quanto de uma capacidade está em uso, com teto conhecido, use Meter: o
Stat mostra o número e a variação, e não diz quanto falta para o limite.
Número que precisa ser julgado por faixas (em dia, atenção, crítico) é o
ChartGauge.
Folha de detalhes, com vários pares de rótulo e valor sem variação nem
tendência, é DescriptionList: um Stat por campo transforma o cadastro num
painel que ele não é.
No React Native
Traduz com o value já formatado, o delta numérico escrito pelo mesmo deltaFormat do web, o invert e o slot chart, que a Sparkline nativa preenche.
A seta da variação é o ArrowUpRight ou o ArrowDownRight do lucide-react-native, os mesmos do web, e não um caractere. A linha toda é um nó só para o leitor de tela, que ouve "alta de" ou "queda de" antes do número, como o texto escondido do web.
O cartão que se toca é onPress ou href, com o selected do web. O onClick vira onPress, como em todo o pacote; o href abre pelo Linking, como o do Link, e com os dois juntos quem navega é o onPress, que é por onde o router do app entra. O render não atravessa, porque não há âncora a trocar. O cartão inteiro vira um nó só, button ou link, e o leitor ouve o rótulo, o valor e a variação; sob o dedo ele escurece em bg-selected, como as outras linhas que se tocam. O selected pinta a borda em accent-text com 2pt por cima da borda, sem mexer no tamanho, e sai em accessibilityState.
API
| Prop | Tipo | Padrão |
|---|---|---|
labelobrigatória0.4.0O que o numero mede: "Faturado em agosto". | string | sem padrão |
valueobrigatória0.4.0O numero, ja formatado: `currencyShort(246_700)`. | ReactNode | sem padrão |
actions0.5.0O canto direito do cartao: o menu de tres pontos, um botao de acao. | ReactNode | sem padrão |
chart0.4.0A tendencia embaixo do numero. | ReactNode | sem padrão |
delta0.4.0A variacao. | number | sem padrão |
deltaFormatComo a variacao e escrita: nome de formatador da casa (`percent`, `currencyShort`, `integer`...) ou funcao propria. | Format | "percent" |
deltaLabel0.4.0Contra o que se compara: "sobre julho". | string | sem padrão |
deltaVariant0.5.0A variacao como pastilha preenchida, que e a convencao dominante em painel, ou como texto com seta, que e o padrao daqui. | "pill" | "text" | "text" |
footer0.5.0A faixa de baixo: meta com barra, comparacao, texto de apoio. | ReactNode | sem padrão |
hint0.4.0Explicacao curta atras de um botao de informacao. | string | sem padrão |
hrefTorna o cartao inteiro um link para este endereco, como o `onClick` faz com o botao. | string | sem padrão |
icon0.5.0O icone solto, a esquerda do rotulo e no tom dele: 16px, sem caixa nem fundo tingido, sem `size`. | ReactNode | sem padrão |
invert0.4.0Subir e ruim aqui: vencidas, custo, inadimplencia. | boolean | sem padrão |
labelsOs textos da peca, para trocar o idioma: `about` e o nome do botao de informacao do `hint`, e recebe o `label`. | Partial<StatLabels> | sem padrão |
onClickTorna o cartao inteiro um botao: o clique em qualquer ponto dele chama isto, o Tab para nele uma vez, e o nome que o leitor de tela ouve e o rotulo, o valor e a variacao. | ((event: MouseEvent<HTMLElement, MouseEvent>) => void) | sem padrão |
renderTroca o elemento que cobre o cartao, para o link do roteador: `render={<Link to="/lojas/centro" />}`. | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
selectedO cartao escolhido da fileira, o filtro de agora. | boolean | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.