@docx4j/core-ts 0.1.4 → 0.2.0

package/README.md

@@ -103,6 +103,20 @@ p?.insertParagraph('Inserted after the fourth block', 'After');
 (await pkg.paragraphAt({ contains: 'Chapter 2' }))?.delete();
 ```
 
+`search` and `replaceText` take Office JS's `matchCase`, `matchWholeWord` and `matchWildcards`
+(Word's `?`, `*`, `[a-z]`, `<`, `>`, `@` and `(...)` groups, with `\1` in the replacement), and
+`matchRegExp` for an ECMAScript regular expression, with `$1` in the replacement. A match never
+crosses a paragraph.
+
+```ts
+body.replaceText('(\\d+) pages', '$1 pp.', { matchRegExp: true });
+body.replaceText('(quick) (fox)', '\\2 \\1', { matchWildcards: true });
+```
+
+A style the document lacks is spliced in from docx4j's defaults, with the styles it is based on and
+linked to: `await pkg.styles.ensure(['FootnoteText', 'FootnoteReference'])` returns the ids it
+added, and a document that already has them keeps its styles part byte for byte.
+
 Docx4j's names are there as aliases (`addParagraphOfText`, `addStyledParagraphOfText`,
 `addObject`, `getContent`), and the tree stays reachable: `paragraph.p` is the `P`,
 `body.content` the live array.
@@ -173,6 +187,12 @@ list.setLevelStartingNumber(0, 5);
 const again = p4.restartList();                 // the same list, numbering again from its start
 ```
 
