pagyra-js 0.0.1

package/src/pdf/header-footer-painter.ts

@@ -0,0 +1,209 @@
+import type { RenderBox, TextPaintOptions, PageSize, Rect } from "./types.js";
+import type { PagePainter } from "./page-painter.js";
+import type { HeaderFooterVariant, HeaderFooterLayout } from "./header-footer-layout.js";
+import type { FontRegistry } from "./font/font-registry.js";
+import { applyPlaceholders } from "./header-footer-tokens.js";
+import {
+  renderHeaderFooterHtml,
+  paintRenderedHeaderFooter,
+  type RenderedHeaderFooter,
+} from "./header-footer-renderer.js";
+import { paintBoxAtomic } from "./renderer/box-painter.js";
+import { log } from "../logging/debug.js";
+import type { Environment } from "../environment/environment.js";
+
+export interface HeaderFooterPaintContext {
+  /** Page margins in pixels */
+  margins: { top: number; right: number; bottom: number; left: number };
+  /** Page width in pixels */
+  pageWidthPx: number;
+  /** Page height in pixels */
+  pageHeightPx: number;
+  /** Font registry for text rendering */
+  fontRegistry: FontRegistry;
+  /** Page offset Y for coordinate transformation */
+  pageOffsetY: number;
+  /** Optional CSS for header/footer styling */
+  css?: string;
+  /** Platform environment (Node/browser) */
+  environment?: Environment;
+}
+
+/**
+ * Renders and paints headers and footers as full HTML content.
+ * This provides Word/mPDF-like behavior where headers and footers
+ * are fully rendered HTML with complete styling support.
+ */
+export async function paintHeaderFooter(
+  painter: PagePainter,
+  header: HeaderFooterVariant | undefined,
+  footer: HeaderFooterVariant | undefined,
+  tokens: Map<string, string | ((page: number, total: number) => string)>,
+  pageIndex: number,
+  totalPages: number,
+  baseOptions: TextPaintOptions = { fontSizePt: 10 },
+  under = false,
+  context?: HeaderFooterPaintContext,
+): Promise<void> {
+  void under;
+
+  // If we have full context, use the new HTML rendering path
+  if (context) {
+    log("layout", "debug", "Using HTML rendering path for headers/footers", {
+      hasHeader: !!header?.content,
+      hasFooter: !!footer?.content,
+      margins: context.margins,
+    });
+    await paintHeaderFooterWithContext(
+      painter,
+      header,
+      footer,
+      tokens,
+      pageIndex,
+      totalPages,
+      context,
+    );
+    return;
+  }
+
+  log("layout", "debug", "Using legacy text rendering for headers/footers (no context)");
+  // Fallback to legacy text-only rendering for backwards compatibility
+  await paintHeaderFooterLegacy(painter, header, footer, tokens, pageIndex, totalPages, baseOptions);
+}
+
+/**
+ * New HTML rendering path for headers/footers.
+ * Renders headers and footers as full HTML through the layout pipeline.
+ */
+async function paintHeaderFooterWithContext(
+  painter: PagePainter,
+  header: HeaderFooterVariant | undefined,
+  footer: HeaderFooterVariant | undefined,
+  tokens: Map<string, string | ((page: number, total: number) => string)>,
+  pageIndex: number,
+  totalPages: number,
+  context: HeaderFooterPaintContext,
+): Promise<void> {
+  const { margins, pageWidthPx, pageHeightPx, fontRegistry, pageOffsetY, css } = context;
+
+  // Calculate content width (page width minus left and right margins)
+  const contentWidthPx = pageWidthPx - margins.left - margins.right;
+
+  log("layout", "debug", "paintHeaderFooterWithContext", {
+    headerContent: header?.content ? String(header.content).slice(0, 100) : "none",
+    footerContent: footer?.content ? String(footer.content).slice(0, 100) : "none",
+    contentWidthPx,
+    pageWidthPx,
+    pageHeightPx,
+  });
+
+  // Render and paint header
+  if (header?.content) {
+    const headerHtml = stringify(header.content);
+    log("layout", "debug", "Rendering header HTML", { headerHtml: headerHtml.slice(0, 200) });
+    if (headerHtml) {
+      try {
+        const rendered = await renderHeaderFooterHtml({
+          html: headerHtml,
+          css,
+          widthPx: contentWidthPx,
+          maxHeightPx: header.maxHeightPx,
+          tokens,
+          pageNumber: pageIndex,
+          totalPages,
+          environment: context.environment,
+        });
+
+        if (rendered) {
+          log("layout", "debug", "Header rendered successfully", { heightPx: rendered.heightPx });
+          // Header is positioned at the top margin area
+          await paintRenderedHeaderFooter(
+            painter,
+            rendered,
+            margins.left,
+            margins.top,
+            fontRegistry,
+            pageOffsetY,
+          );
+        }
+      } catch (err) {
+        log("layout", "warn", "Failed to render header HTML", { error: err });
+      }
+    }
+  }
+
+  // Render and paint footer
+  if (footer?.content) {
+    const footerHtml = stringify(footer.content);
+    if (footerHtml) {
+      try {
+        const rendered = await renderHeaderFooterHtml({
+          html: footerHtml,
+          css,
+          widthPx: contentWidthPx,
+          maxHeightPx: footer.maxHeightPx,
+          tokens,
+          pageNumber: pageIndex,
+          totalPages,
+          environment: context.environment,
+        });
+
+        if (rendered) {
+          // Footer is positioned at the bottom of the page
+          const footerY = pageHeightPx - margins.bottom - footer.maxHeightPx;
+          await paintRenderedHeaderFooter(
+            painter,
+            rendered,
+            margins.left,
+            footerY,
+            fontRegistry,
+            pageOffsetY,
+          );
+        }
+      } catch (err) {
+        log("layout", "warn", "Failed to render footer HTML", { error: err });
+      }
+    }
+  }
+}
+
+/**
+ * Legacy text-only rendering for headers/footers.
+ * Used for backwards compatibility when context is not provided.
+ */
+async function paintHeaderFooterLegacy(
+  painter: PagePainter,
+  header: HeaderFooterVariant | undefined,
+  footer: HeaderFooterVariant | undefined,
+  tokens: Map<string, string | ((page: number, total: number) => string)>,
+  pageIndex: number,
+  totalPages: number,
+  baseOptions: TextPaintOptions,
+): Promise<void> {
+  const headerText = header?.content ? stringify(header.content) : undefined;
+  const footerText = footer?.content ? stringify(footer.content) : undefined;
+
+  if (headerText) {
+    const rendered = applyPlaceholders(headerText, tokens, pageIndex, totalPages);
+    await painter.drawText(rendered, 16, header?.maxHeightPx ?? 24, { ...baseOptions, absolute: true });
+  }
+
+  if (footerText) {
+    const rendered = applyPlaceholders(footerText, tokens, pageIndex, totalPages);
+    const yPx = painter.pageHeightPx ? painter.pageHeightPx - ((footer?.maxHeightPx ?? 24) + 16) : 16;
+    await painter.drawText(rendered, 16, yPx, { ...baseOptions, absolute: true });
+  }
+}
+
+function stringify(content: unknown): string {
+  if (content == null) {
+    return "";
+  }
+  if (typeof content === "string") {
+    return content;
+  }
+  if (typeof content === "function") {
+    return String(content());
+  }
+  return JSON.stringify(content);
+}

