acai-ui 1.65.5

package/src/components/chart/chart-a11y.ts

@@ -0,0 +1,184 @@
+// Acessibilidade — o que o leitor de tela recebe no lugar do desenho.
+//
+// Um SVG de gráfico é opaco pro NVDA: sem isto, quem usa leitor ouve "gráfico" e
+// acabou. O eMAG 3.6 pede alternativa em TEXTO, e a prática consolidada pra
+// gráfico é dupla: um resumo curto (`<desc>`) pra dar a forma geral, e a TABELA
+// de dados equivalente pra quem precisa do número exato.
+//
+// Puro de propósito: gerar o texto certo é lógica, e lógica se testa sem montar.
+
+import type { ChartType, DadosNormalizados } from './acai-ui-chart-interface'
+
+const NOME_TIPO: Record<ChartType, string> = {
+  bar: 'Gráfico de barras',
+  line: 'Gráfico de linhas',
+  area: 'Gráfico de área',
+  pie: 'Gráfico de pizza',
+  donut: 'Gráfico de rosca',
+  gauge: 'Medidor',
+}
+
+interface ContextoResumo {
+  tipo: ChartType
+  titulo?: string | undefined
+  formatar: (valor: number) => string
+  /** Domínio do medidor. Só o `gauge` usa. */
+  medidor?: { min: number; max: number } | undefined
+}
+
+/** Categoria/valor extremos de uma série, ignorando buracos. */
+function extremos(
+  dados: DadosNormalizados,
+): { maior: { rotulo: string; valor: number } | null; menor: { rotulo: string; valor: number } | null } {
+  let maior: { rotulo: string; valor: number } | null = null
+  let menor: { rotulo: string; valor: number } | null = null
+
+  for (const serie of dados.series) {
+    if (serie.oculta) continue
+    for (const ponto of serie.pontos) {
+      if (ponto.valor === null) continue
+      const atual = { rotulo: ponto.rotulo, valor: ponto.valor }
+      if (!maior || ponto.valor > maior.valor) maior = atual
+      if (!menor || ponto.valor < menor.valor) menor = atual
+    }
+  }
+  return { maior, menor }
+}
+
+/**
+ * Resumo falado do gráfico. Vai no `<desc>` e é a primeira coisa que o leitor
+ * de tela anuncia.
+ *
+ * A ordem é deliberada: o QUE é, o tamanho, e os extremos — que é o que alguém
+ * olhando o gráfico extrai em um segundo e o leitor de tela não teria como.
+ */
+export function resumoGrafico(dados: DadosNormalizados, ctx: ContextoResumo): string {
+  const partes: string[] = []
+  partes.push(ctx.titulo ? `${NOME_TIPO[ctx.tipo]}: ${ctx.titulo}.` : `${NOME_TIPO[ctx.tipo]}.`)
+
+  if (dados.vazio || dados.rotulos.length === 0) {
+    partes.push('Sem dados para exibir.')
+    return partes.join(' ')
+  }
+
+  // O medidor tem UM valor. Falar "1 categoria, maior valor X, menor valor X,
+  // total X" seria a mesma informação quatro vezes; o que importa é a posição
+  // dele na escala, que o desenho dá de relance e o leitor de tela não tem.
+  if (ctx.tipo === 'gauge') {
+    return `${partes.join(' ')} ${resumoMedidor(dados, ctx)}`.trim()
+  }
+
+  const visiveis = dados.series.filter((s) => !s.oculta)
+  const nCat = dados.rotulos.length
+  const catTexto = `${nCat} ${nCat === 1 ? 'categoria' : 'categorias'}`
+  partes.push(
+    visiveis.length > 1
+      ? `${catTexto}, ${visiveis.length} séries: ${visiveis.map((s) => s.nome).join(', ')}.`
+      : `${catTexto}.`,
+  )
+
+  const { maior, menor } = extremos(dados)
+  if (maior) partes.push(`Maior valor: ${maior.rotulo}, ${ctx.formatar(maior.valor)}.`)
+  // Com um ponto só, maior e menor são o mesmo — repetir só faz ruído.
+  if (menor && maior && menor.rotulo !== maior.rotulo) {
+    partes.push(`Menor valor: ${menor.rotulo}, ${ctx.formatar(menor.valor)}.`)
+  }
+
+  if (visiveis.length === 1 && Number.isFinite(dados.total)) {
+    partes.push(`Total: ${ctx.formatar(dados.total)}.`)
+  }
+
+  return partes.join(' ')
+}
+
+/**
+ * Frase do medidor: valor, escala e a posição relativa em percentual.
+ *
+ * O percentual é calculado e falado porque é a leitura que o desenho entrega de
+ * graça ("a agulha está quase no fim") e que nenhum número absoluto dá sozinho.
+ */
+function resumoMedidor(dados: DadosNormalizados, ctx: ContextoResumo): string {
+  const serie = dados.series.find((s) => !s.oculta)
+  const ponto = serie?.pontos.find((p) => p.valor !== null)
+  if (!ponto || ponto.valor === null) return 'Sem valor medido.'
+
+  const min = ctx.medidor?.min ?? 0
+  const max = ctx.medidor?.max ?? 100
+  const baixo = Math.min(min, max)
+  const alto = Math.max(min, max)
+
+  const frases = [
+    `Valor: ${ctx.formatar(ponto.valor)} de ${ctx.formatar(alto)}.`,
+    `Escala de ${ctx.formatar(baixo)} a ${ctx.formatar(alto)}.`,
+  ]
+
+  if (alto > baixo) {
+    const pct = ((ponto.valor - baixo) / (alto - baixo)) * 100
+    const limitado = Math.min(100, Math.max(0, pct))
+    frases.push(`${limitado.toFixed(0)}% da escala.`)
+    // Valor fora do domínio não pode passar em silêncio: o arco satura na ponta
+    // e o desenho passaria a mentir sobre a grandeza.
+    if (pct < 0 || pct > 100) frases.push('Valor fora da escala configurada.')
+  }
+
+  if (ponto.rotulo) frases.unshift(`${ponto.rotulo}.`)
+  return frases.join(' ')
+}
+
+export interface TabelaDados {
+  cabecalho: string[]
+  linhas: string[][]
+}
+
+/**
+ * Tabela equivalente ao gráfico.
+ *
+ * Fica SEMPRE no DOM (escondida por clip, nunca `display:none` — que a
+ * esconderia do leitor também). É por ela que alguém obtém o número exato, que
+ * nenhum resumo dá.
+ */
+export function tabelaDeDados(
+  dados: DadosNormalizados,
+  formatar: (valor: number) => string,
+  rotuloCategoria = 'Categoria',
+): TabelaDados {
+  const visiveis = dados.series.filter((s) => !s.oculta)
+
+  return {
+    cabecalho: [rotuloCategoria, ...visiveis.map((s) => s.nome)],
+    linhas: dados.rotulos.map((rotulo, i) => [
+      rotulo || '—',
+      ...visiveis.map((s) => {
+        const valor = s.pontos[i]?.valor
+        // Travessão e não "0": ausência de medição não é zero.
+        return valor === null || valor === undefined ? '—' : formatar(valor)
+      }),
+    ]),
+  }
+}
+
+/**
+ * Texto anunciado no `aria-live` quando o foco de teclado anda pelos pontos.
+ *
+ * Inclui a POSIÇÃO ("3 de 12") porque, sem o desenho, é a única forma de saber
+ * onde se está. Mesmo padrão do "Passo N de M" do `acai-ui-tour`.
+ */
+export function anuncioPonto(
+  dados: DadosNormalizados,
+  indiceSerie: number,
+  indicePonto: number,
+  formatar: (valor: number) => string,
+): string {
+  const serie = dados.series[indiceSerie]
+  const ponto = serie?.pontos[indicePonto]
+  if (!serie || !ponto) return ''
+
+  const posicao = `${indicePonto + 1} de ${dados.rotulos.length}`
+  const valor = ponto.valor === null ? 'sem dados' : formatar(ponto.valor)
+  const visiveis = dados.series.filter((s) => !s.oculta)
+
+  const rotulo = ponto.rotulo || `Categoria ${indicePonto + 1}`
+  return visiveis.length > 1
+    ? `${rotulo}, ${serie.nome}, ${valor}. ${posicao}.`
+    : `${rotulo}, ${valor}. ${posicao}.`
+}

