@jsamuel1/pptxgenjs 4.1.3 → 4.1.4

package/dist/pptxgen.cjs.js

@@ -1,4 +1,4 @@
-/* PptxGenJS 4.1.1 @ 2026-06-07T21:17:30.867Z */
+/* PptxGenJS 4.1.4 @ 2026-06-08T05:10:40.789Z */
 'use strict';
 
 var JSZip = require('jszip');
@@ -844,11 +844,14 @@ function genXmlGradientFill(props) {
     const stops = [...props.stops].sort((a, b) => (a.position || 0) - (b.position || 0));
     const gsList = stops
         .map(stop => {
-        // position 0–100 → `pos` in thousandths of a percent (× 1000)
-        const pos = Math.round((stop.position || 0) * 1000);
+        // position 0–100 → `pos` in thousandths of a percent (× 1000).
+        // `pos` is ST_PositiveFixedPercentage [0,100000]; clamp the 0–100 input
+        // before scaling so out-of-range stops stay schema-valid (clamp-don't-crash).
+        const pos = Math.round(Math.max(0, Math.min(100, stop.position || 0)) * 1000);
         // Per-stop transparency uses PROMPT.md direct mapping (100 = opaque → 100000; 40 → 40000).
         // NOTE: this differs from the solid-fill path which inverts via `(100 - transparency) * 1000`.
-        const inner = typeof stop.transparency === 'number' ? `<a:alpha val="${Math.round(stop.transparency * 1000)}"/>` : '';
+        // `a:alpha@val` is also ST_PositiveFixedPercentage [0,100000]; clamp into [0,100] first.
+        const inner = typeof stop.transparency === 'number' ? `<a:alpha val="${Math.round(Math.max(0, Math.min(100, stop.transparency)) * 1000)}"/>` : '';
         return `<a:gs pos="${pos}">${createColorElement(stop.color, inner)}</a:gs>`;
     })
         .join('');
@@ -1091,6 +1094,75 @@ function svgPathToOoxml(svgPathD, width, height) {
     }
     return `<a:custGeom><a:avLst/><a:gdLst/><a:ahLst/><a:cxnLst/><a:rect l="l" t="t" r="r" b="b"/><a:pathLst><a:path w="${pathW}" h="${pathH}">${xml}</a:path></a:pathLst></a:custGeom>`;
 }
