h17-sspdf 0.1.3 → 0.1.4

package/README.md

@@ -22,7 +22,7 @@ npm install h17-sspdf
 
 ## The problem it solves
 
-Generating PDFs imperatively means tracking the cursor yourself. Every element you place shifts everything below it. Line wrapping, page breaks, font resets — all manual.
+Generating PDFs imperatively means tracking the cursor yourself. Every element you place shifts everything below it. Line wrapping, page breaks, font resets, all manual.
 
 This engine inverts that. You describe *what* to render and *how it looks*. The cursor, the math, the page breaks happen automatically.
 
@@ -34,7 +34,7 @@ Every operation has a `type` and a `label`. The label maps to a style in the the
 operation → label → theme style → layout → cursor advance → next operation
 ```
 
-Page breaks happen automatically when content reaches the bottom margin. Style resets after every operation — nothing leaks.
+Page breaks happen automatically when content reaches the bottom margin. Style resets after every operation, nothing leaks.
 
 ## Quick start
 
@@ -203,7 +203,7 @@ A repeating pattern of `row` + `text` pairs. The row carries the label/value, th
 }
 ```
 
-`xMm` and `maxWidthMm` indent it from the body column — the indentation is in the source, not the theme.
+`xMm` and `maxWidthMm` indent it from the body column, the indentation is in the source, not the theme.
 
 #### Hidden text (ATS / search metadata)
 
@@ -273,8 +273,8 @@ Any operation accepts `xMm` and `maxWidthMm` to override the theme margins for t
 
 ### Page break control
 
-- `keepWithNext: N` — keep this operation on the same page as the next N operations
-- `block` with `keepTogether: true` — all children stay on the same page
+- `keepWithNext: N` - keep this operation on the same page as the next N operations
+- `block` with `keepTogether: true` - all children stay on the same page
 
 ---
 
@@ -344,10 +344,12 @@ Then use `fontFamily: 'Inter'` in any label.
 
 Renders any Chart.js configuration to a PNG and embeds it in the PDF.
 
-### Install peer dependencies
+### Requirements
+
+The chart plugin requires the `canvas` npm package (native C++ addon). Chart.js and chartjs-node-canvas are vendored and ship with the engine.
 
 ```bash
-npm install chart.js chartjs-node-canvas
+npm install canvas
 ```
 
 ### Register
