node-pptx-templater 1.0.0

package/src/core/TemplateEngine.js

@@ -0,0 +1,321 @@
+/**
+ * @fileoverview TemplateEngine - Text placeholder replacement engine.
+ *
+ * Handles {{placeholder}} replacement in slide XML.
+ *
+ * Challenge with OpenXML text replacement:
+ * ─────────────────────────────────────────────────────────────────
+ * A simple string "{{title}}" in PowerPoint might be split across
+ * MULTIPLE text run elements in the XML:
+ *
+ *   <a:r><a:t>{{ti</a:t></a:r>
+ *   <a:r><a:t>tle}}</a:t></a:r>
+ *
+ * This happens because PowerPoint splits text runs when:
+ *  - Spell-check marks parts of the text
+ *  - Font formatting changes mid-word
+ *  - The text was typed in multiple sessions
+ *
+ * Solution Strategy:
+ * 1. Extract all <a:r><a:t>...</a:t></a:r> run sequences within each <a:p>
+ * 2. Concatenate run text to find the full combined text
+ * 3. Check if the combined text contains any placeholder
+ * 4. If yes: merge all runs into a single run with replaced text,
+ *    preserving the formatting of the FIRST run as the template
+ *
+ * This "text normalization" approach correctly handles fragmented placeholders.
+ */
+
+import { createLogger } from '../utils/logger.js';
+
+const logger = createLogger('TemplateEngine');
+
+/**
+ * Default placeholder pattern: {{key}}
+ * Can be overridden per-call.
+ */
+const DEFAULT_PLACEHOLDER_PATTERN = /\{\{([^{}]+)\}\}/g;
+
+/**
+ * @class TemplateEngine
+ * @description Handles text placeholder replacement in OpenXML slide XML.
+ *
+ * Implements the text-normalization strategy to handle fragmented placeholders.
+ */
+export class TemplateEngine {
+  /** @private @type {XMLParser} */
+  #xmlParser;
+
+  /**
+   * @param {XMLParser} xmlParser
+   */
+  constructor(xmlParser) {
+    this.#xmlParser = xmlParser;
+  }
+
+  /**
+   * Replaces all placeholders in a slide XML string.
+   * Uses the text-normalization strategy to handle fragmented text runs.
+   *
+   * @param {string} slideXml - Raw slide XML.
+   * @param {Object.<string, string>} replacements - Placeholder → value map.
+   * @param {RegExp} [pattern] - Custom placeholder pattern. Defaults to {{key}}.
+   * @returns {string} Modified slide XML with placeholders replaced.
+   *
+   * @example
+   * const updated = engine.replaceTextInXml(slideXml, {
+   *   '{{name}}': 'John Doe',
+   *   '{{date}}': '2026-01-01'
+   * });
+   */
+  replaceTextInXml(slideXml, replacements, pattern = DEFAULT_PLACEHOLDER_PATTERN) {
+    if (!replacements || Object.keys(replacements).length === 0) {
+      return slideXml;
+    }
+
+    logger.debug(`Replacing ${Object.keys(replacements).length} placeholder(s)`);
+
+    // Step 1: Process paragraph by paragraph to handle fragmented runs
+    let updated = this.#processParagraphs(slideXml, replacements);
+
+    // Step 2: Simple direct replacement for any remaining unfragmented placeholders
+    for (const [placeholder, value] of Object.entries(replacements)) {
+      const escaped = this.#escapeXml(String(value));
+      const placeholderEscaped = this.#escapeXml(placeholder);
+
+      // Replace the XML-escaped form (e.g., {{name}} as {{name}})
+      updated = updated.split(placeholderEscaped).join(escaped);
+      // Replace the plain form (in case it's not escaped in the XML)
+      updated = updated.split(placeholder).join(escaped);
+    }
+
+    return updated;
+  }
+
+  /**
+   * Processes all paragraphs (<a:p>) in the slide XML, normalizing text runs
+   * within each paragraph to fix fragmented placeholders.
+   *
+   * @private
+   * @param {string} slideXml
+   * @param {Object.<string, string>} replacements
+   * @returns {string}
+   */
+  #processParagraphs(slideXml, replacements) {
+    // Find all <a:p>...</a:p> paragraphs
+    let updated = slideXml;
+    let offset = 0;
+
+    const paragraphPattern = /<a:p>([\s\S]*?)<\/a:p>/g;
+    let match;
+
+    while ((match = paragraphPattern.exec(slideXml)) !== null) {
+      const paragraphXml = match[0];
+      const processedParagraph = this.#processParagraph(paragraphXml, replacements);
+
+      if (processedParagraph !== paragraphXml) {
+        // Replace in the updated string (adjust for offset changes)
+        const start = updated.indexOf(paragraphXml, match.index + offset - (match.index));
+
+        // More reliable: replace from the beginning of the current search area
+        updated = updated.substring(0, match.index + offset) +
+          processedParagraph +
+          updated.substring(match.index + offset + paragraphXml.length);
+
+        offset += processedParagraph.length - paragraphXml.length;
+      }
+    }
+
+    return updated;
+  }
+
+  /**
+   * Processes a single paragraph, normalizing runs and replacing placeholders.
+   *
+   * @private
+   * @param {string} paragraphXml - XML of a single <a:p> element.
+   * @param {Object.<string, string>} replacements
+   * @returns {string} Updated paragraph XML.
+   */
+  #processParagraph(paragraphXml, replacements) {
+    // Extract all text runs from this paragraph
+    const runs = this.#extractRuns(paragraphXml);
+
+    if (runs.length === 0) return paragraphXml;
+
+    // Combine text from all runs
+    const combinedText = runs.map(r => r.text).join('');
+
+    // Check if any placeholder appears in the combined text
+    let hasPlaceholder = false;
+    for (const placeholder of Object.keys(replacements)) {
+      if (combinedText.includes(placeholder)) {
+        hasPlaceholder = true;
+        break;
+      }
+    }
+
+    if (!hasPlaceholder) return paragraphXml;
+
+    // Perform replacement on combined text
+    let replacedText = combinedText;
+    for (const [placeholder, value] of Object.entries(replacements)) {
+      replacedText = replacedText.split(placeholder).join(String(value));
+    }
+
+    // Rebuild the paragraph: merge all runs into a single run using first run's format
+    return this.#mergeRunsWithText(paragraphXml, runs, replacedText);
+  }
+
+  /**
+   * Extracts all text runs from a paragraph's XML.
+   * Returns run XML and the extracted text content.
+   *
+   * @private
+   * @param {string} paragraphXml
+   * @returns {Array<{xml: string, text: string, start: number, end: number}>}
+   */
+  #extractRuns(paragraphXml) {
+    const runs = [];
+    const runPattern = /(<a:r(?:\s[^>]*)?>)([\s\S]*?)(<\/a:r>)/g;
+    let match;
+
+    while ((match = runPattern.exec(paragraphXml)) !== null) {
+      const runXml = match[0];
+      // Extract text from <a:t>...</a:t> within this run
+      const tMatch = /<a:t>([\s\S]*?)<\/a:t>/.exec(runXml);
+      const text = tMatch ? this.#unescapeXml(tMatch[1]) : '';
+
+      runs.push({
+        xml: runXml,
+        text,
+        start: match.index,
+        end: match.index + runXml.length,
+      });
+    }
+
+    return runs;
+  }
+
+  /**
+   * Merges all runs in a paragraph into a single run using the first run's
+   * formatting as the template, with the replaced text as content.
+   *
+   * @private
+   * @param {string} paragraphXml
+   * @param {Array} runs - Extracted run info.
+   * @param {string} newText - New text to inject.
+   * @returns {string} Updated paragraph XML.
+   */
+  #mergeRunsWithText(paragraphXml, runs, newText) {
+    if (runs.length === 0) return paragraphXml;
+
+    // Use the first run as the format template
+    const firstRun = runs[0];
+
+    // Build the replacement run: first run's format + new text
+    const mergedRunXml = this.#setRunText(firstRun.xml, this.#escapeXml(newText));
+
+    // Build new paragraph:
+    // Keep everything before first run, insert merged run, remove the rest,
+    // keep everything after last run
+    const firstRunStart = firstRun.start;
+    const lastRunEnd = runs[runs.length - 1].end;
+
+    return (
+      paragraphXml.substring(0, firstRunStart) +
+      mergedRunXml +
+      paragraphXml.substring(lastRunEnd)
+    );
+  }
+
+  /**
+   * Replaces the text content of a text run XML.
+   *
+   * @private
+   * @param {string} runXml - Run XML string.
+   * @param {string} text - New text content (already XML-escaped).
+   * @returns {string} Updated run XML.
+   */
+  #setRunText(runXml, text) {
+    const tPattern = /(<a:t>)([\s\S]*?)(<\/a:t>)/;
+    if (tPattern.test(runXml)) {
+      return runXml.replace(tPattern, `$1${text}$3`);
+    }
+    // If no <a:t>, add one before </a:r>
+    return runXml.replace('</a:r>', `<a:t>${text}</a:t></a:r>`);
+  }
+
+  /**
+   * Checks if a string contains any placeholder from the map.
+   *
+   * @param {string} text
+   * @param {Object.<string, string>} replacements
+   * @returns {boolean}
+   */
+  containsPlaceholders(text, replacements) {
+    return Object.keys(replacements).some(p => text.includes(p));
+  }
+
+  /**
+   * Extracts all unique placeholder keys from an XML string.
+   *
+   * @param {string} xml - Slide XML.
+   * @param {RegExp} [pattern] - Placeholder pattern.
+   * @returns {string[]} Array of placeholder keys found.
+   *
+   * @example
+   * engine.extractPlaceholders(slideXml);
+   * // → ['{{title}}', '{{date}}', '{{company}}']
+   */
+  extractPlaceholders(xml, pattern = DEFAULT_PLACEHOLDER_PATTERN) {
+    const placeholders = new Set();
+    const textPattern = /<a:t>([\s\S]*?)<\/a:t>/g;
+    let match;
+
+    // Extract text content first, then find placeholders
+    const allText = [];
+    while ((match = textPattern.exec(xml)) !== null) {
+      allText.push(match[1]);
+    }
+
+    const combined = allText.join('');
+    const plPattern = new RegExp(pattern.source, 'g');
+    let plMatch;
+    while ((plMatch = plPattern.exec(combined)) !== null) {
+      placeholders.add(plMatch[0]);
+    }
+
+    return Array.from(placeholders);
+  }
+
+  /**
+   * Escapes XML special characters.
+   * @private
+   * @param {string} str
+   * @returns {string}
+   */
+  #escapeXml(str) {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+  }
+
+  /**
+   * Unescapes XML entities.
+   * @private
+   * @param {string} str
+   * @returns {string}
+   */
+  #unescapeXml(str) {
+    return str
+      .replace(/&amp;/g, '&')
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'");
+  }
+}

