@rowsncolumns/spreadsheet 10.6.0 → 10.6.5

package/dist/cjs/api/cf-overlays.d.ts

@@ -1,7 +1,93 @@
-import type { CfThreshold, IconSetFamily } from "../types";
+import type { CellFormat, CfThreshold, ConditionalFormatRule, IconSetFamily } from "../types";
 export declare const ICON_SET_GLYPHS: Record<IconSetFamily, string[]>;
+/** The colour each icon is painted in — what text stand-ins use. */
 export declare const ICON_SET_COLORS: Record<IconSetFamily, string[]>;
-export declare const resolveThreshold: (threshold: CfThreshold, rangeMin: number, rangeMax: number) => number;
-export declare const pickIconBucket: (value: number, sortedThresholds: number[]) => number;
+/**
+ * Numeric statistics of a rule's covered cells — what cfvo thresholds
+ * resolve against. `sorted` (ascending) backs PERCENTILE thresholds; it may
+ * be omitted when the caller already knows the rule needs no percentile.
+ */
+export type CfRangeStats = {
+    count: number;
+    min: number;
+    max: number;
+    sorted?: number[];
+    /**
+     * Engine-backed stand-ins for `sorted` on windowed hosts: PERCENTILE.INC
+     * at `p` (0..100), the k-th largest / smallest value (`k` a percent of the
+     * count when `percent`), the mean and the sample standard deviation.
+     */
+    percentile?: (p: number) => number;
+    rankValue?: (k: number, top: boolean, percent?: boolean) => number;
+    mean?: number;
+    stdDev?: number;
+};
+/** What a rule needs from its full-range statistics (the engine request). */
+export type CfRuleStatsRequest = {
+    percentiles: number[];
+    ranks: Array<{
+        k: number;
+        top: boolean;
+        percent?: boolean;
+    }>;
+};
+/** The engine's reply to a {@link CfRuleStatsRequest} (`conditionalFormatRuleStats`). */
+export type CfRuleStatsResponse = {
+    count: number;
+    min: number | null;
+    max: number | null;
+    mean: number | null;
+    stdDev: number | null;
+    percentiles: Array<number | null>;
+    ranks: Array<number | null>;
+};
+/** The percentiles / ranks a rule's thresholds resolve with. */
+export declare const buildCfRuleStatsRequest: (rule: ConditionalFormatRule) => CfRuleStatsRequest;
+/**
+ * Turn the engine's reply into {@link CfRangeStats} for the CF hook — what a
+ * windowed host returns from `getConditionalFormatRuleStats`.
+ */
+export declare const toCfRangeStats: (request: CfRuleStatsRequest, response: CfRuleStatsResponse | null | undefined) => CfRangeStats | undefined;
+export declare const buildCfRangeStats: (values: number[]) => CfRangeStats;
+/** Excel's PERCENTILE.INC over ascending values (`p` in 0..100). */
+export declare const percentileInc: (sorted: number[], p: number) => number;
+/**
+ * Resolves a FORMULA threshold's text (e.g. `=$B$1`, `=10`) to a number,
+ * or `undefined` when it can't be evaluated.
+ */
+export type CfFormulaResolver = (formula: string) => number | undefined;
+/**
+ * Resolve a cfvo threshold against the rule's range statistics (OOXML cfvo
+ * semantics). `role` picks the AUTOMATIC bound (data bars only): the lower
+ * bound is `min(0, lowest)`, the upper `max(0, highest)`. Returns NaN when
+ * the threshold can't be resolved.
+ */
+export declare const resolveCfThreshold: (threshold: CfThreshold, stats: CfRangeStats, options?: {
+    role?: "min" | "max";
+    resolveFormula?: CfFormulaResolver;
+}) => number;
+export declare const resolveThreshold: (threshold: CfThreshold, rangeMin: number, rangeMax: number, sorted?: number[]) => number;
+export declare const pickIconBucket: (value: number, thresholds: number[], strict?: boolean[]) => number;
 export declare const computeDataBarFill: (value: number, min: number, max: number) => number;
