@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/document/paragraph.d.ts

@@ -0,0 +1,435 @@
+import { WordDocument } from './document';
+import { FeatureId } from '../../core/registry/feature-registry';
+import { OpenXmlAttribute, OpenXmlElement } from '../../core/xml/index';
+import { FeatureBlock } from './feature-block';
+import { FeatureInline } from './feature-inline';
+import { FeatureRunLeaf } from './feature-run-leaf';
+import { CharacterFormat, CharacterFormatHost, CharacterFormatSnapshot } from './character-format';
+import { ParagraphFormat, ParagraphFormatHost, ParagraphFormatSnapshot } from './paragraph-format';
+import { CnfStyle, NormalizedCnfStyle } from '../tables/tbl-pr';
+import { ParagraphItem } from './paragraph-item';
+import { ParagraphItemCollection, ParagraphItemCollectionHost } from './paragraph-item-collection';
+import { Break, BreakClearType, BreakType, ConcreteParagraphItem, FeatureInlineParagraphItem, FeatureRunParagraphItem, Symbol, TextRange } from './text-range';
+/**
+ * @private Registers the ListFormat constructor bridge (called from numbering feature load).
+ */
+export declare function setListFormatFactory(factory: (paragraph: Paragraph) => any): void;
+/**
+ * @private Test-only reset.
+ */
+export declare function resetListFormatFactoryForTests(): void;
+/**
+ * Body child: a modeled paragraph, optional feature block, or preserved unmodeled markup.
+ *
+ * @public
+ */
+export declare type BlockContent = {
+    readonly type: 'paragraph';
+    readonly paragraph: Paragraph;
+} | {
+    readonly type: 'feature';
+    readonly featureId: FeatureId;
+    readonly value: FeatureBlock;
+} | {
+    readonly type: 'opaque';
+    readonly xml: OpenXmlElement;
+};
+export interface ParagraphOwner {
+    assertAttachedParagraph(target: Paragraph): void;
+    /** @private */
+    owningDocument(): WordDocument;
+    /**
+     * Optional body-owner kind used for ownership queries without circular imports.
+     * Table cells set this to `'tableCell'`.
+     *
+     * @private
+     */
+    readonly bodyOwnerKind?: 'tableCell' | string;
+}
+/**
+ * Optional clear for {@link Paragraph.appendBreak} on line / text-wrapping breaks.
+ *
+ * @public
+ */
+export interface AppendBreakOptions {
+    /**
+     * Text-wrapping clear (`ST_BrClear`). Only valid with
+     * {@link BreakType.LineBreak} or {@link BreakType.TextWrappingBreak}.
+     */
+    readonly clear?: BreakClearType;
+}
+/**
+ * WordprocessingML paragraph (`w:p`).
+ *
+ * Paragraph properties live on {@link Paragraph.paragraphFormat} (`w:pPr`).
+ * Paragraph-mark character formatting lives on
+ * {@link Paragraph.breakCharacterFormat} (`w:pPr/w:rPr`). Text-range character
+ * formatting remains on {@link TextRange.characterFormat} (`w:r/w:rPr`).
+ *
+ * Items appear directly on {@link Paragraph.items} — there is no nested run
+ * collection. Physical `w:r` grouping is reconstructed on serialize.
+ *
+ * @public
+ */
+export declare class Paragraph implements ParagraphFormatHost, CharacterFormatHost, ParagraphItemCollectionHost {
+    private owner;
+    private extraAttributes;
+    private styleIdValue;
+    private numIdValue;
+    private listLevelValue;
+    private numPrExtra;
+    private sectionBreakSectPrElement;
+    /** Live section-break model from the optional sections feature (not XML). */
+    private sectionBreakPropertiesModelValue;
+    /**
+     * Stable paragraph-item collection. Never replaced after construction —
+     * hydrate/clear mutate contents in place.
+     */
+    private readonly paragraphItems;
+    /** TASK-9020-B: all typed `w:pPr` formatting state lives on ParagraphFormat. */
+    private paragraphFormatField;
+    /** Paragraph-mark character formatting (`w:pPr/w:rPr`). */
+    private breakCharacterFormatField;
+    /** Paragraph list formatting (`w:numPr`). */
+    private listFormatField;
+    /** @private */
+    constructor(owner: ParagraphOwner | undefined);
+    /**
+     * The direct paragraph formatting (`w:pPr`) of this paragraph — the only
+     * public paragraph-formatting surface.
+     *
+     * A live view over the typed `w:pPr` state: every read/write goes to the
+     * same storage the parser fills and the serializer reads. Lazily created
+     * on first access and cached; never null.
+     *
+     * Mutating it validates attachment — writes on a detached paragraph throw
+     * {@link DetachedObjectError}.
+     *
+     * @example
+     * ```ts
+     * paragraph.paragraphFormat.beforeSpacing = 18;
+     * paragraph.paragraphFormat.lineSpacing = 10;
+     * paragraph.paragraphFormat.firstLineIndent = 10; // negative = hanging
+     * paragraph.paragraphFormat.backColor = 'D3D3D3';
+     * ```
+     *
+     * @public
+     */
+    readonly paragraphFormat: ParagraphFormat;
+    /**
+     * Character formatting of the paragraph mark (`w:pPr/w:rPr`).
+     *
+     * Reuses the same {@link CharacterFormat} type as {@link TextRange.characterFormat}.
+     * Lazily constructed; never null. Empty format does not emit an empty `w:rPr`.
+     *
+     * @example
+     * ```ts
+     * paragraph.breakCharacterFormat.bold = true;
+     * paragraph.breakCharacterFormat.italic = true;
+     * paragraph.breakCharacterFormat.fontSize = 14;
+     * ```
+     *
+     * @public
+     */
+    readonly breakCharacterFormat: CharacterFormat;
+    /**
+     * Paragraph list formatting (`w:numPr`).
+     *
+     * A live list-format interface for applying and modifying numbering and
+     * bullet formatting on this paragraph. Lazily created on first access
+     * and cached; never null.
+     *
+     * @example
+     * ```ts
+     * paragraph.listFormat.applyDefBulletStyle();
+     * paragraph.listFormat.increaseIndentLevel();
+     * paragraph.listFormat.listId = 5;
+     * ```
+     *
+     * @public
+     */
+    readonly listFormat: import('../numbering/list-format').ListFormat;
+    /** @private ParagraphFormatHost — mutation notification + detachment guard. */
+    notifyParagraphFormatMutation(): void;
+    /** @private CharacterFormatHost — mark rPr mutation notification. */
+    notifyCharacterFormatMutation(): void;
+    /** @private */
+    detach(): void;
+    /** @private */
+    attach(owner: ParagraphOwner): void;
+    /**
+     * @private ParagraphItemOwner — gate item property mutation.
+     */
+    assertAttachedItem(target: ParagraphItem): void;
+    /**
+     * @private Gate paragraph-level authoring.
+     */
+    assertMutable(): void;
+    private mutate;
+    /** @private */
+    owningDocument(): WordDocument;
+    /**
+     * Gets or sets the identifier of the paragraph style applied to this paragraph.
+     *
+     * If undefined, no paragraph style is applied and formatting comes from the
+     * document defaults. The identifier must name a style that exists in the
+     * document when the file is saved.
+     *
+     * @defaultValue No paragraph style when omitted (body text formatting).
+     *
+     * @public
+     */
+    styleId: string | undefined;
+    /**
+     * Applies a paragraph style by id or BuiltInStyle.
+     * Implementation is registered by the styles feature (writes resolved styleId only).
+     * @public
+     */
+    applyStyle(_style: string): void;
+    /**
+     * @private Optional CharacterFormatHost effective resolver (overwritten by styles feature).
+     */
+    resolveEffectiveCharacterValue?(_key: string): unknown;
+    /**
+     * @private Optional ParagraphFormatHost effective resolver (overwritten by styles feature).
+     */
+    resolveEffectiveParagraphValue?(_key: string): unknown;
+    /**
+     * @private
+     * Direct `w:numPr/w:numId/@w:val`. `undefined` means absent (not in a list). */
+    /**
+    * @private
+    * Direct `w:numPr/w:numId/@w:val`. `undefined` means absent (not in a list). */
+    numId: number | undefined;
+    /**
+     * Zero-based list level (`w:ilvl`). Prefer {@link listFormat.listLevelNumber}.
+     *
+     * @private
+     */
+    /**
+    * @private
+    */
+    listLevel: number | undefined;
+    /**
+     * @private
+     * Conditional table-style membership on `w:pPr/w:cnfStyle`.
+     */
+    getConditionalFormatting(): CnfStyle | undefined;
+    /**
+     * @private
+     * Set or clear conditional table-style membership on this paragraph.
+     * Does not call {@link mutate} beyond ParagraphFormat's write path so
+     * detached table rebuilds during calculation can still write masks.
+     */
+    setConditionalFormatting(state: NormalizedCnfStyle | CnfStyle | undefined): void;
+    /**
+     * True when this paragraph’s nearest body owner is a table cell
+     * (including nested table cells). False for body, header/footer, text box,
+     * footnote, endnote, or detached paragraphs.
+     *
+     * @public
+     */
+    readonly isInCell: boolean;
+    /** @private Paragraph section-break `w:pPr/w:sectPr`, when present. */
+    sectionBreakSectPr(): OpenXmlElement | undefined;
+    /**
+     * @private
+     * Replace paragraph section-break `w:sectPr`.
+     *
+     * Load/partition/flatten may dual-hold before the paragraph is attached to a
+     * body (parse uses a detached context; save may append an empty terminator).
+     * When already attached, still assert ownership via {@link mutate}.
+     */
+    replaceSectionBreakSectPr(value: OpenXmlElement | undefined): void;
+    /**
+     * @private
+     * Live paragraph section-break properties model (sections feature), if any.
+     */
+    sectionBreakPropertiesModel(): {
+        toOpenXml(): OpenXmlElement;
+    } | undefined;
+    /**
+     * @private
+     * Attach or clear the live paragraph section-break properties model.
+     * When set, clears preserved `w:sectPr` XML so the model is the sole source of truth.
+     *
+     * Same attach rules as {@link replaceSectionBreakSectPr}: dual-hold is allowed
+     * before body ownership is established (TASK-8075 partition/flatten).
+     */
+    replaceSectionBreakPropertiesModel(value: {
+        toOpenXml(): OpenXmlElement;
+    } | undefined): void;
+    /**
+     * Ordered paragraph items (text ranges, breaks, tabs, symbols, feature
+     * content, opaque markup) in document order.
+     *
+     * Stable collection identity for the life of the paragraph. Physical `w:r`
+     * grouping is reconstructed on serialize via shared wire groups.
+     *
+     * @public
+     */
+    readonly items: ParagraphItemCollection;
+    /**
+     * Gets the concatenated plain text of modeled text ranges and tab characters
+     * in document order.
+     *
+     * Opaque and feature inlines (for example hyperlinks owned by feature modules)
+     * are skipped. Field instruction text is also skipped; only field result text
+     * is included. {@link Tab} items contribute U+0009 so plain-text views match
+     * run-level tab characters authored via {@link appendText} or loaded from
+     * `w:tab`.
+     *
+     * @public
+     */
+    readonly text: string;
+    /**
+     * Appends an empty text range to the end of this paragraph and returns it.
+     *
+     * @returns The newly created empty text range.
+     * @throws DetachedObjectError if this paragraph is no longer attached to a document.
+     *
+     * @public
+     */
+    appendTextRange(): TextRange;
+    /**
+     * Append text as one or more paragraph items, optionally with common character
+     * formatting. U+0009 (tab) characters become dedicated {@link Tab} items
+     * (`w:r/w:tab`) interleaved with {@link TextRange} segments that share one
+     * wire run group, matching Word / OOXML run-inner content.
+     *
+     * @returns The first {@link TextRange} created for non-empty text segments, or
+     * an empty trailing {@link TextRange} when `text` is empty or tab-only (so the
+     * return type stays {@link TextRange}).
+     *
+     * @public
+     */
+    appendText(text: string, options?: {
+        readonly bold?: boolean;
+        readonly italic?: boolean;
+        readonly fontSize?: number;
+    }): TextRange;
+    /**
+     * Append a break (`w:br`) as a direct paragraph item.
+     *
+     * Always run content on the wire (`w:r/w:br`), never a paragraph-level
+     * sibling of `w:r`. Serialization rebuilds the physical run.
+     *
+     * @param type - Break kind ({@link BreakType}).
+     * @param options - Optional text-wrapping clear (Line / TextWrappingBreak only).
+     * @returns The break item.
+     * @throws DocxError `content/invalid-break` if `clear` is set on Page or Column.
+     *
+     * @example
+     * ```ts
+     * paragraph.appendBreak(BreakType.PageBreak);
+     * paragraph.appendBreak(BreakType.LineBreak, { clear: BreakClearType.All });
+     * ```
+     *
+     * @public
+     */
+    appendBreak(type: BreakType, options?: AppendBreakOptions): Break;
+    /**
+     * Append a symbol character (`w:sym`) as a direct paragraph item.
+     *
+     * Always run content on the wire (`w:r/w:sym`, ECMA-376-1 §17.3.3.30).
+     *
+     * @param font - Symbol font name (`w:font`), for example `"Wingdings"`.
+     * @param char - `ST_ShortHexNumber` hex digits for `w:char` (four hex digits, e.g. `"F0FC"`).
+     * @returns The symbol paragraph item that was created.
+     *
+     * @example
+     * ```ts
+     * paragraph.appendText('checkmark: ');
+     * paragraph.appendSymbol('Wingdings', 'F0FC');
+     * ```
+     *
+     * @public
+     */
+    appendSymbol(font: string, char: string): Symbol;
+    /**
+     * Appends a feature-owned run-level item (for example an image) as a direct
+     * paragraph child. Serializes inside a physical `w:r` via its wire group.
+     *
+     * @private
+     */
+    appendFeatureRunItem(featureId: FeatureId, value: FeatureRunLeaf): FeatureRunParagraphItem;
+    /**
+     * Appends a feature-owned inline sibling (for example `w:hyperlink`).
+     *
+     * @private
+     */
+    appendFeatureInline(featureId: FeatureId, value: FeatureInline): FeatureInlineParagraphItem;
+    /**
+     * Inserts a feature-owned inline at a raw content index (`0…items.count` inclusive).
+     *
+     * @private
+     */
+    insertFeatureInlineAt(index: number, featureId: FeatureId, value: FeatureInline): FeatureInlineParagraphItem;
+    /** @private Remove a feature inline from this paragraph. */
+    removeFeatureInline(value: FeatureInline): void;
+    /**
+     * @private Remove a feature run-level item (image, drawing residual, …).
+     */
+    removeFeatureRunItem(value: FeatureRunLeaf): void;
+    /**
+     * @private Append a pre-built paragraph item (feature modules).
+     */
+    appendParagraphItem(item: ConcreteParagraphItem): void;
+    /**
+     * @private Remove a text range by identity.
+     */
+    removeTextRange(run: TextRange): void;
+    /**
+     * Advanced hatch: `w:p` tree. Unstable; prefer semantic properties.
+     */
+    toOpenXml(): OpenXmlElement;
+    /** @private */
+    static fromXml(el: OpenXmlElement, owner: ParagraphOwner): Paragraph;
+    /** @private */
+    hydrate(data: {
+        extraAttributes: ReadonlyArray<OpenXmlAttribute>;
+        styleIdValue: string | undefined;
+        numIdValue: number | undefined;
+        listLevelValue: number | undefined;
+        numPrExtra: OpenXmlElement[];
+        sectionBreakSectPr: OpenXmlElement | undefined;
+        items: ConcreteParagraphItem[];
+        paragraphFormat: ParagraphFormatSnapshot;
+        breakCharacterFormat?: CharacterFormatSnapshot;
+    }): void;
+    /** @private */
+    snapshot(): {
+        extraAttributes: ReadonlyArray<OpenXmlAttribute>;
+        styleIdValue: string | undefined;
+        numIdValue: number | undefined;
+        listLevelValue: number | undefined;
+        numPrExtra: OpenXmlElement[];
+        sectionBreakSectPr: OpenXmlElement | undefined;
+        items: ConcreteParagraphItem[];
+        paragraphFormat: ParagraphFormatSnapshot;
+        breakCharacterFormat: CharacterFormatSnapshot;
+    };
+}
+/**
+ * Serialize a paragraph. `w:pPr` children after `pStyle` come from
+ * {@link ParagraphFormat.buildPPrChildren} (CT_PPr order; TASK-9020-D).
+ * Mark `w:rPr` is injected from {@link Paragraph.breakCharacterFormat}.
+ */
+export declare function serializeParagraph(paragraph: Paragraph): OpenXmlElement;
+/**
+ * True when {@link ParagraphFormat.pageBreakAfter} should emit a dedicated
+ * following paragraph containing only `w:br/@w:type="page"`.
+ *
+ * Skips when the content paragraph already contains a page-break item so
+ * authoring does not duplicate breaks.
+ *
+ * @private
+ */
+export declare function shouldEmitPageBreakAfterParagraph(paragraph: Paragraph): boolean;
+/**
+ * Build a standalone `w:p` whose only content is a page break run.
+ * Used after a content paragraph when {@link shouldEmitPageBreakAfterParagraph}.
+ *
+ * @private
+ */
+export declare function createPageBreakAfterParagraphElement(): OpenXmlElement;