node-pptx-templater 1.1.2 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-pptx-templater",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "High-performance, low-level PowerPoint (PPTX) OpenXML template engine for Node.js. Dynamically replace text, insert images, update charts (with Excel workbook data caching), and merge table cells without PowerPoint corruption or Repair Mode prompts.",
   "main": "./src/index.js",
   "type": "commonjs",
@@ -37,6 +37,8 @@
     "example:table-extraction": "node examples/table-extraction.js",
     "example:nested-rows": "node examples/nested-table-rows.js",
     "example:xml-folder": "node examples/xml-folder-workflow.js",
+    "example:shape-cells": "node examples/shape-cells.js",
+    "example:all": "node scripts/run-examples-check.js",
     "prepublishOnly": "npm run lint && npm run test"
   },
   "keywords": [

package/src/core/OutputWriter.js

@@ -161,11 +161,11 @@ class OutputWriter {
           : e.compressionMethod === 0
             ? 'STORE'
             : `UNKNOWN(${e.compressionMethod})`
-      console.log(e.name)
-      console.log(`compressed: ${e.compressedSize}`)
-      console.log(`uncompressed: ${e.uncompressedSize}`)
-      console.log(`crc: ${e.crc32}`)
-      console.log(`method: ${methodStr}`)
+      logger.info(e.name)
+      logger.info(`compressed: ${e.compressedSize}`)
+      logger.info(`uncompressed: ${e.uncompressedSize}`)
+      logger.info(`crc: ${e.crc32}`)
+      logger.info(`method: ${methodStr}`)
     })
     logger.info('--- End of ZIP debug output ---')
   }

package/src/core/PPTXTemplater.js

@@ -1569,11 +1569,30 @@ class PPTXTemplater {
   }
 
   /**
-   * Appends one or more rows to a table. Supports flat arrays and nested arrays
-   * for rowspan-merged cells.
+   * Appends one or more rows to a table. Supports flat arrays, nested arrays
+   * for rowspan-merged cells, and **Shape Cell** configuration objects that insert
+   * a graphic indicator directly inside a cell.
+   *
+   * ### Shape Cell Object
+   * Instead of a string value you may pass an object with the following keys:
+   *
+   * | Key | Type | Default | Description |
+   * |-----|------|---------|-------------|
+   * | `type` | `string` | **required** | Shape preset: `'circle'`, `'square'`, `'rectangle'`, `'triangle'`, `'diamond'`, `'hexagon'`, `'line'`. |
+   * | `text` | `string` | `''` | Optional label rendered next to the shape. |
+   * | `color` | `string` | `'#4CAF50'` | Fill colour of the shape (hex). |
+   * | `width` | `number` | `14` | Shape width in points. |
+   * | `height` | `number` | `14` | Shape height in points. |
+   * | `position` | `string` | `'center'` | Alignment inside the cell: `'center'`, `'left'`, `'right'`, `'top'`, `'bottom'`, `'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'`. |
+   * | `offsetX` | `number` | `0` | Additional horizontal offset from the resolved anchor (pt). |
+   * | `offsetY` | `number` | `0` | Additional vertical offset from the resolved anchor (pt). |
+   *
+   * The shape is added as a floating overlay anchored to the cell; the table
+   * dimensions (row heights, column widths) are **never mutated**.
    *
    * @param {string} tableId - Table name or shape ID.
-   * @param {Array<string|Array<string>>} rowData - Row data. Nested arrays create rowspan cells.
+   * @param {Array<string|Array<string>|Object>} rowData - Row data. Each element may be
+   *   a plain string, a nested array (rowspan), or a Shape Cell configuration object.
    * @param {Object} [options] - Row insertion options.
    * @param {'rowspan'|'auto'|'none'} [options.mergeStrategy='rowspan'] - How to handle nested arrays.
    *   `'rowspan'` creates OpenXML vertical spans, `'auto'` merges identical adjacent values,
@@ -1586,12 +1605,33 @@ class PPTXTemplater {
    *
    * // Nested row with rowspan
    * ppt.addTableRow('SalesTable', ['Region', ['Q1', 'Q2'], '$5K'], { mergeStrategy: 'rowspan' });
+   *
+   * // KPI indicator – green circle placed in the cell centre, no label
+   * await ppt.addTableRow('StatusTable', [
+   *   'Alice',
+   *   'Engineering',
+   *   { type: 'circle', color: '#4CAF50', width: 12, height: 12, position: 'center' },
+   * ]);
+   *
+   * // Status badge – shape with accompanying text label, aligned to the left
+   * await ppt.addTableRow('StatusTable', [
+   *   'Bob',
+   *   'Design',
+   *   { type: 'circle', color: '#F44336', text: 'Blocked', position: 'left' },
+   * ]);
    */
   addTableRow(tableId, rowData, options = {}) {
     this.#assertLoaded()
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
-      this.#tableManager.addTableRow(idx, tableId, rowData, this.#slideManager, options)
+      this.#tableManager.addTableRow(
+        idx,
+        tableId,
+        rowData,
+        this.#slideManager,
+        this.#shapeManager,
+        options
+      )
     }
     return this
   }