+Without a paragraph, `pkg.numbering.newList()` makes a definition and returns its `w:numId`, and
+`pkg.numbering.restart(numId)` one that numbers again from the start. Both take the identifiers to
+use when the next free one is the wrong answer - two sessions allocating in one co-edited
+document - checked unused, a clash throwing rather than renumbering:
+`await pkg.numbering.newList({ numId: 4242, abstractNumId: 77 })`.
+
 A level writer changes the `w:abstractNum`, so it copies that definition first when another
 `w:num` shares it — the change stays local to this list. `startNewList()` is asynchronous here
 (Office JS's is not): it copies its definition from docx4j's default `numbering.xml` and adds
@@ -208,6 +228,21 @@ body.acceptAll();     // or rejectAll(), or accept()/reject() one at a time
 `getTrackedChanges()` is also on `Paragraph` and `Range`. Text and searches read the accepted
 view throughout, so an agent sees the document as it will read once the changes are taken.
 
+To record one caller's edits without touching the document's own setting - an agent working in a
+document whose `w:trackRevisions` belongs to its owner - use `withTracking`. Nothing is written
+to the settings part, and the author, date and mode are put back when `fn` returns or throws:
+
+```ts
+await pkg.withTracking({ author: { name: 'Agent' } }, () => {
+  body.replaceText('colour', 'color');
+});
+```
+
+Calls nest. While two overlap, the later one's author and mode apply to every edit, since nothing
+can tell which asynchronous call an edit came from: await one before starting another when they
+must be recorded as different authors. A revision is dated to the minute, as Word dates them, and
+its id is above every annotation id in the document, including those in parts nobody has read.
+
 ### Comments
 
 `getComments()` on the body, a paragraph or a range, and `insertComment` on a range or a
@@ -230,6 +265,15 @@ for (const c of await body.getComments()) {    // document order, replies nested
 }
 ```
 
+`insertComment` and `reply` take the author, initials, date and `w:id` when they are not the
+package's - a comment made by another person in a co-edited document - and paragraphs as well as
+a string. A chosen id is checked unused, and a clash throws:
+
+```ts
+await hit.insertComment('Checked', { author: { name: 'Grace Hopper' }, date: new Date('2026-09-27T10:15:00Z'), id: 42 });
+await hit.insertComment([p1, p2]);             // w:p elements, for rich content
+```
+
 ### XML in
 
 A whole `word/document.xml` becomes the main document part's contents with `setXml`, and a
@@ -253,6 +297,33 @@ import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
 body.addObject(el.p({ content: [el.r({ content: [el.t({ value: 'Hello World' })] })] }));
 ```
 
+A part that cannot be unmarshalled throws `PartUnmarshalException`, whose message names the part
+and, where the parser supplies a position (xmldom in Node; not a browser), the element or attribute
+and its line: `/word/styles.xml: w:sz/@w:val (line 7): Argument [NaN] must be an integer, but it is not a number.`
+`partName`, `location`, `line` and `column` are fields of their own.
+
+### XPath over the document
+
+`pkg.selectObjects(xpath)` evaluates an XPath over a part - the main document part unless you pass
+another - and answers as docx4j's `getJAXBNodesViaXPath` does: for each hit, the node, the tree
+object behind it and its path. `body.select(xpath)` gives the content-API view instead, where the
+element has one (`Paragraph`, `Table`, `TableRow`, `TableCell`, `ContentControl`, a `Range` for a
+run):
+
+```ts
+const hits = await pkg.selectObjects("//w:p[w:pPr/w:pStyle/@w:val='Heading1']");
+hits[0].object;         // the P itself, not a copy: change it and the document changes
+hits[0].path;           // '/w:document/w:body[1]/w:p[3]'
+
+for (const heading of await body.select("//w:p[w:pPr/w:pStyle/@w:val='Heading1']")) {
+  if (heading instanceof Paragraph) heading.styleBuiltIn = 'Heading2';
+}
+```
+
+The prefixes are the objects package's (`w`, `r`, `wp`, `a`, ...), and `namespaces` adds others.
+Each call evaluates a fresh snapshot of the part, so what it selects is never stale and changing the
+snapshot's DOM changes nothing. The answers are held to docx4j's own by the XPath goldens (CR-006).
+
 ### Tables, pictures and content controls
 
 `Table`, `TableRow` and `TableCell` are Office JS shapes too; a cell is a `Body` of its own, so
@@ -350,6 +421,7 @@ document part (Word drops a custom XML part the main part does not relate to):
 
 ```ts
 const part = pkg.customXmlParts.add('<greeting xmlns="http://example.com/g"><to>World</to></greeting>');
+// or with the itemID and part name to use, checked unused: { itemID: '{4B0E8F1A-...}', partName: '/customXml/item7.xml' }
 control.xmlMapping.setMapping('/ns0:greeting[1]/ns0:to[1]', "xmlns:ns0='http://example.com/g'", part);
 control.xmlMapping.setMappingByNode(part.selectSingleNode('/ns0:greeting/ns0:to', "xmlns:ns0='http://example.com/g'"));
 ```
@@ -475,6 +547,10 @@ await Word.run(pkg, async (context) => {
 await writeFile('edited.docx', await pkg.save());
 ```
 
+The callback's `context.document` is typed `ShimmedDocument`, so add-in code that uses
+`paragraphs.items`, `load('items/text')`, `getFirst()` or `getCount().value` type-checks here as it
+does against Office JS.
+
 `Word.supported` is the set of `Class.member` strings this package implements
 (`Word.supported.has('Body.insertParagraph')`), generated from the compile-time subset, so a
 tool can check a script before running it. The selection an add-in edits is passed in:

package/dist/model/content/Body.d.mts

@@ -5,10 +5,16 @@ import type { OpcPackage } from '../../packages/OpcPackage.mjs';
 import { type Element, type TextViewOptions } from './tree.mjs';
 import { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
-import { Table } from './Table.mjs';
+import { Table, type TableRow, type TableCell } from './Table.mjs';
 import { ContentControl, type ContentControlType } from './ContentControl.mjs';
 import { InlinePicture, type InlinePictureOptions } from './InlinePicture.mjs';
-import type { SearchOptions } from './search.mjs';
+import { type SearchOptions } from './search.mjs';
+import type { Bound } from './binder.mjs';
+/**
+ * What `Body.select` returns for one hit: the content-API view of the selected element where there
+ * is one, and the `Bound` itself otherwise (CR-006 section 2).
+ */
+export type SelectResult = Paragraph | Table | TableRow | TableCell | ContentControl | Range | Bound;
 import type { Comment } from './Comment.mjs';
 import { type ChangeTracker } from './tracking.mjs';
 import { type TrackedChange } from './TrackedChange.mjs';
@@ -75,6 +81,34 @@ export declare class Body {
     get content(): Element[];
     /** Every paragraph in document order, descending into tables and content controls. */
     get paragraphs(): Paragraph[];
+    /**
+     * The content-API views an XPath selects (CR-006): a `ContentControl`, `Table`, `TableRow`,
+     * `TableCell` or `Paragraph` where the selected element has one, at any depth - an inline content
+     * control is a `ContentControl`, a nested table a `Table`; a `Range` over the whole paragraph for a
+     * `w:r` or anything in one (`w:t`, `w:tab`), wherever the run sits (a hyperlink, an insertion, an
+     * inline control); and the `Bound` itself for anything else - an attribute, a text node, a `w:pPr`,
+     * a `w:hyperlink`, a wildcard child. An attribute or a text node is always the `Bound`, never its
+     * element's view, so that what matched is not lost. A caller that wants the tree objects rather
+     * than views uses `pkg.selectObjects`.
+     *
+     * The expression is evaluated over a snapshot of the part this body belongs to, so it sees the
+     * whole part - `//w:p` from a header's body selects that header's paragraphs. Every call marshals
+     * the part afresh (CR-006 section 2).
+     */
+    select(xpath: string, options?: {
+        namespaces?: Record<string, string>;
+    }): Promise<SelectResult[]>;
+    /**
+     * Every view this body can make, keyed by the tree object behind it, so that a selected object
+     * becomes the view a caller can act on. Built per select: the views are cheap wrappers and nothing
+     * is cached but the `Body` itself (CR-002's "views, not a model"). The first view put for an object
+     * is the one it keeps, so the most specific kinds go first: a content control before the
+     * paragraph that holds an inline one, a table at any depth before the paragraphs in its cells, and
+     * a paragraph before the runs in it. A `w:r` and what is in it map to a `Range` over the paragraph,
+     * which is the nearest thing the content API has - a run is not addressable on its own in Office
+     * JS. A run in a text box is not one of the paragraph's, and stays a `Bound`.
+     */
+    private viewsByObject;
     /** The tables directly in this body, as Office JS reports them (nested tables are a cell's). */
     get tables(): Table[];
     /** Every content control in this body, in document order, nested ones included. */

package/dist/model/content/Body.mjs

@@ -1,7 +1,7 @@
 import { Docx4JException, PropertyResolverNotCreatedException } from '../../opc/exceptions.mjs';
 import { typeNameOf, childrenOf, linkParents, BLOCK_LEVEL_TYPES, textOf, textOfView, rowsOf, cellsOf } from './tree.mjs';
 import { r as textRun, br as breakItem, tbl as tableOf } from '@docx4j/generated-objects-ts/builders/wml';
-import { runOf, paragraphOf } from './tree.mjs';
+import { runOf, paragraphOf, runsOf } from './tree.mjs';
 import { Paragraph } from './Paragraph.mjs';
 import { Table } from './Table.mjs';
 import { ContentControl, collectControls } from './ContentControl.mjs';
@@ -9,6 +9,7 @@ import { sdt as sdtOf, nextSdtId } from '@docx4j/generated-objects-ts/builders/w
 import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
 import { InlinePicture, addImage, writableWidthEmu } from './InlinePicture.mjs';
 import { contentOf } from './ooxml.mjs';
+import { expandReplacement } from './search.mjs';
 import { commentApi } from './comments.mjs';
 import { trackerOf, trackInsertedParagraph, trackInsertedTable } from './tracking.mjs';
 import { trackedChangesOfRow } from './TrackedChange.mjs';
@@ -80,6 +81,78 @@ export class Body {
         visit(this.content);
         return out;
     }
+    /**
+     * The content-API views an XPath selects (CR-006): a `ContentControl`, `Table`, `TableRow`,
+     * `TableCell` or `Paragraph` where the selected element has one, at any depth - an inline content
+     * control is a `ContentControl`, a nested table a `Table`; a `Range` over the whole paragraph for a
+     * `w:r` or anything in one (`w:t`, `w:tab`), wherever the run sits (a hyperlink, an insertion, an
+     * inline control); and the `Bound` itself for anything else - an attribute, a text node, a `w:pPr`,
+     * a `w:hyperlink`, a wildcard child. An attribute or a text node is always the `Bound`, never its
+     * element's view, so that what matched is not lost. A caller that wants the tree objects rather
+     * than views uses `pkg.selectObjects`.
+     *
+     * The expression is evaluated over a snapshot of the part this body belongs to, so it sees the
+     * whole part - `//w:p` from a header's body selects that header's paragraphs. Every call marshals
+     * the part afresh (CR-006 section 2).
+     */
+    async select(xpath, options = {}) {
+        const pkg = this.package_;
+        if ((pkg === null || pkg === void 0 ? void 0 : pkg.selectObjects) === undefined)
+            throw new Docx4JException('select needs the package that owns this body');
+        const bounds = await pkg.selectObjects(xpath, { part: this.part, namespaces: options.namespaces });
+        const views = this.viewsByObject();
+        return bounds.map((bound) => { var _a; return (_a = (bound.node.nodeType === 1 ? views.get(bound.object) : undefined)) !== null && _a !== void 0 ? _a : bound; });
+    }
+    /**
+     * Every view this body can make, keyed by the tree object behind it, so that a selected object
+     * becomes the view a caller can act on. Built per select: the views are cheap wrappers and nothing
+     * is cached but the `Body` itself (CR-002's "views, not a model"). The first view put for an object
+     * is the one it keeps, so the most specific kinds go first: a content control before the
+     * paragraph that holds an inline one, a table at any depth before the paragraphs in its cells, and
+     * a paragraph before the runs in it. A `w:r` and what is in it map to a `Range` over the paragraph,
+     * which is the nearest thing the content API has - a run is not addressable on its own in Office
+     * JS. A run in a text box is not one of the paragraph's, and stays a `Bound`.
+     */
+    viewsByObject() {
+        var _a;
+        const out = new Map();
+        const put = (value, view) => {
+            if (typeof value === 'object' && value !== null && !out.has(value))
+                out.set(value, view);
+        };
+        const controls = this.contentControls;
+        for (const control of controls)
+            put(control.element.value, control);
+        const putTables = (tables) => {
+            for (const table of tables) {
+                put(table.element.value, table);
+                for (const row of table.rows) {
+                    put(row.element.value, row);
+                    for (const cell of row.cells) {
+                        put(cell.element.value, cell);
+                        putTables(cell.tables);
+                    }
+                }
+            }
+        };
+        putTables(this.tables);
+        for (const control of controls)
+            if (control.form === 'Block')
+                putTables(control.tables);
+        for (const paragraph of this.paragraphs) {
+            put(paragraph.element.value, paragraph);
+            const range = paragraph.getRange();
+            // both views, so that a run in a w:del is found as well as one in a w:ins
+            for (const view of ['accepted', 'original']) {
+                for (const run of runsOf(paragraph.element.value, { view })) {
+                    put(run.value, range);
+                    for (const item of (_a = run.value.content) !== null && _a !== void 0 ? _a : [])
+                        put(item.value, range);
+                }
+            }
+        }
+        return out;
+    }
     /** The tables directly in this body, as Office JS reports them (nested tables are a cell's). */
     get tables() {
         return this.content.filter((el) => typeNameOf(el) === 'org_docx4j_wml.Tbl').map((element) => new Table(element, this.content, this));
@@ -282,9 +355,11 @@ export class Body {
      * the package's `changeTrackingMode` is on.
      */
     replaceText(find, replace, options) {
-        const matches = this.search(find, options);
-        for (let i = matches.length - 1; i >= 0; i--)
-            matches[i].insertText(replace, 'Replace');
+        const matches = this.paragraphs.flatMap((p) => p.searchMatches(find, options));
+        for (let i = matches.length - 1; i >= 0; i--) {
+            const { range, match } = matches[i];
+            range.insertText(expandReplacement(replace, match, options), 'Replace');
+        }
         return matches.length;
     }
     /**

package/dist/model/content/Comment.d.mts

@@ -2,7 +2,7 @@ import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import { Body } from './Body.mjs';
 import { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
-import { type CommentParts } from './comments.mjs';
+import { type CommentContent, type CommentOptions, type CommentParts } from './comments.mjs';
 /**
  * A subset of Office JS `Word.Comment` over a `w:comment` and the markers that anchor it. A view:
  * the tree is the state, and a view may be created and discarded freely. Replies are `Comment`s
@@ -51,8 +51,11 @@ export declare class Comment {
     get replies(): Comment[];
     /** The comment this one replies to (extension). */
     get parent(): Comment | undefined;
-    /** A reply in the same thread, anchored to the same range, as Word writes them. */
-    reply(text: string): Promise<Comment>;
+    /**
+     * A reply in the same thread, anchored to the same range, as Word writes them. `options` are
+     * `insertComment`'s (CR-002 section 28.3).
+     */
+    reply(content: CommentContent, options?: CommentOptions): Promise<Comment>;
     /** Removes the comment and its replies: the markers, the reference runs and every side-part entry. */
     delete(): Promise<void>;
     /**
@@ -68,8 +71,15 @@ export declare class Comment {
     /** Used by `commentsOf` while threading. */
     addReply(reply: Comment): void;
 }
-/** `Range.insertComment` (CR-002 section 3.8): the markers, the comment and the side-part entries. */
-export declare function insertComment(range: Range, text: string): Promise<Comment>;
+/**
+ * `Range.insertComment` (CR-002 section 3.8): the markers, the comment and the side-part entries.
+ *
+ * `options` (CR-002 section 28.3) name the author, the initials, the date and the `w:id`: in a
+ * co-editing room the author is the peer who made the comment and the date is when they made it,
+ * neither of which is a property of whoever is saving. A given `id` is checked unused and a clash
+ * throws.
+ */
+export declare function insertComment(range: Range, content: CommentContent, options?: CommentOptions): Promise<Comment>;
 /**
  * `getComments()` on a body, a paragraph or a range: the comments anchored there in document
  * order, replies nested under their parent (a reply is in the array only when its parent is not).

package/dist/model/content/Comment.mjs

@@ -105,12 +105,16 @@ export class Comment {
     get parent() {
         return this.parentComment;
     }
-    /** A reply in the same thread, anchored to the same range, as Word writes them. */
-    async reply(text) {
+    /**
+     * A reply in the same thread, anchored to the same range, as Word writes them. `options` are
+     * `insertComment`'s (CR-002 section 28.3).
+     */
+    async reply(content, options) {
+        const paragraphs = paragraphsOfContent(content);
         const parts = await this.parts.ensureAll();
-        const id = nextCommentId(parts.comments, this.body.container);
+        const id = commentId(parts, this.body, options);
         placeAfter(this.body, this.id, id);
-        const reply = addComment(parts, this.body, id, text, this);
+        const reply = addComment(parts, this.body, id, paragraphs, this, options);
         this.replyList.push(reply);
         reply.parentComment = this;
         return reply;
@@ -291,6 +295,10 @@ function placeAfter(body, parentId, id) {
     const start = markers.find((m) => m.kind === 'start');
     const end = [...markers].reverse().find((m) => m.kind === 'end');
     const reference = [...markers].reverse().find((m) => m.kind === 'reference');
+    if (!((reference === null || reference === void 0 ? void 0 : reference.run) && reference.runOwner) && !end) {
+        // refused before anything is written, so that no marker is left naming a comment never made
+        throw new Docx4JException(`Comment ${parentId} has no markers in this body; cannot anchor a reply`);
+    }
     if (start)
         insertAt(start.owner, start.owner.indexOf(start.item) + 1, [el.commentRangeStart(wmlFactory.createCommentRangeStart({ id }))], parentOf(start.item));
     if (end)
@@ -301,37 +309,37 @@ function placeAfter(body, parentId, id) {
     else if (end) {
         insertAt(end.owner, end.owner.indexOf(end.item) + 1, [referenceRun(id)], parentOf(end.item));
     }
-    else {
-        throw new Docx4JException(`Comment ${parentId} has no markers in this body; cannot anchor a reply`);
-    }
 }
-/** The `w:comment` and the side-part entries of a new comment; the markers are already written. */
-function addComment(parts, body, id, text, parent) {
-    var _a, _b, _c, _d;
-    var _e, _f;
-    const author = parts.author;
-    const paragraphs = text.split('\n').map((line, i) => commentParagraph(line, i === 0));
+/**
+ * The `w:comment` and the side-part entries of a new comment; the markers are already written. The
+ * paragraphs come checked, by `paragraphsOfContent` before the markers were placed.
+ */
+function addComment(parts, body, id, paragraphs, parent, options) {
+    var _a, _b, _c, _d, _e, _f, _g;
+    var _h, _j;
+    const author = (_a = options === null || options === void 0 ? void 0 : options.author) !== null && _a !== void 0 ? _a : parts.author;
     const paraId = randomHexId((candidate) => paraIdTaken(parts, body.container, candidate));
     paragraphs[0].value.paraId = paraId;
     const comment = wmlFactory.createCommentsComment({
-        id, author: author.name, initials: initialsOf(author), date: dateToCalendar(new Date()),
+        id, author: author.name, initials: (_b = options === null || options === void 0 ? void 0 : options.initials) !== null && _b !== void 0 ? _b : initialsOf(author),
+        date: dateToCalendar((_c = options === null || options === void 0 ? void 0 : options.date) !== null && _c !== void 0 ? _c : new Date()),
         content: paragraphs,
     });
-    const comments = ((_a = (_e = parts.comments).comment) !== null && _a !== void 0 ? _a : (_e.comment = []));
+    const comments = ((_d = (_h = parts.comments).comment) !== null && _d !== void 0 ? _d : (_h.comment = []));
     comments.push(comment);
     linkParents(comment, parts.comments);
     const extended = parts.ensureCommentsEx();
     const entry = w15Factory.createCTCommentEx({ paraId, done: '0' });
     if (parent)
         entry.paraIdParent = parent.ensureParaId();
-    ((_b = extended.commentEx) !== null && _b !== void 0 ? _b : (extended.commentEx = [])).push(entry);
+    ((_e = extended.commentEx) !== null && _e !== void 0 ? _e : (extended.commentEx = [])).push(entry);
     linkParents(entry, extended);
     if (parts.commentsIds) {
         const durableId = randomHexId((candidate) => { var _a; return ((_a = parts.commentsIds.commentId) !== null && _a !== void 0 ? _a : []).some((e) => e.durableId === candidate); });
         const commentId = w16cidFactory.createCTCommentId({ paraId, durableId });
-        ((_c = (_f = parts.commentsIds).commentId) !== null && _c !== void 0 ? _c : (_f.commentId = [])).push(commentId);
+        ((_f = (_j = parts.commentsIds).commentId) !== null && _f !== void 0 ? _f : (_j.commentId = [])).push(commentId);
         linkParents(commentId, parts.commentsIds);
-        (_d = parts.extensible) === null || _d === void 0 ? void 0 : _d.set(durableId, new Date());
+        (_g = parts.extensible) === null || _g === void 0 ? void 0 : _g.set(durableId, new Date());
     }
     addPerson(parts, author.name, author.email);
     return new Comment(comment, parts, body);
@@ -354,13 +362,53 @@ function addPerson(parts, name, email) {
     list.push(person);
     linkParents(person, people);
 }
-/** `Range.insertComment` (CR-002 section 3.8): the markers, the comment and the side-part entries. */
-export async function insertComment(range, text) {
+/**
+ * `Range.insertComment` (CR-002 section 3.8): the markers, the comment and the side-part entries.
+ *
+ * `options` (CR-002 section 28.3) name the author, the initials, the date and the `w:id`: in a
+ * co-editing room the author is the peer who made the comment and the date is when they made it,
+ * neither of which is a property of whoever is saving. A given `id` is checked unused and a clash
+ * throws.
+ */
+export async function insertComment(range, content, options) {
+    // Everything that can refuse the call runs before anything is written: the content, then the id
+    // once the parts can say which are taken. A refusal after the markers were placed left them naming
+    // a comment that does not exist (CR-002 section 31).
+    const paragraphs = paragraphsOfContent(content);
     const body = range.paragraph.parentBody;
     const parts = await commentPartsAccess().create(body);
-    const id = nextCommentId(parts.comments, body.container);
+    const id = commentId(parts, body, options);
     placeAround(range, id);
-    return addComment(parts, body, id, text, undefined);
+    return addComment(parts, body, id, paragraphs, undefined, options);
+}
+/**
+ * The `w:id` for a new comment: the caller's when given, checked unused across the comments part and
+ * the markers in the story, else the next free one. A clash throws rather than renumbering, as a
+ * chosen list `numId` does: the caller is asserting something about a room's state (section 28.3).
+ */
+function commentId(parts, body, options) {
+    var _a;
+    if ((options === null || options === void 0 ? void 0 : options.id) === undefined)
+        return nextCommentId(parts.comments, body.container);
+    const id = options.id;
+    if (!Number.isInteger(id) || id < 0)
+        throw new Docx4JException(`A comment id must be a non-negative integer, not ${id}`);
+    if (((_a = parts.comments.comment) !== null && _a !== void 0 ? _a : []).some((c) => c.id === id)) {
+        throw new Docx4JException(`The comment id ${id} is already in use in this document's comments part`);
+    }
+    if (markersOf(body.container).some((m) => m.id === id)) {
+        throw new Docx4JException(`The comment id ${id} is already named by a marker in this story`);
+    }
+    return id;
+}
+/** The paragraphs of a comment's content: a string splits on newlines, elements are taken as they are. */
+function paragraphsOfContent(content) {
+    if (typeof content === 'string')
+        return content.split('\n').map((line, i) => commentParagraph(line, i === 0));
+    const paragraphs = [...content];
+    if (paragraphs.length === 0)
+        throw new Docx4JException('A comment needs at least one paragraph');
+    return paragraphs;
 }
 /**
  * `getComments()` on a body, a paragraph or a range: the comments anchored there in document

package/dist/model/content/List.d.mts

@@ -1,5 +1,5 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
-import type { ListDefinition, LevelDefinition } from '../listnumbering/definitions.mjs';
+import type { NumberingDefinitions, ListDefinition, LevelDefinition } from '../listnumbering/definitions.mjs';
 import type { Emulator } from '../listnumbering/Emulator.mjs';
 import { Font } from './Font.mjs';
 import type { Body } from './Body.mjs';
@@ -31,6 +31,38 @@ export interface ListLabel {
     /** Whether the level's `w:numFmt` is `bullet`. */
     isBullet: boolean;
 }
+/**
+ * The content API must not import `WordprocessingMLPackage` or `parts/wml` at runtime (that
+ * would be a cycle, since `parts/wml` builds the `Body` views), so the numbering part is
+ * reached by shape, as `Body.propertyResolver` and `fonts/lookup` are.
+ */
+interface NumberingPartLike {
+    readonly isUnmarshalled: boolean;
+    readonly contents: wml.Numbering;
+    readonly definitions: NumberingDefinitions;
+    getEmulator(reset?: boolean): Emulator;
+    makeLive(): wml.Numbering;
+    getContents(): Promise<wml.Numbering>;
+}
+/** As much of an `XmlPart` as the story walk reads. */
+interface StoryPartLike {
+    readonly contentType: string;
+    readonly isUnmarshalled: boolean;
+    readonly contents: unknown;
+}
+/** As much of a `MainDocumentPart` as the list views use. */
+interface MainPartLike {
+    numberingDefinitionsPart?: NumberingPartLike;
+    readonly headerParts: StoryPartLike[];
+    readonly footerParts: StoryPartLike[];
+    addTargetPart(part: unknown): unknown;
+}
+/** As much of a `WordprocessingMLPackage` as the list views use. */
+interface ListPackageLike {
+    getMainDocumentPart(): MainPartLike;
+    refreshPropertyResolver(): void;
+    refresh(): Promise<unknown>;
+}
 /**
  * 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).
@@ -251,3 +283,50 @@ export declare function detachFromList(paragraph: Paragraph): void;
  * be unmarshalled, and a document with no numbering part gets one here (CR-002 section 17).
  */
 export declare function startNewList(paragraph: Paragraph, options?: StartListOptions): Promise<List>;
+/**
+ * The document's list definitions, as verbs that need no paragraph (CR-002 section 19, at the
+ * editor's request): `pkg.numbering`.
+ *
+ * `Paragraph.startNewList()` and `List.restart()` are Office JS's shapes and stay as they are,
+ * but both build a definition first and touch a paragraph only at the end. An editor that keeps
+ * its own document model has the numbering part and a `w:numId` to write, and nothing else - and
+ * going through a paragraph would mean projecting a tree, running the verb and projecting back,
+ * a whole-body round trip for what is otherwise one attribute. So the definition half is here.
+ */
+export declare class NumberingFacade {
+    private readonly pkg;
+    constructor(pkg: ListPackageLike);
+    /**
+     * A new list definition, and its `w:numId` as a string for a `w:numPr` to name. The numbering
+     * part is created with docx4j's default definitions where the document has none, and an
+     * existing one is unmarshalled so that what is written to it is saved.
+     *
+     * Asynchronous for the same reasons `startNewList` is: the default definitions are XML to be
+     * unmarshalled, and the part may have to be created. Nothing is attached to anything; the
+     * caller writes `w:numPr` itself.
+     */
+    newList(options?: {
+        bullet?: boolean;
+    } & ChosenListIds): Promise<string>;
+    /**
+     * A `w:num` that numbers as `numId` does but starts again, and its own `w:numId`:
+     * `List.restart()` without needing a `Body`. The counters are shared by abstract definition,
+     * so restarting means a new `w:num` with a `w:startOverride`, spent on its first use in a
+     * story (CR-001 section 15.2).
+     *
+     * Synchronous, so the numbering part must have been read: `await pkg.getPropertyResolver()`,
+     * `newList()` or any list read does it.
+     */
+    restart(numId: string | number, options?: {
+        newNumId?: string | number;
+    }): string;
+}
+/**
+ * The identifiers a caller may choose for a new list definition, when the next integer is the wrong
+ * answer: in a co-editing room two sessions allocate at once, so the editor picks random ids and
+ * needs them honoured rather than renumbered (CR-002 section 24).
+ */
+export interface ChosenListIds {
+    numId?: string | number | undefined;
+    abstractNumId?: string | number | undefined;
+}