@docx4j/core-ts 0.1.0 → 0.1.2

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

@@ -1,8 +1,12 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import { Font } from './Font.mjs';
-import type { Paragraph } from './Paragraph.mjs';
-import type { Element } from './tree.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 { type SearchOptions } from './search.mjs';
+import type { Comment } from './Comment.mjs';
+import type { TrackedChange } from './TrackedChange.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
@@ -16,19 +20,59 @@ export declare class Range {
     get paragraphs(): Paragraph[];
     get text(): string;
     set text(value: string);
-    /** The paragraph's style (Office JS reports the range's paragraph style). */
+    /** The paragraph's style id (extension, as on Paragraph). */
+    get styleId(): string;
+    set styleId(id: string);
+    /** The paragraph's style name (Office JS reports the range's paragraph style). */
     get style(): string;
     set style(id: string);
-    /** Direct formatting of exactly this span: runs are split at the boundaries so that a write touches only the span. */
+    /**
+     * 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
+     * range's offsets are accepted-view offsets.
+     */
+    getText(options?: TextViewOptions): string;
+    /**
+     * The formatting of exactly this span: reads the first run's *effective* properties, writes
+     * direct formatting, splitting the runs at the boundaries so that a write touches only the
+     * span.
+     */
     get font(): Font;
+    /** `font`, with `{ direct: true }` for the direct formatting of the first run (extension). */
+    getFont(options?: FormattingOptions): Font;
     /** The runs the span covers (a run partly inside counts). */
     get runs(): Element<wml.R>[];
     insertText(text: string, location: 'Before' | 'After' | 'Start' | 'End' | 'Replace'): Range;
     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.
+     */
+    insertOoxml(ooxml: string, location: 'Before' | 'After' | 'Replace'): Promise<(Paragraph | BlockElement)[]>;
     /** Removes the span's text. */
     delete(): void;
     search(text: string, options?: SearchOptions): Range[];
+    /** Replaces every match in this span, last first so the offsets stay valid; returns the count (CR-002 section 3.7). */
+    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;
     /** 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. */
+    getComments(): Promise<Comment[]>;
+    /**
+     * Comments the span: the markers and the reference run around it (runs are split at the
+     * boundaries, as `font` does), the comment itself and the side-part entries, creating any of
+     * the comment parts the document lacks. Asynchronous because it unmarshals those parts.
+     */
+    insertComment(text: string): Promise<Comment>;
+    /**
+     * Wraps the runs this span covers in a run-level content control (Office JS
+     * `Range.insertContentControl`), splitting the runs at the boundaries as `font` does. An empty
+     * span gets an empty control at its position. Returns the control.
+     */
+    insertContentControl(kind?: ContentControlType): ContentControl;
 }

package/dist/model/content/Range.mjs

@@ -1,5 +1,13 @@
 import { Font } from './Font.mjs';
+import { runFontSelectorOf } from '../fonts/lookup.mjs';
+import { typeNameOf, linkParents, runItemsOf } from './tree.mjs';
+import { Docx4JException } from '../../opc/exceptions.mjs';
+import { ContentControl } from './ContentControl.mjs';
+import { sdt as sdtOf, nextSdtId } from '@docx4j/generated-objects-ts/builders/wml';
+import { controlIdScope, sdtKindFor } from '../customxml/insert.mjs';
+import { contentOf } from './ooxml.mjs';
 import { searchPattern, findAll } from './search.mjs';
