@docx4j/core-ts 0.4.0 → 0.6.0

package/dist/model/color/DrawingMLColors.mjs

@@ -0,0 +1,374 @@
+import * as ColorMath from './ColorMath.mjs';
+import { PRESET, SYSTEM } from './ColorTables.mjs';
+import { ResolvedColor } from './ResolvedColor.mjs';
+import { StyleFill } from './StyleFill.mjs';
+const KIND_NAMES = {
+    srgbClr: 'org_docx4j_dml.CTSRgbColor', schemeClr: 'org_docx4j_dml.CTSchemeColor', scrgbClr: 'org_docx4j_dml.CTScRgbColor',
+    hslClr: 'org_docx4j_dml.CTHslColor', sysClr: 'org_docx4j_dml.CTSystemColor', prstClr: 'org_docx4j_dml.CTPresetColor',
+};
+const HOLDERS = new Set(['org_docx4j_dml.CTColor', 'org_docx4j_dml.CTSolidColorFillProperties',
+    'org_docx4j_dml.CTStyleMatrixReference', 'org_docx4j_dml.CTFontReference']);
+const FILL_NAMES = {
+    noFill: 'org_docx4j_dml.CTNoFillProperties', solidFill: 'org_docx4j_dml.CTSolidColorFillProperties',
+    gradFill: 'org_docx4j_dml.CTGradientFillProperties', pattFill: 'org_docx4j_dml.CTPatternFillProperties',
+    blipFill: 'org_docx4j_dml.CTBlipFillProperties', grpFill: 'org_docx4j_dml.CTGroupFillProperties',
+};
+const typeNameOf = (o) => o === null || o === void 0 ? void 0 : o.TYPE_NAME;
+/** A JAXBElement's counterpart, `{ name, value }`: the value, with the type its element name gives where it has none. */
+function unwrap(o, names) {
+    var _a;
+    const named = o;
+    if (named !== undefined && named !== null && typeof named === 'object' && named.name !== undefined && 'value' in named) {
+        const local = typeof named.name === 'string' ? named.name : named.name.localPart;
+        return { value: named.value, type: (_a = typeNameOf(named.value)) !== null && _a !== void 0 ? _a : names[local] };
+    }
+    return { value: o, type: typeNameOf(o) };
+}
+const holds = (o) => ['srgbClr', 'schemeClr', 'scrgbClr', 'hslClr', 'sysClr', 'prstClr'].some((k) => o[k] !== undefined && o[k] !== null);
+/** The colour element inside a holder, or the element itself, with its kind's type name. */
+function kind(o) {
+    const { value, type } = unwrap(o, KIND_NAMES);
+    if (value === undefined || value === null || typeof value !== 'object')
+        return undefined;
+    if ((type === undefined || HOLDERS.has(type)) && holds(value)) {
+        const h = value;
+        for (const [key, name] of [['srgbClr', KIND_NAMES.srgbClr], ['schemeClr', KIND_NAMES.schemeClr], ['scrgbClr', KIND_NAMES.scrgbClr],
+            ['hslClr', KIND_NAMES.hslClr], ['sysClr', KIND_NAMES.sysClr], ['prstClr', KIND_NAMES.prstClr]]) {
+            const c = h[key];
+            if (c !== undefined && c !== null)
+                return { value: c, type: name };
+        }
+    }
+    if (type !== undefined && Object.values(KIND_NAMES).includes(type))
+        return { value: value, type };
+    return undefined;
+}
+/** hexBinary as the objects model has it at run time (byte numbers), or as its declarations say (hex digits). */
+export function bytesOf(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v === 'string') {
+        if (!/^([0-9A-Fa-f]{2})*$/.test(v))
+            return undefined;
+        const out = [];
+        for (let i = 0; i < v.length; i += 2)
+            out.push(Number.parseInt(v.substring(i, i + 2), 16));
+        return out;
+    }
+    if (Array.isArray(v) || ArrayBuffer.isView(v))
+        return Array.from(v, (b) => b & 0xFF);
+    return undefined;
+}
+function base(c, type, theme) {
+    switch (type) {
+        case KIND_NAMES.srgbClr: {
+            const val = c.val;
+            if (typeof val === 'string')
+                return ResolvedColor.ofHex(val);
+            const b = bytesOf(val);
+            return b !== undefined && b.length === 3 ? ResolvedColor.rgb(b[0], b[1], b[2]) : undefined;
+        }
+        case KIND_NAMES.schemeClr: {
+            const s = c;
+            // docx4j logs at debug "Couldn't resolve schemeClr ..."
+            return theme === undefined || s.val === undefined || s.val === null ? undefined : theme.schemeColor(s.val);
+        }
+        case KIND_NAMES.scrgbClr: {
+            const s = c;
+            return ResolvedColor.rgb(ColorMath.channel(ColorMath.toSrgb(s.r / 100000.0)), ColorMath.channel(ColorMath.toSrgb(s.g / 100000.0)), ColorMath.channel(ColorMath.toSrgb(s.b / 100000.0)));
+        }
+        case KIND_NAMES.hslClr: {
+            const h = c;
+            const rgb = ColorMath.hslToRgb(h.hue / 21600000.0, h.sat / 100000.0, h.lum / 100000.0);
+            return ResolvedColor.rgb(ColorMath.channel(rgb[0]), ColorMath.channel(rgb[1]), ColorMath.channel(rgb[2]));
+        }
+        case KIND_NAMES.sysClr: {
+            const s = c;
+            // Office draws the machine's colour for the name and ignores lastClr (docx4j CR-034 section 11)
+            const hex = s.val === undefined || s.val === null ? undefined : SYSTEM.get(s.val);
+            if (hex !== undefined)
+                return ResolvedColor.ofHex(hex);
+            const last = bytesOf(s.lastClr);
+            return last !== undefined && last.length === 3 ? ResolvedColor.rgb(last[0], last[1], last[2]) : undefined;
+        }
+        case KIND_NAMES.prstClr: {
+            const p = c;
+            return p.val === undefined || p.val === null ? undefined : ResolvedColor.ofHex(PRESET.get(p.val));
+        }
+        default: return undefined;
+    }
+}
+/** The transforms' value, in thousandths of a percent or 60000ths of a degree; 0 for those without one. */
+function value(t) {
+    const v = t === null || t === void 0 ? void 0 : t.val;
+    return typeof v === 'number' ? v : 0;
+}
+/** A colour with transforms applied in document order. */
+function transform(baseColor, transforms) {
+    if (transforms === undefined || transforms === null || transforms.length === 0)
+        return baseColor;
+    let r = baseColor.red / 255.0, g = baseColor.green / 255.0, b = baseColor.blue / 255.0;
+    let alpha = baseColor.alpha / 100000.0;
+    let lumLast = false; // the last change to the colour a luminance transform: it rounds half down
+    for (const t of transforms) {
+        const name = typeof t.name === 'string' ? t.name : t.name.localPart;
+        const v = value(t.value) / 100000.0;
+        if (!name.startsWith('alpha'))
+            lumLast = name.startsWith('lum');
+        switch (name) {
+            case 'tint':
+                r = ColorMath.toSrgb(1 - (1 - ColorMath.toLinear(r)) * v);
+                g = ColorMath.toSrgb(1 - (1 - ColorMath.toLinear(g)) * v);
+                b = ColorMath.toSrgb(1 - (1 - ColorMath.toLinear(b)) * v);
+                break;
+            case 'shade':
+                r = ColorMath.toSrgb(ColorMath.toLinear(r) * v);
+                g = ColorMath.toSrgb(ColorMath.toLinear(g) * v);
+                b = ColorMath.toSrgb(ColorMath.toLinear(b) * v);
+                break;
+            case 'inv':
+                r = ColorMath.toSrgb(1 - ColorMath.toLinear(r));
+                g = ColorMath.toSrgb(1 - ColorMath.toLinear(g));
+                b = ColorMath.toSrgb(1 - ColorMath.toLinear(b));
+                break;
+            case 'gray': {
+                const y = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+                r = g = b = ColorMath.clamp01(y);
+                break;
+            }
+            case 'gamma':
+                r = ColorMath.toSrgb(r);
+                g = ColorMath.toSrgb(g);
+                b = ColorMath.toSrgb(b);
+                break;
+            case 'invGamma':
+                r = ColorMath.toLinear(r);
+                g = ColorMath.toLinear(g);
+                b = ColorMath.toLinear(b);
+                break;
+            case 'red':
+            case 'redOff':
+            case 'redMod':
+                r = channel(name, r, v);
+                break;
+            case 'green':
+            case 'greenOff':
+            case 'greenMod':
+                g = channel(name, g, v);
+                break;
+            case 'blue':
+            case 'blueOff':
+            case 'blueMod':
+                b = channel(name, b, v);
+                break;
+            case 'alpha':
+                alpha = v;
+                break;
+            case 'alphaOff':
+                alpha += v;
+                break;
+            case 'alphaMod':
+                alpha *= v;
+                break;
+            case 'comp':
+            case 'hue':
+            case 'hueOff':
+            case 'hueMod':
+            case 'sat':
+            case 'satOff':
+            case 'satMod':
+            case 'lum':
+            case 'lumOff':
+            case 'lumMod': {
+                let [h, s, l] = ColorMath.rgbToHsl(r, g, b);
+                const raw = value(t.value);
+                switch (name) {
+                    case 'comp':
+                        h += 0.5;
+                        break;
+                    case 'hue':
+                        h = raw / 21600000.0;
+                        break;
+                    case 'hueOff':
+                        h += raw / 21600000.0;
+                        break;
+                    case 'hueMod':
+                        h *= v;
+                        break;
+                    case 'sat':
+                        s = v;
+                        break;
+                    case 'satOff':
+                        s += v;
+                        break;
+                    case 'satMod':
+                        s *= v;
+                        break;
+                    case 'lum':
+                        l = v;
+                        break;
+                    case 'lumOff':
+                        l += v;
+                        break;
+                    // l x val / 100000 in this order, not l *= v: with hslToRgbFoley and channelHalfDown, which way an exact
+                    // half rounds follows this form's floating-point error, as Office's does (docx4j CR-034 section 11, follow-up)
+                    case 'lumMod':
+                        l = l * raw / 100000.0;
+                        break;
+                    default: break;
+                }
+                h = h % 1;
+                if (h < 0)
+                    h += 1;
+                const rgb = lumLast ? ColorMath.hslToRgbFoley(h, s, ColorMath.clamp01(l)) : ColorMath.hslToRgb(h, s, ColorMath.clamp01(l));
+                r = rgb[0];
+                g = rgb[1];
+                b = rgb[2];
+                break;
+            }
+            default:
+                // docx4j logs at debug "Ignoring an unknown colour transform ..."
+                break;
+        }
+    }
+    if (lumLast) {
+        return ResolvedColor.rgb(ColorMath.channelHalfDown(r), ColorMath.channelHalfDown(g), ColorMath.channelHalfDown(b))
+            .withAlpha(Math.round(ColorMath.clamp01(alpha) * 100000));
+    }
+    return ResolvedColor.rgb(ColorMath.channel(r), ColorMath.channel(g), ColorMath.channel(b))
+        .withAlpha(Math.round(ColorMath.clamp01(alpha) * 100000));
+}
+/** red, redOff, redMod (and green, blue): the channel in linear RGB */
+function channel(name, c, v) {
+    let l = ColorMath.toLinear(c);
+    if (name.endsWith('Off'))
+        l += v;
+    else if (name.endsWith('Mod'))
+        l *= v;
+    else
+        l = v;
+    return ColorMath.toSrgb(l);
+}
+/** The fill's type name: its own, its element name's (`{ name, value }`), or a solid fill's by its colour. */
+function fillOf(o) {
+    const { value, type } = unwrap(o, FILL_NAMES);
+    if (value === undefined || value === null || typeof value !== 'object')
+        return undefined;
+    return { value, type: type !== null && type !== void 0 ? type : (holds(value) ? FILL_NAMES.solidFill : undefined) };
+}
+/**
+ * DrawingML colours (ISO/IEC 29500-1 section 20.1.2.3) resolved as Office draws them. The six kinds: `srgbClr`,
+ * `scrgbClr` (linear percentages), `hslClr`, `sysClr` (the machine's colour by name, not `lastClr`), `prstClr` and
+ * `schemeClr` (through {@link ThemeColors}). Their transforms apply in document order, in the spaces Word and
+ * PowerPoint use, measured on 403 cases each (docx4j CR-034 section 11, P3):
+ * - `tint`, `shade`, `inv`, `red`/`green`/`blue` and their `Off`/`Mod`: linear RGB; `gamma` and `invGamma`: the
+ *   sRGB transfer function each way;
+ * - `hue`, `sat`, `lum` and their `Off`/`Mod`, `comp`: HSL of the sRGB colour, the saturation not clamped (the
+ *   channels are, afterwards); a colour whose last change is a luminance transform converted back as Foley and van
+ *   Dam do and rounded half down, as Office rounds it (so `tx1` at `lumMod 50000 lumOff 50000` is 7F7F7F);
+ * - `gray`: Rec.709 luma of the sRGB channels;
+ * - `alpha`, `alphaOff`, `alphaMod`: the alpha.
+ *
+ * MS-OI29500 says `lumOff` and `satOff` are not supported by Office; Office 365 applies both as above in every case
+ * measured. Known differences from Office: a saturation set on a grey (Office gives a grey's hue about 40 degrees),
+ * and some hue, saturation and luminance cases one unit off.
+ *
+ * An object is known by its `TYPE_NAME` (which the objects package's unmarshal and factories give it), or, wrapped
+ * as `{ name, value }`, by its element name; a holder of a colour also by its `srgbClr`, `schemeClr`, ... member.
+ * docx4j's `null` is `undefined` here.
+ */
+export const DrawingMLColors = {
+    /**
+     * The colour a DrawingML colour element, or an element holding one, resolves to.
+     *
+     * @param colour one of the six kinds (`CTSchemeColor`, `CTSRgbColor`, ...), or a holder of one: `CTColor` (a
+     *   scheme slot), `CTSolidColorFillProperties`, `CTStyleMatrixReference`, `CTFontReference`; `{ name, value }`
+     *   is unwrapped
+     * @param theme the theme and colour map for `schemeClr`; may be undefined where there is none
+     * @returns undefined where there is no colour, or a `schemeClr` cannot be resolved
+     */
+    resolve(colour, theme) {
+        const c = kind(colour);
+        if (c === undefined)
+            return undefined;
+        const b = base(c.value, c.type, theme);
+        if (b === undefined)
+            return undefined;
+        return transform(b, c.value.egColorTransform);
+    },
+    /** A fill: `a:noFill`, `a:solidFill` (its colour resolved), or a gradient, pattern, picture or group fill reported by kind. */
+    fill(fillProperties, theme) {
+        const f = fillOf(fillProperties);
+        return f === undefined ? StyleFill.UNKNOWN : fillOfType(f.type, f.value, theme);
+    },
+    /** A line's fill: none, solid, gradient or pattern. */
+    lineFill(ln, theme) {
+        if (ln === undefined || ln === null)
+            return StyleFill.UNKNOWN;
+        if (ln.noFill !== undefined && ln.noFill !== null)
+            return StyleFill.NONE;
+        if (ln.solidFill !== undefined && ln.solidFill !== null)
+            return fillOfType(FILL_NAMES.solidFill, ln.solidFill, theme);
+        if (ln.gradFill !== undefined && ln.gradFill !== null)
+            return fillOfType(FILL_NAMES.gradFill, ln.gradFill, theme);
+        if (ln.pattFill !== undefined && ln.pattFill !== null)
+            return fillOfType(FILL_NAMES.pattFill, ln.pattFill, theme);
+        return StyleFill.UNKNOWN;
+    },
+    /**
+     * A shape style's `a:fillRef`: index 0 is no fill, 1 to 999 the theme's `a:fillStyleLst`, 1001 and up its
+     * `a:bgFillStyleLst`, with `phClr` the reference's own colour.
+     */
+    fillReference(ref, theme) {
+        var _a, _b;
+        if (ref === undefined || ref === null)
+            return StyleFill.UNKNOWN;
+        const idx = ref.idx;
+        if (idx === 0)
+            return StyleFill.NONE;
+        const fmt = theme === null || theme === void 0 ? void 0 : theme.formatScheme;
+        if (theme === undefined || fmt === undefined)
+            return StyleFill.UNKNOWN;
+        const list = idx >= 1001 ? (_a = fmt.bgFillStyleLst) === null || _a === void 0 ? void 0 : _a.egFillProperties : (_b = fmt.fillStyleLst) === null || _b === void 0 ? void 0 : _b.egFillProperties;
+        const i = Math.trunc(idx >= 1001 ? idx - 1001 : idx - 1);
+        if (list === undefined || list === null || i < 0 || i >= list.length)
+            return StyleFill.UNKNOWN;
+        return DrawingMLColors.fill(list[i], theme.withPlaceholder(DrawingMLColors.resolve(holder(ref), theme)));
+    },
+    /** A shape style's `a:lnRef`: index 0 is no line, else the theme's `a:lnStyleLst` entry's fill. */
+    lineReference(ref, theme) {
+        var _a;
+        if (ref === undefined || ref === null)
+            return StyleFill.UNKNOWN;
+        const idx = ref.idx;
+        if (idx === 0)
+            return StyleFill.NONE;
+        const fmt = theme === null || theme === void 0 ? void 0 : theme.formatScheme;
+        if (theme === undefined || fmt === undefined || fmt.lnStyleLst === undefined || fmt.lnStyleLst === null)
+            return StyleFill.UNKNOWN;
+        const list = (_a = fmt.lnStyleLst.ln) !== null && _a !== void 0 ? _a : [];
+        const i = Math.trunc(idx) - 1;
+        if (i < 0 || i >= list.length)
+            return StyleFill.UNKNOWN;
+        return DrawingMLColors.lineFill(list[i], theme.withPlaceholder(DrawingMLColors.resolve(holder(ref), theme)));
+    },
+    /** A shape style's `a:fontRef`: its colour, the text's where the text states none. */
+    fontReference(ref, theme) {
+        return ref === undefined || ref === null ? undefined : DrawingMLColors.resolve(holder(ref), theme);
+    },
+};
+function fillOfType(type, f, theme) {
+    switch (type) {
+        case FILL_NAMES.noFill: return StyleFill.NONE;
+        case FILL_NAMES.solidFill: return new StyleFill('SOLID', DrawingMLColors.resolve(holder(f), theme), f);
+        case FILL_NAMES.gradFill: return new StyleFill('GRADIENT', undefined, f);
+        case FILL_NAMES.pattFill: return new StyleFill('PATTERN', undefined, f);
+        case FILL_NAMES.blipFill: return new StyleFill('PICTURE', undefined, f);
+        case FILL_NAMES.grpFill: return new StyleFill('GROUP', undefined, f);
+        default: return StyleFill.UNKNOWN;
+    }
+}
+/** A solid fill, a style or a font reference as a holder of its colour, whatever its TYPE_NAME. */
+function holder(ref) {
+    return { srgbClr: ref.srgbClr, schemeClr: ref.schemeClr, scrgbClr: ref.scrgbClr, hslClr: ref.hslClr, sysClr: ref.sysClr, prstClr: ref.prstClr };
+}

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

