@docx4j/core-ts 0.5.0 → 0.6.0

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

@@ -2,11 +2,11 @@ import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import type { PropertyResolver } from '../properties/PropertyResolver.mjs';
 import type { XmlPart } from '../../parts/XmlPart.mjs';
 import type { OpcPackage } from '../../packages/OpcPackage.mjs';
-import { type Element, type TextViewOptions } from './tree.mjs';
+import { type Element, type TextViewOptions, type HiddenRuns, type BranchMode } from './tree.mjs';
 import { Paragraph } from './Paragraph.mjs';
 import { Range } from './Range.mjs';
 import { Table, type TableRow, type TableCell } from './Table.mjs';
-import { ContentControl, type ContentControlType } from './ContentControl.mjs';
+import { ContentControl, type BlockRefusal, type ContentControlType, type ContentControlOptions } from './ContentControl.mjs';
 import { InlinePicture, type InlinePictureOptions } from './InlinePicture.mjs';
 import { type SearchOptions } from './search.mjs';
 import type { Bound } from './binder.mjs';
@@ -18,6 +18,7 @@ export type SelectResult = Paragraph | Table | TableRow | TableCell | ContentCon
 import type { Comment } from './Comment.mjs';
 import { type ChangeTracker } from './tracking.mjs';
 import { type TrackedChange } from './TrackedChange.mjs';