+/**
+ * Compute evenly-spaced grid cell positions within a bounding area.
+ * - Pure math utility (no OOXML emission); returns one `{ x, y, w, h }` (inches) per item, in item order.
+ * - Eliminates repetitive grid-math when positioning capability cards, icon grids, comparison layouts, etc.
+ *
+ * Calculation (per item `i`):
+ *   cellW = (area.w - (columns - 1) * gapX) / columns
+ *   rows  = ceil(items / columns)
+ *   cellH = (area.h - (rows - 1) * gapY) / rows
+ *   col = i % columns; row = floor(i / columns)
+ *   x = area.x + col * (cellW + gapX); y = area.y + row * (cellH + gapY)
+ *
+ * @param {LayoutGridProps} props - grid options
+ * @returns {LayoutGridResult} array of `{ x, y, w, h }` cells (inches), one per item
+ * @throws {Error} when `area` has zero/negative width or height
+ * @example pptx.layoutGrid({ items: 6, columns: 3, area: { x: 0.5, y: 2, w: 12, h: 4 }, gap: 0.2 })
+ */
+function layoutGrid(props) {
+    var _a, _b, _c, _d, _e;
+    const { items, columns, area } = props;
+    const gap = (_a = props.gap) !== null && _a !== void 0 ? _a : 0.2;
+    const gapX = (_b = props.gapX) !== null && _b !== void 0 ? _b : gap;
+    const gapY = (_c = props.gapY) !== null && _c !== void 0 ? _c : gap;
+    const padding = (_d = props.padding) !== null && _d !== void 0 ? _d : 0;
+    const align = (_e = props.align) !== null && _e !== void 0 ? _e : 'start';
+    // Edge case: no items -> empty result
+    if (!items || items <= 0)
+        return [];
+    // Guard: a zero/negative area can't be subdivided
+    if (!area || !(area.w > 0) || !(area.h > 0))
+        throw new Error('layoutGrid: `area` requires positive `w` and `h`');
+    if (!(columns > 0))
+        throw new Error('layoutGrid: `columns` must be a positive number');
+    const rows = Math.ceil(items / columns);
+    const cellW = (area.w - (columns - 1) * gapX) / columns;
+    const cellH = (area.h - (rows - 1) * gapY) / rows;
+    const result = [];
+    for (let i = 0; i < items; i++) {
+        const col = i % columns;
+        const row = Math.floor(i / columns);
+        // Items on the final (possibly partial) row can be re-aligned within the area
+        let rowCellW = cellW;
+        let rowOffsetX = 0;
+        const isLastRow = row === rows - 1;
+        const lastRowCount = items - (rows - 1) * columns;
+        if (isLastRow && lastRowCount < columns && lastRowCount > 0) {
+            const rowCols = lastRowCount;
+            if (align === 'stretch') {
+                // Widen the partial row's cells to fill the full area width
+                rowCellW = (area.w - (rowCols - 1) * gapX) / rowCols;
+            }
+            else if (align === 'center') {
+                // Centre the partial row (cells keep their size)
+                const rowWidth = rowCols * cellW + (rowCols - 1) * gapX;
+                rowOffsetX = (area.w - rowWidth) / 2;
+            }
+        }
+        const x = area.x + rowOffsetX + col * (rowCellW + gapX);
+        const y = area.y + row * (cellH + gapY);
+        // `padding` insets each cell box on all sides
+        result.push({
+            x: x + padding,
+            y: y + padding,
+            w: rowCellW - 2 * padding,
+            h: cellH - 2 * padding,
+        });
+    }
+    return result;
+}
 
 /**
  * PptxGenJS: Table Generation
@@ -2515,6 +2587,122 @@ function addCalloutDefinition(target, opts) {
         textOpts.objectName = options.objectName;
     addTextDefinition(target, [{ text: options.text || '', options: null }], textOpts, false);
 }
+/**
+ * Adds a structured "card" to a slide definition (docs/feature-card-helper.md).
+ * Builds a single shape group (`<p:grpSp>`) containing a rounded-rect background and,
+ * as applicable, an icon container + icon (SVG path or emoji/text), a title, a description,
+ * and a top-right badge — all positioned with group-relative coordinates. When `animation`
+ * is supplied it is attached to the group object so the whole card animates as one.
+ * @param {PresSlide} target slide the card should be added to
+ * @param {CardProps} opts card options
+ */
+function addCardDefinition(target, opts) {
+    const options = typeof opts === 'object' ? opts : {};
+    const x = options.x !== undefined ? Number(options.x) : 1;
+    const y = options.y !== undefined ? Number(options.y) : 1;
+    const w = options.w !== undefined ? Number(options.w) : 3;
+    const h = options.h !== undefined ? Number(options.h) : 2;
+    const padding = 0.2;
+    const cornerRadius = options.cornerRadius !== undefined ? options.cornerRadius : 0.12;
+    const fill = options.fill !== undefined ? options.fill : '1a1a24';
+    const align = options.align === 'left' ? 'left' : 'center';
+    const iconPosition = options.iconPosition === 'left' ? 'left' : 'top';
+    const iconSize = options.iconSize !== undefined ? Number(options.iconSize) : 0.4;
+    const hasIcon = options.icon !== undefined && options.icon !== null;
+    const titleFont = options.titleFont || {};
+    const descFont = options.descFont || {};
+    const textAlign = align === 'center' ? 'center' : 'left';
+    // Create the group container; children below use coords relative to the group origin (0,0..w,h)
+    const group = addGroupDefinition(target, { x, y, w, h, objectName: options.objectName });
+    // The group is the just-pushed top-level slide object — grab it so card-level animation can attach
+    const groupObj = target._slideObjects[target._slideObjects.length - 1];
+    if (options.animation && groupObj && groupObj.options)
+        groupObj.options.animation = options.animation;
+    // 1) Background roundRect (fill + optional border/shadow/glow). `rectRadius` maps inches -> adj.
+    const bgOpts = {
+        x: 0, y: 0, w, h,
+        fill: typeof fill === 'string' ? { color: fill } : fill,
+        rectRadius: cornerRadius,
+    };
+    if (options.border)
+        bgOpts.line = { color: options.border.color || '2A2438', width: options.border.width || 1 };
+    if (options.shadow)
+        bgOpts.shadow = Object.assign({ type: 'outer' }, options.shadow);
+    if (options.glow)
+        bgOpts.glow = options.glow;
+    group.addShape(SHAPE_TYPE.ROUNDED_RECTANGLE, bgOpts);
+    // 2) Layout anchors for icon / title / description (group-relative inches)
+    let iconX = (w - iconSize) / 2;
+    let iconY = padding;
+    let titleX = padding;
+    let titleY = hasIcon ? padding + iconSize + 0.15 : padding;
+    let titleW = w - 2 * padding;
+    const titleH = 0.4;
+    if (iconPosition === 'left' && hasIcon) {
+        iconX = padding;
+        iconY = padding;
+        titleX = padding + iconSize + 0.2;
+        titleY = padding;
+        titleW = w - titleX - padding;
+    }
+    const descX = titleX;
+    const descY = titleY + titleH + 0.05;
+    const descW = titleW;
+    const descH = Math.max(0.2, h - descY - padding);
+    // 3) Icon container + glyph
+    if (hasIcon) {
+        const iconFill = options.iconFill !== undefined ? options.iconFill : '7C3AED';
+        group.addShape(SHAPE_TYPE.ROUNDED_RECTANGLE, {
+            x: iconX, y: iconY, w: iconSize, h: iconSize,
+            fill: { color: iconFill }, rectRadius: cornerRadius / 2, line: { type: 'none' },
+        });
+        const glyphColor = titleFont.color || 'E4E4ED';
+        if (typeof options.icon === 'string') {
+            // Emoji / text glyph centred in the container
+            group.addText(options.icon, {
+                x: iconX, y: iconY, w: iconSize, h: iconSize,
+                align: 'center', valign: 'middle', fontSize: Math.round(iconSize * 36), color: glyphColor,
+            });
+        }
+        else if (options.icon && typeof options.icon === 'object' && options.icon.svgPath) {
+            // SVG path glyph, inset within the container; emits <a:custGeom>
+            const inset = iconSize * 0.22;
+            group.addShape('rect', {
+                x: iconX + inset, y: iconY + inset, w: iconSize - 2 * inset, h: iconSize - 2 * inset,
+                svgPath: options.icon.svgPath, fill: { color: glyphColor }, line: { type: 'none' },
+            });
+        }
+    }
+    // 4) Title
+    group.addText(options.title || '', {
+        x: titleX, y: titleY, w: titleW, h: titleH,
+        fontFace: titleFont.face, fontSize: titleFont.size !== undefined ? titleFont.size : 13,
+        bold: titleFont.bold !== undefined ? titleFont.bold : true,
+        color: titleFont.color || 'E4E4ED', align: textAlign, valign: 'top',
+    });
+    // 5) Description (shrink-to-fit so overflow stays inside the card)
+    if (options.description) {
+        group.addText(options.description, {
+            x: descX, y: descY, w: descW, h: descH,
+            fontFace: descFont.face, fontSize: descFont.size !== undefined ? descFont.size : 10,
+            bold: descFont.bold !== undefined ? descFont.bold : false,
+            color: descFont.color || '8A8A9A', align: textAlign, valign: 'top', fit: 'shrink',
+        });
+    }
+    // 6) Badge (top-right)
+    if (options.badge && options.badge.text) {
+        const badgeH = 0.28;
+        const badgeW = Math.max(0.5, options.badge.text.length * 0.11 + 0.2);
+        group.addShape(SHAPE_TYPE.ROUNDED_RECTANGLE, {
+            x: w - badgeW - padding, y: padding, w: badgeW, h: badgeH,
+            fill: { color: options.badge.fill || '10B981' }, rectRadius: badgeH / 2, line: { type: 'none' },
+        });
+        group.addText(options.badge.text, {
+            x: w - badgeW - padding, y: padding, w: badgeW, h: badgeH,
+            align: 'center', valign: 'middle', fontSize: 8, bold: true, color: options.badge.color || 'FFFFFF',
+        });
+    }
+}
 /**
  * Feature 6: Adds a shape group to a slide definition and returns a group handle.
  * The group emits a `<p:grpSp>` whose `<a:xfrm>` carries the absolute position/size plus
@@ -2858,9 +3046,14 @@ function addTextDefinition(target, text, opts, isPlaceholder) {
                 const value = from + i;
                 const frameOpts = Object.assign({}, opts);
                 delete frameOpts.counter;
-                // Sequential entrance: first frame immediately, each later frame one step after the previous.
-                frameOpts.animation = { type: 'appear', trigger: 'afterPrevious', delay: i === 0 ? 0 : stepMs };
-                // Every frame except the last hides itself one step after appearing -> count-up effect.
+                // Odometer entrance: ALL frames live in ONE parallel build step (`withPrevious`),
+                // each appearing at a CUMULATIVE delay from the container start (frame 0 -> 0,
+                // frame 1 -> stepMs, frame 2 -> 2*stepMs, ...). `afterPrevious` would split each
+                // frame into a separate build step in genXmlTiming, breaking the count-up; using
+                // `withPrevious` keeps them in one group so the staggered delays drive the odometer.
+                frameOpts.animation = { type: 'appear', trigger: 'withPrevious', delay: i * stepMs };
+                // Every frame except the last hides itself one step after IT appears (the exit delay
+                // is relative to each frame's own appearance), so frame N+1 masks frame N -> count-up.
                 if (i < frameCount - 1)
                     frameOpts._counterExit = stepMs;
                 else
@@ -3269,6 +3462,16 @@ class Slide {
         addCalloutDefinition(this, options);
         return this;
     }
+    /**
+     * Add a structured card (rounded-rect background + optional icon/title/description/badge)
+     * to Slide as a single shape group.
+     * @param {CardProps} options - card options
+     * @return {Slide} this Slide
+     */
+    addCard(options) {
+        addCardDefinition(this, options);
+        return this;
+    }
     /**
      * Add table to Slide
      * @param {TableRow[]} tableRows - table rows
@@ -3990,7 +4193,7 @@ function makeXmlCharts(rel) {
  * @example '<c:lineChart>'
  * @return {string} XML chart
  */
