@docx4j/core-ts 0.5.0 → 0.7.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
@@ -36,6 +37,15 @@ function attr(source, destination) {
 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) {
     return source === undefined ? destination : copyLeaf(source);
@@ -76,21 +86,37 @@ export function isEmptyRFonts(value) {
 }
 /**
  * A `w:color` stating only a theme colour is not empty: it is inherited, where until docx4j CR-034
- * (2e381ef26) it was dropped.
+ * (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) && value.themeColor === 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). */
+/**
+ * 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) && value.themeColor === 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) {
@@ -151,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
@@ -317,7 +345,7 @@ export const mergeColor = (source, destination) => {
         return destination;
     const s = source;
     const out = (destination !== null && destination !== void 0 ? destination : {});
-    if (statesColour(s.val, s.themeColor)) {
+    if (statesWordColour(s.val, s.themeColor)) {
         out.val = s.val;
         out.themeColor = s.themeColor;
         out.themeTint = s.themeTint;
@@ -336,7 +364,7 @@ export const mergeU = (source, destination) => {
     const s = source;
     const out = destination !== null && destination !== void 0 ? destination : {};
     out.val = attr(s.val, out.val);
-    if (statesColour(s.color, s.themeColor)) {
+    if (statesWordColour(s.color, s.themeColor)) {
         out.color = s.color;
         out.themeColor = s.themeColor;
         out.themeTint = s.themeTint;
@@ -536,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;
@@ -559,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/index.d.mts

@@ -1,6 +1,6 @@
 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 { PropertyResolver, headingLevelByName, WORD_DEFAULT_CELL_MARGIN_TWIPS, type ResolverSource, type PropertyResolverCreateOptions, } 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';

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, the Markdown export a refused link
+// target (CR-012 section 21), and the text options a deprecated spelling (section 29). 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/styleUtil.d.mts

@@ -1,9 +1,11 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
 import { type RunProps } from './catalogue.mjs';
-/** What the paragraph merge needs from the numbering part: a level's `w:ind`. */
+/** What the paragraph merge needs from the numbering part: a level's `w:ind`, and whether a list exists. */
 export interface NumberingIndents {
     /** The indent the level a `w:numPr` names contributes, or undefined. */
     getInd(numPr: wml.PPrBase.NumPr): wml.PPrBase.Ind | undefined;
+    /** The lists by `w:numId`, as a string. */
+    readonly instanceListDefinitions: ReadonlyMap<string, unknown>;
 }
 export declare function isEmptyRPr(rPr: RunProps | undefined): boolean;
 export declare function isEmptyPPrBase(pPrBase: wml.PPrBase | undefined): boolean;

package/dist/model/properties/styleUtil.mjs

@@ -154,20 +154,16 @@ export function toggle(upper, lower, documentDefault) {
 export function numberingOff(numPr) {
     return numPr !== undefined && numPr.numId !== undefined && numPr.numId.val === 0;
 }
-/** Take out of an indent the components a numbering level contributed. */
-function dropNumberingInd(ind, fromLevel) {
-    if (fromLevel.left !== undefined && fromLevel.left === ind.left)
-        delete ind.left;
-    if (fromLevel.right !== undefined && fromLevel.right === ind.right)
-        delete ind.right;
-    if (fromLevel.hanging !== undefined && fromLevel.hanging === ind.hanging)
-        delete ind.hanging;
-    if (fromLevel.firstLine !== undefined && fromLevel.firstLine === ind.firstLine)
-        delete ind.firstLine;
-    if (fromLevel.start !== undefined && fromLevel.start === ind.start)
-        delete ind.start;
-    if (fromLevel.end !== undefined && fromLevel.end === ind.end)
-        delete ind.end;
+/** What `w:numId 0` leaves of the indent it inherits: the right one. docx4j `dropLeftAndFirstLine`. */
+function dropLeftAndFirstLine(ind) {
+    delete ind.left;
+    delete ind.leftChars;
+    delete ind.start;
+    delete ind.startChars;
+    delete ind.hanging;
+    delete ind.hangingChars;
+    delete ind.firstLine;
+    delete ind.firstLineChars;
 }
 const IND_ONLY = new Set([IND]);
 /**
@@ -185,18 +181,18 @@ export function applyPPrBase(source, destination, numbering) {
         inheritedNumPr = { numId: destination.numPr.numId, ilvl: destination.numPr.ilvl };
     }
     applyCatalogue(PARAGRAPH, source, destination, IND_ONLY);
-    /* ECMA-376 17.9.18: w:numId w:val="0" takes the paragraph out of the list, so neither the
-     * level's label nor its w:ind applies - only the paragraph's own.  Only the components the
-     * inherited level contributed are dropped, so a w:ind the style states itself survives. */
+    /* ECMA-376 17.9.18: w:numId w:val="0" takes the paragraph out of the list, so neither the level's
+     * label nor any left, hanging or first-line indent inherited so far applies, wherever it was stated.
+     * The right indent stays, and a w:ind stated with the w:numId 0 or below it counts, since it is merged
+     * after this.  Where the inherited w:numPr names no list the rule doesn't apply.  docx4j 9e3100351,
+     * its probe numbering-off-style-ind, Word's goldens of 5 November 2026; CR-027. */
     if (numbering !== undefined && numberingOff(source.numPr)
         && inheritedNumPr !== undefined && inheritedNumPr.numId !== undefined
-        && !numberingOff(inheritedNumPr) && destination.ind !== undefined) {
-        const fromLevel = numbering.getInd(inheritedNumPr);
-        if (fromLevel !== undefined) {
-            const own = copyLeaf(destination.ind);
-            dropNumberingInd(own, fromLevel);
-            destination.ind = own;
-        }
+        && !numberingOff(inheritedNumPr) && destination.ind !== undefined
+        && numbering.instanceListDefinitions.has(String(inheritedNumPr.numId.val))) {
+        const own = copyLeaf(destination.ind);
+        dropLeftAndFirstLine(own);
+        destination.ind = own;
     }
     /* The indent of the level of the MERGED w:numPr, since a layer may state only w:ilvl (the
      * list from the style) or only w:numId (the level from the style): CR-015 probe

package/dist/model/properties/table.mjs

@@ -110,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;

package/dist/model/text/CaseMapping.d.mts

@@ -0,0 +1,38 @@
+import type { TextOptions } from './TextOptions.mjs';
+import { TextBlock, TextComment, TextRun } from './TextResult.mjs';
+/**
+ * The capitals Word shows for `w:caps`, written by the plain-text and Markdown writers (WD REQ-607; docx4j CR-069): each
+ * code point mapped to its single uppercase code point (Unicode's simple mapping, Java's `Character.toUpperCase(int)`),
+ * by the run's language, so that Turkish and Azeri `i` gives `İ` (U+0130); nothing expands, so `ß` stays `ß`, the
+ * ligature `fi` stays `fi`, and `dž` gives `DŽ`, not the titlecase `Dž`. Measured in Word for Microsoft 365 on 31 October 2026
+ * (docx4j's `caps-lang` probes, `test/text-extraction/suite/dpp/caps/`). Not `toUpperCase()` or `toLocaleUpperCase()`,
+ * whose full mapping expands `ß` to `SS` and `fi` to `FI`, which Word does not.
+ *
+ * A small-caps run is written as its stored characters, unless `small_caps: upper` is set, when it is mapped as a caps run
+ * is. The block model keeps the stored characters (`TextRun.text`), so that addresses, offsets and `officeOffset` refer to
+ * them; the mapping is the writers', and it keeps the length, in code points and in UTF-16 units.
+ *
+ * The Unicode version is 15.0 (`UNICODE_VERSION`), the version docx4j's tests run (JDK 21), from a table generated by
+ * `scripts/generate-case-mapping.mjs` (CR-012 section 24.1, D4), never the runtime's: Node's ICU is a later Unicode,
+ * whose simple mapping JavaScript doesn't expose, and which differs across Node versions. A case pair added after 15.0 is
+ * left unmapped, U+1C8A (Unicode 16.0) for one, as WD 0.52's REQ-607 has it. docx4j `CaseMapping`.
+ */
+export declare const CaseMapping: {
+    /** The language of last resort (docx4j `DEFAULT_LANGUAGE`). */
+    DEFAULT_LANGUAGE: string;
+    /** The Unicode version of the mapping. */
+    UNICODE_VERSION: string;
+    /**
+     * A text in capitals by a language (`w:lang/@w:val`, a BCP 47 tag such as `tr-TR`; undefined for `DEFAULT_LANGUAGE`):
+     * each code point to its single uppercase code point, `i` to `İ` where the language is Turkish or Azeri. A code point
+     * whose uppercase would change its length in UTF-16 is kept (none at 15.0; the generator leaves such a pair out).
+     */
+    upper(text: string, language?: string): string;
+    /** Whether a writer writes a run in capitals: a caps run, or a small-caps one under `small_caps: upper`. */
+    isUpper(run: TextRun, options: TextOptions | undefined): boolean;
+    /**
+     * As the writers write it: a run's stored text, in capitals where `isUpper`; a block's text (`TextBlock.text`) with each
+     * run's so; a comment's text (`TextComment.text`), its blocks a line apart, each so.
+     */
+    written(item: TextRun | TextBlock | TextComment, options: TextOptions | undefined): string;
+};

package/dist/model/text/CaseMapping.mjs

@@ -0,0 +1,86 @@
+// CR-012 section 24: the capitals Word shows for w:caps (WD REQ-607), docx4j's org.docx4j.model.text.CaseMapping
+// (its CR-069 phase 1, released in 17.3.5).
+import { CASE_MAPPING_UNICODE_VERSION, UPPERCASE_RUNS } from './caseMapping.generated.mjs';
+import { TextBlock, TextRun } from './TextResult.mjs';
+/** `default_language`'s default, the language where a run, its styles and the document defaults name none (WD 0.80's REQ-607). */
+const DEFAULT_LANGUAGE = 'en-US';
+/** The code point's simple uppercase mapping, by binary search over the generated runs; itself where it has none. */
+function upperOf(cp) {
+    let lo = 0;
+    let hi = UPPERCASE_RUNS.length / 4 - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const start = UPPERCASE_RUNS[mid * 4];
+        if (cp < start) {
+            hi = mid - 1;
+        }
+        else if (cp > UPPERCASE_RUNS[mid * 4 + 1]) {
+            lo = mid + 1;
+        }
+        else {
+            return (cp - start) % UPPERCASE_RUNS[mid * 4 + 3] === 0 ? cp + UPPERCASE_RUNS[mid * 4 + 2] : cp;
+        }
+    }
+    return cp;
+}
+/**
+ * The capitals Word shows for `w:caps`, written by the plain-text and Markdown writers (WD REQ-607; docx4j CR-069): each
+ * code point mapped to its single uppercase code point (Unicode's simple mapping, Java's `Character.toUpperCase(int)`),
+ * by the run's language, so that Turkish and Azeri `i` gives `İ` (U+0130); nothing expands, so `ß` stays `ß`, the
+ * ligature `fi` stays `fi`, and `dž` gives `DŽ`, not the titlecase `Dž`. Measured in Word for Microsoft 365 on 31 October 2026
+ * (docx4j's `caps-lang` probes, `test/text-extraction/suite/dpp/caps/`). Not `toUpperCase()` or `toLocaleUpperCase()`,
+ * whose full mapping expands `ß` to `SS` and `fi` to `FI`, which Word does not.
+ *
+ * A small-caps run is written as its stored characters, unless `small_caps: upper` is set, when it is mapped as a caps run
+ * is. The block model keeps the stored characters (`TextRun.text`), so that addresses, offsets and `officeOffset` refer to
+ * them; the mapping is the writers', and it keeps the length, in code points and in UTF-16 units.
+ *
+ * The Unicode version is 15.0 (`UNICODE_VERSION`), the version docx4j's tests run (JDK 21), from a table generated by
+ * `scripts/generate-case-mapping.mjs` (CR-012 section 24.1, D4), never the runtime's: Node's ICU is a later Unicode,
+ * whose simple mapping JavaScript doesn't expose, and which differs across Node versions. A case pair added after 15.0 is
+ * left unmapped, U+1C8A (Unicode 16.0) for one, as WD 0.52's REQ-607 has it. docx4j `CaseMapping`.
+ */
+export const CaseMapping = {
+    /** The language of last resort (docx4j `DEFAULT_LANGUAGE`). */
+    DEFAULT_LANGUAGE,
+    /** The Unicode version of the mapping. */
+    UNICODE_VERSION: CASE_MAPPING_UNICODE_VERSION,
+    /**
+     * A text in capitals by a language (`w:lang/@w:val`, a BCP 47 tag such as `tr-TR`; undefined for `DEFAULT_LANGUAGE`):
+     * each code point to its single uppercase code point, `i` to `İ` where the language is Turkish or Azeri. A code point
+     * whose uppercase would change its length in UTF-16 is kept (none at 15.0; the generator leaves such a pair out).
+     */
+    upper(text, language) {
+        if (text === '')
+            return text;
+        const dotted = dottedI(language);
+        let out = '';
+        for (const ch of text) {
+            const cp = ch.codePointAt(0);
+            out += String.fromCodePoint(dotted && cp === 0x69 ? 0x130 : upperOf(cp));
+        }
+        return out;
+    },
+    /** Whether a writer writes a run in capitals: a caps run, or a small-caps one under `small_caps: upper`. */
+    isUpper(run, options) {
+        return run.caps || (run.smallCaps && (options === null || options === void 0 ? void 0 : options.smallCaps) === 'upper');
+    },
+    /**
+     * As the writers write it: a run's stored text, in capitals where `isUpper`; a block's text (`TextBlock.text`) with each
+     * run's so; a comment's text (`TextComment.text`), its blocks a line apart, each so.
+     */
+    written(item, options) {
+        if (item instanceof TextRun)
+            return CaseMapping.isUpper(item, options) ? CaseMapping.upper(item.text, item.language) : item.text;
+        if (item instanceof TextBlock)
+            return item.textWith((r) => CaseMapping.written(r, options));
+        return item.blocks.map((b) => CaseMapping.written(b, options)).join('\n');
+    },
+};
+/** Whether a language's capital of `i` is the dotted `İ`: Turkish and Azeri, as Java's own casing has it. */
+function dottedI(language) {
+    if (language === undefined)
+        return false;
+    const primary = language.trim().split(/[-_]/, 1)[0].toLowerCase();
+    return primary === 'tr' || primary === 'az';
+}