@@ -0,0 +1,36 @@
+/**
+ * A colour as Office draws it: red, green and blue in sRGB (0 to 255) and an alpha in OOXML's unit
+ * (0 to 100000, where 100000 is opaque). Immutable.
+ *
+ * docx4j's getters are properties here (`getRed()` is `red`); `equals` compares the four values.
+ */
+export declare class ResolvedColor {
+    /** OOXML's opaque alpha, 100% in thousandths of a percent. */
+    static readonly OPAQUE = 100000;
+    static readonly BLACK: ResolvedColor;
+    static readonly WHITE: ResolvedColor;
+    readonly red: number;
+    readonly green: number;
+    readonly blue: number;
+    /** 0 (transparent) to 100000 (opaque). */
+    readonly alpha: number;
+    private constructor();
+    /** An opaque colour; each channel is clamped to 0 to 255. */
+    static rgb(red: number, green: number, blue: number): ResolvedColor;
+    /**
+     * An opaque colour from six hex digits (RRGGBB, either case; a leading '#' is allowed).
+     *
+     * @returns undefined where the string is not six hex digits ("auto", for instance)
+     */
+    static ofHex(hex: string | null | undefined): ResolvedColor | undefined;
+    /** This colour with another alpha (0 to 100000). */
+    withAlpha(alpha: number): ResolvedColor;
+    get isOpaque(): boolean;
+    /** RRGGBB, upper case, without the alpha. */
+    toHex(): string;
+    /** Whether each channel is within `units` of the other colour's (alpha not compared). */
+    within(other: ResolvedColor | undefined, units: number): boolean;
+    equals(other: unknown): boolean;
+    /** RRGGBB, or RRGGBB/alpha where not opaque. */
+    toString(): string;
+}