+/**
+ * Whether a cell counts as a number for data bars, colour scales, icon sets
+ * and the other numeric rules: its computed value is a number (Excel's rule —
+ * a typed `1` or a spilled `=SEQUENCE(3)` value qualifies without any number
+ * format), or it carries a number format (the legacy store's signal).
+ */
+export declare const isConditionalFormatNumberCell: (effectiveValue: Record<string, any> | null | undefined, cellFormat: CellFormat | null | undefined) => boolean;
+/**
+ * The comparison bound of an above / below average rule: the mean, moved
+ * `stdDev` sample standard deviations (Excel's STDEV) above or below it for
+ * the "1/2/3 std dev above / below" options. Mirrors the engine's
+ * `average_bound` (rnc-store `derive.rs`).
+ */
+export declare const averageBound: (values: number[], above: boolean, stdDev?: number | null) => number;
+/**
+ * Whether a CSS colour (`#rrggbb` / `rgb()`) is dark — relative luminance
+ * under 0.5. Unparseable colours count as light.
+ */
+export declare const isDarkCssColor: (color: string | null | undefined) => boolean;
+/** {@link averageBound} from full-range statistics (sorted values or the engine's mean / std dev). */
+export declare const averageBoundFromStats: (stats: CfRangeStats, above: boolean, stdDev?: number | null) => number | undefined;
 //# sourceMappingURL=cf-overlays.d.ts.map

package/dist/cjs/api/cf-overlays.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cf-overlays.d.ts","sourceRoot":"","sources":["../../../api/cf-overlays.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE3D,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,CAqB3D,CAAC;AAIF,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,CAkB3D,CAAC;AAKF,eAAO,MAAM,gBAAgB,GAC3B,WAAW,WAAW,EACtB,UAAU,MAAM,EAChB,UAAU,MAAM,KACf,MA6BF,CAAC;AAIF,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,kBAAkB,MAAM,EAAE,WAQvE,CAAC;AAKF,eAAO,MAAM,kBAAkB,GAC7B,OAAO,MAAM,EACb,KAAK,MAAM,EACX,KAAK,MAAM,KACV,MAWF,CAAC"}
+{"version":3,"file":"cf-overlays.d.ts","sourceRoot":"","sources":["../../../api/cf-overlays.ts"],"names":[],"mappings":"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"}

package/dist/cjs/api/cf-overlays.js

@@ -1,122 +1,231 @@
 "use strict";
 // Helpers for IconSetRule and DataBarRule evaluation.
 //
-// Excel ships ~17 named icon-set families. We render them with Unicode glyphs
-// so no font / SVG asset is required. Each family is an ordered list of
-// glyphs from "worst" → "best"; `reverse` on the rule flips this. The number
-// of glyphs encodes the family's bucket count (3, 4, or 5).
+// Icon sets are painted as vector icons (`cf-icons.ts`); the glyphs below
+// are the plain-text stand-ins menus (filter by icon, rule lists) show. Every
+// family lists its icons in OOXML `iconId` order — index 0 is the icon of the
+// LOWEST bucket; `reverse` on the rule flips the order. The number of icons
+// encodes the family's bucket count (3, 4, or 5).
 //
-// Bucket selection: given thresholds[0..n-2] (ascending) and the cell's
-// numeric value, the bucket index is the count of thresholds the value
-// equals-or-exceeds. (i.e. value < thresholds[0] → 0; >= thresholds[n-2] →
-// n-1.) Threshold types follow OOXML cfvo semantics: NUMBER is absolute,
-// PERCENT/PERCENTILE are computed relative to the range.
+// Bucket selection (Excel): thresholds are checked from the top bucket down;
+// a value lands in the first bucket whose threshold it meets (`>=`, or `>`
+// when the threshold's `gte` is false), else in bucket 0. Threshold types
+// follow OOXML cfvo semantics: NUMBER is absolute, PERCENT is relative to
+// the range's min..max, PERCENTILE is PERCENTILE.INC over the range values.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.computeDataBarFill = exports.pickIconBucket = exports.resolveThreshold = exports.ICON_SET_COLORS = exports.ICON_SET_GLYPHS = void 0;
+exports.averageBoundFromStats = exports.isDarkCssColor = exports.averageBound = exports.isConditionalFormatNumberCell = exports.computeDataBarFill = exports.pickIconBucket = exports.resolveThreshold = exports.resolveCfThreshold = exports.percentileInc = exports.buildCfRangeStats = exports.toCfRangeStats = exports.buildCfRuleStatsRequest = exports.ICON_SET_COLORS = exports.ICON_SET_GLYPHS = void 0;
 var tslib_1 = require("tslib");
