@rowsncolumns/rnc-engine 0.10.132

package/dist/esm/use-engine-pivot-editor.d.ts

@@ -0,0 +1,78 @@
+import type { PivotTable, PivotValue, SheetRange } from "@rowsncolumns/spreadsheet";
+/**
+ * Bridges `@rowsncolumns/pivot`'s `<PivotEditor>` (the pivot settings sidebar) to the RNC
+ * engine's pivot commands — the reusable version of the spec-transform pattern previously
+ * duplicated by each engine host.
+ *
+ * The legacy editor is driven by `usePivot`, which is DuckDB-coupled: it computes pivot
+ * results in JS and writes them into a full `sheetData`. The engine instead computes pivots
+ * wasm-side from the `PivotTable` spec, and `create-pivot-table` / `update-pivot-table`
+ * render the output grid immediately. So every editor callback here is a PURE SPEC TRANSFORM
+ * over the current `PivotTable` (looked up by `pivotId` in the fold's `pivotTables` map),
+ * persisted via `onUpdatePivotTable` — the engine recomputes and re-renders in the same
+ * undoable commit.
+ *
+ * Each row/column/value field carries both `field` (the source column header name) and a
+ * `sourceColumnOffset` resolved from the source range's header row, so the engine can map the
+ * field to its source column regardless of which key it reads. `getGridValues` reads the
+ * source range straight from the engine (the same `{ headers, rows }` shape `usePivot` builds
+ * for the editor's field picker).
+ *
+ * Usage (the returned object spreads directly onto `<PivotEditor>`):
+ * ```tsx
+ * const pivotEditor = useEnginePivotEditor({
+ *   pivotTables: state.pivotTables,
+ *   getEffectiveValue: state.getEffectiveValue,
+ *   onUpdatePivotTable: state.onUpdatePivotTable,
+ *   onRefreshPivot: state.onRefreshPivot,
+ * });
+ * <PivotEditor pivotTable={active} {...pivotEditor} onRequestClose={close} />
+ * ```
+ */
+/** Structural stand-in for `@rowsncolumns/pivot`'s `PivotField` (this package deliberately
+ * does not depend on the pivot package — the shape is what the editor's callbacks pass). */
+export type EnginePivotField = {
+    field: string;
+    displayName?: string;
+    aggFunc?: PivotValue["aggFunc"];
+};
+/** The `columns` sentinel that interleaves value-field headers as a column level. */
+export declare const VALUES_PIVOT_FIELD = "__values__";
+export interface UseEnginePivotEditorParams {
+    /** The fold's pivot spec map (`state.pivotTables` from `useSpreadsheetEngine`). */
+    pivotTables: Map<string | number, PivotTable>;
+    /** Full-document effective-value reader (`state.getEffectiveValue`) — drives the editor's
+     * field picker and `sourceColumnOffset` resolution (off-window-safe). */
+    getEffectiveValue: (sheetId: number, rowIndex: number, columnIndex: number) => unknown;
+    /** `state.onUpdatePivotTable` — persists a transformed spec; the engine re-renders. */
+    onUpdatePivotTable: (pivotId: PivotTable["pivotId"], pivotTable: PivotTable) => void;
+    /** `state.onRefreshPivot` — re-runs the pivot against live source data without a spec
+     * change. Optional: when omitted, refresh falls back to re-emitting the current spec
+     * (`update-pivot-table` recomputes too). */
+    onRefreshPivot?: (pivotId: PivotTable["pivotId"]) => void;
+}
+type GridValues = {
+    headers: (string | number | boolean)[];
+    rows: (string | number | boolean)[][];
+};
+export declare function useEnginePivotEditor({ pivotTables, getEffectiveValue, onUpdatePivotTable, onRefreshPivot, }: UseEnginePivotEditorParams): {
+    getGridValues: (range: SheetRange) => GridValues;
+    addRowPivot: (pivotId: PivotTable["pivotId"], field: EnginePivotField) => Promise<void>;
+    addColumnPivot: (pivotId: PivotTable["pivotId"], field: EnginePivotField) => Promise<void>;
+    addValue: (pivotId: PivotTable["pivotId"], field: EnginePivotField) => Promise<void>;
+    removePivotField: (pivotId: PivotTable["pivotId"], field: string, area: "rows" | "columns" | "values") => Promise<void>;
+    changeFieldOrder: (pivotId: PivotTable["pivotId"], area: "rows" | "columns" | "values", fromIndex: number, toIndex: number) => Promise<void>;
+    setAggregationFunction: (pivotId: PivotTable["pivotId"], field: string, aggFunc: EnginePivotField["aggFunc"]) => Promise<void>;
+    setShowAs: (pivotId: PivotTable["pivotId"], field: string, showAs: NonNullable<PivotValue["showAs"]>) => Promise<void>;
+    addFilter: (pivotId: PivotTable["pivotId"], field: string, filterValue: unknown) => Promise<void>;
+    removeFilter: (pivotId: PivotTable["pivotId"], field: string) => Promise<void>;
+    sortPivotField: (pivotId: PivotTable["pivotId"], field: string, direction: "asc" | "desc") => Promise<void>;
+    removeSortPivotField: (pivotId: PivotTable["pivotId"], field: string) => Promise<void>;
+    toggleSubtotals: (pivotId: PivotTable["pivotId"], show: boolean) => Promise<void>;
+    toggleRowGrandTotals: (pivotId: PivotTable["pivotId"], show: boolean) => Promise<void>;
+    toggleColumnGrandTotals: (pivotId: PivotTable["pivotId"], show: boolean) => Promise<void>;
+    updatePivotSourceRange: (pivotId: PivotTable["pivotId"], sourceRange: SheetRange) => Promise<void>;
+    refreshPivot: (pivotId: PivotTable["pivotId"]) => Promise<void>;
+};
+export {};
+//# sourceMappingURL=use-engine-pivot-editor.d.ts.map