package/dist/model/color/ResolvedColor.mjs

@@ -0,0 +1,65 @@
+// A colour as Office draws it: docx4j `org.docx4j.model.color.ResolvedColor` (CR-034).
+function clamp(v, max) {
+    return v < 0 ? 0 : v > max ? max : v;
+}
+/**
+ * A colour as Office draws it: red, green and blue in sRGB (0 to 255) and an alpha in OOXML's unit
+ * (0 to 100000, where 100000 is opaque). Immutable.
+ *
+ * docx4j's getters are properties here (`getRed()` is `red`); `equals` compares the four values.
+ */
+export class ResolvedColor {
+    constructor(red, green, blue, alpha) {
+        // Java's int arguments: a caller here could pass a fraction
+        this.red = clamp(Math.trunc(red), 255);
+        this.green = clamp(Math.trunc(green), 255);
+        this.blue = clamp(Math.trunc(blue), 255);
+        this.alpha = clamp(Math.trunc(alpha), ResolvedColor.OPAQUE);
+    }
+    /** An opaque colour; each channel is clamped to 0 to 255. */
+    static rgb(red, green, blue) {
+        return new ResolvedColor(red, green, blue, ResolvedColor.OPAQUE);
+    }
+    /**
+     * An opaque colour from six hex digits (RRGGBB, either case; a leading '#' is allowed).
+     *
+     * @returns undefined where the string is not six hex digits ("auto", for instance)
+     */
+    static ofHex(hex) {
+        if (hex === undefined || hex === null)
+            return undefined;
+        const h = hex.startsWith('#') ? hex.substring(1) : hex;
+        if (!/^[0-9A-Fa-f]{6}$/.test(h))
+            return undefined;
+        const v = Number.parseInt(h, 16);
+        return ResolvedColor.rgb((v >> 16) & 0xFF, (v >> 8) & 0xFF, v & 0xFF);
+    }
+    /** This colour with another alpha (0 to 100000). */
+    withAlpha(alpha) {
+        return new ResolvedColor(this.red, this.green, this.blue, alpha);
+    }
+    get isOpaque() {
+        return this.alpha === ResolvedColor.OPAQUE;
+    }
+    /** RRGGBB, upper case, without the alpha. */
+    toHex() {
+        return [this.red, this.green, this.blue].map((c) => c.toString(16).toUpperCase().padStart(2, '0')).join('');
+    }
+    /** Whether each channel is within `units` of the other colour's (alpha not compared). */
+    within(other, units) {
+        return other !== undefined && Math.abs(this.red - other.red) <= units && Math.abs(this.green - other.green) <= units
+            && Math.abs(this.blue - other.blue) <= units;
+    }
+    equals(other) {
+        return other instanceof ResolvedColor && this.red === other.red && this.green === other.green
+            && this.blue === other.blue && this.alpha === other.alpha;
+    }
+    /** RRGGBB, or RRGGBB/alpha where not opaque. */
+    toString() {
+        return this.isOpaque ? this.toHex() : `${this.toHex()}/${this.alpha}`;
+    }
+}
+/** OOXML's opaque alpha, 100% in thousandths of a percent. */
+ResolvedColor.OPAQUE = 100000;
+ResolvedColor.BLACK = new ResolvedColor(0, 0, 0, ResolvedColor.OPAQUE);
+ResolvedColor.WHITE = new ResolvedColor(255, 255, 255, ResolvedColor.OPAQUE);

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

