@tanstack/table-core 9.0.0-beta.56 → 9.0.0-beta.58

package/dist/core/row-models/createCoreRowModel.js

@@ -1,5 +1,6 @@
 import { makeObjectMap, tableMemo } from "../../utils.js";
 import { constructRow } from "../rows/constructRow.js";
+import { table_autoResetCellSelection } from "../../features/cell-selection/cellSelectionFeature.utils.js";
 import { table_autoResetPageIndex } from "../../features/row-pagination/rowPaginationFeature.utils.js";
 
 //#region src/core/row-models/createCoreRowModel.ts
@@ -16,7 +17,10 @@ function createCoreRowModel() {
 			fnName: "table.getCoreRowModel",
 			memoDeps: () => [table.options.data],
 			fn: () => _createCoreRowModel(table, table.options.data),
-			onAfterUpdate: () => table_autoResetPageIndex(table)
+			onAfterUpdate: () => {
+				table_autoResetPageIndex(table);
+				table_autoResetCellSelection(table);
+			}
 		});
 	};
 }

package/dist/features/cell-selection/cellSelectionFeature.d.ts

@@ -0,0 +1,9 @@
+import { TableFeature } from "../../types/TableFeatures.js";
+
+//#region src/features/cell-selection/cellSelectionFeature.d.ts
+/**
+ * Feature that adds spreadsheet-style cell range selection state and APIs.
+ */
+declare const cellSelectionFeature: TableFeature;
+//#endregion
+export { cellSelectionFeature };

package/dist/features/cell-selection/cellSelectionFeature.js

