@docx4j/core-ts 0.1.0 → 0.1.2

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

@@ -1,11 +1,45 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
-import { type Element, W_NS, type TextSegment } from './tree.mjs';
-import { Font } from './Font.mjs';
+import { type Element, W_NS, 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 } from './Body.mjs';
-/** Office JS Word.Alignment. */
-export type Alignment = 'Unknown' | 'Left' | 'Centered' | 'Right' | 'Justified';
+import type { Body, BlockElement } from './Body.mjs';
+import { type TableCell } from './Table.mjs';
+import { ContentControl, type ContentControlType } from './ContentControl.mjs';
+import { InlinePicture, type InlinePictureOptions } from './InlinePicture.mjs';
+import type { Comment } from './Comment.mjs';
+import { type ChangeTracker } from './tracking.mjs';
+import { TrackedChange } from './TrackedChange.mjs';
+import { type List, type ListItem, type StartListOptions } from './List.mjs';
+/**
+ * Office JS `Word.Alignment`, as an *effective* read reports it: an absent `w:jc` resolves to
+ * `'Left'`, which is what Word does and what Office JS answers. `'Unknown'` is what a direct
+ * read (`formatting({ direct: true })`) says for "no `w:jc` here", and is accepted by the
+ * setter, where it removes the element (CR-001 Phase B step 2 decision 4).
+ */
+export type Alignment = 'Left' | 'Centered' | 'Right' | 'Justified';
+/** {@link Alignment} plus the direct reads' "nothing stated" and the setter's "remove it". */
+export type AlignmentOrUnknown = Alignment | 'Unknown';
+/** Whether a read reports direct formatting instead of the effective value. */
+export interface FormattingOptions {
+    /**
+     * `true` reads the direct formatting only - the `w:pPr` or `w:rPr` on the element itself -
+     * as this package did before CR-001 Phase B. The default is the effective value, resolved
+     * through the document defaults and the style chain, which is what Office JS reports.
+     */
+    direct?: boolean;
+}
+/** Office JS's paragraph formatting properties, read in one call (extension). */
+export interface ParagraphFormatting {
+    alignment: AlignmentOrUnknown;
+    leftIndent: number;
+    rightIndent: number;
+    firstLineIndent: number;
+    spaceBefore: number;
+    spaceAfter: number;
+    lineSpacing: number;
+    outlineLevel: number;
+}
 /**
  * A subset of Office JS `Word.Paragraph` over a `w:p` in a body, cell, header, footer or
  * content control. A light view: it holds the element and the array that contains it; nothing
@@ -33,15 +67,45 @@ export declare class Paragraph {
     get text(): string;
     /** Replaces the content with one run of the text, keeping the first run's formatting. */
     set text(value: string);
-    /** The style id (w:pStyle); 'Normal' when none is set. */
+    /**
+     * 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: `w:del` included, `w:ins` excluded.
+     */
+    getText(options?: TextViewOptions): string;
+    /** The style id (w:pStyle; docx4j's name for it); 'Normal' when none is set. Extension: Office JS has `style` and `styleBuiltIn` only. */
+    get styleId(): string;
+    set styleId(id: string);
+    /**
+     * The style's display name ('Heading 1', 'My Style'), as Office JS: from the styles part's
+     * `w:name` when that part is unmarshalled, else derived from the id. Setting accepts a display
+     * name, a stored name, or an id.
+     */
     get style(): string;
-    set style(id: string);
-    /** Word's display name of the style ('Heading 1'); mapped to and from ids by removing spaces. */
+    set style(name: string);
+    /** The `Word.Style` value ('Heading1'), or 'Other' when the style is not a built-in one, as Office JS. */
     get styleBuiltIn(): string;