@@ -0,0 +1,36 @@
+import type * as sml from '@docx4j/generated-objects-ts/modules/org_xlsx4j_sml';
+import { ResolvedColor } from './ResolvedColor.mjs';
+import type { ThemeColors } from './ThemeColors.mjs';
+/**
+ * SpreadsheetML colours (`x:color`, `x:fgColor`, `x:bgColor` and the font and border colours, ISO/IEC 29500-1
+ * section 18.8) resolved as Excel draws them (docx4j CR-034 section 11, P4).
+ *
+ * - `theme`: Excel's index swaps the first two pairs (0 lt1, 1 dk1, 2 lt2, 3 dk2, then the accents and hyperlinks),
+ *   as {@link ThemeColors.sheetThemeColor} does.
+ * - `indexed`: the legacy 64-colour palette, or all 64 entries of the workbook's own `x:indexedColors`; 64 and 65
+ *   the system foreground and background (black, white).
+ * - `tint`, −1 to 1: the HLS luminance, L' = L·(1 + tint) below 0, L·(1 − tint) + HLSMAX·tint above, in Windows'
+ *   integer HLS (HLSMAX 240), the luminance truncated after adding 0.02; a tint of 0 leaves the colour alone. All 90
+ *   theme-and-tint cells measured exact. (Not POI's per-channel rule.)
+ *
+ * The `rgb` attributes are hexBinary, which the objects model holds as byte numbers (its declarations say a string;
+ * either is read). docx4j's `null` is `undefined` here.
+ */
+export declare const SpreadsheetColors: {
+    /**
+     * @param c the colour element
+     * @param theme the workbook's theme
+     * @param indexedColors the workbook's `x:indexedColors`, or undefined for the legacy palette
+     * @returns undefined for `auto` or nothing stated: the caller's automatic colour
+     */
+    resolve(c: sml.CTColor | undefined | null, theme: ThemeColors | undefined, indexedColors?: sml.CTIndexedColors | null): ResolvedColor | undefined;
+    /** An indexed colour: the workbook's palette for 0 to 63 where it has one, else the legacy one. */
+    indexed(i: number, indexedColors?: sml.CTIndexedColors | null): ResolvedColor | undefined;
+    /**
+     * Excel's tint: Windows' integer HLS, the luminance truncated after adding 0.02. Plain truncation is two cells out
+     * of 90 short (both at tint 0.3333, whose luminance comes to just under a whole number and which Excel rounds up);
+     * any tolerance from 0.01 to 0.05 gives all 90, presumably the precision Excel keeps a tint at.
+     * Package-private in docx4j.
+     */
+    tint(c: ResolvedColor, tint: number): ResolvedColor;
+};