package/dist/esm/use-engine-pivot-editor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-engine-pivot-editor.d.ts","sourceRoot":"","sources":["../../src/use-engine-pivot-editor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,UAAU,EACV,UAAU,EACV,UAAU,EACX,MAAM,2BAA2B,CAAC;AAGnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;4FAC4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;CACjC,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAK/C,MAAM,WAAW,0BAA0B;IACzC,mFAAmF;IACnF,WAAW,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,UAAU,CAAC,CAAC;IAC9C;6EACyE;IACzE,iBAAiB,EAAE,CACjB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,KAChB,OAAO,CAAC;IACb,uFAAuF;IACvF,kBAAkB,EAAE,CAClB,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,EAC9B,UAAU,EAAE,UAAU,KACnB,IAAI,CAAC;IACV;;gDAE4C;IAC5C,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC;CAC3D;AAED,KAAK,UAAU,GAAG;IAChB,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;IACvC,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,EAAE,CAAC;CACvC,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,EACnC,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,GACf,EAAE,0BAA0B;2BAGjB,UAAU,KAAG,UAAU;2BAiDf,UAAU,CAAC,SAAS,CAAC,SAAS,gBAAgB;8BAc9C,UAAU,CAAC,SAAS,CAAC,SAAS,gBAAgB;wBA0B9C,UAAU,CAAC,SAAS,CAAC,SAAS,gBAAgB;gCAgBnD,UAAU,CAAC,SAAS,CAAC,SACvB,MAAM,QACP,MAAM,GAAG,SAAS,GAAG,QAAQ;gCAiB1B,UAAU,CAAC,SAAS,CAAC,QACxB,MAAM,GAAG,SAAS,GAAG,QAAQ,aACxB,MAAM,WACR,MAAM;sCAcN,UAAU,CAAC,SAAS,CAAC,SACvB,MAAM,WACJ,gBAAgB,CAAC,SAAS,CAAC;yBAc3B,UAAU,CAAC,SAAS,CAAC,SACvB,MAAM,UACL,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;yBAa3B,UAAU,CAAC,SAAS,CAAC,SAAS,MAAM,eAAe,OAAO;4BAY1D,UAAU,CAAC,SAAS,CAAC,SAAS,MAAM;8BAYzC,UAAU,CAAC,SAAS,CAAC,SACvB,MAAM,aACF,KAAK,GAAG,MAAM;oCAcX,UAAU,CAAC,SAAS,CAAC,SAAS,MAAM;+BAYpC,UAAU,CAAC,SAAS,CAAC,QAAQ,OAAO;oCASpC,UAAU,CAAC,SAAS,CAAC,QAAQ,OAAO;uCASpC,UAAU,CAAC,SAAS,CAAC,QAAQ,OAAO;sCASpC,UAAU,CAAC,SAAS,CAAC,eAAe,UAAU;4BAgC9C,UAAU,CAAC,SAAS,CAAC;EAoDxC"}

