acai-ui 1.65.5

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

@@ -0,0 +1,141 @@
+// Escalas — a ponte entre o VALOR do dado e o PIXEL do SVG.
+//
+// Duas famílias, como em qualquer gramática de gráfico:
+//   • linear  — valor contínuo → posição (eixo de valor);
+//   • banda   — índice de categoria → faixa (eixo de categoria).
+// A sub-banda é o que permite barra AGRUPADA: dentro da banda de "Janeiro",
+// cada série ganha a sua própria fatia.
+//
+// Livre de DOM. Todas devolvem função CHAMÁVEL com metadados anexados, pra o
+// código de desenho ficar `x(valor)` em vez de `escala.aplicar(valor)`.
+
+export interface EscalaLinear {
+  (valor: number): number
+  /** Pixel → valor. Usado pelo tooltip e pelo crosshair. */
+  inverter(px: number): number
+  readonly dominio: readonly [number, number]
+  readonly faixa: readonly [number, number]
+}
+
+/**
+ * Escala contínua. A `faixa` normalmente vem INVERTIDA no eixo Y
+ * (`[base, topo]` = `[150, 10]`), porque em SVG o y cresce para baixo.
+ */
+export function escalaLinear(
+  dominio: readonly [number, number],
+  faixa: readonly [number, number],
+): EscalaLinear {
+  const [d0, d1] = dominio
+  const [f0, f1] = faixa
+  const amplitude = d1 - d0
+
+  // Domínio degenerado (série constante que escapou do dominioBonito, ou dado
+  // vazio): devolve o MEIO da faixa em vez de NaN. Um NaN aqui vira `d="M NaN"`
+  // e o SVG some inteiro, sem erro no console — o pior tipo de bug.
+  const degenerado = amplitude === 0 || !Number.isFinite(amplitude)
+
+  const escala = ((valor: number): number => {
+    if (degenerado) return (f0 + f1) / 2
+    if (!Number.isFinite(valor)) return NaN
+    return f0 + ((valor - d0) / amplitude) * (f1 - f0)
+  }) as EscalaLinear
+
+  return Object.assign(escala, {
+    inverter(px: number): number {
+      if (degenerado || f1 === f0) return d0
+      return d0 + ((px - f0) / (f1 - f0)) * amplitude
+    },
+    dominio,
+    faixa,
+  })
+}
+
+export interface EscalaBanda {
+  /** Início (x ou y) da banda `indice`. */
+  (indice: number): number
+  /** Largura útil de uma banda (já descontado o espaço interno). */
+  readonly larguraBanda: number
+  /** Distância entre inícios de bandas consecutivas. */
+  readonly passo: number
+  readonly quantidade: number
+  /** Centro da banda — onde vai o rótulo do eixo e o ponto da linha. */
+  centro(indice: number): number
+  /** Índice da banda sob a coordenada, já limitado às pontas. Para tooltip/teclado. */
+  indiceEm(px: number): number
+}
+
+export interface OpcoesBanda {
+  /** Fração do passo virando vão ENTRE bandas (0..1). Default 0.2. */
+  espacoInterno?: number
+  /** Fração do passo virando vão nas PONTAS (0..1). Default 0.1. */
+  espacoExterno?: number
+}
+
+/**
+ * Escala de categoria. Mesmo cálculo do d3-scale-band: o passo absorve os vãos
+ * interno e externo, e o conjunto fica centrado na faixa.
+ */
+export function escalaBanda(
+  quantidade: number,
+  faixa: readonly [number, number],
+  opcoes: OpcoesBanda = {},
+): EscalaBanda {
+  const espacoInterno = Math.min(0.95, Math.max(0, opcoes.espacoInterno ?? 0.2))
+  const espacoExterno = Math.max(0, opcoes.espacoExterno ?? 0.1)
+  const [f0, f1] = faixa
+  const n = Math.max(0, Math.floor(quantidade))
+
+  // Sem categorias não há divisão possível — e `n` no denominador viraria /0,
+  // devolvendo Infinity pra toda posição.
+  if (n === 0) {
+    const vazia = ((_indice: number): number => f0) as EscalaBanda
+    return Object.assign(vazia, {
+      larguraBanda: 0,
+      passo: 0,
+      quantidade: 0,
+      centro: (_indice: number): number => f0,
+      indiceEm: (_px: number): number => 0,
+    })
+  }
+
+  const passo = (f1 - f0) / Math.max(1, n - espacoInterno + espacoExterno * 2)
+  const larguraBanda = passo * (1 - espacoInterno)
+  const inicio = f0 + (f1 - f0 - passo * (n - espacoInterno)) / 2
+
+  const escala = ((indice: number): number => inicio + passo * indice) as EscalaBanda
+
+  return Object.assign(escala, {
+    larguraBanda,
+    passo,
+    quantidade: n,
+    centro: (indice: number): number => inicio + passo * indice + larguraBanda / 2,
+    indiceEm(px: number): number {
+      if (passo === 0) return 0
+      const cru = Math.floor((px - inicio) / passo)
+      return Math.min(n - 1, Math.max(0, cru))
+    },
+  })
+}
+
+/**
+ * Sub-bandas DENTRO de uma banda — é o que faz barra agrupada.
+ *
+ * Devolve posições RELATIVAS ao início da banda-mãe, então o desenho fica
+ * `banda(i) + sub(s)`. Sem espaço externo de propósito: o vão nas pontas já é
+ * o da banda-mãe, e somar de novo deixaria as barras do grupo espremidas.
+ */
+export function escalaSubBanda(
+  banda: EscalaBanda,
+  quantidadeSeries: number,
+  espacoInterno = 0.1,
+): EscalaBanda {
+  // Série única: não existe vão ENTRE séries pra abrir, então o espaço interno
+  // vira desperdício puro. Sem esta guarda, o caso mais comum de todos (gráfico
+  // de uma série só) sai com a barra ~10% mais estreita do que a banda permite.
+  const vao = quantidadeSeries <= 1 ? 0 : espacoInterno
+
+  return escalaBanda(quantidadeSeries, [0, banda.larguraBanda], {
+    espacoInterno: vao,
+    espacoExterno: 0,
+  })
+}

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

