@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/numbering/list-format.js

@@ -0,0 +1,590 @@
+import { DocxError, InvalidArgumentError } from '../../core/errors/docx-error';
+import { visitParagraphsInDocumentOrder } from '../../core/registry/index';
+import { ListType } from './list-style';
+import { numberingFor } from './index';
+var MAX_LIST_LEVEL = 8;
+var stylesLookupFactory;
+/**
+ * @private Registered by the styles feature so applyStyle avoids CJS require under Vitest.
+ */
+export function setStylesLookupFactory(factory) {
+    stylesLookupFactory = factory;
+}
+/**
+ * @private Test-only reset.
+ */
+export function resetStylesLookupFactoryForTests() {
+    stylesLookupFactory = undefined;
+}
+/**
+ * Live paragraph list formatting (`w:pPr/w:numPr` + document numbering catalog).
+ *
+ * Obtained via {@link Paragraph.listFormat}. The same logical instance is returned
+ * for repeated access on the same paragraph; mutations update the paragraph and
+ * numbering definitions immediately.
+ *
+ * @public
+ */
+var ListFormat = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function ListFormat(paragraph) {
+        this.paragraph = paragraph;
+    }
+    Object.defineProperty(ListFormat.prototype, "ownerParagraph", {
+        /** Owning paragraph. */
+        get: function () {
+            return this.paragraph;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "listId", {
+        /** Numbering instance id (`w:num/@w:numId`), when the paragraph is in a list. */
+        get: function () {
+            return this.paragraph.numId;
+        },
+        /**
+         * Assign an existing numbering instance id, or clear with `undefined`.
+         * Prefer {@link applyDefBulletStyle} / {@link applyDefNumberedStyle} for new lists.
+         *
+         * Does not fabricate a default definition for unknown ids.
+         */
+        set: function (value) {
+            if (value === undefined) {
+                this.removeList();
+                return;
+            }
+            if (typeof value !== 'number' || !Number.isFinite(value) || value < 1 || Math.floor(value) !== value) {
+                throw new InvalidArgumentError('listId must be a positive integer');
+            }
+            var numbering = this.catalog();
+            var resolved = numbering.getNumbering(value);
+            if (resolved === undefined) {
+                if (numbering.hasInstance(value)) {
+                    // Pending authoring id (createBulletInstance / createDecimalInstance) — keep pending.
+                    numbering.registerPendingInstance(value);
+                }
+                else {
+                    throw new DocxError('content/invalid-num-id', 'Numbering instance ' + String(value) + ' is not defined in this document');
+                }
+            }
+            else {
+                numbering.registerPendingInstance(value);
+            }
+            this.paragraph.numId = value;
+            if (this.paragraph.listLevel === undefined) {
+                this.paragraph.listLevel = 0;
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "listLevelNumber", {
+        /** Zero-based indent level (`w:ilvl`), when present. */
+        get: function () {
+            return this.paragraph.listLevel;
+        },
+        set: function (value) {
+            if (value === undefined) {
+                if (this.paragraph.numId === undefined) {
+                    this.paragraph.listLevel = undefined;
+                    return;
+                }
+                throw new InvalidArgumentError('listLevelNumber cannot be cleared while the paragraph remains in a list');
+            }
+            this.assertLevel(value);
+            this.assertLevelExistsOnAbstract(value);
+            this.paragraph.listLevel = value;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "isList", {
+        /** Whether the paragraph is assigned to a numbering instance. */
+        get: function () {
+            return this.paragraph.numId !== undefined;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "listType", {
+        /**
+         * Broad list category from the resolved active level's `numFmt`.
+         * {@link ListType.Bulleted} when `numFmt` is `bullet`; otherwise {@link ListType.Numbered}.
+         */
+        get: function () {
+            var numberFormat = this.numberFormat;
+            if (numberFormat === undefined) {
+                return undefined;
+            }
+            if (numberFormat === 'bullet') {
+                return ListType.Bulleted;
+            }
+            return ListType.Numbered;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "numberFormat", {
+        /** Number format token at the active level (`w:numFmt/@w:val`). */
+        get: function () {
+            var level = this.resolvedListLevel;
+            return level === undefined ? undefined : level.numFmt;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "levelText", {
+        /** Level text pattern (`w:lvlText/@w:val`) at the active level. */
+        get: function () {
+            var level = this.resolvedListLevel;
+            return level === undefined ? undefined : level.lvlText;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "listStyleName", {
+        /** Named list style applied via {@link applyStyle}, when set. */
+        get: function () {
+            return this.listStyleNameValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "startAt", {
+        /** Start value at the active level (override or abstract level). */
+        get: function () {
+            var listId = this.paragraph.numId;
+            if (listId === undefined) {
+                return undefined;
+            }
+            var level = this.activeLevelIndex();
+            try {
+                var part = this.catalog();
+                var instance = part.getNumbering(listId);
+                if (instance !== undefined) {
+                    var override = instance.levelOverrides.find(function (entry) { return entry.ilvl === level; });
+                    if (override !== undefined && override.startOverride !== undefined) {
+                        return override.startOverride;
+                    }
+                }
+            }
+            catch (_a) {
+                // catalog unavailable
+            }
+            var levelDef = this.resolvedListLevel;
+            return levelDef === undefined ? undefined : levelDef.start;
+        },
+        /**
+         * Set a start override for the active level on the concrete numbering instance.
+         * Does not mutate the shared abstract definition.
+         */
+        set: function (value) {
+            if (value === undefined) {
+                throw new InvalidArgumentError('startAt cannot be cleared; pass a non-negative integer');
+            }
+            this.assertStartAt(value);
+            var listId = this.paragraph.numId;
+            if (listId === undefined) {
+                throw new DocxError('content/not-in-list', 'Paragraph is not in a list; apply a list style before setting startAt');
+            }
+            var numbering = this.catalog();
+            // Materialize pending so overrides can be stored on a concrete instance.
+            if (numbering.getNumbering(listId) === undefined) {
+                var format = this.inferEnsureFormat();
+                numbering.ensureInstance(listId, format);
+            }
+            var existing = numbering.getNumbering(listId);
+            if (existing === undefined) {
+                throw new DocxError('content/invalid-num-id', 'Numbering instance ' + String(listId) + ' could not be resolved');
+            }
+            existing.setStartOverride(this.activeLevelIndex(), value);
+            numbering.markDirty();
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "abstractNumId", {
+        /**
+         * @private
+         * Abstract numbering definition id when the instance is resolved.
+         */
+        get: function () {
+            var resolved = this.resolvedList;
+            return resolved === undefined ? undefined : resolved.abstractNumId;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "multiLevelType", {
+        /** Abstract multi-level type token, when available. */
+        get: function () {
+            var abs = this.resolvedAbstractList;
+            return abs === undefined ? undefined : abs.multiLevelType;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "name", {
+        /** Abstract definition name, when present. */
+        get: function () {
+            var abs = this.resolvedAbstractList;
+            return abs === undefined ? undefined : abs.name;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "resolvedList", {
+        /** Resolved numbering instance (`w:num`), when available. */
+        get: function () {
+            var listId = this.paragraph.numId;
+            if (listId === undefined) {
+                return undefined;
+            }
+            try {
+                return this.catalog().getNumbering(listId);
+            }
+            catch (_a) {
+                return undefined;
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "resolvedAbstractList", {
+        /** Resolved abstract numbering definition, when available. */
+        get: function () {
+            var instance = this.resolvedList;
+            if (instance === undefined) {
+                return undefined;
+            }
+            try {
+                return this.catalog().getAbstractNumbering(instance.abstractNumId);
+            }
+            catch (_a) {
+                return undefined;
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ListFormat.prototype, "resolvedListLevel", {
+        /** Resolved active list level definition, when available. */
+        get: function () {
+            var listId = this.paragraph.numId;
+            if (listId === undefined) {
+                return undefined;
+            }
+            var level = this.activeLevelIndex();
+            try {
+                return resolveLevelDefinition(this.catalog(), listId, level);
+            }
+            catch (_a) {
+                return undefined;
+            }
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Apply the default nine-level bullet list and set level `0`.
+     */
+    ListFormat.prototype.applyDefBulletStyle = function () {
+        var numbering = this.catalog();
+        var listId = numbering.createBulletInstance();
+        this.paragraph.numId = listId;
+        this.paragraph.listLevel = 0;
+        this.listStyleNameValue = undefined;
+    };
+    /**
+     * Apply the default nine-level numbered (decimal hybrid) list and set level `0`.
+     */
+    ListFormat.prototype.applyDefNumberedStyle = function () {
+        var numbering = this.catalog();
+        var listId = numbering.createDecimalInstance();
+        this.paragraph.numId = listId;
+        this.paragraph.listLevel = 0;
+        this.listStyleNameValue = undefined;
+    };
+    /**
+     * Apply a named numbering style from the document styles part.
+     *
+     * Resolves `type="numbering"` styles by style id or display name, then binds a
+     * numbering instance linked through `w:styleLink` / abstract name, or creates
+     * a new instance from a matching abstract definition.
+     *
+     * @param styleName - Non-empty style id or display name.
+     * @throws InvalidArgumentError when `styleName` is empty.
+     * @throws DocxError when the style is missing or not a numbering style.
+     */
+    ListFormat.prototype.applyStyle = function (styleName) {
+        if (typeof styleName !== 'string' || styleName.trim() === '') {
+            throw new InvalidArgumentError('styleName must be a non-empty string');
+        }
+        var name = styleName.trim();
+        var doc = this.paragraph.owningDocument();
+        if (stylesLookupFactory === undefined) {
+            throw new DocxError('feature/not-registered', 'Styles part is required to apply a list style; ensure styles are registered');
+        }
+        var styles;
+        try {
+            styles = stylesLookupFactory(doc);
+        }
+        catch (err) {
+            throw new DocxError('feature/not-registered', 'Styles part is required to apply a list style; ensure styles are registered', err instanceof Error ? { cause: err } : undefined);
+        }
+        var style = styles.getStyle(name) !== undefined
+            ? styles.getStyle(name)
+            : styles.findStyleByDisplayName(name);
+        if (style === undefined) {
+            throw new DocxError('styles/undefined-style', "Style \"" + name + "\" is not defined in this document");
+        }
+        if (style.type !== 'numbering') {
+            throw new DocxError('styles/invalid-type-for-target', "Style \"" + style.styleId + "\" is a " + String(style.type) + " style and cannot be used as a numbering style");
+        }
+        var numbering = this.catalog();
+        var listId = resolveNumberingStyleToInstance(numbering, style.styleId, style.name);
+        this.paragraph.numId = listId;
+        this.paragraph.listLevel = 0;
+        this.listStyleNameValue = style.name !== undefined ? style.name : style.styleId;
+    };
+    /**
+     * Continue the nearest preceding list in document order.
+     * Reuses that paragraph's numbering instance; keeps this paragraph's level when set.
+     *
+     * @throws DocxError when no preceding list paragraph exists in the document.
+     */
+    ListFormat.prototype.continueListNumbering = function () {
+        var _this = this;
+        var doc = this.paragraph.owningDocument();
+        var previous;
+        var foundSelf = false;
+        visitParagraphsInDocumentOrder(doc, function (p) {
+            if (foundSelf) {
+                return;
+            }
+            if (p === _this.paragraph) {
+                foundSelf = true;
+                return;
+            }
+            if (p.numId !== undefined) {
+                previous = p;
+            }
+        });
+        if (previous === undefined || previous.numId === undefined) {
+            throw new DocxError('content/no-preceding-list', 'No preceding list paragraph is available to continue');
+        }
+        var level = this.paragraph.listLevel !== undefined
+            ? this.paragraph.listLevel
+            : previous.listLevel !== undefined
+                ? previous.listLevel
+                : 0;
+        this.paragraph.numId = previous.numId;
+        this.paragraph.listLevel = level;
+        try {
+            this.catalog().registerPendingInstance(previous.numId);
+        }
+        catch (_a) {
+            // ignore if catalog not attached yet
+        }
+    };
+    /**
+     * Restart numbering as a new list instance that reuses the current abstract definition.
+     *
+     * @param startAt - Optional start value for the active level (`w:startOverride`).
+     */
+    ListFormat.prototype.restartNumbering = function (startAt) {
+        var listId = this.paragraph.numId;
+        if (listId === undefined) {
+            throw new DocxError('content/not-in-list', 'Paragraph is not in a list; apply a list style before restarting');
+        }
+        if (startAt !== undefined) {
+            this.assertStartAt(startAt);
+        }
+        var numbering = this.catalog();
+        // Materialize pending so abstract id is known.
+        if (numbering.getNumbering(listId) === undefined) {
+            numbering.ensureInstance(listId, this.inferEnsureFormat());
+        }
+        var existing = numbering.getNumbering(listId);
+        if (existing === undefined) {
+            throw new DocxError('content/invalid-num-id', "Numbering instance " + String(listId) + " could not be resolved");
+        }
+        var level = this.activeLevelIndex();
+        var start = startAt !== undefined ? startAt : 1;
+        var newId = numbering.createInstanceFromAbstract(existing.abstractNumId);
+        var restarted = numbering.getNumbering(newId);
+        if (restarted === undefined) {
+            throw new DocxError('content/invalid-num-id', "Failed to create restarted numbering instance");
+        }
+        restarted.setStartOverride(level, start);
+        numbering.markDirty();
+        this.paragraph.numId = newId;
+        this.paragraph.listLevel = level;
+    };
+    /**
+     * Increase the active list level by one (max 8). No-op when not in a list or already at 8.
+     */
+    ListFormat.prototype.increaseIndentLevel = function () {
+        if (this.paragraph.numId === undefined) {
+            return;
+        }
+        var current = this.activeLevelIndex();
+        if (current >= MAX_LIST_LEVEL) {
+            return;
+        }
+        this.paragraph.listLevel = current + 1;
+    };
+    /**
+     * Decrease the active list level by one (min 0). No-op when not in a list or already at 0.
+     * Does not remove list membership at level 0.
+     */
+    ListFormat.prototype.decreaseIndentLevel = function () {
+        if (this.paragraph.numId === undefined) {
+            return;
+        }
+        var current = this.activeLevelIndex();
+        if (current <= 0) {
+            return;
+        }
+        this.paragraph.listLevel = current - 1;
+    };
+    /**
+     * Remove list membership (`w:numPr` / numId and ilvl) without deleting catalog definitions.
+     */
+    ListFormat.prototype.removeList = function () {
+        this.paragraph.numId = undefined;
+        this.paragraph.listLevel = undefined;
+        this.listStyleNameValue = undefined;
+    };
+    ListFormat.prototype.catalog = function () {
+        return numberingFor(this.paragraph.owningDocument());
+    };
+    ListFormat.prototype.activeLevelIndex = function () {
+        var level = this.paragraph.listLevel;
+        return level !== undefined ? level : 0;
+    };
+    ListFormat.prototype.assertLevel = function (value) {
+        if (typeof value !== 'number' || !Number.isFinite(value) || Math.floor(value) !== value) {
+            throw new InvalidArgumentError('list level must be an integer from 0 through 8');
+        }
+        if (value < 0 || value > MAX_LIST_LEVEL) {
+            throw new InvalidArgumentError('list level must be an integer from 0 through 8');
+        }
+    };
+    ListFormat.prototype.assertStartAt = function (value) {
+        if (typeof value !== 'number' || !Number.isFinite(value) || Math.floor(value) !== value) {
+            throw new InvalidArgumentError('startAt must be a finite integer');
+        }
+        if (value < 0) {
+            throw new InvalidArgumentError('startAt must be a non-negative integer');
+        }
+    };
+    /**
+     * When abstract is already resolved, ensure `ilvl` exists; pending lists skip (nine levels on materialize).
+     */
+    ListFormat.prototype.assertLevelExistsOnAbstract = function (level) {
+        var listId = this.paragraph.numId;
+        if (listId === undefined) {
+            return;
+        }
+        try {
+            var part = this.catalog();
+            var instance = part.getNumbering(listId);
+            if (instance === undefined) {
+                return;
+            }
+            var abstract = part.getAbstractNumbering(instance.abstractNumId);
+            if (abstract === undefined) {
+                return;
+            }
+            var override = instance.levelOverrides.find(function (entry) { return entry.ilvl === level; });
+            if (override !== undefined && override.level !== undefined) {
+                return;
+            }
+            var fromAbstract = abstract.levels.find(function (entry) { return entry.ilvl === level; });
+            if (fromAbstract === undefined) {
+                throw new DocxError('content/invalid-list-level', 'List level ' + String(level) + ' does not exist on numbering instance ' + String(listId));
+            }
+        }
+        catch (err) {
+            if (err instanceof DocxError || err instanceof InvalidArgumentError) {
+                throw err;
+            }
+            // catalog unavailable — skip existence check
+        }
+    };
+    /** Map pending decimal ids to decimal ensure format; default bullet. */
+    ListFormat.prototype.inferEnsureFormat = function () {
+        var listId = this.paragraph.numId;
+        if (listId === undefined) {
+            return 'bullet';
+        }
+        try {
+            var part = this.catalog();
+            if (part.isPendingDecimal(listId)) {
+                return 'decimal';
+            }
+            var numberFormat = this.numberFormat;
+            if (numberFormat !== undefined && numberFormat !== 'bullet') {
+                return 'decimal';
+            }
+        }
+        catch (_a) {
+            // ignore
+        }
+        return 'bullet';
+    };
+    return ListFormat;
+}());
+export { ListFormat };
+/**
+ * @private
+ */
+export function resolveLevelDefinition(part, numId, level) {
+    var instance = part.getNumbering(numId);
+    if (instance === undefined) {
+        return undefined;
+    }
+    var abstract = part.getAbstractNumbering(instance.abstractNumId);
+    if (abstract === undefined) {
+        return undefined;
+    }
+    var override = instance.levelOverrides.find(function (entry) { return entry.ilvl === level; });
+    if (override !== undefined && override.level !== undefined) {
+        return override.level;
+    }
+    var fromAbstract = abstract.levels.find(function (entry) { return entry.ilvl === level; });
+    if (fromAbstract !== undefined) {
+        return fromAbstract;
+    }
+    // Do not silently fall back to level 0 when the requested level is missing.
+    return undefined;
+}
+function resolveNumberingStyleToInstance(numbering, styleId, displayName) {
+    for (var i = 0; i < numbering.abstractNumberings.length; i += 1) {
+        var abs = numbering.abstractNumberings[i];
+        var matchesStyle = abs.styleLink === styleId ||
+            (displayName !== undefined && abs.styleLink === displayName) ||
+            abs.name === styleId ||
+            (displayName !== undefined && abs.name === displayName);
+        if (!matchesStyle) {
+            if (abs.numStyleLink === styleId || (displayName !== undefined && abs.numStyleLink === displayName)) {
+                // External numStyleLink without a local abstract binding — keep searching.
+                continue;
+            }
+            continue;
+        }
+        // Reuse an existing w:num for this abstract so continued applyStyle shares counters.
+        for (var j = 0; j < numbering.numberings.length; j += 1) {
+            var inst = numbering.numberings[j];
+            if (inst.abstractNumId === abs.abstractNumId) {
+                return inst.numId;
+            }
+        }
+        return numbering.createInstanceFromAbstract(abs.abstractNumId);
+    }
+    throw new DocxError('content/unresolved-numbering-style', 'No numbering definition is linked to style "' + styleId + '"');
+}

package/src/features/numbering/list-string.d.ts

@@ -0,0 +1,7 @@
+import { Paragraph } from '../document/paragraph';
+/**
+ * Compute the display string for a paragraph's list label without mutating state.
+ *
+ * @private
+ */
+export declare function computeListString(paragraph: Paragraph): string;