package/dist/esm/use-engine-pivot-editor.js

@@ -0,0 +1,252 @@
+import { useCallback, useMemo } from "react";
+/** The `columns` sentinel that interleaves value-field headers as a column level. */
+export const VALUES_PIVOT_FIELD = "__values__";
+const isValuesField = (field) => field === VALUES_PIVOT_FIELD || field?.toLowerCase() === "values";
+export function useEnginePivotEditor({ pivotTables, getEffectiveValue, onUpdatePivotTable, onRefreshPivot, }) {
+    // Read a range straight from the engine — first row is the header, the rest are data rows.
+    const getGridValues = useCallback((range) => {
+        const headers = [];
+        const rows = [];
+        for (let r = range.startRowIndex; r <= range.endRowIndex; r++) {
+            const row = [];
+            for (let c = range.startColumnIndex; c <= range.endColumnIndex; c++) {
+                const value = getEffectiveValue(range.sheetId, r, c);
+                row.push(typeof value === "string" ||
+                    typeof value === "number" ||
+                    typeof value === "boolean"
+                    ? value
+                    : "");
+            }
+            if (r === range.startRowIndex)
+                headers.push(...row);
+            else
+                rows.push(row);
+        }
+        return { headers, rows };
+    }, [getEffectiveValue]);
+    // The source column index (0-based, relative to `source.startColumnIndex`) whose header
+    // matches `field`.
+    const resolveSourceColumnOffset = useCallback((spec, field) => {
+        const source = spec.source;
+        if (!source)
+            return undefined;
+        const { headers } = getGridValues(source);
+        const offset = headers.findIndex((h) => String(h) === field);
+        return offset >= 0 ? offset : undefined;
+    }, [getGridValues]);
+    const getSpec = useCallback((pivotId) => pivotTables.get(pivotId), [pivotTables]);
+    const update = useCallback((pivotId, next) => onUpdatePivotTable(pivotId, next), [onUpdatePivotTable]);
+    const addRowPivot = useCallback(async (pivotId, field) => {
+        const spec = getSpec(pivotId);
+        if (!spec || spec.rows.some((g) => g.field === field.field))
+            return;
+        const group = {
+            field: field.field,
+            displayName: field.displayName ?? field.field,
+            sourceColumnOffset: resolveSourceColumnOffset(spec, field.field),
+        };
+        update(pivotId, { ...spec, rows: [...spec.rows, group] });
+    }, [getSpec, resolveSourceColumnOffset, update]);
+    const addColumnPivot = useCallback(async (pivotId, field) => {
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        // The "Values" sentinel places the value-field headers as a column level; there can
+        // only be one, and it conventionally leads (PivotManager.addColumnPivot).
+        if (isValuesField(field.field)) {
+            if (spec.columns.some((g) => isValuesField(g.field)))
+                return;
+            const sentinel = {
+                field: VALUES_PIVOT_FIELD,
+                displayName: "Values",
+            };
+            update(pivotId, { ...spec, columns: [sentinel, ...spec.columns] });
+            return;
+        }
+        if (spec.columns.some((g) => g.field === field.field))
+            return;
+        const group = {
+            field: field.field,
+            displayName: field.displayName ?? field.field,
+            sourceColumnOffset: resolveSourceColumnOffset(spec, field.field),
+        };
+        update(pivotId, { ...spec, columns: [...spec.columns, group] });
+    }, [getSpec, resolveSourceColumnOffset, update]);
+    const addValue = useCallback(async (pivotId, field) => {
+        const spec = getSpec(pivotId);
+        if (!spec || spec.values.some((v) => v.field === field.field))
+            return;
+        const value = {
+            field: field.field,
+            displayName: field.displayName ?? field.field,
+            aggFunc: field.aggFunc ?? "sum",
+            sourceColumnOffset: resolveSourceColumnOffset(spec, field.field),
+        };
+        update(pivotId, { ...spec, values: [...spec.values, value] });
+    }, [getSpec, resolveSourceColumnOffset, update]);
+    const removePivotField = useCallback(async (pivotId, field, area) => {
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        const next = area === "columns" && isValuesField(field)
+            ? spec.columns.filter((g) => !isValuesField(g.field))
+            : spec[area].filter((item) => item.field !== field);
+        update(pivotId, { ...spec, [area]: next });
+    }, [getSpec, update]);
+    const changeFieldOrder = useCallback(async (pivotId, area, fromIndex, toIndex) => {
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        const arr = [...spec[area]];
+        const [moved] = arr.splice(fromIndex, 1);
+        arr.splice(toIndex, 0, moved);
+        update(pivotId, { ...spec, [area]: arr });
+    }, [getSpec, update]);
+    const setAggregationFunction = useCallback(async (pivotId, field, aggFunc) => {
+        const spec = getSpec(pivotId);
+        if (!spec || !aggFunc)
+            return;
+        const values = spec.values.map((v) => v.field === field ? { ...v, aggFunc } : v);
+        update(pivotId, { ...spec, values });
+    }, [getSpec, update]);
+    const setShowAs = useCallback(async (pivotId, field, showAs) => {
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        const values = spec.values.map((v) => v.field === field ? { ...v, showAs } : v);
+        update(pivotId, { ...spec, values });
+    }, [getSpec, update]);
+    const addFilter = useCallback(async (pivotId, field, filterValue) => {
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        update(pivotId, {
+            ...spec,
+            filters: { ...spec.filters, [field]: filterValue },
+        });
+    }, [getSpec, update]);
+    const removeFilter = useCallback(async (pivotId, field) => {
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        const filters = { ...spec.filters };
+        delete filters[field];
+        update(pivotId, { ...spec, filters });
+    }, [getSpec, update]);
+    const sortPivotField = useCallback(async (pivotId, field, direction) => {
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        const sortModel = [...(spec.sortModel ?? [])];
+        const idx = sortModel.findIndex((s) => s.field === field);
+        if (idx >= 0)
+            sortModel[idx] = { field, sort: direction };
+        else
+            sortModel.push({ field, sort: direction });
+        update(pivotId, { ...spec, sortModel });
+    }, [getSpec, update]);
+    const removeSortPivotField = useCallback(async (pivotId, field) => {
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        update(pivotId, {
+            ...spec,
+            sortModel: (spec.sortModel ?? []).filter((s) => s.field !== field),
+        });
+    }, [getSpec, update]);
+    const toggleSubtotals = useCallback(async (pivotId, show) => {
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        update(pivotId, { ...spec, showSubtotals: show });
+    }, [getSpec, update]);
+    const toggleRowGrandTotals = useCallback(async (pivotId, show) => {
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        update(pivotId, { ...spec, showRowGrandTotals: show });
+    }, [getSpec, update]);
+    const toggleColumnGrandTotals = useCallback(async (pivotId, show) => {
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        update(pivotId, { ...spec, showColumnGrandTotals: show });
+    }, [getSpec, update]);
+    const updatePivotSourceRange = useCallback(async (pivotId, sourceRange) => {
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        // `sourceColumnOffset` is relative to the source range, so a new source can shift every
+        // field's column — re-resolve each row/column/value offset against the new source's
+        // header row by field name (the sentinel has no source column).
+        const { headers } = getGridValues(sourceRange);
+        const offsetFor = (field) => {
+            if (isValuesField(field))
+                return undefined;
+            const i = headers.findIndex((h) => String(h) === field);
+            return i >= 0 ? i : undefined;
+        };
+        update(pivotId, {
+            ...spec,
+            source: sourceRange,
+            rows: spec.rows.map((g) => ({ ...g, sourceColumnOffset: offsetFor(g.field) })),
+            columns: spec.columns.map((g) => ({
+                ...g,
+                sourceColumnOffset: offsetFor(g.field),
+            })),
+            values: spec.values.map((v) => ({
+                ...v,
+                sourceColumnOffset: offsetFor(v.field),
+            })),
+        });
+    }, [getSpec, getGridValues, update]);
+    // Real refresh: re-run the pivot against live source data (no spec change). Falls back to
+    // re-emitting the spec when the host didn't wire `onRefreshPivot`.
+    const refreshPivot = useCallback(async (pivotId) => {
+        if (onRefreshPivot) {
+            onRefreshPivot(pivotId);
+            return;
+        }
+        const spec = getSpec(pivotId);
+        if (!spec)
+            return;
+        update(pivotId, { ...spec });
+    }, [onRefreshPivot, getSpec, update]);
+    return useMemo(() => ({
+        getGridValues,
+        addRowPivot,
+        addColumnPivot,
+        addValue,
+        removePivotField,
+        changeFieldOrder,
+        setAggregationFunction,
+        setShowAs,
+        addFilter,
+        removeFilter,
+        sortPivotField,
+        removeSortPivotField,
+        toggleSubtotals,
+        toggleRowGrandTotals,
+        toggleColumnGrandTotals,
+        updatePivotSourceRange,
+        refreshPivot,
+    }), [
+        getGridValues,
+        addRowPivot,
+        addColumnPivot,
+        addValue,
+        removePivotField,
+        changeFieldOrder,
+        setAggregationFunction,
+        setShowAs,
+        addFilter,
+        removeFilter,
+        sortPivotField,
+        removeSortPivotField,
+        toggleSubtotals,
+        toggleRowGrandTotals,
+        toggleColumnGrandTotals,
+        updatePivotSourceRange,
+        refreshPivot,
+    ]);
+}

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

