@docx4j/core-ts 0.4.0 → 0.6.0

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

@@ -1,12 +1,13 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import type { CellContext } from '../properties/table.mjs';
-import { type Element, W_NS, type TextSegment, type TextViewOptions } from './tree.mjs';
+import { type Element, W_NS, type HiddenRuns, type SpanEdges, type SegmentOptions, type TextSegment, type TextViewOptions } from './tree.mjs';
 import { Font, type FontTracking } from './Font.mjs';
 import { Range } from './Range.mjs';
 import { type SearchOptions } from './search.mjs';
 import type { Body, BlockElement } from './Body.mjs';
 import { type TableCell } from './Table.mjs';
-import { ContentControl, type ContentControlType } from './ContentControl.mjs';
+import { ContentControl, type ContentControlType, type ContentControlOptions } from './ContentControl.mjs';
+import { type LineBreaks } from './officeText.mjs';
 import { InlinePicture, type InlinePictureOptions } from './InlinePicture.mjs';
 import { type CommentContent, type CommentOptions } from './comments.mjs';
 import type { Comment } from './Comment.mjs';
@@ -64,8 +65,23 @@ export declare class Paragraph {
     parentBody: Body);
     /** The paragraph value (docx4j: the P). */
     get p(): wml.P;
+    /** @internal A view of another paragraph of this one's body, for a `Range` across paragraphs (CR-014). */
+    viewOf(element: Element<wml.P>, container: Element[]): Paragraph;
+    /**
+     * @internal A range from this paragraph's start to the end of `last`, a later paragraph of the same story, with
+     * `last`'s mark where `mark` is set, or `endMark` in its place (CR-014 phase 1).
+     */
+    rangeTo(last: Paragraph, mark: boolean, endMark?: string): Range;
+    /** How many tables deep the paragraph is: 0 outside a table, 1 in a cell, 2 in a nested table's (Office JS `tableNestingLevel`). */
+    get tableNestingLevel(): number;
     get index(): number;
-    /** The paragraph's text: runs joined, tabs as \t, breaks as \n; deleted text excluded. */
+    /**
+     * The paragraph's text as Office JS gives it in Word's default view (CR-012 phase 4, section 6.2):
+     * the accepted text, hidden text left out, in Word's characters (check 48: a note reference U+0002,
+     * a line break U+000B, a page break U+000C, a column break U+000E, a `w:cr` U+000D, the hyphens
+     * U+001E and U+001F, a symbol `(`, an equation as Word draws it). A kept `mc:AlternateContent`
+     * reads as its selected branch (check 49). Every offset a `Range` or `search` takes counts in it.
+     */
     get text(): string;
     /** Replaces the content with one run of the text, keeping the first run's formatting. */
     set text(value: string);
