node-pptx-templater 1.0.10 → 1.0.12

package/README.md

@@ -373,6 +373,68 @@ Repairs common chart corruption issues such as broken caches, missing embedded w
 ppt.useSlide(1).repairCharts();
 ```
 
+#### `getChartLabelPositions(chartId)`
+Retrieves the exact coordinate positions of all data labels for a chart on the active slide. Calculates absolute layout limits in EMUs (English Metric Units).
+
+* **Arguments**:
+  * `chartId` (`string`): 
+* **Returns**: `Promise<Array<{series: string, category: string, seriesIndex: number, categoryIndex: number, value: number, x: number, y: number, width: number, height: number` - 
+
+```javascript
+const positions = await ppt.useSlide(1).getChartLabelPositions('SalesChart');
+```
+
+#### `getChartBarPositions(chartId)`
+Retrieves the exact coordinate positions of all bars/columns for a chart on the active slide. Calculates absolute layout limits in EMUs (English Metric Units).
+
+* **Arguments**:
+  * `chartId` (`string`): 
+* **Returns**: `Promise<Array<{series: string, category: string, seriesIndex: number, categoryIndex: number, value: number, x: number, y: number, width: number, height: number` - 
+
+```javascript
+const bars = await ppt.useSlide(1).getChartBarPositions('SalesChart');
+```
+
+#### `addTextAtPosition(options)`
+Adds a textbox shape at a specific EMU coordinate position on targeted slides. Supports custom font styling and alignment configuration.
+
+* **Arguments**:
+  * `options` (`Object`): 
+  * `options.text` (`string`): 
+  * `options.x` (`number`): 
+  * `options.y` (`number`): 
+  * `[options.width=1200000]` (`number`): 
+  * `[options.height=300000]` (`number`): 
+  * `[options.style]` (`Object`): 
+* **Returns**: `this` - The chainable presentation engine instance.
+
+```javascript
+ppt.useSlide(1).addTextAtPosition({
+  text: 'Label',
+  x: 1000000,
+  y: 1000000
+});
+```
+
+#### `addTextNearChartLabel(options)`
+Dynamically places textboxes next to a chart's data labels with vertical collision avoidance. Textboxes are positioned either on the left or right of the chart area, vertically aligned with their corresponding label.
+
+* **Arguments**:
+  * `options` (`Object`): 
+  * `options.chart` (`string`): 
+  * `options.text` (`string|Function`): 
+  * `[options.position='left']` (`'left'|'right'`): 
+  * `[options.style]` (`Object`): 
+* **Returns**: `this` - The chainable presentation engine instance.
+
+```javascript
+ppt.addTextNearChartLabel({
+  chart: 'SalesChart',
+  text: 'Series',
+  position: 'left'
+});
+```
+
 #### `updateChartData(())`
 Delegates core actions to slide element sub-managers.
 
@@ -446,6 +508,31 @@ const result = await ppt.useSlide(1).validateDataLabels('SalesChart', {
 console.log(result.valid);
 ```
 
+#### `validateChartLabels(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+const result = await ppt.useSlide(1).validateChartLabels('SalesChart', {
+  labels: ['High', 'Low']
+});
+console.log(result.valid);
+```
+
+#### `validateSeriesNameLabels(())`
+Delegates core actions to slide element sub-managers.
+
+* **Returns**: `PPTXTemplater` - The fluent engine instance.
+
+```javascript
+const result = await ppt.useSlide(1).validateSeriesNameLabels('SalesChart', {
+  enabled: true,
+  position: 'left'
+});
+console.log(result.valid);
+```
+
 #### `getCharts(())`
 Delegates core actions to slide element sub-managers.
 
@@ -836,6 +923,38 @@ ppt.useSlide(1).getImages(());
 
 ### Shapes API
 
+#### `updateShapePosition(shapeId, options = {})`
+Updates the position and/or dimensions of an existing shape on targeted slides.
+
+* **Arguments**:
+  * `shapeId` (`string`): 
+  * `options` (`Object`): 
+  * `[options.x]` (`number`): 
+  * `[options.y]` (`number`): 
+  * `[options.width]` (`number`): 
+  * `[options.height]` (`number`): 
+* **Returns**: `this` - The chainable presentation engine instance.
+
+```javascript
+ppt.useSlide(1).updateShapePosition('TitleShape', { x: 1000000, y: 1500000 });
+```
+
+#### `updateTextBoxPosition(textBoxId, options = {})`
+Updates the position and/or dimensions of an existing textbox on targeted slides.
+
+* **Arguments**:
+  * `textBoxId` (`string`): 
+  * `options` (`Object`): 
+  * `[options.x]` (`number`): 
+  * `[options.y]` (`number`): 
+  * `[options.width]` (`number`): 
+  * `[options.height]` (`number`): 
+* **Returns**: `this` - The chainable presentation engine instance.
+
+```javascript
+ppt.useSlide(1).updateTextBoxPosition('TextBox 2', { x: 1000000, y: 1500000 });
+```
+
 #### `updateShapeText(())`
 Delegates core actions to slide element sub-managers.
 
@@ -1416,6 +1535,79 @@ ppt.useSlide(1).updateChart('RevenueChart', {
 
 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.
 
+### 7. Label Style Inheritance & Series Names Inside Bars
+
+#### Style Inheritance
+When custom labels (inline or via `updateDataLabels`) are generated, they inherit the styling properties (font family, font size, bold, italic, color, and alignment) defined in the template's `<c:txPr>` tag for the series. This ensures your custom labels match the branding and layout design from your PowerPoint template file.
+
+#### Series Names Inside Bars (`showSeriesNameInBar`)
+For stacked bar charts, you can show the series name inside each segment (typically centered) to make them easily readable. To enable this, set `showSeriesNameInBar: true` in the chart options (globally) or on individual series:
+
+```javascript
+ppt.useSlide(1).updateChart('RevenueChart', {
+  showSeriesNameInBar: true, // Show series name labels globally
+  categories: ['Q1', 'Q2', 'Q3', 'Q4'],
+  series: [
+    { name: 'Product A', values: [100, 200, 300, 400] },
+    { name: 'Product B', values: [150, 250, 350, 450], showSeriesNameInBar: true } // Or per-series
+  ]
+});
+```
+
+#### Chart Labels Validation
+You can programmatically validate that the chart labels configured in a chart conform to your template structure:
+
+```javascript
+const report = await ppt.useSlide(1).validateChartLabels('RevenueChart', {
+  labels: ['Custom label 1', 'Custom label 2'],
+  showSeriesNameInBar: true
+});
+
+if (!report.valid) {
+  console.log('Errors:', report.errors);
+  console.log('Warnings:', report.warnings);
+}
+```
+
+#### External Series Name Labels (`seriesNameLabels`)
+You can position the series names outside the chart area as separate text boxes (`<p:sp>`) aligned with each corresponding bar or stack. These external labels automatically inherit the styling (font family, font size, bold, italic, color) defined in the template's series properties.
+
+Supported features:
+* **Position**: Can be set to `'left'` or `'right'` to align text boxes to the left or right of the chart.
+* **Auto-fit & Height Wrapping**: Automatically wraps text and calculates height if labels are longer than the available margin space.
+* **Collision Detection**: Prevent overlapping with slide bounds by shrinking the chart, and resolve vertical overlaps of labels by shifting them apart.
+* **Idempotency**: Safely clean up previous labels on multiple chart updates.
+
+Example usage:
+```javascript
+ppt.useSlide(1).updateChart('RevenueChart', {
+  categories: ['Q1', 'Q2', 'Q3', 'Q4'],
+  series: [
+    { name: 'Product A', values: [100, 200, 300, 400] },
+    { name: 'Product B', values: [150, 250, 350, 450] }
+  ],
+  seriesNameLabels: {
+    enabled: true,
+    position: 'left', // 'left' or 'right'
+    autoFit: true     // Automatically wrap and shrink layout if needed (default: true)
+  }
+});
+```
+
+To validate your configuration and check for boundary or collision warning/errors:
+```javascript
+const report = await ppt.useSlide(1).validateSeriesNameLabels('RevenueChart', {
+  enabled: true,
+  position: 'left',
+  autoFit: true
+});
+
+if (!report.valid) {
+  console.error('Validation errors:', report.errors);
+  console.warn('Validation warnings:', report.warnings);
+}
+```
+
 ---
 
 ## 📋 Native Lists (Bullet & Numbered Lists)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-pptx-templater",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "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",
@@ -181,4 +181,4 @@
     "LICENSE",
     "CHANGELOG.md"
   ]
-}
+}

package/src/core/PPTXTemplater.js

@@ -1371,6 +1371,34 @@ class PPTXTemplater {
     return ValidationEngine.validateDataLabels(this, idx, chartId, options)
   }
 
+  async validateChartLabels(chartId, options = {}) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    if (targetIndices.length === 0) return { valid: true, errors: [], warnings: [] }
+    const idx = targetIndices[0]
+    return this.#chartManager.validateChartLabels(
+      idx,
+      chartId,
+      options,
+      this.#slideManager,
+      this.#relationshipManager
+    )
+  }
+
+  async validateSeriesNameLabels(chartId, options = {}) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    if (targetIndices.length === 0) return { valid: true, errors: [], warnings: [] }
+    const idx = targetIndices[0]
+    return this.#chartManager.validateSeriesNameLabels(
+      idx,
+      chartId,
+      options,
+      this.#slideManager,
+      this.#relationshipManager
+    )
+  }
+
   getCharts() {
     this.#assertLoaded()
     const targetIndices = this.#getTargetSlideIndices()
@@ -1383,6 +1411,95 @@ class PPTXTemplater {
     return charts
   }
 
+  /**
+   * Retrieves the exact coordinate positions of all data labels for a chart on the active slide.
+   * Calculates absolute layout limits in EMUs (English Metric Units).
+   *
+   * @param {string} chartId The unique chart name/id in the template slide.
+   * @returns {Promise<Array<{series: string, category: string, seriesIndex: number, categoryIndex: number, value: number, x: number, y: number, width: number, height: number}>>} An array of data label geometry objects.
+   */
+  async getChartLabelPositions(chartId) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    if (targetIndices.length === 0) return []
+    const idx = targetIndices[0]
+    return this.#chartManager.getChartLabelPositions(
+      idx,
+      chartId,
+      this.#slideManager,
+      this.#relationshipManager
+    )
+  }
+
+  /**
+   * Retrieves the exact coordinate positions of all bars/columns for a chart on the active slide.
+   * Calculates absolute layout limits in EMUs (English Metric Units).
+   *
+   * @param {string} chartId The unique chart name/id in the template slide.
+   * @returns {Promise<Array<{series: string, category: string, seriesIndex: number, categoryIndex: number, value: number, x: number, y: number, width: number, height: number}>>} An array of bar geometry objects.
+   */
+  async getChartBarPositions(chartId) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    if (targetIndices.length === 0) return []
+    const idx = targetIndices[0]
+    return this.#chartManager.getChartBarPositions(
+      idx,
+      chartId,
+      this.#slideManager,
+      this.#relationshipManager
+    )
+  }
+
+  /**
+   * Adds a textbox shape at a specific EMU coordinate position on targeted slides.
+   * Supports custom font styling and alignment configuration.
+   *
+   * @param {Object} options Textbox positioning and style configuration.
+   * @param {string} options.text Text content to insert in the textbox.
+   * @param {number} options.x Bounding box X offset coordinate (in EMUs).
+   * @param {number} options.y Bounding box Y offset coordinate (in EMUs).
+   * @param {number} [options.width=1200000] Bounding box width (in EMUs).
+   * @param {number} [options.height=300000] Bounding box height (in EMUs).
+   * @param {Object} [options.style] Font formatting properties (fontSize, fontFamily, color, bold, italic, align).
+   * @returns {this} The chainable presentation engine instance.
+   */
+  addTextAtPosition(options) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      const p = this.#chartManager.addTextAtPosition(idx, options, this.#slideManager)
+      this.#zipManager.addPendingPromise(p)
+    }
+    return this
+  }
+
+  /**
+   * Dynamically places textboxes next to a chart's data labels with vertical collision avoidance.
+   * Textboxes are positioned either on the left or right of the chart area, vertically aligned with their corresponding label.
+   *
+   * @param {Object} options Text alignment, naming, and position configuration.
+   * @param {string} options.chart The target chart name/id.
+   * @param {string|Function} options.text Static label text or a callback function receiving `({ series, category, value })`.
+   * @param {'left'|'right'} [options.position='left'] Alignment position relative to the chart boundaries.
+   * @param {Object} [options.style] Text styling attributes (fontSize, fontFamily, color, bold, italic, align, autoFit).
+   * @returns {this} The chainable presentation engine instance.
+   */
+  addTextNearChartLabel(options) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      const p = this.#chartManager.addTextNearChartLabel(
+        idx,
+        options,
+        this.#slideManager,
+        this.#relationshipManager
+      )
+      this.#zipManager.addPendingPromise(p)
+    }
+    return this
+  }
+
   /**
    * Updates shape text or list content by placeholder tag or shape name/ID.
    * Supports bullet lists, numbered lists, nested lists, and custom styling.
@@ -1485,6 +1602,46 @@ class PPTXTemplater {
     return this
   }
 
+  /**
+   * Updates the position and/or dimensions of an existing shape on targeted slides.
+   *
+   * @param {string} shapeId The unique shape name/id in the template slide.
+   * @param {Object} options Positioning and styling dimensions config.
+   * @param {number} [options.x] Absolute X offset coordinate (in EMUs).
+   * @param {number} [options.y] Absolute Y offset coordinate (in EMUs).
+   * @param {number} [options.width] Bounding box width (in EMUs).
+   * @param {number} [options.height] Bounding box height (in EMUs).
+   * @returns {this} The chainable presentation engine instance.
+   */
+  updateShapePosition(shapeId, options = {}) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      this.#shapeManager.updateShapePosition(idx, shapeId, options, this.#slideManager)
+    }
+    return this
+  }
+
+  /**
+   * Updates the position and/or dimensions of an existing textbox on targeted slides.
+   *
+   * @param {string} textBoxId The unique textbox shape name/id in the template slide.
+   * @param {Object} options Positioning and styling dimensions config.
+   * @param {number} [options.x] Absolute X offset coordinate (in EMUs).
+   * @param {number} [options.y] Absolute Y offset coordinate (in EMUs).
+   * @param {number} [options.width] Bounding box width (in EMUs).
+   * @param {number} [options.height] Bounding box height (in EMUs).
+   * @returns {this} The chainable presentation engine instance.
+   */
+  updateTextBoxPosition(textBoxId, options = {}) {
+    this.#assertLoaded()
+    const targetIndices = this.#getTargetSlideIndices()
+    for (const idx of targetIndices) {
+      this.#shapeManager.updateTextBoxPosition(idx, textBoxId, options, this.#slideManager)
+    }
+    return this
+  }
+
   cloneShape(shapeId, newShapeId, options = {}) {
     this.#assertLoaded()
     const targetIndices = this.#getTargetSlideIndices()

package/src/core/ValidationEngine.js

@@ -497,6 +497,176 @@ class ValidationEngine {
       warnings,
     }
   }
+
+  /**
+   * Validates chart labels for stacked bar charts.
+   *
+   * @param {string} xml - Chart XML string.
+   * @param {Object} options - Validation options.
+   * @returns {Object} report
+   */
+  static validateChartLabels(xml, options = {}) {
+    const errors = []
+    const warnings = []
+
+    if (!xml) {
+      errors.push('Chart XML must be provided')
+      return { valid: false, errors, warnings }
+    }
+
+    // Check chart type is stacked bar
+    const isBarChart = xml.includes('c:barChart')
+    const isStacked = xml.includes('val="stacked"') || xml.includes('val="percentStacked"')
+    if (!isBarChart || !isStacked) {
+      warnings.push(
+        'Chart is not a stacked bar chart (expected <c:barChart> with stacked grouping)'
+      )
+    }
+
+    // Verify label count consistency if options.labels is provided
+    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})`
+        )
+      }
+    }
+
+    // Check series name availability (meaning if showSeriesNameInBar is requested, does the chart have series names?)
+    if (options.showSeriesNameInBar) {
+      const hasSeriesName = xml.includes('<c:tx>') || xml.includes('<c:f>')
+      if (!hasSeriesName) {
+        warnings.push('Series name might not be available or defined in the template')
+      }
+    }
+
+    // Check template style availability (dLbls, txPr, etc.)
+    const hasDLbls = xml.includes('<c:dLbls>')
+    const hasTxPr = xml.includes('<c:txPr>')
+    if (!hasDLbls) {
+      warnings.push('Template does not contain default data labels (<c:dLbls>)')
+    } else if (!hasTxPr) {
+      warnings.push('Template data labels do not have styling properties (<c:txPr>)')
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    }
+  }
+
+  /**
+   * Validates series name labels configuration.
+   *
+   * @param {string} xml - Chart XML string.
+   * @param {Object} xfrm - Chart graphic frame xfrm.
+   * @param {Object} options - Configuration options.
+   * @returns {Object} report
+   */
+  static validateSeriesNameLabels(xml, xfrm, options = {}) {
+    const errors = []
+    const warnings = []
+
+    if (!options || !options.enabled) {
+      return { valid: true, errors, warnings }
+    }
+
+    const { position } = options
+    const allowedPositions = ['left', 'right']
+    if (!position || !allowedPositions.includes(position)) {
+      errors.push(`Invalid position "${position}". Only "left" and "right" are supported.`)
+    }
+
+    if (options.style) {
+      if (typeof options.style !== 'object' || Array.isArray(options.style)) {
+        errors.push('style must be a key-value object')
+      } else {
+        const { fontSize, bold, italic, color, fontFamily, align } = options.style
+        if (fontSize !== undefined && (typeof fontSize !== 'number' || fontSize <= 0)) {
+          errors.push('style.fontSize must be a positive number')
+        }
+        if (bold !== undefined && typeof bold !== 'boolean') {
+          errors.push('style.bold must be a boolean')
+        }
+        if (italic !== undefined && typeof italic !== 'boolean') {
+          errors.push('style.italic must be a boolean')
+        }
+        if (color !== undefined && typeof color !== 'string') {
+          errors.push('style.color must be a string')
+        } else if (color !== undefined) {
+          const cleanColor = color.replace('#', '').trim()
+          if (!/^[0-9A-Fa-f]{6}$/.test(cleanColor)) {
+            errors.push(`style.color "${color}" is not a valid hex color (e.g. "#FF0000")`)
+          }
+        }
+        if (fontFamily !== undefined && typeof fontFamily !== 'string') {
+          errors.push('style.fontFamily must be a string')
+        }
+        if (align !== undefined && !['left', 'right', 'center'].includes(align)) {
+          errors.push(
+            `Invalid style.align "${align}". Supported alignments are "left", "right", "center"`
+          )
+        }
+      }
+    }
+
+    if (!xml) {
+      errors.push('Chart XML must be provided')
+      return { valid: false, errors, warnings }
+    }
+
+    if (!xfrm) {
+      errors.push('Chart coordinates (xfrm) must be resolved')
+      return { valid: false, errors, warnings }
+    }
+
+    // Check plot area layout
+    const plotAreaMatch = /<c:plotArea>([\s\S]*?)<\/c:plotArea>/.exec(xml)
+    if (!plotAreaMatch) {
+      errors.push('Plot area not detected in chart XML')
+    }
+
+    // Verify slide boundary collision
+    if (position === 'left') {
+      if (xfrm.left <= 0) {
+        errors.push(
+          `Chart left boundary (${xfrm.left}) is at or outside slide bounds, labels on the left cannot fit`
+        )
+      } else if (xfrm.left < 500000) {
+        warnings.push(
+          `Chart left boundary (${xfrm.left}) is very close to slide edge, labels on the left might clip`
+        )
+      }
+    } else if (position === 'right') {
+      const chartRight = xfrm.left + xfrm.width
+      const slideWidth = 12192000
+      if (chartRight >= slideWidth) {
+        errors.push(
+          `Chart right boundary (${chartRight}) is at or outside slide bounds, labels on the right cannot fit`
+        )
+      } else if (slideWidth - chartRight < 500000) {
+        warnings.push(
+          `Chart right boundary (${chartRight}) is very close to slide edge, labels on the right might clip`
+        )
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    }
+  }
 }
 
 module.exports = { ValidationEngine }