@trismegisto/charts

Gráficos do Hermes Design System para Angular: 12 gráficos tipados com API orientada a dados e um hm-chart de baixo nível, todos desenhados em SVG com as cores da paleta de dados (--hm-data-*), tema e família ao vivo, resumo para leitor de tela, tabela de dados equivalente ("Ver como tabela"), navegação pelas setas e textos em pt-BR/en/es pelo idioma ativo do @trismegisto/angular.

Na cadeia de camadas (tokens ← icons ← primitives ← core ← angular ← maps · charts · spine) é um pacote Angular ao lado do @trismegisto/maps, montado sobre o @trismegisto/angular. O motor de desenho vem dentro do pacote: sem dependência de gráficos a instalar.

Instalação

npm install @trismegisto/charts

Peers: @trismegisto/angular, @trismegisto/core, @trismegisto/primitives, @trismegisto/tokens (e, pelo @trismegisto/angular, @trismegisto/icons), mais @angular/core e @angular/common ≥ 21. Todos na mesma versão dos pacotes base, já configurados como no README do @trismegisto/angular (CSS dos tokens e do core, hermesTheme na raiz). O pacote não tem CSS próprio a carregar.

Uso

import { Component } from '@angular/core';
import { HmBarChartComponent, HmPieChartComponent, type ChartSeries } from '@trismegisto/charts';

@Component({
  imports: [HmBarChartComponent, HmPieChartComponent],
  template: `
    <hm-bar-chart label="Vendas por trimestre" [categories]="quarters" [series]="sales"
      [numberFormat]="{ style: 'currency', currency: 'BRL', notation: 'compact' }" />
    <hm-pie-chart label="Canais de venda" [data]="channels" [donut]="true" />
  `,
})
export class SalesPanel {
  readonly quarters = ['T1', 'T2', 'T3', 'T4'];
  readonly sales: ChartSeries[] = [
    { name: '2025', data: [120, 132, 101, 134] },
    { name: '2026', data: [140, 150, null, 160] }, // null = lacuna
  ];
  readonly channels = [{ name: 'Loja', value: 40 }, { name: 'Site', value: 60 }];
}

Carregue sob demanda. O pacote pesa cerca de 741 kB minificado (~215 kB gzip). Ponha as telas de gráfico numa rota lazy ou o gráfico num @defer, para ele não entrar no carregamento inicial:

@defer (on viewport) {
  <hm-line-chart label="Acessos por dia" [categories]="days" [series]="visits" [area]="true" />
} @placeholder {
  <hm-skeleton shape="card" [count]="1" label="Carregando gráfico" />
}

Gráficos

Entradas comuns a todos os tipados (HmChartBase): label (obrigatório: nome acessível e legenda da tabela), description (frase somada ao resumo automático), legend, tooltip, height (qualquer comprimento CSS; padrão, oito alturas de controle), numberFormat (Intl.NumberFormatOptions no idioma ativo) e [(showTable)].

| Seletor | Classe | Dados | | --- | --- | --- | | hm-bar-chart | HmBarChartComponent | categories, series: ChartSeries[]; orientation (vertical/horizontal), stacked | | hm-line-chart | HmLineChartComponent | categories, series: ChartSeries[]; area, stacked, smooth | | hm-pie-chart | HmPieChartComponent | data: ChartDatum[]; donut | | hm-heatmap-chart | HmHeatmapChartComponent | data: HeatmapCell[] (x, y, value); xCategories, yCategories | | hm-calendar-heatmap | HmCalendarHeatmapComponent | data: CalendarDatum[]; range, dateFormat | | hm-scatter-chart | HmScatterChartComponent | series: ScatterSeries[] (pontos x, y, name?); xLabel, yLabel | | hm-gauge-chart | HmGaugeChartComponent | value; min (0), max (100) | | hm-funnel-chart | HmFunnelChartComponent | data: ChartDatum[] | | hm-radar-chart | HmRadarChartComponent | indicators: RadarIndicator[], series: RadarSeries[] | | hm-treemap-chart | HmTreemapChartComponent | data: TreemapNode[] | | hm-sankey-chart | HmSankeyChartComponent | links: SankeyLink[]; nodes | | hm-boxplot-chart | HmBoxplotChartComponent | data: BoxplotGroup[]; orientation |

hm-chart (HmChartComponent) é a saída de emergência para o que os tipados não cobrem: recebe a opção completa do motor (option: HmChartOption, tipada pelos Hm*SeriesOption), label e points (pontos navegáveis pelas setas). Ele cuida de ciclo de vida, tema, idioma, movimento reduzido e alto contraste, mas não monta resumo nem tabela: prefira sempre um tipado. O motor grava o retorno de um tooltip.formatter com innerHTML: num formatter próprio, passe todo texto vindo de dados por escapeHtml (@trismegisto/primitives), como os tipados fazem.

Regras que o app precisa saber

• Cores vêm da paleta de dados (--hm-data-categorical-1…8, sequencial e divergente), já validadas para contraste e daltonismo nos dois temas. Não passe cores próprias de série. Com mais de 8 séries, agrupe em "Outros" ou divida em gráficos menores.
• Cor nunca é a única pista: a legenda, o tooltip, o resumo e a tabela dizem os valores em texto. Mantenha label descritivo e use description para a conclusão ou a fonte dos dados.
• prefers-reduced-motion desliga as animações; em forced-colors as séries usam cores do sistema e padrões de preenchimento.

Textos

O catálogo próprio (CHARTS_MESSAGES_PT_BR, _EN, _ES, embutidos) segue HermesI18nService.setLocale: trocar o idioma da lib troca o dos gráficos. Para sobrescrever textos ou acrescentar idiomas:

// catalogoFr: um objeto ChartsMessages do próprio app
provideChartsMessages({ override: { /* chaves de ChartsMessages */ }, catalogs: { fr: catalogoFr } });

Documentação

• Grupo "Gráficos" do site de documentação (docs/website): uma página por gráfico (/components/bar-chart, /components/line-chart… e /components/chart).
• Paleta de dados e critérios de validação: @trismegisto/tokens.
• Regras do pacote: CLAUDE.md §5 e docs/architecture.

Créditos e licenças de terceiros: ver NOTICE e LICENSES/ (publicados junto com o pacote).

Desenvolvimento do pacote

npm test (textos fora do catálogo + checagem estrita + specs) e npm run build (ng-packagr em dist/). src/engine/ é gerado por tools/port/ (ver o README de lá): não edite à mão. Código do pacote fica em src/lib/.