@@ -145,11 +161,12 @@ export declare class Paragraph {
     get outlineLevel(): number;
     set outlineLevel(level: number);
     /**
-     * The runs' formatting: reads the first run's *effective* properties, writes direct
-     * formatting to all (extension: `Font` is over runs, not the paragraph mark).
+     * The runs' formatting: reads the *effective* properties of the runs holding the paragraph's text, `null` (or `''`,
+     * `Mixed`) where they differ, and the mark's where it has no text, as Office JS reads them (CR-002 section 59); writes
+     * direct formatting to every run (extension: `Font` is over runs, not the paragraph mark).
      */
     get font(): Font;
-    /** `font`, with `{ direct: true }` for the direct formatting of the first run (extension). */
+    /** `font`, with `{ direct: true }` for the runs' direct formatting (extension). */
     getFont(options?: FormattingOptions): Font;
     /** w14:paraId, the stable address Word gives paragraphs. */
     get paraId(): string | undefined;
@@ -160,12 +177,29 @@ export declare class Paragraph {
     get parentTableCell(): TableCell | undefined;
     /** The run-level content controls in this paragraph, in order, nested ones included. */
     get contentControls(): ContentControl[];
-    /** The inline pictures in this paragraph, in order (Office JS Paragraph.inlinePictures). */
+    /**
+     * 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 inline pictures in this paragraph, in order (Office JS Paragraph.inlinePictures): each
+     * `w:drawing` whose `wp:inline` holds a `pic:pic`, in a run or in the selected branch of a kept
+     * `mc:AlternateContent` (`picturesIn`). An inline chart, text box or group is not one (CR-010
+     * section 12.6).
+     */
     get inlinePictures(): InlinePicture[];
     /** Text inserted at the start, the end, or replacing the whole paragraph's text. */
     insertText(text: string, location: 'Start' | 'End' | 'Replace'): Range;
-    /** A new paragraph of the text before or after this one, with this paragraph's properties (as Word). */
+    /**
+     * A new paragraph of the text before or after this one, with this paragraph's properties (as Word). Beside the only
+     * paragraph of a block control showing its placeholder it goes outside the control, as Word's went, and the control
+     * stays at block level (CR-002 section 63, D6 (b); check 63 cases 10, 11, 36 and 37).
+     */
     insertParagraph(text: string, location: 'Before' | 'After'): Paragraph;
+    /** The block-level control holding this paragraph directly while it shows its placeholder (CR-002 section 63). */
+    private get placeholderControl();
     insertBreak(type: 'Page' | 'Line', location: 'Before' | 'After' | 'Start' | 'End'): void;
     /**
      * Adds the image as a part of this paragraph's part, with a relationship, and shows it at the
@@ -198,22 +232,52 @@ export declare class Paragraph {
     replaceText(find: string, replace: string, options?: SearchOptions): number;
     /** The tracked changes in this paragraph, in document order (CR-002 phase F). */
     getTrackedChanges(): TrackedChange[];
+    /**
+     * The paragraph's range: 'Whole' and 'Content' hold its whole content, the pictures at its start and
+     * end among them, so deleting it deletes them (CR-002 section 48); 'Start' and 'End' are collapsed.
+     * 'Whole' holds the paragraph's mark too, so its `text` ends with `markText`, as Office JS's does
+     * (check 48); 'Content' ends with the paragraph's text.
+     */
     getRange(location?: 'Whole' | 'Start' | 'End' | 'Content'): Range;
+    /**
+     * The character Office JS gives for this paragraph's mark at the end of its 'Whole' range (check 48):
+     * `\t` for the last paragraph of a table cell, the cell's end; nothing for a mark tracked as deleted, which
+     * Word's default view doesn't show (CR-012 section 19, check 58); and `\r` for any other.
+     */
+    get markText(): string;
     /**
      * Removes the paragraph from its container. While the package tracks changes, the content
      * becomes a `w:del` and the mark is marked deleted (`w:pPr/w:rPr/w:del`) instead, unless the
      * whole paragraph was this author's own insertion, which Word simply takes back.
+     * The paragraph a table cell ends with, as Word reads it, stays where removing it would leave the
+     * cell without one, emptied, its properties kept; tracked, its mark is never marked deleted, as Word
+     * keeps a cell's last paragraph (check 52, cases 88 to 91; CR-002 section 55.6).
      */
     delete(): void;
+    /**
+     * `delete()`; with `keepCellEnd` false a cell's last paragraph goes as any other, for `Body.clearContent`'s
+     * callers, which put their own paragraph in next.
+     * @internal
+     */
+    remove(keepCellEnd: boolean): void;
+    /** Whether the cell this paragraph was in ends with a paragraph without it, as Word reads it (CR-002 section 55). */
+    private cellStillEnds;
     private trackedDelete;
     /**
      * The paragraph's content and its mark marked deleted, the paragraph element itself kept:
      * what the cells of a deleted table row need (a `w:tc` must keep a block-level child, and Word
      * writes `w:del` around every run and `w:pPr/w:rPr/w:del` on every mark inside a deleted row).
      * The same primitives `delete()` uses, without its "take back my own insertion" step.
-     * Does nothing when the mark is already deleted.
+     * A mark already deleted is left as it is, and the text is deleted still: a paragraph another author's
+     * deletion ended keeps text a range's deletion across it must take (CR-014 phase 2).
      */
     markDeletedInPlace(tracker: ChangeTracker): void;
+    /**
+     * Queues the relationships that content removed outright referenced (a picture's image, a link's
+     * target), to be settled when the package is saved: each goes then if nothing references it, and
+     * its part with it when nothing else targets that (CR-002 sections 47 and 48).
+     */
+    releaseRelationships(removed: unknown): void;
     /** The paragraph as XML (extension; Office JS getOoxml wraps it in a package). */
     getXml(): Promise<string>;
     /** docx4j: the P's content list. */
@@ -253,15 +317,104 @@ export declare class Paragraph {
     get changeTracker(): ChangeTracker | undefined;
     /** What `Font` needs to write `w:rPrChange`: the tracker, and the runs that are our own insertion (`Range` shares it). */
     fontTracking(): FontTracking | undefined;
-    /** The text segments (w:t, w:tab, ...) with their offsets. */
-    segments(options?: TextViewOptions): TextSegment[];
+    /**
+     * The text segments (w:t, w:tab, ...) with their offsets in `text`; `{ objects: true }` adds the
+     * pictures and the hidden runs' items.
+     */
+    segments(options?: SegmentOptions): TextSegment[];
+    /**
+     * True for a paragraph in a text box (`w:txbxContent`), at a `textbox:` address (CR-012 D4). Such a view
+     * reads as any paragraph does and is read-only (D5): every write throws `NotSupportedError`.
+     */
+    get inTextBox(): boolean;
+    /**
+     * Refuses a write to a paragraph in a text box (CR-012 D5): a box is in each branch of its
+     * `mc:AlternateContent`, `wps:txbx` in the Choice and `v:textbox` in the Fallback, and nothing maps the
+     * one's paragraphs to the other's, so an edit could not reach every branch as CR-010's D2 has mutators do.
+     * And a write to a paragraph in a branch of a kept `mc:AlternateContent` at block, row or cell level
+     * (CR-013 D4), for the same reason. Internal: the content API's mutators call it first.
+     */
+    assertWritable(): void;
+    /**
+     * True for a paragraph in the selected branch of a kept `mc:AlternateContent` at block, row or cell
+     * level, which readers see as Word does (CR-013 phase 2). Such a view is read-only (D4).
+     */
+    get inBranch(): boolean;
+    /** Which of this paragraph's runs are hidden: a run's own `w:vanish`, else its styles' (CR-012 phase 4). */
+    hiddenRuns(): HiddenRuns;
     /**
      * Replaces the text in [start, end) with `text` and returns the range of the inserted text.
      * Runs are edited in place: a w:t loses or gains characters, a tab or break inside the range
      * is removed, a run left empty is removed. Text is inserted into the w:t at `start`,
      * else into a new run with the formatting of the nearest run.
+     *
+     * The pictures in the span go with its text: those strictly inside it, and those at an edge `edges`
+     * says the span holds (`WHOLE` for a paragraph's whole content), so a span of no text can still
+     * delete a picture (CR-002 section 48).
      */
-    splice(start: number, end: number, text: string, prefer?: 'before' | 'after'): Range;
+    splice(start: number, end: number, text: string, prefer?: 'before' | 'after', edges?: SpanEdges, lineBreaks?: LineBreaks): Range;
+    /**
+     * The controls bound by `w:dataBinding` that [start, end) is in: those holding the paragraph, and the run-level ones
+     * holding text there.
+     */
+    private boundControlsAt;
+    /**
+     * @internal Text written at the paragraph's End by Office JS's routes to it: `insertText('End')`, its End range at any
+     * location, its Content range's End and After, and so a body's or a cell's `insertText('End')` (CR-002 sections 63.24
+     * to 63.27; checks 69 and 70). As Word writes it (D12): after everything the paragraph holds, into none of it - a
+     * run-level control, a link, a revision, a field, a bookmark's or a comment's markers, a text box - in a run of its
+     * own, or the last run extended. The text takes the last item's run properties where that item is a run holding text,
+     * so after a hidden run it is hidden and its range reads nothing (D13); otherwise it has none, and with `plain` (the End
+     * range's After, D14) none either. Word's proofing marks, `w:proofErr`, are no item (a choice: Word redoes them).
+     * Tracked, the run is a `w:ins`, or joins this author's own `w:ins` where one ends the paragraph. A line break makes
+     * paragraphs, as `splice` does (CR-002 section 60 E1); text so broken after a hidden run is written visible (a choice,
+     * unmeasured).
+     */
+    writeAtEnd(text: string, plain?: boolean): Range;
+    /**
+     * `items` put at `at` in `list` (its end by default): onto the end of `run`, which is in `list` right before `at`,
+     * merging into its last `w:t`, or as a new run in its properties where `run` is undefined. Returns the run written.
+     */
+    private appendTo;
+    /** `splice`'s write. */
+    private spliceWrite;
+    /**
+     * Text of several lines put in place of [start, end) as Word's insertText puts it (CR-002 section 60 E1): the lines'
+     * text, then a paragraph break after each line but the last, the paragraphs keeping this one's properties; tracked,
+     * each new mark inserted. Refused before anything changes where a paragraph can't be split there.
+     */
+    private spliceLines;
+    /** @internal Refuses, before anything changes, a paragraph break at `at` where none can be made (E1; `Range`'s Replace across paragraphs). */
+    assertBreakableAt(at: number, prefer: 'before' | 'after'): void;
+    /**
+     * The segment text put at `at` goes into, as `spliceText` chooses it: a replacement's, the one holding the first
+     * replaced character; else the one containing `at`, else the nearer neighbour.
+     */
+    private landingSegment;
+    /** The run-level content control a segment's run is in, the innermost, as a view; undefined for none. */
+    private runControlOf;
+    /** The block-level content control holding this paragraph directly, as a view; undefined for none. */
+    get blockControl(): ContentControl | undefined;
+    /**
+     * Refuses, before anything changes, a paragraph break where the text lands inside something a paragraph can't be
+     * split in: a content control, an equation, a kept mc:AlternateContent (CR-002 section 60 E1, as `splitParagraph`
+     * refuses one). A field's result is split: a complex field's runs across the paragraphs, a `w:fldSimple` made a
+     * complex field first (section 62.2 D1).
+     */
+    private assertBreakable;
+    /**
+     * The characters of [from, to) that are elements written as the elements they read as (CR-002 section 60 D1), each
+     * in its run where it stood: a w:t holding one is cut around it. Characters outside the span are left as they are.
+     */
+    private writeElements;
+    /**
+     * The first run's properties, for text with no run beside it to take its look from; none where that run is hidden,
+     * so that text put into a paragraph whose every run is hidden can be seen (CR-002 section 60: the text was hidden
+     * with it, so read as nothing, and its characters escaped the map).
+     */
+    private visibleFirstRunRPr;
+    /** `splice` before section 60: the text put in as it is, as one stretch of a w:t's text. */
+    private spliceText;
     /**
      * Inserts run-level items (runs, hyperlinks, content controls) at a text offset, splitting the
      * run there when the offset falls inside one. PARENT is linked on what is inserted.
@@ -269,6 +422,16 @@ export declare class Paragraph {
     insertItemsAt(offset: number, items: Element[]): void;
     /** Splits the run at a text offset so that [offset, ...) begins a run; returns nothing when the offset is already a boundary. */
     splitAt(offset: number): void;
+    /**
+     * Splits `seg`'s run so that the items of `owner` from `index` on begin a run of their own, behind it.
+     * `owner` is the run's content, or the selected branch of a run-level `mc:AlternateContent` in it
+     * (CR-012 section 12.2): a run holds the element whole, so the branch splits with it, as the editor's
+     * ED-009 section 3.4 has it. The first piece keeps the element, its other branches as they were; the
+     * second gets an element of its own, the same branches in the same order with the same `Requires`, the
+     * selected one holding the rest of its items and the others empty, so that a reader taking any branch
+     * takes the same one in both. The run's items after the element go with the second piece.
+     */
+    private splitRunAtItem;
     /**
      * Office JS `paragraph.isListItem`: whether Word paints a label in front of this paragraph.
      * The effective `w:numPr` decides it (docx4j `Emulator.numRefFor`), so a "List Number" style
@@ -317,9 +480,29 @@ export declare class Paragraph {
      * The text in [start, end) becomes a deletion: the runs holding it are isolated, their `w:t`
      * turned into `w:delText`, and each run of consecutive ones moved into one `w:del`. Text this
      * author had inserted is simply removed, as Word does, rather than nested in a `w:del`.
+     * The pictures in the span (`splice`'s `edges`) are deleted with the text, each in a run of its own
+     * where its run held more, as `InlinePicture.delete` gives it one (CR-002 section 48). An equation is deleted where
+     * it stands, in Word's form, a `w:del` in each math run and each structure's `m:ctrlPr` (`markEquationDeleted`;
+     * section 62.2 D2), the runs either side in `w:del`s of their own; one holding a revision of its own goes into the
+     * `w:del` whole, as every equation did before.
      * Returns the `w:del` elements it made, in document order.
      */
     private deleteText;
+    /**
+     * The run-level controls showing their placeholder that [start, end) holds whole: where the walk passes one strictly
+     * inside the span, or at an edge `edges` says it holds. A placeholder is no text, so such a control has no width
+     * (CR-002 section 63, D3).
+     */
+    private placeholderControlsIn;
+    /**
+     * The runs of comments' references in [start, end): each a run holding nothing but a reference, where the walk
+     * passes it, strictly inside the span or at an edge `edges` says it holds. A reference has no text, so a
+     * deletion's segments never held it, and a comment whose reference a deletion took stayed. Word's deletion takes
+     * it with the text (check 54 cases 27 and 28; CR-014 section 12.6).
+     */
+    private commentReferencesIn;
+    /** A comment queued to go when the package is saved, its markers, replies and entries with it, as a resolution queues one. */
+    private queueCommentRemoval;
     /**
      * Splits the revision that holds the text at `at` into two - the second half a copy of its
      * attributes under a new `w:id` - and puts `item` between them. Word splits a revision so when
@@ -361,15 +544,31 @@ export declare class Paragraph {
      * are split there: never inside another's revision.
      */
     private placeInsertion;
+    /**
+     * Splits runs so that every run holding text in [start, end) holds nothing else (internal: what a
+     * `Range.font` write formats). A kept `mc:AlternateContent`'s branch splits with its run (section 12.2).
+     */
+    splitRunsAround(start: number, end: number): void;
     /**
      * Splits runs so that every run holding text in [start, end) holds nothing else, and returns
      * the segments inside the span. `splitAt` does the `w:t` boundaries; this also moves the items
      * of a run that straddles a boundary (a tab, a break, a drawing) out into runs of their own.
+     * The pictures in the span (`splice`'s `edges`) are among the segments returned, and a run
+     * holding one holds nothing outside the span either.
      */
     private isolate;
-    /** Moves the items before `seg` into a run of their own, in front of `seg`'s run. */
+    /**
+     * Refuses an edit that would cut an equation (CR-012 phase 4). Its text is one segment, Word's drawing of
+     * its math runs (`mathTextOf`), so an edit may take it whole but not part of it, nor insert into it. Under change
+     * tracking a deletion takes it whole in Word's form (`deleteText`, CR-002 section 62.2 D2, check 57), and a
+     * replacement doesn't take it at all: where Word puts the new text beside a deleted equation isn't measured. Since
+     * phase 4 every other offset is a place in the runs: `text` is the segments' text, where before it was the objects
+     * package's `textOf` and section 12.4 refused an offset past a kept `mc:AlternateContent` among the runs.
+     */
+    private assertPlaceable;
+    /** Moves the items before `seg` into a run of their own, in front of the rest; false where there are none. */
     private splitRunBefore;
-    /** Moves the items after `seg` into a run of their own, behind `seg`'s run. */
+    /** Moves the items after `seg` into a run of their own, behind it; false where there are none. */
     private splitRunAfter;
 }
 type RevisionHolderOf = NonNullable<TextSegment['revision']>;