@svgrid/grid 1.0.2 → 1.1.0

package/dist/css.d.ts

@@ -0,0 +1,3 @@
+// Ambient declaration so TypeScript accepts side-effect CSS imports
+// (e.g. `import "./SvGrid.css"`). The bundler resolves the actual asset.
+declare module "*.css";

package/dist/editing.d.ts

@@ -0,0 +1,24 @@
+import { type Column, type Row, type RowData, type TableFeatures } from "./index";
+import "./sv-grid-scrollbar";
+type HistoryStep = {
+    rowId: string;
+    columnId: string;
+    field: string;
+    before: unknown;
+    after: unknown;
+};
+export declare function createEditing<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData>(ctx: any): {
+    isCellEditable: (column: Column<TData>, row?: Row<TData>) => boolean;
+    isCellEditableAt: (rowIndex: number, colIndex: number) => boolean;
+    getRowColumnValue: (row: Row<TData>, columnId: string) => unknown;
+    getCellDisplayValue: (rowId: string, columnId: string, baseValue: unknown) => any;
+    startEditingWithChar: (rowIndex: number, colIndex: number, char: string) => boolean;
+    saveEditingCell: () => void;
+    applyHistoryStep: (step: HistoryStep, direction: "undo" | "redo") => void;
+    updateEditingCellValue: (value: string) => void;
+    onEditorKeyDown: (event: KeyboardEvent) => void;
+    focusOnMount: (node: HTMLInputElement | HTMLTextAreaElement) => void;
+    onCellDoubleClick: (rowIndex: number, colIndex: number) => void;
+    pasteFromClipboard: () => Promise<void>;
+};
+export {};

package/dist/editing.js

