node-pptx-templater 1.1.0 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-pptx-templater",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "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",
@@ -191,4 +191,4 @@
     "LICENSE",
     "CHANGELOG.md"
   ]
-}
+}

package/src/core/PPTXTemplater.js

@@ -2556,7 +2556,11 @@ class PPTXTemplater {
     this.#assertLoaded()
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
-      this.#shapeManager.updateShapePosition(idx, shapeId, options, this.#slideManager)
+      let resolvedOptions = options
+      if (options.alignToCell) {
+        resolvedOptions = this.#resolveAlignToCell(idx, options, shapeId, true)
+      }
+      this.#shapeManager.updateShapePosition(idx, shapeId, resolvedOptions, this.#slideManager)
     }
     return this
   }
@@ -2650,17 +2654,22 @@ class PPTXTemplater {
     return this.#shapeManager.validateShape(options)
   }
 
-  /**
-   * Adds a new shape dynamically to the targeted slide(s).
-   *
-   * @param {Object} options Shape configuration options.
-   * @returns {this} The chainable presentation templater instance.
-   */
-  async addShape(options) {
+  async addShape(typeOrOptions, options = {}) {
     this.#assertLoaded()
+    let resolvedOptions = {}
+    if (typeof typeOrOptions === 'string') {
+      resolvedOptions = { ...options, type: typeOrOptions }
+    } else {
+      resolvedOptions = { ...typeOrOptions }
+    }
+
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
-      this.#shapeManager.addShape(idx, options, this.#slideManager)
+      let finalOptions = resolvedOptions
+      if (resolvedOptions.alignToCell) {
+        finalOptions = this.#resolveAlignToCell(idx, resolvedOptions)
+      }
+      this.#shapeManager.addShape(idx, finalOptions, this.#slideManager)
     }
     return this
   }
@@ -2676,7 +2685,11 @@ class PPTXTemplater {
     this.#assertLoaded()
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
-      this.#shapeManager.updateShape(idx, shapeId, options, this.#slideManager)
+      let resolvedOptions = options
+      if (options.alignToCell) {
+        resolvedOptions = this.#resolveAlignToCell(idx, options, shapeId)
+      }
+      this.#shapeManager.updateShape(idx, shapeId, resolvedOptions, this.#slideManager)
     }
     return this
   }
