node-pptx-templater 1.0.19 → 1.0.21

package/README.md

@@ -173,6 +173,22 @@ if (!report.valid) {
 }
 ```
 
+### 5. PPTX Extraction & Rebuilding Utilities
+
+You can programmatically extract standard zipped `.pptx` archives into OpenXML folder templates or compile them back. Target directories are created automatically:
+
+#### Extract PPTX to Folder Template
+```javascript
+const { PPTXTemplate } = require('node-pptx-templater');
+
+await PPTXTemplate.extractPptx('./sample.pptx', './output/template', { overwrite: true });
+```
+
+#### Rebuild PPTX from Folder Template
+```javascript
+await PPTXTemplate.buildPptx('./templates/sample', './output.pptx');
+```
+
 ---
 
 ## 📋 OpenXML Presentation Architecture
@@ -208,6 +224,95 @@ Naively duplicating rows in slide tables can leave duplicate `rowId` values or b
 
 ---
 
+## 📊 Reading Table Data & JSON Extraction
+
+PPTXForge allows you to read table data from your template and return it as structured JSON objects or raw arrays. This is extremely useful for reverse-engineering data or verifying layouts.
+
+### 1. Object-Based Extraction (Default)
+By default, the first row is treated as headers, and subsequent rows are returned as objects keyed by header names. Merged cells automatically resolve to their parent cell's value:
+```javascript
+const rows = await ppt.getTableRows('SalesTable');
+// Returns:
+// [
+//   { region: 'North', sales: '1200', growth: '15%' },
+//   { region: 'South', sales: '1800', growth: '22%' }
+// ]
+```
+
+### 2. Raw Extraction
+Return a raw 2D array of string values (excluding the header row) by passing `{ raw: true }`:
+```javascript
+const rows = await ppt.getTableRows('SalesTable', { raw: true });
+// Returns:
+// [
+//   ['North', '1200', '15%'],
+//   ['South', '1800', '22%']
+// ]
+```
+
+### 3. Including Table Metadata
+Pass `{ includeMetadata: true }` to retrieve row counts, column counts, and the list of merged cell ranges alongside the rows:
+```javascript
+const result = await ppt.getTableRows('SalesTable', { includeMetadata: true });
+// Returns:
+// {
+//   rows: [...],
+//   rowCount: 10,
+//   columnCount: 5,
+//   mergedCells: [ { startRow: 1, startCol: 0, endRow: 2, endCol: 0 }, ... ]
+// }
+```
+
+---
+
+## 📈 Nested Table Rows & Rowspan Support
+
+When building financial sheets, invoices, or hierarchical dashboards, you often need to stack multiple rows vertically inside a single column while spanning cells in other columns. PPTXForge supports nested arrays in `addTableRow()` to automatically handle:
+- Proportional height scaling.
+- Vertical merge (`vMerge`) and row span (`rowSpan`) generation.
+- Dynamic layout adjustments.
+
+### 1. Vertical Row Nesting Example
+```javascript
+await ppt.addTableRow('Table1', [
+  'Region',
+  ['Sales', '1200'],
+  ['Growth', '15%']
+]);
+```
+Generates:
+```text
++---------+---------+---------+
+| Region  | Sales   | Growth  |
+|         | 1200    | 15%     |
++---------+---------+---------+
+```
+
+### 2. Deep Nesting Example
+```javascript
+await ppt.addTableRow('Table1', [
+  'Parent',
+  [
+    'Child 1',
+    'Child 2',
+    'Child 3'
+  ]
+]);
+```
+Generates 3 sub-rows where column 0 automatically spans all 3 rows.
+
+### 3. Merge Strategies
+Configure merge behavior via `options.mergeStrategy`:
+- `'auto'` (default): Creates structural merges from nested arrays, and additionally merges consecutive duplicate values in the same column.
+- `'rowspan'`: Creates structural rowspan/merges strictly from the nested array structure.
+- `'none'`: Pads columns to match the target generated height but does not merge cells (leaving them as individual cells).
+
+```javascript
+await ppt.addTableRow('Table1', data, { mergeStrategy: 'rowspan' });
+```
+
+---
+
 ## 📊 Feature Comparison Matrix
 
 Compare PPTXForge with other popular PowerPoint automation libraries:
@@ -243,6 +348,98 @@ 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);
+```
+
+#### `getCellBounds(tableId, rowIndex, colIndex)`
+Retrieves final rendered bounds of a table cell in pixels.
+
+* **Arguments**:
+  * `tableId` (`string`): Table name or shape ID.
+  * `rowIndex` (`number`): 0-based row index.
+  * `colIndex` (`number`): 0-based column index.
+* **Returns**: `Object|null` - Cell bounds { x, y, width, height } in pixels, or null.
+
+```javascript
+const bounds = ppt.getCellBounds('summary-table', 1, 1);
+```
+
+#### `getCellPosition(tableId, rowIndex, colIndex)`
+Retrieves final rendered position of a table cell in pixels.
+
+* **Arguments**:
+  * `tableId` (`string`): Table name or shape ID.
+  * `rowIndex` (`number`): 0-based row index.
+  * `colIndex` (`number`): 0-based column index.
+* **Returns**: `Object|null` - Cell position { row, column, x, y } in pixels, or null.
+
+```javascript
+const pos = ppt.getCellPosition('summary-table', 1, 1);
+```
+
+#### `getTableRows(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+const rows = await ppt.getTableRows('SalesTable');
+```
+
 #### `addTableRow(())`
 Delegates core actions to slide element sub-managers.
 
@@ -1016,6 +1213,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.
 
@@ -1466,6 +1727,24 @@ Delegates core actions to slide element sub-managers.
 const ppt = await PPTXTemplate.fromPresentationXml('./template-folder');
 ```
 
