@galaxy-io/dls 1.6.0 → 2.0.0

package/dist/table/types.d.ts

@@ -1,251 +1,73 @@
+/**
+ * Column and state types shared by `InfiniteTable`, `VirtualizedInfiniteTable` and
+ * `InfiniteSpreadsheet` (`@galaxy-io/dls/table/types`). Types only: importing this module costs
+ * nothing at runtime and pulls in no optional peer. A column array written for one table works
+ * unchanged in the others.
+ */
 import type { ReactNode } from "react";
-import type { OnChangeFn as TanstackOnChangeFn, Row as TanstackRow, RowSelectionState as TanstackRowSelectionState, SortingState as TanstackSortingState, Table as TanstackTable } from "@tanstack/react-table";
-import type { TextVariant } from "../text/Text";
-export declare enum TableVariant {
-    BASE = "BASE",
-    PRIMARY = "PRIMARY",
-    SECONDARY = "SECONDARY",
-    TERTIARY = "TERTIARY"
-}
-export declare enum TableDensity {
-    SMALL = "SMALL",
-    MEDIUM = "MEDIUM",
-    LARGE = "LARGE"
-}
-export declare enum ColumnPin {
-    LEFT = "LEFT",
-    RIGHT = "RIGHT"
-}
-export declare enum ColumnAlign {
-    LEFT = "LEFT",
-    CENTER = "CENTER",
-    RIGHT = "RIGHT"
-}
-export declare enum ColumnResizeMode {
-    /** Column width follows the pointer while dragging. */
-    ON_CHANGE = "ON_CHANGE",
-    /** Column width commits once the drag ends. */
-    ON_END = "ON_END"
+import type { TextProps } from "../text/Text.js";
+import type { Side } from "../theme/enums.js";
+/** Side a column sticks to while the table scrolls sideways. */
+export type TableColumnPin = Side.LEFT | Side.RIGHT;
+/** Horizontal alignment of a column's header and cells (the `Text` `align` values). */
+export type TableColumnAlign = NonNullable<TextProps["align"]>;
+/** What a column's `cell` renderer receives. */
+export interface TableCellContext<TData, TValue = unknown> {
+    /** The column's `accessor` result for this row (`undefined` without an accessor). */
+    value: TValue;
+    /** The row's data object. */
+    row: TData;
+    /** Position of the row in the table body, from 0. */
+    rowIndex: number;
+    /** The row's id (`getRowId`). */
+    rowId: string;
 }
-export interface ColumnDef<TData, TValue = unknown> {
+/** One column of a table. */
+export interface TableColumn<TData, TValue = unknown> {
+    /** Stable identity; used by sorting, `columnLayout` and React keys. */
     id: string;
-    accessorFn?: (row: TData) => TValue;
-    header?: string | ((props: {
-        table: TanstackTable<TData>;
-    }) => ReactNode);
-    cell?: (props: {
-        value: TValue;
-        row: TanstackRow<TData>;
-    }) => ReactNode;
-    size?: number;
-    minSize?: number;
-    maxSize?: number;
-    pin?: ColumnPin;
-    enableSorting?: boolean;
-    sortDescFirst?: boolean;
-    enableResizing?: boolean;
-    align?: ColumnAlign;
-    cellLoading?: () => ReactNode;
-    headerAriaLabel?: string;
-}
-export interface EstimateColumnWidthOptions {
+    /** Column name, shown in the header and used by the Columns menu, the resize handle and screen readers. */
+    header: string;
+    /** Reads the cell value from a row. Sorting compares these values. */
+    accessor?(row: TData): TValue;
+    /** Renders the cell. Without it the value renders as one line of text. Must stay cheap; it runs for every visible row. */
+    cell?(context: TableCellContext<TData, TValue>): ReactNode;
+    /** Content of this column's cell in the sticky footer row (a total). A string renders as medium-weight text. */
+    footer?: ReactNode;
+    /** Width in pixels. Without it the column shares the leftover space. */
+    width?: number;
+    /** Smallest width in pixels, when resizing or sharing space. @default 60 */
     minWidth?: number;
+    /** Largest width in pixels when resizing. @default 800 */
     maxWidth?: number;
-    charWidth?: number;
-    padding?: number;
-}
-/** Column widths keyed by column id, as produced by resizing. */
-export type ColumnSizingState = Record<string, number>;
-/**
- * Props shared by every table surface — dimensions, paging, loading/error
- * states and resizing behave identically whether or not rows are virtualized.
- */
-export interface BaseTableProps<TData> {
-    columns: ColumnDef<TData, unknown>[];
-    getRowId?: (row: TData, index: number) => string;
-    height?: number | string;
-    minHeight?: number | string;
-    maxHeight?: number | string;
-    width?: number | string;
-    fillWidth?: boolean;
-    fillHeight?: boolean;
-    density?: TableDensity;
-    variant?: TableVariant;
-    hasNextPage?: boolean;
-    isFetchingNextPage?: boolean;
-    fetchNextPage?: () => void;
-    isLoading?: boolean;
-    isError?: boolean;
-    error?: Error;
-    loadingRowCount?: number;
-    contentWhenEmpty?: ReactNode;
-    contentWhenError?: ReactNode | ((error?: Error) => ReactNode);
-    noHeader?: boolean;
-    noLastRowBorder?: boolean;
-    noLastRowPadding?: boolean;
-    enableColumnResizing?: boolean;
-    columnSizing?: ColumnSizingState;
-    defaultColumnSizing?: ColumnSizingState;
-    onColumnSizingChange?: (columnSizing: ColumnSizingState) => void;
-    columnResizeMode?: ColumnResizeMode;
-    ariaLabel?: string;
-    ariaLabelledBy?: string;
-}
-export interface InfiniteTableProps<TData> extends BaseTableProps<TData> {
-    data: TData[];
-    enableRowSelection?: boolean | ((row: TanstackRow<TData>) => boolean);
-    enableMultiRowSelection?: boolean;
-    rowSelection?: TanstackRowSelectionState;
-    defaultRowSelection?: TanstackRowSelectionState;
-    onRowSelectionChange?: TanstackOnChangeFn<TanstackRowSelectionState>;
-    onSelectedRowsChange?: (rows: TanstackRow<TData>[]) => void;
-    /** Renders a leading checkbox column that can actually toggle selection. */
-    showSelectionColumn?: boolean;
-    selectionColumnPin?: ColumnPin;
-    enableSelectAll?: boolean;
-    /** Shift-click selects the range between the last click and this row. */
-    enableSelectionRange?: boolean;
-    selectAllAriaLabel?: string;
-    getRowSelectAriaLabel?: (row: TanstackRow<TData>) => string;
-    enableSorting?: boolean;
-    enableMultiSort?: boolean;
-    sorting?: TanstackSortingState;
-    onSortingChange?: TanstackOnChangeFn<TanstackSortingState>;
-    manualSorting?: boolean;
-    onRowExpand?: (row: TanstackRow<TData>) => ReactNode;
-    expandedRowIds?: string[];
-    defaultExpandedRowIds?: string[];
-    onExpandedChange?: (expandedRowIds: string[]) => void;
-    getRowCanExpand?: (row: TanstackRow<TData>) => boolean;
-    /** When false, expanding a row collapses whichever row was open. */
-    enableMultiRowExpansion?: boolean;
-    showExpandColumn?: boolean;
-    expandColumnPin?: ColumnPin;
-    onRowClick?: (row: TanstackRow<TData>, event: React.MouseEvent) => void;
-    onRowDoubleClick?: (row: TanstackRow<TData>, event: React.MouseEvent) => void;
-    /** Fired by click *and* by Enter/Space when a row has keyboard focus. */
-    onRowActivate?: (row: TanstackRow<TData>, event: React.MouseEvent | React.KeyboardEvent) => void;
-    getRowAriaLabel?: (row: TanstackRow<TData>) => string;
-    enableRowFocus?: boolean;
-    onTableReady?: (table: TanstackTable<TData>) => void;
-}
-export interface VirtualizedInfiniteTableProps<TData> extends BaseTableProps<TData> {
-    totalRowCount: number;
-    getRowData: (index: number) => TData | undefined;
-    estimateRowHeight?: number;
-    overscan?: number;
-    onRowClick?: (row: TanstackRow<TData>, event: React.MouseEvent) => void;
-}
-export type { TanstackRow as Row, TanstackTable as Table };
-export declare enum CellEnrichmentStatus {
-    IDLE = "IDLE",
-    PENDING = "PENDING",
-    RUNNING = "RUNNING",
-    COMPLETE = "COMPLETE",
-    ERROR = "ERROR"
-}
-export declare enum SpreadsheetCellType {
-    TEXT = "TEXT",
-    NUMBER = "NUMBER",
-    BOOLEAN = "BOOLEAN",
-    ENUM = "ENUM",
-    DATE = "DATE",
-    READONLY = "READONLY"
-}
-/**
- * Row access handed to a column-level enrichment action.
- *
- * A spreadsheet is virtualized over an index, so there is no row array to pass.
- * Actions that genuinely need every row call `getLoadedRows()`; actions that
- * only need a count read `totalRowCount` without paying for a full scan.
- */
-export interface SpreadsheetRowsContext<TData> {
-    totalRowCount: number;
-    getRowData: (index: number) => TData | undefined;
-    /**
-     * Materializes every currently-loaded row, skipping indices that have not
-     * been fetched. O(totalRowCount) — call once, never per row.
-     */
-    getLoadedRows: () => TData[];
-}
-export interface SpreadsheetColumnAction<TData> {
-    id: string;
-    label: string;
-    icon?: ReactNode;
-    onAction: (columnId: string, rows: SpreadsheetRowsContext<TData>) => void;
-}
-export interface SpreadsheetHeaderAction {
-    id: string;
-    label: string;
-    icon?: ReactNode;
-    variant?: TextVariant;
-    onAction: (columnId: string) => void;
-}
-/**
- * A spreadsheet column.
- *
- * Extends `ColumnDef` so `id`, `accessorFn`, sizing, `pin`, `align`,
- * `cellLoading`, `enableResizing` and `headerAriaLabel` have one definition
- * across the domain — and so these columns feed `useTableColumnLayout` and
- * `useTableColumnResize` without a cast.
- *
- * `header` is narrowed to a string and sorting is dropped: the spreadsheet
- * header owns its own menu affordance, and there is no table instance to hand
- * a header render function.
- */
-export interface SpreadsheetColumnDef<TData, TValue = unknown> extends Omit<ColumnDef<TData, TValue>, "cell" | "header" | "enableSorting" | "sortDescFirst"> {
-    header?: string;
-    /**
-     * Custom cell renderer.
-     *
-     * `row` carries only `original` and `index` — a virtualized spreadsheet has
-     * no TanStack row model behind it, so row methods (`id`, `getIsSelected`,
-     * `subRows`, `getValue`) are absent at runtime despite being on the type.
-     *
-     * `isEditing` is optional on purpose: it keeps this signature assignable to
-     * `ColumnDef["cell"]`, which is what lets the shared layout and resize hooks
-     * consume these columns unchanged.
-     */
-    cell?: (props: {
-        value: TValue;
-        row: TanstackRow<TData>;
-        isEditing?: boolean;
-    }) => ReactNode;
-    cellType: SpreadsheetCellType;
-    editable?: boolean;
-    enumOptions?: string[];
-    onCellChange?: (rowIndex: number, row: TData, value: TValue) => void;
-    headerActions?: SpreadsheetHeaderAction[];
-    enrichmentActions?: SpreadsheetColumnAction<TData>[];
-    getCellEnrichmentStatus?: (row: TData, rowIndex: number) => CellEnrichmentStatus;
-}
-export interface SpreadsheetRowAction<TData> {
-    id: string;
-    label: string;
-    icon?: ReactNode;
-    onAction: (rowIndex: number, row: TData) => void;
-}
-export interface EditingCell {
-    rowIndex: number;
+    /** Alignment of the header and cells. Use "right" for numbers. @default "left" */
+    align?: TableColumnAlign;
+    /** Keeps the column in view at the left or right edge while the table scrolls sideways. Give pinned columns a `width`. */
+    pin?: TableColumnPin;
+    /** This column's value names the row (a name or title). Its cells are row headers, and it labels the row's checkbox and actions. */
+    isRowHeader?: boolean;
+    /** The header sorts the table when pressed. @default false */
+    canSort?: boolean;
+    /** The column can be resized. @default the table's `canResizeColumns` */
+    canResize?: boolean;
+    /** The column can be hidden from the Columns menu. @default the table's `canCustomizeColumns` */
+    canHide?: boolean;
+    /** Menu rows (`MenuItem`, …) for a menu opened from a "…" button in this column's header. */
+    actions?: ReactNode;
+}
+/** The sorted column. */
+export interface TableSort {
+    /** `id` of the sorted column. */
     columnId: string;
-}
-/**
- * Inherits dimensions, density, variant, paging, loading/error state,
- * controlled column sizing and the ARIA labels from the virtualized table.
- *
- * `onRowClick` is omitted deliberately: a whole-row click target would fight
- * the per-cell click-to-edit affordance.
- */
-export interface InfiniteSpreadsheetProps<TData> extends Omit<VirtualizedInfiniteTableProps<TData>, "columns" | "onRowClick"> {
-    columns: SpreadsheetColumnDef<TData, unknown>[];
-    /** Renders the trailing action column with an add-column control. */
-    onAddColumn?: () => void;
-    addColumnAriaLabel?: string;
-    rowActions?: SpreadsheetRowAction<TData>[];
-    getRowActionsAriaLabel?: (rowIndex: number) => string;
-    /** Controlled when provided; uncontrolled otherwise. */
-    editingCell?: EditingCell | null;
-    onEditingCellChange?: (cell: EditingCell | null) => void;
-    /** Roving-tabindex row focus and arrow-key row navigation. Defaults to true. */
-    enableRowFocus?: boolean;
+    /** Sorted high to low (Z–A, newest first). */
+    isDescending: boolean;
+}
+/** The user's arrangement of the columns. Every field is optional; missing fields mean "as defined in `columns`". */
+export interface TableColumnLayout {
+    /** Column ids in display order. Ids not listed follow in `columns` order; unknown ids are ignored. */
+    order?: string[];
+    /** Ids of hidden columns. */
+    hiddenIds?: string[];
+    /** Widths in pixels set by resizing, by column id. They win over `width`. */
+    widths?: Record<string, number>;
 }

package/dist/table/types.js

@@ -1,51 +0,0 @@
-//#region src/table/types.ts
-var TableVariant = /* @__PURE__ */ function(TableVariant) {
-	TableVariant["BASE"] = "BASE";
-	TableVariant["PRIMARY"] = "PRIMARY";
-	TableVariant["SECONDARY"] = "SECONDARY";
-	TableVariant["TERTIARY"] = "TERTIARY";
-	return TableVariant;
-}({});
-var TableDensity = /* @__PURE__ */ function(TableDensity) {
-	TableDensity["SMALL"] = "SMALL";
-	TableDensity["MEDIUM"] = "MEDIUM";
-	TableDensity["LARGE"] = "LARGE";
-	return TableDensity;
-}({});
-var ColumnPin = /* @__PURE__ */ function(ColumnPin) {
-	ColumnPin["LEFT"] = "LEFT";
-	ColumnPin["RIGHT"] = "RIGHT";
-	return ColumnPin;
-}({});
-var ColumnAlign = /* @__PURE__ */ function(ColumnAlign) {
-	ColumnAlign["LEFT"] = "LEFT";
-	ColumnAlign["CENTER"] = "CENTER";
-	ColumnAlign["RIGHT"] = "RIGHT";
-	return ColumnAlign;
-}({});
-var ColumnResizeMode = /* @__PURE__ */ function(ColumnResizeMode) {
-	/** Column width follows the pointer while dragging. */
-	ColumnResizeMode["ON_CHANGE"] = "ON_CHANGE";
-	/** Column width commits once the drag ends. */
-	ColumnResizeMode["ON_END"] = "ON_END";
-	return ColumnResizeMode;
-}({});
-var CellEnrichmentStatus = /* @__PURE__ */ function(CellEnrichmentStatus) {
-	CellEnrichmentStatus["IDLE"] = "IDLE";
-	CellEnrichmentStatus["PENDING"] = "PENDING";
-	CellEnrichmentStatus["RUNNING"] = "RUNNING";
-	CellEnrichmentStatus["COMPLETE"] = "COMPLETE";
-	CellEnrichmentStatus["ERROR"] = "ERROR";
-	return CellEnrichmentStatus;
-}({});
-var SpreadsheetCellType = /* @__PURE__ */ function(SpreadsheetCellType) {
-	SpreadsheetCellType["TEXT"] = "TEXT";
-	SpreadsheetCellType["NUMBER"] = "NUMBER";
-	SpreadsheetCellType["BOOLEAN"] = "BOOLEAN";
-	SpreadsheetCellType["ENUM"] = "ENUM";
-	SpreadsheetCellType["DATE"] = "DATE";
-	SpreadsheetCellType["READONLY"] = "READONLY";
-	return SpreadsheetCellType;
-}({});
-//#endregion
-export { CellEnrichmentStatus, ColumnAlign, ColumnPin, ColumnResizeMode, SpreadsheetCellType, TableDensity, TableVariant };

package/dist/table/useInfiniteScrollSentinel.d.ts

@@ -1,24 +1,28 @@
-interface UseInfiniteScrollSentinelOptions {
-    scrollRef: React.RefObject<HTMLElement | null>;
-    hasNextPage?: boolean;
-    isFetchingNextPage?: boolean;
-    fetchNextPage?: () => void;
-    /**
-     * Number of rows currently rendered. Changing it re-arms the observer, which
-     * is what makes a short first page keep paging until the viewport fills.
-     */
-    rowCount: number;
-}
 /**
- * Drives infinite scroll from an `IntersectionObserver` on a sentinel element
- * placed after the last row.
- *
- * A plain `scroll` listener can dead-end: if the first page is shorter than the
- * viewport, no scroll event ever fires and paging never starts. Re-observing an
- * already-intersecting sentinel re-fires the callback, so this keeps pumping
- * until the content overflows or `hasNextPage` goes false.
+ * @internal Shared by the table components; apps use InfiniteTable, VirtualizedInfiniteTable or
+ * InfiniteSpreadsheet.
  *
- * @returns A ref to attach to the sentinel element.
+ * The `onEndReached` sentinel: a 1px element after the table, observed with an
+ * `IntersectionObserver` whose bottom margin is `marginPx` (`TABLE_END_REACHED_MARGIN_PX`). The root is the
+ * scroll container when it overflows, otherwise the viewport, so a table in an unbounded parent
+ * pages on page scroll. Armed only while enabled (not loading, no error), re-armed when the row
+ * count changes, and calls `onEndReached` at most once per row count: an app with no next page
+ * adds no rows, so it is not called again. Without `IntersectionObserver` it falls back to a
+ * passive `scroll` listener. Nothing runs at module scope.
  */
-export declare function useInfiniteScrollSentinel({ scrollRef, hasNextPage, isFetchingNextPage, fetchNextPage, rowCount, }: UseInfiniteScrollSentinelOptions): import("react").RefObject<HTMLDivElement>;
-export {};
+import { type RefObject } from "react";
+/** @internal Options for `useInfiniteScrollSentinel`. */
+export interface UseInfiniteScrollSentinelOptions {
+    /** The table's scroll container. */
+    scrollRef: RefObject<HTMLElement | null>;
+    /** Called when the end comes within reach; omitted, nothing is observed. */
+    onEndReached: (() => void) | undefined;
+    /** False while loading or in error: paging pauses. */
+    isEnabled: boolean;
+    /** Loaded rows; a change re-arms the observer. */
+    rowCount: number;
+    /** How far below the visible area the end counts as reached, in pixels. */
+    marginPx: number;
+}
+/** @internal Observes the sentinel and calls `onEndReached`; returns the sentinel's ref. */
+export declare function useInfiniteScrollSentinel({ scrollRef, onEndReached, isEnabled, rowCount, marginPx, }: UseInfiniteScrollSentinelOptions): RefObject<HTMLDivElement | null>;

package/dist/table/useInfiniteScrollSentinel.js

@@ -1,51 +1,59 @@
-import "./utils.js";
 import { useEffect, useRef } from "react";
 //#region src/table/useInfiniteScrollSentinel.ts
 /**
-* Drives infinite scroll from an `IntersectionObserver` on a sentinel element
-* placed after the last row.
+* @internal Shared by the table components; apps use InfiniteTable, VirtualizedInfiniteTable or
+* InfiniteSpreadsheet.
 *
-* A plain `scroll` listener can dead-end: if the first page is shorter than the
-* viewport, no scroll event ever fires and paging never starts. Re-observing an
-* already-intersecting sentinel re-fires the callback, so this keeps pumping
-* until the content overflows or `hasNextPage` goes false.
-*
-* @returns A ref to attach to the sentinel element.
+* The `onEndReached` sentinel: a 1px element after the table, observed with an
+* `IntersectionObserver` whose bottom margin is `marginPx` (`TABLE_END_REACHED_MARGIN_PX`). The root is the
+* scroll container when it overflows, otherwise the viewport, so a table in an unbounded parent
+* pages on page scroll. Armed only while enabled (not loading, no error), re-armed when the row
+* count changes, and calls `onEndReached` at most once per row count: an app with no next page
+* adds no rows, so it is not called again. Without `IntersectionObserver` it falls back to a
+* passive `scroll` listener. Nothing runs at module scope.
 */
-function useInfiniteScrollSentinel({ scrollRef, hasNextPage, isFetchingNextPage, fetchNextPage, rowCount }) {
+/** @internal Observes the sentinel and calls `onEndReached`; returns the sentinel's ref. */
+function useInfiniteScrollSentinel({ scrollRef, onEndReached, isEnabled, rowCount, marginPx }) {
 	const sentinelRef = useRef(null);
-	const fetchNextPageRef = useRef(fetchNextPage);
-	useEffect(() => {
-		fetchNextPageRef.current = fetchNextPage;
-	});
-	const canFetch = fetchNextPage !== void 0;
+	const onEndReachedRef = useRef(onEndReached);
+	onEndReachedRef.current = onEndReached;
+	const calledForCountRef = useRef(null);
+	const hasHandler = onEndReached !== void 0;
 	useEffect(() => {
-		const root = scrollRef.current;
+		const scroll = scrollRef.current;
 		const sentinel = sentinelRef.current;
-		if (!root || !sentinel || !canFetch || !hasNextPage || isFetchingNextPage) return;
+		if (!hasHandler || !isEnabled || scroll === null || sentinel === null) return;
+		if (calledForCountRef.current === rowCount) return;
+		const reach = () => {
+			if (calledForCountRef.current === rowCount) return;
+			calledForCountRef.current = rowCount;
+			onEndReachedRef.current?.();
+		};
+		const isScrollRoot = scroll.scrollHeight > scroll.clientHeight;
 		if (typeof IntersectionObserver === "undefined") {
-			const onScroll = () => {
-				const { scrollHeight, scrollTop, clientHeight } = root;
-				if (scrollHeight - scrollTop - clientHeight < 500) fetchNextPageRef.current?.();
+			const target = isScrollRoot ? scroll : window;
+			const check = () => {
+				const bottom = isScrollRoot ? scroll.getBoundingClientRect().bottom : window.innerHeight;
+				if (sentinel.getBoundingClientRect().top - bottom < marginPx) reach();
 			};
-			onScroll();
-			root.addEventListener("scroll", onScroll, { passive: true });
-			return () => root.removeEventListener("scroll", onScroll);
+			check();
+			target.addEventListener("scroll", check, { passive: true });
+			return () => target.removeEventListener("scroll", check);
 		}
 		const observer = new IntersectionObserver((entries) => {
-			if (entries.some((entry) => entry.isIntersecting)) fetchNextPageRef.current?.();
+			if (entries.some((entry) => entry.isIntersecting)) reach();
 		}, {
-			root,
-			rootMargin: `0px 0px 500px 0px`
+			root: isScrollRoot ? scroll : null,
+			rootMargin: `0px 0px ${marginPx}px 0px`
 		});
 		observer.observe(sentinel);
 		return () => observer.disconnect();
 	}, [
 		scrollRef,
-		canFetch,
-		hasNextPage,
-		isFetchingNextPage,
-		rowCount
+		hasHandler,
+		isEnabled,
+		rowCount,
+		marginPx
 	]);
 	return sentinelRef;
 }

package/dist/table/useSpreadsheetCellNavigation.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @internal Shared by InfiniteSpreadsheet; apps use InfiniteSpreadsheet.
+ *
+ * Roving cell focus over a spreadsheet body (the WAI-ARIA grid pattern): one cell is the tab stop
+ * (`tabIndex` 0), every other -1. Arrow keys move one cell, Home / End go to the ends of the row,
+ * Ctrl/Cmd+Home / End to the first / last cell of the grid, PageUp / PageDown one visible page.
+ * A move scrolls the row into the virtual window first (`scrollToIndex`), focuses the cell once it
+ * is mounted and scrolls it into view sideways. A cell element replaced in place (a skeleton row
+ * whose data arrives, a row re-keyed by id) takes the focus back on mount.
+ */
+import { type KeyboardEvent } from "react";
+/** @internal A cell of the navigation grid (column index over the navigable columns). */
+export interface SpreadsheetGridCell {
+    /** Row index, from 0. */
+    rowIndex: number;
+    /** Column index among the navigable columns, from 0. */
+    columnIndex: number;
+}
+/** @internal Options for `useSpreadsheetCellNavigation`. */
+export interface UseSpreadsheetCellNavigationOptions {
+    /** Rows, loaded or not. */
+    rowCount: number;
+    /** Navigable columns (visible columns, plus the row-actions column). */
+    columnCount: number;
+    /** Rows in one visible page, for PageUp / PageDown. */
+    getPageSize: () => number;
+    /** Brings a row into the rendered window. */
+    scrollToIndex: (rowIndex: number) => void;
+}
+/** @internal What `useSpreadsheetCellNavigation` returns. */
+export interface SpreadsheetCellNavigation {
+    /** The tab-stop cell, clamped to the grid. */
+    active: SpreadsheetGridCell;
+    /** Ref registration for each rendered cell. */
+    registerCell: (rowIndex: number, columnIndex: number, element: HTMLElement | null) => void;
+    /** Makes a cell the tab stop and focuses it (scrolling it into view). */
+    focusCell: (rowIndex: number, columnIndex: number) => void;
+    /** A cell received focus: it becomes the tab stop. */
+    handleCellFocus: (rowIndex: number, columnIndex: number) => void;
+    /** Moves for a navigation key from `from`; returns `true` when the key was handled. */
+    handleNavigationKey: (from: SpreadsheetGridCell, event: KeyboardEvent<HTMLElement>) => boolean;
+}
+/** @internal Roving focus over the cells of a spreadsheet body. */
+export declare function useSpreadsheetCellNavigation({ rowCount, columnCount, getPageSize, scrollToIndex, }: UseSpreadsheetCellNavigationOptions): SpreadsheetCellNavigation;