@hed-hog/core 0.0.400 → 0.0.401

package/src/pdf/document/charts/chart-primitives.ts

@@ -0,0 +1,188 @@
+import { escapeHtml } from '../pdf-document.renderer';
+import { PdfDocumentTheme } from '../pdf-document.theme';
+import { asSafeSvg, SafeSvg } from '../pdf-document.types';
+import { estimateTextWidth, formatNumber, truncateToWidth } from './chart-scale';
+
+/** Opções comuns a todos os gráficos do kit. */
+export interface ChartBaseOptions {
+  theme: PdfDocumentTheme;
+  /** Padrão 682px — a largura útil de um A4 retrato com as margens do documento. */
+  width?: number;
+  height?: number;
+  /** Descrição para leitor de tela; vira `<title>` do SVG. */
+  ariaLabel?: string;
+  valueFormat?: (value: number) => string;
+  emptyText?: string;
+}
+
+export interface ChartSeries {
+  name: string;
+  values: Array<number | null>;
+  color?: string;
+}
+
+/** Largura útil do A4 retrato com as margens de 56px do documento padrão. */
+export const CHART_FULL_WIDTH = 682;
+/** Largura de cada gráfico numa grade de duas colunas. */
+export const CHART_HALF_WIDTH = 330;
+export const CHART_DEFAULT_HEIGHT = 220;
+
+/** Tamanhos de fonte. Abaixo de 8px o texto ainda imprime, mas não se lê na tela. */
+export const CHART_FONT = { axis: 8, value: 9, legend: 9 };
+
+export const chartColor = (theme: PdfDocumentTheme, index: number, override?: string): string =>
+  override ?? theme.chartPalette[index % theme.chartPalette.length] ?? theme.primary;
+
+export const text = (
+  content: string,
+  x: number,
+  y: number,
+  options: {
+    size?: number;
+    fill?: string;
+    anchor?: 'start' | 'middle' | 'end';
+    weight?: number;
+    rotate?: number;
+  } = {},
+): string => {
+  const { size = CHART_FONT.axis, fill = '#71717a', anchor = 'start', weight = 400, rotate } = options;
+  const transform = rotate ? ` transform="rotate(${rotate} ${x} ${y})"` : '';
+
+  return (
+    `<text x="${x}" y="${y}" font-size="${size}" fill="${fill}" text-anchor="${anchor}" ` +
+    `font-weight="${weight}"${transform}>${escapeHtml(content)}</text>`
+  );
+};
+
+export const line = (
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  stroke: string,
+  options: { width?: number; dash?: string } = {},
+): string =>
+  `<line x1="${x1}" y1="${y1}" x2="${x2}" y2="${y2}" stroke="${stroke}" ` +
+  `stroke-width="${options.width ?? 1}"${options.dash ? ` stroke-dasharray="${options.dash}"` : ''} ` +
+  'shape-rendering="crispEdges" />';
+
+/** Envelope do SVG. `viewBox` + largura relativa deixam o gráfico acompanhar a página. */
+export function svgRoot(
+  width: number,
+  height: number,
+  body: string,
+  ariaLabel?: string,
+): SafeSvg {
+  return asSafeSvg(
+    `<svg viewBox="0 0 ${width} ${height}" width="100%" height="${height}" ` +
+      `xmlns="http://www.w3.org/2000/svg" role="img">` +
+      (ariaLabel ? `<title>${escapeHtml(ariaLabel)}</title>` : '') +
+      body +
+      '</svg>',
+  );
+}
+
+/** Placeholder de gráfico sem dados — melhor que uma moldura vazia sem explicação. */
+export function emptyChart(options: ChartBaseOptions): SafeSvg {
+  const width = options.width ?? CHART_FULL_WIDTH;
+  const height = options.height ?? CHART_DEFAULT_HEIGHT;
+  const label = options.emptyText ?? 'Sem dados no período';
+
+  return svgRoot(
+    width,
+    height,
+    `<rect x="0.5" y="0.5" width="${width - 1}" height="${height - 1}" fill="none" ` +
+      `stroke="${options.theme.line}" stroke-dasharray="4 3" rx="8" />` +
+      text(label, width / 2, height / 2, {
+        size: 10,
+        fill: options.theme.mutedFg,
+        anchor: 'middle',
+      }),
+    options.ariaLabel,
+  );
+}
+
+/** Legenda em uma linha, com quebra automática quando não cabe. */
+export function legendRows(
+  entries: Array<{ label: string; color: string }>,
+  width: number,
+  y: number,
+  theme: PdfDocumentTheme,
+): { markup: string; height: number } {
+  const gap = 14;
+  const swatch = 8;
+  let cursorX = 0;
+  let cursorY = y;
+  const parts: string[] = [];
+
+  for (const entry of entries) {
+    const labelWidth = estimateTextWidth(entry.label, CHART_FONT.legend);
+    const entryWidth = swatch + 4 + labelWidth + gap;
+
+    if (cursorX > 0 && cursorX + entryWidth > width) {
+      cursorX = 0;
+      cursorY += 13;
+    }
+
+    parts.push(
+      `<rect x="${cursorX}" y="${cursorY - swatch + 1}" width="${swatch}" height="${swatch}" rx="2" fill="${entry.color}" />`,
+      text(entry.label, cursorX + swatch + 4, cursorY, {
+        size: CHART_FONT.legend,
+        fill: theme.mutedFg,
+      }),
+    );
+
+    cursorX += entryWidth;
+  }
+
+  return { markup: parts.join(''), height: cursorY - y + 13 };
+}
+
+/** Grade horizontal + rótulos do eixo Y. */
+export function yAxis(
+  ticks: number[],
+  scale: (value: number) => number,
+  plot: { left: number; right: number },
+  theme: PdfDocumentTheme,
+  format: (value: number) => string = (value) => formatNumber(value),
+): string {
+  return ticks
+    .map((tick) => {
+      const y = scale(tick);
+      return (
+        line(plot.left, y, plot.right, y, theme.line) +
+        text(format(tick), plot.left - 5, y + 3, {
+          fill: theme.mutedFg,
+          anchor: 'end',
+          size: CHART_FONT.axis,
+        })
+      );
+    })
+    .join('');
+}
+
+/** Rótulos do eixo X, já cortados e girados conforme o espaço. */
+export function xAxisLabels(
+  labels: string[],
+  center: (index: number) => number,
+  baseline: number,
+  plan: { rotate: 0 | -35; skipEvery: number },
+  bandwidth: number,
+  theme: PdfDocumentTheme,
+): string {
+  return labels
+    .map((label, index) => {
+      if (index % plan.skipEvery !== 0) return '';
+
+      const x = center(index);
+      const maxWidth = plan.rotate === 0 ? bandwidth : bandwidth * 3;
+
+      return text(truncateToWidth(label, CHART_FONT.axis, maxWidth), x, baseline, {
+        fill: theme.mutedFg,
+        anchor: plan.rotate === 0 ? 'middle' : 'end',
+        size: CHART_FONT.axis,
+        rotate: plan.rotate,
+      });
+    })
+    .join('');
+}

