@hed-hog/core 0.0.400 → 0.0.402

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

@@ -0,0 +1,163 @@
+import { SafeSvg } from '../pdf-document.types';
+import {
+  CHART_DEFAULT_HEIGHT,
+  CHART_FONT,
+  CHART_FULL_WIDTH,
+  ChartBaseOptions,
+  chartColor,
+  emptyChart,
+  svgRoot,
+  text,
+} from './chart-primitives';
+import { estimateTextWidth, formatNumber, truncateToWidth } from './chart-scale';
+
+export interface DonutSlice {
+  label: string;
+  value: number;
+  color?: string;
+}
+
+const polar = (cx: number, cy: number, radius: number, angle: number) => ({
+  x: cx + radius * Math.cos(angle),
+  y: cy + radius * Math.sin(angle),
+});
+
+/** Setor em anel, desenhado com dois arcos — o `path` é o único jeito no SVG puro. */
+function ringSegment(
+  cx: number,
+  cy: number,
+  outer: number,
+  inner: number,
+  start: number,
+  end: number,
+): string {
+  const largeArc = end - start > Math.PI ? 1 : 0;
+  const p1 = polar(cx, cy, outer, start);
+  const p2 = polar(cx, cy, outer, end);
+  const p3 = polar(cx, cy, inner, end);
+  const p4 = polar(cx, cy, inner, start);
+
+  if (inner <= 0) {
+    return (
+      `M${cx.toFixed(1)},${cy.toFixed(1)} L${p1.x.toFixed(1)},${p1.y.toFixed(1)} ` +
+      `A${outer},${outer} 0 ${largeArc} 1 ${p2.x.toFixed(1)},${p2.y.toFixed(1)} Z`
+    );
+  }
+
+  return (
+    `M${p1.x.toFixed(1)},${p1.y.toFixed(1)} A${outer},${outer} 0 ${largeArc} 1 ${p2.x.toFixed(1)},${p2.y.toFixed(1)} ` +
+    `L${p3.x.toFixed(1)},${p3.y.toFixed(1)} A${inner},${inner} 0 ${largeArc} 0 ${p4.x.toFixed(1)},${p4.y.toFixed(1)} Z`
+  );
+}
+
+/** Rosca (ou pizza, com `innerRadiusRatio: 0`) com legenda à direita. */
+export function donutChartSvg(
+  options: ChartBaseOptions & {
+    slices: DonutSlice[];
+    innerRadiusRatio?: number;
+    centerLabel?: string;
+    centerValue?: string;
+    showPercent?: boolean;
+  },
+): SafeSvg {
+  const {
+    theme,
+    slices,
+    width = CHART_FULL_WIDTH,
+    height = CHART_DEFAULT_HEIGHT,
+    innerRadiusRatio = 0.62,
+    showPercent = true,
+    valueFormat = (value: number) => formatNumber(value, 0),
+  } = options;
+
+  const usable = slices.filter((slice) => Number.isFinite(slice.value) && slice.value > 0);
+  const total = usable.reduce((sum, slice) => sum + slice.value, 0);
+
+  if (total <= 0) return emptyChart(options);
+
+  // A coluna da direita é dimensionada pelo texto que realmente vai nela: o
+  // valor ("318 · 76%") fixa a largura mínima, e o que sobra é do rótulo.
+  const valueLabels = usable.map((slice) =>
+    showPercent
+      ? `${valueFormat(slice.value)} · ${Math.round((slice.value / total) * 100)}%`
+      : valueFormat(slice.value),
+  );
+  const valueWidth = Math.max(
+    ...valueLabels.map((label) => estimateTextWidth(label, CHART_FONT.legend)),
+  );
+  // A largura do rótulo é decidida primeiro e a legenda é montada a partir dela.
+  // Derivar na ordem inversa (legenda menos valor menos folga) devolve o mesmo
+  // número com um epsilon de ponto flutuante a menos, e um rótulo que cabia
+  // certinho sai cortado — "Em risco" virava "Em ris…".
+  const maxLabelWidth = Math.min(
+    Math.max(...usable.map((s) => estimateTextWidth(s.label, CHART_FONT.legend))),
+    width * 0.45 - valueWidth - 26,
+  );
+  const legendWidth = maxLabelWidth + valueWidth + 26;
+  const chartWidth = width - legendWidth;
+  const radius = Math.min(chartWidth, height) / 2 - 8;
+  const cx = chartWidth / 2;
+  const cy = height / 2;
+  const inner = radius * innerRadiusRatio;
+
+  const parts: string[] = [];
+  // Começa às 12h: é onde o olho procura o início de uma rosca.
+  let angle = -Math.PI / 2;
+
+  usable.forEach((slice, index) => {
+    const sweep = (slice.value / total) * Math.PI * 2;
+    const color = chartColor(theme, index, slice.color);
+
+    parts.push(
+      `<path d="${ringSegment(cx, cy, radius, inner, angle, angle + sweep)}" fill="${color}" />`,
+    );
+    angle += sweep;
+  });
+
+  if (inner > 0 && (options.centerValue || options.centerLabel)) {
+    if (options.centerValue) {
+      parts.push(
+        text(options.centerValue, cx, cy + (options.centerLabel ? 0 : 4), {
+          size: 16,
+          fill: theme.ink,
+          anchor: 'middle',
+          weight: 700,
+        }),
+      );
+    }
+    if (options.centerLabel) {
+      parts.push(
+        text(options.centerLabel, cx, cy + 12, {
+          size: CHART_FONT.axis,
+          fill: theme.mutedFg,
+          anchor: 'middle',
+        }),
+      );
+    }
+  }
+
+  const legendX = chartWidth + 4;
+  const lineHeight = 15;
+  const legendTop = cy - (usable.length * lineHeight) / 2 + 8;
+
+  usable.forEach((slice, index) => {
+    const y = legendTop + index * lineHeight;
+    const label = truncateToWidth(
+      slice.label,
+      CHART_FONT.legend,
+      maxLabelWidth,
+    );
+
+    parts.push(
+      `<rect x="${legendX}" y="${y - 7}" width="8" height="8" rx="2" fill="${chartColor(theme, index, slice.color)}" />`,
+      text(label, legendX + 12, y, { size: CHART_FONT.legend, fill: theme.ink }),
+      text(valueLabels[index] ?? '', width, y, {
+        size: CHART_FONT.legend,
+        fill: theme.mutedFg,
+        anchor: 'end',
+      }),
+    );
+  });
+
+  return svgRoot(width, height, parts.join(''), options.ariaLabel);
+}

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

