@cartella/renderer-html

Server-side Canvas JSON → HTML+CSS renderer for Cartella. Runs in Node (no DOM); pipe the output through any HTML-to-PDF toolchain — Gotenberg, Puppeteer, Playwright, headless Chromium. Shares the layout engine with the editor, so the render is pixel-identical to what authors see.

Install

pnpm add @cartella/renderer-html @cartella/core

Usage

import { renderHtml } from '@cartella/renderer-html';

const html = renderHtml(canvas, { data, fieldRegistry });
const pdf = await gotenberg.convert(html); // or Puppeteer/Playwright

renderHtml migrates, validates, and merges brand context internally — pass the raw Canvas JSON.

Flowing (paginated) documents — invoices, receipts, statements, reports

A page with layout: 'flow' lays its content out in normal vertical flow: a table (overflowBehavior: 'flow') grows to any number of rows, pushes the blocks after it down, and paginates automatically across pages with the header/footer bands repeating on each page.

For the print/PDF pipeline, use renderFlowPrintAssets — it returns the body plus the bands as native header/footer templates (which Chromium places in the page margin on every page, without the overlap that CSS position: fixed bands cause in printToPDF):

import { renderFlowPrintAssets } from '@cartella/renderer-html';

const { html, header, footer } = renderFlowPrintAssets(canvas, { data, fieldRegistry });

// Gotenberg /forms/chromium/convert/html:
//   index.html        = html
//   header.html       = header      (omit if '')
//   footer.html       = footer      (omit if '')
//   printBackground   = true
//   preferCssPageSize = true        // the body's @page reserves the band space

renderHtml's inline bands are for on-screen preview; use renderFlowPrintAssets for print.

API

• renderHtml(canvas, options) → string — full HTML document.
• renderFlowPrintAssets(canvas, options) → { html, header, footer, marginTop, marginBottom, marginLeft, marginRight } — print pieces for Gotenberg native header/footer.
• RenderOptions — data, fieldRegistry, brandContext, assetResolver, dpi, pageSelection, flowBands, and QR/barcode renderer overrides.

Full types ship with the package (renderFlowPrintAssets' JSDoc includes the Gotenberg mapping).

Documentation

• Flowing documents & print: docs/document-flow-layout.md
• All guides: Cartella docs

License

MIT