@@ -0,0 +1,343 @@
+// editing handlers extracted from the controller. Imperative event handlers
+// reading/writing controller state via the `ctx` handle; the reactive core
+// ($state/$derived/$effect) stays in the controller.
+import { parseEditorValue, } from "./index";
+import "./sv-grid-scrollbar";
+import { getCellKey, toValueArray, } from "./SvGrid.helpers";
+import { getColumnBaseValue, isGroupRow, } from "./cell-values";
+export function createEditing(ctx) {
+    /**
+     * Resolve `columnDef.editable` for one row × column pair.
+     *
+     *   - `undefined` / `true` → editable
+     *   - `false` → not editable (column-level lockdown, fastest path)
+     *   - function → call it with the cell's context and honour the
+     *     boolean it returns (cell-level lockdown - used for things like
+     *     "this field is owned by the server, this one isn't, by row")
+     *
+     * Called from every editing entry point: double-click, type-to-edit,
+     * fill-handle drag, Delete-clear, clipboard paste. A central helper
+     * keeps the cell-level callback signature consistent and saves a
+     * lookup of CellContext at each site.
+     */
+    function isCellEditable(column, row) {
+        const editable = column.columnDef.editable;
+        if (editable === false)
+            return false;
+        if (typeof editable !== "function")
+            return true;
+        if (!row)
+            return true;
+        const cellCtx = {
+            cell: {
+                id: `${row.id}_${column.id}`,
+                row,
+                column,
+                getValue: () => getColumnBaseValue(row, column),
+                getContext: () => cellCtx,
+            },
+            row,
+            column,
+            table: ctx.grid,
+            getValue: () => getColumnBaseValue(row, column),
+        };
+        try {
+            return editable(cellCtx) !== false;
+        }
+        catch {
+            // A throwing predicate shouldn't crash the grid - log and treat
+            // as not-editable so any error biases toward safety.
+            return false;
+        }
+    }
+    /** Variant that takes raw row + column indices for the rare callers
+     *  (fill-handle, paste, Delete) that already work in index-space. */
+    function isCellEditableAt(rowIndex, colIndex) {
+        const row = ctx.allRows[rowIndex];
+        const column = ctx.allColumns[colIndex];
+        if (!column)
+            return false;
+        return isCellEditable(column, row);
+    }
+    function getRowColumnValue(row, columnId) {
+        const column = ctx.allColumns.find((entry) => entry.id === columnId);
+        return column
+            ? getColumnBaseValue(row, column)
+            : row.getCellValueByColumnId(columnId);
+    }
+    function getCellDisplayValue(rowId, columnId, baseValue) {
+        const key = getCellKey(rowId, columnId);
+        return key in ctx.editedCellValues ? ctx.editedCellValues[key] : baseValue;
+    }
+    /** Start editing seeded with a typed character (Excel-style type-to-edit). */
+    function startEditingWithChar(rowIndex, colIndex, char) {
+        if (!ctx.editingEnabled)
+            return false;
+        const row = ctx.allRows[rowIndex];
+        const column = ctx.allColumns[colIndex];
+        if (!row || !column || isGroupRow(row))
+            return false;
+        if (!isCellEditable(column, row))
+            return false;
+        const editorType = (column.columnDef.editorType ??
+            "text");
+        if (editorType === "checkbox" ||
+            editorType === "date" ||
+            editorType === "datetime" ||
+            editorType === "list" ||
+            editorType === "chips") {
+            return false;
+        }
+        if (editorType === "number" && !/[0-9.+\-]/.test(char))
+            return false;
+        ctx.editorSelectAll = false;
+        ctx.editingCell = {
+            rowId: row.id,
+            columnId: column.id,
+            editorType,
+            value: char,
+        };
+        ctx.setActiveCell(rowIndex, colIndex);
+        ctx.setSelection(rowIndex, colIndex);
+        return true;
+    }
+    function saveEditingCell() {
+        if (!ctx.editingCell)
+            return;
+        const row = ctx.allRows.find((entry) => entry.id === ctx.editingCell?.rowId);
+        const column = ctx.allColumns.find((entry) => entry.id === ctx.editingCell?.columnId);
+        const parsedValue = parseEditorValue(ctx.editingCell.editorType, ctx.editingCell.value, {
+            multiple: column?.columnDef.editorMultiple === true,
+        });
+        let oldValue = undefined;
+        if (row?.original && column?.columnDef.field) {
+            oldValue = row.original[column.columnDef.field];
+            row.original[column.columnDef.field] =
+                parsedValue;
+        }
+        const key = getCellKey(ctx.editingCell.rowId, ctx.editingCell.columnId);
+        ctx.editedCellValues = {
+            ...ctx.editedCellValues,
+            [key]: parsedValue,
+        };
+        ctx.grid.store.setState((prev) => ({ ...prev }));
+        // Record into the history at the current pointer. Any forward
+        // history (steps the user could have redone) is truncated - this
+        // is the standard "edit invalidates redo" rule.
+        if (oldValue !== parsedValue && row?.original && column?.columnDef.field) {
+            const step = {
+                rowId: ctx.editingCell.rowId,
+                columnId: ctx.editingCell.columnId,
+                field: column.columnDef.field,
+                before: oldValue,
+                after: parsedValue,
+            };
+            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;
+        }
+        // Notify the consumer AFTER the row has been updated so any callback-
+        // driven recompute (cascade totals, server save, undo stack) sees the
+        // post-write state. `rowIndex` matches the position in `props.data`.
+        if (ctx.props.onCellValueChange && row?.original && column) {
+            const rowIndex = ctx.internalData.indexOf(row.original);
+            ctx.props.onCellValueChange({
+                rowIndex,
+                columnId: column.id,
+                oldValue,
+                newValue: parsedValue,
+                row: row.original,
+            });
+        }
+        ctx.editingCell = null;
+    }
+    /** 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) {
+        const row = ctx.allRows.find((r) => r.id === step.rowId);
+        const col = ctx.allColumns.find((c) => c.id === step.columnId);
+        if (!row?.original || !col)
+            return;
+        const value = direction === 'undo' ? step.before : step.after;
+        row.original[step.field] = value;
+        const key = getCellKey(step.rowId, step.columnId);
+        ctx.editedCellValues = { ...ctx.editedCellValues, [key]: value };
+        ctx.grid.store.setState((prev) => ({ ...prev }));
+        if (ctx.props.onCellValueChange) {
+            const rowIndex = ctx.internalData.indexOf(row.original);
+            ctx.props.onCellValueChange({
+                rowIndex,
+                columnId: step.columnId,
+                oldValue: direction === 'undo' ? step.after : step.before,
+                newValue: value,
+                row: row.original,
+            });
+        }
+    }
+    function updateEditingCellValue(value) {
+        ctx.editingCell = ctx.editingCell ? { ...ctx.editingCell, value } : ctx.editingCell;
+    }
+    function onEditorKeyDown(event) {
+        event.stopPropagation();
+        if (event.key === "Enter") {
+            event.preventDefault();
+            saveEditingCell();
+            ctx.gridRootEl?.focus({ preventScroll: true });
+        }
+        else if (event.key === "Escape") {
+            event.preventDefault();
+            ctx.editingCell = null;
+            ctx.gridRootEl?.focus({ preventScroll: true });
+        }
+    }
+    function focusOnMount(node) {
+        const selectAll = ctx.editorSelectAll;
+        requestAnimationFrame(() => {
+            node.focus({ preventScroll: true });
+            try {
+                if (selectAll) {
+                    node.select();
+                }
+                else {
+                    const end = node.value.length;
+                    node.setSelectionRange(end, end);
+                }
+            }
+            catch {
+                /* date/number inputs may not support text selection */
+            }
+        });
+    }
+    function onCellDoubleClick(rowIndex, colIndex) {
+        if (!ctx.editingEnabled)
+            return;
+        const row = ctx.allRows[rowIndex];
+        const column = ctx.allColumns[colIndex];
+        if (!row || !column)
+            return;
+        if (isGroupRow(row))
+            return;
+        if (!isCellEditable(column, row))
+            return;
+        if (ctx.editingCell?.rowId === row.id && ctx.editingCell?.columnId === column.id)
+            return;
+        const editorType = (column.columnDef.editorType ??
+            "text");
+        ctx.editorSelectAll = true;
+        let initialValue = getCellDisplayValue(row.id, column.id, row.getCellValueByColumnId(column.id));
+        if (editorType === "list" || editorType === "chips") {
+            if (column.columnDef.editorMultiple) {
+                // Seed with an array so the editor can mutate slot-by-slot.
+                initialValue = toValueArray(initialValue);
+            }
+            else if (Array.isArray(initialValue)) {
+                initialValue = initialValue[0] ?? "";
+            }
+        }
+        ctx.editingCell = {
+            rowId: row.id,
+            columnId: column.id,
+            editorType,
+            value: initialValue,
+        };
+        ctx.setActiveCell(rowIndex, colIndex);
+        ctx.setSelection(rowIndex, colIndex);
+    }
+    async function pasteFromClipboard() {
+        if (!navigator.clipboard?.readText)
+            return;
+        let text;
+        try {
+            text = await navigator.clipboard.readText();
+        }
+        catch {
+            return;
+        }
+        const anchor = ctx.selectionRange.anchor ?? ctx.grid.getState().activeCell;
+        if (!anchor)
+            return;
+        const focus = ctx.selectionRange.focus ?? anchor;
+        const startRow = Math.min(anchor.rowIndex, focus.rowIndex);
+        const startCol = Math.min(anchor.colIndex, focus.colIndex);
+        const endRow = Math.max(anchor.rowIndex, focus.rowIndex);
+        const endCol = Math.max(anchor.colIndex, focus.colIndex);
+        const lines = text.replace(/\r\n/g, "\n").split("\n");
+        if (lines.length > 0 && lines[lines.length - 1] === "")
+            lines.pop();
+        if (!lines.length)
+            return;
+        // Excel/Sheets behaviour: when the clipboard holds a single cell and
+        // the selection is a range, fill the entire range with that value.
+        // For larger clipboards (multi-row/col TSV), paste at the top-left
+        // corner and let the clipboard determine the span (the original
+        // behaviour).
+        const clipboardIsSingleCell = lines.length === 1 && (lines[0]?.split("\t").length ?? 0) === 1;
+        const selectionIsRange = startRow !== endRow || startCol !== endCol;
+        const fillRange = clipboardIsSingleCell && selectionIsRange;
+        const rowSpan = fillRange ? endRow - startRow + 1 : lines.length;
+        const colSpan = fillRange
+            ? endCol - startCol + 1
+            : Math.max(...lines.map((l) => l.split("\t").length));
+        const next = ctx.internalData.slice();
+        for (let i = 0; i < rowSpan; i += 1) {
+            const targetRowIndex = startRow + i;
+            const row = ctx.allRows[targetRowIndex];
+            if (!row || isGroupRow(row))
+                continue;
+            // Map the visible row back to its index in the data array via row.id (default = String(index)).
+            const dataIndex = Number(row.id);
+            if (!Number.isInteger(dataIndex) ||
+                dataIndex < 0 ||
+                dataIndex >= next.length)
+                continue;
+            const originalRow = next[dataIndex];
+            if (!originalRow)
+                continue;
+            const sourceCells = fillRange
+                ? null
+                : lines[i]?.split("\t") ?? [];
+            const updated = {
+                ...originalRow,
+            };
+            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 editorType = (column.columnDef.editorType ??
+                    "text");
+                const raw = fillRange ? lines[0] : sourceCells?.[j] ?? "";
+                updated[column.columnDef.field] = parseEditorValue(editorType, raw);
+            }
+            next[dataIndex] = updated;
+        }
+        ctx.internalData = next;
+        ctx.grid.store.setState((prev) => ({ ...prev }));
+    }
+    return {
+        isCellEditable,
+        isCellEditableAt,
+        getRowColumnValue,
+        getCellDisplayValue,
+        startEditingWithChar,
+        saveEditingCell,
+        applyHistoryStep,
+        updateEditingCellValue,
+        onEditorKeyDown,
+        focusOnMount,
+        onCellDoubleClick,
+        pasteFromClipboard,
+    };
+}