+import { type TrackedChangeSelection } from './trackedChangeFilter.mjs';
 import { type List, type ListLabel } from './List.mjs';
 /** Where a paragraph or table is, for agents and across tool calls (CR-002 section 3.3). */
 export type Address = string | {
@@ -34,7 +35,16 @@ export interface OutlineParagraph {
     address: string;
     paraId?: string;
     style: string;
+    /** The text model's text of the paragraph (CR-012 D3): hidden text left out, a deleted mark joined, in the options' view. */
     text: string;
+    /** True for a paragraph in a text box, listed after its anchor at a `textbox:` address (CR-012 D3, D4). */
+    textbox?: true;
+    /**
+     * The addresses of the paragraphs the view joins to this one, in order (a deleted mark in the `accepted`
+     * view, an inserted one in `original`): their text is in `text`, and they have no entry of their own
+     * (CR-012 section 17.13).
+     */
+    joined?: string[];
 }
 export interface OutlineTable {
     address: string;
@@ -45,6 +55,10 @@ export interface Outline {
     paragraphs: OutlineParagraph[];
     tables: OutlineTable[];
 }
+/** Which of a body's blocks `Body.outline` reads (CR-012 section 17.13): its top-level blocks, by index or view. */
+export interface OutlineSelection {
+    blocks: readonly (number | Paragraph | BlockElement)[];
+}
 /**
  * A subset of Office JS `Word.Body` over any container with block-level content: the main
  * document's body, a header, a footer, a footnote, a cell or a content control. A view: the
@@ -77,10 +91,22 @@ export declare class Body {
      * which does it) first - or read direct formatting with `{ direct: true }`.
      */
     get propertyResolver(): PropertyResolver;
+    /** Which of a paragraph's runs are hidden: a run's own `w:vanish`, else its styles' (`hiddenRunsOf`; CR-012 phase 4). */
+    hiddenRuns(p: wml.P): HiddenRuns;
     /** The live content array (docx4j getContent()); block-level elements only, sectPr excluded. */
     get content(): Element[];
-    /** Every paragraph in document order, descending into tables and content controls. */
+    /**
+     * Every paragraph in document order, descending into tables and content controls, and into the
+     * selected branch of a kept `mc:AlternateContent` at block, row and cell level, as Word reads it
+     * (CR-013 phase 2). A paragraph in a branch is read-only (D4).
+     */
     get paragraphs(): Paragraph[];
+    /**
+     * The paragraphs a walk in this mode takes: a reader's, `paragraphs`; a bulk edit's (`'every'`), every
+     * branch's too, the selected branch's where a reader sees them and each other branch's after them,
+     * where the element stands (CR-013 phase 3).
+     */
+    private paragraphsIn;
     /**
      * 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
@@ -109,10 +135,25 @@ export declare class Body {
      * 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). */
+    /**
+     * The tables directly in this body, as Office JS reports them (nested tables are a cell's), a table in
+     * the selected branch of a kept block-level `mc:AlternateContent` among them (CR-013 phase 2).
+     */
     get tables(): Table[];
     /** Every content control in this body, in document order, nested ones included. */
     get contentControls(): ContentControl[];
+    /**
+     * Office JS `getContentControls` (WordApi 1.5): the content controls `contentControls` lists, those of `options.types`
+     * where given. Word's `contentControls` lists rich-text controls only; this package's lists every kind, a recorded
+     * departure (CR-002 section 60 G1, check 55b), so this is how add-in code that asks for plain-text controls finds them.
+     */
+    getContentControls(options?: ContentControlOptions): ContentControl[];
+    /**
+     * The content controls a walk in this mode takes: a reader's, `contentControls`; the binding passes'
+     * (`'every'`), every branch's of a kept `mc:AlternateContent` too, each other branch's where the element
+     * stands (CR-013 phase 3). An extension.
+     */
+    contentControlsIn(mode: BranchMode): ContentControl[];
     /** Every inline picture in this body, in document order (Office JS Body.inlinePictures). */
     get inlinePictures(): InlinePicture[];
     /**
@@ -139,15 +180,29 @@ export declare class Body {
     }, prefix?: string): Body;
     /** The view of a `w:p` somewhere in this body's tree; its container comes from PARENT. */
     paragraphFor(p: wml.P): Paragraph | undefined;
-    /** The text, a paragraph per line. */
+    /**
+     * The text as Office JS's `body.text` gives it in Word's default view (CR-012 phase 4; checks 30, 31, 48
+     * and 51): each paragraph's text (`Paragraph.text`) followed by its mark, `\r`, the last paragraph's left
+     * out; in a table a row's cells a `\t` apart, each cell's paragraphs a mark apart (its last mark not
+     * written), and the row ended by `\r\n`. Text boxes are not the body's (check 42).
+     */
     get text(): string;
     /**
      * The text in one of the two views (extension; `text` is the accepted one).
      * `{ view: 'original' }` reads the document as it was before the tracked changes.
      */
     getText(options?: TextViewOptions): string;
+    /**
+     * The body's range (Office JS `Body.getRange`; CR-014 phase 1): 'Whole' from its first paragraph's start to
+     * its last one's end, with that paragraph's mark (check 51: a cell's `CELLP1\rCELLP2\rCELLP3\t`, a note's
+     * `… NOTEP2\r`), 'Content' the same without the mark, 'Start' and 'End' collapsed at its ends.
+     */
+    getRange(location?: 'Whole' | 'Start' | 'End' | 'Content'): Range;
+    private textIn;
     /** The package's change tracker while `changeTrackingMode` is on; undefined when it is off (CR-002 phase F). */
     get changeTracker(): ChangeTracker | undefined;
+    /** Refuses a write to a body in a branch of a kept `mc:AlternateContent`: a cell or a control a reader found there (CR-013 D4). */
+    private assertWritable;
     insertParagraph(text: string, location: 'Start' | 'End'): Paragraph;
     /** Text at the start of the first paragraph, the end of the last, or replacing everything with one paragraph. */
     insertText(text: string, location: 'Start' | 'End' | 'Replace'): Range;
@@ -168,7 +223,7 @@ export declare class Body {
      * before or after a target paragraph, element or address. Links PARENT. Rejects anything the
      * body cannot hold, naming what was passed. Returns the view of the first inserted element.
      */
-    insertElement(element: Element | Element[], location: 'Start' | 'End' | 'Before' | 'After', target?: Paragraph | BlockElement | Address): Paragraph | BlockElement;
+    insertElement(element: Element | Element[], location: 'Start' | 'End' | 'Before' | 'After', target?: Paragraph | BlockElement | Address, refusal?: BlockRefusal, replacing?: Element): Paragraph | BlockElement;
     /** Inserts a WML fragment (one or more w:p / w:tbl / ... as inside document.xml); the standard prefixes are declared for it. */
     insertXml(xml: string, location: 'Start' | 'End' | 'Before' | 'After', target?: Paragraph | BlockElement | Address): Promise<(Paragraph | BlockElement)[]>;
     /**
@@ -179,6 +234,13 @@ export declare class Body {
      * what was inserted, as `insertXml` does, since a package may bring several blocks.
      */
     insertOoxml(ooxml: string, location: 'Start' | 'End' | 'Replace' | 'Before' | 'After', target?: Paragraph | BlockElement | Address): Promise<(Paragraph | BlockElement)[]>;
+    /**
+     * After an insertion into a cell: the cell still ends with a paragraph, as Word reads it (CR-002 section 55). Where
+     * a table went in after the paragraph the cell ended with, in the cell's own content, Word's form (check 52, cases 86
+     * and 87, `keepCellMarkLast`): that paragraph split at its end, the cell's mark staying last after the table, the
+     * first half's mark the inserted one under tracking. Anywhere else docx4j's repair, an empty paragraph after any wrapper.
+     */
+    private keepCellEnd;
     /** The package's DOM preprocessor (the MCE one), for fragments and incoming packages. */
     private preprocessor;
     private insertContent;
@@ -194,40 +256,89 @@ export declare class Body {
      * Removes everything (section properties stay). While the package tracks changes, every
      * paragraph is marked deleted and every row's `w:trPr` takes a `w:del` instead. Removed outright,
      * the relationships the content held (its pictures' images) are settled on save (CR-002 section 47).
+     * In a table cell the paragraph the cell ends with stays, emptied, its properties kept, and tracked
+     * only its text is deleted, as Word keeps a cell's last paragraph (check 52, cases 92 and 93; CR-002 section 55.6).
      */
     clear(): void;
+    /**
+     * `clear()`; with `keepCellEnd` false a cell's last paragraph goes as well, its mark marked deleted under
+     * tracking, for a caller that puts its own paragraph in next (`insertText(…, 'Replace')`, `TableCell.value`).
+     * @internal
+     */
+    clearContent(keepCellEnd: boolean): void;
+    /**
+     * Marks everything in this body deleted in place, in every branch of a kept `mc:AlternateContent`: each
+     * paragraph's text and mark, each row of its tables (a tracked row or table deletion's cells; CR-013
+     * phase 3). Internal: what `Table.delete` and `deleteRows` write while changes are tracked.
+     */
+    markContentDeleted(tracker: ChangeTracker): void;
     /**
      * Every tracked change in this body, in document order. Touching insertions or deletions by one
      * author - a deleted paragraph's text and mark, a deletion across a mark - are one change, as
      * Office JS lists them (CR-002 section 29, checks 22 and 23).
+     *
+     * In a kept `mc:AlternateContent` at block, paragraph, row or cell level the selected branch's changes
+     * are listed, as Word reads it (CR-013 phase 2); each other branch's are their twins, paired by kind and
+     * position, which resolving a listed change resolves too (phase 3, docx4j's twins).
      */
     getTrackedChanges(): TrackedChange[];
+    /** The listing in either mode (`Listing`): resolve-all's puts every other branch's changes after the story's. */
+    private trackedChanges;
     /**
      * Accepts every tracked change, last first so that a paragraph join never disturbs one still
      * to do (docx4j `AcceptTrackedChanges` is the reference). Returns how many were listed.
+     *
+     * With a filter (an extension, CR-011), only the single changes it matches are accepted, so a group
+     * can be resolved in part, and what no change owns is left alone; the count is of the listed changes
+     * with a matching piece (docx4j's `TrackedChanges.acceptAll(pkg, filter)`).
      */
-    acceptAll(): number;
-    /** Rejects every tracked change, last first. Returns how many were listed. */
-    rejectAll(): number;
+    acceptAll(filter?: TrackedChangeSelection): number;
+    /** Rejects every tracked change, last first, as `acceptAll` accepts them. Returns how many were listed. */
+    rejectAll(filter?: TrackedChangeSelection): number;
     /**
      * Resolving one change can leave another to be listed afresh: accepting a move carries a deletion
      * nested in its moved text out of it, and resolving a broken move dissolves the rest of it into a
      * new `w:ins` or `w:del` (CR-002 section 29), so the list read first goes stale. The list is read
-     * again after each pass until nothing is left, as "all" promises (found by the editor's C5); a
-     * pass that resolves nothing ends it.
+     * again after each pass until nothing is left, as "all" promises (found by the editor's C5); as
+     * docx4j's `TrackedChanges.resolveAll` does it (CR-011): a change whose pieces all match is resolved
+     * whole, one with some matching its matching pieces alone, for up to 20 passes, and two passes in a
+     * row that leave as many matching changes as the one before end it. Then, with no filter, what is
+     * never listed is swept.
      */
     private resolveAll;
-    /** Every `w:tr` in this body's tables, in document order (rows of nested tables included). */
+    /** Every `w:tr` in this body's tables, in document order (rows of nested tables included), in every branch (CR-013 phase 3). */
     private rowElements;
     /** The part's XML (extension; Office JS getOoxml wraps it in a package). */
     getXml(): Promise<string>;
-    /** The element at an address: 'body/3' (fourth block), 'body/3/1/0/2' (table row 1, cell 0, block 2), a paraId, or a text match. */
+    /**
+     * The element at an address: 'body/3' (fourth block), 'body/3/1/0/2' (table row 1, cell 0, block 2),
+     * 'body/3/textbox:0/1' (the second block of the first text box body/3 anchors, CR-012 D4), a paraId, or a
+     * text match. Undefined, never an error, where the address names nothing.
+     */
     elementAt(address: Address): BlockElement | undefined;
     paragraphAt(address: Address): Paragraph | undefined;
     /** The ordinal address of a paragraph or element in this body, from PARENT links; undefined when it is not here. */
     addressOf(target: Paragraph | BlockElement): string | undefined;
-    /** What an agent asks for first: every paragraph and table with its address, style and text. */
-    outline(): Outline;
+    /**
+     * What an agent asks for first: every paragraph and table with its address, style and text, read by the
+     * text model (CR-012 D3; `Texts.of`'s options, `TextOptionsInit`): each paragraph's text is the model's
+     * (hidden text left out, a paragraph whose mark the view deletes joined to the next, in the view asked
+     * for), and each text box's paragraphs follow their anchoring paragraph, or the table it is in (REQ-518),
+     * at `textbox:` addresses (`body/3/textbox:0/1`), flagged `textbox`. A cell's paragraphs and tables follow
+     * their table's entry.
+     * Async since phase 4, as the model's reading is; calls under one `TextContext` (`Texts.contextOf`) read
+     * the package's stories once. The package is not changed (REQ-204).
+     *
+     * With `select`, only some of this body's top-level blocks are read (CR-012 section 17.13): their entries
+     * are those the whole outline gives them under the same context and options, in document order. A
+     * paragraph whose text a paragraph before it holds (`joined`) gives none; a block that starts inside a
+     * field open before it (a table of contents left out, D12) is read inside it. Under a context, the first
+     * such call over a body walks its blocks' field characters once; each block after that costs its own
+     * reading. A context is a snapshot: after an edit, make another.
+     */
+    outline(options?: object, context?: object, select?: OutlineSelection): Promise<Outline>;
+    /** The index in `content` of one of this body's top-level blocks. */
+    private blockIndexOf;
     /** docx4j MainDocumentPart.addParagraphOfText. */
     addParagraphOfText(text: string): wml.P;
     /** docx4j MainDocumentPart.addStyledParagraphOfText. */
@@ -241,9 +352,11 @@ export declare class Body {
     private ownerOf;
     private containerOf;
     private pathOf;
-    /** Gives a new paragraph a w14:paraId when the document already uses them. */
-    private assignParaId;
-    private usesParaIds;
+    /**
+     * Gives a new paragraph a w14:paraId when the document already uses them, free in every branch (CR-013 phase 3).
+     * @internal a paragraph split (CR-014 phase 2) gives its new first half one.
+     */
+    assignParaId(p: wml.P): void;
     /**
      * The comments anchored in this body, in document order, with replies nested under their
      * parent (only top-level comments are in the array). Asynchronous because it unmarshals the
@@ -258,13 +371,22 @@ export declare class Body {
     insertContentControl(kind?: ContentControlType): ContentControl;
 }
 /**
- * A story's tracked changes resolved (`Body.acceptAll` or `rejectAll`), then those of each text box in
- * it - a `w:txbxContent`, in a DrawingML shape or a VML one - which Word counts as a story of its own
- * (CR-002 section 49). A text box inside a text box is reached through its own story. Returns how many
- * changes were listed.
+ * A story's tracked changes resolved (`Body.acceptAll` or `rejectAll`, with the filter if one is given),
+ * then those of each text box in it - a `w:txbxContent`, in a DrawingML shape or a VML one - which Word
+ * counts as a story of its own (CR-002 section 49). A text box inside a text box is reached through its
+ * own story. Returns how many changes were listed (with a filter, how many had a matching piece).
  *
  * In a kept `mc:AlternateContent` the text box of every branch is resolved, so that each says the same
  * afterwards (docx4j's `McMode.ALL`), and the changes are counted in the selected branch alone, so a
  * text box held in both counts once, as a resolved load's does (CR-010 phase 3).
  */
-export declare function resolveStory(body: Body, what: 'accept' | 'reject'): number;
+export declare function resolveStory(body: Body, what: 'accept' | 'reject', filter?: TrackedChangeSelection): number;
+/**
+ * A story's tracked changes (`Body.getTrackedChanges`), then each text box's in it, as `resolveStory`
+ * resolves them: docx4j's order (its CR-043 `Lister`, CR-011). In a kept `mc:AlternateContent` the
+ * selected branch's text boxes alone are listed, so a text box held in both branches is listed once;
+ * each other branch's box at the same place is its twin, whose changes are paired with the listed ones
+ * by kind and position and resolved with them, as docx4j resolves a text box's `mc:Fallback` twin
+ * (`pairTwins`; CR-013 phase 3).
+ */
+export declare function trackedChangesOfStory(body: Body): TrackedChange[];