@@ -0,0 +1,7 @@
+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 declare function useSpreadsheetEngine(options: UseEngineSpreadsheetOptions): SpreadsheetEngine;
+//# sourceMappingURL=use-spreadsheet-engine.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,23 @@
+import { useCallback, useMemo } from "react";
+import { useEngineCore, } from "./use-engine-core";
+import { useSpreadsheetUI } from "./use-spreadsheet-ui";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _assertDropInParity = true;
+export function useSpreadsheetEngine(options) {
+    const core = useEngineCore(options);
+    const ui = useSpreadsheetUI();
+    // Insert → Checkbox / Dropdown pass a pre-built rule (checkbox with `showEditUI: false`). The
+    // chrome opener alone would drop it and only show the dialog — create the rule through the engine
+    // first, then open the dialog unless suppressed, mirroring the JS host's
+    // `useOnRequestDataValidation` (create immediately; dialog is optional edit UI on top).
+    const onRequestDataValidation = useCallback((sheetId, activeCell, selections, rule, showEditUI = true) => {
+        if (rule) {
+            core.onCreateDataValidationRule?.(rule);
+        }
+        if (showEditUI) {
+            ui.onRequestDataValidation(sheetId, activeCell, selections, rule, showEditUI);
+        }
+    }, [core, ui]);
+    // `ui` last: its dialog-openers + host-intent defaults complete the engine core's surface.
+    return useMemo(() => ({ ...core, ...ui, onRequestDataValidation }), [core, ui, onRequestDataValidation]);
+}

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