package/dist/model/color/SpreadsheetColors.mjs

@@ -0,0 +1,84 @@
+import * as ColorMath from './ColorMath.mjs';
+import { INDEXED } from './ColorTables.mjs';
+import { bytesOf } from './DrawingMLColors.mjs';
+import { ResolvedColor } from './ResolvedColor.mjs';
+/** ARGB (4 bytes) or RGB (3 bytes); the alpha byte is not drawn by Excel and is ignored. */
+function argb(v) {
+    const b = bytesOf(v);
+    if (b === undefined)
+        return undefined;
+    if (b.length === 4)
+        return ResolvedColor.rgb(b[1], b[2], b[3]);
+    if (b.length === 3)
+        return ResolvedColor.rgb(b[0], b[1], b[2]);
+    return undefined;
+}
+/**
+ * SpreadsheetML colours (`x:color`, `x:fgColor`, `x:bgColor` and the font and border colours, ISO/IEC 29500-1
+ * section 18.8) resolved as Excel draws them (docx4j CR-034 section 11, P4).
+ *
+ * - `theme`: Excel's index swaps the first two pairs (0 lt1, 1 dk1, 2 lt2, 3 dk2, then the accents and hyperlinks),
+ *   as {@link ThemeColors.sheetThemeColor} does.
+ * - `indexed`: the legacy 64-colour palette, or all 64 entries of the workbook's own `x:indexedColors`; 64 and 65
+ *   the system foreground and background (black, white).
+ * - `tint`, −1 to 1: the HLS luminance, L' = L·(1 + tint) below 0, L·(1 − tint) + HLSMAX·tint above, in Windows'
+ *   integer HLS (HLSMAX 240), the luminance truncated after adding 0.02; a tint of 0 leaves the colour alone. All 90
+ *   theme-and-tint cells measured exact. (Not POI's per-channel rule.)
+ *
+ * The `rgb` attributes are hexBinary, which the objects model holds as byte numbers (its declarations say a string;
+ * either is read). docx4j's `null` is `undefined` here.
+ */
+export const SpreadsheetColors = {
+    /**
+     * @param c the colour element
+     * @param theme the workbook's theme
+     * @param indexedColors the workbook's `x:indexedColors`, or undefined for the legacy palette
+     * @returns undefined for `auto` or nothing stated: the caller's automatic colour
+     */
+    resolve(c, theme, indexedColors) {
+        var _a;
+        if (c === undefined || c === null || c.auto === true)
+            return undefined;
+        let base;
+        if (c.rgb !== undefined && c.rgb !== null) {
+            base = argb(c.rgb);
+        }
+        else if (c.theme !== undefined && c.theme !== null) {
+            base = theme === undefined ? undefined : theme.sheetThemeColor(Math.trunc(c.theme));
+        }
+        else if (c.indexed !== undefined && c.indexed !== null) {
+            base = SpreadsheetColors.indexed(Math.trunc(c.indexed), indexedColors);
+        }
+        if (base === undefined)
+            return undefined;
+        const tint = (_a = c.tint) !== null && _a !== void 0 ? _a : 0;
+        return tint === 0 ? base : SpreadsheetColors.tint(base, tint);
+    },
+    /** An indexed colour: the workbook's palette for 0 to 63 where it has one, else the legacy one. */
+    indexed(i, indexedColors) {
+        var _a;
+        if (indexedColors !== undefined && indexedColors !== null && i >= 0 && i < 64) {
+            const custom = (_a = indexedColors.rgbColor) !== null && _a !== void 0 ? _a : [];
+            if (i < custom.length && custom[i].rgb !== undefined && custom[i].rgb !== null)
+                return argb(custom[i].rgb);
+        }
+        return i >= 0 && i < INDEXED.length ? ResolvedColor.ofHex(INDEXED[i]) : undefined;
+    },
+    /**
+     * Excel's tint: Windows' integer HLS, the luminance truncated after adding 0.02. Plain truncation is two cells out
+     * of 90 short (both at tint 0.3333, whose luminance comes to just under a whole number and which Excel rounds up);
+     * any tolerance from 0.01 to 0.05 gives all 90, presumably the precision Excel keeps a tint at.
+     * Package-private in docx4j.
+     */
+    tint(c, tint) {
+        const hls = ColorMath.rgbToHls240(c.red, c.green, c.blue);
+        const l = tint < 0 ? hls[1] * (1 + tint) : hls[1] * (1 - tint) + (ColorMath.HLSMAX - ColorMath.HLSMAX * (1 - tint));
+        let li = Math.trunc(l + 0.02);
+        if (li < 0)
+            li = 0;
+        if (li > ColorMath.HLSMAX)
+            li = ColorMath.HLSMAX;
+        const rgb = ColorMath.hls240ToRgb(hls[0], li, hls[2]);
+        return ResolvedColor.rgb(rgb[0], rgb[1], rgb[2]);
+    },
+};

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