package/src/pdf/document/charts/chart-radar.ts

@@ -0,0 +1,136 @@
+import { SafeSvg } from '../pdf-document.types';
+import {
+  CHART_DEFAULT_HEIGHT,
+  CHART_FONT,
+  CHART_FULL_WIDTH,
+  ChartBaseOptions,
+  ChartSeries,
+  chartColor,
+  emptyChart,
+  legendRows,
+  svgRoot,
+  text,
+} from './chart-primitives';
+import { formatNumber, niceScale, truncateToWidth, withAlpha } from './chart-scale';
+
+/**
+ * Radar de eixos comparáveis — a forma da tela para "nota média por tópico",
+ * onde todos os eixos compartilham a mesma escala (0 a 5).
+ */
+export function radarChartSvg(
+  options: ChartBaseOptions & {
+    axes: string[];
+    series: ChartSeries[];
+    max?: number;
+    rings?: number;
+  },
+): SafeSvg {
+  const {
+    theme,
+    axes,
+    series,
+    width = CHART_FULL_WIDTH,
+    height = CHART_DEFAULT_HEIGHT,
+    rings = 4,
+    valueFormat = (value: number) => formatNumber(value),
+  } = options;
+
+  const values = series
+    .flatMap((s) => s.values)
+    .filter((v): v is number => typeof v === 'number' && Number.isFinite(v));
+
+  // Abaixo de 3 eixos o radar vira uma linha ou um triângulo degenerado, que
+  // engana mais do que informa.
+  if (axes.length < 3 || values.length === 0) return emptyChart(options);
+
+  const max = options.max ?? niceScale(0, Math.max(...values), rings).max;
+  const showLegend = series.length > 1;
+  const legendHeight = showLegend ? 16 : 0;
+
+  const cx = width / 2;
+  const cy = (height - legendHeight) / 2;
+  const radius = Math.min(cx, cy) - 26;
+
+  const angleOf = (index: number) => (index / axes.length) * Math.PI * 2 - Math.PI / 2;
+  const point = (index: number, value: number) => {
+    const ratio = max === 0 ? 0 : Math.min(Math.max(value / max, 0), 1);
+    const angle = angleOf(index);
+    return { x: cx + radius * ratio * Math.cos(angle), y: cy + radius * ratio * Math.sin(angle) };
+  };
+
+  const parts: string[] = [];
+
+  for (let ring = 1; ring <= rings; ring += 1) {
+    const r = (radius * ring) / rings;
+    const polygon = axes
+      .map((_, index) => {
+        const angle = angleOf(index);
+        return `${(cx + r * Math.cos(angle)).toFixed(1)},${(cy + r * Math.sin(angle)).toFixed(1)}`;
+      })
+      .join(' ');
+
+    parts.push(`<polygon points="${polygon}" fill="none" stroke="${theme.line}" stroke-width="1" />`);
+  }
+
+  axes.forEach((axis, index) => {
+    const angle = angleOf(index);
+    const edgeX = cx + radius * Math.cos(angle);
+    const edgeY = cy + radius * Math.sin(angle);
+
+    parts.push(
+      `<line x1="${cx}" y1="${cy}" x2="${edgeX.toFixed(1)}" y2="${edgeY.toFixed(1)}" stroke="${theme.line}" />`,
+    );
+
+    const labelX = cx + (radius + 12) * Math.cos(angle);
+    const labelY = cy + (radius + 12) * Math.sin(angle) + 3;
+    const anchor = Math.abs(Math.cos(angle)) < 0.3 ? 'middle' : Math.cos(angle) > 0 ? 'start' : 'end';
+
+    parts.push(
+      text(truncateToWidth(axis, CHART_FONT.axis, 90), labelX, labelY, {
+        size: CHART_FONT.axis,
+        fill: theme.mutedFg,
+        anchor,
+      }),
+    );
+  });
+
+  series.forEach((serie, serieIndex) => {
+    const color = chartColor(theme, serieIndex, serie.color);
+    const points = axes.map((_, index) => {
+      const raw = serie.values[index];
+      return point(index, typeof raw === 'number' && Number.isFinite(raw) ? raw : 0);
+    });
+
+    parts.push(
+      `<polygon points="${points.map((p) => `${p.x.toFixed(1)},${p.y.toFixed(1)}`).join(' ')}" ` +
+        `fill="${withAlpha(color, 0.18)}" stroke="${color}" stroke-width="1.8" stroke-linejoin="round" />`,
+    );
+
+    points.forEach((p) => {
+      parts.push(`<circle cx="${p.x.toFixed(1)}" cy="${p.y.toFixed(1)}" r="2" fill="${color}" />`);
+    });
+  });
+
+  parts.push(
+    text(`Escala 0 a ${valueFormat(max)}`, width, height - legendHeight - 2, {
+      size: CHART_FONT.axis,
+      fill: theme.mutedFg,
+      anchor: 'end',
+    }),
+  );
+
+  if (showLegend) {
+    const legend = legendRows(
+      series.map((serie, index) => ({
+        label: serie.name,
+        color: chartColor(theme, index, serie.color),
+      })),
+      width,
+      height - 4,
+      theme,
+    );
+    parts.push(legend.markup);
+  }
+
+  return svgRoot(width, height, parts.join(''), options.ariaLabel);
+}

