@docx4j/core-ts 0.3.1 → 0.3.2

package/dist/model/properties/table.mjs

@@ -0,0 +1,315 @@
+import { isEmptyPPr, isEmptyRPr } from './styleUtil.mjs';
+import { rowsOf, cellsOf } from '../content/tree.mjs';
+import { PRECEDENCE, DEFAULT_LOOK, lookOf, rowBandSize, colBandSize, rowCnf, resolve, rowConditions, applicable, formatsText, key as conditionsKey, } from './tableStyleConditions.mjs';
+/** The conditions as bits over {@link PRECEDENCE}: an exact value for keying caches. */
+function maskOf(conditions) {
+    let mask = 0;
+    PRECEDENCE.forEach((t, i) => { if (conditions.has(t))
+        mask |= 1 << i; });
+    return mask;
+}
+/**
+ * The table level of a paragraph's formatting, as a value: two paragraphs whose keys are equal
+ * get the same contribution from their table. A structured key, never a joined string (docx4j
+ * CR-030 D8: ids may contain the separator); `mask` is the conditions as a number, so a cache
+ * keys on the table style id and then on it.
+ */
+export class CellContextKey {
+    constructor(tableStyleId, 
+    /** The conditional formats which give the paragraph text formatting, `wholeTable` included where the style has one. */
+    conditions) {
+        this.tableStyleId = tableStyleId;
+        this.conditions = conditions;
+        this.mask = maskOf(conditions);
+    }
+    equals(other) {
+        return other !== undefined && this.tableStyleId === other.tableStyleId && this.mask === other.mask;
+    }
+    toString() {
+        var _a;
+        return `${(_a = this.tableStyleId) !== null && _a !== void 0 ? _a : null} [${PRECEDENCE.filter((t) => this.conditions.has(t)).join(', ')}]`;
+    }
+}
+/**
+ * Where a paragraph sits in a table, as far as its formatting is concerned: the table style
+ * which applies to the table, and the conditional formats the paragraph is under. Handed to the
+ * `PropertyResolver` overloads which take one. Obtained from a {@link TableContext}
+ * (`forParagraph`), from a {@link TableContextTracker} during a walk, or from
+ * `PropertyResolver.cellContextOf(p)`. Undefined stands for "not in a table". Immutable.
+ */
+export class CellContext {
+    constructor(
+    /** The id of the table style the table resolves to, or undefined where none applies. */
+    tableStyleId, 
+    /** That style's `w:basedOn` chain merged (`getTableStyleChain`): shared, read it only. */
+    tableStyle, conditions) {
+        this.tableStyleId = tableStyleId;
+        this.tableStyle = tableStyle;
+        const c = new Set(conditions !== null && conditions !== void 0 ? conditions : []);
+        this.conditions = c;
+        const text = [];
+        const named = new Set();
+        for (const pr of applicable(tableStyle, c)) {
+            if (formatsText(pr)) {
+                text.push(pr);
+                named.add(pr.type);
+            }
+        }
+        this.textConditions = text;
+        this.formatsText = text.length > 0 || !isEmptyPPr(tableStyle.pPr) || !isEmptyRPr(tableStyle.rPr);
+        this.key = new CellContextKey(tableStyleId, named);
+    }
+    toString() {
+        var _a;
+        return `CellContext[${(_a = this.tableStyleId) !== null && _a !== void 0 ? _a : null} ${conditionsKey(this.conditions)}]`;
+    }
+}
+function gridOf(tr, name) {
+    var _a, _b, _c, _d;
+    for (const item of ((_b = (_a = tr.trPr) === null || _a === void 0 ? void 0 : _a.cnfStyleOrDivIdOrGridBefore) !== null && _b !== void 0 ? _b : [])) {
+        if (((_c = item === null || item === void 0 ? void 0 : item.name) === null || _c === void 0 ? void 0 : _c.localPart) === name) {
+            const val = (_d = item.value) === null || _d === void 0 ? void 0 : _d.val;
+            return typeof val === 'number' ? Math.max(0, Math.trunc(val)) : 0;
+        }
+    }
+    return 0;
+}
+/**
+ * What a table's paragraphs need to know about it to be formatted: the table style it resolves
+ * to (its `w:basedOn` chain merged), the conditional formats its `w:tblLook` asks for, its band
+ * sizes, and where each row and cell sits. {@link forParagraph} then gives the
+ * {@link CellContext} of a paragraph in one of its cells.
+ *
+ * A reading of the table's *content* (rows, spans, look), so it is built fresh for each table by
+ * `PropertyResolver.tableContext(tbl)` and held by the caller while it is in the table; the
+ * resolver keeps none (a cached one would go stale when a row is added). The rows and cells are
+ * counted with nested tables excluded, a cell's column its row's `w:gridBefore` plus the spans
+ * before it.
+ */
+export class TableContext {
+    /** Use `PropertyResolver.tableContext(tbl)`. */
+    constructor(tbl, resolver) {
+        this.rowIndex = new Map();
+        /** [first grid column, span] per cell */
+        this.cellColumns = new Map();
+        const tblPr = tbl.tblPr;
+        this.tableStyleId = resolver.getTableStyleIdOf(tblPr);
+        this.namesStyle = (tblPr === null || tblPr === void 0 ? void 0 : tblPr.tblStyle) !== undefined;
+        this.tableStyle = resolver.getTableStyleChain(this.tableStyleId);
+        // the table's own tblPr decides the look and band sizes; the style's is the fallback
+        const stylePr = this.tableStyle.tblPr;
+        if ((tblPr === null || tblPr === void 0 ? void 0 : tblPr.tblLook) !== undefined)
+            this.look = lookOf(tblPr.tblLook);
+        else if ((stylePr === null || stylePr === void 0 ? void 0 : stylePr.tblLook) !== undefined)
+            this.look = lookOf(stylePr.tblLook);
+        else
+            this.look = DEFAULT_LOOK;
+        this.rowBandSize = (tblPr === null || tblPr === void 0 ? void 0 : tblPr.tblStyleRowBandSize) !== undefined ? rowBandSize(tblPr) : rowBandSize(stylePr);
+        this.colBandSize = (tblPr === null || tblPr === void 0 ? void 0 : tblPr.tblStyleColBandSize) !== undefined ? colBandSize(tblPr) : colBandSize(stylePr);
+        const rows = rowsOf(tbl);
+        let cols = 0;
+        rows.forEach((located, r) => {
+            var _a, _b;
+            const tr = located.element.value;
+            this.rowIndex.set(tr, r);
+            let c = gridOf(tr, 'gridBefore');
+            for (const cell of cellsOf(tr)) {
+                const tc = cell.element.value;
+                const val = (_b = (_a = tc.tcPr) === null || _a === void 0 ? void 0 : _a.gridSpan) === null || _b === void 0 ? void 0 : _b.val;
+                const span = typeof val === 'number' ? Math.max(1, Math.trunc(val)) : 1;
+                this.cellColumns.set(tc, [c, span]);
+                c += span;
+            }
+            c += gridOf(tr, 'gridAfter');
+            if (c > cols)
+                cols = c;
+        });
+        this.rowCount = rows.length;
+        this.colCount = cols;
+    }
+    /**
+     * The context of a paragraph in this table: the conditions its row, its cell and its own
+     * `w:cnfStyle` caches say it is under, or its position where they say nothing. A row or cell
+     * this table does not hold (a nested table's, or one added since this context was built) is
+     * under no condition.
+     */
+    forParagraph(tr, tc, pPr) {
+        return new CellContext(this.tableStyleId, this.tableStyle, this.conditions(tr, tc, pPr));
+    }
+    /** The context of a cell, for its row and cell properties: {@link forParagraph} without a paragraph's own `w:cnfStyle`. */
+    forCell(tr, tc) {
+        return this.forParagraph(tr, tc, undefined);
+    }
+    /** The row-axis conditions a row is under, for its own properties; none for a row this table does not hold. */
+    rowConditions(tr) {
+        const r = tr === undefined ? undefined : this.rowIndex.get(tr);
+        if (r === undefined)
+            return new Set();
+        return rowConditions(this.look, this.rowBandSize, r, this.rowCount, rowCnf(tr.trPr));
+    }
+    /** The table style's `w:tblStylePr` entries which apply under these conditions, in order: all of them. */
+    applicable(conditions) {
+        return applicable(this.tableStyle, conditions);
+    }
+    /** The row's index in the table, nested tables excluded, or -1 for a row it does not hold. */
+    rowIndexOf(tr) {
+        const r = tr === undefined ? undefined : this.rowIndex.get(tr);
+        return r === undefined ? -1 : r;
+    }
+    conditions(tr, tc, pPr) {
+        var _a;
+        const r = tr === undefined ? undefined : this.rowIndex.get(tr);
+        const cc = tc === undefined ? undefined : this.cellColumns.get(tc);
+        if (r === undefined || cc === undefined)
+            return new Set();
+        return resolve(this.look, this.rowBandSize, this.colBandSize, r, this.rowCount, cc[0], cc[1], this.colCount, rowCnf(tr.trPr), (_a = tc.tcPr) === null || _a === void 0 ? void 0 : _a.cnfStyle, pPr === null || pPr === void 0 ? void 0 : pPr.cnfStyle);
+    }
+}
+const TBL = 'org_docx4j_wml.Tbl';
+const TR = 'org_docx4j_wml.Tr';
+const TC = 'org_docx4j_wml.Tc';
+const P = 'org_docx4j_wml.P';
+const TXBX_CONTENT = 'org_docx4j_wml.CTTxbxContent';
+/**
+ * The objects a walk entering which enters another story: `w:txbxContent`, and what a walk
+ * reaches it through (a VML text box, a DrawingML anchor or inline). Word gives the paragraphs
+ * of a text box anchored in a cell none of the table's formatting (docx4j CR-030 probe T3).
+ */
+const STORY_BOUNDARIES = new Set([
+    TXBX_CONTENT,
+    'org_docx4j_vml.CTTextbox',
+    'org_docx4j_dml_wordprocessingDrawing.Anchor',
+    'org_docx4j_dml_wordprocessingDrawing.Inline',
+]);
+/**
+ * Knows, for each paragraph a walk reaches, the table context the paragraph is in: the way to
+ * resolve every paragraph of a document in context (`PropertyResolver.cellContextOf(p)` builds a
+ * {@link TableContext} per call and is for one paragraph at a time).
+ *
+ * docx4j's is a `TraversalUtil` callback to extend; here it is the stack on its own, driven by
+ * any walker: call {@link enter} with each object before descending into it and the function it
+ * returns afterwards, and {@link cellContext} for each paragraph. {@link walk} is a walker that
+ * does so over a whole tree.
+ *
+ * The table on top of the stack is the paragraph's own (a nested table pushes its own context).
+ * A text box is a story of its own, so the walk starts an empty stack inside every text box and
+ * restores the cell's on the way out.
+ */
+export class TableContextTracker {
+    constructor(resolver) {
+        this.resolver = resolver;
+        /** One entry per table being walked, innermost last; a barrier (no table) inside a text box. */
+        this.stack = [];
+    }
+    /**
+     * Call before descending into an object (a `w:tbl`, `w:tr`, `w:tc`, or anything else: other
+     * types change nothing unless they begin a story); call what it returns after its children.
+     */
+    enter(o) {
+        var _a;
+        const typeName = o === null || o === void 0 ? void 0 : o.TYPE_NAME;
+        if (typeName === undefined)
+            return NOTHING;
+        const enclosing = this.stack[this.stack.length - 1];
+        if (typeName === TBL) {
+            // with no resolver, nothing is tracked: every paragraph is in no table
+            this.stack.push({ table: (_a = this.resolver) === null || _a === void 0 ? void 0 : _a.tableContext(o), tr: undefined, tc: undefined });
+            return () => { this.stack.pop(); };
+        }
+        if (STORY_BOUNDARIES.has(typeName)) {
+            this.stack.push({ table: undefined, tr: undefined, tc: undefined });
+            return () => { this.stack.pop(); };
+        }
+        if ((enclosing === null || enclosing === void 0 ? void 0 : enclosing.table) !== undefined && typeName === TR) {
+            const { tr, tc } = enclosing;
+            enclosing.tr = o;
+            enclosing.tc = undefined;
+            return () => { enclosing.tr = tr; enclosing.tc = tc; };
+        }
+        if ((enclosing === null || enclosing === void 0 ? void 0 : enclosing.table) !== undefined && typeName === TC) {
+            const tc = enclosing.tc;
+            enclosing.tc = o;
+            return () => { enclosing.tc = tc; };
+        }
+        return NOTHING;
+    }
+    /** The context of a paragraph reached by this walk, or undefined where it is in no table (or in a text box). */
+    cellContext(p) {
+        const f = this.stack[this.stack.length - 1];
+        if ((f === null || f === void 0 ? void 0 : f.table) === undefined)
+            return undefined;
+        return f.table.forParagraph(f.tr, f.tc, p.pPr);
+    }
+    /** The table the walk is in, or undefined (outside any table, or in a text box). */
+    tableContext() {
+        var _a;
+        return (_a = this.stack[this.stack.length - 1]) === null || _a === void 0 ? void 0 : _a.table;
+    }
+    /**
+     * Walks everything under `root` (an object, an element pair or an array of them), in document
+     * order, calling `visit` for each paragraph with its context. It descends through every
+     * member but the `PARENT` pointers, so a text box's paragraphs are reached, in no table.
+     */
+    walk(root, visit) {
+        const seen = new Set();
+        const descend = (o, depth) => {
+            if (o === null || typeof o !== 'object' || depth > 200)
+                return;
+            if (Array.isArray(o)) {
+                for (const item of o)
+                    descend(item, depth + 1);
+                return;
+            }
+            if (seen.has(o))
+                return;
+            seen.add(o);
+            const typeName = o.TYPE_NAME;
+            if (typeName === P)
+                visit(o, this.cellContext(o));
+            const leave = this.enter(o);
+            for (const key of Object.keys(o)) {
+                if (key === 'PARENT')
+                    continue;
+                descend(o[key], depth + 1);
+            }
+            leave();
+        };
+        descend(root, 0);
+    }
+}
+const NOTHING = () => { };
+/** The types at which a walk up the parent pointers has left the cell's story, or reached a story root. */
+const STORY_ROOTS = new Set([
+    TXBX_CONTENT, 'org_docx4j_wml.CTFtnEdn', 'org_docx4j_wml.Comments.Comment',
+    'org_docx4j_wml.Hdr', 'org_docx4j_wml.Ftr', 'org_docx4j_wml.Body', 'org_docx4j_wml.Document',
+]);
+/**
+ * The nearest enclosing cell, row and table of a paragraph, through its `PARENT` pointers and
+ * whatever lies between (`w:sdt`, `w:customXml`, `w:smartTag`); undefined where the paragraph is
+ * in no table, where a story begins before a cell is reached, or where the pointers are not
+ * there (content built by hand and never linked: `linkParents`).
+ */
+export function enclosingCellOf(p) {
+    let tc;
+    let tr;
+    const parentOf = (o) => o === null || o === void 0 ? void 0 : o.PARENT;
+    let hops = 0;
+    for (let o = parentOf(p); o !== undefined && o !== null && hops < 1000; o = parentOf(o), hops++) {
+        const typeName = o.TYPE_NAME;
+        if (typeName === undefined)
+            continue;
+        if (STORY_ROOTS.has(typeName))
+            return undefined;
+        if (typeName === TC) {
+            tc !== null && tc !== void 0 ? tc : (tc = o);
+        }
+        else if (typeName === TR) {
+            if (tc !== undefined && tr === undefined)
+                tr = o;
+        }
+        else if (typeName === TBL) {
+            return tr === undefined || tc === undefined ? undefined : { tbl: o, tr, tc };
+        }
+    }
+    return undefined;
+}