@@ -2822,13 +2835,17 @@ class PPTXTemplater {
   /**
    * Retrieves final rendered bounds of a table cell in pixels.
    *
-   * @param {string} tableId - Table name or shape ID.
+   * @param {string|Object} tableIdOrObj - Table name, shape ID, or table object.
    * @param {number} rowIndex - 0-based row index.
    * @param {number} colIndex - 0-based column index.
    * @returns {Object|null} Cell bounds { x, y, width, height } in pixels, or null.
    */
-  getCellBounds(tableId, rowIndex, colIndex) {
+  getCellBounds(tableIdOrObj, rowIndex, colIndex) {
     this.#assertLoaded()
+    const tableId =
+      typeof tableIdOrObj === 'object'
+        ? tableIdOrObj.id || tableIdOrObj.name || tableIdOrObj.tableId
+        : tableIdOrObj
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
       try {
@@ -2851,14 +2868,21 @@ class PPTXTemplater {
 
   /**
    * Retrieves final rendered position of a table cell in pixels.
+   * Optionally calculates centered top-left coordinates for a shape of given dimensions.
    *
-   * @param {string} tableId - Table name or shape ID.
+   * @param {string|Object} tableIdOrObj - Table name, shape ID, or table object.
    * @param {number} rowIndex - 0-based row index.
    * @param {number} colIndex - 0-based column index.
-   * @returns {Object|null} Cell position { row, column, x, y } in pixels, or null.
+   * @param {number|Object} [shapeWidthOrOptions] - Width of the shape in pixels, or options object.
+   * @param {number} [shapeHeight] - Height of the shape in pixels.
+   * @returns {Object|null} Cell position { row, column, x, y, width, height } in pixels, or null.
    */
-  getCellPosition(tableId, rowIndex, colIndex) {
+  getCellPosition(tableIdOrObj, rowIndex, colIndex, shapeWidthOrOptions, shapeHeight) {
     this.#assertLoaded()
+    const tableId =
+      typeof tableIdOrObj === 'object'
+        ? tableIdOrObj.id || tableIdOrObj.name || tableIdOrObj.tableId
+        : tableIdOrObj
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
       try {
@@ -2867,7 +2891,9 @@ class PPTXTemplater {
           tableId,
           rowIndex,
           colIndex,
-          this.#slideManager
+          this.#slideManager,
+          shapeWidthOrOptions,
+          shapeHeight
         )
         if (pos) return pos
       } catch (err) {
@@ -3548,6 +3574,126 @@ class PPTXTemplater {
     this.#zOrderManager.normalizeZOrder(targetIdx, this.#slideManager)
     return this
   }
+
+  /**
+   * Aligns an existing shape to a table cell's position.
+   *
+   * @param {string} shapeId - Unique shape name/id in the template.
+   * @param {string|Object} tableIdOrObj - Table ID string, or table object.
+   * @param {number} rowIndex - 0-based row index.
+   * @param {number} colIndex - 0-based column index.
+   * @param {Object} [options] - Alignment options.
+   * @param {'left'|'center'|'right'} [options.horizontal='center'] - Horizontal alignment.
+   * @param {'top'|'middle'|'bottom'} [options.vertical='middle'] - Vertical alignment.
+   * @returns {this} The chainable presentation templater instance.
+   */
+  alignShapeToCell(shapeId, tableIdOrObj, rowIndex, colIndex, options = {}) {
+    const tableId =
+      typeof tableIdOrObj === 'object'
+        ? tableIdOrObj.id || tableIdOrObj.name || tableIdOrObj.tableId
+        : tableIdOrObj
+    this.updateShapePosition(shapeId, {
+      alignToCell: {
+        table: tableId,
+        row: rowIndex,
+        col: colIndex,
+        horizontal: options.horizontal || 'center',
+        vertical: options.vertical || 'middle',
+      },
+    })
+    return this
+  }
+
+  #resolveAlignToCell(slideIndex, options, shapeId, convertToEmus = false) {
+    const align = options.alignToCell
+    if (!align || !align.table) return options
+
+    const tableId =
+      typeof align.table === 'object'
+        ? align.table.id || align.table.name || align.table.tableId
+        : align.table
+    const row = align.row !== undefined ? align.row : 0
+    const col = align.col !== undefined ? align.col : 0
+
+    // Get cell bounds
+    const bounds = this.#tableManager.getCellBounds(
+      slideIndex,
+      tableId,
+      row,
+      col,
+      this.#slideManager
+    )
+
+    if (!bounds) return options
+
+    // Determine shape dimensions
+    let shapeWidth = options.width
+    let shapeHeight = options.height
+
+    if (convertToEmus) {
+      if (shapeWidth !== undefined) shapeWidth = Math.round(shapeWidth / 9525)
+      if (shapeHeight !== undefined) shapeHeight = Math.round(shapeHeight / 9525)
+    }
+
+    if (shapeWidth === undefined || shapeHeight === undefined) {
+      if (options.type === 'square' && options.size !== undefined) {
+        shapeWidth = options.size
+        shapeHeight = options.size
+      } else if (options.type === 'circle' && options.radius !== undefined) {
+        shapeWidth = options.radius * 2
+        shapeHeight = options.radius * 2
+      } else if (shapeId) {
+        // Try getting existing shape dimensions
+        const existing = this.#shapeManager.getShape(slideIndex, shapeId, this.#slideManager)
+        if (existing) {
+          shapeWidth = existing.width
+          shapeHeight = existing.height
+        }
+      }
+    }
+
+    // Default to fallback dimensions if still undefined
+    if (shapeWidth === undefined) shapeWidth = 100
+    if (shapeHeight === undefined) shapeHeight = 100
+
+    // Align horizontally
+    let horiz = align.horizontal || align.alignX || 'center'
+    horiz = String(horiz).toLowerCase()
+    if (horiz === 'middle') horiz = 'center'
+
+    let x = bounds.x
+    if (horiz === 'center') {
+      x = bounds.x + (bounds.width - shapeWidth) / 2
+    } else if (horiz === 'right') {
+      x = bounds.x + bounds.width - shapeWidth
+    }
+
+    // Align vertically
+    let vert = align.vertical || align.alignY || 'middle'
+    vert = String(vert).toLowerCase()
+    if (vert === 'center') vert = 'middle'
+
+    let y = bounds.y
+    if (vert === 'middle') {
+      y = bounds.y + (bounds.height - shapeHeight) / 2
+    } else if (vert === 'bottom') {
+      y = bounds.y + bounds.height - shapeHeight
+    }
+
+    const resolved = { ...options }
+    if (convertToEmus) {
+      resolved.x = Math.round(x * 9525)
+      resolved.y = Math.round(y * 9525)
+    } else {
+      resolved.x = Math.round(x)
+      resolved.y = Math.round(y)
+    }
+
+    // Remove alignToCell to prevent it polluting lower levels
+    delete resolved.alignToCell
+
+    return resolved
+  }
 }
 
 module.exports = { PPTXTemplater }

package/src/managers/TableManager.js

@@ -796,6 +796,8 @@ class TableManager {
   getCellBounds(slideIndex, tableId, rowIndex, colIndex, slideManager) {
     const { tblObj, frameObj } = this.#getTableContext(slideIndex, tableId, slideManager)
 
+    this.#calculateRowHeights(slideIndex, tableId, slideManager, tblObj)
+
     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
@@ -843,13 +845,50 @@ class TableManager {
     }
   }
 
-  getCellPosition(slideIndex, tableId, rowIndex, colIndex, slideManager) {
+  getCellPosition(
+    slideIndex,
+    tableId,
+    rowIndex,
+    colIndex,
+    slideManager,
+    shapeWidthOrOptions,
+    shapeHeight
+  ) {
     const bounds = this.getCellBounds(slideIndex, tableId, rowIndex, colIndex, slideManager)
+    if (!bounds) return null
+
+    let shapeWidth
+    let shapeHeightVal
+
+    if (shapeWidthOrOptions && typeof shapeWidthOrOptions === 'object') {
+      shapeWidth =
+        shapeWidthOrOptions.width !== undefined
+          ? shapeWidthOrOptions.width
+          : shapeWidthOrOptions.shapeWidth
+      shapeHeightVal =
+        shapeWidthOrOptions.height !== undefined
+          ? shapeWidthOrOptions.height
+          : shapeWidthOrOptions.shapeHeight
+    } else {
+      shapeWidth = shapeWidthOrOptions
+      shapeHeightVal = shapeHeight
+    }
+
+    let x = bounds.x
+    let y = bounds.y
+
+    if (shapeWidth !== undefined && shapeHeightVal !== undefined) {
+      x = Math.round(bounds.x + (bounds.width - shapeWidth) / 2)
+      y = Math.round(bounds.y + (bounds.height - shapeHeightVal) / 2)
+    }
+
     return {
       row: rowIndex,
       column: colIndex,
-      x: bounds.x,
-      y: bounds.y,
+      x,
+      y,
+      width: bounds.width,
+      height: bounds.height,
     }
   }
 
@@ -1352,8 +1391,17 @@ class TableManager {
     }
 
     // 2. Determine alignment settings
-    let alignX = config.alignX
-    let alignY = config.alignY
+    let alignX = config.alignX || config.horizontal
+    let alignY = config.alignY || config.vertical
+
+    if (alignX) {
+      alignX = String(alignX).toLowerCase()
+      if (alignX === 'middle') alignX = 'center'
+    }
+    if (alignY) {
+      alignY = String(alignY).toLowerCase()
+      if (alignY === 'center') alignY = 'middle'
+    }
 
     if (config.position) {
       switch (config.position) {
@@ -1444,7 +1492,13 @@ class TableManager {
 
       // 4. Boundary Constraints Validation/Enforcement
       if (shapeWidth > cellWidth_px) {
-        shapeLeft = cellLeft_px
+        if (alignX === 'center') {
+          shapeLeft = cellLeft_px + (cellWidth_px - shapeWidth) / 2
+        } else if (alignX === 'right') {
+          shapeLeft = cellLeft_px + cellWidth_px - shapeWidth
+        } else {
+          shapeLeft = cellLeft_px
+        }
       } else {
         shapeLeft = Math.max(
           cellLeft_px,
@@ -1453,7 +1507,13 @@ class TableManager {
       }
 
       if (shapeHeight > cellHeight_px) {
-        shapeTop = cellTop_px
+        if (alignY === 'middle') {
+          shapeTop = cellTop_px + (cellHeight_px - shapeHeight) / 2
+        } else if (alignY === 'bottom') {
+          shapeTop = cellTop_px + cellHeight_px - shapeHeight
+        } else {
+          shapeTop = cellTop_px
+        }
       } else {
         shapeTop = Math.max(
           cellTop_px,
@@ -1876,6 +1936,8 @@ class TableManager {
       slideManager
     )
 
+    this.#calculateRowHeights(slideIndex, tableId, slideManager, tblObj)
+
     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
@@ -1959,6 +2021,8 @@ class TableManager {
       slideManager
     )
 
+    this.#calculateRowHeights(slideIndex, tableId, slideManager, tblObj)
+
     const shapes = shapeManager.getShapes(slideIndex, slideManager)
     const prefix = `cellshape_${resolvedTableId}_${rowIndex}_${colIndex}_${shapeIndex}`
     const matchingShapes = shapes.filter(
@@ -2105,8 +2169,11 @@ class TableManager {
     const numRows = trsArr.length
     const numCols = colWidths.length
 
-    // Initialize rowHeights with original height or 0
-    const rowHeights = trsArr.map(row => parseInt(row['@_h'] || 0, 10))
+    // Initialize rowHeights with original height or a safe minimum floor of 228600 EMUs (~24px/pt)
+    const rowHeights = trsArr.map(row => {
+      const h = parseInt(row['@_h'] || 0, 10)
+      return Math.max(h, 228600)
+    })
 
     // Helper to get paragraph font size
     const getParagraphFontSize = p => {
@@ -2228,7 +2295,7 @@ class TableManager {
         }
 
         const totalCellHeight_emu = marT + marB + textHeight_emu
-        cellHeights[r][c] = totalCellHeight_emu
+        cellHeights[r][c] = Math.max(totalCellHeight_emu, 228600)
       }
     }