node-pptx-templater 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.3] - 2026-06-22
+
+### Fixed
+
+- **Layout Preservation in `addCellShape()`**: Fixed a critical layout bug where querying cell bounds or adding cell shapes dynamically (via `addCellShape()` or `updateCellShape()`) mutated table row heights inside the XML. The sizing/positioning logic now runs in a layout-only mode, keeping the table XML completely untouched and respecting original template custom row heights.
+
+## [1.1.2] - 2026-06-22
+
+### Fixed
+
+- **Slide Link Relationships Target Paths**: Fixed PowerPoint "Repair Mode" errors when adding slide-to-slide hyperlinks (via `addSlideLink` or `addImageLink`). The relative target path resolves correctly to the sibling filename `slideX.xml` instead of using the redundant parent prefix `../slides/slideX.xml` (which exited and re-entered the same directory, violating PowerPoint's relative path resolution rules).
+
+### Added
+
+- **Redundant Traversal Validation**: Added automated check in `ValidationEngine` to identify and error on redundant relative path traversals inside relationship files (e.g. referencing `../slides/slideX.xml` from a source slide file already located in `ppt/slides/`).
+
 ## [1.1.0] - 2026-06-12
 
 ### Added

package/README.md

@@ -172,27 +172,51 @@ const meta = await ppt.getTableRows('SalesTable', { includeMetadata: true });
 ```
 
 ### Table Cell Shapes
-Cell shapes are overlay graphics anchored within table cells. They are positioned absolutely based on cell bounds, and **never** modify row heights, column widths, cell margins, or trigger table reflow. Offsets (`x`, `y`) are relative to the cell's top-left corner. Oversized shapes are scaled down proportionally to fit inside the cell.
+Cell shapes are overlay graphics anchored within table cells. They are positioned absolutely based on cell bounds, and **never** modify row heights, column widths, cell margins, or trigger table reflow.
+
+#### Merged Cell Support
+When targeting a merged cell (spanned using `rowSpan` or `colSpan`), `addCellShape()` dynamically resolves the **actual rendered bounds** of the entire merged cell region (summing the width and height of the spanned rows/columns). The shape is positioned and aligned relative to this final merged boundary. Any offset `x` and `y` specified is interpreted relative to the top-left corner of the resolved merged cell region.
+
+#### Alignment & Presets
+Shapes can be aligned dynamically within the cell (or merged region) using preset positions or explicit alignments:
+* **Presets**: Use `position` values like `'top-left'`, `'center'`, `'bottom-right'`, etc.
+* **Alignment Options**: Set `alignX: 'left' | 'center' | 'right'` and `alignY: 'top' | 'middle' | 'bottom'`. If no alignments or offsets are provided, shapes default to true centering (`'center'`/`'middle'`).
+* **Offsets & Padding**: Offsets (`x`, `y`) are applied relative to the resolved alignment. For instance, when `alignX: 'right'` is used, the shape is placed at `cellRight - shapeWidth - x` (defaulting to a `5px` padding if `x` is omitted).
 
 ```javascript
-// Add a simple indicator
-await ppt.addCellShape('SalesTable', 2, 1, {
+// Add a status icon centered in a merged cell (rowSpan=2, colSpan=2)
+await ppt.addCellShape('StatusTable', 1, 1, {
   type: 'circle',
   width: 12,
   height: 12,
-  fill: '#10B981' // Green status dot
+  fill: '#10B981', // Green status dot
+  alignX: 'center',
+  alignY: 'middle' // Visually centered in the merged cell
 });
 
-// Add a badge with text and custom offsets
-await ppt.addCellShape('SalesTable', 1, 2, {
+// Add a badge with text and explicit offsets inside a merged cell
+await ppt.addCellShape('StatusTable', 1, 1, {
   type: 'badge',
-  text: 'Active',
-  fill: '#3B82F6',
-  x: 4,
-  y: 2,
+  text: 'Urgent',
+  fill: '#EF4444',
+  alignX: 'left',
+  alignY: 'top',
+  x: 5,
+  y: 3,
   width: 50,
   height: 16
 });
+
+// Add an indicator with bottom-right alignment and custom padding
+await ppt.addCellShape('StatusTable', 1, 1, {
+  type: 'icon',
+  icon: 'up',
+  size: 14,
+  alignX: 'right',
+  alignY: 'bottom',
+  x: 4,
+  y: 2
+});
 ```
 
 ### XML Folder Workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-pptx-templater",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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
   }
@@ -2714,6 +2727,8 @@ class PPTXTemplater {
 
   /**
    * Dynamically adds a shape inside a table cell based on cell coordinates.
+   * Cell shapes are overlay graphics anchored independently of the table layout,
+   * and adding a cell shape never modifies row heights, column widths, or table dimensions.
    *
    * @param {string} tableId - Table name or shape ID.
    * @param {number} rowIndex - 0-based row index.
@@ -2822,13 +2837,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 +2870,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 +2893,9 @@ class PPTXTemplater {
           tableId,
           rowIndex,
           colIndex,
-          this.#slideManager
+          this.#slideManager,
+          shapeWidthOrOptions,
+          shapeHeight
         )
         if (pos) return pos
       } catch (err) {
@@ -3548,6 +3576,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/core/ValidationEngine.js

@@ -237,6 +237,18 @@ class ValidationEngine {
         if (!ppt.zipManager.hasFile(resolved)) {
           errors.push(`Relationship ${rel.id} points to non-existent file: ${resolved}`)
         }
+
+        // Catch redundant relative path traversals (e.g., '../slides/slide1.xml' from 'ppt/slides/slide2.xml')
+        const sourceDir = partPath.split('/').slice(0, -1).join('/')
+        const resolvedDir = resolved.split('/').slice(0, -1).join('/')
+        if (sourceDir === resolvedDir) {
+          const expectedTarget = resolved.split('/').pop()
+          if (rel.target !== expectedTarget) {
+            errors.push(
+              `Relationship "${rel.id}" in ${relsPath} uses redundant relative target "${rel.target}" (expected "${expectedTarget}")`
+            )
+          }
+        }
       }
     }
 

package/src/managers/HyperlinkManager.js

@@ -100,7 +100,7 @@ class HyperlinkManager {
     const targetInfo = slideManager.getSlideInfo(targetSlideIndex)
 
     // Build relative target path from source to target slide
-    const relativePath = `../slides/${targetInfo.zipPath.split('/').pop()}`
+    const relativePath = targetInfo.zipPath.split('/').pop()
 
     // Add relationship pointing to the target slide
     const rId = relationshipManager.addRelationship(
@@ -130,7 +130,7 @@ class HyperlinkManager {
     const sourceInfo = slideManager.getSlideInfo(sourceSlideIndex)
     const targetInfo = slideManager.getSlideInfo(targetSlideIndex)
 
-    const relativePath = `../slides/${targetInfo.zipPath.split('/').pop()}`
+    const relativePath = targetInfo.zipPath.split('/').pop()
     const rId = relationshipManager.addRelationship(
       sourceInfo.zipPath,
       REL_TYPES.SLIDE,
@@ -167,7 +167,7 @@ class HyperlinkManager {
     const sourceInfo = slideManager.getSlideInfo(sourceSlideIndex)
     const targetInfo = slideManager.getSlideInfo(targetSlideIndex)
 
-    const relativePath = `../slides/${targetInfo.zipPath.split('/').pop()}`
+    const relativePath = targetInfo.zipPath.split('/').pop()
     const rId = relationshipManager.addRelationship(
       sourceInfo.zipPath,
       REL_TYPES.SLIDE,

package/src/managers/TableManager.js

@@ -223,7 +223,7 @@ class TableManager {
       )
     }
 
-    this.#calculateRowHeights(slideIndex, tableId, slideManager, tblObj)
+    this.#calculateRowHeights(slideIndex, tableId, slideManager, tblObj, true)
 
     if (cellShapes) {
       this.#processCellShapes(
@@ -805,7 +805,7 @@ class TableManager {
     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 rowHeights = this.#calculateRowHeights(slideIndex, tableId, slideManager, tblObj, false)
 
     const parent = this.getMergeParent(slideIndex, tableId, rowIndex, colIndex, slideManager)
     const pr = parent.row
@@ -843,13 +843,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 +1389,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 +1490,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 +1505,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,
@@ -1885,7 +1943,7 @@ class TableManager {
     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 rowHeights = this.#calculateRowHeights(slideIndex, tableId, slideManager, tblObj, false)
 
     const parent = this.getMergeParent(slideIndex, tableId, rowIndex, colIndex, slideManager)
     const pr = parent.row
@@ -1982,7 +2040,7 @@ class TableManager {
     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 rowHeights = this.#calculateRowHeights(slideIndex, tableId, slideManager, tblObj, false)
 
     const parent = this.getMergeParent(slideIndex, tableId, rowIndex, colIndex, slideManager)
     const pr = parent.row
@@ -2094,7 +2152,7 @@ class TableManager {
     }
   }
 
-  #calculateRowHeights(slideIndex, tableId, slideManager, tblObj) {
+  #calculateRowHeights(slideIndex, tableId, slideManager, tblObj, writeToXml = true) {
     const trsArr = tblObj['a:tr'] || []
     if (trsArr.length === 0) return []
 
@@ -2105,8 +2163,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 h > 0 ? h : 228600
+    })
 
     // Helper to get paragraph font size
     const getParagraphFontSize = p => {
@@ -2228,7 +2289,9 @@ class TableManager {
         }
 
         const totalCellHeight_emu = marT + marB + textHeight_emu
-        cellHeights[r][c] = totalCellHeight_emu
+        const rowTemplateHeight = parseInt(row['@_h'] || 0, 10)
+        const minFloor = rowTemplateHeight > 0 ? rowTemplateHeight : 228600
+        cellHeights[r][c] = Math.max(totalCellHeight_emu, minFloor)
       }
     }
 
@@ -2279,8 +2342,10 @@ class TableManager {
     }
 
     // Update row heights in XML
-    for (let r = 0; r < numRows; r++) {
-      trsArr[r]['@_h'] = String(rowHeights[r])
+    if (writeToXml) {
+      for (let r = 0; r < numRows; r++) {
+        trsArr[r]['@_h'] = String(rowHeights[r])
+      }
     }
 
     return rowHeights