@svgrid/enterprise 3.0.0 → 3.0.2

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';

package/dist/sheet/index.js

@@ -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, } from './tables.js';
+export { goalSeek, goalSeekCell, } from './goal-seek.js';
+export { default as SvSheetTabs } from '../SvSheetTabs.svelte';
+export { createWorkbook, isValidSheetName, } from './workbook.js';
+export { setWorkbook, getWorkbook } from './shortcuts.js';
+export { createSheetDocument, } from './document.js';
+export { shiftRect, shiftRects, subtractRect, rectContains, rectsIntersect, remapNotes, lineShift } 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, } from './validation.js';
+export { ruleStats, evaluateCf, shiftCf, removeCf, cfIn, describeCf, scaleColor, iconIndex, hasStyle, cfId, CF_PRESET_STYLES, COLOR_SCALES, DATA_BAR_COLOR, } from './conditional-formats.js';
+export { mergePlan, unmergePlan, mergeDropsValues, mergesIn, mergeAt as sheetMergeAt, isCoveredCell, selectionMerged, toGridMerges, sortBlockedByMerges, reorderMerges, normalRect, } from './merges.js';
+export { distinctValues, hiddenRowsFor, passesFilter, isFiltering, withColumnFilter, valuesFilter, shiftAutoFilter, describeFilter, } from './auto-filter.js';
+export { splitText, textToColumns, guessDelimiter, findDuplicates, removeDuplicates, } from './transforms.js';
+export { insertRows, deleteRows, insertColumns, deleteColumns, axisForSelection, setStructureTarget, getStructureTarget, rewriteFormulas, } from './structure.js';
+export { findAll, findNext, replaceOne, replaceAll, replaceInText, cellMatches, setFindTarget, getFindTarget, } from './find-replace.js';
+export { splitFrozenRows, frozenColumnIds, applyFreeze, freezeAtActiveCell, freezeTopRow, freezeFirstColumn, unfreeze, } from './freeze.js';
+export { buildClipboardPayload, parseClipboard, parseClipboardText, parseClipboardHtml, readClipboardOrigin, anchorForeignFormulas, resolvePasteCell, planPaste, msoNumberFormat, numFmtFromMso, isR1C1, r1c1ToA1, } 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, } from './ribbon.js';
+export { RIBBON_ICONS, RIBBON_ICON_NAMES } from './ribbon-icons.js';
+export { THEME_COLOURS, STANDARD_COLOURS, ALL_COLOURS, tint } 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, } from './number-format.js';
+export { createFormatStore, entryToStyle, } from './format-store.js';
+export { createNames, isValidName, } from './names.js';
+export { suggestFunctions, applySuggestion, signatureAt, partialAt, SIGNATURES, } from './autocomplete.js';
+export { setFormatTarget, getFormatTarget, setFormatDialogHandler, } from './shortcuts.js';
+export { parseFormula, parse, } from './parse.js';
+export { tokenize } from './tokenize.js';
+export { evaluate, formatValue } from './evaluate.js';
+export { FUNCTIONS, withCustomFunctions, } from './functions.js';
+export { translateFormula, fixupReferences, renameSheetReferences, formatFormula, referenceSpans, REFERENCE_COLOURS, } from './refs.js';
+export { createDependencyGraph, precedentsOf, cellKey, parseCellKey, } from './deps.js';
+export { parseA1, formatA1, colToLetters, lettersToCol, } from './address.js';
+export { isError, } from './ast.js';
+export { SHEET_BINDINGS, handleSheetKey, } from './shortcuts.js';
+export { edgeOfRegion, currentRegion, isWholeSheet, wholeSheet, isBlankValue, } from './navigate.js';
+export { fillDown, fillRight, fillSelection, stampDate, stampNow, copyFromAbove, copyValueFromAbove, guessSumRange, looksNumeric, numericAt, targetRect, setFillTranslator, setSheetValueProbe, getSheetValueProbe, } from './commands.js';

