node-pptx-templater 1.0.6 → 1.0.8

package/README.md

@@ -35,6 +35,7 @@ You design your layouts, tables, fonts, brand styles, charts, and animations ins
 * 🛡️ **Hardened XML Security**: Fully immune to Billion Laughs (XML bombs), XXE (XML External Entity Injection), and parser crashes due to oversized expansions.
 * 🧩 **Text Run Fragmentation Healing**: Solves the split-tag issue. PowerPoint splits `{{placeholders}}` into fragmented `<a:r>` nodes; our parser unifies and replaces them while keeping original formatting intact.
 * 📊 **Excel Cache Synchronized Charting**: Supports Bar, Line, Pie, Doughnut, Area, and Scatter charts. Not only updates the visual XML coordinates but also synchronizes data points inside the underlying embedded Excel spreadsheets (`ppt/embeddings/`) to bypass PowerPoint's "Update Data" warnings.
+* 🏷️ **Chart Data Labels & Value From Cells**: Configure custom arrays, dynamic category maps, rich templates, positions (insideEnd, bestFit, center), and custom styles (fonts, colors, weight) and serialize them directly to the underlying Excel backing sheet.
 * 📋 **DrawingML Table Cell Merging**: Easily configure horizontal spans (`gridSpan`/`hMerge`), vertical spans (`rowSpan`/`vMerge`), and rectangular blocks. Injects unique `rowId` hashes to maintain relationship integrity.
 * 🥞 **Z-Order Layer Stacking**: Reorder shapes, images, charts, and tables programmatically. Simulates PowerPoint's "Bring to Front" and "Send to Back" commands directly in the slide's `<p:spTree>`.
 * 🎛️ **Slide Management**: Duplicate, delete, reorder slides, or import slides from external decks with automatic media and theme deduplication.
@@ -80,6 +81,15 @@ async function generateReport() {
        ]
      });
 