+import { commentApi } from './comments.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
@@ -20,22 +28,50 @@ export class Range {
     set text(value) {
         this.insertText(value, 'Replace');
     }
-    /** The paragraph's style (Office JS reports the range's paragraph style). */
+    /** The paragraph's style id (extension, as on Paragraph). */
+    get styleId() {
+        return this.paragraph.styleId;
+    }
+    set styleId(id) {
+        this.paragraph.styleId = id;
+    }
+    /** The paragraph's style name (Office JS reports the range's paragraph style). */
     get style() {
         return this.paragraph.style;
     }
     set style(id) {
         this.paragraph.style = id;
     }
-    /** Direct formatting of exactly this span: runs are split at the boundaries so that a write touches only the span. */
+    /**
+     * 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
+     * range's offsets are accepted-view offsets.
+     */
+    getText(options) {
+        if ((options === null || options === void 0 ? void 0 : options.view) === 'original')
+            throw new Docx4JException("A Range's offsets are accepted-view offsets; read the original view on its Paragraph");
+        return this.text;
+    }
+    /**
+     * The formatting of exactly this span: reads the first run's *effective* properties, writes
+     * direct formatting, splitting the runs at the boundaries so that a write touches only the
+     * span.
+     */
     get font() {
-        return new Font(() => {
+        return this.getFont();
+    }
+    /** `font`, with `{ direct: true }` for the direct formatting of the first run (extension). */
+    getFont(options) {
+        const holders = () => {
             if (this.start === this.end)
                 return [];
             this.paragraph.splitAt(this.start);
             this.paragraph.splitAt(this.end);
             return this.runs.map((r) => r.value);
-        });
+        };
+        if ((options === null || options === void 0 ? void 0 : options.direct) === true)
+            return new Font(holders, () => this.paragraph.fontTracking());
+        return new Font(holders, () => this.paragraph.fontTracking(), (rPr) => this.paragraph.parentBody.propertyResolver.getEffectiveRPr(rPr, this.paragraph.p.pPr), (rPr) => { var _a; return (_a = runFontSelectorOf(this.paragraph.parentBody.package_)) === null || _a === void 0 ? void 0 : _a.asciiFontName(rPr); });
     }
     /** The runs the span covers (a run partly inside counts). */
     get runs() {
@@ -71,6 +107,39 @@ export class Range {
     insertParagraph(text, location) {
         return this.paragraph.insertParagraph(text, location);
     }
+    /**
+     * 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.
+     */
+    async insertOoxml(ooxml, location) {
+        var _a, _b, _c;
+        const body = this.paragraph.parentBody;
+        const preprocess = (_a = body.package_) === null || _a === void 0 ? void 0 : _a.loadOptions.preprocessor;
+        const elements = await contentOf(ooxml, { preprocess: preprocess ? (doc) => preprocess(doc) : undefined, target: body.part });
+        if (elements.length === 0)
+            return [];
+        const only = elements.length === 1 && typeNameOf(elements[0]) === 'org_docx4j_wml.P' ? elements[0].value : undefined;
+        if (only) {
+            if (location === 'Replace') {
+                this.delete();
+                this.paragraph.insertItemsAt(this.start, ((_b = only.content) !== null && _b !== void 0 ? _b : []));
+            }
+            else
+                this.paragraph.insertItemsAt(location === 'Before' ? this.start : this.end, ((_c = only.content) !== null && _c !== void 0 ? _c : []));
+            return [this.paragraph];
+        }
+        body.insertElement(elements, location === 'Before' ? 'Before' : 'After', this.paragraph);
+        if (location === 'Replace')
+            this.delete();
+        return elements.map((el) => {
+            var _a;
+            return typeNameOf(el) === 'org_docx4j_wml.P'
+                ? (_a = body.paragraphFor(el.value)) !== null && _a !== void 0 ? _a : { element: el, container: this.paragraph.container }
+                : { element: el, container: this.paragraph.container };
+        });
+    }
     /** Removes the span's text. */
     delete() {
         this.paragraph.splice(this.start, this.end, '');
@@ -80,6 +149,22 @@ export class Range {
         const base = this.start;
         return findAll(this.text, searchPattern(text, options)).map(([s, e]) => new Range(this.paragraph, base + s, base + e));
     }
+    /** Replaces every match in this span, last first so the offsets stay valid; returns the count (CR-002 section 3.7). */
+    replaceText(find, replace, options) {
+        const matches = this.search(find, options);
+        for (let i = matches.length - 1; i >= 0; i--)
+            matches[i].insertText(replace, 'Replace');
+        return matches.length;
+    }
+    /** The tracked changes this span covers, in document order (CR-002 phase F). */
+    getTrackedChanges() {
+        return this.paragraph.getTrackedChanges().filter((change) => {
+            const range = change.getRange();
+            if (!range)
+                return false;
+            return range.start <= this.end && range.end >= this.start;
+        });
+    }
     getRange(location = 'Whole') {
         if (location === 'Start')
             return new Range(this.paragraph, this.start, this.start);
@@ -91,4 +176,76 @@ export class Range {
     toString() {
         return this.text;
     }
+    // --- comments (CR-002 phase G) ---
+    /** The comments this span touches, replies nested under their parent. */
+    async getComments() {
+        return commentApi().commentsOf(this);
+    }
+    /**
+     * Comments the span: the markers and the reference run around it (runs are split at the
+     * boundaries, as `font` does), the comment itself and the side-part entries, creating any of
+     * the comment parts the document lacks. Asynchronous because it unmarshals those parts.
+     */
+    async insertComment(text) {
+        return commentApi().insertComment(this, text);
+    }
+    // --- content controls (CR-002 phase E) ---
+    /**
+     * Wraps the runs this span covers in a run-level content control (Office JS
+     * `Range.insertContentControl`), splitting the runs at the boundaries as `font` does. An empty
+     * span gets an empty control at its position. Returns the control.
+     */
+    insertContentControl(kind) {
+        var _a;
+        const paragraph = this.paragraph;
+        const body = paragraph.parentBody;
+        // The control is built empty first: `sdt` refuses a kind that cannot be run-level (a repeating
+        // section), and that refusal must come before any run is split.
+        const sdt = sdtOf([], { kind: sdtKindFor(kind), id: nextSdtId(controlIdScope(body)), form: 'run' });
+        if (this.start === this.end) {
+            paragraph.insertItemsAt(this.start, [sdt]);
+            return new ContentControl(sdt, containerOf(sdt, paragraph), body);
+        }
+        paragraph.splitAt(this.start);
+        paragraph.splitAt(this.end);
+        const segments = paragraph.segments().filter((s) => s.start >= this.start && s.end <= this.end);
+        if (segments.length === 0)
+            throw new Docx4JException('This range covers no run');
+        const owner = segments[0].runOwner;
+        if (segments.some((s) => s.runOwner !== owner)) {
+            throw new Docx4JException('This range spans more than one run holder (a hyperlink or a tracked change); wrap a narrower span');
+        }
+        const items = [];
+        for (const segment of segments) {
+            const element = owner[segment.runIndex];
+            if (!items.includes(element))
+                items.push(element);
+        }
+        const at = owner.indexOf(items[0]);
+        sdt.value.sdtContent.content = items;
+        owner.splice(at, items.length, sdt);
+        linkParents(sdt, (_a = segments[0].run.PARENT) !== null && _a !== void 0 ? _a : paragraph.p);
+        return new ContentControl(sdt, owner, body);
+    }
+}
+/** The run-level array holding an element, after `insertItemsAt` put it somewhere in the paragraph. */
+function containerOf(element, paragraph) {
+    var _a, _b;
+    var _c;
+    const seek = (items) => {
+        if (!items)
+            return undefined;
+        if (items.includes(element))
+            return items;
+        for (const item of items) {
+            const value = item.value;
+            if (typeof value !== 'object' || value === null)
+                continue;
+            const found = seek(runItemsOf(value));
+            if (found)
+                return found;
+        }
+        return undefined;
+    };
+    return (_a = seek(runItemsOf(paragraph.p))) !== null && _a !== void 0 ? _a : ((_b = (_c = paragraph.p).content) !== null && _b !== void 0 ? _b : (_c.content = []));
 }

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

@@ -0,0 +1,130 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type Element } from './tree.mjs';
+import type { Body } from './Body.mjs';
+import type { Paragraph } from './Paragraph.mjs';
+import type { Range } from './Range.mjs';
+import { type ChangeTracker } from './tracking.mjs';
+/**
+ * A subset of Office JS `Word.Table` over a `w:tbl`. Rows are read through row-level content
+ * controls (an OpenDoPE repeat wraps its `w:tr` in a `w:sdt`), so `rows` is what Word shows.
+ */
+export declare class Table {
+    /** The `w:tbl` element pair. */
+    readonly element: Element<wml.Tbl>;
+    /** The content array holding the element. */
+    readonly container: Element[];
+    /** The body the table is in (the part's), for addresses and paragraph ids. */
+    readonly parentBody: Body;
+    constructor(
+    /** The `w:tbl` element pair. */
+    element: Element<wml.Tbl>, 
+    /** The content array holding the element. */
+    container: Element[], 
+    /** The body the table is in (the part's), for addresses and paragraph ids. */
+    parentBody: Body);
+    /** The table value (docx4j: the Tbl). */
+    get tbl(): wml.Tbl;
+    get index(): number;
+    get rowCount(): number;
+    get rows(): TableRow[];
+    /** The text of every cell, row by row (Office JS values). */
+    get values(): string[][];
+    set values(values: string[][]);
+    /** The table style id (w:tblStyle; docx4j's name for it); '' when none is set. Extension, as on Paragraph. */
+    get styleId(): string;
+    set styleId(id: string);
+    /** The style's display name ('Table Grid'), as Office JS; '' when none is set. Setting accepts a name or an id, as Paragraph. */
+    get style(): string;
+    set style(name: string);
+    /** The `Word.Style` value ('TableGrid'), or 'Other', as Office JS. */
+    get styleBuiltIn(): string;
+    set styleBuiltIn(value: string);
+    /** The number of leading rows marked as header rows (w:tblHeader), as Office JS. */
+    get headerRowCount(): number;
+    set headerRowCount(count: number);
+    /** The cell at a row and cell index; throws when there is none, as Office JS's getCell does. */
+    getCell(rowIndex: number, cellIndex: number): TableCell;
+    /** Adds rows at the start or the end, with the column count and widths of this table. */
+    addRows(location: 'Start' | 'End', rowCount: number, values?: string[][]): TableRow[];
+    /**
+     * Removes `rowCount` rows from `rowIndex` (one by default), as Office JS. While the package
+     * tracks changes the rows stay and take a `w:trPr/w:del` instead (CR-002 phase F).
+     */
+    deleteRows(rowIndex: number, rowCount?: number): void;
+    /** Removes the table from its container; tracked, every row is marked deleted instead. */
+    delete(): void;
+    /** The package's change tracker while `changeTrackingMode` is on (CR-002 phase F). */
+    get changeTracker(): ChangeTracker | undefined;
+    /** The cell this table is nested in, if any (extension). */
+    get parentTableCell(): TableCell | undefined;
+    /** The text of the table: a line per paragraph, as docx4j TextUtils (extension). */
+    get text(): string;
+    /** The column widths in twips, from the grid or from the first row (extension). */
+    columnWidths(): number[];
+    private tblPr;
+}
+/** A subset of Office JS `Word.TableRow` over a `w:tr`. */
+export declare class TableRow {
+    readonly element: Element<wml.Tr>;
+    /** The array holding the row: the table's content, or a row-level content control's. */
+    readonly container: Element[];
+    readonly parentTable: Table;
+    constructor(element: Element<wml.Tr>, 
+    /** The array holding the row: the table's content, or a row-level content control's. */
+    container: Element[], parentTable: Table);
+    get tr(): wml.Tr;
+    /** The row's index among the table's rows. */
+    get rowIndex(): number;
+    get cellCount(): number;
+    get cells(): TableCell[];
+    /** The text of the row's cells. */
+    get values(): string[];
+    set values(values: string[]);
+    /** w:tblHeader: the row repeats at the top of every page (Office JS Table.headerRowCount). */
+    get isHeader(): boolean;
+    set isHeader(header: boolean);
+    /** New rows before or after this one, with this table's columns. */
+    insertRows(location: 'Before' | 'After', rowCount: number, values?: string[][]): TableRow[];
+    /** Removes the row; tracked, it stays and takes a `w:trPr/w:del` (CR-002 phase F). */
+    delete(): void;
+    private trPrItem;
+}
+/** A subset of Office JS `Word.TableCell` over a `w:tc`: a body of its own, plus its position. */
+export declare class TableCell {
+    readonly element: Element<wml.Tc>;
+    /** The array holding the cell: the row's content, or a cell-level content control's. */
+    readonly container: Element[];
+    readonly parentRow: TableRow;
+    constructor(element: Element<wml.Tc>, 
+    /** The array holding the cell: the row's content, or a cell-level content control's. */
+    container: Element[], parentRow: TableRow);
+    get tc(): wml.Tc;
+    get parentTable(): Table;
+    get rowIndex(): number;
+    get cellIndex(): number;
+    /**
+     * The cell's content as a `Body` (Office JS TableCell.body): the same part and package as the
+     * table's body, addressed from the cell (`body/4/0/1`).
+     */
+    get body(): Body;
+    get paragraphs(): Paragraph[];
+    get tables(): Table[];
+    /** The cell's text, a line per paragraph. */
+    get text(): string;
+    /** Office JS TableCell.value: the text, replaced as one paragraph when set. */
+    get value(): string;
+    set value(text: string);
+    insertParagraph(text: string, location: 'Start' | 'End'): Paragraph;
+    insertText(text: string, location: 'Start' | 'End' | 'Replace'): Range;
+    /** The cell width in points (w:tcW in twips), as Office JS reports it; 0 when it is not a fixed width. */
+    get width(): number;
+    set width(points: number);
+    /** Office JS TableCell.columnWidth, the same value. */
+    get columnWidth(): number;
+    set columnWidth(points: number);
+}
+/**
+ * The cell a value is in, from its PARENT links; undefined when it is not in a table. Shared by
+ * `Paragraph.parentTableCell` and `Table.parentTableCell`.
+ */
+export declare function cellOf(value: object, parentBody: Body): TableCell | undefined;