package/dist/sheet/merges.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Merged cells in the sheet: Excel's Merge & Center, Merge Across, Merge
+ * Cells and Unmerge Cells over the document's per-sheet `merges`, which
+ * are rectangles `[minRow, minCol, maxRow, maxCol]`. The grid draws them
+ * through its `mergedCells` prop; this module is the pure part: what a
+ * command does to the rectangles and to the cells under them.
+ *
+ * As in Excel, a merge keeps the top-left cell's value and drops the
+ * rest, so `mergePlan` says which cells to clear; the shell writes them
+ * through the command context so the merge and the clears are one undo.
+ */
+import { type Rect } from './rects.js';
+export type MergeKind = 'center' | 'across' | 'cells';
+export type MergePlan = {
+    /** The rectangles after the command. */
+    merges: Rect[];
+    /** Cells to clear, top-left cells of each new merge excluded. */
+    clear: Array<[row: number, col: number]>;
+    /** Whether Merge & Center also centres: the shell sets `align`. */
+    center: boolean;
+    /** The new merges' top-left cells, where the centre alignment goes. */
+    origins: Array<[row: number, col: number]>;
+};
+/** Normalise a rectangle to top-left / bottom-right. */
+export declare function normalRect(rect: Rect): Rect;
+/** The merges touching any of the rectangles. */
+export declare function mergesIn(merges: ReadonlyArray<Rect>, rects: ReadonlyArray<Rect>): Rect[];
+/** The merge covering (r, c), or undefined. */
+export declare function mergeAt(merges: ReadonlyArray<Rect>, r: number, c: number): Rect | undefined;
+/** Whether (r, c) is inside a merge without being its top-left cell. */
+export declare function isCoveredCell(merges: ReadonlyArray<Rect>, r: number, c: number): boolean;
+/**
+ * Merge the selection: one merge per rectangle (Merge & Center, Merge
+ * Cells) or one per row of each rectangle (Merge Across). Merges already
+ * inside the selection are replaced, as Excel replaces them. A single
+ * cell merges nothing.
+ */
+export declare function mergePlan(merges: ReadonlyArray<Rect>, rects: ReadonlyArray<Rect>, kind: MergeKind, isBlank: (r: number, c: number) => boolean): MergePlan;
+/**
+ * Whether merging the selection would drop a value: Excel warns that
+ * "merging cells only keeps the upper-left value". The shell asks before
+ * it merges.
+ */
+export declare function mergeDropsValues(rects: ReadonlyArray<Rect>, kind: MergeKind, isBlank: (r: number, c: number) => boolean): boolean;
+/** Unmerge: every merge the selection touches goes. */
+export declare function unmergePlan(merges: ReadonlyArray<Rect>, rects: ReadonlyArray<Rect>): Rect[];
+/**
+ * A rectangle grown to hold every merge it touches, to a fixed point: the
+ * grid selects this way (a click on a merged cell takes the whole merge),
+ * so the header shading and anything else that reads the selection's
+ * columns and rows has to see the same rectangle.
+ */
+export declare function expandToMerges(merges: ReadonlyArray<Rect>, rect: Rect): Rect;
+/** Whether the selection holds a merge, for the button's state. */
+export declare function selectionMerged(merges: ReadonlyArray<Rect>, rects: ReadonlyArray<Rect>): boolean;
+/** The merges as the grid takes them. */
+export declare function toGridMerges(merges: ReadonlyArray<Rect>): Array<{
+    rowIndex: number;
+    colIndex: number;
+    rowSpan: number;
+    colSpan: number;
+}>;
+/**
+ * Whether a sort of `rect` can go ahead: Excel refuses when a merge
+ * crosses the range's edge ("all merged cells need to be the same size"),
+ * and the shell moves whole merges with their rows only when every merge
+ * in the range is one row tall and sits inside it.
+ */
+export declare function sortBlockedByMerges(merges: ReadonlyArray<Rect>, rect: Rect): boolean;
+/** The merges of a sorted region, each moved with the row it sat on. */
+export declare function reorderMerges(merges: ReadonlyArray<Rect>, rect: Rect, rowFor: (oldRow: number) => number): Rect[];

package/dist/sheet/merges.js

