@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

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

@@ -0,0 +1,597 @@
+export * from './border-style-map';
+export * from './borders';
+export * from './collections';
+export * from './format';
+export * from './paddings';
+export * from './tbl-pr-positioning';
+export * from './tbl-pr';
+export * from './tc-pr';
+export * from './tr-pr';
+import { WordDocument, Body } from '../document/document';
+import { FeatureBlock } from '../document/feature-block';
+import { BlockContent } from '../document/paragraph';
+import { BodyItem } from '../document/body-item';
+import { OpenXmlElement } from '../../core/xml/index';
+import { CnfStyle, NormalizedCnfStyle, TableLayout, TableLook, TableWidth } from './tbl-pr';
+import { BuiltinTableStyle, TableStyle } from '../styles/index';
+import { VerticalMerge } from './tc-pr';
+import { CellFormat, CellFormatHost, RowFormat, RowFormatHost, TableFormat, TableFormatHost } from './format';
+import { TableCellCollection, TableCellCollectionHost, TableRowCollection, TableRowCollectionHost } from './collections';
+/**
+ * Alias for {@link TableRowHeightRule} (DocIO `RowHeightType` naming).
+ *
+ * @public
+ */
+export declare type TableRowHeightType = import('./tbl-pr').TableRowHeightRule;
+/**
+ * AutoFit modes for {@link Table.autoFit}, matching DocIO `AutoFitType`.
+ *
+ * - {@link AutoFitType.FitToContent}: auto layout; clear fixed preferred widths.
+ * - {@link AutoFitType.FitToWindow}: auto layout; table 100% width; cell % widths.
+ * - {@link AutoFitType.FixedColumnWidth}: fixed layout; cell DXA widths from grid.
+ *
+ * @public
+ */
+export declare const AutoFitType: {
+    FitToContent: "fitToContent";
+    FitToWindow: "fitToWindow";
+    FixedColumnWidth: "fixedColumnWidth";
+};
+/** One of the {@link AutoFitType} tokens. */
+export declare type AutoFitType = (typeof AutoFitType)[keyof typeof AutoFitType];
+/**
+ * @private
+ */
+export interface MergeRegion {
+    readonly fromRow: number;
+    readonly fromColumn: number;
+    readonly toRow: number;
+    readonly toColumn: number;
+    readonly origin: TableCell;
+    readonly continuations: ReadonlyArray<TableCell>;
+}
+/**
+ * @private
+ */
+export interface MergeCellsRange {
+    readonly fromRow: number;
+    readonly fromColumn: number;
+    readonly toRow: number;
+    readonly toColumn: number;
+}
+declare const TABLES: import("../../core/registry").FeatureId;
+/**
+ * A table — ordered grid of rows and cells with table-level formatting.
+ *
+ * Create with {@link Body.appendTable} then size via {@link Table.resetCells}.
+ *
+ * @public
+ */
+export declare class Table implements FeatureBlock, TableRowCollectionHost<TableRow>, TableFormatHost {
+    private readonly prefixMarkup;
+    private tblPr;
+    private tblGrid;
+    private tableRows;
+    private documentOwner;
+    private readonly rowsInstance;
+    private readonly tableFormatInstance;
+    private conditionalFormattingDirty;
+    /**
+     * @private
+     */
+    constructor(prefixMarkup: OpenXmlElement[], tblPr: OpenXmlElement, tblGrid: OpenXmlElement, rows: TableRow[]);
+    /** Rows collection (DocIO-aligned). */
+    readonly rows: TableRowCollection<TableRow>;
+    /**
+     * @private
+     */
+    listRows(): TableRow[];
+    /**
+     * @private
+     */
+    replaceRows(rows: TableRow[]): void;
+    /**
+     * @private
+     */
+    createEmptyRow(): TableRow;
+    /**
+     * @private
+     */
+    bindRow(row: TableRow): void;
+    /**
+     * @private
+     */
+    minRowCount(): number;
+    /**
+     * @private
+     */
+    readTblPr(): OpenXmlElement;
+    /**
+     * @private
+     */
+    writeTblPr(next: OpenXmlElement): void;
+    /**
+     * DocIO parity: copy table back fill onto every cell as direct `w:tcPr/w:shd`
+     * (`val="clear"` `color="auto"` `fill=<wire>`). Clearing table backColor
+     * removes cell fills that still match the previous painted fill so independent
+     * cell colors are left alone when possible.
+     *
+     * @private
+     */
+    applyTableBackColorToCells(fill: string | undefined): void;
+    /** Table-level format facade. */
+    readonly tableFormat: TableFormat;
+    /**
+     * Accessibility title (`w:tblCaption`). Formerly `caption`.
+     */
+    title: string | undefined;
+    description: string | undefined;
+    /**
+     * Left indent in points (`w:tblInd`). Formerly `indent`.
+     */
+    indentFromLeft: number | undefined;
+    /**
+     * Effective table width in points from the sum of grid column widths
+     * (`w:tblGrid`). When a fixed DXA preferred width is set, that value is
+     * written on the setter; the getter always reports the grid sum.
+     */
+    width: number;
+    /**
+     * @private
+     */
+    preferredWidth: TableWidth | undefined;
+    /**
+     * @private
+     */
+    layout: TableLayout;
+    /**
+     * @private
+     */
+    look: TableLook | undefined;
+    /**
+     * Rows per table-style horizontal band (`w:tblStyleRowBandSize/@w:val`).
+     *
+     * Absent on the wire reads as `undefined` (Word default band height is 1).
+     * Setting `undefined` removes the element. Non-finite values throw
+     * `RangeError`. Does not recompute conditional formatting masks.
+     *
+     * @public
+     */
+    rowBandSize: number | undefined;
+    /**
+     * Columns per table-style vertical band (`w:tblStyleColBandSize/@w:val`).
+     *
+     * Absent on the wire reads as `undefined` (Word default band width is 1).
+     * Setting `undefined` removes the element. Non-finite values throw
+     * `RangeError`. Does not recompute conditional formatting masks.
+     *
+     * @public
+     */
+    columnBandSize: number | undefined;
+    /**
+     * Canonical table style id (`w:tblStyle/@w:val`), when assigned.
+     *
+     * @public
+     */
+    styleId: string | undefined;
+    /**
+     * Style id of the applied table style (`w:tblStyle/@w:val`).
+     * Matches the id written by {@link Table.applyStyle} / authoring defaults
+     * (e.g. `TableGrid`, `LightShading`). Absent style → `undefined`.
+     *
+     * @public
+     */
+    readonly styleName: string | undefined;
+    /**
+     * Apply a built-in, custom, or named table style to this table.
+     *
+     * Resolves the style through the document styles collection, materializing
+     * built-in definitions when needed, and writes `w:tblPr/w:tblStyle`.
+     * Does not change table-look application options.
+     *
+     * @param style Built-in id, live {@link TableStyle}, or style id / name string.
+     * @throws DetachedObjectError when the table is not bound to a document.
+     * @public
+     */
+    applyStyle(style: string | TableStyle | BuiltinTableStyle): void;
+    /**
+     * Whether the assigned table style applies first-row conditional formatting.
+     * Maps to `w:tblLook/@w:firstRow`. Absent look → `false`.
+     *
+     * @public
+     */
+    applyStyleForFirstRow: boolean;
+    /**
+     * Whether the assigned table style applies last-row conditional formatting.
+     * Maps to `w:tblLook/@w:lastRow`. Absent look → `false`.
+     *
+     * @public
+     */
+    applyStyleForLastRow: boolean;
+    /**
+     * Whether the assigned table style applies first-column conditional formatting.
+     * Maps to `w:tblLook/@w:firstColumn`. Absent look → `false`.
+     *
+     * @public
+     */
+    applyStyleForFirstColumn: boolean;
+    /**
+     * Whether the assigned table style applies last-column conditional formatting.
+     * Maps to `w:tblLook/@w:lastColumn`. Absent look → `false`.
+     *
+     * @public
+     */
+    applyStyleForLastColumn: boolean;
+    /**
+     * Whether the assigned table style applies horizontal band formatting to
+     * alternating table rows. Maps inversely to `w:tblLook/@w:noHBand`.
+     * Absent look → `true`.
+     *
+     * @public
+     */
+    applyStyleForBandedRows: boolean;
+    /**
+     * Whether the assigned table style applies vertical band formatting to
+     * alternating table columns. Maps inversely to `w:tblLook/@w:noVBand`.
+     * Absent look → `true`.
+     *
+     * @public
+     */
+    applyStyleForBandedColumns: boolean;
+    /**
+     * Merge one or more `w:tblLook` flags without clearing unrelated flags.
+     *
+     * @private
+     */
+    private mergeTableLook;
+    /**
+     * Marks row and cell conditional style membership for recalculation.
+     * Paragraph `w:pPr/w:cnfStyle` is not authored on dirty paths (DocIO parity).
+     *
+     * @private
+     */
+    markConditionalFormattingDirty(): void;
+    /**
+     * Recalculate conditional table-style membership masks on rows and cells
+     * (`w:trPr` / `w:tcPr`). Does not write `w:pPr/w:cnfStyle` — DocIO emits
+     * membership on row/cell only; paragraph cnf is cleared when styles are
+     * removed or when a dirty recompute runs so authored output stays clean.
+     * Nested tables own their own cascade.
+     *
+     * @private
+     */
+    updateConditionalFormatting(): void;
+    /**
+     * Owning document when bound.
+     *
+     * @private
+     */
+    readonly owner: WordDocument | undefined;
+    /**
+     * Rebuild the table to `rowCount` × `columnCount` empty cells.
+     *
+     * Authoring path: empty cells (no auto paragraph), fixed layout, equal
+     * client-width columns, and `TableGrid` when document-bound.
+     */
+    resetCells(rowCount: number, columnCount: number): void;
+    autoFit(autoFitType: AutoFitType): void;
+    /**
+     * Append an empty row with the current column count.
+     * Prefer {@link Table.rows}.add for new code.
+     */
+    appendRow(): TableRow;
+    /**
+     * Insert an empty row at `index` (0 … rows.length inclusive).
+     * Prefer {@link Table.rows}.insert for new code.
+     */
+    insertRow(index: number): TableRow;
+    /**
+     * Remove a row that currently belongs to this table.
+     * Prefer {@link Table.rows}.remove for new code.
+     */
+    removeRow(row: TableRow): void;
+    /**
+     * Merge contiguous structural cells in one row (inclusive cell indexes).
+     */
+    applyHorizontalMerge(rowIndex: number, startCellIndex: number, endCellIndex: number): void;
+    /**
+     * Vertical merge along one grid column across inclusive row indexes.
+     */
+    applyVerticalMerge(columnIndex: number, startRowIndex: number, endRowIndex: number): void;
+    /**
+     * @private
+     */
+    mergeCells(range: MergeCellsRange): TableCell;
+    /**
+     * @private
+     */
+    splitCell(cell: TableCell): ReadonlyArray<TableCell>;
+    /**
+     * @private
+     */
+    getMergeRegion(cell: TableCell): MergeRegion | undefined;
+    private moveCellContentInto;
+    private ensureAtLeastOneParagraph;
+    private createBoundEmptyCell;
+    /**
+     * Re-paint every cell from current `w:tblPr/w:shd` fill (DocIO parity).
+     * No-op when table shading has no fill.
+     *
+     * @private
+     */
+    reapplyTableBackColorToCells(): void;
+    /**
+     * Copy table-level back fill onto one newly created cell.
+     *
+     * @private
+     */
+    paintTableBackColorOntoCell(cell: TableCell): void;
+    /**
+     * @private
+     */
+    bindDocument(document: WordDocument): void;
+    /**
+     * @private
+     */
+    toOpenXml(): OpenXmlElement;
+    private columnCount;
+    private gridColumnWidthsTwips;
+    private cellWidthFromGridTwips;
+    private applyFitToContent;
+    private applyFitToWindow;
+    private applyFixedColumnWidth;
+    private buildEmptyRow;
+    private buildEmptyRowWithColumns;
+    /**
+     * @private
+     * Effective cell width in points from the table grid (and cell span).
+     */
+    effectiveCellWidthPoints(cell: TableCell): number;
+}
+/**
+ * One row of a table — ordered cells with row-level formatting.
+ *
+ * @public
+ */
+export declare class TableRow implements TableCellCollectionHost<TableCell, Table>, RowFormatHost {
+    private readonly rowExtras;
+    private trPr;
+    private tableCells;
+    private boundDocument;
+    private ownerTableRef;
+    private readonly cellsInstance;
+    private readonly rowFormatInstance;
+    /**
+     * @private
+     */
+    constructor(extras: OpenXmlElement[], trPr: OpenXmlElement | undefined, cells: TableCell[], ownerTable?: Table);
+    /**
+     * @private
+     */
+    setOwnerTable(table: Table | undefined): void;
+    /** Cells collection (DocIO-aligned). */
+    readonly cells: TableCellCollection<TableCell>;
+    /**
+     * @private
+     */
+    listCells(): TableCell[];
+    /**
+     * @private
+     * Replace structural cells in this row (merge/split internal).
+     */
+    replaceCells(cells: TableCell[]): void;
+    /**
+     * @private
+     */
+    createEmptyCell(): TableCell;
+    /**
+     * @private
+     */
+    bindCell(cell: TableCell): void;
+    /**
+     * @private
+     */
+    minCellCount(): number;
+    /**
+     * @private
+     * Host probe for {@link TableCellCollection} (nullable; does not throw).
+     */
+    getOwnerTableOrUndefined(): Table | undefined;
+    /**
+     * @private
+     */
+    readTrPr(): OpenXmlElement | undefined;
+    /**
+     * @private
+     */
+    writeTrPr(next: OpenXmlElement | undefined): void;
+    /** Row-level format facade. */
+    readonly rowFormat: RowFormat;
+    /**
+     * Owning table. Throws {@link DetachedObjectError} when the row is detached.
+     */
+    readonly ownerTable: Table;
+    /**
+     * Row height in points (`w:trHeight/@w:val` twips on the wire).
+     * `0` when unset (auto height to content).
+     */
+    height: number;
+    /**
+     * How Word treats {@link TableRow.height} (`w:trHeight/@w:hRule`).
+     * Defaults to `'auto'` when unset.
+     */
+    heightType: TableRowHeightType;
+    /**
+     * When `true`, the row repeats at the top of every page the table spans
+     * (a repeating header row). Defaults to `false`.
+     */
+    isHeader: boolean;
+    /**
+     * @private
+     * Records the owning document so appended cells bind to it.
+     */
+    bindDocument(document: WordDocument): void;
+    /**
+     * @private
+     * Serializes the row back to its `w:tr` element.
+     */
+    /**
+     * Conditional table-style membership on `w:trPr/w:cnfStyle`.
+     *
+     * @public
+     */
+    getConditionalFormatting(): CnfStyle | undefined;
+    /**
+     * Write or clear row conditional formatting membership.
+     *
+     * @param state Normalized flags, or `undefined` to remove.
+     * @public
+     */
+    setConditionalFormatting(state: NormalizedCnfStyle | CnfStyle | undefined): void;
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * One cell of a table — a body container for paragraphs and nested tables,
+ * with cell-level settings such as width and formatting.
+ *
+ * Nested tables: call {@link Body.appendTable} on the cell, then
+ * {@link Table.resetCells} for size.
+ *
+ * @public
+ */
+export declare class TableCell extends Body implements CellFormatHost {
+    private tcPrValue;
+    private readonly cellFormatInstance;
+    private ownerRowRef;
+    /**
+     * Marks this body as a table-cell owner for {@link Paragraph.isInCell}.
+     *
+     * @private
+     */
+    readonly bodyOwnerKind: 'tableCell';
+    /**
+     * @private
+     */
+    constructor(document: WordDocument | undefined, blocks: ReadonlyArray<BlockContent>);
+    /**
+     * @private
+     */
+    setOwnerRow(row: TableRow | undefined): void;
+    /**
+     * @private
+     * Apply `w:tcPr` after parse (constructor only takes body blocks).
+     */
+    applyTcPr(tcPr: OpenXmlElement | undefined): void;
+    /**
+     * @private
+     */
+    readTcPr(): OpenXmlElement | undefined;
+    /**
+     * @private
+     */
+    writeTcPr(next: OpenXmlElement | undefined): void;
+    /** Cell-level format facade. */
+    readonly cellFormat: CellFormat;
+    /**
+     * Number of grid columns this cell spans (`w:tcPr/w:gridSpan`).
+     *
+     * @private
+     * Merge plumbing writes this value; public surface is
+     * {@link CellFormat.columnSpan}.
+     */
+    gridSpan: number | undefined;
+    /**
+     * Vertical merge wire state (`w:tcPr/w:vMerge`): `'restart'` | `'continue'`.
+     *
+     * @private
+     * Merge algorithm uses this; public surface is
+     * {@link CellFormat.verticalMerge} ({@link CellMerge}).
+     */
+    verticalMerge: VerticalMerge | undefined;
+    /**
+     * Outer width of the cell as authored (`w:tcPr/w:tcW`).
+     *
+     * @private
+     */
+    preferredWidth: TableWidth | undefined;
+    /**
+     * Preferred / effective cell width in points (1/72 inch).
+     *
+     * Fixed DXA `w:tcW` wins when present; otherwise the value is derived from
+     * the parent table grid. Never returns `undefined`.
+     */
+    width: number;
+    /**
+     * Plain text of the cell, concatenated across all paragraphs.
+     */
+    text: string;
+    /**
+     * Nested tables contained in this cell body (feature blocks).
+     * Prefer {@link TableCell.appendTable} to create nested tables.
+     */
+    readonly nestedTables: ReadonlyArray<Table>;
+    /**
+     * @private
+     * Binds the cell (and nested tables) to a document on attachment.
+     */
+    bindDocument(document: WordDocument): void;
+    /**
+     * @private
+     * Re-attach nested table ownership after construction / content moves.
+     */
+    private reattachNestedTables;
+    /**
+     * @private
+     * Serializes the cell back to its `w:tc` element.
+     */
+    /**
+     * Conditional table-style membership on `w:tcPr/w:cnfStyle`.
+     *
+     * @public
+     */
+    getConditionalFormatting(): CnfStyle | undefined;
+    /**
+     * Write or clear cell conditional formatting membership.
+     *
+     * @param state Normalized flags, or `undefined` to remove.
+     * @public
+     */
+    setConditionalFormatting(state: NormalizedCnfStyle | CnfStyle | undefined): void;
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * Create an empty table with empty cells (no auto-injected paragraphs).
+ * Authoring defaults (style/layout/equal widths) are applied by appendTable/resetCells.
+ *
+ * @private
+ */
+export declare function createTable(rowCount: number, columnCount: number): Table;
+/**
+ * @private
+ * Test hook
+ */
+export declare function resetTablesFeatureForTests(): void;
+/**
+ * @private
+ * Register the tables feature block handler. Idempotent.
+ */
+export declare function registerTablesFeature(): void;
+/**
+ * Feature id constant for the tables module (used by host features that embed
+ * table blocks, e.g. text box bodies in the drawing module).
+ *
+ * @private
+ */
+export declare const TABLES_FEATURE_ID: import("../../core/registry").FeatureId;
+/**
+ * Type guard for a tables feature block on a {@link BodyItem} list.
+ *
+ * @private
+ */
+export declare function isTableBlock(block: BodyItem | BlockContent | unknown): block is {
+    readonly type: 'feature';
+    readonly featureId: typeof TABLES;
+    readonly value: Table;
+};
+/** True when `value` is a public Table body item instance. */
+export declare function isTableBodyItem(value: unknown): value is Table;