@docx4j/core-ts 0.5.0 → 0.7.0

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

@@ -1,6 +1,6 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import type * as mce from '@docx4j/generated-objects-ts/modules/org_docx4j_mce';
-import { isElement, runItemsOf, type Element } from '@docx4j/generated-objects-ts/builders/wml';
+import { isElement, runItemsOf, type McOptions, type Element } from '@docx4j/generated-objects-ts/builders/wml';
 export { isElement, typeNameOf, walk, find, linkParents, textOf, W_NS, type Element } from '@docx4j/generated-objects-ts/builders/wml';
 /** The two views of a tracked document: as it will read once accepted, or as it read before the changes. */
 export type TextView = 'accepted' | 'original';
@@ -8,13 +8,42 @@ export interface TextViewOptions {
     /** 'accepted' (the default: w:ins included, w:del excluded) or 'original' (the other way). */
     view?: TextView;
 }
-/** `segmentsOf`'s options: a view, and whether drawn objects get a segment of their own. */
+/** Whether a run is hidden: its effective `w:vanish` (`hiddenRunsOf` makes one for a paragraph). */
+export type HiddenRuns = (run: wml.R) => boolean;
+/** `segmentsOf`'s options: a view, whether drawn objects get a segment of their own, which runs are hidden. */
 export interface SegmentOptions extends TextViewOptions {
     /**
      * True to list each picture or other drawn object (`OBJECT_ITEMS`) as a segment of no text at its
      * place in the text (`object` set), so that a deletion of a span can find it (CR-002 section 48).
+     * Hidden runs' items are listed with them.
      */
     objects?: boolean;
+    /**
+     * Which runs are hidden. Office JS's text leaves hidden text out, a run's own `w:vanish` or its
+     * styles' (check 48b), so `Paragraph.text` does too (CR-012 phase 4): a hidden run's items take no
+     * offset, and are listed only with the objects, each `object` and `hidden`, so that a span's deletion
+     * takes the hidden text strictly inside it as it takes a picture. Undefined: no run is hidden.
+     */
+    hidden?: HiddenRuns;
+    /**
+     * Called for every element the walk passes that adds no text: each element of a run holder's list
+     * (runs, revision holders, markers, before it is entered) and each item of a run that adds none (a
+     * comment reference, a field character, a drawing, a hidden run's text), with the offset it stands at,
+     * the list holding it and its run. What gives a comment marker or a revision its offset in the same text.
+     */
+    visit?: (item: Element, at: number, owner: Element[], run: {
+        element: Element<wml.R>;
+        owner: Element[];
+    } | undefined) => void;
+    /**
+     * `office` (the default): Office JS's characters (`officeItemText`), a kept `mc:AlternateContent`'s
+     * selected branch read, an equation's drawn text. `textOf`: the characters of the objects package's
+     * `textOf` and docx4j's `TextUtils`, as this function read before CR-012 phase 4 (a break `\n`, the
+     * hyphens U+2011 and U+00AD, a symbol its code point, a note reference nothing), a run-level element
+     * one object, a paragraph-level one and an equation nothing: what a tracked change's `text` is, which
+     * the revisions goldens hold to docx4j's.
+     */
+    characters?: 'office' | 'textOf';
 }
 /**
  * Run content that stands in the text and has no text of its own: a `w:drawing` (a picture, a chart, a
@@ -27,12 +56,13 @@ export declare const OBJECT_ITEMS: ReadonlySet<string>;
 export declare 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 declare function selectedBranchOf(value: mce.AlternateContent | undefined): Element[] | undefined;
+export declare function selectedBranchOf(value: mce.AlternateContent | undefined, options?: McOptions): Element[] | undefined;
 /** True for a kept `mc:AlternateContent`: its element pair, or its value. */
 export declare function isAlternateContent(value: unknown): boolean;
 /**
@@ -87,44 +117,162 @@ export interface TextSegment {
      * next to it goes beside it (`revision.owner`) unless the same author may extend it.
      */
     revision?: RevisionHolder;
