@svgrid/enterprise 3.0.0 → 3.0.2

package/dist/sheet/autocomplete.js

@@ -0,0 +1,162 @@
+/**
+ * Formula-bar autocomplete, kept out of the component so the interesting part
+ * is testable without mounting anything.
+ *
+ * The job is narrow: given the text in the bar and where the caret is, work out
+ * whether the user is partway through typing a function name, and if so which
+ * ones match. Everything else (arrow keys, accepting a suggestion) is a list
+ * with an index, which the component owns.
+ */
+import { FUNCTIONS } from './functions.js';
+const NAMES = Object.keys(FUNCTIONS).sort();
+/** Signature hints, for the ones whose argument order is not obvious. */
+export const SIGNATURES = {
+    VLOOKUP: 'VLOOKUP(lookup, table, colIndex)',
+    HLOOKUP: 'HLOOKUP(lookup, table, rowIndex)',
+    XLOOKUP: 'XLOOKUP(lookup, haystack, results, [ifMissing])',
+    INDEX: 'INDEX(range, row, [col])',
+    MATCH: 'MATCH(lookup, range, [mode])',
+    SUMIF: 'SUMIF(range, criterion, [sumRange])',
+    SUMIFS: 'SUMIFS(sumRange, range, criterion, ...)',
+    COUNTIF: 'COUNTIF(range, criterion)',
+    COUNTIFS: 'COUNTIFS(range, criterion, ...)',
+    AVERAGEIF: 'AVERAGEIF(range, criterion, [avgRange])',
+    IF: 'IF(condition, then, else)',
+    IFS: 'IFS(condition, value, ...)',
+    IFERROR: 'IFERROR(value, fallback)',
+    SWITCH: 'SWITCH(subject, case, value, ..., [default])',
+    ROUND: 'ROUND(number, digits)',
+    TEXT: 'TEXT(number, pattern)',
+    TEXTJOIN: 'TEXTJOIN(separator, skipEmpty, ...)',
+    SUBSTITUTE: 'SUBSTITUTE(text, find, replace)',
+    MID: 'MID(text, start, length)',
+    DATE: 'DATE(year, month, day)',
+    EOMONTH: 'EOMONTH(date, months)',
+};
+/**
+ * The word being typed immediately before the caret, if it could be a function
+ * name. Returns null when the caret is not in a formula, or sits somewhere a
+ * function name cannot start (inside a string, or right after a reference).
+ */
+export function partialAt(text, caret) {
+    if (!text.startsWith('='))
+        return null;
+    const upto = text.slice(0, caret);
+    // Inside a string literal there is nothing to suggest. Count unescaped
+    // quotes: an odd number means the caret is inside one.
+    let quotes = 0;
+    for (let i = 0; i < upto.length; i += 1) {
+        if (upto[i] === '"') {
+            if (upto[i + 1] === '"') {
+                i += 1;
+                continue;
+            }
+            quotes += 1;
+        }
+    }
+    if (quotes % 2 === 1)
+        return null;
+    const m = /([A-Za-z][A-Za-z0-9.]*)$/.exec(upto);
+    if (!m)
+        return null;
+    const word = m[1];
+    const start = caret - word.length;
+    // A word followed by digits is a cell reference being typed, not a function.
+    if (/\d$/.test(word))
+        return null;
+    return { word, start };
+}
+/**
+ * Function names matching what is being typed.
+ *
+ * Prefix matches first, then anything merely containing the text, so typing
+ * "look" still finds VLOOKUP. Within each group, SHORTER names rank first:
+ * alphabetical order puts SUBSTITUTE above SUM for "SU", which is exactly
+ * backwards from what someone typing two letters wants.
+ */
+export function suggestFunctions(text, caret, limit = 8) {
+    const partial = partialAt(text, caret);
+    if (!partial || partial.word.length < 1)
+        return [];
+    const upper = partial.word.toUpperCase();
+    const prefix = [];
+    const contains = [];
+    for (const name of NAMES) {
+        if (name === upper)
+            continue;
+        if (name.startsWith(upper))
+            prefix.push(name);
+        else if (name.includes(upper))
+            contains.push(name);
+    }
+    const byCloseness = (a, b) => a.length - b.length || a.localeCompare(b);
+    return [...prefix.sort(byCloseness), ...contains.sort(byCloseness)]
+        .slice(0, limit)
+        .map((name) => ({ name, start: partial.start, end: caret }));
+}
+/** Splice an accepted suggestion in, leaving the caret inside the parens. */
+export function applySuggestion(text, suggestion) {
+    const before = text.slice(0, suggestion.start);
+    const after = text.slice(suggestion.end);
+    // Do not double up a parenthesis the user already typed.
+    const needsParen = !after.startsWith('(');
+    // Only the OPENING parenthesis, as Excel inserts it. Inserting the pair
+    // put the caret between them, and everyone who then typed the arguments
+    // finished with a ")" of their own and got =SUM(A1:A3)) and #PARSE!.
+    // The closing one is supplied at commit by `balanceParens` when it is
+    // still missing, which is what Excel does too.
+    const inserted = needsParen ? `${suggestion.name}(` : suggestion.name;
+    return {
+        text: before + inserted + after,
+        caret: before.length + inserted.length,
+    };
+}
+/**
+ * Close the parentheses a formula left open, the way Excel corrects
+ * "=SUM(A1:A3" to "=SUM(A1:A3)" when it is entered. Quoted text is skipped,
+ * so a ")" inside a string neither closes nor needs closing. Text that is
+ * not a formula, or has more closers than openers, is returned as it is:
+ * that one is an error the engine should report, not paper over.
+ */
+export function balanceParens(text) {
+    if (!text.startsWith('='))
+        return text;
+    let depth = 0;
+    let inString = false;
+    for (const ch of text) {
+        if (ch === '"')
+            inString = !inString;
+        else if (!inString && ch === '(')
+            depth += 1;
+        else if (!inString && ch === ')')
+            depth -= 1;
+    }
+    return depth > 0 ? text + ')'.repeat(depth) : text;
+}
+/** The signature hint for whatever call the caret is inside, if any. */
+export function signatureAt(text, caret) {
+    if (!text.startsWith('='))
+        return null;
+    const upto = text.slice(0, caret);
+    // Walk back looking for an unclosed '(' and read the name before it.
+    let depth = 0;
+    for (let i = upto.length - 1; i >= 0; i -= 1) {
+        const ch = upto[i];
+        if (ch === ')') {
+            depth += 1;
+            continue;
+        }
+        if (ch === '(') {
+            if (depth > 0) {
+                depth -= 1;
+                continue;
+            }
+            const name = /([A-Za-z][A-Za-z0-9.]*)$/.exec(upto.slice(0, i))?.[1];
+            if (!name)
+                return null;
+            const upper = name.toUpperCase();
+            return SIGNATURES[upper] ?? (upper in FUNCTIONS ? `${upper}(...)` : null);
+        }
+    }
+    return null;
+}