-function makeChartType(chartType, data, opts, valAxisId, catAxisId, isMultiTypeChart) {
+function makeChartType(chartType, data, opts, valAxisId, catAxisId, _isMultiTypeChart) {
     // NOTE: "Chart Range" (as shown in "select Chart Area dialog") is calculated.
     // ....: Ensure each X/Y Axis/Col has same row height (esp. applicable to XY Scatter where X can often be larger than Y's)
     let colorIndex = -1; // Maintain the color index by region
@@ -4015,6 +4218,11 @@ function makeChartType(chartType, data, opts, valAxisId, catAxisId, isMultiTypeC
             if (chartType === CHART_TYPE.RADAR) {
                 strXml += '<c:radarStyle val="' + opts.radarStyle + '"/>';
             }
+            // `c:grouping` is a required first child of CT_LineChart (EG_LineChartShared, minOccurs=1)
+            // and must precede `c:varyColors`. Without it, line/combo charts fail schema validation.
+            if (chartType === CHART_TYPE.LINE) {
+                strXml += '<c:grouping val="standard"/>';
+            }
             strXml += '<c:varyColors val="0"/>';
             // 2: "Series" block for every data row
             /* EX1:
@@ -4090,7 +4298,26 @@ function makeChartType(chartType, data, opts, valAxisId, catAxisId, isMultiTypeC
                 }
                 strXml += createShadowElement(opts.shadow, DEF_SHAPE_SHADOW);
                 strXml += '  </c:spPr>';
-                strXml += '  <c:invertIfNegative val="0"/>';
+                // `c:invertIfNegative` is only valid on bar/bar3D series (CT_BarSer). Emitting it for
+                // area/line/radar series violates the OOXML schema (invalid child of CT_AreaSer/CT_LineSer/CT_RadarSer).
+                if (chartType === CHART_TYPE.BAR || chartType === CHART_TYPE.BAR3D) {
+                    strXml += '  <c:invertIfNegative val="0"/>';
+                }
+                // 'c:marker' tag: `lineDataSymbol`
+                // NOTE: CT_LineSer requires `marker` to precede `dLbls` (sequence: …spPr, marker?, dPt*, dLbls?…),
+                // so this block must be emitted before the `c:dLbls` block below or line/combo charts fail schema validation.
+                if (chartType === CHART_TYPE.LINE || chartType === CHART_TYPE.RADAR) {
+                    strXml += '<c:marker>';
+                    strXml += '  <c:symbol val="' + opts.lineDataSymbol + '"/>';
+                    if (opts.lineDataSymbolSize)
+                        strXml += `<c:size val="${opts.lineDataSymbolSize}"/>`; // Defaults to "auto" otherwise (but this is usually too small, so there is a default)
+                    strXml += '  <c:spPr>';
+                    strXml += `    <a:solidFill>${createColorElement(opts.chartColors[obj._dataIndex + 1 > opts.chartColors.length ? Math.floor(Math.random() * opts.chartColors.length) : obj._dataIndex])}</a:solidFill>`;
+                    strXml += `    <a:ln w="${opts.lineDataSymbolLineSize}" cap="flat"><a:solidFill>${createColorElement(opts.lineDataSymbolLineColor || seriesColor)}</a:solidFill><a:prstDash val="solid"/><a:round/></a:ln>`;
+                    strXml += '    <a:effectLst/>';
+                    strXml += '  </c:spPr>';
+                    strXml += '</c:marker>';
+                }
                 // Data Labels per series
                 // NOTE: [20190117] Adding these to RADAR chart causes unrecoverable corruption!
                 if (chartType !== CHART_TYPE.RADAR) {
@@ -4111,19 +4338,6 @@ function makeChartType(chartType, data, opts, valAxisId, catAxisId, isMultiTypeC
                     strXml += `<c:showLeaderLines val="${opts.showLeaderLines ? '1' : '0'}"/>`;
                     strXml += '</c:dLbls>';
                 }
-                // 'c:marker' tag: `lineDataSymbol`
-                if (chartType === CHART_TYPE.LINE || chartType === CHART_TYPE.RADAR) {
-                    strXml += '<c:marker>';
-                    strXml += '  <c:symbol val="' + opts.lineDataSymbol + '"/>';
-                    if (opts.lineDataSymbolSize)
-                        strXml += `<c:size val="${opts.lineDataSymbolSize}"/>`; // Defaults to "auto" otherwise (but this is usually too small, so there is a default)
-                    strXml += '  <c:spPr>';
-                    strXml += `    <a:solidFill>${createColorElement(opts.chartColors[obj._dataIndex + 1 > opts.chartColors.length ? Math.floor(Math.random() * opts.chartColors.length) : obj._dataIndex])}</a:solidFill>`;
-                    strXml += `    <a:ln w="${opts.lineDataSymbolLineSize}" cap="flat"><a:solidFill>${createColorElement(opts.lineDataSymbolLineColor || seriesColor)}</a:solidFill><a:prstDash val="solid"/><a:round/></a:ln>`;
-                    strXml += '    <a:effectLst/>';
-                    strXml += '  </c:spPr>';
-                    strXml += '</c:marker>';
-                }
                 // Allow users with a single data set to pass their own array of colors (check for this using != ours)
                 // Color chart bars various colors when >1 color
                 // NOTE: `<c:dPt>` created with various colors will change PPT legend by design so each dataPt/color is an legend item!
@@ -4272,6 +4486,7 @@ function makeChartType(chartType, data, opts, valAxisId, catAxisId, isMultiTypeC
             // 2: Series: (One for each Y-Axis)
             colorIndex = -1;
             data.filter((_obj, idx) => idx > 0).forEach((obj, idx) => {
+                var _a;
                 colorIndex++;
                 strXml += '<c:ser>';
                 strXml += `  <c:idx val="${idx}"/>`;
@@ -4324,7 +4539,7 @@ function makeChartType(chartType, data, opts, valAxisId, catAxisId, isMultiTypeC
                 // Option: scatter data point labels
                 if (opts.showLabel) {
                     const chartUuid = getUuid('-xxxx-xxxx-xxxx-xxxxxxxxxxxx');
-                    if (obj.labels[0] && (opts.dataLabelFormatScatter === 'custom' || opts.dataLabelFormatScatter === 'customXY')) {
+                    if (((_a = obj.labels) === null || _a === void 0 ? void 0 : _a[0]) && (opts.dataLabelFormatScatter === 'custom' || opts.dataLabelFormatScatter === 'customXY')) {
                         strXml += '<c:dLbls>';
                         obj.labels[0].forEach((label, idx) => {
                             if (opts.dataLabelFormatScatter === 'custom' || opts.dataLabelFormatScatter === 'customXY') {
@@ -4793,8 +5008,12 @@ function makeChartType(chartType, data, opts, valAxisId, catAxisId, isMultiTypeC
             // 4: Close "SERIES"
             strXml += '  </c:ser>';
             strXml += `  <c:firstSliceAng val="${opts.firstSliceAng ? Math.round(opts.firstSliceAng) : 0}"/>`;
-            if (chartType === CHART_TYPE.DOUGHNUT)
-                strXml += `<c:holeSize val="${typeof opts.holeSize === 'number' ? opts.holeSize : '50'}"/>`;
+            if (chartType === CHART_TYPE.DOUGHNUT) {
+                // ST_HoleSize restricts to [10,90]; clamp out-of-range input (clamp-don't-crash)
+                const rawHoleSize = typeof opts.holeSize === 'number' ? opts.holeSize : 50;
+                const holeSizeVal = Math.max(10, Math.min(90, Math.round(rawHoleSize)));
+                strXml += `<c:holeSize val="${holeSizeVal}"/>`;
+            }
             strXml += '</c:' + chartType + 'Chart>';
             // Done with Doughnut/Pie
             break;
@@ -4887,11 +5106,15 @@ function makeCatAxis(opts, axisId, valAxisId) {
     strXml += ' </c:txPr>';
     strXml += ' <c:crossAx val="' + valAxisId + '"/>';
     strXml += ` <c:${typeof opts.valAxisCrossesAt === 'number' ? 'crossesAt' : 'crosses'} val="${opts.valAxisCrossesAt || 'autoZero'}"/>`;
-    strXml += ' <c:auto val="1"/>';
-    strXml += ' <c:lblAlgn val="ctr"/>';
-    strXml += ` <c:noMultiLvlLbl val="${opts.catAxisMultiLevelLabels ? 0 : 1}"/>`;
-    if (opts.catAxisLabelFrequency)
-        strXml += ' <c:tickLblSkip val="' + opts.catAxisLabelFrequency + '"/>';
+    // NOTE: `auto`/`lblAlgn`/`noMultiLvlLbl`/`tickLblSkip` are CT_CatAx-only children and are invalid on the
+    // CT_ValAx that scatter/bubble/bubble3D charts emit for their (numeric) x-axis. Gate them to the catAx/dateAx case.
+    if (!(opts._type === CHART_TYPE.SCATTER || opts._type === CHART_TYPE.BUBBLE || opts._type === CHART_TYPE.BUBBLE3D)) {
+        strXml += ' <c:auto val="1"/>';
+        strXml += ' <c:lblAlgn val="ctr"/>';
+        strXml += ` <c:noMultiLvlLbl val="${opts.catAxisMultiLevelLabels ? 0 : 1}"/>`;
+        if (opts.catAxisLabelFrequency)
+            strXml += ' <c:tickLblSkip val="' + opts.catAxisLabelFrequency + '"/>';
+    }
     // Issue#149: PPT will auto-adjust these as needed after calcing the date bounds, so we only include them when specified by user
     // Allow major and minor units to be set for double value axis charts
     if (opts.catLabelFormatCode || opts._type === CHART_TYPE.SCATTER || opts._type === CHART_TYPE.BUBBLE || opts._type === CHART_TYPE.BUBBLE3D) {
@@ -7179,6 +7402,36 @@ function genXmlTiming(slide) {
     const presetMap = { appear: 1, fadeIn: 10, flyIn: 2, zoomIn: 23 };
     // trigger -> build-step wrapper nodeType
     const wrapNodeTypeMap = { afterPrevious: 'afterEffect', withPrevious: 'withEffect', onClick: 'clickEffect' };
+    // --- Pre-process group/stagger sugar into trigger/delay -------------------
+    // `group` is syntactic sugar over `trigger` (spec: docs/feature-animation-stagger.md).
+    // Walking the animated objects in order: the first object of each consecutive `group`
+    // run becomes the group leader (-> afterPrevious, starting a new build step); the rest
+    // of the run join it (-> withPrevious). When `stagger` is set, the Nth item within the
+    // run (0-indexed) gets `delay = N * stagger`. Objects without a `group` are left untouched
+    // so the explicit `trigger` behaviour stays byte-for-byte identical (backwards-compat).
+    // Entries are shallow-copied before mutation so the caller's `options.animation` is never
+    // modified (keeps repeated `stream()`/`write()` calls deterministic).
+    let prevGroup;
+    let groupIndex = 0;
+    animated.forEach(entry => {
+        const a = entry.anim;
+        if (typeof a.group === 'number') {
+            const isNewGroup = a.group !== prevGroup;
+            if (isNewGroup)
+                groupIndex = 0;
+            else
+                groupIndex++;
+            const resolved = Object.assign(Object.assign({}, a), { trigger: isNewGroup ? 'afterPrevious' : 'withPrevious' });
+            if (typeof a.stagger === 'number')
+                resolved.delay = groupIndex * a.stagger;
+            entry.anim = resolved;
+            prevGroup = a.group;
+        }
+        else {
+            // Ungrouped object forms its own step; reset so a later same-numbered group is a fresh run
+            prevGroup = undefined;
+        }
+    });
     const steps = [];
     animated.forEach(entry => {
         var _a;
@@ -7571,7 +7824,7 @@ function makeXmlViewProps() {
  *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  *  SOFTWARE.
  */
-const VERSION = '4.1.1';
+const VERSION = '4.1.4';
 class PptxGenJS {
     set layout(value) {
         const newLayout = this.LAYOUTS[value];
@@ -7924,6 +8177,7 @@ class PptxGenJS {
             addImage: null,
             addMedia: null,
             addNotes: null,
+            addCard: null,
             addShape: null,
             addTable: null,
             addText: null,
@@ -8086,6 +8340,16 @@ class PptxGenJS {
         }
         return newSlide;
     }
+    /**
+     * Compute evenly-spaced grid cell positions within a bounding area.
+     * - Pure layout helper: returns one `{ x, y, w, h }` (inches) per item; emits no slide content.
+     * @param {LayoutGridProps} props - grid options
+     * @returns {LayoutGridResult} array of `{ x, y, w, h }` cells (inches), one per item
+     * @example const grid = pptx.layoutGrid({ items: 6, columns: 3, area: { x: 0.5, y: 2, w: 12, h: 4 }, gap: 0.2 })
+     */
+    layoutGrid(props) {
+        return layoutGrid(props);
+    }
     /**
      * Create a custom Slide Layout in any size
      * @param {PresLayout} layout - layout properties