@rowsncolumns/spreadsheet 10.5.17 → 10.6.4

package/dist/esm/api/cf-icons.js

@@ -0,0 +1,306 @@
+// Conditional-format icon sets drawn as small vector icons on the canvas.
+//
+// Excel's 20 icon sets (https://support.microsoft.com/office/
+// use-data-bars-color-scales-and-icon-sets-to-highlight-data-
+// f118d0b6-f19e-4ca2-8c9d-e4eac0b3b0f1, "Icon sets"). Each set lists its
+// icons in OOXML `iconId` order — index 0 is the icon for the LOWEST bucket —
+// so `iconId` matches what `<iconFilter>` / `<x14:cfIcon>` store. Each icon
+// is described once in a 16 × 16 design box and painted with plain canvas
+// paths, so it scales with zoom and needs no font or image asset.
+const RED = "#E5383B";
+const YELLOW = "#F2C12E";
+const GREEN = "#2BA84A";
+const GRAY = "#7F7F7F";
+const BLACK = "#262626";
+const PINK = "#F4A6A6";
+const DARK_GRAY = "#8C8C8C";
+const GOLD = "#F5B800";
+const BLUE = "#2F6EBA";
+const EMPTY = "#D9D9D9";
+const UP = 0;
+const UP_RIGHT = 45;
+const RIGHT = 90;
+const DOWN_RIGHT = 135;
+const DOWN = 180;
+const arrow = (angle, color) => ({
+    kind: "arrow",
+    angle,
+    color,
+});
+const circle = (color) => ({ kind: "circle", color });
+/** Every icon set, lowest bucket first (OOXML `iconId` order). */
+export const CF_ICON_SETS = {
+    "3Arrows": [arrow(DOWN, RED), arrow(RIGHT, YELLOW), arrow(UP, GREEN)],
+    "3ArrowsGray": [arrow(DOWN, GRAY), arrow(RIGHT, GRAY), arrow(UP, GRAY)],
+    "3Flags": [
+        { kind: "flag", color: RED },
+        { kind: "flag", color: YELLOW },
+        { kind: "flag", color: GREEN },
+    ],
+    "3TrafficLights1": [circle(RED), circle(YELLOW), circle(GREEN)],
+    "3TrafficLights2": [
+        { kind: "rimmedCircle", color: RED },
+        { kind: "rimmedCircle", color: YELLOW },
+        { kind: "rimmedCircle", color: GREEN },
+    ],
+    "3Signs": [
+        { kind: "diamond", color: RED },
+        { kind: "triangleUp", color: YELLOW },
+        circle(GREEN),
+    ],
+    "3Symbols": [
+        { kind: "symbol", glyph: "cross", color: RED },
+        { kind: "symbol", glyph: "exclamation", color: YELLOW },
+        { kind: "symbol", glyph: "check", color: GREEN },
+    ],
+    "3Symbols2": [
+        { kind: "symbolPlain", glyph: "cross", color: RED },
+        { kind: "symbolPlain", glyph: "exclamation", color: YELLOW },
+        { kind: "symbolPlain", glyph: "check", color: GREEN },
+    ],
+    "3Stars": [
+        { kind: "star", fill: 0 },
+        { kind: "star", fill: 0.5 },
+        { kind: "star", fill: 1 },
+    ],
+    "3Triangles": [
+        { kind: "triangleDown", color: RED },
+        { kind: "dash", color: YELLOW },
+        { kind: "triangleUp", color: GREEN },
+    ],
+    "4Arrows": [
+        arrow(DOWN, RED),
+        arrow(DOWN_RIGHT, YELLOW),
+        arrow(UP_RIGHT, YELLOW),
+        arrow(UP, GREEN),
+    ],
+    "4ArrowsGray": [
+        arrow(DOWN, GRAY),
+        arrow(DOWN_RIGHT, GRAY),
+        arrow(UP_RIGHT, GRAY),
+        arrow(UP, GRAY),
+    ],
+    "4RedToBlack": [circle(BLACK), circle(DARK_GRAY), circle(PINK), circle(RED)],
+    "4Rating": [1, 2, 3, 4].map((filled) => ({ kind: "rating", filled })),
+    "4TrafficLights": [circle(BLACK), circle(RED), circle(YELLOW), circle(GREEN)],
+    "5Arrows": [
+        arrow(DOWN, RED),
+        arrow(DOWN_RIGHT, YELLOW),
+        arrow(RIGHT, YELLOW),
+        arrow(UP_RIGHT, YELLOW),
+        arrow(UP, GREEN),
+    ],
+    "5ArrowsGray": [
+        arrow(DOWN, GRAY),
+        arrow(DOWN_RIGHT, GRAY),
+        arrow(RIGHT, GRAY),
+        arrow(UP_RIGHT, GRAY),
+        arrow(UP, GRAY),
+    ],
+    "5Rating": [0, 1, 2, 3, 4].map((filled) => ({ kind: "rating", filled })),
+    "5Quarters": [0, 1, 2, 3, 4].map((filled) => ({ kind: "quarters", filled })),
+    "5Boxes": [0, 1, 2, 3, 4].map((filled) => ({ kind: "boxes", filled })),
+};
+/** Families Excel only stores in the x14 extension (no Excel 2007 equivalent). */
+export const X14_ONLY_ICON_SETS = new Set([
+    "3Stars",
+    "3Triangles",
+    "5Boxes",
+]);
+export const getCfIcon = (iconSet, iconId) => iconSet && iconId != null
+    ? CF_ICON_SETS[iconSet]?.[iconId]
+    : undefined;
+const ARROW_POINTS = [
+    [8, 1],
+    [15, 8],
+    [11, 8],
+    [11, 15],
+    [5, 15],
+    [5, 8],
+    [1, 8],
+];
+const STAR_POINTS = Array.from({ length: 10 }, (_, i) => {
+    const radius = i % 2 === 0 ? 7.5 : 3.2;
+    const angle = -Math.PI / 2 + (i * Math.PI) / 5;
+    return [8 + radius * Math.cos(angle), 8.6 + radius * Math.sin(angle)];
+});
+/**
+ * Paint `icon` into the square at (`x`, `y`) with side `size` (local canvas
+ * coordinates).
+ */
+export const paintCfIcon = (ctx, icon, x, y, size) => {
+    const k = size / 16;
+    const px = (u) => x + u * k;
+    const py = (v) => y + v * k;
+    const polygon = (points) => {
+        ctx.beginPath();
+        points.forEach(([u, v], i) => i === 0 ? ctx.moveTo(px(u), py(v)) : ctx.lineTo(px(u), py(v)));
+        ctx.closePath();
+    };
+    const fillWith = (color) => {
+        ctx.setAttr("fillStyle", color);
+        ctx.fill();
+    };
+    const strokeWith = (color, width) => {
+        ctx.setAttr("strokeStyle", color);
+        ctx.setAttr("lineWidth", width * k);
+        ctx.setAttr("lineCap", "round");
+        ctx.setAttr("lineJoin", "round");
+        ctx.stroke();
+    };
+    const disc = (radius) => {
+        ctx.beginPath();
+        ctx.arc(px(8), py(8), radius * k, 0, Math.PI * 2);
+        ctx.closePath();
+    };
+    const glyph = (kind, color, width) => {
+        ctx.beginPath();
+        if (kind === "check") {
+            ctx.moveTo(px(4.5), py(8.5));
+            ctx.lineTo(px(7), py(11));
+            ctx.lineTo(px(11.5), py(5));
+        }
+        else if (kind === "cross") {
+            ctx.moveTo(px(5), py(5));
+            ctx.lineTo(px(11), py(11));
+            ctx.moveTo(px(11), py(5));
+            ctx.lineTo(px(5), py(11));
+        }
+        else {
+            ctx.moveTo(px(8), py(3.5));
+            ctx.lineTo(px(8), py(9));
+            ctx.moveTo(px(8), py(12));
+            ctx.lineTo(px(8), py(12.2));
+        }
+        strokeWith(color, width);
+    };
+    switch (icon.kind) {
+        case "arrow": {
+            const rad = (icon.angle * Math.PI) / 180;
+            const cos = Math.cos(rad);
+            const sin = Math.sin(rad);
+            polygon(ARROW_POINTS.map(([u, v]) => [
+                8 + (u - 8) * cos - (v - 8) * sin,
+                8 + (u - 8) * sin + (v - 8) * cos,
+            ]));
+            fillWith(icon.color);
+            return;
+        }
+        case "circle":
+            disc(7);
+            fillWith(icon.color);
+            return;
+        case "rimmedCircle":
+            ctx.beginPath();
+            ctx.rect(px(0.5), py(0.5), 15 * k, 15 * k);
+            ctx.closePath();
+            fillWith(BLACK);
+            disc(5.5);
+            fillWith(icon.color);
+            return;
+        case "flag":
+            ctx.beginPath();
+            ctx.rect(px(3), py(1), 1.5 * k, 14 * k);
+            ctx.closePath();
+            fillWith(BLACK);
+            polygon([
+                [4.5, 1.5],
+                [14, 5.25],
+                [4.5, 9],
+            ]);
+            fillWith(icon.color);
+            return;
+        case "diamond":
+            polygon([
+                [8, 1],
+                [15, 8],
+                [8, 15],
+                [1, 8],
+            ]);
+            fillWith(icon.color);
+            return;
+        case "triangleUp":
+            polygon([
+                [8, 2],
+                [15, 14],
+                [1, 14],
+            ]);
+            fillWith(icon.color);
+            return;
+        case "triangleDown":
+            polygon([
+                [1, 2],
+                [15, 2],
+                [8, 14],
+            ]);
+            fillWith(icon.color);
+            return;
+        case "dash":
+            ctx.beginPath();
+            ctx.rect(px(2), py(6), 12 * k, 4 * k);
+            ctx.closePath();
+            fillWith(icon.color);
+            return;
+        case "symbol":
+            disc(7.5);
+            fillWith(icon.color);
+            glyph(icon.glyph, "#FFFFFF", 2);
+            return;
+        case "symbolPlain":
+            glyph(icon.glyph, icon.color, 2.6);
+            return;
+        case "star":
+            if (icon.fill > 0) {
+                ctx.save();
+                if (icon.fill < 1) {
+                    ctx.beginPath();
+                    ctx.rect(px(0), py(0), 8 * k, 16 * k);
+                    ctx.clip();
+                }
+                polygon(STAR_POINTS);
+                fillWith(GOLD);
+                ctx.restore();
+            }
+            polygon(STAR_POINTS);
+            strokeWith(GOLD, 1);
+            return;
+        case "rating":
+            for (let bar = 0; bar < 4; bar++) {
+                const height = 4 + bar * 3.5;
+                ctx.beginPath();
+                ctx.rect(px(1 + bar * 3.75), py(15 - height), 2.75 * k, height * k);
+                ctx.closePath();
+                fillWith(bar < icon.filled ? BLUE : EMPTY);
+            }
+            return;
+        case "quarters":
+            disc(7);
+            fillWith("#FFFFFF");
+            if (icon.filled > 0) {
+                ctx.beginPath();
+                ctx.moveTo(px(8), py(8));
+                ctx.arc(px(8), py(8), 7 * k, -Math.PI / 2, -Math.PI / 2 + (icon.filled / 4) * Math.PI * 2);
+                ctx.closePath();
+                fillWith(BLACK);
+            }
+            disc(7);
+            strokeWith(BLACK, 1);
+            return;
+        case "boxes": {
+            // Quadrants fill clockwise from the top-left.
+            const cells = [
+                [1.5, 1.5],
+                [8.5, 1.5],
+                [8.5, 8.5],
+                [1.5, 8.5],
+            ];
+            cells.forEach(([u, v], i) => {
+                ctx.beginPath();
+                ctx.rect(px(u), py(v), 6 * k, 6 * k);
+                ctx.closePath();
+                fillWith(i < icon.filled ? BLUE : EMPTY);
+            });
+            return;
+        }
+    }
+};

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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"}