node-pptx-templater 1.0.2 → 1.0.3

package/src/managers/TextManager.js

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview TextManager - Handles slide text search, retrieval, and replacement.
+ */
+
+const { createLogger } = require('../utils/logger.js')
+
+const logger = createLogger('TextManager')
+
+/**
+ * @class TextManager
+ * @description Manages text elements, replacements, and search inside slide XML.
+ */
+class TextManager {
+  /** @private @type {XMLParser} */
+  #xmlParser
+
+  /**
+   * @param {XMLParser} xmlParser
+   */
+  constructor(xmlParser) {
+    this.#xmlParser = xmlParser
+  }
+
+  /**
+   * Replaces a specific tag/placeholder with a value.
+   *
+   * @param {number} slideIndex
+   * @param {string} tag - E.g. '{{name}}' or 'name' (auto-wraps if simple).
+   * @param {string} value
+   * @param {Object} options
+   * @param {SlideManager} slideManager
+   * @param {TemplateEngine} templateEngine
+   */
+  replaceTextByTag(slideIndex, tag, value, _options = {}, slideManager, templateEngine) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+
+    // Auto-wrap tag in {{}} if not already present
+    const normalizedTag = tag.startsWith('{{') && tag.endsWith('}}') ? tag : `{{${tag}}}`
+
+    const replacements = { [normalizedTag]: value }
+    const updatedXml = templateEngine.replaceTextInXml(slideXml, replacements)
+
+    slideManager.setSlideXml(slideIndex, updatedXml)
+    logger.debug(`Replaced text tag "${normalizedTag}" with value on slide ${slideIndex}`)
+  }
+
+  /**
+   * Performs multiple text replacements at once.
+   *
+   * @param {number} slideIndex
+   * @param {Object.<string, string>} replacements - Map of key -> value.
+   * @param {Object} options
+   * @param {SlideManager} slideManager
+   * @param {TemplateEngine} templateEngine
+   */
+  replaceMultiple(slideIndex, replacements, _options = {}, slideManager, templateEngine) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+
+    // Normalize keys in the replacements map to ensure they are wrapped in placeholders
+    const normalized = {}
+    for (const [key, val] of Object.entries(replacements)) {
+      const normalizedKey = key.startsWith('{{') && key.endsWith('}}') ? key : `{{${key}}}`
+      normalized[normalizedKey] = val
+    }
+
+    const updatedXml = templateEngine.replaceTextInXml(slideXml, normalized)
+    slideManager.setSlideXml(slideIndex, updatedXml)
+    logger.debug(`Replaced multiple tags on slide ${slideIndex}`)
+  }
+
+  /**
+   * Searches for a text string inside all text runs on a slide.
+   *
+   * @param {number} slideIndex
+   * @param {string} searchText
+   * @param {SlideManager} slideManager
+   * @returns {Array<Object>} List of match details.
+   */
+  findText(slideIndex, searchText, slideManager) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const results = []
+
+    // Find in shapes (p:sp)
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+    if (!spTree) return results
+
+    this.#searchShapesForText(spTree, searchText, results)
+    return results
+  }
+
+  /**
+   * Extracts and returns all text elements on a slide.
+   *
+   * @param {number} slideIndex
+   * @param {SlideManager} slideManager
+   * @returns {Array<Object>} Elements with text contents.
+   */
+  getTextElements(slideIndex, slideManager) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const results = []
+
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+    if (!spTree) return results
+
+    this.#collectTextElements(spTree, results)
+    return results
+  }
+
+  #searchShapesForText(container, searchText, results) {
+    if (!container) return
+
+    let shapes = container['p:sp'] || []
+    if (!Array.isArray(shapes)) shapes = [shapes]
+
+    for (const shape of shapes) {
+      const cNvPr = shape?.['p:nvSpPr']?.['p:cNvPr']
+      const shapeName = cNvPr ? cNvPr['@_name'] : 'unnamed'
+      const shapeId = cNvPr ? String(cNvPr['@_id']) : 'unknown'
+
+      const txBody = shape['p:txBody']
+      if (txBody && txBody['a:p']) {
+        const paras = Array.isArray(txBody['a:p']) ? txBody['a:p'] : [txBody['a:p']]
+        paras.forEach((p, pIdx) => {
+          let pText = ''
+          if (p['a:r']) {
+            const runs = Array.isArray(p['a:r']) ? p['a:r'] : [p['a:r']]
+            runs.forEach(r => {
+              if (r['a:t']) pText += String(r['a:t'])
+            })
+          }
+
+          if (pText.toLowerCase().includes(searchText.toLowerCase())) {
+            results.push({
+              shapeId,
+              shapeName,
+              paragraphIndex: pIdx,
+              text: pText,
+              match: searchText,
+            })
+          }
+        })
+      }
+    }
+
+    let groups = container['p:grpSp'] || []
+    if (!Array.isArray(groups)) groups = [groups]
+    for (const g of groups) {
+      this.#searchShapesForText(g, searchText, results)
+    }
+  }
+
+  #collectTextElements(container, results) {
+    if (!container) return
+
+    let shapes = container['p:sp'] || []
+    if (!Array.isArray(shapes)) shapes = [shapes]
+
+    for (const shape of shapes) {
+      const cNvPr = shape?.['p:nvSpPr']?.['p:cNvPr']
+      const shapeName = cNvPr ? cNvPr['@_name'] : 'unnamed'
+      const shapeId = cNvPr ? String(cNvPr['@_id']) : 'unknown'
+
+      const txBody = shape['p:txBody']
+      if (txBody && txBody['a:p']) {
+        const paras = Array.isArray(txBody['a:p']) ? txBody['a:p'] : [txBody['a:p']]
+        paras.forEach((p, pIdx) => {
+          let pText = ''
+          if (p['a:r']) {
+            const runs = Array.isArray(p['a:r']) ? p['a:r'] : [p['a:r']]
+            runs.forEach(r => {
+              if (r['a:t']) pText += String(r['a:t'])
+            })
+          }
+
+          if (pText.trim()) {
+            results.push({
+              shapeId,
+              shapeName,
+              paragraphIndex: pIdx,
+              text: pText,
+            })
+          }
+        })
+      }
+    }
+
+    let groups = container['p:grpSp'] || []
+    if (!Array.isArray(groups)) groups = [groups]
+    for (const g of groups) {
+      this.#collectTextElements(g, results)
+    }
+  }
+}
+
+module.exports = { TextManager }