package/dist/sheet/coerce.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Value coercions, shared by the evaluator and the function table.
+ *
+ * Excel's rules, not JavaScript's. The differences that matter:
+ *   - An empty cell is 0 in arithmetic but is NOT counted by COUNT or averaged
+ *     by AVERAGE, so "coerce to number" and "is a number" are separate tests.
+ *   - Text that does not parse as a number is `#VALUE!`, not NaN. Returning NaN
+ *     would let a bad cell poison a total silently.
+ *   - Text comparison is case-insensitive: `="a"="A"` is TRUE.
+ *   - Booleans are 1 and 0 in arithmetic but are skipped by numeric aggregates.
+ */
+import { type CellValue } from './ast.js';
+export declare function toNumber(v: CellValue): number;
+export declare function toBool(v: CellValue): boolean;
+export declare function toText(v: CellValue): string;
+/** Excel's `=` between two values. Text compares case-insensitively; a number
+ *  never equals the text that looks like it. */
+export declare function looseEquals(a: CellValue, b: CellValue): boolean;
+/** Ordering for `<` and friends. Excel orders number < text < boolean. */
+export declare function compare(a: CellValue, b: CellValue): number;
+/** The numeric members of a flattened argument list. Blanks, text and booleans
+ *  are skipped, which is what makes AVERAGE of a column with a header work. */
+export declare function numericOnly(values: ReadonlyArray<CellValue>): number[];
+/** Is this cell empty for COUNTA / COUNTBLANK purposes. */
+export declare function isBlank(v: CellValue): boolean;
+/**
+ * An Excel criterion: a bare value matches by equality, a string starting with
+ * an operator compares (`">100"`, `"<>x"`). Used by SUMIF / COUNTIF / their
+ * plural forms, which all share this grammar.
+ */
+export declare function matchesCriterion(value: CellValue, criterion: CellValue): boolean;

