@svgrid/enterprise 3.0.1 → 3.0.2

package/dist/sheet/functions.js

@@ -0,0 +1,362 @@
+/**
+ * The function table.
+ *
+ * Each entry receives its arguments already evaluated, in two shapes:
+ *   - `flat`  every argument flattened into one list, ranges expanded. What
+ *             SUM and COUNT want.
+ *   - `args`  one list per argument, so a function can tell `SUM(A1:A3, 5)`
+ *             from `SUM(A1:A3)` and `SUMIF` can line a range up against a
+ *             parallel one.
+ *   - `grids` the 2-D shape of any range argument, kept for VLOOKUP / INDEX /
+ *             MATCH, which lose meaning once flattened.
+ *
+ * Functions that must NOT evaluate every argument (IF, IFERROR, AND, OR with
+ * short-circuit semantics) are handled in the evaluator instead, because by the
+ * time a table entry runs, evaluation has already happened.
+ */
+import { FormulaError, isError, err } from './ast.js';
+import { toNumber, toBool, toText, looseEquals, compare, numericOnly, isBlank, matchesCriterion, } from './coerce.js';
+const first = (a) => a.flat[0] ?? '';
+const nth = (a, i) => a.args[i]?.[0] ?? '';
+function sum(values) {
+    return numericOnly(values).reduce((x, y) => x + y, 0);
+}
+function average(values) {
+    const ns = numericOnly(values);
+    if (ns.length === 0)
+        return err('#DIV/0!');
+    return ns.reduce((x, y) => x + y, 0) / ns.length;
+}
+function roundTo(value, digits) {
+    const f = Math.pow(10, digits);
+    // Scale, round, unscale. The epsilon nudge keeps 1.005 -> 1.01 rather than
+    // 1.00, which is the binary-float surprise users report as a bug.
+    return Math.round((value * f) * (1 + Number.EPSILON)) / f;
+}
+function toDate(v) {
+    if (typeof v === 'number') {
+        // Excel serial: day 1 is 1900-01-01, with the famous phantom leap day.
+        return new Date(Date.UTC(1899, 11, 30) + v * 86400000);
+    }
+    const d = new Date(toText(v));
+    if (Number.isNaN(d.getTime()))
+        throw new FormulaError('#VALUE!');
+    return d;
+}
+const iso = (d) => d.toISOString().slice(0, 10);
+/** Sum / count / average over a criterion range, optionally summing a parallel
+ *  range. The three IF functions differ only in what they do with the hits. */
+function criteriaHits(range, criterion) {
+    const out = [];
+    for (let i = 0; i < range.length; i += 1) {
+        if (matchesCriterion(range[i], criterion))
+            out.push(i);
+    }
+    return out;
+}
+/** SUMIFS / COUNTIFS: every (range, criterion) pair must match at an index. */
+function multiCriteriaHits(pairs) {
+    const firstPair = pairs[0];
+    if (!firstPair)
+        return [];
+    const out = [];
+    for (let i = 0; i < firstPair[0].length; i += 1) {
+        if (pairs.every(([range, crit]) => matchesCriterion(range[i] ?? '', crit)))
+            out.push(i);
+    }
+    return out;
+}
+export const FUNCTIONS = {
+    // ---- Math and aggregation -------------------------------------------
+    SUM: (a) => sum(a.flat),
+    AVERAGE: (a) => average(a.flat),
+    AVG: (a) => average(a.flat),
+    MIN: (a) => { const n = numericOnly(a.flat); return n.length ? Math.min(...n) : 0; },
+    MAX: (a) => { const n = numericOnly(a.flat); return n.length ? Math.max(...n) : 0; },
+    COUNT: (a) => a.flat.filter((v) => typeof v === 'number').length,
+    COUNTA: (a) => a.flat.filter((v) => !isBlank(v)).length,
+    COUNTBLANK: (a) => a.flat.filter((v) => isBlank(v)).length,
+    ABS: (a) => Math.abs(toNumber(first(a))),
+    INT: (a) => Math.floor(toNumber(first(a))),
+    MOD: (a) => {
+        const d = toNumber(nth(a, 1));
+        if (d === 0)
+            return err('#DIV/0!');
+        // Excel's MOD follows the sign of the divisor, unlike JavaScript's %.
+        const n = toNumber(nth(a, 0));
+        return n - d * Math.floor(n / d);
+    },
+    POWER: (a) => Math.pow(toNumber(nth(a, 0)), toNumber(nth(a, 1))),
+    SQRT: (a) => {
+        const n = toNumber(first(a));
+        return n < 0 ? err('#NUM!') : Math.sqrt(n);
+    },
+    ROUND: (a) => roundTo(toNumber(nth(a, 0)), Math.round(toNumber(nth(a, 1) || 0))),
+    ROUNDUP: (a) => {
+        const d = Math.round(toNumber(nth(a, 1) || 0));
+        const f = Math.pow(10, d);
+        const v = toNumber(nth(a, 0));
+        return (v < 0 ? -Math.ceil(-v * f) : Math.ceil(v * f)) / f;
+    },
+    ROUNDDOWN: (a) => {
+        const d = Math.round(toNumber(nth(a, 1) || 0));
+        const f = Math.pow(10, d);
+        const v = toNumber(nth(a, 0));
+        return (v < 0 ? -Math.floor(-v * f) : Math.floor(v * f)) / f;
+    },
+    MEDIAN: (a) => {
+        const n = numericOnly(a.flat).sort((x, y) => x - y);
+        if (!n.length)
+            return err('#NUM!');
+        const mid = Math.floor(n.length / 2);
+        return n.length % 2 ? n[mid] : (n[mid - 1] + n[mid]) / 2;
+    },
+    STDEV: (a) => {
+        const n = numericOnly(a.flat);
+        if (n.length < 2)
+            return err('#DIV/0!');
+        const mean = n.reduce((x, y) => x + y, 0) / n.length;
+        const variance = n.reduce((acc, v) => acc + (v - mean) ** 2, 0) / (n.length - 1);
+        return Math.sqrt(variance);
+    },
+    RANK: (a) => {
+        const value = toNumber(nth(a, 0));
+        const pool = numericOnly(a.args[1] ?? []);
+        const ascending = a.args[2] !== undefined && toBool(nth(a, 2));
+        const sorted = pool.slice().sort((x, y) => (ascending ? x - y : y - x));
+        const at = sorted.indexOf(value);
+        return at < 0 ? err('#N/A') : at + 1;
+    },
+    // ---- Conditional aggregation ----------------------------------------
+    SUMIF: (a) => {
+        const range = a.args[0] ?? [];
+        const hits = criteriaHits(range, nth(a, 1));
+        // The optional third argument is the range actually summed.
+        const target = a.args[2] ?? range;
+        return sum(hits.map((i) => target[i] ?? ''));
+    },
+    COUNTIF: (a) => criteriaHits(a.args[0] ?? [], nth(a, 1)).length,
+    AVERAGEIF: (a) => {
+        const range = a.args[0] ?? [];
+        const hits = criteriaHits(range, nth(a, 1));
+        const target = a.args[2] ?? range;
+        return average(hits.map((i) => target[i] ?? ''));
+    },
+    SUMIFS: (a) => {
+        const target = a.args[0] ?? [];
+        const pairs = [];
+        for (let i = 1; i + 1 < a.args.length + 1; i += 2) {
+            const range = a.args[i];
+            if (!range)
+                break;
+            pairs.push([range, a.args[i + 1]?.[0] ?? '']);
+        }
+        return sum(multiCriteriaHits(pairs).map((i) => target[i] ?? ''));
+    },
+    COUNTIFS: (a) => {
+        const pairs = [];
+        for (let i = 0; i < a.args.length; i += 2) {
+            const range = a.args[i];
+            if (!range)
+                break;
+            pairs.push([range, a.args[i + 1]?.[0] ?? '']);
+        }
+        return multiCriteriaHits(pairs).length;
+    },
+    // ---- Logical ---------------------------------------------------------
+    NOT: (a) => !toBool(first(a)),
+    AND: (a) => a.flat.every((v) => toBool(v)),
+    OR: (a) => a.flat.some((v) => toBool(v)),
+    XOR: (a) => a.flat.filter((v) => toBool(v)).length % 2 === 1,
+    // ---- Information -----------------------------------------------------
+    // What a value IS, not what it can be coerced to: "12" typed as text is
+    // text here, the way Excel answers, and a blank is neither.
+    ISNUMBER: (a) => typeof first(a) === 'number',
+    ISTEXT: (a) => typeof first(a) === 'string' && first(a) !== '',
+    ISLOGICAL: (a) => typeof first(a) === 'boolean',
+    ISBLANK: (a) => first(a) === '',
+    // ---- Text ------------------------------------------------------------
+    LEN: (a) => toText(first(a)).length,
+    LEFT: (a) => toText(nth(a, 0)).slice(0, Math.max(0, Math.round(toNumber(a.args[1] ? nth(a, 1) : 1)))),
+    RIGHT: (a) => {
+        const s = toText(nth(a, 0));
+        const n = Math.max(0, Math.round(toNumber(a.args[1] ? nth(a, 1) : 1)));
+        return n >= s.length ? s : s.slice(s.length - n);
+    },
+    MID: (a) => {
+        const s = toText(nth(a, 0));
+        const start = Math.round(toNumber(nth(a, 1)));
+        if (start < 1)
+            return err('#VALUE!');
+        return s.slice(start - 1, start - 1 + Math.max(0, Math.round(toNumber(nth(a, 2)))));
+    },
+    UPPER: (a) => toText(first(a)).toUpperCase(),
+    LOWER: (a) => toText(first(a)).toLowerCase(),
+    TRIM: (a) => toText(first(a)).trim().replace(/\s+/g, ' '),
+    CONCAT: (a) => a.flat.map((v) => toText(v)).join(''),
+    CONCATENATE: (a) => a.flat.map((v) => toText(v)).join(''),
+    TEXTJOIN: (a) => {
+        const sep = toText(nth(a, 0));
+        const skipEmpty = toBool(nth(a, 1));
+        const rest = a.args.slice(2).flat();
+        return rest.filter((v) => !skipEmpty || !isBlank(v)).map((v) => toText(v)).join(sep);
+    },
+    SUBSTITUTE: (a) => {
+        const s = toText(nth(a, 0));
+        const find = toText(nth(a, 1));
+        const replace = toText(nth(a, 2));
+        if (find === '')
+            return s;
+        return s.split(find).join(replace);
+    },
+    FIND: (a) => {
+        // Case sensitive, 1-based, #VALUE! when absent. SEARCH is its
+        // case-insensitive twin.
+        const at = toText(nth(a, 1)).indexOf(toText(nth(a, 0)));
+        return at < 0 ? err('#VALUE!') : at + 1;
+    },
+    SEARCH: (a) => {
+        const at = toText(nth(a, 1)).toLowerCase().indexOf(toText(nth(a, 0)).toLowerCase());
+        return at < 0 ? err('#VALUE!') : at + 1;
+    },
+    TEXT: (a) => {
+        // Minimal: the full Excel format grammar arrives with per-cell number
+        // formats. Until then this covers the common fixed-decimal case.
+        const v = toNumber(nth(a, 0));
+        const pattern = toText(nth(a, 1));
+        const decimals = /\.(0+)/.exec(pattern)?.[1]?.length ?? 0;
+        const body = v.toFixed(decimals);
+        if (pattern.includes(',')) {
+            const [int = '', frac] = body.split('.');
+            const grouped = int.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+            return frac ? `${grouped}.${frac}` : grouped;
+        }
+        return body;
+    },
+    // ---- Date ------------------------------------------------------------
+    TODAY: () => iso(new Date()),
+    NOW: () => new Date().toISOString().slice(0, 19).replace('T', ' '),
+    YEAR: (a) => toDate(first(a)).getUTCFullYear(),
+    MONTH: (a) => toDate(first(a)).getUTCMonth() + 1,
+    DAY: (a) => toDate(first(a)).getUTCDate(),
+    DATE: (a) => iso(new Date(Date.UTC(Math.round(toNumber(nth(a, 0))), Math.round(toNumber(nth(a, 1))) - 1, Math.round(toNumber(nth(a, 2)))))),
+    EOMONTH: (a) => {
+        const d = toDate(nth(a, 0));
+        const months = Math.round(toNumber(nth(a, 1)));
+        // Day 0 of the following month is the last day of the target month.
+        return iso(new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + months + 1, 0)));
+    },
+    // DAYS(end, start): whole days, negative when the end comes first.
+    DAYS: (a) => Math.round((toDate(nth(a, 0)).getTime() - toDate(nth(a, 1)).getTime()) / 86400000),
+    // DATEDIF(start, end, unit): Excel's "d", "m" and "y", completed units
+    // only, and #NUM! when the start comes after the end, as Excel gives.
+    DATEDIF: (a) => {
+        const start = toDate(nth(a, 0));
+        const end = toDate(nth(a, 1));
+        if (end.getTime() < start.getTime())
+            return err('#NUM!');
+        const unit = toText(nth(a, 2)).toUpperCase();
+        if (unit === 'D')
+            return Math.floor((end.getTime() - start.getTime()) / 86400000);
+        let months = (end.getUTCFullYear() - start.getUTCFullYear()) * 12 + (end.getUTCMonth() - start.getUTCMonth());
+        if (end.getUTCDate() < start.getUTCDate())
+            months -= 1;
+        if (unit === 'M')
+            return months;
+        if (unit === 'Y')
+            return Math.floor(months / 12);
+        return err('#NUM!');
+    },
+    // ---- Lookup ----------------------------------------------------------
+    VLOOKUP: (a) => {
+        const needle = nth(a, 0);
+        const grid = a.grids[1];
+        if (!grid)
+            return err('#REF!');
+        const col = Math.round(toNumber(nth(a, 2)));
+        if (col < 1)
+            return err('#VALUE!');
+        for (const row of grid) {
+            if (row[0] !== undefined && looseEquals(row[0], needle)) {
+                const cell = row[col - 1];
+                return cell === undefined ? err('#REF!') : cell;
+            }
+        }
+        return err('#N/A');
+    },
+    HLOOKUP: (a) => {
+        const needle = nth(a, 0);
+        const grid = a.grids[1];
+        if (!grid)
+            return err('#REF!');
+        const rowIndex = Math.round(toNumber(nth(a, 2)));
+        if (rowIndex < 1)
+            return err('#VALUE!');
+        const header = grid[0] ?? [];
+        for (let c = 0; c < header.length; c += 1) {
+            if (looseEquals(header[c], needle)) {
+                const cell = grid[rowIndex - 1]?.[c];
+                return cell === undefined ? err('#REF!') : cell;
+            }
+        }
+        return err('#N/A');
+    },
+    MATCH: (a) => {
+        const needle = nth(a, 0);
+        const pool = a.args[1] ?? [];
+        const mode = a.args[2] ? Math.round(toNumber(nth(a, 2))) : 1;
+        if (mode === 0) {
+            const at = pool.findIndex((v) => looseEquals(v, needle));
+            return at < 0 ? err('#N/A') : at + 1;
+        }
+        // Ordered search: the last value not past the needle.
+        let best = -1;
+        for (let i = 0; i < pool.length; i += 1) {
+            const cmp = compare(pool[i], needle);
+            if (mode === 1 ? cmp <= 0 : cmp >= 0)
+                best = i;
+        }
+        return best < 0 ? err('#N/A') : best + 1;
+    },
+    INDEX: (a) => {
+        const grid = a.grids[0];
+        if (!grid) {
+            const at = Math.round(toNumber(nth(a, 1)));
+            const v = (a.args[0] ?? [])[at - 1];
+            return v === undefined ? err('#REF!') : v;
+        }
+        const given = Math.round(toNumber(nth(a, 1)));
+        // With one number, a one-column range indexes by row and a one-row range
+        // by column, as Excel does: =INDEX(B4:D4, 2) is the second scenario
+        // heading, not #REF!.
+        const oneRow = grid.length === 1 && !a.args[2];
+        const rowIndex = oneRow ? 1 : given;
+        const colIndex = oneRow ? given : a.args[2] ? Math.round(toNumber(nth(a, 2))) : 1;
+        const row = grid[rowIndex - 1];
+        if (!row)
+            return err('#REF!');
+        const cell = row[colIndex - 1];
+        return cell === undefined ? err('#REF!') : cell;
+    },
+    XLOOKUP: (a) => {
+        const needle = nth(a, 0);
+        const haystack = a.args[1] ?? [];
+        const results = a.args[2] ?? [];
+        const at = haystack.findIndex((v) => looseEquals(v, needle));
+        if (at < 0)
+            return a.args[3] ? nth(a, 3) : err('#N/A');
+        const cell = results[at];
+        return cell === undefined ? err('#REF!') : cell;
+    },
+};
+/** Merge caller-supplied functions over the built-ins. Keys are uppercased so
+ *  a consumer can register `myFn` and write `=MYFN()`. */
+export function withCustomFunctions(custom) {
+    if (!custom)
+        return FUNCTIONS;
+    const out = { ...FUNCTIONS };
+    for (const [name, fn] of Object.entries(custom))
+        out[name.toUpperCase()] = fn;
+    return out;
+}
+export { isError };