@@ -0,0 +1,137 @@
+/**
+ * Merged cells in the sheet: Excel's Merge & Center, Merge Across, Merge
+ * Cells and Unmerge Cells over the document's per-sheet `merges`, which
+ * are rectangles `[minRow, minCol, maxRow, maxCol]`. The grid draws them
+ * through its `mergedCells` prop; this module is the pure part: what a
+ * command does to the rectangles and to the cells under them.
+ *
+ * As in Excel, a merge keeps the top-left cell's value and drops the
+ * rest, so `mergePlan` says which cells to clear; the shell writes them
+ * through the command context so the merge and the clears are one undo.
+ */
+import { rectContains, rectsIntersect } from './rects.js';
+/** Normalise a rectangle to top-left / bottom-right. */
+export function normalRect(rect) {
+    return [Math.min(rect[0], rect[2]), Math.min(rect[1], rect[3]), Math.max(rect[0], rect[2]), Math.max(rect[1], rect[3])];
+}
+/** The merges touching any of the rectangles. */
+export function mergesIn(merges, rects) {
+    return merges.filter((m) => rects.some((r) => rectsIntersect(m, normalRect(r))));
+}
+/** The merge covering (r, c), or undefined. */
+export function mergeAt(merges, r, c) {
+    return merges.find((m) => rectContains(m, r, c));
+}
+/** Whether (r, c) is inside a merge without being its top-left cell. */
+export function isCoveredCell(merges, r, c) {
+    const m = mergeAt(merges, r, c);
+    return !!m && (m[0] !== r || m[1] !== c);
+}
+/**
+ * Merge the selection: one merge per rectangle (Merge & Center, Merge
+ * Cells) or one per row of each rectangle (Merge Across). Merges already
+ * inside the selection are replaced, as Excel replaces them. A single
+ * cell merges nothing.
+ */
+export function mergePlan(merges, rects, kind, isBlank) {
+    const targets = [];
+    for (const raw of rects) {
+        const rect = normalRect(raw);
+        if (kind === 'across') {
+            if (rect[1] === rect[3])
+                continue;
+            for (let r = rect[0]; r <= rect[2]; r += 1)
+                targets.push([r, rect[1], r, rect[3]]);
+        }
+        else if (rect[0] !== rect[2] || rect[1] !== rect[3]) {
+            targets.push(rect);
+        }
+    }
+    const kept = merges.filter((m) => !targets.some((t) => rectsIntersect(m, t)));
+    const clear = [];
+    const origins = [];
+    for (const t of targets) {
+        origins.push([t[0], t[1]]);
+        for (let r = t[0]; r <= t[2]; r += 1) {
+            for (let c = t[1]; c <= t[3]; c += 1) {
+                if (r === t[0] && c === t[1])
+                    continue;
+                if (!isBlank(r, c))
+                    clear.push([r, c]);
+            }
+        }
+    }
+    return { merges: [...kept, ...targets], clear, center: kind === 'center', origins };
+}
+/**
+ * Whether merging the selection would drop a value: Excel warns that
+ * "merging cells only keeps the upper-left value". The shell asks before
+ * it merges.
+ */
+export function mergeDropsValues(rects, kind, isBlank) {
+    return mergePlan([], rects, kind, isBlank).clear.length > 0;
+}
+/** Unmerge: every merge the selection touches goes. */
+export function unmergePlan(merges, rects) {
+    const touched = mergesIn(merges, rects);
+    return merges.filter((m) => !touched.includes(m));
+}
+/**
+ * A rectangle grown to hold every merge it touches, to a fixed point: the
+ * grid selects this way (a click on a merged cell takes the whole merge),
+ * so the header shading and anything else that reads the selection's
+ * columns and rows has to see the same rectangle.
+ */
+export function expandToMerges(merges, rect) {
+    let out = normalRect(rect);
+    for (let guard = 0; guard < 64; guard += 1) {
+        let grown = false;
+        for (const m of merges) {
+            if (!rectsIntersect(m, out))
+                continue;
+            const next = [Math.min(out[0], m[0]), Math.min(out[1], m[1]), Math.max(out[2], m[2]), Math.max(out[3], m[3])];
+            if (next[0] !== out[0] || next[1] !== out[1] || next[2] !== out[2] || next[3] !== out[3]) {
+                out = next;
+                grown = true;
+            }
+        }
+        if (!grown)
+            break;
+    }
+    return out;
+}
+/** Whether the selection holds a merge, for the button's state. */
+export function selectionMerged(merges, rects) {
+    return mergesIn(merges, rects).length > 0;
+}
+/** The merges as the grid takes them. */
+export function toGridMerges(merges) {
+    return merges.map((m) => ({ rowIndex: m[0], colIndex: m[1], rowSpan: m[2] - m[0] + 1, colSpan: m[3] - m[1] + 1 }));
+}
+/**
+ * Whether a sort of `rect` can go ahead: Excel refuses when a merge
+ * crosses the range's edge ("all merged cells need to be the same size"),
+ * and the shell moves whole merges with their rows only when every merge
+ * in the range is one row tall and sits inside it.
+ */
+export function sortBlockedByMerges(merges, rect) {
+    const range = normalRect(rect);
+    for (const m of merges) {
+        if (!rectsIntersect(m, range))
+            continue;
+        const inside = m[0] >= range[0] && m[2] <= range[2] && m[1] >= range[1] && m[3] <= range[3];
+        if (!inside || m[0] !== m[2])
+            return true;
+    }
+    return false;
+}
+/** The merges of a sorted region, each moved with the row it sat on. */
+export function reorderMerges(merges, rect, rowFor) {
+    const range = normalRect(rect);
+    return merges.map((m) => {
+        if (!rectsIntersect(m, range))
+            return m;
+        const row = rowFor(m[0]);
+        return [row, m[1], row, m[3]];
+    });
+}