package/dist/sheet/coerce.js

@@ -0,0 +1,122 @@
+/**
+ * Value coercions, shared by the evaluator and the function table.
+ *
+ * Excel's rules, not JavaScript's. The differences that matter:
+ *   - An empty cell is 0 in arithmetic but is NOT counted by COUNT or averaged
+ *     by AVERAGE, so "coerce to number" and "is a number" are separate tests.
+ *   - Text that does not parse as a number is `#VALUE!`, not NaN. Returning NaN
+ *     would let a bad cell poison a total silently.
+ *   - Text comparison is case-insensitive: `="a"="A"` is TRUE.
+ *   - Booleans are 1 and 0 in arithmetic but are skipped by numeric aggregates.
+ */
+import { FormulaError, isError } from './ast.js';
+export function toNumber(v) {
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'boolean')
+        return v ? 1 : 0;
+    if (typeof v === 'string') {
+        if (v.trim() === '')
+            return 0;
+        const n = Number(v);
+        if (Number.isFinite(n))
+            return n;
+        throw new FormulaError('#VALUE!');
+    }
+    if (isError(v))
+        throw new FormulaError(v.error);
+    return 0;
+}
+export function toBool(v) {
+    if (typeof v === 'boolean')
+        return v;
+    if (typeof v === 'number')
+        return v !== 0;
+    if (typeof v === 'string') {
+        const upper = v.trim().toUpperCase();
+        if (upper === 'TRUE')
+            return true;
+        if (upper === 'FALSE')
+            return false;
+        return v.length > 0;
+    }
+    if (isError(v))
+        throw new FormulaError(v.error);
+    return false;
+}
+export function toText(v) {
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'boolean')
+        return v ? 'TRUE' : 'FALSE';
+    if (typeof v === 'number')
+        return String(v);
+    if (isError(v))
+        throw new FormulaError(v.error);
+    return '';
+}
+/** Excel's `=` between two values. Text compares case-insensitively; a number
+ *  never equals the text that looks like it. */
+export function looseEquals(a, b) {
+    if (typeof a === 'number' && typeof b === 'number')
+        return a === b;
+    if (typeof a === 'string' && typeof b === 'string') {
+        return a.toLowerCase() === b.toLowerCase();
+    }
+    if (typeof a === 'boolean' && typeof b === 'boolean')
+        return a === b;
+    if (isError(a) || isError(b))
+        return false;
+    return false;
+}
+/** Ordering for `<` and friends. Excel orders number < text < boolean. */
+export function compare(a, b) {
+    if (typeof a === 'number' && typeof b === 'number')
+        return a < b ? -1 : a > b ? 1 : 0;
+    if (typeof a === 'string' && typeof b === 'string') {
+        const x = a.toLowerCase();
+        const y = b.toLowerCase();
+        return x < y ? -1 : x > y ? 1 : 0;
+    }
+    return toNumber(a) < toNumber(b) ? -1 : toNumber(a) > toNumber(b) ? 1 : 0;
+}
+/** The numeric members of a flattened argument list. Blanks, text and booleans
+ *  are skipped, which is what makes AVERAGE of a column with a header work. */
+export function numericOnly(values) {
+    const out = [];
+    for (const v of values) {
+        if (typeof v === 'number' && Number.isFinite(v))
+            out.push(v);
+    }
+    return out;
+}
+/** Is this cell empty for COUNTA / COUNTBLANK purposes. */
+export function isBlank(v) {
+    return v === '' || v === null || v === undefined;
+}
+/**
+ * An Excel criterion: a bare value matches by equality, a string starting with
+ * an operator compares (`">100"`, `"<>x"`). Used by SUMIF / COUNTIF / their
+ * plural forms, which all share this grammar.
+ */
+export function matchesCriterion(value, criterion) {
+    if (typeof criterion === 'string') {
+        const m = /^(<=|>=|<>|<|>|=)(.*)$/.exec(criterion.trim());
+        if (m) {
+            const opText = m[1];
+            const rest = m[2].trim();
+            const n = Number(rest);
+            const operand = rest !== '' && Number.isFinite(n) ? n : rest;
+            switch (opText) {
+                case '=': return looseEquals(value, operand);
+                case '<>': return !looseEquals(value, operand);
+                case '<': return compare(value, operand) < 0;
+                case '>': return compare(value, operand) > 0;
+                case '<=': return compare(value, operand) <= 0;
+                case '>=': return compare(value, operand) >= 0;
+                default: break;
+            }
+        }
+    }
+    return looseEquals(value, criterion);
+}

