node-pptx-templater 1.0.6 → 1.0.7

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.
 
@@ -1249,6 +1293,93 @@ 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.
+
+---
+
 ## 🔒 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.7",
   "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()

package/src/core/ValidationEngine.js

@@ -318,6 +318,99 @@ class ValidationEngine {
       warnings,
     }
   }
+
+  /**
+   * Validates data label configurations for a chart.
+   *
+   * @param {PPTXTemplater} ppt
+   * @param {number} slideIndex
+   * @param {string} chartId
+   * @param {Object} options
+   * @returns {Promise<Object>} report
+   */
+  static async validateDataLabels(ppt, slideIndex, chartId, options = {}) {
+    const errors = []
+    const warnings = []
+
+    try {
+      const chartInfo = ppt.chartManager.findChartInSlide(
+        slideIndex,
+        chartId,
+        ppt.slideManager,
+        ppt.relationshipManager
+      )
+
+      if (!chartInfo) {
+        errors.push(`Chart "${chartId}" not found in slide ${slideIndex}`)
+        return { valid: false, errors, warnings }
+      }
+
+      const chartType = await ppt.chartManager.getChartTypeAsync(
+        slideIndex,
+        chartId,
+        ppt.slideManager,
+        ppt.relationshipManager
+      )
+
+      const supportedTypes = [
+        'bar',
+        'column',
+        'line',
+        'pie',
+        'doughnut',
+        'area',
+        'scatter',
+        'combo',
+        'unknown',
+      ]
+      if (!supportedTypes.includes(chartType)) {
+        errors.push(`Unsupported chart type "${chartType}" for data labels`)
+      }
+
+      const xml = await ppt.zipManager.readFile(chartInfo.zipPath)
+      let ptsCount = 0
+      const catMatch = /<c:cat>([\s\S]*?)<\/c:cat>/.exec(xml)
+      const valMatch = /<c:val>([\s\S]*?)<\/c:val>/.exec(xml)
+      const targetBlock = catMatch ? catMatch[1] : valMatch ? valMatch[1] : ''
+      const ptCountMatch = /<c:ptCount val="(\d+)"\/>/.exec(targetBlock)
+      if (ptCountMatch) {
+        ptsCount = parseInt(ptCountMatch[1], 10)
+      }
+
+      if (options.labels) {
+        if (ptsCount > 0 && options.labels.length !== ptsCount) {
+          errors.push(
+            `Label count (${options.labels.length}) does not match chart data points count (${ptsCount})`
+          )
+        }
+
+        options.labels.forEach((lbl, i) => {
+          if (lbl === null || lbl === undefined || String(lbl).trim() === '') {
+            warnings.push(`Label at index ${i} is empty`)
+          }
+        })
+      }
+
+      if (options.labelsFromCells) {
+        const range = options.labelsFromCells
+        const parts = range.split('!')
+        const rangePart = parts.length > 1 ? parts[1] : parts[0]
+
+        const rangeRegex = /^\$?[A-Z]+\$?\d+(?::\$?[A-Z]+\$?\d+)?$/i
+        if (!rangeRegex.test(rangePart)) {
+          errors.push(`Invalid range format: "${options.labelsFromCells}"`)
+        }
+      }
+    } catch (err) {
+      errors.push(`Data labels validation error: ${err.message}`)
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    }
+  }
 }
 
 module.exports = { ValidationEngine }