@docx4j/core-ts 0.5.0 → 0.7.0

package/dist/model/color/ThemeColors.d.mts

@@ -0,0 +1,86 @@
+import type * as dml from '@docx4j/generated-objects-ts/modules/org_docx4j_dml';
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type * as chart from '@docx4j/generated-objects-ts/modules/org_docx4j_dml_chart';
+import { Part } from '../../parts/Part.mjs';
+import type { XmlPart } from '../../parts/XmlPart.mjs';
+import type { OpcPackage } from '../../packages/OpcPackage.mjs';
+import { type DefaultTheme } from '../fonts/defaultTheme.mjs';
+import { ResolvedColor } from './ResolvedColor.mjs';
+/**
+ * A theme's colour scheme and the colour map that leads to it: all a colour reference needs. Immutable; each
+ * `with...` returns a new one. Which theme and which map apply depends on the host: {@link ThemeColors.of} takes a
+ * package (docx or xlsx) or a part (a slide, layout, master or notes part; a part of a docx or xlsx), and
+ * {@link ThemeColors.forChart} a chart in any of them - drawn in its host's theme.
+ *
+ * The scheme's slots are `dk1`, `lt1`, `dk2`, `lt2`, `accent1` to `accent6`, `hlink` and `folHlink`; the map takes
+ * `bg1`, `tx1`, `bg2`, `tx2` (and, in principle, the accents and hyperlinks) to a slot. A slot holding a system
+ * colour is the machine's colour, not its `lastClr` (docx4j CR-034 section 11).
+ *
+ * docx4j's names, but: `of(Theme)` is {@link ThemeColors.ofTheme} here (synchronous), and `of(WordprocessingMLPackage)`,
+ * `of(SpreadsheetMLPackage)` and `of(Part)` are one asynchronous {@link ThemeColors.of}; `forChart(Chart)` is
+ * asynchronous; `getFormatScheme()` and `getPlaceholder()` are the properties `formatScheme` and `placeholder`.
+ */
+export declare class ThemeColors {
+    private readonly slots;
+    private readonly map;
+    /** The theme's format scheme, which style references index into; undefined where the theme has none. */
+    readonly formatScheme: dml.CTStyleMatrix | undefined;
+    /** `phClr`'s colour, where a style reference supplies one. */
+    readonly placeholder: ResolvedColor | undefined;
+    private constructor();
+    /**
+     * A theme with the default colour map (docx4j `of(Theme)`).
+     *
+     * @param theme undefined for the theme Office supplies where a package has none: the bundled theme `defaultTheme`
+     *   names, else {@link defaultThemeSetting}'s. Parsing it needs the objects package's context, which is built once
+     *   anything has been read; {@link ThemeColors.loadDefaultTheme} builds it.
+     */
+    static ofTheme(theme: dml.Theme | undefined, defaultTheme?: DefaultTheme): ThemeColors;
+    /** Parses a bundled theme ahead of a synchronous {@link ThemeColors.ofTheme}(undefined), building the context if need be. */
+    static loadDefaultTheme(defaultTheme?: DefaultTheme): Promise<dml.Theme>;
+    /**
+     * The theme colours of a package or a part:
+     * - a docx: the main document part's theme (or the default theme) and `w:clrSchemeMapping` from the settings,
+     *   which applies to WordprocessingML theme colours and DrawingML scheme colours alike (docx4j CR-034 section 11, P2);
+     * - an xlsx: the workbook's theme (or the default theme), with the default map for its drawings;
+     * - a slide: its master's theme, its master's `p:clrMap`, then its layout's `p:clrMapOvr`, then its own; a layout,
+     *   a master, a notes slide, a notes or handout master likewise;
+     * - a part of a docx or xlsx: its package's.
+     * Anything else, or a part that can't be read, gets the default theme with the default map.
+     */
+    static of(source: OpcPackage | Part): Promise<ThemeColors>;
+    private static themed;
+    private static ofPart;
+    /** This theme with a DrawingML colour map (`p:clrMap`, `c:clrMapOvr`); undefined leaves it. */
+    withMapping(m: dml.CTColorMapping | undefined | null): ThemeColors;
+    /** `a:overrideClrMapping` replaces the map; `a:masterClrMapping` (or nothing) keeps it. */
+    withOverride(o: dml.CTColorMappingOverride | undefined | null): ThemeColors;
+    /** This theme with WordprocessingML's `w:clrSchemeMapping` (whose names differ: dark1, t1, ...). */
+    withWordMapping(m: wml.CTColorSchemeMapping | undefined | null): ThemeColors;
+    /** This theme with another colour scheme and format scheme (a theme override part's). */
+    withScheme(clrScheme: dml.CTColorScheme | undefined | null, fmt?: dml.CTStyleMatrix | null): ThemeColors;
+    /**
+     * A chart's colours: this (its host's) theme, under the chart's theme override part if it has one, and the
+     * chart's `c:clrMapOvr` if it states one.
+     */
+    forChart(chartPart: XmlPart<chart.CTChartSpace>): Promise<ThemeColors>;
+    /** This theme with `phClr` standing for the given colour (a style reference's). */
+    withPlaceholder(color: ResolvedColor | undefined): ThemeColors;
+    /** A scheme slot's colour (dk1, lt1, ..., folHlink), not through the map. */
+    slot(slot: string): ResolvedColor | undefined;
+    /**
+     * A DrawingML `schemeClr` value's colour: bg1, tx1, bg2, tx2 (and the accents and hyperlinks) through the map,
+     * dk1 ... lt2 directly, `phClr` the placeholder.
+     */
+    schemeColor(val: string | undefined | null): ResolvedColor | undefined;
+    /**
+     * A WordprocessingML `w:themeColor` value's colour: text1, background1, text2, background2 through the map,
+     * dark1 ... followedHyperlink directly; undefined for "none".
+     */
+    wordThemeColor(themeColor: string | undefined | null): ResolvedColor | undefined;
+    /**
+     * A SpreadsheetML `theme` index's colour. Excel swaps the first two pairs: 0 is lt1, 1 dk1, 2 lt2, 3 dk2, then
+     * accent1 to accent6, hlink, folHlink (docx4j CR-034 section 11, P4).
+     */
+    sheetThemeColor(index: number): ResolvedColor | undefined;
+}

