Visão geral
Visão geral dos charts do EDS — quando usar cada tipo, estados, legenda interativa e acessibilidade.
Os charts do EletroDS são componentes prontos para dashboards e telas analíticas. Cada tipo vive dentro de um Card, usa a paleta de tokens de chart (light/dark automático), legenda clicável no rodapé e tooltip no hover. A API é orientada aos dados do produto — você passa o dataset e as chaves, não opções brutas do motor de render.
Quando usar cada tipo
Escolha pela pergunta que o gráfico responde, não pela aparência. Cada família tem página própria com variantes e exemplos.
| Tipo | Use quando | Quando NÃO usar | Doc |
|---|---|---|---|
| Area | Evolução temporal de uma métrica, com ênfase no volume sob a linha | Comparar categorias não temporais → use Bar | Area Charts |
| Line | Tendência ao longo do tempo, uma ou mais séries comparáveis | Poucos pontos sem continuidade temporal → use Bar | Line Charts |
| Bar / Horizontal Bar | Comparar categorias discretas; horizontal quando os rótulos são longos ou há muitas categorias | Mostrar partes de um todo → use Pie/Donut | Bar Charts |
| Pie / Donut | Partes de um todo, 2 a 6 categorias com proporções claras; donut quando há um valor agregado central | Muitas fatias finas → use Bar ou top N + "Outros" | Pie & Donut |
| Radar | Comparar várias dimensões de um mesmo item (perfil multidimensional) | Tendência ou ranking → use Line ou Bar | Radar Charts |
| Radial | Progresso (gauge value/max), multi-anel ou gauge stacked | Comparar séries entre si → use Bar | Radial Charts |
Analytics (KpiCard, TagCloud) | Indicador único de destaque e nuvem de tags | Séries com eixos → use os tipos XY acima | Analytics |
A grade acima mostra um exemplo de cada tipo. Os charts XY (Area, Line, Bar, Horizontal Bar) compartilham a mesma base de props e comportamento; pie, donut, radar e radial recebem dados no formato { label, value } ou séries específicas — os detalhes ficam nas páginas das famílias.
Variantes de estilo e comportamento
- Modo de exibição: o modo padrão mostra título, eixos, legenda e tooltip. O modo compacto suprime tudo isso e deixa só o desenho — ideal para o gráfico viver dentro de um KPI ou widget pequeno.
- Sem card: o modo "bare" renderiza apenas o gráfico, sem
Cardnem título, para reuso dentro de um Widget que já traz a moldura. - Empilhamento: barras aceitam séries empilhadas (stacked) quando o total da categoria importa tanto quanto a composição.
- Tooltip e cores: ver as seções Tooltips e Cores das séries abaixo.
Legenda interativa
Todos os charts (exceto o radial sem rótulo) trazem a legenda no rodapé. Clicar num item oculta ou exibe a série correspondente — útil para isolar uma métrica sem recarregar dados. A série não-selecionada perde opacidade em vez de sumir, mantendo o contexto.
Estados — loading, vazio e erro
Todos os charts e o KpiCard têm três estados, com prioridade loading → erro → vazio → gráfico. O skeleton e as mensagens respeitam as dimensões do container.
- Loading: skeleton no lugar do desenho enquanto a requisição do squad está em andamento.
- Vazio: mensagem padrão do EDS quando
datachega vazio; pode ser personalizada por texto ou pelo slot de vazio (ex.: "Configure um filtro para ver os dados"). - Erro: alerta padrão quando a carga falha, também personalizável.
Os componentes não fazem fetch: loading e error são controlados pelo squad consumidor a partir do estado da própria requisição.
Acessibilidade
Cada chart expõe role="img" + aria-label no desenho e renderiza uma tabela sr-only (invisível, lida por leitores de tela) com os dados como alternativa textual — gerada automaticamente a partir dos dados. Nada a configurar.
O aria-label é montado do título mais a descrição — ex.: título "Vendas" + descrição "Últimos 6 meses" vira "Gráfico de linhas: Vendas — Últimos 6 meses". Por isso, sempre informe título e descrição com sentido completo.
Responsividade
Cada chart observa o tamanho do pai e re-renderiza ao redimensionar, preenchendo a altura disponível. Em grids ou dashboards, garanta uma altura mínima no card (ex.: min-h-[280px]) para o desenho não colapsar.
Importação e tipos
Os charts, o KpiCard e os widgets são a entrega "UI Blocks" do EDS, no pacote @mercadoeletronico/eds-next (o PDD os chama de @eds/ui-blocks — nome conceitual, não um pacote npm separado). Props, eventos e tipos têm contrato estável com os squads consumidores. Caminhos de import, nomes de tipo e assinatura de eventos (update:activeIndex, compatível com v-model) estão na API completa no EletroDS.
Tooltips
Todos os charts exibem tooltip no hover por padrão (fundo do tema, borda, sombra, Roboto) — ajuste só indicador, rótulos e valores.
- Indicador — Dot (padrão, quadrado colorido por série), Line (linha vertical sólida), Dashed (tracejada, p/ série prevista) ou Sem indicador (valor único). Escolha pela leitura.
- Ocultar o título — a linha superior repete o valor do eixo X; oculte quando já é óbvio pela posição do cursor.
- Formatters — traduzem o dado cru para a linguagem do usuário (moeda pt-BR, datas localizadas) sem alterar a fonte; aplicam-se ao título e ao valor de cada série.
- Customizado — para mini-comparação, ícone de tendência ou múltiplas métricas, substitua por um componente próprio mantendo a mesma casca visual.
- Por tipo — linha/área/barra usam crosshair (reúne as séries no ponto X); pizza/rosca/radial mostram a fatia sob o cursor; radar, os vértices do eixo. No radial o trilho vazio não dispara tooltip.
hideLabel ou indicator: 'none'.Cores das séries
As séries usam a paleta de charts — 10 cores categóricas e não-semânticas (cor de série só diferencia séries; status usa as cores semânticas). A atribuição é automática: cada série recebe --chart-1, --chart-2… em ordem, alternando quente/frio. Definição completa, valores light/dark e acessibilidade em Tokens › Charts.
Acima de ~10 séries o olho não diferencia as cores — prefira Top N + "Outros", small multiples ou isolar a série por hover/legenda.