node-pptx-templater 1.0.3 → 1.0.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "node-pptx-templater",
-  "version": "1.0.3",
-  "description": "Low-level PowerPoint OpenXML template engine for Node.js — generate and edit PPTX files directly through XML manipulation without relying on PowerPoint generation libraries.",
+  "version": "1.0.5",
+  "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",
   "exports": {
@@ -43,7 +43,16 @@
     "report",
     "generator",
     "nodejs",
-    "esm"
+    "powerpoint-automation",
+    "pptx-template-engine",
+    "merge-cells",
+    "table-merge",
+    "chart-update",
+    "dynamic-slides",
+    "mail-merge",
+    "report-generator",
+    "xml-manipulation",
+    "pptx-editor"
   ],
   "author": {
     "name": "node-pptx-templater contributors"

package/src/core/PPTXTemplater.js

@@ -36,6 +36,7 @@ const { RelationshipManager } = require('../managers/RelationshipManager.js')
 const { ShapeManager } = require('../managers/ShapeManager.js')
 const { ImageManager } = require('../managers/ImageManager.js')
 const { TextManager } = require('../managers/TextManager.js')
+const { ZOrderManager } = require('../managers/ZOrderManager.js')
 const { ValidationEngine } = require('./ValidationEngine.js')
 const { OutputWriter } = require('./OutputWriter.js')
 const { TemplateEngine } = require('./TemplateEngine.js')
@@ -121,6 +122,12 @@ class PPTXTemplater {
    */
   #textManager
 
+  /**
+   * @private
+   * @type {ZOrderManager}
+   */
+  #zOrderManager
+
   /**
    * @private
    * @type {RelationshipManager}
@@ -169,6 +176,7 @@ class PPTXTemplater {
     this.#imageManager = new ImageManager(this.#xmlParser)
     this.#textManager = new TextManager(this.#xmlParser)
     this.#templateEngine = new TemplateEngine(this.#xmlParser)
+    this.#zOrderManager = new ZOrderManager(this.#xmlParser)
     this.#outputWriter = new OutputWriter(this.#zipManager, this.#contentTypesManager)
   }
 
@@ -253,6 +261,8 @@ class PPTXTemplater {
     await this.#contentTypesManager.initialize(this.#zipManager)
     await this.#relationshipManager.initialize(this.#zipManager)
     await this.#slideManager.initialize(this.#zipManager)
+    // Pre-load all slide XML so synchronous operations work on the blank template's existing slides
+    await this.#slideManager.preloadAll()
     await this.#chartManager.initialize(this.#zipManager)
     await this.#mediaManager.initialize(this.#zipManager)
     this.#loaded = true
@@ -1541,6 +1551,266 @@ class PPTXTemplater {
   get mediaManager() {
     return this.#mediaManager
   }
+
+  // Z-Order / Layer Management APIs
+
+  /**
+   * Moves slide element one layer forward.
+   */
+  bringForward(optionsOrId) {
+    this.#assertLoaded()
+    let slideIndex, objectId
+    if (typeof optionsOrId === 'object' && optionsOrId !== null) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+    }
+    this.#zOrderManager.bringForward(slideIndex, objectId, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Moves slide element one layer backward.
+   */
+  sendBackward(optionsOrId) {
+    this.#assertLoaded()
+    let slideIndex, objectId
+    if (typeof optionsOrId === 'object' && optionsOrId !== null) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+    }
+    this.#zOrderManager.sendBackward(slideIndex, objectId, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Moves slide element above all other objects.
+   */
+  bringToFront(optionsOrId) {
+    this.#assertLoaded()
+    let slideIndex, objectId
+    if (typeof optionsOrId === 'object' && optionsOrId !== null) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+    }
+    this.#zOrderManager.bringToFront(slideIndex, objectId, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Moves slide element behind all other objects.
+   */
+  sendToBack(optionsOrId) {
+    this.#assertLoaded()
+    let slideIndex, objectId
+    if (typeof optionsOrId === 'object' && optionsOrId !== null) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+    }
+    this.#zOrderManager.sendToBack(slideIndex, objectId, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Moves slide element to the specific 1-based stacking position.
+   */
+  setZIndex(optionsOrId, zIndex) {
+    this.#assertLoaded()
+    let slideIndex, objectId, targetZIndex
+    if (
+      typeof optionsOrId === 'object' &&
+      optionsOrId !== null &&
+      optionsOrId.zIndex !== undefined
+    ) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+      targetZIndex = optionsOrId.zIndex
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+      targetZIndex = zIndex
+    }
+    this.#zOrderManager.setZIndex(slideIndex, objectId, targetZIndex, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Moves slide element directly before (below) a target element.
+   */
+  moveObjectBefore(optionsOrId, targetId) {
+    this.#assertLoaded()
+    let slideIndex, objectId, target
+    if (
+      typeof optionsOrId === 'object' &&
+      optionsOrId !== null &&
+      optionsOrId.targetId !== undefined
+    ) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+      target = optionsOrId.targetId
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+      target = targetId
+    }
+    this.#zOrderManager.moveObjectBefore(slideIndex, objectId, target, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Moves slide element directly after (above) a target element.
+   */
+  moveObjectAfter(optionsOrId, targetId) {
+    this.#assertLoaded()
+    let slideIndex, objectId, target
+    if (
+      typeof optionsOrId === 'object' &&
+      optionsOrId !== null &&
+      optionsOrId.targetId !== undefined
+    ) {
+      slideIndex =
+        optionsOrId.slide !== undefined ? optionsOrId.slide : this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId.objectId
+      target = optionsOrId.targetId
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId = optionsOrId
+      target = targetId
+    }
+    this.#zOrderManager.moveObjectAfter(slideIndex, objectId, target, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Reorders slide objects exactly as specified in the array.
+   */
+  reorderObjects(optionsOrOrder) {
+    this.#assertLoaded()
+    let slideIndex, order
+    if (
+      typeof optionsOrOrder === 'object' &&
+      optionsOrOrder !== null &&
+      Array.isArray(optionsOrOrder.order)
+    ) {
+      slideIndex =
+        optionsOrOrder.slide !== undefined
+          ? optionsOrOrder.slide
+          : this.#getTargetSlideIndices()[0] || 1
+      order = optionsOrOrder.order
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      order = optionsOrOrder
+    }
+    this.#zOrderManager.reorderObjects(slideIndex, order, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Gets the ordered metadata of all objects on the slide.
+   */
+  getObjectOrder(slideIndex) {
+    this.#assertLoaded()
+    const targetIdx = slideIndex !== undefined ? slideIndex : this.#getTargetSlideIndices()[0] || 1
+    return this.#zOrderManager.getObjectOrder(targetIdx, this.#slideManager)
+  }
+
+  /**
+   * Applies bulk template configurations for slide elements stacking layers.
+   */
+  applyZOrder(slideOrConfigs, configsOption) {
+    this.#assertLoaded()
+    let slideIndex, configs
+    if (Array.isArray(slideOrConfigs)) {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      configs = slideOrConfigs
+    } else {
+      slideIndex = slideOrConfigs
+      configs = configsOption
+    }
+    this.#zOrderManager.applyZOrder(slideIndex, configs, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Retrieves the info of the top-most object on the slide.
+   */
+  getTopMostObject(slideIndex) {
+    this.#assertLoaded()
+    const targetIdx = slideIndex !== undefined ? slideIndex : this.#getTargetSlideIndices()[0] || 1
+    return this.#zOrderManager.getTopMostObject(targetIdx, this.#slideManager)
+  }
+
+  /**
+   * Retrieves the info of the bottom-most object on the slide.
+   */
+  getBottomMostObject(slideIndex) {
+    this.#assertLoaded()
+    const targetIdx = slideIndex !== undefined ? slideIndex : this.#getTargetSlideIndices()[0] || 1
+    return this.#zOrderManager.getBottomMostObject(targetIdx, this.#slideManager)
+  }
+
+  /**
+   * Swaps stacking positions of two slide objects.
+   */
+  swapObjects(slideIndexOrId1, id1OrId2, id2) {
+    this.#assertLoaded()
+    let slideIndex, objectId1, objectId2
+    if (id2 !== undefined) {
+      slideIndex = slideIndexOrId1
+      objectId1 = id1OrId2
+      objectId2 = id2
+    } else {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      objectId1 = slideIndexOrId1
+      objectId2 = id1OrId2
+    }
+    this.#zOrderManager.swapObjects(slideIndex, objectId1, objectId2, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Sorts stacking order using a custom comparison function.
+   */
+  sortObjects(slideIndexOrCompareFn, compareFnOption) {
+    this.#assertLoaded()
+    let slideIndex, compareFn
+    if (typeof slideIndexOrCompareFn === 'function') {
+      slideIndex = this.#getTargetSlideIndices()[0] || 1
+      compareFn = slideIndexOrCompareFn
+    } else {
+      slideIndex = slideIndexOrCompareFn
+      compareFn = compareFnOption
+    }
+    this.#zOrderManager.sortObjects(slideIndex, compareFn, this.#slideManager)
+    return this
+  }
+
+  /**
+   * Cleans up and normalizes stacking order consistency.
+   */
+  normalizeZOrder(slideIndex) {
+    this.#assertLoaded()
+    const targetIdx = slideIndex !== undefined ? slideIndex : this.#getTargetSlideIndices()[0] || 1
+    this.#zOrderManager.normalizeZOrder(targetIdx, this.#slideManager)
+    return this
+  }
 }
 
 module.exports = { PPTXTemplater }

package/src/core/ValidationEngine.js

@@ -105,6 +105,11 @@ class ValidationEngine {
           )
         }
       }
+
+      // Verify Z-order and duplicate IDs
+      const zOrderResult = this.validateObjectOrder(ppt, slideIndex)
+      errors.push(...zOrderResult.errors)
+      warnings.push(...zOrderResult.warnings)
     } catch (err) {
       errors.push(`Slide ${slideIndex} validation error: ${err.message}`)
     }
@@ -241,6 +246,78 @@ class ValidationEngine {
       warnings,
     }
   }
+
+  /**
+   * Audits the shape tree structure for duplicate drawing element IDs.
+   */
+  static validateObjectOrder(ppt, slideIndex) {
+    const errors = []
+    const warnings = []
+
+    try {
+      const slideXml = ppt.slideManager.getSlideXml(slideIndex)
+      const slideObj = ppt.xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+      const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+
+      if (!spTree) {
+        errors.push(`Slide ${slideIndex} shape tree not found`)
+        return { valid: false, errors, warnings }
+      }
+
+      const idToTags = new Map()
+
+      const checkIdsRecursive = container => {
+        if (!container) return
+
+        for (const tag of ['p:sp', 'p:pic', 'p:graphicFrame', 'p:grpSp', 'p:cxnSp']) {
+          let items = container[tag] || []
+          if (!Array.isArray(items)) items = [items]
+          for (const item of items) {
+            let id = null
+            let name = null
+            if (tag === 'p:sp') {
+              id = item?.['p:nvSpPr']?.['p:cNvPr']?.['@_id']
+              name = item?.['p:nvSpPr']?.['p:cNvPr']?.['@_name']
+            } else if (tag === 'p:pic') {
+              id = item?.['p:nvPicPr']?.['p:cNvPr']?.['@_id']
+              name = item?.['p:nvPicPr']?.['p:cNvPr']?.['@_name']
+            } else if (tag === 'p:graphicFrame') {
+              id = item?.['p:nvGraphicFramePr']?.['p:cNvPr']?.['@_id']
+              name = item?.['p:nvGraphicFramePr']?.['p:cNvPr']?.['@_name']
+            } else if (tag === 'p:grpSp') {
+              id = item?.['p:nvGrpSpPr']?.['p:cNvPr']?.['@_id']
+              name = item?.['p:nvGrpSpPr']?.['p:cNvPr']?.['@_name']
+              checkIdsRecursive(item)
+            } else if (tag === 'p:cxnSp') {
+              id = item?.['p:nvCxnSpPr']?.['p:cNvPr']?.['@_id']
+              name = item?.['p:nvCxnSpPr']?.['p:cNvPr']?.['@_name']
+            }
+
+            if (id !== undefined && id !== null) {
+              const strId = String(id)
+              if (idToTags.has(strId)) {
+                errors.push(
+                  `Duplicate drawing object ID "${strId}" found in slide ${slideIndex} (name: "${name}")`
+                )
+              } else {
+                idToTags.set(strId, tag)
+              }
+            }
+          }
+        }
+      }
+
+      checkIdsRecursive(spTree)
+    } catch (err) {
+      errors.push(`Slide ${slideIndex} shape tree validation error: ${err.message}`)
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    }
+  }
 }
 
 module.exports = { ValidationEngine }

package/src/index.js

@@ -26,7 +26,7 @@
 
 const { PPTXTemplater } = require('./core/PPTXTemplater.js')
 const { ZipManager } = require('./managers/ZipManager.js')
-const { XMLParser } = require('./parsers/XMLParser.js')
+const { XMLParser, Z_ORDER_SYMBOL } = require('./parsers/XMLParser.js')
 const { SlideManager } = require('./managers/SlideManager.js')
 const { ChartManager } = require('./managers/ChartManager.js')
 const { TableManager } = require('./managers/TableManager.js')
@@ -55,6 +55,7 @@ module.exports = {
   PPTXTemplater,
   ZipManager,
   XMLParser,
+  Z_ORDER_SYMBOL,
   SlideManager,
   ChartManager,
   TableManager,