@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/document/body-always-on.js

@@ -0,0 +1,66 @@
+/**
+ * Always-on body/run/inline / package-part feature bootstrap (tables,
+ * content-controls, images, drawing, bookmarks, fields, numbering, sections,
+ * headers-footers, comments, revisions).
+ *
+ * Core never imports feature modules. Feature entry side-effects (and the main
+ * `@syncfusion/ej2-docx` entry) register idempotent `register*Feature` callbacks here so
+ * every `WordDocument.create` / `fromPackage` re-arms handlers after test resets.
+ * Numbering uses the same hook to re-arm its `registerFeaturePartHandler` for
+ * `/word/numbering.xml`. Headers/footers and comments re-arm
+ * `registerFeatureMultiPartHandler` for their relationship types (comments also
+ * registers inline/run-leaf handlers for range markers and `commentReference`).
+ * Sections re-arm WordDocument.create wrapping and feature registration for typed
+ * `w:sectPr` (not classic body-block handlers). Revisions re-arm inline/block
+ * track-change handlers and move-range markers (no package part).
+ *
+ * @private
+ */
+var __values = (this && this.__values) || function (o) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator], i = 0;
+    if (m) return m.call(o);
+    return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+};
+var bootstraps = [];
+/**
+ * Register a callback invoked before main-document body parse/create.
+ * Idempotent registration of the feature itself is the callee's job.
+ *
+ * @private
+ */
+export function registerAlwaysOnBodyFeatureBootstrap(fn) {
+    bootstraps.push(fn);
+}
+/**
+ * Run all always-on body feature bootstraps. Safe when none are registered
+ * (pure core without main entry / feature imports).
+ *
+ * @private
+ */
+export function ensureAlwaysOnBodyFeaturesRegistered() {
+    var e_1, _a;
+    try {
+        for (var bootstraps_1 = __values(bootstraps), bootstraps_1_1 = bootstraps_1.next(); !bootstraps_1_1.done; bootstraps_1_1 = bootstraps_1.next()) {
+            var fn = bootstraps_1_1.value;
+            fn();
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (bootstraps_1_1 && !bootstraps_1_1.done && (_a = bootstraps_1.return)) _a.call(bootstraps_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+}
+/**
+ * @private
+ * Test hook — clear bootstrap list (does not unregister handlers). */
+export function resetAlwaysOnBodyFeatureBootstrapsForTests() {
+    bootstraps.length = 0;
+}

package/src/features/document/body-blocks.d.ts

@@ -0,0 +1,7 @@
+import { registerFeatureBlockHandler, resetFeatureBlockHandlers, tryParseFeatureBlock, serializeFeatureBlock, BodyBlockParseContext, FeatureBlockHandler } from '../../core/registry/block-handlers';
+import { BlockContent } from './paragraph';
+import { OpenXmlChild, OpenXmlElement } from '../../core/xml/index';
+export { BodyBlockParseContext, FeatureBlockHandler };
+export { registerFeatureBlockHandler, resetFeatureBlockHandlers, tryParseFeatureBlock, serializeFeatureBlock, };
+export declare function parseBodyBlocks(children: ReadonlyArray<OpenXmlChild>, ctx: BodyBlockParseContext): BlockContent[];
+export declare function serializeBodyBlocks(blocks: ReadonlyArray<BlockContent>): OpenXmlElement[];

package/src/features/document/body-blocks.js

@@ -0,0 +1,78 @@
+var __values = (this && this.__values) || function (o) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator], i = 0;
+    if (m) return m.call(o);
+    return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+};
+import { registerFeatureBlockHandler, resetFeatureBlockHandlers, tryParseFeatureBlock, serializeFeatureBlock } from '../../core/registry/block-handlers';
+import { Paragraph, shouldEmitPageBreakAfterParagraph, createPageBreakAfterParagraphElement, } from './paragraph';
+import { isWml } from './wml';
+export { registerFeatureBlockHandler, resetFeatureBlockHandlers, tryParseFeatureBlock, serializeFeatureBlock, };
+export function parseBodyBlocks(children, ctx) {
+    var e_1, _a;
+    var blocks = [];
+    try {
+        for (var children_1 = __values(children), children_1_1 = children_1.next(); !children_1_1.done; children_1_1 = children_1.next()) {
+            var child = children_1_1.value;
+            if (child.kind !== 'element') {
+                continue;
+            }
+            if (isWml(child, 'p')) {
+                var parsed = Paragraph.fromXml(child, ctx);
+                blocks.push({ type: 'paragraph', paragraph: parsed });
+                continue;
+            }
+            var feature = tryParseFeatureBlock(child, ctx);
+            if (feature !== undefined) {
+                blocks.push(feature);
+                continue;
+            }
+            blocks.push({ type: 'opaque', xml: child });
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (children_1_1 && !children_1_1.done && (_a = children_1.return)) _a.call(children_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return blocks;
+}
+export function serializeBodyBlocks(blocks) {
+    var e_2, _a;
+    var out = [];
+    try {
+        for (var blocks_1 = __values(blocks), blocks_1_1 = blocks_1.next(); !blocks_1_1.done; blocks_1_1 = blocks_1.next()) {
+            var block = blocks_1_1.value;
+            if (block.type === 'paragraph') {
+                out.push(block.paragraph.toOpenXml());
+                // DocIO pageBreakAfter: emit a separate page-break paragraph after
+                // content — never invent w:pageBreakAfter on pPr, and never put the
+                // break run inside the content paragraph.
+                // Citation: ECMA-376-1 §17.3.3.1 w:br; docs/specs/paragraph-formatting.md.
+                if (shouldEmitPageBreakAfterParagraph(block.paragraph)) {
+                    out.push(createPageBreakAfterParagraphElement());
+                }
+                continue;
+            }
+            if (block.type === 'feature') {
+                out.push(serializeFeatureBlock(block));
+                continue;
+            }
+            out.push(block.xml);
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (blocks_1_1 && !blocks_1_1.done && (_a = blocks_1.return)) _a.call(blocks_1);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    return out;
+}

package/src/features/document/body-item-adapters.d.ts

@@ -0,0 +1,62 @@
+import { BodyItem } from './body-item';
+import { BlockContent } from './paragraph';
+import { FeatureId } from '../../core/registry/feature-registry';
+import { FeatureBlock } from './feature-block';
+/**
+ * @private
+ * Feature-block wrapper on the internal body store.
+ */
+export declare type FeatureBodyBlock = {
+    readonly type: 'feature';
+    readonly featureId: FeatureId;
+    readonly value: FeatureBlock;
+};
+/**
+ * @private
+ * Maps a feature {@link BlockContent} entry to/from a public body-item instance.
+ */
+export declare type BodyItemAdapter = {
+    /**
+     * Project an internal feature block to a public instance, or `undefined` to skip.
+     */
+    project(block: FeatureBodyBlock): BodyItem | undefined;
+    /**
+     * Wrap a public instance as an internal feature block, or `undefined` if not this kind.
+     */
+    toBlock(item: BodyItem): FeatureBodyBlock | undefined;
+    /**
+     * True when `item` is a public instance owned by this adapter.
+     */
+    isInstance(item: unknown): item is BodyItem;
+};
+/**
+ * @private
+ * Register a feature adapter (tables, block content controls). Idempotent per call site.
+ */
+export declare function registerBodyItemAdapter(adapter: BodyItemAdapter): void;
+/**
+ * @private
+ */
+export declare function resetBodyItemAdaptersForTests(): void;
+/**
+ * @private
+ * Project an internal store entry to a public {@link BodyItem}, or `undefined`
+ * when the block is opaque / unregistered feature markup (preserved off the public list).
+ */
+export declare function projectBlockToBodyItem(block: BlockContent): BodyItem | undefined;
+/**
+ * @private
+ * Convert a public body item to an internal {@link BlockContent} entry.
+ *
+ * Accepts direct {@link BodyItem} instances. Also unwraps legacy
+ * `{ type: 'paragraph', paragraph }` / feature BlockContent-shaped values so
+ * older call sites continue to work during the DOM flatten migration.
+ *
+ * @throws TypeError when `item` is not a supported public body item.
+ */
+export declare function bodyItemToBlock(item: BodyItem): BlockContent;
+/**
+ * @private
+ * True when `value` is a public body item (paragraph or registered feature instance).
+ */
+export declare function isSupportedBodyItem(value: unknown): value is BodyItem;

package/src/features/document/body-item-adapters.js

@@ -0,0 +1,97 @@
+import { isParagraphBodyItem } from './body-item';
+import { Paragraph } from './paragraph';
+var adapters = [];
+/**
+ * @private
+ * Register a feature adapter (tables, block content controls). Idempotent per call site.
+ */
+export function registerBodyItemAdapter(adapter) {
+    // Replace existing adapter with the same instance-predicate when re-registered in tests.
+    for (var i = 0; i < adapters.length; i += 1) {
+        if (adapters[i] === adapter) {
+            return;
+        }
+    }
+    adapters.push(adapter);
+}
+/**
+ * @private
+ */
+export function resetBodyItemAdaptersForTests() {
+    adapters.length = 0;
+}
+/**
+ * @private
+ * Project an internal store entry to a public {@link BodyItem}, or `undefined`
+ * when the block is opaque / unregistered feature markup (preserved off the public list).
+ */
+export function projectBlockToBodyItem(block) {
+    if (block.type === 'paragraph') {
+        return block.paragraph;
+    }
+    if (block.type === 'opaque') {
+        return undefined;
+    }
+    var featureBlock = block;
+    for (var i = 0; i < adapters.length; i += 1) {
+        var projected = adapters[i].project(featureBlock);
+        if (projected !== undefined) {
+            return projected;
+        }
+    }
+    return undefined;
+}
+/**
+ * @private
+ * Convert a public body item to an internal {@link BlockContent} entry.
+ *
+ * Accepts direct {@link BodyItem} instances. Also unwraps legacy
+ * `{ type: 'paragraph', paragraph }` / feature BlockContent-shaped values so
+ * older call sites continue to work during the DOM flatten migration.
+ *
+ * @throws TypeError when `item` is not a supported public body item.
+ */
+export function bodyItemToBlock(item) {
+    if (isParagraphBodyItem(item)) {
+        return { type: 'paragraph', paragraph: item };
+    }
+    // Legacy BlockContent wrapper still appearing in some tests/callers.
+    if (typeof item === 'object' && item !== null) {
+        var candidate = item;
+        if (candidate.type === 'paragraph' && candidate.paragraph instanceof Paragraph) {
+            return { type: 'paragraph', paragraph: candidate.paragraph };
+        }
+        if (candidate.type === 'feature' && candidate.value !== undefined) {
+            for (var i = 0; i < adapters.length; i += 1) {
+                if (adapters[i].isInstance(candidate.value)) {
+                    var block = adapters[i].toBlock(candidate.value);
+                    if (block !== undefined) {
+                        return block;
+                    }
+                }
+            }
+        }
+    }
+    for (var i = 0; i < adapters.length; i += 1) {
+        var block = adapters[i].toBlock(item);
+        if (block !== undefined) {
+            return block;
+        }
+    }
+    throw new TypeError('Unsupported body item type');
+}
+/**
+ * @private
+ * True when `value` is a public body item (paragraph or registered feature instance).
+ */
+export function isSupportedBodyItem(value) {
+    if (value instanceof Paragraph) {
+        return true;
+    }
+    for (var i = 0; i < adapters.length; i += 1) {
+        if (adapters[i].isInstance(value)) {
+            return true;
+        }
+    }
+    return false;
+}

package/src/features/document/body-item-collection.d.ts

@@ -0,0 +1,151 @@
+import { BodyItem } from './body-item';
+import { BlockContent, Paragraph } from './paragraph';
+import { WordDocument } from './document';
+import { Section } from './section';
+/**
+ * @private
+ * Host that owns the internal ordered {@link BlockContent} store projected by
+ * {@link BodyItemCollection}.
+ */
+export interface BodyItemCollectionHost {
+    /** @private */
+    owningDocument(): WordDocument;
+    /** @private */
+    owningSection(): Section | undefined;
+    /** @private */
+    rawBlocks(): BlockContent[];
+    /** @private */
+    replaceRawBlocks(blocks: ReadonlyArray<BlockContent>): void;
+    /** @private */
+    assertAttachedParagraph(target: Paragraph): void;
+    /**
+     * @private
+     * Refresh body/section typed views after public or raw item mutations.
+     * Optional so test doubles need not implement it.
+     */
+    notifyBodyItemsChanged?(): void;
+}
+/**
+ * Managed mutable collection of public {@link BodyItem} instances for a body.
+ *
+ * Projects from the body's internal ordered store. Unsupported markup remains
+ * in the package but is not listed here. Index access uses own numeric
+ * properties (no `Proxy`); identity at a given index is stable across reads.
+ *
+ * @public
+ */
+export declare class BodyItemCollection implements Iterable<BodyItem> {
+    private readonly host;
+    private cachedLength;
+    /** @private */
+    constructor(host: BodyItemCollectionHost);
+    /**
+     * Number of public body items (paragraphs, tables, block content controls).
+     */
+    readonly count: number;
+    /**
+     * Alias of {@link count} for array-like consumers (`toHaveLength`, `items.length`).
+     */
+    readonly length: number;
+    /**
+     * Append a body item after existing public children.
+     *
+     * @param item - Paragraph, table, or block content control instance.
+     * @returns The same `item` reference.
+     * @throws TypeError when `item` is not a supported body item.
+     * @throws DetachedObjectError when `item` is already owned.
+     */
+    add(item: BodyItem): BodyItem;
+    /**
+     * Insert a body item at a public-items index (`0…count` inclusive).
+     *
+     * @param index - Insert-before index; `count` appends.
+     * @param item - Paragraph, table, or block content control instance.
+     * @returns The same `item` reference.
+     * @throws RangeError when `index` is outside `0…count`.
+     * @throws TypeError when `item` is not a supported body item.
+     * @throws DetachedObjectError when `item` is already owned.
+     */
+    insert(index: number, item: BodyItem): BodyItem;
+    /**
+     * Remove a body item by instance identity.
+     *
+     * @param item - Item currently in this collection.
+     * @throws DetachedObjectError when `item` is not in this collection.
+     */
+    remove(item: BodyItem): void;
+    /**
+     * Remove the public body item at `index` (`0…count-1`).
+     *
+     * @throws RangeError when `index` is out of range.
+     */
+    removeAt(index: number): void;
+    /**
+     * Remove all body items (paragraphs, tables, block content controls) and
+     * detach/release owned content. Opaque unmodeled blocks are also cleared.
+     */
+    clear(): void;
+    /**
+     * Index of `item` in this collection, or `-1` when absent.
+     */
+    indexOf(item: BodyItem): number;
+    /**
+     * Snapshot of public body items in order.
+     */
+    toArray(): BodyItem[];
+    /**
+     * Invoke `fn` for each public body item.
+     */
+    forEach(fn: (item: BodyItem, index: number) => void): void;
+    /**
+     * True when at least one public body item satisfies `predicate`.
+     */
+    some(predicate: (item: BodyItem, index: number) => boolean): boolean;
+    /**
+     * Public body items that satisfy `predicate`.
+     */
+    filter(predicate: (item: BodyItem, index: number) => boolean): BodyItem[];
+    /**
+     * First public body item that satisfies `predicate`, or `undefined`.
+     */
+    find(predicate: (item: BodyItem, index: number) => boolean): BodyItem | undefined;
+    /**
+     * Map public body items with `fn`.
+     */
+    map<U>(fn: (item: BodyItem, index: number) => U): U[];
+    /**
+     * Iterate public body items in document order.
+     */
+    [Symbol.iterator](): Iterator<BodyItem>;
+    /**
+     * @private
+     * Refresh numeric index properties after any raw-store mutation outside
+     * this collection (load, feature internal hooks).
+     */
+    syncFromHost(): void;
+    /**
+     * @private
+     * Insert an internal block at a raw store index (features / load bridge).
+     */
+    insertRawBlockAt(index: number, block: BlockContent): void;
+    /**
+     * @private
+     */
+    removeRawBlockAt(index: number): void;
+    /**
+     * @private
+     */
+    appendRawBlock(block: BlockContent): void;
+    /**
+     * @private
+     */
+    indexOfRawBlock(block: BlockContent): number;
+    private project;
+    private rawIndexForPublicInsert;
+    private assertNotOwned;
+    private rebuildIndexProperties;
+    private notifyHostBodyItemsChanged;
+}
+export interface BodyItemCollection {
+    readonly [index: number]: BodyItem;
+}