node-pptx-templater 1.0.2 → 1.0.4

package/src/managers/ImageManager.js

@@ -0,0 +1,336 @@
+/**
+ * @fileoverview ImageManager - Manages slide-level image operations like replace, add, remove, and list.
+ */
+
+const { createLogger } = require('../utils/logger.js')
+const { PPTXError } = require('../utils/errors.js')
+const { REL_TYPES } = require('./RelationshipManager.js')
+
+const logger = createLogger('ImageManager')
+
+/**
+ * @class ImageManager
+ * @description Manages image elements and relationships on individual slides.
+ */
+class ImageManager {
+  /** @private @type {XMLParser} */
+  #xmlParser
+
+  /**
+   * @param {XMLParser} xmlParser
+   */
+  constructor(xmlParser) {
+    this.#xmlParser = xmlParser
+  }
+
+  /**
+   * Replaces an existing image on a slide.
+   *
+   * @param {number} slideIndex
+   * @param {string} imageIdOrName - Shape name or shape ID.
+   * @param {string|Buffer} sourcePathOrBuffer - New image source path or Buffer.
+   * @param {SlideManager} slideManager
+   * @param {MediaManager} mediaManager
+   * @param {RelationshipManager} relationshipManager
+   */
+  async replaceImage(
+    slideIndex,
+    imageIdOrName,
+    sourcePathOrBuffer,
+    slideManager,
+    mediaManager,
+    relationshipManager
+  ) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+    const picRes = this.#findPicRecursive(spTree, imageIdOrName)
+
+    if (!picRes) {
+      throw new PPTXError(`Image shape "${imageIdOrName}" not found on slide ${slideIndex}`)
+    }
+
+    const rId = picRes.pic?.['p:blipFill']?.['a:blip']?.['@_r:embed']
+    if (!rId) {
+      throw new PPTXError(`No relationship ID found on image shape "${imageIdOrName}"`)
+    }
+
+    // Embed the new image bytes
+    const destMediaZipPath = await mediaManager.embedImage(sourcePathOrBuffer)
+    const relativeTarget = `../media/${destMediaZipPath.split('/').pop()}`
+
+    // Update relationship target path
+    const slideInfo = slideManager.getSlideInfo(slideIndex)
+    relationshipManager.updateRelationshipTarget(slideInfo.zipPath, rId, relativeTarget)
+
+    logger.debug(`Replaced image "${imageIdOrName}" target with "${relativeTarget}"`)
+  }
+
+  /**
+   * Adds a new image to a slide.
+   *
+   * @param {number} slideIndex
+   * @param {string|Buffer} sourcePathOrBuffer
+   * @param {Object} options - Position options (x, y, width, height in EMUs or inches).
+   * @param {SlideManager} slideManager
+   * @param {MediaManager} mediaManager
+   * @param {RelationshipManager} relationshipManager
+   */
+  async addImage(
+    slideIndex,
+    sourcePathOrBuffer,
+    options = {},
+    slideManager,
+    mediaManager,
+    relationshipManager
+  ) {
+    const slideInfo = slideManager.getSlideInfo(slideIndex)
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+
+    if (!spTree) {
+      throw new PPTXError(`Invalid slide structure for slide ${slideIndex}`)
+    }
+
+    // Embed the image
+    const destMediaZipPath = await mediaManager.embedImage(sourcePathOrBuffer)
+    const relativeTarget = `../media/${destMediaZipPath.split('/').pop()}`
+
+    // Add relationship
+    const rId = relationshipManager.addRelationship(
+      slideInfo.zipPath,
+      REL_TYPES.IMAGE,
+      relativeTarget
+    )
+
+    // Generate unique shape ID
+    const existingIds = this.#getAllShapeIds(spTree)
+    const maxId = existingIds.length > 0 ? Math.max(...existingIds) : 1000
+    const newId = maxId + 1
+
+    // Convert positions
+    const x =
+      options.x === undefined
+        ? 0
+        : options.x < 100
+          ? Math.round(options.x * 914400)
+          : Math.round(options.x)
+    const y =
+      options.y === undefined
+        ? 0
+        : options.y < 100
+          ? Math.round(options.y * 914400)
+          : Math.round(options.y)
+    const cx =
+      options.width === undefined
+        ? 2743200
+        : options.width < 100
+          ? Math.round(options.width * 914400)
+          : Math.round(options.width)
+    const cy =
+      options.height === undefined
+        ? 1828800
+        : options.height < 100
+          ? Math.round(options.height * 914400)
+          : Math.round(options.height)
+    const name = options.name || `Picture ${newId}`
+
+    // Build the pic XML snippet using mediaManager's builder and parse it
+    const picXml = mediaManager.buildImageXml(rId, {
+      x,
+      y,
+      width: cx,
+      height: cy,
+      name,
+      shapeId: newId,
+    })
+    const picObj = this.#xmlParser.parse(picXml, 'pic.xml')['p:pic']
+
+    if (!spTree['p:pic']) {
+      spTree['p:pic'] = []
+    }
+    if (!Array.isArray(spTree['p:pic'])) {
+      spTree['p:pic'] = [spTree['p:pic']]
+    }
+    spTree['p:pic'].push(picObj)
+
+    const decl = this.#xmlParser.extractDeclaration(slideXml)
+    slideManager.setSlideXml(slideIndex, this.#xmlParser.build(slideObj, decl))
+    logger.debug(`Added image "${name}" with ID ${newId} and rId ${rId} to slide ${slideIndex}`)
+  }
+
+  /**
+   * Removes an image from a slide.
+   *
+   * @param {number} slideIndex
+   * @param {string} imageIdOrName
+   * @param {SlideManager} slideManager
+   * @param {RelationshipManager} relationshipManager
+   */
+  removeImage(slideIndex, imageIdOrName, slideManager, relationshipManager) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+    const picRes = this.#findPicRecursive(spTree, imageIdOrName)
+
+    if (!picRes) {
+      throw new PPTXError(`Image shape "${imageIdOrName}" not found on slide ${slideIndex}`)
+    }
+
+    // Remove from shape list
+    const parent = picRes.parent
+    if (parent['p:pic']) {
+      if (Array.isArray(parent['p:pic'])) {
+        parent['p:pic'] = parent['p:pic'].filter(p => p !== picRes.pic)
+      } else if (parent['p:pic'] === picRes.pic) {
+        delete parent['p:pic']
+      }
+    }
+
+    // Remove relationship
+    const rId = picRes.pic?.['p:blipFill']?.['a:blip']?.['@_r:embed']
+    if (rId) {
+      const slideInfo = slideManager.getSlideInfo(slideIndex)
+      relationshipManager.removeRelationship(slideInfo.zipPath, rId)
+    }
+
+    const decl = this.#xmlParser.extractDeclaration(slideXml)
+    slideManager.setSlideXml(slideIndex, this.#xmlParser.build(slideObj, decl))
+    logger.debug(`Removed image "${imageIdOrName}" from slide ${slideIndex}`)
+  }
+
+  /**
+   * Enumerates all images on a slide.
+   *
+   * @param {number} slideIndex
+   * @param {SlideManager} slideManager
+   * @param {RelationshipManager} relationshipManager
+   * @returns {Array<Object>} List of image elements found.
+   */
+  getImages(slideIndex, slideManager, relationshipManager) {
+    const slideInfo = slideManager.getSlideInfo(slideIndex)
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+
+    const imagesInfo = []
+    this.#collectImagesInfo(spTree, slideInfo.zipPath, relationshipManager, imagesInfo)
+    return imagesInfo
+  }
+
+  #findPicRecursive(container, targetId) {
+    if (!container) return null
+
+    let pics = container['p:pic'] || []
+    if (!Array.isArray(pics)) pics = [pics]
+
+    for (const pic of pics) {
+      const cNvPr = pic?.['p:nvPicPr']?.['p:cNvPr']
+      if (cNvPr) {
+        const name = cNvPr['@_name']
+        const id = String(cNvPr['@_id'])
+        const embedId = pic?.['p:blipFill']?.['a:blip']?.['@_r:embed']
+        if (name === targetId || id === targetId || embedId === targetId) {
+          return { pic, parent: container }
+        }
+      }
+    }
+
+    let groups = container['p:grpSp'] || []
+    if (!Array.isArray(groups)) groups = [groups]
+    for (const group of groups) {
+      const res = this.#findPicRecursive(group, targetId)
+      if (res) return res
+    }
+
+    return null
+  }
+
+  #getAllShapeIds(container) {
+    const ids = []
+    if (!container) return ids
+
+    let shapes = container['p:sp'] || []
+    if (!Array.isArray(shapes)) shapes = [shapes]
+    for (const s of shapes) {
+      const id = parseInt(s?.['p:nvSpPr']?.['p:cNvPr']?.['@_id'], 10)
+      if (!isNaN(id)) ids.push(id)
+    }
+
+    let pics = container['p:pic'] || []
+    if (!Array.isArray(pics)) pics = [pics]
+    for (const p of pics) {
+      const id = parseInt(p?.['p:nvPicPr']?.['p:cNvPr']?.['@_id'], 10)
+      if (!isNaN(id)) ids.push(id)
+    }
+
+    let frames = container['p:graphicFrame'] || []
+    if (!Array.isArray(frames)) frames = [frames]
+    for (const f of frames) {
+      const id = parseInt(f?.['p:nvGraphicFramePr']?.['p:cNvPr']?.['@_id'], 10)
+      if (!isNaN(id)) ids.push(id)
+    }
+
+    let groups = container['p:grpSp'] || []
+    if (!Array.isArray(groups)) groups = [groups]
+    for (const g of groups) {
+      const id = parseInt(g?.['p:nvGrpSpPr']?.['p:cNvPr']?.['@_id'], 10)
+      if (!isNaN(id)) ids.push(id)
+      ids.push(...this.#getAllShapeIds(g))
+    }
+
+    return ids
+  }
+
+  #collectImagesInfo(container, slideZipPath, relationshipManager, results) {
+    if (!container) return
+
+    let pics = container['p:pic'] || []
+    if (!Array.isArray(pics)) pics = [pics]
+
+    for (const pic of pics) {
+      const cNvPr = pic?.['p:nvPicPr']?.['p:cNvPr']
+      if (!cNvPr) continue
+
+      const name = cNvPr['@_name']
+      const id = String(cNvPr['@_id'])
+
+      const rId = pic?.['p:blipFill']?.['a:blip']?.['@_r:embed']
+      let targetPath = ''
+      if (rId) {
+        const rel = relationshipManager.getRelationshipById(slideZipPath, rId)
+        if (rel) {
+          targetPath = relationshipManager.resolveTarget(slideZipPath, rel.target)
+        }
+      }
+
+      const xfrm = pic['p:spPr']?.['a:xfrm']
+      const position = xfrm
+        ? {
+            x: parseInt(xfrm['a:off']?.['@_x'] || 0, 10),
+            y: parseInt(xfrm['a:off']?.['@_y'] || 0, 10),
+            cx: parseInt(xfrm['a:ext']?.['@_cx'] || 0, 10),
+            cy: parseInt(xfrm['a:ext']?.['@_cy'] || 0, 10),
+          }
+        : null
+
+      results.push({
+        type: 'image',
+        id,
+        name,
+        relationshipId: rId,
+        targetPath,
+        position,
+      })
+    }
+
+    let groups = container['p:grpSp'] || []
+    if (!Array.isArray(groups)) groups = [groups]
+    for (const g of groups) {
+      this.#collectImagesInfo(g, slideZipPath, relationshipManager, results)
+    }
+  }
+}
+
+module.exports = { ImageManager }

