@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

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

@@ -0,0 +1,162 @@
+import { ParagraphItem, ParagraphItemOwner } from './paragraph-item';
+import { ConcreteParagraphItem } from './text-range';
+/**
+ * Host for {@link ParagraphItemCollection}: owns mutation gates and document link.
+ *
+ * @private
+ */
+export interface ParagraphItemCollectionHost extends ParagraphItemOwner {
+    /** Gate paragraph-level authoring (detached paragraph throws). */
+    assertMutable(): void;
+}
+/**
+ * Stable mutable collection of {@link ParagraphItem} children on a paragraph.
+ *
+ * Single source of truth for order, ownership, insert/remove, hydrate, and the
+ * serialize snapshot. Indexers are own properties refreshed after each mutation
+ * (no `Proxy` — TypeScript 3.3 / ES5 target).
+ *
+ * Array-like surface mirrors {@link BodyItemCollection}: {@link count}/{@link length},
+ * numeric index, {@link add}/{@link insert}/{@link remove}/{@link removeAt}/{@link clear},
+ * {@link toArray}, iterators, and common query helpers.
+ *
+ * @public
+ */
+export declare class ParagraphItemCollection implements Iterable<ConcreteParagraphItem> {
+    private readonly host;
+    private readonly items;
+    private cachedCount;
+    /**
+     * @private
+     */
+    constructor(host: ParagraphItemCollectionHost);
+    /**
+     * Number of paragraph items in document order.
+     * @public
+     */
+    readonly count: number;
+    /**
+     * Alias of {@link count} for array-like consumers (`items.length`).
+     * @public
+     */
+    readonly length: number;
+    /**
+     * Append `item` at the end. Transfers ownership to this paragraph.
+     *
+     * @throws DetachedObjectError if the paragraph is detached, or `item` is
+     * already attached elsewhere.
+     * @public
+     */
+    add(item: ConcreteParagraphItem): void;
+    /**
+     * Insert `item` at `index` (`0…count` inclusive).
+     *
+     * @throws RangeError if `index` is out of range.
+     * @throws DetachedObjectError if the paragraph is detached or `item` is owned.
+     * @public
+     */
+    insert(index: number, item: ConcreteParagraphItem): void;
+    /**
+     * Remove `item` by identity and detach it.
+     *
+     * @throws DetachedObjectError if `item` is not in this collection.
+     * @public
+     */
+    remove(item: ConcreteParagraphItem): void;
+    /**
+     * Remove the item at `index` (`0…count-1`) and detach it.
+     *
+     * @throws RangeError if `index` is out of range.
+     * @public
+     */
+    removeAt(index: number): void;
+    /**
+     * Remove and detach every item.
+     * @public
+     */
+    clear(): void;
+    /**
+     * @private Identity membership (reference equality).
+     */
+    containsIdentity(item: ParagraphItem): boolean;
+    /**
+     * Index of `item` by reference, or `-1`.
+     * @public
+     */
+    indexOf(item: ConcreteParagraphItem): number;
+    /**
+     * @private Index of `item` by reference, or `-1`.
+     */
+    indexOfIdentity(item: ParagraphItem): number;
+    /**
+     * Ordered public items (projects feature wrappers to leaf entities).
+     * @public
+     */
+    toArray(): ConcreteParagraphItem[];
+    /**
+     * @private Ordered storage snapshot for serialize (wrappers retained).
+     */
+    snapshot(): ConcreteParagraphItem[];
+    /**
+     * Invoke `fn` for each item in document order.
+     * @public
+     */
+    forEach(fn: (item: ConcreteParagraphItem, index: number) => void): void;
+    /**
+     * True when at least one item satisfies `predicate`.
+     * @public
+     */
+    some(predicate: (item: ConcreteParagraphItem, index: number) => boolean): boolean;
+    /**
+     * True when every item satisfies `predicate` (empty collection is true).
+     * @public
+     */
+    every(predicate: (item: ConcreteParagraphItem, index: number) => boolean): boolean;
+    /**
+     * Items that satisfy `predicate`.
+     * @public
+     */
+    filter(predicate: (item: ConcreteParagraphItem, index: number) => boolean): ConcreteParagraphItem[];
+    /**
+     * First item that satisfies `predicate`, or `undefined`.
+     * @public
+     */
+    find(predicate: (item: ConcreteParagraphItem, index: number) => boolean): ConcreteParagraphItem | undefined;
+    /**
+     * Index of the first item that satisfies `predicate`, or `-1`.
+     * @public
+     */
+    findIndex(predicate: (item: ConcreteParagraphItem, index: number) => boolean): number;
+    /**
+     * Map items with `fn`.
+     * @public
+     */
+    map<U>(fn: (item: ConcreteParagraphItem, index: number) => U): U[];
+    /**
+     * Iterate items in document order.
+     * @public
+     */
+    [Symbol.iterator](): Iterator<ConcreteParagraphItem>;
+    /**
+     * @private Replace contents during parse/hydrate without authoring mutate.
+     * Detaches prior items, attaches incoming items to this host.
+     */
+    hydrate(items: ReadonlyArray<ConcreteParagraphItem>): void;
+    /**
+     * @private Append during parse without assertMutable (owner may still be wiring).
+     */
+    addFromParse(item: ConcreteParagraphItem): void;
+    /**
+     * @private Detach every item without clearing the array (paragraph detach).
+     */
+    detachAll(): void;
+    /**
+     * @private Re-attach every item to this host (paragraph attach).
+     */
+    reattachAll(): void;
+    private assertNotOwned;
+    private rebuildIndexProperties;
+}
+export interface ParagraphItemCollection {
+    readonly [index: number]: ConcreteParagraphItem;
+}