package/dist/sheet/goal-seek.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Goal Seek: find the input value that makes a formula cell hit a target.
+ *
+ * "What interest rate makes the monthly payment 1500?" You know the answer
+ * you want and one cell you are willing to change; the solver finds it.
+ *
+ * The method is secant with a bisection fallback, not Newton. Newton needs a
+ * derivative, and the function here is "recalculate a spreadsheet", which has
+ * no analytic one. Secant approximates the slope from two evaluations, which
+ * is the same information a numerical derivative would cost anyway.
+ *
+ * Bisection is the fallback because secant is fast but not safe: it can step
+ * to infinity on a flat stretch or oscillate on a kink. When a bracket is
+ * known - two inputs whose results straddle the target - bisection cannot
+ * fail, only be slow. Trying secant first and falling back keeps the common
+ * case quick and the awkward case terminating.
+ */
+export type GoalSeekOptions = {
+    /** Stop once the result is this close to the target. */
+    tolerance?: number;
+    /** Give up after this many recalculations. */
+    maxIterations?: number;
+    /** Where to start looking. Defaults to the input cell's current value. */
+    initialGuess?: number;
+    /** Keep the answer inside these bounds. A rate solver wants [0, 1]. */
+    min?: number;
+    max?: number;
+};
+export type GoalSeekResult = {
+    /** Whether the target was reached within tolerance. */
+    converged: boolean;
+    /** The input value found. Present even when it did not converge, so a
+     *  caller can show the closest attempt rather than nothing. */
+    value: number;
+    /** What the formula produced at that input. */
+    result: number;
+    iterations: number;
+    /** Why it stopped, when it did not converge. */
+    reason?: 'maxIterations' | 'notNumeric' | 'flat' | 'outOfBounds';
+};
+/**
+ * Solve `evaluate(input) = target` for `input`.
+ *
+ * `evaluate` sets the input cell, recalculates, and returns the formula
+ * cell's value. It is called many times, so it should be the workbook's own
+ * recalculation rather than anything that touches the DOM.
+ *
+ * The caller owns the input cell: this never writes. It reports the value it
+ * found and lets the caller decide whether to keep it, which is what makes
+ * Excel's "Goal Seek found a solution / OK or Cancel" dialog possible.
+ */
+export declare function goalSeek(evaluate: (input: number) => unknown, target: number, start: number, options?: GoalSeekOptions): GoalSeekResult;
+/** What `goalSeekCell` needs of a workbook. */
+export type GoalSeekSheet = {
+    getRaw(sheet: string, row: number, col: number): string;
+    setRaw(sheet: string, row: number, col: number, text: string): void;
+    getValue(sheet: string, row: number, col: number): unknown;
+};
+export type CellAddress = {
+    sheet: string;
+    row: number;
+    col: number;
+};
+/**
+ * Goal Seek over a workbook: change `input` until `formula` reads `target`.
+ *
+ * The input cell is RESTORED before returning, whatever the outcome. The
+ * solver writes to it dozens of times while searching, and leaving the last
+ * probe behind would be worse than not running: Excel shows you the answer
+ * and asks before keeping it, which it cannot do if the sheet has already
+ * moved. Apply `result.value` yourself once the user says yes.
+ */
+export declare function goalSeekCell(book: GoalSeekSheet, formula: CellAddress, input: CellAddress, target: number, options?: GoalSeekOptions): GoalSeekResult;

