@rowsncolumns/spreadsheet 10.6.0 → 10.6.4

package/dist/esm/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/esm/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/esm/api/cf-overlays.js

@@ -1,106 +1,203 @@
 // 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.
+import { getExtendedValueNumber } from "@rowsncolumns/utils";
+import { CF_ICON_SETS } from "./cf-icons";
 export const 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.
-export const 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"],
+const shapeColor = (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.
-export const resolveThreshold = (threshold, rangeMin, rangeMax) => {
-    const raw = threshold.value;
-    const num = typeof raw === "number" ? raw : Number(raw);
+/** The colour each icon is painted in — what text stand-ins use. */
+export const ICON_SET_COLORS = Object.fromEntries(Object.entries(CF_ICON_SETS).map(([family, shapes]) => [
+    family,
+    shapes.map(shapeColor),
+]));
+/** The percentiles / ranks a rule's thresholds resolve with. */
+export const buildCfRuleStatsRequest = (rule) => {
+    const percentiles = new Set();
+    const addPoint = (point) => {
+        if (point?.type !== "PERCENTILE")
+            return;
+        const 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(rule.dataBarRule?.minpoint);
+    addPoint(rule.dataBarRule?.maxpoint);
+    rule.iconSetRule?.thresholds.forEach(addPoint);
+    addPoint(rule.gradientRule?.minpoint);
+    addPoint(rule.gradientRule?.midpoint);
+    addPoint(rule.gradientRule?.maxpoint);
+    const ranks = [];
+    if (rule.topBottomRule) {
+        ranks.push({
+            k: rule.topBottomRule.rank,
+            top: rule.topBottomRule.type === "TOP",
+            percent: !!rule.topBottomRule.isPercent,
+        });
+    }
+    return { percentiles: [...percentiles], ranks };
+};
+/**
+ * Turn the engine's reply into {@link CfRangeStats} for the CF hook — what a
+ * windowed host returns from `getConditionalFormatRuleStats`.
+ */
+export const toCfRangeStats = (request, response) => {
+    if (!response)
+        return undefined;
+    const at = (list, i) => i >= 0 && list[i] != null ? list[i] : NaN;
+    return {
+        count: response.count,
+        min: response.min ?? NaN,
+        max: response.max ?? NaN,
+        mean: response.mean ?? undefined,
+        stdDev: response.stdDev ?? undefined,
+        percentile: (p) => at(response.percentiles, request.percentiles.indexOf(p)),
+        rankValue: (k, top, percent) => at(response.ranks, request.ranks.findIndex((r) => r.k === k && r.top === top && !!r.percent === !!percent)),
+    };
+};
+export const buildCfRangeStats = (values) => {
+    const sorted = values.slice().sort((a, b) => a - b);
+    return {
+        count: sorted.length,
+        min: sorted.length ? sorted[0] : NaN,
+        max: sorted.length ? sorted[sorted.length - 1] : NaN,
+        sorted,
+    };
+};
+/** Excel's PERCENTILE.INC over ascending values (`p` in 0..100). */
+export const percentileInc = (sorted, p) => {
+    if (!sorted.length || !Number.isFinite(p))
+        return NaN;
+    const k = (Math.max(0, Math.min(100, p)) / 100) * (sorted.length - 1);
+    const lower = Math.floor(k);
+    const upper = Math.ceil(k);
+    if (lower === upper)
+        return sorted[lower];
+    return sorted[lower] + (sorted[upper] - sorted[lower]) * (k - lower);
+};
+const numericValue = (raw) => 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.
+ */
+export const resolveCfThreshold = (threshold, stats, options = {}) => {
+    const 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;
-            const 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
+                ? 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;
+            const text = String(threshold.value ?? "").trim();
+            if (!text)
+                return NaN;
+            const literal = Number(text.replace(/^=/, ""));
+            if (text.replace(/^=/, "") !== "" && Number.isFinite(literal)) {
+                return literal;
+            }
+            const resolved = options.resolveFormula?.(text);
+            return typeof resolved === "number" && Number.isFinite(resolved)
+                ? resolved
+                : NaN;
+        }
         default:
             return NaN;
     }
 };
-// Pick the icon bucket index for a value given ordered thresholds.
-// thresholds: length = (iconCount - 1), ascending.
-export const pickIconBucket = (value, sortedThresholds) => {
-    let bucket = 0;
-    for (const t of sortedThresholds) {
+// 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.
+export const resolveThreshold = (threshold, rangeMin, rangeMax, sorted) => resolveCfThreshold(threshold, {
+    count: sorted?.length ?? 0,
+    min: rangeMin,
+    max: rangeMax,
+    sorted,
+});
+// 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.
+export const pickIconBucket = (value, thresholds, strict) => {
+    for (let i = thresholds.length - 1; i >= 0; i--) {
+        const t = thresholds[i];
         if (!Number.isFinite(t))
-            break;
-        if (value >= t)
-            bucket++;
-        else
-            break;
+            continue;
+        if (strict?.[i] ? value > t : value >= t)
+            return i + 1;
     }
-    return bucket;
+    return 0;
 };
 // Compute a 0..1 fill fraction for a data-bar cell value.
 // When `min >= max`, all cells in the range share the same value; return 1
@@ -116,3 +213,62 @@ export const computeDataBarFill = (value, min, max) => {
     const clamped = Math.max(min, Math.min(max, value));
     return (clamped - min) / (max - min);
 };
+/**
+ * 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 const isConditionalFormatNumberCell = (effectiveValue, cellFormat) => getExtendedValueNumber(effectiveValue) != null ||
+    !!cellFormat?.numberFormat?.type;
+/**
+ * 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 const averageBound = (values, above, stdDev) => {
+    const mean = values.reduce((sum, v) => sum + v, 0) / values.length;
+    if (!stdDev || stdDev <= 0 || values.length < 2)
+        return mean;
+    const variance = values.reduce((sum, v) => sum + (v - mean) ** 2, 0) / (values.length - 1);
+    const offset = stdDev * Math.sqrt(variance);
+    return above ? mean + offset : mean - offset;
+};
+/**
+ * Whether a CSS colour (`#rrggbb` / `rgb()`) is dark — relative luminance
+ * under 0.5. Unparseable colours count as light.
+ */
+export const isDarkCssColor = (color) => {
+    if (!color)
+        return false;
+    const hex = /^#?([0-9a-f]{6})/i.exec(color.trim());
+    const rgb = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/i.exec(color.trim());
+    let channels;
+    if (hex) {
+        const 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;
+    const [r, g, b] = channels.map((c) => {
+        const v = c / 255;
+        return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.5;
+};
+/** {@link averageBound} from full-range statistics (sorted values or the engine's mean / std dev). */
+export const averageBoundFromStats = (stats, above, stdDev) => {
+    if (stats.sorted) {
+        return stats.sorted.length
+            ? averageBound(stats.sorted, above, stdDev)
+            : undefined;
+    }
+    if (stats.mean == null || !stats.count)
+        return undefined;
+    const offset = stdDev && stdDev > 0 ? stdDev * (stats.stdDev ?? 0) : 0;
+    return above ? stats.mean + offset : stats.mean - offset;
+};

package/dist/esm/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/esm/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/esm/api/cf-priority.js

@@ -0,0 +1,61 @@
+/**
+ * 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 const sortConditionalFormatRules = (rules) => rules
+    .map((rule, index) => ({ rule, index }))
+    .sort((left, right) => {
+    const leftPriority = left.rule.priority ?? Number.POSITIVE_INFINITY;
+    const rightPriority = right.rule.priority ?? Number.POSITIVE_INFINITY;
+    if (leftPriority === rightPriority) {
+        return left.index - right.index;
+    }
+    return leftPriority - rightPriority;
+})
+    .map(({ rule }) => rule);
+/**
+ * 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 const getTopConditionalFormatPriority = (rules) => {
+    let top = 1;
+    for (const rule of rules) {
+        if (typeof rule.priority === "number" && Number.isFinite(rule.priority)) {
+            top = Math.min(top, rule.priority);
+        }
+    }
+    return top - 1;
+};
+/** A new rule with its `priority` set to the top of `rules`, unless it already carries one. */
+export const withTopConditionalFormatPriority = (rule, rules) => typeof rule.priority === "number"
+    ? rule
+    : { ...rule, priority: getTopConditionalFormatPriority(rules) };
+/**
+ * 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 const planConditionalFormatMove = (rules, ruleId, direction, scope = rules) => {
+    const ordered = sortConditionalFormatRules(rules);
+    const scopeIds = new Set(scope.map((rule) => rule.id));
+    const visible = ordered.filter((rule) => scopeIds.has(rule.id));
+    const at = visible.findIndex((rule) => rule.id === ruleId);
+    const neighbour = visible[at + direction];
+    if (at === -1 || !neighbour) {
+        return [];
+    }
+    const from = ordered.indexOf(visible[at]);
+    const to = ordered.indexOf(neighbour);
+    const next = [...ordered];
+    next[from] = neighbour;
+    next[to] = visible[at];
+    return planConditionalFormatOrder(next);
+};
+/** `priority` updates that make `ordered` the precedence order (1..N), changed rules only. */
+export const planConditionalFormatOrder = (ordered) => ordered.flatMap((rule, index) => rule.priority === index + 1 ? [] : [{ rule, priority: index + 1 }]);

package/dist/esm/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/esm/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"}

package/dist/esm/api/heatmap.js

@@ -1,9 +1,14 @@
 import { hexToRgb, isNil, rgbToHex } from "@rowsncolumns/utils";
 import { getStringifiedColor } from "../themes";
-export const getGradientColors = (values, gradientRule, theme) => {
+/**
+ * `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 const getGradientColors = (values, gradientRule, theme, population) => {
     const colors = [];
     const { minpoint, midpoint, maxpoint } = gradientRule;
-    const [minValue, midValue, maxValue] = getMinMidMax(values, gradientRule);
+    const [minValue, midValue, maxValue] = getMinMidMax(population?.sorted ? [[population.sorted]] : values, gradientRule, population?.sorted ? undefined : population);
     const range = maxValue - minValue || 1;
     const minColor = getStringifiedColor(minpoint?.color, theme);
     const midColor = getStringifiedColor(midpoint?.color, theme);
@@ -67,16 +72,20 @@ const interpolateColor = (color1, color2, ratio) => {
 const interpolate = (value1, value2, ratio) => {
     return value1 + (value2 - value1) * ratio;
 };
-const getMinMidMax = (values, { minpoint, midpoint, maxpoint }) => {
-    const flattenedValues = values
-        .flat(2)
-        .filter((value) => typeof value === "number" && Number.isFinite(value));
-    if (flattenedValues.length === 0) {
+const getMinMidMax = (values, { minpoint, midpoint, maxpoint }, 
+// Engine statistics without the sorted values (windowed hosts).
+stats) => {
+    const flattenedValues = stats
+        ? []
+        : values
+            .flat(2)
+            .filter((value) => typeof value === "number" && Number.isFinite(value));
+    if (stats ? !stats.count : flattenedValues.length === 0) {
         return [0, 0, 0];
     }
     const sortedValues = [...flattenedValues].sort((a, b) => a - b);
-    const dataMin = sortedValues[0];
-    const dataMax = sortedValues[sortedValues.length - 1];
+    const dataMin = stats ? stats.min : sortedValues[0];
+    const dataMax = stats ? stats.max : sortedValues[sortedValues.length - 1];
     const parseNumericInput = (value) => {
         if (typeof value === "number") {
             return Number.isFinite(value) ? value : undefined;
@@ -93,6 +102,12 @@ const getMinMidMax = (values, { minpoint, midpoint, maxpoint }) => {
         return undefined;
     };
     const getPercentileValue = (percent) => {
+        if (stats) {
+            const value = stats.percentile?.(percent);
+            return value !== undefined && Number.isFinite(value)
+                ? value
+                : dataMin + ((dataMax - dataMin) * percent) / 100;
+        }
         if (!sortedValues.length) {
             return dataMin;
         }

package/dist/esm/api/selections.d.ts

@@ -8,7 +8,7 @@ import type { SheetRange, TableView } from "../types";
  * @param isActiveCell
  * @param isSelection
  */
-export declare const getSelectionStrokeStyle: (formulaMode: boolean, isFill: boolean, isActiveCell: boolean, emptySelections: boolean) => "solid" | "dashed";
+export declare const getSelectionStrokeStyle: (formulaMode: boolean, isFill: boolean, isActiveCell: boolean, emptySelections: boolean) => "dashed" | "solid";
 export type SelectionStrokeOptions = {
     /** Border width of a range selection outside formula mode. Default `1`. */
     selectionStrokeWidth?: number;
@@ -37,7 +37,7 @@ export declare const getSelectionStrokeWidth: (formulaMode: boolean, isFill: boo
  * @param isFill
  * @returns
  */
-export declare const getSelectionFillOpacity: (formulaMode: boolean, isFill: boolean) => 0 | 1 | 0.2;
+export declare const getSelectionFillOpacity: (formulaMode: boolean, isFill: boolean) => 1 | 0 | 0.2;
 /**
  * Get background color of selection
  * @param formulaMode