package/dist/model/color/ThemeColors.mjs

@@ -0,0 +1,304 @@
+import { getContext, getContextSync } from '@docx4j/generated-objects-ts';
+import { Part } from '../../parts/Part.mjs';
+import { Namespaces } from '../../parts/Namespaces.mjs';
+import { ThemePart, ThemeOverridePart } from '../../parts/dml/index.mjs';
+import { SlidePart, SlideLayoutPart, SlideMasterPart, NotesSlidePart, NotesMasterPart, HandoutMasterPart, } from '../../parts/pml/index.mjs';
+import { Docx4JException } from '../../opc/exceptions.mjs';
+import { themeOfSettings, defaultThemeSetting } from '../fonts/defaultTheme.mjs';
+import { DrawingMLColors } from './DrawingMLColors.mjs';
+/** The scheme's slots. */
+const SLOTS = ['dk1', 'lt1', 'dk2', 'lt2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
+/** What a colour map takes to a slot. */
+const MAPPED = ['bg1', 'tx1', 'bg2', 'tx2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
+/** WordprocessingML's names for the scheme's slots. */
+const WORD_NAMES = new Map([
+    ['dark1', 'dk1'], ['light1', 'lt1'], ['dark2', 'dk2'], ['light2', 'lt2'],
+    ['accent1', 'accent1'], ['accent2', 'accent2'], ['accent3', 'accent3'], ['accent4', 'accent4'], ['accent5', 'accent5'], ['accent6', 'accent6'],
+    ['hyperlink', 'hlink'], ['followedHyperlink', 'folHlink'],
+]);
+/** Excel's theme indexes: the first two pairs swapped (docx4j CR-034 section 11, P4). */
+const SHEET_ORDER = ['lt1', 'dk1', 'lt2', 'dk2', 'accent1', 'accent2', 'accent3', 'accent4', 'accent5', 'accent6', 'hlink', 'folHlink'];
+/** The default colour map: bg1 to lt1, tx1 to dk1, bg2 to lt2, tx2 to dk2, the rest to themselves. */
+function defaultMap() {
+    const m = new Map([['bg1', 'lt1'], ['tx1', 'dk1'], ['bg2', 'lt2'], ['tx2', 'dk2']]);
+    for (let i = 4; i < MAPPED.length; i++)
+        m.set(MAPPED[i], MAPPED[i]);
+    return m;
+}
+function scheme(cs) {
+    const m = new Map();
+    if (cs !== undefined && cs !== null) {
+        for (const slot of SLOTS) {
+            const c = cs[slot];
+            const r = c === undefined || c === null ? undefined : DrawingMLColors.resolve(c, undefined);
+            if (r !== undefined)
+                m.set(slot, r);
+        }
+    }
+    return m;
+}
+// ------------------------------------------------------------------ the bundled themes
+const bundled = new Map();
+function parseTheme(context, xml) {
+    const element = context.createUnmarshaller().unmarshalString(xml);
+    return element.value;
+}
+/** A bundled theme, parsed; the objects package's context must be built (it is once anything has been read). */
+function bundledThemeSync(theme) {
+    let t = bundled.get(theme.value);
+    if (t === undefined) {
+        let context;
+        try {
+            context = getContextSync();
+        }
+        catch (e) {
+            throw new Docx4JException(`The default theme ${theme.value} needs the objects context: await ThemeColors.loadDefaultTheme() first`, { cause: e });
+        }
+        t = parseTheme(context, theme.xml);
+        bundled.set(theme.value, t);
+    }
+    return t;
+}
+async function readQuietly(part) {
+    if (part === undefined)
+        return undefined;
+    try {
+        return await part.readContents();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The part a relationship of this type leads to, if it is one of this class. */
+function related(part, type, kind) {
+    const rp = part.relationshipsPart;
+    const rel = rp === null || rp === void 0 ? void 0 : rp.getRelationshipByType(type);
+    const target = rel === undefined ? undefined : rp.getPart(rel);
+    return target instanceof kind ? target : undefined;
+}
+const isWord = (pkg) => typeof (pkg === null || pkg === void 0 ? void 0 : pkg.getMainDocumentPart) === 'function';
+const isSpreadsheet = (pkg) => typeof (pkg === null || pkg === void 0 ? void 0 : pkg.getWorkbookPart) === 'function';
+/** The default theme a package names (`pkg.fonts.defaultTheme`), else the process-wide setting. */
+function defaultThemeOfPackage(pkg) {
+    return themeOfSettings(pkg === null || pkg === void 0 ? void 0 : pkg.fonts);
+}
+/**
+ * A theme's colour scheme and the colour map that leads to it: all a colour reference needs. Immutable; each
+ * `with...` returns a new one. Which theme and which map apply depends on the host: {@link ThemeColors.of} takes a
+ * package (docx or xlsx) or a part (a slide, layout, master or notes part; a part of a docx or xlsx), and
+ * {@link ThemeColors.forChart} a chart in any of them - drawn in its host's theme.
+ *
+ * The scheme's slots are `dk1`, `lt1`, `dk2`, `lt2`, `accent1` to `accent6`, `hlink` and `folHlink`; the map takes
+ * `bg1`, `tx1`, `bg2`, `tx2` (and, in principle, the accents and hyperlinks) to a slot. A slot holding a system
+ * colour is the machine's colour, not its `lastClr` (docx4j CR-034 section 11).
+ *
+ * docx4j's names, but: `of(Theme)` is {@link ThemeColors.ofTheme} here (synchronous), and `of(WordprocessingMLPackage)`,
+ * `of(SpreadsheetMLPackage)` and `of(Part)` are one asynchronous {@link ThemeColors.of}; `forChart(Chart)` is
+ * asynchronous; `getFormatScheme()` and `getPlaceholder()` are the properties `formatScheme` and `placeholder`.
+ */
+export class ThemeColors {
+    constructor(slots, map, 
+    /** The theme's format scheme, which style references index into; undefined where the theme has none. */
+    formatScheme, 
+    /** `phClr`'s colour, where a style reference supplies one. */
+    placeholder) {
+        this.slots = slots;
+        this.map = map;
+        this.formatScheme = formatScheme;
+        this.placeholder = placeholder;
+    }
+    // ------------------------------------------------------------------ making one
+    /**
+     * A theme with the default colour map (docx4j `of(Theme)`).
+     *
+     * @param theme undefined for the theme Office supplies where a package has none: the bundled theme `defaultTheme`
+     *   names, else {@link defaultThemeSetting}'s. Parsing it needs the objects package's context, which is built once
+     *   anything has been read; {@link ThemeColors.loadDefaultTheme} builds it.
+     */
+    static ofTheme(theme, defaultTheme) {
+        var _a;
+        theme !== null && theme !== void 0 ? theme : (theme = bundledThemeSync(defaultTheme !== null && defaultTheme !== void 0 ? defaultTheme : defaultThemeSetting()));
+        const elements = theme.themeElements;
+        return new ThemeColors(scheme(elements === null || elements === void 0 ? void 0 : elements.clrScheme), defaultMap(), (_a = elements === null || elements === void 0 ? void 0 : elements.fmtScheme) !== null && _a !== void 0 ? _a : undefined, undefined);
+    }
+    /** Parses a bundled theme ahead of a synchronous {@link ThemeColors.ofTheme}(undefined), building the context if need be. */
+    static async loadDefaultTheme(defaultTheme = defaultThemeSetting()) {
+        let t = bundled.get(defaultTheme.value);
+        if (t === undefined) {
+            t = parseTheme(await getContext(), defaultTheme.xml);
+            bundled.set(defaultTheme.value, t);
+        }
+        return t;
+    }
+    /**
+     * The theme colours of a package or a part:
+     * - a docx: the main document part's theme (or the default theme) and `w:clrSchemeMapping` from the settings,
+     *   which applies to WordprocessingML theme colours and DrawingML scheme colours alike (docx4j CR-034 section 11, P2);
+     * - an xlsx: the workbook's theme (or the default theme), with the default map for its drawings;
+     * - a slide: its master's theme, its master's `p:clrMap`, then its layout's `p:clrMapOvr`, then its own; a layout,
+     *   a master, a notes slide, a notes or handout master likewise;
+     * - a part of a docx or xlsx: its package's.
+     * Anything else, or a part that can't be read, gets the default theme with the default map.
+     */
+    static async of(source) {
+        if (source instanceof Part)
+            return ThemeColors.ofPart(source);
+        const fallback = defaultThemeOfPackage(source);
+        if (isWord(source)) {
+            const main = source.getMainDocumentPart();
+            const tc = await ThemeColors.themed(await readQuietly(main.themePart), fallback);
+            const settings = await readQuietly(main.documentSettingsPart);
+            const m = settings === null || settings === void 0 ? void 0 : settings.clrSchemeMapping;
+            return m === undefined || m === null ? tc : tc.withWordMapping(m);
+        }
+        if (isSpreadsheet(source)) {
+            return ThemeColors.themed(await readQuietly(source.getWorkbookPart().themePart), fallback);
+        }
+        return ThemeColors.themed(undefined, fallback);
+    }
+    static async themed(theme, fallback) {
+        if (theme === undefined)
+            await ThemeColors.loadDefaultTheme(fallback);
+        return ThemeColors.ofTheme(theme, fallback);
+    }
+    static async ofPart(part) {
+        const fallback = defaultThemeOfPackage(part.package);
+        try {
+            if (part instanceof SlidePart) {
+                const layout = part.slideLayoutPart;
+                const tc = layout === undefined ? await ThemeColors.themed(undefined, fallback) : await ThemeColors.ofPart(layout);
+                return tc.withOverride((await part.readContents()).clrMapOvr);
+            }
+            if (part instanceof SlideLayoutPart) {
+                const master = part.slideMasterPart;
+                const tc = master === undefined ? await ThemeColors.themed(undefined, fallback) : await ThemeColors.ofPart(master);
+                return tc.withOverride((await part.readContents()).clrMapOvr);
+            }
+            if (part instanceof SlideMasterPart || part instanceof NotesMasterPart || part instanceof HandoutMasterPart) {
+                const theme = await readQuietly(related(part, Namespaces.THEME, ThemePart));
+                return (await ThemeColors.themed(theme, fallback)).withMapping((await part.readContents()).clrMap);
+            }
+            if (part instanceof NotesSlidePart) {
+                const master = related(part, Namespaces.PRESENTATIONML_NOTES_MASTER, NotesMasterPart);
+                const tc = master === undefined ? await ThemeColors.themed(undefined, fallback) : await ThemeColors.ofPart(master);
+                return tc.withOverride((await part.readContents()).clrMapOvr);
+            }
+        }
+        catch {
+            // docx4j logs "Couldn't read the colour map of ..." and takes the default theme
+            return ThemeColors.themed(undefined, fallback);
+        }
+        const pkg = part.package;
+        if (isWord(pkg) || isSpreadsheet(pkg))
+            return ThemeColors.of(pkg);
+        return ThemeColors.themed(undefined, fallback);
+    }
+    // ------------------------------------------------------------------ deriving one
+    /** This theme with a DrawingML colour map (`p:clrMap`, `c:clrMapOvr`); undefined leaves it. */
+    withMapping(m) {
+        if (m === undefined || m === null)
+            return this;
+        const mm = new Map(this.map);
+        for (const key of MAPPED)
+            put(mm, key, m[key]);
+        return new ThemeColors(this.slots, mm, this.formatScheme, this.placeholder);
+    }
+    /** `a:overrideClrMapping` replaces the map; `a:masterClrMapping` (or nothing) keeps it. */
+    withOverride(o) {
+        return o === undefined || o === null || o.overrideClrMapping === undefined || o.overrideClrMapping === null
+            ? this : this.withMapping(o.overrideClrMapping);
+    }
+    /** This theme with WordprocessingML's `w:clrSchemeMapping` (whose names differ: dark1, t1, ...). */
+    withWordMapping(m) {
+        if (m === undefined || m === null)
+            return this;
+        const mm = new Map(this.map);
+        put(mm, 'bg1', wordSlot(m.bg1));
+        put(mm, 'tx1', wordSlot(m.t1));
+        put(mm, 'bg2', wordSlot(m.bg2));
+        put(mm, 'tx2', wordSlot(m.t2));
+        put(mm, 'accent1', wordSlot(m.accent1));
+        put(mm, 'accent2', wordSlot(m.accent2));
+        put(mm, 'accent3', wordSlot(m.accent3));
+        put(mm, 'accent4', wordSlot(m.accent4));
+        put(mm, 'accent5', wordSlot(m.accent5));
+        put(mm, 'accent6', wordSlot(m.accent6));
+        put(mm, 'hlink', wordSlot(m.hyperlink));
+        put(mm, 'folHlink', wordSlot(m.followedHyperlink));
+        return new ThemeColors(this.slots, mm, this.formatScheme, this.placeholder);
+    }
+    /** This theme with another colour scheme and format scheme (a theme override part's). */
+    withScheme(clrScheme, fmt) {
+        return new ThemeColors(clrScheme === undefined || clrScheme === null ? this.slots : scheme(clrScheme), this.map, fmt === undefined || fmt === null ? this.formatScheme : fmt, this.placeholder);
+    }
+    /**
+     * A chart's colours: this (its host's) theme, under the chart's theme override part if it has one, and the
+     * chart's `c:clrMapOvr` if it states one.
+     */
+    async forChart(chartPart) {
+        let tc = this;
+        try {
+            const override = await readQuietly(related(chartPart, Namespaces.THEME_OVERRIDE, ThemeOverridePart));
+            if (override !== undefined)
+                tc = tc.withScheme(override.clrScheme, override.fmtScheme);
+            tc = tc.withMapping((await chartPart.readContents()).clrMapOvr);
+        }
+        catch {
+            // docx4j logs "Couldn't read ...'s theme override or colour map" and keeps what it has
+        }
+        return tc;
+    }
+    /** This theme with `phClr` standing for the given colour (a style reference's). */
+    withPlaceholder(color) {
+        return new ThemeColors(this.slots, this.map, this.formatScheme, color);
+    }
+    // ------------------------------------------------------------------ reading it
+    /** A scheme slot's colour (dk1, lt1, ..., folHlink), not through the map. */
+    slot(slot) {
+        return this.slots.get(slot);
+    }
+    /**
+     * A DrawingML `schemeClr` value's colour: bg1, tx1, bg2, tx2 (and the accents and hyperlinks) through the map,
+     * dk1 ... lt2 directly, `phClr` the placeholder.
+     */
+    schemeColor(val) {
+        if (val === undefined || val === null)
+            return undefined;
+        if (val === 'phClr')
+            return this.placeholder;
+        const slot = this.map.get(val);
+        return this.slots.get(slot !== null && slot !== void 0 ? slot : val);
+    }
+    /**
+     * A WordprocessingML `w:themeColor` value's colour: text1, background1, text2, background2 through the map,
+     * dark1 ... followedHyperlink directly; undefined for "none".
+     */
+    wordThemeColor(themeColor) {
+        if (themeColor === undefined || themeColor === null)
+            return undefined;
+        switch (themeColor) {
+            case 'text1': return this.schemeColor('tx1');
+            case 'background1': return this.schemeColor('bg1');
+            case 'text2': return this.schemeColor('tx2');
+            case 'background2': return this.schemeColor('bg2');
+            default: {
+                const slot = WORD_NAMES.get(themeColor);
+                return slot === undefined ? undefined : this.slots.get(slot);
+            }
+        }
+    }
+    /**
+     * A SpreadsheetML `theme` index's colour. Excel swaps the first two pairs: 0 is lt1, 1 dk1, 2 lt2, 3 dk2, then
+     * accent1 to accent6, hlink, folHlink (docx4j CR-034 section 11, P4).
+     */
+    sheetThemeColor(index) {
+        return index < 0 || index >= SHEET_ORDER.length ? undefined : this.slots.get(SHEET_ORDER[Math.trunc(index)]);
+    }
+}
+function wordSlot(i) {
+    return i === undefined || i === null ? undefined : WORD_NAMES.get(i);
+}
+function put(m, key, slot) {
+    if (slot !== undefined && slot !== null)
+        m.set(key, slot);
+}

package/dist/model/color/WordColors.d.mts

@@ -0,0 +1,71 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { ResolvedColor } from './ResolvedColor.mjs';
+import type { ThemeColors } from './ThemeColors.mjs';
+/**
+ * WordprocessingML colours (`w:color`, `w:shd`, the borders, `w:u`) resolved as Word draws them (docx4j CR-034
+ * section 11, P1).
+ *
+ * - A theme reference (`w:themeColor`, `w:themeFill`) wins over the value written beside it (`w:val`, `w:color`,
+ *   `w:fill`), which is a cache Word keeps: Word draws the theme colour even where the value disagrees (an older
+ *   theme's, or anything else).
+ * - `w:themeTint` and `w:themeShade` change the HSL luminance: tint t, L' = L·t + (1 − t); shade t, L' = L·t, t
+ *   being the byte over 255 (MS-OI29500 2.1.72). Where both are present Word applies the tint (the same note).
+ * - Word's own rounding of that arithmetic is not reproduced exactly (within one unit per channel in all 7,700 tints
+ *   and shades of four corpora), so where the written value is within one unit of the computed one - a current
+ *   cache - Word's value is returned: exact for every attribute Word itself wrote against the document's theme.
+ * - A value is read as Word 365 reads it ({@link WordColors.normalise}, docx4j CR-060 and core-ts CR-015): trimmed,
+ *   hex in either case with an optional `#`, or one of the 140 classic HTML colour names. One Word rejects is
+ *   automatic. A fill, a pattern colour and a border's colour are read the same way, as Word reads them (round 5: a
+ *   name there is drawn): docx4j's `WordColors` since `a9e0303ff` (until then it normalised in `of(Color)` and `of(U)`
+ *   only; CR-015 section 11.4).
+ *
+ * docx4j's overloads `of(Color)`, `of(CTBorder)` and `of(U)` are {@link WordColors.of}, {@link WordColors.ofBorder}
+ * and {@link WordColors.ofUnderline} here, since the three objects can't be told apart by shape; its `null` (for
+ * automatic) is `undefined`.
+ */
+export declare const WordColors: {
+    /**
+     * The colour Word draws for a WordprocessingML colour's attributes.
+     *
+     * @param val the written value: RRGGBB, "auto", or undefined
+     * @param themeColor the theme reference, or undefined (or "none")
+     * @param themeTint a byte in hex ("99"), or undefined
+     * @param themeShade a byte in hex ("BF"), or undefined
+     * @returns undefined for automatic (no theme reference and val "auto" or absent): the caller's default
+     */
+    resolve(val: string | undefined | null, themeColor: string | undefined | null, themeTint: string | undefined | null, themeShade: string | undefined | null, theme: ThemeColors | undefined): ResolvedColor | undefined;
+    /**
+     * A colour value (`w:color/@w:val`, `w:u/@w:color`, `w:shd/@w:fill`, a border's `w:color`) as Word 365 reads it
+     * (docx4j CR-060 section 1, rule 3, and sections 12 and 13): surrounding whitespace trimmed, six hex digits in
+     * either case with an optional leading `#`; else a classic HTML colour name, in any case. The rule is the objects
+     * package's `wordColor` (its CR-013, held to docx4j's `WordColorValues`).
+     *
+     * @returns six upper-case hex digits; undefined for `auto` and for a value Word rejects, which Word reads as
+     * automatic in a fill or a border colour, and as absent in a text or underline colour ({@link WordColors.stated})
+     */
+    normalise(val: string | undefined | null): string | undefined;
+    /**
+     * Whether a `w:color/@w:val` or `w:u/@w:color` value states a colour, as Word reads it (docx4j CR-060 sections 12
+     * and 13): one {@link WordColors.normalise} accepts, or exactly `auto` (automatic, which overrides a style's
+     * colour). Word reads any other value (`F00`, `bogus`, `""`, `Auto`, `" auto"`) as absent: a style's colour beneath
+     * still shows. (In a fill or a border colour it reads such a value as automatic instead.)
+     */
+    stated(val: string | undefined | null): boolean;
+    /** A run's colour (`w:color`); undefined for automatic. */
+    of(c: wml.Color | undefined | null, theme: ThemeColors | undefined): ResolvedColor | undefined;
+    /** A shading's fill (`w:fill`, `w:themeFill`); undefined for automatic. */
+    fill(shd: wml.CTShd | undefined | null, theme: ThemeColors | undefined): ResolvedColor | undefined;
+    /** A shading's pattern colour (`w:color`, `w:themeColor`); undefined for automatic. */
+    pattern(shd: wml.CTShd | undefined | null, theme: ThemeColors | undefined): ResolvedColor | undefined;
+    /** A border's colour; undefined for automatic. docx4j `of(CTBorder)`. */
+    ofBorder(border: wml.CTBorder | undefined | null, theme: ThemeColors | undefined): ResolvedColor | undefined;
+    /** An underline's colour; undefined for automatic (the text's colour). docx4j `of(U)`. */
+    ofUnderline(u: wml.U | undefined | null, theme: ThemeColors | undefined): ResolvedColor | undefined;
+    /**
+     * Word's themeTint (tint true) or themeShade on a colour: float HSL, the channels truncated. That is what Word 365
+     * draws (docx4j CR-034 section 11: the three P1 cases with no usable written value, all exact); the values older
+     * versions of Word wrote are within one unit of it (all 119 distinct ones in four corpora, 77 exact).
+     * Package-private in docx4j; public here for the corpus vectors' test.
+     */
+    luminance(c: ResolvedColor, t: number, tint: boolean): ResolvedColor;
+};

package/dist/model/color/WordColors.mjs

@@ -0,0 +1,121 @@
+import { wordColor } from '@docx4j/generated-objects-ts/helpers/wml';
+import * as ColorMath from './ColorMath.mjs';
+import { ResolvedColor } from './ResolvedColor.mjs';
+function hexByte(s) {
+    if (s === undefined || s === null || s.length === 0)
+        return undefined;
+    // Java's Integer.parseInt(s, 16): an optional sign, then hex digits
+    if (!/^[+-]?[0-9A-Fa-f]+$/.test(s))
+        return undefined;
+    const v = Number.parseInt(s, 16);
+    return v >= 0 && v <= 255 ? v : undefined;
+}
+function truncate(v) {
+    return Math.floor(ColorMath.clamp01(v) * 255 + 1e-9);
+}
+/**
+ * WordprocessingML colours (`w:color`, `w:shd`, the borders, `w:u`) resolved as Word draws them (docx4j CR-034
+ * section 11, P1).
+ *
+ * - A theme reference (`w:themeColor`, `w:themeFill`) wins over the value written beside it (`w:val`, `w:color`,
+ *   `w:fill`), which is a cache Word keeps: Word draws the theme colour even where the value disagrees (an older
+ *   theme's, or anything else).
+ * - `w:themeTint` and `w:themeShade` change the HSL luminance: tint t, L' = L·t + (1 − t); shade t, L' = L·t, t
+ *   being the byte over 255 (MS-OI29500 2.1.72). Where both are present Word applies the tint (the same note).
+ * - Word's own rounding of that arithmetic is not reproduced exactly (within one unit per channel in all 7,700 tints
+ *   and shades of four corpora), so where the written value is within one unit of the computed one - a current
+ *   cache - Word's value is returned: exact for every attribute Word itself wrote against the document's theme.
+ * - A value is read as Word 365 reads it ({@link WordColors.normalise}, docx4j CR-060 and core-ts CR-015): trimmed,
+ *   hex in either case with an optional `#`, or one of the 140 classic HTML colour names. One Word rejects is
+ *   automatic. A fill, a pattern colour and a border's colour are read the same way, as Word reads them (round 5: a
+ *   name there is drawn): docx4j's `WordColors` since `a9e0303ff` (until then it normalised in `of(Color)` and `of(U)`
+ *   only; CR-015 section 11.4).
+ *
+ * docx4j's overloads `of(Color)`, `of(CTBorder)` and `of(U)` are {@link WordColors.of}, {@link WordColors.ofBorder}
+ * and {@link WordColors.ofUnderline} here, since the three objects can't be told apart by shape; its `null` (for
+ * automatic) is `undefined`.
+ */
+export const WordColors = {
+    /**
+     * The colour Word draws for a WordprocessingML colour's attributes.
+     *
+     * @param val the written value: RRGGBB, "auto", or undefined
+     * @param themeColor the theme reference, or undefined (or "none")
+     * @param themeTint a byte in hex ("99"), or undefined
+     * @param themeShade a byte in hex ("BF"), or undefined
+     * @returns undefined for automatic (no theme reference and val "auto" or absent): the caller's default
+     */
+    resolve(val, themeColor, themeTint, themeShade, theme) {
+        const written = ResolvedColor.ofHex(val);
+        if (themeColor === undefined || themeColor === null || themeColor === 'none' || theme === undefined)
+            return written;
+        // Word's value where it is a current cache: Word's own rounding, which the computation below matches for Word 365
+        // but not for every older version that wrote the file
+        const base = theme.wordThemeColor(themeColor);
+        if (base === undefined)
+            return written;
+        const tint = hexByte(themeTint), shade = hexByte(themeShade);
+        const computed = tint !== undefined ? WordColors.luminance(base, tint / 255.0, true)
+            : shade !== undefined ? WordColors.luminance(base, shade / 255.0, false) : base;
+        return written !== undefined && written.within(computed, 1) ? written : computed;
+    },
+    /**
+     * A colour value (`w:color/@w:val`, `w:u/@w:color`, `w:shd/@w:fill`, a border's `w:color`) as Word 365 reads it
+     * (docx4j CR-060 section 1, rule 3, and sections 12 and 13): surrounding whitespace trimmed, six hex digits in
+     * either case with an optional leading `#`; else a classic HTML colour name, in any case. The rule is the objects
+     * package's `wordColor` (its CR-013, held to docx4j's `WordColorValues`).
+     *
+     * @returns six upper-case hex digits; undefined for `auto` and for a value Word rejects, which Word reads as
+     * automatic in a fill or a border colour, and as absent in a text or underline colour ({@link WordColors.stated})
+     */
+    normalise(val) {
+        const w = typeof val === 'string' ? wordColor(val) : undefined;
+        return w === undefined || w === 'auto' ? undefined : w.substring(1);
+    },
+    /**
+     * Whether a `w:color/@w:val` or `w:u/@w:color` value states a colour, as Word reads it (docx4j CR-060 sections 12
+     * and 13): one {@link WordColors.normalise} accepts, or exactly `auto` (automatic, which overrides a style's
+     * colour). Word reads any other value (`F00`, `bogus`, `""`, `Auto`, `" auto"`) as absent: a style's colour beneath
+     * still shows. (In a fill or a border colour it reads such a value as automatic instead.)
+     */
+    stated(val) {
+        return typeof val === 'string' && wordColor(val) !== undefined;
+    },
+    /** A run's colour (`w:color`); undefined for automatic. */
+    of(c, theme) {
+        return c === undefined || c === null ? undefined
+            : WordColors.resolve(WordColors.normalise(c.val), c.themeColor, c.themeTint, c.themeShade, theme);
+    },
+    /** A shading's fill (`w:fill`, `w:themeFill`); undefined for automatic. */
+    fill(shd, theme) {
+        return shd === undefined || shd === null ? undefined
+            : WordColors.resolve(WordColors.normalise(shd.fill), shd.themeFill, shd.themeFillTint, shd.themeFillShade, theme);
+    },
+    /** A shading's pattern colour (`w:color`, `w:themeColor`); undefined for automatic. */
+    pattern(shd, theme) {
+        return shd === undefined || shd === null ? undefined
+            : WordColors.resolve(WordColors.normalise(shd.color), shd.themeColor, shd.themeTint, shd.themeShade, theme);
+    },
+    /** A border's colour; undefined for automatic. docx4j `of(CTBorder)`. */
+    ofBorder(border, theme) {
+        return border === undefined || border === null ? undefined
+            : WordColors.resolve(WordColors.normalise(border.color), border.themeColor, border.themeTint, border.themeShade, theme);
+    },
+    /** An underline's colour; undefined for automatic (the text's colour). docx4j `of(U)`. */
+    ofUnderline(u, theme) {
+        return u === undefined || u === null ? undefined
+            : WordColors.resolve(WordColors.normalise(u.color), u.themeColor, u.themeTint, u.themeShade, theme);
+    },
+    /**
+     * Word's themeTint (tint true) or themeShade on a colour: float HSL, the channels truncated. That is what Word 365
+     * draws (docx4j CR-034 section 11: the three P1 cases with no usable written value, all exact); the values older
+     * versions of Word wrote are within one unit of it (all 119 distinct ones in four corpora, 77 exact).
+     * Package-private in docx4j; public here for the corpus vectors' test.
+     */
+    luminance(c, t, tint) {
+        const hsl = ColorMath.rgbToHsl(c.red / 255.0, c.green / 255.0, c.blue / 255.0);
+        const l = tint ? hsl[2] * t + (1 - t) : hsl[2] * t;
+        const rgb = ColorMath.hslToRgb(hsl[0], hsl[1], ColorMath.clamp01(l));
+        return ResolvedColor.rgb(truncate(rgb[0]), truncate(rgb[1]), truncate(rgb[2]));
+    },
+};

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

@@ -0,0 +1,6 @@
+export { ResolvedColor } from './ResolvedColor.mjs';
+export { ThemeColors } from './ThemeColors.mjs';
+export { WordColors } from './WordColors.mjs';
+export { DrawingMLColors } from './DrawingMLColors.mjs';
+export { SpreadsheetColors } from './SpreadsheetColors.mjs';
+export { StyleFill, type StyleFillKind } from './StyleFill.mjs';

package/dist/model/color/index.mjs

@@ -0,0 +1,30 @@
+// CR-008 phase 2: colours as Office draws them (docx4j `org.docx4j.model.color`, its CR-034): any colour reference in
+// a docx, pptx or xlsx resolved to the RGB value (and alpha) Word, PowerPoint or Excel draws for it.
+//
+// A reference resolves against a {@link ThemeColors}: a theme's colour scheme and the colour map that leads to it,
+// made for the reference's host by `await ThemeColors.of(pkg or part)` (a docx: the main document part's theme and
+// the settings' `w:clrSchemeMapping`, which applies to WordprocessingML theme colours and DrawingML scheme colours
+// alike, and is `PropertyResolver.getThemeColors()`; a slide, layout, master, notes slide, notes or handout master:
+// its master's theme with the master's `p:clrMap`, then the layout's and the slide's `p:clrMapOvr`; an xlsx: the
+// workbook's theme; a chart, `forChart` on its host's). A package with no theme part gets the theme Office supplies,
+// the bundled one `pkg.fonts.defaultTheme` names (Office 2023's by default).
+//
+// - {@link WordColors}: `w:color`, `w:shd`, the borders and `w:u`. Word draws the theme reference and keeps the
+//   value beside it as a cache, which can be stale; `w:themeTint` and `w:themeShade` change the HSL luminance, the
+//   tint winning where both are given.
+// - {@link DrawingMLColors}: the six DrawingML colour kinds and their transforms, applied in document order; a system
+//   colour is the machine's, not its `lastClr`. A shape's style references (`a:fillRef`, `a:lnRef`, `a:fontRef`)
+//   resolve through the theme's format scheme; an entry that is not a solid fill comes back as a {@link StyleFill} of
+//   its kind, not guessed at.
+// - {@link SpreadsheetColors}: `rgb`, `theme` (whose first four indexes Excel reads as lt1, dk1, lt2, dk2),
+//   `indexed` (the legacy palette or the workbook's `x:indexedColors`) and `tint`, in Windows' integer HLS.
+//
+// Each returns a {@link ResolvedColor}, or undefined for "automatic", which is the caller's default. Every rule was
+// read from Office's own renderings (docx4j CR-034 section 11); the probes, Office's readings and the corpus tint and
+// shade triples are this package's vectors too (`test/theme-colors/`, CR-008 section 7).
+export { ResolvedColor } from './ResolvedColor.mjs';
+export { ThemeColors } from './ThemeColors.mjs';
+export { WordColors } from './WordColors.mjs';
+export { DrawingMLColors } from './DrawingMLColors.mjs';
+export { SpreadsheetColors } from './SpreadsheetColors.mjs';
+export { StyleFill } from './StyleFill.mjs';