@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/document/body.js

@@ -0,0 +1,263 @@
+import { BodyItemCollection } from './body-item-collection';
+import { Paragraph } from './paragraph';
+import { ParagraphCollection } from './typed-body-collections';
+import { DetachedObjectError } from '../../core/errors/docx-error';
+/**
+ * Section body (`w:body` story content for one section).
+ *
+ * Collection owner only: mutate through {@link Body.items}
+ * ({@link BodyItemCollection}). The internal ordered store holds
+ * {@link BlockContent} wrappers for parse/serialize; the public collection
+ * projects {@link import('./body-item').BodyItem} instances.
+ *
+ * Temporary bridges until TASK-8076: {@link Body.paragraphs},
+ * {@link Body.appendParagraph}. Prefer {@link Body.items} for insert/remove.
+ *
+ * @public
+ */
+var Body = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function Body(document, items, section) {
+        if (items === void 0) { items = []; }
+        this.document = document;
+        this.section = section;
+        this.itemList = items.slice();
+        this.itemsInstance = new BodyItemCollection(this);
+        this.paragraphsInstance = new ParagraphCollection(this.itemsInstance, function () { return new Paragraph(undefined); });
+        // Constructor path bypasses BodyItemCollection.insert, so attach
+        // paragraphs here (table cells, section load helpers, etc.).
+        for (var i = 0; i < this.itemList.length; i += 1) {
+            var block = this.itemList[i];
+            if (block.type === 'paragraph') {
+                block.paragraph.attach(this);
+            }
+        }
+    }
+    Object.defineProperty(Body.prototype, "items", {
+        /**
+         * Managed mutable collection of public body items (paragraphs, tables,
+         * block content controls). Same instance on every access.
+         */
+        get: function () {
+            return this.itemsInstance;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(Body.prototype, "paragraphs", {
+        /**
+         * Paragraphs in this body (filtered view over {@link Body.items}).
+         *
+         * Temporary bridge until TASK-8076 — prefer {@link Section.paragraphs}
+         * when using the sections spine.
+         */
+        get: function () {
+            return this.paragraphsInstance;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     * Owning section when this body is attached under a {@link Section}.
+     */
+    Body.prototype.owningSection = function () {
+        return this.section;
+    };
+    /**
+     * @private
+     */
+    Body.prototype.setOwningSection = function (section) {
+        this.section = section;
+    };
+    /**
+     * @private
+     */
+    Body.prototype.setOwningDocument = function (document) {
+        this.document = document;
+    };
+    /**
+     * @private
+     * Document that owns this body (via section or direct bind during load).
+     */
+    Body.prototype.owningDocument = function () {
+        if (this.section !== undefined) {
+            return this.section.owningDocument();
+        }
+        if (this.document !== undefined) {
+            return this.document;
+        }
+        throw new DetachedObjectError('Body is not attached to a document');
+    };
+    /**
+     * @private
+     */
+    Body.prototype.rawBlocks = function () {
+        return this.itemList;
+    };
+    /**
+     * @private
+     */
+    Body.prototype.replaceRawBlocks = function (blocks) {
+        this.itemList = blocks.slice();
+    };
+    /**
+     * @private
+     */
+    Body.prototype.assertAttachedParagraph = function (target) {
+        var found = this.itemList.some(function (b) { return b.type === 'paragraph' && b.paragraph === target; });
+        if (!found) {
+            throw new DetachedObjectError('This paragraph is no longer in the document');
+        }
+    };
+    /**
+     * @private
+     * Full internal store (paragraphs, features, opaque) for serialize/load.
+     */
+    Body.prototype.listBlocks = function () {
+        return this.itemList;
+    };
+    /**
+     * @private
+     * Replace the entire internal store (load / section partition helpers).
+     */
+    Body.prototype.replaceItems = function (items) {
+        var previous = this.itemList;
+        for (var i = 0; i < previous.length; i += 1) {
+            var block = previous[i];
+            if (block.type === 'paragraph') {
+                // Only detach paragraphs that are leaving this body.
+                var stillPresent = false;
+                for (var j = 0; j < items.length; j += 1) {
+                    var next = items[j];
+                    if (next.type === 'paragraph' && next.paragraph === block.paragraph) {
+                        stillPresent = true;
+                        break;
+                    }
+                }
+                if (!stillPresent) {
+                    block.paragraph.detach();
+                }
+            }
+        }
+        this.itemList = items.slice();
+        for (var i = 0; i < this.itemList.length; i += 1) {
+            var block = this.itemList[i];
+            if (block.type === 'paragraph') {
+                block.paragraph.attach(this);
+            }
+        }
+        this.itemsInstance.syncFromHost();
+        this.syncTypedViews();
+    };
+    /**
+     * @private
+     * Append an internal block (feature/load bridge — not a public Body mutator).
+     * Typed views refresh via {@link notifyBodyItemsChanged} from the item collection.
+     */
+    Body.prototype.appendRawBlock = function (block) {
+        this.itemsInstance.appendRawBlock(block);
+    };
+    /**
+     * @private
+     */
+    Body.prototype.insertRawBlockAt = function (index, block) {
+        this.itemsInstance.insertRawBlockAt(index, block);
+    };
+    /**
+     * @private
+     */
+    Body.prototype.removeRawBlockAt = function (index) {
+        this.itemsInstance.removeRawBlockAt(index);
+    };
+    /**
+     * @private
+     * Paragraph instances in store order (internal bridge).
+     */
+    Body.prototype.listParagraphs = function () {
+        var out = [];
+        for (var i = 0; i < this.itemList.length; i += 1) {
+            var block = this.itemList[i];
+            if (block.type === 'paragraph') {
+                out.push(block.paragraph);
+            }
+        }
+        return out;
+    };
+    /**
+     * Appends an empty `w:p` after existing body children (before preserved `sectPr`).
+     *
+     * Temporary bridge until TASK-8076.
+     *
+     * @param options - Optional paragraph style id and/or initial text.
+     * @returns The appended {@link Paragraph}.
+     */
+    Body.prototype.appendParagraph = function (options) {
+        var paragraph = this.paragraphsInstance.add();
+        if ((options == null ? undefined : options.style) !== undefined) {
+            // Route through the styles facade (`Paragraph.style`) so built-in
+            // ids/display-names resolve eagerly; do not assign `styleId` raw.
+            paragraph.applyStyle(options.style);
+        }
+        if ((options == null ? undefined : options.text) !== undefined) {
+            paragraph.appendText(options.text);
+        }
+        return paragraph;
+    };
+    /**
+     * Inserts an empty paragraph among existing paragraphs.
+     *
+     * @private
+     * Not part of the customer Body surface (API-RULES). Prefer
+     * {@link Body.items} or {@link Body.paragraphs} collection verbs.
+     *
+     * @param index - Index in {@link Body.paragraphs}, `0…count` inclusive.
+     * @throws RangeError if `index` is out of range.
+     */
+    Body.prototype.insertParagraph = function (index) {
+        return this.paragraphsInstance.insert(index);
+    };
+    /**
+     * Removes a paragraph. Further mutation of it throws {@link DetachedObjectError}.
+     *
+     * @private
+     * Not part of the customer Body surface (API-RULES). Prefer
+     * {@link Body.items} or {@link Body.paragraphs} collection verbs.
+     */
+    Body.prototype.removeParagraph = function (paragraph) {
+        this.paragraphsInstance.remove(paragraph);
+    };
+    /**
+     * @private
+     * Refresh typed views after raw mutations that bypass Body helpers.
+     */
+    Body.prototype.syncParagraphs = function () {
+        this.syncTypedViews();
+    };
+    /**
+     * @private
+     * Invoked by {@link BodyItemCollection} after public/raw item mutations so
+     * body paragraphs and section typed views stay aligned with `items`.
+     */
+    Body.prototype.notifyBodyItemsChanged = function () {
+        this.syncTypedViews();
+    };
+    /**
+     * @private
+     * Rebuild body paragraph indexes and, when this body is a section main
+     * story, section typed views (`paragraphs` / `tables` / block CCs).
+     * Cell bodies (`TableCell extends Body`) have no owning section — only
+     * local paragraphs refresh.
+     */
+    Body.prototype.syncTypedViews = function () {
+        this.paragraphsInstance.syncFromHost();
+        var section = this.owningSection();
+        if (section !== undefined) {
+            section.syncCollections();
+        }
+    };
+    return Body;
+}());
+export { Body };

package/src/features/document/character-format.d.ts

@@ -0,0 +1,413 @@
+/**
+ * Character formatting for a run (`w:rPr`).
+ *
+ * Sole public surface for run properties. Owned by {@link Run}; never null once
+ * accessed via {@link Run.characterFormat}.
+ *
+ * Citation: ECMA-376-1 §17.3.2; TASK-9019 / docs/specs/run-character-format.md Rev 2.
+ *
+ * @public
+ */
+import { OpenXmlElement } from '../../core/xml/index';
+import { HalfPoints } from './length';
+import { Color } from './color';
+import { LocaleIDs } from './locale-ids';
+import { SubSuperScript } from './sub-super-script';
+import { UnderlineStyle } from './underline-style';
+export { SubSuperScript } from './sub-super-script';
+/**
+ * Emphasis mark (`ST_Em`). §17.18.24
+ * @public
+ */
+export declare type EmphasisMarkValue = 'none' | 'dot' | 'comma' | 'circle' | 'underDot';
+/**
+ * Animated text effect (`ST_TextEffect`). §17.18.91
+ * @public
+ */
+export declare type TextEffectValue = 'none' | 'blinkBackground' | 'lights' | 'antsBlack' | 'antsRed' | 'shimmer' | 'sparkle' | 'movie';
+/**
+ * Run character border (`w:bdr`). §17.3.2.5
+ * @public
+ */
+export interface RunBorderEdge {
+    /** `@w:val` — border style (`ST_Border`). */
+    readonly style: string;
+    /** `@w:color` — hex color or `'auto'`. */
+    readonly color?: string;
+    /** `@w:sz` — border width in eighths-of-a-point. */
+    readonly size?: number;
+    /** `@w:space` — space from text in points. */
+    readonly space?: number;
+}
+/**
+ * Run language wire record (`w:lang`). §17.3.2.20
+ *
+ * Internal / snapshot only. Public API uses {@link LocaleIDs} via
+ * `localeId` / `localeIdBidi` / `localeIdFarEast`.
+ *
+ * @private
+ */
+export interface RunLanguage {
+    /** `@w:val` — BCP 47 language tag for Latin text. */
+    readonly latin?: string;
+    /** `@w:bidi` — BCP 47 language tag for bidirectional text. */
+    readonly bidi?: string;
+    /** `@w:eastAsia` — BCP 47 language tag for East Asian text. */
+    readonly eastAsia?: string;
+}
+/**
+ * Batch-assign delta for {@link CharacterFormat.assign}.
+ * @public
+ */
+export interface CharacterFormatDelta {
+    bold?: boolean;
+    italic?: boolean;
+    strikethrough?: boolean;
+    doubleStrikethrough?: boolean;
+    allCaps?: boolean;
+    smallCaps?: boolean;
+    hidden?: boolean;
+    emboss?: boolean;
+    engrave?: boolean;
+    outline?: boolean;
+    shadow?: boolean;
+    noProof?: boolean;
+    webHidden?: boolean;
+    fontSize?: number;
+    fontName?: string;
+    fontNameBidi?: string;
+    underlineStyle?: UnderlineStyle;
+    underlineColor?: Color;
+    textColor?: Color;
+    highlightColor?: Color;
+    textBackgroundColor?: Color;
+    subSuperScript?: SubSuperScript;
+    characterSpacing?: number;
+    position?: number;
+    kerning?: number;
+    scaling?: number;
+    border?: RunBorderEdge;
+    localeId?: LocaleIDs;
+    localeIdBidi?: LocaleIDs;
+    localeIdFarEast?: LocaleIDs;
+    characterStyle?: string;
+    bidi?: boolean;
+    complexScript?: boolean;
+    boldBidi?: boolean;
+    italicBidi?: boolean;
+    fontSizeBidi?: number;
+    emphasisMark?: EmphasisMarkValue;
+    textEffect?: TextEffectValue;
+}
+/**
+ * Host that owns a {@link CharacterFormat} and receives mutation notifications.
+ * @private
+ */
+export interface CharacterFormatHost {
+    notifyCharacterFormatMutation(): void;
+    /**
+     * Optional effective resolver (Paragraph host). Style-hosted CF must omit this
+     * so public getters stay direct/authored-only for style-chain walks.
+     * @private
+     */
+    resolveEffectiveCharacterValue?(key: string): unknown;
+}
+/** @private Internal fonts record (`w:rFonts`). */
+export interface CharacterFontsRecord {
+    ascii?: string;
+    hAnsi?: string;
+    cs?: string;
+    eastAsia?: string;
+    hint?: string;
+    asciiTheme?: string;
+    hAnsiTheme?: string;
+    eastAsiaTheme?: string;
+    cTheme?: string;
+}
+/** @private Internal shading record (`w:shd`). */
+export interface CharacterShadingRecord {
+    fill?: string;
+    color?: string;
+    pattern?: string;
+}
+/**
+ * @private
+ * Formatting snapshot for hydrate/serialize (CharacterFormat module).
+ */
+export interface CharacterFormatSnapshot {
+    rPrExtra: OpenXmlElement[];
+    styleIdValue: string | undefined;
+    boldValue: boolean | undefined;
+    italicValue: boolean | undefined;
+    strikeValue: boolean | undefined;
+    doubleStrikeValue: boolean | undefined;
+    vanishValue: boolean | undefined;
+    /** Legacy `w:hidden` for round-trip only (public `hidden` maps to `w:vanish`). */
+    legacyHiddenValue: boolean | undefined;
+    noProofValue: boolean | undefined;
+    fontSizeValue: HalfPoints | undefined;
+    fontSizeBidiValue: HalfPoints | undefined;
+    textColorValue: string | undefined;
+    textColorTheme: string | undefined;
+    /** Wire highlight name (`ST_HighlightColor`). */
+    highlightValue: string | undefined;
+    shadingValue: CharacterShadingRecord | undefined;
+    /** Wire underline style (`ST_Underline`). */
+    underlineStyleValue: string | undefined;
+    underlineColorValue: string | undefined;
+    /** Wire vertAlign (`ST_VerticalAlignRun`). */
+    vertAlignValue: string | undefined;
+    smallCapsValue: boolean | undefined;
+    allCapsValue: boolean | undefined;
+    fontsValue: CharacterFontsRecord | undefined;
+    characterScaleValue: number | undefined;
+    kerningValue: number | undefined;
+    characterSpacingValue: number | undefined;
+    positionValue: number | undefined;
+    borderValue: RunBorderEdge | undefined;
+    languageValue: RunLanguage | undefined;
+    embossValue: boolean | undefined;
+    imprintValue: boolean | undefined;
+    outlineValue: boolean | undefined;
+    shadowValue: boolean | undefined;
+    webHiddenValue: boolean | undefined;
+    bidiValue: boolean | undefined;
+    complexScriptValue: boolean | undefined;
+    boldBidiValue: boolean | undefined;
+    italicBidiValue: boolean | undefined;
+    emphasisValue: EmphasisMarkValue | undefined;
+    textEffectValue: TextEffectValue | undefined;
+    specVanishValue: boolean | undefined;
+    snapToGridValue: boolean | undefined;
+}
+/**
+ * Parse `w:rPr` children into a {@link CharacterFormatSnapshot}.
+ * Invalid modeled markup is parked in `rPrExtra` (never throws on load).
+ *
+ * @private
+ */
+export declare function parseCharacterFormat(rPrElement: OpenXmlElement): CharacterFormatSnapshot;
+/**
+ * Build `w:rPr` children in Spec §7.2 house order.
+ * @private
+ */
+export declare function buildRPrChildrenFromSnapshot(snap: CharacterFormatSnapshot): OpenXmlElement[];
+/**
+ * Character formatting model for a run (`w:rPr`).
+ *
+ * @public
+ */
+export declare class CharacterFormat {
+    private readonly host;
+    private rPrExtra;
+    private styleIdValue;
+    private boldValue;
+    private italicValue;
+    private strikeValue;
+    private doubleStrikeValue;
+    /** Public `hidden` → `w:vanish`. */
+    private vanishValue;
+    /** Legacy `w:hidden` only (not public). */
+    private legacyHiddenValue;
+    private noProofValue;
+    private fontSizeValue;
+    private fontSizeBidiValue;
+    private textColorValue;
+    private textColorTheme;
+    private highlightValue;
+    private shadingValue;
+    private underlineStyleValue;
+    private underlineColorValue;
+    private vertAlignValue;
+    private smallCapsValue;
+    private allCapsValue;
+    private fontsValue;
+    private characterScaleValue;
+    private kerningValue;
+    private characterSpacingValue;
+    private positionValue;
+    private borderValue;
+    private languageValue;
+    private embossValue;
+    private imprintValue;
+    private outlineValue;
+    private shadowValue;
+    private webHiddenValue;
+    private bidiValue;
+    private complexScriptValue;
+    private boldBidiValue;
+    private italicBidiValue;
+    private emphasisValue;
+    private textEffectValue;
+    private specVanishValue;
+    private snapToGridValue;
+    /**
+     * @private
+     */
+    constructor(host: CharacterFormatHost);
+    private mutate;
+    private effective;
+    private effectiveOrDefault;
+    /** Direct `w:b` (`CT_OnOff`). `undefined` means absent. */
+    bold: boolean | undefined;
+    /** Direct `w:i` (`CT_OnOff`). `undefined` means absent. */
+    italic: boolean | undefined;
+    /** Direct `w:strike` (`CT_OnOff`). Setter clears `doubleStrikethrough` when set true. */
+    strikethrough: boolean | undefined;
+    /** Direct `w:dstrike`. Setter clears `strikethrough` when set true. */
+    doubleStrikethrough: boolean | undefined;
+    /** Direct `w:caps`. Setter clears `smallCaps` when set true (not on hydrate). */
+    allCaps: boolean | undefined;
+    /** Direct `w:smallCaps`. Setter clears `allCaps` when set true (not on hydrate). */
+    smallCaps: boolean | undefined;
+    /**
+     * Hidden text. Maps to `w:vanish` (Spec §4.1 #7).
+     * `undefined` means absent.
+     */
+    hidden: boolean | undefined;
+    /** Direct `w:emboss`. Setter clears engrave/outline/shadow when true (not on hydrate). */
+    emboss: boolean | undefined;
+    /** Direct `w:imprint` (engrave). Member of legacy effect group. */
+    engrave: boolean | undefined;
+    /** Direct `w:outline`. */
+    outline: boolean | undefined;
+    /** Direct `w:shadow`. */
+    shadow: boolean | undefined;
+    /** Direct `w:noProof`. */
+    noProof: boolean | undefined;
+    /** Direct `w:webHidden`. */
+    webHidden: boolean | undefined;
+    /** Font size in points (`w:sz` half-points). Range (0, 1638]. */
+    fontSize: number;
+    /**
+     * Font name (`w:rFonts` ascii + hAnsi).
+     * Setter also writes eastAsia/cs only when those slots are already set.
+     */
+    fontName: string;
+    /**
+     * @private
+     * `w:rFonts/@w:ascii`
+     */
+    /**
+    * @private
+    */
+    fontNameAscii: string;
+    /**
+     * @private
+     * `w:rFonts/@w:hAnsi`
+     */
+    /**
+    * @private
+    */
+    fontNameNonFarEast: string;
+    /**
+     * @private
+     * `w:rFonts/@w:eastAsia`
+     */
+    /**
+    * @private
+    */
+    fontNameFarEast: string;
+    /** Complex-script font (`w:rFonts/@w:cs`). */
+    fontNameBidi: string;
+    /** Underline style (`w:u/@w:val`). */
+    underlineStyle: UnderlineStyle;
+    /** Underline color (`w:u/@w:color`). */
+    underlineColor: Color;
+    /** Text color (`w:color/@w:val`). Setting clears theme color. */
+    textColor: Color;
+    /** Highlight color (`w:highlight`). */
+    highlightColor: Color;
+    /**
+     * Text background (`w:shd/@w:fill`). Authoring writes `val="clear"` + fill.
+     */
+    textBackgroundColor: Color;
+    /** Sub/superscript (`w:vertAlign`). */
+    subSuperScript: SubSuperScript;
+    /** Character spacing in points (`w:spacing` twips). Range ±1584. */
+    characterSpacing: number;
+    /** Raised/lowered position in points (`w:position` half-points). Range ±1584. */
+    position: number;
+    /** Kerning threshold in points (`w:kern` half-points). */
+    kerning: number;
+    /** Character scale percentage (`w:w`). Integer 1–600. */
+    scaling: number;
+    /** Character border (`w:bdr`). */
+    border: RunBorderEdge | undefined;
+    /**
+     * Latin locale id (`w:lang/@w:val` as {@link LocaleIDs}).
+     * @public
+     */
+    localeId: LocaleIDs;
+    /**
+     * Bidirectional locale id (`w:lang/@w:bidi` as {@link LocaleIDs}).
+     * @public
+     */
+    localeIdBidi: LocaleIDs;
+    /**
+     * East Asian locale id (`w:lang/@w:eastAsia` as {@link LocaleIDs}).
+     * @public
+     */
+    localeIdFarEast: LocaleIDs;
+    /** Character style id (`w:rStyle/@w:val`). */
+    characterStyle: string | undefined;
+    /** Bidirectional (`w:rtl`). */
+    bidi: boolean | undefined;
+    /** Complex script (`w:cs`). */
+    complexScript: boolean | undefined;
+    /** Bold complex script (`w:bCs`). */
+    boldBidi: boolean | undefined;
+    /** Italic complex script (`w:iCs`). */
+    italicBidi: boolean | undefined;
+    /** Complex-script font size in points (`w:szCs`). Range (0, 1638]. */
+    fontSizeBidi: number;
+    /** Emphasis mark (`w:em`). */
+    emphasisMark: EmphasisMarkValue;
+    /** Animated text effect (`w:effect`). */
+    textEffect: TextEffectValue;
+    /**
+     * @private
+     * `w:specVanish`
+     */
+    /**
+    * @private
+    */
+    specVanish: boolean | undefined;
+    /**
+     * @private
+     * `w:snapToGrid`
+     */
+    /**
+    * @private
+    */
+    snapToGrid: boolean | undefined;
+    /**
+     * Apply a partial delta. Uses setters (exclusivity applies).
+     * @public
+     */
+    assign(delta: CharacterFormatDelta): void;
+    /**
+     * Clear all typed formatting. Does not clear `rPrExtra`.
+     * @public
+     */
+    clear(): void;
+    /**
+     * @private
+     * Load snapshot without exclusivity side-effects.
+     */
+    hydrate(data: CharacterFormatSnapshot): void;
+    /**
+     * @private
+     */
+    snapshot(): CharacterFormatSnapshot;
+    /**
+     * @private
+     * Materialize `w:rPr` children (Spec §7.2 order).
+     */
+    buildRPrChildren(): OpenXmlElement[];
+    /**
+     * @private
+     * Fonts record for style resolver / direct font parse.
+     */
+    fontsRecord(): CharacterFontsRecord | undefined;
+}