@@ -0,0 +1,94 @@
+import { SafeSvg } from '../pdf-document.types';
+import {
+  CHART_DEFAULT_HEIGHT,
+  CHART_FONT,
+  CHART_FULL_WIDTH,
+  ChartBaseOptions,
+  chartColor,
+  emptyChart,
+  svgRoot,
+  text,
+} from './chart-primitives';
+import { truncateToWidth } from './chart-scale';
+
+/**
+ * Arcos concêntricos de percentual — a figura de "meu progresso por curso" da
+ * visão do aluno. Cada item é um anel; o arco completo é 100%.
+ */
+export function gaugeChartSvg(
+  options: ChartBaseOptions & {
+    items: Array<{ label: string; pct: number; color?: string }>;
+    centerLabel?: string;
+  },
+): SafeSvg {
+  const {
+    theme,
+    items,
+    width = CHART_FULL_WIDTH,
+    height = CHART_DEFAULT_HEIGHT,
+  } = options;
+
+  const usable = items.filter((item) => Number.isFinite(item.pct)).slice(0, 6);
+  if (usable.length === 0) return emptyChart(options);
+
+  const legendWidth = Math.min(width * 0.45, 240);
+  const chartWidth = width - legendWidth;
+  const cx = chartWidth / 2;
+  const cy = height / 2;
+
+  const outer = Math.min(chartWidth, height) / 2 - 8;
+  const thickness = Math.max((outer - 18) / usable.length, 6);
+  const parts: string[] = [];
+
+  usable.forEach((item, index) => {
+    const radius = outer - index * thickness - thickness / 2;
+    if (radius <= 2) return;
+
+    const color = chartColor(theme, index, item.color);
+    const circumference = 2 * Math.PI * radius;
+    const pct = Math.min(Math.max(item.pct, 0), 100);
+
+    parts.push(
+      // Trilho + arco, com o traço girado para começar às 12h.
+      `<circle cx="${cx}" cy="${cy}" r="${radius.toFixed(1)}" fill="none" stroke="${theme.mutedBg}" ` +
+        `stroke-width="${(thickness - 2).toFixed(1)}" />`,
+      `<circle cx="${cx}" cy="${cy}" r="${radius.toFixed(1)}" fill="none" stroke="${color}" ` +
+        `stroke-width="${(thickness - 2).toFixed(1)}" stroke-linecap="round" ` +
+        `stroke-dasharray="${((circumference * pct) / 100).toFixed(1)} ${circumference.toFixed(1)}" ` +
+        `transform="rotate(-90 ${cx} ${cy})" />`,
+    );
+  });
+
+  if (options.centerLabel) {
+    parts.push(
+      text(options.centerLabel, cx, cy + 3, {
+        size: CHART_FONT.axis,
+        fill: theme.mutedFg,
+        anchor: 'middle',
+      }),
+    );
+  }
+
+  const legendX = chartWidth + 4;
+  const lineHeight = 16;
+  const legendTop = cy - (usable.length * lineHeight) / 2 + 8;
+
+  usable.forEach((item, index) => {
+    const y = legendTop + index * lineHeight;
+
+    parts.push(
+      `<rect x="${legendX}" y="${y - 7}" width="8" height="8" rx="2" fill="${chartColor(theme, index, item.color)}" />`,
+      text(truncateToWidth(item.label, CHART_FONT.legend, legendWidth - 60), legendX + 12, y, {
+        size: CHART_FONT.legend,
+        fill: theme.ink,
+      }),
+      text(`${Math.round(item.pct)}%`, width, y, {
+        size: CHART_FONT.legend,
+        fill: theme.mutedFg,
+        anchor: 'end',
+      }),
+    );
+  });
+
+  return svgRoot(width, height, parts.join(''), options.ariaLabel);
+}

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