@@ -1610,7 +1650,13 @@ class PPTXTemplater {
     this.#assertLoaded()
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
-      this.#tableManager.removeTableRow(idx, tableId, rowIndex, this.#slideManager)
+      this.#tableManager.removeTableRow(
+        idx,
+        tableId,
+        rowIndex,
+        this.#slideManager,
+        this.#shapeManager
+      )
     }
     return this
   }
@@ -1630,7 +1676,14 @@ class PPTXTemplater {
     this.#assertLoaded()
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
-      this.#tableManager.insertTableRow(idx, tableId, rowIndex, rowData, this.#slideManager)
+      this.#tableManager.insertTableRow(
+        idx,
+        tableId,
+        rowIndex,
+        rowData,
+        this.#slideManager,
+        this.#shapeManager
+      )
     }
     return this
   }
@@ -1655,7 +1708,8 @@ class PPTXTemplater {
         tableId,
         sourceRowIndex,
         targetRowIndex,
-        this.#slideManager
+        this.#slideManager,
+        this.#shapeManager
       )
     }
     return this
@@ -1735,7 +1789,16 @@ class PPTXTemplater {
     }
 
     for (const idx of targetIndices) {
-      this.#tableManager.mergeCells(idx, tableId, sRow, sCol, eRow, eCol, this.#slideManager)
+      this.#tableManager.mergeCells(
+        idx,
+        tableId,
+        sRow,
+        sCol,
+        eRow,
+        eCol,
+        this.#slideManager,
+        this.#shapeManager
+      )
     }
     return this
   }
@@ -1786,9 +1849,25 @@ class PPTXTemplater {
 
     for (const idx of targetIndices) {
       if (isCellCoord) {
-        this.#tableManager.unmergeCells(idx, tableId, cellRow, cellCol, this.#slideManager)
+        this.#tableManager.unmergeCells(
+          idx,
+          tableId,
+          cellRow,
+          cellCol,
+          this.#slideManager,
+          this.#shapeManager
+        )
       } else {
-        this.#tableManager.unmergeCells(idx, tableId, sRow, sCol, eRow, eCol, this.#slideManager)
+        this.#tableManager.unmergeCells(
+          idx,
+          tableId,
+          sRow,
+          sCol,
+          eRow,
+          eCol,
+          this.#slideManager,
+          this.#shapeManager
+        )
       }
     }
     return this
@@ -2654,6 +2733,16 @@ class PPTXTemplater {
     return this.#shapeManager.validateShape(options)
   }
 