@@ -0,0 +1,39 @@
+/**
+ * `useSpreadsheetUI` — the backend-agnostic **chrome** layer: which dialog is open, the target it's
+ * editing, and the host-owned UI intents (clipboard, citations, comments, drag-drop, paint-format,
+ * link/file insertion). It owns NO document data and runs NO calc, so it composes equally with either
+ * data hook ({@link useEngineCore} / `useSpreadsheetState`). The `onRequest*` handlers are the seam
+ * CanvasGrid calls ("the user asked to edit this table / open the CF dialog / …"); here they flip
+ * dialog state. The remaining handlers are inert defaults the host app overrides (it owns the real
+ * clipboard / citation / comment behavior). The app renders its dialog components from
+ * `dialogs`/`dialogContext` and submits the result through the data hook's commands (e.g.
+ * `onUpdateTable`). Self-contained (plain `useState`) so it carries no jotai/`spreadsheet-state`
+ * dependency and can move to its own package unchanged.
+ */
+import type { useSpreadsheetState } from "@rowsncolumns/spreadsheet-state";
+/** The reference hook's return type — used to type every chrome handler EXACTLY as `useSpreadsheetState`
+ * exposes it (so they're drop-in for CanvasGrid's props). Erased at runtime. */
+type SS = ReturnType<typeof useSpreadsheetState>;
+/** The dialogs the chrome can open. */
+export type DialogName = "editTable" | "editEmbed" | "editSlicer" | "deleteSheet" | "namedRange" | "resize" | "formatCells" | "conditionalFormat" | "insertImage" | "insertLink" | "dataValidation" | "note";
+/** The host/chrome slice of `useSpreadsheetState`: dialog-openers (`onRequest*`, `onInsertNote`) plus
+ * the few intents the HOST genuinely owns (file drag/drop/insert). Picked from `SS` so signatures stay
+ * exact. Everything that reads or mutates engine data — paint format, citations, comments, link follow,
+ * CF preview — moved to {@link useEngineCore}; the chrome is backend-agnostic UI only. */
+export type ChromeParityStubs = Pick<SS, "onRequestConditionalFormat" | "onRequestDataValidation" | "onRequestDefineNamedRange" | "onRequestDeleteSheet" | "onRequestEditEmbed" | "onRequestEditSlicer" | "onRequestEditTable" | "onRequestFormatCells" | "onRequestInsertImage" | "onRequestInsertLink" | "onRequestResize" | "onRequestUpdateNamedRange" | "onInsertNote" | "onDragOver" | "onDrop" | "onInsertFile">;
+/** Chrome state + the dialog-opener handlers + host-owned UI intents. Spread into
+ * {@link useSpreadsheetEngine}'s return, where these override the engine core's omitted surface. */
+export interface SpreadsheetUI extends ChromeParityStubs {
+    /** Which dialogs are currently open. */
+    dialogs: Partial<Record<DialogName, boolean>>;
+    /** The target each open dialog is editing (the table / embed / sheetId / cell+selection it was
+     * opened for) — the app reads this to populate the dialog. */
+    dialogContext: Partial<Record<DialogName, unknown>>;
+    /** Open a dialog, stashing the value it should edit. */
+    openDialog: (name: DialogName, context?: unknown) => void;
+    /** Close a dialog. */
+    closeDialog: (name: DialogName) => void;
+}
+export declare function useSpreadsheetUI(): SpreadsheetUI;
+export {};
+//# sourceMappingURL=use-spreadsheet-ui.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-spreadsheet-ui.d.ts","sourceRoot":"","sources":["../../src/use-spreadsheet-ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAG3E;gFACgF;AAChF,KAAK,EAAE,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEjD,uCAAuC;AACvC,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,WAAW,GACX,YAAY,GACZ,aAAa,GACb,YAAY,GACZ,QAAQ,GACR,aAAa,GACb,mBAAmB,GACnB,aAAa,GACb,YAAY,GACZ,gBAAgB,GAChB,MAAM,CAAC;AAEX;;;0FAG0F;AAC1F,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,EAAE,EACA,4BAA4B,GAC5B,yBAAyB,GACzB,2BAA2B,GAC3B,sBAAsB,GACtB,oBAAoB,GACpB,qBAAqB,GACrB,oBAAoB,GACpB,sBAAsB,GACtB,sBAAsB,GACtB,qBAAqB,GACrB,iBAAiB,GACjB,2BAA2B,GAC3B,cAAc,GACd,YAAY,GACZ,QAAQ,GACR,cAAc,CACjB,CAAC;AAYF;oGACoG;AACpG,MAAM,WAAW,aAAc,SAAQ,iBAAiB;IACtD,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IAC9C;kEAC8D;IAC9D,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,wDAAwD;IACxD,UAAU,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1D,sBAAsB;IACtB,WAAW,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;CACzC;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CA+HhD"}

