@rowsncolumns/rnc-engine 0.11.9 → 1.1.0

package/dist/esm/use-engine-core.js

@@ -1,11 +1,11 @@
 // Lightweight dependency-graph NODE classes (data holders — NOT the JS calculator) used to shape the
 // real `getPrecedents`/`getDependents` results, which the engine now backs with actual graph data.
 import { CellNode, CellRangeNode, isCellCoordinate, isCellNode, makeKey, } from "@rowsncolumns/dag";
-import { DEFAULT_ACTIVE_CELL, DEFAULT_ARRAY, defaultSpreadsheetTheme, getBandedCells, getInitialActiveSheetId, ICON_SET_COLORS, ICON_SET_GLYPHS, useFonts, } from "@rowsncolumns/spreadsheet";
-import { applyAdvancedFilterPlan, applySubtotalPlan, CellXfsRegistry, collectPaintMerges, generateDataFromClipboard, getBandedCellFormat, isStyleReference, layerBandedFormat, paintSourceForActiveCell, pickFormula, pickValue, planAdvancedFilter, planSubtotals, resolvePasteSpecialOptions, SharedStringRegistry, spreadMergeAnchorFormats, STRUCTURAL_REFUSAL_MESSAGES, STRUCTURAL_REFUSAL_TITLE, tilePaintMerges, transpose, useOnCopy, useOnTraceDependentsPrecedents, useShowError, } from "@rowsncolumns/spreadsheet-state";
-import { getCellUserEnteredFormat, getCellUserEnteredValue, getExtendedValueBool, getExtendedValueFormula, getExtendedValueNumber, getExtendedValueString, normalizeExternalUrl, resolveDefaultHorizontalAlignment, } from "@rowsncolumns/utils";
+import { DEFAULT_ACTIVE_CELL, DEFAULT_ARRAY, defaultSpreadsheetTheme, getBandedCells, getInitialActiveSheetId, ICON_SET_COLORS, ICON_SET_GLYPHS, useFocusEmbedOrChart, useFonts, useSetTableAutoExpansion, useSetCalculatedColumnFill, } from "@rowsncolumns/spreadsheet";
+import { applyAdvancedFilterPlan, applySubtotalPlan, CellXfsRegistry, collectPaintMerges, generateDataFromClipboard, getBandedCellFormat, isStyleReference, layerBandedFormat, paintSourceForActiveCell, pickFormula, pickValue, planAdvancedFilter, planSubtotals, resolvePasteSpecialOptions, SharedStringRegistry, spreadMergeAnchorFormats, tilePaintMerges, transpose, useOnCopy, previewTableStyle, useOnTraceDependentsPrecedents, useShowError, } from "@rowsncolumns/spreadsheet-state";
+import { getCellUserEnteredFormat, getCellUserEnteredValue, getExtendedValueBool, getExtendedValueFormula, getExtendedValueNumber, getExtendedValueString, getFormulaLocale, normalizeExternalUrl, resolveDefaultHorizontalAlignment, } from "@rowsncolumns/utils";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { createCommandHandlers, } from "./command-handlers";
+import { createCommandHandlers, rejectionDialog, } from "./command-handlers";
 import { emptyRenderState, foldCommit, foldCommitStructuralOnly, foldWindow, foldWindows, frozenBandRanges, reconcileSheets, } from "./fold";
 import { RncEngine, } from "./index";
 import { cellKey, parseCellKey } from "./keys";
@@ -140,6 +140,7 @@ const EMPTY_FACETS = {
     embeds: [],
     slicers: [],
     bandedRanges: [],
+    customTableStyles: [],
     protectedRanges: [],
     basicFilters: [],
     citations: [],
@@ -252,9 +253,6 @@ function parseInternalLocation(location) {
         },
     };
 }
-/** The rnc engine's structural-edit refusals (`off-sheet-push`, `torn-merge`, `torn-table`,
- * `torn-array`) — the codes the legacy engine's `constants.ts` defines, surfaced as a dialog. */
-const isStructuralRejection = (rejection) => rejection.code in STRUCTURAL_REFUSAL_MESSAGES;
 // `useEngineCore` is the engine-only surface (data / calc / commands / accessors) — NOT a standalone
 // drop-in for `useSpreadsheetState`. The chrome (dialogs + host intents) lives in `useSpreadsheetUI`;
 // the drop-in parity lock is asserted on their composition, `useSpreadsheetEngine`.
