@hed-hog/core 0.0.400 → 0.0.402

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);
+}

package/src/pdf/document/charts/charts.spec.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { PdfDocumentTheme } from '../pdf-document.theme';
+import {
+  areaChartSvg,
+  barChartSvg,
+  donutChartSvg,
+  gaugeChartSvg,
+  horizontalBarChartSvg,
+  lineChartSvg,
+  radarChartSvg,
+} from './index';
+
+const theme: PdfDocumentTheme = {
+  primary: '#ff760c',
+  mutedBg: '#f4f4f5',
+  mutedFg: '#71717a',
+  ink: '#18181b',
+  line: '#e4e4e7',
+  companyName: 'HedHog',
+  logoUrl: '',
+  fontFamily: 'Arial, Helvetica, sans-serif',
+  chartPalette: ['#ff760c', '#2563eb', '#16a34a'],
+};
+
+const meses = ['Jan', 'Fev', 'Mar', 'Abr'];
+
+describe('desenhistas de gráfico', () => {
+  it('produzem SVG válido com viewBox', () => {
+    const svgs = [
+      barChartSvg({ theme, categories: meses, series: [{ name: 'Matrículas', values: [3, 8, 5, 9] }] }),
+      horizontalBarChartSvg({
+        theme,
+        categories: ['Curso A', 'Curso B'],
+        series: [{ name: 'Conclusão', values: [80, 45] }],
+      }),
+      lineChartSvg({ theme, categories: meses, series: [{ name: 'Frequência', values: [70, 75, 80, 90] }] }),
+      donutChartSvg({
+        theme,
+        slices: [
+          { label: 'Ativos', value: 30 },
+          { label: 'Em risco', value: 10 },
+        ],
+      }),
+      radarChartSvg({
+        theme,
+        axes: ['Conteúdo', 'Didática', 'Ritmo'],
+        series: [{ name: 'Média', values: [4.5, 3.8, 4.1] }],
+        max: 5,
+      }),
+      gaugeChartSvg({ theme, items: [{ label: 'Curso A', pct: 62 }] }),
+    ];
+
+    for (const svg of svgs) {
+      expect(svg).toMatch(/^<svg viewBox="0 0 \d+ \d+"/);
+      expect(svg.endsWith('</svg>')).toBe(true);
+      // Tag desbalanceada só apareceria no papel, e tarde demais.
+      expect(svg.split('<').length).toBe(svg.split('>').length);
+    }
+  });
+
+  // Rótulo de curso é dado de usuário indo para dentro de um Chromium headless.
+  it('escapam o texto que vem dos dados', () => {
+    const svg = horizontalBarChartSvg({
+      theme,
+      categories: ['<script>alert(1)</script>'],
+      series: [{ name: 'x', values: [10] }],
+    });
+
+    expect(svg).not.toContain('<script>');
+    expect(svg).toContain('&lt;script&gt;');
+  });
+
+  it('caem no aviso de vazio em vez de desenhar uma moldura sem nada', () => {
+    const semDados = barChartSvg({ theme, categories: [], series: [] });
+    const soNulos = lineChartSvg({ theme, categories: meses, series: [{ name: 'x', values: [null, null, null, null] }] });
+    const roscaZerada = donutChartSvg({ theme, slices: [{ label: 'Nada', value: 0 }] });
+
+    for (const svg of [semDados, soNulos, roscaZerada]) {
+      expect(svg).toContain('Sem dados no período');
+    }
+  });
+
+  it('respeitam o texto de vazio escolhido pelo chamador', () => {
+    expect(
+      barChartSvg({ theme, categories: [], series: [], emptyText: 'Nenhuma turma no recorte' }),
+    ).toContain('Nenhuma turma no recorte');
+  });
+
+  // Buraco na série é ausência de dado, não zero: emendar a linha inventaria
+  // uma queda que não aconteceu.
+  it('interrompem a linha no buraco da série', () => {
+    const comBuraco = lineChartSvg({
+      theme,
+      categories: meses,
+      series: [{ name: 'Nota', values: [4, null, 3, 5] }],
+    });
+
+    expect((comBuraco.match(/<path d="M/g) ?? []).length).toBeGreaterThan(1);
+  });
+
+  it('desenham a linha de meta quando pedida', () => {
+    const svg = areaChartSvg({
+      theme,
+      categories: meses,
+      series: [{ name: 'Frequência', values: [70, 75, 80, 90] }],
+      referenceLine: { value: 80, label: 'Meta 80%' },
+    });
+
+    expect(svg).toContain('stroke-dasharray="4 3"');
+    expect(svg).toContain('Meta 80%');
+  });
+
+  it('a área preenche sob a linha e a linha simples não', () => {
+    const base = { theme, categories: meses, series: [{ name: 'x', values: [1, 2, 3, 4] }] };
+
+    expect(areaChartSvg(base)).toContain('rgba(255,118,12,0.18)');
+    expect(lineChartSvg(base)).not.toContain('rgba(255,118,12,0.18)');
+  });
+
+  it('a rosca mostra o percentual de cada fatia', () => {
+    const svg = donutChartSvg({
+      theme,
+      slices: [
+        { label: 'Ativos', value: 75 },
+        { label: 'Inativos', value: 25 },
+      ],
+    });
+
+    expect(svg).toContain('75%');
+    expect(svg).toContain('25%');
+  });
+
+  // A legenda era dimensionada por subtração e o epsilon de ponto flutuante
+  // cortava o rótulo que cabia exatamente: "Em risco" saía "Em ris…".
+  it('a legenda não corta o rótulo que cabe', () => {
+    const svg = donutChartSvg({
+      theme,
+      width: 330,
+      height: 200,
+      slices: [
+        { label: 'Ativos', value: 318 },
+        { label: 'Em risco', value: 87 },
+        { label: 'Inativos', value: 16 },
+      ],
+    });
+
+    expect(svg).toContain('Em risco');
+    expect(svg).not.toContain('…');
+  });
+
+  it('o radar exige três eixos para não virar um triângulo degenerado', () => {
+    expect(
+      radarChartSvg({ theme, axes: ['A', 'B'], series: [{ name: 'x', values: [1, 2] }] }),
+    ).toContain('Sem dados no período');
+  });
+});

package/src/pdf/document/charts/index.ts

@@ -0,0 +1,7 @@
+export * from './chart-bar';
+export * from './chart-donut';
+export * from './chart-gauge';
+export * from './chart-line';
+export * from './chart-primitives';
+export * from './chart-radar';
+export * from './chart-scale';

package/src/pdf/document/index.ts

@@ -0,0 +1,7 @@
+export * from './charts';
+export * from './pdf-document.chrome';
+export * from './pdf-document.css';
+export * from './pdf-document.renderer';
+export * from './pdf-document.service';
+export * from './pdf-document.theme';
+export * from './pdf-document.types';

package/src/pdf/document/pdf-document.chrome.ts

@@ -0,0 +1,38 @@
+import { escapeHtml } from './pdf-document.renderer';
+import { PdfDocumentTheme } from './pdf-document.theme';
+
+/**
+ * Cabeçalho e rodapé nativos do Chromium — a barra laranja que repete em toda
+ * página e o "3 / 15" que só o renderizador sabe calcular.
+ *
+ * Eles são mini-documentos, não parte da página: começam em `font-size: 0`,
+ * precisam do próprio `print-color-adjust` para manter fundo, e só
+ * `<span class="pageNumber">` e `<span class="totalPages">` são substituídos.
+ * As margens abaixo reservam o espaço deles — encolher `top`/`bottom` faz o
+ * conteúdo imprimir por cima.
+ */
+export const PDF_DOCUMENT_MARGIN = {
+  top: '72px',
+  right: '56px',
+  bottom: '56px',
+  left: '56px',
+};
+
+export function buildAccentHeaderTemplate(theme: PdfDocumentTheme): string {
+  return (
+    '<style>*{margin:0;padding:0;box-sizing:border-box;}html,body{margin:0;padding:0;}</style>' +
+    '<div style="position:absolute;top:0;left:0;right:0;width:100%;height:8px;' +
+    `background:${theme.primary};-webkit-print-color-adjust:exact;print-color-adjust:exact;"></div>`
+  );
+}
+
+export function buildFooterTemplate(theme: PdfDocumentTheme, left: string): string {
+  return (
+    '<div style="width:100%;padding:0 56px;display:flex;justify-content:space-between;' +
+    `align-items:center;font-family:${theme.fontFamily};font-size:8px;color:${theme.mutedFg};` +
+    '-webkit-print-color-adjust:exact;print-color-adjust:exact;">' +
+    `<span>${escapeHtml(left)}</span>` +
+    '<span><span class="pageNumber"></span> / <span class="totalPages"></span></span>' +
+    '</div>'
+  );
+}