package/src/managers/ZipManager.js

@@ -13,13 +13,13 @@
  * raw file content within the ZIP.
  */
 
-const JSZip = require('jszip');
-const fsExtra = require('fs-extra');
-const { createLogger } = require('../utils/logger.js');
-const { PPTXError } = require('../utils/errors.js');
-const { BLANK_PPTX_BASE64 } = require('../templates/blankPptx.js');
+const JSZip = require('jszip')
+const fsExtra = require('fs-extra')
+const { createLogger } = require('../utils/logger.js')
+const { PPTXError } = require('../utils/errors.js')
+const { BLANK_PPTX_BASE64 } = require('../templates/blankPptx.js')
 
-const logger = createLogger('ZipManager');
+const logger = createLogger('ZipManager')
 
 /**
  * @class ZipManager
@@ -32,25 +32,25 @@ class ZipManager {
    * @private
    * @type {JSZip}
    */
-  #zip = null;
+  #zip = null
 
   /**
    * @private
    * @type {Map<string, string>} Cache of decoded XML strings for fast repeated access.
    */
-  #xmlCache = new Map();
+  #xmlCache = new Map()
 
   /**
    * @private
    * @type {Map<string, string>} Dirty (modified) files that need to be re-written.
    */
-  #dirtyFiles = new Map();
+  #dirtyFiles = new Map()
 
   /**
    * @private
    * @type {Map<string, string>} Core properties (dc:title, dc:creator, etc.)
    */
-  #coreProperties = new Map();
+  #coreProperties = new Map()
 
   /**
    * Loads a PPTX file from a path or Buffer.
@@ -61,22 +61,24 @@ class ZipManager {
    */
   async load(source) {
     try {
-      let data;
+      let data
       if (typeof source === 'string') {
-        logger.debug(`Reading file: ${source}`);
-        data = await fsExtra.readFile(source);
+        logger.debug(`Reading file: ${source}`)
+        data = await fsExtra.readFile(source)
       } else if (Buffer.isBuffer(source) || source instanceof Uint8Array) {
-        data = source;
+        data = source
       } else {
-        throw new PPTXError(`Invalid source type: ${typeof source}. Expected string path or Buffer.`);
+        throw new PPTXError(
+          `Invalid source type: ${typeof source}. Expected string path or Buffer.`
+        )
       }
 
-      this.#zip = await JSZip.loadAsync(data);
-      await this.#loadCoreProperties();
-      logger.debug(`ZIP loaded successfully. Files: ${Object.keys(this.#zip.files).length}`);
+      this.#zip = await JSZip.loadAsync(data)
+      await this.#loadCoreProperties()
+      logger.debug(`ZIP loaded successfully. Files: ${Object.keys(this.#zip.files).length}`)
     } catch (err) {
-      if (err instanceof PPTXError) throw err;
-      throw new PPTXError(`Failed to load PPTX: ${err.message}`, err);
+      if (err instanceof PPTXError) throw err
+      throw new PPTXError(`Failed to load PPTX: ${err.message}`, err)
     }
   }
 