package/src/components/chart/chart-caminhos.ts

@@ -0,0 +1,466 @@
+// Geração de `d` de SVG — linha, área, barra, setor e marcador.
+//
+// Tudo aqui é aritmética pura, sem DOM: é o que permite testar as armadilhas de
+// geometria (arco de 100% que não desenha, largeArcFlag, buraco na série, raio
+// maior que a barra) sem montar componente. Mesmo modelo do `tour-posicionar.ts`.
+
+export interface Ponto {
+  x: number
+  y: number
+}
+
+export type CurvaLinha = 'linear' | 'smooth'
+
+export type MarcadorSerie = 'circle' | 'square' | 'triangle' | 'diamond' | 'cross' | 'none'
+
+/** Quanto arredondar antes de virar string. Evita `d` com 15 casas decimais. */
+const CASAS = 2
+const n = (valor: number): string => Number(valor.toFixed(CASAS)).toString()
+
+// ── linha e área ───────────────────────────────────────────────────────────
+
+/**
+ * Quebra a lista em segmentos contínuos. `null` INTERROMPE a linha — não
+ * interpola. Ligar por cima de um buraco inventa dado que não existe: se
+ * fevereiro não tem medição, a linha não pode atravessar fevereiro.
+ */
+function segmentar(pontos: ReadonlyArray<Ponto | null>): Ponto[][] {
+  const segmentos: Ponto[][] = []
+  let atual: Ponto[] = []
+
+  for (const ponto of pontos) {
+    if (ponto && Number.isFinite(ponto.x) && Number.isFinite(ponto.y)) {
+      atual.push(ponto)
+    } else if (atual.length > 0) {
+      segmentos.push(atual)
+      atual = []
+    }
+  }
+  if (atual.length > 0) segmentos.push(atual)
+
+  return segmentos
+}
+
+/**
+ * Tangentes de Fritsch-Carlson — interpolação cúbica MONOTÔNICA.
+ *
+ * Por que não Catmull-Rom/Bézier solto: eles produzem *overshoot*. Numa série
+ * que vai 0 → 100 → 0, a curva solta desce abaixo de zero entre os pontos, e o
+ * leitor vê valor negativo que nunca existiu. Em gráfico isso não é estética,
+ * é correção: a curva não pode sair da faixa dos dados vizinhos.
+ */
+function tangentes(p: readonly Ponto[]): number[] {
+  const total = p.length
+  const dx: number[] = []
+  const inclinacoes: number[] = []
+
+  for (let i = 0; i < total - 1; i++) {
+    const passoX = (p[i + 1] as Ponto).x - (p[i] as Ponto).x
+    dx.push(passoX)
+    inclinacoes.push(passoX === 0 ? 0 : ((p[i + 1] as Ponto).y - (p[i] as Ponto).y) / passoX)
+  }
+
+  const t: number[] = new Array<number>(total)
+  t[0] = inclinacoes[0] ?? 0
+  t[total - 1] = inclinacoes[total - 2] ?? 0
+
+  for (let i = 1; i < total - 1; i++) {
+    const anterior = inclinacoes[i - 1] as number
+    const proxima = inclinacoes[i] as number
+
+    // Troca de sinal (ou platô) = extremo local. Tangente zero prende a curva
+    // no ponto e é justamente o que impede o overshoot.
+    if (anterior * proxima <= 0) {
+      t[i] = 0
+      continue
+    }
+    const p1 = 2 * (dx[i] as number) + (dx[i - 1] as number)
+    const p2 = (dx[i] as number) + 2 * (dx[i - 1] as number)
+    t[i] = (p1 + p2) / (p1 / anterior + p2 / proxima)
+  }
+
+  return t
+}
+
+function segmentoParaD(pontos: readonly Ponto[], curva: CurvaLinha): string {
+  const primeiro = pontos[0] as Ponto
+  if (pontos.length === 1) {
+    // Ponto solto entre dois buracos: sem um `L` o path não pinta nada e o dado
+    // some. O marcador é quem o torna visível; o path só precisa existir.
+    return `M ${n(primeiro.x)} ${n(primeiro.y)}`
+  }
+
+  const partes = [`M ${n(primeiro.x)} ${n(primeiro.y)}`]
+
+  if (curva !== 'smooth' || pontos.length === 2) {
+    for (let i = 1; i < pontos.length; i++) {
+      const ponto = pontos[i] as Ponto
+      partes.push(`L ${n(ponto.x)} ${n(ponto.y)}`)
+    }
+    return partes.join(' ')
+  }
+
+  const t = tangentes(pontos)
+  for (let i = 0; i < pontos.length - 1; i++) {
+    const a = pontos[i] as Ponto
+    const b = pontos[i + 1] as Ponto
+    const terco = (b.x - a.x) / 3
+    partes.push(
+      `C ${n(a.x + terco)} ${n(a.y + (t[i] as number) * terco)}` +
+        ` ${n(b.x - terco)} ${n(b.y - (t[i + 1] as number) * terco)}` +
+        ` ${n(b.x)} ${n(b.y)}`,
+    )
+  }
+
+  return partes.join(' ')
+}
+
+/** Caminho da linha. Cada trecho contínuo vira um `M` novo (buraco = corte). */
+export function caminhoLinha(
+  pontos: ReadonlyArray<Ponto | null>,
+  curva: CurvaLinha = 'linear',
+): string {
+  return segmentar(pontos)
+    .map((s) => segmentoParaD(s, curva))
+    .join(' ')
+}
+
+/**
+ * Caminho da área. Mesmo traçado da linha, fechado contra `yBase`.
+ * Cada segmento fecha sozinho — senão o preenchimento atravessaria o buraco.
+ */
+export function caminhoArea(
+  pontos: ReadonlyArray<Ponto | null>,
+  yBase: number,
+  curva: CurvaLinha = 'linear',
+): string {
+  return segmentar(pontos)
+    .filter((s) => s.length > 1)
+    .map((s) => {
+      const inicio = s[0] as Ponto
+      const fim = s[s.length - 1] as Ponto
+      return `${segmentoParaD(s, curva)} L ${n(fim.x)} ${n(yBase)} L ${n(inicio.x)} ${n(yBase)} Z`
+    })
+    .join(' ')
+}
+
+// ── barra ──────────────────────────────────────────────────────────────────
+
+/** De que lado a barra tem a ponta arredondada (a ponta do DADO, não a base). */
+export type PontaBarra = 'topo' | 'base' | 'direita' | 'esquerda' | 'nenhuma'
+
+/** Retângulo com raio por canto: [sup-esq, sup-dir, inf-dir, inf-esq]. */
+function retanguloArredondado(
+  x: number,
+  y: number,
+  largura: number,
+  altura: number,
+  raios: readonly [number, number, number, number],
+): string {
+  // Raio maior que a metade do lado inverte a curva e desenha uma gravatinha.
+  const limite = Math.max(0, Math.min(largura, altura) / 2)
+  const [a, b, c, d] = raios.map((r) => Math.max(0, Math.min(r, limite))) as [
+    number,
+    number,
+    number,
+    number,
+  ]
+
+  return [
+    `M ${n(x + a)} ${n(y)}`,
+    `L ${n(x + largura - b)} ${n(y)}`,
+    b > 0 ? `A ${n(b)} ${n(b)} 0 0 1 ${n(x + largura)} ${n(y + b)}` : '',
+    `L ${n(x + largura)} ${n(y + altura - c)}`,
+    c > 0 ? `A ${n(c)} ${n(c)} 0 0 1 ${n(x + largura - c)} ${n(y + altura)}` : '',
+    `L ${n(x + d)} ${n(y + altura)}`,
+    d > 0 ? `A ${n(d)} ${n(d)} 0 0 1 ${n(x)} ${n(y + altura - d)}` : '',
+    `L ${n(x)} ${n(y + a)}`,
+    a > 0 ? `A ${n(a)} ${n(a)} 0 0 1 ${n(x + a)} ${n(y)}` : '',
+    'Z',
+  ]
+    .filter(Boolean)
+    .join(' ')
+}
+
+/**
+ * Barra com arredondamento só na ponta do dado. A base fica reta porque encosta
+ * no eixo — arredondar os dois lados faz a barra parecer flutuar.
+ */
+export function caminhoBarra(
+  x: number,
+  y: number,
+  largura: number,
+  altura: number,
+  raio = 0,
+  ponta: PontaBarra = 'topo',
+): string {
+  // Valor zero (ou quase) ainda precisa ocupar uma linha: barra de altura 0 some
+  // e o leitor não distingue "zero" de "sem dado".
+  const larg = Math.max(0, largura)
+  const alt = Math.max(0, altura)
+
+  const cantos: Record<PontaBarra, [number, number, number, number]> = {
+    topo: [raio, raio, 0, 0],
+    base: [0, 0, raio, raio],
+    direita: [0, raio, raio, 0],
+    esquerda: [raio, 0, 0, raio],
+    nenhuma: [0, 0, 0, 0],
+  }
+
+  return retanguloArredondado(x, y, larg, alt, cantos[ponta])
+}
+
+// ── arco, pizza e rosca ────────────────────────────────────────────────────
+
+/** Ponto na circunferência. 0° aponta para a direita; cresce no sentido horário. */
+export function pontoNoArco(cx: number, cy: number, raio: number, anguloGraus: number): Ponto {
+  const rad = (anguloGraus * Math.PI) / 180
+  return { x: cx + raio * Math.cos(rad), y: cy + raio * Math.sin(rad) }
+}
+
+/** Acima disso tratamos como volta completa (ver armadilha no `caminhoSetor`). */
+const VOLTA_COMPLETA = 359.999
+
+/**
+ * Setor de pizza (`raioInterno = 0`) ou anel de rosca (`raioInterno > 0`).
+ *
+ * ⚠️ Armadilha do 100%: um arco cujo ponto inicial coincide com o final NÃO
+ * desenha nada em SVG — uma única categoria sumiria da tela, sem erro. Por isso
+ * a volta completa é emitida como DOIS arcos de 180°.
+ *
+ * ⚠️ `largeArcFlag` precisa ser 1 acima de 180°, senão o arco vai pelo lado
+ * curto e a fatia dominante aparece invertida.
+ */
+export function caminhoSetor(
+  cx: number,
+  cy: number,
+  raioExterno: number,
+  raioInterno: number,
+  anguloInicio: number,
+  anguloFim: number,
+): string {
+  const re = Math.max(0, raioExterno)
+  const ri = Math.max(0, Math.min(raioInterno, re))
+  const varredura = anguloFim - anguloInicio
+
+  if (varredura <= 0) return ''
+
+  const p = (raio: number, graus: number): string => {
+    const { x, y } = pontoNoArco(cx, cy, raio, graus)
+    return `${n(x)} ${n(y)}`
+  }
+
+  if (varredura >= VOLTA_COMPLETA) {
+    const meio = anguloInicio + 180
+    const externo =
+      `M ${p(re, anguloInicio)} A ${n(re)} ${n(re)} 0 1 1 ${p(re, meio)}` +
+      ` A ${n(re)} ${n(re)} 0 1 1 ${p(re, anguloInicio)} Z`
+    if (ri <= 0) return externo
+    // Subcaminho interno no sentido CONTRÁRIO: com fill-rule nonzero é isso que
+    // abre o furo da rosca.
+    const interno =
+      `M ${p(ri, anguloInicio)} A ${n(ri)} ${n(ri)} 0 1 0 ${p(ri, meio)}` +
+      ` A ${n(ri)} ${n(ri)} 0 1 0 ${p(ri, anguloInicio)} Z`
+    return `${externo} ${interno}`
+  }
+
+  const arcoGrande = varredura > 180 ? 1 : 0
+
+  if (ri <= 0) {
+    return [
+      `M ${n(cx)} ${n(cy)}`,
+      `L ${p(re, anguloInicio)}`,
+      `A ${n(re)} ${n(re)} 0 ${arcoGrande} 1 ${p(re, anguloFim)}`,
+      'Z',
+    ].join(' ')
+  }
+
+  return [
+    `M ${p(re, anguloInicio)}`,
+    `A ${n(re)} ${n(re)} 0 ${arcoGrande} 1 ${p(re, anguloFim)}`,
+    `L ${p(ri, anguloFim)}`,
+    `A ${n(ri)} ${n(ri)} 0 ${arcoGrande} 0 ${p(ri, anguloInicio)}`,
+    'Z',
+  ].join(' ')
+}
+
+/**
+ * Arco ABERTO — só a linha, sem fechar contra o centro. É o traçado do medidor:
+ * a espessura vem do `stroke-width` e a ponta redonda do `stroke-linecap`, o que
+ * o `caminhoSetor` (preenchido) não consegue dar.
+ *
+ * Convenção igual à do `pontoNoArco`: 0° à direita, crescendo no sentido
+ * horário. `anguloFim > anguloInicio` varre no horário.
+ *
+ * ⚠️ Mesma armadilha do setor de 100%: início coincidindo com o fim não desenha
+ * nada. Aqui a volta completa sai em dois arcos de 180°.
+ */
+export function caminhoArco(
+  cx: number,
+  cy: number,
+  raio: number,
+  anguloInicio: number,
+  anguloFim: number,
+): string {
+  const r = Math.max(0, raio)
+  const varredura = anguloFim - anguloInicio
+  if (r === 0 || varredura <= 0) return ''
+
+  const p = (graus: number): string => {
+    const { x, y } = pontoNoArco(cx, cy, r, graus)
+    return `${n(x)} ${n(y)}`
+  }
+
+  if (varredura >= VOLTA_COMPLETA) {
+    const meio = anguloInicio + 180
+    return (
+      `M ${p(anguloInicio)} A ${n(r)} ${n(r)} 0 1 1 ${p(meio)}` +
+      ` A ${n(r)} ${n(r)} 0 1 1 ${p(anguloInicio)}`
+    )
+  }
+
+  return `M ${p(anguloInicio)} A ${n(r)} ${n(r)} 0 ${varredura > 180 ? 1 : 0} 1 ${p(anguloFim)}`
+}
+
+/**
+ * Caixa que um arco de raio 1 centrado na origem ocupa.
+ *
+ * Existe porque o medidor NÃO é um círculo inteiro: um semicírculo de 180° usa
+ * só a metade de cima, e centrar pelo círculo completo desperdiçaria metade da
+ * altura — o arco sairia pequeno com uma faixa vazia embaixo. Amostrar os
+ * extremos e os cruzamentos de eixo dentro da varredura dá a caixa REAL, e o
+ * mesmo cálculo serve pra 180°, 270° ou volta completa.
+ *
+ * A origem entra na caixa de propósito: é onde mora o número no meio do medidor.
+ */
+export function caixaDoArco(
+  anguloInicio: number,
+  anguloFim: number,
+): { minX: number; maxX: number; minY: number; maxY: number } {
+  const amostras: Ponto[] = [
+    { x: 0, y: 0 },
+    pontoNoArco(0, 0, 1, anguloInicio),
+    pontoNoArco(0, 0, 1, anguloFim),
+  ]
+
+  // Os extremos de x e y de um arco só podem cair nas pontas ou onde ele cruza
+  // um dos quatro eixos.
+  const primeiroEixo = Math.ceil(anguloInicio / 90) * 90
+  for (let a = primeiroEixo; a < anguloFim; a += 90) {
+    amostras.push(pontoNoArco(0, 0, 1, a))
+  }
+
+  const xs = amostras.map((p) => p.x)
+  const ys = amostras.map((p) => p.y)
+  return {
+    minX: Math.min(...xs),
+    maxX: Math.max(...xs),
+    minY: Math.min(...ys),
+    maxY: Math.max(...ys),
+  }
+}
+
+export interface Fatia {
+  indice: number
+  valor: number
+  /** Participação no total, 0..1. É o que o rótulo mostra como percentual. */
+  fracao: number
+  anguloInicio: number
+  anguloFim: number
+}
+
+/**
+ * Converte valores em ângulos. Começa no topo (-90°) porque é onde o olho
+ * entra num gráfico circular.
+ *
+ * Valor negativo é ignorado: não existe fatia negativa, e somá-lo ao total
+ * distorceria todas as outras em silêncio.
+ */
+export function fatiasPizza(
+  valores: readonly number[],
+  opcoes: { anguloInicioGraus?: number; espacoGraus?: number } = {},
+): Fatia[] {
+  const inicioBase = opcoes.anguloInicioGraus ?? -90
+  const espaco = Math.max(0, opcoes.espacoGraus ?? 0)
+
+  const limpos = valores.map((v) => (Number.isFinite(v) && v > 0 ? v : 0))
+  const total = limpos.reduce((soma, v) => soma + v, 0)
+  if (total <= 0) return []
+
+  // O vão entre fatias sai do total, senão a soma passa de 360°.
+  const naoVazias = limpos.filter((v) => v > 0).length
+  const vaoTotal = naoVazias > 1 ? espaco * naoVazias : 0
+  const disponivel = 360 - vaoTotal
+
+  let cursor = inicioBase
+  return limpos.map((valor, indice) => {
+    const fracao = valor / total
+    const varredura = fracao * disponivel
+    const fatia: Fatia = {
+      indice,
+      valor,
+      fracao,
+      anguloInicio: cursor,
+      anguloFim: cursor + varredura,
+    }
+    cursor = fatia.anguloFim + (valor > 0 && naoVazias > 1 ? espaco : 0)
+    return fatia
+  })
+}
+
+// ── marcador ───────────────────────────────────────────────────────────────
+
+/**
+ * Marcador do ponto, como `path` (e não `<circle>`/`<rect>`) para a legenda
+ * poder reaproveitar exatamente a mesma forma do gráfico.
+ *
+ * A forma é o SEGUNDO canal de codificação, além da cor: é o que mantém as
+ * séries distinguíveis em impressão P&B e para quem não vê cor (eMAG 4.2).
+ */
+export function caminhoMarcador(
+  tipo: MarcadorSerie,
+  cx: number,
+  cy: number,
+  tamanho: number,
+): string {
+  const r = Math.max(0, tamanho) / 2
+  if (r === 0 || tipo === 'none') return ''
+
+  switch (tipo) {
+    case 'square':
+      return `M ${n(cx - r)} ${n(cy - r)} H ${n(cx + r)} V ${n(cy + r)} H ${n(cx - r)} Z`
+    case 'triangle':
+      return `M ${n(cx)} ${n(cy - r)} L ${n(cx + r)} ${n(cy + r)} L ${n(cx - r)} ${n(cy + r)} Z`
+    case 'diamond':
+      return `M ${n(cx)} ${n(cy - r)} L ${n(cx + r)} ${n(cy)} L ${n(cx)} ${n(cy + r)} L ${n(cx - r)} ${n(cy)} Z`
+    case 'cross': {
+      const b = r / 2.5
+      return (
+        `M ${n(cx - b)} ${n(cy - r)} H ${n(cx + b)} V ${n(cy - b)} H ${n(cx + r)}` +
+        ` V ${n(cy + b)} H ${n(cx + b)} V ${n(cy + r)} H ${n(cx - b)}` +
+        ` V ${n(cy + b)} H ${n(cx - r)} V ${n(cy - b)} H ${n(cx - b)} Z`
+      )
+    }
+    case 'circle':
+    default:
+      // Círculo em dois arcos pelo mesmo motivo do setor de 100%.
+      return (
+        `M ${n(cx - r)} ${n(cy)} A ${n(r)} ${n(r)} 0 1 0 ${n(cx + r)} ${n(cy)}` +
+        ` A ${n(r)} ${n(r)} 0 1 0 ${n(cx - r)} ${n(cy)} Z`
+      )
+  }
+}
+
+/** Marcador do índice da série. Ciclo de 5, alinhado com os 5 slots de cor. */
+const CICLO_MARCADORES: readonly MarcadorSerie[] = [
+  'circle',
+  'square',
+  'triangle',
+  'diamond',
+  'cross',
+]
+
+export function marcadorDaSerie(indice: number): MarcadorSerie {
+  if (indice < 0) return 'circle'
+  return CICLO_MARCADORES[indice % CICLO_MARCADORES.length] as MarcadorSerie
+}