-    set styleBuiltIn(name: string);
+    set styleBuiltIn(value: string);
+    /**
+     * The paragraph properties which actually apply: the document defaults, the style chain and
+     * the numbering level, then this paragraph's own `w:pPr` (docx4j
+     * `PropertyResolver.getEffectivePPr`). A live, possibly cached object: copy it before
+     * changing it. Needs the package's resolver; see `Body.propertyResolver`.
+     */
+    get effectivePPr(): wml.PPr;
+    /** The paragraph mark's effective run properties (docx4j `getEffectiveParagraphMarkRPr`). */
+    get effectiveParagraphMarkRPr(): wml.RPr;
+    /** The `w:pPr` a formatting read works from: the resolved one, or this paragraph's own. */
+    private readPPr;
+    /**
+     * Office JS's paragraph formatting in one call, and the way to ask for direct formatting:
+     * `formatting({ direct: true })` is what the individual getters reported before CR-001
+     * Phase B step 2 (an absent property reads 0, 10 or `'Unknown'`).
+     */
+    formatting(options?: FormattingOptions): ParagraphFormatting;
+    /** The effective alignment; an absent `w:jc` after resolution is `'Left'`, as Office JS. */
     get alignment(): Alignment;
-    set alignment(v: Alignment);
-    /** Indents and spacing in points, as Office JS; 0 when not set directly. */
+    set alignment(v: AlignmentOrUnknown);
+    /** Indents and spacing in points, as Office JS; the effective values (CR-001 Phase B step 2). */
     get leftIndent(): number;
     set leftIndent(pt: number);
     get rightIndent(): number;
@@ -56,35 +120,97 @@ export declare class Paragraph {
     /** Line spacing in points: w:line/240 lines of 12pt when the rule is auto, else w:line twips; 0 when not set. */
     get lineSpacing(): number;
     set lineSpacing(pt: number);
-    /** w:outlineLvl + 1 (1 to 9); 10 for body text, as Office JS. */
+    /** w:outlineLvl + 1 (1 to 9); 10 for body text, as Office JS. A heading style supplies it. */
     get outlineLevel(): number;
     set outlineLevel(level: number);
-    /** Direct formatting of the runs: reads the first run, writes all (extension: `Font` is over runs, not the paragraph mark). */
+    /**
+     * The runs' formatting: reads the first run's *effective* properties, writes direct
+     * formatting to all (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). */
+    getFont(options?: FormattingOptions): Font;
     /** w14:paraId, the stable address Word gives paragraphs. */
     get paraId(): string | undefined;
     set paraId(id: string | undefined);
     /** The runs, direct and nested (hyperlinks, content controls, insertions), in order. */
     get runs(): Element<wml.R>[];
+    /** The cell this paragraph is in, or undefined when it is not in a table (Office JS). */
+    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). */
+    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). */
     insertParagraph(text: string, location: 'Before' | 'After'): Paragraph;
     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
+     * start or the end of this paragraph, or in place of its content (Office JS).
+     */
+    insertInlinePictureFromBase64(base64: string, location: 'Start' | 'End' | 'Replace', options?: InlinePictureOptions): InlinePicture;
+    /**
+     * Word's `insertOoxml` at paragraph level: a flat OPC `pkg:package` (or a bare fragment). One
+     * incoming paragraph is merged into this one at 'Start' and 'End', as Word's paste does;
+     * anything else is inserted as blocks before or after. 'Replace' puts the content where this
+     * paragraph was and removes it.
+     */
+    insertOoxml(ooxml: string, location: 'Before' | 'After' | 'Start' | 'End' | 'Replace'): Promise<(Paragraph | BlockElement)[]>;
     /** Matches within this paragraph. */
     search(text: string, options?: SearchOptions): Range[];
+    /**
+     * Replaces every match of `find` with `replace`, last match first so that the offsets of the
+     * ones still to do stay valid (CR-002 section 3.7). Returns the number replaced; tracked when
+     * the package's `changeTrackingMode` is on.
+     */
+    replaceText(find: string, replace: string, options?: SearchOptions): number;
+    /** The tracked changes in this paragraph, in document order (CR-002 phase F). */
+    getTrackedChanges(): TrackedChange[];
     getRange(location?: 'Whole' | 'Start' | 'End' | 'Content'): Range;
-    /** Removes the paragraph from its container. */
+    /**
+     * 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.
+     */
     delete(): void;
+    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.
+     */
+    markDeletedInPlace(tracker: ChangeTracker): void;
     /** The paragraph as XML (extension; Office JS getOoxml wraps it in a package). */
     getXml(): Promise<string>;
     /** docx4j: the P's content list. */
     getContent(): Element[];