package/src/pdf/document/charts/chart-scale.spec.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from '@jest/globals';
+
+import {
+  axisLabelPlan,
+  bandScale,
+  estimateTextWidth,
+  linearScale,
+  niceScale,
+  truncateToWidth,
+  withAlpha,
+} from './chart-scale';
+
+describe('niceScale', () => {
+  it('arredonda o topo para um valor redondo', () => {
+    const scale = niceScale(0, 97, 4);
+
+    expect(scale.max).toBe(100);
+    expect(scale.step).toBe(25);
+    expect(scale.ticks).toEqual([0, 25, 50, 75, 100]);
+  });
+
+  // Uma série constante (ou toda zero) não tem amplitude: sem este caso a
+  // divisão pelo intervalo daria NaN e o gráfico sairia vazio.
+  it('sobrevive a série sem amplitude', () => {
+    expect(niceScale(0, 0).ticks.length).toBeGreaterThan(1);
+    expect(niceScale(7, 7).max).toBe(7);
+    expect(niceScale(7, 7).ticks.every((t) => Number.isFinite(t))).toBe(true);
+  });
+
+  it('inclui o último tick apesar do erro de ponto flutuante', () => {
+    const scale = niceScale(0, 0.3, 3);
+
+    expect(scale.ticks[scale.ticks.length - 1]).toBeGreaterThanOrEqual(0.3);
+  });
+});
+
+describe('linearScale', () => {
+  it('mapeia o domínio no intervalo de pixels, invertendo o eixo Y', () => {
+    const y = linearScale([0, 100], [200, 0]);
+
+    expect(y(0)).toBe(200);
+    expect(y(100)).toBe(0);
+    expect(y(50)).toBe(100);
+  });
+
+  it('não divide por zero quando o domínio é degenerado', () => {
+    expect(Number.isFinite(linearScale([5, 5], [0, 10])(5))).toBe(true);
+  });
+});
+
+describe('bandScale', () => {
+  it('distribui as faixas com folga entre elas', () => {
+    const band = bandScale(4, [0, 400], 0.2);
+
+    expect(band.bandwidth).toBe(80);
+    expect(band.center(0)).toBe(50);
+    expect(band.center(3)).toBe(350);
+  });
+});
+
+describe('medidas de texto', () => {
+  it('corta com reticências quando não cabe', () => {
+    const long = 'Curso de Introdução à Inteligência Artificial';
+
+    expect(truncateToWidth(long, 8, 40)).toMatch(/…$/);
+    expect(estimateTextWidth(truncateToWidth(long, 8, 40), 8)).toBeLessThanOrEqual(44);
+    expect(truncateToWidth('Curto', 8, 200)).toBe('Curto');
+  });
+
+  it('deita o rótulo quando cabe e gira quando não cabe', () => {
+    expect(axisLabelPlan(['jan', 'fev'], 40, 8).rotate).toBe(0);
+    expect(axisLabelPlan(['Janeiro de 2026', 'Fevereiro de 2026'], 20, 8).rotate).toBe(-35);
+  });
+
+  it('pula rótulos quando nem girado cabe', () => {
+    const plan = axisLabelPlan(
+      Array.from({ length: 40 }, (_, i) => `Semana ${i + 1} de 2026`),
+      6,
+      8,
+    );
+
+    expect(plan.skipEvery).toBeGreaterThan(1);
+  });
+});
+
+describe('withAlpha', () => {
+  it.each([
+    ['#ff760c', 'rgba(255,118,12,0.18)'],
+    ['#FFF', 'rgba(255,255,255,0.18)'],
+  ])('converte %s', (color, expected) => {
+    expect(withAlpha(color, 0.18)).toBe(expected);
+  });
+});

