@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/tables/collections.d.ts

@@ -0,0 +1,113 @@
+import { Paragraph } from '../document/paragraph';
+import { WordDocument } from '../document/document';
+/**
+ * Host for {@link TableRowCollection}.
+ *
+ * @private
+ */
+export interface TableRowCollectionHost<TRow> {
+    listRows(): TRow[];
+    replaceRows(rows: TRow[]): void;
+    createEmptyRow(): TRow;
+    bindRow(row: TRow): void;
+    /** Minimum rows required after mutation (usually 1). */
+    minRowCount(): number;
+}
+/**
+ * Host for {@link TableCellCollection}.
+ *
+ * @private
+ */
+export interface TableCellCollectionHost<TCell, TTable = unknown> {
+    listCells(): TCell[];
+    replaceCells(cells: TCell[]): void;
+    createEmptyCell(): TCell;
+    bindCell(cell: TCell): void;
+    minCellCount(): number;
+    /** Nullable owner probe — must not throw when detached. */
+    getOwnerTableOrUndefined(): TTable | undefined;
+}
+/**
+ * Mutable collection of table rows.
+ *
+ * @public
+ */
+export declare class TableRowCollection<TRow = unknown> {
+    private readonly host;
+    /** Tracks last published index span for cleanup (length getter is live). */
+    private indexedCount;
+    /**
+     * @private
+     */
+    constructor(host: TableRowCollectionHost<TRow>);
+    readonly count: number;
+    readonly length: number;
+    /**
+     * @private
+     */
+    syncFromHost(): void;
+    add(): TRow;
+    insert(index: number): TRow;
+    remove(row: TRow): void;
+    removeAt(index: number): void;
+    get(index: number): TRow;
+    indexOf(row: TRow): number;
+    toArray(): TRow[];
+    forEach(fn: (row: TRow, index: number) => void): void;
+    private rebuildIndexProperties;
+}
+/**
+ * Numeric indexer for {@link TableRowCollection} (IntelliSense / `rows[i]`).
+ *
+ * @public
+ */
+export interface TableRowCollection<TRow = unknown> {
+    readonly [index: number]: TRow;
+    [Symbol.iterator](): IterableIterator<TRow>;
+}
+/**
+ * Mutable collection of table cells in a row.
+ *
+ * @public
+ */
+export declare class TableCellCollection<TCell = unknown> {
+    private readonly host;
+    /** Tracks last published index span for cleanup (length getter is live). */
+    private indexedCount;
+    /**
+     * @private
+     */
+    constructor(host: TableCellCollectionHost<TCell>);
+    readonly count: number;
+    readonly length: number;
+    /**
+     * @private
+     */
+    syncFromHost(): void;
+    add(): TCell;
+    insert(index: number): TCell;
+    remove(cell: TCell): void;
+    removeAt(index: number): void;
+    get(index: number): TCell;
+    indexOf(cell: TCell): number;
+    toArray(): TCell[];
+    forEach(fn: (cell: TCell, index: number) => void): void;
+    private rebuildIndexProperties;
+}
+/**
+ * Numeric indexer for {@link TableCellCollection} (IntelliSense / `cells[i]`).
+ *
+ * @public
+ */
+export interface TableCellCollection<TCell = unknown> {
+    readonly [index: number]: TCell;
+    [Symbol.iterator](): IterableIterator<TCell>;
+}
+/**
+ * @private
+ * Create a cell with a single empty paragraph (construction helper).
+ */
+export declare function createEmptyParagraphCellFactory<TCell>(CellCtor: new (document: WordDocument | undefined, blocks: ReadonlyArray<{
+    type: 'paragraph';
+    paragraph: Paragraph;
+}>) => TCell): TCell;

package/src/features/tables/collections.js

