@docx4j/core-ts 0.1.0 → 0.1.2

package/dist/model/content/List.mjs

@@ -0,0 +1,778 @@
+import { deepCopy, unmarshalNode } from '@docx4j/generated-objects-ts';
+import * as f from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
+import { parseXml } from '../../xml/dom.mjs';
+import { Docx4JException } from '../../opc/exceptions.mjs';
+import { DEFAULT_NUMBERING_XML } from '../../parts/wml/defaultNumbering.mjs';
+import { NumberingState, storyKindOf } from '../listnumbering/state.mjs';
+import { LEVELS } from '../listnumbering/definitions.mjs';
+import { isElement, linkParents } from './tree.mjs';
+import { Font } from './Font.mjs';
+function packageOf(body) {
+    const pkg = body.package_;
+    return typeof (pkg === null || pkg === void 0 ? void 0 : pkg.getMainDocumentPart) === 'function' ? pkg : undefined;
+}
+function mainOf(body) {
+    var _a;
+    try {
+        return (_a = packageOf(body)) === null || _a === void 0 ? void 0 : _a.getMainDocumentPart();
+    }
+    catch {
+        return undefined; // no main document part
+    }
+}
+/** The numbering part, or undefined where the document has none. */
+function numberingPartOf(body) {
+    var _a;
+    return (_a = mainOf(body)) === null || _a === void 0 ? void 0 : _a.numberingDefinitionsPart;
+}
+/** The definitions, or undefined where there is no numbering part or nothing has read it. */
+function definitionsOf(body) {
+    var _a;
+    try {
+        return (_a = numberingPartOf(body)) === null || _a === void 0 ? void 0 : _a.definitions;
+    }
+    catch {
+        return undefined; // the part has not been read (await pkg.getPropertyResolver())
+    }
+}
+/**
+ * The package's numbering emulator, or undefined where the document has no lists (or nothing
+ * has read the numbering part: `await pkg.getBody()` builds the resolver, which reads it).
+ */
+export function numberingEmulatorOf(body) {
+    var _a;
+    try {
+        return (_a = numberingPartOf(body)) === null || _a === void 0 ? void 0 : _a.getEmulator();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Where a paragraph's numbering resolves to (docx4j `Emulator.numRefFor`), or undefined. */
+function numRefOf(paragraph) {
+    var _a;
+    const ref = (_a = numberingEmulatorOf(paragraph.parentBody)) === null || _a === void 0 ? void 0 : _a.numRefFor(paragraph.p.pPr);
+    return ref === undefined || ref.notNumbered ? undefined : ref;
+}
+// --------------------------------------------------------------------------- the story walk
+/**
+ * Every paragraph under `root` in document order, each with the {@link NumberingState} it
+ * counts in. `test/parity.test.mjs`'s `walkNumbering`, which is the harness's own walk: a text
+ * box's paragraphs stay in this story's list (they are in the part, in document order) but
+ * count in a story of their own, which is docx4j's rule (CR-014 probe P7).
+ */
+function walkStory(root, state, emit) {
+    const walk = (value, current) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                walk(item, current);
+            return;
+        }
+        if (typeof value !== 'object' || value === null)
+            return;
+        if (isElement(value)) {
+            walk(value.value, current);
+            return;
+        }
+        const node = value;
+        let inner = current;
+        if (node.TYPE_NAME === 'org_docx4j_wml.P')
+            emit(node, current);
+        else if (node.TYPE_NAME === 'org_docx4j_wml.CTTxbxContent')
+            inner = new NumberingState();
+        for (const key of Object.keys(node)) {
+            if (key === 'PARENT' || key === 'TYPE_NAME')
+                continue;
+            walk(node[key], inner);
+        }
+    };
+    walk(root, state);
+}
+/**
+ * The parts whose paragraphs share one story with this one, in docx4j's order: every header
+ * then every footer for a header or a footer, and the part alone otherwise (CR-001 section
+ * 15.2, `NumberingStates.forPart`).
+ */
+function storyPartsOf(body, part) {
+    if (storyKindOf(part) !== 'headersFooters')
+        return [part];
+    const main = mainOf(body);
+    return main === undefined ? [part] : [...main.headerParts, ...main.footerParts];
+}
+/**
+ * Every numbered paragraph of this body's **story**, with the label and the counters, in one
+ * walk. A header or footer that has not been unmarshalled contributes nothing to the count,
+ * since it cannot be read synchronously: `await part.getBody()` on each first where a footer's
+ * numbers must continue the headers' (the story rule).
+ */
+export function listLabelsOf(body) {
+    const out = new Map();
+    const emulator = numberingEmulatorOf(body);
+    const part = body.part;
+    if (emulator === undefined || part === undefined)
+        return out;
+    const state = new NumberingState();
+    for (const story of storyPartsOf(body, part)) {
+        if (!story.isUnmarshalled)
+            continue;
+        walkStory(story.contents, state, (p, counters) => {
+            var _a, _b, _c, _d, _e;
+            const result = emulator.getNumber(p.pPr, counters);
+            if (result === undefined || result.numString === undefined)
+                return;
+            out.set(p, {
+                listString: result.numString,
+                level: Number((_a = result.ilvl) !== null && _a !== void 0 ? _a : '0'),
+                numId: (_b = result.numId) !== null && _b !== void 0 ? _b : '',
+                siblingIndex: ((_c = result.count) !== null && _c !== void 0 ? _c : 1) - ((_e = (_d = result.level) === null || _d === void 0 ? void 0 : _d.start) !== null && _e !== void 0 ? _e : 1),
+                isBullet: result.isBullet,
+            });
+        });
+    }
+    return out;
+}
+/** The label of one paragraph, from a walk of its story. */
+function labelOf(paragraph) {
+    return listLabelsOf(paragraph.parentBody).get(paragraph.p);
+}
+// ------------------------------------------------------------------------- the null objects
+/**
+ * Office JS's `*OrNullObject` result: `isNullObject` is true and every other member throws.
+ * `src/office-js/proxy.mts` has the same shape for collections; it is repeated here rather
+ * than imported so that the content API does not pull the shim's proxies into a bundle.
+ */
+function nullObject(className) {
+    const fail = (member) => {
+        throw new ItemNotFound(`Word.${className} is a null object (this paragraph is not a list item); check isNullObject before using ${member}`);
+    };
+    const proxy = new Proxy({ isNullObject: true }, {
+        get(target, prop) {
+            if (typeof prop === 'symbol')
+                return Reflect.get(target, prop);
+            if (prop === 'isNullObject')
+                return true;
+            if (prop === 'toJSON')
+                return () => ({ isNullObject: true });
+            if (prop === 'then')
+                return undefined;
+            return fail(prop);
+        },
+        set(_target, prop) {
+            return fail(String(prop));
+        },
+    });
+    return proxy;
+}
+/**
+ * Nothing matched, as Office JS's `ItemNotFound` says it: the same `code` as the shim's
+ * `ItemNotFoundError`, so add-in code branching on `error.code` behaves the same.
+ */
+class ItemNotFound extends Error {
+    constructor(message) {
+        super(message);
+        this.code = 'ItemNotFound';
+        this.name = 'ItemNotFoundError';
+    }
+}
+export { ItemNotFound as ListItemNotFoundError };
+// -------------------------------------------------------------------------------- the views
+/**
+ * A subset of Office JS `Word.List` over one `w:num` and the `w:abstractNum` it names. A light
+ * view: it holds the `w:numId` and the body it was found through, and resolves both elements
+ * through the numbering part's definitions on every call.
+ *
+ * Every `setLevel*` method writes on the **abstract** definition, copying it first where
+ * another `w:num` shares it ({@link separate}), so that the change stays local to this list;
+ * each then refreshes the package's resolver, which rebuilds the numbering definitions.
+ */
+export class List {
+    constructor(
+    /** `w:numId`, as a string (docx4j's key; {@link id} is Office JS's number). */
+    numId, 
+    /** The body this list was found through: where {@link paragraphs} looks. */
+    body) {
+        this.numId = numId;
+        this.body = body;
+    }
+    /** Office JS `list.id`: the `w:numId`. */
+    get id() {
+        return Number(this.numId);
+    }
+    /** The definitions this list is read from; throws where the numbering part has not been read. */
+    get definitions() {
+        const definitions = definitionsOf(this.body);
+        if (definitions === undefined) {
+            throw new Docx4JException('This document has no numbering definitions; await pkg.getBody() (or getPropertyResolver()) first');
+        }
+        return definitions;
+    }
+    /** The `w:num`'s definition (docx4j `ListNumberingDefinition`). */
+    get definition() {
+        const definition = this.definitions.list(this.numId);
+        if (definition === undefined)
+            throw new ItemNotFound(`No w:num for numId ${this.numId}`);
+        return definition;
+    }
+    /** The `w:num` (extension: the tree). */
+    get element() {
+        return this.definition.num;
+    }
+    /** The `w:abstractNum` this list resolves to (extension: the tree). */
+    get abstractElement() {
+        var _a;
+        return (_a = this.definition.abstractDefinition) === null || _a === void 0 ? void 0 : _a.abstractNum;
+    }
+    /** The level definition (the abstract level with this `w:num`'s override over it), or undefined. */
+    level(level) {
+        return this.definition.level(level);
+    }
+    /** Office JS `list.levelExistences`: whether each of the nine levels is defined. */
+    get levelExistences() {
+        return Array.from({ length: LEVELS }, (_, i) => this.definition.levelExists(i));
+    }
+    /** Whether the level is defined (extension; Office JS has {@link levelExistences}). */
+    levelExists(level) {
+        return this.definition.levelExists(level);
+    }
+    /**
+     * Office JS `list.levelTypes`: `Bullet`, `Number` or `Picture` for each of the nine levels,
+     * from the level's `w:numFmt` and its `w:lvlPicBulletId`. A level that is not defined reads
+     * `Number`, as Office JS reports for a level with no format of its own.
+     */
+    get levelTypes() {
+        return Array.from({ length: LEVELS }, (_, i) => {
+            const level = this.level(i);
+            if (level === undefined)
+                return 'Number';
+            if (level.lvlPicBulletId !== undefined)
+                return 'Picture';
+            return level.isBullet ? 'Bullet' : 'Number';
+        });
+    }
+    /** Office JS `list.getLevelString(level)`: the level's `w:lvlText` ('%1.', '(%2)', a bullet). */
+    getLevelString(level) {
+        var _a, _b;
+        return (_b = (_a = this.level(level)) === null || _a === void 0 ? void 0 : _a.lvlText) !== null && _b !== void 0 ? _b : '';
+    }
+    /**
+     * Office JS `list.getLevelFont(level)`: the `Font` the level's label is drawn with, over the
+     * level's `w:rPr`.
+     *
+     * **It is a writable view**, and Office JS pairs it with `resetLevelFont`, so it
+     * {@link separate}s first: the numbering part becomes live and a shared abstract definition
+     * is copied, exactly as the `setLevel*` methods do. A read that must not cost the part its
+     * byte-for-byte round trip is `list.level(n).labelRPr` (CR-002 section 17).
+     */
+    getLevelFont(level) {
+        this.separate();
+        const holder = this.writableLvl(level);
+        return new Font(() => [holder]);
+    }
+    /** Office JS `list.getLevelParagraphs(level)`: this body's paragraphs at that level of this list. */
+    getLevelParagraphs(level) {
+        return this.paragraphs.filter((p) => levelOf(p) === level);
+    }
+    /**
+     * Office JS `list.paragraphs`: every paragraph of this body whose effective `w:numPr` names
+     * this list, in document order (a style-contributed `w:numPr` counts).
+     */
+    get paragraphs() {
+        return this.body.paragraphs.filter((p) => { var _a; return ((_a = numRefOf(p)) === null || _a === void 0 ? void 0 : _a.numId) === this.numId; });
+    }
+    /**
+     * Office JS `list.insertParagraph(text, location)`: a new paragraph of this list before its
+     * first item or after its last, at that item's level.
+     */
+    insertParagraph(text, location) {
+        var _a;
+        const items = this.paragraphs;
+        if (items.length === 0) {
+            throw new ItemNotFound(`List ${this.id} has no paragraphs in this body to insert relative to`);
+        }
+        const anchor = location === 'Start' ? items[0] : items[items.length - 1];
+        const paragraph = anchor.insertParagraph(text, location === 'Start' ? 'Before' : 'After');
+        paragraph.attachToList(this.id, (_a = levelOf(anchor)) !== null && _a !== void 0 ? _a : 0);
+        return paragraph;
+    }
+    // --- the level writers ------------------------------------------------------------------
+    /**
+     * Office JS `list.setLevelNumbering(level, listNumbering, formatString)`: the level's
+     * `w:numFmt` and, from `formatString`, its `w:lvlText` - each number in the array is a
+     * 0-based level whose counter goes there (`[0, '.', 1]` is `'%1.%2'`), each string a literal.
+     * Without one the level numbers itself and takes a trailing full stop (`'%<n>.'`).
+     */
+    setLevelNumbering(level, listNumbering, formatString) {
+        const lvl = this.writableLvl(level);
+        lvl.numFmt = f.createNumFmt({ val: NUMBERING_FORMATS[listNumbering] });
+        linkParents(lvl.numFmt, lvl);
+        lvl.lvlText = f.createLvlLvlText({ val: lvlTextOf(level, formatString) });
+        linkParents(lvl.lvlText, lvl);
+        this.written();
+    }
+    /**
+     * Office JS `list.setLevelBullet(level, listBullet, charCode, fontName)`: the level's
+     * `w:numFmt` becomes `bullet` and its `w:lvlText` the bullet character, with the font in the
+     * level's `w:rPr/w:rFonts`. `Custom` takes `charCode` and `fontName`; the other six are the
+     * characters and faces Word's bullet library uses.
+     */
+    setLevelBullet(level, listBullet, charCode, fontName) {
+        var _a, _b;
+        const preset = BULLETS[listBullet];
+        const code = listBullet === 'Custom' ? charCode : preset === null || preset === void 0 ? void 0 : preset.charCode;
+        if (code === undefined)
+            throw new Docx4JException("setLevelBullet('Custom') needs a charCode");
+        const font = fontName !== null && fontName !== void 0 ? fontName : preset === null || preset === void 0 ? void 0 : preset.fontName;
+        const lvl = this.writableLvl(level);
+        lvl.numFmt = f.createNumFmt({ val: 'bullet' });
+        linkParents(lvl.numFmt, lvl);
+        lvl.lvlText = f.createLvlLvlText({ val: String.fromCharCode(code) });
+        linkParents(lvl.lvlText, lvl);
+        if (font !== undefined && font !== '') {
+            const rPr = ((_a = lvl.rPr) !== null && _a !== void 0 ? _a : (lvl.rPr = { TYPE_NAME: 'org_docx4j_wml.RPr' }));
+            const rFonts = ((_b = rPr.rFonts) !== null && _b !== void 0 ? _b : (rPr.rFonts = { TYPE_NAME: 'org_docx4j_wml.RFonts' }));
+            rFonts.ascii = font;
+            rFonts.hAnsi = font;
+            rFonts.hint = 'default';
+            linkParents(rPr, lvl);
+        }
+        this.written();
+    }
+    /**
+     * Office JS `list.setLevelIndents(level, textIndent, bulletNumberPictureIndent)`, both in
+     * points: the level's `w:ind/@w:left` is where the text sits and the label's position is the
+     * hanging indent from it (or `w:firstLine` where the label sits to the right of the text).
+     */
+    setLevelIndents(level, textIndent, bulletNumberPictureIndent) {
+        var _a, _b;
+        const lvl = this.writableLvl(level);
+        const pPr = ((_a = lvl.pPr) !== null && _a !== void 0 ? _a : (lvl.pPr = { TYPE_NAME: 'org_docx4j_wml.PPr' }));
+        const ind = ((_b = pPr.ind) !== null && _b !== void 0 ? _b : (pPr.ind = f.createPPrBaseInd({})));
+        const left = Math.round(textIndent * TWIPS_PER_POINT);
+        const label = Math.round(bulletNumberPictureIndent * TWIPS_PER_POINT);
+        ind.left = left;
+        if (label <= left) {
+            ind.hanging = left - label;
+            delete ind.firstLine;
+        }
+        else {
+            ind.firstLine = label - left;
+            delete ind.hanging;
+        }
+        linkParents(pPr, lvl);
+        this.written();
+    }
+    /** Office JS `list.setLevelAlignment(level, alignment)`: the level's `w:lvlJc`. */
+    setLevelAlignment(level, alignment) {
+        const lvl = this.writableLvl(level);
+        const val = LVL_JC[alignment];
+        if (val === undefined)
+            delete lvl.lvlJc;
+        else {
+            lvl.lvlJc = f.createJc({ val });
+            linkParents(lvl.lvlJc, lvl);
+        }
+        this.written();
+    }
+    /**
+     * Office JS `list.setLevelStartingNumber(level, startingNumber)`: the level's `w:start`. A
+     * `w:startOverride` this `w:num` carries for the level would still win the first use, so it
+     * is removed with it.
+     */
+    setLevelStartingNumber(level, startingNumber) {
+        var _a;
+        const lvl = this.writableLvl(level);
+        lvl.start = f.createLvlStart({ val: startingNumber });
+        linkParents(lvl.start, lvl);
+        for (const override of (_a = this.element.lvlOverride) !== null && _a !== void 0 ? _a : []) {
+            if (Number(override.ilvl) === level)
+                delete override.startOverride;
+        }
+        this.written();
+    }
+    /**
+     * A new `w:num` over this list's `w:abstractNum` with a `w:startOverride` on level 0, which
+     * is how Word restarts a list: the counters are shared by abstract definition, and the
+     * override is spent on the new `w:num`'s first use in a story (CR-001 section 15.2). Attach
+     * the paragraphs that are to start again to the list it returns.
+     *
+     * Extension name (Office JS has no restart verb); `Paragraph.restartList()` is the sugar.
+     */
+    restart() {
+        var _a, _b, _c;
+        const numbering = this.live();
+        const num = this.element;
+        const start = (_b = (_a = this.level(0)) === null || _a === void 0 ? void 0 : _a.start) !== null && _b !== void 0 ? _b : 1;
+        const created = f.createNumberingNum({
+            numId: nextNumId(numbering),
+            abstractNumId: f.createNumberingNumAbstractNumId({ val: num.abstractNumId.val }),
+            lvlOverride: [f.createNumberingNumLvlOverride({
+                    ilvl: 0,
+                    startOverride: f.createNumberingNumLvlOverrideStartOverride({ val: start }),
+                })],
+        });
+        ((_c = numbering.num) !== null && _c !== void 0 ? _c : (numbering.num = [])).push(created);
+        linkParents(created, numbering);
+        this.written();
+        return new List(String(created.numId), this.body);
+    }
+    /**
+     * Gives this list a `w:abstractNum` of its own where another `w:num` shares the one it names
+     * (CR-002 section 3.9), so that a change to its levels stays local to it. The numbering part
+     * becomes live either way; the `setLevel*` methods call it for you.
+     */
+    separate() {
+        var _a, _b, _c;
+        const numbering = this.live();
+        const num = this.element;
+        const abstractId = num.abstractNumId.val;
+        const shared = ((_a = numbering.num) !== null && _a !== void 0 ? _a : []).some((other) => { var _a; return other !== num && ((_a = other.abstractNumId) === null || _a === void 0 ? void 0 : _a.val) === abstractId; });
+        if (!shared)
+            return;
+        const source = ((_b = numbering.abstractNum) !== null && _b !== void 0 ? _b : []).find((a) => a.abstractNumId === abstractId);
+        if (source === undefined)
+            return;
+        const copy = deepCopy(source);
+        copy.abstractNumId = nextAbstractNumId(numbering);
+        copy.nsid = f.createCTLongHexNumber({ val: hexId() });
+        // w:styleLink maps a numbering style to one definition; the copy must not claim it too
+        delete copy.styleLink;
+        ((_c = numbering.abstractNum) !== null && _c !== void 0 ? _c : (numbering.abstractNum = [])).push(copy);
+        linkParents(copy, numbering);
+        num.abstractNumId = f.createNumberingNumAbstractNumId({ val: copy.abstractNumId });
+        linkParents(num.abstractNumId, num);
+        this.written();
+    }
+    // --- internals --------------------------------------------------------------------------
+    /** The numbering part's live tree; the first write promotes the tree the definitions hold. */
+    live() {
+        const part = numberingPartOf(this.body);
+        if (part === undefined)
+            throw new Docx4JException('This document has no numbering part');
+        return part.makeLive();
+    }
+    /**
+     * The `w:lvl` a write goes to: this list's own abstract definition's, created where the
+     * definition has no level for it. A `w:lvlOverride/w:lvl` this `w:num` carries for the level
+     * would mask the abstract one, so it goes (the `w:startOverride` beside it stays).
+     */
+    writableLvl(level) {
+        var _a, _b;
+        this.separate();
+        const abstract = this.abstractElement;
+        if (abstract === undefined) {
+            throw new ItemNotFound(`w:num ${this.numId} names no w:abstractNum that this document defines`);
+        }
+        for (const override of (_a = this.element.lvlOverride) !== null && _a !== void 0 ? _a : []) {
+            if (Number(override.ilvl) === level)
+                delete override.lvl;
+        }
+        const levels = ((_b = abstract.lvl) !== null && _b !== void 0 ? _b : (abstract.lvl = []));
+        let lvl = levels.find((l) => Number(l.ilvl) === level);
+        if (lvl === undefined) {
+            lvl = f.createLvl({ ilvl: level });
+            levels.push(lvl);
+            levels.sort((a, b) => Number(a.ilvl) - Number(b.ilvl));
+            linkParents(lvl, abstract);
+        }
+        return lvl;
+    }
+    /** The numbering tree changed: the resolver (and with it the definitions) is rebuilt. */
+    written() {
+        var _a;
+        (_a = packageOf(this.body)) === null || _a === void 0 ? void 0 : _a.refreshPropertyResolver();
+    }
+}
+/**
+ * A subset of Office JS `Word.ListItem` over one paragraph's place in its list. A view: the
+ * paragraph is the state.
+ */
+export class ListItem {
+    constructor(
+    /** The paragraph this is the list item of (Office JS: `paragraph.listItem`). */
+    paragraph) {
+        this.paragraph = paragraph;
+    }
+    /** Where this paragraph's numbering resolves to; throws when it is not a list item any more. */
+    get ref() {
+        const ref = numRefOf(this.paragraph);
+        if (ref === undefined)
+            throw new ItemNotFound('This paragraph is not a list item');
+        return ref;
+    }
+    /** The list this item is in. */
+    get list() {
+        return new List(this.ref.numId, this.paragraph.parentBody);
+    }
+    /**
+     * Office JS `listItem.level`: the `w:ilvl` the paragraph counts at, a style-contributed level
+     * included. Setting it writes the paragraph's own `w:numPr/w:ilvl` (with the `w:numId` beside
+     * it where the list came from the style), through the accessor that records `w:pPrChange`
+     * while the package tracks changes.
+     */
+    get level() {
+        var _a;
+        return Number((_a = this.ref.ilvl) !== null && _a !== void 0 ? _a : '0');
+    }
+    set level(value) {
+        var _a;
+        const ref = this.ref;
+        const numPr = this.paragraph.numPr();
+        if (((_a = numPr.numId) === null || _a === void 0 ? void 0 : _a.val) === undefined && ref.numId !== undefined) {
+            numPr.numId = f.createPPrBaseNumPrNumId({ val: Number(ref.numId) });
+            linkParents(numPr.numId, numPr);
+        }
+        numPr.ilvl = f.createPPrBaseNumPrIlvl({ val: value });
+        linkParents(numPr.ilvl, numPr);
+    }
+    /**
+     * Office JS `listItem.listString`: the label Word paints in front of the paragraph.
+     *
+     * It is counted by walking the paragraph's **story** from its start in document order
+     * (CR-001 section 15.2), so it costs one walk of the story per read; `Body.listLabels()`
+     * answers for every paragraph of the story in one walk.
+     */
+    get listString() {
+        var _a, _b;
+        return (_b = (_a = labelOf(this.paragraph)) === null || _a === void 0 ? void 0 : _a.listString) !== null && _b !== void 0 ? _b : '';
+    }
+    /**
+     * Office JS `listItem.siblingIndex`: the 0-based index of this item among the items of the
+     * same list and level, counted from where the level last restarted. The same walk as
+     * {@link listString}.
+     */
+    get siblingIndex() {
+        var _a, _b;
+        return (_b = (_a = labelOf(this.paragraph)) === null || _a === void 0 ? void 0 : _a.siblingIndex) !== null && _b !== void 0 ? _b : 0;
+    }
+    /**
+     * Office JS `listItem.getAncestor(parentOnly)`: the nearest preceding paragraph of this list
+     * at a shallower level - the parent when `parentOnly` is true, which throws when the nearest
+     * one is not exactly one level up. Throws `ItemNotFound` when there is no ancestor.
+     */
+    getAncestor(parentOnly = false) {
+        const level = this.level;
+        const items = this.list.paragraphs;
+        const at = items.findIndex((p) => p.p === this.paragraph.p);
+        for (let i = at - 1; i >= 0; i--) {
+            const other = levelOf(items[i]);
+            if (other === undefined || other >= level)
+                continue;
+            if (parentOnly && other !== level - 1)
+                break;
+            return items[i];
+        }
+        throw new ItemNotFound(`This list item (level ${level}) has no ${parentOnly ? 'parent' : 'ancestor'} in list ${this.list.id}`);
+    }
+    /**
+     * Office JS `listItem.getDescendants(directChildrenOnly)`: the paragraphs of this list which
+     * follow this one at a deeper level, up to the next one at this level or shallower; only the
+     * ones one level down when `directChildrenOnly` is true.
+     */
+    getDescendants(directChildrenOnly = false) {
+        const level = this.level;
+        const items = this.list.paragraphs;
+        const at = items.findIndex((p) => p.p === this.paragraph.p);
+        const out = [];
+        for (let i = at + 1; i < items.length; i++) {
+            const other = levelOf(items[i]);
+            if (other === undefined || other <= level)
+                break;
+            if (!directChildrenOnly || other === level + 1)
+                out.push(items[i]);
+        }
+        return out;
+    }
+}
+// ------------------------------------------------------------- what Paragraph and Body call
+/** The effective `w:ilvl` of a paragraph, or undefined when it is not a list item. */
+export function levelOf(paragraph) {
+    var _a;
+    const ref = numRefOf(paragraph);
+    return ref === undefined ? undefined : Number((_a = ref.ilvl) !== null && _a !== void 0 ? _a : '0');
+}
+/** Office JS `paragraph.isListItem`: docx4j's `Emulator.numRefFor` answers it. */
+export function isListItem(paragraph) {
+    return numRefOf(paragraph) !== undefined;
+}
+/** Office JS `paragraph.listItem`; throws `ItemNotFound` when the paragraph is not one. */
+export function listItemOf(paragraph) {
+    if (!isListItem(paragraph)) {
+        throw new ItemNotFound('This paragraph is not a list item (listItemOrNullObject does not throw)');
+    }
+    return new ListItem(paragraph);
+}
+/** Office JS `paragraph.listItemOrNullObject`. */
+export function listItemOrNullObjectOf(paragraph) {
+    return isListItem(paragraph) ? new ListItem(paragraph) : nullObject('ListItem');
+}
+/** Office JS `paragraph.list`; throws `ItemNotFound` when the paragraph is not a list item. */
+export function listOf(paragraph) {
+    const ref = numRefOf(paragraph);
+    if (ref === undefined) {
+        throw new ItemNotFound('This paragraph is not a list item (listOrNullObject does not throw)');
+    }
+    return new List(ref.numId, paragraph.parentBody);
+}
+/** Office JS `paragraph.listOrNullObject`. */
+export function listOrNullObjectOf(paragraph) {
+    const ref = numRefOf(paragraph);
+    return ref === undefined ? nullObject('List') : new List(ref.numId, paragraph.parentBody);
+}
+/** Office JS `body.lists`: every `w:num` a paragraph of this body names, in order of first use. */
+export function listsOf(body) {
+    const emulator = numberingEmulatorOf(body);
+    if (emulator === undefined)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const paragraph of body.paragraphs) {
+        const ref = emulator.numRefFor(paragraph.p.pPr);
+        if (ref.notNumbered || ref.numId === undefined || seen.has(ref.numId))
+            continue;
+        seen.add(ref.numId);
+        out.push(new List(ref.numId, body));
+    }
+    return out;
+}
+/** Office JS `paragraph.attachToList(listId, level)`: the paragraph's own `w:numPr`. */
+export function attachToList(paragraph, listId, level = 0) {
+    const numPr = paragraph.numPr();
+    numPr.numId = f.createPPrBaseNumPrNumId({ val: Number(listId) });
+    numPr.ilvl = f.createPPrBaseNumPrIlvl({ val: level });
+    linkParents(numPr, paragraph.p.pPr);
+    return new List(String(listId), paragraph.parentBody);
+}
+/**
+ * Office JS `paragraph.detachFromList()`: the paragraph's own `w:numPr` goes. Where its style
+ * still numbers it, a `w:numPr` with `w:numId` 0 takes its place, which is how Word switches an
+ * inherited list off (ECMA-376 17.9.18, and what `Emulator.resolve` reads).
+ */
+export function detachFromList(paragraph) {
+    var _a;
+    if (((_a = paragraph.p.pPr) === null || _a === void 0 ? void 0 : _a.numPr) !== undefined) {
+        delete paragraph.pPr().numPr;
+    }
+    if (!isListItem(paragraph))
+        return;
+    const numPr = paragraph.numPr();
+    numPr.numId = f.createPPrBaseNumPrNumId({ val: 0 });
+    linkParents(numPr.numId, numPr);
+    delete numPr.ilvl;
+}
+/**
+ * Office JS `paragraph.startNewList()`: a `w:abstractNum` copied from docx4j's default
+ * definitions (its `numbering.xml` resource: `w:abstractNum` 1 is Word's decimal set and 0 its
+ * bullet set), a `w:num` for it, and the paragraph attached to that list.
+ *
+ * Asynchronous where Office JS's is synchronous: the default definitions are XML which has to
+ * be unmarshalled, and a document with no numbering part gets one here (CR-002 section 17).
+ */
+export async function startNewList(paragraph, options) {
+    var _a, _b, _c, _d, _e;
+    const body = paragraph.parentBody;
+    const part = await ensureNumberingPart(body);
+    const numbering = await part.getContents();
+    const defaults = await defaultNumbering();
+    const template = ((_a = defaults.abstractNum) !== null && _a !== void 0 ? _a : [])[(options === null || options === void 0 ? void 0 : options.bullet) === true ? 0 : 1];
+    if (template === undefined)
+        throw new Docx4JException('The default numbering definitions are missing an abstractNum');
+    const abstract = deepCopy(template);
+    abstract.abstractNumId = nextAbstractNumId(numbering);
+    abstract.nsid = f.createCTLongHexNumber({ val: hexId() });
+    delete abstract.styleLink;
+    delete abstract.numStyleLink;
+    ((_b = numbering.abstractNum) !== null && _b !== void 0 ? _b : (numbering.abstractNum = [])).push(abstract);
+    linkParents(abstract, numbering);
+    const num = f.createNumberingNum({
+        numId: nextNumId(numbering),
+        abstractNumId: f.createNumberingNumAbstractNumId({ val: abstract.abstractNumId }),
+    });
+    ((_c = numbering.num) !== null && _c !== void 0 ? _c : (numbering.num = [])).push(num);
+    linkParents(num, numbering);
+    (_d = packageOf(body)) === null || _d === void 0 ? void 0 : _d.refreshPropertyResolver();
+    return attachToList(paragraph, num.numId, (_e = options === null || options === void 0 ? void 0 : options.level) !== null && _e !== void 0 ? _e : 0);
+}
+/**
+ * The numbering part, created with docx4j's default numbering where the document has none
+ * (docx4j's own `createNumbering` idiom), and unmarshalled either way so that what is written
+ * to it is saved.
+ */
+async function ensureNumberingPart(body) {
+    const pkg = packageOf(body);
+    const main = mainOf(body);
+    if (pkg === undefined || main === undefined) {
+        throw new Docx4JException('This body has no package, so a list cannot be added to it');
+    }
+    const existing = main.numberingDefinitionsPart;
+    if (existing !== undefined) {
+        // the resolver read the part privately; unmarshalling it gives a second tree, so the
+        // definitions (and the `getInd` the resolver folds into every layer) are rebuilt over the
+        // live one
+        const before = existing.isUnmarshalled;
+        await existing.getContents();
+        if (!before)
+            pkg.refreshPropertyResolver();
+        return existing;
+    }
+    // Imported here so that the content API does not import the parts statically: parts/wml
+    // builds the Body views, so a static import would be a runtime cycle (as `ooxml.mts` does).
+    const { NumberingDefinitionsPart } = await import('../../parts/wml/index.mjs');
+    const created = new NumberingDefinitionsPart();
+    main.addTargetPart(created);
+    await created.unmarshalDefaultNumbering();
+    // the resolver was built before the part existed, and refreshPropertyResolver() cannot find
+    // a part added since (CR-001 section 15.2 departure 6)
+    await pkg.refresh();
+    return created;
+}
+// ----------------------------------------------------------------------------- the mechanics
+const TWIPS_PER_POINT = 20;
+/** Office JS `Word.ListNumbering` as `w:numFmt`. */
+const NUMBERING_FORMATS = {
+    None: 'none',
+    Arabic: 'decimal',
+    UpperRoman: 'upperRoman',
+    LowerRoman: 'lowerRoman',
+    UpperLetter: 'upperLetter',
+    LowerLetter: 'lowerLetter',
+};
+/** Office JS `Word.ListBullet` as the character and face Word's bullet library uses. */
+const BULLETS = {
+    Custom: undefined,
+    Solid: { charCode: 0xf0b7, fontName: 'Symbol' }, // a filled round bullet
+    Hollow: { charCode: 0x006f, fontName: 'Courier New' }, // a lower-case o
+    Square: { charCode: 0xf0a7, fontName: 'Wingdings' }, // a filled square
+    Diamonds: { charCode: 0xf076, fontName: 'Wingdings' }, // a four-diamond bullet
+    Arrow: { charCode: 0xf0d8, fontName: 'Wingdings' }, // a solid right-pointing arrowhead
+    Checkmark: { charCode: 0xf0fc, fontName: 'Wingdings' }, // a tick
+};
+/** `w:lvlJc`, which takes the same values as a paragraph's `w:jc`. */
+const LVL_JC = {
+    Left: 'left', Centered: 'center', Right: 'right', Justified: 'both', Unknown: undefined,
+};
+/** Office JS's `formatString` as a `w:lvlText`: a number is a 0-based level, a string a literal. */
+function lvlTextOf(level, formatString) {
+    if (formatString === undefined || formatString.length === 0)
+        return `%${level + 1}.`;
+    return formatString.map((part) => (typeof part === 'number' ? `%${part + 1}` : part)).join('');
+}
+/** A free `w:numId`: one past the highest the document uses (Word numbers from 1). */
+function nextNumId(numbering) {
+    var _a;
+    return ((_a = numbering.num) !== null && _a !== void 0 ? _a : []).reduce((max, num) => Math.max(max, Number(num.numId)), 0) + 1;
+}
+/** A free `w:abstractNumId`. */
+function nextAbstractNumId(numbering) {
+    var _a;
+    return ((_a = numbering.abstractNum) !== null && _a !== void 0 ? _a : []).reduce((max, a) => Math.max(max, Number(a.abstractNumId)), -1) + 1;
+}
+/** An eight-digit `w:nsid`, which is how Word tells two list families apart. */
+function hexId() {
+    return Math.floor(Math.random() * 0x7fffffff).toString(16).toUpperCase().padStart(8, '0');
+}
+/** docx4j's default numbering definitions, unmarshalled once. */
+let defaults;
+function defaultNumbering() {
+    defaults !== null && defaults !== void 0 ? defaults : (defaults = (async () => (await unmarshalNode(parseXml(DEFAULT_NUMBERING_XML))).value)());
+    return defaults;
+}