+  // 3b. Configure custom chart data labels with templates and styling
+  ppt.useSlide(2)
+     .updateDataLabels('revenue-chart', {
+       series: 0,
+       template: '{category}: {value}',
+       position: 'insideEnd',
+       labelStyle: { fontFamily: 'Arial', fontSize: 10, bold: true }
+     });
+
   // 4. Update table structure with cell merges and colors on Slide 3
   ppt.useSlide(3)
      .updateTable('performance-table', [
@@ -330,7 +340,7 @@ ppt.useSlide(1).getTables(());
 ### Charts API
 
 #### `updateChart(chartId, data)`
-Updates chart data in the selected slide(s). Finds charts by their name/ID and updates categories, series, and values. Preserves original chart styles, themes, and formatting.
+Updates chart data in the selected slide(s). Finds charts by their name/ID and updates categories, series, and values. Preserves original chart styles, themes, and formatting. Supports inline custom data labels by passing objects in the format `{ data: number, label: string }` instead of numbers.
 
 * **Arguments**:
   * `chartId` (`string`): Chart name or relationship ID.
@@ -338,7 +348,7 @@ Updates chart data in the selected slide(s). Finds charts by their name/ID and u
   * `data.categories` (`string[]`): Category labels (X-axis).
   * `data.series` (`SeriesData[]`): Data series array.
   * `data.series[].name` (`string`): Series name.
-  * `data.series[].values` (`number[]`): Data values.
+  * `data.series[].values` (`number[]|object[]`): Data values (numbers or label objects).
 * **Returns**: `PPTXTemplater` - this (chainable)
 
 ```javascript
@@ -402,6 +412,40 @@ Delegates core actions to slide element sub-managers.
 ppt.useSlide(1).updateChartCategories(());
 ```
 
+#### `updateDataLabels(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+ppt.useSlide(1).updateDataLabels('SalesChart', {
+  series: 0,
+  labels: ['Excellent', 'Good', 'Poor']
+});
+```
+
+#### `getDataLabels(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+const labels = await ppt.useSlide(1).getDataLabels('SalesChart', { series: 0 });
+console.log(labels); // [{ point: 0, value: 'Excellent' }, ...]
+```
+
+#### `validateDataLabels(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+const result = await ppt.useSlide(1).validateDataLabels('SalesChart', {
+  labels: ['High', 'Low']
+});
+console.log(result.valid);
+```
+
 #### `getCharts(())`
 Delegates core actions to slide element sub-managers.
 
@@ -674,6 +718,44 @@ Adds a special navigation link (next, previous, first, last slide) to a shape or
 ppt.useSlide(1).addShapeNavigationLink(options);
 ```
 
+#### `updateText(tag, data)`
+Updates shape text or list content by placeholder tag or shape name/ID. Supports bullet lists, numbered lists, nested lists, and custom styling.
+
+* **Arguments**:
+  * `tag` (`string`): Placeholder tag (e.g. '{{name}}' or 'name') or shape name/ID.
+  * `data` (`string|Object`): String value or list configuration object.
+* **Returns**: `PPTXTemplater` - this (chainable)
+
+```javascript
+ppt.useSlide(1).updateText('Features', {
+  list: ['Point A', 'Point B', 'Point C']
+});
+```
+
+#### `getList(tag)`
+Retrieves list items from a shape or text box by name or placeholder tag.
+
+* **Arguments**:
+  * `tag` (`string`): Shape name/ID or placeholder tag.
+* **Returns**: `Array` - Nested list structure of items.
+
+```javascript
+const items = ppt.useSlide(1).getList('Features');
+console.log(items); // ['A', { text: 'B', children: [...] }]
+```
+
+#### `validateList(data)`
+Validates a list structure and values.
+
+* **Arguments**:
+  * `data` (`Object|Array`): List config object or array of items.
+* **Returns**: `Object` - Report containing validation result.
+
+```javascript
+const result = ppt.validateList(['Valid string', 'Another item']);
+console.log(result.valid);
+```
+
 #### `replaceTextByTag(())`
 Delegates core actions to slide element sub-managers.
 
@@ -1249,6 +1331,180 @@ ppt.useSlide(1).create(());
 
 ---
 
+## 📊 Chart Data Labels & Value From Cells
+
+PPTXForge supports advanced, PowerPoint-compatible chart data labels. You can customize label data sources, templates, positioning, and visual styles. 
+
+### 1. Value From Cells (Excel Synchronization)
+Pull dynamic data labels directly from worksheet range cells inside the backing Excel spreadsheet. This is Excel's native "Value From Cells" feature, reconstructed programmatically inside the `.pptx` XML and `.xlsx` worksheets.
+
+```javascript
+ppt.useSlide(1).updateDataLabels('SalesChart', {
+  series: 0,
+  labelsFromCells: 'Sheet1!D2:D5'
+});
+```
+
+### 2. Literal Arrays
+Override data labels for specific points in a series with a static list of strings:
+
+```javascript
+ppt.useSlide(1).updateDataLabels('SalesChart', {
+  series: 0,
+  labels: ['Top Performance', 'Met Target', 'Action Required', 'At Risk']
+});
+```
+
+### 3. Dynamic Label Templates
+Combine values, category names, percentages, and custom label strings to format annotations:
+
+```javascript
+ppt.useSlide(1).updateDataLabels('SalesChart', {
+  series: 0,
+  template: '{category}: {value} ({percentage}%)'
+});
+```
+* **Variables**: `{category}`, `{value}`, `{percentage}`, `{series}`, `{customLabel}`
+
+### 4. Label Positions
+Set label alignment to any of PowerPoint's standard values:
+
+```javascript
+ppt.useSlide(1).updateDataLabels('SalesChart', {
+  series: 0,
+  position: 'insideEnd' // 'center', 'insideEnd', 'insideBase', 'outsideEnd', 'bestFit', 'left', 'right', 'top', 'bottom'
+});
+```
+
+### 5. Custom Label Styling
+Format your data labels using custom fonts, sizes, colors, and weight properties:
+
+```javascript
+ppt.useSlide(1).updateDataLabels('SalesChart', {
+  series: 0,
+  labels: ['High', 'Medium', 'Low'],
+  labelStyle: {
+    fontFamily: 'Century Gothic',
+    fontSize: 12,
+    color: '#0055A5',
+    bold: true,
+    italic: true,
+    underline: true
+  }
+});
+```
+
+### 6. Inline Custom Data Labels (`updateChart`)
+You can define custom data labels inline within the standard `updateChart()` series `values` array using objects in the format `{ data: number, label: string }`. This avoids calling separate styling or update methods:
+
+```javascript
+ppt.useSlide(1).updateChart('RevenueChart', {
+  categories: ['Q1', 'Q2', 'Q3', 'Q4'],
+  series: [
+    {
+      name: 'Product A',
+      values: [
+        { data: 145, label: 'Q1: 145 (Low)' },
+        { data: 210, label: 'Q2: 210 (Med)' },
+        { data: 190, label: 'Q3: 190 (Med)' },
+        { data: 250, label: 'Q4: 250 (High)' }
+      ]
+    }
+  ]
+});
+```
+
+To preserve PowerPoint integrity, the engine ensures that if one value contains a label, all values in that series must have labels, and the label properties must be string values.
+
+---
+
+## 📋 Native Lists (Bullet & Numbered Lists)
+
+PPTXForge supports native PowerPoint bullet lists and numbered lists across text placeholders, shapes, text boxes, table cells, and grouped shapes. When generating lists, the engine preserves run styles, custom bullet characters, indentation, and color overlays, generating valid OpenXML/DrawingML without repair alerts.
+
+### 1. Basic Bullet List
+Update a shape or text placeholder to be a bullet list:
+
+```javascript
+ppt.useSlide(1).updateText('Features', {
+  list: [
+    'Fast PPTX generation',
+    'OpenXML based',
+    'Chart updates',
+    'Table updates'
+  ]
+});
+```
+
+### 2. Numbered / Ordered List
+Use the `ordered` flag to convert the list to a numbered format:
+
+```javascript
+ppt.useSlide(1).updateText('Steps', {
+  ordered: true,
+  list: [
+    'Import template',
+    'Update data',
+    'Generate PPTX'
+  ]
+});
+```
+* Custom numbering systems can be specified with `style.numberType` (e.g., `arabicPeriod`, `alphaLcParen`, `romanUcPeriod`).
+
+### 3. Nested / Multi-Level Lists
+Construct hierarchy by passing objects containing a `text` string and a `children` array:
+
+```javascript
+ppt.useSlide(1).updateText('Requirements', {
+  list: [
+    'Frontend',
+    {
+      text: 'Backend Development',
+      children: [
+        'Node.js',
+        {
+          text: 'Databases',
+          children: ['MS SQL', 'PostgreSQL']
+        }
+      ]
+    }
+  ]
+});
+```
+
+### 4. Custom List Styling
+Customize bullet characters, colors, sizes, and font properties:
+
+```javascript
+ppt.useSlide(1).updateText('KPIs', {
+  list: ['Revenue Up', 'Margins Normal'],
+  style: {
+    fontFamily: 'Arial',
+    fontSize: 18,
+    color: '#0055AA',
+    bulletColor: '#FF5500',
+    bulletChar: '✦',
+    bulletSize: 120 // Percentage relative to text (e.g. 120%)
+  }
+});
+```
+
+### 5. Table Cell Lists
+You can also generate list hierarchies directly inside a cell of a DrawingML table:
+
+```javascript
+ppt.useSlide(3).updateTable('sales-table', [
+  ['Category', 'Performance details'],
+  ['North Region', '{{CellPlaceholder}}']
+]);
+
+ppt.updateText('CellPlaceholder', {
+  list: ['Table Bullet 1', 'Table Bullet 2']
+});
+```
+
+---
+
 ## 🔒 Advanced XML Security
 
 PPTXForge uses a secure XML parser that defends your application servers against common XML vulnerabilities.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-pptx-templater",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "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

@@ -359,20 +359,34 @@ class PPTXTemplater {
    * Updates chart data in the selected slide(s).
    * Finds charts by their name/ID and updates categories, series, and values.
    * Preserves original chart styles, themes, and formatting.
+   * Supports inline custom data labels by passing objects in the format `{ data: number, label: string }` instead of numbers.
    *
    * @param {string} chartId - Chart name or relationship ID.
    * @param {ChartData} data - New chart data.
    * @param {string[]} data.categories - Category labels (X-axis).
    * @param {SeriesData[]} data.series - Data series array.
    * @param {string} data.series[].name - Series name.
-   * @param {number[]} data.series[].values - Data values.
+   * @param {number[]|object[]} data.series[].values - Data values (numbers or label objects).
    * @returns {PPTXTemplater} this (chainable)
    *
    * @example
+   * // Simple numeric values:
    * ppt.updateChart('sales-chart', {
    *   categories: ['Jan', 'Feb', 'Mar'],
    *   series: [{ name: 'Revenue', values: [120, 150, 180] }]
    * });
+   *
+   * // Custom inline data labels:
+   * ppt.updateChart('sales-chart', {
+   *   categories: ['Q1', 'Q2'],
+   *   series: [{
+   *     name: 'Revenue',
+   *     values: [
+   *       { data: 120, label: '120 (40%)' },
+   *       { data: 180, label: '180 (60%)' }
+   *     ]
+   *   }]
+   * });
    */
   updateChart(chartId, data) {
     this.#assertLoaded()
@@ -1320,6 +1334,43 @@ class PPTXTemplater {
     return this
   }
 
+  updateDataLabels(chartId, options) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      this.#chartManager.updateDataLabels(
+        idx,
+        chartId,
+        options,
+        this.#slideManager,
+        this.#relationshipManager
+      )
+    }
+    return this
+  }
+
+  async getDataLabels(chartId, options = {}) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    if (targetIndices.length === 0) return []
+    const idx = targetIndices[0]
+    return this.#chartManager.getDataLabels(
+      idx,
+      chartId,
+      options,
+      this.#slideManager,
+      this.#relationshipManager
+    )
+  }
+
+  async validateDataLabels(chartId, options = {}) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    if (targetIndices.length === 0) return { valid: true, errors: [] }
+    const idx = targetIndices[0]
+    return ValidationEngine.validateDataLabels(this, idx, chartId, options)
+  }
+
   getCharts() {
     this.#assertLoaded()
     const targetIndices = this.#getTargetSlideIndices()
@@ -1332,6 +1383,46 @@ class PPTXTemplater {
     return charts
   }
 
+  /**
+   * Updates shape text or list content by placeholder tag or shape name/ID.
+   * Supports bullet lists, numbered lists, nested lists, and custom styling.
+   *
+   * @param {string} tag - Placeholder tag (e.g. '{{name}}' or 'name') or shape name/ID.
+   * @param {string|Object} data - String value or list configuration object.
+   * @returns {PPTXTemplater} this (chainable)
+   */
+  updateText(tag, data) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      this.#textManager.updateText(idx, tag, data, this.#slideManager, this.#templateEngine)
+    }
+    return this
+  }
+
+  /**
+   * Retrieves list items from a shape or text box by name or placeholder tag.
+   *
+   * @param {string} tag - Shape name/ID or placeholder tag.
+   * @returns {Array} Nested list structure of items.
+   */
+  getList(tag) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    const idx = targetIndices.length > 0 ? targetIndices[0] : 1
+    return this.#textManager.getList(idx, tag, this.#slideManager)
+  }
+
+  /**
+   * Validates a list structure and values.
+   *
+   * @param {Object|Array} data - List config object or array of items.
+   * @returns {Object} Report containing validation result.
+   */
+  validateList(data) {
+    return ValidationEngine.validateList(data)
+  }
+
   // === Text Features ===
   replaceTextByTag(tag, value, options = {}) {
     this.#assertLoaded()

package/src/core/TemplateEngine.js

@@ -80,6 +80,13 @@ class TemplateEngine {
 
     // Step 2: Simple direct replacement for any remaining unfragmented placeholders
     for (const [placeholder, value] of Object.entries(replacements)) {
+      if (
+        value &&
+        typeof value === 'object' &&
+        (Array.isArray(value) || value.list !== undefined)
+      ) {
+        continue
+      }
       const escaped = this.#escapeXml(String(value))
       const placeholderEscaped = this.#escapeXml(placeholder)
 
@@ -146,15 +153,35 @@ class TemplateEngine {
 
     // Check if any placeholder appears in the combined text
     let hasPlaceholder = false
+    let matchedPlaceholder = null
     for (const placeholder of Object.keys(replacements)) {
       if (combinedText.includes(placeholder)) {
         hasPlaceholder = true
+        matchedPlaceholder = placeholder
         break
       }
     }
 
     if (!hasPlaceholder) return paragraphXml
 
+    const replacementValue = replacements[matchedPlaceholder]
+    const isList =
+      replacementValue &&
+      (Array.isArray(replacementValue) ||
+        (typeof replacementValue === 'object' && replacementValue.list !== undefined))
+
+    if (isList) {
+      const listConfig = Array.isArray(replacementValue)
+        ? { list: replacementValue }
+        : replacementValue
+      const { ValidationEngine } = require('./ValidationEngine.js')
+      const validation = ValidationEngine.validateList(listConfig)
+      if (!validation.valid) {
+        throw new Error(`List validation failed: ${validation.errors.join(', ')}`)
+      }
+      return this.generateListParagraphs(paragraphXml, runs[0], listConfig)
+    }
+
     // Perform replacement on combined text
     let replacedText = combinedText
     for (const [placeholder, value] of Object.entries(replacements)) {
@@ -285,6 +312,105 @@ class TemplateEngine {
     return Array.from(placeholders)
   }
 
+  /**
+   * Generates a block of list paragraph XML elements from a template paragraph,
+   * a baseline run, and list options.
+   *
+   * @param {string} paragraphXml
+   * @param {Object} firstRun - Run XML info.
+   * @param {Object} listConfig - List styling and items.
+   * @returns {string} XML string of multiple paragraphs.
+   */
+  generateListParagraphs(paragraphXml, firstRun, listConfig) {
+    const list = listConfig.list || []
+    const ordered = !!listConfig.ordered
+    const style = listConfig.style || {}
+
+    const flattenList = (items, currentLvl = 0) => {
+      let flat = []
+      for (const item of items) {
+        if (typeof item === 'string') {
+          flat.push({ text: item, lvl: currentLvl })
+        } else if (typeof item === 'object' && item !== null) {
+          const text = item.text || ''
+          flat.push({ text, lvl: currentLvl })
+          if (Array.isArray(item.children)) {
+            flat = flat.concat(flattenList(item.children, currentLvl + 1))
+          }
+        }
+      }
+      return flat
+    }
+
+    const flatItems = flattenList(list)
+
+    const rPrMatch = /(<a:rPr>[\s\S]*?<\/a:rPr>)/.exec(firstRun.xml)
+    let baseRPr = rPrMatch ? rPrMatch[1] : '<a:rPr/>'
+
+    if (style.fontSize) {
+      const szVal = Math.round(style.fontSize * 100)
+      if (/sz="\d+"/.test(baseRPr)) {
+        baseRPr = baseRPr.replace(/sz="\d+"/, `sz="${szVal}"`)
+      } else {
+        baseRPr = baseRPr.replace('<a:rPr', `<a:rPr sz="${szVal}"`)
+      }
+    }
+    if (style.color) {
+      const cleanColor = style.color.replace('#', '')
+      const newFill = `<a:solidFill><a:srgbClr val="${cleanColor}"/></a:solidFill>`
+      if (/<a:solidFill>[\s\S]*?<\/a:solidFill>/.test(baseRPr)) {
+        baseRPr = baseRPr.replace(/<a:solidFill>[\s\S]*?<\/a:solidFill>/, newFill)
+      } else {
+        if (baseRPr.endsWith('/>')) {
+          baseRPr = baseRPr.replace('/>', `>${newFill}</a:rPr>`)
+        } else {
+          baseRPr = baseRPr.replace('</a:rPr>', `${newFill}</a:rPr>`)
+        }
+      }
+    }
+    if (style.fontFamily) {
+      const latinXml = `<a:latin typeface="${style.fontFamily}"/><a:cs typeface="${style.fontFamily}"/>`
+      baseRPr = baseRPr.replace(/<a:latin\s+[^>]*\/>/g, '').replace(/<a:cs\s+[^>]*\/>/g, '')
+      if (baseRPr.endsWith('/>')) {
+        baseRPr = baseRPr.replace('/>', `>${latinXml}</a:rPr>`)
+      } else {
+        baseRPr = baseRPr.replace('</a:rPr>', `${latinXml}</a:rPr>`)
+      }
+    }
+
+    let paragraphsXml = ''
+    for (const item of flatItems) {
+      const lvl = item.lvl
+      const marL = style.marL !== undefined ? style.marL : 381000 + lvl * 457200
+      const indent = style.indent !== undefined ? style.indent : -228600
+
+      let pPr = `<a:pPr lvl="${lvl}" marL="${marL}" indent="${indent}">`
+      if (ordered) {
+        const numType = style.numberType || 'arabicPeriod'
+        pPr += `<a:buAutoNum type="${numType}"/>`
+      } else {
+        const bulletChar = style.bulletChar || '•'
+        pPr += `<a:buChar char="${bulletChar}"/>`
+      }
+
+      if (style.bulletColor) {
+        const cleanBClr = style.bulletColor.replace('#', '')
+        pPr += `<a:buClr><a:srgbClr val="${cleanBClr}"/></a:buClr>`
+      }
+
+      if (style.bulletSize) {
+        pPr += `<a:buSzPct val="${Math.round(style.bulletSize * 1000)}"/>`
+      }
+
+      pPr += `</a:pPr>`
+
+      const runXml = `<a:r>${baseRPr}<a:t>${this.#escapeXml(item.text)}</a:t></a:r>`
+      paragraphsXml += `<a:p>${pPr}${runXml}</a:p>`
+    }
+
+    return paragraphsXml
+  }
+
   /**
    * Escapes XML special characters.
    * @private