@svgrid/grid 3.0.2 → 3.0.4

package/dist/editing.js

@@ -3,9 +3,12 @@
 // ($state/$derived/$effect) stays in the controller.
 import { parseEditorValue, } from "./index.js";
 import "./sv-grid-scrollbar.js";
-import { getNextActiveCell } from "./keyboard.js";
+import { getEntryStep } from "./keyboard.js";
 import { getCellKey, toValueArray, } from "./SvGrid.helpers.js";
 import { createDataIndexLookup, getColumnBaseValue, isGroupRow, } from "./cell-values.js";
+import { pushHistory, nextGroupId, runHistoryGroup } from "./history.js";
+import { hasGridShortcuts, runGridShortcuts } from "./shortcut-registry.js";
+import { buildCommandContext } from "./command-context.js";
 export function createEditing(ctx) {
     /**
      * Resolve `columnDef.editable` for one row × column pair.
@@ -100,10 +103,27 @@ export function createEditing(ctx) {
             rowRef: row.original,
         };
         ctx.setActiveCell(rowIndex, colIndex);
-        ctx.setSelection(rowIndex, colIndex);
+        selectForEdit(rowIndex, colIndex);
         return true;
     }
+    /**
+     * The selection an edit starts with. A cell already inside the selection
+     * leaves it standing: typing into the active cell of a selected block
+     * used to collapse the block to that one cell, so Enter could never walk
+     * on inside it. A cell outside the selection becomes the selection.
+     */
+    function selectForEdit(rowIndex, colIndex) {
+        if (ctx.isCellInSelectedRange(rowIndex, colIndex))
+            return;
+        ctx.setSelection(rowIndex, colIndex);
+    }
     function saveEditingCell() {
+        // One group: a consumer's onCellValueChange may record a step of its own
+        // (a spreadsheet gives "12%" a percent format as it lands), and that
+        // belongs to the same Ctrl+Z as the value.
+        runHistoryGroup(ctx, () => commitEditingCell());
+    }
+    function commitEditingCell() {
         if (!ctx.editingCell)
             return;
         const editing = ctx.editingCell;
@@ -154,20 +174,7 @@ export function createEditing(ctx) {
                 before: oldValue,
                 after: finalValue,
             };
-            const truncated = ctx.history.slice(0, ctx.historyPtr + 1);
-            truncated.push(step);
-            // Cap the buffer at UNDO_LIMIT; drop the OLDEST entries so the
-            // pointer stays valid relative to the newest steps.
-            if (truncated.length > ctx.UNDO_LIMIT) {
-                const drop = truncated.length - ctx.UNDO_LIMIT;
-                ctx.history = truncated.slice(drop);
-                ctx.historyPtr = ctx.history.length - 1;
-            }
-            else {
-                ctx.history = truncated;
-                ctx.historyPtr = ctx.history.length - 1;
-            }
-            ctx.historyVersion += 1;
+            pushHistory(ctx, [step]);
         }
         // Notify the consumer AFTER the row has been updated so any callback-
         // driven recompute (cascade totals, server save, undo stack) sees the
@@ -187,6 +194,13 @@ export function createEditing(ctx) {
     /** Apply an undo / redo step directly to the underlying row, bypassing
      *  the editor pipeline so we don't accidentally re-push to the stack. */
     function applyHistoryStep(step, direction) {
+        if (step.custom) {
+            if (direction === 'undo')
+                step.custom.undo();
+            else
+                step.custom.redo();
+            return;
+        }
         const row = ctx.allRows.find((r) => r.id === step.rowId);
         const col = ctx.allColumns.find((c) => c.id === step.columnId);
         if (!row?.original || !col)
@@ -217,26 +231,115 @@ export function createEditing(ctx) {
      * move, Tab committed the edit and then let the browser walk focus out of the
      * grid entirely (#48). Shared by every editor type, including the textarea.
      */
-    function commitAndMoveByTab(shiftKey) {
+    /**
+     * Commit the edit and step the cursor the way data entry expects: Tab a
+     * column to the right (wrapping at the row's end), Enter a row down, Shift
+     * reversing either. Enter used to commit and stay, so a column of numbers
+     * took a click or an arrow between every value; Excel and every other
+     * sheet move down, and the accessibility page has always said this grid
+     * does too. At the last row or column the cursor stays put.
+     */
+    function commitAndMove(intent) {
         const active = ctx.activeCell;
         saveEditingCell();
         ctx.gridRootEl?.focus({ preventScroll: true });
         if (!active)
             return;
-        const next = getNextActiveCell(active, shiftKey ? "tabPrev" : "tabNext", {
+        // The same stepping as Enter and Tab on the grid root: a Tab run's Enter
+        // goes back to the run's first column, and a selected block keeps the
+        // cursor inside it.
+        const step = getEntryStep(active, intent, {
             maxRow: ctx.allRows.length - 1,
             maxCol: ctx.allColumns.length - 1,
+            tabOrigin: ctx.tabRunOrigin,
+            range: ctx.activeRangeRect(),
+            collapsed: {
+                isRowCollapsed: (i) => ctx.isRowCollapsed(i),
+                isColumnCollapsed: (i) => !!ctx.collapsedColumns[ctx.allColumns[i]?.id],
+            },
         });
+        const next = step.cell;
         ctx.setActiveCell(next.rowIndex, next.colIndex);
-        ctx.setSelection(next.rowIndex, next.colIndex);
+        ctx.tabRunOrigin = step.tabOrigin;
+        if (!step.withinRange)
+            ctx.setSelection(next.rowIndex, next.colIndex);
         ctx.scrollActiveCellIntoView(next.rowIndex, next.colIndex);
     }
+    function commitAndMoveByTab(shiftKey) {
+        commitAndMove(shiftKey ? "tabPrev" : "tabNext");
+    }
+    /**
+     * Ctrl+Enter: the entry goes into every cell of the selected block and the
+     * cursor stays where it is, as in Excel, where it is how a block is filled
+     * with one value in one go. Each cell takes the same raw entry through the
+     * ordinary commit, so its column's parser, the history and
+     * `onCellValueChange` all see it, and the whole block is one undo. A cell
+     * that cannot be edited is left alone. With nothing but the active cell
+     * selected it is a commit that does not move.
+     */
+    function commitToSelection() {
+        const editing = ctx.editingCell;
+        if (!editing)
+            return;
+        const raw = editing.value;
+        const active = ctx.activeCell;
+        const range = ctx.activeRangeRect();
+        runHistoryGroup(ctx, () => {
+            commitEditingCell();
+            if (!active || !range)
+                return;
+            for (let r = range.minRow; r <= range.maxRow; r += 1) {
+                for (let c = range.minCol; c <= range.maxCol; c += 1) {
+                    if (r === active.rowIndex && c === active.colIndex)
+                        continue;
+                    const row = ctx.allRows[r];
+                    const column = ctx.allColumns[c];
+                    if (!row || !column || isGroupRow(row) || !isCellEditable(column, row))
+                        continue;
+                    ctx.editingCell = {
+                        rowId: row.id,
+                        columnId: column.id,
+                        editorType: (column.columnDef.editorType ?? "text"),
+                        value: raw,
+                        rowRef: row.original,
+                    };
+                    commitEditingCell();
+                }
+            }
+        });
+        ctx.gridRootEl?.focus({ preventScroll: true });
+    }
     function onEditorKeyDown(event) {
         event.stopPropagation();
-        if (event.key === "Enter") {
+        // Registered commands get the key first here too, with `editing: true`, so
+        // a handler can claim a combination that only means something mid-edit
+        // (Alt+Enter for a newline, F4 to cycle a reference between relative and
+        // absolute) before the editor's own Enter / Tab / Escape handling runs.
+        if (hasGridShortcuts() && runGridShortcuts(event, buildCommandContext(ctx, true))) {
+            return;
+        }
+        if (event.key === "Enter" && event.altKey) {
+            // A line break, in an editor that can hold one (`editorMultiline`).
+            // In a single-line editor Alt+Enter is just Enter.
+            const el = event.currentTarget;
+            if (el instanceof HTMLTextAreaElement) {
+                event.preventDefault();
+                const start = el.selectionStart ?? el.value.length;
+                const end = el.selectionEnd ?? start;
+                el.value = el.value.slice(0, start) + "\n" + el.value.slice(end);
+                el.selectionStart = el.selectionEnd = start + 1;
+                updateEditingCellValue(el.value);
+                el.dispatchEvent(new Event("input", { bubbles: true }));
+                return;
+            }
+        }
+        if (event.key === "Enter" && (event.ctrlKey || event.metaKey)) {
             event.preventDefault();
-            saveEditingCell();
-            ctx.gridRootEl?.focus({ preventScroll: true });
+            commitToSelection();
+        }
+        else if (event.key === "Enter") {
+            event.preventDefault();
+            commitAndMove(event.shiftKey ? "moveUp" : "moveDown");
         }
         else if (event.key === "Tab") {
             event.preventDefault();
@@ -316,7 +419,7 @@ export function createEditing(ctx) {
             rowRef: row.original,
         };
         ctx.setActiveCell(rowIndex, colIndex);
-        ctx.setSelection(rowIndex, colIndex);
+        selectForEdit(rowIndex, colIndex);
     }
     async function pasteFromClipboard() {
         // Preferred path: the async Clipboard API. Requires a secure context
@@ -325,6 +428,34 @@ export function createEditing(ctx) {
         // On plain HTTP (a XAMPP/Apache LAN host) `navigator.clipboard` is
         // undefined - there the Ctrl+V keydown handler skips preventDefault and
         // lets the browser deliver a native `paste` event to `onGridPaste`.
+        if (ctx.props.onPasteClipboard && navigator.clipboard?.read) {
+            // Both types, for a handler that reads the HTML.
+            try {
+                const items = await navigator.clipboard.read();
+                let text = "";
+                let html = null;
+                for (const item of items) {
+                    if (item.types.includes("text/html"))
+                        html = await (await item.getType("text/html")).text();
+                    if (item.types.includes("text/plain"))
+                        text = await (await item.getType("text/plain")).text();
+                }
+                if (text || html)
+                    applyPastedPayload({ text, html, source: "async" });
+            }
+            catch {
+                // No permission or nothing readable: the text-only read below may still work.
+                if (!navigator.clipboard.readText)
+                    return;
+                try {
+                    applyPastedPayload({ text: await navigator.clipboard.readText(), html: null, source: "async" });
+                }
+                catch {
+                    return;
+                }
+            }
+            return;
+        }
         if (!navigator.clipboard?.readText)
             return;
         let text;
@@ -336,6 +467,27 @@ export function createEditing(ctx) {
         }
         applyPastedText(text);
     }
+    /**
+     * With `onPasteClipboard` set, Ctrl+V leaves the key to the browser so the
+     * `paste` event arrives with the HTML. A browser that does not deliver
+     * that event to the grid root (Firefox, a non-editable element) would
+     * paste nothing, so the async read is armed to run shortly after unless
+     * the event lands first and disarms it.
+     */
+    let pasteFallback = null;
+    function armPasteFallback() {
+        if (pasteFallback)
+            clearTimeout(pasteFallback);
+        pasteFallback = setTimeout(() => {
+            pasteFallback = null;
+            void pasteFromClipboard();
+        }, 80);
+    }
+    function disarmPasteFallback() {
+        if (pasteFallback)
+            clearTimeout(pasteFallback);
+        pasteFallback = null;
+    }
     /**
      * Native `paste` ClipboardEvent fallback (insecure-context path). A real
      * Ctrl/Cmd+V on the focused grid root fires this with `clipboardData`
@@ -351,6 +503,18 @@ export function createEditing(ctx) {
         // so the edit "wouldn't update".
         if (ctx.editingCell)
             return;
+        if (ctx.props.onPasteClipboard) {
+            // The event is the preferred path for a handler: it carries the HTML
+            // as the source wrote it, needs no permission, and works over HTTP.
+            disarmPasteFallback();
+            const text = event.clipboardData?.getData("text/plain") ?? "";
+            const html = event.clipboardData?.getData("text/html") || null;
+            if (!text && !html)
+                return;
+            event.preventDefault();
+            applyPastedPayload({ text, html, source: "event" });
+            return;
+        }
         // When the async API is available the keydown handler already pasted via
         // pasteFromClipboard(); ignore the (suppressed) native event so we don't
         // paste twice.
@@ -363,6 +527,22 @@ export function createEditing(ctx) {
         applyPastedText(text);
     }
     function applyPastedText(text) {
+        // One history group for the whole paste, so whatever a consumer's
+        // processCellFromClipboard records alongside the values (a format, via
+        // recordUndo) comes back with them on a single Ctrl+Z.
+        runHistoryGroup(ctx, () => applyPastedCells(text));
+    }
+    /** A paste with both types: the handler first, the plain text otherwise. */
+    function applyPastedPayload(payload) {
+        runHistoryGroup(ctx, () => {
+            const handled = ctx.props.onPasteClipboard?.(payload);
+            if (handled === true)
+                return;
+            if (payload.text)
+                applyPastedCells(payload.text);
+        });
+    }
+    function applyPastedCells(text) {
         const anchor = ctx.selectionRange.anchor ?? ctx.grid.getState().activeCell;
         if (!anchor)
             return;
@@ -390,6 +570,12 @@ export function createEditing(ctx) {
             : Math.max(...lines.map((l) => l.split("\t").length));
         const next = ctx.internalData.slice();
         const dataIndexOf = createDataIndexLookup(next);
+        // Every cell the paste changes: one grouped history entry for the lot,
+        // so Ctrl+Z takes the whole paste back, and one onCellValueChange each,
+        // so a consumer keeping its own model behind the grid (a formula engine)
+        // learns the values. The loop used to swap the rows in and stop, which
+        // left the undo stack blind to a paste and the consumer never told.
+        const changed = [];
         for (let i = 0; i < rowSpan; i += 1) {
             const targetRowIndex = startRow + i;
             const row = ctx.allRows[targetRowIndex];
@@ -409,23 +595,69 @@ export function createEditing(ctx) {
             const updated = {
                 ...originalRow,
             };
+            const rowChanges = [];
+            const record = (column, before, after) => {
+                if (before === after)
+                    return;
+                rowChanges.push({
+                    row: updated, rowId: row.id, rowIndex: dataIndex, columnId: column.id,
+                    field: column.columnDef.field, before, after,
+                });
+            };
             for (let j = 0; j < colSpan; j += 1) {
                 const column = ctx.allColumns[startCol + j];
                 if (!column?.columnDef.field)
                     continue;
                 if (!isCellEditableAt(targetRowIndex, startCol + j))
                     continue;
+                const before = updated[column.columnDef.field];
                 const editorType = (column.columnDef.editorType ??
                     "text");
                 const raw = fillRange ? lines[0] : sourceCells?.[j] ?? "";
-                updated[column.columnDef.field] = parseEditorValue(editorType, raw, {
+                const parsedValue = parseEditorValue(editorType, raw, {
                     dateOnly: column.columnDef.cellDataType === "dateString",
                 });
+                // The inbound half of the clipboard pair. A consumer (or a feature
+                // pack doing paste-special) gets the raw text AND what the grid would
+                // have written, and can return either. `undefined` leaves the cell
+                // alone, which is how "paste values only" skips a formula column.
+                const hook = ctx.props.processCellFromClipboard;
+                if (hook) {
+                    const decided = hook({
+                        text: raw,
+                        parsedValue,
+                        row: originalRow,
+                        rowIndex: targetRowIndex,
+                        columnId: column.id,
+                    });
+                    if (decided === undefined)
+                        continue;
+                    updated[column.columnDef.field] = decided;
+                    record(column, before, decided);
+                    continue;
+                }
+                updated[column.columnDef.field] = parsedValue;
+                record(column, before, parsedValue);
             }
+            if (!rowChanges.length)
+                continue;
             next[dataIndex] = updated;
+            changed.push(...rowChanges);
         }
+        if (!changed.length)
+            return;
         ctx.internalData = next;
         ctx.grid.store.setState((prev) => ({ ...prev }));
+        pushHistory(ctx, changed.map((c) => ({
+            rowId: c.rowId, columnId: c.columnId, field: c.field, before: c.before, after: c.after,
+        })), nextGroupId());
+        if (ctx.props.onCellValueChange) {
+            for (const c of changed) {
+                ctx.props.onCellValueChange({
+                    rowIndex: c.rowIndex, columnId: c.columnId, oldValue: c.before, newValue: c.after, row: c.row,
+                });
+            }
+        }
     }
     /** Programmatically begin editing a cell (mirrors a double-click). */
     function startEditing(rowIndex, columnId) {
@@ -531,15 +763,11 @@ export function createEditing(ctx) {
         }
         // Record the whole-row change as consecutive history steps.
         if (changed.length) {
-            let hist = ctx.history.slice(0, ctx.historyPtr + 1);
-            for (const c of changed) {
-                hist.push({ rowId: fr.rowId, columnId: c.columnId, field: c.field, before: c.before, after: c.after });
-            }
-            if (hist.length > ctx.UNDO_LIMIT)
-                hist = hist.slice(hist.length - ctx.UNDO_LIMIT);
-            ctx.history = hist;
-            ctx.historyPtr = ctx.history.length - 1;
-            ctx.historyVersion += 1;
+            // One full-row commit is ONE undo, not one per changed column.
+            pushHistory(ctx, changed.map((c) => ({
+                rowId: fr.rowId, columnId: c.columnId, field: c.field,
+                before: c.before, after: c.after,
+            })), nextGroupId());
         }
         ctx.grid.store.setState((prev) => ({ ...prev }));
         if (ctx.props.onCellValueChange && changed.length) {
@@ -581,5 +809,6 @@ export function createEditing(ctx) {
         onCellDoubleClick,
         pasteFromClipboard,
         onGridPaste,
+        armPasteFallback,
     };
 }

package/dist/fill-patterns.d.ts

@@ -22,9 +22,4 @@
  * A single source value falls through to the cycle case (repeats), which
  * matches Excel's default fill behavior.
  */
-/**
- * Compute the values to write into `targetCount` new cells given the
- * `sourceValues` already in the selection. See module header for the
- * pattern-detection rules.
- */
 export declare function buildFillPattern(sourceValues: ReadonlyArray<unknown>, targetCount: number): unknown[];

package/dist/fill-patterns.js

@@ -149,10 +149,48 @@ function arithmeticStep(nums) {
  * `sourceValues` already in the selection. See module header for the
  * pattern-detection rules.
  */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * The sources as day stamps when every one is a date: `Date` objects, or
+ * `YYYY-MM-DD` text (read as UTC so a fill never crosses a day boundary
+ * with the time zone). Anything else means "not a date series".
+ */
+function datesOf(values) {
+    if (values.every((v) => v instanceof Date && Number.isFinite(v.getTime()))) {
+        return { stamps: values.map((v) => v.getTime()), iso: false };
+    }
+    if (values.every((v) => typeof v === 'string' && ISO_DATE.test(v))) {
+        const stamps = values.map((v) => Date.parse(`${v}T00:00:00Z`));
+        return stamps.every((t) => Number.isFinite(t)) ? { stamps, iso: true } : null;
+    }
+    return null;
+}
 export function buildFillPattern(sourceValues, targetCount) {
     if (sourceValues.length === 0 || targetCount <= 0)
         return [];
-    // -------- 1) Numeric arithmetic progression (2+ values) -----------
+    // -------- 0) Dates step by the day ---------------------------------
+    // Before the numeric rule, since a Date coerces to a finite number of
+    // milliseconds, and before the prefix rule, which read 2024-01-15 as the
+    // number 2024 with a suffix and filled 2025-01-15. Two dates set the step
+    // (a week apart fills weekly); one date steps by a day, as Excel's does.
+    const dates = datesOf(sourceValues);
+    if (dates) {
+        const DAY = 86400000;
+        const days = dates.stamps.map((t) => Math.round(t / DAY));
+        const step = days.length >= 2 ? arithmeticStep(days) : 1;
+        if (step !== null) {
+            const last = days[days.length - 1];
+            return Array.from({ length: targetCount }, (_, i) => {
+                const stamp = (last + step * (i + 1)) * DAY;
+                return dates.iso ? new Date(stamp).toISOString().slice(0, 10) : new Date(stamp);
+            });
+        }
+    }
+    // -------- 1) Numbers: the linear trend (2+ values) -----------------
+    // Excel's AutoFill of two or more numbers continues their least-squares
+    // line: 1, 2, 3 goes on 4, 5, 6, and 1, 2, 4 goes on 5.33, 6.83, ...
+    // rather than repeating. An even step is the same line, so the common
+    // case is unchanged.
     const nums = sourceValues.map((v) => Number(v));
     const allNumericLike = sourceValues.every((v) => v !== null && v !== '' && v !== undefined) &&
         nums.every((n) => Number.isFinite(n));
@@ -162,6 +200,20 @@ export function buildFillPattern(sourceValues, targetCount) {
             const last = nums[nums.length - 1];
             return Array.from({ length: targetCount }, (_, i) => last + step * (i + 1));
         }
+        const n = nums.length;
+        const meanX = (n - 1) / 2;
+        const meanY = nums.reduce((a, b) => a + b, 0) / n;
+        let sxy = 0;
+        let sxx = 0;
+        for (let i = 0; i < n; i += 1) {
+            sxy += (i - meanX) * (nums[i] - meanY);
+            sxx += (i - meanX) ** 2;
+        }
+        const slope = sxx === 0 ? 0 : sxy / sxx;
+        const intercept = meanY - slope * meanX;
+        // Rounded to the precision floating point gives 5.333333333333333, so
+        // 10, 20, 40 fills 50, 60 and not 50.00000000000001.
+        return Array.from({ length: targetCount }, (_, i) => Number((intercept + slope * (n + i)).toPrecision(15)));
     }
     // -------- 2) Known string sequence (days / months / quarters) -----
     const allStrings = sourceValues.every((v) => typeof v === 'string');
@@ -179,7 +231,9 @@ export function buildFillPattern(sourceValues, targetCount) {
     if (allStrings && sourceValues.length >= 1) {
         const stringSources = sourceValues;
         const split = findPrefixNumberSuffix(stringSources);
-        if (split) {
+        // A bare number as text ('5') is a number, not 'Item 5': one of them
+        // copies, as a numeric 5 does, and two or more were a progression above.
+        if (split && (split.prefix !== '' || split.suffix !== '')) {
             const step = split.numbers.length >= 2
                 ? arithmeticStep(split.numbers) ?? 1
                 : 1;

package/dist/grid-messages.d.ts

@@ -1,5 +1,12 @@
+import type { GridChartPanelMessages } from './chart-panel-messages.js';
+/**
+ * Every string `localization.text` accepts: the grid chrome's own
+ * ({@link GridChromeMessages}) and the chart panel's
+ * ({@link GridChartPanelMessages}).
+ */
+export type GridMessages = GridChromeMessages & GridChartPanelMessages;
 /** Every localizable chrome string, grouped by area in the comments. */
-export type GridMessages = {
+export type GridChromeMessages = {
     noRows: string;
     loading: string;
     columns: string;
@@ -74,10 +81,10 @@ export type GridMessages = {
     upsellLicenseLink: string;
 };
 /** English defaults - the literal strings the grid shipped before localization. */
-export declare const defaultGridMessages: GridMessages;
+export declare const defaultGridMessages: GridChromeMessages;
 /**
  * Merge a consumer's `localeText` over the English defaults. Undefined/empty
  * values fall back to the default (via `resolveMessages`), so a partial map only
  * replaces the keys it sets.
  */
-export declare function resolveGridMessages(overrides?: Partial<GridMessages> | null): GridMessages;
+export declare function resolveGridMessages(overrides?: Partial<GridMessages> | null): GridChromeMessages;

package/dist/grid-messages.js

@@ -7,6 +7,11 @@
  *
  * This mirrors the editor kit's `resolveMessages` pattern (editor-contract.ts) so
  * chrome and editors share one localization idiom.
+ *
+ * The chart panel's strings are the other half of `GridMessages`
+ * (`GridChartPanelMessages` in chart-panel-messages.ts): same map, same
+ * `localization.text`, but their English defaults load with the panel, not
+ * with every grid.
  */
 import { resolveMessages } from './editor-contract.js';
 /** English defaults - the literal strings the grid shipped before localization. */

package/dist/history.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Undo / redo over the grid's history array, group-aware.
+ *
+ * The history is one ordered array of per-cell steps plus a pointer to the
+ * last applied step (the model lives in SvGrid.controller.svelte.ts). A step
+ * describes ONE cell, which is right for a single edit and wrong for anything
+ * that writes many cells at once: `applyMoveRange` in clipboard.ts pushes one
+ * step per moved cell, so undoing a 15x20 range move takes 300 presses of
+ * Ctrl+Z, and with UNDO_LIMIT at 200 the same move evicts the entire history
+ * behind it.
+ *
+ * `groupId` fixes that without changing the storage model. Steps written
+ * inside one logical action share an id; undo and redo walk the whole run of
+ * steps carrying that id and apply them together, so a paste, a fill-down or
+ * a range move is one press, the way it is in a spreadsheet. Steps with no
+ * groupId behave exactly as before, one step per press.
+ *
+ * Undo applies a group in REVERSE order. Two steps that touched the same cell
+ * inside one action have to be unwound newest-first or the older `before`
+ * value is overwritten by the newer one and the cell lands on the wrong value.
+ */
+export type HistoryStep = {
+    rowId: string;
+    columnId: string;
+    field: string;
+    before: unknown;
+    after: unknown;
+    /** Set when this step is part of a multi-cell action. Steps sharing an id
+     *  are contiguous in the array and undo / redo as one. */
+    groupId?: string;
+    /**
+     * A step that is not a cell write: something outside the grid's data that
+     * still belongs in the same Ctrl+Z stream, such as a cell format kept in a
+     * consumer's store. The cell fields are empty on such a step and the two
+     * functions do the work. Never serialised, since a closure cannot be.
+     */
+    custom?: {
+        undo: () => void;
+        redo: () => void;
+    };
+};
+/** Ctx surface these helpers touch. The controller satisfies it structurally. */
+type HistoryCtx = {
+    history: HistoryStep[];
+    historyPtr: number;
+    historyVersion: number;
+    UNDO_LIMIT: number;
+    /** Set while a `runHistoryGroup` call is on the stack. Every step pushed
+     *  inside it joins that group, so a command does not have to thread a group
+     *  id down through the writers it calls. */
+    historyGroupId: string | undefined;
+    applyHistoryStep(step: HistoryStep, direction: 'undo' | 'redo'): void;
+};
+/** Undo one action. Returns false when there is nothing left to undo. */
+export declare function undoHistory(ctx: HistoryCtx): boolean;
+/** Redo one action. Returns false when there is nothing left to redo. */
+export declare function redoHistory(ctx: HistoryCtx): boolean;
+/**
+ * Append steps at the pointer, truncating any forward history (the standard
+ * "an edit invalidates redo" rule) and capping the buffer at UNDO_LIMIT by
+ * dropping the OLDEST entries.
+ *
+ * Every writer goes through here rather than open-coding the slice / push /
+ * cap dance, which editing.ts and clipboard.ts previously did three times
+ * with three slightly different shapes.
+ */
+export declare function pushHistory(ctx: HistoryCtx, steps: ReadonlyArray<HistoryStep>, groupId?: string): void;
+/** A fresh group id. Monotonic, not random: ids never leave the session and a
+ *  counter is comparable in a test snapshot. */
+export declare function nextGroupId(): string;
+/**
+ * Run `fn` with every history step it writes tagged as one undoable action.
+ *
+ * This is ambient rather than a wrapper that re-tags afterwards, because
+ * `pushHistory` can drop the oldest entries when the buffer hits UNDO_LIMIT.
+ * A re-tagging implementation would compute its slice bounds from a length
+ * that had shifted underneath it and stamp the wrong steps.
+ *
+ * Nested calls join the outer group: one user action is one undo, however many
+ * layers of helper it goes through.
+ */
+export declare function runHistoryGroup<T>(ctx: HistoryCtx, fn: () => T): T;
+export {};