@docx4j/core-ts 0.5.0 → 0.7.0

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

@@ -3,15 +3,26 @@ import { Font } from './Font.mjs';
 import type { Paragraph, FormattingOptions } from './Paragraph.mjs';
 import type { BlockElement } from './Body.mjs';
 import { type Element, type TextViewOptions } from './tree.mjs';
-import { ContentControl, type ContentControlType } from './ContentControl.mjs';
+import { ContentControl, type ContentControlType, type ContentControlOptions } from './ContentControl.mjs';
 import { type SearchOptions } from './search.mjs';
 import { type CommentContent, type CommentOptions } from './comments.mjs';
 import type { Comment } from './Comment.mjs';
 import type { TrackedChange } from './TrackedChange.mjs';
+import type { Table } from './Table.mjs';
+import type { TableCell } from './Table.mjs';
 /**
- * A subset of Office JS `Word.Range`: a span of text within one paragraph, [start, end) in the
- * paragraph's text. Positions are recomputed from the tree on every use, so a range stays
- * valid across edits made through it; edits made elsewhere may shift it.
+ * A subset of Office JS `Word.Range`: a span of text from an offset in one paragraph to an offset in the same
+ * paragraph or a later one of the same story, [start, end), `start` in `paragraph`'s text and `end` in
+ * `endParagraph`'s. Positions are recomputed from the tree on every use, so a range stays valid across edits
+ * made through it; edits made elsewhere may shift it.
+ *
+ * A range within one paragraph is what it has been since CR-002: `endParagraph` is `paragraph`. A range across
+ * paragraphs (CR-014 phase 1) reads as Office JS's does (check 52): its `text` in `body.text`'s form between
+ * its ends, `paragraphs` every paragraph it touches (a table's cells' among them), `font` `null` where the runs
+ * differ, `search`, the tracked changes and the comments over all of it. Its writes (phase 2) are Word's too:
+ * `delete` and `insertText('Replace')` join the paragraphs in the last one's properties, `font` formats every
+ * run and mark in it, `insertText` goes at its ends, and `insertParagraph` splits the paragraph at its start or
+ * end; the rest of its writes throw `NotSupportedError`.
  *
  * A picture has a place in the text and no text of its own, so a picture at the range's start or
  * end offset may be inside it or outside it. `whole` says: a range from `Paragraph.getRange('Whole')`
@@ -20,22 +31,150 @@ import type { TrackedChange } from './TrackedChange.mjs';
  * hit replaced does not take the picture beside it (CR-002 section 48).
  */
 export declare class Range {
-    readonly paragraph: Paragraph;
     start: number;
     end: number;
-    readonly whole: boolean;
-    constructor(paragraph: Paragraph, start: number, end: number, whole?: boolean);
+    private startParagraph;
+    private lastParagraph;
+    private holdsWhole;
+    private holdsMark;
+    private lastMarkText;
+    constructor(paragraph: Paragraph, start: number, end: number, whole?: boolean, 
+    /**
+     * A paragraph's 'Whole' range: its text ends with the paragraph's mark, as Office JS's does (check 48:
+     * `\r`, and `\t` for a cell's last paragraph, the cell's end), where 'Content' ends with its text.
+     * The mark is no offset: every edit and search works on the text before it.
+     */
+    mark?: boolean, 
+    /** The paragraph holding `end`, where it isn't `paragraph` (CR-014 phase 1). */
+    endParagraph?: Paragraph, 
+    /**
+     * What the range's text ends with in place of `endParagraph`'s mark, where `mark` is set: a table's
+     * 'Whole' range ends with its last row's end, `\r\n` (check 52).
+     */
+    endMark?: string);
+    /** @internal Which of a paragraph's own ranges this is, where its writes at the end are the paragraph's End's (D12). */
+    private endOf?;
+    /** @internal Marks this range as its paragraph's End or Content range (`Paragraph.getRange`); returns it. */
+    atEndOf(kind: 'End' | 'Content'): this;
+    /** Whether text put at `location` is written at the paragraph's End: its End range's, at any location; its Content range's End and After. */
+    private writesAtParagraphEnd;
+    /**
+     * @internal The content control whose 'Content' or 'Whole' range this is (CR-002 section 63, D4): a run-level
+     * control holding no text, or showing its placeholder, has no width, so its own range is where its writes go in,
+     * not its offset, which the text either side of it shares.
+     */
+    ofControl: {
+        control: ContentControl;
+        part: 'Content' | 'Whole';
+    } | undefined;
+    /** The paragraph holding `start`. */
+    get paragraph(): Paragraph;
+    /** The paragraph holding `end`: `paragraph` for a range within one paragraph (CR-014 phase 1). */
+    get endParagraph(): Paragraph;
+    /** The range holds its paragraphs' whole content, the pictures at its edges too (CR-002 section 48). */
+    get whole(): boolean;
+    /** The range's text ends with its last paragraph's mark: a 'Whole' range. */
+    get mark(): boolean;
+    /** What the text ends with in place of the last paragraph's mark: a table's 'Whole' range's `\r\n`. */
+    get endMark(): string | undefined;
+    /**
+     * True where the range holds its last paragraph's mark (a 'Whole' range ending at the paragraph's end), or a
+     * table's end in its place: what `delete` takes and `Replace` keeps (check 52, W1 and W2). An extension.
+     */
+    get holdsEndMark(): boolean;
+    /** The range collapsed where an edit through it closed it up, or over what the edit put there. */
+    /**
+     * This range moved onto another's span: its paragraphs and offsets (a replacement's, CR-002 section 60); `fresh`, it
+     * no longer holds a mark or a paragraph's whole content either, as `landAt` leaves one.
+     */
+    private cover;
+    private landAt;
+    /** True for a range across paragraphs: its ends are in two (extension; CR-014). */
+    get spansParagraphs(): boolean;
     /** The edges `Paragraph.splice` is given: both for a whole range. */
     private get edges();
+    /** The story's layout, and where this range's two paragraphs are in it. */
+    private located;
+    /** The view of a paragraph of this range's story: this range's own where it is one of its two. */
+    private viewOf;
+    /**
+     * The range as one range per paragraph it touches: its part of the first, the whole of each between, its
+     * part of the last. A range within one paragraph is itself.
+     */
+    private pieces;
+    /**
+     * Refuses a hyperlink set on a range across paragraphs. Word wrote a HYPERLINK field from the first paragraph into
+     * the last (check 54 case 34), where this package's links are `w:hyperlink` elements, one paragraph's each, which
+     * its getter reads (CR-014 section 12).
+     */
+    private assertOneParagraph;
+    /** Refuses, before anything changes, a write over a paragraph of the range that is read-only (a text box's, a branch's). */
+    private assertWritableSpan;
+    /** Every paragraph the range touches, in document order, a table's cells' among them (check 52). */
     get paragraphs(): Paragraph[];
+    /**
+     * The range's text, in `body.text`'s form across paragraphs (check 52): a mark `\r` between paragraphs, a
+     * table's cells a `\t` apart and each row ended `\r\n`; with the last paragraph's mark where the range
+     * holds it (a 'Whole' range).
+     */
     get text(): string;
     set text(value: string);
-    /** The paragraph's style id (extension, as on Paragraph). */
+    /** True when the range holds no text (Office JS `isEmpty`). */
+    get isEmpty(): boolean;
+    /**
+     * The paragraph's style id (extension, as on Paragraph); a range across paragraphs gives the first one's. Set
+     * across paragraphs, each paragraph's (check 54 cases 32 and 33: Word gave both Heading 2).
+     */
     get styleId(): string;
     set styleId(id: string);
-    /** The paragraph's style name (Office JS reports the range's paragraph style). */
+    /**
+     * The range's style name, as Office JS reads it (checks 52 and 53). A range holding its paragraphs whole reads
+     * their paragraph style, where they share one, else `Normal`. Any other range reads its runs' character style
+     * where they share one (`Emphasis`), `''` where their character styles differ (some runs styled, some not: a
+     * footnote reference among plain text), and the paragraph style where none has one. Setting it sets the
+     * paragraph's style.
+     */
     get style(): string;
     set style(id: string);
+    /** The built-in name of `style` (Office JS `styleBuiltIn`): `Other` where it is `''`, `Normal` where paragraphs across it differ. */
+    get styleBuiltIn(): string;
+    /** Sets each paragraph's style by its built-in name, as `style` does. */
+    set styleBuiltIn(value: string);
+    /**
+     * The paragraphs a style set on the range goes to: its own, or each across paragraphs (check 54 cases 32 and 33:
+     * Word gave a body paragraph and a list item Heading 2). Word also took away the body paragraph's centring and
+     * italic and the list item's numbering, which `Paragraph.style` doesn't (CR-014 section 12).
+     */
+    private styledParagraphs;
+    /**
+     * What `style` reads: the runs' shared character style id, `''` where their character styles differ, or
+     * undefined where the paragraph style applies, with how to read that.
+     */
+    private styleRead;
+    /** The table cell holding the range's start, if it is in one (Office JS `parentTableCell`, which throws instead). */
+    get parentTableCell(): TableCell | undefined;
+    /** The table holding the range's start, if it is in one (Office JS `parentTable`, which throws instead). */
+    get parentTable(): Table | undefined;
+    /**
+     * The tables in the range (Office JS `Range.tables`): a table the range covers some of, unless the range is
+     * inside one of its cells, where that cell's tables are looked at instead (check 52: a range across a table,
+     * or into or out of one, lists it; a cell's whole range lists none).
+     */
+    get tables(): Table[];
+    /**
+     * The content controls in the range (Office JS `Range.contentControls`): each control the range overlaps,
+     * except one holding the whole range, in document order (check 53: a range from a paragraph into a control
+     * lists it, one inside a control, its content whole, doesn't, one over an inline control lists it).
+     */
+    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[];
+    /** A body over this range's story, for its tables and controls. */
+    private storyBody;
     /**
      * The text in one of the two views (extension; `text` is the accepted one). `{ view: 'original' }`
      * is offered on `Paragraph` and `Body`; on a `Range` it is the accepted-view span only, since a
@@ -52,18 +191,76 @@ export declare class Range {
     getFont(options?: FormattingOptions): Font;
     /** The runs the span covers (a run partly inside counts). */
     get runs(): Element<wml.R>[];
+    /**
+     * Text put at the range's start ('Start', 'Before'), at its end ('End', 'After'), or in its place ('Replace').
+     * Across paragraphs (CR-014 phase 2, check 52) the start is in the first paragraph and the end in the last,
+     * before a last mark the range holds, and a replacement is `delete()` keeping a last mark, then the text where the
+     * paragraphs joined: untracked, in the first replaced character's look (`lookOf`); tracked, a `w:ins` before the
+     * deletion, as Word writes it. A range holding its paragraph's mark is replaced so too under tracking.
+     */
     insertText(text: string, location: 'Before' | 'After' | 'Start' | 'End' | 'Replace'): Range;
+    /**
+     * A new paragraph of the text where the range starts ('Before') or ends ('After'), splitting the paragraph there,
+     * as Word does (`insertParagraphAt`): across paragraphs (check 52) and within one (check 54 cases 1 to 3; until
+     * then a range within one paragraph put it before or after the whole paragraph). At a paragraph's start or end,
+     * or after a range holding its mark, it goes before or after the paragraph. This range keeps covering its text.
+     */
     insertParagraph(text: string, location: 'Before' | 'After'): Paragraph;
     /**
      * Word's `insertOoxml` at range level: a flat OPC `pkg:package` (or a bare fragment). One
      * incoming paragraph's runs go at the start or the end of the span, or in its place; anything
      * else is inserted as blocks before or after the paragraph. Returns what was inserted, as
-     * `insertXml` does.
+     * `insertXml` does. Across paragraphs (check 54 case 35) one paragraph's runs replace the range as
+     * `insertText('Replace')` replaces it, where the paragraphs joined; the start is the first paragraph's,
+     * the end the last's; several blocks go before the first paragraph or after the last, and replacing a
+     * range across paragraphs with several blocks is refused, as unmeasured.
      */
     insertOoxml(ooxml: string, location: 'Before' | 'After' | 'Replace'): Promise<(Paragraph | BlockElement)[]>;
-    /** Removes the span's text, and the pictures in it (CR-002 section 48). */
+    /**
+     * The range's content removed as a replacement removes it, keeping a last mark the range holds (check 52):
+     * `delete()`'s join across paragraphs, else the paragraph's splice. Where the paragraphs closed up.
+     */
+    private removeKeepingMark;
+    /**
+     * The extent of a range a replacement may take: refused where it ends with a whole table, as Word refused it
+     * (`GeneralException`, check 54 case 7), and where it starts with a whole table or control (unmeasured).
+     */
+    private replaceableExtent;
+    /**
+     * Removes the span's text, and the pictures in it (CR-002 section 48). Across paragraphs, or holding its
+     * paragraph's mark, it is Word's (CR-014 phase 2, check 52; `deleteSpan`): the paragraphs join in the last one's
+     * properties, the blocks between go, a last mark the range holds goes with it, joining the paragraph after; a
+     * footnote whose reference goes goes on save. Tracked, the text is deleted and every mark in the range marked
+     * deleted. A range starting or ending inside a table is refused with `GeneralException`, as Office JS refuses it.
+     */
     delete(): void;
+    /** `delete()`'s own work. */
+    private deleteSpan;
+    /** `insertText(text, 'Replace')` across paragraphs, and any under tracking (CR-014 phases 2 and 3). */
+    private replaceAcross;
+    /**
+     * The hits of a query in the range, as Office JS's `search` gives them. A plain query holding `^p`, Word's
+     * paragraph mark, matches across paragraphs (`searchMarks`); any other matches a paragraph at a time.
+     */
     search(text: string, options?: SearchOptions): Range[];
+    /**
+     * A query's hits where it holds `^p`, Word's paragraph mark, as Word finds them (check 52 case 2; CR-014 phase
+     * 3): `pieces` is the query split at its marks. A hit starts in one paragraph with the first piece matching to
+     * its end, takes each middle piece as a whole paragraph's text, and ends with the last piece matching from the
+     * next paragraph's start; a query ending with `^p` ends with that paragraph's mark, which the hit holds. A mark
+     * matches only a paragraph's own mark the range holds: never a cell's or a row's end, and never across the edge
+     * of a table, so every paragraph of a hit is in the same cell or in none (`^p` between a list item and the first
+     * cell after it found nothing). `^p^p` matches an empty paragraph's mark after another mark. Plain queries only:
+     * Word's wildcards write the mark another way.
+     */
+    private searchMarks;
+    /**
+     * A wildcard query's hits across the paragraphs' marks, as Word's wildcards match them (check 59; CR-002 section 32,
+     * K7): where `^p` matches one (`searchMarks`), a paragraph's own mark the range holds, never a cell's or a row's end,
+     * and never across a table's edge, so the paragraphs a hit spans are in one cell or in none. `?`, `*` and a class cross
+     * such a mark and `^13` is one; a hit ending with one holds it.
+     */
+    private searchWildcards;
     /**
      * Replaces every match in this span, last first so the offsets stay valid; returns the count
      * (CR-002 section 3.7). The replacement's `$1` or Word's `\1` expands as it does on a paragraph
@@ -72,7 +269,17 @@ export declare class Range {
     replaceText(find: string, replace: string, options?: SearchOptions): number;
     /** The tracked changes this span covers, in document order (CR-002 phase F). */
     getTrackedChanges(): TrackedChange[];
-    getRange(location?: 'Whole' | 'Start' | 'End' | 'Content'): Range;
+    /**
+     * A range of this one, as Office JS's `getRange` (check 52): 'Whole' is the range itself, 'Content' the same
+     * without a last mark, 'Start' and 'End' collapsed at its ends, and 'After' collapsed just after it - at the
+     * start of the next paragraph where the range holds its last paragraph's mark.
+     */
+    getRange(location?: 'Whole' | 'Start' | 'End' | 'Content' | 'After'): Range;
+    /**
+     * A range from this range's start or `range`'s, whichever comes first, to the end that comes last (Office JS
+     * `expandTo`; which is first doesn't matter, check 52). Both must be in one story.
+     */
+    expandTo(range: Range): Range;
     /** The span's text as it stands (extension; Office JS getOoxml wraps it in a package). */
     toString(): string;
     /** The comments this span touches, replies nested under their parent. */
@@ -89,6 +296,14 @@ export declare class Range {
      * span gets an empty control at its position. Returns the control.
      */
     insertContentControl(kind?: ContentControlType): ContentControl;
+    /**
+     * A block content control around the paragraphs of a range across paragraphs, as Word puts one (check 54 cases
+     * 38 and 43, untracked and tracked): only a range holding its paragraphs whole, from the first's start to the
+     * last's end, its mark or not. Any other, starting or ending inside a paragraph or a table, is refused with
+     * `GeneralException`, as Word refused it (cases 36, 37 and 39 to 42). Tracked, the control is an insertion, as a
+     * paragraph's control is (check 30's markers).
+     */
+    private wrapParagraphs;
     /**
      * Office JS `Range.hyperlink`: the address of the first hyperlink in this range, or a new
      * hyperlink over it. `address#location` separates the address from an optional location within