package/src/pdf/header-footer-renderer.ts

@@ -0,0 +1,357 @@
+/**
+ * Header/Footer Renderer
+ *
+ * This module provides Word/mPDF-like header and footer rendering.
+ * Headers and footers are rendered as full HTML through the same layout pipeline
+ * as the main content, giving them full styling capabilities.
+ *
+ * Key behaviors:
+ * - Headers are rendered at the top of each page (within top margin area)
+ * - Footers are rendered at the bottom of each page (within bottom margin area)
+ * - Main content area is automatically reduced to exclude header/footer space
+ * - Placeholders like {{pageNumber}}, {{totalPages}}, {{date}} are supported
+ */
+
+import { parseHTML } from "linkedom";
+import type { FontConfig } from "../types/fonts.js";
+import { parseCss } from "../html/css/parse-css.js";
+import { makeUnitParsers, type UnitCtx, pxToPt } from "../units/units.js";
+import { LayoutNode } from "../dom/node.js";
+import { ComputedStyle } from "../css/style.js";
+import { layoutTree } from "../layout/pipeline/layout-tree.js";
+import { buildRenderTree, type RenderTreeOptions } from "./layout-tree-builder.js";
+import type { RenderBox, Rect, LayoutTree, RGBA, Run, TextPaintOptions } from "./types.js";
+import { convertDomNode } from "../html/dom-converter.js";
+import { computeStyleForElement } from "../css/compute-style.js";
+import { Display } from "../css/enums.js";
+import { log } from "../logging/debug.js";
+import { offsetRenderTree } from "../render/offset.js";
+import type { FontEmbedder } from "./font/embedder.js";
+import { FontRegistryResolver } from "../fonts/font-registry-resolver.js";
+import type { FontRegistry } from "./font/font-registry.js";
+import { computeGlyphRun, applyWordSpacingToGlyphRun } from "./utils/node-text-run-factory.js";
+import type { PagePainter } from "./page-painter.js";
+import { paintBoxAtomic } from "./renderer/box-painter.js";
+import { applyPlaceholders } from "./header-footer-tokens.js";
+import type { Environment } from "../environment/environment.js";
+
+export interface HeaderFooterRenderOptions {
+  /** The HTML content for the header/footer */
+  html: string;
+  /** Optional CSS to apply */
+  css?: string;
+  /** Width of the header/footer area in pixels */
+  widthPx: number;
+  /** Maximum height of the header/footer area in pixels */
+  maxHeightPx: number;
+  /** Font configuration for rendering */
+  fontConfig?: FontConfig;
+  /** Font embedder for PDF output */
+  fontEmbedder?: FontEmbedder | null;
+  /** Resource base directory for loading assets */
+  resourceBaseDir?: string;
+  /** Asset root directory */
+  assetRootDir?: string;
+  /** Tokens for placeholder replacement */
+  tokens?: Map<string, string | ((page: number, total: number) => string)>;
+  /** Current page number (1-indexed) */
+  pageNumber?: number;
+  /** Total number of pages */
+  totalPages?: number;
+  /** Platform environment (Node/browser) for resource loading */
+  environment?: Environment;
+}
+
+export interface RenderedHeaderFooter {
+  /** The render tree for the header/footer */
+  renderTree: LayoutTree;
+  /** The actual height of the rendered content in pixels */
+  heightPx: number;
+  /** The root render box */
+  root: RenderBox;
+}
+
+/**
+ * Renders header or footer HTML into a layout tree.
+ * This uses the same pipeline as the main content for full HTML/CSS support.
+ */
+export async function renderHeaderFooterHtml(
+  options: HeaderFooterRenderOptions
+): Promise<RenderedHeaderFooter | null> {
+  const {
+    html,
+    css = "",
+    widthPx,
+    maxHeightPx,
+    fontEmbedder,
+    resourceBaseDir,
+    assetRootDir,
+    tokens,
+    pageNumber = 1,
+    totalPages = 1,
+    environment,
+  } = options;
+
+  const resolvedResourceBase = resourceBaseDir ?? "";
+  const resolvedAssetRoot = assetRootDir ?? resolvedResourceBase;
+
+  if (!html || !html.trim()) {
+    return null;
+  }
+
+  // Apply placeholder replacements
+  let processedHtml = html;
+  if (tokens) {
+    processedHtml = applyPlaceholders(html, tokens, pageNumber, totalPages);
+  }
+
+  // Wrap in a container if not already a full document
+  const normalizedHtml = normalizeHtmlFragment(processedHtml);
+
+  const unitCtx: UnitCtx = { viewport: { width: widthPx, height: maxHeightPx } };
+  const units = makeUnitParsers(unitCtx);
+
+  const { document } = parseHTML(normalizedHtml);
+
+  // Parse CSS
+  const { styleRules: cssRules } = parseCss(css);
+
+  // Get the root element
+  const rootElement = document.body || document.documentElement;
+
+  const baseParentStyle = new ComputedStyle();
+  const rootFontSize = baseParentStyle.fontSize;
+
+  let rootStyle = computeStyleForElement(rootElement, cssRules, baseParentStyle, units, rootFontSize);
+  if (isInlineDisplay(rootStyle.display)) {
+    rootStyle.display = Display.Block;
+  }
+
+  const rootLayout = new LayoutNode(rootStyle, [], { tagName: rootElement?.tagName?.toLowerCase() });
+
+  const conversionContext = { resourceBaseDir: resolvedResourceBase, assetRootDir: resolvedAssetRoot, units, rootFontSize, environment };
+
+  if (rootElement) {
+    for (const child of Array.from(rootElement.childNodes)) {
+      if (child.nodeType === child.ELEMENT_NODE) {
+        const tagName = (child as HTMLElement).tagName.toLowerCase();
+        if (tagName === "head" || tagName === "meta" || tagName === "title" || tagName === "link" || tagName === "script") {
+          continue;
+        }
+      }
+      const layoutChild = await convertDomNode(child, cssRules, rootStyle, conversionContext);
+      if (layoutChild) rootLayout.appendChild(layoutChild);
+    }
+  }
+
+  // Layout with constrained dimensions
+  layoutTree(rootLayout, { width: widthPx, height: maxHeightPx }, fontEmbedder ?? null);
+
+  const renderTree = buildRenderTree(rootLayout, {});
+
+  // Calculate actual height
+  const actualHeight = Math.min(calculateTreeHeight(renderTree.root), maxHeightPx);
+
+  log("layout", "debug", "Header/footer rendered", {
+    widthPx,
+    maxHeightPx,
+    actualHeight,
+    hasContent: renderTree.root.children.length > 0,
+  });
+
+  return {
+    renderTree,
+    heightPx: actualHeight,
+    root: renderTree.root,
+  };
+}
+
+/**
+ * Deep clones a render box tree for per-page rendering.
+ * This is needed because we apply offsets that are page-specific.
+ */
+function cloneRenderBox(box: RenderBox): RenderBox {
+  const clonedRuns = box.textRuns.map((run) => ({
+    ...run,
+    lineMatrix: run.lineMatrix ? { ...run.lineMatrix } : undefined,
+    decorations: run.decorations ? { ...run.decorations } : undefined,
+    glyphs: run.glyphs ? { ...run.glyphs } : undefined,
+  })) as Run[];
+
+  const clonedBox: RenderBox = {
+    ...box,
+    contentBox: { ...box.contentBox },
+    paddingBox: { ...box.paddingBox },
+    borderBox: { ...box.borderBox },
+    visualOverflow: { ...box.visualOverflow },
+    padding: { ...box.padding },
+    border: { ...box.border },
+    borderRadius: {
+      topLeft: { ...box.borderRadius.topLeft },
+      topRight: { ...box.borderRadius.topRight },
+      bottomRight: { ...box.borderRadius.bottomRight },
+      bottomLeft: { ...box.borderRadius.bottomLeft },
+    },
+    background: box.background
+      ? {
+          color: box.background.color ? { ...box.background.color } : undefined,
+          image: box.background.image
+            ? {
+                ...box.background.image,
+                rect: { ...box.background.image.rect },
+                originRect: { ...box.background.image.originRect },
+              }
+            : undefined,
+          gradient: box.background.gradient
+            ? {
+                ...box.background.gradient,
+                rect: { ...box.background.gradient.rect },
+                originRect: { ...box.background.gradient.originRect },
+              }
+            : undefined,
+        }
+      : { color: undefined },
+    textRuns: clonedRuns,
+    markerRect: box.markerRect ? { ...box.markerRect } : undefined,
+    boxShadows: box.boxShadows.map((s) => ({ ...s, color: { ...s.color } })),
+    links: box.links.map((link) => ({
+      rect: { ...link.rect },
+      target: { ...link.target },
+    })),
+    children: box.children.map((child) => cloneRenderBox(child)),
+  };
+
+  return clonedBox;
+}
+
+/**
+ * Paints a rendered header/footer onto a page.
+ */
+export async function paintRenderedHeaderFooter(
+  painter: PagePainter,
+  rendered: RenderedHeaderFooter,
+  xOffsetPx: number,
+  yOffsetPx: number,
+  fontRegistry: FontRegistry,
+  pageOffsetY: number,
+): Promise<void> {
+  // Clone the tree to avoid mutating the original
+  const clonedRoot = cloneRenderBox(rendered.root);
+
+  // Enrich text runs with glyph data
+  const fontResolver = new FontRegistryResolver(fontRegistry);
+  await enrichTreeWithGlyphRuns(clonedRoot, fontResolver);
+
+  // Offset the tree to the correct position
+  offsetRenderTree(clonedRoot, xOffsetPx, yOffsetPx - pageOffsetY, false);
+
+  // Paint all boxes
+  const stack: RenderBox[] = [clonedRoot];
+  while (stack.length > 0) {
+    const box = stack.pop()!;
+    await paintBoxAtomic(painter, box);
+    // Add children in reverse order to paint in correct order
+    for (let i = box.children.length - 1; i >= 0; i--) {
+      stack.push(box.children[i]);
+    }
+  }
+}
+
+/**
+ * Calculates the configuration for page content area when headers/footers are present.
+ */
+export interface PageContentAreaConfig {
+  /** Y offset where content should start (after header) */
+  contentStartY: number;
+  /** Available height for content (excluding header and footer) */
+  contentHeightPx: number;
+  /** Y position where footer should be placed */
+  footerY: number;
+}
+
+export function calculatePageContentArea(
+  pageHeightPx: number,
+  marginTop: number,
+  marginBottom: number,
+  headerHeightPx: number,
+  footerHeightPx: number,
+): PageContentAreaConfig {
+  // Header is placed at marginTop
+  // Content starts after header
+  const contentStartY = marginTop + headerHeightPx;
+
+  // Footer is placed at (pageHeight - marginBottom - footerHeight)
+  const footerY = pageHeightPx - marginBottom - footerHeightPx;
+
+  // Content height is the space between header and footer
+  const contentHeightPx = footerY - contentStartY;
+
+  return {
+    contentStartY,
+    contentHeightPx: Math.max(0, contentHeightPx),
+    footerY,
+  };
+}
+
+function normalizeHtmlFragment(html: string): string {
+  const hasHtmlTag = /<\s*html[\s>]/i.test(html);
+  if (hasHtmlTag) {
+    return html;
+  }
+  return `<!doctype html><html><head></head><body>${html}</body></html>`;
+}
+
+function isInlineDisplay(display: Display): boolean {
+  return (
+    display === Display.Inline ||
+    display === Display.InlineBlock ||
+    display === Display.InlineFlex ||
+    display === Display.InlineGrid ||
+    display === Display.InlineTable
+  );
+}
+
+function calculateTreeHeight(root: RenderBox): number {
+  let maxBottom = 0;
+
+  function traverse(box: RenderBox): void {
+    const bottom = box.borderBox.y + box.borderBox.height;
+    maxBottom = Math.max(maxBottom, bottom);
+    for (const child of box.children) {
+      traverse(child);
+    }
+  }
+
+  traverse(root);
+  return maxBottom;
+}
+
+async function enrichTreeWithGlyphRuns(root: RenderBox, fontResolver: FontRegistryResolver): Promise<void> {
+  async function enrichRun(run: Run): Promise<void> {
+    if (run.glyphs) {
+      return;
+    }
+    try {
+      const font = await fontResolver.resolve(run.fontFamily, run.fontWeight, run.fontStyle);
+      const letterSpacing = run.letterSpacing ?? 0;
+      const glyphRun = computeGlyphRun(font, run.text, run.fontSize, letterSpacing);
+      applyWordSpacingToGlyphRun(glyphRun, run.text, run.wordSpacing);
+      run.glyphs = glyphRun;
+    } catch {
+      // Ignore font resolution errors for headers/footers
+    }
+  }
+
+  async function traverse(box: RenderBox): Promise<void> {
+    if (box.textRuns && box.textRuns.length > 0) {
+      for (const run of box.textRuns) {
+        await enrichRun(run);
+      }
+    }
+    for (const child of box.children) {
+      await traverse(child);
+    }
+  }
+
+  await traverse(root);
+}