+  /**
+   * Adds a new shape to the targeted slide(s).
+   *
+   * @param {string|Object} typeOrOptions Either the shape type string (e.g., 'rect', 'ellipse') or a full options object.
+   * @param {Object} [options={}] Additional configuration options if type was specified as a string.
+   * @returns {Promise<PPTXTemplater>} The templater instance for chaining.
+   *
+   * @example
+   * await ppt.addShape('rect', { id: 'MyShape', x: 100, y: 100, width: 200, height: 100 });
+   */
   async addShape(typeOrOptions, options = {}) {
     this.#assertLoaded()
     let resolvedOptions = {}
@@ -2738,14 +2827,28 @@ class PPTXTemplater {
    */
   async addCellShape(tableId, rowIndex, colIndex, options) {
     this.#assertLoaded()
+    let row = rowIndex
+    let col = colIndex
+    let opts = options
+    if (rowIndex && typeof rowIndex === 'object') {
+      row = rowIndex.row !== undefined ? rowIndex.row : rowIndex.rowIndex
+      col =
+        rowIndex.column !== undefined
+          ? rowIndex.column
+          : rowIndex.col !== undefined
+            ? rowIndex.col
+            : rowIndex.colIndex
+      opts = rowIndex
+    }
+
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
       this.#tableManager.addCellShape(
         idx,
         tableId,
-        rowIndex,
-        colIndex,
-        options,
+        row,
+        col,
+        opts,
         this.#slideManager,
         this.#shapeManager
       )
@@ -2765,15 +2868,36 @@ class PPTXTemplater {
    */
   async updateCellShape(tableId, rowIndex, colIndex, shapeIndex, options) {
     this.#assertLoaded()
+    let row = rowIndex
+    let col = colIndex
+    let shpIdx = shapeIndex
+    let opts = options
+    if (rowIndex && typeof rowIndex === 'object') {
+      row = rowIndex.row !== undefined ? rowIndex.row : rowIndex.rowIndex
+      col =
+        rowIndex.column !== undefined
+          ? rowIndex.column
+          : rowIndex.col !== undefined
+            ? rowIndex.col
+            : rowIndex.colIndex
+      shpIdx =
+        rowIndex.shapeIndex !== undefined
+          ? rowIndex.shapeIndex
+          : rowIndex.shape !== undefined
+            ? rowIndex.shape
+            : colIndex
+      opts = options !== undefined ? options : rowIndex
+    }
+
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
       this.#tableManager.updateCellShape(
         idx,
         tableId,
-        rowIndex,
-        colIndex,
-        shapeIndex,
-        options,
+        row,
+        col,
+        shpIdx,
+        opts,
         this.#slideManager,
         this.#shapeManager
       )
@@ -2792,14 +2916,33 @@ class PPTXTemplater {
    */
   async removeCellShape(tableId, rowIndex, colIndex, shapeIndex) {
     this.#assertLoaded()
+    let row = rowIndex
+    let col = colIndex
+    let shpIdx = shapeIndex
+    if (rowIndex && typeof rowIndex === 'object') {
+      row = rowIndex.row !== undefined ? rowIndex.row : rowIndex.rowIndex
+      col =
+        rowIndex.column !== undefined
+          ? rowIndex.column
+          : rowIndex.col !== undefined
+            ? rowIndex.col
+            : rowIndex.colIndex
+      shpIdx =
+        rowIndex.shapeIndex !== undefined
+          ? rowIndex.shapeIndex
+          : rowIndex.shape !== undefined
+            ? rowIndex.shape
+            : colIndex
+    }
+
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
       this.#tableManager.removeCellShape(
         idx,
         tableId,
-        rowIndex,
-        colIndex,
-        shapeIndex,
+        row,
+        col,
+        shpIdx,
         this.#slideManager,
         this.#shapeManager
       )
@@ -2818,14 +2961,33 @@ class PPTXTemplater {
    */
   getCellShape(tableId, rowIndex, colIndex, shapeIndex) {
     this.#assertLoaded()
+    let row = rowIndex
+    let col = colIndex
+    let shpIdx = shapeIndex
+    if (rowIndex && typeof rowIndex === 'object') {
+      row = rowIndex.row !== undefined ? rowIndex.row : rowIndex.rowIndex
+      col =
+        rowIndex.column !== undefined
+          ? rowIndex.column
+          : rowIndex.col !== undefined
+            ? rowIndex.col
+            : rowIndex.colIndex
+      shpIdx =
+        rowIndex.shapeIndex !== undefined
+          ? rowIndex.shapeIndex
+          : rowIndex.shape !== undefined
+            ? rowIndex.shape
+            : colIndex
+    }
+
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
       const shape = this.#tableManager.getCellShape(
         idx,
         tableId,
-        rowIndex,
-        colIndex,
-        shapeIndex,
+        row,
+        col,
+        shpIdx,
         this.#slideManager,
         this.#shapeManager
       )
@@ -2848,16 +3010,22 @@ class PPTXTemplater {
       typeof tableIdOrObj === 'object'
         ? tableIdOrObj.id || tableIdOrObj.name || tableIdOrObj.tableId
         : tableIdOrObj
+    let row = rowIndex
+    let col = colIndex
+    if (rowIndex && typeof rowIndex === 'object') {
+      row = rowIndex.row !== undefined ? rowIndex.row : rowIndex.rowIndex
+      col =
+        rowIndex.column !== undefined
+          ? rowIndex.column
+          : rowIndex.col !== undefined
+            ? rowIndex.col
+            : rowIndex.colIndex
+    }
+
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
       try {
-        const bounds = this.#tableManager.getCellBounds(
-          idx,
-          tableId,
-          rowIndex,
-          colIndex,
-          this.#slideManager
-        )
+        const bounds = this.#tableManager.getCellBounds(idx, tableId, row, col, this.#slideManager)
         if (bounds) return bounds
       } catch (err) {
         logger.debug(
@@ -2885,17 +3053,33 @@ class PPTXTemplater {
       typeof tableIdOrObj === 'object'
         ? tableIdOrObj.id || tableIdOrObj.name || tableIdOrObj.tableId
         : tableIdOrObj
+    let row = rowIndex
+    let col = colIndex
+    let widthOrOpts = shapeWidthOrOptions
+    let height = shapeHeight
+    if (rowIndex && typeof rowIndex === 'object') {
+      row = rowIndex.row !== undefined ? rowIndex.row : rowIndex.rowIndex
+      col =
+        rowIndex.column !== undefined
+          ? rowIndex.column
+          : rowIndex.col !== undefined
+            ? rowIndex.col
+            : rowIndex.colIndex
+      widthOrOpts = colIndex
+      height = shapeWidthOrOptions
+    }
+
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
       try {
         const pos = this.#tableManager.getCellPosition(
           idx,
           tableId,
-          rowIndex,
-          colIndex,
+          row,
+          col,
           this.#slideManager,
-          shapeWidthOrOptions,
-          shapeHeight
+          widthOrOpts,
+          height
         )
         if (pos) return pos
       } catch (err) {