package/dist/model/properties/tableStyleConditions.d.mts

@@ -0,0 +1,101 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+export type Condition = wml.STTblStyleOverrideType;
+/**
+ * The order in which a table style's conditional formats are applied to a cell, later
+ * overriding earlier (ECMA-376-1 17.7.6).
+ */
+export declare const PRECEDENCE: readonly Condition[];
+/** Which conditional formats a table asks for: `w:tblPr/w:tblLook`, resolved. */
+export interface Look {
+    readonly firstRow: boolean;
+    readonly lastRow: boolean;
+    readonly firstColumn: boolean;
+    readonly lastColumn: boolean;
+    /** Horizontal (row) banding is on: `w:noHBand` is off. */
+    readonly hBand: boolean;
+    /** Vertical (column) banding is on: `w:noVBand` is off. */
+    readonly vBand: boolean;
+}
+/**
+ * What Word assumes where a table states no `w:tblLook` at all: its own default, `04A0` - first
+ * row, first column and row banding on, column banding off.
+ */
+export declare const DEFAULT_LOOK: Look;
+/**
+ * The look a `w:tblLook` states. The six attributes win where any of them is present; otherwise
+ * the legacy `w:val` bitmask (0x0020 firstRow, 0x0040 lastRow, 0x0080 firstColumn, 0x0100
+ * lastColumn, 0x0200 noHBand, 0x0400 noVBand); none, or an empty element, is {@link DEFAULT_LOOK}.
+ */
+export declare function lookOf(tblLook: wml.CTTblLook | undefined): Look;
+/** Whether a look lets the condition through at all. */
+export declare function lookAllows(look: Look, t: Condition): boolean;
+/**
+ * `w:tblStyleRowBandSize`, at least 1 where it is stated, and 0 where it is not: Word bands no
+ * row of a table whose style chain and own `w:tblPr` state no band size, whatever its `w:tblLook`
+ * and the style's band conditions (measured, docx4j CR-030 probes T9 and T10, D11: Word's re-save
+ * writes no band bit, and its PDF has no band formatting; a size stated by the table alone is
+ * enough). Until docx4j 0349796f9 an absent size was taken as 1.
+ */
+export declare function rowBandSize(tblPr: wml.CTTblPrBase | undefined): number;
+/**
+ * `w:tblStyleColBandSize`, as {@link rowBandSize} for the columns: 0, no vertical banding, where
+ * it is not stated. (By the rows' rule; the columns themselves were not probed in Word.)
+ */
+export declare function colBandSize(tblPr: wml.CTTblPrBase | undefined): number;
+/**
+ * The conditions a `w:cnfStyle` bitmask names: twelve characters, firstRow, lastRow,
+ * firstColumn, lastColumn, oddVBand, evenVBand, oddHBand, evenHBand, then the corners nw, ne,
+ * sw, se. A short string is read as far as it goes; none is the empty set.
+ */
+export declare function fromCnf(cnf: wml.CTCnf | string | undefined): Set<Condition>;
+/** The `w:cnfStyle` of a row, or undefined where the row states none. */
+export declare function rowCnf(trPr: wml.CTTrPrBase | undefined): wml.CTCnf | undefined;
+/** Remove the conditions the look does not allow (in place), and return the set. */
+export declare function gate(conditions: Set<Condition>, look?: Look): Set<Condition>;
+/**
+ * The conditions a cell is under by its position alone, with no `w:cnfStyle` to go by.
+ *
+ * Banding counts from the first row (column) which is not under a condition of its own: where
+ * the look has `firstRow` on, row 1 is the first banded row; a last row (column) the look gives
+ * its own condition is left out of the bands too. A band is `w:tblStyleRowBandSize` rows deep,
+ * and a size of 0 (none stated anywhere, see {@link rowBandSize}) bands nothing.
+ * A cell spanning several columns is placed by its first column, and is in the last column
+ * where its span reaches it.
+ */
+export declare function atPosition(look: Look, rowBand: number, colBand: number, row: number, rowCount: number, col: number, colSpan: number, colCount: number): Set<Condition>;
+/**
+ * The conditions a cell (or a paragraph in it) is under: the `w:cnfStyle` caches where the
+ * document has them, the position where it has not, gated by the look (docx4j
+ * `TableStyleConditions.resolve`).
+ *
+ * Word writes the row-axis bits on the `w:tr`, the column-axis bits on the `w:tc` and the
+ * row-axis bits again on each `w:p`, and never the corner bits. So the row's cache, where there
+ * is one, decides the row axis, the cell's the column axis, a paragraph's bits are added on
+ * whichever axis they name, and the corners are derived from the result. An axis with no cache
+ * falls back to {@link atPosition}. Every bit is then gated by the look, so a stale cache cannot
+ * switch on a format the table has turned off.
+ */
+export declare function resolve(look: Look, rowBand: number, colBand: number, row: number, rowCount: number, col: number, colSpan: number, colCount: number, rowCnfStyle: wml.CTCnf | undefined, cellCnf: wml.CTCnf | undefined, paraCnf: wml.CTCnf | undefined): Set<Condition>;
+/**
+ * The row-axis conditions a row is under - first row, last row, or a horizontal band - for the
+ * row's own properties: its `w:cnfStyle` where it has one, else its position, gated by the look.
+ */
+export declare function rowConditions(look: Look, rowBand: number, row: number, rowCount: number, rowCnfStyle: wml.CTCnf | undefined): Set<Condition>;
+/**
+ * The style's `w:tblStylePr` entry for a condition, or undefined. Pass the merged table style
+ * (`PropertyResolver.getTableStyleChain`) to see inherited conditions.
+ */
+export declare function lookup(tableStyle: wml.Style | undefined, type: Condition): wml.CTTblStylePr | undefined;
+/**
+ * The style's `w:tblStylePr` entries which apply under these conditions, in the order they are
+ * to be applied ({@link PRECEDENCE}); a `wholeTable` entry, where the style has one, always
+ * applies and comes first.
+ */
+export declare function applicable(tableStyle: wml.Style | undefined, conditions: ReadonlySet<Condition> | undefined): wml.CTTblStylePr[];
+/** Whether the entry has any paragraph or run formatting to contribute. */
+export declare function formatsText(pr: wml.CTTblStylePr | undefined): boolean;
+/**
+ * A short name for a set of conditions, in precedence order - `firstCol-firstRow-nwCell` - the
+ * form docx4j's goldens and synthetic style ids use; the empty string for none.
+ */
+export declare function key(conditions: ReadonlySet<Condition> | undefined): string;