node-pptx-templater 1.0.7 → 1.0.8

package/README.md

@@ -718,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.
 
@@ -1380,6 +1418,93 @@ To preserve PowerPoint integrity, the engine ensures that if one value contains
 
 ---
 
+## 📋 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.7",
+  "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

@@ -1383,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

package/src/core/ValidationEngine.js

@@ -411,6 +411,92 @@ class ValidationEngine {
       warnings,
     }
   }
+
+  /**
+   * Validates a list structure and values.
+   *
+   * @param {Object|Array} data - List config object or array of items.
+   * @returns {Object} Report containing errors and warnings.
+   */
+  static validateList(data) {
+    const errors = []
+    const warnings = []
+
+    if (!data) {
+      errors.push('List data must be provided')
+      return { valid: false, errors, warnings }
+    }
+
+    const listArray = Array.isArray(data) ? data : data.list
+    if (!listArray) {
+      errors.push('List data must contain an array under the "list" property or be an array')
+      return { valid: false, errors, warnings }
+    }
+
+    const checkItem = (item, level) => {
+      if (level < 0 || level > 8) {
+        errors.push(`Level ${level} is out of supported range (0 to 8)`)
+      }
+
+      if (typeof item === 'string') {
+        if (item.trim() === '') {
+          errors.push('Empty list item text is not allowed')
+        }
+      } else if (typeof item === 'object' && item !== null) {
+        if (item.text === undefined || item.text === null || String(item.text).trim() === '') {
+          errors.push('Empty list item text is not allowed')
+        }
+        if (item.children) {
+          if (!Array.isArray(item.children)) {
+            errors.push('Children property must be an array of items')
+          } else {
+            item.children.forEach(child => {
+              checkItem(child, level + 1)
+            })
+          }
+        }
+      } else {
+        errors.push(`Invalid list item type: "${typeof item}"`)
+      }
+    }
+
+    listArray.forEach(item => {
+      checkItem(item, 0)
+    })
+
+    if (data.style) {
+      const style = data.style
+      if (style.fontSize !== undefined) {
+        if (typeof style.fontSize !== 'number' || style.fontSize <= 0) {
+          errors.push('fontSize must be a positive number')
+        }
+      }
+      if (style.color !== undefined) {
+        if (typeof style.color !== 'string' || !/^#(?:[0-9a-fA-F]{3}){1,2}$/.test(style.color)) {
+          errors.push(`Invalid color format: "${style.color}" (expected hex e.g. #FF0000)`)
+        }
+      }
+      if (style.bulletColor !== undefined) {
+        if (
+          typeof style.bulletColor !== 'string' ||
+          !/^#(?:[0-9a-fA-F]{3}){1,2}$/.test(style.bulletColor)
+        ) {
+          errors.push(`Invalid bulletColor format: "${style.bulletColor}"`)
+        }
+      }
+      if (style.bulletSize !== undefined) {
+        if (typeof style.bulletSize !== 'number' || style.bulletSize <= 0) {
+          errors.push('bulletSize must be a positive number')
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+    }
+  }
 }
 
 module.exports = { ValidationEngine }

package/src/managers/ChartManager.js

@@ -262,7 +262,13 @@ class ChartManager {
     const seriesLabels = normalized.labels
 
     // 3. Apply Chart XML Updates
-    const updatedXml = this.#applyChartData(xml, cleanNumericData, chartZipPath)
+    let updatedXml = this.#applyChartData(xml, cleanNumericData, chartZipPath)
+    if (data.title !== undefined) {
+      updatedXml = require('./charts/ChartCacheGenerator.js').ChartCacheGenerator.updateTitle(
+        updatedXml,
+        data.title
+      )
+    }
     this.#zipManager.writeFile(chartZipPath, updatedXml)
 
     // 4. Find and Update Embedded Workbook
@@ -680,6 +686,9 @@ class ChartManager {
 
   #validateChartData(data) {
     const { categories, series } = data
+    if (data.title !== undefined && typeof data.title !== 'string') {
+      throw new Error('Chart title must be a string')
+    }
     if (!series || series.length === 0) return
 
     // Series lengths remain consistent (if categories exist, check against length of categories)
@@ -688,23 +697,45 @@ class ChartManager {
       : series[0].values
         ? series[0].values.length
         : 0
+
     for (const ser of series) {
       const name = ser.name || 'Unknown'
-      const len = ser.values ? ser.values.length : 0
-      if (len !== expectedLen) {
-        throw new Error(
-          `Series lengths mismatch: expected ${expectedLen} values, got ${len} in series ${name}`
-        )
+      if (!ser.values) {
+        ser.values = []
+      }
+
+      // Check if there is any label in the series to determine padding style
+      let seriesHasLabels = false
+      for (const val of ser.values) {
+        if (typeof val === 'object' && val !== null && val.label !== undefined) {
+          seriesHasLabels = true
+          break
+        }
       }
 
+      // Pad or truncate values to match expectedLen
+      if (ser.values.length < expectedLen) {
+        while (ser.values.length < expectedLen) {
+          if (seriesHasLabels) {
+            ser.values.push({ value: null, label: '' })
+          } else {
+            ser.values.push(null)
+          }
+        }
+      } else if (ser.values.length > expectedLen) {
+        ser.values = ser.values.slice(0, expectedLen)
+      }
+
+      const len = ser.values.length
+
       // Check values inside the series
       let hasLabels = false
       let labelCount = 0
       for (const val of ser.values) {
         if (typeof val === 'object' && val !== null) {
           const numVal = val.value !== undefined ? val.value : val.data
-          // Data values remain numeric
-          if (typeof numVal !== 'number' || isNaN(numVal)) {
+          // Data values remain numeric or null
+          if (numVal !== null && (typeof numVal !== 'number' || isNaN(numVal))) {
             throw new Error(`Data value must be numeric in series ${name}`)
           }
           if (val.label !== undefined) {
@@ -716,8 +747,8 @@ class ChartManager {
             }
           }
         } else {
-          // Data values remain numeric (primitive value)
-          if (typeof val !== 'number' || isNaN(val)) {
+          // Data values remain numeric (primitive value) or null
+          if (val !== null && (typeof val !== 'number' || isNaN(val))) {
             throw new Error(`Data value must be numeric in series ${name}`)
           }
         }
@@ -743,12 +774,12 @@ class ChartManager {
         if (ser.values) {
           ser.values.forEach(v => {
             if (typeof v === 'object' && v !== null) {
-              const val = v.value !== undefined ? v.value : v.data !== undefined ? v.data : 0
+              const val = v.value !== undefined ? v.value : v.data !== undefined ? v.data : null
               cleanValues.push(val)
               labels.push(v.label)
               if (v.label !== undefined) hasLabel = true
             } else {
-              cleanValues.push(Number(v) || 0)
+              cleanValues.push(v === null || v === undefined ? null : Number(v) || 0)
               labels.push(undefined)
             }
           })

package/src/managers/TextManager.js

@@ -192,6 +192,277 @@ class TextManager {
       this.#collectTextElements(g, results)
     }
   }
+
+  /**
+   * Updates shape text or list content by placeholder tag or shape name/ID.
+   *
+   * @param {number} slideIndex
+   * @param {string} tag - Placeholder tag (e.g. '{{name}}') or shape name/ID.
+   * @param {string|Object} data - String value or list configuration object.
+   * @param {SlideManager} slideManager
+   * @param {TemplateEngine} templateEngine
+   */
+  updateText(slideIndex, tag, data, slideManager, templateEngine) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const normalizedTag = tag.startsWith('{{') && tag.endsWith('}}') ? tag : `{{${tag}}}`
+
+    // Option A: Tag exists as a placeholder in the slide XML
+    if (slideXml.includes(normalizedTag)) {
+      const replacements = { [normalizedTag]: data }
+      const updatedXml = templateEngine.replaceTextInXml(slideXml, replacements)
+      slideManager.setSlideXml(slideIndex, updatedXml)
+      logger.debug(`Updated text tag "${normalizedTag}" on slide ${slideIndex}`)
+      return
+    }
+
+    // Option B: Search for a shape whose name or ID matches the tag
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+    const res = this.findShapeRecursive(spTree, tag)
+
+    if (!res) {
+      const { PPTXError } = require('../utils/errors.js')
+      throw new PPTXError(`Text placeholder or shape "${tag}" not found in slide ${slideIndex}`)
+    }
+
+    // Replace the text body of the shape
+    const shape = res.shape
+    const listConfig =
+      typeof data === 'object' && data !== null
+        ? data.list !== undefined
+          ? data
+          : { list: [data] }
+        : { list: [String(data)] }
+
+    const { ValidationEngine } = require('../core/ValidationEngine.js')
+    const validation = ValidationEngine.validateList(listConfig)
+    if (!validation.valid) {
+      throw new Error(`List validation failed: ${validation.errors.join(', ')}`)
+    }
+
+    if (!shape['p:txBody']) {
+      shape['p:txBody'] = {
+        'a:bodyPr': {},
+        'a:lstStyle': {},
+        'a:p': [],
+      }
+    }
+
+    const txBody = shape['p:txBody']
+    const originalParas = Array.isArray(txBody['a:p']) ? txBody['a:p'] : [txBody['a:p']]
+    const templatePara = originalParas.length > 0 ? originalParas[0] : {}
+    const templateRuns = templatePara['a:r']
+      ? Array.isArray(templatePara['a:r'])
+        ? templatePara['a:r']
+        : [templatePara['a:r']]
+      : []
+    const firstRun = templateRuns.length > 0 ? templateRuns[0] : { 'a:rPr': {} }
+
+    const firstRunXml = this.#xmlParser.build({ 'a:r': firstRun })
+    const dummyParaXml = `<a:p>${firstRunXml}</a:p>`
+    const generatedXml = templateEngine.generateListParagraphs(
+      dummyParaXml,
+      { xml: firstRunXml },
+      listConfig
+    )
+
+    // Parse the generated XML paragraphs back to objects
+    const wrappedXml = `<root xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">${generatedXml}</root>`
+    const parsedObj = this.#xmlParser.parse(wrappedXml)
+    let newParas = parsedObj?.root?.['a:p'] || []
+    if (!Array.isArray(newParas)) {
+      newParas = [newParas]
+    }
+
+    txBody['a:p'] = newParas
+
+    const decl = this.#xmlParser.extractDeclaration(slideXml)
+    slideManager.setSlideXml(slideIndex, this.#xmlParser.build(slideObj, decl))
+    logger.debug(`Updated text content for shape "${tag}" on slide ${slideIndex}`)
+  }
+
+  /**
+   * Retrieves list items from a shape or text box by name or placeholder tag.
+   *
+   * @param {number} slideIndex
+   * @param {string} tag - Shape name/ID or placeholder tag.
+   * @param {SlideManager} slideManager
+   * @returns {Array} Nested list structure of items.
+   */
+  getList(slideIndex, tag, slideManager) {
+    const slideXml = slideManager.getSlideXml(slideIndex)
+    const slideObj = this.#xmlParser.parse(slideXml, `slide${slideIndex}.xml`)
+    const spTree = slideObj?.['p:sld']?.['p:cSld']?.['p:spTree']
+
+    // Step 1: Find shape by name or ID matching tag
+    let res = this.findShapeRecursive(spTree, tag)
+
+    // Step 2: If not found, look for any shape containing the placeholder string
+    if (!res) {
+      const collectMatchingShape = container => {
+        if (!container) return null
+
+        let shapes = container['p:sp'] || []
+        if (!Array.isArray(shapes)) shapes = [shapes]
+
+        for (const shape of shapes) {
+          const txBody = shape['p:txBody']
+          if (txBody && txBody['a:p']) {
+            const paras = Array.isArray(txBody['a:p']) ? txBody['a:p'] : [txBody['a:p']]
+            for (const p of paras) {
+              let pText = ''
+              if (p['a:r']) {
+                const runs = Array.isArray(p['a:r']) ? p['a:r'] : [p['a:r']]
+                for (const r of runs) {
+                  if (r['a:t']) pText += String(r['a:t'])
+                }
+              }
+              if (pText.includes(tag)) {
+                return { shape, parent: container, type: 'sp' }
+              }
+            }
+          }
+        }
+
+        // Search in tables inside graphicFrames
+        let frames = container['p:graphicFrame'] || []
+        if (!Array.isArray(frames)) frames = [frames]
+
+        for (const frame of frames) {
+          const tbl = frame?.['a:graphic']?.['a:graphicData']?.['a:tbl']
+          if (tbl && tbl['a:tr']) {
+            const rows = Array.isArray(tbl['a:tr']) ? tbl['a:tr'] : [tbl['a:tr']]
+            for (const row of rows) {
+              const cells = Array.isArray(row['a:tc']) ? row['a:tc'] : [row['a:tc']]
+              for (const cell of cells) {
+                const txBody = cell['a:txBody']
+                if (txBody && txBody['a:p']) {
+                  const paras = Array.isArray(txBody['a:p']) ? txBody['a:p'] : [txBody['a:p']]
+                  for (const p of paras) {
+                    let pText = ''
+                    if (p['a:r']) {
+                      const runs = Array.isArray(p['a:r']) ? p['a:r'] : [p['a:r']]
+                      for (const r of runs) {
+                        if (r['a:t']) pText += String(r['a:t'])
+                      }
+                    }
+                    if (pText.includes(tag)) {
+                      return { shape: cell, parent: row, type: 'cell' }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+
+        let groups = container['p:grpSp'] || []
+        if (!Array.isArray(groups)) groups = [groups]
+
+        for (const group of groups) {
+          const matched = collectMatchingShape(group)
+          if (matched) return matched
+        }
+
+        return null
+      }
+      res = collectMatchingShape(spTree)
+    }
+
+    if (!res || !res.shape || !(res.shape['p:txBody'] || res.shape['a:txBody'])) {
+      return []
+    }
+
+    const txBody = res.shape['p:txBody'] || res.shape['a:txBody']
+    const paras = Array.isArray(txBody['a:p']) ? txBody['a:p'] : [txBody['a:p']]
+
+    const flatItems = []
+    for (const p of paras) {
+      let lvl = 0
+      if (p['a:pPr'] && p['a:pPr']['@_lvl'] !== undefined) {
+        lvl = parseInt(p['a:pPr']['@_lvl'], 10) || 0
+      }
+
+      let text = ''
+      if (p['a:r']) {
+        const runs = Array.isArray(p['a:r']) ? p['a:r'] : [p['a:r']]
+        const textParts = []
+        for (const r of runs) {
+          if (r['a:t']) textParts.push(String(r['a:t']))
+        }
+        text = textParts.join('')
+      }
+
+      if (text.trim() !== '') {
+        flatItems.push({ text: text.trim(), lvl })
+      }
+    }
+
+    if (flatItems.length === 0) {
+      return []
+    }
+
+    const result = []
+    const stack = []
+
+    for (const item of flatItems) {
+      const node = { text: item.text, children: [] }
+
+      while (stack.length > 0 && stack[stack.length - 1].lvl >= item.lvl) {
+        stack.pop()
+      }
+
+      if (stack.length === 0) {
+        result.push(node)
+      } else {
+        const parent = stack[stack.length - 1].node
+        parent.children.push(node)
+      }
+
+      stack.push({ lvl: item.lvl, node })
+    }
+
+    const cleanNode = n => {
+      if (n.children.length === 0) {
+        return n.text
+      }
+      return {
+        text: n.text,
+        children: n.children.map(cleanNode),
+      }
+    }
+
+    return result.map(cleanNode)
+  }
+
+  /**
+   * Helper to recursively scan a container for shapes.
+   */
+  findShapeRecursive(container, shapeId) {
+    if (!container) return null
+
+    let shapes = container['p:sp'] || []
+    if (!Array.isArray(shapes)) shapes = [shapes]
+
+    for (const shape of shapes) {
+      const cNvPr = shape?.['p:nvSpPr']?.['p:cNvPr']
+      if (cNvPr) {
+        if (cNvPr['@_name'] === shapeId || String(cNvPr['@_id']) === shapeId) {
+          return { shape, parent: container, type: 'sp' }
+        }
+      }
+    }
+
+    let groups = container['p:grpSp'] || []
+    if (!Array.isArray(groups)) groups = [groups]
+
+    for (const group of groups) {
+      const res = this.findShapeRecursive(group, shapeId)
+      if (res) return res
+    }
+
+    return null
+  }
 }
 
 module.exports = { TextManager }

package/src/managers/charts/ChartCacheGenerator.js

@@ -16,7 +16,12 @@ class ChartCacheGenerator {
    */
   static generateNumCache(values) {
     const ptEntries = values
-      .map((val, i) => `<c:pt idx="${i}"><c:v>${Number(val) || 0}</c:v></c:pt>`)
+      .map((val, i) => {
+        if (val === null || val === undefined) {
+          return `<c:pt idx="${i}"/>`
+        }
+        return `<c:pt idx="${i}"><c:v>${val}</c:v></c:pt>`
+      })
       .join('')
     return `<c:numCache><c:formatCode>General</c:formatCode><c:ptCount val="${values.length}"/>${ptEntries}</c:numCache>`
   }
@@ -189,6 +194,8 @@ class ChartCacheGenerator {
       let existingTxPr = ''
       let existingDLblPos = ''
       let existingNumFmt = ''
+      let existingSpPr = ''
+      const existingDLblSpPrs = {}
       const existingShowTags = {}
 
       const dLblsMatch = /<c:dLbls>([\s\S]*?)<\/c:dLbls>/.exec(content)
@@ -206,6 +213,26 @@ class ChartCacheGenerator {
         if (numFmtMatch) {
           existingNumFmt = numFmtMatch[1]
         }
+        const spPrMatch = /(<c:spPr>[\s\S]*?<\/c:spPr>)/.exec(dLblsContent)
+        if (spPrMatch) {
+          existingSpPr = spPrMatch[1]
+        }
+
+        // Parse individual <c:dLbl> shape properties to map their background fills
+        const dLblPattern = /<c:dLbl>([\s\S]*?)<\/c:dLbl>/g
+        let dLblMatch
+        while ((dLblMatch = dLblPattern.exec(dLblsContent)) !== null) {
+          const dLblContent = dLblMatch[1]
+          const idxMatch = /<c:idx val="(\d+)"\/>/.exec(dLblContent)
+          if (idxMatch) {
+            const idx = parseInt(idxMatch[1], 10)
+            const dLblSpPrMatch = /(<c:spPr>[\s\S]*?<\/c:spPr>)/.exec(dLblContent)
+            if (dLblSpPrMatch) {
+              existingDLblSpPrs[idx] = dLblSpPrMatch[1]
+            }
+          }
+        }
+
         const showTagsList = [
           'showLegendKey',
           'showVal',
@@ -231,7 +258,9 @@ class ChartCacheGenerator {
         existingTxPr,
         existingDLblPos,
         existingNumFmt,
-        existingShowTags
+        existingShowTags,
+        existingSpPr,
+        existingDLblSpPrs
       )
 
       let updatedContent = content
@@ -259,7 +288,9 @@ class ChartCacheGenerator {
     existingTxPr = '',
     existingDLblPos = '',
     existingNumFmt = '',
-    existingShowTags = {}
+    existingShowTags = {},
+    existingSpPr = '',
+    existingDLblSpPrs = {}
   ) {
     const { labels, labelsFromCells, template, position, labelStyle, labelMap } = options
 
@@ -372,6 +403,25 @@ class ChartCacheGenerator {
           }
         }
 
+        // Restore individual point-level spPr (background fill, border, line) from template.
+        // Priority: individual dLbl spPr → first available individual dLbl spPr → series-level spPr.
+        // The series-level spPr fallback ensures fills are preserved even when the template stores
+        // styling only at the dLbls level (not per individual dLbl override).
+        if (existingDLblSpPrs && existingDLblSpPrs[i]) {
+          xml += existingDLblSpPrs[i]
+        } else {
+          const firstIdx =
+            existingDLblSpPrs && Object.keys(existingDLblSpPrs).length > 0
+              ? Object.keys(existingDLblSpPrs)[0]
+              : undefined
+          if (firstIdx !== undefined && existingDLblSpPrs[firstIdx]) {
+            xml += existingDLblSpPrs[firstIdx]
+          } else if (existingSpPr) {
+            // Fall back to series-level spPr so fills are preserved on each label
+            xml += existingSpPr
+          }
+        }
+
         if (labelStyle) {
           xml += this.generateTxPrXml(labelStyle)
         } else if (existingTxPr) {
@@ -399,6 +449,11 @@ class ChartCacheGenerator {
       xml += existingNumFmt
     }
 
+    // Restore series-level spPr (background fill, border, line) from template
+    if (existingSpPr) {
+      xml += existingSpPr
+    }
+
     if (labelStyle) {
       xml += this.generateTxPrXml(labelStyle)
     } else if (existingTxPr) {

package/src/managers/charts/ChartWorkbookUpdater.js

@@ -123,6 +123,22 @@ class ChartWorkbookUpdater {
   static #updateCellGrid(cells, data) {
     const { categories = [], series = [] } = data
 
+    // Clear cells that are outside the new category/series grid
+    const maxRow = categories.length + 1
+    const maxCol = series.length // Column A is 0, Column B is 1, etc.
+
+    for (const ref of Object.keys(cells)) {
+      const match = /^([A-Z]+)(\d+)$/.exec(ref)
+      if (match) {
+        const colLetter = match[1]
+        const row = parseInt(match[2], 10)
+        const col = this.colLetterToNum(colLetter)
+        if (row > maxRow || col > maxCol) {
+          delete cells[ref]
+        }
+      }
+    }
+
     // 1. Write Header A1 as empty
     cells['A1'] = ''
 
@@ -142,7 +158,7 @@ class ChartWorkbookUpdater {
       const colLetter = this.getColumnLetter(colIndex + 1)
       if (ser.values) {
         ser.values.forEach((val, rowIndex) => {
-          cells[`${colLetter}${rowIndex + 2}`] = val !== undefined ? val : 0
+          cells[`${colLetter}${rowIndex + 2}`] = val !== undefined ? val : null
         })
       }
     })
@@ -203,7 +219,9 @@ class ChartWorkbookUpdater {
         if (colNum > maxColNum) maxColNum = colNum
 
         const val = cells[ref]
-        if (typeof val === 'number') {
+        if (val === null || val === undefined) {
+          sheetData += `<c r="${ref}" t="inlineStr"><is><t></t></is></c>`
+        } else if (typeof val === 'number') {
           sheetData += `<c r="${ref}"><v>${val}</v></c>`
         } else {
           sheetData += `<c r="${ref}" t="inlineStr"><is><t>${this.#escapeXml(String(val))}</t></is></c>`