package/src/features/document/paragraph-item-collection.js

@@ -0,0 +1,363 @@
+import { DetachedObjectError } from '../../core/errors/docx-error';
+import { FeatureInlineParagraphItem, FeatureRunParagraphItem, } from './text-range';
+/**
+ * Project internal feature wrappers to public leaf objects when the leaf
+ * exposes a numeric {@link EntityType} discriminant (e.g. Picture).
+ * Storage and serialize stay on the wrapper.
+ * @private
+ */
+function projectPublicItem(item) {
+    if (item instanceof FeatureRunParagraphItem) {
+        var value = item.value;
+        if (value != null && (typeof value.type === 'number' || typeof value.entityType === 'number')) {
+            return value;
+        }
+    }
+    if (item instanceof FeatureInlineParagraphItem) {
+        var value = item.value;
+        if (value != null && (typeof value.type === 'number' || typeof value.entityType === 'number')) {
+            return value;
+        }
+    }
+    return item;
+}
+/**
+ * Resolve a public leaf back to the stored wrapper (identity if unprojected).
+ * @private
+ */
+function resolveStoredItem(items, item) {
+    for (var i = 0; i < items.length; i += 1) {
+        var raw = items[i];
+        if (raw === item || projectPublicItem(raw) === item) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Stable mutable collection of {@link ParagraphItem} children on a paragraph.
+ *
+ * Single source of truth for order, ownership, insert/remove, hydrate, and the
+ * serialize snapshot. Indexers are own properties refreshed after each mutation
+ * (no `Proxy` — TypeScript 3.3 / ES5 target).
+ *
+ * Array-like surface mirrors {@link BodyItemCollection}: {@link count}/{@link length},
+ * numeric index, {@link add}/{@link insert}/{@link remove}/{@link removeAt}/{@link clear},
+ * {@link toArray}, iterators, and common query helpers.
+ *
+ * @public
+ */
+var ParagraphItemCollection = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function ParagraphItemCollection(host) {
+        this.host = host;
+        this.items = [];
+        this.cachedCount = 0;
+        this.rebuildIndexProperties();
+    }
+    Object.defineProperty(ParagraphItemCollection.prototype, "count", {
+        /**
+         * Number of paragraph items in document order.
+         * @public
+         */
+        get: function () {
+            return this.items.length;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ParagraphItemCollection.prototype, "length", {
+        /**
+         * Alias of {@link count} for array-like consumers (`items.length`).
+         * @public
+         */
+        get: function () {
+            return this.count;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * Append `item` at the end. Transfers ownership to this paragraph.
+     *
+     * @throws DetachedObjectError if the paragraph is detached, or `item` is
+     * already attached elsewhere.
+     * @public
+     */
+    ParagraphItemCollection.prototype.add = function (item) {
+        this.insert(this.items.length, item);
+    };
+    /**
+     * Insert `item` at `index` (`0…count` inclusive).
+     *
+     * @throws RangeError if `index` is out of range.
+     * @throws DetachedObjectError if the paragraph is detached or `item` is owned.
+     * @public
+     */
+    ParagraphItemCollection.prototype.insert = function (index, item) {
+        this.host.assertMutable();
+        if (index < 0 || index > this.items.length) {
+            throw new RangeError("Paragraph item index " + String(index) + " is out of range");
+        }
+        this.assertNotOwned(item);
+        this.items.splice(index, 0, item);
+        item.attach(this.host);
+        this.rebuildIndexProperties();
+    };
+    /**
+     * Remove `item` by identity and detach it.
+     *
+     * @throws DetachedObjectError if `item` is not in this collection.
+     * @public
+     */
+    ParagraphItemCollection.prototype.remove = function (item) {
+        this.host.assertMutable();
+        var at = resolveStoredItem(this.items, item);
+        if (at === -1) {
+            throw new DetachedObjectError('This paragraph item is no longer in its paragraph');
+        }
+        var raw = this.items[at];
+        this.items.splice(at, 1);
+        raw.detach();
+        this.rebuildIndexProperties();
+    };
+    /**
+     * Remove the item at `index` (`0…count-1`) and detach it.
+     *
+     * @throws RangeError if `index` is out of range.
+     * @public
+     */
+    ParagraphItemCollection.prototype.removeAt = function (index) {
+        this.host.assertMutable();
+        if (index < 0 || index >= this.items.length) {
+            throw new RangeError("Paragraph item index " + String(index) + " is out of range");
+        }
+        var item = this.items[index];
+        this.items.splice(index, 1);
+        item.detach();
+        this.rebuildIndexProperties();
+    };
+    /**
+     * Remove and detach every item.
+     * @public
+     */
+    ParagraphItemCollection.prototype.clear = function () {
+        this.host.assertMutable();
+        this.detachAll();
+        this.items.length = 0;
+        this.rebuildIndexProperties();
+    };
+    /**
+     * @private Identity membership (reference equality).
+     */
+    ParagraphItemCollection.prototype.containsIdentity = function (item) {
+        return this.indexOfIdentity(item) !== -1;
+    };
+    /**
+     * Index of `item` by reference, or `-1`.
+     * @public
+     */
+    ParagraphItemCollection.prototype.indexOf = function (item) {
+        return resolveStoredItem(this.items, item);
+    };
+    /**
+     * @private Index of `item` by reference, or `-1`.
+     */
+    ParagraphItemCollection.prototype.indexOfIdentity = function (item) {
+        for (var i = 0; i < this.items.length; i += 1) {
+            if (this.items[i] === item) {
+                return i;
+            }
+        }
+        return -1;
+    };
+    /**
+     * Ordered public items (projects feature wrappers to leaf entities).
+     * @public
+     */
+    ParagraphItemCollection.prototype.toArray = function () {
+        var out = [];
+        for (var i = 0; i < this.items.length; i += 1) {
+            out.push(projectPublicItem(this.items[i]));
+        }
+        return out;
+    };
+    /**
+     * @private Ordered storage snapshot for serialize (wrappers retained).
+     */
+    ParagraphItemCollection.prototype.snapshot = function () {
+        return this.items.slice();
+    };
+    /**
+     * Invoke `fn` for each item in document order.
+     * @public
+     */
+    ParagraphItemCollection.prototype.forEach = function (fn) {
+        for (var i = 0; i < this.items.length; i += 1) {
+            fn(projectPublicItem(this.items[i]), i);
+        }
+    };
+    /**
+     * True when at least one item satisfies `predicate`.
+     * @public
+     */
+    ParagraphItemCollection.prototype.some = function (predicate) {
+        for (var i = 0; i < this.items.length; i += 1) {
+            if (predicate(projectPublicItem(this.items[i]), i)) {
+                return true;
+            }
+        }
+        return false;
+    };
+    /**
+     * True when every item satisfies `predicate` (empty collection is true).
+     * @public
+     */
+    ParagraphItemCollection.prototype.every = function (predicate) {
+        for (var i = 0; i < this.items.length; i += 1) {
+            if (!predicate(projectPublicItem(this.items[i]), i)) {
+                return false;
+            }
+        }
+        return true;
+    };
+    /**
+     * Items that satisfy `predicate`.
+     * @public
+     */
+    ParagraphItemCollection.prototype.filter = function (predicate) {
+        var out = [];
+        for (var i = 0; i < this.items.length; i += 1) {
+            var item = projectPublicItem(this.items[i]);
+            if (predicate(item, i)) {
+                out.push(item);
+            }
+        }
+        return out;
+    };
+    /**
+     * First item that satisfies `predicate`, or `undefined`.
+     * @public
+     */
+    ParagraphItemCollection.prototype.find = function (predicate) {
+        for (var i = 0; i < this.items.length; i += 1) {
+            var item = projectPublicItem(this.items[i]);
+            if (predicate(item, i)) {
+                return item;
+            }
+        }
+        return undefined;
+    };
+    /**
+     * Index of the first item that satisfies `predicate`, or `-1`.
+     * @public
+     */
+    ParagraphItemCollection.prototype.findIndex = function (predicate) {
+        for (var i = 0; i < this.items.length; i += 1) {
+            if (predicate(projectPublicItem(this.items[i]), i)) {
+                return i;
+            }
+        }
+        return -1;
+    };
+    /**
+     * Map items with `fn`.
+     * @public
+     */
+    ParagraphItemCollection.prototype.map = function (fn) {
+        var out = [];
+        for (var i = 0; i < this.items.length; i += 1) {
+            out.push(fn(projectPublicItem(this.items[i]), i));
+        }
+        return out;
+    };
+    /**
+     * Iterate items in document order.
+     * @public
+     */
+    ParagraphItemCollection.prototype[Symbol.iterator] = function () {
+        var items = this.items.slice();
+        var i = 0;
+        return {
+            next: function () {
+                if (i >= items.length) {
+                    return { done: true, value: undefined };
+                }
+                var value = projectPublicItem(items[i]);
+                i += 1;
+                return { done: false, value: value };
+            },
+        };
+    };
+    /**
+     * @private Replace contents during parse/hydrate without authoring mutate.
+     * Detaches prior items, attaches incoming items to this host.
+     */
+    ParagraphItemCollection.prototype.hydrate = function (items) {
+        this.detachAll();
+        this.items.length = 0;
+        for (var i = 0; i < items.length; i += 1) {
+            var item = items[i];
+            this.items.push(item);
+            item.attach(this.host);
+        }
+        this.rebuildIndexProperties();
+    };
+    /**
+     * @private Append during parse without assertMutable (owner may still be wiring).
+     */
+    ParagraphItemCollection.prototype.addFromParse = function (item) {
+        this.items.push(item);
+        item.attach(this.host);
+        this.rebuildIndexProperties();
+    };
+    /**
+     * @private Detach every item without clearing the array (paragraph detach).
+     */
+    ParagraphItemCollection.prototype.detachAll = function () {
+        for (var i = 0; i < this.items.length; i += 1) {
+            this.items[i].detach();
+        }
+    };
+    /**
+     * @private Re-attach every item to this host (paragraph attach).
+     */
+    ParagraphItemCollection.prototype.reattachAll = function () {
+        for (var i = 0; i < this.items.length; i += 1) {
+            this.items[i].attach(this.host);
+        }
+    };
+    ParagraphItemCollection.prototype.assertNotOwned = function (item) {
+        if (item.owner !== undefined) {
+            if (item.owner === this.host && this.containsIdentity(item)) {
+                throw new DetachedObjectError('Paragraph item is already in this paragraph');
+            }
+            throw new DetachedObjectError('Paragraph item is already attached');
+        }
+    };
+    ParagraphItemCollection.prototype.rebuildIndexProperties = function () {
+        var nextLen = this.items.length;
+        var prevLen = this.cachedCount;
+        var limit = prevLen > nextLen ? prevLen : nextLen;
+        for (var i = 0; i < limit; i += 1) {
+            var key = String(i);
+            if (i < nextLen) {
+                var value = projectPublicItem(this.items[i]);
+                Object.defineProperty(this, key, {
+                    value: value,
+                    writable: false,
+                    enumerable: true,
+                    configurable: true,
+                });
+            }
+            else {
+                delete this[key];
+            }
+        }
+        this.cachedCount = nextLen;
+    };
+    return ParagraphItemCollection;
+}());
+export { ParagraphItemCollection };

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

@@ -0,0 +1,83 @@
+/**
+ * Owner that validates {@link ParagraphItem} attachment for mutation.
+ *
+ * Implemented by {@link Paragraph} (and nested feature owners that host nested
+ * text ranges). Collection mutations go through the paragraph collection; this
+ * interface is the mutation gate for item property writes.
+ *
+ * @public
+ */
+export interface ParagraphItemOwner {
+    /**
+     * Assert that `target` is still attached to this owner and that the owner
+     * itself is mutable. Throws {@link DetachedObjectError} otherwise.
+     */
+    assertAttachedItem(target: ParagraphItem): void;
+}
+/**
+ * Base class for every modeled child of {@link Paragraph.items}.
+ *
+ * Concrete subclasses include {@link TextRange}, breaks, symbols, tabs,
+ * feature-owned items, and opaque round-trip holders. Ownership is exclusive:
+ * an item is attached to at most one owner (normally a paragraph via its
+ * {@link ParagraphItemCollection}).
+ *
+ * @public
+ */
+export declare abstract class ParagraphItem {
+    private ownerValue;
+    /**
+     * Document context for never-attached authoring (`new TextRange(document)`).
+     * Cleared only when the item is removed after having been attached.
+     * @private
+     */
+    private documentContextValue;
+    /**
+     * True once this item has been attached at least once and later detached.
+     * @private
+     */
+    private wasRemovedValue;
+    /**
+     * @private
+     */
+    constructor();
+    /**
+     * Owning paragraph/item host when attached; `undefined` when detached.
+     *
+     * @private
+     */
+    readonly owner: ParagraphItemOwner | undefined;
+    /**
+     * @private Document context for unattached authoring.
+     */
+    readonly documentContext: unknown | undefined;
+    /**
+     * @private Bind document context without attaching to a paragraph.
+     */
+    setDocumentContext(document: unknown | undefined): void;
+    /**
+     * @private Attach to an owner (collection / nested host only).
+     */
+    attach(owner: ParagraphItemOwner): void;
+    /**
+     * @private Detach from the current owner. Further authoring mutates throw
+     * unless the item was never attached and still has document context.
+     */
+    detach(): void;
+    /**
+     * Hook for subclasses that hold nested content (feature inlines, …).
+     * @private
+     */
+    protected onDetached(): void;
+    /**
+     * Ensure this item is still attached and the owner accepts mutation.
+     * @private
+     */
+    assertAttached(): void;
+    /**
+     * @private Convenience for property setters.
+     * Allows mutation when the item has document context and was never attached,
+     * or is currently attached. Throws after removal from a parent.
+     */
+    protected mutate(): void;
+}

package/src/features/document/paragraph-item.js

@@ -0,0 +1,103 @@
+import { DetachedObjectError } from '../../core/errors/docx-error';
+/**
+ * Base class for every modeled child of {@link Paragraph.items}.
+ *
+ * Concrete subclasses include {@link TextRange}, breaks, symbols, tabs,
+ * feature-owned items, and opaque round-trip holders. Ownership is exclusive:
+ * an item is attached to at most one owner (normally a paragraph via its
+ * {@link ParagraphItemCollection}).
+ *
+ * @public
+ */
+var ParagraphItem = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function ParagraphItem() {
+        this.ownerValue = undefined;
+        this.documentContextValue = undefined;
+        this.wasRemovedValue = false;
+    }
+    Object.defineProperty(ParagraphItem.prototype, "owner", {
+        /**
+         * Owning paragraph/item host when attached; `undefined` when detached.
+         *
+         * @private
+         */
+        get: function () {
+            return this.ownerValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(ParagraphItem.prototype, "documentContext", {
+        /**
+         * @private Document context for unattached authoring.
+         */
+        get: function () {
+            return this.documentContextValue;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private Bind document context without attaching to a paragraph.
+     */
+    ParagraphItem.prototype.setDocumentContext = function (document) {
+        this.documentContextValue = document;
+        this.wasRemovedValue = false;
+    };
+    /**
+     * @private Attach to an owner (collection / nested host only).
+     */
+    ParagraphItem.prototype.attach = function (owner) {
+        this.ownerValue = owner;
+        this.wasRemovedValue = false;
+    };
+    /**
+     * @private Detach from the current owner. Further authoring mutates throw
+     * unless the item was never attached and still has document context.
+     */
+    ParagraphItem.prototype.detach = function () {
+        if (this.ownerValue !== undefined) {
+            this.wasRemovedValue = true;
+            this.documentContextValue = undefined;
+        }
+        this.ownerValue = undefined;
+        this.onDetached();
+    };
+    /**
+     * Hook for subclasses that hold nested content (feature inlines, …).
+     * @private
+     */
+    ParagraphItem.prototype.onDetached = function () {
+        // default no-op
+    };
+    /**
+     * Ensure this item is still attached and the owner accepts mutation.
+     * @private
+     */
+    ParagraphItem.prototype.assertAttached = function () {
+        if (this.ownerValue === undefined) {
+            throw new DetachedObjectError('This paragraph item is no longer attached');
+        }
+        this.ownerValue.assertAttachedItem(this);
+    };
+    /**
+     * @private Convenience for property setters.
+     * Allows mutation when the item has document context and was never attached,
+     * or is currently attached. Throws after removal from a parent.
+     */
+    ParagraphItem.prototype.mutate = function () {
+        if (this.ownerValue !== undefined) {
+            this.ownerValue.assertAttachedItem(this);
+            return;
+        }
+        if (!this.wasRemovedValue && this.documentContextValue !== undefined) {
+            return;
+        }
+        throw new DetachedObjectError('This paragraph item is no longer attached');
+    };
+    return ParagraphItem;
+}());
+export { ParagraphItem };