@docx4j/core-ts 0.4.0 → 0.6.0

package/dist/model/listnumbering/Emulator.mjs

@@ -70,12 +70,23 @@ export class Emulator {
      * to.  The style itself, or any style it is based on, counts as the level's own.  Direct
      * formatting is never suppressed: a paragraph whose *own* `w:numPr` names such a level is
      * numbered.
+     *
+     * A level which names no style belongs to one all the same: the first paragraph style in
+     * styles.xml whose own `w:numPr` names it ({@link levelStyleId}, docx4j 17.3.4, measured in
+     * Word 365 on the three documents of docx4j's `LevelOwnerTest`).  Of two styles carrying such
+     * a level Word numbers the first in styles.xml - whatever their names, whichever the document
+     * uses first, whether or not it uses that style at all - and gives the other style's paragraphs
+     * no label and no count.  They keep the level's indent, which the effective indent already
+     * gives them.  A paragraph naming no style is the default paragraph style's in this check.
      */
     styleLinkedElsewhere(numId, ilvl, pStyleVal) {
         var _a, _b;
-        const linked = this.definitions.getLinkedStyleId(numId, ilvl);
+        const linked = this.levelStyleId(numId, ilvl);
         if (linked === undefined || linked === '')
             return false;
+        // a paragraph naming no style is in the default paragraph style, which can own a level
+        if (pStyleVal === undefined && this.resolver !== undefined)
+            pStyleVal = this.resolver.getDefaultParagraphStyleId();
         if (pStyleVal === undefined)
             return true;
         const seen = new Set();
@@ -89,6 +100,42 @@ export class Emulator {
         }
         return true;
     }
+    /**
+     * The paragraph style a numbering level belongs to: the one its `w:lvl/w:pStyle` names (the
+     * `w:num`'s override level's first, as {@link NumberingDefinitions.getLinkedStyleId} reads it),
+     * else the first paragraph style in styles.xml whose own `w:numPr` names a `w:num` on the same
+     * `w:abstractNum` at that level (its `w:ilvl`, 0 where it states none).  Undefined where neither:
+     * no style carries the level, so a paragraph reaches it only through its own `w:numPr`.
+     *
+     * The level is the `w:abstractNum`'s, not a `w:num`'s: a style reaching it through a second
+     * `w:num` is on the same level, even where that `w:num` overrides it with a `w:lvl` of its own.
+     * A style's level is its `w:numPr`'s `w:ilvl`, not the level whose `w:pStyle` names it, as Word
+     * reads it (ECMA-376 17.9.24 has the naming level). docx4j `Emulator.levelStyleId` (17.3.4).
+     *
+     * @param numId a `w:numId` (not 0)
+     * @param ilvl  a `w:ilvl`; undefined or empty for 0
+     */
+    levelStyleId(numId, ilvl) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const linked = this.definitions.getLinkedStyleId(numId, ilvl);
+        if (linked !== undefined && linked !== '')
+            return linked;
+        const abstract = (_a = this.definitions.list(numId)) === null || _a === void 0 ? void 0 : _a.abstractDefinition;
+        if (abstract === undefined)
+            return undefined;
+        const level = ilvl === undefined || ilvl === '' ? '0' : ilvl;
+        for (const style of (_c = (_b = this.resolver) === null || _b === void 0 ? void 0 : _b.getStylesInOrder()) !== null && _c !== void 0 ? _c : []) {
+            const own = (_d = style.pPr) === null || _d === void 0 ? void 0 : _d.numPr;
+            if (style.type !== 'paragraph' || style.styleId === undefined || ((_e = own === null || own === void 0 ? void 0 : own.numId) === null || _e === void 0 ? void 0 : _e.val) === undefined)
+                continue;
+            if (((_f = this.definitions.list(String(own.numId.val))) === null || _f === void 0 ? void 0 : _f.abstractDefinition) !== abstract)
+                continue;
+            const ownLevel = ((_g = own.ilvl) === null || _g === void 0 ? void 0 : _g.val) === undefined ? '0' : String(own.ilvl.val);
+            if (ownLevel === level)
+                return style.styleId;
+        }
+        return undefined;
+    }
     /**
      * The one resolution of numId and ilvl for a paragraph. docx4j `Emulator.resolve`
      * (CR-014 phase 3, which collapsed `getNumber`'s and `getInd`'s two copies onto it).
@@ -171,11 +218,13 @@ export class Emulator {
     }
     /**
      * The numbering reference a paragraph resolves to, without taking a number and without
-     * touching any state. docx4j `Emulator.numRefFor` (17.1.1); never undefined.
+     * touching any state. docx4j `Emulator.numRefFor` (17.1.1); never undefined.  A paragraph with
+     * no `w:pPr` resolves as an empty one, against the default paragraph style, as
+     * {@link getNumber} resolves it (docx4j `c283dffdb`, 17.3.4).
      */
     numRefFor(pPr) {
         if (pPr === undefined)
-            return NumRef.not('no pPr');
+            return this.resolve(undefined, undefined, undefined, false);
         const [pStyleVal, numId, ilvl] = readNumPr(pPr);
         return this.resolve(pStyleVal, numId, ilvl, numId !== undefined && numId !== '');
     }
@@ -184,11 +233,14 @@ export class Emulator {
      * The next number for a paragraph, from its `w:pPr` (its own `w:numPr`, else its style's),
      * counted in `state` or in this emulator's default state.
      *
+     * A paragraph with no `w:pPr` resolves as one with an empty `w:pPr` does, against the default
+     * paragraph style, which may be numbered (docx4j 17.3.4; before, it was not numbered).
+     *
      * @returns undefined where the paragraph is not numbered
      */
     getNumber(pPr, state) {
         if (pPr === undefined)
-            return undefined;
+            return this.getNumberOf(undefined, undefined, undefined, false, state);
         const [pStyleVal, numId, ilvl] = readNumPr(pPr);
         return this.getNumberOf(pStyleVal, numId, ilvl, numId !== undefined && numId !== '', state);
     }
@@ -280,13 +332,11 @@ export class Emulator {
     }
     /**
      * docx4j `Emulator.numRefFor(wmlPackage, pPr)`: where this paragraph's numbering resolves to,
-     * before any counting.  Never undefined; a package with no numbering part, a null `w:pPr` or
-     * a package whose `PropertyResolver` has not been built each answer {@link NumRef.notNumbered}
-     * with the reason.
+     * before any counting.  Never undefined; a package with no numbering part or a package whose
+     * `PropertyResolver` has not been built each answer {@link NumRef.notNumbered} with the reason.
+     * A null `w:pPr` resolves as an empty one (docx4j `c283dffdb`, 17.3.4).
      */
     static numRefFor(pkg, pPr) {
-        if (pPr === undefined)
-            return NumRef.not('no pPr');
         const part = numberingPartOf(pkg);
         if (part === undefined)
             return NumRef.not('no numbering part');
@@ -296,6 +346,10 @@ export class Emulator {
         }
         return part.getEmulator().numRefFor(pPr);
     }
+    /** docx4j `Emulator.levelStyleId(numberingPart, numId, levelId)`: the paragraph style a level belongs to. */
+    static levelStyleId(part, numId, ilvl) {
+        return part.getEmulator().levelStyleId(numId, ilvl);
+    }
     /** docx4j `Emulator.getInd(wmlPackage, pStyleVal, numId, levelId)`. */
     static getInd(pkg, pStyleVal, numId, ilvl) {
         var _a;

package/dist/model/listnumbering/definitions.mjs

@@ -1,3 +1,4 @@
+import * as f from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
 import { log } from '../properties/log.mjs';
 import { formatValue } from './formats.mjs';
 /** How many levels a list definition may have (ECMA-376: `w:ilvl` 0 to 8). */
@@ -216,6 +217,16 @@ export class LevelDefinition {
         return `LevelDefinition ${this.ilvl} ${(_a = this.numFmt) !== null && _a !== void 0 ? _a : '-'} ${JSON.stringify((_b = this.lvlText) !== null && _b !== void 0 ? _b : '')}`;
     }
 }
+/**
+ * What Word makes of a `w:lvl` without `w:ilvl`: level 0, with no number. docx4j
+ * `ListLevel.emptyLevelZero`; the document's own `w:lvl` is left as it is.
+ */
+function emptyLevelZero() {
+    const lvl = f.createLvl({ ilvl: 0 });
+    lvl.numFmt = f.createNumFmt({ val: 'none' });
+    lvl.lvlText = f.createLvlLvlText({ val: '' });
+    return lvl;
+}
 /**
  * One `w:abstractNum`: its levels, and - where it carries `w:numStyleLink` - the numbering style
  * whose definition it takes them from. docx4j `AbstractListNumberingDefinition`.
@@ -238,6 +249,13 @@ export class AbstractListDefinition {
     }
     /** Adds (or replaces) the level read from this `w:lvl`. docx4j `readLevel`. */
     readLevel(lvl) {
+        if (lvl.ilvl === undefined) {
+            // w:ilvl is required.  Word reads a w:lvl without it as level 0 and keeps none of its
+            // content - no number, no indent - and a later level 0 replaces it as usual (docx4j
+            // ListLevel, issue 593 at f6b87cd2f: probes 593-a and 593-b, Word 365, 2026-10-11)
+            log.warn('w:lvl without w:ilvl: read as an empty level 0, as Word does');
+            lvl = emptyLevelZero();
+        }
         const level = new LevelDefinition(String(lvl.ilvl), lvl);
         // the REFERENCING abstract list: a w:numStyleLink definition counts on its own (P2)
         level.abstractNumId = this.id;

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

@@ -1,6 +1,10 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type * as dml from '@docx4j/generated-objects-ts/modules/org_docx4j_dml';
 import { NumberingDefinitions } from '../listnumbering/definitions.mjs';
 import { CellContext, TableContext } from './table.mjs';
+import { ThemeColors } from '../color/ThemeColors.mjs';
+import type { ResolvedColor } from '../color/ResolvedColor.mjs';
+import { type DefaultTheme, type FontSettings } from '../fonts/defaultTheme.mjs';
 /** The parts the resolver reads. Structural, so this module imports no part class. */
 export interface ResolverSource {
     /** The styles part's `w:styles`, or undefined when the package has none. */
@@ -9,9 +13,14 @@ export interface ResolverSource {
     numbering?: wml.Numbering;
     /**
      * The settings part's `w:settings`, or undefined: read for the compatibility mode and
-     * `overrideTableStyleFontSizeAndJustification` (CR-007). A document with none is in mode 12.
+     * `overrideTableStyleFontSizeAndJustification` (CR-007), and `w:clrSchemeMapping` (CR-008).
+     * A document with none is in mode 12.
      */
     settings?: wml.CTSettings;
+    /** The theme part's `a:theme`, or undefined where the package has none (CR-008). */
+    theme?: dml.Theme;
+    /** The bundled theme a package with no theme part is read as having; `defaultThemeSetting()`'s where undefined. */
+    defaultTheme?: DefaultTheme;
 }
 /** As much of an `XmlPart<T>` as the resolver uses. */
 interface ReadablePart<T> {
@@ -25,7 +34,9 @@ interface PackageLike {
         styleDefinitionsPart?: ReadablePart<wml.Styles>;
         numberingDefinitionsPart?: ReadablePart<wml.Numbering>;
         documentSettingsPart?: ReadablePart<wml.CTSettings>;
+        themePart?: ReadablePart<dml.Theme>;
     };
+    fonts?: FontSettings;
 }
 /** 108 twips (0.08in): the left and right cell margin of Word's built-in Normal Table. */
 export declare const WORD_DEFAULT_CELL_MARGIN_TWIPS = 108;
@@ -48,6 +59,8 @@ export declare class PropertyResolver {
     /** A style's `w:basedOn` chain merged root-first, WITHOUT the document defaults, per style id. */
     private readonly chainPPrCache;
     private readonly chainRPrCache;
+    /** A character style's chain as it applies to a run, where it differs from its chain: see {@link characterLevel}. */
+    private readonly characterLevelCache;
     /** The document defaults with the chain applied over them: what the style overloads return. */
     private readonly effectivePPrByStyle;
     private readonly effectiveRPrByStyle;
@@ -62,6 +75,14 @@ export declare class PropertyResolver {
     private readonly composedRPrCache;
     /** See {@link appliesTableStyleSizeJcException}; read once per `refresh()`. */
     private tableStyleSizeJcException;
+    /**
+     * Whether the document's own `w:docDefaults` state a size, rather than the 10pt the resolver
+     * makes explicit where they do not: the size exception takes the document defaults' size only
+     * where they state one. Read once per `refresh()`.
+     */
+    private docDefaultsStateSize;
+    /** Whether a paragraph style and a character style hide a run, by paragraph style then character style (`isVanishedByStyles`). */
+    private readonly vanishCache;
     /** Missing styles are logged once each per resolver. */
     private readonly missingLogged;
     private numberingDefinitions;
@@ -98,6 +119,28 @@ export declare class PropertyResolver {
      * contents replaced. The content API calls it where it creates a style.
      */
     refresh(): void;
+    private themeColors;
+    /**
+     * The document's theme colours: its theme part (or the bundled theme `pkg.fonts.defaultTheme` names where it has
+     * none) and the settings' `w:clrSchemeMapping`. Read once per `refresh()`. A resolver made `fromSource` with no
+     * theme parses the bundled one, which needs the objects package's context built (`ThemeColors.loadDefaultTheme()`).
+     */
+    getThemeColors(): ThemeColors;
+    /**
+     * The colour Word draws for a run's `w:color`: its theme reference where it has one (the value beside it is a
+     * cache), else its value.
+     *
+     * @returns undefined for automatic: the caller's default (black text, as a rule)
+     */
+    resolveColor(color: wml.Color | undefined): ResolvedColor | undefined;
+    /** A border's colour, as {@link resolveColor}; undefined for automatic. docx4j `resolveColor(CTBorder)`. */
+    resolveBorderColor(border: wml.CTBorder | undefined): ResolvedColor | undefined;
+    /** An underline's colour, as {@link resolveColor}; undefined for automatic (the text's). docx4j `resolveColor(U)`. */
+    resolveUnderlineColor(u: wml.U | undefined): ResolvedColor | undefined;
+    /** A shading's fill (`w:fill`, `w:themeFill`); undefined for automatic. */
+    resolveFill(shd: wml.CTShd | undefined): ResolvedColor | undefined;
+    /** A shading's pattern colour (`w:color`, `w:themeColor`); undefined for automatic. */
+    resolvePatternColor(shd: wml.CTShd | undefined): ResolvedColor | undefined;
     getDocumentDefaultPPr(): wml.PPr;
     getDocumentDefaultRPr(): wml.RPr;
     /** The style id of the `w:default="1"` paragraph style, or undefined when the part declares none. */
@@ -106,6 +149,13 @@ export declare class PropertyResolver {
     getResolvedDefaultParagraphStyle(): wml.PPr;
     /** The style with this id, or undefined (docx4j `getStyle`). */
     getStyle(styleId: string | undefined): wml.Style | undefined;
+    /**
+     * The styles part's `w:style` elements in document order, from the tree this resolver reads (its
+     * private copy, or the part's own once that is unmarshalled); empty where there is no styles part.
+     * docx4j reads `StyleDefinitionsPart.getJaxbElement().getStyle()` where order matters
+     * (`Emulator.levelStyleId`: the first paragraph style in styles.xml carrying a level owns it).
+     */
+    getStylesInOrder(): readonly wml.Style[];
     /**
      * The list definitions of the numbering part this resolver read (CR-001 Phase B step 3), or
      * undefined where the package has none. The resolver builds them because the paragraph merge
@@ -132,6 +182,13 @@ export declare class PropertyResolver {
      * object: copy before changing.
      */
     getChainRPr(styleId: string | undefined): wml.RPr;
+    /**
+     * A character style's chain as a level over a run or a paragraph mark: {@link getChainRPr} without its highlight,
+     * since Word draws no highlight from a character style (docx4j CR-060 section 13, round 6: alone, with bold, or
+     * through `w:basedOn`; its save writes `w:highlight="none"` on such a run). A paragraph style's highlight and a
+     * run's own are drawn. docx4j `characterLevel` (1d1b824a9). Cached; live: copy before changing.
+     */
+    private characterLevel;
     /**
      * A style's own `w:pPr` as a layer of its chain. The built-in heading styles have a fixed
      * outline level, which Word takes from the style's built-in NAME ("heading 1" ...
@@ -193,6 +250,14 @@ export declare class PropertyResolver {
      * context resolves exactly as `getEffectiveRPr(rPr, pPr)`. A new object each call.
      */
     getEffectiveRPr(rPr: wml.RPr | undefined, pPr: wml.PPr | undefined, cellContext: CellContext | undefined): wml.RPr;
+    /**
+     * Whether a run with no `w:vanish` of its own is hidden by its styles: the effective `w:vanish` of its
+     * paragraph style (undefined: the default paragraph style) and its character style, the table style left
+     * out, as the text model's hidden rule has it (REQ-507). What `Paragraph.text` leaves out, as Office JS
+     * does (CR-012 phase 4, check 48b case 20). Cached per pair; a pair naming a style the part lacks is
+     * not cached, so that adding the style is seen.
+     */
+    isVanishedByStyles(paragraphStyleId: string | undefined, runStyleId: string | undefined): boolean;
     private effectiveRPrOfStyle;
     /**
      * The character style's chain, then the direct formatting.
@@ -205,10 +270,18 @@ export declare class PropertyResolver {
     private applyCharacterStyleAndDirect;
     /**
      * The run properties of the paragraph mark: document defaults, the paragraph style's run
-     * properties, then the `w:pPr`'s own `w:rPr`. What sizes an empty paragraph, and what a list
-     * label starts from.
+     * properties, the mark's character style, then the `w:pPr`'s own `w:rPr`. What sizes an empty
+     * paragraph, and what a list label starts from.
      */
     getEffectiveParagraphMarkRPr(pPr: wml.PPr | undefined, cellContext?: CellContext | undefined): wml.RPr;
+    /**
+     * The paragraph mark's character style (`w:pPr/w:rPr/w:rStyle`) as a level over what is
+     * beneath it, then the mark's direct formatting: the order {@link applyCharacterStyleAndDirect}
+     * gives a run. docx4j `applyMarkRPr`, since 17.3.2 (fb2a764f7: until then the mark's
+     * `w:rStyle` was copied as an attribute and never resolved, so an empty paragraph whose mark
+     * names a 9pt character style was sized at its paragraph style's 12pt).
+     */
+    private applyMarkRPr;
     /** Whether the run states any formatting of its own (docx4j's deprecated `hasDirectRPrFormatting`). */
     hasDirectRPrFormatting(rPr: wml.RPr | undefined): boolean;
     /**
@@ -282,6 +355,12 @@ export declare class PropertyResolver {
      * is quadratic.
      */
     cellContextOf(p: wml.P): CellContext | undefined;
+    /**
+     * Whether a paragraph in this context is composed over its table level: where the table style
+     * gives it text formatting, or, under [MS-DOCX]'s size exception, where the style formats text
+     * anywhere ({@link CellContext.styleFormatsText}). docx4j `composes` (900b6a212, 17.3.2).
+     */
+    private composes;
     private clearTableCaches;
     /** The table level's `w:pPr`: the style's own, then its conditional formats'; undefined if none. */
     private tableLevelPPr;
@@ -290,10 +369,11 @@ export declare class PropertyResolver {
     private composedPPr;
     private composedRPr;
     /**
-     * [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.
+     * [MS-DOCX]'s exception, for a paragraph in a table whose style formats text (for the size: the
+     * style need not state one, since docx4j 17.3.2) or states 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.
      */
     private paragraphStyleGivesWay;
     /** Word's built-in Normal Table, as a style: what it applies whatever the document's own definition says. */