@@ -385,7 +387,7 @@ registerPlugin('chart', plugins.chart);
 }
 ```
 
-`data` and `options` are passed directly to Chart.js — the plugin does not abstract the Chart.js API. `canvasWidth`/`canvasHeight` control render resolution (default 1600×800). `widthMm`/`heightMm` control the slot size in the PDF.
+`data` and `options` are passed directly to Chart.js, the plugin does not abstract the Chart.js API. `canvasWidth`/`canvasHeight` control render resolution (default 1600×800). `widthMm`/`heightMm` control the slot size in the PDF.
 
 ---
 
@@ -406,12 +408,20 @@ npx sspdf -s source.json -t theme.js -o output.pdf
 ## Constraints
 
 - A4 only
-- Single-line `row` cells — no multi-line column pairs
+- Single-line `row` cells, no multi-line column pairs
 - No `{{pages}}` total page count token
-- The `chart` plugin requires Node.js (`chartjs-node-canvas` is server-side only) — the core engine works in the browser if you use the jsPDF UMD build
+- The `canvas` npm package (native C++ addon) is the only runtime dependency, required for server-side chart rendering.
 
 ---
 
 Hugo Palma, 2026
 
-Built on [jsPDF](https://github.com/parallax/jsPDF).
+## Third-party
+
+This project vendors the following MIT-licensed libraries:
+
+- [jsPDF](https://github.com/parallax/jsPDF) - PDF generation. Copyright (c) 2010-2025 James Hall, yWorks GmbH.
+- [Chart.js](https://github.com/chartjs/Chart.js) - Chart rendering. Copyright (c) 2014-2024 Chart.js Contributors.
+- [chartjs-node-canvas](https://github.com/SeanSobey/ChartjsNodeCanvas) - Server-side Chart.js rendering. Copyright (c) 2018 Sean Sobey.
+
+Full license texts are in `vendor/*/LICENSE`.

package/cli.js

@@ -2,7 +2,7 @@
 
 const fs = require("fs");
 const path = require("path");
-const { renderDocument } = require("./core/render-document");
+const { renderDocument, registerPlugin, plugins } = require("./index");
 
 const EXAMPLES_THEMES_DIR = path.join(__dirname, "examples", "themes");
 
@@ -84,7 +84,7 @@ function readSource(sourcePath) {
 function printHelp() {
   const themes = listBuiltInThemes();
   console.log(`
-sspdf CLI — Render a source JSON + theme into a PDF.
+sspdf CLI - Render a source JSON + theme into a PDF.
 
 Usage:
   node cli.js --source <file.json> --theme <theme> --output <file.pdf>
@@ -105,7 +105,25 @@ Examples:
 `.trim());
 }
 
-function main() {
+function collectChartOps(obj) {
+  const charts = [];
+  if (!obj || typeof obj !== "object") return charts;
+  if (Array.isArray(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"]) {
+      if (Array.isArray(obj[key])) charts.push(...collectChartOps(obj[key]));
+    }
+    if (obj.pageTemplates) {
+      if (Array.isArray(obj.pageTemplates.header)) charts.push(...collectChartOps(obj.pageTemplates.header));
+      if (Array.isArray(obj.pageTemplates.footer)) charts.push(...collectChartOps(obj.pageTemplates.footer));
+    }
+  }
+  return charts;
+}
+
+async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.help) {
     printHelp();
@@ -121,15 +139,21 @@ function main() {
 
   fs.mkdirSync(path.dirname(outputPath), { recursive: true });
 
+  const chartOps = collectChartOps(source);
+  if (chartOps.length > 0) {
+    registerPlugin("chart", plugins.chart);
+    for (const op of chartOps) {
+      await plugins.chart.preRender(op);
+    }
+  }
+
   const result = renderDocument({ source, theme, outputPath });
 
   console.log(`[OK] ${result.operationsCount} operations rendered`);
   console.log(`[OK] ${outputPath}`);
 }
 
-try {
-  main();
-} catch (err) {
+main().catch((err) => {
   console.error(`[ERROR] ${err.message}`);
   process.exit(1);
-}
+});

package/core/pdf-core.js

@@ -1,8 +1,8 @@
 const fs = require("fs");
-const { jsPDF } = require("jspdf");
+const { jsPDF } = require("../vendor/jspdf/jspdf.node");
 const { pxToMm, ptToMm, resolveLineHeightMm } = require("./units");
 
-// Style math helpers — shared between core rendering and height estimation.
+// Style math helpers, shared between core rendering and height estimation.
 
 function getMarginTopMm(style) {
   if (style.marginTopMm !== undefined) {
@@ -130,7 +130,7 @@ class PDFCore {
       subject: meta.subject || "",
       author: meta.author || "Hugo Palma",
       keywords: meta.keywords || "",
-      creator: "SuperSimplePDF (github.com/hugopalma17/sspdf) — built on jsPDF",
+      creator: "SuperSimplePDF (github.com/hugopalma17/sspdf) - built on jsPDF",
     });
 
     this.paintBackground();
@@ -628,6 +628,213 @@ class PDFCore {
     return { y: drawY, endY };
   }
 
+  /**
+   * Draw a table with header row, data rows, per-edge borders, and alt row shading.
+   * All values derived from style properties, no hardcoded constants.
+   *
+   * @param {object} payload
+   * @param {Array<{widthMm: number, align: string}>} payload.columns  Resolved column definitions
+   * @param {string[]|null} payload.headers  Header cell texts, or null for no header row
+   * @param {string[][]} payload.rows  Data rows, each row is an array of cell strings
+   * @param {object} payload.cellStyle  Resolved style for data cells
+   * @param {object|null} payload.headerStyle  Resolved style for header cells
+   * @param {number} [payload.x]  Left edge of table
+   * @param {number} [payload.maxWidth]  Total table width
+   * @param {boolean} [payload.allowPageBreak]
+   * @returns {{ y: number, endY: number, rowCount: number }}
+   */
+  drawTable(payload) {
+    const columns = payload.columns;
+    const headers = payload.headers || null;
+    const rows = payload.rows || [];
+    const cellStyle = payload.cellStyle || {};
+    const headerStyle = payload.headerStyle || null;
+    const x = payload.x !== undefined ? payload.x : this.marginLeftMm;
+    const allowPageBreak = payload.allowPageBreak !== false;
+
+    const marginTopMm = getMarginTopMm(cellStyle);
+    const marginBottomMm = getMarginBottomMm(cellStyle);
+
+    const cellPad = Number(cellStyle.cellPaddingMm) || 0;
+    const headerPad = headerStyle
+      ? (Number(headerStyle.cellPaddingMm) || 0)
+      : cellPad;
+
+    // Column x positions
+    const colX = [];
+    let cx = x;
+    for (let c = 0; c < columns.length; c++) {
+      colX.push(cx);
+      cx += columns[c].widthMm;
+    }
+
+    // Margin before table
+    if (allowPageBreak) {
+      const firstRowHeight = headers
+        ? this._measureTableRowHeight(headers, columns, colX, headerStyle, headerPad)
+        : this._measureTableRowHeight(rows[0] || [], columns, colX, cellStyle, cellPad);
+      this.ensureSpace(marginTopMm + firstRowHeight);
+    }
+    const tableStartY = this.cursorY + marginTopMm;
+    this.cursorY = tableStartY;
+
+    // Draw header
+    if (headerStyle && headers) {
+      this._drawTableRow({
+        rowData: headers,
+        columns, colX,
+        style: headerStyle,
+        cellPadding: headerPad,
+        bgColor: this._resolveColor(headerStyle.backgroundColor),
+      });
+    }
+
+    // Draw data rows
+    for (let r = 0; r < rows.length; r++) {
+      const rowData = rows[r];
+      const rowHeight = this._measureTableRowHeight(rowData, columns, colX, cellStyle, cellPad);
+
+      // Page break check - re-draw header after break
+      if (allowPageBreak && this.cursorY + rowHeight > this.contentBottomY) {
+        this.addPage();
+        if (headerStyle && headers) {
+          this._drawTableRow({
+            rowData: headers,
+            columns, colX,
+            style: headerStyle,
+            cellPadding: headerPad,
+            bgColor: this._resolveColor(headerStyle.backgroundColor),
+          });
+        }
+      }
+
+      // Determine row background
+      const baseBg = this._resolveColor(cellStyle.backgroundColor);
+      const altBg = cellStyle.altRowColor && Array.isArray(cellStyle.altRowColor) && cellStyle.altRowColor.length === 3
+        ? cellStyle.altRowColor
+        : null;
+      const bgColor = (altBg && r % 2 === 1) ? altBg : baseBg;
+
+      this._drawTableRow({
+        rowData,
+        columns, colX,
+        style: cellStyle,
+        cellPadding: cellPad,
+        bgColor,
+      });
+    }
+
+    const endY = this.cursorY;
+    this.cursorY = endY + marginBottomMm;
+
+    this.lastDrawnBounds = {
+      topY: tableStartY,
+      bottomY: endY,
+      leftX: x,
+      rightX: colX.length > 0 ? colX[colX.length - 1] + columns[columns.length - 1].widthMm : x,
+    };
+
+    return { y: tableStartY, endY, rowCount: rows.length };
+  }
+
+  /**
+   * Measure the height of a single table row.
+   * @private
+   */
+  _measureTableRowHeight(rowData, columns, colX, style, cellPadding) {
+    const lineHeightMm = style.lineHeightMm || resolveLineHeightMm(Number(style.fontSize), style.lineHeight);
+    let maxLines = 1;
+    for (let c = 0; c < columns.length; c++) {
+      const innerWidth = columns[c].widthMm - (cellPadding * 2);
+      if (innerWidth <= 0) continue;
+      const text = String((rowData && rowData[c]) || "");
+      const lines = this.measureWrappedLines(text, innerWidth, style);
+      if (lines.length > maxLines) maxLines = lines.length;
+    }
+    return cellPadding + (maxLines * lineHeightMm) + cellPadding;
+  }
+
+  /**
+   * Draw a single table row (background, text, borders).
+   * @private
+   */
+  _drawTableRow(payload) {
+    const { rowData, columns, colX, style, cellPadding, bgColor } = payload;
+    const rowY = this.cursorY;
+    const lineHeightMm = style.lineHeightMm || resolveLineHeightMm(Number(style.fontSize), style.lineHeight);
+
+    // Measure row height
+    let maxLines = 1;
+    const cellLines = [];
+    for (let c = 0; c < columns.length; c++) {
+      const innerWidth = columns[c].widthMm - (cellPadding * 2);
+      const text = String((rowData && rowData[c]) || "");
+      const lines = innerWidth > 0 ? this.measureWrappedLines(text, innerWidth, style) : [text];
+      cellLines.push(lines);
+      if (lines.length > maxLines) maxLines = lines.length;
+    }
+    const rowHeight = cellPadding + (maxLines * lineHeightMm) + cellPadding;
+
+    // Draw cell backgrounds
+    if (bgColor) {
+      this.doc.setFillColor(...bgColor);
+      for (let c = 0; c < columns.length; c++) {
+        this.doc.rect(colX[c], rowY, columns[c].widthMm, rowHeight, "F");
+      }
+    }
+
+    // Draw cell text
+    this.applyTextStyle(style);
+    const baselineOffset = this._getBaselineOffsetMm(Number(style.fontSize));
+    this.doc.setLineHeightFactor(Number(style.lineHeight));
+    for (let c = 0; c < columns.length; c++) {
+      const innerWidth = columns[c].widthMm - (cellPadding * 2);
+      if (innerWidth <= 0) continue;
+      const textX = colX[c] + cellPadding;
+      const textY = rowY + cellPadding + baselineOffset;
+      const align = columns[c].align || "left";
+      this._drawTextLines(cellLines[c], {
+        x: textX,
+        y: textY,
+        maxWidth: innerWidth,
+        align,
+        lineHeightMm,
+      });
+    }
+
+    // Draw cell borders
+    for (let c = 0; c < columns.length; c++) {
+      this._drawTableCellBorders(style, colX[c], rowY, columns[c].widthMm, rowHeight);
+    }
+
+    this.applyDefaultRenderState();
+    this.cursorY = rowY + rowHeight;
+    return rowHeight;
+  }
+
+  /**
+   * Draw per-edge borders for a single table cell.
+   * @private
+   */
+  _drawTableCellBorders(style, cellX, cellY, cellWidth, cellHeight) {
+    const baseBorderColor = this._resolveColor(style.borderColor, [200, 200, 200]);
+    const edges = [
+      { widthProp: "borderTopMm",    colorProp: "borderTopColor",    x1: cellX, y1: cellY, x2: cellX + cellWidth, y2: cellY },
+      { widthProp: "borderBottomMm", colorProp: "borderBottomColor", x1: cellX, y1: cellY + cellHeight, x2: cellX + cellWidth, y2: cellY + cellHeight },
+      { widthProp: "borderLeftMm",   colorProp: "borderLeftColor",   x1: cellX, y1: cellY, x2: cellX, y2: cellY + cellHeight },
+      { widthProp: "borderRightMm",  colorProp: "borderRightColor",  x1: cellX + cellWidth, y1: cellY, x2: cellX + cellWidth, y2: cellY + cellHeight },
+    ];
+
+    for (const edge of edges) {
+      const width = Number(style[edge.widthProp]) || 0;
+      if (width <= 0) continue;
+      const color = this._resolveColor(style[edge.colorProp], baseBorderColor);
+      this.doc.setDrawColor(...color);
+      this.doc.setLineWidth(width);
+      this.doc.line(edge.x1, edge.y1, edge.x2, edge.y2);
+    }
+  }
+
   /**
    * Draw visually hidden text (ATS tags, keywords) without moving cursor.
    * @param {object} payload

package/core/plugin-chart.js

@@ -6,8 +6,8 @@
  * Renders any Chart.js configuration server-side via chartjs-node-canvas
  * and embeds the result as a PNG image in the PDF.
  *
- * Requires peer dependencies:
- *   npm install chart.js chartjs-node-canvas
+ * Requires the `canvas` npm package (native C++ addon):
+ *   npm install canvas
  *
  * Registration:
  *   const { registerPlugin, plugins } = require('h17-sspdf');
@@ -45,7 +45,7 @@
  * - canvasWidth/canvasHeight control render resolution (default 1600x800).
  *   Higher values = sharper chart. widthMm/heightMm control the PDF slot size.
  * - responsive: false and animation: false are injected automatically.
- * - Pass any valid Chart.js config in data and options — the plugin does not
+ * - Pass any valid Chart.js config in data and options, the plugin does not
  *   modify or abstract it.
  */
 
