@1doc/1ds-react 0.0.2 → 2.7.1

package/src/utils/chart.ts

@@ -0,0 +1,682 @@
+/**
+ * Geometria dos gráficos do 1DS (BarChart, LineChart, DonutChart).
+ *
+ * Módulo puro, sem DOM: recebe dados e medidas, devolve coordenadas prontas
+ * para o SVG. Mora fora dos `.lite.tsx` por dois motivos:
+ *
+ * - o Mitosis não aceita função em escopo de módulo dentro de um `.lite.tsx`
+ *   (tenta ler a declaração como JSON5 e explode);
+ * - os três gráficos compartilham a escala, o formatador e a medição de
+ *   texto — cópia em três arquivos seria três lugares para corrigir.
+ *
+ * Nada aqui escolhe cor. A cor de cada série é uma classe CSS
+ * (`umds-chart__serie--N`) que aponta para um token semântico — é assim que o
+ * gráfico acompanha o tema escuro sem nenhuma linha de JavaScript.
+ */
+
+/** Um ponto de uma série única: rótulo da categoria e valor. */
+export interface ChartPonto {
+  label: string;
+  value: number | null;
+}
+
+/** Uma série nomeada, com um valor por categoria. */
+export interface ChartSerieBruta {
+  name: string;
+  values: Array<number | null>;
+}
+
+/**
+ * Quantas séries (ou fatias) cabem com cor própria.
+ *
+ * O DS não tem paleta categórica: as cinco cores saem dos tokens semânticos
+ * que já existem e que passaram no validador de daltonismo nos temas 1doc e
+ * 1doc-dark. Uma sexta série não ganha cor gerada — gráfico com mais séries
+ * pede small multiples ou agrupamento em "Outros".
+ */
+export const CHART_MAX_SERIES = 5;
+
+/** Altura de linha do texto dos eixos (12px da escala oficial). */
+const FONTE_EIXO = 12;
+/** Largura média de um caractere de Open Sans a 12px, com folga. */
+const LARGURA_CARACTERE = 7;
+export interface ChartFormato {
+  valueFormatter?: (value: number) => string;
+  unit?: string;
+}
+
+/** Formata um valor para leitura: formatador do consumidor ou pt-BR + unidade. */
+export function formatarValor(valor: number | null | undefined, formato: ChartFormato): string {
+  if (valor === null || valor === undefined || Number.isNaN(valor)) return "—";
+  if (typeof formato.valueFormatter === "function") return formato.valueFormatter(valor);
+  const numero = valor.toLocaleString("pt-BR", {
+    maximumFractionDigits: 2
+  });
+  const unidade = formato.unit || "";
+  if (!unidade) return numero;
+  // "%" encosta no número (12%); qualquer outra unidade leva espaço (12 dias).
+  return unidade === "%" ? `${numero}%` : `${numero} ${unidade}`;
+}
+
+/**
+ * O mesmo valor, para leitor de tela: "—" é lido como "travessão" (ou nada),
+ * então ausência de dado vira "sem dado".
+ */
+export function valorAcessivel(valor: number | null | undefined, formato: ChartFormato): string {
+  if (valor === null || valor === undefined || Number.isNaN(valor)) return "sem dado";
+  return formatarValor(valor, formato);
+}
+
+/** Estimativa da largura de um texto de eixo, sem medir no DOM. */
+export function larguraDoTexto(texto: string): number {
+  return (texto || "").length * LARGURA_CARACTERE;
+}
+
+/** Arredonda o erro de ponto flutuante de somas como 0,1 + 0,2. */
+function limpar(numero: number): number {
+  return Math.round(numero * 1e9) / 1e9;
+}
+
+/** Passo "redondo" (1, 2, 2,5, 5 × 10^n) mais próximo acima do bruto. */
+function passoRedondo(bruto: number): number {
+  if (bruto <= 0 || !Number.isFinite(bruto)) return 1;
+  const expoente = Math.floor(Math.log10(bruto));
+  const base = Math.pow(10, expoente);
+  const fracao = bruto / base;
+  const redondo = fracao <= 1 ? 1 : fracao <= 2 ? 2 : fracao <= 2.5 ? 2.5 : fracao <= 5 ? 5 : 10;
+  return redondo * base;
+}
+export interface ChartEscala {
+  min: number;
+  max: number;
+  ticks: number[];
+}
+
+/**
+ * Escala do eixo Y com números redondos, sempre incluindo o zero: barra que
+ * não nasce do zero mente sobre a proporção.
+ */
+export function escalaRedonda(valores: number[], divisoes = 4): ChartEscala {
+  let min = 0;
+  let max = 0;
+  for (const v of valores) {
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+  if (min === max) max = min + 1;
+  const passo = passoRedondo((max - min) / divisoes);
+  const inicio = Math.floor(limpar(min / passo)) * passo;
+  const fim = Math.ceil(limpar(max / passo)) * passo;
+  const ticks: number[] = [];
+  for (let t = inicio; t <= fim + passo / 2; t += passo) ticks.push(limpar(t));
+  return {
+    min: limpar(inicio),
+    max: limpar(fim),
+    ticks
+  };
+}
+export interface ChartDados {
+  categorias: string[];
+  series: ChartSerieBruta[];
+}
+
+/**
+ * Junta as duas formas de entrada numa só: `data` (série única de
+ * `{ label, value }`) ou `series` + `labels`. Corta em CHART_MAX_SERIES.
+ */
+export function normalizarDados(data: ChartPonto[] | undefined, series: ChartSerieBruta[] | undefined, labels: string[] | undefined, nomePadrao: string): ChartDados {
+  if (series && series.length > 0) {
+    const cortadas = series.slice(0, CHART_MAX_SERIES);
+    let n = 0;
+    for (const s of cortadas) n = Math.max(n, (s.values || []).length);
+    const categorias: string[] = [];
+    for (let i = 0; i < n; i++) {
+      categorias.push(labels && labels[i] !== undefined ? String(labels[i]) : String(i + 1));
+    }
+    return {
+      categorias,
+      series: cortadas.map(s => ({
+        name: s.name,
+        values: categorias.map((_, i) => {
+          const v = (s.values || [])[i];
+          return typeof v === "number" && Number.isFinite(v) ? v : null;
+        })
+      }))
+    };
+  }
+  const pontos = data || [];
+  return {
+    categorias: pontos.map(p => String(p.label)),
+    series: pontos.length ? [{
+      name: nomePadrao,
+      values: pontos.map(p => typeof p.value === "number" && Number.isFinite(p.value) ? p.value : null)
+    }] : []
+  };
+}
+
+/** Existe ao menos um número para desenhar? */
+export function temValores(dados: ChartDados): boolean {
+  return dados.series.some(s => s.values.some(v => v !== null));
+}
+
+// ─── Plano cartesiano (barras e linhas) ───────────────────────────────
+
+export interface ChartTick {
+  y: number;
+  texto: string;
+}
+export interface ChartRotuloX {
+  x: number;
+  texto: string;
+}
+export interface ChartLinhaDoTooltip {
+  serie: number;
+  nome: string;
+  texto: string;
+}
+
+/** Área de interação de uma categoria: posição em % e o que o tooltip lê. */
+export interface ChartAlvo {
+  indice: number;
+  categoria: string;
+  esquerda: string;
+  largura: string;
+  lado: "direita" | "esquerda";
+  descricao: string;
+  linhas: ChartLinhaDoTooltip[];
+}
+export interface ChartPlano {
+  largura: number;
+  altura: number;
+  topo: number;
+  base: number;
+  esquerda: number;
+  direita: number;
+  banda: number;
+  y0: number;
+  ticks: ChartTick[];
+  rotulosX: ChartRotuloX[];
+  alvos: ChartAlvo[];
+  escalaY: (valor: number) => number;
+  centroX: (indice: number) => number;
+}
+
+/**
+ * Monta o plano: margens medidas pelo texto dos ticks, escala Y redonda,
+ * rótulos do X rareados quando não cabem, e uma área de interação por
+ * categoria.
+ */
+export function montarPlano(dados: ChartDados, largura: number, altura: number, formato: ChartFormato): ChartPlano {
+  const valores: number[] = [];
+  for (const s of dados.series) for (const v of s.values) if (v !== null) valores.push(v);
+  const escala = escalaRedonda(valores);
+  const textosTick = escala.ticks.map(t => formatarValor(t, formato));
+  let maiorTick = 0;
+  for (const t of textosTick) maiorTick = Math.max(maiorTick, larguraDoTexto(t));
+  const topo = FONTE_EIXO / 2 + 2;
+  const esquerda = Math.ceil(maiorTick) + 8;
+  const n = Math.max(1, dados.categorias.length);
+  // O último rótulo do X é centrado na última banda e pode passar da borda
+  // direita; a margem cresce só o que ele passar.
+  const bandaPrevia = Math.max(1, largura - esquerda - 8) / n;
+  const ultimo = larguraDoTexto(dados.categorias[dados.categorias.length - 1] || "");
+  const direita = Math.max(8, Math.ceil(ultimo / 2 - bandaPrevia / 2) + 2);
+  const base = altura - (FONTE_EIXO + 12);
+  const larguraUtil = Math.max(1, largura - esquerda - direita);
+  const banda = larguraUtil / n;
+  const escalaY = (valor: number) => topo + (escala.max - valor) / (escala.max - escala.min) * (base - topo);
+  const centroX = (indice: number) => esquerda + banda * indice + banda / 2;
+  const ticks = escala.ticks.map((t, i) => ({
+    y: escalaY(t),
+    texto: textosTick[i]
+  }));
+  let maiorRotulo = 0;
+  for (const c of dados.categorias) maiorRotulo = Math.max(maiorRotulo, larguraDoTexto(c));
+  const pulo = Math.max(1, Math.ceil((maiorRotulo + 8) / banda));
+  const rotulosX: ChartRotuloX[] = [];
+  dados.categorias.forEach((c, i) => {
+    if (i % pulo === 0) rotulosX.push({
+      x: centroX(i),
+      texto: c
+    });
+  });
+  const alvos: ChartAlvo[] = dados.categorias.map((categoria, i) => {
+    const linhas = dados.series.map((s, j) => ({
+      serie: j + 1,
+      nome: s.name,
+      texto: formatarValor(s.values[i], formato)
+    }));
+    const partes = dados.series.map(s => {
+      const texto = valorAcessivel(s.values[i], formato);
+      return dados.series.length > 1 ? `${s.name}: ${texto}` : texto;
+    });
+    return {
+      indice: i,
+      categoria,
+      esquerda: `${(esquerda + banda * i) / largura * 100}%`,
+      largura: `${banda / largura * 100}%`,
+      lado: i < n / 2 ? "direita" : "esquerda",
+      descricao: `${categoria}: ${partes.join("; ")}`,
+      linhas
+    };
+  });
+  return {
+    largura,
+    altura,
+    topo,
+    base,
+    esquerda,
+    direita,
+    banda,
+    y0: escalaY(0),
+    ticks,
+    rotulosX,
+    alvos,
+    escalaY,
+    centroX
+  };
+}
+
+/**
+ * Raio da ponta da barra, em px. Espelha `--umds-primitive-border-radius-sm`
+ * (8px), o raio universal do DS. Precisa ser número porque o arredondamento
+ * é geometria do caminho SVG, calculada aqui — não é um token novo.
+ */
+export const RAIO_DA_BARRA = 8;
+
+/**
+ * Caminho de uma barra: quadrada na linha de base, arredondada na ponta do
+ * dado com o raio canônico. Valor negativo arredonda embaixo. O raio nunca
+ * passa de metade da largura (barra fina não vira pílula) nem de metade da
+ * altura (barra curta não estoura a linha de base).
+ */
+export function caminhoDaBarra(x: number, largura: number, y0: number, y: number): string {
+  const altura = Math.abs(y0 - y);
+  if (altura < 0.5 || largura <= 0) return "";
+  const r = Math.min(RAIO_DA_BARRA, largura / 2, altura / 2);
+  const x1 = x + largura;
+  if (y <= y0) {
+    return `M${x},${y0}V${y + r}A${r},${r} 0 0 1 ${x + r},${y}H${x1 - r}A${r},${r} 0 0 1 ${x1},${y + r}V${y0}Z`;
+  }
+  return `M${x},${y0}V${y - r}A${r},${r} 0 0 0 ${x + r},${y}H${x1 - r}A${r},${r} 0 0 0 ${x1},${y - r}V${y0}Z`;
+}
+export interface ChartBarra {
+  chave: string;
+  serie: number;
+  indice: number;
+  d: string;
+}
+
+/** Barras verticais, agrupadas lado a lado quando há mais de uma série. */
+export function montarBarras(dados: ChartDados, plano: ChartPlano): ChartBarra[] {
+  const m = Math.max(1, dados.series.length);
+  const vao = 2;
+  const espessura = Math.max(2, Math.min(24, (plano.banda * 0.72 - vao * (m - 1)) / m));
+  const grupo = espessura * m + vao * (m - 1);
+  const barras: ChartBarra[] = [];
+  dados.categorias.forEach((_, i) => {
+    const inicio = plano.esquerda + plano.banda * i + (plano.banda - grupo) / 2;
+    dados.series.forEach((s, j) => {
+      const v = s.values[i];
+      if (v === null) return;
+      const d = caminhoDaBarra(inicio + j * (espessura + vao), espessura, plano.y0, plano.escalaY(v));
+      if (d) barras.push({
+        chave: `${j}-${i}`,
+        serie: j + 1,
+        indice: i,
+        d
+      });
+    });
+  });
+  return barras;
+}
+export interface ChartPontoDaLinha {
+  chave: string;
+  serie: number;
+  indice: number;
+  x: number;
+  y: number;
+}
+export interface ChartTraco {
+  chave: string;
+  serie: number;
+  d: string;
+  pontos: ChartPontoDaLinha[];
+}
+
+/** Uma linha por série; valor ausente (`null`) interrompe o traço. */
+export function montarLinhas(dados: ChartDados, plano: ChartPlano): ChartTraco[] {
+  return dados.series.map((s, j) => {
+    let d = "";
+    let caneta = false;
+    const pontos: ChartPontoDaLinha[] = [];
+    s.values.forEach((v, i) => {
+      if (v === null) {
+        caneta = false;
+        return;
+      }
+      const x = plano.centroX(i);
+      const y = plano.escalaY(v);
+      d += `${caneta ? "L" : "M"}${x},${y}`;
+      caneta = true;
+      pontos.push({
+        chave: `${j}-${i}`,
+        serie: j + 1,
+        indice: i,
+        x,
+        y
+      });
+    });
+    return {
+      chave: String(j),
+      serie: j + 1,
+      d,
+      pontos
+    };
+  });
+}
+
+/** Frase curta para o `aria-label` do gráfico: o que é e a faixa de valores. */
+export function resumoCartesiano(tipo: string, dados: ChartDados, formato: ChartFormato): string {
+  let min = Infinity;
+  let max = -Infinity;
+  for (const s of dados.series) for (const v of s.values) if (v !== null) {
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+  const n = dados.categorias.length;
+  const m = dados.series.length;
+  const series = m > 1 ? `, ${m} séries (${dados.series.map(s => s.name).join(", ")})` : "";
+  const faixa = min === Infinity ? "" : ` Valores de ${formatarValor(min, formato)} a ${formatarValor(max, formato)}.`;
+  return `${tipo} com ${n} ${n === 1 ? "categoria" : "categorias"}${series}.${faixa}`;
+}
+
+// ─── Rosca ────────────────────────────────────────────────────────────
+
+export interface ChartFatia {
+  chave: string;
+  /** Posição da cor (1 a CHART_MAX_SERIES); 0 é a fatia "Outros", em neutro. */
+  serie: number;
+  indice: number;
+  nome: string;
+  valor: number;
+  texto: string;
+  percentual: string;
+  d: string;
+}
+export interface ChartRosca {
+  total: number;
+  fatias: ChartFatia[];
+}
+function pontoNoCirculo(c: number, r: number, angulo: number): string {
+  return `${c + r * Math.cos(angulo)},${c + r * Math.sin(angulo)}`;
+}
+
+/** Setor de anel entre dois ângulos (radianos, zero às 12h, sentido horário). */
+export function caminhoDoSetor(c: number, raio: number, interno: number, a0: number, a1: number): string {
+  // Um setor de 360° degenera (início = fim); desenha como duas metades.
+  if (a1 - a0 >= Math.PI * 2 - 1e-6) {
+    const meio = a0 + Math.PI;
+    return caminhoDoSetor(c, raio, interno, a0, meio) + caminhoDoSetor(c, raio, interno, meio, a1);
+  }
+  const g0 = a0 - Math.PI / 2;
+  const g1 = a1 - Math.PI / 2;
+  const grande = a1 - a0 > Math.PI ? 1 : 0;
+  return `M${pontoNoCirculo(c, raio, g0)}` + `A${raio},${raio} 0 ${grande} 1 ${pontoNoCirculo(c, raio, g1)}` + `L${pontoNoCirculo(c, interno, g1)}` + `A${interno},${interno} 0 ${grande} 0 ${pontoNoCirculo(c, interno, g0)}Z`;
+}
+
+/**
+ * Fatias da rosca. Mais que CHART_MAX_SERIES partes: as primeiras ficam e o
+ * resto vira uma fatia só, `rotuloOutros`. Valor negativo ou ausente conta
+ * como zero — parte de um todo não pode ser negativa.
+ */
+export function montarRosca(data: ChartPonto[] | undefined, tamanho: number, formato: ChartFormato, rotuloOutros: string): ChartRosca {
+  const limpos = (data || []).map(p => ({
+    nome: String(p.label),
+    valor: typeof p.value === "number" && p.value > 0 ? p.value : 0
+  }));
+  let partes = limpos;
+  let agrupou = false;
+  if (limpos.length > CHART_MAX_SERIES) {
+    const ficam = limpos.slice(0, CHART_MAX_SERIES - 1);
+    const resto = limpos.slice(CHART_MAX_SERIES - 1).reduce((soma, p) => soma + p.valor, 0);
+    partes = [...ficam, {
+      nome: rotuloOutros,
+      valor: resto
+    }];
+    agrupou = true;
+  }
+  const total = partes.reduce((soma, p) => soma + p.valor, 0);
+  const c = tamanho / 2;
+  const raio = c - 1;
+  const interno = raio * 0.64;
+  let angulo = 0;
+  const fatias = partes.map((p, i) => {
+    const fracao = total > 0 ? p.valor / total : 0;
+    const a0 = angulo;
+    const a1 = angulo + fracao * Math.PI * 2;
+    angulo = a1;
+    return {
+      chave: String(i),
+      serie: agrupou && i === partes.length - 1 ? 0 : i + 1,
+      indice: i,
+      nome: p.nome,
+      valor: p.valor,
+      texto: formatarValor(p.valor, formato),
+      percentual: `${(fracao * 100).toLocaleString("pt-BR", {
+        maximumFractionDigits: 1
+      })}%`,
+      d: fracao > 0 ? caminhoDoSetor(c, raio, interno, a0, a1) : ""
+    };
+  });
+  return {
+    total,
+    fatias
+  };
+}
+
+// ─── Modelos prontos para o template ─────────────────────────────────
+//
+// O template de um `.lite.tsx` só lê campos destes objetos. Nenhum getter do
+// componente lê outro getter (na geração Vue isso perde o `.value`), então
+// tudo o que o desenho precisa é calculado aqui, de uma vez.
+
+export interface ChartEntradaCartesiana extends ChartFormato {
+  data?: ChartPonto[];
+  series?: ChartSerieBruta[];
+  labels?: string[];
+  seriesName?: string;
+  title?: string;
+  ariaLabel?: string;
+  showLegend?: any;
+  showGrid?: any;
+}
+export interface ChartGradeLinha {
+  chave: string;
+  x1: number;
+  x2: number;
+  y: number;
+  xTexto: number;
+  texto: string;
+}
+export interface ChartRotuloXPosicionado {
+  chave: string;
+  x: number;
+  y: number;
+  texto: string;
+}
+export interface ChartAlvoPosicionado extends ChartAlvo {
+  cx: number;
+}
+export interface ChartItemDeLegenda {
+  chave: string;
+  serie: number;
+  nome: string;
+}
+export interface ChartLinhaDaTabela {
+  chave: string;
+  categoria: string;
+  valores: Array<{
+    chave: string;
+    texto: string;
+  }>;
+}
+export interface ChartModeloCartesiano {
+  vazio: boolean;
+  viewBox: string;
+  largura: number;
+  altura: number;
+  topo: number;
+  base: number;
+  esquerda: number;
+  fimX: number;
+  y0: number;
+  mostraGrade: boolean;
+  mostraLegenda: boolean;
+  grade: ChartGradeLinha[];
+  rotulosX: ChartRotuloXPosicionado[];
+  alvos: ChartAlvoPosicionado[];
+  barras: ChartBarra[];
+  tracos: ChartTraco[];
+  pontos: ChartPontoDaLinha[];
+  legenda: ChartItemDeLegenda[];
+  resumo: string;
+  rotuloDaLista: string;
+  legendaDaTabela: string;
+  cabecalhos: ChartItemDeLegenda[];
+  tabela: ChartLinhaDaTabela[];
+}
+
+/** Prop booleana que liga por padrão: só `false` desliga (Vue entrega `undefined` sem `boolean`). */
+function ligadoPorPadrao(valor: any): boolean {
+  return valor !== false && valor !== "false";
+}
+export function modeloCartesiano(tipo: "barras" | "linhas", entrada: ChartEntradaCartesiana, largura: number, altura: number): ChartModeloCartesiano {
+  const formato: ChartFormato = {
+    valueFormatter: entrada.valueFormatter,
+    unit: entrada.unit
+  };
+  const dados = normalizarDados(entrada.data, entrada.series, entrada.labels, entrada.seriesName || entrada.title || "Valor");
+  const largo = Math.max(120, Math.round(largura || 0));
+  const alto = Math.max(80, Math.round(altura || 0));
+  const legenda = dados.series.map((s, j) => ({
+    chave: String(j),
+    serie: j + 1,
+    nome: s.name
+  }));
+  const nomeDoTipo = tipo === "barras" ? "Gráfico de barras" : "Gráfico de linhas";
+  const base: ChartModeloCartesiano = {
+    vazio: true,
+    viewBox: `0 0 ${largo} ${alto}`,
+    largura: largo,
+    altura: alto,
+    topo: 0,
+    base: alto,
+    esquerda: 0,
+    fimX: largo,
+    y0: alto,
+    mostraGrade: ligadoPorPadrao(entrada.showGrid),
+    mostraLegenda: legenda.length > 1 && ligadoPorPadrao(entrada.showLegend),
+    grade: [],
+    rotulosX: [],
+    alvos: [],
+    barras: [],
+    tracos: [],
+    pontos: [],
+    legenda,
+    resumo: entrada.ariaLabel || `${nomeDoTipo} sem dados.`,
+    rotuloDaLista: entrada.title ? `Valores por categoria — ${entrada.title}` : "Valores por categoria",
+    legendaDaTabela: entrada.title || nomeDoTipo,
+    cabecalhos: legenda,
+    tabela: []
+  };
+  if (!temValores(dados)) return base;
+  const plano = montarPlano(dados, largo, alto, formato);
+  const fimX = largo - plano.direita;
+  const tracos = tipo === "linhas" ? montarLinhas(dados, plano) : [];
+  const pontos: ChartPontoDaLinha[] = [];
+  for (const t of tracos) for (const p of t.pontos) pontos.push(p);
+  return {
+    ...base,
+    vazio: false,
+    topo: plano.topo,
+    base: plano.base,
+    esquerda: plano.esquerda,
+    fimX,
+    y0: plano.y0,
+    grade: plano.ticks.map((t, i) => ({
+      chave: String(i),
+      x1: plano.esquerda,
+      x2: fimX,
+      y: t.y,
+      xTexto: plano.esquerda - 8,
+      texto: t.texto
+    })),
+    rotulosX: plano.rotulosX.map((r, i) => ({
+      chave: String(i),
+      x: r.x,
+      y: plano.base + 8,
+      texto: r.texto
+    })),
+    alvos: plano.alvos.map(a => ({
+      ...a,
+      cx: plano.centroX(a.indice)
+    })),
+    barras: tipo === "barras" ? montarBarras(dados, plano) : [],
+    tracos,
+    pontos,
+    // Sem o título: a <figcaption> já dá nome à figura, e repetir aqui faria o
+    // leitor de tela anunciar o título duas vezes.
+    resumo: entrada.ariaLabel || resumoCartesiano(nomeDoTipo, dados, formato),
+    tabela: dados.categorias.map((categoria, i) => ({
+      chave: String(i),
+      categoria,
+      valores: dados.series.map((s, j) => ({
+        chave: String(j),
+        texto: valorAcessivel(s.values[i], formato)
+      }))
+    }))
+  };
+}
+export interface ChartEntradaRosca extends ChartFormato {
+  data?: ChartPonto[];
+  title?: string;
+  ariaLabel?: string;
+  centerLabel?: string;
+  centerValue?: string;
+  otherLabel?: string;
+  showLegend?: any;
+}
+export interface ChartModeloRosca {
+  vazio: boolean;
+  tamanho: number;
+  viewBox: string;
+  fatias: ChartFatia[];
+  centroValor: string;
+  centroRotulo: string;
+  mostraLegenda: boolean;
+  resumo: string;
+}
+export function modeloRosca(entrada: ChartEntradaRosca, tamanho: number): ChartModeloRosca {
+  const formato: ChartFormato = {
+    valueFormatter: entrada.valueFormatter,
+    unit: entrada.unit
+  };
+  const lado = Math.max(96, Math.round(tamanho || 0));
+  const rosca = montarRosca(entrada.data, lado, formato, entrada.otherLabel || "Outros");
+  const centroValor = entrada.centerValue || formatarValor(rosca.total, formato);
+  const centroRotulo = entrada.centerLabel === undefined ? "Total" : entrada.centerLabel;
+  return {
+    vazio: rosca.total <= 0,
+    tamanho: lado,
+    viewBox: `0 0 ${lado} ${lado}`,
+    fatias: rosca.fatias,
+    centroValor,
+    centroRotulo,
+    mostraLegenda: ligadoPorPadrao(entrada.showLegend),
+    // Curto de propósito: as partes, com valor e percentual, estão na legenda
+    // (visível ou oculta), que é a leitura principal. Repetir aqui faria o
+    // leitor de tela ler tudo duas vezes.
+    resumo: entrada.ariaLabel || (rosca.total > 0 ? `Gráfico de rosca com ${rosca.fatias.length} partes. Total: ${centroValor}${centroRotulo && centroRotulo !== "Total" ? " " + centroRotulo : ""}.` : "Gráfico de rosca sem dados.")
+  };
+}

package/src/utils/density.ts

@@ -0,0 +1,27 @@
+/**
+ * Densidade global de interação (decisão 25/07, simulação de adoção).
+ *
+ * O modo "touch" (`<html data-density="touch">`) eleva os alvos de toque dos
+ * controles interativos para ≥44px (Apple HIG / WCAG 2.5.8), aumentando
+ * controle e espaçamento juntos — sem hit-areas invisíveis, que roubam
+ * clique de vizinhos em listas densas. O default permanece idêntico.
+ */
+export type Density = "default" | "touch";
+const DENSITY_ATTRIBUTE = "data-density";
+
+/** Define a densidade global (remove o atributo quando "default"). */
+export const setDensity = (density: Density): void => {
+  if (typeof document === "undefined") return;
+  if (density === "default") {
+    document.documentElement.removeAttribute(DENSITY_ATTRIBUTE);
+  } else {
+    document.documentElement.setAttribute(DENSITY_ATTRIBUTE, density);
+  }
+};
+
+/** Densidade global atual. */
+export const getDensity = (): Density => {
+  if (typeof document === "undefined") return "default";
+  const value = document.documentElement.getAttribute(DENSITY_ATTRIBUTE);
+  return value === "touch" ? "touch" : "default";
+}