package/dist/editors/cell-editors.d.ts

@@ -1,4 +1,4 @@
-export type CellEditorType = 'text' | 'number' | 'date' | 'datetime' | 'time' | 'password' | 'checkbox' | 'list' | 'chips' | 'select' | 'rich-select' | 'textarea' | 'color' | 'rating';
+export type CellEditorType = 'text' | 'number' | 'date' | 'datetime' | 'time' | 'password' | 'checkbox' | 'list' | 'chips' | 'select' | 'rich-select' | 'autocomplete' | 'textarea' | 'color' | 'rating';
 /** Normalized option used by list/chips editors. The optional `color`
  *  paints the chip - both in the in-cell readonly chips render and in
  *  the dropdown trigger when `renderChipsInTrigger` is on. Any CSS

package/dist/facet-buckets.d.ts

@@ -0,0 +1,13 @@
+import type { Column, RowData } from "./index";
+export type FacetBucket = {
+    label: string;
+    numericMin: number;
+    numericMax: number;
+    isLast: boolean;
+    isDate: boolean;
+};
+export declare function isBucketableColumn<TData extends RowData>(column: Column<TData>): {
+    isDate: boolean;
+} | null;
+export declare function buildBuckets<TData extends RowData>(column: Column<TData>, isDate: boolean, data: ReadonlyArray<TData>, getAccessor: (row: TData, column: Column<TData>) => unknown): Array<FacetBucket> | null;
+export declare function isInBucket(num: number, bucket: FacetBucket): boolean;

package/dist/facet-buckets.js

@@ -0,0 +1,54 @@
+import { rawToNumber, formatFacetDate, formatFacetNumber } from "./SvGrid.helpers";
+const FACET_BUCKET_THRESHOLD = 30;
+const FACET_BUCKET_COUNT = 10;
+export function isBucketableColumn(column) {
+    const editorType = column.columnDef.editorType;
+    if (editorType === "number")
+        return { isDate: false };
+    if (editorType === "date" || editorType === "datetime")
+        return { isDate: true };
+    return null;
+}
+export function buildBuckets(column, isDate, data, getAccessor) {
+    let min = Number.POSITIVE_INFINITY;
+    let max = Number.NEGATIVE_INFINITY;
+    const distinct = new Set();
+    for (const rowData of data) {
+        const num = rawToNumber(getAccessor(rowData, column), isDate);
+        if (!Number.isFinite(num))
+            continue;
+        distinct.add(num);
+        if (num < min)
+            min = num;
+        if (num > max)
+            max = num;
+    }
+    if (distinct.size <= FACET_BUCKET_THRESHOLD)
+        return null;
+    if (!Number.isFinite(min) || !Number.isFinite(max) || min === max)
+        return null;
+    const span = max - min;
+    const buckets = [];
+    for (let i = 0; i < FACET_BUCKET_COUNT; i += 1) {
+        const lo = min + (span * i) / FACET_BUCKET_COUNT;
+        const hi = min + (span * (i + 1)) / FACET_BUCKET_COUNT;
+        const label = isDate
+            ? `${formatFacetDate(lo)} – ${formatFacetDate(hi)}`
+            : `${formatFacetNumber(lo)} – ${formatFacetNumber(hi)}`;
+        buckets.push({
+            label,
+            numericMin: lo,
+            numericMax: hi,
+            isLast: i === FACET_BUCKET_COUNT - 1,
+            isDate,
+        });
+    }
+    return buckets;
+}
+export function isInBucket(num, bucket) {
+    if (!Number.isFinite(num))
+        return false;
+    if (num < bucket.numericMin)
+        return false;
+    return bucket.isLast ? num <= bucket.numericMax : num < bucket.numericMax;
+}

package/dist/features.d.ts

@@ -0,0 +1,5 @@
+import { type RowData, type TableFeatures } from "./index";
+import "./sv-grid-scrollbar";
+export declare function createFeatures<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData>(ctx: any): {
+    resolveEffectiveFeatures: () => TableFeatures;
+};

package/dist/features.js

@@ -0,0 +1,30 @@
+// features handlers extracted from the controller. Imperative event handlers
+// reading/writing controller state via the `ctx` handle; the reactive core
+// ($state/$derived/$effect) stays in the controller.
+import { tableFeatures, rowSortingFeature, columnFilteringFeature, columnGroupingFeature, } from "./index";
+import "./sv-grid-scrollbar";
+export function createFeatures(ctx) {
+    // Merge the consumer's `features` set with whatever the boolean shortcuts
+    // imply. A shortcut set to `true` injects its feature; set to `false` it
+    // removes it (so `sortable={false}` wins even if `rowSortingFeature` was
+    // passed in `features`); left undefined it defers to `features`.
+    function resolveEffectiveFeatures() {
+        const merged = { ...(ctx.props.features ?? {}) };
+        if (ctx.props.sortable === true)
+            merged.rowSortingFeature = rowSortingFeature;
+        else if (ctx.props.sortable === false)
+            delete merged.rowSortingFeature;
+        if (ctx.props.filterable === true)
+            merged.columnFilteringFeature = columnFilteringFeature;
+        else if (ctx.props.filterable === false)
+            delete merged.columnFilteringFeature;
+        if (ctx.props.groupable === true)
+            merged.columnGroupingFeature = columnGroupingFeature;
+        else if (ctx.props.groupable === false)
+            delete merged.columnGroupingFeature;
+        return tableFeatures(merged);
+    }
+    return {
+        resolveEffectiveFeatures,
+    };
+}

package/dist/filter-operators.d.ts

@@ -0,0 +1,16 @@
+import type { Column, RowData } from "./index";
+import type { FilterOperator, FilterOption } from "./SvGrid.types";
+export declare const filterOperatorOptions: Array<FilterOption>;
+/** Which operators make sense for each column editor type. */
+export declare const TEXT_OPERATORS: Array<FilterOperator>;
+export declare const NUMBER_OPERATORS: Array<FilterOperator>;
+export declare const DATE_OPERATORS: Array<FilterOperator>;
+export declare const CHECKBOX_OPERATORS: Array<FilterOperator>;
+export declare const fallbackOperatorOption: FilterOption;
+export declare function operatorOption(value: FilterOperator): FilterOption;
+/** Returns the operators that make sense for the given column's data type. */
+export declare function operatorsForColumn<TData extends RowData>(column: Column<TData> | undefined): Array<FilterOption>;
+/** Default operator for a column (first one valid for its type). */
+export declare function defaultOperatorFor<TData extends RowData>(column: Column<TData> | undefined): FilterOperator;
+/** Date columns get friendlier labels for "less / greater than". */
+export declare function operatorLabelFor<TData extends RowData>(option: FilterOption, column: Column<TData> | undefined): string;