package/dist/sheet/names.d.ts

@@ -0,0 +1,31 @@
+import type { Node } from './ast.js';
+export type DefinedName = {
+    name: string;
+    /** What it refers to, e.g. `=Sheet1!$B$1` or `=$A$1:$C$9`. */
+    refersTo: string;
+};
+export type SheetNames = {
+    define(name: string, refersTo: string): void;
+    remove(name: string): void;
+    has(name: string): boolean;
+    /** The parsed reference behind a name, or null when undefined or unparseable. */
+    resolve(name: string): Node | null;
+    list(): DefinedName[];
+    serialize(): Record<string, string>;
+    hydrate(entries: Record<string, string>): void;
+    clear(): void;
+};
+/**
+ * Excel's rules, and the ones worth enforcing because a name that looks like a
+ * reference makes every formula containing it ambiguous:
+ *   - starts with a letter or underscore
+ *   - letters, digits, underscores and dots after that
+ *   - not something that reads as a CELL reference (`A1`, `$A$1`)
+ *   - not `R` or `C`, which Excel reserves for R1C1 notation
+ *
+ * A bare word like `Tax` is fine even though `TAX` is a valid column label:
+ * the tokenizer only reads a word as a column when it is qualified by a sheet
+ * or followed by a colon, so `=Tax` is never ambiguous.
+ */
+export declare function isValidName(name: string): boolean;
+export declare function createNames(initial?: Record<string, string>): SheetNames;

package/dist/sheet/names.js