@@ -0,0 +1,98 @@
+// Formatação de valor pt-BR para eixo, rótulo e tooltip.
+//
+// Existe pra o consumidor NÃO precisar passar um formatador em toda tela: o
+// gráfico olha a amostra e decide sozinho se mostra casas decimais. Quem quiser
+// controle passa `valueFormat` (nome ou função) e ganha o controle inteiro.
+
+/** Formatos prontos. Qualquer coisa fora disso, passe uma função. */
+export type FormatoValor = 'auto' | 'integer' | 'decimal' | 'currency' | 'percent' | 'compact'
+
+// Criar um Intl.NumberFormat por ponto é o gargalo real numa série de 500
+// pontos — a construção é cara, a formatação não. Memoiza por assinatura.
+// Sem estado observável de fora, então continua tree-shakeable.
+const cache = new Map<string, Intl.NumberFormat>()
+
+function formatador(opcoes: Intl.NumberFormatOptions): Intl.NumberFormat {
+  const chave = JSON.stringify(opcoes)
+  let achado = cache.get(chave)
+  if (!achado) {
+    achado = new Intl.NumberFormat('pt-BR', opcoes)
+    cache.set(chave, achado)
+  }
+  return achado
+}
+
+/** Valor que não dá pra desenhar. Melhor um travessão do que "NaN" no eixo. */
+const VAZIO = '—'
+
+/** Número pt-BR: ponto de milhar, vírgula decimal. */
+export function formatarNumeroGrafico(valor: number, casas = 0): string {
+  if (!Number.isFinite(valor)) return VAZIO
+  const c = Math.max(0, Math.min(20, casas))
+  return formatador({ minimumFractionDigits: c, maximumFractionDigits: c }).format(valor)
+}
+
+/**
+ * Notação compacta: 1.200 → "1,2 mil", 3.400.000 → "3,4 mi".
+ * É o que salva o eixo Y quando os valores têm 7 dígitos e o rótulo não cabe.
+ */
+export function formatarCompacto(valor: number): string {
+  if (!Number.isFinite(valor)) return VAZIO
+  return formatador({ notation: 'compact', maximumFractionDigits: 1 }).format(valor)
+}
+
+export function formatarMoedaGrafico(valor: number, casas = 2): string {
+  if (!Number.isFinite(valor)) return VAZIO
+  const c = Math.max(0, Math.min(20, casas))
+  return formatador({
+    style: 'currency',
+    currency: 'BRL',
+    minimumFractionDigits: c,
+    maximumFractionDigits: c,
+  }).format(valor)
+}
+
+/** Percentual. Recebe o número JÁ em escala de 0-100 (12,3 → "12,3%"). */
+export function formatarPercentualGrafico(valor: number, casas = 1): string {
+  if (!Number.isFinite(valor)) return VAZIO
+  return `${formatarNumeroGrafico(valor, casas)}%`
+}
+
+/** Todos os valores da amostra são inteiros? Decide o `auto`. */
+function tudoInteiro(amostra: readonly number[]): boolean {
+  return amostra.every((v) => !Number.isFinite(v) || Number.isInteger(v))
+}
+
+/**
+ * Devolve a função que o gráfico vai usar em todo valor.
+ *
+ * `auto` olha a AMOSTRA: série de contagem (tudo inteiro) sai sem casas —
+ * "1.204", não "1.204,00". Série com fração ganha 2 casas. É a regra que
+ * dispensa o consumidor de configurar o caso comum.
+ */
+export function resolverFormatador(
+  formato: FormatoValor | ((valor: number) => string) | undefined,
+  casas: number | undefined,
+  amostra: readonly number[] = [],
+): (valor: number) => string {
+  if (typeof formato === 'function') return formato
+
+  switch (formato) {
+    case 'integer':
+      return (v) => formatarNumeroGrafico(v, 0)
+    case 'decimal':
+      return (v) => formatarNumeroGrafico(v, casas ?? 2)
+    case 'currency':
+      return (v) => formatarMoedaGrafico(v, casas ?? 2)
+    case 'percent':
+      return (v) => formatarPercentualGrafico(v, casas ?? 1)
+    case 'compact':
+      return formatarCompacto
+    case 'auto':
+    case undefined:
+    default: {
+      const padrao = casas ?? (tudoInteiro(amostra) ? 0 : 2)
+      return (v) => formatarNumeroGrafico(v, padrao)
+    }
+  }
+}

