@docx4j/core-ts 0.3.1 → 0.4.0

package/dist/model/properties/PropertyResolver.mjs

@@ -2,9 +2,62 @@ import { deepCopy } from '@docx4j/generated-objects-ts';
 import { Docx4JException } from '../../opc/exceptions.mjs';
 import { log } from './log.mjs';
 import { NumberingDefinitions } from '../listnumbering/definitions.mjs';
-import { applyPPrBase, applyRPr, applyStyle, applyStyleLevel, applyTblPr, hasDirectFormattingPPr, hasDirectFormattingRPr, isCyclic, } from './styleUtil.mjs';
+import { applyPPr, applyPPrBase, applyRPr, applyStyle, applyStyleLevel, applyTblPr, applyToggles, hasDirectFormattingPPr, hasDirectFormattingRPr, isCyclic, isEmptyStyle, } from './styleUtil.mjs';
+import { TableContext, enclosingCellOf } from './table.mjs';
 /** The cache key for "no style" (a styles part with no default paragraph style). */
 const NO_STYLE = '';
+/** An empty table style: what a table with no style to apply contributes. Shared, never changed. */
+const NO_TABLE_STYLE = Object.freeze({ TYPE_NAME: 'org_docx4j_wml.Style' });
+/** Word's compatibility mode where the document states none (docx4j `CompatibilityOptions.DEFAULT_MODE`). */
+const DEFAULT_COMPATIBILITY_MODE = 12;
+const WORD_COMPAT_URI = 'http://schemas.microsoft.com/office/word';
+/** A `w:compatSetting` of Word's own (`w:uri` its namespace), by name. */
+function wordCompatSetting(settings, name) {
+    var _a, _b;
+    return (_b = (_a = settings === null || settings === void 0 ? void 0 : settings.compat) === null || _a === void 0 ? void 0 : _a.compatSetting) === null || _b === void 0 ? void 0 : _b.find((cs) => cs.uri === WORD_COMPAT_URI && cs.name === name);
+}
+/** `compatibilityMode` (11, 12, 14 or 15); 12 where none is stated or it is unreadable. */
+function compatibilityModeOf(settings) {
+    var _a;
+    const val = (_a = wordCompatSetting(settings, 'compatibilityMode')) === null || _a === void 0 ? void 0 : _a.val;
+    if (val === undefined || val === null)
+        return DEFAULT_COMPATIBILITY_MODE;
+    const text = String(val).trim();
+    // Integer.parseInt: an optional sign and decimal digits, nothing else
+    return /^[+-]?\d+$/.test(text) ? parseInt(text, 10) : DEFAULT_COMPATIBILITY_MODE;
+}
+/** Whether a Word compat setting is stated on (docx4j `CompatibilityOptions.setting(name, false)`). */
+function compatSettingOn(settings, name) {
+    var _a;
+    const val = (_a = wordCompatSetting(settings, name)) === null || _a === void 0 ? void 0 : _a.val;
+    if (val === undefined || val === null)
+        return false;
+    const v = String(val).trim().toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+/** A two-level cache: (paragraph style, table style) and then the conditions' mask - a structured key, never a joined string. */
+class CompositionCache {
+    constructor() {
+        this.byStyle = new Map();
+    }
+    get(styleId, key) {
+        var _a, _b, _c;
+        return (_c = (_a = this.byStyle.get(styleId !== null && styleId !== void 0 ? styleId : NO_STYLE)) === null || _a === void 0 ? void 0 : _a.get((_b = key.tableStyleId) !== null && _b !== void 0 ? _b : NO_STYLE)) === null || _c === void 0 ? void 0 : _c.get(key.mask);
+    }
+    set(styleId, key, value) {
+        var _a, _b;
+        let byTable = this.byStyle.get(styleId !== null && styleId !== void 0 ? styleId : NO_STYLE);
+        if (byTable === undefined)
+            this.byStyle.set(styleId !== null && styleId !== void 0 ? styleId : NO_STYLE, byTable = new Map());
+        let byMask = byTable.get((_a = key.tableStyleId) !== null && _a !== void 0 ? _a : NO_STYLE);
+        if (byMask === undefined)
+            byTable.set((_b = key.tableStyleId) !== null && _b !== void 0 ? _b : NO_STYLE, byMask = new Map());
+        byMask.set(key.mask, value);
+    }
+    clear() {
+        this.byStyle.clear();
+    }
+}
 /** 108 twips (0.08in): the left and right cell margin of Word's built-in Normal Table. */
 export const WORD_DEFAULT_CELL_MARGIN_TWIPS = 108;
 const HEADING_NAME = /^heading ([1-9])$/i;
@@ -40,6 +93,17 @@ export class PropertyResolver {
         /** The document defaults with the chain applied over them: what the style overloads return. */
         this.effectivePPrByStyle = new Map();
         this.effectiveRPrByStyle = new Map();
+        /** Each table style's `w:basedOn` chain merged, by id; styles only, so `refresh()` clears it. */
+        this.tableStyleChains = new Map();
+        /**
+         * A paragraph style composed over a table level, document defaults included; by (paragraph
+         * style, table level). What the overloads with a context start from, as
+         * `getEffectivePPr(styleId)` is what they start from without one.
+         */
+        this.composedPPrCache = new CompositionCache();
+        this.composedRPrCache = new CompositionCache();
+        /** See {@link appliesTableStyleSizeJcException}; read once per `refresh()`. */
+        this.tableStyleSizeJcException = true;
         /** Missing styles are logged once each per resolver. */
         this.missingLogged = new Set();
         this.source = provider();
@@ -70,9 +134,19 @@ export class PropertyResolver {
         const numberingPart = main.numberingDefinitionsPart;
         const privateStyles = stylesPart === undefined ? undefined : await stylesPart.readContents();
         const privateNumbering = numberingPart === undefined ? undefined : await numberingPart.readContents();
+        // the settings are read for two compatibility values (CR-007), privately, as the others are
+        const settingsPart = main.documentSettingsPart;
+        let privateSettings;
+        try {
+            privateSettings = settingsPart === undefined ? undefined : await settingsPart.readContents();
+        }
+        catch (e) {
+            log.warn(`The settings part could not be read; taking compatibility mode ${DEFAULT_COMPATIBILITY_MODE}: ${String(e)}`);
+        }
         return new PropertyResolver(() => ({
             styles: (stylesPart === null || stylesPart === void 0 ? void 0 : stylesPart.isUnmarshalled) === true ? stylesPart.contents : privateStyles,
             numbering: (numberingPart === null || numberingPart === void 0 ? void 0 : numberingPart.isUnmarshalled) === true ? numberingPart.contents : privateNumbering,
+            settings: (settingsPart === null || settingsPart === void 0 ? void 0 : settingsPart.isUnmarshalled) === true ? settingsPart.contents : privateSettings,
         }), () => stylesPart !== undefined && !stylesPart.isUnmarshalled);
     }
     /** Builds a resolver over object trees directly (a test, or parts already in hand). */
@@ -103,6 +177,10 @@ export class PropertyResolver {
         }
         if (this.defaultParagraphStyleId === undefined)
             log.warn('No default paragraph style!!');
+        // [MS-DOCX] overrideTableStyleFontSizeAndJustification: see appliesTableStyleSizeJcException
+        const settings = this.source.settings;
+        this.tableStyleSizeJcException = compatibilityModeOf(settings) < 15
+            && !compatSettingOn(settings, 'overrideTableStyleFontSizeAndJustification');
         // private copies: the resolver's defaults are its own, so nothing below writes into the
         // styles part (until CR-015 phase 3 the w:sz 20 default went into the part, and a docx
         // saved after an export carried it)
@@ -163,6 +241,7 @@ export class PropertyResolver {
         this.chainRPrCache.clear();
         this.effectivePPrByStyle.clear();
         this.effectiveRPrByStyle.clear();
+        this.clearTableCaches();
         this.missingLogged.clear();
         this.source = this.provider();
         this.init();
@@ -304,7 +383,15 @@ export class PropertyResolver {
         }
         return styleId;
     }
-    getEffectivePPr(arg) {
+    getEffectivePPr(arg, cellContext) {
+        if (cellContext !== undefined && cellContext.formatsText && typeof arg !== 'string') {
+            const composed = this.composedPPr(this.paragraphStyleOf(arg), cellContext);
+            if (!hasDirectFormattingPPr(arg))
+                return composed;
+            const effective = deepCopy(composed);
+            this.applyPPrLayer(arg, effective);
+            return effective;
+        }
         if (arg === undefined || typeof arg === 'string')
             return this.effectivePPrOfStyle(arg);
         const resolved = this.effectivePPrOfStyle(this.paragraphStyleOf(arg));
@@ -325,9 +412,14 @@ export class PropertyResolver {
         this.effectivePPrByStyle.set(key, resolved);
         return resolved;
     }
-    getEffectiveRPr(arg, pPr) {
+    getEffectiveRPr(arg, pPr, cellContext) {
         if (typeof arg === 'string')
             return this.effectiveRPrOfStyle(arg);
+        if (cellContext !== undefined && cellContext.formatsText) {
+            const inTable = deepCopy(this.composedRPr(this.paragraphStyleOf(pPr), cellContext));
+            this.applyCharacterStyleAndDirect(arg, inTable);
+            return inTable;
+        }
         const effective = deepCopy(this.documentDefaultRPr);
         applyRPr(this.getChainRPr(this.paragraphStyleOf(pPr)), effective);
         this.applyCharacterStyleAndDirect(arg, effective);
@@ -373,7 +465,14 @@ export class PropertyResolver {
      * properties, then the `w:pPr`'s own `w:rPr`. What sizes an empty paragraph, and what a list
      * label starts from.
      */
-    getEffectiveParagraphMarkRPr(pPr) {
+    getEffectiveParagraphMarkRPr(pPr, cellContext) {
+        if (cellContext !== undefined && cellContext.formatsText) {
+            // in a table cell: the table level beneath the paragraph style's (CR-007)
+            const inTable = deepCopy(this.composedRPr(this.paragraphStyleOf(pPr), cellContext));
+            if ((pPr === null || pPr === void 0 ? void 0 : pPr.rPr) !== undefined)
+                applyRPr(pPr.rPr, inTable);
+            return inTable;
+        }
         const effective = deepCopy(this.documentDefaultRPr);
         applyRPr(this.getChainRPr(this.paragraphStyleOf(pPr)), effective);
         if ((pPr === null || pPr === void 0 ? void 0 : pPr.rPr) !== undefined)
@@ -389,45 +488,209 @@ export class PropertyResolver {
      * The table style which applies, merged root-first down its `w:basedOn` chain, then the
      * table's own `w:tblPr` over it.
      *
-     * Word's built-in "Normal Table" (`w:tblInd` 0; cell margins 108 twips left and right, 0 top
-     * and bottom) underlies a table naming no style and a table whose chain reaches the
-     * document's default table style - and it is the built-in that applies, not the document's
-     * definition of that style (measured, CR-015 probe styles-table-default). So the default
-     * style's own layer is skipped in favour of the built-in, and a chain that does not reach it
-     * starts from nothing.
+     * Word goes by the style's **name** (measured, docx4j CR-030 probes T1, T2 and T7). A style
+     * named "Normal Table" is Word's built-in Normal Table (`w:tblInd` 0; cell margins 108 twips
+     * left and right, 0 top and bottom), whatever its own definition says and whether or not it is
+     * the document's default: the built-in stands in for it, and the walk up the chain ends there.
+     * Every other style applies as written, with nothing beneath it: a chain which reaches no style
+     * so named starts from nothing, and the document's default table style, where it is named
+     * otherwise, applies as written to a table naming no style. The built-in also stands in for a
+     * style which is missing, and where the document has no default table style. (Until CR-007 the
+     * built-in was decided by the default table style's *id*, as docx4j did until 17.3.1.)
      *
      * A new `Style` each call, with a non-null `w:tblPr`.
      */
     getEffectiveTableStyle(tblPr) {
-        var _a, _b;
-        const styleId = (_a = tblPr === null || tblPr === void 0 ? void 0 : tblPr.tblStyle) === null || _a === void 0 ? void 0 : _a.val;
-        const chain = styleId === undefined ? [] : this.ancestry(styleId);
-        const builtIn = chain.length === 0
-            || (this.defaultTableStyleId !== undefined && chain.some((s) => s.styleId === this.defaultTableStyleId));
-        const result = builtIn ? this.builtInTableNormal() : emptyTableStyle();
-        for (const layer of chain) {
-            // the built-in stands in for the document's definition of the default table style
-            if (this.defaultTableStyleId !== undefined && layer.styleId === this.defaultTableStyleId)
-                continue;
-            applyStyle(layer, result);
-        }
+        var _a;
+        const styleId = this.getTableStyleIdOf(tblPr);
+        const result = this.builtInTableNormalUnderlies(styleId) ? this.builtInTableNormal() : emptyTableStyle();
+        const chain = this.getTableStyleChain(styleId);
+        if (chain !== NO_TABLE_STYLE)
+            applyStyle(deepCopy(chain), result);
         if (tblPr !== undefined) {
             result.tblPr = applyTblPr(tblPr, result.tblPr);
         }
-        (_b = result.tblPr) !== null && _b !== void 0 ? _b : (result.tblPr = { TYPE_NAME: 'org_docx4j_wml.CTTblPrBase' });
+        (_a = result.tblPr) !== null && _a !== void 0 ? _a : (result.tblPr = { TYPE_NAME: 'org_docx4j_wml.CTTblPrBase' });
         return result;
     }
     /**
-     * Whether a table's style chain reaches the document's default table style - the flag
-     * {@link getEffectiveTableStyle} decides Word's built-in Normal Table by (a table naming no
-     * style counts as reaching it).
+     * Whether Word's built-in Normal Table underlies a table - the flag
+     * {@link getEffectiveTableStyle} decides by: the table's style chain (its own `w:tblStyle`,
+     * else the default table style) reaches a style *named* "Normal Table", or the style is
+     * missing, or there is none. Decided by name since CR-007; the method keeps docx4j's name
+     * from when it was decided by the default style's id.
      */
     reachesDefaultTableStyle(tblPr) {
-        var _a;
-        const styleId = (_a = tblPr === null || tblPr === void 0 ? void 0 : tblPr.tblStyle) === null || _a === void 0 ? void 0 : _a.val;
-        const chain = styleId === undefined ? [] : this.ancestry(styleId);
-        return chain.length === 0
-            || (this.defaultTableStyleId !== undefined && chain.some((s) => s.styleId === this.defaultTableStyleId));
+        return this.builtInTableNormalUnderlies(this.getTableStyleIdOf(tblPr));
+    }
+    builtInTableNormalUnderlies(styleId) {
+        if (styleId === undefined)
+            return true;
+        const chain = this.ancestry(styleId);
+        return chain.length === 0 || chain.some(isNamedNormalTable);
+    }
+    // ------------------------------------------------------------------ the table context (CR-007)
+    /**
+     * Whether [MS-DOCX]'s `overrideTableStyleFontSizeAndJustification` exception applies to this
+     * document: a default paragraph style's 12pt does not override the table style's size, nor its
+     * left justification the table style's, for paragraphs in tables. Measured with Word 365
+     * (docx4j CR-030 probes T5 and T6): it applies below compatibility mode 15 (a document stating
+     * no `compatibilityMode` is mode 12) where the setting is not on, and never in mode 15.
+     */
+    appliesTableStyleSizeJcException() {
+        return this.tableStyleSizeJcException;
+    }
+    /**
+     * The id of the table style a table resolves to: its own `w:tblStyle`, else the document's
+     * `w:default` table style, whatever its name; undefined where the table names none and the
+     * document has no default. (Whether that style contributes anything is
+     * {@link getTableStyleChain}'s question.)
+     */
+    getTableStyleIdOf(tblPr) {
+        return (tblPr === null || tblPr === void 0 ? void 0 : tblPr.tblStyle) !== undefined ? tblPr.tblStyle.val : this.defaultTableStyleId;
+    }
+    /**
+     * A table style's `w:basedOn` chain merged root-first, conditional formats merged per
+     * condition, as it gives the paragraphs of its tables their text formatting. Word goes by the
+     * style's *name*: a style named "Normal Table" is Word's built-in, which gives text nothing
+     * whatever its own definition says, so the walk up the chain ends below it; every other style
+     * applies as written, the default table style included.
+     *
+     * Cached per id, and shared: read it, do not change it. An empty style for undefined, for a
+     * missing style, and for a chain which is "Normal Table" all the way down.
+     */
+    getTableStyleChain(styleId) {
+        if (styleId === undefined)
+            return NO_TABLE_STYLE;
+        const cached = this.tableStyleChains.get(styleId);
+        if (cached !== undefined)
+            return cached;
+        const chain = this.ancestry(styleId);
+        let start = 0;
+        for (let i = chain.length - 1; i >= 0; i--) {
+            if (isNamedNormalTable(chain[i])) {
+                start = i + 1;
+                break;
+            }
+        }
+        let merged;
+        for (let i = start; i < chain.length; i++) {
+            const layer = chain[i];
+            // docx4j apply(Style, null): an empty layer leaves the destination as it is, null included
+            if (isEmptyStyle(layer))
+                continue;
+            merged = applyStyle(layer, merged !== null && merged !== void 0 ? merged : { TYPE_NAME: 'org_docx4j_wml.Style' });
+        }
+        const result = merged !== null && merged !== void 0 ? merged : NO_TABLE_STYLE;
+        this.tableStyleChains.set(styleId, result);
+        return result;
+    }
+    /**
+     * The context of a table, for the paragraphs in it: build one per table and hold it while
+     * walking the table (the resolver keeps none, since it reads the table's content).
+     */
+    tableContext(tbl) {
+        return new TableContext(tbl, this);
+    }
+    /**
+     * The table context of one paragraph, found through its `PARENT` pointers: the nearest
+     * enclosing cell, its row and its table, through 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 (a text box, a footnote, endnote or comment, a header, a
+     * footer, the body), or where the pointers are not there (unmarshalled content, and content
+     * the content API inserted, has them: `linkParents`).
+     *
+     * Each call builds a {@link TableContext}, a walk of the table's rows. That is right for "what
+     * formatting does this paragraph have"; code resolving every paragraph of a document walks it
+     * with a `TableContextTracker` instead, since calling this for each paragraph of a large table
+     * is quadratic.
+     */
+    cellContextOf(p) {
+        const found = enclosingCellOf(p);
+        return found === undefined ? undefined : this.tableContext(found.tbl).forParagraph(found.tr, found.tc, p.pPr);
+    }
+    clearTableCaches() {
+        this.tableStyleChains.clear();
+        this.composedPPrCache.clear();
+        this.composedRPrCache.clear();
+    }
+    /** The table level's `w:pPr`: the style's own, then its conditional formats'; undefined if none. */
+    tableLevelPPr(ctx) {
+        let out = applyPPr(ctx.tableStyle.pPr, undefined);
+        for (const pr of ctx.textConditions)
+            out = applyPPr(pr.pPr, out);
+        return out;
+    }
+    /** The table level's `w:rPr`: the style's own, then its conditional formats'; undefined if none. */
+    tableLevelRPr(ctx) {
+        let out = applyRPr(ctx.tableStyle.rPr, undefined);
+        for (const pr of ctx.textConditions)
+            out = applyRPr(pr.rPr, out);
+        return out;
+    }
+    /*
+     * The composition: document defaults, the table level over them, the paragraph style's chain
+     * over that (for the run properties a level of its own, the toggles combined), then the
+     * [MS-DOCX] exception. Cached per (paragraph style, table level).
+     */
+    composedPPr(styleId, ctx) {
+        const cached = this.composedPPrCache.get(styleId, ctx.key);
+        if (cached !== undefined)
+            return cached;
+        const tableLevel = this.tableLevelPPr(ctx);
+        const composed = deepCopy(this.documentDefaultPPr);
+        if (tableLevel !== undefined)
+            applyPPr(tableLevel, composed);
+        this.applyPPrLayer(this.getChainPPr(styleId), composed);
+        if (this.tableStyleSizeJcException && (tableLevel === null || tableLevel === void 0 ? void 0 : tableLevel.jc) !== undefined
+            && this.paragraphStyleGivesWay(styleId, false)) {
+            composed.jc = deepCopy(tableLevel.jc);
+        }
+        this.composedPPrCache.set(styleId, ctx.key, composed);
+        return composed;
+    }
+    composedRPr(styleId, ctx) {
+        const cached = this.composedRPrCache.get(styleId, ctx.key);
+        if (cached !== undefined)
+            return cached;
+        const tableOnly = this.tableLevelRPr(ctx);
+        const tableLevel = deepCopy(this.documentDefaultRPr);
+        if (tableOnly !== undefined)
+            applyRPr(tableOnly, tableLevel);
+        const paragraphLevel = this.getChainRPr(styleId);
+        const composed = deepCopy(tableLevel);
+        applyRPr(paragraphLevel, composed);
+        // the table and the paragraph style are two levels of the hierarchy: the twelve toggles
+        // combine across them rather than the paragraph's overriding (17.7.3)
+        applyToggles(paragraphLevel, tableLevel, this.documentDefaultRPr, composed);
+        if (this.tableStyleSizeJcException && (tableOnly === null || tableOnly === void 0 ? void 0 : tableOnly.sz) !== undefined
+            && this.paragraphStyleGivesWay(styleId, true)) {
+            composed.sz = deepCopy(tableOnly.sz);
+        }
+        this.composedRPrCache.set(styleId, ctx.key, composed);
+        return composed;
+    }
+    /**
+     * [MS-DOCX]'s exception, for a paragraph in a table whose style states a size (or a
+     * justification): the paragraph's style gives way to it if the style is the default paragraph
+     * style, or states no size (justification) of its own, and resolves to 12pt (left). A style of
+     * the paragraph's own which states one keeps it.
+     */
+    paragraphStyleGivesWay(styleId, size) {
+        var _a, _b, _c, _d;
+        const isDefault = styleId === undefined || styleId === this.defaultParagraphStyleId;
+        const express = this.getLiveStyle(styleId);
+        if (!isDefault && express !== undefined) {
+            if (size && ((_a = express.rPr) === null || _a === void 0 ? void 0 : _a.sz) !== undefined)
+                return false;
+            if (!size && ((_b = express.pPr) === null || _b === void 0 ? void 0 : _b.jc) !== undefined)
+                return false;
+        }
+        if (size) {
+            const effective = styleId === undefined ? undefined : this.effectiveRPrOfStyle(styleId);
+            return ((_c = effective === null || effective === void 0 ? void 0 : effective.sz) === null || _c === void 0 ? void 0 : _c.val) === 24;
+        }
+        return ((_d = this.effectivePPrOfStyle(styleId).jc) === null || _d === void 0 ? void 0 : _d.val) === 'left';
     }
     /** Word's built-in Normal Table, as a style: what it applies whatever the document's own definition says. */
     builtInTableNormal() {
@@ -502,6 +765,7 @@ export class PropertyResolver {
         this.chainRPrCache.clear();
         this.effectivePPrByStyle.clear();
         this.effectiveRPrByStyle.clear();
+        this.clearTableCaches();
         let ok = true;
         const basedOn = (_b = style.basedOn) === null || _b === void 0 ? void 0 : _b.val;
         if (basedOn !== undefined)
@@ -515,6 +779,11 @@ export class PropertyResolver {
 function twips(w) {
     return { TYPE_NAME: 'org_docx4j_wml.TblWidth', type: 'dxa', w };
 }
+/** Google Docs (Nov 2014) writes table styles without a `w:name`. */
+function isNamedNormalTable(style) {
+    var _a;
+    return ((_a = style.name) === null || _a === void 0 ? void 0 : _a.val) === 'Normal Table';
+}
 function emptyTableStyle() {
     return {
         TYPE_NAME: 'org_docx4j_wml.Style',

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

@@ -1,4 +1,7 @@
 export { type Property, type RunProps, type Merge, RUN, PARAGRAPH, TABLE, CELL, TOGGLES, TOGGLE_NAMES, IND, RUN_EXCLUDED, PARAGRAPH_EXCLUDED, TABLE_EXCLUDED, CELL_EXCLUDED, namedProperty, isEmptyOf, hasDirectFormattingOf, applyCatalogue, applyProperty, unsetCatalogue, copyLeaf, } from './catalogue.mjs';
 export * from './styleUtil.mjs';
 export { PropertyResolver, headingLevelByName, WORD_DEFAULT_CELL_MARGIN_TWIPS, type ResolverSource, } from './PropertyResolver.mjs';
+export * as TableStyleConditions from './tableStyleConditions.mjs';
+export { type Condition, type Look } from './tableStyleConditions.mjs';
+export { type TableStyleSource, type TableContextSource, CellContextKey, CellContext, TableContext, TableContextTracker, enclosingCellOf, } from './table.mjs';
 export { setLogger, type Logger } from './log.mjs';

package/dist/model/properties/index.mjs

@@ -6,4 +6,6 @@
 export { RUN, PARAGRAPH, TABLE, CELL, TOGGLES, TOGGLE_NAMES, IND, RUN_EXCLUDED, PARAGRAPH_EXCLUDED, TABLE_EXCLUDED, CELL_EXCLUDED, namedProperty, isEmptyOf, hasDirectFormattingOf, applyCatalogue, applyProperty, unsetCatalogue, copyLeaf, } from './catalogue.mjs';
 export * from './styleUtil.mjs';
 export { PropertyResolver, headingLevelByName, WORD_DEFAULT_CELL_MARGIN_TWIPS, } from './PropertyResolver.mjs';
+export * as TableStyleConditions from './tableStyleConditions.mjs';
+export { CellContextKey, CellContext, TableContext, TableContextTracker, enclosingCellOf, } from './table.mjs';
 export { setLogger } from './log.mjs';

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

@@ -0,0 +1,155 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type Condition, type Look } from './tableStyleConditions.mjs';
+/**
+ * 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 declare class CellContextKey {
+    readonly tableStyleId: string | undefined;
+    /** The conditional formats which give the paragraph text formatting, `wholeTable` included where the style has one. */
+    readonly conditions: ReadonlySet<Condition>;
+    /** The conditions as bits over {@link PRECEDENCE}. */
+    readonly mask: number;
+    constructor(tableStyleId: string | undefined, 
+    /** The conditional formats which give the paragraph text formatting, `wholeTable` included where the style has one. */
+    conditions: ReadonlySet<Condition>);
+    equals(other: CellContextKey | undefined): boolean;
+    toString(): string;
+}
+/**
+ * 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 declare class CellContext {
+    /** The id of the table style the table resolves to, or undefined where none applies. */
+    readonly tableStyleId: string | undefined;
+    /** That style's `w:basedOn` chain merged (`getTableStyleChain`): shared, read it only. */
+    readonly tableStyle: wml.Style;
+    /** The conditions the paragraph is under, gated by the table's `w:tblLook`. */
+    readonly conditions: ReadonlySet<Condition>;
+    /**
+     * The table style's conditional formats which apply here and give text a `w:pPr` or `w:rPr`,
+     * in the order they are applied (ECMA-376-1 17.7.6).
+     */
+    readonly textConditions: readonly wml.CTTblStylePr[];
+    /**
+     * Whether the table style gives this paragraph anything at all: its own `w:pPr` or `w:rPr`, or
+     * a conditional format with one. Where it does not, resolving with this context gives the same
+     * answer as resolving without one.
+     */
+    readonly formatsText: boolean;
+    /** What the table level's composition depends on. A value, for keying caches. */
+    readonly key: CellContextKey;
+    constructor(
+    /** The id of the table style the table resolves to, or undefined where none applies. */
+    tableStyleId: string | undefined, 
+    /** That style's `w:basedOn` chain merged (`getTableStyleChain`): shared, read it only. */
+    tableStyle: wml.Style, conditions: ReadonlySet<Condition> | undefined);
+    toString(): string;
+}
+/** What a {@link TableContext} needs of the resolver; `PropertyResolver` satisfies it. */
+export interface TableStyleSource {
+    getTableStyleIdOf(tblPr: wml.CTTblPrBase | undefined): string | undefined;
+    getTableStyleChain(styleId: string | undefined): wml.Style;
+}
+/**
+ * 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 declare class TableContext {
+    /** The id of the table style the table resolves to, or undefined. */
+    readonly tableStyleId: string | undefined;
+    /** Whether the table states its own `w:tblStyle` (rather than taking the default table style). */
+    readonly namesStyle: boolean;
+    /** The table style's chain merged; shared, read it only. */
+    readonly tableStyle: wml.Style;
+    readonly look: Look;
+    readonly rowBandSize: number;
+    readonly colBandSize: number;
+    readonly rowCount: number;
+    readonly colCount: number;
+    private readonly rowIndex;
+    /** [first grid column, span] per cell */
+    private readonly cellColumns;
+    /** Use `PropertyResolver.tableContext(tbl)`. */
+    constructor(tbl: wml.Tbl, resolver: TableStyleSource);
+    /**
+     * 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: wml.Tr | undefined, tc: wml.Tc | undefined, pPr?: wml.PPr | undefined): CellContext;
+    /** The context of a cell, for its row and cell properties: {@link forParagraph} without a paragraph's own `w:cnfStyle`. */
+    forCell(tr: wml.Tr | undefined, tc: wml.Tc | undefined): CellContext;
+    /** The row-axis conditions a row is under, for its own properties; none for a row this table does not hold. */
+    rowConditions(tr: wml.Tr | undefined): Set<Condition>;
+    /** The table style's `w:tblStylePr` entries which apply under these conditions, in order: all of them. */
+    applicable(conditions: ReadonlySet<Condition>): wml.CTTblStylePr[];
+    /** The row's index in the table, nested tables excluded, or -1 for a row it does not hold. */
+    rowIndexOf(tr: wml.Tr | undefined): number;
+    private conditions;
+}
+/** What a tracker needs of the resolver. */
+export interface TableContextSource {
+    tableContext(tbl: wml.Tbl): TableContext;
+}
+/**
+ * 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 declare class TableContextTracker {
+    private readonly resolver;
+    /** One entry per table being walked, innermost last; a barrier (no table) inside a text box. */
+    private readonly stack;
+    constructor(resolver: TableContextSource | undefined);
+    /**
+     * 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: unknown): () => void;
+    /** The context of a paragraph reached by this walk, or undefined where it is in no table (or in a text box). */
+    cellContext(p: wml.P): CellContext | undefined;
+    /** The table the walk is in, or undefined (outside any table, or in a text box). */
+    tableContext(): TableContext | undefined;
+    /**
+     * 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: unknown, visit: (p: wml.P, cellContext: CellContext | undefined) => void): void;
+}
+/**
+ * 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 declare function enclosingCellOf(p: wml.P): {
+    tbl: wml.Tbl;
+    tr: wml.Tr;
+    tc: wml.Tc;
+} | undefined;