@docx4j/core-ts 0.1.0 → 0.1.1

package/dist/model/listnumbering/definitions.mjs

@@ -0,0 +1,571 @@
+import { log } from '../properties/log.mjs';
+import { formatValue } from './formats.mjs';
+/** How many levels a list definition may have (ECMA-376: `w:ilvl` 0 to 8). */
+export const LEVELS = 9;
+/**
+ * One `w:lvl`: the abstract definition's level, and - for a level of a `w:num` - the instance's
+ * `w:lvlOverride/w:lvl` applied over it. docx4j `ListLevel`; the count lives in a
+ * {@link NumberingState}, keyed by {@link abstractNumId} and {@link ilvl}.
+ *
+ * Five members are **merged** attribute by attribute, as docx4j's `setOverrides` merges them -
+ * the override replaces each only where it states one: `w:start`, `w:lvlRestart`, `w:lvlText`,
+ * `w:numFmt` (and so `isBullet`), and the `w:hAnsi` of the level's `w:rPr/w:rFonts`.  Everything
+ * else is read off **one** `w:lvl`, the override where the instance has one and the abstract
+ * level otherwise ({@link controllingLvl}): `w:isLgl` (docx4j's rule, measured through
+ * `IsLglTest`), `w:pStyle`, `w:suff`, `w:lvlJc` and `w:lvlPicBulletId`.  `w:ind` and the label's
+ * `w:rPr` have rules of their own; see {@link ind} and {@link labelRPr}.
+ */
+export class LevelDefinition {
+    constructor(ilvl, lvl) {
+        /** The **referencing** `w:abstractNum` (the counter's key; never the `w:numStyleLink` target's). */
+        this.abstractNumId = '';
+        /** `w:start` **less one**, since every fetch increments first. */
+        this.startValue = 0;
+        /** This instance level carries a `w:startOverride`, spent on the `w:num`'s first use. */
+        this.hasStartOverride = false;
+        /** Whether `w:numFmt` is `bullet`. */
+        this.isBullet = false;
+        this.ilvl = ilvl;
+        this.abstractLvl = lvl;
+        if (lvl !== undefined)
+            this.read(lvl);
+    }
+    /** Take from a `w:lvl` whatever it states; leave the rest alone. docx4j's constructor body. */
+    read(lvl) {
+        var _a, _b, _c;
+        if (lvl.start !== undefined) {
+            // one less than the user set it to, since whenever we fetch the number we first increment
+            this.startValue = lvl.start.val - 1;
+        }
+        if (((_a = lvl.lvlRestart) === null || _a === void 0 ? void 0 : _a.val) !== undefined)
+            this.lvlRestart = lvl.lvlRestart.val;
+        if (lvl.lvlText !== undefined)
+            this.lvlText = lvl.lvlText.val;
+        const hAnsi = (_c = (_b = lvl.rPr) === null || _b === void 0 ? void 0 : _b.rFonts) === null || _c === void 0 ? void 0 : _c.hAnsi;
+        if (hAnsi !== undefined)
+            this.font = hAnsi;
+        if (lvl.numFmt !== undefined) {
+            this.numFmt = lvl.numFmt.val;
+            this.isBullet = lvl.numFmt.val === 'bullet';
+        }
+    }
+    /** A copy for an instance definition. docx4j's copy constructor: no override, no owner. */
+    copy() {
+        const other = new LevelDefinition(this.ilvl);
+        other.abstractLvl = this.abstractLvl;
+        other.abstractNumId = this.abstractNumId; // the counter is shared through the state, by this key
+        other.startValue = this.startValue;
+        other.lvlRestart = this.lvlRestart;
+        other.lvlText = this.lvlText;
+        other.numFmt = this.numFmt;
+        other.isBullet = this.isBullet;
+        other.font = this.font;
+        return other;
+    }
+    /** Applies the instance's `w:lvlOverride/w:lvl`. docx4j `setOverrides`. */
+    applyOverride(lvl) {
+        this.overrideLvl = lvl;
+        this.read(lvl);
+    }
+    /** A `w:startOverride`: given effect on the first use of this `w:num` in a story. */
+    setStartValue(value) {
+        this.startValue = value;
+        this.hasStartOverride = true;
+    }
+    /** `w:ilvl` as a number. */
+    get level() {
+        const n = Number(this.ilvl);
+        return Number.isFinite(n) ? n : 0;
+    }
+    /**
+     * The one `w:lvl` the members docx4j does not merge are read from: the instance's override
+     * where there is one, else the abstract level's.
+     */
+    get controllingLvl() {
+        var _a;
+        return (_a = this.overrideLvl) !== null && _a !== void 0 ? _a : this.abstractLvl;
+    }
+    /** `w:start` as the document states it (one more than {@link startValue}). */
+    get start() {
+        return this.abstractLvl === undefined && this.overrideLvl === undefined ? undefined : this.startValue + 1;
+    }
+    /**
+     * `w:isLgl`: the levels this number *inherits* print in decimal whatever their own `w:numFmt`
+     * (Word's "legal style numbering": "Section 1.01" and not "Section I.01").
+     */
+    get isLgl() {
+        var _a;
+        const isLgl = (_a = this.controllingLvl) === null || _a === void 0 ? void 0 : _a.isLgl;
+        return isLgl !== undefined && isLgl.val !== false;
+    }
+    /** The `w:pStyle` this level is linked to (ECMA-376 17.9.24), or undefined. */
+    get pStyle() {
+        var _a, _b;
+        const override = this.overrideLvl;
+        if (override !== undefined && override.pStyle !== undefined)
+            return override.pStyle.val;
+        return (_b = (_a = this.abstractLvl) === null || _a === void 0 ? void 0 : _a.pStyle) === null || _b === void 0 ? void 0 : _b.val;
+    }
+    /** `w:suff`: what separates the label from the text (tab, space, nothing). */
+    get suff() {
+        var _a, _b;
+        return (_b = (_a = this.controllingLvl) === null || _a === void 0 ? void 0 : _a.suff) === null || _b === void 0 ? void 0 : _b.val;
+    }
+    /** `w:lvlJc`: how the label is justified in its column. */
+    get lvlJc() {
+        var _a, _b;
+        return (_b = (_a = this.controllingLvl) === null || _a === void 0 ? void 0 : _a.lvlJc) === null || _b === void 0 ? void 0 : _b.val;
+    }
+    /** `w:lvlPicBulletId`: the `w:numPicBullet` a picture bullet level names. */
+    get lvlPicBulletId() {
+        var _a, _b;
+        return (_b = (_a = this.controllingLvl) === null || _a === void 0 ? void 0 : _a.lvlPicBulletId) === null || _b === void 0 ? void 0 : _b.val;
+    }
+    /** The level's `w:pPr`: the override's where it has one, else the abstract level's. */
+    get pPr() {
+        var _a, _b, _c;
+        return (_b = (_a = this.overrideLvl) === null || _a === void 0 ? void 0 : _a.pPr) !== null && _b !== void 0 ? _b : (_c = this.abstractLvl) === null || _c === void 0 ? void 0 : _c.pPr;
+    }
+    /**
+     * The level's **own** `w:ind`: the instance's override level's where *it* states one, else the
+     * abstract level's (docx4j `Emulator.getNumber`'s `triple.ind`, since 17.1.0).  The linked
+     * `w:pStyle`'s is not consulted here; {@link NumberingDefinitions.getInd} does that.
+     */
+    get ind() {
+        var _a, _b, _c, _d, _e;
+        return (_c = (_b = (_a = this.overrideLvl) === null || _a === void 0 ? void 0 : _a.pPr) === null || _b === void 0 ? void 0 : _b.ind) !== null && _c !== void 0 ? _c : (_e = (_d = this.abstractLvl) === null || _d === void 0 ? void 0 : _d.pPr) === null || _e === void 0 ? void 0 : _e.ind;
+    }
+    /** The **abstract** level's `w:rPr`, never the override's. docx4j `NumberingResult.getRPr()`. */
+    get rPr() {
+        var _a;
+        return (_a = this.abstractLvl) === null || _a === void 0 ? void 0 : _a.rPr;
+    }
+    /**
+     * The `w:rPr` the label is drawn with: the `w:lvlOverride/w:lvl`'s where the instance
+     * overrides this level with one carrying an rPr, else the abstract level's - one or the other,
+     * as Word applies them (CR-014 probe P3, measured: an abstract `w:i` under an override
+     * `w:b` + `w:sz 36` gives a bold 18pt label with no italic anywhere).  It formats the number
+     * alone, never the paragraph's text (ECMA-376 17.9.24).
+     */
+    get labelRPr() {
+        const override = this.overrideLvl;
+        return override !== undefined && override.rPr !== undefined ? override.rPr : this.rPr;
+    }
+    /** This level's counter in the given state. */
+    counter(state) {
+        return state.counter(this.abstractNumId, this.ilvl, this.startValue);
+    }
+    /**
+     * One more item at this level. docx4j `incrementCounter(state)`.
+     *
+     * The shared counter takes this level's start value the first time it is met in the state, and
+     * again the first time this instance level's `w:num` is met there when that `w:num` overrides
+     * the start - deferred until then, since otherwise earlier numbering over the same abstract
+     * list would use it.
+     */
+    incrementCounter(state) {
+        const counter = this.counter(state);
+        const overridePending = this.hasStartOverride && this.ownerNumId !== undefined
+            && !state.startOverrideApplied(this.ownerNumId, this.ilvl);
+        if (overridePending || !counter.encounteredAlready) {
+            counter.value = this.startValue;
+            counter.encounteredAlready = true;
+            counter.resetPending = false;
+            if (this.ownerNumId !== undefined)
+                state.markStartOverrideApplied(this.ownerNumId, this.ilvl);
+        }
+        if (counter.resetPending) {
+            // the reset already placed the counter at its start value (see resetCounter)
+            counter.resetPending = false;
+            return;
+        }
+        counter.increment();
+    }
+    /**
+     * A shallower level was used: the level shows its start value from now until it is next used,
+     * and that first use does not increment it (CR-014 probe P8; before, the counter went to
+     * start-1 and a deeper label printed "2.0.1" where Word prints "2.1.1").
+     */
+    resetCounter(state) {
+        const counter = this.counter(state);
+        counter.value = this.startValue + 1;
+        counter.resetPending = true;
+    }
+    /**
+     * Whether using `shallowerIlvl` (0-based) restarts this level. ECMA-376 17.9.11: without
+     * `w:lvlRestart` any shallower level restarts it; `w:val="0"` means none does; `w:val="n"`
+     * means levels 1..n (1-based, so ilvl 0..n-1) do and deeper ones do not.  Measured, P8.
+     */
+    restartsAfter(shallowerIlvl) {
+        if (this.lvlRestart === undefined)
+            return true;
+        if (this.lvlRestart <= 0)
+            return false;
+        return shallowerIlvl <= this.lvlRestart - 1;
+    }
+    /** The count at this level, in this level's `w:numFmt`. */
+    currentValueFormatted(state, where) {
+        return formatValue(this.numFmt, this.counter(state).value, where === undefined ? undefined : `${where} ilvl ${this.ilvl}`);
+    }
+    /** The count at this level as a decimal, whatever its `w:numFmt` (what `w:isLgl` shows). */
+    currentValueUnformatted(state) {
+        return String(this.counter(state).value);
+    }
+    toString() {
+        var _a, _b;
+        return `LevelDefinition ${this.ilvl} ${(_a = this.numFmt) !== null && _a !== void 0 ? _a : '-'} ${JSON.stringify((_b = this.lvlText) !== null && _b !== void 0 ? _b : '')}`;
+    }
+}
+/**
+ * One `w:abstractNum`: its levels, and - where it carries `w:numStyleLink` - the numbering style
+ * whose definition it takes them from. docx4j `AbstractListNumberingDefinition`.
+ */
+export class AbstractListDefinition {
+    constructor(abstractNum) {
+        var _a, _b;
+        this.abstractNum = abstractNum;
+        /** The levels, keyed by `w:ilvl` ("0" to "8"). */
+        this.levels = new Map();
+        this.id = String(abstractNum.abstractNumId);
+        this.linkedStyleId = (_a = abstractNum.numStyleLink) === null || _a === void 0 ? void 0 : _a.val;
+        this.styleLink = (_b = abstractNum.styleLink) === null || _b === void 0 ? void 0 : _b.val;
+        this.readLevels(abstractNum);
+    }
+    readLevels(abstractNum) {
+        var _a;
+        for (const lvl of (_a = abstractNum.lvl) !== null && _a !== void 0 ? _a : [])
+            this.readLevel(lvl);
+    }
+    /** Adds (or replaces) the level read from this `w:lvl`. docx4j `readLevel`. */
+    readLevel(lvl) {
+        const level = new LevelDefinition(String(lvl.ilvl), lvl);
+        // the REFERENCING abstract list: a w:numStyleLink definition counts on its own (P2)
+        level.abstractNumId = this.id;
+        this.levels.set(level.ilvl, level);
+    }
+    /**
+     * The second pass for a definition carrying `w:numStyleLink`: read its levels from the
+     * abstract definition the numbering style's own `w:num` names.  They count under **this**
+     * definition's id, not the linked one's. docx4j `updateDefinitionFromLinkedStyle`.
+     */
+    updateFromLinkedStyle(linked) {
+        if (!this.hasLinkedStyle)
+            return;
+        this.readLevels(linked);
+    }
+    /** Whether this definition carries `w:numStyleLink`. */
+    get hasLinkedStyle() {
+        return this.linkedStyleId !== undefined && this.linkedStyleId !== '';
+    }
+    /** How many levels are defined; 0 for an unresolved `w:numStyleLink` definition. */
+    get levelCount() {
+        return this.levels.size;
+    }
+}
+/**
+ * One `w:num`: the abstract definition it names, with its `w:lvlOverride`s applied to copies of
+ * that definition's levels, and the counting. docx4j `ListNumberingDefinition`.
+ */
+export class ListDefinition {
+    constructor(num, abstracts, resolveLinkedStyle) {
+        var _a, _b;
+        this.num = num;
+        /** The levels, with this instance's overrides applied. */
+        this.levels = new Map();
+        this.numId = String(num.numId);
+        const abstractNumId = num.abstractNumId;
+        if (abstractNumId === undefined) {
+            log.warn(`No abstractNumId on w:numId=${this.numId}`);
+            return;
+        }
+        const abstract = abstracts.get(String(abstractNumId.val));
+        this.abstractDefinition = abstract;
+        if (abstract === undefined) {
+            log.warn(`No abstractListDefinition for w:numId=${this.numId}`);
+            return;
+        }
+        if (abstract.levelCount === 0 && abstract.hasLinkedStyle && !resolveLinkedStyle) {
+            // resolved on the second pass, once the numbering style is known
+            return;
+        }
+        for (const [ilvl, level] of abstract.levels) {
+            const instance = level.copy();
+            instance.ownerNumId = this.numId;
+            this.levels.set(ilvl, instance);
+        }
+        for (const override of (_a = num.lvlOverride) !== null && _a !== void 0 ? _a : []) {
+            if (override.ilvl === undefined) {
+                log.warn(`Missing @w:ilvl on a w:lvlOverride of w:numId=${this.numId}`);
+                continue;
+            }
+            const ilvl = String(override.ilvl);
+            const level = this.levels.get(ilvl);
+            // the w:startOverride first, as docx4j applies them: an override w:lvl stating its own
+            // w:start then replaces the value, but the level still counts as start-overridden
+            const start = (_b = override.startOverride) === null || _b === void 0 ? void 0 : _b.val;
+            if (start !== undefined) {
+                if (level === undefined) {
+                    log.warn(`level ${ilvl} missing for abstractNum ${abstract.id}, referenced from w:num ${this.numId}`);
+                }
+                else {
+                    level.setStartValue(start - 1);
+                }
+            }
+            if (override.lvl !== undefined && level !== undefined)
+                level.applyOverride(override.lvl);
+        }
+    }
+    /** The level with this `w:ilvl`, or undefined. */
+    level(ilvl) {
+        return this.levels.get(String(ilvl));
+    }
+    /** Whether the level exists: Word writes `w:num`s whose abstract definition or level is missing. */
+    levelExists(ilvl) {
+        return this.levels.has(String(ilvl));
+    }
+    /** Whether the level's `w:numFmt` is `bullet`. */
+    isBullet(ilvl) {
+        var _a, _b;
+        return (_b = (_a = this.level(ilvl)) === null || _a === void 0 ? void 0 : _a.isBullet) !== null && _b !== void 0 ? _b : false;
+    }
+    /** The `w:hAnsi` font the level's `w:rPr` names, or undefined. */
+    font(ilvl) {
+        var _a;
+        return (_a = this.level(ilvl)) === null || _a === void 0 ? void 0 : _a.font;
+    }
+    /**
+     * One more item at a level, and the deeper levels that restart after it reset.
+     * docx4j `incrementCounter(level, state)`.
+     */
+    incrementCounter(ilvl, state) {
+        const levelInt = Number(ilvl);
+        const thisLevel = this.level(levelInt);
+        if (thisLevel === undefined)
+            return; // guarded by levelExists
+        if (!thisLevel.counter(state).encounteredAlready) {
+            // make sure the shallower levels have been initialised
+            for (let shallower = levelInt - 1; shallower >= 0; shallower--) {
+                const level = this.level(shallower);
+                if (level === undefined || level.counter(state).encounteredAlready)
+                    break;
+                level.incrementCounter(state);
+            }
+        }
+        thisLevel.incrementCounter(state);
+        // the deeper levels go back to their start - each unless its w:lvlRestart says this level
+        // does not restart it (ECMA-376 17.9.11, CR-014 phase 2)
+        for (let deeper = levelInt + 1;; deeper++) {
+            const level = this.level(deeper);
+            if (level === undefined)
+                break;
+            if (level.restartsAfter(levelInt))
+                level.resetCounter(state);
+        }
+    }
+    /**
+     * The label of a level: its `w:lvlText` with the counters filled in ("1.2.", "(c)").
+     * docx4j `getCurrentNumberString(level, state)`.
+     *
+     * `w:isLgl` at **any** level shows the levels this number *inherits* in decimal whatever their
+     * own `w:numFmt`, the level carrying it keeping its own: Word's Article / Section numbering
+     * prints "Section 1.01" where the plain reading would print "Section I.01".
+     */
+    currentNumberString(ilvl, state) {
+        var _a;
+        const controlling = this.level(ilvl);
+        if (controlling === undefined)
+            return ''; // guarded by levelExists
+        const isLegal = controlling.isLgl;
+        const thisLevel = Number.isFinite(Number(ilvl)) ? Number(ilvl) : -1;
+        const format = (_a = controlling.lvlText) !== null && _a !== void 0 ? _a : '';
+        let out = '';
+        for (let i = 0; i < format.length; i++) {
+            const char = format.charAt(i);
+            if (char !== '%') {
+                out += char;
+                continue;
+            }
+            // a trailing '%' names no level and is dropped, as docx4j's loop drops it
+            if (i >= format.length - 1)
+                continue;
+            const digit = format.charAt(i + 1);
+            if (digit < '0' || digit > '9') {
+                // docx4j throws NumberFormatException here; a malformed w:lvlText is not worth an
+                // exception, so the two characters stand as they are written
+                out += char;
+                continue;
+            }
+            i++;
+            const levelId = Number(digit) - 1; // the format string is 1-based
+            const level = this.level(levelId);
+            if (level === undefined)
+                continue; // Word's referential-integrity bugs (docx4j NPEs here)
+            out += (isLegal && levelId < thisLevel)
+                ? level.currentValueUnformatted(state)
+                : level.currentValueFormatted(state, `numId ${this.numId}`);
+        }
+        return out;
+    }
+}
+/**
+ * The definitions of one `w:numbering`: every `w:abstractNum` and every `w:num`, with
+ * `w:numStyleLink` resolved. docx4j `NumberingDefinitionsPart.initialiseMaps` and the two maps
+ * it fills, plus `getInd` and `getLinkedStyleId`.
+ *
+ * Immutable once built; the numbering part rebuilds it when its tree changes.
+ */
+export class NumberingDefinitions {
+    /**
+     * @param numbering the `w:numbering` tree, or undefined for a package with no numbering part
+     * @param getStyle  a style by id, for `w:numStyleLink` and a level's linked `w:pStyle`
+     */
+    constructor(numbering, getStyle = () => undefined) {
+        var _a;
+        this.numbering = numbering;
+        this.getStyle = getStyle;
+        /** `w:abstractNumId` -> the definition. docx4j `getAbstractListDefinitions()`. */
+        this.abstractListDefinitions = new Map();
+        /** `w:numId` -> the definition. docx4j `getInstanceListDefinitions()`. */
+        this.instanceListDefinitions = new Map();
+        if (numbering === undefined)
+            return;
+        // pass 1: every w:abstractNum, then every w:num
+        let needSecondPass = false;
+        for (const abstractNum of (_a = numbering.abstractNum) !== null && _a !== void 0 ? _a : []) {
+            const definition = new AbstractListDefinition(abstractNum);
+            this.abstractListDefinitions.set(definition.id, definition);
+            if (abstractNum.numStyleLink !== undefined)
+                needSecondPass = true;
+        }
+        this.readInstances(numbering, false);
+        if (!needSecondPass)
+            return;
+        // pass 2: resolveLinkedAbstractNum, then the instances again (which overwrites them)
+        for (const definition of this.abstractListDefinitions.values())
+            this.resolveLinkedAbstractNum(definition);
+        this.readInstances(numbering, true);
+    }
+    readInstances(numbering, resolveLinkedStyle) {
+        var _a;
+        for (const num of (_a = numbering.num) !== null && _a !== void 0 ? _a : []) {
+            const definition = new ListDefinition(num, this.abstractListDefinitions, resolveLinkedStyle);
+            this.instanceListDefinitions.set(definition.numId, definition);
+        }
+    }
+    /**
+     * docx4j `resolveLinkedAbstractNum`: the numbering style `w:numStyleLink` names, the `w:num`
+     * its `w:numPr` points at, and *that* `w:num`'s abstract definition, whose levels this one
+     * takes while counting under its own id - "treated as a separate list by Word (ie its numbers
+     * are incremented independently), and this code honours that".
+     */
+    resolveLinkedAbstractNum(definition) {
+        var _a, _b;
+        if (!definition.hasLinkedStyle)
+            return;
+        const numStyleId = definition.linkedStyleId;
+        const style = this.getStyle(numStyleId);
+        if (style === undefined) {
+            log.warn(`For w:numStyleLink, couldn't find style ${numStyleId}`);
+            return;
+        }
+        const numPr = (_a = style.pPr) === null || _a === void 0 ? void 0 : _a.numPr;
+        if (numPr === undefined) {
+            log.warn(`For w:numStyleLink, style ${numStyleId} has no w:numPr`);
+            return;
+        }
+        if (((_b = numPr.numId) === null || _b === void 0 ? void 0 : _b.val) === undefined) {
+            log.warn(`For w:numStyleLink, style ${numStyleId} w:numPr has no w:numId`);
+            return;
+        }
+        const concrete = String(numPr.numId.val);
+        const target = this.instanceListDefinitions.get(concrete);
+        if (target === undefined) {
+            log.warn(`No ListDefinition entry with ID ${concrete}`);
+            return;
+        }
+        const linked = target.abstractDefinition;
+        if (linked === undefined || linked === definition)
+            return;
+        definition.updateFromLinkedStyle(linked.abstractNum);
+        // docx4j also copies the levels into the underlying w:abstractNum object here; this port
+        // does not, so that a numbering part nobody has edited still saves byte for byte
+    }
+    /** The definition of a `w:numId`, or undefined. */
+    list(numId) {
+        return numId === undefined ? undefined : this.instanceListDefinitions.get(String(numId));
+    }
+    /** The level of a `w:numId` / `w:ilvl`, or undefined. */
+    level(numId, ilvl) {
+        var _a;
+        return (_a = this.list(numId)) === null || _a === void 0 ? void 0 : _a.level(ilvl === undefined || ilvl === '' ? '0' : ilvl);
+    }
+    /**
+     * The paragraph style this level is linked to - the `w:pStyle` of ECMA-376 17.9.24, on the
+     * instance's `w:lvlOverride/w:lvl` where it has one and on the abstract level otherwise - or
+     * undefined. docx4j `NumberingDefinitionsPart.getLinkedStyleId`.
+     */
+    getLinkedStyleId(numId, ilvl) {
+        var _a;
+        return (_a = this.level(numId, ilvl)) === null || _a === void 0 ? void 0 : _a.pStyle;
+    }
+    /** docx4j `NumberingDefinitionsPart.getInd(NumPr)`: `w:ilvl` is optional and means level 0. */
+    getInd(numPr) {
+        var _a, _b;
+        if (((_a = numPr.numId) === null || _a === void 0 ? void 0 : _a.val) === undefined)
+            return undefined;
+        const ilvl = ((_b = numPr.ilvl) === null || _b === void 0 ? void 0 : _b.val) === undefined ? '0' : String(numPr.ilvl.val);
+        return this.indOf(String(numPr.numId.val), ilvl);
+    }
+    /**
+     * The indent this level contributes. docx4j `NumberingDefinitionsPart.getInd(String, String)`:
+     * the instance's override level first, then the abstract level, each read by
+     * {@link indFromLvl}.
+     */
+    indOf(numId, ilvl) {
+        const list = this.list(numId);
+        if (list === undefined)
+            return undefined;
+        const level = list.level(ilvl !== null && ilvl !== void 0 ? ilvl : '0');
+        if (level === undefined)
+            return undefined;
+        if (level.overrideLvl !== undefined) {
+            const ind = this.indFromLvl(level.overrideLvl);
+            if (ind !== undefined)
+                return ind;
+        }
+        return level.abstractLvl === undefined ? undefined : this.indFromLvl(level.abstractLvl);
+    }
+    /**
+     * **The level's own `w:pPr/w:ind` comes first** (ECMA-376 17.9.24: a `w:lvl/w:pPr` states the
+     * paragraph properties applied to a paragraph at this level).  A `w:lvl/w:pStyle` only *links*
+     * the level to a paragraph style; it does not make that style's indent the level's.  Where the
+     * level states no indent of its own the linked style's is still used, following `w:basedOn` as
+     * every other property a style contributes does (docx4j 17.1.0 and 17.1.1; CR-014 claim 7,
+     * measured, and probe P5).
+     *
+     * A style reference in the level's `w:pPr`, but not also as a sibling of `w:pPr`, contributes
+     * nothing here - and numbers nothing (CR-014 P4; `Emulator.resolve` decides "not numbered").
+     */
+    indFromLvl(lvl) {
+        var _a, _b, _c, _d;
+        if (((_a = lvl.pPr) === null || _a === void 0 ? void 0 : _a.ind) !== undefined)
+            return lvl.pPr.ind;
+        const linked = (_b = lvl.pStyle) === null || _b === void 0 ? void 0 : _b.val;
+        if (linked === undefined)
+            return undefined;
+        const seen = new Set();
+        let id = linked;
+        while (id !== undefined && !seen.has(id)) {
+            seen.add(id);
+            const style = this.getStyle(id);
+            if (style === undefined) {
+                log.warn(`Couldn't find style ${id}`);
+                return undefined;
+            }
+            if (((_c = style.pPr) === null || _c === void 0 ? void 0 : _c.ind) !== undefined)
+                return style.pPr.ind;
+            id = (_d = style.basedOn) === null || _d === void 0 ? void 0 : _d.val;
+        }
+        return undefined;
+    }
+}