package/src/components/chart/chart-gauge.vue

@@ -0,0 +1,152 @@
+<template>
+  <g class="acai-chart-gauge">
+    <!--
+      Trilho: as faixas de threshold quando pedidas, senão um arco neutro só.
+      O trilho existe mesmo com valor nulo — é o que diz "a escala vai até aqui",
+      e sem ele um valor baixo pareceria um gráfico quebrado.
+    -->
+    <template v-if="plano.faixas.length > 0">
+      <path
+        v-for="faixa in plano.faixas"
+        :key="faixa.chave"
+        class="acai-chart-gauge__arco"
+        :d="faixa.d"
+        :stroke="faixa.cor"
+        :stroke-width="plano.espessura"
+      />
+    </template>
+    <path
+      v-else
+      class="acai-chart-gauge__arco acai-chart-gauge__trilho"
+      :d="plano.dTrilho"
+      :stroke-width="plano.espessura"
+    />
+
+    <path
+      v-if="plano.dProgresso"
+      class="acai-chart-gauge__arco acai-chart-gauge__progresso"
+      :class="{ 'acai-chart-gauge__progresso--sobre-faixas': plano.faixas.length > 0 }"
+      :d="plano.dProgresso"
+      :stroke="plano.cor"
+      :stroke-width="progressoEspessura"
+    />
+
+    <!--
+      Halo primeiro, traço depois: o marcador tem que ser legível sobre verde,
+      amarelo ou vermelho, e escolher tinta clara ou escura por faixa não escala.
+      Mesma solução do rótulo interno da pizza.
+    -->
+    <template v-if="plano.dMarcadorValor">
+      <path class="acai-chart-gauge__marcador-halo" :d="plano.dMarcadorValor" />
+      <path class="acai-chart-gauge__marcador" :d="plano.dMarcadorValor" />
+    </template>
+
+    <path v-if="plano.dPonteiro" class="acai-chart-gauge__ponteiro" :d="plano.dPonteiro" :fill="plano.cor" />
+    <path v-if="plano.dEixoPonteiro" class="acai-chart-gauge__eixo" :d="plano.dEixoPonteiro" />
+
+    <!--
+      Rótulos das pontas. Sem eles o arco não tem escala: 40% preenchido pode ser
+      40 de 100 ou 400 de 1000, e o leitor não tem como saber.
+    -->
+    <g v-if="plano.mostrarEscala" class="acai-chart-gauge__escala" aria-hidden="true">
+      <text :x="plano.minX" :y="plano.rotulosY" text-anchor="middle">{{ plano.minFormatado }}</text>
+      <text :x="plano.maxX" :y="plano.rotulosY" text-anchor="middle">{{ plano.maxFormatado }}</text>
+    </g>
+
+    <!-- Número dentro do SVG de propósito: overlay HTML não entra no export. -->
+    <g class="acai-chart-gauge__centro" aria-hidden="true">
+      <text
+        class="acai-chart-gauge__valor"
+        :x="plano.textoX"
+        :y="plano.textoY"
+        text-anchor="middle"
+        dominant-baseline="auto"
+      >
+        {{ plano.valorFormatado }}
+      </text>
+      <text
+        v-if="plano.legenda"
+        class="acai-chart-gauge__legenda"
+        :x="plano.textoX"
+        :y="plano.legendaY"
+        text-anchor="middle"
+        dominant-baseline="auto"
+      >
+        {{ plano.legenda }}
+      </text>
+    </g>
+  </g>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import type { PlanoGauge } from './chart-plano'
+
+const props = defineProps<{ plano: PlanoGauge }>()
+
+/**
+ * Sobre as faixas coloridas o progresso desenha mais FINO, centrado no mesmo
+ * raio: com a espessura cheia ele cobriria as faixas e a escala de risco que
+ * elas mostram desapareceria justo no trecho que interessa.
+ */
+const progressoEspessura = computed(() =>
+  props.plano.faixas.length > 0 ? Math.max(4, props.plano.espessura * 0.45) : props.plano.espessura,
+)
+</script>
+
+<style lang="scss" scoped>
+.acai-chart-gauge {
+  &__arco {
+    fill: none;
+    // Ponta redonda: é o que dá o acabamento de medidor. Em valor muito baixo o
+    // cap ainda desenha um pinguinho — melhor que o arco sumir.
+    stroke-linecap: round;
+  }
+
+  &__trilho {
+    stroke: var(--acai-chart-track);
+  }
+
+  &__marcador-halo {
+    fill: none;
+    stroke: var(--acai-chart-surface);
+    stroke-width: 5;
+    stroke-linecap: round;
+  }
+
+  &__marcador {
+    fill: none;
+    stroke: var(--acai-chart-ink);
+    stroke-width: 2.5;
+    stroke-linecap: round;
+  }
+
+  &__ponteiro {
+    stroke: var(--acai-chart-surface);
+    stroke-width: 1;
+  }
+
+  &__eixo {
+    fill: var(--acai-chart-surface);
+    stroke: var(--acai-chart-axis);
+    stroke-width: 1.5;
+  }
+
+  &__escala text {
+    // rem e não atributo: acompanha a preferência de tamanho de fonte.
+    font-size: 0.6875rem;
+    fill: var(--acai-chart-ink-muted);
+  }
+
+  &__valor {
+    font-size: 1.75rem;
+    font-weight: 700;
+    fill: var(--acai-chart-ink);
+  }
+
+  &__legenda {
+    font-size: 0.75rem;
+    fill: var(--acai-chart-ink-muted);
+  }
+}
+</style>

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

