node-pptx-templater 1.0.18 → 1.0.20

package/README.md

@@ -243,6 +243,63 @@ ppt.useSlide(1).updateTable('summary-table', [
 ]);
 ```
 
+#### `addCellShape(tableId, rowIndex, colIndex, options)`
+Dynamically adds a shape inside a table cell based on cell coordinates.
+
+* **Arguments**:
+  * `tableId` (`string`): Table name or shape ID.
+  * `rowIndex` (`number`): 0-based row index.
+  * `colIndex` (`number`): 0-based column index.
+  * `options` (`Object`): Shape configuration options.
+* **Returns**: `this` - The chainable presentation templater instance.
+
+```javascript
+await ppt.addCellShape('Table', 1, 2, { type: 'circle', fill: '#10B981' });
+```
+
+#### `updateCellShape(tableId, rowIndex, colIndex, shapeIndex, options)`
+Updates an existing shape inside a table cell.
+
+* **Arguments**:
+  * `tableId` (`string`): Table name or shape ID.
+  * `rowIndex` (`number`): 0-based row index.
+  * `colIndex` (`number`): 0-based column index.
+  * `shapeIndex` (`number`): 0-based shape index in the cell.
+  * `options` (`Object`): Shape configuration properties to update.
+* **Returns**: `this` - The chainable presentation templater instance.
+
+```javascript
+await ppt.updateCellShape('Table', 1, 2, 0, { fill: '#EF4444' });
+```
+
+#### `removeCellShape(tableId, rowIndex, colIndex, shapeIndex)`
+Removes a shape from a table cell.
+
+* **Arguments**:
+  * `tableId` (`string`): Table name or shape ID.
+  * `rowIndex` (`number`): 0-based row index.
+  * `colIndex` (`number`): 0-based column index.
+  * `shapeIndex` (`number`): 0-based shape index in the cell.
+* **Returns**: `this` - The chainable presentation templater instance.
+
+```javascript
+await ppt.removeCellShape('Table', 1, 2, 0);
+```
+
+#### `getCellShape(tableId, rowIndex, colIndex, shapeIndex)`
+Discovers and retrieves details of an existing cell shape on the targeted slide.
+
+* **Arguments**:
+  * `tableId` (`string`): Table name or shape ID.
+  * `rowIndex` (`number`): 0-based row index.
+  * `colIndex` (`number`): 0-based column index.
+  * `shapeIndex` (`number`): 0-based shape index in the cell.
+* **Returns**: `Object|null` - Shape details object, or null if not found.
+
+```javascript
+const shape = ppt.getCellShape('Table', 1, 2, 0);
+```
+
 #### `addTableRow(())`
 Delegates core actions to slide element sub-managers.
 
@@ -1016,6 +1073,70 @@ Updates the position and/or dimensions of an existing textbox on targeted slides
 ppt.useSlide(1).updateTextBoxPosition('TextBox 2', { x: 1000000, y: 1500000 });
 ```
 
+#### `validateShape(options)`
+Validates shape options configuration.
+
+* **Arguments**:
+  * `options` (`Object`): 
+* **Returns**: `string[]` - List of validation error messages.
+
+```javascript
+const errors = ppt.validateShape(shapeOptions);
+```
+
+#### `addShape(options)`
+Adds a new shape dynamically to the targeted slide(s).
+
+* **Arguments**:
+  * `options` (`Object`): 
+* **Returns**: `this` - The chainable presentation templater instance.
+
+```javascript
+await ppt.useSlide(1).addShape({
+  type: 'rectangle',
+  id: 'sales-box',
+  x: 100,
+  y: 100,
+  width: 200,
+  height: 100,
+  fill: '#2563EB'
+});
+```
+
+#### `updateShape(shapeId, options)`
+Updates an existing shape in-place.
+
+* **Arguments**:
+  * `shapeId` (`string`): 
+  * `options` (`Object`): 
+* **Returns**: `this` - The chainable presentation templater instance.
+
+```javascript
+await ppt.useSlide(1).updateShape('sales-box', { fill: '#10B981' });
+```
+
+#### `removeShape(shapeId)`
+Removes a shape from the targeted slide(s).
+
+* **Arguments**:
+  * `shapeId` (`string`): 
+* **Returns**: `this` - The chainable presentation templater instance.
+
+```javascript
+await ppt.useSlide(1).removeShape('sales-box');
+```
+
+#### `getShape(shapeId)`
+Discovers and retrieves details of an existing shape on the targeted slides.
+
+* **Arguments**:
+  * `shapeId` (`string`): 
+* **Returns**: `Object|null` - Shape details object, or null if not found.
+
+```javascript
+const shape = ppt.getShape('sales-box');
+```
+
 #### `updateShapeText(())`
 Delegates core actions to slide element sub-managers.
 