package/dist/sheet/commands.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The keyboard commands themselves, written against `GridCommandContext` so
+ * they stay testable without mounting a grid.
+ *
+ * Every one that writes more than one cell runs inside `cmd.batch()`, so the
+ * whole action is a single Ctrl+Z. That is the seam added in @svgrid/grid;
+ * without it a Ctrl+D down a hundred rows would take a hundred presses to undo
+ * and would evict the history behind it.
+ *
+ * Phase 1 fills VALUES. Excel also translates relative references as it fills,
+ * so `=A1*2` in the source row becomes `=A2*2` one row down; that needs the
+ * formula engine's AST and lands with it in phase 2. Until then a formula
+ * fills as literal text, which is wrong for formulas and right for everything
+ * else, and is why `fillDown` routes through one `translateForFill` hook
+ * rather than inlining the copy.
+ */
+import type { GridCommandContext } from '@svgrid/grid/shortcuts';
+import { type Rect } from './navigate.js';
+/**
+ * How a value copied from (srcRow, srcCol) to (dstRow, dstCol) is rewritten.
+ * Phase 1 is identity. Phase 2 swaps in the engine's `translateFormula`, which
+ * is why every fill path calls it rather than copying the value directly.
+ */
+export type FillTranslator = (value: unknown, delta: {
+    rows: number;
+    cols: number;
+}) => unknown;
+/** Install the formula-aware translator. The engine calls this in phase 2. */
+export declare function setFillTranslator(fn: FillTranslator | null): void;
+export declare function targetRect(cmd: GridCommandContext): Rect | null;
+/**
+ * Ctrl+D. Copies the TOP row of the selection into every row below it.
+ *
+ * Excel has a second behaviour here: with only one cell selected it fills from
+ * the cell directly above instead, which is what makes Ctrl+D useful while
+ * typing down a column. Both are implemented.
+ */
+export declare function fillDown(cmd: GridCommandContext): boolean;
+/** Ctrl+R. The same shape as fillDown, across instead of down. */
+export declare function fillRight(cmd: GridCommandContext): boolean;
+/** Write one value into every cell of the selection. Excel's Ctrl+Enter. */
+export declare function fillSelection(cmd: GridCommandContext, value: unknown): boolean;
+/** Ctrl+; and Ctrl+Shift+;. ISO rather than locale-formatted, because the
+ *  value goes into the data and a column's own `format` decides how it reads;
+ *  stamping a localised string would put display text in the model. */
+export declare function stampNow(kind: 'date' | 'time' | 'datetime', now?: Date): string;
+export declare function stampDate(cmd: GridCommandContext, kind: 'date' | 'time' | 'datetime', now?: Date): boolean;
+/**
+ * Ctrl+'. Copies the cell above VERBATIM - no reference translation, which is
+ * the whole point of the shortcut: it is how you get a copy of the formula
+ * above to edit, rather than one that has already shifted.
+ */
+export declare function copyFromAbove(cmd: GridCommandContext): boolean;
+/**
+ * Ctrl+Shift+". The VALUE of the cell above: what a formula there shows,
+ * not the formula, so a running total can be frozen as a number. With an
+ * engine attached the evaluated value is what goes in; without one there is
+ * nothing but the text, which is what Ctrl+' copies. An error above copies
+ * nothing.
+ */
+export declare function copyValueFromAbove(cmd: GridCommandContext): boolean;
+/**
+ * Alt+=. The range Excel guesses for a SUM anchored at the active cell: the
+ * run of numbers directly above, or directly to the left when there is nothing
+ * above. Returns null when neither direction has numbers to add.
+ */
+export declare function guessSumRange(cmd: GridCommandContext, isNumeric?: (value: unknown) => boolean): Rect | null;
+/**
+ * How to find out what a cell actually EVALUATES to.
+ *
+ * Cells hold raw text, so a cell containing `=SUM(A1:A3)` reads as the string
+ * "=SUM(A1:A3)" and `looksNumeric` says no. AutoSum under a column of
+ * subtotals then finds no run and declines, which is the opposite of what
+ * Excel does: there, a formula that produces a number IS a number.
+ *
+ * Optional. Without one, a sheet with no engine behind it behaves as before
+ * and only literal numbers count.
+ */
+export type SheetValueProbe = (row: number, col: number) => unknown;
+export declare function setSheetValueProbe(fn: SheetValueProbe | null): void;
+export declare function getSheetValueProbe(): SheetValueProbe | null;
+/**
+ * The numeric test AutoSum should use for the cell at (row, col): the
+ * evaluated value when an engine is attached, the raw text otherwise.
+ */
+export declare function numericAt(cmd: GridCommandContext, row: number, col: number): boolean;
+/** Default numeric test for AutoSum: a finite number, or a string that parses
+ *  as one. A blank is not a number, so a gap ends the run. */
+export declare function looksNumeric(value: unknown): boolean;