package/dist/filter-operators.js

@@ -0,0 +1,69 @@
+export const filterOperatorOptions = [
+    { value: "contains", label: "Contains", iconName: "op-contains" },
+    { value: "equals", label: "Equals", iconName: "op-equals" },
+    { value: "startsWith", label: "Starts with", iconName: "op-startsWith" },
+    { value: "greaterThan", label: "Greater than", iconName: "op-greaterThan" },
+    { value: "lessThan", label: "Less than", iconName: "op-lessThan" },
+    { value: "between", label: "Between", iconName: "op-between" },
+    { value: "isBlank", label: "Is blank", iconName: "op-isBlank" },
+];
+/** Which operators make sense for each column editor type. */
+export const TEXT_OPERATORS = [
+    "contains",
+    "equals",
+    "startsWith",
+    "isBlank",
+];
+export const NUMBER_OPERATORS = [
+    "equals",
+    "greaterThan",
+    "lessThan",
+    "between",
+    "isBlank",
+];
+export const DATE_OPERATORS = [
+    "equals",
+    "lessThan",
+    "greaterThan",
+    "between",
+    "isBlank",
+];
+export const CHECKBOX_OPERATORS = ["equals", "isBlank"];
+export const fallbackOperatorOption = {
+    value: "contains",
+    label: "Contains",
+    iconName: "op-contains",
+};
+export function operatorOption(value) {
+    return (filterOperatorOptions.find((option) => option.value === value) ??
+        fallbackOperatorOption);
+}
+/** Returns the operators that make sense for the given column's data type. */
+export function operatorsForColumn(column) {
+    const editorType = column?.columnDef.editorType ?? "text";
+    const ids = editorType === "number"
+        ? NUMBER_OPERATORS
+        : editorType === "date" || editorType === "datetime"
+            ? DATE_OPERATORS
+            : editorType === "checkbox"
+                ? CHECKBOX_OPERATORS
+                : TEXT_OPERATORS;
+    return ids
+        .map((id) => filterOperatorOptions.find((option) => option.value === id))
+        .filter((option) => Boolean(option));
+}
+/** Default operator for a column (first one valid for its type). */
+export function defaultOperatorFor(column) {
+    return operatorsForColumn(column)[0]?.value ?? "contains";
+}
+/** Date columns get friendlier labels for "less / greater than". */
+export function operatorLabelFor(option, column) {
+    const editorType = column?.columnDef.editorType;
+    if (editorType === "date" || editorType === "datetime") {
+        if (option.value === "lessThan")
+            return "Before";
+        if (option.value === "greaterThan")
+            return "After";
+    }
+    return option.label;
+}

