h17-sspdf 1.0.2 → 1.2.0

package/DOCUMENTATION.md

@@ -240,6 +240,7 @@ Shared layout defaults read by operation handlers.
 layout: {
   bulletIndentMm: 4.5,     // text indent after bullet marker (default: 4)
   chartAlign: "center",    // chart horizontal alignment: "left" (default) or "center"
+  columnGutterMm: 5,       // default gutter between columns (required if columns ops omit gutterMm)
 }
 ```
 
@@ -645,6 +646,39 @@ Identical to `block` but defaults to `keepTogether: false`. Use sections to grou
 
 Alias for `block`.
 
+#### `columns`
+
+Renders two independent operation lists side by side. Each column gets half the content width minus half the gutter. The cursor advances to the bottom of the taller column, so subsequent full-width operations continue from the correct position.
+
+```json
+{
+  "type": "columns",
+  "gutterMm": 5,
+  "column1": [
+    { "type": "text", "label": "doc.heading", "text": "Left Column" },
+    { "type": "text", "label": "doc.body", "text": "Content on the left." }
+  ],
+  "column2": [
+    { "type": "text", "label": "doc.heading", "text": "Right Column" },
+    { "type": "text", "label": "doc.body", "text": "Content on the right." }
+  ]
+}
+```
+
+| Field | Required | Type | Description |
+|---|---|---|---|
+| `column1` | yes | array | Operations for the left column |
+| `column2` | yes | array | Operations for the right column |
+| `gutterMm` | no* | number | Gap between columns in mm. *Required if `theme.layout.columnGutterMm` is not set |
+
+**Gutter resolution:** `gutterMm` on the operation takes precedence. If omitted, `theme.layout.columnGutterMm` is used. If neither is defined, the engine throws.
+
+**Column width:** `(contentWidth - gutterMm) / 2`. Both columns are always equal width.
+
+**Cursor after:** `max(col1EndY, col2EndY)` - the bottom of the taller column.
+
+Any operation type that works at the top level works inside columns. Tables, images, bullets, nested blocks all work. Columns inside columns are supported (the margin stack is re-entrant).
+
 ### Inferred text operations
 
 If a node has `label` and `text` (or `value`) but no `type`, it's treated as text:
@@ -675,6 +709,7 @@ The engine positions content using a cursor that starts at `marginTopMm` and mov
 | `table` | marginTop + headerRowHeight + sum(dataRowHeights) + marginBottom |
 | `image` | marginTop + paddingTop + imageHeightMm + captionHeight + paddingBottom + marginBottom |
 | `block` | sum of children deltas (+ spaceAfter if defined) |
+| `columns` | max(col1Height, col2Height) |
 
 Where:
 - `lineHeightMm = (fontSize × 25.4/72) × lineHeight` (font points → mm × multiplier)
@@ -1350,6 +1385,7 @@ This applies to all color properties: `color`, `backgroundColor`, `borderColor`,
 | `section` | `content` | `label`, `keepTogether` |
 | `quote` | `label`, `text` | `attribution`, `attributionLabel` |
 | `hiddenText` | `label`, `text` | - |
+| `columns` | `column1`, `column2` | `gutterMm` (falls back to `theme.layout.columnGutterMm`) |
 
 Every operation also accepts `xMm` and `maxWidthMm` to override the theme margins for that operation only.
 

package/README.md

@@ -20,7 +20,7 @@ Source JSON  +  Theme  =  PDF
 npm install h17-sspdf
 ```
 
