@hed-hog/core 0.0.400 → 0.0.402

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

@@ -0,0 +1,317 @@
+import { buildDocumentCss } from './pdf-document.css';
+import { PdfDocumentTheme } from './pdf-document.theme';
+import {
+  PdfDocumentBlock,
+  PdfDocumentCard,
+  PdfDocumentInput,
+  PdfDocumentProgressCard,
+  PdfDocumentRow,
+  PdfDocumentSegment,
+  PdfDocumentSegmentTone,
+  PdfDocumentTableCell,
+  PdfDocumentTableColumn,
+} from './pdf-document.types';
+
+/**
+ * Único ponto por onde texto entra no HTML. Nome de aluno, título de curso e
+ * rótulo de tarefa são dados de usuário indo para um Chromium headless.
+ */
+export function escapeHtml(value: unknown): string {
+  if (value === null || value === undefined) return '';
+
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+const formatGeneratedAt = (date: Date, locale: string): string =>
+  new Intl.DateTimeFormat(locale, {
+    day: '2-digit',
+    month: 'long',
+    year: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+  }).format(date);
+
+const toCell = (value: PdfDocumentRow[number]): PdfDocumentTableCell => {
+  if (value === null || value === undefined) return { text: '—', tone: 'muted' };
+  if (typeof value === 'object') return value;
+  return { text: String(value) };
+};
+
+const alignClass = (column: PdfDocumentTableColumn): string =>
+  column.align === 'right'
+    ? ' class="align-right"'
+    : column.align === 'center'
+      ? ' class="align-center"'
+      : '';
+
+function renderCards(items: PdfDocumentCard[], columns: number, variant: string): string {
+  const cards = items
+    .map(
+      (item) =>
+        `<div class="card"><div class="card-label">${escapeHtml(item.label)}</div>` +
+        `<div class="card-value">${escapeHtml(item.value)}</div>` +
+        (item.hint ? `<div class="card-hint">${escapeHtml(item.hint)}</div>` : '') +
+        '</div>',
+    )
+    .join('');
+
+  return `<div class="cards cards-${columns} cards-${variant}">${cards}</div>`;
+}
+
+function renderTable(block: Extract<PdfDocumentBlock, { kind: 'table' }>): string {
+  const {
+    columns,
+    rows,
+    numbered = false,
+    numberHeader = '#',
+    zebra = true,
+    compact = false,
+    emptyText = 'Nenhum registro no recorte selecionado.',
+    truncatedNote,
+  } = block;
+
+  if (rows.length === 0) {
+    return `<div class="table-empty">${escapeHtml(emptyText)}</div>`;
+  }
+
+  const head =
+    (numbered ? `<th class="idx">${escapeHtml(numberHeader)}</th>` : '') +
+    columns
+      .map(
+        (column) =>
+          `<th${alignClass(column)}${column.width ? ` style="width:${escapeHtml(column.width)}"` : ''}>` +
+          `${escapeHtml(column.header)}</th>`,
+      )
+      .join('');
+
+  // `push` + `join` em vez de concatenar em laço: uma conta grande gera milhares
+  // de linhas, e a string intermediária de cada passo é o que faz o render
+  // arrastar.
+  const body: string[] = [];
+
+  rows.forEach((row, index) => {
+    const cells: string[] = [];
+
+    if (numbered) cells.push(`<td class="idx">${index + 1}</td>`);
+
+    columns.forEach((column, columnIndex) => {
+      const cell = toCell(row[columnIndex]);
+      const tone = cell.tone && cell.tone !== 'default' ? ` tone-${cell.tone}` : '';
+      const align =
+        column.align === 'right' ? ' align-right' : column.align === 'center' ? ' align-center' : '';
+
+      cells.push(
+        `<td class="${(tone + align).trim()}">${escapeHtml(cell.text)}` +
+          (cell.sub ? `<div class="cell-sub">${escapeHtml(cell.sub)}</div>` : '') +
+          '</td>',
+      );
+    });
+
+    body.push(`<tr>${cells.join('')}</tr>`);
+  });
+
+  const table =
+    `<table class="doc-table${zebra ? ' zebra' : ''}${compact ? ' compact' : ''}">` +
+    `<thead><tr>${head}</tr></thead><tbody>${body.join('')}</tbody></table>`;
+
+  return truncatedNote ? `${table}<div class="note">${escapeHtml(truncatedNote)}</div>` : table;
+}
+
+/** Barra fina empilhada. Largura em % do total; total zero vira barra vazia. */
+function renderSegments(segments: PdfDocumentSegment[]): string {
+  const total = segments.reduce((sum, segment) => sum + Math.max(0, segment.value), 0);
+  const parts =
+    total > 0
+      ? segments
+          .filter((segment) => segment.value > 0)
+          .map(
+            (segment) =>
+              `<span class="seg seg-${segment.tone}" style="width:${((segment.value / total) * 100).toFixed(2)}%"></span>`,
+          )
+          .join('')
+      : '';
+
+  return `<div class="seg-bar">${parts}</div>`;
+}
+
+const dot = (tone: PdfDocumentSegmentTone): string => `<span class="dot dot-${tone}"></span>`;
+
+function renderSegmentBar(block: Extract<PdfDocumentBlock, { kind: 'segmentBar' }>): string {
+  const total = block.segments.reduce((sum, segment) => sum + Math.max(0, segment.value), 0);
+  const legend = block.segments
+    .map((segment) => {
+      const pct = total > 0 ? Math.round((segment.value / total) * 100) : 0;
+      return (
+        `<span class="seg-legend-item">${dot(segment.tone)}${escapeHtml(segment.label ?? '')} ` +
+        `<strong>${segment.value} (${pct}%)</strong></span>`
+      );
+    })
+    .join('');
+
+  return (
+    '<div class="seg-block">' +
+    (block.title ? `<div class="seg-title">${escapeHtml(block.title)}</div>` : '') +
+    renderSegments(block.segments) +
+    `<div class="seg-legend">${legend}</div>` +
+    (block.caption ? `<div class="seg-caption">${escapeHtml(block.caption)}</div>` : '') +
+    '</div>'
+  );
+}
+
+function renderProgressCard(card: PdfDocumentProgressCard): string {
+  const entries = card.entries
+    .map(
+      (entry) =>
+        `<div class="pc-entry${entry.highlight ? ` pc-entry-hl pc-entry-hl-${entry.tone}` : ''}">` +
+        `<div class="pc-entry-text">${escapeHtml(entry.text)}</div>` +
+        '<div class="pc-entry-meta">' +
+        `<span class="pc-entry-status">${dot(entry.tone)}${escapeHtml(entry.status)}</span>` +
+        (entry.aside ? `<span class="pc-entry-aside">${escapeHtml(entry.aside)}</span>` : '') +
+        '</div>' +
+        (entry.sub
+          ? `<div class="pc-entry-sub${entry.subTone === 'danger' ? ' pc-entry-sub-danger' : ''}">${escapeHtml(entry.sub)}</div>`
+          : '') +
+        '</div>',
+    )
+    .join('');
+
+  const body =
+    card.entries.length > 0
+      ? (card.listTitle ? `<div class="pc-list-title">${escapeHtml(card.listTitle)}</div>` : '') + entries
+      : card.emptyText
+        ? `<div class="pc-empty">${escapeHtml(card.emptyText)}</div>`
+        : '';
+
+  return (
+    '<div class="pc-card">' +
+    '<div class="pc-head">' +
+    `<div class="pc-head-text"><div class="pc-title">${escapeHtml(card.title)}</div>` +
+    (card.subtitle ? `<div class="pc-subtitle">${escapeHtml(card.subtitle)}</div>` : '') +
+    '</div>' +
+    `<div class="pc-value"><div class="pc-value-num">${escapeHtml(card.value)}</div>` +
+    (card.valueHint ? `<div class="pc-value-hint">${escapeHtml(card.valueHint)}</div>` : '') +
+    '</div></div>' +
+    renderSegments(card.segments) +
+    body +
+    '</div>'
+  );
+}
+
+function renderProgressCards(block: Extract<PdfDocumentBlock, { kind: 'progressCards' }>): string {
+  const legend = block.legend?.length
+    ? `<div class="pc-legend">${block.legend
+        .map((item) => `<span class="seg-legend-item">${dot(item.tone)}${escapeHtml(item.label)}</span>`)
+        .join('')}</div>`
+    : '';
+
+  return (
+    legend +
+    `<div class="pc-grid pc-grid-${block.columns ?? 2}">${block.items.map(renderProgressCard).join('')}</div>`
+  );
+}
+
+export function renderBlock(block: PdfDocumentBlock): string {
+  switch (block.kind) {
+    case 'section':
+      return (
+        `<h2>${escapeHtml(block.title)}` +
+        (block.hint ? `<span class="section-hint">${escapeHtml(block.hint)}</span>` : '') +
+        '</h2>'
+      );
+
+    case 'cards':
+      return renderCards(block.items, block.columns ?? 4, block.variant ?? 'metric');
+
+    case 'table':
+      return renderTable(block);
+
+    case 'chart':
+      return (
+        '<div class="chart">' +
+        (block.title ? `<div class="chart-title">${escapeHtml(block.title)}</div>` : '') +
+        block.svg +
+        (block.caption ? `<div class="chart-caption">${escapeHtml(block.caption)}</div>` : '') +
+        '</div>'
+      );
+
+    case 'chartGrid':
+      return (
+        '<div class="chart-grid">' +
+        block.items
+          .map(
+            (item) =>
+              '<div class="chart">' +
+              (item.title ? `<div class="chart-title">${escapeHtml(item.title)}</div>` : '') +
+              item.svg +
+              (item.caption ? `<div class="chart-caption">${escapeHtml(item.caption)}</div>` : '') +
+              '</div>',
+          )
+          .join('') +
+        '</div>'
+      );
+
+    case 'segmentBar':
+      return renderSegmentBar(block);
+
+    case 'progressCards':
+      return renderProgressCards(block);
+
+    case 'note':
+      return `<div class="note${block.tone === 'accent' ? ' note-accent' : ''}">${escapeHtml(block.text)}</div>`;
+
+    case 'legend':
+      return `<div class="legend">${block.lines.map((l) => `<p>${escapeHtml(l)}</p>`).join('')}</div>`;
+
+    case 'pageBreak':
+      return '<div class="page-break"></div>';
+
+    default:
+      return '';
+  }
+}
+
+export function renderDocumentHtml(input: PdfDocumentInput, theme: PdfDocumentTheme): string {
+  const locale = input.locale ?? 'pt-BR';
+  const generatedAt = input.generatedAt ?? new Date();
+  const logo = input.logoDataUri || theme.logoUrl;
+
+  const meta = (input.meta ?? [])
+    .map(
+      (item) =>
+        `<div>${escapeHtml(item.label)}: <span class="meta-value">${escapeHtml(item.value)}</span></div>`,
+    )
+    .join('');
+
+  const body = input.blocks.map((block) => renderBlock(block)).join('\n');
+
+  return `<!DOCTYPE html>
+<html lang="${escapeHtml(locale)}">
+  <head>
+    <meta charset="utf-8" />
+    <title>${escapeHtml(input.title)}</title>
+    <style>${buildDocumentCss(theme, input.landscape ?? false)}</style>
+  </head>
+  <body>
+    <header>
+      <div class="brand">
+        <img src="${escapeHtml(logo)}" alt="${escapeHtml(theme.companyName)}" />
+        <div class="brand-text">
+          ${input.eyebrow ? `<div class="eyebrow">${escapeHtml(input.eyebrow)}</div>` : ''}
+          <h1>${escapeHtml(input.title)}</h1>
+          ${input.subtitle ? `<div class="company-name">${escapeHtml(input.subtitle)}</div>` : ''}
+        </div>
+      </div>
+      <div class="meta-block">
+        <div>Gerado em: <span class="meta-value">${escapeHtml(formatGeneratedAt(generatedAt, locale))}</span></div>
+        ${meta}
+      </div>
+    </header>
+    ${body}
+  </body>
+</html>`;
+}

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

@@ -0,0 +1,77 @@
+import { Inject, Injectable, forwardRef } from '@nestjs/common';
+
+import { BrandAssetService } from '../../setting/brand-asset.service';
+import { SettingService } from '../../setting/setting.service';
+import { PdfService } from '../pdf.service';
+import {
+  PDF_DOCUMENT_MARGIN,
+  buildAccentHeaderTemplate,
+  buildFooterTemplate,
+} from './pdf-document.chrome';
+import { renderDocumentHtml } from './pdf-document.renderer';
+import {
+  PdfDocumentTheme,
+  PdfDocumentThemeOverrides,
+  resolveDocumentTheme,
+} from './pdf-document.theme';
+import { PdfDocumentInput } from './pdf-document.types';
+
+/**
+ * Gera o documento PDF padrão do sistema: letterhead com logo, cards, tabelas,
+ * gráficos, barra de destaque no topo de toda página e paginação "X / N".
+ *
+ * Quem chama entrega blocos de dados ({@link PdfDocumentInput}); o HTML e o
+ * Chromium são responsabilidade daqui.
+ */
+@Injectable()
+export class PdfDocumentService {
+  constructor(
+    @Inject(forwardRef(() => PdfService))
+    private readonly pdf: PdfService,
+    @Inject(forwardRef(() => SettingService))
+    private readonly settingService: SettingService,
+    @Inject(forwardRef(() => BrandAssetService))
+    private readonly brandAsset: BrandAssetService,
+  ) {}
+
+  loadTheme(overrides?: PdfDocumentThemeOverrides): Promise<PdfDocumentTheme> {
+    return resolveDocumentTheme(this.settingService, this.brandAsset, overrides);
+  }
+
+  /** HTML puro, sem Chromium — serve aos testes e a quem quiser inspecionar. */
+  async buildHtml(input: PdfDocumentInput, theme?: PdfDocumentTheme): Promise<string> {
+    return renderDocumentHtml(input, theme ?? (await this.loadTheme()));
+  }
+
+  async render(
+    input: PdfDocumentInput,
+    options: { theme?: PdfDocumentTheme; label?: string; timeoutMs?: number } = {},
+  ): Promise<Buffer> {
+    const theme = options.theme ?? (await this.loadTheme());
+    const html = renderDocumentHtml(input, theme);
+
+    const generatedAt = input.generatedAt ?? new Date();
+    const footerLeft = [
+      input.footerLeft ?? 'Documento Confidencial',
+      `Gerado em ${new Intl.DateTimeFormat(input.locale ?? 'pt-BR').format(generatedAt)}`,
+      theme.companyName,
+    ]
+      .filter(Boolean)
+      .join(' · ');
+
+    return this.pdf.generatePdfFromHtml(html, {
+      format: 'A4',
+      landscape: input.landscape ?? false,
+      printBackground: true,
+      margin: PDF_DOCUMENT_MARGIN,
+      displayHeaderFooter: true,
+      headerTemplate: buildAccentHeaderTemplate(theme),
+      footerTemplate: buildFooterTemplate(theme, footerLeft),
+      // O logo já vem embutido como data URI e não há fonte web: esperar por
+      // rede ociosa só adicionaria o timeout do `networkidle` ao render.
+      waitUntil: 'load',
+      timeoutMs: options.timeoutMs ?? 60_000,
+      label: options.label,
+    });
+  }
+}

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

@@ -0,0 +1,146 @@
+import { BrandAssetService } from '../../setting/brand-asset.service';
+import { SettingService } from '../../setting/setting.service';
+
+/**
+ * Tokens do documento padrão. São as mesmas settings que a proposta comercial
+ * do CRM lê, para que os dois PDFs saiam com a mesma identidade sem um copiar
+ * as cores do outro na mão.
+ */
+export interface PdfDocumentTheme {
+  primary: string;
+  /** Fundo suave dos cards e do cabeçalho da tabela. */
+  mutedBg: string;
+  /** Texto secundário: rótulos, legendas, rodapé. */
+  mutedFg: string;
+  /** Texto principal. */
+  ink: string;
+  /** Bordas. */
+  line: string;
+  companyName: string;
+  /** Data URI ou URL absoluta do logo do sistema. */
+  logoUrl: string;
+  fontFamily: string;
+  /** Cores categóricas dos gráficos, com a primária na frente. */
+  chartPalette: string[];
+}
+
+const FALLBACK = {
+  primary: '#ff760c',
+  mutedBg: '#f4f4f5',
+  mutedFg: '#71717a',
+  ink: '#18181b',
+  line: '#e4e4e7',
+  companyName: 'HedHog',
+};
+
+/**
+ * Nenhuma fonte web: o container da API só tem `ttf-freefont`, e um `<link>`
+ * para o Google Fonts com `waitUntil: 'networkidle'` vira espera até o timeout
+ * quando o pod não tem saída para a internet.
+ */
+export const PDF_DOCUMENT_FONT = 'Arial, Helvetica, sans-serif';
+
+/** Paleta print-safe: sem amarelo puro nem cinza claro, que somem no papel. */
+const CATEGORICAL = [
+  '#2563eb',
+  '#16a34a',
+  '#9333ea',
+  '#dc2626',
+  '#0891b2',
+  '#b45309',
+  '#4f46e5',
+  '#475569',
+];
+
+const text = (value: unknown): string | null => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+export interface PdfDocumentThemeOverrides {
+  companyName?: string;
+  primary?: string;
+}
+
+/**
+ * Lê as settings de marca. Qualquer falha cai nos valores de fábrica — um
+ * relatório sem cor certa ainda é um relatório; um relatório que não sai não é.
+ */
+export async function resolveDocumentTheme(
+  settingService: SettingService,
+  brandAsset: BrandAssetService,
+  overrides: PdfDocumentThemeOverrides = {},
+): Promise<PdfDocumentTheme> {
+  let values: Record<string, any> = {};
+
+  try {
+    values = await settingService.getSettingValues([
+      'theme-primary-light',
+      'theme-muted-light',
+      'theme-muted-foreground-light',
+      'theme-secondary-foreground-light',
+      'system-name',
+      'image-url',
+      'icon-url',
+    ]);
+  } catch {
+    values = {};
+  }
+
+  const primary = overrides.primary ?? text(values['theme-primary-light']) ?? FALLBACK.primary;
+
+  return {
+    primary,
+    mutedBg: text(values['theme-muted-light']) ?? FALLBACK.mutedBg,
+    mutedFg: text(values['theme-muted-foreground-light']) ?? FALLBACK.mutedFg,
+    ink: text(values['theme-secondary-foreground-light']) ?? FALLBACK.ink,
+    line: FALLBACK.line,
+    companyName: overrides.companyName ?? text(values['system-name']) ?? FALLBACK.companyName,
+    logoUrl: await resolveSystemLogo(brandAsset, values, primary),
+    fontFamily: PDF_DOCUMENT_FONT,
+    chartPalette: [primary, ...CATEGORICAL],
+  };
+}
+
+/**
+ * O Chromium renderiza sem sessão e, dentro do cluster, pode não ter rota para
+ * o host público — por isso a imagem é baixada e embutida como data URI, com a
+ * URL absoluta como segundo recurso e um wordmark inline como último.
+ */
+async function resolveSystemLogo(
+  brandAsset: BrandAssetService,
+  values: Record<string, any>,
+  primary: string,
+): Promise<string> {
+  const configured = text(values['image-url']) ?? text(values['icon-url']);
+
+  if (configured) {
+    try {
+      const absolute = await brandAsset.resolveAssetUrl(configured);
+      if (absolute) {
+        const dataUri = await brandAsset.fetchAsDataUri(absolute);
+        if (dataUri) return dataUri;
+        return absolute;
+      }
+    } catch {
+      // Cai no wordmark abaixo.
+    }
+  }
+
+  return inlineWordmark(primary);
+}
+
+export function inlineWordmark(primary: string): string {
+  const svg = encodeURIComponent(
+    [
+      '<svg xmlns="http://www.w3.org/2000/svg" width="240" height="72" viewBox="0 0 240 72">',
+      '<rect width="240" height="72" rx="18" fill="#0f172a"/>',
+      `<circle cx="38" cy="36" r="18" fill="${primary}"/>`,
+      '<text x="72" y="43" fill="#ffffff" font-size="26" font-family="Arial, sans-serif" font-weight="700">HedHog</text>',
+      '</svg>',
+    ].join(''),
+  );
+
+  return `data:image/svg+xml;charset=UTF-8,${svg}`;
+}

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

@@ -0,0 +1,149 @@
+/**
+ * Modelo de um documento PDF padrão: o chamador descreve **dados**, nunca HTML.
+ *
+ * É o que sustenta a regra de escape do renderer — se um serviço pudesse passar
+ * markup, o nome de um aluno com `<` viraria tag dentro de um Chromium headless.
+ * A única exceção é o SVG dos gráficos, que carrega o tipo {@link SafeSvg} e só
+ * pode ser produzido pelos desenhistas do próprio kit.
+ */
+
+/** SVG montado pelos helpers de gráfico do kit — a única string injetada sem escape. */
+export type SafeSvg = string & { readonly __safeSvg: unique symbol };
+
+/**
+ * Marca um SVG como seguro. Só os desenhistas de `./charts` devem chamar isto:
+ * quem passar conteúdo de usuário aqui reabre a porta que o modelo de blocos fecha.
+ */
+export const asSafeSvg = (svg: string): SafeSvg => svg as SafeSvg;
+
+export interface PdfDocumentMeta {
+  label: string;
+  value: string;
+}
+
+export interface PdfDocumentCard {
+  label: string;
+  value: string;
+  /** Linha pequena abaixo do valor, para a unidade ou a ressalva. */
+  hint?: string;
+}
+
+export interface PdfDocumentTableColumn {
+  header: string;
+  align?: 'left' | 'center' | 'right';
+  /**
+   * Largura CSS (ex.: '18%'). Sem ela o Chromium reparte pelo conteúdo e a
+   * tabela muda de forma a cada página.
+   */
+  width?: string;
+}
+
+export interface PdfDocumentTableCell {
+  text: string;
+  /** Segunda linha menor: o e-mail sob o nome, o "Em risco" sob o status. */
+  sub?: string;
+  tone?: 'default' | 'muted' | 'bold' | 'accent' | 'warn';
+}
+
+export type PdfDocumentRow = Array<string | number | null | undefined | PdfDocumentTableCell>;
+
+/**
+ * Paleta fechada das barras e marcadores — o chamador escolhe o papel, o tema
+ * decide a cor: 'ink' (feito), 'muted' e 'light' (dois cinzas), 'accent' (cor
+ * da marca) e 'danger' (atraso).
+ */
+export type PdfDocumentSegmentTone = 'ink' | 'muted' | 'light' | 'accent' | 'danger';
+
+export interface PdfDocumentSegment {
+  value: number;
+  tone: PdfDocumentSegmentTone;
+  /** Só a barra avulsa (`segmentBar`) mostra rótulo, na legenda abaixo dela. */
+  label?: string;
+}
+
+export interface PdfDocumentProgressEntry {
+  text: string;
+  /** Linha pequena com marcador da cor de `tone` (ex.: "Em revisão"). */
+  status: string;
+  tone: PdfDocumentSegmentTone;
+  /** Texto à direita da linha de status (ex.: "há 3d 4h"). */
+  aside?: string;
+  /** Terceira linha opcional (ex.: o prazo). */
+  sub?: string;
+  subTone?: 'muted' | 'danger';
+  /** Fundo tingido com a cor do `tone` — o item que pede atenção. */
+  highlight?: boolean;
+}
+
+export interface PdfDocumentProgressCard {
+  title: string;
+  subtitle?: string;
+  /** O número grande à direita (ex.: "33%"). */
+  value: string;
+  valueHint?: string;
+  segments: PdfDocumentSegment[];
+  listTitle?: string;
+  entries: PdfDocumentProgressEntry[];
+  /** Mostrado no lugar da lista quando `entries` vem vazio. */
+  emptyText?: string;
+}
+
+export type PdfDocumentBlock =
+  | { kind: 'section'; title: string; hint?: string }
+  | {
+      kind: 'cards';
+      items: PdfDocumentCard[];
+      /** Padrão: 4. */
+      columns?: 2 | 3 | 4 | 5;
+      /** 'metric' destaca o valor (indicador); 'filter' é o carimbo do recorte. */
+      variant?: 'metric' | 'filter';
+    }
+  | {
+      kind: 'table';
+      columns: PdfDocumentTableColumn[];
+      rows: PdfDocumentRow[];
+      /** Coluna "#" à esquerda, 1..N contínua entre páginas. */
+      numbered?: boolean;
+      numberHeader?: string;
+      zebra?: boolean;
+      /** Fonte menor, para tabela com muitas colunas. */
+      compact?: boolean;
+      emptyText?: string;
+      /** Aviso de corte quando a origem truncou as linhas. */
+      truncatedNote?: string;
+    }
+  | { kind: 'chart'; title?: string; svg: SafeSvg; caption?: string }
+  | { kind: 'chartGrid'; items: Array<{ title?: string; svg: SafeSvg; caption?: string }> }
+  /** Barra empilhada com legenda "rótulo N (x%)" — a composição de um total. */
+  | { kind: 'segmentBar'; title?: string; segments: PdfDocumentSegment[]; caption?: string }
+  /** Grade de cartões com %, barra e lista de itens — um por pessoa, por exemplo. */
+  | {
+      kind: 'progressCards';
+      items: PdfDocumentProgressCard[];
+      /** Legenda dos marcadores, acima da grade. */
+      legend?: Array<{ label: string; tone: PdfDocumentSegmentTone }>;
+      /** Padrão: 2. */
+      columns?: 1 | 2;
+    }
+  | { kind: 'note'; text: string; tone?: 'muted' | 'accent' }
+  | { kind: 'legend'; lines: string[] }
+  | { kind: 'pageBreak' };
+
+export interface PdfDocumentInput {
+  /** O `h1` do letterhead. */
+  title: string;
+  /** Sobretítulo laranja, em caixa alta (ex.: "Relatório de Alunos"). */
+  eyebrow?: string;
+  /** Linha cinza abaixo do título — normalmente o nome da empresa. */
+  subtitle?: string;
+  /** Bloco alinhado à direita do letterhead. */
+  meta?: PdfDocumentMeta[];
+  blocks: PdfDocumentBlock[];
+  /** Data URI do logo; sem ele o kit usa o logo do sistema. */
+  logoDataUri?: string | null;
+  generatedAt?: Date;
+  locale?: string;
+  landscape?: boolean;
+  /** Padrão: 'Documento Confidencial'. */
+  footerLeft?: string;
+}