@@ -54,10 +54,10 @@ let _ChartJSNodeCanvas = null;
 function getCanvas() {
   if (!_ChartJSNodeCanvas) {
     try {
-      _ChartJSNodeCanvas = require('chartjs-node-canvas').ChartJSNodeCanvas;
+      _ChartJSNodeCanvas = require('../vendor/chartjs-node-canvas').ChartJSNodeCanvas;
     } catch {
       throw new Error(
-        'chart plugin requires chartjs-node-canvas — run: npm install chart.js chartjs-node-canvas'
+        'chart plugin requires the canvas package - run: npm install canvas'
       );
     }
   }
@@ -70,6 +70,32 @@ function getCanvas() {
  * @param {object} operation - the chart operation object (mutated in place)
  * @returns {Promise<void>}
  */
+/**
+ * Walk an options object and convert callback template strings like "{{v}}%"
+ * into real functions. This lets JSON sources define simple tick formatters
+ * without requiring executable code in the source file.
+ *
+ * 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)); };
+    } else {
+      obj[key] = resolveCallbackTemplates(obj[key]);
+    }
+  }
+  return obj;
+}
+
 async function preRender(operation) {
   const ChartJSNodeCanvas = getCanvas();
   const canvasW = operation.canvasWidth  || 1600;
@@ -81,14 +107,16 @@ async function preRender(operation) {
     backgroundColour: 'transparent',
   });
 
+  const options = resolveCallbackTemplates({
+    ...(operation.options || {}),
+    responsive: false,
+    animation:  false,
+  });
+
   operation._buf = await canvas.renderToBuffer({
     type:    operation.chartType || 'bar',
     data:    operation.data    || { labels: [], datasets: [] },
-    options: {
-      ...(operation.options || {}),
-      responsive: false,
-      animation:  false,
-    },
+    options,
   });
 }
 
@@ -100,7 +128,7 @@ module.exports = {
 
     if (!operation._buf) {
       throw new Error(
-        'chart plugin: operation._buf is missing — call plugin.preRender(operation) before renderDocument()'
+        'chart plugin: operation._buf is missing - call plugin.preRender(operation) before renderDocument()'
       );
     }
 
@@ -120,7 +148,7 @@ module.exports = {
       throw new Error('chart operation requires chartType (e.g. "bar", "line", "doughnut")');
     }
     if (!operation.data) {
-      throw new Error('chart operation requires data — pass a Chart.js data config object');
+      throw new Error('chart operation requires data - pass a Chart.js data config object');
     }
   },
 };

package/core/plugin-registry.js

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