package/dist/esm/use-spreadsheet-ui.js

@@ -0,0 +1,78 @@
+import { useCallback, useMemo, useState } from "react";
+// A rejected promise (`Promise<never>` → assignable anywhere) for the async intents the HOST owns —
+// paste / file-drop. An honest signal if a drop-in caller ever invokes one without wiring it.
+const hostOwned = (op) => Promise.reject(new Error(`${op} is host-owned in the chrome layer`));
+// Inert defaults for the file-drag/drop intents the host app owns. Module-level → stable identity.
+const onDragOver = () => { };
+const onDrop = () => Promise.resolve();
+const onInsertFile = () => hostOwned("onInsertFile");
+export function useSpreadsheetUI() {
+    const [dialogs, setDialogs] = useState({});
+    const [dialogContext, setDialogContext] = useState({});
+    const openDialog = useCallback((name, context) => {
+        setDialogs((prev) => ({ ...prev, [name]: true }));
+        setDialogContext((prev) => ({ ...prev, [name]: context }));
+    }, []);
+    const closeDialog = useCallback((name) => {
+        setDialogs((prev) => ({ ...prev, [name]: false }));
+    }, []);
+    // Each opener stashes the value the dialog edits, then opens it. Arg shapes come from `SS[K]`, so
+    // they match exactly what CanvasGrid passes.
+    const onRequestEditTable = useCallback((table) => openDialog("editTable", table), [openDialog]);
+    const onRequestEditEmbed = useCallback((embed) => openDialog("editEmbed", embed), [openDialog]);
+    const onRequestEditSlicer = useCallback((slicer) => openDialog("editSlicer", slicer), [openDialog]);
+    const onRequestDeleteSheet = useCallback((sheetId) => openDialog("deleteSheet", sheetId), [openDialog]);
+    const onRequestDefineNamedRange = useCallback((sheetId, activeCell, selections) => openDialog("namedRange", { sheetId, activeCell, selections }), [openDialog]);
+    const onRequestUpdateNamedRange = useCallback((sheetId, namedRange) => openDialog("namedRange", { sheetId, namedRange }), [openDialog]);
+    const onRequestResize = useCallback((sheetId, indexes, axis) => openDialog("resize", { sheetId, indexes, axis }), [openDialog]);
+    const onRequestFormatCells = useCallback(() => openDialog("formatCells"), [openDialog]);
+    const onRequestConditionalFormat = useCallback(() => openDialog("conditionalFormat"), [openDialog]);
+    const onRequestInsertImage = useCallback((sheetId, activeCell, insertOverCells) => openDialog("insertImage", { sheetId, activeCell, insertOverCells }), [openDialog]);
+    const onRequestInsertLink = useCallback((sheetId, activeCell, selections) => openDialog("insertLink", { sheetId, activeCell, selections }), [openDialog]);
+    const onRequestDataValidation = useCallback((sheetId, activeCell, selections) => openDialog("dataValidation", { sheetId, activeCell, selections }), [openDialog]);
+    // Inserting a note opens the note editor (UI state) — the note text is written via the engine's
+    // `update-note` command once the user submits. Mirrors `useInsertNote` (a dialog opener).
+    const onInsertNote = useCallback((sheetId, cell, selections) => openDialog("note", { sheetId, cell, selections }), [openDialog]);
+    return useMemo(() => ({
+        dialogs,
+        dialogContext,
+        openDialog,
+        closeDialog,
+        // dialog-openers (real)
+        onRequestEditTable,
+        onRequestEditEmbed,
+        onRequestEditSlicer,
+        onRequestDeleteSheet,
+        onRequestDefineNamedRange,
+        onRequestUpdateNamedRange,
+        onRequestResize,
+        onRequestFormatCells,
+        onRequestConditionalFormat,
+        onRequestInsertImage,
+        onRequestInsertLink,
+        onRequestDataValidation,
+        onInsertNote,
+        // file drag/drop/insert — genuinely host-owned (inert defaults the app overrides)
+        onDragOver,
+        onDrop,
+        onInsertFile,
+    }), [
+        dialogs,
+        dialogContext,
+        openDialog,
+        closeDialog,
+        onRequestEditTable,
+        onRequestEditEmbed,
+        onRequestEditSlicer,
+        onRequestDeleteSheet,
+        onRequestDefineNamedRange,
+        onRequestUpdateNamedRange,
+        onRequestResize,
+        onRequestFormatCells,
+        onRequestConditionalFormat,
+        onRequestInsertImage,
+        onRequestInsertLink,
+        onRequestDataValidation,
+        onInsertNote,
+    ]);
+}