@docx4j/core-ts 0.4.0 → 0.6.0

package/dist/model/properties/catalogue.mjs

@@ -1,3 +1,4 @@
+import { WordColors } from '../color/WordColors.mjs';
 // ---------------------------------------------------------------- copying
 /**
  * A structural copy of a leaf value, without its `PARENT` link: what the merges store, so
@@ -29,9 +30,21 @@ function emptyThemeColor(value) {
 function attr(source, destination) {
     return source === undefined ? destination : source;
 }
-/** docx4j `StyleUtil.apply(STThemeColor, STThemeColor)`: `none` does not override. */
-function themeColor(source, destination) {
-    return emptyThemeColor(source) ? destination : source;
+/**
+ * docx4j `StyleUtil.statesColour`: a colour's value or theme reference is stated, so the colour
+ * inherits as one (docx4j CR-034, 2e381ef26; see {@link mergeColor}).
+ */
+function statesColour(val, theme) {
+    return !emptyString(val) || !emptyThemeColor(theme);
+}
+/**
+ * docx4j `StyleUtil.statesWordColour` (its CR-060, 1d1b824a9): as {@link statesColour}, for a text or underline
+ * colour, whose value Word reads as absent where it rejects it ({@link WordColors.stated}: `F00`, `bogus`, `Auto`).
+ * A fill's or a border's colour keeps {@link statesColour}: Word reads any value there, one it rejects as automatic,
+ * which overrides a style's (CR-015 section 2, rule 5).
+ */
+function statesWordColour(val, theme) {
+    return WordColors.stated(val) || !emptyThemeColor(theme);
 }
 /** A merge with no per-attribute rule: a copy of the source where it has one, else the inherited. */
 export function mergeReplace(source, destination) {
@@ -71,14 +84,39 @@ export function isEmptyRFonts(value) {
             && emptyString(value.eastAsia) && value.eastAsiaTheme === undefined
             && emptyString(value.hAnsi) && value.hAnsiTheme === undefined);
 }
+/**
+ * A `w:color` stating only a theme colour is not empty: it is inherited, where until docx4j CR-034
+ * (2e381ef26) it was dropped. A value Word reads as absent (`F00`, `bogus`, `Auto`) is empty, so a style's
+ * colour beneath still shows, and only exactly `auto` overrides it (docx4j CR-060, {@link WordColors.stated};
+ * CR-015 section 2, rules 4 and 5).
+ */
 export function isEmptyColor(value) {
-    return value === undefined || emptyString(value.val);
+    return value === undefined
+        || (!WordColors.stated(value.val) && value.themeColor === undefined
+            && emptyString(value.themeTint) && emptyString(value.themeShade));
 }
+/**
+ * The underline's colour attributes count, the theme ones too (docx4j CR-034, 2e381ef26); a colour Word reads as
+ * absent doesn't (docx4j CR-060, {@link WordColors.stated}).
+ */
 export function isEmptyU(value) {
-    return value === undefined || (value.val === undefined && emptyString(value.color));
+    return value === undefined
+        || (value.val === undefined && !WordColors.stated(value.color) && value.themeColor === undefined
+            && emptyString(value.themeTint) && emptyString(value.themeShade));
+}
+/** `ST_HighlightColor`'s values, which Word compares case-exactly (docx4j `WordRepairs`). */
+const HIGHLIGHT_COLORS = new Set(['black', 'blue', 'cyan', 'green', 'magenta', 'red', 'yellow',
+    'white', 'darkBlue', 'darkCyan', 'darkGreen', 'darkMagenta', 'darkRed', 'darkYellow', 'darkGray', 'lightGray', 'none']);
+/** Whether a `w:highlight` value is one of `ST_HighlightColor`'s, compared case-exactly, as Word does (docx4j `WordRepairs.isHighlightColor`). */
+export function isHighlightColor(val) {
+    return val !== undefined && HIGHLIGHT_COLORS.has(val);
 }
+/**
+ * A value outside `ST_HighlightColor` (`YELLOW`, `bogus`), or none, is empty: Word's repair drops it, so a style's
+ * highlight beneath still shows (docx4j CR-060, its `StyleUtil.isEmpty(Highlight)`).
+ */
 export function isEmptyHighlight(value) {
-    return value === undefined || emptyString(value.val);
+    return value === undefined || !isHighlightColor(value.val);
 }
 /** @since CR-015 phase 1: a style stating only `w:lang` used to count as empty and was never applied. */
 export function isEmptyLang(value) {
@@ -139,16 +177,18 @@ export function isEmptyNumPr(value) {
         || ((value.numId === undefined || value.numId.val === undefined)
             && (value.ilvl === undefined || value.ilvl.val === undefined));
 }
-/** `w:anchorLock` defaults to true, so only an explicit `w:anchorLock="0"` makes a frame non-empty by itself. */
+/**
+ * Empty only with `w:anchorLock` absent too, as docx4j 82c64bf14 reads it (its CR-059: until then
+ * `isAnchorLock()`, which the schema's old `default="true"` made true for an absent attribute).
+ */
 export function isEmptyFramePr(value) {
-    var _a;
     return value === undefined
         || (value.dropCap === undefined && value.lines === undefined && value.w === undefined
             && value.h === undefined && value.vSpace === undefined && value.hSpace === undefined
             && value.wrap === undefined && value.hAnchor === undefined && value.vAnchor === undefined
             && value.x === undefined && value.xAlign === undefined
             && value.y === undefined && value.yAlign === undefined && value.hRule === undefined
-            && ((_a = value.anchorLock) !== null && _a !== void 0 ? _a : true));
+            && value.anchorLock === undefined);
 }
 function isEmptyTblWidth(value) {
     // @w:type is ignored, as docx4j does
@@ -291,28 +331,49 @@ export const mergeRFonts = (source, destination) => {
         out.hint = source.hint;
     return out;
 };
+/**
+ * A colour inherits as one (docx4j CR-034, 2e381ef26): where the source states a value or a theme
+ * reference, its value, theme colour, tint and shade replace the destination's together. Word
+ * draws a theme reference over the value written beside it, so taken one by one, a run's
+ * `w:val="FF0000"` under a style's `w:themeColor="accent1"` would keep the style's reference and
+ * draw accent1, where Word draws red. A tint or shade stated alone still inherits on its own. The
+ * same holds for the colours of `w:u`, `w:shd` (its pattern colour and its fill) and the borders.
+ * (Attribute by attribute until then, CR-015 phase 1.)
+ */
 export const mergeColor = (source, destination) => {
     if (isEmptyColor(source))
         return destination;
     const s = source;
     const out = (destination !== null && destination !== void 0 ? destination : {});
-    out.themeColor = themeColor(s.themeColor, out.themeColor);
-    out.themeShade = attr(s.themeShade, out.themeShade);
-    out.themeTint = attr(s.themeTint, out.themeTint);
-    out.val = attr(s.val, out.val);
+    if (statesWordColour(s.val, s.themeColor)) {
+        out.val = s.val;
+        out.themeColor = s.themeColor;
+        out.themeTint = s.themeTint;
+        out.themeShade = s.themeShade;
+    }
+    else {
+        out.themeShade = attr(s.themeShade, out.themeShade);
+        out.themeTint = attr(s.themeTint, out.themeTint);
+    }
     return out;
 };
-/** `w:val` and the colour attributes each inherit on their own (CR-015 phase 1). */
+/** `w:val` and the colour inherit on their own (CR-015 phase 1), the colour as one ({@link mergeColor}). */
 export const mergeU = (source, destination) => {
     if (isEmptyU(source))
         return destination;
     const s = source;
     const out = destination !== null && destination !== void 0 ? destination : {};
     out.val = attr(s.val, out.val);
-    out.color = attr(s.color, out.color);
-    out.themeColor = themeColor(s.themeColor, out.themeColor);
-    out.themeTint = attr(s.themeTint, out.themeTint);
-    out.themeShade = attr(s.themeShade, out.themeShade);
+    if (statesWordColour(s.color, s.themeColor)) {
+        out.color = s.color;
+        out.themeColor = s.themeColor;
+        out.themeTint = s.themeTint;
+        out.themeShade = s.themeShade;
+    }
+    else {
+        out.themeTint = attr(s.themeTint, out.themeTint);
+        out.themeShade = attr(s.themeShade, out.themeShade);
+    }
     return out;
 };
 /** `w:val`, `w:eastAsia` and `w:bidi` each name the language of one script range and each inherits. */
@@ -331,16 +392,29 @@ export const mergeShd = (source, destination) => {
         return destination;
     const s = source;
     const out = (destination !== null && destination !== void 0 ? destination : {});
-    out.color = attr(s.color, out.color);
-    out.fill = attr(s.fill, out.fill);
     out.val = attr(s.val, out.val);
-    out.themeTint = attr(s.themeTint, out.themeTint);
-    out.themeShade = attr(s.themeShade, out.themeShade);
-    out.themeFillTint = attr(s.themeFillTint, out.themeFillTint);
-    out.themeFillShade = attr(s.themeFillShade, out.themeFillShade);
-    // the enums only when the source states them (until CR-015 a null source cleared them)
-    out.themeColor = themeColor(s.themeColor, out.themeColor);
-    out.themeFill = themeColor(s.themeFill, out.themeFill);
+    // the pattern colour and the fill each inherit as one (see mergeColor), so a direct w:shd
+    // stating no fill still leaves an inherited w:themeFill (CR-015)
+    if (statesColour(s.color, s.themeColor)) {
+        out.color = s.color;
+        out.themeColor = s.themeColor;
+        out.themeTint = s.themeTint;
+        out.themeShade = s.themeShade;
+    }
+    else {
+        out.themeTint = attr(s.themeTint, out.themeTint);
+        out.themeShade = attr(s.themeShade, out.themeShade);
+    }
+    if (statesColour(s.fill, s.themeFill)) {
+        out.fill = s.fill;
+        out.themeFill = s.themeFill;
+        out.themeFillTint = s.themeFillTint;
+        out.themeFillShade = s.themeFillShade;
+    }
+    else {
+        out.themeFillTint = attr(s.themeFillTint, out.themeFillTint);
+        out.themeFillShade = attr(s.themeFillShade, out.themeFillShade);
+    }
     return out;
 };
 export const mergeBorder = (source, destination) => {
@@ -348,13 +422,20 @@ export const mergeBorder = (source, destination) => {
         return destination;
     const s = source;
     const out = (destination !== null && destination !== void 0 ? destination : {});
-    out.color = attr(s.color, out.color);
     out.space = attr(s.space, out.space);
     out.sz = attr(s.sz, out.sz);
-    out.themeColor = themeColor(s.themeColor, out.themeColor);
-    out.themeShade = attr(s.themeShade, out.themeShade);
-    out.themeTint = attr(s.themeTint, out.themeTint);
     out.val = attr(s.val, out.val);
+    // the colour inherits as one (see mergeColor)
+    if (statesColour(s.color, s.themeColor)) {
+        out.color = s.color;
+        out.themeColor = s.themeColor;
+        out.themeTint = s.themeTint;
+        out.themeShade = s.themeShade;
+    }
+    else {
+        out.themeShade = attr(s.themeShade, out.themeShade);
+        out.themeTint = attr(s.themeTint, out.themeTint);
+    }
     return out;
 };
 export const mergePBdr = (source, destination) => {
@@ -483,11 +564,10 @@ export const mergeTabs = (source, destination) => {
 };
 /**
  * `w:framePr`'s attributes each inherit on their own: a paragraph whose direct `w:framePr`
- * gives only `w:x`/`w:y` keeps the anchors its style states. `w:anchorLock` defaults to true,
- * and docx4j's merge writes that default out explicitly.
+ * gives only `w:x`/`w:y` keeps the anchors its style states, `w:anchorLock` among them (docx4j
+ * 82c64bf14 merges it as stated; until then its merge wrote `isAnchorLock()`'s default out).
  */
 export const mergeFramePr = (source, destination) => {
-    var _a;
     if (isEmptyFramePr(source))
         return destination;
     const s = source;
@@ -506,8 +586,7 @@ export const mergeFramePr = (source, destination) => {
     out.y = attr(s.y, out.y);
     out.yAlign = attr(s.yAlign, out.yAlign);
     out.hRule = attr(s.hRule, out.hRule);
-    // docx4j reads this through isAnchorLock(), which answers true when the attribute is absent
-    out.anchorLock = (_a = s.anchorLock) !== null && _a !== void 0 ? _a : true;
+    out.anchorLock = attr(s.anchorLock, out.anchorLock);
     return out;
 };
 const mergeTblWidth = (source, destination) => {

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

@@ -1,7 +1,7 @@
 export interface Logger {
     warn(message: string): void;
 }
-/** The logger property resolution writes to. */
+/** The logger property resolution and the Markdown export write to. */
 export declare const log: Logger;
 /** Replaces the sink; pass nothing to go back to `console.warn`. */
 export declare function setLogger(logger?: Logger): void;

package/dist/model/properties/log.mjs

@@ -1,7 +1,7 @@
-// The one place property resolution writes a diagnostic. docx4j logs through SLF4J; this
-// package has no logging framework, so a missing style or a style cycle goes to `console.warn`
-// behind a settable sink (an add-in that must stay silent, or a test that wants to assert what
-// was logged, replaces it).
+// The one place property resolution writes a diagnostic, and the Markdown export a refused link
+// target (CR-012 section 21). docx4j logs through SLF4J; this package has no logging framework, so
+// a missing style, a style cycle or a refused link goes to `console.warn` behind a settable sink
+// (an add-in that must stay silent, or a test that wants to assert what was logged, replaces it).
 //
 // Resolution logs a missing style *once per id* (a `w:pStyle` naming a deleted style is common
 // in real documents, and docx4j used to log one ERROR per paragraph); the resolver keeps that
@@ -13,7 +13,7 @@ const consoleLogger = {
     },
 };
 let sink = consoleLogger;
-/** The logger property resolution writes to. */
+/** The logger property resolution and the Markdown export write to. */
 export const log = {
     warn(message) {
         sink.warn(message);

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

@@ -40,9 +40,21 @@ export declare class CellContext {
     /**
      * 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.
+     * answer as resolving without one - except under [MS-DOCX]'s size exception, for which see
+     * {@link styleFormatsText}.
      */
     readonly formatsText: boolean;
+    /**
+     * Whether the table style formats text anywhere: its own `w:pPr` or `w:rPr`, or a conditional
+     * format with one, whether or not that condition holds for this paragraph. Below compatibility
+     * mode 15 this, not what applies here, is what brings [MS-DOCX]'s size exception into play:
+     * measured on docx4j's table-style-size-trigger probes (its corpus document 1912), a table
+     * style with only a `w:pPr`, only an `w:rPr` colour, or only a `firstRow` format sets every row
+     * of its table at the document defaults' size where Normal states 12pt - the `firstRow`
+     * format's second row included - while a style with none of these leaves Normal's 12pt.
+     * docx4j `styleFormatsText()` (900b6a212, 17.3.2).
+     */
+    readonly styleFormatsText: boolean;
     /** What the table level's composition depends on. A value, for keying caches. */
     readonly key: CellContextKey;
     constructor(
@@ -138,7 +150,9 @@ export declare class TableContextTracker {
     /**
      * 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.
+     * member but the `PARENT` pointers, so a text box's paragraphs are reached, in no table. A kept
+     * `mc:AlternateContent` is descended through its selected branch alone (`selectedBranchOf`,
+     * docx4j's `McMode.READ`), so a text box held in both branches is visited once (CR-010 phase 3).
      */
     walk(root: unknown, visit: (p: wml.P, cellContext: CellContext | undefined) => void): void;
 }

package/dist/model/properties/table.mjs

@@ -1,5 +1,5 @@
 import { isEmptyPPr, isEmptyRPr } from './styleUtil.mjs';
-import { rowsOf, cellsOf } from '../content/tree.mjs';
+import { rowsOf, cellsOf, selectedBranchOf, ALTERNATE_CONTENT } 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) {
@@ -43,6 +43,7 @@ export class CellContext {
     tableStyleId, 
     /** That style's `w:basedOn` chain merged (`getTableStyleChain`): shared, read it only. */
     tableStyle, conditions) {
+        var _a;
         this.tableStyleId = tableStyleId;
         this.tableStyle = tableStyle;
         const c = new Set(conditions !== null && conditions !== void 0 ? conditions : []);
@@ -56,7 +57,10 @@ export class CellContext {
             }
         }
         this.textConditions = text;
-        this.formatsText = text.length > 0 || !isEmptyPPr(tableStyle.pPr) || !isEmptyRPr(tableStyle.rPr);
+        const own = !isEmptyPPr(tableStyle.pPr) || !isEmptyRPr(tableStyle.rPr);
+        this.formatsText = text.length > 0 || own;
+        this.styleFormatsText = own
+            || ((_a = tableStyle.tblStylePr) !== null && _a !== void 0 ? _a : []).some((pr) => pr !== undefined && pr !== null && formatsText(pr));
         this.key = new CellContextKey(tableStyleId, named);
     }
     toString() {
@@ -106,14 +110,16 @@ export class TableContext {
             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);
+        // the rows and cells Word reads: a kept row- or cell-level mc:AlternateContent's selected branch (CR-013
+        // phase 2), so that its rows count for the first row, the last and the bands
+        const rows = rowsOf(tbl, 'read');
         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)) {
+            for (const cell of cellsOf(tr, 'read')) {
                 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;
@@ -248,7 +254,9 @@ export class TableContextTracker {
     /**
      * 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.
+     * member but the `PARENT` pointers, so a text box's paragraphs are reached, in no table. A kept
+     * `mc:AlternateContent` is descended through its selected branch alone (`selectedBranchOf`,
+     * docx4j's `McMode.READ`), so a text box held in both branches is visited once (CR-010 phase 3).
      */
     walk(root, visit) {
         const seen = new Set();
@@ -264,6 +272,10 @@ export class TableContextTracker {
                 return;
             seen.add(o);
             const typeName = o.TYPE_NAME;
+            if (typeName === ALTERNATE_CONTENT) {
+                descend(selectedBranchOf(o), depth + 1);
+                return;
+            }
             if (typeName === P)
                 visit(o, this.cellContext(o));
             const leave = this.enter(o);