package/package.json

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

package/src/core/PPTXTemplater.js

@@ -588,7 +588,13 @@ class PPTXTemplater {
     const targetIndices = this.#getTargetSlideIndices()
 
     for (const slideIndex of targetIndices) {
-      this.#tableManager.updateTable(slideIndex, tableId, rows, this.#slideManager)
+      this.#tableManager.updateTable(
+        slideIndex,
+        tableId,
+        rows,
+        this.#slideManager,
+        this.#shapeManager
+      )
     }
 
     logger.debug(`Updated table "${tableId}" in ${targetIndices.length} slide(s)`)
@@ -1914,6 +1920,185 @@ class PPTXTemplater {
     return shapes
   }
 
+  /**
+   * Validates shape options configuration.
+   *
+   * @param {Object} options Shape creation/update options.
+   * @returns {string[]} List of validation error messages.
+   */
+  validateShape(options) {
+    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) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      this.#shapeManager.addShape(idx, options, this.#slideManager)
+    }
+    return this
+  }
+
+  /**
+   * Updates an existing shape in-place.
+   *
+   * @param {string} shapeId Shape ID or template name to update.
+   * @param {Object} options Configuration properties to update.
+   * @returns {this} The chainable presentation templater instance.
+   */
+  async updateShape(shapeId, options) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      this.#shapeManager.updateShape(idx, shapeId, options, this.#slideManager)
+    }
+    return this
+  }
+
+  /**
+   * Removes a shape from the targeted slide(s).
+   *
+   * @param {string} shapeId Shape ID or template name to remove.
+   * @returns {this} The chainable presentation templater instance.
+   */
+  async removeShape(shapeId) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      this.#shapeManager.removeShape(idx, shapeId, this.#slideManager)
+    }
+    return this
+  }
+
+  /**
+   * Discovers and retrieves details of an existing shape on the targeted slides.
+   *
+   * @param {string} shapeId Shape ID or template name to locate.
+   * @returns {Object|null} Shape details object, or null if not found.
+   */
+  getShape(shapeId) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      const shape = this.#shapeManager.getShape(idx, shapeId, this.#slideManager)
+      if (shape) return shape
+    }
+    return null
+  }
+
+  /**
+   * Dynamically adds a shape inside a table cell based on cell coordinates.
+   *
+   * @param {string} tableId - Table name or shape ID.
+   * @param {number} rowIndex - 0-based row index.
+   * @param {number} colIndex - 0-based column index.
+   * @param {Object} options - Shape configuration options.
+   * @returns {this} The chainable presentation templater instance.
+   */
+  async addCellShape(tableId, rowIndex, colIndex, options) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      this.#tableManager.addCellShape(
+        idx,
+        tableId,
+        rowIndex,
+        colIndex,
+        options,
+        this.#slideManager,
+        this.#shapeManager
+      )
+    }
+    return this
+  }
+
+  /**
+   * Updates an existing shape inside a table cell.
+   *
+   * @param {string} tableId - Table name or shape ID.
+   * @param {number} rowIndex - 0-based row index.
+   * @param {number} colIndex - 0-based column index.
+   * @param {number} shapeIndex - 0-based shape index in the cell.
+   * @param {Object} options - Shape configuration properties to update.
+   * @returns {this} The chainable presentation templater instance.
+   */
+  async updateCellShape(tableId, rowIndex, colIndex, shapeIndex, options) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      this.#tableManager.updateCellShape(
+        idx,
+        tableId,
+        rowIndex,
+        colIndex,
+        shapeIndex,
+        options,
+        this.#slideManager,
+        this.#shapeManager
+      )
+    }
+    return this
+  }
+
+  /**
+   * Removes a shape from a table cell.
+   *
+   * @param {string} tableId - Table name or shape ID.
+   * @param {number} rowIndex - 0-based row index.
+   * @param {number} colIndex - 0-based column index.
+   * @param {number} shapeIndex - 0-based shape index in the cell.
+   * @returns {this} The chainable presentation templater instance.
+   */
+  async removeCellShape(tableId, rowIndex, colIndex, shapeIndex) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      this.#tableManager.removeCellShape(
+        idx,
+        tableId,
+        rowIndex,
+        colIndex,
+        shapeIndex,
+        this.#slideManager,
+        this.#shapeManager
+      )
+    }
+    return this
+  }
+
+  /**
+   * Discovers and retrieves details of an existing cell shape on the targeted slide.
+   *
+   * @param {string} tableId - Table name or shape ID.
+   * @param {number} rowIndex - 0-based row index.
+   * @param {number} colIndex - 0-based column index.
+   * @param {number} shapeIndex - 0-based shape index in the cell.
+   * @returns {Object|null} Shape details object, or null if not found.
+   */
+  getCellShape(tableId, rowIndex, colIndex, shapeIndex) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      const shape = this.#tableManager.getCellShape(
+        idx,
+        tableId,
+        rowIndex,
+        colIndex,
+        shapeIndex,
+        this.#slideManager,
+        this.#shapeManager
+      )
+      if (shape) return shape
+    }
+    return null
+  }
+
   // === Image Features ===
   async replaceImage(imageIdOrName, sourcePathOrBuffer) {
     this.#assertLoaded()

package/src/managers/MediaManager.js

@@ -40,20 +40,9 @@ const { createHash } = require('crypto')
 const { createLogger } = require('../utils/logger.js')
 const { PPTXError } = require('../utils/errors.js')
 const fsExtra = require('fs-extra')
-const fs = require('fs')
 
 const logger = createLogger('MediaManager')
 
-function getFileHash(filePath) {
-  return new Promise((resolve, reject) => {
-    const hash = createHash('sha1')
-    const stream = fs.createReadStream(filePath)
-    stream.on('data', chunk => hash.update(chunk))
-    stream.on('end', () => resolve(hash.digest('hex')))
-    stream.on('error', reject)
-  })
-}
-
 function streamToBuffer(stream) {
   return new Promise((resolve, reject) => {
     const chunks = []
@@ -182,119 +171,58 @@ class MediaManager {
     let hash
     let size
     const isStream = source && typeof source.on === 'function' && typeof source.pipe === 'function'
-    let streamForZip = null
 
     if (isStream) {
-      if (source.path) {
-        // It's a file stream (fs.createReadStream)
+      // Buffer the stream to avoid JSZip streaming pipeline crashes and file locks
+      data = await streamToBuffer(source)
+      if (source.path && typeof source.path === 'string') {
         const filePath = source.path
-        hash = await getFileHash(filePath)
         ext = filePath.split('.').pop().toLowerCase()
-        mimeType = mimeType || EXT_TO_MIME[ext] || 'image/png'
-
-        // Check for duplicate (content-addressable dedup)
-        if (this.#mediaHashIndex.has(hash)) {
-          const existingPath = this.#mediaHashIndex.get(hash)
-          logger.debug(`Reusing existing media: ${existingPath} (hash: ${hash.substring(0, 8)}...)`)
-          return existingPath
-        }
-
-        // Ensure all media from template is hashed to check for duplicates
-        await this.#ensureAllMediaHashed()
-
-        if (this.#mediaHashIndex.has(hash)) {
-          const existingPath = this.#mediaHashIndex.get(hash)
-          logger.debug(`Reusing existing media: ${existingPath} (hash: ${hash.substring(0, 8)}...)`)
-          return existingPath
-        }
-
-        const stat = await fsExtra.stat(filePath)
-        size = stat.size
-        streamForZip = fs.createReadStream(filePath)
       } else {
-        // Generic stream - we must buffer it to hash and reuse
-        data = await streamToBuffer(source)
-        hash = this.#hashBytes(data)
         ext = this.#detectExtension(data)
-        mimeType = mimeType || EXT_TO_MIME[ext] || 'image/png'
-        size = data.length
-
-        // Check for duplicate (content-addressable dedup)
-        if (this.#mediaHashIndex.has(hash)) {
-          const existingPath = this.#mediaHashIndex.get(hash)
-          logger.debug(`Reusing existing media: ${existingPath} (hash: ${hash.substring(0, 8)}...)`)
-          return existingPath
-        }
-
-        // Ensure all media from template is hashed to check for duplicates
-        await this.#ensureAllMediaHashed()
-
-        if (this.#mediaHashIndex.has(hash)) {
-          const existingPath = this.#mediaHashIndex.get(hash)
-          logger.debug(`Reusing existing media: ${existingPath} (hash: ${hash.substring(0, 8)}...)`)
-          return existingPath
-        }
       }
+      mimeType = mimeType || EXT_TO_MIME[ext] || 'image/png'
+      hash = this.#hashBytes(data)
+      size = data.length
     } else if (typeof source === 'string') {
-      // Load from file path
-      hash = await getFileHash(source)
+      // Load from file path directly to buffer
+      data = await fsExtra.readFile(source)
       ext = source.split('.').pop().toLowerCase()
       mimeType = mimeType || EXT_TO_MIME[ext] || 'image/png'
-
-      if (this.#mediaHashIndex.has(hash)) {
-        const existingPath = this.#mediaHashIndex.get(hash)
-        logger.debug(`Reusing existing media: ${existingPath} (hash: ${hash.substring(0, 8)}...)`)
-        return existingPath
-      }
-
-      // Ensure all media from template is hashed to check for duplicates
-      await this.#ensureAllMediaHashed()
-
-      if (this.#mediaHashIndex.has(hash)) {
-        const existingPath = this.#mediaHashIndex.get(hash)
-        logger.debug(`Reusing existing media: ${existingPath} (hash: ${hash.substring(0, 8)}...)`)
-        return existingPath
-      }
-
-      const stat = await fsExtra.stat(source)
-      size = stat.size
-      streamForZip = fs.createReadStream(source)
+      hash = this.#hashBytes(data)
+      size = data.length
     } else if (Buffer.isBuffer(source) || source instanceof Uint8Array) {
       data = source
       ext = this.#detectExtension(data)
       mimeType = mimeType || EXT_TO_MIME[ext] || 'image/png'
       hash = this.#hashBytes(data)
       size = data.length
-
-      if (this.#mediaHashIndex.has(hash)) {
-        const existingPath = this.#mediaHashIndex.get(hash)
-        logger.debug(`Reusing existing media: ${existingPath} (hash: ${hash.substring(0, 8)}...)`)
-        return existingPath
-      }
-
-      // Ensure all media from template is hashed to check for duplicates
-      await this.#ensureAllMediaHashed()
-
-      if (this.#mediaHashIndex.has(hash)) {
-        const existingPath = this.#mediaHashIndex.get(hash)
-        logger.debug(`Reusing existing media: ${existingPath} (hash: ${hash.substring(0, 8)}...)`)
-        return existingPath
-      }
     } else {
       throw new PPTXError(
         'embedImage: source must be a file path string, Buffer, or Readable Stream'
       )
     }
 
+    if (this.#mediaHashIndex.has(hash)) {
+      const existingPath = this.#mediaHashIndex.get(hash)
+      logger.debug(`Reusing existing media: ${existingPath} (hash: ${hash.substring(0, 8)}...)`)
+      return existingPath
+    }
+
+    // Ensure all media from template is hashed to check for duplicates
+    await this.#ensureAllMediaHashed()
+
+    if (this.#mediaHashIndex.has(hash)) {
+      const existingPath = this.#mediaHashIndex.get(hash)
+      logger.debug(`Reusing existing media: ${existingPath} (hash: ${hash.substring(0, 8)}...)`)
+      return existingPath
+    }
+
     // Create a new media file
     const mediaId = this.#nextMediaId++
     const zipPath = `ppt/media/image${mediaId}.${ext}`
 
-    if (streamForZip) {
-      this.#zipManager.writeBinaryFile(zipPath, streamForZip)
-    } else {
-      this.#zipManager.writeBinaryFile(zipPath, data)
-    }
+    this.#zipManager.writeBinaryFile(zipPath, data)
 
     this.#mediaHashIndex.set(hash, zipPath)
     this.#mediaRegistry.set(zipPath, { zipPath, hash, mimeType, size })