@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/model/content/tree.mjs

@@ -1,5 +1,6 @@
-import { isElement, typeNameOf, runItemsOf, mcBranchOf } from '@docx4j/generated-objects-ts/builders/wml';
-import { UNDERSTOOD_PREFIXES } from '../../opc/mce/understood.mjs';
+import { isElement, typeNameOf, runItemsOf, mcBranchOf, sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
+import { isMath, mathTextOf } from './mathText.mjs';
+import { NotSupportedError } from '../../office-js/errors.mjs';
 export { isElement, typeNameOf, walk, find, linkParents, textOf, W_NS } from '@docx4j/generated-objects-ts/builders/wml';
 /**
  * Run content that stands in the text and has no text of its own: a `w:drawing` (a picture, a chart, a
@@ -12,13 +13,14 @@ export const OBJECT_ITEMS = new Set(['drawing', 'pict', 'object']);
 export const ALTERNATE_CONTENT = 'org_docx4j_mce.AlternateContent';
 /**
  * The branch of a kept `mc:AlternateContent` the content API reads (docx4j's `McMode.READ`, CR-010
- * phase 3): the objects package's `mcBranchOf` over the prefixes load understands
- * (`UNDERSTOOD_PREFIXES`), so a reader of the kept element takes the branch the preprocessor would have
- * resolved it to. A mutator walks every branch instead (docx4j's `McMode.ALL`). Undefined for an element
- * with no branches.
+ * phase 3): the objects package's `mcBranchOf`, the first `mc:Choice` whose `Requires` names only namespaces in the
+ * understood set, by URI, else the `mc:Fallback`, else nothing (WD REQ-302 to REQ-305, CR-029). So a reader takes the
+ * branch the preprocessor resolves the element to. A mutator walks every branch instead (docx4j's `McMode.ALL`). Undefined
+ * where nothing is selected, as for an element with no branches. `options` are `mcBranchOf`'s: the text model passes
+ * `onNothingSelected` for `mce.nothing_selected`.
  */
-export function selectedBranchOf(value) {
-    return mcBranchOf(value, { understood: UNDERSTOOD_PREFIXES });
+export function selectedBranchOf(value, options) {
+    return mcBranchOf(value, options);
 }
 /** True for a kept `mc:AlternateContent`: its element pair, or its value. */
 export function isAlternateContent(value) {
@@ -52,6 +54,46 @@ function shows(view, kind) {
     return view === 'accepted' ? kind === 'ins' || kind === 'moveTo' : kind === 'del' || kind === 'moveFrom';
 }
 export { runItemsOf };
+/**
+ * An item's text in Office JS's text, Word's own character stream (CR-012 phase 4; check 48, Word 365):
+ * a `w:br` U+000B, of type page U+000C and column U+000E; a `w:cr` U+000D; a `w:ptab` `0`; the
+ * non-breaking and optional hyphens U+001E and U+001F; any `w:sym` `(`, whatever its font or code
+ * (check 48b); a footnote or endnote reference U+0002, and so the note's own mark (`w:footnoteRef`,
+ * `w:endnoteRef`, not measured). Undefined for an item that adds no text: a comment reference, a
+ * field's characters and code, a drawing.
+ */
+export function officeItemText(item) {
+    var _a;
+    const v = item.value;
+    switch (item.name.localPart) {
+        case 't':
+        case 'delText': return String((_a = v.value) !== null && _a !== void 0 ? _a : '');
+        case 'tab': return '\t';
+        case 'br': return v.type === 'page' ? '\f' : v.type === 'column' ? '\u000E' : '\u000B';
+        case 'cr': return '\r';
+        case 'ptab': return '0';
+        case 'noBreakHyphen': return '\u001E';
+        case 'softHyphen': return '\u001F';
+        case 'sym': return '(';
+        case 'footnoteReference':
+        case 'endnoteReference':
+        case 'footnoteRef':
+        case 'endnoteRef': return '\u0002';
+        default: return undefined;
+    }
+}
+/** An item a run-level element's selected branch may hold that makes the element one object (CR-012 section 12.2 item 5). */
+function isDrawn(item) {
+    return OBJECT_ITEMS.has(item.name.localPart);
+}
+/** The `run` of an equation's segment: it is in no run, and nothing may be written to this one. */
+function standIn(math) {
+    return Object.freeze({ TYPE_NAME: 'org_docx4j_wml.R', PARENT: math.value.PARENT });
+}
+/**
+ * The item text the revision listings and the text model's plan count (`itemTextOf`): whether a run
+ * holds text, in the characters `textOf` gives. Not Office JS's (`officeItemText`).
+ */
 function itemText(item) {
     var _a, _b;
     const t = item.name.localPart;
@@ -72,53 +114,103 @@ function itemText(item) {
     }
 }
 /**
- * The text segments of a paragraph (or any run holder) in order. The default view is the
- * accepted one: the runs of a `w:ins` or `w:moveTo` count, those of a `w:del` or `w:moveFrom`
- * do not. `{ view: 'original' }` is the other way round (CR-002 phase F). `{ objects: true }`
- * lists the drawn objects too, each a segment of no text where it stands (CR-002 section 48).
+ * The text segments of a paragraph (or any run holder) in order, in Office JS's characters
+ * (`officeItemText`). The default view is the accepted one: the runs of a `w:ins` or `w:moveTo`
+ * count, those of a `w:del` or `w:moveFrom` do not. `{ view: 'original' }` is the other way round
+ * (CR-002 phase F). `{ objects: true }` lists the drawn objects too, each a segment of no text where
+ * it stands (CR-002 section 48), and the items of hidden runs (`hidden`).
  *
- * A kept `mc:AlternateContent` in a run is one object segment, whatever its branches hold, so that
- * removing a span removes every branch with it (CR-010 phase 3). A drawing adds no text, so the
- * offsets are a resolved load's. One in a paragraph's content, outside a run, is not listed: Word
- * writes none, and the corpus has none (CR-010 section 11.3).
+ * A kept `mc:AlternateContent` reads as its selected branch (CR-012 section 12.2, ED-009): in a run,
+ * a branch holding run items reads as those items, at the run's offsets, and one holding a drawing,
+ * a picture or an object is one object segment, as a drawing is (CR-010 phase 3); among a paragraph's
+ * runs, it reads as the runs its branch holds. Either way the segments carry `alternate`, so that an
+ * edit lands in that branch. An equation is one segment of its drawn text (`math`).
  */
 export function segmentsOf(container, options) {
     var _a;
     const view = (_a = options === null || options === void 0 ? void 0 : options.view) !== null && _a !== void 0 ? _a : 'accepted';
     const objects = (options === null || options === void 0 ? void 0 : options.objects) === true;
+    const hiddenRun = options === null || options === void 0 ? void 0 : options.hidden;
+    const visit = options === null || options === void 0 ? void 0 : options.visit;
+    const office = (options === null || options === void 0 ? void 0 : options.characters) !== 'textOf';
+    const charactersOf = office ? officeItemText : itemText;
     const out = [];
     let pos = 0;
-    const visitRuns = (items, revision) => {
+    const runContent = (run, runEl, content, runOwner, runIndex, revision, alternate, hidden) => {
+        for (let j = 0; j < content.length; j++) {
+            const item = content[j];
+            const where = { owner: content, index: j, run, runOwner, runIndex };
+            if (office && isAlternateContent(item)) {
+                const branch = selectedBranchOf(item.value);
+                // a branch holding content the model doesn't bind (DOM) is one object, as a drawing is
+                if (branch && branch.every(isElement) && !branch.some(isDrawn)) {
+                    runContent(run, runEl, branch, runOwner, runIndex, revision, { element: item, owner: content, branch, level: 'run' }, hidden);
+                    continue;
+                }
+            }
+            const text = charactersOf(item);
+            if (text === undefined || (hidden && text !== '')) {
+                const drawn = OBJECT_ITEMS.has(item.name.localPart) || isAlternateContent(item);
+                if (objects && (drawn || (hidden && text !== undefined))) {
+                    const seg = { item, ...where, text: '', start: pos, end: pos, editable: false, object: true };
+                    if (hidden)
+                        seg.hidden = true;
+                    if (revision)
+                        seg.revision = revision;
+                    if (alternate)
+                        seg.alternate = alternate;
+                    out.push(seg);
+                }
+                visit === null || visit === void 0 ? void 0 : visit(item, pos, content, { element: runEl, owner: runOwner });
+                continue;
+            }
+            const seg = { item, ...where, text, start: pos, end: pos + text.length, editable: item.name.localPart === 't' };
+            if (revision)
+                seg.revision = revision;
+            if (alternate)
+                seg.alternate = alternate;
+            out.push(seg);
+            pos += text.length;
+        }
+    };
+    const visitRuns = (items, revision, alternate) => {
         var _a;
         if (!items)
             return;
         for (let i = 0; i < items.length; i++) {
             const el = items[i];
+            if (!isElement(el))
+                continue; // a kept branch's unbound content (DOM)
+            visit === null || visit === void 0 ? void 0 : visit(el, pos, items, undefined);
             const tn = typeNameOf(el);
             if (tn === 'org_docx4j_wml.R') {
                 const run = el.value;
-                const content = (_a = run.content) !== null && _a !== void 0 ? _a : [];
-                for (let j = 0; j < content.length; j++) {
-                    const item = content[j];
-                    const text = itemText(item);
-                    if (text === undefined) {
-                        if (objects && (OBJECT_ITEMS.has(item.name.localPart) || isAlternateContent(item))) {
-                            const seg = { item, owner: content, index: j, run, runOwner: items, runIndex: i, text: '', start: pos, end: pos, editable: false, object: true };
-                            if (revision)
-                                seg.revision = revision;
-                            out.push(seg);
-                        }
-                        continue;
-                    }
-                    const seg = {
-                        item, owner: content, index: j, run, runOwner: items, runIndex: i, text,
-                        start: pos, end: pos + text.length, editable: item.name.localPart === 't',
-                    };
-                    if (revision)
-                        seg.revision = revision;
-                    out.push(seg);
-                    pos += text.length;
-                }
+                runContent(run, el, (_a = run.content) !== null && _a !== void 0 ? _a : [], items, i, revision, alternate, (hiddenRun === null || hiddenRun === void 0 ? void 0 : hiddenRun(run)) === true);
+                continue;
+            }
+            if (!office) {
+                // textOf's reader: no branch among the runs, no equation
+            }
+            else if (isAlternateContent(el)) {
+                const branch = selectedBranchOf(el.value);
+                if (branch)
+                    visitRuns(branch, revision, { element: el, owner: items, branch, level: 'paragraph' });
+                continue;
+            }
+            else if (isMath(el)) {
+                const text = mathTextOf(el.value, view);
+                if (text === '')
+                    continue;
+                const seg = {
+                    item: el, owner: items, index: i, run: standIn(el), runOwner: items, runIndex: i, text,
+                    start: pos, end: pos + text.length, editable: false, math: true,
+                };
+                if (revision)
+                    seg.revision = revision;
+                if (alternate)
+                    seg.alternate = alternate;
+                out.push(seg);
+                pos += text.length;
                 continue;
             }
             const kind = revisionKindOf(el);
@@ -127,21 +219,60 @@ export function segmentsOf(container, options) {
                     continue;
                 const nested = runItemsOf(el.value);
                 if (nested)
-                    visitRuns(nested, { kind, element: el, value: el.value, items: nested, owner: items });
+                    visitRuns(nested, { kind, element: el, value: el.value, items: nested, owner: items }, alternate);
             }
             else if (tn !== undefined && RUN_HOLDERS.has(tn)) {
-                visitRuns(runItemsOf(el.value), revision);
+                visitRuns(runItemsOf(el.value), revision, alternate);
             }
         }
     };
-    visitRuns(runItemsOf(container), undefined);
+    visitRuns(runItemsOf(container), undefined, undefined);
     return out;
 }
-/** The text of a paragraph or container in one of the two views (`textOf` is the accepted one). */
+/**
+ * Which of a paragraph's runs are hidden, as the text model's rule has it (REQ-507) and Office JS's text
+ * leaves them out (check 48b): a run's own `w:vanish`, else its paragraph style's and character style's.
+ * Without a resolver only a run's own counts.
+ */
+export function hiddenRunsOf(resolver, p) {
+    var _a, _b;
+    const pStyle = (_b = (_a = p.pPr) === null || _a === void 0 ? void 0 : _a.pStyle) === null || _b === void 0 ? void 0 : _b.val;
+    return (run) => {
+        var _a, _b, _c, _d;
+        if (inShowingPlaceholder(run))
+            return true;
+        const own = (_a = run.rPr) === null || _a === void 0 ? void 0 : _a.vanish;
+        if (own !== undefined && own !== null)
+            return own.val !== false;
+        return (_d = resolver === null || resolver === void 0 ? void 0 : resolver.isVanishedByStyles(pStyle, (_c = (_b = run.rPr) === null || _b === void 0 ? void 0 : _b.rStyle) === null || _c === void 0 ? void 0 : _c.val)) !== null && _d !== void 0 ? _d : false;
+    };
+}
+/**
+ * Whether a run is in a content control showing its placeholder (`w:showingPlcHdr`), run-level or block-level, up its
+ * `PARENT`s. Office JS reads a placeholder as no text, and finds no text there to keep (check 53 cases 34 and 35, check 58
+ * cases 11 and 12; CR-012 section 18), so the readers take its runs as they take hidden ones.
+ */
+export function inShowingPlaceholder(run) {
+    var _a;
+    let o = run.PARENT;
+    for (let guard = 0; o && guard < 32; guard++, o = o.PARENT) {
+        const v = o;
+        if (v.sdtPr === undefined || v.sdtContent === undefined)
+            continue;
+        const item = sdtProperty(v.sdtPr, 'showingPlcHdr');
+        if (item !== undefined && ((_a = item.value) === null || _a === void 0 ? void 0 : _a.val) !== false)
+            return true;
+    }
+    return false;
+}
+/** The text of a paragraph or container in one of the two views, in Office JS's characters (`segmentsOf`). */
 export function textOfView(container, options) {
     return segmentsOf(container, options).map((s) => s.text).join('');
 }
-/** The runs of a paragraph, direct and nested in hyperlinks, content controls and insertions, in order. */
+/**
+ * The runs of a paragraph, direct and nested in hyperlinks, content controls and insertions, in order,
+ * and in the selected branch of a kept `mc:AlternateContent` among them (CR-012 section 12.2).
+ */
 export function runsOf(container, options) {
     var _a;
     const view = (_a = options === null || options === void 0 ? void 0 : options.view) !== null && _a !== void 0 ? _a : 'accepted';
@@ -155,6 +286,10 @@ export function runsOf(container, options) {
                 out.push(el);
                 continue;
             }
+            if (isAlternateContent(el)) {
+                visit(selectedBranchOf(el.value));
+                continue;
+            }
             const kind = revisionKindOf(el);
             if (kind !== undefined) {
                 if (shows(view, kind))
@@ -167,30 +302,129 @@ export function runsOf(container, options) {
     visit(runItemsOf(container));
     return out;
 }
+/** The TYPE_NAMEs of a kept `mc:AlternateContent`'s branches, whose items are their `any`. */
+export const BRANCH_TYPES = new Set(['org_docx4j_mce.AlternateContent.Choice', 'org_docx4j_mce.AlternateContent.Fallback']);
 /**
  * The block-level children of a container: body, header, footer, cell, sdt content, table (rows),
  * row (cells). A content control of any kind (block, row, cell, run) answers with its
- * `sdtContent`'s content, so that a traversal does not have to know the four types.
+ * `sdtContent`'s content, so that a traversal does not have to know the four types. A branch of a kept
+ * `mc:AlternateContent` (a Choice or the Fallback) answers with its items, so that a locator climbing
+ * `PARENT` from a branch's paragraph, row or cell finds the list it is in; the element itself answers
+ * in a reader's walk (`'read'`) with its selected branch (CR-013 phase 2), and otherwise not at all.
  */
-export function childrenOf(value) {
+export function childrenOf(value, mode) {
     const v = value;
     if (v.sdtContent)
         return v.sdtContent.content;
-    return Array.isArray(v.content) ? v.content : undefined;
+    if (Array.isArray(v.content))
+        return v.content;
+    const tn = v.TYPE_NAME;
+    if (tn === undefined)
+        return undefined;
+    if (BRANCH_TYPES.has(tn))
+        return v.any;
+    if (mode === 'read' && tn === ALTERNATE_CONTENT)
+        return selectedBranchOf(v);
+    return undefined;
+}
+/** Every branch of a kept `mc:AlternateContent`, the Choices in order, then the Fallback. */
+export function branchesOf(value) {
+    var _a, _b;
+    const out = [];
+    for (const choice of (_a = value.choice) !== null && _a !== void 0 ? _a : [])
+        if (choice.any)
+            out.push(choice.any);
+    if ((_b = value.fallback) === null || _b === void 0 ? void 0 : _b.any)
+        out.push(value.fallback.any);
+    return out;
+}
+/** How many bulk edits are writing in every branch now (`writingEveryBranch`). */
+let everyBranch = 0;
+/**
+ * Runs a bulk edit that reaches every branch of a kept `mc:AlternateContent` (CR-013 phase 3): a
+ * `replaceText`, a tracked clear or row deletion, the binding passes. Inside it the views it makes of
+ * what is in a branch write, where a caller's view refuses (D4): the edit itself reaches every branch,
+ * the selected one and the others alike, as CR-010's rule has mutators do.
+ */
+export function writingEveryBranch(edit) {
+    everyBranch++;
+    try {
+        return edit();
+    }
+    finally {
+        everyBranch--;
+    }
+}
+/**
+ * Refuses a write through a view in a branch of a kept `mc:AlternateContent` at block, row or cell level
+ * (CR-013 D4): the view reads the selected branch, and a write would have to reach the element's other
+ * branches too, which nothing maps. A bulk edit reaching every branch writes there (`writingEveryBranch`).
+ * `className` is Office JS's ('Paragraph', 'Body').
+ */
+export function assertOutsideBranch(value, className, what = `this ${className.toLowerCase()}`) {
+    if (everyBranch === 0 && inBranch(value)) {
+        throw new NotSupportedError(className, 'edit', `${what} is in a branch of an mc:AlternateContent, which is read-only (CR-013 D4): `
+            + "a write would have to reach the element's other branches too, which nothing maps yet");
+    }
+}
+/**
+ * True for a value inside a branch of a kept `mc:AlternateContent` at block, row or cell level: a
+ * paragraph, table, row, cell or content control a reader sees in the selected branch (CR-013 phase 2).
+ * A view of one is read-only (D4). From `PARENT` links; a run-level element's content is not reached
+ * from a paragraph, which is outside it.
+ */
+export function inBranch(value) {
+    let o = value === null || value === void 0 ? void 0 : value.PARENT;
+    for (let guard = 0; o && guard < 256; guard++, o = o.PARENT) {
+        const tn = o.TYPE_NAME;
+        if (tn !== undefined && BRANCH_TYPES.has(tn))
+            return true;
+    }
+    return false;
+}
+/**
+ * True for a value no reader sees: inside a branch of a kept `mc:AlternateContent` other than the one
+ * `selectedBranchOf` takes, at any depth (CR-013 phase 3). What a bulk edit writes there it does not
+ * count, as resolve-all counts the listed changes: the count is of what a reader sees.
+ */
+export function inUnreadBranch(value) {
+    let o = value === null || value === void 0 ? void 0 : value.PARENT;
+    for (let guard = 0; o && guard < 256; guard++, o = o.PARENT) {
+        const tn = o.TYPE_NAME;
+        if (tn === undefined || !BRANCH_TYPES.has(tn))
+            continue;
+        const ac = o.PARENT;
+        if (ac && selectedBranchOf(ac) !== o.any)
+            return true;
+    }
+    return false;
+}
+/**
+ * The lists a walk takes for a kept `mc:AlternateContent` among blocks, rows or cells: a reader's
+ * (`'read'`) its selected branch, a mutator's (`'every'`) every branch, the Choices first.
+ */
+export function branchListsOf(value, mode) {
+    if (mode === 'every')
+        return branchesOf(value);
+    const read = selectedBranchOf(value);
+    return read ? [read] : [];
 }
 /** w:sdt and w:customXml at row level: they hold the rows of a table (docx4j CTSdtRow, CTCustomXmlRow). */
 const ROW_HOLDERS = new Set(['org_docx4j_wml.CTSdtRow', 'org_docx4j_wml.CTCustomXmlRow']);
 /** The same at cell level. */
 const CELL_HOLDERS = new Set(['org_docx4j_wml.CTSdtCell', 'org_docx4j_wml.CTCustomXmlCell']);
-/** The rows of a table, in order, descending into row-level content controls (an OpenDoPE repeat). */
-export function rowsOf(tbl) {
-    return located(childrenOf(tbl), 'org_docx4j_wml.Tr', ROW_HOLDERS);
+/**
+ * The rows of a table, in order, descending into row-level content controls (an OpenDoPE repeat), and,
+ * with a mode, into a row-level `mc:AlternateContent` (`BranchMode`; CR-013 phase 2).
+ */
+export function rowsOf(tbl, mode) {
+    return located(childrenOf(tbl), 'org_docx4j_wml.Tr', ROW_HOLDERS, mode);
 }
-/** The cells of a row, in order, descending into cell-level content controls. */
-export function cellsOf(tr) {
-    return located(childrenOf(tr), 'org_docx4j_wml.Tc', CELL_HOLDERS);
+/** The cells of a row, in order, descending into cell-level content controls, and with a mode into a cell-level `mc:AlternateContent`. */
+export function cellsOf(tr, mode) {
+    return located(childrenOf(tr), 'org_docx4j_wml.Tc', CELL_HOLDERS, mode);
 }
-function located(items, typeName, holders) {
+function located(items, typeName, holders, mode, reading) {
     const out = [];
     const visit = (list) => {
         if (!list)
@@ -201,11 +435,51 @@ function located(items, typeName, holders) {
                 out.push({ element, container: list });
             else if (tn !== undefined && holders.has(tn) && typeof element.value === 'object' && element.value !== null)
                 visit(childrenOf(element.value));
+            else if (tn === ALTERNATE_CONTENT && mode !== undefined) {
+                if (reading && element.value === reading.ac)
+                    visit(reading.branch);
+                else
+                    for (const branch of branchListsOf(element.value, mode))
+                        visit(branch);
+            }
         }
     };
     visit(items);
     return out;
 }
+/**
+ * A row's cells as laid along the grid, one list per reading of the row (docx4j's `Lister.cellLayoutsOf`,
+ * its CR-051 phase 2): the selected branches' first (`cellsOf(tr, 'read')`), then, for each cell-level
+ * `mc:AlternateContent` and each of its other branches, the row read with that branch in the element's
+ * place. Every branch spans the same grid columns, so every cell is in some list at its grid position:
+ * what a pass over the grid's columns walks (`collapseGrid`, the column passes; CR-013 phase 3).
+ */
+export function cellLayoutsOf(tr) {
+    const out = [cellsOf(tr, 'read')];
+    const elements = [];
+    const collect = (list) => {
+        for (const element of list !== null && list !== void 0 ? list : []) {
+            const tn = typeNameOf(element);
+            if (tn === ALTERNATE_CONTENT) {
+                elements.push(element.value);
+                for (const branch of branchesOf(element.value))
+                    collect(branch);
+            }
+            else if (tn !== undefined && CELL_HOLDERS.has(tn) && typeof element.value === 'object' && element.value !== null) {
+                collect(childrenOf(element.value));
+            }
+        }
+    };
+    collect(childrenOf(tr));
+    for (const ac of elements) {
+        const read = selectedBranchOf(ac);
+        for (const branch of branchesOf(ac)) {
+            if (branch !== read)
+                out.push(located(childrenOf(tr), 'org_docx4j_wml.Tc', CELL_HOLDERS, 'read', { ac, branch }));
+        }
+    }
+    return out;
+}
 /** Content controls: `w:sdt` at block, row, cell and run level, by TYPE_NAME. */
 export const SDT_TYPES = new Set([
     'org_docx4j_wml.SdtBlock', 'org_docx4j_wml.SdtRun', 'org_docx4j_wml.CTSdtRow', 'org_docx4j_wml.CTSdtCell',

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

@@ -0,0 +1,48 @@
+/** How Word 365 stores an attribute a setter writes, and the range the setter writes within, in the attribute's unit. */
+export interface WordStorage {
+    /** The attribute, as the part writes it. */
+    attribute: string;
+    /** The attribute's unit, and how many make a point. */
+    unit: 'twips' | 'half-points' | 'fiftieths of a percent';
+    min: number;
+    max: number;
+    /** What Word reads a value as, once it is stored: the wrap, as CR-066 measured it (the objects package's `wordIntegerReading`). */
+    reads(value: number): string;
+    /** Measured by CR-066's rounds 5 and 6: every row is, since round 6 (section 65.6). */
+    measured: boolean;
+    /** The range Word keeps as written, the objects table's (`keptRange`), before the setter's policy narrows it. */
+    stored: readonly [number, number];
+    /** Why a value Word would keep as written is refused all the same: the range narrowed below Word's storage. */
+    why?: string;
+    /** The objects table's entry the row reads: `TYPE_NAME`, property, and the rule beside the attribute where one applies. */
+    objects: {
+        typeName: string;
+        property: string;
+        rule?: 'auto' | 'exact' | 'atLeast';
+    };
+}
+/**
+ * The attributes the content API's setters write, by Word 365's storage (the objects table; CR-066 sections 3.1 and 3.4),
+ * narrowed where Word's own setter stops short of its storage (check 71b, CR-002 section 65.9, D2): there this package
+ * refuses where Word does, and no earlier.
+ */
+export declare const WORD_STORAGE: {
+    readonly indLeft: WordStorage;
+    readonly indRight: WordStorage;
+    readonly indFirstLine: WordStorage;
+    readonly indHanging: WordStorage;
+    readonly lvlIndLeft: WordStorage;
+    readonly spacingBefore: WordStorage;
+    readonly spacingAfter: WordStorage;
+    readonly spacingLineAuto: WordStorage;
+    readonly tcWDxa: WordStorage;
+    readonly tcWPct: WordStorage;
+    readonly sz: WordStorage;
+};
+/**
+ * `points` in the attribute's unit, rounded, where Word stores it as written and the setter's policy allows; else
+ * `InvalidArgument`, naming the range and what Word would read, or why the policy stops short of Word's storage (CR-002
+ * section 65; the policy section 65.9's). `where` is the setter (`Paragraph.leftIndent`). `units` is the value already
+ * in the attribute's unit, where the setter computes it otherwise (a percentage width's fiftieths).
+ */
+export declare function withinWord(where: string, points: number, storage: WordStorage, units?: number): number;

package/dist/model/content/wordRange.mjs

@@ -0,0 +1,97 @@
+// CR-002 section 65: a measurement setter writes a value only where Word 365 stores it as written. Word keeps each
+// integer attribute in a field of its binary format's width, 16 bits for these, and reads a value past it wrapped, with
+// no error or repair (docx4j CR-065 round 2, CR-066 rounds 5 and 6, run by Jason 2026-10-26): a left indent of 400,000 pt,
+// 8,000,000 twips, opens as 4,608. So the setters refuse such a value, as Office JS refuses an argument it won't take.
+// The width is the attribute's, not its simple type's (CR-066 section 3.1). A file's value is read and kept as written.
+// Since section 65.3 the storage comes from the objects package's table (`WORD_INTEGER_STORAGE`, its CR-016), through
+// `keptRange`, one source for the setters' guards and the out-of-range warnings (CR-017); what each row adds is the
+// setters' own policy, a range narrowed below Word's storage where a value Word keeps is still a caller's mistake.
+import { wordIntegerReading } from '@docx4j/generated-objects-ts/helpers/wml';
+import { keptRange } from '../wordIntegers.mjs';
+import { InvalidArgument } from './generalException.mjs';
+const WML = 'org_docx4j_wml.';
+const WORD_SPACING_LIMIT = "Word's own setter stops at 22 inches, 1584 pt (check 71b); its storage runs to 65535, which its save writes back as -1";
+/**
+ * A row from the objects table: the range Word keeps as written there (`keptRange`), narrowed by the setter's policy
+ * where `min`, `max` and `why` say so; `reads` through `wordIntegerReading`. A row whose entry the table lacks, or
+ * no longer measures, fails here, at load, so a table change announces itself.
+ */
+function row(attribute, unit, typeName, property, policy = {}) {
+    var _a, _b;
+    const range = keptRange(WML + typeName, property, policy.rule);
+    if (range === undefined || range === null)
+        throw new Error(`wordRange: the objects table has no measured range for ${typeName}.${property}`);
+    const name = (p) => (p === 'hanging' ? 'a hanging indent' : 'a first-line indent');
+    return {
+        attribute, unit, measured: true, stored: range,
+        min: (_a = policy.min) !== null && _a !== void 0 ? _a : range[0], max: (_b = policy.max) !== null && _b !== void 0 ? _b : range[1],
+        ...(policy.why !== undefined ? { why: policy.why } : {}),
+        objects: { typeName: WML + typeName, property, ...(policy.rule !== undefined ? { rule: policy.rule } : {}) },
+        reads(value) {
+            const r = wordIntegerReading(WML + typeName, property, value, policy.rule);
+            if (r === undefined || r.value === null)
+                return 'not known';
+            if (r.attribute !== undefined && r.attribute !== property)
+                return `${name(r.attribute)} of ${r.value}`;
+            if (r.rule !== undefined && policy.rule !== undefined)
+                return `${r.rule} ${r.value}`;
+            return String(r.value);
+        },
+    };
+}
+/**
+ * The attributes the content API's setters write, by Word 365's storage (the objects table; CR-066 sections 3.1 and 3.4),
+ * narrowed where Word's own setter stops short of its storage (check 71b, CR-002 section 65.9, D2): there this package
+ * refuses where Word does, and no earlier.
+ */
+export const WORD_STORAGE = {
+    // int16, wraps (w:left measured by round 5, w:right by round 6); Word's own indent setters wrap too, and this package
+    // refuses instead (section 65.5, D1)
+    indLeft: row('w:ind/@w:left', 'twips', 'PPrBase.Ind', 'left'),
+    indRight: row('w:ind/@w:right', 'twips', 'PPrBase.Ind', 'right'),
+    // one signed 16-bit field, the binary format's dxaLeft1: a first-line indent as itself, a hanging indent as its negative,
+    // so 0 to 32767 and 0 to 32768 (check 71: Word's firstLineIndent setter wrote 1638.4 pt as a hanging indent of 32768;
+    // round 6, the file side: a first-line indent of 32768 reads as a hanging indent of 32768)
+    indFirstLine: row('w:ind/@w:firstLine', 'twips', 'PPrBase.Ind', 'firstLine'),
+    indHanging: row('w:ind/@w:hanging', 'twips', 'PPrBase.Ind', 'hanging'),
+    // a list level's text indent, the same int16 field, but Word's own setLevelIndents refuses at 1584 pt either side
+    // (check 71b: 1583.95 and -1583.95 written, 1584 and -1584 InvalidArgument), so 31679 twips either way
+    lvlIndLeft: row('w:ind/@w:left', 'twips', 'PPrBase.Ind', 'left', { min: -31679, max: 31679, why: "Word's own setLevelIndents stops short of 22 inches, 1584 pt, either way (check 71b)" }),
+    // uint16, wraps, and Word's save writes 0xFFFF back as -1; Word's own setters stop at 22 inches, 1584 pt (check 71b: 1584
+    // written as 31680, 1584.05 InvalidArgument; a negative refused, the schema's type being unsigned too)
+    spacingBefore: row('w:spacing/@w:before', 'twips', 'PPrBase.Spacing', 'before', { max: 31680, why: WORD_SPACING_LIMIT }),
+    spacingAfter: row('w:spacing/@w:after', 'twips', 'PPrBase.Spacing', 'after', { max: 31680, why: WORD_SPACING_LIMIT }),
+    // Office JS's lineSpacing, in points, is the line as a multiple of 12 pt ("in the Word UI, this value is divided by 12"):
+    // Word's own setter writes w:line = 20 × points under w:lineRule="auto" (check 71b: 0.75 pt as w:line="15"
+    // w:lineRule="auto", 1584 as 31680), and takes 0.75 to 1584 pt (0.7 and 1584.05 InvalidArgument); int16, wraps
+    spacingLineAuto: row('w:spacing/@w:line', 'twips', 'PPrBase.Spacing', 'line', { rule: 'auto', min: 15, max: 31680, why: "Word's own setter takes 0.75 to 1584 pt, 15 to 31680 twips under w:lineRule=\"auto\" (check 71b)" }),
+    // int16, wraps, under dxa and under pct; a width is never negative
+    tcWDxa: row('w:tcW/@w:w', 'twips', 'TblWidth', 'w', { min: 0, why: "a cell's width is never negative" }),
+    tcWPct: row('w:tcW/@w:w', 'fiftieths of a percent', 'TblWidth', 'w', { min: 0, why: "a cell's width is never negative" }),
+    // uint16, wraps; Word's own setter takes 1 to 1638 pt, in half-points after rounding (check 71b: 0.9 written as w:sz
+    // w:val="2", 1638.05 as 3276, 0.5 and 1638.4 InvalidArgument), where its storage runs to 65535
+    sz: row('w:sz/@w:val', 'half-points', 'HpsMeasure', 'val', { min: 2, max: 3276, why: "Word's own setter takes 1 to 1638 pt, 2 to 3276 half-points after rounding (check 71b)" }),
+};
+const PER_POINT = { twips: 20, 'half-points': 2 };
+/**
+ * `points` in the attribute's unit, rounded, where Word stores it as written and the setter's policy allows; else
+ * `InvalidArgument`, naming the range and what Word would read, or why the policy stops short of Word's storage (CR-002
+ * section 65; the policy section 65.9's). `where` is the setter (`Paragraph.leftIndent`). `units` is the value already
+ * in the attribute's unit, where the setter computes it otherwise (a percentage width's fiftieths).
+ */
+export function withinWord(where, points, storage, units) {
+    if (!Number.isFinite(points))
+        throw new InvalidArgument(`${where}: ${points} is not a measurement in points`);
+    const unit = storage.unit;
+    const value = units !== null && units !== void 0 ? units : Math.round(points * PER_POINT[unit]);
+    if (value >= storage.min && value <= storage.max)
+        return value;
+    const inPoints = unit in PER_POINT
+        ? `, ${storage.min / PER_POINT[unit]} to ${storage.max / PER_POINT[unit]} pt`
+        : '';
+    // within Word's storage the value is kept as written, so the refusal is the setter's policy; past it, what Word reads
+    const kept = value >= storage.stored[0] && value <= storage.stored[1];
+    const reason = kept && storage.why !== undefined ? storage.why : `Word 365 would read it as ${storage.reads(value)}`;
+    throw new InvalidArgument(`${where}: ${points} pt is ${value} ${unit} in ${storage.attribute}, outside the range written there `
+        + `(${storage.min} to ${storage.max} ${unit}${inPoints}): ${reason} (CR-002 section 65)`);
+}