@hed-hog/core 0.0.400 → 0.0.401

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

package/src/pdf/document/pdf-document.renderer.spec.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from '@jest/globals';
+
+import { escapeHtml, renderBlock, renderDocumentHtml } from './pdf-document.renderer';
+import { PdfDocumentTheme } from './pdf-document.theme';
+import { PdfDocumentBlock, PdfDocumentRow } from './pdf-document.types';
+
+const theme: PdfDocumentTheme = {
+  primary: '#ff760c',
+  mutedBg: '#f4f4f5',
+  mutedFg: '#71717a',
+  ink: '#18181b',
+  line: '#e4e4e7',
+  companyName: 'HedHog',
+  logoUrl: 'data:image/svg+xml;charset=UTF-8,%3Csvg%3E%3C/svg%3E',
+  fontFamily: 'Arial, Helvetica, sans-serif',
+  chartPalette: ['#ff760c'],
+};
+
+const table = (rows: PdfDocumentRow[]): PdfDocumentBlock => ({
+  kind: 'table',
+  numbered: true,
+  columns: [{ header: 'Aluno' }, { header: 'Horas', align: 'right' }],
+  rows,
+});
+
+describe('escapeHtml', () => {
+  it('neutraliza os cinco caracteres que viram markup', () => {
+    expect(escapeHtml(`<script>alert("1" & '2')</script>`)).toBe(
+      '&lt;script&gt;alert(&quot;1&quot; &amp; &#39;2&#39;)&lt;/script&gt;',
+    );
+  });
+
+  it('trata nulo e indefinido como texto vazio', () => {
+    expect(escapeHtml(null)).toBe('');
+    expect(escapeHtml(undefined)).toBe('');
+  });
+});
+
+describe('tabela', () => {
+  // O pedido que originou o kit: cada linha numerada a partir de 1.
+  it('numera as linhas de 1 a N, na ordem recebida', () => {
+    const html = renderBlock(table([['Ana', '10h'], ['Bruno', '9h'], ['Carla', '8h']]));
+    const indices = [...html.matchAll(/<td class="idx">(\d+)<\/td>/g)].map((m) => m[1]);
+
+    expect(indices).toEqual(['1', '2', '3']);
+  });
+
+  // Sem `display: table-header-group` o cabeçalho some da segunda página em
+  // diante; o `<thead>` tem que existir de verdade para a regra pegar.
+  it('emite thead próprio, que o CSS manda repetir por página', () => {
+    const html = renderBlock(table([['Ana', '10h']]));
+
+    expect(html).toContain('<thead><tr>');
+    expect(html).toContain('<th class="idx">#</th>');
+  });
+
+  it('escapa o conteúdo das células e da segunda linha', () => {
+    const html = renderBlock({
+      kind: 'table',
+      columns: [{ header: 'Aluno' }],
+      rows: [[{ text: '<b>Ana</b>', sub: 'a&b@x.com' }]],
+    });
+
+    expect(html).toContain('&lt;b&gt;Ana&lt;/b&gt;');
+    expect(html).toContain('a&amp;b@x.com');
+    expect(html).not.toContain('<b>Ana</b>');
+  });
+
+  it('mostra um aviso no lugar da tabela quando não há linha nenhuma', () => {
+    const html = renderBlock({ kind: 'table', columns: [{ header: 'Aluno' }], rows: [] });
+
+    expect(html).toContain('table-empty');
+    expect(html).not.toContain('<table');
+  });
+
+  it('preenche célula vazia com travessão em vez de deixar buraco', () => {
+    const html = renderBlock(table([['Ana', null]]));
+
+    expect(html).toContain('—');
+  });
+});
+
+describe('documento', () => {
+  it('monta o letterhead com sobretítulo, título e metadados', () => {
+    const html = renderDocumentHtml(
+      {
+        title: 'Alunos',
+        eyebrow: 'Relatório de Alunos',
+        subtitle: 'BRClick',
+        meta: [{ label: 'Status', value: 'Todos os status' }],
+        generatedAt: new Date('2026-09-22T13:32:00Z'),
+        blocks: [{ kind: 'section', title: 'Resumo' }],
+      },
+      theme,
+    );
+
+    expect(html).toContain('<div class="eyebrow">Relatório de Alunos</div>');
+    expect(html).toContain('<h1>Alunos</h1>');
+    expect(html).toContain('Status: <span class="meta-value">Todos os status</span>');
+    expect(html).toContain('Gerado em:');
+  });
+
+  it('escapa o título também no <title> da página', () => {
+    const html = renderDocumentHtml(
+      { title: 'Turma <A>', blocks: [] },
+      theme,
+    );
+
+    expect(html).toContain('<title>Turma &lt;A&gt;</title>');
+  });
+
+  // O SVG é a única string injetada crua — e só os desenhistas do kit produzem.
+  it('injeta o SVG do gráfico sem escapar, mas escapa o título dele', () => {
+    const html = renderBlock({
+      kind: 'chart',
+      title: 'Matrículas & conclusões',
+      svg: '<svg><rect /></svg>' as never,
+    });
+
+    expect(html).toContain('<svg><rect /></svg>');
+    expect(html).toContain('Matrículas &amp; conclusões');
+  });
+
+  it('vira paisagem quando o documento pede', () => {
+    const html = renderDocumentHtml({ title: 'Frequência', landscape: true, blocks: [] }, theme);
+
+    expect(html).toContain('size: A4 landscape');
+  });
+});