node-pptx-templater 1.1.2 → 1.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-pptx-templater",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "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,7 @@
     "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: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

@@ -2654,6 +2654,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 +2748,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 +2789,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 +2837,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 +2882,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 +2931,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 +2974,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) {

package/src/managers/TableManager.js

@@ -1302,10 +1302,10 @@ class TableManager {
   }
 
   #expandCellShape(config, cellBounds) {
-    const cellLeft_px = Math.round(cellBounds.left / 9525)
-    const cellTop_px = Math.round(cellBounds.top / 9525)
-    const cellWidth_px = Math.round(cellBounds.width / 9525)
-    const cellHeight_px = Math.round(cellBounds.height / 9525)
+    const cellLeft_px = cellBounds.x
+    const cellTop_px = cellBounds.y
+    const cellWidth_px = cellBounds.width
+    const cellHeight_px = cellBounds.height
 
     const parseLength = (val, maxVal) => {
       if (typeof val === 'string' && val.endsWith('%')) {
@@ -1743,7 +1743,7 @@ class TableManager {
     slideManager,
     shapeManager,
     tblObj,
-    frameObj
+    _frameObj
   ) {
     if (!cellShapes || !shapeManager) return
 
@@ -1761,62 +1761,16 @@ class TableManager {
       }
     }
 
-    const xfrm = frameObj['p:xfrm']
-    const tableX = xfrm?.['a:off']?.['@_x'] ? parseInt(xfrm['a:off']['@_x'], 10) : 0
-    const tableY = xfrm?.['a:off']?.['@_y'] ? parseInt(xfrm['a:off']['@_y'], 10) : 0
-
-    const gridCols = tblObj['a:tblGrid']?.['a:gridCol'] || []
-    const gridColsArr = Array.isArray(gridCols) ? gridCols : [gridCols]
-    const colWidths = gridColsArr.map(col => parseInt(col['@_w'] || 0, 10))
-
-    const trsArr = tblObj['a:tr'] || []
-    const rowHeights = trsArr.map(row => parseInt(row['@_h'] || 0, 10))
-
-    const getCellBounds = (r, c) => {
-      const parent = this.getMergeParent(slideIndex, tableId, r, c, slideManager)
-      const pr = parent.row
-      const pc = parent.col
-
-      let cellLeft = tableX
-      for (let idx = 0; idx < pc; idx++) {
-        cellLeft += colWidths[idx] || 0
-      }
-
-      let cellTop = tableY
-      for (let idx = 0; idx < pr; idx++) {
-        cellTop += rowHeights[idx] || 0
-      }
-
-      const parentCell = trsArr[pr]?.['a:tc']?.[pc]
-      const gridSpan = parentCell?.['@_gridSpan'] ? parseInt(parentCell['@_gridSpan'], 10) : 1
-      const rowSpan = parentCell?.['@_rowSpan'] ? parseInt(parentCell['@_rowSpan'], 10) : 1
-
-      let cellWidth = 0
-      for (let idx = 0; idx < gridSpan; idx++) {
-        cellWidth += colWidths[pc + idx] || 0
-      }
-
-      let cellHeight = 0
-      for (let idx = 0; idx < rowSpan; idx++) {
-        cellHeight += rowHeights[pr + idx] || 0
-      }
-
-      return {
-        left: cellLeft,
-        top: cellTop,
-        width: cellWidth,
-        height: cellHeight,
-      }
-    }
-
     const shapesToCreate = []
-    const headerNames = (trsArr[0]?.['a:tc'] || []).map(cell => this.#getCellText(cell).trim())
+    const headerNames = (tblObj['a:tr']?.[0]?.['a:tc'] || []).map(cell =>
+      this.#getCellText(cell).trim()
+    )
 
     for (let i = 0; i < rowsData.length; i++) {
       const rowData = rowsData[i]
       const finalRowIndex = isObjectRows ? i + 1 : i
 
-      const numCols = trsArr[finalRowIndex]?.['a:tc']?.length || 0
+      const numCols = tblObj['a:tr']?.[finalRowIndex]?.['a:tc']?.length || 0
       for (let j = 0; j < numCols; j++) {
         const headerName = headerNames[j]
         let shapeFn = null
@@ -1851,16 +1805,24 @@ class TableManager {
     shapesToCreate.sort((a, b) => (a.config.zIndex || 0) - (b.config.zIndex || 0))
 
     shapesToCreate.forEach(item => {
-      const bounds = getCellBounds(item.rowIndex, item.colIndex)
-      const expandedConfigs = this.#expandCellShape(item.config, bounds)
+      const bounds = this.getCellBounds(
+        slideIndex,
+        tableId,
+        item.rowIndex,
+        item.colIndex,
+        slideManager
+      )
+      if (bounds) {
+        const expandedConfigs = this.#expandCellShape(item.config, bounds)
 
-      expandedConfigs.forEach((expandedConfig, expIdx) => {
-        const finalShapeIndex =
-          expandedConfigs.length > 1 ? `${item.shapeIndex}_${expIdx}` : item.shapeIndex
-        expandedConfig.id = `cellshape_${resolvedTableId}_${item.rowIndex}_${item.colIndex}_${finalShapeIndex}`
+        expandedConfigs.forEach((expandedConfig, expIdx) => {
+          const finalShapeIndex =
+            expandedConfigs.length > 1 ? `${item.shapeIndex}_${expIdx}` : item.shapeIndex
+          expandedConfig.id = `cellshape_${resolvedTableId}_${item.rowIndex}_${item.colIndex}_${finalShapeIndex}`
 
-        shapeManager.addShape(slideIndex, expandedConfig, slideManager)
-      })
+          shapeManager.addShape(slideIndex, expandedConfig, slideManager)
+        })
+      }
     })
   }
 
@@ -1928,53 +1890,13 @@ class TableManager {
   }
 
   addCellShape(slideIndex, tableId, rowIndex, colIndex, options, slideManager, shapeManager) {
-    const { tblObj, frameObj, resolvedTableId } = this.#getTableContext(
-      slideIndex,
-      tableId,
-      slideManager
-    )
-
-    const xfrm = frameObj['p:xfrm']
-    const tableX = xfrm?.['a:off']?.['@_x'] ? parseInt(xfrm['a:off']['@_x'], 10) : 0
-    const tableY = xfrm?.['a:off']?.['@_y'] ? parseInt(xfrm['a:off']['@_y'], 10) : 0
-
-    const gridCols = tblObj['a:tblGrid']?.['a:gridCol'] || []
-    const gridColsArr = Array.isArray(gridCols) ? gridCols : [gridCols]
-    const colWidths = gridColsArr.map(col => parseInt(col['@_w'] || 0, 10))
-
-    const trsArr = tblObj['a:tr'] || []
-    const rowHeights = this.#calculateRowHeights(slideIndex, tableId, slideManager, tblObj, false)
-
-    const parent = this.getMergeParent(slideIndex, tableId, rowIndex, colIndex, slideManager)
-    const pr = parent.row
-    const pc = parent.col
-
-    let cellLeft = tableX
-    for (let idx = 0; idx < pc; idx++) {
-      cellLeft += colWidths[idx] || 0
-    }
-
-    let cellTop = tableY
-    for (let idx = 0; idx < pr; idx++) {
-      cellTop += rowHeights[idx] || 0
-    }
-
-    const parentCell = trsArr[pr]?.['a:tc']?.[pc]
-    const gridSpan = parentCell?.['@_gridSpan'] ? parseInt(parentCell['@_gridSpan'], 10) : 1
-    const rowSpan = parentCell?.['@_rowSpan'] ? parseInt(parentCell['@_rowSpan'], 10) : 1
-
-    let cellWidth = 0
-    for (let idx = 0; idx < gridSpan; idx++) {
-      cellWidth += colWidths[pc + idx] || 0
-    }
+    const { resolvedTableId } = this.#getTableContext(slideIndex, tableId, slideManager)
 
-    let cellHeight = 0
-    for (let idx = 0; idx < rowSpan; idx++) {
-      cellHeight += rowHeights[pr + idx] || 0
+    const bounds = this.getCellBounds(slideIndex, tableId, rowIndex, colIndex, slideManager)
+    if (!bounds) {
+      throw new PPTXError(`Could not calculate bounds for cell (${rowIndex}, ${colIndex})`)
     }
 
-    const bounds = { left: cellLeft, top: cellTop, width: cellWidth, height: cellHeight }
-
     const shapes = shapeManager.getShapes(slideIndex, slideManager)
     const prefix = `cellshape_${resolvedTableId}_${rowIndex}_${colIndex}_`
     let maxShapeIndex = -1
@@ -2011,11 +1933,7 @@ class TableManager {
     slideManager,
     shapeManager
   ) {
-    const { tblObj, frameObj, resolvedTableId } = this.#getTableContext(
-      slideIndex,
-      tableId,
-      slideManager
-    )
+    const { resolvedTableId } = this.#getTableContext(slideIndex, tableId, slideManager)
 
     const shapes = shapeManager.getShapes(slideIndex, slideManager)
     const prefix = `cellshape_${resolvedTableId}_${rowIndex}_${colIndex}_${shapeIndex}`
@@ -2031,47 +1949,11 @@ class TableManager {
       shapeManager.deleteShape(slideIndex, s.name, slideManager)
     }
 
-    const xfrm = frameObj['p:xfrm']
-    const tableX = xfrm?.['a:off']?.['@_x'] ? parseInt(xfrm['a:off']['@_x'], 10) : 0
-    const tableY = xfrm?.['a:off']?.['@_y'] ? parseInt(xfrm['a:off']['@_y'], 10) : 0
-
-    const gridCols = tblObj['a:tblGrid']?.['a:gridCol'] || []
-    const gridColsArr = Array.isArray(gridCols) ? gridCols : [gridCols]
-    const colWidths = gridColsArr.map(col => parseInt(col['@_w'] || 0, 10))
-
-    const trsArr = tblObj['a:tr'] || []
-    const rowHeights = this.#calculateRowHeights(slideIndex, tableId, slideManager, tblObj, false)
-
-    const parent = this.getMergeParent(slideIndex, tableId, rowIndex, colIndex, slideManager)
-    const pr = parent.row
-    const pc = parent.col
-
-    let cellLeft = tableX
-    for (let idx = 0; idx < pc; idx++) {
-      cellLeft += colWidths[idx] || 0
-    }
-
-    let cellTop = tableY
-    for (let idx = 0; idx < pr; idx++) {
-      cellTop += rowHeights[idx] || 0
-    }
-
-    const parentCell = trsArr[pr]?.['a:tc']?.[pc]
-    const gridSpan = parentCell?.['@_gridSpan'] ? parseInt(parentCell['@_gridSpan'], 10) : 1
-    const rowSpan = parentCell?.['@_rowSpan'] ? parseInt(parentCell['@_rowSpan'], 10) : 1
-
-    let cellWidth = 0
-    for (let idx = 0; idx < gridSpan; idx++) {
-      cellWidth += colWidths[pc + idx] || 0
-    }
-
-    let cellHeight = 0
-    for (let idx = 0; idx < rowSpan; idx++) {
-      cellHeight += rowHeights[pr + idx] || 0
+    const bounds = this.getCellBounds(slideIndex, tableId, rowIndex, colIndex, slideManager)
+    if (!bounds) {
+      throw new PPTXError(`Could not calculate bounds for cell (${rowIndex}, ${colIndex})`)
     }
 
-    const bounds = { left: cellLeft, top: cellTop, width: cellWidth, height: cellHeight }
-
     const expandedConfigs = this.#expandCellShape(options, bounds)
 
     expandedConfigs.forEach((expandedConfig, expIdx) => {

package/src/managers/ZipManager.js

@@ -646,7 +646,11 @@ class ZipManager {
           await fs.writeFile(targetPath, this.#dirtyBinaryFiles.get(relPath))
         } else {
           const srcPath = path.join(this.#folderRoot, relPath)
-          await fs.copy(srcPath, targetPath)
+          const resolvedSrc = path.resolve(srcPath)
+          const resolvedDest = path.resolve(targetPath)
+          if (resolvedSrc !== resolvedDest) {
+            await fs.copy(srcPath, targetPath)
+          }
         }
       }
     } else {