+#### `extractPptx(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+await PPTXTemplater.extractPptx('sample.pptx', './extracted');
+```
+
+#### `buildPptx(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+await PPTXTemplater.buildPptx('./extracted', 'output.pptx');
+```
+
 #### `validatePresentation(())`
 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.21",
   "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

@@ -340,6 +340,89 @@ class PPTXTemplater {
     return engine
   }
 
+  /**
+   * Extracts a PPTX file into an unzipped OpenXML folder structure.
+   *
+   * @static
+   * @param {string} pptxPath - Path to the source PPTX file.
+   * @param {string} outputPath - Path to the destination folder.
+   * @param {Object} [options] - Options (e.g. { overwrite: true }).
+   * @returns {Promise<void>}
+   */
+  static async extractPptx(pptxPath, outputPath, options = {}) {
+    const fs = require('fs-extra')
+    const path = require('path')
+
+    const resolvedPptx = path.resolve(pptxPath)
+    const resolvedOut = path.resolve(outputPath)
+
+    if (!fs.existsSync(resolvedPptx)) {
+      throw new PPTXError(`Source PPTX file not found: ${pptxPath}`)
+    }
+
+    if (fs.existsSync(resolvedOut)) {
+      const stats = fs.statSync(resolvedOut)
+      if (stats.isFile()) {
+        throw new PPTXError(`Destination is a file: ${outputPath}`)
+      }
+      const files = fs.readdirSync(resolvedOut)
+      if (files.length > 0 && !options.overwrite) {
+        throw new PPTXError(
+          `Destination directory "${outputPath}" is not empty. Set overwrite: true to overwrite.`
+        )
+      }
+    } else {
+      await fs.ensureDir(resolvedOut)
+    }
+
+    const engine = await PPTXTemplater.load(resolvedPptx)
+    await engine.#zipManager.toFolder(resolvedOut)
+
+    // Validation
+    const criticalParts = ['ppt/presentation.xml', 'ppt/slides', 'ppt/_rels', '[Content_Types].xml']
+
+    for (const part of criticalParts) {
+      const p = path.join(resolvedOut, part)
+      if (!fs.existsSync(p)) {
+        throw new PPTXError(`Extracted structure is missing critical part: ${part}`)
+      }
+    }
+  }
+
+  /**
+   * Rebuilds a PPTX file from an unzipped OpenXML folder structure.
+   *
+   * @static
+   * @param {string} folderPath - Path to the source folder structure.
+   * @param {string} pptxPath - Path to the destination PPTX file.
+   * @returns {Promise<void>}
+   */
+  static async buildPptx(folderPath, pptxPath) {
+    const fs = require('fs-extra')
+    const path = require('path')
+
+    const resolvedFolder = path.resolve(folderPath)
+    const resolvedPptx = path.resolve(pptxPath)
+
+    if (!fs.existsSync(resolvedFolder)) {
+      throw new PPTXError(`Source folder not found: ${folderPath}`)
+    }
+
+    // Validation of the source folder
+    const criticalParts = ['ppt/presentation.xml', 'ppt/slides', 'ppt/_rels', '[Content_Types].xml']
+
+    for (const part of criticalParts) {
+      const p = path.join(resolvedFolder, part)
+      if (!fs.existsSync(p)) {
+        throw new PPTXError(`Source folder is missing critical OpenXML part: ${part}`)
+      }
+    }
+
+    const engine = await PPTXTemplater.load(resolvedFolder)
+    await fs.ensureDir(path.dirname(resolvedPptx))
+    await engine.saveToFile(resolvedPptx)
+  }
+
   /**
    * Initializes the engine by loading a PPTX file/buffer.
    * @private
@@ -588,7 +671,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)`)
@@ -1291,11 +1380,21 @@ class PPTXTemplater {
   }
 
   // === Table Features ===