package/dist/hyperformula-adapter.d.ts

@@ -0,0 +1,82 @@
+/**
+ * HyperFormula adapter — Excel-class formula evaluation for SvGrid.
+ *
+ * `hyperformula` is an OPTIONAL peer dependency. Consumers who want
+ * full Excel-compatible formulas install it themselves:
+ *
+ * ```bash
+ *   pnpm add hyperformula
+ * ```
+ *
+ * The adapter wraps an HF instance around the grid's flat-row data:
+ *
+ *   - Treats each `data[]` row as a spreadsheet row
+ *   - Each registered field maps to a spreadsheet column
+ *   - Values that start with `=` are evaluated by HF
+ *   - The adapter returns the computed rows ready to render
+ *   - On edit, call `update(rowIdx, field, value)` and the adapter
+ *     re-evaluates only the cells HF tells it are dirty
+ *
+ * Why not bundle HF: it's ~1MB minified and 99% of grids never need it.
+ * Keeping it peer-optional means tiny default bundle + heavy-formula
+ * users get the ~400 functions (VLOOKUP, INDIRECT, IFS, XLOOKUP, full
+ * date/time/financial libraries) on demand.
+ */
+/** Minimal HF type surface this adapter uses. Mirrored here (rather
+ *  than importing) so consumers without `hyperformula` installed still
+ *  type-check. */
+export type HyperFormulaInstance = {
+    setCellContents(cell: {
+        sheet: number;
+        row: number;
+        col: number;
+    }, contents: unknown): Array<{
+        address: {
+            sheet: number;
+            row: number;
+            col: number;
+        };
+        newValue: unknown;
+    }>;
+    getCellValue(cell: {
+        sheet: number;
+        row: number;
+        col: number;
+    }): unknown;
+    destroy(): void;
+    rebuildAndRecalculate(): void;
+};
+export type HyperFormulaSheetConfig<T extends Record<string, unknown>> = {
+    /** The HF instance the consumer constructed (so they pick the
+     *  license key + options). */
+    hyperformula: HyperFormulaInstance;
+    /** Sheet index inside the HF instance. Default 0. */
+    sheetId?: number;
+    /** Source rows. Cell values starting with `=` are evaluated. */
+    rows: T[];
+    /** Ordered list of fields to expose to the formula engine. The
+     *  order determines the HF column index, which is how A1-style
+     *  references resolve. */
+    fields: ReadonlyArray<keyof T & string>;
+};
+export type HyperFormulaSheet<T extends Record<string, unknown>> = {
+    /** Rows with every `=...` formula replaced by its evaluated value.
+     *  Use this in a custom cell renderer to DISPLAY the result. */
+    computed: T[];
+    /** Rows with formulas kept as their raw `=SUM(...)` strings.
+     *  Pass this as `<SvGrid data={...}>` so the inline editor lets the
+     *  user edit the formula text itself, not the evaluated value. */
+    raw: T[];
+    /** Call when a cell edit lands. Returns the new computed + raw
+     *  snapshots so the consumer can reassign both. */
+    update(rowIndex: number, field: keyof T & string, value: unknown): {
+        computed: T[];
+        raw: T[];
+    };
+    /** Tear the adapter + the HF instance down (releases memory). */
+    destroy(): void;
+};
+/** Build a live spreadsheet adapter around a HyperFormula instance.
+ *  Returns computed rows + an `update()` hook to push edits back into
+ *  the engine. */
+export declare function createHyperFormulaSheet<T extends Record<string, unknown>>(config: HyperFormulaSheetConfig<T>): HyperFormulaSheet<T>;