@@ -0,0 +1,117 @@
+import { assignPrototypeAPIs, assignTableAPIs, callMemoOrStaticFn, makeStateUpdater } from "../../utils.js";
+import { cell_getCanSelect, cell_getIsFocused, cell_getIsSelected, cell_getSelectionEdges, cell_getSelectionExtendHandler, cell_getSelectionStartHandler, cell_getTabIndex, getDefaultCellSelectionState, table_autoResetCellSelection, table_extendCellSelection, table_getCellSelectionBounds, table_getCellSelectionColumnIds, table_getCellSelectionColumnIndexes, table_getCellSelectionRowIds, table_getFocusedCell, table_getSelectedCellCount, table_getSelectedCellIds, table_getSelectedCellRangesData, table_moveCellSelection, table_resetCellSelection, table_selectAllCells, table_selectCellRange, table_setCellSelection, table_setFocusedCell } from "./cellSelectionFeature.utils.js";
+
+//#region src/features/cell-selection/cellSelectionFeature.ts
+/**
+* Feature that adds spreadsheet-style cell range selection state and APIs.
+*/
+const cellSelectionFeature = {
+	initTableInstanceData: (table) => {
+		table._isSelectingCells = false;
+	},
+	resetTableInstanceData: (table) => {
+		table._isSelectingCells = false;
+	},
+	getInitialState: (initialState) => {
+		return {
+			cellSelection: getDefaultCellSelectionState(),
+			...initialState
+		};
+	},
+	getDefaultTableOptions: (table) => {
+		return {
+			onCellSelectionChange: makeStateUpdater("cellSelection", table),
+			autoResetCellSelection: true,
+			enableCellSelection: true,
+			enableCellRangeSelection: true,
+			enableMultiCellRangeSelection: true,
+			enableCellSelectionDrag: true,
+			isCellRangeSelectionEvent: (event) => {
+				const rangeEvent = event;
+				return Boolean(rangeEvent.shiftKey || rangeEvent.nativeEvent?.shiftKey);
+			},
+			isMultiCellRangeSelectionEvent: (event) => {
+				const multiEvent = event;
+				return Boolean(multiEvent.ctrlKey || multiEvent.metaKey || multiEvent.nativeEvent?.ctrlKey || multiEvent.nativeEvent?.metaKey);
+			}
+		};
+	},
+	assignCellPrototype: (prototype, table) => {
+		assignPrototypeAPIs("cellSelectionFeature", prototype, table, {
+			cell_getCanSelect: { fn: (cell) => cell_getCanSelect(cell) },
+			cell_getIsSelected: { fn: (cell) => cell_getIsSelected(cell) },
+			cell_getIsFocused: { fn: (cell) => cell_getIsFocused(cell) },
+			cell_getTabIndex: { fn: (cell) => cell_getTabIndex(cell) },
+			cell_getSelectionEdges: { fn: (cell) => cell_getSelectionEdges(cell) },
+			cell_getSelectionStartHandler: { fn: (cell, contextDocument) => cell_getSelectionStartHandler(cell, contextDocument) },
+			cell_getSelectionExtendHandler: { fn: (cell) => cell_getSelectionExtendHandler(cell) }
+		});
+	},
+	constructTableAPIs: (table) => {
+		assignTableAPIs("cellSelectionFeature", table, {
+			table_setCellSelection: { fn: (updater) => table_setCellSelection(table, updater) },
+			table_resetCellSelection: { fn: (defaultState) => table_resetCellSelection(table, defaultState) },
+			table_autoResetCellSelection: { fn: () => table_autoResetCellSelection(table) },
+			table_getCellSelectionColumnIndexes: {
+				fn: () => table_getCellSelectionColumnIndexes(table),
+				memoDeps: () => [
+					table.atoms.columnVisibility?.get(),
+					table.atoms.columnOrder?.get(),
+					table.atoms.columnPinning?.get(),
+					table.atoms.grouping?.get(),
+					table.options.columns,
+					table.options.groupedColumnMode
+				]
+			},
+			table_getCellSelectionBounds: {
+				fn: () => table_getCellSelectionBounds(table),
+				memoDeps: () => [
+					table.atoms.cellSelection?.get(),
+					table.getRowsInDisplayOrder(),
+					callMemoOrStaticFn(table, "getCellSelectionColumnIndexes", table_getCellSelectionColumnIndexes)
+				]
+			},
+			table_selectCellRange: { fn: (range, opts) => table_selectCellRange(table, range, opts) },
+			table_selectAllCells: { fn: () => table_selectAllCells(table) },
+			table_setFocusedCell: { fn: (rowId, columnId) => table_setFocusedCell(table, rowId, columnId) },
+			table_getFocusedCell: { fn: () => table_getFocusedCell(table) },
+			table_moveCellSelection: { fn: (direction) => table_moveCellSelection(table, direction) },
+			table_extendCellSelection: { fn: (direction) => table_extendCellSelection(table, direction) },
+			table_getSelectedCellIds: {
+				fn: () => table_getSelectedCellIds(table),
+				memoDeps: () => [
+					callMemoOrStaticFn(table, "getCellSelectionBounds", table_getCellSelectionBounds),
+					table.getRowsInDisplayOrder(),
+					table.options.enableCellSelection
+				]
+			},
+			table_getSelectedCellRangesData: {
+				fn: () => table_getSelectedCellRangesData(table),
+				memoDeps: () => [
+					callMemoOrStaticFn(table, "getCellSelectionBounds", table_getCellSelectionBounds),
+					table.getRowsInDisplayOrder(),
+					table.options.enableCellSelection
+				]
+			},
+			table_getSelectedCellCount: {
+				fn: () => table_getSelectedCellCount(table),
+				memoDeps: () => [
+					callMemoOrStaticFn(table, "getCellSelectionBounds", table_getCellSelectionBounds),
+					table.getRowsInDisplayOrder(),
+					table.options.enableCellSelection
+				]
+			},
+			table_getCellSelectionRowIds: {
+				fn: () => table_getCellSelectionRowIds(table),
+				memoDeps: () => [callMemoOrStaticFn(table, "getCellSelectionBounds", table_getCellSelectionBounds), table.getRowsInDisplayOrder()]
+			},
+			table_getCellSelectionColumnIds: {
+				fn: () => table_getCellSelectionColumnIds(table),
+				memoDeps: () => [callMemoOrStaticFn(table, "getCellSelectionBounds", table_getCellSelectionBounds)]
+			}
+		});
+	}
+};
+
+//#endregion
+export { cellSelectionFeature };

package/dist/features/cell-selection/cellSelectionFeature.types.d.ts

