@hed-hog/core 0.0.399 → 0.0.401

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

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

@@ -0,0 +1,238 @@
+import { PdfDocumentTheme } from './pdf-document.theme';
+
+/**
+ * O CSS do documento padrão — o mesmo acabamento da proposta comercial do CRM
+ * (`libraries/crm/src/proposal/proposal.service.ts`), com três acréscimos que
+ * a proposta não precisava e um relatório precisa:
+ *
+ * 1. `thead { display: table-header-group }` — sem isso a tabela perde o
+ *    cabeçalho a partir da segunda página, e um relatório de 15 páginas fica
+ *    ilegível da página 2 em diante.
+ * 2. `tbody tr { break-inside: avoid }` — linha não parte no meio.
+ * 3. Nada de wrapper com `break-inside: avoid`, `overflow` ou borda arredondada
+ *    em volta da tabela: foi o que fez a folha de impressão da tela sair com
+ *    uma primeira página vazia e conteúdo cortado.
+ *
+ * A barra laranja do topo e o "X / N" do rodapé **não estão aqui** — são
+ * templates do Chromium (ver ./pdf-document.chrome.ts), porque só eles repetem
+ * em toda página e só eles sabem o total de páginas.
+ */
+export function buildDocumentCss(theme: PdfDocumentTheme, landscape = false): string {
+  const { primary, mutedBg, mutedFg, ink, line, fontFamily } = theme;
+
+  return `
+    @page {
+      size: A4${landscape ? ' landscape' : ''};
+      margin: 72px 56px 56px 56px;
+    }
+    * { box-sizing: border-box; }
+    html, body {
+      -webkit-print-color-adjust: exact;
+      print-color-adjust: exact;
+    }
+    body {
+      color: ${ink};
+      font-family: ${fontFamily};
+      font-size: 11.5px;
+      line-height: 1.55;
+      margin: 0;
+    }
+
+    /* ── Letterhead ── */
+    header {
+      display: flex;
+      justify-content: space-between;
+      align-items: flex-start;
+      gap: 24px;
+      margin-bottom: 24px;
+      padding-bottom: 20px;
+      border-bottom: 1px solid ${line};
+    }
+    .brand { display: flex; align-items: center; gap: 14px; }
+    .brand img { height: 44px; max-width: 150px; object-fit: contain; }
+    .brand-text .eyebrow {
+      color: ${primary};
+      font-size: 9px;
+      font-weight: 700;
+      letter-spacing: 0.14em;
+      text-transform: uppercase;
+      margin-bottom: 3px;
+    }
+    .brand-text h1 {
+      font-size: 20px;
+      font-weight: 700;
+      color: ${ink};
+      margin: 0 0 2px;
+      line-height: 1.2;
+    }
+    .brand-text .company-name { font-size: 11px; color: ${mutedFg}; }
+    .meta-block {
+      text-align: right;
+      font-size: 11px;
+      color: ${mutedFg};
+      line-height: 1.7;
+      white-space: nowrap;
+    }
+    .meta-block .meta-value { font-weight: 600; color: ${ink}; }
+
+    /* ── Cards ── */
+    .cards {
+      display: grid;
+      gap: 12px;
+      margin-bottom: 18px;
+      break-inside: avoid;
+    }
+    .cards-2 { grid-template-columns: repeat(2, 1fr); }
+    .cards-3 { grid-template-columns: repeat(3, 1fr); }
+    .cards-4 { grid-template-columns: repeat(4, 1fr); }
+    .cards-5 { grid-template-columns: repeat(5, 1fr); }
+    .card {
+      background: ${mutedBg};
+      border: 1px solid ${line};
+      border-top: 2px solid ${primary};
+      border-radius: 10px;
+      padding: 10px 12px;
+    }
+    .card .card-label {
+      font-size: 8.5px;
+      font-weight: 700;
+      letter-spacing: 0.12em;
+      text-transform: uppercase;
+      color: ${mutedFg};
+      margin-bottom: 4px;
+    }
+    .card .card-value { font-size: 12px; font-weight: 600; color: ${ink}; }
+    .cards-metric .card .card-value { font-size: 17px; font-weight: 700; }
+    .card .card-hint { font-size: 9px; color: ${mutedFg}; margin-top: 2px; }
+
+    /* ── Seções ── */
+    h2 {
+      font-size: 12.5px;
+      font-weight: 700;
+      color: ${ink};
+      margin: 22px 0 10px;
+      padding-bottom: 6px;
+      border-bottom: 1px solid ${line};
+      text-transform: uppercase;
+      letter-spacing: 0.06em;
+      break-after: avoid;
+    }
+    h2 .section-hint {
+      float: right;
+      font-size: 9.5px;
+      font-weight: 400;
+      letter-spacing: 0;
+      text-transform: none;
+      color: ${mutedFg};
+    }
+
+    /* ── Tabela ── */
+    .doc-table {
+      border-collapse: collapse;
+      width: 100%;
+      font-size: 10.5px;
+    }
+    .doc-table.compact { font-size: 9px; }
+    .doc-table thead { display: table-header-group; }
+    .doc-table thead tr { border-bottom: 1px solid ${line}; }
+    .doc-table th {
+      background: ${mutedBg};
+      color: ${mutedFg};
+      font-size: 9px;
+      font-weight: 700;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      padding: 7px 8px;
+      text-align: left;
+      vertical-align: middle;
+    }
+    .doc-table td {
+      border-bottom: 1px solid ${line};
+      padding: 6px 8px;
+      text-align: left;
+      vertical-align: top;
+      color: ${ink};
+    }
+    /*
+     * Os tons precisam vencer o color da propria celula: ".doc-table td" tem
+     * especificidade 0-1-1 e ".tone-accent" sozinho tem 0-1-0, entao a cor do
+     * tom era descartada em toda tabela do sistema — so o font-weight passava,
+     * porque a regra da celula nao mexe nele. Quem marca um valor como "warn"
+     * quer que ele salte aos olhos, nao que fique so em negrito igual ao resto.
+     */
+    .doc-table td.tone-muted { color: ${mutedFg}; }
+    .doc-table td.tone-accent { color: ${primary}; }
+    .doc-table td.tone-warn { color: #b45309; }
+    .doc-table tbody tr { break-inside: avoid; }
+    .doc-table tbody tr:last-child td { border-bottom: none; }
+    .doc-table.zebra tbody tr:nth-child(even) td { background: ${mutedBg}; }
+    .doc-table .align-right { text-align: right; }
+    .doc-table .align-center { text-align: center; }
+    /* Valor numérico não quebra: "1h 00min" partido em duas linhas dobra a
+       altura da linha e desalinha a leitura de cima a baixo. O cabeçalho pode
+       quebrar à vontade — é o que mantém "On demand" numa coluna estreita. */
+    .doc-table td.align-right,
+    .doc-table td.align-center { white-space: nowrap; }
+    /* A coluna "#" é numerada no servidor: contador de CSS reiniciaria a cada
+       repetição do <thead>. */
+    .doc-table .idx {
+      width: 30px;
+      color: ${mutedFg};
+      text-align: right;
+      font-variant-numeric: tabular-nums;
+    }
+    .cell-sub { font-size: 8.5px; color: ${mutedFg}; margin-top: 1px; }
+    .tone-muted { color: ${mutedFg}; }
+    .tone-bold { font-weight: 700; }
+    .tone-accent { color: ${primary}; font-weight: 600; }
+    .tone-warn { color: #b45309; font-weight: 600; }
+    .table-empty {
+      border: 1px dashed ${line};
+      border-radius: 10px;
+      padding: 18px;
+      text-align: center;
+      font-size: 10.5px;
+      color: ${mutedFg};
+    }
+
+    /* ── Gráficos ── */
+    .chart { margin: 4px 0 18px; break-inside: avoid; }
+    .chart-title {
+      font-size: 10.5px;
+      font-weight: 700;
+      color: ${ink};
+      margin-bottom: 6px;
+    }
+    .chart svg { width: 100%; height: auto; }
+    .chart-caption { font-size: 9px; color: ${mutedFg}; margin-top: 4px; }
+    .chart-grid {
+      display: grid;
+      grid-template-columns: repeat(2, 1fr);
+      gap: 16px;
+      margin-bottom: 18px;
+    }
+
+    /* ── Notas e legenda ── */
+    .note {
+      background: ${mutedBg};
+      border: 1px solid ${line};
+      border-radius: 8px;
+      padding: 9px 12px;
+      font-size: 10px;
+      color: ${mutedFg};
+      margin: 12px 0;
+      break-inside: avoid;
+    }
+    .note-accent { border-left: 3px solid ${primary}; }
+    .legend {
+      margin-top: 18px;
+      padding-top: 10px;
+      border-top: 1px solid ${line};
+      font-size: 9px;
+      line-height: 1.6;
+      color: ${mutedFg};
+    }
+    .legend p { margin: 0 0 3px; }
+    .page-break { break-before: page; }
+  `;
+}