@@ -85,10 +87,10 @@ class ZipManager {
    * @returns {Promise<void>}
    */
   async createBlank() {
-    const buffer = Buffer.from(BLANK_PPTX_BASE64, 'base64');
-    this.#zip = await JSZip.loadAsync(buffer);
-    await this.#loadCoreProperties();
-    logger.debug('Created blank PPTX structure');
+    const buffer = Buffer.from(BLANK_PPTX_BASE64, 'base64')
+    this.#zip = await JSZip.loadAsync(buffer)
+    await this.#loadCoreProperties()
+    logger.debug('Created blank PPTX structure')
   }
 
   /**
@@ -99,27 +101,27 @@ class ZipManager {
    */
   async readFile(zipPath) {
     // Normalize path separators
-    const normalPath = zipPath.replace(/\\/g, '/');
+    const normalPath = zipPath.replace(/\\/g, '/')
 
     // Return cached version if available and not dirty
     if (this.#xmlCache.has(normalPath) && !this.#dirtyFiles.has(normalPath)) {
-      return this.#xmlCache.get(normalPath);
+      return this.#xmlCache.get(normalPath)
     }
 
     // Check dirty files (pending writes)
     if (this.#dirtyFiles.has(normalPath)) {
-      return this.#dirtyFiles.get(normalPath);
+      return this.#dirtyFiles.get(normalPath)
     }
 
-    const file = this.#zip.file(normalPath);
+    const file = this.#zip.file(normalPath)
     if (!file) {
-      logger.debug(`File not found in ZIP: ${normalPath}`);
-      return null;
+      logger.debug(`File not found in ZIP: ${normalPath}`)
+      return null
     }
 
-    const content = await file.async('text');
-    this.#xmlCache.set(normalPath, content);
-    return content;
+    const content = await file.async('text')
+    this.#xmlCache.set(normalPath, content)
+    return content
   }
 
   /**
@@ -129,10 +131,10 @@ class ZipManager {
    * @returns {Promise<Uint8Array|null>} Binary content or null if not found.
    */
   async readBinaryFile(zipPath) {
-    const normalPath = zipPath.replace(/\\/g, '/');
-    const file = this.#zip.file(normalPath);
-    if (!file) return null;
-    return file.async('uint8array');
+    const normalPath = zipPath.replace(/\\/g, '/')
+    const file = this.#zip.file(normalPath)
+    if (!file) return null
+    return file.async('uint8array')
   }
 
   /**
@@ -143,12 +145,12 @@ class ZipManager {
    * @param {string} content - UTF-8 string content.
    */
   writeFile(zipPath, content) {
-    const normalPath = zipPath.replace(/\\/g, '/');
-    this.#dirtyFiles.set(normalPath, content);
-    this.#xmlCache.set(normalPath, content);
+    const normalPath = zipPath.replace(/\\/g, '/')
+    this.#dirtyFiles.set(normalPath, content)
+    this.#xmlCache.set(normalPath, content)
     // Also write to the underlying JSZip object
-    this.#zip.file(normalPath, content);
-    logger.debug(`Queued write: ${normalPath}`);
+    this.#zip.file(normalPath, content)
+    logger.debug(`Queued write: ${normalPath}`)
   }
 
   /**
@@ -158,23 +160,23 @@ class ZipManager {
    * @param {Buffer|Uint8Array} data - Binary data.
    */
   writeBinaryFile(zipPath, data) {
-    const normalPath = zipPath.replace(/\\/g, '/');
-    this.#zip.file(normalPath, data);
-    logger.debug(`Queued binary write: ${normalPath}`);
+    const normalPath = zipPath.replace(/\\/g, '/')
+    this.#zip.file(normalPath, data)
+    logger.debug(`Queued binary write: ${normalPath}`)
   }
 
   /**
    * @private
    * @type {Promise[]}
    */
-  #pendingPromises = [];
+  #pendingPromises = []
 
   /**
    * Adds a promise to the pending queue to be awaited before saving.
    * @param {Promise} promise
    */
   addPendingPromise(promise) {
-    this.#pendingPromises.push(promise);
+    this.#pendingPromises.push(promise)
   }
 
   /**
@@ -183,8 +185,8 @@ class ZipManager {
    */
   async waitForPendingWrites() {
     if (this.#pendingPromises.length > 0) {
-      await Promise.all(this.#pendingPromises);
-      this.#pendingPromises = [];
+      await Promise.all(this.#pendingPromises)
+      this.#pendingPromises = []
     }
   }
 
@@ -194,10 +196,10 @@ class ZipManager {
    * @param {string} zipPath - Path to remove.
    */
   removeFile(zipPath) {
-    const normalPath = zipPath.replace(/\\/g, '/');
-    this.#zip.remove(normalPath);
-    this.#xmlCache.delete(normalPath);
-    this.#dirtyFiles.delete(normalPath);
+    const normalPath = zipPath.replace(/\\/g, '/')
+    this.#zip.remove(normalPath)
+    this.#xmlCache.delete(normalPath)
+    this.#dirtyFiles.delete(normalPath)
   }
 
   /**
@@ -207,8 +209,8 @@ class ZipManager {
    * @returns {boolean}
    */
   hasFile(zipPath) {
-    const normalPath = zipPath.replace(/\\/g, '/');
-    return this.#zip.file(normalPath) !== null;
+    const normalPath = zipPath.replace(/\\/g, '/')
+    return this.#zip.file(normalPath) !== null
   }
 
   /**
@@ -218,9 +220,7 @@ class ZipManager {
    * @returns {string[]} Array of matching file paths.
    */
   listFiles(prefix = '') {
-    return Object.keys(this.#zip.files).filter(
-      f => !this.#zip.files[f].dir && f.startsWith(prefix)
-    );
+    return Object.keys(this.#zip.files).filter(f => !this.#zip.files[f].dir && f.startsWith(prefix))
   }
 
   /**
@@ -234,7 +234,7 @@ class ZipManager {
       type: 'nodebuffer',
       compression: 'DEFLATE',
       compressionOptions: { level: 6 },
-    });
+    })
   }
 
   /**
@@ -248,7 +248,7 @@ class ZipManager {
       compression: 'DEFLATE',
       compressionOptions: { level: 6 },
       streamFiles: true,
-    });
+    })
   }
 
   /**
@@ -258,7 +258,7 @@ class ZipManager {
    * @returns {string|undefined}
    */
   getCoreProperty(key) {
-    return this.#coreProperties.get(key);
+    return this.#coreProperties.get(key)
   }
 
   /**
@@ -269,7 +269,7 @@ class ZipManager {
    * @param {string} value - Property value.
    */
   setCoreProperty(key, value) {
-    this.#coreProperties.set(key, value);
+    this.#coreProperties.set(key, value)
   }
 
   /**
@@ -277,14 +277,14 @@ class ZipManager {
    * @private
    */
   async #loadCoreProperties() {
-    const coreXml = await this.readFile('docProps/core.xml');
-    if (!coreXml) return;
+    const coreXml = await this.readFile('docProps/core.xml')
+    if (!coreXml) return
 
     // Simple regex extraction for core properties (lightweight vs full parse)
-    const propPattern = /<(dc:[a-zA-Z]+|dcterms:[a-zA-Z]+)[^>]*>([^<]*)<\/\1>/g;
-    let match;
+    const propPattern = /<(dc:[a-zA-Z]+|dcterms:[a-zA-Z]+)[^>]*>([^<]*)<\/\1>/g
+    let match
     while ((match = propPattern.exec(coreXml)) !== null) {
-      this.#coreProperties.set(match[1], match[2]);
+      this.#coreProperties.set(match[1], match[2])
     }
   }
 
@@ -293,8 +293,8 @@ class ZipManager {
    * @returns {JSZip}
    */
   get rawZip() {
-    return this.#zip;
+    return this.#zip
   }
 }
 
-module.exports = { ZipManager };
+module.exports = { ZipManager }