@@ -0,0 +1,159 @@
+import { SafeSvg } from '../pdf-document.types';
+import {
+  CHART_DEFAULT_HEIGHT,
+  CHART_FONT,
+  CHART_FULL_WIDTH,
+  ChartBaseOptions,
+  ChartSeries,
+  chartColor,
+  emptyChart,
+  legendRows,
+  line,
+  svgRoot,
+  text,
+  xAxisLabels,
+  yAxis,
+} from './chart-primitives';
+import {
+  axisLabelPlan,
+  bandScale,
+  formatNumber,
+  linearScale,
+  niceScale,
+  withAlpha,
+} from './chart-scale';
+
+export interface LineChartOptions extends ChartBaseOptions {
+  categories: string[];
+  series: ChartSeries[];
+  /** Preenche a área sob a linha. */
+  area?: boolean;
+  yMin?: number;
+  yMax?: number;
+  yTicks?: number;
+  /** Linha tracejada de meta (ex.: frequência de 80%). */
+  referenceLine?: { value: number; label?: string };
+  showDots?: boolean;
+  legend?: boolean;
+}
+
+/**
+ * Linha (ou área) ao longo de categorias.
+ *
+ * Buraco na série vira interrupção da linha, não zero: um mês sem dado e um mês
+ * com zero matrículas são coisas diferentes, e emendar os dois inventa uma
+ * queda que não houve.
+ */
+export function lineChartSvg(options: LineChartOptions): SafeSvg {
+  const {
+    theme,
+    categories,
+    series,
+    width = CHART_FULL_WIDTH,
+    height = CHART_DEFAULT_HEIGHT,
+    valueFormat = (value: number) => formatNumber(value),
+  } = options;
+
+  const hasData = series.some((s) => s.values.some((v) => typeof v === 'number' && Number.isFinite(v)));
+  if (categories.length === 0 || !hasData) return emptyChart(options);
+
+  const showLegend = options.legend ?? series.length > 1;
+  const legendHeight = showLegend ? 16 : 0;
+  const plot = { left: 42, right: width - 8, top: 10, bottom: height - 26 - legendHeight };
+
+  const values = series
+    .flatMap((s) => s.values)
+    .filter((v): v is number => typeof v === 'number' && Number.isFinite(v));
+  const reference = options.referenceLine?.value;
+
+  const scale = niceScale(
+    options.yMin ?? Math.min(0, ...values),
+    options.yMax ?? Math.max(...values, reference ?? Number.NEGATIVE_INFINITY),
+    options.yTicks ?? 4,
+  );
+  const y = linearScale([scale.min, scale.max], [plot.bottom, plot.top]);
+  const band = bandScale(categories.length, [plot.left, plot.right], 0);
+
+  const parts: string[] = [
+    yAxis(scale.ticks, y, plot, theme, valueFormat),
+    line(plot.left, plot.bottom, plot.right, plot.bottom, theme.mutedFg),
+  ];
+
+  if (typeof reference === 'number') {
+    parts.push(
+      line(plot.left, y(reference), plot.right, y(reference), theme.mutedFg, { dash: '4 3' }),
+      text(options.referenceLine?.label ?? valueFormat(reference), plot.right, y(reference) - 4, {
+        size: CHART_FONT.axis,
+        fill: theme.mutedFg,
+        anchor: 'end',
+      }),
+    );
+  }
+
+  const showDots = options.showDots ?? categories.length <= 24;
+
+  series.forEach((serie, serieIndex) => {
+    const color = chartColor(theme, serieIndex, serie.color);
+    const segments: Array<Array<{ x: number; y: number }>> = [];
+    let current: Array<{ x: number; y: number }> = [];
+
+    categories.forEach((_, index) => {
+      const raw = serie.values[index];
+      if (typeof raw !== 'number' || !Number.isFinite(raw)) {
+        if (current.length) segments.push(current);
+        current = [];
+        return;
+      }
+      current.push({ x: band.center(index), y: y(raw) });
+    });
+    if (current.length) segments.push(current);
+
+    segments.forEach((points) => {
+      const path = points.map((p, i) => `${i === 0 ? 'M' : 'L'}${p.x.toFixed(1)},${p.y.toFixed(1)}`).join(' ');
+
+      if (options.area && points.length > 1) {
+        const first = points[0]!;
+        const last = points[points.length - 1]!;
+        parts.push(
+          `<path d="${path} L${last.x.toFixed(1)},${plot.bottom} L${first.x.toFixed(1)},${plot.bottom} Z" ` +
+            `fill="${withAlpha(color, 0.18)}" stroke="none" />`,
+        );
+      }
+
+      parts.push(
+        `<path d="${path}" fill="none" stroke="${color}" stroke-width="1.8" ` +
+          'stroke-linejoin="round" stroke-linecap="round" />',
+      );
+
+      if (showDots) {
+        points.forEach((point) => {
+          parts.push(
+            `<circle cx="${point.x.toFixed(1)}" cy="${point.y.toFixed(1)}" r="2.2" fill="${color}" />`,
+          );
+        });
+      }
+    });
+  });
+
+  const plan = axisLabelPlan(categories, band.bandwidth, CHART_FONT.axis);
+  parts.push(xAxisLabels(categories, band.center, plot.bottom + 12, plan, band.bandwidth, theme));
+
+  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);
+}
+
+/** Mesma figura com a área preenchida — o nome existe para o chamador ler melhor. */
+export const areaChartSvg = (options: LineChartOptions): SafeSvg =>
+  lineChartSvg({ ...options, area: true });

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