@@ -0,0 +1,87 @@
+/**
+ * Defined names: `Tax` resolving to `Sheet1!$B$1`, so a formula can say
+ * `=Subtotal*Tax` instead of `=D5*$B$1`.
+ *
+ * Names are stored as the TEXT they refer to rather than a parsed reference,
+ * because that is what the user typed and what round-trips to xlsx. Resolution
+ * parses on demand and caches nothing: names change rarely and resolving is
+ * cheap next to evaluating the formula that asked.
+ */
+import { parseFormula } from './parse.js';
+/**
+ * Excel's rules, and the ones worth enforcing because a name that looks like a
+ * reference makes every formula containing it ambiguous:
+ *   - starts with a letter or underscore
+ *   - letters, digits, underscores and dots after that
+ *   - not something that reads as a CELL reference (`A1`, `$A$1`)
+ *   - not `R` or `C`, which Excel reserves for R1C1 notation
+ *
+ * A bare word like `Tax` is fine even though `TAX` is a valid column label:
+ * the tokenizer only reads a word as a column when it is qualified by a sheet
+ * or followed by a colon, so `=Tax` is never ambiguous.
+ */
+export function isValidName(name) {
+    if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(name))
+        return false;
+    if (name.length > 255)
+        return false;
+    // Letters followed by digits is a cell reference, whatever else it spells.
+    if (/^\$?[A-Za-z]{1,3}\$?\d+$/.test(name))
+        return false;
+    if (/^[RC]$/i.test(name))
+        return false;
+    if (/^(TRUE|FALSE)$/i.test(name))
+        return false;
+    return true;
+}
+export function createNames(initial) {
+    // Names are case-insensitive in Excel but keep the case they were defined
+    // with, so the map keys on the uppercase form and the entry holds the
+    // original.
+    const byUpper = new Map();
+    const api = {
+        define(name, refersTo) {
+            if (!isValidName(name)) {
+                throw new Error(`"${name}" is not a valid defined name: it must start with a letter ` +
+                    'or underscore and must not look like a cell reference.');
+            }
+            byUpper.set(name.toUpperCase(), { name, refersTo });
+        },
+        remove(name) {
+            byUpper.delete(name.toUpperCase());
+        },
+        has(name) {
+            return byUpper.has(name.toUpperCase());
+        },
+        resolve(name) {
+            const entry = byUpper.get(name.toUpperCase());
+            if (!entry)
+                return null;
+            try {
+                return parseFormula(entry.refersTo);
+            }
+            catch {
+                return null;
+            }
+        },
+        list() {
+            return [...byUpper.values()].sort((a, b) => a.name.localeCompare(b.name));
+        },
+        serialize() {
+            return Object.fromEntries([...byUpper.values()].map((e) => [e.name, e.refersTo]));
+        },
+        hydrate(entries) {
+            byUpper.clear();
+            for (const [name, refersTo] of Object.entries(entries)) {
+                if (isValidName(name))
+                    byUpper.set(name.toUpperCase(), { name, refersTo });
+            }
+        },
+        clear() {
+            byUpper.clear();
+        },
+    };
+    if (initial)
+        api.hydrate(initial);
+    return api;
+}

package/dist/sheet/navigate.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Excel's jump-to-edge navigation, as pure functions over a cell-value lookup.
+ *
+ * `Ctrl+Arrow` is not "move a long way". It is a run-boundary search, and the
+ * rule flips depending on what you are standing on:
+ *
+ *   - Standing on a FILLED cell with a filled neighbour: run to the LAST filled
+ *     cell before the next blank. This is how you get from the top of a column
+ *     to its bottom in one press.
+ *   - Standing on a FILLED cell whose neighbour is blank: skip the blank run
+ *     and land on the NEXT filled cell. This is how you hop between blocks.
+ *   - Standing on a BLANK cell: skip to the next filled cell.
+ *   - Nothing filled ahead in either case: land on the last cell of the sheet
+ *     in that direction, which is what Ctrl+Down does on an empty column.
+ *
+ * Getting this wrong in the obvious way (always run to the end of the filled
+ * block) means the shortcut stops working the moment there is a gap, which is
+ * most real spreadsheets.
+ */
+/** What counts as empty. Excel treats a cell holding an empty string as blank
+ *  for navigation, and so does this: a column of `''` should not trap the
+ *  cursor. A zero, a `false` and a whitespace-only string are all content. */
+export declare function isBlankValue(value: unknown): boolean;
+export type Direction = 'up' | 'down' | 'left' | 'right';
+export type Grid = {
+    rowCount: number;
+    colCount: number;
+    isBlank(row: number, col: number): boolean;
+};
+export type Cell = {
+    row: number;
+    col: number;
+};
+/**
+ * Where `Ctrl+Arrow` lands from `from`, going `dir`. Never returns a cell off
+ * the sheet, and returns `from` unchanged when it is already on the edge.
+ */
+export declare function edgeOfRegion(grid: Grid, from: Cell, dir: Direction): Cell;
+export type Rect = readonly [minRow: number, minCol: number, maxRow: number, maxCol: number];
+/**
+ * Excel's `Ctrl+A` first press: the contiguous block of non-blank cells around
+ * `from`, grown outward until every bounding edge is blank.
+ *
+ * Grown as a rectangle rather than flood-filled, because that is what Excel
+ * selects: a block with a notch in it still comes back as the rectangle that
+ * encloses it. Returns the single cell when `from` sits alone in white space.
+ */
+export declare function currentRegion(grid: Grid, from: Cell): Rect;
+/** Whether `rect` already covers every cell, so `Ctrl+A` should stop growing. */
+export declare function isWholeSheet(grid: Grid, rect: Rect): boolean;
+/** The whole sheet as a rectangle. */
+export declare function wholeSheet(grid: Grid): Rect;