@@ -0,0 +1,273 @@
+import { CellData, OnChangeFn, RowData, Updater } from "../../types/type-utils.js";
+import { Cell } from "../../types/Cell.js";
+import { TableFeatures } from "../../types/TableFeatures.js";
+
+//#region src/features/cell-selection/cellSelectionFeature.types.d.ts
+/**
+ * A single rectangular cell selection, stored as its two defining corners.
+ *
+ * The `anchor` corner stays put while the `focus` corner moves during a
+ * shift-extend or a drag, so the pair carries strictly more information than a
+ * normalized min/max rectangle would. Corners are stored as flat row and column
+ * ids rather than nested objects or a packed `rowId_columnId` key, because
+ * `getRowId` is user-supplied and may return ids containing any separator.
+ */
+interface CellSelectionRange {
+  anchorColumnId: string;
+  anchorRowId: string;
+  focusColumnId: string;
+  focusRowId: string;
+}
+/**
+ * The selected rectangles. The last entry is the active one that shift-extend
+ * and drag operate on.
+ *
+ * A bare array, matching `SortingState` and `ColumnFiltersState`. Drag session
+ * state deliberately lives outside this slice as non-reactive instance data, so
+ * nothing here is transient and the whole slice is safe to persist.
+ */
+type CellSelectionState = Array<CellSelectionRange>;
+interface TableState_CellSelection {
+  cellSelection: CellSelectionState;
+}
+/**
+ * A range resolved into inclusive display-order indexes.
+ *
+ * Ranges whose corners no longer resolve are omitted rather than clamped, so a
+ * range with a filtered-out corner contributes nothing while remaining in state.
+ */
+interface CellSelectionBounds {
+  maxColumnIndex: number;
+  maxRowIndex: number;
+  minColumnIndex: number;
+  minRowIndex: number;
+}
+/**
+ * Which sides of a selected cell sit on the outer boundary of the selection.
+ */
+interface CellSelectionEdges {
+  bottom: boolean;
+  left: boolean;
+  right: boolean;
+  top: boolean;
+}
+type CellSelectionDirection = 'up' | 'down' | 'left' | 'right';
+interface SelectCellRangeOptions {
+  /**
+   * Whether the range should be added alongside existing ranges rather than
+   * replacing them. Defaults to `false`.
+   */
+  additive?: boolean;
+}
+interface TableOptions_CellSelection<in out TFeatures extends TableFeatures, in out TData extends RowData> {
+  /**
+   * Resets cell selection to `initialState.cellSelection` whenever `data`
+   * changes. Defaults to `true`.
+   *
+   * Ranges are stored as row and column ids, so new data would otherwise leave
+   * a selection pointing at rows that no longer exist, or silently re-select
+   * cells if the new data happens to reuse ids. Set to `false` to keep ranges
+   * across data changes, and note `autoResetAll` overrides this.
+   */
+  autoResetCellSelection?: boolean;
+  /**
+   * Enables inclusive cell range selection through shift-click and drag.
+   * Defaults to `true`.
+   */
+  enableCellRangeSelection?: boolean;
+  /**
+   * Allows cells to be selected.
+   *
+   * Provide a predicate to decide per cell. A column def may also opt out with
+   * its own `enableCellSelection: false`. Defaults to `true`.
+   */
+  enableCellSelection?: boolean | ((cell: Cell<TFeatures, TData, any>) => boolean);
+  /**
+   * Enables extending a selection by dragging across cells. Defaults to `true`.
+   */
+  enableCellSelectionDrag?: boolean;
+  /**
+   * Allows multiple disjoint rectangles to be selected at once. Defaults to
+   * `true`.
+   */
+  enableMultiCellRangeSelection?: boolean;
+  /**
+   * Determines whether a selection-start event should extend the active range
+   * instead of replacing the selection.
+   *
+   * By default, events with `shiftKey` directly on the event or on
+   * `event.nativeEvent` are treated as range-selection events.
+   */
+  isCellRangeSelectionEvent?: (event: unknown) => boolean;
+  /**
+   * Determines whether a selection-start event should add a new rectangle
+   * alongside the existing ones.
+   *
+   * By default, events with `ctrlKey` or `metaKey` directly on the event or on
+   * `event.nativeEvent` are treated as multi-range events.
+   */
+  isMultiCellRangeSelectionEvent?: (event: unknown) => boolean;
+  /**
+   * Called with an updater when cell selection state changes. Pair this with
+   * `state.cellSelection` when using external state; external atoms can own the
+   * slice without this callback.
+   *
+   * A drag emits one change per cell crossed. Subscribe to
+   * `table.atoms.cellSelection` for finer-grained reads when that matters.
+   */
+  onCellSelectionChange?: OnChangeFn<CellSelectionState>;
+}
+interface ColumnDef_CellSelection {
+  /**
+   * Allows cells in this column to be selected. Defaults to `true`.
+   */
+  enableCellSelection?: boolean;
+}
+interface Cell_CellSelection {
+  /**
+   * Checks whether this cell can currently be selected.
+   */
+  getCanSelect: () => boolean;
+  /**
+   * Checks whether this cell is the active cell, i.e. the anchor of the most
+   * recent range.
+   */
+  getIsFocused: () => boolean;
+  /**
+   * Checks whether this cell falls inside any selected range.
+   */
+  getIsSelected: () => boolean;
+  /**
+   * Returns which sides of this cell sit on the outer boundary of the
+   * selection, for rendering a spreadsheet-style outline without each cell
+   * inspecting its neighbours.
+   *
+   * All sides are `false` when the cell is not selected.
+   */
+  getSelectionEdges: () => CellSelectionEdges;
+  /**
+   * Creates a handler that extends the active range to this cell while a drag
+   * is in progress. Bind it to `mouseenter`.
+   *
+   * The handler no-ops unless a drag is open, and skips redundant writes when
+   * the active range already focuses this cell.
+   */
+  getSelectionExtendHandler: () => (event: unknown) => void;
+  /**
+   * Creates a handler that begins a selection at this cell. Bind it to
+   * `mousedown`.
+   *
+   * Pass the original mouse event, or a framework event whose `nativeEvent` is
+   * that event, so modifier keys can be detected. The handler attaches its own
+   * document-level `mouseup` listener so a drag released outside the table
+   * still ends correctly; pass `contextDocument` when the table renders into
+   * another document, such as an iframe or popout window.
+   */
+  getSelectionStartHandler: (contextDocument?: Document) => (event: unknown) => void;
+  /**
+   * Returns `0` for the focused cell and `-1` otherwise, for roving tabindex.
+   */
+  getTabIndex: () => number;
+}
+interface Table_CellSelection<in out TFeatures extends TableFeatures, in out TData extends RowData> {
+  /**
+   * Whether a drag selection is currently open.
+   *
+   * Non-reactive instance data rather than state: only the mouse handlers read
+   * it, nothing renders from it, and keeping it out of the slice means a
+   * selection persisted mid-drag cannot rehydrate into a stuck drag.
+   *
+   * @internal
+   */
+  _isSelectingCells: boolean;
+  /**
+   * Schedules a cell selection reset after `data` changes.
+   *
+   * Honors `autoResetAll` and `autoResetCellSelection`. Called by the core row
+   * model; you rarely need to invoke it yourself.
+   */
+  autoResetCellSelection: () => void;
+  /**
+   * Extends the active range one step in a direction, keeping its anchor fixed.
+   */
+  extendCellSelection: (direction: CellSelectionDirection) => void;
+  /**
+   * Returns the selected ranges resolved into inclusive display-order indexes.
+   *
+   * This is the memoized cache every per-cell read goes through. Ranges whose
+   * corners no longer resolve are omitted.
+   */
+  getCellSelectionBounds: () => Array<CellSelectionBounds>;
+  /**
+   * Returns the ids of all columns intersected by the selection.
+   */
+  getCellSelectionColumnIds: () => Array<string>;
+  /**
+   * Returns a column id to display-index map for the current column order.
+   *
+   * Registered so the lookup stays memoized even when `columnOrderingFeature`
+   * is absent, since its `getColumnIndexes` static rebuilds on every call.
+   *
+   * @internal
+   */
+  getCellSelectionColumnIndexes: () => Record<string, number>;
+  /**
+   * Returns the ids of all rows intersected by the selection.
+   */
+  getCellSelectionRowIds: () => Array<string>;
+  /**
+   * Returns the active cell, i.e. the anchor of the most recent range.
+   */
+  getFocusedCell: () => Cell<TFeatures, TData, any> | undefined;
+  /**
+   * Returns the number of selected cells.
+   *
+   * Computed as rectangle arithmetic for one range. Falls back to enumerating
+   * cells for overlapping ranges or a per-cell `enableCellSelection` predicate.
+   */
+  getSelectedCellCount: () => number;
+  /**
+   * Returns the unique ids of all selected cells, in row-major order.
+   *
+   * This expands the selection, so it costs one pass over the selected area.
+   * It is memoized and never runs unless called.
+   */
+  getSelectedCellIds: () => Array<string>;
+  /**
+   * Returns each selected range's values as a row-major grid.
+   *
+   * Indexed as `[rangeIndex][rowIndex][columnIndex]`. Serializing this to
+   * clipboard text is left to userland, since the delimiter, the null
+   * representation, and any quoting rules are application decisions.
+   */
+  getSelectedCellRangesData: () => Array<Array<Array<unknown>>>;
+  /**
+   * Moves the selection one step in a direction, collapsing it to a single
+   * cell. Columns that cannot be selected are skipped over.
+   */
+  moveCellSelection: (direction: CellSelectionDirection) => void;
+  /**
+   * Resets `cellSelection` to `initialState.cellSelection`.
+   *
+   * Pass `true` to ignore initial state and reset to an empty selection.
+   */
+  resetCellSelection: (defaultState?: boolean) => void;
+  /**
+   * Selects every selectable cell in the table as one range.
+   */
+  selectAllCells: () => void;
+  /**
+   * Selects a rectangle, replacing the current selection unless `additive`.
+   */
+  selectCellRange: (range: CellSelectionRange, opts?: SelectCellRangeOptions) => void;
+  /**
+   * Updates cell selection state with a next value or updater function.
+   */
+  setCellSelection: (updater: Updater<CellSelectionState>) => void;
+  /**
+   * Collapses the selection to a single cell at the given coordinates.
+   */
+  setFocusedCell: (rowId: string, columnId: string) => void;
+}
+//#endregion
+export { CellSelectionBounds, CellSelectionDirection, CellSelectionEdges, CellSelectionRange, CellSelectionState, Cell_CellSelection, ColumnDef_CellSelection, SelectCellRangeOptions, TableOptions_CellSelection, TableState_CellSelection, Table_CellSelection };