@@ -0,0 +1,28 @@
+import type { ResolvedColor } from './ResolvedColor.mjs';
+/**
+ * docx4j's `StyleFill.Kind`, as its names: `NONE` (`a:noFill`, or a style reference with index 0), `SOLID`
+ * (`a:solidFill`: `color` is its colour), `GRADIENT` (`a:gradFill`), `PATTERN` (`a:pattFill`), `PICTURE`
+ * (`a:blipFill`), `GROUP` (`a:grpFill`: the group's fill), `UNKNOWN` (nothing stated, or a style reference whose
+ * index is outside the theme's lists).
+ */
+export type StyleFillKind = 'NONE' | 'SOLID' | 'GRADIENT' | 'PATTERN' | 'PICTURE' | 'GROUP' | 'UNKNOWN';
+/**
+ * A DrawingML fill as far as colour resolution goes: none, a solid colour (resolved), or a gradient, pattern,
+ * picture or group fill, which is reported as such and not guessed at - drawing one is a renderer's business.
+ * For a line, the fill is the line's. docx4j's getters are properties here (`getKind()` is `kind`).
+ */
+export declare class StyleFill {
+    readonly kind: StyleFillKind;
+    /** The colour of a `SOLID` fill, else undefined. */
+    readonly color: ResolvedColor | undefined;
+    /** The fill object (`a:gradFill` and so on), for a renderer; undefined for none. */
+    readonly fill: unknown;
+    static readonly NONE: StyleFill;
+    static readonly UNKNOWN: StyleFill;
+    constructor(kind: StyleFillKind, 
+    /** The colour of a `SOLID` fill, else undefined. */
+    color: ResolvedColor | undefined, 
+    /** The fill object (`a:gradFill` and so on), for a renderer; undefined for none. */
+    fill: unknown);
+    toString(): string;
+}

package/dist/model/color/StyleFill.mjs

@@ -0,0 +1,21 @@
+/**
+ * A DrawingML fill as far as colour resolution goes: none, a solid colour (resolved), or a gradient, pattern,
+ * picture or group fill, which is reported as such and not guessed at - drawing one is a renderer's business.
+ * For a line, the fill is the line's. docx4j's getters are properties here (`getKind()` is `kind`).
+ */
+export class StyleFill {
+    constructor(kind, 
+    /** The colour of a `SOLID` fill, else undefined. */
+    color, 
+    /** The fill object (`a:gradFill` and so on), for a renderer; undefined for none. */
+    fill) {
+        this.kind = kind;
+        this.color = color;
+        this.fill = fill;
+    }
+    toString() {
+        return this.kind === 'SOLID' ? `solid ${String(this.color)}` : this.kind.toLowerCase();
+    }
+}
+StyleFill.NONE = new StyleFill('NONE', undefined, undefined);
+StyleFill.UNKNOWN = new StyleFill('UNKNOWN', undefined, undefined);