@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/document/text-range.d.ts

@@ -0,0 +1,445 @@
+import { FeatureId } from '../../core/registry/feature-registry';
+import { OpenXmlAttribute, OpenXmlElement } from '../../core/xml/index';
+import { CharacterFormat, CharacterFormatDelta, CharacterFormatHost, CharacterFormatSnapshot } from './character-format';
+import { FeatureInline } from './feature-inline';
+import { FeatureRunLeaf } from './feature-run-leaf';
+import { ParagraphItem, ParagraphItemOwner } from './paragraph-item';
+export { ParagraphItem, ParagraphItemOwner } from './paragraph-item';
+import { EntityType } from './entity-type';
+import { Field, FieldMark } from '../fields/paragraph-field';
+/**
+ * Break kind for `w:br` (`ST_BrType` plus the Line default).
+ *
+ * OOXML has no `@w:type="line"` value: a line break is a bare `w:br` (type omitted).
+ * Text-wrapping breaks use `@w:type="textWrapping"`.
+ *
+ * Citation: ECMA-376-1 §17.3.3.1–2; transitional `wml.xsd` `CT_Br` / `ST_BrType`.
+ *
+ * @public
+ */
+export declare const BreakType: {
+    /**
+     * Page break. Maps to `w:br` with `@w:type="page"`.
+     */
+    PageBreak: "page";
+    /**
+     * Column break. Maps to `w:br` with `@w:type="column"`.
+     */
+    ColumnBreak: "column";
+    /**
+     * Line break (Shift+Enter / soft break). Maps to a bare `w:br` (type omitted).
+     */
+    LineBreak: "line";
+    /**
+     * Text-wrapping break. Maps to `w:br` with `@w:type="textWrapping"`.
+     */
+    TextWrappingBreak: "textWrapping";
+};
+/**
+ * Break kind for `w:br`.
+ * @public
+ */
+export declare type BreakType = (typeof BreakType)[keyof typeof BreakType];
+/**
+ * Text-wrapping clear for a line or text-wrapping break (`ST_BrClear`).
+ * Internal / parse-serialize only — not part of the public Break API surface.
+ *
+ * Citation: ECMA-376-1 §17.3.3.2; transitional `wml.xsd` `ST_BrClear`.
+ *
+ * @private
+ */
+export declare const BreakClearType: {
+    None: "none";
+    Left: "left";
+    Right: "right";
+    All: "all";
+};
+/** @private */
+export declare type BreakClearType = (typeof BreakClearType)[keyof typeof BreakClearType];
+/**
+ * @private
+ * Shared identity for paragraph items that serialize inside one physical `w:r`.
+ * Owns `w:rPr` ({@link CharacterFormat}) and unmodeled `w:r` attributes.
+ */
+export declare class WireRunGroup implements CharacterFormatHost {
+    private characterFormatField;
+    private extraAttributesValue;
+    constructor(extraAttributes?: ReadonlyArray<OpenXmlAttribute>);
+    readonly characterFormat: CharacterFormat;
+    readonly extraAttributes: ReadonlyArray<OpenXmlAttribute>;
+    setExtraAttributes(attrs: ReadonlyArray<OpenXmlAttribute>): void;
+    notifyCharacterFormatMutation(): void;
+    hydrateCharacterFormat(data: CharacterFormatSnapshot): void;
+    snapshotCharacterFormat(): CharacterFormatSnapshot;
+}
+/**
+ * @private
+ * Marker on every run-level paragraph item that shares a {@link WireRunGroup}.
+ */
+export interface WireRunMember {
+    /** @private */
+    readonly wireGroup: WireRunGroup;
+}
+/**
+ * @private Base for run-level items that share a WireRunGroup + CharacterFormatHost.
+ */
+declare abstract class WireRunParagraphItem extends ParagraphItem implements CharacterFormatHost, WireRunMember {
+    private wireGroupValue;
+    constructor(wireGroup?: WireRunGroup);
+    /**
+     * @private
+     */
+    readonly wireGroup: WireRunGroup;
+    /**
+     * Character formatting for this item (`w:rPr`), shared with siblings from the same `w:r`.
+     * @public
+     */
+    readonly characterFormat: CharacterFormat;
+    /**
+     * @private
+     */
+    notifyCharacterFormatMutation(): void;
+}
+/**
+ * Tab stop character in a paragraph (`w:r/w:tab`).
+ * @public
+ */
+export declare class Tab extends WireRunParagraphItem {
+    /**
+     * Discriminant for {@link Paragraph.items} / {@link paragraphElementTypeOf}.
+     * @public
+     */
+    readonly type: EntityType.AbsoluteTab;
+    /** @private */
+    constructor(wireGroup?: WireRunGroup);
+}
+/**
+ * Carriage return in a paragraph (`w:r/w:cr`).
+ * @public
+ */
+export declare class CarriageReturn extends WireRunParagraphItem {
+    /**
+     * Discriminant for {@link Paragraph.items} / {@link paragraphElementTypeOf}.
+     * @public
+     */
+    readonly type: 'carriageReturn';
+    /** @private */
+    constructor(wireGroup?: WireRunGroup);
+}
+/**
+ * Symbol character in a paragraph (`w:r/w:sym`).
+ * @public
+ */
+export declare class Symbol extends WireRunParagraphItem {
+    /**
+     * Discriminant for {@link Paragraph.items} / {@link paragraphElementTypeOf}.
+     * @public
+     */
+    readonly type: EntityType.Symbol;
+    private fontValue;
+    private charValue;
+    /**
+     * @private
+     */
+    constructor(font: string, char: string, wireGroup?: WireRunGroup);
+    /**
+     * Symbol font name (`w:font`).
+     * @public
+     */
+    font: string;
+    /**
+     * Character code as `ST_ShortHexNumber` hex digits (`w:char`).
+     * @public
+     */
+    char: string;
+}
+/**
+ * Break in a paragraph (`w:r/w:br` / `CT_Br`).
+ *
+ * Always serialized as run content (`w:r/w:br`). Clear and extras are internal
+ * round-trip state — not part of the public authoring API.
+ *
+ * Citation: ECMA-376-1 §17.3.3.1–2; transitional `wml.xsd` `CT_Br`.
+ *
+ * @public
+ */
+export declare class Break extends WireRunParagraphItem {
+    /**
+     * Discriminant for {@link Paragraph.items} / {@link paragraphElementTypeOf}.
+     * @public
+     */
+    readonly type: EntityType.Break;
+    private breakTypeValue;
+    /** @private Present when clear is not None (`left`|`right`|`all`). */
+    private clearValue;
+    /** @private Unmodeled or unknown attributes (round-trip). */
+    private extrasValue;
+    /**
+     * @private
+     */
+    constructor(breakType: BreakType, clear?: BreakClearType, extras?: ReadonlyArray<OpenXmlAttribute>, wireGroup?: WireRunGroup);
+    /**
+     * Break kind (`ST_BrType` plus the Line default).
+     * @public
+     */
+    breakType: BreakType;
+    /**
+     * @private
+     */
+    readonly clear: Exclude<BreakClearType, typeof BreakClearType.None> | undefined;
+    /**
+     * @private
+     */
+    readonly extras: ReadonlyArray<OpenXmlAttribute>;
+}
+/**
+ * Feature-owned run-level content promoted onto {@link Paragraph.items}
+ * (for example images). Storage uses a private tag; public classifiers map
+ * to domain types.
+ *
+ * @private
+ */
+export declare class FeatureRunParagraphItem extends WireRunParagraphItem {
+    readonly type: 'featureRun';
+    readonly featureId: FeatureId;
+    readonly value: FeatureRunLeaf;
+    /** @private */
+    constructor(featureId: FeatureId, value: FeatureRunLeaf, wireGroup?: WireRunGroup);
+}
+/**
+ * Opaque unmodeled run child preserved for round-trip (`w:r/*`).
+ * @public
+ */
+export declare class OpaqueRunItem extends WireRunParagraphItem {
+    readonly type: 'opaqueRun';
+    readonly xml: OpenXmlElement;
+    /** @private */
+    constructor(xml: OpenXmlElement, wireGroup?: WireRunGroup);
+}
+/**
+ * Feature-owned inline sibling of runs (for example `w:hyperlink`).
+ * Storage uses a private tag; public classifiers map to domain types.
+ *
+ * Concrete feature classes may extend {@link ParagraphItem} directly in a
+ * later cut; this wrapper preserves FeatureInline payloads during migration.
+ *
+ * @private
+ */
+export declare class FeatureInlineParagraphItem extends ParagraphItem {
+    readonly type: 'featureInline';
+    readonly featureId: FeatureId;
+    readonly value: FeatureInline;
+    /** @private */
+    constructor(featureId: FeatureId, value: FeatureInline);
+    /** @private */
+    protected onDetached(): void;
+}
+/**
+ * Opaque unmodeled paragraph child preserved for round-trip.
+ * @public
+ */
+export declare class OpaqueParagraphItem extends ParagraphItem {
+    readonly type: 'opaque';
+    readonly xml: OpenXmlElement;
+    /** @private */
+    constructor(xml: OpenXmlElement);
+}
+export declare function needsXmlSpacePreserve(text: string): boolean;
+/**
+ * Snapshot / hydrate bag for a text range: text content, wire-group linkage, and
+ * character-format fields (merged from {@link CharacterFormat.snapshot}).
+ *
+ * @private
+ */
+interface TextRangeHydrateData extends CharacterFormatSnapshot {
+    extraAttributes: ReadonlyArray<OpenXmlAttribute>;
+    text: string;
+    xmlSpacePreserve: boolean;
+}
+/**
+ * WordprocessingML text range — public face of text + character formatting.
+ *
+ * Physical OOXML remains `w:r` with optional `w:rPr` and `w:t`. Non-text run
+ * children (breaks, tabs, symbols, images, …) appear as sibling
+ * {@link ParagraphItem}s sharing a private {@link WireRunGroup} so serialization
+ * can reconstruct the original run.
+ *
+ * Character formatting lives on {@link TextRange.characterFormat} only
+ * (`docs/specs/run-character-format.md` Rev 2 / TASK-9019).
+ *
+ * @public
+ */
+export declare class TextRange extends WireRunParagraphItem {
+    /**
+     * Discriminant for {@link Paragraph.items} / {@link paragraphElementTypeOf}.
+     * @public
+     */
+    readonly type: EntityType.TextRange;
+    private textValue;
+    private xmlSpacePreserveValue;
+    /**
+     * Create a text range. Prefer `new TextRange(document)` so property setters
+     * work before the range is appended to a paragraph. Passing a paragraph-item
+     * owner attaches immediately (internal / load paths).
+     *
+     * @public
+     */
+    constructor(ownerOrDocument?: ParagraphItemOwner | object, wireGroup?: WireRunGroup);
+    /**
+     * Plain text of this range (`w:t`). Setter replaces the text content.
+     * @public
+     */
+    text: string;
+    /**
+     * Apply character formatting onto this range (DocIO-aligned).
+     *
+     * - {@link CharacterFormatDelta}: merges listed properties (`assign`).
+     * - {@link CharacterFormat}: copies the full snapshot into this range's `rPr`.
+     *
+     * @public
+     */
+    applyCharacterFormat(source: CharacterFormatDelta | CharacterFormat): void;
+    /**
+     * @private
+     */
+    readonly xmlSpacePreserve: boolean;
+    /**
+     * @private Set text during parse without owner mutation checks or CF wipe.
+     */
+    setTextFromParse(text: string, preserveSpace: boolean): void;
+    /**
+     * @private
+     * Advanced hatch: `w:r` tree for a lone text range. Unstable; prefer semantic properties.
+     */
+    toOpenXml(): OpenXmlElement;
+    /**
+     * @private
+     */
+    static fromXml(el: OpenXmlElement, owner: ParagraphItemOwner): TextRange;
+    /**
+     * @private
+     */
+    hydrate(data: TextRangeHydrateData): void;
+    /**
+     * @private
+     */
+    snapshot(): TextRangeHydrateData;
+}
+/**
+ * @private Author a break item under a new wire group (single-item run).
+ */
+export declare function createStandaloneBreakItem(type: BreakType, clear?: BreakClearType): Break;
+/**
+ * @private Author a symbol item under a new wire group.
+ */
+export declare function createStandaloneSymbolItem(font: string, char: string): Symbol;
+/**
+ * @private Author a tab item under a new wire group.
+ */
+export declare function createStandaloneTabItem(): Tab;
+/**
+ * Split plain text on U+0009 into {@link TextRange} and {@link Tab} items that
+ * share one {@link WireRunGroup} (one physical `w:r` with interleaved `w:t` /
+ * `w:tab`). Empty segments around tabs are omitted. Text with no tab characters
+ * yields a single {@link TextRange} (possibly empty). Tab-only text yields only
+ * {@link Tab} items.
+ *
+ * Citation: ECMA-376-1 `EG_RunInnerContent` / `w:tab` (run-level tab character).
+ *
+ * @private
+ */
+export declare function createTextAndTabItems(text: string, wireGroup?: WireRunGroup): ConcreteParagraphItem[];
+/**
+ * Parse a physical `w:r` into one or more flattened {@link ParagraphItem}s that
+ * share character formatting via {@link WireRunGroup}.
+ *
+ * @private
+ */
+export declare function parseTextRangeGroup(el: OpenXmlElement, owner: ParagraphItemOwner | undefined): ConcreteParagraphItem[];
+/**
+ * Serialize a lone {@link TextRange} as a complete `w:r` (rPr + single w:t).
+ * Prefer {@link serializeParagraphItems} when emitting a full paragraph.
+ *
+ * @private
+ */
+export declare function serializeTextRange(textRange: TextRange): OpenXmlElement;
+/**
+ * Serialize flattened paragraph items, regrouping consecutive wire-run members
+ * that share the same {@link WireRunGroup} into physical `w:r` elements.
+ * Field and FieldMark items serialize directly.
+ * TextRange items in field instruction regions serialize as w:instrText.
+ *
+ * @private
+ */
+export declare function serializeParagraphItems(items: ReadonlyArray<ParagraphItem>): OpenXmlElement[];
+/**
+ * @deprecated Prefer {@link Break}. Public break view shape used by older APIs.
+ * @private
+ */
+export interface BreakLeaf {
+    readonly type: 'break';
+    readonly breakType: BreakType;
+    readonly clear: BreakClearType;
+}
+/**
+ * @deprecated Prefer {@link Break}.
+ * @private
+ */
+export declare type BreakItem = Break;
+/**
+ * @deprecated Prefer {@link Tab}.
+ * @private
+ */
+export declare type TabItem = Tab;
+/**
+ * @deprecated Prefer {@link CarriageReturn}.
+ * @private
+ */
+export declare type CarriageReturnItem = CarriageReturn;
+/**
+ * @deprecated Prefer {@link Symbol}.
+ * @private
+ */
+export declare type SymbolItem = Symbol;
+/**
+ * @deprecated Prefer {@link ParagraphItemOwner}.
+ * @private
+ */
+export declare type Owner = ParagraphItemOwner;
+/**
+ * Concrete paragraph-item instances stored on {@link Paragraph.items}.
+ * Discriminated by each subclass’s `type` field for switch/narrowing.
+ *
+ * @public
+ */
+export declare type ConcreteParagraphItem = TextRange | Tab | CarriageReturn | Symbol | Break | FeatureRunParagraphItem | FeatureInlineParagraphItem | OpaqueRunItem | OpaqueParagraphItem | Field | FieldMark;
+/**
+ * @deprecated Prefer {@link ConcreteParagraphItem}.
+ * @private
+ */
+export declare type RunLeaf = ConcreteParagraphItem;
+/**
+ * @deprecated Prefer {@link ConcreteParagraphItem}.
+ * @private
+ */
+export declare type InlineContent = ConcreteParagraphItem;
+/**
+ * @deprecated Prefer {@link TextRange}.
+ * @private
+ */
+export declare const Run: typeof TextRange;
+/**
+ * @deprecated Prefer {@link ParagraphItemOwner}.
+ * @private
+ */
+export declare type RunOwner = ParagraphItemOwner;
+/**
+ * @deprecated Prefer {@link serializeTextRange}.
+ * @private
+ */
+export declare const serializeRun: typeof serializeTextRange;
+/**
+ * Public break view (no extras / wireGroup).
+ * @private
+ */
+export declare function toBreakLeafView(leaf: Break): BreakLeaf;