-Requires **Node.js 18 or newer**. The engine vendors a single self-contained UMD build of jsPDF (which bundles fflate, fast-png, iobuffer internally) plus Chart.js and chartjs-node-canvas. The only install-time dependency is [`canvas`](https://www.npmjs.com/package/canvas) (native C++ addon, used by the chart plugin) — no transitive dependency tree beyond that.
+Requires **Node.js 18 or newer**. The engine vendors a single self-contained UMD build of jsPDF (which bundles fflate, fast-png, iobuffer internally) plus Chart.js and chartjs-node-canvas. The base install has no runtime dependencies. The optional chart plugin uses [`canvas`](https://www.npmjs.com/package/canvas) as an optional peer dependency.
 
 ## The problem it solves
 
@@ -199,7 +199,7 @@ A repeating pattern of `row` + `text` pairs. The row carries the label/value, th
   "type": "quote",
   "label": "news.pullquote",
   "text": "When the format becomes a system instead of a template, agencies stop re-solving the same layout problem every week.",
-  "attribution": "— Elena Ward, public records modernization lead",
+  "attribution": "- Elena Ward, public records modernization lead",
   "xMm": 22,
   "maxWidthMm": 166
 }
@@ -270,6 +270,7 @@ labels: {
 | `quote` | Blockquote with attribution | `label`, `text`, `attribution` |
 | `block` | Group children, optional background + border | `children`, `keepTogether` |
 | `section` | Logical group, allows breaks inside | `content` |
+| `columns` | Two-column side-by-side layout | `column1`, `column2`, `gutterMm` |
 
 ### Position overrides
 
@@ -473,7 +474,7 @@ Claude Code skills for generating PDFs and themes are available in the `skills/`
 - Single-line `row` cells, no multi-line column pairs
 - `{{page}}` gives the current page number; `{{pages}}` (total page count) is not supported because keep-together rules make the final page count unpredictable until the last operation is laid out
 - Charts require the `canvas` npm package (native C++ addon) for server-side rendering; everything else is zero native dependencies
-- A `jspdf.umd.js` build is vendored for client-side/browser use. It bundles all dependencies internally but requires wiring up your own entry point — `pdf-core.js` uses the Node build by default
+- A `jspdf.umd.js` build is vendored for client-side/browser use. It bundles all dependencies internally but requires wiring up your own entry point; `pdf-core.js` uses the Node build by default
 
 ---
 

package/cli.js

@@ -155,7 +155,7 @@ function collectChartOps(obj) {
     obj.forEach((item) => charts.push(...collectChartOps(item)));
   } else {
     if (obj.type === "chart") charts.push(obj);
-    for (const key of ["operations", "sections", "content", "items", "children"]) {
+    for (const key of ["operations", "sections", "content", "items", "children", "column1", "column2"]) {
       if (Array.isArray(obj[key])) charts.push(...collectChartOps(obj[key]));
     }
     if (obj.pageTemplates) {

package/core/pdf-core.js

@@ -278,6 +278,33 @@ class PDFCore {
     this.cursorY = Number(y) || this.cursorY;
   }
 
+  /**
+   * Narrow the content area to a column band. Saves current margins and cursor.
+   * @param {number} left  Absolute left x in mm
+   * @param {number} right Absolute right x in mm
+   */
+  _enterColumnBounds(left, right) {
+    if (!this._colMarginStack) this._colMarginStack = [];
+    this._colMarginStack.push({ left: this.marginLeftMm, right: this.marginRightMm });
+    this.marginLeftMm = left;
+    this.marginRightMm = this.pageWidth - right;
+  }
+
+  /**
+   * Restore margins saved by _enterColumnBounds. Returns the cursor position
+   * reached at end of column so the caller can track the tallest column.
+   * @param {number} savedCursorY  The cursor to restore after saving column end Y
+   * @returns {number}  Cursor Y at end of column
+   */
+  _exitColumnBounds(savedCursorY) {
+    const endY = this.cursorY;
+    const saved = this._colMarginStack.pop();
+    this.marginLeftMm = saved.left;
+    this.marginRightMm = saved.right;
+    this.cursorY = savedCursorY;
+    return endY;
+  }
+
   /**
    * Apply a text style to jsPDF.
    * @param {object} style

package/core/plugin-chart.js

@@ -50,6 +50,10 @@
  */
 
 let _ChartJSNodeCanvas = null;
+const _rendererCache = new Map();
+const MAX_RENDERER_CACHE_SIZE = 8;
+const DEFAULT_CANVAS_WIDTH = 1600;
+const DEFAULT_CANVAS_HEIGHT = 800;
 
 function getCanvas() {
   if (!_ChartJSNodeCanvas) {
@@ -64,6 +68,46 @@ function getCanvas() {
   return _ChartJSNodeCanvas;
 }
 
+function getRenderer(width, height) {
+  const ChartJSNodeCanvas = getCanvas();
+  const key = `${width}x${height}`;
+  if (_rendererCache.has(key)) {
+    return _rendererCache.get(key);
+  }
+  if (_rendererCache.size >= MAX_RENDERER_CACHE_SIZE) {
+    const oldestKey = _rendererCache.keys().next().value;
+    _rendererCache.delete(oldestKey);
+  }
+  const renderer = new ChartJSNodeCanvas({
+    width,
+    height,
+    backgroundColour: 'transparent',
+  });
+  _rendererCache.set(key, renderer);
+  return renderer;
+}
+
+function resolvePositiveNumber(value, fallback, name) {
+  if (value === undefined || value === null || value === '') {
+    return fallback;
+  }
+  const numberValue = Number(value);
+  if (!Number.isFinite(numberValue) || numberValue <= 0) {
+    throw new Error(`chart plugin: ${name} must be a positive number`);
+  }
+  return numberValue;
+}
+
+function cloneChartValue(value) {
+  if (!value || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(cloneChartValue);
+  const out = {};
+  for (const key of Object.keys(value)) {
+    out[key] = cloneChartValue(value[key]);
+  }
+  return out;
+}
+
 /**
  * Pre-render the chart to a PNG buffer and cache it on the operation.
  * Call this before renderDocument() for any source containing chart operations.
@@ -77,35 +121,28 @@ function getCanvas() {
  *
  * Supported token: {{v}} - replaced with the callback's first argument (value).
  */
-function resolveCallbackTemplates(obj) {
-  if (!obj || typeof obj !== 'object') return obj;
-  if (Array.isArray(obj)) {
-    for (let i = 0; i < obj.length; i++) {
-      obj[i] = resolveCallbackTemplates(obj[i]);
-    }
-    return obj;
-  }
-  for (const key of Object.keys(obj)) {
-    if (key === 'callback' && typeof obj[key] === 'string' && obj[key].includes('{{v}}')) {
-      const template = obj[key];
-      obj[key] = function (value) { return template.replace(/\{\{v\}\}/g, String(value)); };
+function resolveCallbackTemplates(value) {
+  if (!value || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(resolveCallbackTemplates);
+
+  const out = {};
+  for (const key of Object.keys(value)) {
+    if (key === 'callback' && typeof value[key] === 'string' && value[key].includes('{{v}}')) {
+      const template = value[key];
+      out[key] = function (callbackValue) {
+        return template.replace(/\{\{v\}\}/g, String(callbackValue));
+      };
     } else {
-      obj[key] = resolveCallbackTemplates(obj[key]);
+      out[key] = resolveCallbackTemplates(value[key]);
     }
   }
-  return obj;
+  return out;
 }
 
 async function preRender(operation) {
-  const ChartJSNodeCanvas = getCanvas();
-  const canvasW = operation.canvasWidth  || 1600;
-  const canvasH = operation.canvasHeight || 800;
-
-  const canvas = new ChartJSNodeCanvas({
-    width: canvasW,
-    height: canvasH,
-    backgroundColour: 'transparent',
-  });
+  const canvasW = resolvePositiveNumber(operation.canvasWidth, DEFAULT_CANVAS_WIDTH, 'canvasWidth');
+  const canvasH = resolvePositiveNumber(operation.canvasHeight, DEFAULT_CANVAS_HEIGHT, 'canvasHeight');
+  const canvas = getRenderer(canvasW, canvasH);
 
   const options = resolveCallbackTemplates({
     ...(operation.options || {}),
@@ -115,7 +152,7 @@ async function preRender(operation) {
 
   operation._buf = await canvas.renderToBuffer({
     type:    operation.chartType || 'bar',
-    data:    operation.data    || { labels: [], datasets: [] },
+    data:    cloneChartValue(operation.data || { labels: [], datasets: [] }),
     options,
   });
 }

package/core/plugin-registry.js

@@ -3,6 +3,7 @@ const _plugins = new Map();
 const BUILT_IN_TYPES = new Set([
   "text", "row", "bullet", "divider", "spacer", "hiddenText",
   "block", "section", "group", "quote", "table", "image",
+  "columns", "pageBreak",
 ]);
 
 function registerPlugin(type, handler) {

package/core/render-document.js

@@ -284,6 +284,14 @@ function normalizeNode(node, path) {
     }];
   }
 
+  if (node.type === "columns") {
+    return [{
+      ...node,
+      column1: Array.isArray(node.column1) ? normalizeNodes(node.column1, `${path}.column1`) : [],
+      column2: Array.isArray(node.column2) ? normalizeNodes(node.column2, `${path}.column2`) : [],
+    }];
+  }
+
   if (isOperationType(node.type)) {
     return expandOperationNode(node, path);
   }
@@ -344,6 +352,7 @@ function isOperationType(type) {
     || type === "hiddenText"
     || type === "table"
     || type === "image"
+    || type === "columns"
     || hasPlugin(type);
 }
 
@@ -873,6 +882,39 @@ function executeOperation(ctx) {
     return;
   }
 
+  if (operation.type === "columns") {
+    const bounds = getHorizontalBounds(core, templateBypassMargins);
+    const contentWidth = bounds.right - bounds.left;
+    const gutterMm = resolveColumnsGutter(operation, theme, index);
+    const colWidth = (contentWidth - gutterMm) / 2;
+    const col1Left = bounds.left;
+    const col1Right = bounds.left + colWidth;
+    const col2Left = col1Right + gutterMm;
+    const col2Right = bounds.right;
+    const startY = core.getCursorY();
+
+    core._enterColumnBounds(col1Left, col1Right);
+    executeOperations({
+      core, theme,
+      operations: Array.isArray(operation.column1) ? operation.column1 : [],
+      indexPrefix: `${index}.col1.`,
+      templateMode, templateBypassMargins,
+    });
+    const col1EndY = core._exitColumnBounds(startY);
+
+    core._enterColumnBounds(col2Left, col2Right);
+    executeOperations({
+      core, theme,
+      operations: Array.isArray(operation.column2) ? operation.column2 : [],
+      indexPrefix: `${index}.col2.`,
+      templateMode, templateBypassMargins,
+    });
+    const col2EndY = core._exitColumnBounds(startY);
+
+    core.setCursorY(Math.max(col1EndY, col2EndY));
+    return;
+  }
+
   const plugin = getPlugin(operation.type);
   if (plugin) {
     const bounds = getHorizontalBounds(core, templateBypassMargins);
@@ -1120,6 +1162,35 @@ function estimateOperationHeight(ctx) {
     return margins.top + padding.top + imgHeightMm + captionHeight + padding.bottom + margins.bottom;
   }
 
+  if (operation.type === "columns") {
+    const contentWidth = core.pageWidth - core.marginLeftMm - core.marginRightMm;
+    const gutterMm = resolveColumnsGutter(operation, theme, index);
+    const colWidth = (contentWidth - gutterMm) / 2;
+
+    const savedMarginLeft = core.marginLeftMm;
+    const savedMarginRight = core.marginRightMm;
+
+    core.marginLeftMm = savedMarginLeft;
+    core.marginRightMm = core.pageWidth - (savedMarginLeft + colWidth);
+    const col1H = estimateOperationsHeight({
+      core, theme,
+      operations: Array.isArray(operation.column1) ? operation.column1 : [],
+      indexPrefix: `${index}.col1.`,
+    });
+
+    core.marginLeftMm = savedMarginLeft + colWidth + gutterMm;
+    core.marginRightMm = core.pageWidth - (savedMarginLeft + colWidth + gutterMm + colWidth);
+    const col2H = estimateOperationsHeight({
+      core, theme,
+      operations: Array.isArray(operation.column2) ? operation.column2 : [],
+      indexPrefix: `${index}.col2.`,
+    });
+
+    core.marginLeftMm = savedMarginLeft;
+    core.marginRightMm = savedMarginRight;
+    return Math.max(col1H, col2H);
+  }
+
   const plugin = getPlugin(operation.type);
   if (plugin) {
     if (typeof plugin.estimateHeight === "function") {
@@ -1172,6 +1243,20 @@ function applyPageTokens(value, core) {
   return String(value).replace(/\{\{page\}\}/g, String(page));
 }
 
+function resolveColumnsGutter(operation, theme, index) {
+  if (operation.gutterMm !== undefined) {
+    return Number(operation.gutterMm);
+  }
+  const themeGutter = (theme.layout || {}).columnGutterMm;
+  if (themeGutter !== undefined) {
+    return Number(themeGutter);
+  }
+  throw new Error(
+    `columns operation at index ${index} has no gutterMm. ` +
+    `Set gutterMm on the operation or columnGutterMm in theme.layout.`
+  );
+}
+
 function getHorizontalBounds(core, bypassMargins) {
   if (bypassMargins) {
     return { left: 0, right: core.pageWidth };

package/core/validate.js

@@ -2,7 +2,7 @@ const { hasPlugin } = require("./plugin-registry");
 
 const OPERATION_TYPES = new Set([
   "text", "row", "bullet", "divider", "spacer", "hiddenText",
-  "block", "group", "section", "quote", "table", "image",
+  "block", "group", "section", "quote", "table", "image", "columns",
 ]);
 
 function validateSource(source) {
@@ -108,6 +108,18 @@ function validateOperation(op, path) {
     return;
   }
 
+  if (type === "columns") {
+    if (!Array.isArray(op.column1)) {
+      throw new Error(`${path}: columns requires column1 array`);
+    }
+    if (!Array.isArray(op.column2)) {
+      throw new Error(`${path}: columns requires column2 array`);
+    }
+    op.column1.forEach((child, i) => validateOperation(child, `${path}.column1[${i}]`));
+    op.column2.forEach((child, i) => validateOperation(child, `${path}.column2[${i}]`));
+    return;
+  }
+
   if (hasPlugin(type)) {
     return;
   }
@@ -147,6 +159,8 @@ function collectLabels(node, missing, themeLabels) {
   if (Array.isArray(ops)) {
     ops.forEach((n) => collectLabels(n, missing, themeLabels));
   }
+  if (Array.isArray(node.column1)) node.column1.forEach((n) => collectLabels(n, missing, themeLabels));
+  if (Array.isArray(node.column2)) node.column2.forEach((n) => collectLabels(n, missing, themeLabels));
 
   if (node.label && !themeLabels.has(node.label)) missing.push(node.label);
   if (node.leftLabel && !themeLabels.has(node.leftLabel)) missing.push(node.leftLabel);