node-pptx-templater 1.0.19 → 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.19",
+  "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()