@@ -0,0 +1,261 @@
+/**
+ * Table row and cell collections (DocIO-aligned customer surface).
+ *
+ * @public
+ */
+import { DetachedObjectError } from '../../core/errors/docx-error';
+import { Paragraph } from '../document/paragraph';
+/**
+ * Mutable collection of table rows.
+ *
+ * @public
+ */
+var TableRowCollection = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function TableRowCollection(host) {
+        this.host = host;
+        this.indexedCount = 0;
+        this.rebuildIndexProperties();
+    }
+    Object.defineProperty(TableRowCollection.prototype, "count", {
+        get: function () {
+            return this.host.listRows().length;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(TableRowCollection.prototype, "length", {
+        get: function () {
+            return this.count;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     */
+    TableRowCollection.prototype.syncFromHost = function () {
+        this.rebuildIndexProperties();
+    };
+    TableRowCollection.prototype.add = function () {
+        return this.insert(this.count);
+    };
+    TableRowCollection.prototype.insert = function (index) {
+        var rows = this.host.listRows().slice();
+        if (index < 0 || index > rows.length) {
+            throw new RangeError('Row index ' + String(index) + ' is out of range');
+        }
+        var row = this.host.createEmptyRow();
+        rows.splice(index, 0, row);
+        this.host.replaceRows(rows);
+        this.host.bindRow(row);
+        this.rebuildIndexProperties();
+        return row;
+    };
+    TableRowCollection.prototype.remove = function (row) {
+        var rows = this.host.listRows();
+        var at = rows.indexOf(row);
+        if (at === -1) {
+            throw new DetachedObjectError('This row is no longer in its table');
+        }
+        this.removeAt(at);
+    };
+    TableRowCollection.prototype.removeAt = function (index) {
+        var rows = this.host.listRows().slice();
+        if (index < 0 || index >= rows.length) {
+            throw new RangeError('Row index ' + String(index) + ' is out of range');
+        }
+        if (rows.length <= this.host.minRowCount()) {
+            throw new DetachedObjectError('A table must retain at least one row');
+        }
+        rows.splice(index, 1);
+        this.host.replaceRows(rows);
+        this.rebuildIndexProperties();
+    };
+    TableRowCollection.prototype.get = function (index) {
+        var rows = this.host.listRows();
+        if (index < 0 || index >= rows.length) {
+            throw new RangeError('Row index ' + String(index) + ' is out of range');
+        }
+        return rows[index];
+    };
+    TableRowCollection.prototype.indexOf = function (row) {
+        return this.host.listRows().indexOf(row);
+    };
+    TableRowCollection.prototype.toArray = function () {
+        return this.host.listRows().slice();
+    };
+    TableRowCollection.prototype.forEach = function (fn) {
+        var rows = this.host.listRows();
+        for (var i = 0; i < rows.length; i += 1) {
+            fn(rows[i], i);
+        }
+    };
+    /** Enables `for (const row of table.rows)`. */
+    TableRowCollection.prototype[Symbol.iterator] = function () {
+        return this.host.listRows().slice()[Symbol.iterator]();
+    };
+    TableRowCollection.prototype.rebuildIndexProperties = function () {
+        var self = this;
+        var host = this.host;
+        var rows = host.listRows();
+        var nextCount = rows.length;
+        var clearThrough = this.indexedCount > nextCount ? this.indexedCount : nextCount;
+        for (var i = 0; i < clearThrough + 8; i += 1) {
+            if (Object.prototype.hasOwnProperty.call(self, i)) {
+                delete self[i];
+            }
+        }
+        for (var i = 0; i < nextCount; i += 1) {
+            Object.defineProperty(self, i, {
+                get: (function (index) {
+                    return function () {
+                        var live = host.listRows();
+                        if (index < 0 || index >= live.length) {
+                            return undefined;
+                        }
+                        return live[index];
+                    };
+                })(i),
+                enumerable: true,
+                configurable: true,
+            });
+        }
+        this.indexedCount = nextCount;
+    };
+    return TableRowCollection;
+}());
+export { TableRowCollection };
+/**
+ * Mutable collection of table cells in a row.
+ *
+ * @public
+ */
+var TableCellCollection = /** @class */ (function () {
+    /**
+     * @private
+     */
+    function TableCellCollection(host) {
+        this.host = host;
+        this.indexedCount = 0;
+        this.rebuildIndexProperties();
+    }
+    Object.defineProperty(TableCellCollection.prototype, "count", {
+        get: function () {
+            return this.host.listCells().length;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    Object.defineProperty(TableCellCollection.prototype, "length", {
+        get: function () {
+            return this.count;
+        },
+        enumerable: true,
+        configurable: true
+    });
+    /**
+     * @private
+     */
+    TableCellCollection.prototype.syncFromHost = function () {
+        this.rebuildIndexProperties();
+    };
+    TableCellCollection.prototype.add = function () {
+        return this.insert(this.count);
+    };
+    TableCellCollection.prototype.insert = function (index) {
+        var cells = this.host.listCells().slice();
+        if (index < 0 || index > cells.length) {
+            throw new RangeError('Cell index ' + String(index) + ' is out of range');
+        }
+        var cell = this.host.createEmptyCell();
+        cells.splice(index, 0, cell);
+        this.host.replaceCells(cells);
+        this.host.bindCell(cell);
+        this.rebuildIndexProperties();
+        return cell;
+    };
+    TableCellCollection.prototype.remove = function (cell) {
+        var cells = this.host.listCells();
+        var at = cells.indexOf(cell);
+        if (at === -1) {
+            throw new DetachedObjectError('This cell is no longer in its row');
+        }
+        this.removeAt(at);
+    };
+    TableCellCollection.prototype.removeAt = function (index) {
+        var cells = this.host.listCells().slice();
+        if (index < 0 || index >= cells.length) {
+            throw new RangeError('Cell index ' + String(index) + ' is out of range');
+        }
+        if (cells.length <= this.host.minCellCount()) {
+            throw new DetachedObjectError('A table row must retain at least one cell');
+        }
+        cells.splice(index, 1);
+        this.host.replaceCells(cells);
+        this.rebuildIndexProperties();
+    };
+    TableCellCollection.prototype.get = function (index) {
+        var cells = this.host.listCells();
+        if (index < 0 || index >= cells.length) {
+            throw new RangeError('Cell index ' + String(index) + ' is out of range');
+        }
+        return cells[index];
+    };
+    TableCellCollection.prototype.indexOf = function (cell) {
+        return this.host.listCells().indexOf(cell);
+    };
+    TableCellCollection.prototype.toArray = function () {
+        return this.host.listCells().slice();
+    };
+    TableCellCollection.prototype.forEach = function (fn) {
+        var cells = this.host.listCells();
+        for (var i = 0; i < cells.length; i += 1) {
+            fn(cells[i], i);
+        }
+    };
+    /** Enables `for (const cell of row.cells)`. */
+    TableCellCollection.prototype[Symbol.iterator] = function () {
+        return this.host.listCells().slice()[Symbol.iterator]();
+    };
+    TableCellCollection.prototype.rebuildIndexProperties = function () {
+        var self = this;
+        var host = this.host;
+        var cells = host.listCells();
+        var nextCount = cells.length;
+        var clearThrough = this.indexedCount > nextCount ? this.indexedCount : nextCount;
+        for (var i = 0; i < clearThrough + 8; i += 1) {
+            if (Object.prototype.hasOwnProperty.call(self, i)) {
+                delete self[i];
+            }
+        }
+        for (var i = 0; i < nextCount; i += 1) {
+            Object.defineProperty(self, i, {
+                get: (function (index) {
+                    return function () {
+                        var live = host.listCells();
+                        if (index < 0 || index >= live.length) {
+                            return undefined;
+                        }
+                        return live[index];
+                    };
+                })(i),
+                enumerable: true,
+                configurable: true,
+            });
+        }
+        this.indexedCount = nextCount;
+    };
+    return TableCellCollection;
+}());
+export { TableCellCollection };
+/**
+ * @private
+ * Create a cell with a single empty paragraph (construction helper).
+ */
+export function createEmptyParagraphCellFactory(CellCtor) {
+    var paragraph = new Paragraph(undefined);
+    return new CellCtor(undefined, [{ type: 'paragraph', paragraph: paragraph }]);
+}

package/src/features/tables/format.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Table / row / cell format facades and positioning (DocIO-aligned).
+ *
+ * @public
+ */
+import { Borders } from './borders';
+import { Paddings } from './paddings';
+import { TableAlignment, TableLayout, TableWidth } from './tbl-pr';
+import { TableCellTextDirection, TableCellVerticalAlignment } from './tc-pr';
+import { OpenXmlElement } from '../../core/xml/index';
+import { Color } from '../document/color';
+/**
+ * Horizontal merge / vertical merge token (`ST_Merge` mapping).
+ *
+ * @public
+ */
+export declare const CellMerge: {
+    None: "none";
+    Start: "start";
+    Continue: "continue";
+};
+/** One of the {@link CellMerge} tokens. */
+export declare type CellMerge = (typeof CellMerge)[keyof typeof CellMerge];
+/**
+ * Horizontal origin for floating table position (`w:tblpPr/@w:horzAnchor`).
+ *
+ * @public
+ */
+export declare const TableHorizontalOrigin: {
+    Margin: "margin";
+    Page: "page";
+    Column: "column";
+};
+/** One of the {@link TableHorizontalOrigin} tokens. */
+export declare type TableHorizontalOrigin = (typeof TableHorizontalOrigin)[keyof typeof TableHorizontalOrigin];
+/**
+ * Vertical origin for floating table position (`w:tblpPr/@w:vertAnchor`).
+ *
+ * @public
+ */
+export declare const TableVerticalOrigin: {
+    Margin: "margin";
+    Page: "page";
+    Paragraph: "paragraph";
+};
+/** One of the {@link TableVerticalOrigin} tokens. */
+export declare type TableVerticalOrigin = (typeof TableVerticalOrigin)[keyof typeof TableVerticalOrigin];
+/**
+ * @private
+ */
+export interface TableFormatHost {
+    readTblPr(): OpenXmlElement;
+    writeTblPr(next: OpenXmlElement): void;
+    /**
+     * DocIO paints `tableFormat.backColor` onto each cell's `w:tcPr/w:shd`
+     * so Word shows the fill even when table-level shading alone is insufficient.
+     * Optional so style-only hosts need not implement cell walks.
+     */
+    applyTableBackColorToCells?(fill: string | undefined): void;
+}
+/**
+ * @private
+ */
+export interface RowFormatHost {
+    readTrPr(): OpenXmlElement | undefined;
+    writeTrPr(next: OpenXmlElement | undefined): void;
+}
+/**
+ * @private
+ */
+export interface CellFormatHost {
+    readTcPr(): OpenXmlElement | undefined;
+    writeTcPr(next: OpenXmlElement | undefined): void;
+}
+/**
+ * Floating table position (`w:tblpPr`).
+ *
+ * @public
+ */
+export declare class TablePositioning {
+    private readonly host;
+    /**
+     * @private
+     */
+    constructor(host: TableFormatHost);
+    private readBag;
+    private writeBag;
+    horizontalPosition: number;
+    verticalPosition: number;
+    horizontalOrigin: TableHorizontalOrigin;
+    verticalOrigin: TableVerticalOrigin;
+    distanceFromTop: number;
+    distanceFromBottom: number;
+    distanceFromLeft: number;
+    distanceFromRight: number;
+}
+/**
+ * Table-level formatting surface.
+ *
+ * @public
+ */
+export declare class TableFormat {
+    private readonly host;
+    private readonly bordersInstance;
+    private readonly paddingsInstance;
+    private readonly positioningInstance;
+    /**
+     * @private
+     */
+    constructor(host: TableFormatHost);
+    readonly borders: Borders;
+    readonly paddings: Paddings;
+    readonly positioning: TablePositioning;
+    horizontalAlignment: TableAlignment;
+    cellSpacing: number;
+    /**
+     * Table background fill (`w:tblPr/w:shd/@w:fill`).
+     *
+     * - **Get (runtime)**: OOXML wire string — hex `RRGGBB`, `'auto'`, or `undefined` when unset.
+     * - **Set**: hex string / `'auto'` (optional leading `#`), a {@link Color} enum value, or
+     *   `undefined` to clear the authored fill. {@link Color.Transparent} clears fill
+     *   (does not invent `w:fill="auto"`).
+     *
+     * TypeScript 3.3 requires identical get/set types, so the declared type is
+     * `string | Color | undefined`; the getter always returns a string when set.
+     */
+    backColor: string | Color | undefined;
+    /**
+     * When `true`, text may wrap around a floating table (`w:tblpPr` present).
+     * When `false`, the table is inline (no `w:tblpPr`).
+     */
+    wrapAround: boolean;
+    /**
+     * Inverse of fixed layout: `true` when layout is autoFit (default).
+     */
+    isAutoResized: boolean;
+    /**
+     * @private
+     * Preferred width bag used by AutoFit / width helpers.
+     */
+    preferredWidth: TableWidth | undefined;
+    /**
+     * @private
+     */
+    layout: TableLayout;
+}
+/**
+ * Row-level formatting surface.
+ *
+ * @public
+ */
+export declare class RowFormat {
+    private readonly host;
+    /**
+     * @private
+     */
+    constructor(host: RowFormatHost);
+    /**
+     * When `true`, the row may break across pages (Word default).
+     * Maps inversely to `w:cantSplit`.
+     */
+    isBreakAcrossPages: boolean;
+    /**
+     * Row background fill (`w:trPr/w:shd/@w:fill`).
+     *
+     * - **Get (runtime)**: OOXML wire string — hex `RRGGBB`, `'auto'`, or `undefined` when unset.
+     * - **Set**: hex string / `'auto'` (optional leading `#`), a {@link Color} enum value, or
+     *   `undefined` to clear the authored fill. {@link Color.Transparent} clears fill
+     *   (does not invent `w:fill="auto"`).
+     */
+    backColor: string | Color | undefined;
+}
+/**
+ * Cell-level formatting surface.
+ *
+ * @public
+ */
+export declare class CellFormat {
+    private readonly host;
+    private readonly bordersInstance;
+    private readonly paddingsInstance;
+    /**
+     * @private
+     */
+    constructor(host: CellFormatHost);
+    /**
+     * Cell background fill (`w:tcPr/w:shd/@w:fill`).
+     *
+     * - **Get (runtime)**: OOXML wire string — hex `RRGGBB`, `'auto'`, or `undefined` when unset.
+     * - **Set**: hex string / `'auto'` (optional leading `#`), a {@link Color} enum value, or
+     *   `undefined` to clear the authored fill. {@link Color.Transparent} clears fill
+     *   (does not invent `w:fill="auto"`).
+     */
+    backColor: string | Color | undefined;
+    readonly borders: Borders;
+    readonly paddings: Paddings;
+    verticalAlignment: TableCellVerticalAlignment;
+    textDirection: TableCellTextDirection;
+    /**
+     * When `true`, cell text wraps (default). Maps inversely to `w:noWrap`.
+     */
+    wrapText: boolean;
+    fitText: boolean;
+    columnSpan: number;
+    horizontalMerge: CellMerge;
+    verticalMerge: CellMerge;
+    samePaddingsAsTable: boolean;
+}