@svgrid/enterprise 3.0.1 → 3.0.2

package/dist/sheet/conditional-formats.js

@@ -0,0 +1,316 @@
+/**
+ * Conditional formatting, Excel's: rules over cells that colour them by
+ * what they hold. Highlight Cells Rules (greater than, between, text that
+ * contains, duplicates), Top/Bottom Rules (top 10, above average), Data
+ * Bars, Color Scales and Icon Sets, each over rectangles that move with
+ * an insert or delete.
+ *
+ * Rules are evaluated over COMPUTED values (what a formula shows, not its
+ * text), which is why the model lives here beside the workbook rather than
+ * in the grid's own value-driven rules. The statistics a rule needs over
+ * its range (min, max, mean, rank, counts) are computed once per repaint by
+ * the shell and handed in, so a thousand cells cost one pass.
+ *
+ * Priority is array order, first rule first, as Excel's Manage Rules lists
+ * them: the first rule that decides a property wins it, and a rule with
+ * Stop If True stops the rules below it for the cells it matches.
+ */
+import { isError } from './ast.js';
+import { toText } from './coerce.js';
+import { rectContains, shiftRects, subtractRect, rectsIntersect } from './rects.js';
+// ---------------------------------------------------------------------------
+// Excel's palettes
+// ---------------------------------------------------------------------------
+/** The six "with" styles of Excel's Highlight Cells dialogs. */
+export const CF_PRESET_STYLES = [
+    { id: 'light-red', label: 'Light Red Fill with Dark Red Text', style: { fill: '#FFC7CE', color: '#9C0006' } },
+    { id: 'yellow', label: 'Yellow Fill with Dark Yellow Text', style: { fill: '#FFEB9C', color: '#9C5700' } },
+    { id: 'green', label: 'Green Fill with Dark Green Text', style: { fill: '#C6EFCE', color: '#006100' } },
+    { id: 'red-fill', label: 'Light Red Fill', style: { fill: '#FFC7CE' } },
+    { id: 'red-text', label: 'Red Text', style: { color: '#9C0006' } },
+];
+export const DATA_BAR_COLOR = '#638EC6';
+export const COLOR_SCALES = {
+    'green-yellow-red': ['#63BE7B', '#FFEB84', '#F8696B'],
+    'red-yellow-green': ['#F8696B', '#FFEB84', '#63BE7B'],
+    'green-white': ['#63BE7B', '#FCFCFF'],
+    'white-red': ['#FCFCFF', '#F8696B'],
+};
+let nextId = 1;
+export function cfId() {
+    nextId += 1;
+    return `cf${Date.now().toString(36)}${nextId}`;
+}
+// ---------------------------------------------------------------------------
+// Statistics
+// ---------------------------------------------------------------------------
+/**
+ * The numbers and the texts a rule's rectangles hold. One pass; the shell
+ * caches the result per rule until the next repaint.
+ */
+export function ruleStats(rule, valueAt, displayAt) {
+    const numbers = [];
+    const counts = new Map();
+    let sum = 0;
+    for (const [r1, c1, r2, c2] of rule.rects) {
+        for (let r = r1; r <= r2; r += 1) {
+            for (let c = c1; c <= c2; c += 1) {
+                const v = valueAt(r, c);
+                if (typeof v === 'number' && Number.isFinite(v)) {
+                    numbers.push(v);
+                    sum += v;
+                }
+                if (rule.kind === 'duplicates') {
+                    const shown = displayAt(r, c);
+                    if (shown !== '')
+                        counts.set(shown, (counts.get(shown) ?? 0) + 1);
+                }
+            }
+        }
+    }
+    numbers.sort((a, b) => a - b);
+    return {
+        sorted: numbers,
+        min: numbers[0] ?? 0,
+        max: numbers[numbers.length - 1] ?? 0,
+        mean: numbers.length ? sum / numbers.length : 0,
+        counts,
+    };
+}
+// ---------------------------------------------------------------------------
+// Evaluation
+// ---------------------------------------------------------------------------
+function numberOf(text, ctx) {
+    const v = ctx.evaluate(text);
+    if (isError(v) || typeof v === 'boolean')
+        return null;
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) ? n : null;
+}
+function textOf(text, ctx) {
+    const t = text.trim();
+    if (!t.startsWith('='))
+        return t;
+    const v = ctx.evaluate(t);
+    return isError(v) ? '' : toText(v);
+}
+function cellIs(value, operator, a, b) {
+    if (a === null)
+        return false;
+    switch (operator) {
+        case 'greater': return value > a;
+        case 'less': return value < a;
+        case 'greaterOrEqual': return value >= a;
+        case 'lessOrEqual': return value <= a;
+        case 'equal': return value === a;
+        case 'notEqual': return value !== a;
+        case 'between': return b !== null && value >= Math.min(a, b) && value <= Math.max(a, b);
+        case 'notBetween': return b !== null && (value < Math.min(a, b) || value > Math.max(a, b));
+    }
+}
+/** Whether a styling rule matches the cell. */
+function matches(rule, value, display, stats, ctx) {
+    switch (rule.kind) {
+        case 'cellIs': {
+            const isEquality = rule.operator === 'equal' || rule.operator === 'notEqual';
+            const a = numberOf(rule.value1, ctx);
+            if (typeof value === 'number' && (a !== null || !isEquality)) {
+                return cellIs(value, rule.operator, a, rule.value2 === undefined ? null : numberOf(rule.value2, ctx));
+            }
+            // Equal to / not equal to compare as text where either side is text,
+            // as Excel does: 5 is not equal to 'Paid', and 'paid' is equal to it.
+            if (!isEquality)
+                return false;
+            const same = display !== '' && display.toLowerCase() === textOf(rule.value1, ctx).toLowerCase();
+            return rule.operator === 'equal' ? same : display !== '' && !same;
+        }
+        case 'text': {
+            if (display === '')
+                return false;
+            const hay = display.toLowerCase();
+            const needle = textOf(rule.value, ctx).toLowerCase();
+            if (needle === '')
+                return false;
+            switch (rule.match) {
+                case 'contains': return hay.includes(needle);
+                case 'notContains': return !hay.includes(needle);
+                case 'beginsWith': return hay.startsWith(needle);
+                case 'endsWith': return hay.endsWith(needle);
+                default: return false;
+            }
+        }
+        case 'duplicates': {
+            if (display === '')
+                return false;
+            const n = stats.counts.get(display) ?? 0;
+            return rule.unique ? n === 1 : n > 1;
+        }
+        case 'topBottom': {
+            if (typeof value !== 'number' || !stats.sorted.length)
+                return false;
+            const count = rule.percent
+                ? Math.max(1, Math.round((stats.sorted.length * rule.rank) / 100))
+                : rule.rank;
+            if (count <= 0)
+                return false;
+            // The cut is the count-th value from the top (or bottom); ties keep
+            // every cell at that value in, as Excel's do.
+            const sorted = stats.sorted;
+            const cut = rule.top
+                ? sorted[Math.max(sorted.length - count, 0)]
+                : sorted[Math.min(count - 1, sorted.length - 1)];
+            return rule.top ? value >= cut : value <= cut;
+        }
+        case 'average': {
+            if (typeof value !== 'number' || !stats.sorted.length)
+                return false;
+            return rule.above ? value > stats.mean : value < stats.mean;
+        }
+        default:
+            return false;
+    }
+}
+/**
+ * A data bar's share of the cell, 0..1. Excel measures from zero when the
+ * range is non-negative (10, 20, 40 draw a quarter, a half and the whole
+ * width), so the smallest value keeps a bar; a range with negatives runs
+ * from its minimum instead, since there is no negative axis here.
+ */
+function barRatio(value, stats) {
+    const lo = Math.min(0, stats.min);
+    const hi = Math.max(0, stats.max);
+    if (hi === lo)
+        return 0;
+    return Math.min(1, Math.max(0, (value - lo) / (hi - lo)));
+}
+/** Where a number sits in a range, 0..1; 0.5 for a flat range. */
+function ratioOf(value, stats) {
+    if (stats.max === stats.min)
+        return 0.5;
+    return Math.min(1, Math.max(0, (value - stats.min) / (stats.max - stats.min)));
+}
+/** Linear interpolate two hex colours. */
+function lerp(a, b, t) {
+    const pa = parseHex(a);
+    const pb = parseHex(b);
+    if (!pa || !pb)
+        return a;
+    const k = Math.min(1, Math.max(0, t));
+    const ch = (i) => Math.round(pa[i] + (pb[i] - pa[i]) * k).toString(16).padStart(2, '0');
+    return `#${ch(0)}${ch(1)}${ch(2)}`;
+}
+function parseHex(hex) {
+    const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+/** The colour a scale gives a position 0..1. */
+export function scaleColor(colors, t) {
+    if (colors.length === 2)
+        return lerp(colors[0], colors[1], t);
+    return t <= 0.5 ? lerp(colors[0], colors[1], t * 2) : lerp(colors[1], colors[2], (t - 0.5) * 2);
+}
+/** Which of an icon set's three icons a position 0..1 gets: Excel's thirds. */
+export function iconIndex(t) {
+    return t >= 2 / 3 ? 0 : t >= 1 / 3 ? 1 : 2;
+}
+/**
+ * What the rules say about (r, c). Array order is priority; the first rule
+ * that decides a property (the fill, the text colour, the bar, the icon)
+ * keeps it; a matching rule with Stop If True ends the walk.
+ */
+export function evaluateCf(rules, r, c, value, display, statsFor, ctx) {
+    let out = null;
+    for (const rule of rules) {
+        if (!rule.rects.some((rect) => rectContains(rect, r, c)))
+            continue;
+        let hit = false;
+        if (rule.kind === 'dataBar') {
+            if (typeof value === 'number' && !(out?.dataBar)) {
+                const stats = statsFor(rule);
+                out = { ...(out ?? {}), dataBar: { ratio: barRatio(value, stats), color: rule.color } };
+                hit = true;
+            }
+        }
+        else if (rule.kind === 'colorScale') {
+            const current = out ?? {};
+            if (typeof value === 'number' && current.style?.fill === undefined) {
+                const stats = statsFor(rule);
+                out = { ...current, style: { ...(current.style ?? {}), fill: scaleColor(rule.colors, ratioOf(value, stats)) } };
+                hit = true;
+            }
+        }
+        else if (rule.kind === 'iconSet') {
+            if (typeof value === 'number' && !(out?.icon)) {
+                const stats = statsFor(rule);
+                out = { ...(out ?? {}), icon: { set: rule.set, index: iconIndex(ratioOf(value, stats)) } };
+                hit = true;
+            }
+        }
+        else if (hasStyle(rule) && matches(rule, value, display, statsFor(rule), ctx)) {
+            const style = { ...(out?.style ?? {}) };
+            const own = rule.style;
+            for (const key of Object.keys(own)) {
+                if (style[key] === undefined && own[key] !== undefined)
+                    style[key] = own[key];
+            }
+            out = { ...(out ?? {}), style };
+            hit = true;
+        }
+        if (hit && rule.stopIfTrue)
+            break;
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Bookkeeping
+// ---------------------------------------------------------------------------
+/** The rules after an insert or delete. */
+export function shiftCf(rules, edit) {
+    return shiftRects(rules, edit);
+}
+/** The rules with the rectangles cut out of them: Clear Rules from Selected Cells. */
+export function removeCf(rules, rects) {
+    const out = [];
+    for (const rule of rules) {
+        let kept = [...rule.rects];
+        for (const hole of rects)
+            kept = kept.flatMap((rect) => subtractRect(rect, hole));
+        if (kept.length)
+            out.push({ ...rule, rects: kept });
+    }
+    return out;
+}
+/** The rules touching any of the rectangles. */
+export function cfIn(rules, rects) {
+    return rules.filter((rule) => rule.rects.some((a) => rects.some((b) => rectsIntersect(a, b))));
+}
+const OPERATOR_WORDS = {
+    greater: 'greater than', less: 'less than', between: 'between', notBetween: 'not between',
+    equal: 'equal to', notEqual: 'not equal to', greaterOrEqual: 'greater than or equal to', lessOrEqual: 'less than or equal to',
+};
+const MATCH_WORDS = {
+    contains: 'contains', notContains: 'does not contain', beginsWith: 'begins with', endsWith: 'ends with',
+};
+/** A rule in words, the way Excel's Manage Rules lists it. */
+export function describeCf(rule) {
+    switch (rule.kind) {
+        case 'cellIs':
+            return rule.operator === 'between' || rule.operator === 'notBetween'
+                ? `Cell Value ${OPERATOR_WORDS[rule.operator]} ${rule.value1} and ${rule.value2 ?? ''}`
+                : `Cell Value ${OPERATOR_WORDS[rule.operator]} ${rule.value1}`;
+        case 'text': return `Cell Value ${MATCH_WORDS[rule.match]} '${rule.value}'`;
+        case 'duplicates': return rule.unique ? 'Unique Values' : 'Duplicate Values';
+        case 'topBottom': return `${rule.top ? 'Top' : 'Bottom'} ${rule.rank}${rule.percent ? '%' : ''}`;
+        case 'average': return rule.above ? 'Above Average' : 'Below Average';
+        case 'dataBar': return 'Data Bar';
+        case 'colorScale': return rule.colors.length === 3 ? 'Graded Color Scale' : 'Two-Color Scale';
+        case 'iconSet': return 'Icon Set';
+    }
+}
+/** Whether a rule carries a style the dialog can edit. */
+export function hasStyle(rule) {
+    return 'style' in rule;
+}

package/dist/sheet/deps.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Dependency graph, so a recalc costs what the edit actually affects.
+ *
+ * The demo engines call `computeSheet`, which resolves every cell on every
+ * keystroke. On a small budget sheet nobody notices; on demo 211's 360-row
+ * amortisation schedule, typing one digit in an input cell walks every cell in
+ * the sheet and re-parses every formula among them.
+ *
+ * This tracks which cells each formula reads, inverts that into "who reads
+ * me", and walks forward from an edit in topological order.
+ *
+ * Cycles are reported rather than thrown. A cycle is a normal thing to type on
+ * the way to something correct, and every cell in one shows #CYCLE! while the
+ * rest of the sheet keeps working.
+ */
+import { type Node } from './ast.js';
+export type CellKey = string;
+/**
+ * Cells are keyed "row col sheet", in that order deliberately.
+ *
+ * Row and column are numbers and contain no separator, so the first two fields
+ * are unambiguous and EVERYTHING after the second space is the sheet name.
+ * Putting the sheet first would let a name like `Price list` collide with a
+ * different cell, and a ':' or '!' separator has the same problem the moment
+ * someone names a sheet after a range.
+ */
+export declare function cellKey(sheet: string | null, row: number, col: number): CellKey;
+export declare function parseCellKey(key: CellKey): {
+    sheet: string | null;
+    row: number;
+    col: number;
+};
+/**
+ * Every cell a formula reads. A range contributes each cell inside it, which
+ * is why `lastRow` is needed: a whole-column reference has no upper bound of
+ * its own.
+ */
+export declare function precedentsOf(ast: Node, self: {
+    sheet: string | null;
+}, lastRow: (sheet: string | null) => number, 
+/**
+ * The reference behind a defined name. Without it a formula that reads
+ * `=Subtotal*Tax` records no precedents at all, so editing the cell behind
+ * `Tax` leaves the formula showing its old value until something else
+ * forces a recalculation.
+ */
+resolveName?: (name: string) => Node | null, depth?: number): CellKey[];
+export type DependencyGraph = {
+    /** Record (or clear, with null) what one cell reads. */
+    setPrecedents(cell: CellKey, precedents: ReadonlyArray<CellKey> | null): void;
+    /** Cells that must recompute after `changed`, ordered so every cell comes
+     *  after everything it reads. Excludes the changed cells themselves. */
+    dirtyFrom(changed: ReadonlyArray<CellKey>): CellKey[];
+    /** Every cell taking part in a dependency cycle. */
+    cycles(): CellKey[];
+    /** Direct readers of a cell. */
+    dependentsOf(cell: CellKey): CellKey[];
+    clear(): void;
+};
+export declare function createDependencyGraph(): DependencyGraph;

package/dist/sheet/deps.js

@@ -0,0 +1,199 @@
+/**
+ * Dependency graph, so a recalc costs what the edit actually affects.
+ *
+ * The demo engines call `computeSheet`, which resolves every cell on every
+ * keystroke. On a small budget sheet nobody notices; on demo 211's 360-row
+ * amortisation schedule, typing one digit in an input cell walks every cell in
+ * the sheet and re-parses every formula among them.
+ *
+ * This tracks which cells each formula reads, inverts that into "who reads
+ * me", and walks forward from an edit in topological order.
+ *
+ * Cycles are reported rather than thrown. A cycle is a normal thing to type on
+ * the way to something correct, and every cell in one shows #CYCLE! while the
+ * rest of the sheet keeps working.
+ */
+import { visit } from './ast.js';
+/**
+ * Cells are keyed "row col sheet", in that order deliberately.
+ *
+ * Row and column are numbers and contain no separator, so the first two fields
+ * are unambiguous and EVERYTHING after the second space is the sheet name.
+ * Putting the sheet first would let a name like `Price list` collide with a
+ * different cell, and a ':' or '!' separator has the same problem the moment
+ * someone names a sheet after a range.
+ */
+export function cellKey(sheet, row, col) {
+    return `${row} ${col} ${sheet ?? ''}`;
+}
+export function parseCellKey(key) {
+    const firstGap = key.indexOf(' ');
+    const secondGap = key.indexOf(' ', firstGap + 1);
+    const sheet = key.slice(secondGap + 1);
+    return {
+        sheet: sheet === '' ? null : sheet,
+        row: Number(key.slice(0, firstGap)),
+        col: Number(key.slice(firstGap + 1, secondGap)),
+    };
+}
+/**
+ * Every cell a formula reads. A range contributes each cell inside it, which
+ * is why `lastRow` is needed: a whole-column reference has no upper bound of
+ * its own.
+ */
+export function precedentsOf(ast, self, lastRow, 
+/**
+ * The reference behind a defined name. Without it a formula that reads
+ * `=Subtotal*Tax` records no precedents at all, so editing the cell behind
+ * `Tax` leaves the formula showing its old value until something else
+ * forces a recalculation.
+ */
+resolveName, depth = 0) {
+    const out = [];
+    visit(ast, (n) => {
+        if (n.k === 'name') {
+            // A name defined as another name is followed; a circular chain is cut
+            // after a few hops rather than recursing forever.
+            const target = depth < 8 ? resolveName?.(n.name) : null;
+            if (target)
+                out.push(...precedentsOf(target, self, lastRow, resolveName, depth + 1));
+            return;
+        }
+        if (n.k === 'ref' && n.ref.row !== null) {
+            out.push(cellKey(n.ref.sheet ?? self.sheet, n.ref.row, n.ref.col));
+            return;
+        }
+        if (n.k === 'range') {
+            const sheet = n.from.sheet ?? n.to.sheet ?? self.sheet;
+            const r1 = Math.min(n.from.row ?? 0, n.to.row ?? n.from.row ?? 0);
+            const r2 = n.to.row === null || n.from.row === null
+                ? lastRow(sheet)
+                : Math.max(n.from.row, n.to.row);
+            const c1 = Math.min(n.from.col, n.to.col);
+            const c2 = Math.max(n.from.col, n.to.col);
+            for (let r = r1; r <= r2; r += 1) {
+                for (let c = c1; c <= c2; c += 1)
+                    out.push(cellKey(sheet, r, c));
+            }
+        }
+    });
+    return out;
+}
+export function createDependencyGraph() {
+    /** cell -> what it reads. */
+    const precedents = new Map();
+    /** cell -> who reads it. The index that makes dirtyFrom cheap. */
+    const dependents = new Map();
+    function unlink(cell) {
+        const old = precedents.get(cell);
+        if (!old)
+            return;
+        for (const p of old) {
+            const set = dependents.get(p);
+            if (!set)
+                continue;
+            set.delete(cell);
+            if (set.size === 0)
+                dependents.delete(p);
+        }
+        precedents.delete(cell);
+    }
+    return {
+        setPrecedents(cell, next) {
+            unlink(cell);
+            if (!next || next.length === 0)
+                return;
+            // A self-reference is a cycle of one; it is kept so `cycles()` sees it.
+            const set = new Set(next);
+            precedents.set(cell, set);
+            for (const p of set) {
+                let back = dependents.get(p);
+                if (!back) {
+                    back = new Set();
+                    dependents.set(p, back);
+                }
+                back.add(cell);
+            }
+        },
+        dirtyFrom(changed) {
+            // Collect everything reachable downstream, then order it so a cell only
+            // recomputes once its own inputs have. Kahn's algorithm over that
+            // subgraph, not over the whole sheet.
+            const affected = new Set();
+            const stack = [...changed];
+            while (stack.length) {
+                const cur = stack.pop();
+                for (const d of dependents.get(cur) ?? []) {
+                    if (affected.has(d))
+                        continue;
+                    affected.add(d);
+                    stack.push(d);
+                }
+            }
+            if (affected.size === 0)
+                return [];
+            const indegree = new Map();
+            for (const cell of affected) {
+                let n = 0;
+                for (const p of precedents.get(cell) ?? [])
+                    if (affected.has(p))
+                        n += 1;
+                indegree.set(cell, n);
+            }
+            const ready = [...affected].filter((c) => (indegree.get(c) ?? 0) === 0);
+            const order = [];
+            const placed = new Set();
+            while (ready.length) {
+                const cur = ready.shift();
+                order.push(cur);
+                placed.add(cur);
+                for (const d of dependents.get(cur) ?? []) {
+                    if (!affected.has(d))
+                        continue;
+                    const n = (indegree.get(d) ?? 0) - 1;
+                    indegree.set(d, n);
+                    if (n === 0)
+                        ready.push(d);
+                }
+            }
+            // Anything left never reached indegree zero, so it sits in a cycle.
+            // Append it rather than dropping it: those cells still need evaluating
+            // so they can report #CYCLE! instead of keeping a stale value.
+            for (const cell of affected)
+                if (!placed.has(cell))
+                    order.push(cell);
+            return order;
+        },
+        cycles() {
+            // A cell is in a cycle when it can reach itself through its precedents.
+            const out = [];
+            for (const start of precedents.keys()) {
+                const seen = new Set();
+                const stack = [...(precedents.get(start) ?? [])];
+                let found = false;
+                while (stack.length) {
+                    const cur = stack.pop();
+                    if (cur === start) {
+                        found = true;
+                        break;
+                    }
+                    if (seen.has(cur))
+                        continue;
+                    seen.add(cur);
+                    for (const p of precedents.get(cur) ?? [])
+                        stack.push(p);
+                }
+                if (found)
+                    out.push(start);
+            }
+            return out;
+        },
+        dependentsOf(cell) {
+            return [...(dependents.get(cell) ?? [])];
+        },
+        clear() {
+            precedents.clear();
+            dependents.clear();
+        },
+    };
+}