-    private pPr;
+    /**
+     * The paragraph's properties, created when absent. Every property setter goes through this
+     * one accessor, so this is where a tracked write records `w:pPrChange` with the properties as
+     * they stand before it.
+     *
+     * @internal public so that the list views (CR-002 phase H) write `w:numPr` the same way.
+     */
+    pPr(): wml.PPr;
+    /**
+     * The paragraph's `w:numPr`, created when absent, through {@link pPr} so that a tracked
+     * write records `w:pPrChange` first.
+     *
+     * @internal what the list views write through (CR-002 phase H).
+     */
+    numPr(): wml.PPrBase.NumPr;
     private ind;
     private spacing;
+    /** The package's change tracker while `changeTrackingMode` is on; undefined when it is off. */
+    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(): TextSegment[];
+    segments(options?: TextViewOptions): TextSegment[];
     /**
      * 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
@@ -92,8 +218,79 @@ export declare class Paragraph {
      * else into a new run with the formatting of the nearest run.
      */
     splice(start: number, end: number, text: string): Range;
+    /**
+     * 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.
+     */
+    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;
+    /**
+     * 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
+     * counts; a `w:numId` of 0, a `w:numId` naming no `w:num`, and a level linked to another
+     * paragraph style do not.
+     */
+    get isListItem(): boolean;
+    /** Office JS `paragraph.list`: the list this paragraph is in; throws when it is not in one. */
+    get list(): List;
+    /** Office JS `paragraph.listOrNullObject`: the list, or a null object (`isNullObject` true). */
+    get listOrNullObject(): List;
+    /** Office JS `paragraph.listItem`: this paragraph's place in its list; throws when it has none. */
+    get listItem(): ListItem;
+    /** Office JS `paragraph.listItemOrNullObject`. */
+    get listItemOrNullObject(): ListItem;
+    /**
+     * Office JS `paragraph.startNewList()`: a new list definition (docx4j's default decimal set,
+     * or its bullet set with `{ bullet: true }`) with this paragraph as its first item, adding
+     * the numbering part and its relationship when the document has none.
+     *
+     * Asynchronous where Office JS's is synchronous, since the default definitions are XML to be
+     * unmarshalled (CR-002 section 17).
+     */
+    startNewList(options?: StartListOptions): Promise<List>;
+    /** Office JS `paragraph.attachToList(listId, level)`: this paragraph joins that list. */
+    attachToList(listId: number | string, level?: number): List;
+    /** Office JS `paragraph.detachFromList()`: this paragraph leaves its list. */
+    detachFromList(): void;
+    /**
+     * The same list, starting again at this paragraph: a new `w:num` over the same
+     * `w:abstractNum` with a `w:startOverride` (extension; `List.restart()` is the verb).
+     */
+    restartList(): List;
+    /** The comments anchored in this paragraph, replies nested under their parent. */
+    getComments(): Promise<Comment[]>;
+    /** Comments the whole paragraph (sugar over `getRange().insertComment`). */
+    insertComment(text: string): Promise<Comment>;
+    /**
+     * Wraps this paragraph in a new block-level content control (Office JS
+     * `Paragraph.insertContentControl`), typed for the kind when one is given. The `w:id` is free in
+     * the body. Returns the control.
+     */
+    insertContentControl(kind?: ContentControlType): ContentControl;
     private removeEmptyRuns;
+    /**
+     * 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`.
+     * Returns the `w:del` elements it made, in document order.
+     */
+    private deleteText;
+    /**
+     * Text inserted at `at` as a `w:ins`. A run of this author's own that is already inside a
+     * `w:ins` is extended rather than nested in another one, as Word does. `anchor` is the `w:del`
+     * of a replacement, which the insertion must follow.
+     */
+    private insertTracked;
+    /**
+     * 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.
+     */
+    private isolate;
+    /** Moves the items before `seg` into a run of their own, in front of `seg`'s run. */
+    private splitRunBefore;
+    /** Moves the items after `seg` into a run of their own, behind `seg`'s run. */
+    private splitRunAfter;
 }
 export { W_NS };