@@ -0,0 +1,130 @@
+// Render fora da árvore — gráfico que NUNCA aparece na tela e ainda assim vira PNG.
+//
+// É o caso do gerador de Book/PDF: ele percorre 11 relatórios e precisa da figura
+// de cada um sem que nenhuma delas seja montada numa página. Com componente Vue a
+// única forma honesta é montar de verdade, medir, exportar e desmontar — o que
+// exige um container com LAYOUT REAL, e é aí que estão as armadilhas.
+
+import { createApp, nextTick } from 'vue'
+import AcaiUiChart from './acai-ui-chart.vue'
+import type { ImagemChart, OpcoesImagemChart } from './chart-imagem'
+import type { ChartProps } from './acai-ui-chart-interface'
+
+export interface OpcoesImagemHeadless extends OpcoesImagemChart {
+  /** Largura da figura em CSS px. Default 800. */
+  largura?: number
+  /** Altura da figura em CSS px. Default 400. */
+  altura?: number
+}
+
+/** Espera o Vue renderizar E o gráfico se medir. */
+function proximoFrame(): Promise<void> {
+  return new Promise((resolver) => {
+    if (typeof requestAnimationFrame === 'undefined') {
+      setTimeout(resolver, 16)
+      return
+    }
+    requestAnimationFrame(() => resolver())
+  })
+}
+
+/**
+ * Dois frames, não um.
+ *
+ * O `useTamanhoElemento` mede no `onMounted` e AGENDA uma segunda medição via
+ * `requestAnimationFrame` (pra pegar a fonte já diagramada). Exportar no primeiro
+ * frame pegaria o gráfico no tamanho PADRÃO — 640×320 — em vez do pedido, sem
+ * erro nenhum: a imagem simplesmente sairia com a proporção errada.
+ */
+async function esperarDesenho(): Promise<void> {
+  await nextTick()
+  await proximoFrame()
+  await proximoFrame()
+  await nextTick()
+}
+
+interface InstanciaChart {
+  exportarImagem?: (opcoes?: OpcoesImagemChart) => Promise<ImagemChart>
+}
+
+/**
+ * Desenha um `<acai-ui-chart>` fora da tela e devolve o PNG.
+ *
+ * ```ts
+ * const { dataUrl, proporcao } = await chartParaImagem(
+ *   { type: 'bar', data: municipios, title: '10 municípios com as maiores frotas' },
+ *   { largura: 1240, altura: 620 },
+ * )
+ * pdf.addImage(dataUrl, 'PNG', x, y, largura, largura / proporcao)
+ * ```
+ *
+ * ⚠️ **A legenda não entra na imagem.** Ela é HTML ao lado do SVG, e o raster
+ * captura só o SVG. Em gráfico de série múltipla, ligue `showValues` ou identifique
+ * as séries no texto do relatório. Por isso a legenda é forçada pra baixo aqui: no
+ * `legendPosition: 'right'` ela roubaria largura do SVG e o desenho sairia estreito
+ * sem que nada aparecesse no lugar.
+ */
+export async function chartParaImagem(
+  props: ChartProps,
+  opcoes: OpcoesImagemHeadless = {},
+): Promise<ImagemChart> {
+  if (typeof document === 'undefined') {
+    throw new Error('acai-ui-chart: chartParaImagem exige navegador.')
+  }
+
+  const largura = Math.max(1, Math.round(opcoes.largura ?? 800))
+  const altura = Math.max(1, Math.round(opcoes.altura ?? 400))
+
+  const container = document.createElement('div')
+  container.setAttribute('aria-hidden', 'true')
+  // Fora da tela por POSIÇÃO, nunca por `display:none` nem `visibility:hidden`:
+  // sem layout a caixa mede 0 e o `useTamanhoElemento` mantém o padrão de
+  // propósito, então o gráfico sairia no tamanho errado. `opacity: 0` não
+  // remove layout — é o que torna o truque seguro.
+  container.style.cssText = [
+    'position:fixed',
+    'left:-10000px',
+    'top:0',
+    `width:${largura}px`,
+    `height:${altura}px`,
+    'opacity:0',
+    'pointer-events:none',
+    'z-index:-1',
+  ].join(';')
+
+  document.body.appendChild(container)
+
+  const app = createApp(AcaiUiChart, {
+    ...props,
+    height: altura,
+    legendPosition: 'bottom',
+    // Nada disso vai pro raster, e a tabela oculta ainda custa DOM por linha.
+    dataTable: false,
+    tableToggle: false,
+    loading: false,
+  })
+
+  try {
+    const instancia = app.mount(container) as unknown as InstanciaChart
+    await esperarDesenho()
+
+    if (typeof instancia.exportarImagem !== 'function') {
+      throw new Error('acai-ui-chart: instância montada sem exportarImagem.')
+    }
+
+    // `exactOptionalPropertyTypes`: montar o objeto com spread condicional em vez
+    // de passar `undefined` explícito nas chaves opcionais.
+    return await instancia.exportarImagem({
+      ...(opcoes.escala === undefined ? {} : { escala: opcoes.escala }),
+      ...(opcoes.fundo === undefined ? {} : { fundo: opcoes.fundo }),
+    })
+  } finally {
+    // `finally` e não depois do return: erro no meio do caminho não pode deixar
+    // um app Vue montado e um `<div>` fantasma no `<body>` a cada relatório.
+    app.unmount()
+    container.remove()
+  }
+}
+
+export { svgChartParaImagem, serializarSvgChart } from './chart-imagem'
+export type { ImagemChart, OpcoesImagemChart, SvgSerializado } from './chart-imagem'