package/src/pdf/document/charts/chart-scale.ts

@@ -0,0 +1,141 @@
+/**
+ * Escalas, medidas e formatação dos gráficos do documento PDF.
+ *
+ * Tudo aqui é função pura e sem dependência: o gráfico é desenhado como SVG no
+ * servidor, onde não há canvas para medir texto nem biblioteca de plotagem.
+ */
+
+/** Domínio arredondado para valores "redondos" (1, 2, 5 × 10^k) e os ticks dele. */
+export function niceScale(
+  min: number,
+  max: number,
+  tickCount = 4,
+): { min: number; max: number; step: number; ticks: number[] } {
+  const safeMin = Number.isFinite(min) ? min : 0;
+  const safeMax = Number.isFinite(max) ? max : 0;
+
+  // Série toda igual (ou toda zero) não tem amplitude para dividir: um passo de
+  // 1 mantém o eixo legível em vez de gerar divisão por zero.
+  if (safeMax === safeMin) {
+    const value = safeMax === 0 ? 1 : Math.abs(safeMax);
+    const step = value / tickCount || 1;
+    return {
+      min: Math.min(0, safeMin),
+      max: safeMax === 0 ? 1 : safeMax,
+      step,
+      ticks: Array.from({ length: tickCount + 1 }, (_, i) => Math.min(0, safeMin) + step * i),
+    };
+  }
+
+  const rawStep = (safeMax - safeMin) / Math.max(tickCount, 1);
+  const magnitude = 10 ** Math.floor(Math.log10(rawStep));
+  const normalized = rawStep / magnitude;
+  // O 2,5 está na escada de propósito: sem ele, um eixo de 0 a 97 pedindo 4
+  // divisões cai no passo 50 e imprime só 0/50/100 — informação de menos para
+  // um relatório que se lê no papel, sem passar o mouse em nada.
+  const niceNormalized =
+    normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 2.5 ? 2.5 : normalized <= 5 ? 5 : 10;
+  const step = niceNormalized * magnitude;
+
+  const niceMin = Math.floor(safeMin / step) * step;
+  const niceMax = Math.ceil(safeMax / step) * step;
+
+  const ticks: number[] = [];
+  // Tolerância pelo passo: somar 0.1+0.2 em ponto flutuante erraria o último tick.
+  for (let value = niceMin; value <= niceMax + step / 1000; value += step) {
+    ticks.push(Number(value.toFixed(10)));
+  }
+
+  return { min: niceMin, max: niceMax, step, ticks };
+}
+
+/** Converte valor do domínio em pixel. */
+export function linearScale(
+  domain: [number, number],
+  range: [number, number],
+): (value: number) => number {
+  const [d0, d1] = domain;
+  const [r0, r1] = range;
+  const span = d1 - d0 || 1;
+
+  return (value: number) => r0 + ((value - d0) / span) * (r1 - r0);
+}
+
+/** Divide um intervalo em faixas de mesma largura, uma por categoria. */
+export function bandScale(
+  count: number,
+  range: [number, number],
+  paddingRatio = 0.2,
+): { band: (index: number) => number; center: (index: number) => number; bandwidth: number } {
+  const [r0, r1] = range;
+  const total = r1 - r0;
+  const slots = Math.max(count, 1);
+  const slot = total / slots;
+  const bandwidth = slot * (1 - paddingRatio);
+  const offset = (slot - bandwidth) / 2;
+
+  return {
+    band: (index: number) => r0 + slot * index + offset,
+    center: (index: number) => r0 + slot * index + slot / 2,
+    bandwidth,
+  };
+}
+
+/**
+ * Largura aproximada de um texto. Sem canvas no servidor, 0,55 × tamanho da
+ * fonte por caractere erra pouco para Arial/FreeSans e é o bastante para
+ * decidir corte e rotação de rótulo.
+ */
+export function estimateTextWidth(text: string, fontSize: number): number {
+  return text.length * fontSize * 0.55;
+}
+
+/** Corta o texto no limite de pixels, com reticências. */
+export function truncateToWidth(text: string, fontSize: number, maxWidth: number): string {
+  if (estimateTextWidth(text, fontSize) <= maxWidth) return text;
+
+  const maxChars = Math.max(Math.floor(maxWidth / (fontSize * 0.55)) - 1, 1);
+  return `${text.slice(0, maxChars).trimEnd()}…`;
+}
+
+/** Decide se os rótulos do eixo X cabem deitados e quantos pular. */
+export function axisLabelPlan(
+  labels: string[],
+  bandwidth: number,
+  fontSize: number,
+): { rotate: 0 | -35; skipEvery: number } {
+  const widest = labels.reduce((max, label) => Math.max(max, estimateTextWidth(label, fontSize)), 0);
+
+  if (widest <= bandwidth) return { rotate: 0, skipEvery: 1 };
+  // Girar resolve até certo ponto; passado ele, é melhor mostrar menos rótulos
+  // do que empilhar texto ilegível.
+  if (widest <= bandwidth * 3) return { rotate: -35, skipEvery: 1 };
+
+  return { rotate: -35, skipEvery: Math.ceil(widest / (bandwidth * 3)) };
+}
+
+/** `#ff760c` + alpha → `rgba(255,118,12,0.18)`, para o preenchimento de área. */
+export function withAlpha(hexColor: string, alpha: number): string {
+  const hex = hexColor.replace('#', '');
+  const full =
+    hex.length === 3
+      ? hex
+          .split('')
+          .map((char) => char + char)
+          .join('')
+      : hex;
+
+  const value = Number.parseInt(full.slice(0, 6), 16);
+  if (!Number.isFinite(value)) return hexColor;
+
+  const r = (value >> 16) & 255;
+  const g = (value >> 8) & 255;
+  const b = value & 255;
+
+  return `rgba(${r},${g},${b},${alpha})`;
+}
+
+/** Número no formato pt-BR, sem casas decimais desnecessárias. */
+export function formatNumber(value: number, maximumFractionDigits = 1): string {
+  return new Intl.NumberFormat('pt-BR', { maximumFractionDigits }).format(value);
+}