package/src/pdf/header-footer-tokens.ts

@@ -0,0 +1,55 @@
+import type { HeaderFooterHTML } from "./types.js";
+
+export function computeHfTokens(
+  placeholders: HeaderFooterHTML["placeholders"],
+  _totalPages: number,
+  meta: { title?: string } = {},
+): Map<string, string | ((page: number, total: number) => string)> {
+  const tokens = new Map<string, string | ((page: number, total: number) => string)>();
+  for (const [key, value] of Object.entries(placeholders ?? {})) {
+    tokens.set(key, value);
+  }
+  // Support multiple naming conventions for page numbers
+  tokens.set("page", (page, _total) => String(page));
+  tokens.set("pageNumber", (page, _total) => String(page));
+  tokens.set("pages", (_page, total) => String(total));
+  tokens.set("totalPages", (_page, total) => String(total));
+  if (!tokens.has("title") && meta.title) {
+    tokens.set("title", meta.title);
+  }
+  tokens.set("date", () => new Date().toLocaleDateString());
+  return tokens;
+}
+
+export function applyPlaceholders(
+  template: string,
+  tokens: Map<string, string | ((page: number, total: number) => string)>,
+  pageIndex: number,
+  totalPages: number,
+): string {
+  // Support both {{key}} (double curly braces) and {key} (single curly braces) syntax
+  // First replace double braces, then single braces
+  let result = template.replace(/\{\{([^}]+)\}\}/g, (_, key) => {
+    const entry = tokens.get(key.trim());
+    if (entry === undefined) {
+      return "";
+    }
+    if (typeof entry === "string") {
+      return entry;
+    }
+    return entry(pageIndex, totalPages);
+  });
+
+  result = result.replace(/\{([^}]+)\}/g, (_, key) => {
+    const entry = tokens.get(key.trim());
+    if (entry === undefined) {
+      return "";
+    }
+    if (typeof entry === "string") {
+      return entry;
+    }
+    return entry(pageIndex, totalPages);
+  });
+
+  return result;
+}

package/src/pdf/header-footer.ts

@@ -0,0 +1,25 @@
+export {
+  type HeaderFooterContext,
+  type HeaderFooterLayout,
+  type HeaderFooterVariant,
+  type HeaderFooterVariants,
+  initHeaderFooterContext,
+  layoutHeaderFooterTrees,
+  adjustPageBoxForHf,
+  pickHeaderVariant,
+  pickFooterVariant,
+} from "./header-footer-layout.js";
+
+export { computeHfTokens, applyPlaceholders } from "./header-footer-tokens.js";
+
+export { paintHeaderFooter, type HeaderFooterPaintContext } from "./header-footer-painter.js";
+
+export {
+  renderHeaderFooterHtml,
+  paintRenderedHeaderFooter,
+  calculatePageContentArea,
+  type HeaderFooterRenderOptions,
+  type RenderedHeaderFooter,
+  type PageContentAreaConfig,
+} from "./header-footer-renderer.js";
+export type { Environment as HeaderFooterEnvironment } from "../environment/environment.js";