package/src/managers/MediaManager.js

@@ -36,31 +36,12 @@
  *   Audio: MP3, WAV, M4A
  */
 
-const { createHash } = require('crypto');
-const { createLogger } = require('../utils/logger.js');
-const { PPTXError } = require('../utils/errors.js');
-const { REL_TYPES } = require('./RelationshipManager.js');
-const fsExtra = require('fs-extra');
+const { createHash } = require('crypto')
+const { createLogger } = require('../utils/logger.js')
+const { PPTXError } = require('../utils/errors.js')
+const fsExtra = require('fs-extra')
 
-const logger = createLogger('MediaManager');
-
-/**
- * MIME type to extension mapping for media files.
- */
-const MEDIA_TYPES = {
-  'image/png': 'png',
-  'image/jpeg': 'jpeg',
-  'image/jpg': 'jpg',
-  'image/gif': 'gif',
-  'image/svg+xml': 'svg',
-  'image/tiff': 'tiff',
-  'image/bmp': 'bmp',
-  'image/x-wmf': 'wmf',
-  'image/x-emf': 'emf',
-  'image/webp': 'webp',
-  'video/mp4': 'mp4',
-  'audio/mpeg': 'mp3',
-};
+const logger = createLogger('MediaManager')
 
 /**
  * Extension to MIME type mapping.
@@ -78,7 +59,7 @@ const EXT_TO_MIME = {
   webp: 'image/webp',
   mp4: 'video/mp4',
   mp3: 'audio/mpeg',
-};
+}
 
 /**
  * @class MediaManager
@@ -86,34 +67,34 @@ const EXT_TO_MIME = {
  */
 class MediaManager {
   /** @private @type {ContentTypesManager} */
-  #contentTypesManager;
+  #contentTypesManager
   /** @private @type {ZipManager} */
-  #zipManager;
+  #zipManager
 
   /**
    * @param {ContentTypesManager} contentTypesManager
    */
   constructor(contentTypesManager) {
-    this.#contentTypesManager = contentTypesManager;
+    this.#contentTypesManager = contentTypesManager
   }
 
   /**
    * Content hash → existing media ZIP path for deduplication.
    * @private @type {Map<string, string>}
    */
-  #mediaHashIndex = new Map();
+  #mediaHashIndex = new Map()
 
   /**
    * All known media files.
    * @private @type {Map<string, MediaInfo>}
    */
-  #mediaRegistry = new Map();
+  #mediaRegistry = new Map()
 
   /**
    * Counter for generating unique media file names.
    * @private @type {number}
    */
-  #nextMediaId = 1;
+  #nextMediaId = 1
 
   /**
    * Initializes by scanning existing media files in the PPTX.
@@ -122,33 +103,33 @@ class MediaManager {
    * @returns {Promise<void>}
    */
   async initialize(zipManager) {
-    this.#zipManager = zipManager;
-    const mediaFiles = zipManager.listFiles('ppt/media/');
+    this.#zipManager = zipManager
+    const mediaFiles = zipManager.listFiles('ppt/media/')
 
     // Index all existing media files by content hash for deduplication
     await Promise.all(
       mediaFiles.map(async mediaPath => {
-        const data = await zipManager.readBinaryFile(mediaPath);
+        const data = await zipManager.readBinaryFile(mediaPath)
         if (data) {
-          const hash = this.#hashBytes(data);
-          const ext = mediaPath.split('.').pop().toLowerCase();
-          const mimeType = EXT_TO_MIME[ext] || 'application/octet-stream';
+          const hash = this.#hashBytes(data)
+          const ext = mediaPath.split('.').pop().toLowerCase()
+          const mimeType = EXT_TO_MIME[ext] || 'application/octet-stream'
 
-          const mediaInfo = { zipPath: mediaPath, hash, mimeType, size: data.length };
-          this.#mediaHashIndex.set(hash, mediaPath);
-          this.#mediaRegistry.set(mediaPath, mediaInfo);
+          const mediaInfo = { zipPath: mediaPath, hash, mimeType, size: data.length }
+          this.#mediaHashIndex.set(hash, mediaPath)
+          this.#mediaRegistry.set(mediaPath, mediaInfo)
 
           // Track the highest media ID to avoid collisions
-          const numMatch = /\d+/.exec(mediaPath.split('/').pop());
+          const numMatch = /\d+/.exec(mediaPath.split('/').pop())
           if (numMatch) {
-            const num = parseInt(numMatch[0], 10);
-            if (num >= this.#nextMediaId) this.#nextMediaId = num + 1;
+            const num = parseInt(numMatch[0], 10)
+            if (num >= this.#nextMediaId) this.#nextMediaId = num + 1
           }
         }
       })
-    );
+    )
 
-    logger.debug(`Indexed ${this.#mediaRegistry.size} media file(s)`);
+    logger.debug(`Indexed ${this.#mediaRegistry.size} media file(s)`)
   }
 
   /**
@@ -156,7 +137,7 @@ class MediaManager {
    * @returns {number}
    */
   get mediaCount() {
-    return this.#mediaRegistry.size;
+    return this.#mediaRegistry.size
   }
 
   /**
@@ -169,44 +150,44 @@ class MediaManager {
    * @returns {Promise<string>} ZIP path of the embedded image (e.g., 'ppt/media/image5.png').
    */
   async embedImage(source, mimeType) {
-    let data;
-    let ext;
+    let data
+    let ext
 
     if (typeof source === 'string') {
       // Load from file path
-      data = await fsExtra.readFile(source);
-      ext = source.split('.').pop().toLowerCase();
-      mimeType = mimeType || EXT_TO_MIME[ext] || 'image/png';
+      data = await fsExtra.readFile(source)
+      ext = source.split('.').pop().toLowerCase()
+      mimeType = mimeType || EXT_TO_MIME[ext] || 'image/png'
     } else if (Buffer.isBuffer(source) || source instanceof Uint8Array) {
-      data = source;
+      data = source
       // Detect format from magic bytes
-      ext = this.#detectExtension(data);
-      mimeType = mimeType || EXT_TO_MIME[ext] || 'image/png';
+      ext = this.#detectExtension(data)
+      mimeType = mimeType || EXT_TO_MIME[ext] || 'image/png'
     } else {
-      throw new PPTXError('embedImage: source must be a file path string or Buffer');
+      throw new PPTXError('embedImage: source must be a file path string or Buffer')
     }
 
     // Check for duplicate (content-addressable dedup)
-    const hash = this.#hashBytes(data);
+    const hash = this.#hashBytes(data)
     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 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}`;
+    const mediaId = this.#nextMediaId++
+    const zipPath = `ppt/media/image${mediaId}.${ext}`
 
-    this.#zipManager.writeBinaryFile(zipPath, data);
-    this.#mediaHashIndex.set(hash, zipPath);
-    this.#mediaRegistry.set(zipPath, { zipPath, hash, mimeType, size: data.length });
+    this.#zipManager.writeBinaryFile(zipPath, data)
+    this.#mediaHashIndex.set(hash, zipPath)
+    this.#mediaRegistry.set(zipPath, { zipPath, hash, mimeType, size: data.length })
 
     // Register content type
-    this.#registerContentType(ext, mimeType);
+    this.#registerContentType(ext, mimeType)
 
-    logger.debug(`Embedded new media: ${zipPath} (${data.length} bytes)`);
-    return zipPath;
+    logger.debug(`Embedded new media: ${zipPath} (${data.length} bytes)`)
+    return zipPath
   }
 
   /**
@@ -223,7 +204,7 @@ class MediaManager {
    * @returns {string} XML snippet for the image.
    */
   buildImageXml(rId, opts) {
-    const { x = 0, y = 0, width = 2743200, height = 1828800, name = 'image', shapeId = 1 } = opts;
+    const { x = 0, y = 0, width = 2743200, height = 1828800, name = 'image', shapeId = 1 } = opts
 
     return `<p:pic>
   <p:nvPicPr>
@@ -244,7 +225,7 @@ class MediaManager {
     </a:xfrm>
     <a:prstGeom prst="rect"><a:avLst/></a:prstGeom>
   </p:spPr>
-</p:pic>`;
+</p:pic>`
   }
 
   /**
@@ -254,7 +235,7 @@ class MediaManager {
    * @returns {MediaInfo|undefined}
    */
   getMediaInfo(zipPath) {
-    return this.#mediaRegistry.get(zipPath);
+    return this.#mediaRegistry.get(zipPath)
   }
 
   /**
@@ -262,7 +243,7 @@ class MediaManager {
    * @returns {MediaInfo[]}
    */
   getAllMedia() {
-    return Array.from(this.#mediaRegistry.values());
+    return Array.from(this.#mediaRegistry.values())
   }
 
   /**
@@ -274,7 +255,7 @@ class MediaManager {
    * @returns {string} Hex digest.
    */
   #hashBytes(data) {
-    return createHash('sha1').update(data).digest('hex');
+    return createHash('sha1').update(data).digest('hex')
   }
 
   /**
@@ -285,25 +266,25 @@ class MediaManager {
    * @returns {string} File extension.
    */
   #detectExtension(data) {
-    const sig = data.slice(0, 8);
+    const sig = data.slice(0, 8)
 
     // PNG: 89 50 4E 47 0D 0A 1A 0A
-    if (sig[0] === 0x89 && sig[1] === 0x50) return 'png';
+    if (sig[0] === 0x89 && sig[1] === 0x50) return 'png'
     // JPEG: FF D8 FF
-    if (sig[0] === 0xFF && sig[1] === 0xD8) return 'jpg';
+    if (sig[0] === 0xff && sig[1] === 0xd8) return 'jpg'
     // GIF: 47 49 46
-    if (sig[0] === 0x47 && sig[1] === 0x49) return 'gif';
+    if (sig[0] === 0x47 && sig[1] === 0x49) return 'gif'
     // WEBP: 52 49 46 46 ... 57 45 42 50
-    if (sig[0] === 0x52 && sig[1] === 0x49 && sig[8] === 0x57) return 'webp';
+    if (sig[0] === 0x52 && sig[1] === 0x49 && sig[8] === 0x57) return 'webp'
     // BMP: 42 4D
-    if (sig[0] === 0x42 && sig[1] === 0x4D) return 'bmp';
+    if (sig[0] === 0x42 && sig[1] === 0x4d) return 'bmp'
 
-    return 'png'; // Default fallback
+    return 'png' // Default fallback
   }
 
   #registerContentType(ext, mimeType) {
-    this.#contentTypesManager.addDefault(ext, mimeType);
+    this.#contentTypesManager.addDefault(ext, mimeType)
   }
 }
 
-module.exports = { MediaManager };
+module.exports = { MediaManager }