@syncfusion/ej2-docx 0.0.0-stage → 35.1.39

package/src/features/tables/tbl-pr.d.ts

@@ -0,0 +1,528 @@
+/**
+ * Typed parse/serialize helpers for `w:tblPr` and shared table property types.
+ *
+ * Citations: Transitional `wml.xsd` `CT_TblPrBase`, `CT_TblWidth`, `CT_TblBorders`,
+ * `CT_TblCellMar`, `CT_TblLook`, `ST_JcTable`, `ST_TblWidth`.
+ */
+import { twipsToPoint, pointToTwips } from '../document/length';
+import { parseOnOff, serializeOnOff } from '../document/on-off';
+import { OpenXmlElement } from '../../core/xml/index';
+export { pointToTwips, twipsToPoint };
+/**
+ * Table / cell preferred width (`CT_TblWidth`).
+ *
+ * - `dxa`: `@w:w` is twips on the wire; `value` is stored as points (`twips / 20`).
+ * - `pct`: `@w:w` is fiftieths-of-a-percent; stored via the same twips→points bridge
+ *   so callers can round-trip with `pointToTwips(value)` recovering the fiftieths.
+ * - `auto` / `nil`: `value` is typically zero.
+ *
+ * @private
+ * Internal storage shape for table and cell width settings. Prefer
+ * the point-based {@link TableCell.width} accessor, or {@link Table.autoFit}.
+ */
+export interface TableWidth {
+    readonly type: 'auto' | 'dxa' | 'nil' | 'pct';
+    /** Preferred width in points (for `dxa`); see type notes for `pct`/`auto`/`nil`. */
+    readonly value: number;
+}
+/**
+ * One border edge of a table or table cell (`CT_Border` subset).
+ *
+ * A border is described by its line style, color, thickness, and the gap to
+ * the cell contents. Omitting a field lets Word apply its own default for
+ * that aspect; omitting the whole edge leaves the neighboring setting
+ * (table defaults or cell override) in charge.
+ *
+ * `size` is measured in eighths of a point (so a value of 8 draws a 1 pt
+ * line) and `space` in points.
+ */
+export interface TableBorder {
+    /**
+     * @private
+   * Border line token as stored in `@w:val` (e.g. `'single'`). */
+    readonly style?: string;
+    /** Border line color. Hex RGB (e.g. `'FF0000'`) or `'auto'`. */
+    readonly color?: string;
+    /** Line thickness in eighths of a point (`8` = 1 pt). */
+    readonly size?: number;
+    /** Gap between the line and the cell contents, in points. */
+    readonly space?: number;
+    /** Shadow flag from `w:shadow` on `CT_Border`. */
+    readonly shadow?: boolean;
+}
+/**
+ * Border settings for a whole table.
+ *
+ * The outer edges (`top`, `left`, `bottom`, `right`) frame the table;
+ * `insideH` and `insideV` draw the lines between rows and columns. Any edge
+ * left undefined falls back to Word's table style — set only the edges that
+ * must differ from the surrounding look.
+ *
+ * Borders set here apply to the table as a whole; individual cells can
+ * override them with {@link TableCell.borders}.
+ */
+export interface TableBorders {
+    /** Top edge of the table. */
+    readonly top?: TableBorder;
+    /** Left edge of the table. */
+    readonly left?: TableBorder;
+    /** Bottom edge of the table. */
+    readonly bottom?: TableBorder;
+    /** Right edge of the table. */
+    readonly right?: TableBorder;
+    /** Line between adjacent rows. */
+    readonly insideH?: TableBorder;
+    /** Line between adjacent columns. */
+    readonly insideV?: TableBorder;
+}
+/**
+ * Border settings for one table cell.
+ *
+ * Cell borders override the table-level borders for this cell. Configure the
+ * outer and inside edges the same way as {@link TableBorders}; any edge left
+ * undefined keeps the inherited table setting.
+ */
+export interface TableCellBorders extends TableBorders {
+    /**
+     * Diagonal from the top-left to the bottom-right corner (`w:tl2br`).
+     * @private
+     * Diagonal edge kept for round-trip; not part of the end-user
+     * cell-border surface.
+     */
+    readonly tl2br?: TableBorder;
+    /**
+     * Diagonal from the top-right to the bottom-left corner (`w:tr2bl`).
+     * @private
+     * Diagonal edge kept for round-trip; not part of the end-user
+     * cell-border surface.
+     */
+    readonly tr2bl?: TableBorder;
+}
+/**
+ * Padding between a cell's content and its borders, one value per side.
+ * `undefined` per side uses Word's default.
+ */
+export interface TableCellMargins {
+    /** Top padding in points (`w:top` DXA on the wire). */
+    readonly top?: number;
+    /** Right padding in points (`w:right` DXA on the wire). */
+    readonly right?: number;
+    /** Bottom padding in points (`w:bottom` DXA on the wire). */
+    readonly bottom?: number;
+    /** Left padding in points (`w:left` DXA on the wire). */
+    readonly left?: number;
+}
+/**
+ * Background shading of a table or table cell (`w:shd`).
+ *
+ * @private
+ * Internal storage shape. Pattern/color tokens map directly to
+ * `w:shd` attributes and are consumed by internal table plumbing.
+ */
+export interface TableShading {
+    readonly fill?: string;
+    readonly color?: string;
+    readonly pattern?: string;
+}
+/**
+ * Conditional formatting flags for table style banding (`w:tblLook`).
+ *
+ * @private
+ * Internal storage shape for `w:tblLook`; authored by table style
+ * plumbing rather than end-user code.
+ */
+export interface TableLook {
+    readonly firstRow?: boolean;
+    readonly lastRow?: boolean;
+    readonly firstCol?: boolean;
+    readonly lastCol?: boolean;
+    readonly noHBand?: boolean;
+    readonly noVBand?: boolean;
+}
+/**
+ * How Word interprets a table row's height (`ST_HeightRule`).
+ *
+ * - `auto`: the row grows and shrinks with its content.
+ * - `atLeast`: the height is a minimum; content can still push it taller.
+ * - `exact`: the height is fixed; overflow is clipped.
+ */
+export declare const TableRowHeightRule: {
+    Auto: string;
+    AtLeast: string;
+    Exact: string;
+};
+/** One of the {@link TableRowHeightRule} tokens. */
+export declare type TableRowHeightRule = (typeof TableRowHeightRule)[keyof typeof TableRowHeightRule];
+/**
+ * Height setting for a table row (`w:trHeight`).
+ *
+ * `value` is the measured height in **points** (`@w:val` twips on the wire);
+ * `rule` (see {@link TableRowHeightRule}) decides whether it is a minimum, a
+ * fixed value, or ignored.
+ */
+export interface TableRowHeight {
+    /** Row height in points (`@w:val` twips at serialize). */
+    readonly value: number;
+    readonly rule: TableRowHeightRule;
+}
+/**
+ * Horizontal alignment of a table or table row on the page
+ * (`w:jc` / `ST_JcTable` public subset).
+ *
+ * - {@link TableAlignment.Left}: hug the left margin (Word default; wire `left`).
+ * - {@link TableAlignment.Center}: center between the margins (wire `center`).
+ * - {@link TableAlignment.Right}: hug the right margin (wire `right`).
+ *
+ * @public
+ */
+export declare const TableAlignment: {
+    Left: "left";
+    Center: "center";
+    Right: "right";
+};
+/** One of the {@link TableAlignment} tokens. */
+export declare type TableAlignment = (typeof TableAlignment)[keyof typeof TableAlignment];
+/**
+ * Table column sizing algorithm (`w:tblLayout` / `ST_TblLayoutType`).
+ *
+ * @private
+ * Internal flag behind `Table.autoFit`; exposes raw wire tokens
+ * `autoFit` | `fixed` and defaults to `autoFit` when `w:tblLayout` is absent
+ * ([MS-OE376] 2.1.159; ECMA-376 §17.4.52–53). Prefer `Table.autoFit`.
+ */
+export declare type TableLayout = 'autoFit' | 'fixed';
+export declare function parseDecimalVal(raw: string | undefined): number | undefined;
+export declare function wmlAttrVal(el: OpenXmlElement, localName: string): string | undefined;
+/**
+ * Replace or remove all children with `localName`; append when missing.
+ * Preserves attributes and unmodeled siblings on the parent element.
+ */
+export declare function upsertPropChild(parent: OpenXmlElement, parentLocalName: string, localName: string, replacement: OpenXmlElement | undefined): OpenXmlElement;
+export declare function emptyPropsToUndefined(el: OpenXmlElement | undefined): OpenXmlElement | undefined;
+/**
+ * Parse `CT_TblWidth` (`@w:w`, `@w:type`).
+ *
+ * @private
+ */
+export declare function parseTblWidth(el: OpenXmlElement): TableWidth | undefined;
+/**
+ * Serialize `CT_TblWidth`.
+ *
+ * @private
+ */
+export declare function serializeTblWidth(localName: string, width: TableWidth): OpenXmlElement;
+/**
+ * Parse one `CT_Border`.
+ *
+ * @private
+ */
+export declare function parseBorderEdge(el: OpenXmlElement): TableBorder | undefined;
+/**
+ * Serialize one border edge element.
+ *
+ * `CT_Border` requires `@w:val`; an edge parsed without a style token
+ * (schema-invalid input) is skipped so the output stays schema-valid.
+ *
+ * @private
+ */
+export declare function serializeBorderEdge(localName: string, edge: TableBorder): OpenXmlElement | undefined;
+/**
+ * Parse table borders. Maps `start`→`left`, `end`→`right` (Strict → API).
+ *
+ * @private
+ */
+export declare function parseTblBorders(el: OpenXmlElement): TableBorders;
+/**
+ * Serialize table borders as Transitional `left`/`right` (Word parity).
+ * Preserves unmodeled children (e.g. Strict `start`/`end`) when rewriting.
+ *
+ * @private
+ */
+export declare function serializeTblBorders(borders: TableBorders, existing?: OpenXmlElement): OpenXmlElement;
+/**
+ * Parse cell borders including diagonals.
+ *
+ * @private
+ */
+export declare function parseTcBorders(el: OpenXmlElement): TableCellBorders;
+/**
+ * Serialize cell borders (`w:tcBorders`).
+ *
+ * @private
+ */
+export declare function serializeTcBorders(borders: TableCellBorders, existing?: OpenXmlElement): OpenXmlElement;
+/**
+ * Parse table/cell margins. Maps `start`→`left`, `end`→`right`.
+ *
+ * @private
+ */
+export declare function parseCellMargins(el: OpenXmlElement): TableCellMargins;
+/**
+ * Serialize margins container (`tblCellMar` or `tcMar`) with Transitional left/right.
+ *
+ * @private
+ */
+export declare function serializeCellMargins(containerLocalName: 'tblCellMar' | 'tcMar', margins: TableCellMargins, existing?: OpenXmlElement): OpenXmlElement;
+/**
+ * Parse `w:shd` (pattern is free string per task).
+ *
+ * @private
+ */
+export declare function parseShd(el: OpenXmlElement): TableShading;
+/**
+ * Serialize `w:shd` (order: pattern/val, color, fill).
+ *
+ * @private
+ */
+export declare function serializeShd(shd: TableShading): OpenXmlElement;
+/**
+ * Parse table/row `w:jc` → public left|center|right (start→left, end→right).
+ *
+ * @private
+ */
+export declare function parseTableAlignment(el: OpenXmlElement): TableAlignment | undefined;
+/**
+ * Serialize table/row alignment as Transitional left|center|right.
+ *
+ * @private
+ */
+export declare function serializeTableAlignment(alignment: TableAlignment): OpenXmlElement;
+/**
+ * Parse `w:tblLook` named onOff attrs and/or legacy hex `@w:val`.
+ *
+ * @private
+ */
+export declare function parseTblLook(el: OpenXmlElement): TableLook;
+/**
+ * Serialize `w:tblLook` with named onOff attributes (preferred over hex-only).
+ *
+ * @private
+ */
+export declare function serializeTblLook(look: TableLook): OpenXmlElement;
+/**
+ * Conditional formatting membership flags on a row or cell (`w:cnfStyle` / `CT_Cnf`).
+ *
+ * Named OnOff attributes match Transitional `CT_Cnf`. The transitional
+ * `@w:val` ST_Cnf 12-char bitmask is accepted on parse and emitted complete
+ * on serialize so dual-form consumers round-trip.
+ *
+ * @private
+ * Typed internal storage only — not a public TableRow/TableCell surface.
+ * Does not recompute membership from table layout (preserve-only).
+ */
+export interface CnfStyle {
+    readonly firstRow?: boolean;
+    readonly lastRow?: boolean;
+    readonly firstColumn?: boolean;
+    readonly lastColumn?: boolean;
+    readonly oddVBand?: boolean;
+    readonly evenVBand?: boolean;
+    readonly oddHBand?: boolean;
+    readonly evenHBand?: boolean;
+    readonly firstRowFirstColumn?: boolean;
+    readonly firstRowLastColumn?: boolean;
+    readonly lastRowFirstColumn?: boolean;
+    readonly lastRowLastColumn?: boolean;
+}
+/**
+ * Fully resolved `w:cnfStyle` membership — every named flag is present.
+ *
+ * @private
+ */
+export interface NormalizedCnfStyle {
+    readonly firstRow: boolean;
+    readonly lastRow: boolean;
+    readonly firstColumn: boolean;
+    readonly lastColumn: boolean;
+    readonly oddVBand: boolean;
+    readonly evenVBand: boolean;
+    readonly oddHBand: boolean;
+    readonly evenHBand: boolean;
+    readonly firstRowFirstColumn: boolean;
+    readonly firstRowLastColumn: boolean;
+    readonly lastRowFirstColumn: boolean;
+    readonly lastRowLastColumn: boolean;
+}
+/**
+ * All-false normalized conditional membership.
+ *
+ * @private
+ */
+export declare function createDefaultCnfStyle(): NormalizedCnfStyle;
+/**
+ * Coerce partial/optional {@link CnfStyle} into a fully boolean {@link NormalizedCnfStyle}.
+ *
+ * @private
+ */
+export declare function normalizeCnfStyle(state: CnfStyle | undefined): NormalizedCnfStyle;
+/**
+ * True when any named flag is true on a normalized state.
+ *
+ * @private
+ */
+export declare function normalizedCnfStyleHasTrue(state: NormalizedCnfStyle): boolean;
+/**
+ * Alias of {@link normalizedCnfStyleHasTrue} (DocIO placement helper name).
+ *
+ * @private
+ */
+export declare function hasAnyCnfStyleFlag(state: NormalizedCnfStyle): boolean;
+/**
+ * Parse `w:cnfStyle` named OnOff attributes and/or transitional `@w:val` ST_Cnf.
+ * Named attributes win when both forms are present (same rule as {@link parseTblLook}).
+ *
+ * @private
+ */
+export declare function parseCnfStyle(el: OpenXmlElement): CnfStyle;
+/**
+ * Serialize `w:cnfStyle` with `w:val` first, then all twelve named OnOff attrs
+ * as explicit `0`/`1`. Preserves unknown attributes, namespaces, and children.
+ *
+ * @private
+ */
+export declare function serializeCnfStyle(state: NormalizedCnfStyle, existing?: OpenXmlElement): OpenXmlElement;
+/**
+ * True when any `CnfStyle` flag is explicitly set (including `false`).
+ *
+ * @private
+ */
+export declare function cnfStyleIsEmpty(state: CnfStyle): boolean;
+/**
+ * @private
+ */
+export declare function readTableAlignment(tblPr: OpenXmlElement): TableAlignment | undefined;
+/**
+ * @private
+ */
+export declare function writeTableAlignment(tblPr: OpenXmlElement, alignment: TableAlignment | undefined): OpenXmlElement;
+/**
+ * @private
+ */
+export declare function readTableIndent(tblPr: OpenXmlElement): number | undefined;
+/**
+ * @private
+ */
+export declare function writeTableIndent(tblPr: OpenXmlElement, indent: number | undefined): OpenXmlElement;
+/**
+ * @private
+ */
+export declare function readTablePreferredWidth(tblPr: OpenXmlElement): TableWidth | undefined;
+/**
+ * @private
+ */
+export declare function writeTablePreferredWidth(tblPr: OpenXmlElement, width: TableWidth | undefined): OpenXmlElement;
+/**
+ * @private
+ */
+export declare function readTableBorders(tblPr: OpenXmlElement): TableBorders | undefined;
+/**
+ * @private
+ */
+export declare function writeTableBorders(tblPr: OpenXmlElement, borders: TableBorders | undefined): OpenXmlElement;
+/**
+ * @private
+ */
+export declare function readTableCellMargins(tblPr: OpenXmlElement): TableCellMargins | undefined;
+/**
+ * @private
+ */
+export declare function writeTableCellMargins(tblPr: OpenXmlElement, margins: TableCellMargins | undefined): OpenXmlElement;
+/**
+ * @private
+ */
+export declare function readTableCellSpacing(tblPr: OpenXmlElement): number | undefined;
+/**
+ * @private
+ */
+export declare function writeTableCellSpacing(tblPr: OpenXmlElement, spacing: number | undefined): OpenXmlElement;
+/**
+ * @private
+ */
+export declare function readTableShading(tblPr: OpenXmlElement): TableShading | undefined;
+/**
+ * @private
+ */
+export declare function writeTableShading(tblPr: OpenXmlElement, shading: TableShading | undefined): OpenXmlElement;
+/**
+ * @private
+ */
+export declare function readTableLook(tblPr: OpenXmlElement): TableLook | undefined;
+/**
+ * @private
+ */
+export declare function writeTableLook(tblPr: OpenXmlElement, look: TableLook | undefined): OpenXmlElement;
+/**
+ * @private
+ */
+export declare function readTableCaption(tblPr: OpenXmlElement): string | undefined;
+/**
+ * @private
+ */
+export declare function writeTableCaption(tblPr: OpenXmlElement, caption: string | undefined): OpenXmlElement;
+/**
+ * @private
+ */
+export declare function readTableDescription(tblPr: OpenXmlElement): string | undefined;
+/**
+ * @private
+ */
+export declare function writeTableDescription(tblPr: OpenXmlElement, description: string | undefined): OpenXmlElement;
+/**
+ * Read `w:tblStyle/@w:val`.
+ *
+ * @private
+ */
+export declare function readTableStyle(tblPr: OpenXmlElement): string | undefined;
+/**
+ * Write or clear `w:tblStyle`.
+ *
+ * @private
+ */
+export declare function writeTableStyle(tblPr: OpenXmlElement, styleId: string | undefined): OpenXmlElement;
+/**
+ * Read `w:tblLayout/@w:type` → public {@link TableLayout}.
+ *
+ * Absent element → `autoFit`. Unknown wire tokens leave the child untouched and
+ * return `autoFit` for the typed surface (extras preserved on the element).
+ *
+ * @private
+ */
+export declare function readTableLayout(tblPr: OpenXmlElement): TableLayout;
+/**
+ * Write `w:tblLayout`. Omit-on-default: `autoFit` removes the element;
+ * `fixed` emits `<w:tblLayout w:type="fixed"/>`.
+ *
+ * @private
+ */
+export declare function writeTableLayout(tblPr: OpenXmlElement, layout: TableLayout): OpenXmlElement;
+/**
+ * Read `w:tblStyleRowBandSize/@w:val` (`CT_DecimalNumber`).
+ *
+ * Absent or non-integer wire → `undefined` (consumer default band height is 1).
+ * Citations: ECMA-376-1 §17.7.6.7; Transitional `wml.xsd` `CT_TblPrBase`.
+ *
+ * @private
+ */
+export declare function readTableRowBandSize(tblPr: OpenXmlElement): number | undefined;
+/**
+ * Write or clear `w:tblStyleRowBandSize`. Emitted only when `size` is defined.
+ *
+ * @private
+ */
+export declare function writeTableRowBandSize(tblPr: OpenXmlElement, size: number | undefined): OpenXmlElement;
+/**
+ * Read `w:tblStyleColBandSize/@w:val` (`CT_DecimalNumber`).
+ *
+ * Absent or non-integer wire → `undefined` (consumer default band width is 1).
+ * Citations: ECMA-376-1 §17.7.6.5; Transitional `wml.xsd` `CT_TblPrBase`.
+ *
+ * @private
+ */
+export declare function readTableColumnBandSize(tblPr: OpenXmlElement): number | undefined;
+/**
+ * Write or clear `w:tblStyleColBandSize`. Emitted only when `size` is defined.
+ *
+ * @private
+ */
+export declare function writeTableColumnBandSize(tblPr: OpenXmlElement, size: number | undefined): OpenXmlElement;
+export { parseOnOff, serializeOnOff };