@docx4j/core-ts 0.5.0 → 0.7.0

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

@@ -3,7 +3,7 @@ import type * as w15 from '@docx4j/generated-objects-ts/modules/org_docx4j_w15';
 import type * as w16cid from '@docx4j/generated-objects-ts/modules/org_docx4j_w16cid';
 import type { XmlCalendar } from '@docx4j/generated-objects-ts';
 import type { XmlPart } from '../../parts/XmlPart.mjs';
-import { type Element } from './tree.mjs';
+import { type BranchMode, type HiddenRuns, type Element } from './tree.mjs';
 import type { Body } from './Body.mjs';
 import type { Paragraph } from './Paragraph.mjs';
 import type { Range } from './Range.mjs';
@@ -92,6 +92,14 @@ export interface CommentParts {
     ensureCommentsEx(): w15.CTCommentsEx;
     /** Loads and creates the side parts the bookkeeping needs (w15, w16cid; w16cex only if present). */
     ensureAll(): Promise<CommentParts>;
+    /** Loads the side parts the document has, creating none: what removing a comment needs. */
+    loadExisting(): Promise<CommentParts>;
+    /**
+     * Takes the comments part and its commentsExtended, commentsIds and commentsExtensible parts out of
+     * the package, with their relationships, and the people part too when `people` is true. A part
+     * another relationship still targets stays.
+     */
+    drop(people: boolean): void;
 }
 /** How the content API reaches the comment parts; implemented and registered by `src/parts/wml/comments.mts`. */
 export interface CommentPartsAccess {
@@ -130,11 +138,13 @@ export interface CommentMarker {
 }
 /**
  * Every comment marker under a container (a body, a cell, a paragraph), in document order.
- * Deleted content (`w:del`) is not entered, as the text model does not enter it either.
+ * Deleted content (`w:del`) is not entered, as the text model does not enter it either. A kept
+ * `mc:AlternateContent` at block, row or cell level is read as `mode` says (CR-013 phase 2): a reader's
+ * walk takes its selected branch, an edit's (`removeMarkers`, the ids) every branch.
  */
-export declare function markersOf(container: object): CommentMarker[];
-/** The markers of one paragraph, with their offsets in its text. */
-export declare function markersOfParagraph(element: Element<wml.P>, container: Element[]): CommentMarker[];
+export declare function markersOf(container: object, hidden?: (p: wml.P) => HiddenRuns, mode?: BranchMode): CommentMarker[];
+/** The markers of one paragraph, with their offsets in its text (`Paragraph.text` where `hidden` is its `hiddenRuns()`). */
+export declare function markersOfParagraph(element: Element<wml.P>, container: Element[], hidden?: HiddenRuns): CommentMarker[];
 /** The comment ids under a container, in document order, first occurrence first. */
 export declare function commentIdsOf(container: object): number[];
 /** Removes every marker of a comment from a body, and the reference run when nothing is left in it. */
@@ -143,7 +153,11 @@ export declare function removeMarkers(container: object, id: number): void;
 export declare function nextCommentId(comments: wml.Comments, container: object): number;
 /** An 8 hex digit id, as Word writes `w14:paraId` and `w16cid:durableId` (never 0, high bit clear). */
 export declare function randomHexId(taken: (id: string) => boolean): string;
-/** The `w14:paraId` of a comment's first paragraph: the key of its w15 and w16cid entries. */
+/**
+ * The `w14:paraId` of a comment's first paragraph: the key of its w15 and w16cid entries. A kept
+ * `mc:AlternateContent` before any paragraph is read in its selected branch, as Word reads it (CR-013
+ * phase 3; docx4j's `Trees.lastParaId` looks into the branch the same way).
+ */
 export declare function commentParaId(comment: wml.Comments.Comment): string | undefined;
 /** True when a paragraph id is already used by a comment or by a paragraph of the document. */
 export declare function paraIdTaken(parts: CommentParts, container: object, id: string): boolean;

package/dist/model/content/comments.mjs

@@ -1,5 +1,5 @@
 import { Docx4JException } from '../../opc/exceptions.mjs';
-import { typeNameOf, childrenOf, runItemsOf, itemTextOf, revisionKindOf, RUN_HOLDERS } from './tree.mjs';
+import { typeNameOf, childrenOf, segmentsOf, rowsOf, cellsOf, branchesOf, selectedBranchOf, ALTERNATE_CONTENT } from './tree.mjs';
 /** The style Word gives a comment's paragraphs. */
 export const COMMENT_TEXT_STYLE = 'CommentText';
 /** The character style of the annotation reference run, in the comment and in the body. */
@@ -34,64 +34,51 @@ const COMMENT_RANGE_END = 'org_docx4j_wml.CommentRangeEnd';
 const COMMENT_REFERENCE = 'org_docx4j_wml.R.CommentReference';
 /**
  * Every comment marker under a container (a body, a cell, a paragraph), in document order.
- * Deleted content (`w:del`) is not entered, as the text model does not enter it either.
+ * Deleted content (`w:del`) is not entered, as the text model does not enter it either. A kept
+ * `mc:AlternateContent` at block, row or cell level is read as `mode` says (CR-013 phase 2): a reader's
+ * walk takes its selected branch, an edit's (`removeMarkers`, the ids) every branch.
  */
-export function markersOf(container) {
+export function markersOf(container, hidden, mode = 'read') {
     const out = [];
-    collect(out, container);
+    collect(out, container, undefined, hidden, mode);
     return out;
 }
-/** The markers of one paragraph, with their offsets in its text. */
-export function markersOfParagraph(element, container) {
+/** The markers of one paragraph, with their offsets in its text (`Paragraph.text` where `hidden` is its `hiddenRuns()`). */
+export function markersOfParagraph(element, container, hidden) {
     const out = [];
-    collect(out, undefined, { element, container });
+    collect(out, undefined, { element, container }, hidden === undefined ? undefined : () => hidden);
     return out;
 }
-function collect(out, container, paragraph) {
+/**
+ * The walk behind both. A paragraph's markers are found by the same walk as its text (`segmentsOf`, in
+ * the accepted view: a `w:ins` and a `w:moveTo` hold text and markers, a `w:del` and a `w:moveFrom` hold
+ * neither), so that each offset is one in `Paragraph.text`, hidden runs left out where `hidden` says
+ * which they are, and a kept `mc:AlternateContent`'s selected branch read (CR-012 phase 4).
+ */
+function collect(out, container, paragraph, hidden, mode = 'read') {
     var _a;
     const visitParagraph = (element, blockContainer) => {
-        let pos = 0;
-        const visitRuns = (items) => {
-            var _a, _b, _c;
-            if (!items)
-                return;
-            for (const el of items) {
+        segmentsOf(element.value, {
+            hidden: hidden === null || hidden === void 0 ? void 0 : hidden(element.value),
+            visit: (el, at, owner, run) => {
                 const tn = typeNameOf(el);
-                if (tn === 'org_docx4j_wml.R') {
-                    const content = (_a = el.value.content) !== null && _a !== void 0 ? _a : [];
-                    for (const item of content) {
-                        if (typeNameOf(item) === COMMENT_REFERENCE) {
-                            out.push({
-                                id: item.value.id, kind: 'reference', item, owner: content,
-                                run: el, runOwner: items, paragraph: element, paragraphContainer: blockContainer, offset: pos,
-                            });
-                        }
-                        else
-                            pos += (_c = (_b = itemTextOf(item)) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0;
-                    }
+                if (tn === COMMENT_REFERENCE && run) {
+                    out.push({
+                        id: el.value.id, kind: 'reference', item: el, owner,
+                        run: run.element, runOwner: run.owner, paragraph: element, paragraphContainer: blockContainer, offset: at,
+                    });
                 }
                 else if (tn === COMMENT_RANGE_START || tn === COMMENT_RANGE_END) {
                     out.push({
                         id: el.value.id, kind: tn === COMMENT_RANGE_START ? 'start' : 'end',
-                        item: el, owner: items, paragraph: element, paragraphContainer: blockContainer, offset: pos,
+                        item: el, owner, paragraph: element, paragraphContainer: blockContainer, offset: at,
                     });
                 }
-                else if (tn !== undefined && RUN_HOLDERS.has(tn)) {
-                    visitRuns(runItemsOf(el.value));
-                }
-                else {
-                    // the accepted view, which is what the offsets are in: a w:ins and a w:moveTo hold text
-                    // and markers, a w:del and a w:moveFrom hold neither (CR-002 phase F)
-                    const kind = revisionKindOf(el);
-                    if (kind === 'ins' || kind === 'moveTo')
-                        visitRuns(runItemsOf(el.value));
-                }
-            }
-        };
-        visitRuns(runItemsOf(element.value));
+            },
+        });
     };
     const visitBlocks = (items) => {
-        var _a, _b, _c;
+        var _a, _b;
         for (const el of items) {
             const tn = typeNameOf(el);
             if (tn === 'org_docx4j_wml.P')
@@ -101,10 +88,14 @@ function collect(out, container, paragraph) {
             }
             else if (typeof el.value === 'object' && el.value !== null) {
                 if (tn === 'org_docx4j_wml.Tbl') {
-                    for (const row of (_a = childrenOf(el.value)) !== null && _a !== void 0 ? _a : []) {
-                        for (const cell of (_b = childrenOf(row.value)) !== null && _b !== void 0 ? _b : [])
-                            visitBlocks((_c = childrenOf(cell.value)) !== null && _c !== void 0 ? _c : []);
-                    }
+                    for (const row of rowsOf(el.value, mode))
+                        for (const cell of cellsOf(row.element.value, mode))
+                            visitBlocks((_a = childrenOf(cell.element.value)) !== null && _a !== void 0 ? _a : []);
+                }
+                else if (tn === ALTERNATE_CONTENT) {
+                    const ac = el.value;
+                    for (const branch of mode === 'every' ? branchesOf(ac) : [(_b = selectedBranchOf(ac)) !== null && _b !== void 0 ? _b : []])
+                        visitBlocks(branch);
                 }
                 else {
                     const children = childrenOf(el.value);
@@ -133,7 +124,7 @@ export function commentIdsOf(container) {
 /** Removes every marker of a comment from a body, and the reference run when nothing is left in it. */
 export function removeMarkers(container, id) {
     var _a;
-    for (const marker of markersOf(container)) {
+    for (const marker of markersOf(container, undefined, 'every')) {
         if (marker.id !== id)
             continue;
         const i = marker.owner.indexOf(marker.item);
@@ -157,7 +148,7 @@ export function nextCommentId(comments, container) {
     for (const c of (_a = comments.comment) !== null && _a !== void 0 ? _a : [])
         if (typeof c.id === 'number' && c.id > max)
             max = c.id;
-    for (const m of markersOf(container))
+    for (const m of markersOf(container, undefined, 'every'))
         if (m.id > max)
             max = m.id;
     return max + 1;
@@ -171,13 +162,28 @@ export function randomHexId(taken) {
     }
     throw new Docx4JException('Could not allocate a paragraph id');
 }
-/** The `w14:paraId` of a comment's first paragraph: the key of its w15 and w16cid entries. */
+/**
+ * The `w14:paraId` of a comment's first paragraph: the key of its w15 and w16cid entries. A kept
+ * `mc:AlternateContent` before any paragraph is read in its selected branch, as Word reads it (CR-013
+ * phase 3; docx4j's `Trees.lastParaId` looks into the branch the same way).
+ */
 export function commentParaId(comment) {
-    var _a;
-    for (const el of (_a = comment.content) !== null && _a !== void 0 ? _a : [])
-        if (typeNameOf(el) === 'org_docx4j_wml.P')
-            return el.value.paraId;
-    return undefined;
+    var _a, _b;
+    const first = (items) => {
+        var _a;
+        for (const el of items) {
+            const tn = typeNameOf(el);
+            if (tn === 'org_docx4j_wml.P')
+                return el.value.paraId;
+            if (tn === ALTERNATE_CONTENT) {
+                const found = first((_a = selectedBranchOf(el.value)) !== null && _a !== void 0 ? _a : []);
+                if (found !== null)
+                    return found;
+            }
+        }
+        return null;
+    };
+    return (_b = first(((_a = comment.content) !== null && _a !== void 0 ? _a : []))) !== null && _b !== void 0 ? _b : undefined;
 }
 /** True when a paragraph id is already used by a comment or by a paragraph of the document. */
 export function paraIdTaken(parts, container, id) {
@@ -189,7 +195,7 @@ export function paraIdTaken(parts, container, id) {
         }
     let found = false;
     const visit = (items) => {
-        var _a, _b, _c;
+        var _a;
         for (const el of items) {
             const tn = typeNameOf(el);
             if (tn === 'org_docx4j_wml.P') {
@@ -198,9 +204,13 @@ export function paraIdTaken(parts, container, id) {
             }
             else if (typeof el.value === 'object' && el.value !== null) {
                 if (tn === 'org_docx4j_wml.Tbl') {
-                    for (const row of (_a = childrenOf(el.value)) !== null && _a !== void 0 ? _a : [])
-                        for (const cell of (_b = childrenOf(row.value)) !== null && _b !== void 0 ? _b : [])
-                            visit((_c = childrenOf(cell.value)) !== null && _c !== void 0 ? _c : []);
+                    for (const row of rowsOf(el.value, 'every'))
+                        for (const cell of cellsOf(row.element.value, 'every'))
+                            visit((_a = childrenOf(cell.element.value)) !== null && _a !== void 0 ? _a : []);
+                }
+                else if (tn === ALTERNATE_CONTENT) {
+                    for (const branch of branchesOf(el.value))
+                        visit(branch); // an id is every branch's (CR-013)
                 }
                 else {
                     const children = childrenOf(el.value);

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

@@ -0,0 +1,18 @@
+import { Docx4JException } from '../../opc/exceptions.mjs';
+/**
+ * What Office JS throws where the host refuses an operation it has no answer for: its `code`, so that
+ * add-in code branching on `error.code` behaves the same here (check 19: a hyperlink set on an empty range;
+ * check 52: a range starting or ending inside a table deleted or replaced).
+ */
+export declare class GeneralException extends Docx4JException {
+    readonly code = "GeneralException";
+    constructor(message: string);
+}
+/**
+ * What Office JS throws for an argument it won't take (`InvalidArgument`): its `code`, as `GeneralException` carries its
+ * own (check 56: `insertTable` into a bound block content control).
+ */
+export declare class InvalidArgument extends Docx4JException {
+    readonly code = "InvalidArgument";
+    constructor(message: string);
+}

package/dist/model/content/generalException.mjs

@@ -0,0 +1,24 @@
+import { Docx4JException } from '../../opc/exceptions.mjs';
+/**
+ * What Office JS throws where the host refuses an operation it has no answer for: its `code`, so that
+ * add-in code branching on `error.code` behaves the same here (check 19: a hyperlink set on an empty range;
+ * check 52: a range starting or ending inside a table deleted or replaced).
+ */
+export class GeneralException extends Docx4JException {
+    constructor(message) {
+        super(message);
+        this.code = 'GeneralException';
+        this.name = 'GeneralException';
+    }
+}
+/**
+ * What Office JS throws for an argument it won't take (`InvalidArgument`): its `code`, as `GeneralException` carries its
+ * own (check 56: `insertTable` into a bound block content control).
+ */
+export class InvalidArgument extends Docx4JException {
+    constructor(message) {
+        super(message);
+        this.code = 'InvalidArgument';
+        this.name = 'InvalidArgument';
+    }
+}

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

@@ -7,13 +7,20 @@ export { List, ListItem, ListItemNotFoundError, NumberingFacade, listsOf, listLa
 export { type Author, type CommentContent, type CommentOptions, type CommentEntry, type CommentParts, type CommentPartsAccess, type CommentsExtensible, type CommentMarker, COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
 export { Font, type UnderlineType, type RPrHolder, type FontTracking } from './Font.mjs';
 export { Table, TableRow, TableCell, cellOf } from './Table.mjs';
+export { endsWithParagraph, endWithParagraph } from './tableRules.mjs';
 export { layoutModeOf, textWidthTwips, gridWidthsOf, widthTypeOf, insertGridColumns, deleteGridColumns, gridRangeOf, type TableLayoutMode, type ColumnInsertion } from './tableColumns.mjs';
 export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, addImagePart, writableWidthEmu, type ImageFormat, type ImageInfo, type InlinePictureOptions, type NewPicture, type NewImagePart } from './InlinePicture.mjs';
 export { ContentControl, collectControls, collectRunControls, W14_NS, W15_NS, type ContentControlType, type ContentControlForm, type ContentControlAppearance } from './ContentControl.mjs';
 export { contentOf, isFlatOpc, rewriteRelationshipIds, type OoxmlOptions } from './ooxml.mjs';
-export { type SearchOptions, searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
-export { segmentsOf, runsOf, runItemsOf, selectedBranchOf, isAlternateContent, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf, type TextSegment, type Located, type TextView, type TextViewOptions, type RevisionKind, type RevisionHolder } from './tree.mjs';
-export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext, type TrackedChangeType, type TrackedChangeTarget, type NoteRemovals } from './TrackedChange.mjs';
+export { DEFAULT_ENTRIES, DEFAULT_PLACEHOLDER_ENTRY, DEFAULT_PLACEHOLDER_TEXT, defaultEntryFor, placeholderEntryOf, namePlaceholderEntry, type DefaultEntry, } from './placeholders.mjs';
+export { type SearchOptions, searchPattern, findAll, matchesOf, expandReplacement, officeMatches, type OfficeMatch, type SearchSegment, wildcardMatchesAcross, paragraphMarkPieces, type MarkedSegments, type MarkedMatch, } from './search.mjs';
+export { dropExcluded, officeItems } from './officeText.mjs';
+export { segmentsOf, runsOf, runItemsOf, selectedBranchOf, isAlternateContent, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf, officeItemText, hiddenRunsOf, type TextSegment, type Located, type TextView, type TextViewOptions, type SegmentOptions, type HiddenRuns, type AlternateLocation, type RevisionKind, type RevisionHolder } from './tree.mjs';
+export { mathTextOf, mathLetter } from './mathText.mjs';
+export { textBoxesOf, type AnchoredBox } from './textBoxes.mjs';
+export { ResolvedView } from './ResolvedView.mjs';
+export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext, type TrackedChangeType, type TrackedChangeKind, type TrackedChangeTarget, type NoteRemovals } from './TrackedChange.mjs';
+export type { TrackedChangeFilter, TrackedChangeSelection } from './trackedChangeFilter.mjs';
 export { ChangeTracker, trackerOf, calendarOf, dateOf, wordCalendarOf, revisionDateOf, copyRPr, markDeleted, markInserted, highestAnnotationId, MARKUP_TYPES, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, trackInsertedBlocks, wrapNewRuns, wrapInsertedRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, type ChangeTrackingMode, type TrackingHost, type TrackingScope, type TrackedPart, } from './tracking.mjs';
 export { wml, wmlOne, p, r, t, br, tab, tbl, tr, tc, sdt, sdtPr, nextSdtId, sdtProperty, sdtKindOf, inlinePicture, rPrToElements, rPrFromElements, textOf, walk, walkAll, find, linkParents, applyRunOptions, readRunOptions, UNDERLINE_TO_WML, isElement, typeNameOf, W_NS, type Element, type Wrapper, type WmlOptions, type Raw, type Interpolated, type RunOptions, type RunFormatting, type ParagraphOptions, type TableOptions, type CellOptions, type SdtKind, type SdtForm, type SdtOptions } from '@docx4j/generated-objects-ts/builders/wml';
 export { StylesFacade, type StylePackageLike } from './stylesFacade.mjs';

package/dist/model/content/index.mjs

@@ -9,13 +9,21 @@ export { List, ListItem, ListItemNotFoundError, NumberingFacade, listsOf, listLa
 export { COMMENT_TEXT_STYLE, COMMENT_REFERENCE_STYLE, markersOf, markersOfParagraph, commentIdsOf } from './comments.mjs';
 export { Font } from './Font.mjs';
 export { Table, TableRow, TableCell, cellOf } from './Table.mjs';
+// Word's rule for what a cell holds (CR-002 section 55; docx4j's TableRules)
+export { endsWithParagraph, endWithParagraph } from './tableRules.mjs';
 export { layoutModeOf, textWidthTwips, gridWidthsOf, widthTypeOf, insertGridColumns, deleteGridColumns, gridRangeOf } from './tableColumns.mjs';
 export { InlinePicture, imageInfoOf, naturalSizeEmu, addImage, addImagePart, writableWidthEmu } from './InlinePicture.mjs';
 export { ContentControl, collectControls, collectRunControls, W14_NS, W15_NS } from './ContentControl.mjs';
 export { contentOf, isFlatOpc, rewriteRelationshipIds } from './ooxml.mjs';
-export { searchPattern, findAll, matchesOf, expandReplacement } from './search.mjs';
-export { segmentsOf, runsOf, runItemsOf, selectedBranchOf, isAlternateContent, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf } from './tree.mjs';
+export { DEFAULT_ENTRIES, DEFAULT_PLACEHOLDER_ENTRY, DEFAULT_PLACEHOLDER_TEXT, defaultEntryFor, placeholderEntryOf, namePlaceholderEntry, } from './placeholders.mjs';
+export { searchPattern, findAll, matchesOf, expandReplacement, officeMatches, wildcardMatchesAcross, paragraphMarkPieces, } from './search.mjs';
+// the writers' rule for Office JS's characters, for a caller's own text (CR-002 section 60.9; the editor's UPSTREAM-25)
+export { dropExcluded, officeItems } from './officeText.mjs';
+export { segmentsOf, runsOf, runItemsOf, selectedBranchOf, isAlternateContent, childrenOf, rowsOf, cellsOf, BLOCK_LEVEL_TYPES, SDT_TYPES, runOf, paragraphOf, textOfView, revisionKindOf, officeItemText, hiddenRunsOf } from './tree.mjs';
+export { mathTextOf, mathLetter } from './mathText.mjs';
+export { textBoxesOf } from './textBoxes.mjs';
 // change tracking (CR-002 phase F)
+export { ResolvedView } from './ResolvedView.mjs';
 export { TrackedChange, trackedChangesOfParagraph, trackedChangesOfRow, joinWithNext } from './TrackedChange.mjs';
 export { ChangeTracker, trackerOf, calendarOf, dateOf, wordCalendarOf, revisionDateOf, copyRPr, markDeleted, markInserted, highestAnnotationId, MARKUP_TYPES, toDeletedText, toRestoredText, restoreRPr, restorePPr, trackInsertedParagraph, trackInsertedTable, trackInsertedBlocks, wrapNewRuns, wrapInsertedRuns, paraRPrOf, rowPrOf, pruneParagraphProperties, } from './tracking.mjs';
 // The objects package's builders, re-exported so that one import serves the content API and the tree it works on.

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

@@ -0,0 +1,21 @@
+import type { Element } from '@docx4j/generated-objects-ts/builders/wml';
+/** The two views a paragraph's text is read in. */
+type View = 'accepted' | 'original';
+/** True for an equation at run-holder level: `m:oMath` or `m:oMathPara`. */
+export declare function isMath(el: Element): boolean;
+/**
+ * The text of an equation (`m:oMath`, `m:oMathPara`) in a view: the `m:t` of every math run in document
+ * order, a revision's runs as the view has them, a structure the view hides (its `m:ctrlPr`'s revision) left out
+ * whole, each letter mapped as Word draws it (`mathLetter`).
+ */
+export declare function mathTextOf(math: unknown, view?: View): string;
+/**
+ * A character as Word draws it in a math run with this `m:sty` (`p`, `b`, `i`, `bi`; none is Word's default,
+ * italic) and `m:scr` (`roman`, the default, `script`, `fraktur`, `double-struck`, `sans-serif`,
+ * `monospace`), as check 51 measured: letters, Greek capitals, small letters and nabla alike, in the
+ * alphabet of the style and script; digits upright in the script's family (bold for bold or bold italic,
+ * sans-serif under sans-serif, none of their own in script or fraktur); a character no alphabet has is
+ * itself.
+ */
+export declare function mathLetter(c: string, sty: string | undefined, scr: string | undefined): string;
+export {};

package/dist/model/content/mathText.mjs

@@ -0,0 +1,267 @@
+const MATH_RUN = 'org_docx4j_math.CTR';
+const MATH_TEXT = 'org_docx4j_math.CTText';
+const MATH_RUN_TRACK_CHANGE = 'org_docx4j_wml.CTMathRunTrackChange';
+const CONTROL_PROPERTIES = 'org_docx4j_math.CTCtrlPr';
+/** True for an equation at run-holder level: `m:oMath` or `m:oMathPara`. */
+export function isMath(el) {
+    var _a;
+    const tn = (_a = el.value) === null || _a === void 0 ? void 0 : _a.TYPE_NAME;
+    return tn === 'org_docx4j_math.CTOMath' || tn === 'org_docx4j_math.CTOMathPara';
+}
+/**
+ * The text of an equation (`m:oMath`, `m:oMathPara`) in a view: the `m:t` of every math run in document
+ * order, a revision's runs as the view has them, a structure the view hides (its `m:ctrlPr`'s revision) left out
+ * whole, each letter mapped as Word draws it (`mathLetter`).
+ */
+export function mathTextOf(math, view = 'accepted') {
+    let out = '';
+    const hides = (name) => view === 'accepted' ? name === 'del' || name === 'moveFrom' : name === 'ins' || name === 'moveTo';
+    const runText = (run) => {
+        var _a, _b, _c, _d;
+        const rPr = mathRunProperties(run);
+        const add = (text) => { out += styled(String(text !== null && text !== void 0 ? text : ''), rPr); };
+        for (const o of (_a = run.content) !== null && _a !== void 0 ? _a : []) {
+            const el = o;
+            const v = el.value;
+            if ((v === null || v === void 0 ? void 0 : v.TYPE_NAME) === MATH_RUN_TRACK_CHANGE) {
+                if (hides((_b = el.name) === null || _b === void 0 ? void 0 : _b.localPart))
+                    continue;
+                for (const inner of (_c = v.rest) !== null && _c !== void 0 ? _c : []) {
+                    const iv = inner.value;
+                    if ((iv === null || iv === void 0 ? void 0 : iv.TYPE_NAME) === MATH_TEXT)
+                        add(iv.value);
+                }
+                continue;
+            }
+            if ((v === null || v === void 0 ? void 0 : v.TYPE_NAME) === MATH_TEXT)
+                add(v.value);
+            else if ((v === null || v === void 0 ? void 0 : v.TYPE_NAME) === 'org_docx4j_wml.Text' && ((_d = el.name) === null || _d === void 0 ? void 0 : _d.localPart) === 't')
+                add(v.value);
+        }
+    };
+    const visit = (value, depth) => {
+        if (typeof value !== 'object' || value === null || depth > 64)
+            return;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                visit(v, depth + 1);
+            return;
+        }
+        const named = value;
+        if (named.name !== undefined && 'value' in named) {
+            if (hides(named.name.localPart) && isRevisionValue(named.value))
+                return;
+            visit(named.value, depth + 1);
+            return;
+        }
+        const tn = value.TYPE_NAME;
+        if (tn === MATH_RUN) {
+            runText(value);
+            return;
+        }
+        if (isProperties(tn))
+            return;
+        if (tn !== undefined && tn.startsWith('org_docx4j_math.') && !CONTAINERS.has(tn)) {
+            // a structure the view hides, its own m:ctrlPr holding the revision, goes whole (CR-002 section 62.2, F2)
+            if (hidesStructure(value, hides))
+                return;
+            // a structure: `,`, its arguments joined by `-`, `.` (check 51 case 12)
+            out += ',';
+            argumentsOf(value).forEach((argument, i) => {
+                if (i > 0)
+                    out += '-';
+                visit(argument, depth + 1);
+            });
+            out += '.';
+            return;
+        }
+        for (const key of Object.keys(value)) {
+            if (key === 'PARENT' || key === 'TYPE_NAME')
+                continue;
+            visit(value[key], depth + 1);
+        }
+    };
+    visit(math, 0);
+    return out;
+}
+/**
+ * True when a structure is inserted or deleted, in Word's form a `w:ins` or `w:del` in the `m:ctrlPr` of its own
+ * properties (`m:sSupPr`, `m:fPr`, ...), and the view hides that revision. An argument's own `m:ctrlPr` marks no
+ * structure (CR-002 section 51).
+ */
+function hidesStructure(structure, hides) {
+    var _a;
+    for (const key of Object.keys(structure)) {
+        if (key === 'PARENT' || key === 'TYPE_NAME')
+            continue;
+        const properties = structure[key];
+        if (!((_a = properties === null || properties === void 0 ? void 0 : properties.TYPE_NAME) === null || _a === void 0 ? void 0 : _a.endsWith('Pr')) || !properties.ctrlPr)
+            continue;
+        if ((properties.ctrlPr.del && hides('del')) || (properties.ctrlPr.ins && hides('ins')))
+            return true;
+    }
+    return false;
+}
+/** What holds math elements without being a structure: an equation, a display equation, an argument. */
+const CONTAINERS = new Set(['org_docx4j_math.CTOMath', 'org_docx4j_math.CTOMathPara', 'org_docx4j_math.CTOMathArg']);
+/** A math object's properties (`m:fPr`, `m:radPr`, `m:ctrlPr`, ...): no text. */
+function isProperties(tn) {
+    return tn !== undefined && tn.startsWith('org_docx4j_math.') && (tn.endsWith('Pr') || tn === CONTROL_PROPERTIES);
+}
+/**
+ * A structure's arguments (`m:e`, `m:num`, `m:den`, `m:sub`, `m:sup`, `m:deg`, `m:lim`, `m:fName`) in schema
+ * order, a matrix's rows' arguments in turn, and a radical's degree left out where `m:degHide` hides it.
+ */
+function argumentsOf(structure) {
+    var _a;
+    const out = [];
+    const degHidden = on((_a = structure.radPr) === null || _a === void 0 ? void 0 : _a.degHide);
+    const take = (v) => {
+        var _a;
+        if (typeof v !== 'object' || v === null)
+            return;
+        if (Array.isArray(v)) {
+            for (const o of v)
+                take(o);
+            return;
+        }
+        const named = v;
+        const value = (named.name !== undefined && 'value' in named ? named.value : v);
+        if ((value === null || value === void 0 ? void 0 : value.TYPE_NAME) === 'org_docx4j_math.CTOMathArg') {
+            out.push(value);
+            return;
+        }
+        if (isProperties(value === null || value === void 0 ? void 0 : value.TYPE_NAME))
+            return;
+        if ((_a = value === null || value === void 0 ? void 0 : value.TYPE_NAME) === null || _a === void 0 ? void 0 : _a.startsWith('org_docx4j_math.')) {
+            for (const key of Object.keys(value))
+                if (key !== 'PARENT' && key !== 'TYPE_NAME')
+                    take(value[key]);
+        }
+    };
+    for (const key of Object.keys(structure)) {
+        if (key === 'PARENT' || key === 'TYPE_NAME' || (key === 'deg' && degHidden))
+            continue;
+        take(structure[key]);
+    }
+    return out;
+}
+/** An `m:` on/off property: present and not `0`, `false` or `off`. */
+function on(property) {
+    return property !== undefined && property !== null && property.val !== false && property.val !== 'off' && property.val !== '0' && property.val !== 0;
+}
+/** A `w:ins`, `w:del` or `w:move*` around math runs. */
+function isRevisionValue(value) {
+    const tn = value === null || value === void 0 ? void 0 : value.TYPE_NAME;
+    return tn === 'org_docx4j_wml.RunIns' || tn === 'org_docx4j_wml.RunDel' || tn === 'org_docx4j_wml.RunTrackChange' || tn === MATH_RUN_TRACK_CHANGE;
+}
+function mathRunProperties(run) {
+    var _a, _b, _c;
+    for (const o of (_a = run.content) !== null && _a !== void 0 ? _a : []) {
+        const v = o.value;
+        if ((v === null || v === void 0 ? void 0 : v.TYPE_NAME) === 'org_docx4j_math.CTRPR')
+            return { sty: (_b = v.sty) === null || _b === void 0 ? void 0 : _b.val, scr: (_c = v.scr) === null || _c === void 0 ? void 0 : _c.val, nor: on(v.nor) };
+    }
+    return { nor: false };
+}
+function styled(text, rPr) {
+    if (rPr.nor)
+        return text; // normal text: as the run's w:rPr draws it (check 51 case 11)
+    let out = '';
+    for (const c of text)
+        out += c === '-' ? '\u2212' : mathLetter(c, rPr.sty, rPr.scr); // a minus sign (check 51 case 6)
+    return out;
+}
+// Unicode's Mathematical Alphanumeric Symbols: each alphabet's capital A and small a, its digit zero
+// where it has digits, and its Greek block (capitals, nabla, smalls, then the variants).
+const LATIN = {
+    bold: [0x1D400, 0x1D41A], italic: [0x1D434, 0x1D44E], boldItalic: [0x1D468, 0x1D482],
+    script: [0x1D49C, 0x1D4B6], boldScript: [0x1D4D0, 0x1D4EA], fraktur: [0x1D504, 0x1D51E],
+    doubleStruck: [0x1D538, 0x1D552], boldFraktur: [0x1D56C, 0x1D586], sans: [0x1D5A0, 0x1D5BA],
+    sansBold: [0x1D5D4, 0x1D5EE], sansItalic: [0x1D608, 0x1D622], sansBoldItalic: [0x1D63C, 0x1D656],
+    monospace: [0x1D670, 0x1D68A],
+};
+const DIGITS = { bold: 0x1D7CE, doubleStruck: 0x1D7D8, sans: 0x1D7E2, sansBold: 0x1D7EC, monospace: 0x1D7F6 };
+const GREEK = { bold: 0x1D6A8, italic: 0x1D6E2, boldItalic: 0x1D71C, sansBold: 0x1D756, sansBoldItalic: 0x1D790 };
+/** The letters Unicode left where they were before the block: the BMP's letterlike symbols. */
+const HOLES = {
+    italic: { h: 0x210E },
+    script: { B: 0x212C, E: 0x2130, F: 0x2131, H: 0x210B, I: 0x2110, L: 0x2112, M: 0x2133, R: 0x211B, e: 0x212F, g: 0x210A, o: 0x2134 },
+    fraktur: { C: 0x212D, H: 0x210C, I: 0x2111, R: 0x211C, Z: 0x2128 },
+    doubleStruck: { C: 0x2102, H: 0x210D, N: 0x2115, P: 0x2119, Q: 0x211A, R: 0x211D, Z: 0x2124 },
+};
+/** A Greek letter's place in an alphabet's Greek block of 58. */
+function greekIndex(cp) {
+    if (cp >= 0x391 && cp <= 0x3A1)
+        return cp - 0x391; // Alpha to Rho
+    if (cp === 0x3F4)
+        return 17; // capital theta symbol
+    if (cp >= 0x3A3 && cp <= 0x3A9)
+        return cp - 0x3A3 + 18; // Sigma to Omega
+    if (cp === 0x2207)
+        return 25; // nabla
+    if (cp >= 0x3B1 && cp <= 0x3C9)
+        return cp - 0x3B1 + 26; // alpha to omega, final sigma among them
+    const variants = { 0x2202: 51, 0x3F5: 52, 0x3D1: 53, 0x3F0: 54, 0x3D5: 55, 0x3F1: 56, 0x3D6: 57 };
+    return variants[cp];
+}
+/**
+ * A character as Word draws it in a math run with this `m:sty` (`p`, `b`, `i`, `bi`; none is Word's default,
+ * italic) and `m:scr` (`roman`, the default, `script`, `fraktur`, `double-struck`, `sans-serif`,
+ * `monospace`), as check 51 measured: letters, Greek capitals, small letters and nabla alike, in the
+ * alphabet of the style and script; digits upright in the script's family (bold for bold or bold italic,
+ * sans-serif under sans-serif, none of their own in script or fraktur); a character no alphabet has is
+ * itself.
+ */
+export function mathLetter(c, sty, scr) {
+    var _a;
+    const cp = c.codePointAt(0);
+    const bold = sty === 'b' || sty === 'bi';
+    const italic = sty === undefined || sty === 'i' || sty === 'bi';
+    let alphabet;
+    let digits;
+    switch (scr !== null && scr !== void 0 ? scr : 'roman') {
+        case 'roman':
+            alphabet = bold ? (italic ? 'boldItalic' : 'bold') : italic ? 'italic' : undefined;
+            digits = bold ? 'bold' : undefined;
+            break;
+        case 'script':
+            alphabet = bold ? 'boldScript' : 'script';
+            break;
+        case 'fraktur':
+            alphabet = bold ? 'boldFraktur' : 'fraktur';
+            break;
+        case 'double-struck':
+            alphabet = 'doubleStruck';
+            digits = 'doubleStruck';
+            break;
+        case 'sans-serif':
+            alphabet = bold ? (italic ? 'sansBoldItalic' : 'sansBold') : italic ? 'sansItalic' : 'sans';
+            digits = bold ? 'sansBold' : 'sans';
+            break;
+        case 'monospace':
+            alphabet = 'monospace';
+            digits = 'monospace';
+            break;
+        default: alphabet = undefined;
+    }
+    if (cp >= 0x30 && cp <= 0x39) {
+        const zero = digits === undefined ? undefined : DIGITS[digits];
+        return zero === undefined ? c : String.fromCodePoint(zero + cp - 0x30);
+    }
+    if (alphabet === undefined)
+        return c;
+    const hole = (_a = HOLES[alphabet]) === null || _a === void 0 ? void 0 : _a[c];
+    if (hole !== undefined)
+        return String.fromCodePoint(hole);
+    const latin = LATIN[alphabet];
+    if (cp >= 0x41 && cp <= 0x5A)
+        return String.fromCodePoint(latin[0] + cp - 0x41);
+    if (cp >= 0x61 && cp <= 0x7A)
+        return String.fromCodePoint(latin[1] + cp - 0x61);
+    const g = greekIndex(cp);
+    if (g === undefined)
+        return c;
+    const base = GREEK[alphabet];
+    return base === undefined ? c : String.fromCodePoint(base + g);
+}