package/src/index.js

@@ -0,0 +1,43 @@
+/**
+ * node-pptx-templater
+ *
+ * A low-level PowerPoint OpenXML templating engine for Node.js.
+ * Generates and edits PPTX files directly through XML manipulation
+ * without relying on PowerPoint generation libraries.
+ *
+ * @module node-pptx-templater
+ * @author node-pptx-templater contributors
+ * @license MIT
+ *
+ * Architecture Overview:
+ * ┌─────────────────────────────────────────────────────────────┐
+ * │                   PPTXTemplater                        │
+ * │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
+ * │  │ZipManager│  │XMLParser │  │SlideManager│ │ChartMgr  │  │
+ * │  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
+ * │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
+ * │  │TableMgr  │  │HyperlinkMgr│ │MediaMgr  │  │RelMgr    │  │
+ * │  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
+ * │                   ┌──────────────┐                         │
+ * │                   │OutputWriter  │                         │
+ * │                   └──────────────┘                         │
+ * └─────────────────────────────────────────────────────────────┘
+ */
+
+export { PPTXTemplater } from './core/PPTXTemplater.js';
+export { ZipManager } from './managers/ZipManager.js';
+export { XMLParser } from './parsers/XMLParser.js';
+export { SlideManager } from './managers/SlideManager.js';
+export { ChartManager } from './managers/ChartManager.js';
+export { TableManager } from './managers/TableManager.js';
+export { HyperlinkManager } from './managers/HyperlinkManager.js';
+export { MediaManager } from './managers/MediaManager.js';
+export { RelationshipManager } from './managers/RelationshipManager.js';
+export { OutputWriter } from './core/OutputWriter.js';
+export { TemplateEngine } from './core/TemplateEngine.js';
+
+// Utility exports
+export { generateRelationshipId, parseRelationshipId } from './utils/relationshipUtils.js';
+export { validateXML, repairXML } from './utils/xmlUtils.js';
+export { createLogger } from './utils/logger.js';
+export { PPTXError, SlideNotFoundError, ChartNotFoundError, TableNotFoundError } from './utils/errors.js';

