@svgrid/enterprise 3.0.1 → 3.0.2

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;

package/dist/sheet/navigate.js

@@ -0,0 +1,135 @@
+/**
+ * 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 function isBlankValue(value) {
+    return value === null || value === undefined || value === '';
+}
+const STEP = {
+    up: { row: -1, col: 0 },
+    down: { row: 1, col: 0 },
+    left: { row: 0, col: -1 },
+    right: { row: 0, col: 1 },
+};
+function inBounds(grid, row, col) {
+    return row >= 0 && row < grid.rowCount && col >= 0 && col < grid.colCount;
+}
+/** The last cell in `dir` that is still on the sheet. */
+function lastInDirection(grid, from, dir) {
+    switch (dir) {
+        case 'up': return { row: 0, col: from.col };
+        case 'down': return { row: Math.max(grid.rowCount - 1, 0), col: from.col };
+        case 'left': return { row: from.row, col: 0 };
+        case 'right': return { row: from.row, col: Math.max(grid.colCount - 1, 0) };
+    }
+}
+/**
+ * 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 function edgeOfRegion(grid, from, dir) {
+    if (grid.rowCount === 0 || grid.colCount === 0)
+        return from;
+    const step = STEP[dir];
+    const first = { row: from.row + step.row, col: from.col + step.col };
+    if (!inBounds(grid, first.row, first.col))
+        return from;
+    const startFilled = !grid.isBlank(from.row, from.col);
+    const nextFilled = !grid.isBlank(first.row, first.col);
+    if (startFilled && nextFilled) {
+        // Run to the last filled cell before the next blank.
+        let cur = first;
+        for (;;) {
+            const ahead = { row: cur.row + step.row, col: cur.col + step.col };
+            if (!inBounds(grid, ahead.row, ahead.col) || grid.isBlank(ahead.row, ahead.col))
+                return cur;
+            cur = ahead;
+        }
+    }
+    // Otherwise skip ahead to the next filled cell.
+    let cur = first;
+    for (;;) {
+        if (!grid.isBlank(cur.row, cur.col))
+            return cur;
+        const ahead = { row: cur.row + step.row, col: cur.col + step.col };
+        // Nothing filled the whole way: Excel parks you on the last cell.
+        if (!inBounds(grid, ahead.row, ahead.col))
+            return lastInDirection(grid, from, dir);
+        cur = ahead;
+    }
+}
+/**
+ * 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 function currentRegion(grid, from) {
+    if (grid.rowCount === 0 || grid.colCount === 0)
+        return [0, 0, 0, 0];
+    let minRow = from.row;
+    let maxRow = from.row;
+    let minCol = from.col;
+    let maxCol = from.col;
+    const edgeHasContent = (r0, r1, c0, c1) => {
+        for (let r = r0; r <= r1; r += 1) {
+            for (let c = c0; c <= c1; c += 1) {
+                if (inBounds(grid, r, c) && !grid.isBlank(r, c))
+                    return true;
+            }
+        }
+        return false;
+    };
+    // Keep growing while any bounding edge still touches content. One side
+    // growing can expose content on another, so this repeats until stable.
+    for (let grew = true; grew;) {
+        grew = false;
+        if (minRow > 0 && edgeHasContent(minRow - 1, minRow - 1, minCol, maxCol)) {
+            minRow -= 1;
+            grew = true;
+        }
+        if (maxRow < grid.rowCount - 1 && edgeHasContent(maxRow + 1, maxRow + 1, minCol, maxCol)) {
+            maxRow += 1;
+            grew = true;
+        }
+        if (minCol > 0 && edgeHasContent(minRow, maxRow, minCol - 1, minCol - 1)) {
+            minCol -= 1;
+            grew = true;
+        }
+        if (maxCol < grid.colCount - 1 && edgeHasContent(minRow, maxRow, maxCol + 1, maxCol + 1)) {
+            maxCol += 1;
+            grew = true;
+        }
+    }
+    return [minRow, minCol, maxRow, maxCol];
+}
+/** Whether `rect` already covers every cell, so `Ctrl+A` should stop growing. */
+export function isWholeSheet(grid, rect) {
+    return (rect[0] === 0 && rect[1] === 0 &&
+        rect[2] === Math.max(grid.rowCount - 1, 0) &&
+        rect[3] === Math.max(grid.colCount - 1, 0));
+}
+/** The whole sheet as a rectangle. */
+export function wholeSheet(grid) {
+    return [0, 0, Math.max(grid.rowCount - 1, 0), Math.max(grid.colCount - 1, 0)];
+}

package/dist/sheet/number-format.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Excel number-format strings, compiled once and applied many times.
+ *
+ * The grammar is small but full of traps, so this file is explicit about the
+ * ones that bite:
+ *
+ *   - A pattern has up to four sections separated by `;`:
+ *     positive;negative;zero;text. With two, the second covers negatives AND
+ *     zero. With one, it covers everything. A negative rendered by section two
+ *     uses its ABSOLUTE value, which is why `0.00;(0.00)` shows `(1.50)` and
+ *     not `(-1.50)`.
+ *   - `,` means two different things. Between placeholders it is a thousands
+ *     separator; immediately before the decimal point (or at the end) it scales
+ *     the number down by a thousand per comma.
+ *   - `%` scales UP by 100 and prints a literal percent.
+ *   - `0` prints a digit or a zero, `#` prints a digit or nothing, `?` prints a
+ *     digit or a space. They can be mixed: `#,##0.0#` keeps one decimal always
+ *     and a second only when it is there.
+ *   - Anything in quotes, after a backslash, or in the set of always-literal
+ *     characters is emitted as-is.
+ *   - `[Red]` and friends set a colour rather than printing.
+ *   - `@` is the text placeholder and only appears in the fourth section.
+ *
+ * Dates are detected rather than configured: a pattern containing date tokens
+ * outside quotes is a date pattern. `m` is minutes when it follows an hour
+ * token and months otherwise, which is the one piece of context the token
+ * scanner has to carry.
+ */
+export type CompiledFormat = {
+    /** Render a value. `color` is set when the matching section named one. */
+    format(value: unknown): {
+        text: string;
+        color?: string;
+    };
+    /** The pattern this was compiled from, for round-tripping to xlsx. */
+    readonly pattern: string;
+};
+export declare function compileNumberFormat(pattern: string): CompiledFormat;
+/** Format one value against a pattern. Convenience over compile-then-call. */
+export declare function formatWithPattern(value: unknown, pattern: string): string;
+/** The presets behind Ctrl+Shift+1 through 6. */
+export declare const FORMAT_PRESETS: {
+    readonly general: "General";
+    readonly number: "#,##0.00";
+    readonly time: "h:mm AM/PM";
+    readonly date: "yyyy-mm-dd";
+    readonly currency: "$#,##0.00;($#,##0.00)";
+    readonly percent: "0.00%";
+    readonly scientific: "0.00E+00";
+};
+export type FormatPresetName = keyof typeof FORMAT_PRESETS;
+/**
+ * Which of Excel's categories a pattern belongs to, with the decimals and
+ * separator it carries, so the ribbon's combo can say "Percentage" for a
+ * cell holding `0%` (a typed 12%) as well as for the preset's `0.00%`, and
+ * Format Cells can open on the right category. A pattern that is none of
+ * them is 'custom'.
+ */
+export declare function formatCategory(fmt: string | undefined): {
+    category: FormatPresetName | 'custom';
+    decimals: number;
+    thousands: boolean;
+};