package/dist/sheet/commands.js

@@ -0,0 +1,230 @@
+import { isBlankValue } from './navigate.js';
+const identity = (value) => value;
+let translator = identity;
+/** Install the formula-aware translator. The engine calls this in phase 2. */
+export function setFillTranslator(fn) {
+    translator = fn ?? identity;
+}
+/** The rectangle a command should act on: the active range, or the active cell
+ *  alone when nothing is selected. Returns null when there is no active cell. */
+/**
+ * Whether a command may write a cell. `setCellValue` trusts its caller, so
+ * a fill over a protected sheet has to ask for itself and leave the locked
+ * cells as they are, the way the grid's own fill handle does.
+ */
+function writable(cmd, r, c) {
+    return cmd.canEdit?.(r, c) !== false;
+}
+export function targetRect(cmd) {
+    const last = cmd.ranges[cmd.ranges.length - 1];
+    if (last)
+        return last;
+    const active = cmd.activeCell;
+    if (!active)
+        return null;
+    return [active.rowIndex, active.colIndex, active.rowIndex, active.colIndex];
+}
+/**
+ * Ctrl+D. Copies the TOP row of the selection into every row below it.
+ *
+ * Excel has a second behaviour here: with only one cell selected it fills from
+ * the cell directly above instead, which is what makes Ctrl+D useful while
+ * typing down a column. Both are implemented.
+ */
+export function fillDown(cmd) {
+    const rect = targetRect(cmd);
+    if (!rect)
+        return false;
+    const [minRow, minCol, maxRow, maxCol] = rect;
+    if (minRow === maxRow) {
+        // Single row selected: pull from the row above.
+        if (minRow === 0)
+            return false;
+        return cmd.batch(() => {
+            for (let c = minCol; c <= maxCol; c += 1) {
+                if (!writable(cmd, minRow, c))
+                    continue;
+                const value = cmd.getCellValue(minRow - 1, c);
+                cmd.setCellValue(minRow, c, translator(value, { rows: 1, cols: 0 }));
+            }
+            return true;
+        });
+    }
+    return cmd.batch(() => {
+        for (let c = minCol; c <= maxCol; c += 1) {
+            const source = cmd.getCellValue(minRow, c);
+            for (let r = minRow + 1; r <= maxRow; r += 1) {
+                if (!writable(cmd, r, c))
+                    continue;
+                cmd.setCellValue(r, c, translator(source, { rows: r - minRow, cols: 0 }));
+            }
+        }
+        return true;
+    });
+}
+/** Ctrl+R. The same shape as fillDown, across instead of down. */
+export function fillRight(cmd) {
+    const rect = targetRect(cmd);
+    if (!rect)
+        return false;
+    const [minRow, minCol, maxRow, maxCol] = rect;
+    if (minCol === maxCol) {
+        if (minCol === 0)
+            return false;
+        return cmd.batch(() => {
+            for (let r = minRow; r <= maxRow; r += 1) {
+                if (!writable(cmd, r, minCol))
+                    continue;
+                const value = cmd.getCellValue(r, minCol - 1);
+                cmd.setCellValue(r, minCol, translator(value, { rows: 0, cols: 1 }));
+            }
+            return true;
+        });
+    }
+    return cmd.batch(() => {
+        for (let r = minRow; r <= maxRow; r += 1) {
+            const source = cmd.getCellValue(r, minCol);
+            for (let c = minCol + 1; c <= maxCol; c += 1) {
+                if (!writable(cmd, r, c))
+                    continue;
+                cmd.setCellValue(r, c, translator(source, { rows: 0, cols: c - minCol }));
+            }
+        }
+        return true;
+    });
+}
+/** Write one value into every cell of the selection. Excel's Ctrl+Enter. */
+export function fillSelection(cmd, value) {
+    const rect = targetRect(cmd);
+    if (!rect)
+        return false;
+    const [minRow, minCol, maxRow, maxCol] = rect;
+    return cmd.batch(() => {
+        for (let r = minRow; r <= maxRow; r += 1) {
+            for (let c = minCol; c <= maxCol; c += 1) {
+                if (writable(cmd, r, c))
+                    cmd.setCellValue(r, c, value);
+            }
+        }
+        return true;
+    });
+}
+/** Ctrl+; and Ctrl+Shift+;. ISO rather than locale-formatted, because the
+ *  value goes into the data and a column's own `format` decides how it reads;
+ *  stamping a localised string would put display text in the model. */
+export function stampNow(kind, now = new Date()) {
+    const pad = (n) => String(n).padStart(2, '0');
+    const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+    const time = `${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`;
+    if (kind === 'date')
+        return date;
+    if (kind === 'time')
+        return time;
+    return `${date} ${time}`;
+}
+export function stampDate(cmd, kind, now) {
+    return fillSelection(cmd, stampNow(kind, now));
+}
+/**
+ * Ctrl+'. Copies the cell above VERBATIM - no reference translation, which is
+ * the whole point of the shortcut: it is how you get a copy of the formula
+ * above to edit, rather than one that has already shifted.
+ */
+export function copyFromAbove(cmd) {
+    const active = cmd.activeCell;
+    if (!active || active.rowIndex === 0)
+        return false;
+    if (!writable(cmd, active.rowIndex, active.colIndex))
+        return false;
+    const value = cmd.getCellValue(active.rowIndex - 1, active.colIndex);
+    cmd.setCellValue(active.rowIndex, active.colIndex, value);
+    return true;
+}
+/**
+ * Ctrl+Shift+". The VALUE of the cell above: what a formula there shows,
+ * not the formula, so a running total can be frozen as a number. With an
+ * engine attached the evaluated value is what goes in; without one there is
+ * nothing but the text, which is what Ctrl+' copies. An error above copies
+ * nothing.
+ */
+export function copyValueFromAbove(cmd) {
+    const active = cmd.activeCell;
+    if (!active || active.rowIndex === 0)
+        return false;
+    if (!writable(cmd, active.rowIndex, active.colIndex))
+        return false;
+    const probe = valueProbe;
+    const raw = cmd.getCellValue(active.rowIndex - 1, active.colIndex);
+    let value = raw;
+    if (probe) {
+        const shown = probe(active.rowIndex - 1, active.colIndex);
+        if (shown !== null && typeof shown === 'object')
+            return false;
+        if (shown !== undefined && shown !== null)
+            value = typeof shown === 'boolean' ? (shown ? 'TRUE' : 'FALSE') : String(shown);
+    }
+    cmd.setCellValue(active.rowIndex, active.colIndex, value);
+    return true;
+}
+/**
+ * Alt+=. The range Excel guesses for a SUM anchored at the active cell: the
+ * run of numbers directly above, or directly to the left when there is nothing
+ * above. Returns null when neither direction has numbers to add.
+ */
+export function guessSumRange(cmd, isNumeric = looksNumeric) {
+    const active = cmd.activeCell;
+    if (!active)
+        return null;
+    const { rowIndex: row, colIndex: col } = active;
+    // When an engine is attached the run is measured against evaluated values,
+    // so a column of SUM subtotals counts as numbers the way it does in Excel.
+    const numeric = valueProbe
+        ? (r, c) => numericAt(cmd, r, c)
+        : (r, c) => isNumeric(cmd.getCellValue(r, c));
+    let top = row;
+    while (top > 0 && numeric(top - 1, col))
+        top -= 1;
+    if (top < row)
+        return [top, col, row - 1, col];
+    let left = col;
+    while (left > 0 && numeric(row, left - 1))
+        left -= 1;
+    if (left < col)
+        return [row, left, row, col - 1];
+    return null;
+}
+let valueProbe = null;
+export function setSheetValueProbe(fn) {
+    valueProbe = fn;
+}
+export function getSheetValueProbe() {
+    return valueProbe;
+}
+/**
+ * The numeric test AutoSum should use for the cell at (row, col): the
+ * evaluated value when an engine is attached, the raw text otherwise.
+ */
+export function numericAt(cmd, row, col) {
+    const probe = valueProbe;
+    if (!probe)
+        return looksNumeric(cmd.getCellValue(row, col));
+    const value = probe(row, col);
+    // An engine reports an error as an object; that is not a number, and it
+    // should end the run rather than be counted as one.
+    if (value !== null && typeof value === 'object')
+        return false;
+    return looksNumeric(value);
+}
+/** Default numeric test for AutoSum: a finite number, or a string that parses
+ *  as one. A blank is not a number, so a gap ends the run. */
+export function looksNumeric(value) {
+    if (isBlankValue(value))
+        return false;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value === 'string') {
+        const n = Number(value.trim());
+        return value.trim() !== '' && Number.isFinite(n);
+    }
+    return false;
+}

package/dist/sheet/comments.d.ts

@@ -0,0 +1,29 @@
+import type { NotesMap } from './rects.js';
+export type { NotesMap } from './rects.js';
+/** The comment on (r, c), or undefined when there is none. */
+export declare function commentAt(notes: NotesMap, r: number, c: number): string | undefined;
+/**
+ * The map with (r, c) set to `text`, or cleared when the text is blank.
+ * A new map, never the old one changed: the grid re-reads `notes` only
+ * when the object it is handed is a different one.
+ */
+export declare function withComment(notes: NotesMap, r: number, c: number, text: string): NotesMap;
+/** Every comment, top to bottom then left to right. */
+export declare function listComments(notes: NotesMap): Array<{
+    row: number;
+    col: number;
+    text: string;
+}>;
+/**
+ * The comment after (or before) `from`, reading the sheet row by row and
+ * wrapping at the end, as Excel's Next Comment and Previous Comment do. The
+ * cell itself is skipped, so pressing Next on a commented cell moves on;
+ * null when the sheet has no comments at all.
+ */
+export declare function nextComment(notes: NotesMap, from: {
+    row: number;
+    col: number;
+}, dir: 1 | -1): {
+    row: number;
+    col: number;
+} | null;