+    /**
+     * An item of a hidden run (`SegmentOptions.hidden`): no text, listed with the objects, `object` set too;
+     * a drawing in a hidden run is one (Word's default view doesn't show it: `search`'s `^g` passes it by).
+     */
+    hidden?: boolean;
+    /**
+     * An equation (`m:oMath`, `m:oMathPara`): one segment holding its text as Word draws it
+     * (`mathTextOf`). `item` is the equation and `owner` the list holding it, as `runOwner` is; `run`
+     * is a frozen stand-in, since an equation is in no run. An edit may take it whole, not in part.
+     */
+    math?: boolean;
+    /**
+     * The kept `mc:AlternateContent` whose selected branch holds this item (a run-level element) or its
+     * run (a paragraph-level one), the innermost: an edit lands in that branch, the others kept as they
+     * were read (CR-012 section 12.2).
+     */
+    alternate?: AlternateLocation;
+}
+/** Where a kept `mc:AlternateContent` whose selected branch holds text stands (CR-012 section 12.2). */
+export interface AlternateLocation {
+    /** The element pair. */
+    element: Element;
+    /** The array holding it: a run's content (`run` level) or a run holder's list (`paragraph` level). */
+    owner: Element[];
+    /** Its selected branch's items (`selectedBranchOf`). */
+    branch: Element[];
+    /** `run`: the element is run content and its branch holds run items; `paragraph`: it stands among runs and its branch holds runs. */
+    level: 'run' | 'paragraph';
 }
 /** Types whose value holds runs (directly or through sdtContent); the revision holders are separate. */
 declare const RUN_HOLDERS: Set<string>;
 /** The kind of a run-level revision element, by its name; undefined when it is not one. */
 export declare function revisionKindOf(el: Element): RevisionKind | undefined;
 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 declare function officeItemText(item: Element): string | undefined;
+/**
+ * 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`).
+ */
 declare function itemText(item: Element): string | undefined;
 /**
- * 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 declare function segmentsOf(container: object, options?: SegmentOptions): TextSegment[];
-/** The text of a paragraph or container in one of the two views (`textOf` is the accepted one). */
-export declare function textOfView(container: object, options?: TextViewOptions): string;
-/** The runs of a paragraph, direct and nested in hyperlinks, content controls and insertions, in order. */
+/** What `hiddenRunsOf` asks of a `PropertyResolver`. */
+export interface VanishResolver {
+    isVanishedByStyles(paragraphStyleId: string | undefined, runStyleId: string | undefined): boolean;
+}
+/**
+ * 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 declare function hiddenRunsOf(resolver: VanishResolver | undefined, p: wml.P): HiddenRuns;
+/**
+ * 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 declare function inShowingPlaceholder(run: object): boolean;
+/** The text of a paragraph or container in one of the two views, in Office JS's characters (`segmentsOf`). */
+export declare function textOfView(container: object, options?: SegmentOptions): string;
+/**
+ * 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 declare function runsOf(container: object, options?: TextViewOptions): Element<wml.R>[];
+/** The TYPE_NAMEs of a kept `mc:AlternateContent`'s branches, whose items are their `any`. */
+export declare const BRANCH_TYPES: ReadonlySet<string>;
+/**
+ * How a walk takes a kept `mc:AlternateContent` among blocks, rows or cells (CR-013): `'read'`, a reader's,
+ * its selected branch (`selectedBranchOf`), as Word reads it; `'every'`, a mutator's, every branch, Choices
+ * first (phase 3). With no mode the element is stepped over, as every walk did before CR-013 phase 2.
+ */
+export type BranchMode = 'read' | 'every';
 /**
  * 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 declare function childrenOf(value: object, mode?: 'read'): Element[] | undefined;
+/** Every branch of a kept `mc:AlternateContent`, the Choices in order, then the Fallback. */
+export declare function branchesOf(value: mce.AlternateContent): Element[][];
+/**
+ * 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 declare function writingEveryBranch<T>(edit: () => T): T;
+/**
+ * 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 declare function childrenOf(value: object): Element[] | undefined;
+export declare function assertOutsideBranch(value: object | undefined, className: string, what?: string): void;
+/**
+ * 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 declare function inBranch(value: object | undefined): boolean;
+/**
+ * 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 declare function inUnreadBranch(value: object | undefined): boolean;
+/**
+ * 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 declare function branchListsOf(value: mce.AlternateContent, mode: BranchMode): Element[][];
 /** An element with the array that holds it: what a view needs to edit it in place. */
 export interface Located<T = unknown> {
     element: Element<T>;
     container: Element[];
 }
-/** The rows of a table, in order, descending into row-level content controls (an OpenDoPE repeat). */
-export declare function rowsOf(tbl: object): Located<wml.Tr>[];
-/** The cells of a row, in order, descending into cell-level content controls. */
-export declare function cellsOf(tr: object): Located<wml.Tc>[];
+/**
+ * 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 declare function rowsOf(tbl: object, mode?: BranchMode): Located<wml.Tr>[];
+/** The cells of a row, in order, descending into cell-level content controls, and with a mode into a cell-level `mc:AlternateContent`. */
+export declare function cellsOf(tr: object, mode?: BranchMode): Located<wml.Tc>[];
+/**
+ * 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 declare function cellLayoutsOf(tr: object): Located<wml.Tc>[][];
 /** Content controls: `w:sdt` at block, row, cell and run level, by TYPE_NAME. */
 export declare const SDT_TYPES: Set<string>;
 /** True for what a body or cell may hold directly (the Body content union), by TYPE_NAME. */