+var utils_1 = require("@rowsncolumns/utils");
+var cf_icons_1 = require("./cf-icons");
 exports.ICON_SET_GLYPHS = {
-    // 3-icon families (worst → best)
+    // 3-icon families (lowest → highest)
     "3Arrows": ["▼", "▶", "▲"],
     "3ArrowsGray": ["▽", "▷", "△"],
-    "3Flags": ["⚑", "⚐", "⚑"],
+    "3Flags": ["⚑", "⚑", "⚑"],
     "3TrafficLights1": ["●", "●", "●"],
-    "3TrafficLights2": ["■", "■", "■"],
+    "3TrafficLights2": ["●", "●", "●"],
     "3Signs": ["◆", "▲", "●"],
-    "3Symbols": ["✖", "❗", "✔"],
+    "3Symbols": ["✖", "!", "✔"],
     "3Symbols2": ["✗", "!", "✓"],
+    "3Stars": ["☆", "⯪", "★"],
+    "3Triangles": ["▼", "▬", "▲"],
     // 4-icon families
     "4Arrows": ["▼", "↘", "↗", "▲"],
     "4ArrowsGray": ["▽", "↘", "↗", "△"],
     "4RedToBlack": ["●", "●", "●", "●"],
-    "4Rating": ["▁", "▃", "▅", "▇"],
-    "4TrafficLights": ["■", "●", "●", "●"],
+    "4Rating": ["▂", "▃", "▅", "▇"],
+    "4TrafficLights": ["●", "●", "●", "●"],
     // 5-icon families
     "5Arrows": ["▼", "↘", "→", "↗", "▲"],
     "5ArrowsGray": ["▽", "↘", "→", "↗", "△"],
     "5Rating": ["▁", "▂", "▄", "▆", "▇"],
     "5Quarters": ["○", "◔", "◑", "◕", "●"],
+    "5Boxes": ["□", "◰", "◧", "◩", "■"],
 };