package/dist/sheet/goal-seek.js

@@ -0,0 +1,153 @@
+/**
+ * Goal Seek: find the input value that makes a formula cell hit a target.
+ *
+ * "What interest rate makes the monthly payment 1500?" You know the answer
+ * you want and one cell you are willing to change; the solver finds it.
+ *
+ * The method is secant with a bisection fallback, not Newton. Newton needs a
+ * derivative, and the function here is "recalculate a spreadsheet", which has
+ * no analytic one. Secant approximates the slope from two evaluations, which
+ * is the same information a numerical derivative would cost anyway.
+ *
+ * Bisection is the fallback because secant is fast but not safe: it can step
+ * to infinity on a flat stretch or oscillate on a kink. When a bracket is
+ * known - two inputs whose results straddle the target - bisection cannot
+ * fail, only be slow. Trying secant first and falling back keeps the common
+ * case quick and the awkward case terminating.
+ */
+const DEFAULTS = {
+    tolerance: 1e-7,
+    maxIterations: 100,
+};
+/**
+ * Solve `evaluate(input) = target` for `input`.
+ *
+ * `evaluate` sets the input cell, recalculates, and returns the formula
+ * cell's value. It is called many times, so it should be the workbook's own
+ * recalculation rather than anything that touches the DOM.
+ *
+ * The caller owns the input cell: this never writes. It reports the value it
+ * found and lets the caller decide whether to keep it, which is what makes
+ * Excel's "Goal Seek found a solution / OK or Cancel" dialog possible.
+ */
+export function goalSeek(evaluate, target, start, options = {}) {
+    const tolerance = options.tolerance ?? DEFAULTS.tolerance;
+    const maxIterations = options.maxIterations ?? DEFAULTS.maxIterations;
+    const min = options.min ?? Number.NEGATIVE_INFINITY;
+    const max = options.max ?? Number.POSITIVE_INFINITY;
+    let iterations = 0;
+    const clamp = (x) => Math.min(Math.max(x, min), max);
+    /** The signed distance from the target. Zero is the answer. */
+    const f = (x) => {
+        iterations += 1;
+        const raw = evaluate(x);
+        const n = typeof raw === 'number' ? raw : Number(raw);
+        return Number.isFinite(n) ? n - target : null;
+    };
+    let x0 = clamp(options.initialGuess ?? start);
+    let f0 = f(x0);
+    if (f0 === null) {
+        return { converged: false, value: x0, result: NaN, iterations, reason: 'notNumeric' };
+    }
+    if (Math.abs(f0) <= tolerance) {
+        return { converged: true, value: x0, result: f0 + target, iterations };
+    }
+    // A second point, offset enough to see a slope. Scaling with the guess
+    // matters: a fixed step of 1 is enormous next to an interest rate of 0.05
+    // and invisible next to a loan of 300000.
+    let x1 = clamp(x0 !== 0 ? x0 * 1.1 : 1);
+    if (x1 === x0)
+        x1 = clamp(x0 + 1);
+    let f1 = f(x1);
+    if (f1 === null) {
+        return { converged: false, value: x0, result: f0 + target, iterations, reason: 'notNumeric' };
+    }
+    /** Best seen so far, so a failure still reports the closest attempt. */
+    let best = Math.abs(f0) <= Math.abs(f1) ? { x: x0, fx: f0 } : { x: x1, fx: f1 };
+    const bracket = { lo: null, hi: null };
+    const noteBracket = (a, b) => {
+        if (a.fx === 0 || b.fx === 0)
+            return;
+        if ((a.fx < 0) !== (b.fx < 0)) {
+            bracket.lo = a.fx < 0 ? a : b;
+            bracket.hi = a.fx < 0 ? b : a;
+        }
+    };
+    noteBracket({ x: x0, fx: f0 }, { x: x1, fx: f1 });
+    while (iterations < maxIterations) {
+        if (Math.abs(f1) <= tolerance) {
+            return { converged: true, value: x1, result: f1 + target, iterations };
+        }
+        let next;
+        const slope = f1 - f0;
+        if (slope === 0) {
+            // Flat between the two points. Secant divides by this, so bisect if a
+            // bracket exists and give up if not - a genuinely flat function has no
+            // solution to find.
+            const { lo, hi } = bracket;
+            if (!lo || !hi) {
+                return { converged: false, value: best.x, result: best.fx + target, iterations, reason: 'flat' };
+            }
+            next = (lo.x + hi.x) / 2;
+        }
+        else {
+            next = x1 - f1 * ((x1 - x0) / slope);
+            // Secant can step anywhere, including outside a bracket we already
+            // trust. Bisect instead when it does.
+            const { lo, hi } = bracket;
+            const outside = !Number.isFinite(next) ||
+                (lo !== null && hi !== null && (next < Math.min(lo.x, hi.x) || next > Math.max(lo.x, hi.x)));
+            if (outside)
+                next = lo && hi ? (lo.x + hi.x) / 2 : clamp(next);
+        }
+        next = clamp(next);
+        if (next === x1) {
+            // Clamped against a bound and cannot move.
+            return {
+                converged: false, value: best.x, result: best.fx + target, iterations,
+                reason: Number.isFinite(min) || Number.isFinite(max) ? 'outOfBounds' : 'flat',
+            };
+        }
+        const fNext = f(next);
+        if (fNext === null) {
+            return { converged: false, value: best.x, result: best.fx + target, iterations, reason: 'notNumeric' };
+        }
+        if (Math.abs(fNext) < Math.abs(best.fx))
+            best = { x: next, fx: fNext };
+        noteBracket({ x: x1, fx: f1 }, { x: next, fx: fNext });
+        x0 = x1;
+        f0 = f1;
+        x1 = next;
+        f1 = fNext;
+    }
+    if (Math.abs(f1) <= tolerance) {
+        return { converged: true, value: x1, result: f1 + target, iterations };
+    }
+    return {
+        converged: false, value: best.x, result: best.fx + target,
+        iterations, reason: 'maxIterations',
+    };
+}
+/**
+ * Goal Seek over a workbook: change `input` until `formula` reads `target`.
+ *
+ * The input cell is RESTORED before returning, whatever the outcome. The
+ * solver writes to it dozens of times while searching, and leaving the last
+ * probe behind would be worse than not running: Excel shows you the answer
+ * and asks before keeping it, which it cannot do if the sheet has already
+ * moved. Apply `result.value` yourself once the user says yes.
+ */
+export function goalSeekCell(book, formula, input, target, options = {}) {
+    const original = book.getRaw(input.sheet, input.row, input.col);
+    const startText = original.trim();
+    const start = Number(startText);
+    try {
+        return goalSeek((x) => {
+            book.setRaw(input.sheet, input.row, input.col, String(x));
+            return book.getValue(formula.sheet, formula.row, formula.col);
+        }, target, Number.isFinite(start) ? start : 0, options);
+    }
+    finally {
+        book.setRaw(input.sheet, input.row, input.col, original);
+    }
+}