package/dist/model/listnumbering/formats.d.mts

@@ -0,0 +1,25 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+/**
+ * Turns a list counter into the label text of one `w:numFmt`: 3 into "iii", "C", "3rd",
+ * "Three", "Third", "03", "③".  docx4j `LabelFormatter.format(int)`.
+ *
+ * Throws `RangeError` where the format has no label for the value; {@link formatValue}
+ * substitutes the decimal label.
+ */
+export type LabelFormatter = (value: number) => string;
+/** Adds or replaces the formatter for a `w:numFmt`; `undefined` removes it. docx4j `register`. */
+export declare function register(numFmt: wml.NumberFormat, formatter: LabelFormatter | undefined): void;
+/** The formatter registered for a `w:numFmt`, or undefined. docx4j `NumberFormatter.get`. */
+export declare function formatterFor(numFmt: wml.NumberFormat | undefined): LabelFormatter | undefined;
+/** Every `w:numFmt` this package can format (a test's, and a caller's, inventory). */
+export declare function registeredFormats(): wml.NumberFormat[];
+/** Forgets which formats have been warned about; a test that asserts on the warning needs it. */
+export declare function resetWarnings(): void;
+/**
+ * A counter as its label. docx4j `NumberFormatter.getCurrentValueFormatted(numFmt, current, where)`.
+ *
+ * A `w:numFmt` of undefined is decimal; so is a format with no formatter, and a value the
+ * formatter cannot express - with one warning per format naming `where` ("numId 3 ilvl 0") it
+ * first happened.
+ */
+export declare function formatValue(numFmt: wml.NumberFormat | undefined, value: number, where?: string): string;