-// Per-family default colors for traffic lights / signs / arrows. When the
-// imported rule doesn't carry explicit per-icon colors we use these.
-exports.ICON_SET_COLORS = {
-    "3Arrows": ["#dc2626", "#f59e0b", "#16a34a"],
-    "3ArrowsGray": ["#6b7280", "#6b7280", "#6b7280"],
-    "3Flags": ["#dc2626", "#f59e0b", "#16a34a"],
-    "3TrafficLights1": ["#dc2626", "#f59e0b", "#16a34a"],
-    "3TrafficLights2": ["#dc2626", "#f59e0b", "#16a34a"],
-    "3Signs": ["#dc2626", "#f59e0b", "#16a34a"],
-    "3Symbols": ["#dc2626", "#f59e0b", "#16a34a"],
-    "3Symbols2": ["#dc2626", "#f59e0b", "#16a34a"],
-    "4Arrows": ["#dc2626", "#f59e0b", "#84cc16", "#16a34a"],
-    "4ArrowsGray": ["#6b7280", "#6b7280", "#6b7280", "#6b7280"],
-    "4RedToBlack": ["#dc2626", "#f97316", "#525252", "#000000"],
-    "4Rating": ["#6b7280", "#6b7280", "#6b7280", "#6b7280"],
-    "4TrafficLights": ["#dc2626", "#f59e0b", "#84cc16", "#16a34a"],
-    "5Arrows": ["#dc2626", "#f59e0b", "#eab308", "#84cc16", "#16a34a"],
-    "5ArrowsGray": ["#6b7280", "#6b7280", "#6b7280", "#6b7280", "#6b7280"],
-    "5Rating": ["#6b7280", "#6b7280", "#6b7280", "#6b7280", "#6b7280"],
-    "5Quarters": ["#6b7280", "#6b7280", "#6b7280", "#6b7280", "#6b7280"],
+var shapeColor = function (shape) {
+    switch (shape.kind) {
+        case "star":
+            return "#F5B800";
+        case "rating":
+        case "boxes":
+            return "#2F6EBA";
+        case "quarters":
+            return "#262626";
+        default:
+            return shape.color;
+    }
 };
-// Resolve a cfvo threshold value against a range's min/max numeric values.
-// Returns NaN when the threshold can't be resolved (e.g. PERCENT against
-// an empty range), which downstream callers should skip.
-var resolveThreshold = function (threshold, rangeMin, rangeMax) {
-    var raw = threshold.value;
-    var num = typeof raw === "number" ? raw : Number(raw);
+/** The colour each icon is painted in — what text stand-ins use. */
+exports.ICON_SET_COLORS = Object.fromEntries(Object.entries(cf_icons_1.CF_ICON_SETS).map(function (_a) {
+    var _b = tslib_1.__read(_a, 2), family = _b[0], shapes = _b[1];
+    return [
+        family,
+        shapes.map(shapeColor),
+    ];
+}));
+/** The percentiles / ranks a rule's thresholds resolve with. */
+var buildCfRuleStatsRequest = function (rule) {
+    var _a, _b, _c, _d, _e, _f;
+    var percentiles = new Set();
+    var addPoint = function (point) {
+        if ((point === null || point === void 0 ? void 0 : point.type) !== "PERCENTILE")
+            return;
+        var p = Number(point.value);
+        if (!Number.isFinite(p))
+            return;
+        percentiles.add(p);
+        // Colour scales read a 0..1 percentile as a fraction.
+        if (p <= 1)
+            percentiles.add(p * 100);
+    };
+    addPoint((_a = rule.dataBarRule) === null || _a === void 0 ? void 0 : _a.minpoint);
+    addPoint((_b = rule.dataBarRule) === null || _b === void 0 ? void 0 : _b.maxpoint);
+    (_c = rule.iconSetRule) === null || _c === void 0 ? void 0 : _c.thresholds.forEach(addPoint);
+    addPoint((_d = rule.gradientRule) === null || _d === void 0 ? void 0 : _d.minpoint);
+    addPoint((_e = rule.gradientRule) === null || _e === void 0 ? void 0 : _e.midpoint);
+    addPoint((_f = rule.gradientRule) === null || _f === void 0 ? void 0 : _f.maxpoint);
+    var ranks = [];
+    if (rule.topBottomRule) {
+        ranks.push({
+            k: rule.topBottomRule.rank,
+            top: rule.topBottomRule.type === "TOP",
+            percent: !!rule.topBottomRule.isPercent,
+        });
+    }
+    return { percentiles: tslib_1.__spreadArray([], tslib_1.__read(percentiles), false), ranks: ranks };
+};
+exports.buildCfRuleStatsRequest = buildCfRuleStatsRequest;
+/**
+ * Turn the engine's reply into {@link CfRangeStats} for the CF hook — what a
+ * windowed host returns from `getConditionalFormatRuleStats`.
+ */
+var toCfRangeStats = function (request, response) {
+    var _a, _b, _c, _d;
+    if (!response)
+        return undefined;
+    var at = function (list, i) {
+        return i >= 0 && list[i] != null ? list[i] : NaN;
+    };
+    return {
+        count: response.count,
+        min: (_a = response.min) !== null && _a !== void 0 ? _a : NaN,
+        max: (_b = response.max) !== null && _b !== void 0 ? _b : NaN,
+        mean: (_c = response.mean) !== null && _c !== void 0 ? _c : undefined,
+        stdDev: (_d = response.stdDev) !== null && _d !== void 0 ? _d : undefined,
+        percentile: function (p) {
+            return at(response.percentiles, request.percentiles.indexOf(p));
+        },
+        rankValue: function (k, top, percent) {
+            return at(response.ranks, request.ranks.findIndex(function (r) { return r.k === k && r.top === top && !!r.percent === !!percent; }));
+        },
+    };
+};
+exports.toCfRangeStats = toCfRangeStats;
+var buildCfRangeStats = function (values) {
+    var sorted = values.slice().sort(function (a, b) { return a - b; });
+    return {
+        count: sorted.length,
+        min: sorted.length ? sorted[0] : NaN,
+        max: sorted.length ? sorted[sorted.length - 1] : NaN,
+        sorted: sorted,
+    };
+};
+exports.buildCfRangeStats = buildCfRangeStats;
+/** Excel's PERCENTILE.INC over ascending values (`p` in 0..100). */
+var percentileInc = function (sorted, p) {
+    if (!sorted.length || !Number.isFinite(p))
+        return NaN;
+    var k = (Math.max(0, Math.min(100, p)) / 100) * (sorted.length - 1);
+    var lower = Math.floor(k);
+    var upper = Math.ceil(k);
+    if (lower === upper)
+        return sorted[lower];
+    return sorted[lower] + (sorted[upper] - sorted[lower]) * (k - lower);
+};
+exports.percentileInc = percentileInc;
+var numericValue = function (raw) {
+    return typeof raw === "number" ? raw : raw == null || raw === "" ? NaN : Number(raw);
+};
+/**
+ * Resolve a cfvo threshold against the rule's range statistics (OOXML cfvo
+ * semantics). `role` picks the AUTOMATIC bound (data bars only): the lower
+ * bound is `min(0, lowest)`, the upper `max(0, highest)`. Returns NaN when
+ * the threshold can't be resolved.
+ */
+var resolveCfThreshold = function (threshold, stats, options) {
+    var _a, _b;
+    if (options === void 0) { options = {}; }
+    var num = numericValue(threshold.value);
     switch (threshold.type) {
         case "MIN":
-            return rangeMin;
+            return stats.min;
         case "MAX":
-            return rangeMax;
+            return stats.max;
+        case "AUTOMATIC":
+            return options.role === "max"
+                ? Math.max(0, stats.max)
+                : Math.min(0, stats.min);
         case "NUMBER":
             return Number.isFinite(num) ? num : NaN;
-        case "PERCENT": {
+        case "PERCENT":
             if (!Number.isFinite(num))
                 return NaN;
-            var span = rangeMax - rangeMin;
-            return rangeMin + (span * num) / 100;
-        }
+            return stats.min + ((stats.max - stats.min) * num) / 100;
         case "PERCENTILE":
-            // Approximate percentile by linear interpolation of min/max — the
-            // engine doesn't have access to the sorted value list here. For tight
-            // OOXML conformance the caller can pass a true percentile separately.
             if (!Number.isFinite(num))
                 return NaN;
-            return rangeMin + (rangeMax - rangeMin) * (num / 100);
-        case "FORMULA":
-            // FORMULA thresholds aren't evaluated client-side here; the importer
-            // will have substituted a computed number into `value`. If still a
-            // string, skip.
-            return Number.isFinite(num) ? num : NaN;
+            return stats.sorted
+                ? (0, exports.percentileInc)(stats.sorted, num)
+                : stats.percentile
+                    ? stats.percentile(num)
+                    : stats.min + (stats.max - stats.min) * (num / 100);
+        case "FORMULA": {
+            if (Number.isFinite(num))
+                return num;
+            var text = String((_a = threshold.value) !== null && _a !== void 0 ? _a : "").trim();
+            if (!text)
+                return NaN;
+            var literal = Number(text.replace(/^=/, ""));
+            if (text.replace(/^=/, "") !== "" && Number.isFinite(literal)) {
+                return literal;
+            }
+            var resolved = (_b = options.resolveFormula) === null || _b === void 0 ? void 0 : _b.call(options, text);
+            return typeof resolved === "number" && Number.isFinite(resolved)
+                ? resolved
+                : NaN;
+        }
         default:
             return NaN;
     }
 };
+exports.resolveCfThreshold = resolveCfThreshold;
+// Resolve a cfvo threshold value against a range's min/max numeric values.
+// Returns NaN when the threshold can't be resolved (e.g. PERCENT against
+// an empty range), which downstream callers should skip. Pass `sorted`
+// values for an exact PERCENTILE.
+var resolveThreshold = function (threshold, rangeMin, rangeMax, sorted) {
+    var _a;
+    return (0, exports.resolveCfThreshold)(threshold, {
+        count: (_a = sorted === null || sorted === void 0 ? void 0 : sorted.length) !== null && _a !== void 0 ? _a : 0,
+        min: rangeMin,
+        max: rangeMax,
+        sorted: sorted,
+    });
+};
 exports.resolveThreshold = resolveThreshold;
-// Pick the icon bucket index for a value given ordered thresholds.
-// thresholds: length = (iconCount - 1), ascending.
-var pickIconBucket = function (value, sortedThresholds) {
-    var e_1, _a;
-    var bucket = 0;
-    try {
-        for (var sortedThresholds_1 = tslib_1.__values(sortedThresholds), sortedThresholds_1_1 = sortedThresholds_1.next(); !sortedThresholds_1_1.done; sortedThresholds_1_1 = sortedThresholds_1.next()) {
-            var t = sortedThresholds_1_1.value;
-            if (!Number.isFinite(t))
-                break;
-            if (value >= t)
-                bucket++;
-            else
-                break;
-        }
+// Pick the icon bucket index for a value. `thresholds[i]` is the lower bound
+// of bucket `i + 1` (length = iconCount - 1); `strict[i]` makes it a `>`
+// comparison. Checked from the top bucket down, like Excel; non-finite
+// thresholds never match.
+var pickIconBucket = function (value, thresholds, strict) {
+    for (var i = thresholds.length - 1; i >= 0; i--) {
+        var t = thresholds[i];
+        if (!Number.isFinite(t))
+            continue;
+        if ((strict === null || strict === void 0 ? void 0 : strict[i]) ? value > t : value >= t)
+            return i + 1;
     }
-    catch (e_1_1) { e_1 = { error: e_1_1 }; }
-    finally {
-        try {
-            if (sortedThresholds_1_1 && !sortedThresholds_1_1.done && (_a = sortedThresholds_1.return)) _a.call(sortedThresholds_1);
-        }
-        finally { if (e_1) throw e_1.error; }
-    }
-    return bucket;
+    return 0;
 };
 exports.pickIconBucket = pickIconBucket;
 // Compute a 0..1 fill fraction for a data-bar cell value.
@@ -134,3 +243,70 @@ var computeDataBarFill = function (value, min, max) {
     return (clamped - min) / (max - min);
 };
 exports.computeDataBarFill = computeDataBarFill;
+/**
+ * Whether a cell counts as a number for data bars, colour scales, icon sets
+ * and the other numeric rules: its computed value is a number (Excel's rule —
+ * a typed `1` or a spilled `=SEQUENCE(3)` value qualifies without any number
+ * format), or it carries a number format (the legacy store's signal).
+ */
+var isConditionalFormatNumberCell = function (effectiveValue, cellFormat) {
+    var _a;
+    return (0, utils_1.getExtendedValueNumber)(effectiveValue) != null ||
+        !!((_a = cellFormat === null || cellFormat === void 0 ? void 0 : cellFormat.numberFormat) === null || _a === void 0 ? void 0 : _a.type);
+};
+exports.isConditionalFormatNumberCell = isConditionalFormatNumberCell;
+/**
+ * The comparison bound of an above / below average rule: the mean, moved
+ * `stdDev` sample standard deviations (Excel's STDEV) above or below it for
+ * the "1/2/3 std dev above / below" options. Mirrors the engine's
+ * `average_bound` (rnc-store `derive.rs`).
+ */
+var averageBound = function (values, above, stdDev) {
+    var mean = values.reduce(function (sum, v) { return sum + v; }, 0) / values.length;
+    if (!stdDev || stdDev <= 0 || values.length < 2)
+        return mean;
+    var variance = values.reduce(function (sum, v) { return sum + Math.pow((v - mean), 2); }, 0) / (values.length - 1);
+    var offset = stdDev * Math.sqrt(variance);
+    return above ? mean + offset : mean - offset;
+};
+exports.averageBound = averageBound;
+/**
+ * Whether a CSS colour (`#rrggbb` / `rgb()`) is dark — relative luminance
+ * under 0.5. Unparseable colours count as light.
+ */
+var isDarkCssColor = function (color) {
+    if (!color)
+        return false;
+    var hex = /^#?([0-9a-f]{6})/i.exec(color.trim());
+    var rgb = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i.exec(color.trim());
+    var channels;
+    if (hex) {
+        var n = parseInt(hex[1], 16);
+        channels = [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+    }
+    else if (rgb) {
+        channels = [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])];
+    }
+    if (!channels)
+        return false;
+    var _a = tslib_1.__read(channels.map(function (c) {
+        var v = c / 255;
+        return v <= 0.03928 ? v / 12.92 : Math.pow(((v + 0.055) / 1.055), 2.4);
+    }), 3), r = _a[0], g = _a[1], b = _a[2];
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.5;
+};
+exports.isDarkCssColor = isDarkCssColor;
+/** {@link averageBound} from full-range statistics (sorted values or the engine's mean / std dev). */
+var averageBoundFromStats = function (stats, above, stdDev) {
+    var _a;
+    if (stats.sorted) {
+        return stats.sorted.length
+            ? (0, exports.averageBound)(stats.sorted, above, stdDev)
+            : undefined;
+    }
+    if (stats.mean == null || !stats.count)
+        return undefined;
+    var offset = stdDev && stdDev > 0 ? stdDev * ((_a = stats.stdDev) !== null && _a !== void 0 ? _a : 0) : 0;
+    return above ? stats.mean + offset : stats.mean - offset;
+};
+exports.averageBoundFromStats = averageBoundFromStats;

package/dist/cjs/api/cf-priority.d.ts

@@ -0,0 +1,34 @@
+import type { ConditionalFormatRule } from "../types";
+/**
+ * Conditional-format precedence, as Excel defines it ("Manage conditional formatting rule
+ * precedence", support.microsoft.com): the rule listed FIRST has the highest precedence and wins a
+ * conflicting format; new rules go to the top of the list.
+ *
+ * `priority` carries that order (lower = higher precedence, as in xlsx `<cfRule priority>`). A rule
+ * without one ranks below every rule that has one; ties keep the stored order. The grid paints, the
+ * Rules Manager lists and the exporters number rules with this one ordering.
+ */
+export declare const sortConditionalFormatRules: <T extends Pick<ConditionalFormatRule, "priority">>(rules: ReadonlyArray<T>) => T[];
+/**
+ * The `priority` that puts a new rule above every existing one (Excel adds new rules at the top of
+ * the list). Priorities may go to zero or below; exporters renumber from 1.
+ */
+export declare const getTopConditionalFormatPriority: (rules: ReadonlyArray<Pick<ConditionalFormatRule, "priority">>) => number;
+/** A new rule with its `priority` set to the top of `rules`, unless it already carries one. */
+export declare const withTopConditionalFormatPriority: <T extends Pick<ConditionalFormatRule, "priority">>(rule: T, rules: ReadonlyArray<Pick<ConditionalFormatRule, "priority">>) => T;
+/**
+ * Move one rule up (`-1`) or down (`+1`) among `scope` (the rules the Rules Manager is showing —
+ * "Show formatting rules for" may hide some), returning the `priority` updates that realise the new
+ * order: every rule of the workbook renumbered 1..N in its new precedence order, keeping only the
+ * rules whose priority changes. Empty when the move is a no-op (first rule up, last rule down).
+ */
+export declare const planConditionalFormatMove: <T extends Pick<ConditionalFormatRule, "id" | "priority">>(rules: ReadonlyArray<T>, ruleId: T["id"], direction: -1 | 1, scope?: ReadonlyArray<Pick<T, "id">>) => Array<{
+    rule: T;
+    priority: number;
+}>;
+/** `priority` updates that make `ordered` the precedence order (1..N), changed rules only. */
+export declare const planConditionalFormatOrder: <T extends Pick<ConditionalFormatRule, "priority">>(ordered: ReadonlyArray<T>) => Array<{
+    rule: T;
+    priority: number;
+}>;
+//# sourceMappingURL=cf-priority.d.ts.map

package/dist/cjs/api/cf-priority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cf-priority.d.ts","sourceRoot":"","sources":["../../../api/cf-priority.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEtD;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GACrC,CAAC,SAAS,IAAI,CAAC,qBAAqB,EAAE,UAAU,CAAC,EAEjD,OAAO,aAAa,CAAC,CAAC,CAAC,KACtB,CAAC,EAWwB,CAAC;AAE7B;;;GAGG;AACH,eAAO,MAAM,+BAA+B,GAC1C,OAAO,aAAa,CAAC,IAAI,CAAC,qBAAqB,EAAE,UAAU,CAAC,CAAC,KAC5D,MAQF,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,gCAAgC,GAC3C,CAAC,SAAS,IAAI,CAAC,qBAAqB,EAAE,UAAU,CAAC,EAEjD,MAAM,CAAC,EACP,OAAO,aAAa,CAAC,IAAI,CAAC,qBAAqB,EAAE,UAAU,CAAC,CAAC,KAC5D,CAGgE,CAAC;AAEpE;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GACpC,CAAC,SAAS,IAAI,CAAC,qBAAqB,EAAE,IAAI,GAAG,UAAU,CAAC,EAExD,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,QAAQ,CAAC,CAAC,IAAI,CAAC,EACf,WAAW,CAAC,CAAC,GAAG,CAAC,EACjB,QAAO,aAAa,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,CAAS,KAC1C,KAAK,CAAC;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAerC,CAAC;AAEF,8FAA8F;AAC9F,eAAO,MAAM,0BAA0B,GACrC,CAAC,SAAS,IAAI,CAAC,qBAAqB,EAAE,UAAU,CAAC,EAEjD,SAAS,aAAa,CAAC,CAAC,CAAC,KACxB,KAAK,CAAC;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAGnC,CAAC"}

package/dist/cjs/api/cf-priority.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planConditionalFormatOrder = exports.planConditionalFormatMove = exports.withTopConditionalFormatPriority = exports.getTopConditionalFormatPriority = exports.sortConditionalFormatRules = void 0;
+var tslib_1 = require("tslib");
+/**
+ * Conditional-format precedence, as Excel defines it ("Manage conditional formatting rule
+ * precedence", support.microsoft.com): the rule listed FIRST has the highest precedence and wins a
+ * conflicting format; new rules go to the top of the list.
+ *
+ * `priority` carries that order (lower = higher precedence, as in xlsx `<cfRule priority>`). A rule
+ * without one ranks below every rule that has one; ties keep the stored order. The grid paints, the
+ * Rules Manager lists and the exporters number rules with this one ordering.
+ */
+var sortConditionalFormatRules = function (rules) {
+    return rules
+        .map(function (rule, index) { return ({ rule: rule, index: index }); })
+        .sort(function (left, right) {
+        var _a, _b;
+        var leftPriority = (_a = left.rule.priority) !== null && _a !== void 0 ? _a : Number.POSITIVE_INFINITY;
+        var rightPriority = (_b = right.rule.priority) !== null && _b !== void 0 ? _b : Number.POSITIVE_INFINITY;
+        if (leftPriority === rightPriority) {
+            return left.index - right.index;
+        }
+        return leftPriority - rightPriority;
+    })
+        .map(function (_a) {
+        var rule = _a.rule;
+        return rule;
+    });
+};
+exports.sortConditionalFormatRules = sortConditionalFormatRules;
+/**
+ * The `priority` that puts a new rule above every existing one (Excel adds new rules at the top of
+ * the list). Priorities may go to zero or below; exporters renumber from 1.
+ */
+var getTopConditionalFormatPriority = function (rules) {
+    var e_1, _a;
+    var top = 1;
+    try {
+        for (var rules_1 = tslib_1.__values(rules), rules_1_1 = rules_1.next(); !rules_1_1.done; rules_1_1 = rules_1.next()) {
+            var rule = rules_1_1.value;
+            if (typeof rule.priority === "number" && Number.isFinite(rule.priority)) {
+                top = Math.min(top, rule.priority);
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (rules_1_1 && !rules_1_1.done && (_a = rules_1.return)) _a.call(rules_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return top - 1;
+};
+exports.getTopConditionalFormatPriority = getTopConditionalFormatPriority;
+/** A new rule with its `priority` set to the top of `rules`, unless it already carries one. */
+var withTopConditionalFormatPriority = function (rule, rules) {
+    return typeof rule.priority === "number"
+        ? rule
+        : tslib_1.__assign(tslib_1.__assign({}, rule), { priority: (0, exports.getTopConditionalFormatPriority)(rules) });
+};
+exports.withTopConditionalFormatPriority = withTopConditionalFormatPriority;
+/**
+ * Move one rule up (`-1`) or down (`+1`) among `scope` (the rules the Rules Manager is showing —
+ * "Show formatting rules for" may hide some), returning the `priority` updates that realise the new
+ * order: every rule of the workbook renumbered 1..N in its new precedence order, keeping only the
+ * rules whose priority changes. Empty when the move is a no-op (first rule up, last rule down).
+ */
+var planConditionalFormatMove = function (rules, ruleId, direction, scope) {
+    if (scope === void 0) { scope = rules; }
+    var ordered = (0, exports.sortConditionalFormatRules)(rules);
+    var scopeIds = new Set(scope.map(function (rule) { return rule.id; }));
+    var visible = ordered.filter(function (rule) { return scopeIds.has(rule.id); });
+    var at = visible.findIndex(function (rule) { return rule.id === ruleId; });
+    var neighbour = visible[at + direction];
+    if (at === -1 || !neighbour) {
+        return [];
+    }
+    var from = ordered.indexOf(visible[at]);
+    var to = ordered.indexOf(neighbour);
+    var next = tslib_1.__spreadArray([], tslib_1.__read(ordered), false);
+    next[from] = neighbour;
+    next[to] = visible[at];
+    return (0, exports.planConditionalFormatOrder)(next);
+};
+exports.planConditionalFormatMove = planConditionalFormatMove;
+/** `priority` updates that make `ordered` the precedence order (1..N), changed rules only. */
+var planConditionalFormatOrder = function (ordered) {
+    return ordered.flatMap(function (rule, index) {
+        return rule.priority === index + 1 ? [] : [{ rule: rule, priority: index + 1 }];
+    });
+};
+exports.planConditionalFormatOrder = planConditionalFormatOrder;

package/dist/cjs/api/heatmap.d.ts

@@ -1,4 +1,10 @@
 import type { SpreadsheetTheme } from "../components/canvas-grid/typings";
 import type { GradientRule } from "../types";
-export declare const getGradientColors: (values: (number | undefined)[][][], gradientRule: GradientRule, theme: SpreadsheetTheme) => (string | undefined)[][][];
+import type { CfRangeStats } from "./cf-overlays";
+/**
+ * `population` — the rule's full-range statistics when `values` is only the
+ * visible slice of a windowed rule; min / mid / max resolve over it instead
+ * of the slice.
+ */
+export declare const getGradientColors: (values: (number | undefined)[][][], gradientRule: GradientRule, theme: SpreadsheetTheme, population?: CfRangeStats) => (string | undefined)[][][];
 //# sourceMappingURL=heatmap.d.ts.map

package/dist/cjs/api/heatmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heatmap.d.ts","sourceRoot":"","sources":["../../../api/heatmap.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,EAClC,cAAc,YAAY,EAC1B,OAAO,gBAAgB,+BAgExB,CAAC"}
+{"version":3,"file":"heatmap.d.ts","sourceRoot":"","sources":["../../../api/heatmap.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,EAAE,EAAE,EAClC,cAAc,YAAY,EAC1B,OAAO,gBAAgB,EACvB,aAAa,YAAY,+BAoE1B,CAAC"}