package/dist/sheet/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `@svgrid/enterprise/sheet` - the Excel keyboard layer on its own subpath.
+ *
+ * Importing the package barrel pulls every module it reaches into the chunk
+ * (the package sets no `sideEffects` flag), which for an app that only wants
+ * the shortcuts would mean shipping export, pivot, the scheduler and the board
+ * as well. This subpath is the shortcuts and nothing else. It matters more once
+ * the formula engine lands beside them in phase 2.
+ */
+export { enableSheet } from '../sheet-enable.js';
+export { createTableRegistry, isValidTableName, resolveTableRange, columnIndexOf, rowCountOf, type TableRegion, type TableRegistry, type TableRange, type TableSpecifier, } from './tables.js';
+export { goalSeek, goalSeekCell, type GoalSeekOptions, type GoalSeekResult, type GoalSeekSheet, type CellAddress as GoalSeekCellAddress, } from './goal-seek.js';
+export { default as SvSheetTabs } from '../SvSheetTabs.svelte';
+export { createWorkbook, isValidSheetName, type Workbook, type SheetData, type WorkbookOptions, } from './workbook.js';
+export { setWorkbook, getWorkbook } from './shortcuts.js';
+export { createSheetDocument, type SheetDocument, type SheetDocumentInit, type SheetState, type SheetStateEntry, type PerSheetState, type SheetChangeReason, } from './document.js';
+export { shiftRect, shiftRects, subtractRect, rectContains, rectsIntersect, remapNotes, lineShift, type NotesMap } from './rects.js';
+export { isLocked, rectsHaveLocked, rectsMixLocked, PROTECTED_MESSAGE } from './protection.js';
+export { commentAt, withComment, listComments, nextComment } from './comments.js';
+export { ruleAt, rulesIn, checkEntry, listChoices, shiftValidation, removeValidation, describeRule, dateValue, validationId, DEFAULT_ALERT_MESSAGE, OPERATOR_LABELS, type ValidationRule, type ValidationAllow, type ValidationOperator, type ValidationContext, type ValidationVerdict, type ValidationSpec, } from './validation.js';
+export { ruleStats, evaluateCf, shiftCf, removeCf, cfIn, describeCf, scaleColor, iconIndex, hasStyle, cfId, CF_PRESET_STYLES, COLOR_SCALES, DATA_BAR_COLOR, type CfRule, type CfRuleBody, type CfStyledRule, type CfBody, type CfPreset, type CfStyle, type CfStats, type CfResult, type CfContext, type CfOperator, type CfTextMatch, type CfIconSet, type CfScaleColors, type CfKind, } from './conditional-formats.js';
+export { mergePlan, unmergePlan, mergeDropsValues, mergesIn, mergeAt as sheetMergeAt, isCoveredCell, selectionMerged, toGridMerges, sortBlockedByMerges, reorderMerges, normalRect, type MergeKind, type MergePlan, } from './merges.js';
+export { distinctValues, hiddenRowsFor, passesFilter, isFiltering, withColumnFilter, valuesFilter, shiftAutoFilter, describeFilter, type AutoFilterState, type ColumnFilter, type FilterCondition, type FilterValue, } from './auto-filter.js';
+export { splitText, textToColumns, guessDelimiter, findDuplicates, removeDuplicates, type SplitOptions, type DuplicateOptions, type DuplicateReport, } from './transforms.js';
+export { insertRows, deleteRows, insertColumns, deleteColumns, axisForSelection, setStructureTarget, getStructureTarget, rewriteFormulas, type StructureTarget, } from './structure.js';
+export { findAll, findNext, replaceOne, replaceAll, replaceInText, cellMatches, setFindTarget, getFindTarget, type FindOptions, type FindHit, type FindTarget, } from './find-replace.js';
+export { splitFrozenRows, frozenColumnIds, applyFreeze, freezeAtActiveCell, freezeTopRow, freezeFirstColumn, unfreeze, type FreezeState, type FreezeSplit, } from './freeze.js';
+export { buildClipboardPayload, parseClipboard, parseClipboardText, parseClipboardHtml, readClipboardOrigin, anchorForeignFormulas, resolvePasteCell, planPaste, msoNumberFormat, numFmtFromMso, isR1C1, r1c1ToA1, type PasteSpecialOptions, type PasteWhat, type PasteOperation, type ClipboardCell, type ClipboardGrid, type PasteResolution, } from './paste-special.js';
+export { setFindReplaceHandler, setPasteSpecialHandler } from './shortcuts.js';
+export { default as SvFormulaBar } from '../SvFormulaBar.svelte';
+export { default as SvSheet } from '../SvSheet.svelte';
+export { default as SvSheetRibbon } from '../SvSheetRibbon.svelte';
+export { RIBBON_TABS, ribbonItems, withDecimals, applyBorders, type RibbonTab, type RibbonGroup, type RibbonItem, type RibbonOption, type RibbonItemKind, type RibbonActionId, type BorderPreset, } from './ribbon.js';
+export { RIBBON_ICONS, RIBBON_ICON_NAMES, type RibbonIconName, type IconPath } from './ribbon-icons.js';
+export { THEME_COLOURS, STANDARD_COLOURS, ALL_COLOURS, tint, type PaletteColour } from './palette.js';
+export { default as SvRibbonIcon } from '../SvRibbonIcon.svelte';
+export { move, selectRegion, selectLine, applyFormat, toggleFormat, preset, autoSum, structural, switchSheet, gridOf, } from './shortcuts.js';
+export { compileNumberFormat, formatWithPattern, FORMAT_PRESETS, type CompiledFormat, type FormatPresetName, } from './number-format.js';
+export { createFormatStore, entryToStyle, type SheetFormatStore, type CellFormatEntry, type CellAddressLookup, } from './format-store.js';
+export { createNames, isValidName, type SheetNames, type DefinedName, } from './names.js';
+export { suggestFunctions, applySuggestion, signatureAt, partialAt, SIGNATURES, type FunctionSuggestion, } from './autocomplete.js';
+export { setFormatTarget, getFormatTarget, setFormatDialogHandler, type SheetFormatTarget, } from './shortcuts.js';
+export { parseFormula, parse, } from './parse.js';
+export { tokenize, type Token } from './tokenize.js';
+export { evaluate, formatValue, type EvalContext } from './evaluate.js';
+export { FUNCTIONS, withCustomFunctions, type SheetFunction, type FnArgs, } from './functions.js';
+export { translateFormula, fixupReferences, renameSheetReferences, formatFormula, referenceSpans, REFERENCE_COLOURS, type StructuralEdit, type EditScope, type ReferenceSpan, } from './refs.js';
+export { createDependencyGraph, precedentsOf, cellKey, parseCellKey, type DependencyGraph, type CellKey, } from './deps.js';
+export { parseA1, formatA1, colToLetters, lettersToCol, type CellRef, } from './address.js';
+export { isError, type CellValue, type SheetError, type Node as FormulaNode, } from './ast.js';
+export { SHEET_BINDINGS, handleSheetKey, type SheetBinding, type SheetCommand, } from './shortcuts.js';
+export { edgeOfRegion, currentRegion, isWholeSheet, wholeSheet, isBlankValue, type Direction, type Grid, type Cell, type Rect, } from './navigate.js';
+export { fillDown, fillRight, fillSelection, stampDate, stampNow, copyFromAbove, copyValueFromAbove, guessSumRange, looksNumeric, numericAt, targetRect, setFillTranslator, setSheetValueProbe, getSheetValueProbe, type FillTranslator, type SheetValueProbe, } from './commands.js';