-  addTableRow(tableId, rowData) {
+  getTableRows(tableId, options = {}) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    if (targetIndices.length === 0) {
+      throw new PPTXError('No slides active/loaded')
+    }
+    const idx = targetIndices[0]
+    return this.#tableManager.getTableRows(idx, tableId, options, this.#slideManager)
+  }
+
+  addTableRow(tableId, rowData, options = {}) {
     this.#assertLoaded()
     const targetIndices = this.#getTargetSlideIndices()
     for (const idx of targetIndices) {
-      this.#tableManager.addTableRow(idx, tableId, rowData, this.#slideManager)
+      this.#tableManager.addTableRow(idx, tableId, rowData, this.#slideManager, options)
     }
     return this
   }
@@ -1914,6 +2013,245 @@ 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
+  }
+
+  /**
+   * Retrieves final rendered bounds of a table cell in pixels.
+   *
+   * @param {string} tableId - Table name or shape ID.
+   * @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) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      try {
+        const bounds = this.#tableManager.getCellBounds(
+          idx,
+          tableId,
+          rowIndex,
+          colIndex,
+          this.#slideManager
+        )
+        if (bounds) return bounds
+      } catch (err) {
+        logger.debug(
+          `Could not get cell bounds for table ${tableId} on slide ${idx}: ${err.message}`
+        )
+      }
+    }
+    return null
+  }
+
+  /**
+   * Retrieves final rendered position of a table cell in pixels.
+   *
+   * @param {string} tableId - Table name or shape ID.
+   * @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.
+   */
+  getCellPosition(tableId, rowIndex, colIndex) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      try {
+        const pos = this.#tableManager.getCellPosition(
+          idx,
+          tableId,
+          rowIndex,
+          colIndex,
+          this.#slideManager
+        )
+        if (pos) return pos
+      } catch (err) {
+        logger.debug(
+          `Could not get cell position for table ${tableId} on slide ${idx}: ${err.message}`
+        )
+      }
+    }
+    return null
+  }
+
   // === Image Features ===
   async replaceImage(imageIdOrName, sourcePathOrBuffer) {
     this.#assertLoaded()