h17-sspdf 1.0.2 → 1.1.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

@@ -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
 

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/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);

package/examples/sources/source-two-column.json

@@ -0,0 +1,68 @@
+{
+  "operations": [
+    { "type": "text", "label": "demo.title", "text": "Service Plan Comparison" },
+    { "type": "text", "label": "demo.subtitle", "text": "Choose the plan that fits your team. Both plans include SLA, onboarding, and 24/7 support." },
+    { "type": "divider", "label": "demo.rule" },
+
+    {
+      "type": "columns",
+      "column1": [
+        { "type": "text", "label": "demo.col.heading", "text": "Starter" },
+        { "type": "text", "label": "demo.col.tagline", "text": "For small teams getting started with automation" },
+        { "type": "text", "label": "demo.col.price", "text": "$49 / mo" },
+        { "type": "text", "label": "demo.col.price.note", "text": "Per workspace, billed monthly" },
+        { "type": "divider", "label": "demo.rule.soft" },
+        {
+          "type": "table",
+          "label": "demo.table.cell",
+          "headerLabel": "demo.table.header",
+          "columns": [
+            { "header": "Feature", "width": "72%", "align": "left" },
+            { "header": "Included", "width": "28%", "align": "center" }
+          ],
+          "rows": [
+            ["Users",               "Up to 5"],
+            ["Projects",            "10"],
+            ["Storage",             "20 GB"],
+            ["API calls / day",     "5,000"],
+            ["Custom integrations", "—"],
+            ["SSO / SAML",          "—"],
+            ["Audit log",           "—"],
+            ["Priority support",    "—"],
+            ["SLA uptime",          "99.5%"]
+          ]
+        }
+      ],
+      "column2": [
+        { "type": "text", "label": "demo.col.heading", "text": "Professional" },
+        { "type": "text", "label": "demo.col.tagline", "text": "For growing teams that need scale and compliance" },
+        { "type": "text", "label": "demo.col.price", "text": "$149 / mo" },
+        { "type": "text", "label": "demo.col.price.note", "text": "Per workspace, billed monthly" },
+        { "type": "divider", "label": "demo.rule.soft" },
+        {
+          "type": "table",
+          "label": "demo.table.cell",
+          "headerLabel": "demo.table.header",
+          "columns": [
+            { "header": "Feature", "width": "72%", "align": "left" },
+            { "header": "Included", "width": "28%", "align": "center" }
+          ],
+          "rows": [
+            ["Users",               "Unlimited"],
+            ["Projects",            "Unlimited"],
+            ["Storage",             "500 GB"],
+            ["API calls / day",     "100,000"],
+            ["Custom integrations", "Yes"],
+            ["SSO / SAML",          "Yes"],
+            ["Audit log",           "90 days"],
+            ["Priority support",    "Yes"],
+            ["SLA uptime",          "99.9%"]
+          ]
+        }
+      ]
+    },
+
+    { "type": "text", "label": "demo.footer.note", "text": "Prices shown in USD. Annual billing saves 20%. All plans include a 14-day free trial with no credit card required." },
+    { "type": "text", "label": "demo.footer.cta", "text": "Contact sales@example.com to discuss enterprise pricing or volume discounts." }
+  ]
+}

package/examples/themes/theme-two-column.js

@@ -0,0 +1,105 @@
+const table = require("./table");
+
+const BLACK  = [15, 15, 15];
+const MUTED  = [100, 100, 100];
+const WHITE  = [255, 255, 255];
+const LIGHT  = [245, 245, 245];
+const RULE   = [210, 210, 210];
+const ACCENT = [30, 90, 180];
+
+module.exports = {
+  name: "Two-Column Demo",
+
+  page: {
+    format: "a4",
+    orientation: "portrait",
+    unit: "mm",
+    compress: true,
+    marginTopMm: 14,
+    marginBottomMm: 14,
+    marginLeftMm: 14,
+    marginRightMm: 14,
+    backgroundColor: WHITE,
+    defaultText: {
+      fontFamily: "helvetica",
+      fontStyle: "normal",
+      fontSize: 9,
+      color: BLACK,
+      lineHeight: 1.4,
+    },
+    defaultStroke: {
+      color: RULE,
+      lineWidth: 0.2,
+      lineCap: "butt",
+      lineJoin: "miter",
+    },
+    defaultFillColor: WHITE,
+    metadata: {
+      title: "Service Plan Comparison",
+      subject: "sspdf two-column layout demo",
+    },
+  },
+
+  layout: {
+    columnGutterMm: 6,
+  },
+
+  labels: {
+    "demo.title": {
+      fontFamily: "helvetica", fontStyle: "bold", fontSize: 18, color: BLACK,
+      lineHeight: 1.1, marginBottomMm: 1,
+    },
+    "demo.subtitle": {
+      fontFamily: "helvetica", fontStyle: "normal", fontSize: 10, color: MUTED,
+      lineHeight: 1.3, marginBottomMm: 5,
+    },
+    "demo.rule": {
+      color: ACCENT, lineWidth: 0.6, marginBottomMm: 5,
+    },
+    "demo.rule.soft": {
+      color: RULE, lineWidth: 0.2, marginTopMm: 3, marginBottomMm: 3,
+    },
+
+    "demo.col.heading": {
+      fontFamily: "helvetica", fontStyle: "bold", fontSize: 11, color: ACCENT,
+      lineHeight: 1.15, marginBottomMm: 2,
+    },
+    "demo.col.tagline": {
+      fontFamily: "helvetica", fontStyle: "normal", fontSize: 8, color: MUTED,
+      lineHeight: 1.3, marginBottomMm: 3,
+    },
+    "demo.col.price": {
+      fontFamily: "helvetica", fontStyle: "bold", fontSize: 20, color: BLACK,
+      lineHeight: 1.1, marginBottomMm: 1,
+    },
+    "demo.col.price.note": {
+      fontFamily: "helvetica", fontStyle: "normal", fontSize: 7, color: MUTED,
+      lineHeight: 1.2, marginBottomMm: 3,
+    },
+
+    "demo.table.cell": {
+      ...table.cell,
+      fontFamily: "helvetica", fontStyle: "normal", fontSize: 8, color: BLACK,
+      lineHeight: 1.3, cellPaddingMm: 1.2,
+      backgroundColor: WHITE, altRowColor: LIGHT,
+      borderColor: RULE,
+      borderTopMm: 0, borderBottomMm: 0.15, borderLeftMm: 0, borderRightMm: 0,
+    },
+    "demo.table.header": {
+      ...table.header,
+      fontFamily: "helvetica", fontStyle: "bold", fontSize: 8, color: WHITE,
+      lineHeight: 1.3, cellPaddingMm: 1.2,
+      backgroundColor: ACCENT, borderColor: ACCENT,
+      borderTopMm: 0, borderBottomMm: 0, borderLeftMm: 0, borderRightMm: 0,
+    },
+
+    "demo.footer.note": {
+      fontFamily: "helvetica", fontStyle: "normal", fontSize: 7.5, color: MUTED,
+      lineHeight: 1.4, marginTopMm: 4, align: "center",
+    },
+    "demo.footer.cta": {
+      fontFamily: "helvetica", fontStyle: "bold", fontSize: 9, color: ACCENT,
+      lineHeight: 1.3, align: "center",
+    },
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h17-sspdf",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Declarative PDF engine - define layout once, feed it JSON, get consistent PDFs",
   "main": "index.js",
   "author": "Hugo Palma",