package/src/managers/ChartManager.js

@@ -0,0 +1,317 @@
+/**
+ * @fileoverview ChartManager - Updates chart data in PPTX slides.
+ *
+ * Charts in OpenXML PPTX:
+ * ─────────────────────────────────────────────────────────────────
+ * Charts are embedded as separate XML files referenced via relationships.
+ * A chart on a slide appears as:
+ *
+ *   <p:graphicFrame>
+ *     <p:nvGraphicFramePr>
+ *       <p:cNvPr id="5" name="sales-chart"/>    ← chart name/ID
+ *     </p:nvGraphicFramePr>
+ *     <a:graphic>
+ *       <a:graphicData uri="...chart">
+ *         <c:chart r:id="rId5"/>                ← references chart XML
+ *       </a:graphicData>
+ *     </a:graphic>
+ *   </p:graphicFrame>
+ *
+ * The chart XML at ppt/charts/chartN.xml contains:
+ *  - c:chartSpace → root element
+ *    - c:chart → chart metadata
+ *      - c:plotArea → chart data
+ *        - c:barChart / c:lineChart / c:pieChart / etc.
+ *          - c:ser → each data series
+ *            - c:idx / c:order → series index/order
+ *            - c:tx → series name
+ *            - c:cat → categories (X-axis)
+ *            - c:val → values (Y-axis)
+ *
+ * Category Reference Types:
+ *  - c:strRef  → string categories (labels)
+ *  - c:numRef  → numeric categories
+ *
+ * Value Reference Types:
+ *  - c:numRef  → numeric values (typical)
+ *
+ * Data is stored in both a formula (c:f) and a cache (c:strCache/c:numCache).
+ * We update both to ensure compatibility with both cached and live data.
+ */
+
+import { createLogger } from '../utils/logger.js';
+import { ChartNotFoundError } from '../utils/errors.js';
+import { REL_TYPES } from './RelationshipManager.js';
+import { ChartWorkbookUpdater } from './charts/ChartWorkbookUpdater.js';
+import { ChartCacheGenerator } from './charts/ChartCacheGenerator.js';
+
+const logger = createLogger('ChartManager');
+
+/**
+ * Supported chart types and their XML element names.
+ */
+const CHART_TYPE_MAP = {
+  bar: 'c:barChart',
+  line: 'c:lineChart',
+  pie: 'c:pieChart',
+  area: 'c:areaChart',
+  scatter: 'c:scatterChart',
+  doughnut: 'c:doughnutChart',
+  radar: 'c:radarChart',
+  bubble: 'c:bubbleChart',
+  stock: 'c:stockChart',
+};
+
+/**
+ * @class ChartManager
+ * @description Handles chart data updates by directly manipulating chart XML files.
+ *
+ * Unlike high-level charting libraries, this manager edits the raw OpenXML
+ * chart structure, allowing full control while preserving styles and themes.
+ */
+export class ChartManager {
+  /** @private @type {XMLParser} */
+  #xmlParser;
+  /** @private @type {ZipManager} */
+  #zipManager;
+
+  /**
+   * Cache of chart ZIP paths: maps chartName → { zipPath, slideIndex }
+   * @private @type {Map<string, { zipPath: string, slideIndex: number }>}
+   */
+  #chartRegistry = new Map();
+
+  /**
+   * @param {XMLParser} xmlParser
+   */
+  constructor(xmlParser) {
+    this.#xmlParser = xmlParser;
+  }
+
+  /**
+   * Initializes by scanning the ZIP for chart files.
+   *
+   * @param {ZipManager} zipManager
+   * @returns {Promise<void>}
+   */
+  async initialize(zipManager) {
+    this.#zipManager = zipManager;
+    const chartFiles = zipManager.listFiles('ppt/charts/').filter(f => f.endsWith('.xml') && !f.includes('_rels'));
+
+    for (const chartPath of chartFiles) {
+      // Chart name is inferred from file name
+      const chartName = chartPath.split('/').pop().replace('.xml', '');
+      this.#chartRegistry.set(chartName, { zipPath: chartPath, slideIndex: null });
+    }
+
+    logger.debug(`Found ${chartFiles.length} chart file(s)`);
+  }
+
+  /**
+   * Updates chart data for a named chart within a slide.
+   *
+   * @param {number} slideIndex - 1-based slide index.
+   * @param {string} chartId - Chart name (from shape's cNvPr name attribute) or chart file name.
+   * @param {ChartData} data - New chart data.
+   * @param {SlideManager} slideManager
+   * @param {RelationshipManager} relationshipManager
+   * @throws {ChartNotFoundError} If the chart cannot be found.
+   */
+  updateChart(slideIndex, chartId, data, slideManager, relationshipManager) {
+    const chartInfo = this.#findChartInSlide(slideIndex, chartId, slideManager, relationshipManager);
+
+    if (!chartInfo) {
+      throw new ChartNotFoundError(`Chart "${chartId}" not found in slide ${slideIndex}`);
+    }
+
+    logger.debug(`Updating chart "${chartId}" at ${chartInfo.zipPath}`);
+    this.#updateChartXml(chartInfo.zipPath, data, relationshipManager);
+  }
+
+  /**
+   * Returns all chart info objects for a given slide.
+   *
+   * @param {number} slideIndex
+   * @param {SlideManager} slideManager
+   * @param {RelationshipManager} relationshipManager
+   * @returns {Array<{name: string, zipPath: string}>}
+   */
+  getChartsInSlide(slideIndex, slideManager, relationshipManager) {
+    const slideInfo = slideManager.getSlideInfo(slideIndex);
+    const rels = relationshipManager.getRelationshipsByType(slideInfo.zipPath, REL_TYPES.CHART);
+
+    return rels.map(rel => {
+      const chartPath = relationshipManager.resolveTarget(slideInfo.zipPath, rel.target);
+      return { rId: rel.id, zipPath: chartPath };
+    });
+  }
+
+  /**
+   * Finds a chart in a slide by name/ID.
+   * @private
+   *
+   * @param {number} slideIndex
+   * @param {string} chartId - Shape name or rId.
+   * @param {SlideManager} slideManager
+   * @param {RelationshipManager} relationshipManager
+   * @returns {{ zipPath: string }|null}
+   */
+  #findChartInSlide(slideIndex, chartId, slideManager, relationshipManager) {
+    const slideInfo = slideManager.getSlideInfo(slideIndex);
+    const slideXml = slideManager.getSlideXml(slideIndex);
+
+    // Strategy 1: Look for shape with matching name (cNvPr name attribute)
+    const shapeNamePattern = new RegExp(
+      `<p:cNvPr[^>]*name="${chartId}"[^>]*>(?:.*?)<c:chart[^>]*r:id="(rId\\d+)"`,
+      's'
+    );
+    const rIdMatch = shapeNamePattern.exec(slideXml);
+
+    // Strategy 2: Find graphicFrame shapes and match chart rIds
+    if (!rIdMatch) {
+      const chartRIdPattern = /<c:chart[^>]*r:id="(rId\d+)"/g;
+      let chartMatch;
+      while ((chartMatch = chartRIdPattern.exec(slideXml)) !== null) {
+        const rId = chartMatch[1];
+        const rel = relationshipManager.getRelationshipById(slideInfo.zipPath, rId);
+        if (rel) {
+          const chartPath = relationshipManager.resolveTarget(slideInfo.zipPath, rel.target);
+          // Check if chart file name matches chartId
+          if (chartPath.includes(chartId) || rel.id === chartId) {
+            return { zipPath: chartPath };
+          }
+          // For the first chart found, if chartId looks like a chart file name
+          if (chartId.startsWith('chart')) {
+            return { zipPath: chartPath };
+          }
+        }
+      }
+    }
+
+    if (rIdMatch) {
+      const rId = rIdMatch[1];
+      const rel = relationshipManager.getRelationshipById(slideInfo.zipPath, rId);
+      if (rel) {
+        const chartPath = relationshipManager.resolveTarget(slideInfo.zipPath, rel.target);
+        return { zipPath: chartPath };
+      }
+    }
+
+    // Strategy 3: Direct chart registry lookup
+    if (this.#chartRegistry.has(chartId)) {
+      return this.#chartRegistry.get(chartId);
+    }
+
+    // Strategy 4: Try chartN naming convention
+    const chartPath = `ppt/charts/${chartId}.xml`;
+    if (this.#zipManager.hasFile(chartPath)) {
+      return { zipPath: chartPath };
+    }
+
+    return null;
+  }
+
+  /**
+   * Updates the chart XML file with new data.
+   * Preserves all styling, themes, and chart configuration.
+   *
+   * @private
+   * @param {string} chartZipPath - ZIP path to the chart XML file.
+   * @param {ChartData} data - New chart data.
+   * @param {RelationshipManager} relationshipManager
+   */
+  #updateChartXml(chartZipPath, data, relationshipManager) {
+    if (!this.#zipManager.hasFile(chartZipPath)) {
+      throw new ChartNotFoundError(`Chart file not found: ${chartZipPath}`);
+    }
+
+    // Register async update to ensure it completes before saving
+    this.#zipManager.addPendingPromise(
+      this.updateChartAsync(chartZipPath, data, relationshipManager)
+    );
+  }
+
+  /**
+   * Async version of chart update — updates XML and embedded workbook.
+   *
+   * @param {string} chartZipPath
+   * @param {ChartData} data
+   * @param {RelationshipManager} relationshipManager
+   * @returns {Promise<void>}
+   */
+  async updateChartAsync(chartZipPath, data, relationshipManager) {
+    // 1. Read Chart XML
+    const xml = await this.#zipManager.readFile(chartZipPath);
+    if (!xml) throw new ChartNotFoundError(`Chart file not found: ${chartZipPath}`);
+
+    // 2. Apply Chart XML Updates
+    const updatedXml = this.#applyChartData(xml, data, chartZipPath);
+    this.#zipManager.writeFile(chartZipPath, updatedXml);
+
+    // 3. Find and Update Embedded Workbook
+    if (relationshipManager) {
+      const rels = relationshipManager.getRelationshipsByType(chartZipPath, REL_TYPES.PACKAGE);
+      for (const rel of rels) {
+        const xlsxPath = relationshipManager.resolveTarget(chartZipPath, rel.target);
+        const xlsxData = this.#zipManager.rawZip.file(xlsxPath);
+        if (xlsxData) {
+          console.log(`Found embedded workbook: ${xlsxPath}`);
+          const buffer = await xlsxData.async('nodebuffer');
+          const updatedXlsx = await ChartWorkbookUpdater.updateWorkbook(buffer, data);
+          if (updatedXlsx) {
+            console.log(`Writing updated workbook to: ${xlsxPath}, size: ${updatedXlsx.length}`);
+            this.#zipManager.writeBinaryFile(xlsxPath, updatedXlsx);
+          }
+        } else {
+          console.log(`Could not find workbook at: ${xlsxPath}`);
+        }
+      }
+    }
+  }
+
+  /**
+   * Applies new chart data to the chart XML string.
+   *
+   * @private
+   * @param {string} xml - Original chart XML.
+   * @param {ChartData} data - New data to apply.
+   * @param {string} context - For error messages.
+   * @returns {string} Updated XML.
+   */
+  #applyChartData(xml, data, context) {
+    const { categories, series } = data;
+
+    // Detect chart type
+    const chartType = this.#detectChartType(xml);
+    logger.debug(`Updating ${chartType} chart at ${context}`);
+
+    let updatedXml = xml;
+
+    if (series && series.length > 0) {
+      updatedXml = ChartCacheGenerator.appendDynamicSeries(updatedXml, series.length);
+    }
+
+    if (categories && categories.length > 0) {
+      updatedXml = ChartCacheGenerator.updateCategories(updatedXml, categories);
+    }
+
+    if (series && series.length > 0) {
+      updatedXml = ChartCacheGenerator.updateSeries(updatedXml, series, categories ? categories.length : null);
+    }
+
+    return updatedXml;
+  }
+
+  /**
+   * Detects the chart type from its XML.
+   * @private
+   * @param {string} xml
+   * @returns {string} Chart type name.
+   */
+  #detectChartType(xml) {
+    for (const [name, element] of Object.entries(CHART_TYPE_MAP)) {
+      if (xml.includes(element)) return name;
+    }
+    return 'unknown';
+  }
+}