@@ -284,6 +282,7 @@ export function useEngineCore(options) {
     const onCustomEvalCancelRef = useRef(options.onCustomEvalCancel);
     onCustomEvalCancelRef.current = options.onCustomEvalCancel;
     const showError = useShowError();
+    const focusEmbedOrChart = useFocusEmbedOrChart();
     // Latest-refs for the streaming batch-write observers (identities may change every render).
     const onStreamStartRef = useRef(options.onStreamStart);
     onStreamStartRef.current = options.onStreamStart;
@@ -313,6 +312,16 @@ export function useEngineCore(options) {
     stateSheetsRef.current = state.sheets;
     const customAutofillListsRef = useRef(options.customAutofillLists);
     customAutofillListsRef.current = options.customAutofillLists;
+    const autoExpandTablesRef = useRef(options.autoExpandTables);
+    autoExpandTablesRef.current = options.autoExpandTables;
+    const autoCalculatedColumnsRef = useRef(options.autoCalculatedColumns);
+    autoCalculatedColumnsRef.current = options.autoCalculatedColumns;
+    // Excel's AutoCorrect smart tag after a table auto-expanded — armed from the commit's
+    // `tableAutoExpansion` record when a value-writing command grew a table; `CanvasGrid` renders it.
+    const setTableAutoExpansion = useSetTableAutoExpansion();
+    // Excel's AutoCorrect smart tag after a formula typed into a table column — armed from the
+    // commit's `calculatedColumnFill` record; `CanvasGrid` renders it.
+    const setCalculatedColumnFill = useSetCalculatedColumnFill();
     // One windowed read = the buffered window + the sheet's frozen bands + the sheet's active cell
     // (pinned so the formula bar's active-cell read survives scrolling it out of the window — see
     // `readWindowWithFrozenBands`). Frozen counts come from the host's getter when provided (see
@@ -412,6 +421,7 @@ export function useEngineCore(options) {
     // The initial sheets/document are creation-time inputs; capture them so the effect runs once and
     // doesn't tear the engine down on every render.
     const initial = useRef(options);
+    const formulaLocale = useMemo(() => getFormulaLocale(options.formulaLocale ?? options.locale), [options.formulaLocale, options.locale]);
     useEffect(() => {
         let alive = true;
         let unsubscribe = () => { };
@@ -652,6 +662,12 @@ export function useEngineCore(options) {
         const preview = streamPreviewRef.current;
         if (!preview?.size)
             return;
+        // A batch retires what each of its members covers.
+        if (command.command === "batch") {
+            for (const member of command.commands)
+                retireStreamPreviewForCommand(member);
+            return;
+        }
         const cmd = command;
         if (cmd.command === "change-theme")
             return;
@@ -686,10 +702,16 @@ export function useEngineCore(options) {
     sheetDataRef.current = state.sheetData;
     const committedFvAt = useCallback((sheetId, rowIndex, columnIndex) => sheetDataRef.current?.[sheetId]?.[rowIndex]?.values?.[columnIndex]?.fv ??
         undefined, []);
+    // Commands issued while a `batchHistory` action runs, applied together when it returns.
+    const batchCommandsRef = useRef(null);
     const onCommand = useCallback((command) => {
         const engine = engineRef.current;
         if (!engine)
             return;
+        if (batchCommandsRef.current) {
+            batchCommandsRef.current.push(command);
+            return;
+        }
         // The host's apply (or any other local write) is the authority — retire the preview for the cells
         // it covers in this same render, so the committed value replaces the previewed one with no blank
         // frame in between.
@@ -704,12 +726,22 @@ export function useEngineCore(options) {
         // Snapshot the view BEFORE applying — that's where undo should return the user.
         const before = viewRef.current;
         const commit = engine.applyCommand(command);
-        // Excel's structural refusals (rowsncolumns/spreadsheet#647): the engine wrote nothing — show
-        // the user Excel's dialog text through the same channel the legacy engine's hooks use
-        // (`useShowError`). Other refusals keep riding `commit.rejections` to the command handlers.
+        // A value-writing command grew a table over the written cells: arm the AutoCorrect smart tag
+        // with the engine's record of the growth (rowsncolumns/spreadsheet#668 T-12) — "Undo Table
+        // AutoExpansion" resizes back and clears the cells the growth wrote (`writes`, T-89).
+        if (commit.tableAutoExpansion) {
+            setTableAutoExpansion(commit.tableAutoExpansion);
+        }
+        if (commit.calculatedColumnFill) {
+            setCalculatedColumnFill(commit.calculatedColumnFill);
+        }
+        // A refusal wrote nothing — show the user Excel's dialog text through the same channel the
+        // legacy engine's hooks use (`useShowError`), once: `createCommandHandlers` skips the
+        // refusals that have a dialog here. The rest keep riding `commit.rejections` to it.
         for (const rejection of commit.rejections ?? []) {
-            if (isStructuralRejection(rejection)) {
-                showError({ title: STRUCTURAL_REFUSAL_TITLE, message: rejection.message });
+            const dialog = rejectionDialog(rejection);
+            if (dialog) {
+                showError(dialog);
             }
         }
         // Only record a view snapshot if the command actually pushed a document undo entry (skips
@@ -719,6 +751,12 @@ export function useEngineCore(options) {
             viewRedo.current = [];
         }
         lastUndoDepth.current = engine.undoDepth();
+        // Excel selects a freshly inserted chart; a batch ends up on the last one it inserted.
+        for (const member of command.command === "batch" ? command.commands : [command]) {
+            if (member.command === "create-chart") {
+                focusEmbedOrChart(member.spec.chartId);
+            }
+        }
         // The engine's move-range relocates cells but never re-scopes range-scoped CF/DV rules —
         // carry the touched rules to the destination right after the move (Excel/Sheets behavior).
         if (command.command === "move-range") {
@@ -728,7 +766,25 @@ export function useEngineCore(options) {
         }
         // Handed back so the command handlers can surface an engine refusal (`commit.rejections`).
         return commit;
-    }, [retireStreamPreviewForCommand, showError]);
+    }, [retireStreamPreviewForCommand, showError, focusEmbedOrChart, setTableAutoExpansion, setCalculatedColumnFill]);
+    const batchHistory = useCallback((action) => {
+        if (batchCommandsRef.current) {
+            return action();
+        }
+        const commands = [];
+        batchCommandsRef.current = commands;
+        let result;
+        try {
+            result = action();
+        }
+        finally {
+            batchCommandsRef.current = null;
+        }
+        if (commands.length) {
+            onCommand({ command: "batch", commands });
+        }
+        return result;
+    }, [onCommand]);
     // "Calculate Now" (F9): force a full recalculation so volatile functions (NOW/TODAY/RAND/…) refresh.
     // The engine re-evaluates + streams the changed cells through the normal commit (folded like any edit);
     // it mutates no document state, so it isn't undoable. The reference's `options` (reset-graph /
@@ -797,6 +853,19 @@ export function useEngineCore(options) {
         customFnsRef.current.set(name, impl);
         engineRef.current?.registerCustomFunction(name);
     }, []);
+    // Chart selection after an undo/redo step (Excel: the chart an undo brings back, or a redo
+    // re-creates / re-positions, ends up selected; one whose step removed it is deselected). The
+    // engine's chart deltas are the signal — same as the legacy history's `selectedEmbedOrChart`.
+    const restoreChartSelection = useCallback((commit) => {
+        for (const change of commit.chartChanges) {
+            if (change.chart) {
+                focusEmbedOrChart(change.chartId);
+            }
+            else {
+                focusEmbedOrChart((prev) => prev === change.chartId ? undefined : prev);
+            }
+        }
+    }, [focusEmbedOrChart]);
     // Undo AND redo of an edit both return the cursor to the EDIT location — mirroring the reference's
     // `{ activeCell: { undo: coords, redo: coords } }`. So when an entry crosses between the undo/redo
     // stacks we move the SAME stored view, NOT the live cursor (pushing the live cursor would make redo
@@ -806,7 +875,7 @@ export function useEngineCore(options) {
         if (!engine)
             return;
         const prevDepth = engine.undoDepth();
-        engine.undo();
+        const commit = engine.undo();
         if (engine.undoDepth() < prevDepth) {
             const restore = viewUndo.current.pop();
             if (restore) {
@@ -815,13 +884,14 @@ export function useEngineCore(options) {
             }
         }
         lastUndoDepth.current = engine.undoDepth();
-    }, [applyView]);
+        restoreChartSelection(commit);
+    }, [applyView, restoreChartSelection]);
     const redo = useCallback(() => {
         const engine = engineRef.current;
         if (!engine)
             return;
         const prevRedoDepth = engine.redoDepth();
-        engine.redo();
+        const commit = engine.redo();
         if (engine.redoDepth() < prevRedoDepth) {
             const restore = viewRedo.current.pop();
             if (restore) {
@@ -830,7 +900,8 @@ export function useEngineCore(options) {
             }
         }
         lastUndoDepth.current = engine.undoDepth();
-    }, [applyView]);
+        restoreChartSelection(commit);
+    }, [applyView, restoreChartSelection]);
     const load = useCallback((document) => {
         engineRef.current?.load(document);
     }, []);
@@ -859,6 +930,9 @@ export function useEngineCore(options) {
             hidden: es.hidden,
             tabColor: es.tabColor,
             defaultRowHeight: es.defaultRowHeight,
+            defaultColumnWidth: es.defaultColumnWidth,
+            type: es.type,
+            chartId: es.chartId,
         }));
         const firstId = engineSheets[0]?.sheetId ?? viewRef.current.activeSheetId;
         windowRef.current = windowedRef.current
@@ -1757,6 +1831,8 @@ export function useEngineCore(options) {
     // handler→command mapping; nothing here touches the document directly.
     const handlers = useMemo(() => createCommandHandlers(onCommand, {
         getCustomAutofillLists: () => customAutofillListsRef.current,
+        getAutoExpandTables: () => autoExpandTablesRef.current,
+        getAutoCalculatedColumns: () => autoCalculatedColumnsRef.current,
     }), [onCommand]);
     // Data tools composed over the streamed commands. The planners need the WHOLE list range (a
     // windowed host holds only the viewport), so they read it straight from the engine in one
@@ -1776,15 +1852,18 @@ export function useEngineCore(options) {
         });
         if (!plan)
             return undefined;
-        applySubtotalPlan(sheetId, plan, {
+        // Excel undoes a Subtotal in ONE step: the plan's row deletes / inserts, total-row writes and
+        // outline groups apply as one `batch` — one commit to fold, one undo entry on either history
+        // backend, one view snapshot — instead of ten Ctrl+Z presses.
+        batchHistory(() => applySubtotalPlan(sheetId, plan, {
             onDeleteRow: handlers.onDeleteRow,
             onInsertRow: handlers.onInsertRow,
             onChangeBatch: (s, range, values) => handlers.onChangeBatch(s, range, values),
             onGroupRows: handlers.onGroupRows,
             onUngroupRows: handlers.onUngroupRows,
-        });
+        }));
         return plan;
-    }, [handlers, readRect, dimMeta]);
+    }, [batchHistory, handlers, readRect, dimMeta]);
     const onAdvancedFilter = useCallback((sheetId, options) => {
         const list = readRect(sheetId, options.listRange, "raw");
         const criteria = readRect(sheetId, options.criteriaRange, "raw");
@@ -1812,15 +1891,46 @@ export function useEngineCore(options) {
     // (the live active sheet) instead of closing over `activeSheetId`, so identity never changes. The
     // grid omits sheetId from chart move/resize (charts live on the active sheet) and passes just the rule
     // to create-conditional-format.
-    const onMoveChart = useCallback((chartId, anchorCell, offsetXPixels, offsetYPixels) => onCommand({
+    const onMoveChart = useCallback((chartId, anchorCell, offsetXPixels, offsetYPixels, toAnchor) => onCommand({
         command: "move-chart",
         chartId,
         sheetId: viewRef.current.activeSheetId,
         anchorCell,
         offsetXPixels,
         offsetYPixels,
+        ...toAnchor,
     }), [onCommand]);
-    const onResizeChart = useCallback((chartId, anchorCell, offsetXPixels, offsetYPixels, width, height) => onCommand({
+    // Excel's "Move Chart…" (#668 C-17): the engine relocates the chart (minting / deleting the
+    // chartsheet); the view follows the chart to its destination sheet and keeps it selected.
+    const onMoveChartToSheet = useCallback((chart, target) => {
+        const engine = engineRef.current;
+        if (!engine)
+            return undefined;
+        const sourceSheetId = chart.position.sheetId;
+        if (target.kind === "sheet" && target.sheetId === sourceSheetId) {
+            return undefined;
+        }
+        onCommand({
+            command: "move-chart-to-sheet",
+            chartId: chart.chartId,
+            ...(target.kind === "sheet"
+                ? { sheetId: target.sheetId }
+                : { title: target.title }),
+        });
+        const destination = target.kind === "sheet"
+            ? target.sheetId
+            : engine
+                .sheets?.()
+                .find((sheet) => sheet.type === "chartsheet" &&
+                String(sheet.chartId) === String(chart.chartId))?.sheetId;
+        if (destination === undefined || destination === sourceSheetId) {
+            return undefined;
+        }
+        onChangeActiveSheet(destination);
+        focusEmbedOrChart(chart.chartId);
+        return destination;
+    }, [onCommand, onChangeActiveSheet, focusEmbedOrChart]);
+    const onResizeChart = useCallback((chartId, anchorCell, offsetXPixels, offsetYPixels, width, height, toAnchor) => onCommand({
         command: "resize-chart",
         chartId,
         sheetId: viewRef.current.activeSheetId,
@@ -1829,6 +1939,7 @@ export function useEngineCore(options) {
         offsetYPixels,
         width,
         height,
+        ...toAnchor,
     }), [onCommand]);
     const onCreateConditionalFormattingRule = useCallback((rule) => onCommand({
         command: "create-conditional-format",
@@ -1854,6 +1965,9 @@ export function useEngineCore(options) {
                 .filter((t) => t.sheetId === sheetId && t.bandedRange != null)
                 .map((t) => ({
                 bandedRangeId: `${t.id}-${t.theme}`,
+                showFirstColumn: t.showFirstColumn,
+                showLastColumn: t.showLastColumn,
+                totalRow: t.totalRow ?? false,
                 range: { ...t.range, sheetId },
                 ...t.bandedRange,
             })),
@@ -1903,6 +2017,44 @@ export function useEngineCore(options) {
             }
         }
     }, [onCommand]);
+    // Convert to Range keeps the table's look (Excel bakes the table style into the cell formats):
+    // the banded formats the grid painted under the table become static cell formats — the same
+    // capture the format painter makes (#620) — replayed over the table's range in one batch with
+    // the removal, so one undo restores the table and the unbaked cells together.
+    const onRemoveTable = useCallback((tableView) => {
+        const { sheetId, range } = tableView;
+        const banded = paintBandedCells(sheetId);
+        batchHistory(() => {
+            if (banded?.size) {
+                let baked = false;
+                const grid = [];
+                for (let r = range.startRowIndex; r <= range.endRowIndex; r++) {
+                    const row = [];
+                    for (let c = range.startColumnIndex; c <= range.endColumnIndex; c++) {
+                        // The hook's own formats are consolidated `CellFormat`s (never a style reference).
+                        const own = getUserEnteredFormat(sheetId, r, c);
+                        const band = getBandedCellFormat(banded, r, c);
+                        if (band)
+                            baked = true;
+                        // `replace` re-writes every cell of the range: a cell without a band keeps its own format.
+                        row.push((band ? layerBandedFormat(own, band) : own) ?? null);
+                    }
+                    grid.push(row);
+                }
+                if (baked) {
+                    onCommand({
+                        command: "change-formatting",
+                        sheetId,
+                        activeCell: { rowIndex: range.startRowIndex, columnIndex: range.startColumnIndex },
+                        selections: [{ range }],
+                        cellFormat: grid,
+                        options: { replace: true },
+                    });
+                }
+            }
+            handlers.onRemoveTable(tableView);
+        });
+    }, [paintBandedCells, getUserEnteredFormat, batchHistory, onCommand, handlers]);
     const onSavePaintFormat = useCallback((sheetId, activeCell, selections) => {
         // A plain click on a merged cell arms the painter with the anchor and NO selection (the
         // grid clears the list) — Excel treats that click as the whole merged area.
@@ -2053,11 +2205,22 @@ export function useEngineCore(options) {
     // style is materialized on its facet entry as `bandedRange` (never as per-cell format), so derive
     // those here exactly like `useSpreadsheetState` — this single array is what the grid paints and the
     // copy path serializes table styling from.
+    // The gallery's hovered style paints over the table's own while the pointer rests on the
+    // swatch — UI state only, never a command.
+    const [tableStylePreview, setTableStylePreview] = useState(null);
+    const onPreviewTableStyle = useCallback((preview) => setTableStylePreview(preview), []);
     const bandedRanges = useMemo(() => {
         const tableBands = (tables ?? [])
-            .filter((t) => t.sheetId === activeSheetId && t.bandedRange != null)
+            .filter((t) => t.sheetId === activeSheetId)
+            .map((t) => tableStylePreview?.sheetId === t.sheetId && tableStylePreview.tableId === t.id
+            ? previewTableStyle(t, tableStylePreview)
+            : t)
+            .filter((t) => t.bandedRange != null)
             .map((t) => ({
             bandedRangeId: `${t.id}-${t.theme}`,
+            showFirstColumn: t.showFirstColumn,
+            showLastColumn: t.showLastColumn,
+            totalRow: t.totalRow ?? false,
             range: { ...t.range, sheetId: activeSheetId },
             ...t.bandedRange,
         }));
@@ -2065,7 +2228,7 @@ export function useEngineCore(options) {
             ...facets.bandedRanges.filter((b) => b.range?.sheetId === activeSheetId),
             ...tableBands,
         ];
-    }, [facets, tables, activeSheetId]);
+    }, [facets, tables, activeSheetId, tableStylePreview]);
     const basicFilter = useMemo(() => facets.basicFilters.find((f) => f.sheetId === activeSheetId)?.filter, [facets, activeSheetId]);
     // Body rows the engine hid for the active sheet (basic filter OR a table-column filter), as compact
     // [start,end] 1-based inclusive ranges. CanvasGrid derives `visibleRowRanges` from these — the
@@ -2141,7 +2304,11 @@ export function useEngineCore(options) {
     // the engine applies it via `set_style` (streams on `styleChanges`). Only a still-unresolved
     // `StyleReference` (no matching cellXfs entry) is skipped, since a bare ref can't cross to the engine.
     const onPaste = useCallback(async (e, sourceSheetId, destinationSheetId, copiedSelections, pasteActiveCell, pasteSelections, _finalSelections, isCutOperation) => {
-        const parsed = await generateDataFromClipboard(e, pasteActiveCell, destinationSheetId, getSheetName(destinationSheetId), true, initial.current.locale);
+        // A cut is a MOVE: Excel keeps the moved formulas' text verbatim (`=B1*2` cut from A1 to A5
+        // still reads `=B1*2`) and only repoints references INTO the moved block — the engine does
+        // that remap (`repoint_formulas_into_moved_block`), so the clipboard parse must not
+        // relativize cut formulas the way it does copied ones.
+        const parsed = await generateDataFromClipboard(e, pasteActiveCell, destinationSheetId, getSheetName(destinationSheetId), true, initial.current.locale, undefined, undefined, undefined, { relocateFormulas: !isCutOperation });
         let results = parsed?.results ?? [];
         if (!results.length)
             return;
@@ -2170,19 +2337,39 @@ export function useEngineCore(options) {
         // A paste selection larger than the clipboard tiles it (copy G1, select G2:G5, paste fills all
         // four), wrapping like `useOnPaste`. Tiling UI-side keeps the engine's `paste` a plain rectangle
         // and the whole paste ONE undo entry; the tiles' formulas are shifted here (see `paste-tiling`).
-        if (to) {
+        // A cut block is placed exactly once — Excel never tiles a moved range over a larger
+        // selection (its source is cleared once).
+        if (to && !isCutOperation) {
             results = tileClipboardToSelection(results, to, pasteActiveCell, destinationSheetId, getSheetName(destinationSheetId), initial.current.locale);
         }
         const tiles = applyPasteSpecialToTiles(results, target, destinationSheetId, pasteSpecial, { getCellData, getUserEnteredFormat }, initial.current.locale);
         // The copied range top-left, kept for the cut source-clear below.
         const from = copiedSelections?.[0]?.range;
-        // `generateDataFromClipboard` has ALREADY re-anchored each relative formula ref to its destination
-        // (its `moveFormula(sourceCell → destinationCell)` pass overwrites the cell's `fv`), so the formula
-        // text in `cells` is destination-shifted on arrival. The engine's paste then shifts relative refs by
-        // (target − source); passing the real copy origin as `source` would apply that shift a SECOND time and
-        // DOUBLE the offset (`=A1` from B1 pasted to B2 → `=A3` instead of `=A2`). Pin `source` to `target` so
-        // the engine's shift is a zero-delta no-op and the already-correct formula is preserved.
-        const source = target;
+        const cutMove = isCutOperation && from && sourceSheetId != null;
+        // COPY: `generateDataFromClipboard` has ALREADY re-anchored each relative formula ref to its
+        // destination (its `moveFormula(sourceCell → destinationCell)` pass overwrites the cell's `fv`), so
+        // the formula text in `cells` is destination-shifted on arrival. The engine's paste then shifts
+        // relative refs by (target − source); passing the real copy origin as `source` would apply that
+        // shift a SECOND time and DOUBLE the offset (`=A1` from B1 pasted to B2 → `=A3` instead of `=A2`).
+        // Pin `source` to `target` so the engine's shift is a zero-delta no-op.
+        // CUT: the formulas arrive verbatim (see `relocateFormulas` above) and the engine needs the REAL
+        // cut origin — (target − source) is the delta it uses to repoint every formula that reads the
+        // moved cells (`C1 =A1` → `=E1` after cut A1 → paste E1; `=SUM(A1:A3)` → `=SUM(D1:D3)`, other
+        // sheets included). Pinning it to `target` zeroed that delta, so cut + paste never repointed.
+        const source = cutMove
+            ? { rowIndex: from.startRowIndex, columnIndex: from.startColumnIndex }
+            : target;
+        // Notes ride with the cells they annotate (Excel carries a note on copy and moves it on cut).
+        // The clipboard rectangle is row-major from the copied range's top-left, so the note of the
+        // tile's source cell is looked up by offset; tiled repeats (copy only) reuse the modular offset.
+        const noteAt = (i, j) => {
+            // A transposed paste no longer maps tiles back to source cells by offset.
+            if (!from || sourceSheetId == null || pasteSpecial.transpose)
+                return undefined;
+            const height = from.endRowIndex - from.startRowIndex + 1;
+            const width = from.endColumnIndex - from.startColumnIndex + 1;
+            return getNote(sourceSheetId, from.startRowIndex + (i % height), from.startColumnIndex + (j % width));
+        };
         const toPasteCell = (cell) => {
             if (!cell)
                 return null;
@@ -2216,12 +2403,16 @@ export function useEngineCore(options) {
                         : hl.location;
             return { value, format, hyperlink };
         };
-        const cells = tiles.map((row) => row.map((cell) => 
-        // Skip blanks: the engine leaves a `skip` cell untouched (the snapshot is only read by
-        // an engine build predating `skip`, which writes it back instead of clearing).
-        isSkippedPasteCell(cell)
-            ? { skip: true, value: null, ...(toPasteCell(cell.fallback) ?? {}) }
-            : toPasteCell(cell)));
+        const cells = tiles.map((row, i) => row.map((cell, j) => {
+            // Skip blanks: the engine leaves a `skip` cell untouched (the snapshot is only read by
+            // an engine build predating `skip`, which writes it back instead of clearing).
+            if (isSkippedPasteCell(cell)) {
+                return { skip: true, value: null, ...(toPasteCell(cell.fallback) ?? {}) };
+            }
+            const pasteCell = toPasteCell(cell);
+            const note = noteAt(i, j);
+            return pasteCell && note != null ? { ...pasteCell, note } : pasteCell;
+        }));
         onCommand({
             command: "paste",
             sheetId: destinationSheetId,
@@ -2232,21 +2423,28 @@ export function useEngineCore(options) {
                 ? { sheetId: sourceSheetId, range: from }
                 : null,
             formatOnly,
+            ...(autoExpandTablesRef.current === false ? { autoExpandTables: false } : {}),
+            ...(autoCalculatedColumnsRef.current === false
+                ? { autoCalculatedColumns: false }
+                : {}),
         });
-    }, [getSheetName, getCellData, getUserEnteredFormat, onCommand]);
+    }, [getSheetName, getCellData, getUserEnteredFormat, getNote, onCommand]);
     return useMemo(() => ({
         ...state,
         ...handlers,
+        onRemoveTable,
         ready,
         engine: engineRef.current,
         canUndo: hist.canUndo,
         canRedo: hist.canRedo,
+        formulaLocale,
         onCommand,
         undo,
         redo,
         onUndo: undo,
         onRedo: redo,
         onMoveChart,
+        onMoveChartToSheet,
         onResizeChart,
         onCreateConditionalFormattingRule,
         // Repeat last formatting (the action itself is recorded in `onCommand`).
@@ -2321,8 +2519,11 @@ export function useEngineCore(options) {
         // Undefined when the file didn't specify — CanvasGrid falls back to its own default.
         defaultRowHeight: state.sheets.find((s) => s.sheetId === activeSheetId)
             ?.defaultRowHeight ?? undefined,
+        defaultColumnWidth: state.sheets.find((s) => s.sheetId === activeSheetId)
+            ?.defaultColumnWidth ?? undefined,
         isDarkMode: false,
         bandedRanges,
+        onPreviewTableStyle,
         basicFilter,
         hostHiddenRowRanges,
         arrows,
@@ -2330,6 +2531,7 @@ export function useEngineCore(options) {
         tables,
         namedRanges,
         protectedRanges,
+        customTableStyles: facets.customTableStyles,
         embeds,
         slicers,
         getDataValidation,
@@ -2366,6 +2568,7 @@ export function useEngineCore(options) {
         applyPatch,
         generateStatePatches,
         createHistory,
+        batchHistory,
         onClearHistory,
         getFormattingFromRange,
         getFormulasFromRange,
@@ -2382,14 +2585,18 @@ export function useEngineCore(options) {
         onCopy,
         onPaste,
     }), [
+        formulaLocale,
         state,
         handlers,
+        onRemoveTable,
         ready,
         hist,
         onCommand,
         undo,
         redo,
+        batchHistory,
         onMoveChart,
+        onMoveChartToSheet,
         onResizeChart,
         onCreateConditionalFormattingRule,
         onRepeatFormatting,
@@ -2452,6 +2659,7 @@ export function useEngineCore(options) {
         onSelectNextSheet,
         onSelectPreviousSheet,
         bandedRanges,
+        onPreviewTableStyle,
         basicFilter,
         hostHiddenRowRanges,
         arrows,
@@ -2459,6 +2667,7 @@ export function useEngineCore(options) {
         tables,
         namedRanges,
         protectedRanges,
+        facets.customTableStyles,
         embeds,
         slicers,
         getDataValidation,

package/dist/esm/use-spreadsheet-engine.d.ts

@@ -1,7 +1,16 @@
+/**
+ * `useSpreadsheetEngine` — the batteries-included **Option B** hook: the engine-backed data/calc core
+ * ({@link useEngineCore}) composed with the backend-agnostic chrome ({@link useSpreadsheetUI}). It's
+ * the Option-B peer of `useSpreadsheetState` — one hook a component drives the whole grid + dialogs
+ * from. The core owns the engine surface (data/calc/commands/accessors); the chrome owns the dialogs +
+ * host intents (clipboard/citations/comments/…). Their UNION is what makes this a structural drop-in
+ * for `useSpreadsheetState` — the parity lock below is asserted here, not on either layer alone.
+ */
+import { type SparklineGroupHandlers } from "@rowsncolumns/spreadsheet-state";
 import { type EngineSpreadsheet, type UseEngineSpreadsheetOptions } from "./use-engine-core";
 import { type SpreadsheetUI } from "./use-spreadsheet-ui";
 /** The composed surface: the engine core (data/calc/commands/accessors) + the chrome (dialogs + host
  * intents). This — not `useEngineCore` alone — is the drop-in replacement for `useSpreadsheetState`. */
-export type SpreadsheetEngine = EngineSpreadsheet & SpreadsheetUI;
+export type SpreadsheetEngine = EngineSpreadsheet & SpreadsheetUI & SparklineGroupHandlers;
 export declare function useSpreadsheetEngine(options: UseEngineSpreadsheetOptions): SpreadsheetEngine;
 //# sourceMappingURL=use-spreadsheet-engine.d.ts.map

package/dist/esm/use-spreadsheet-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-spreadsheet-engine.d.ts","sourceRoot":"","sources":["../../src/use-spreadsheet-engine.ts"],"names":[],"mappings":"AAWA,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,2BAA2B,EACjC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,KAAK,aAAa,EAAoB,MAAM,sBAAsB,CAAC;AAE5E;wGACwG;AACxG,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,aAAa,CAAC;AAalE,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,2BAA2B,GACnC,iBAAiB,CA6BnB"}
+{"version":3,"file":"use-spreadsheet-engine.d.ts","sourceRoot":"","sources":["../../src/use-spreadsheet-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,KAAK,sBAAsB,EAO5B,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,2BAA2B,EACjC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,KAAK,aAAa,EAAoB,MAAM,sBAAsB,CAAC;AAE5E;wGACwG;AACxG,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAC/C,aAAa,GACb,sBAAsB,CAAC;AAazB,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,2BAA2B,GACnC,iBAAiB,CAwGnB"}