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

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 };

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

@@ -0,0 +1,288 @@
+import { CellData, RowData, Updater } from "../../types/type-utils.js";
+import { CellSelectionBounds, CellSelectionDirection, CellSelectionEdges, CellSelectionRange, CellSelectionState, SelectCellRangeOptions } from "./cellSelectionFeature.types.js";
+import { Table } from "../../types/Table.js";
+import { Cell } from "../../types/Cell.js";
+import { TableFeatures } from "../../types/TableFeatures.js";
+
+//#region src/features/cell-selection/cellSelectionFeature.utils.d.ts
+/**
+ * Creates the default cell selection state.
+ *
+ * The feature default is an empty selection. Reset APIs use this value when
+ * `defaultState` is `true`.
+ *
+ * @example
+ * ```ts
+ * const selection = getDefaultCellSelectionState()
+ * ```
+ */
+declare function getDefaultCellSelectionState(): CellSelectionState;
+/**
+ * Routes a cell selection updater through the table's selection change handler.
+ *
+ * @example
+ * ```ts
+ * table_setCellSelection(table, (old) => old.slice(0, -1))
+ * ```
+ */
+declare function table_setCellSelection<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>, updater: Updater<CellSelectionState>): void;
+/**
+ * Resets `cellSelection` to the configured initial state or feature default.
+ *
+ * With no argument, the reset clones `table.initialState.cellSelection` when it
+ * exists. Passing `true` ignores initial state and resets to an empty selection.
+ *
+ * @example
+ * ```ts
+ * table_resetCellSelection(table, true)
+ * ```
+ */
+declare function table_resetCellSelection<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>, defaultState?: boolean): void;
+/**
+ * Schedules a cell selection reset after `data` changes.
+ *
+ * Ranges are stored as row and column ids, so without this a data swap would
+ * leave a selection pointing at rows that no longer exist, or silently
+ * re-select cells whenever new data reuses ids. The reset runs when
+ * `autoResetAll` or `autoResetCellSelection` allows it, defaulting to on.
+ *
+ * Resetting to `initialState.cellSelection` rather than to empty means the
+ * first row-model computation is a no-op, matching `table_autoResetExpanded`.
+ *
+ * @example
+ * ```ts
+ * table_autoResetCellSelection(table)
+ * ```
+ */
+declare function table_autoResetCellSelection<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>): void;
+/**
+ * Builds a column id to render-order index map.
+ *
+ * Registered by this feature so the lookup stays memoized even when
+ * `columnOrderingFeature` is absent, since that feature's `getColumnIndexes`
+ * static rebuilds all four maps on every call, which would make per-cell reads
+ * O(columns).
+ *
+ * @example
+ * ```ts
+ * const index = table_getCellSelectionColumnIndexes(table)[columnId]
+ * ```
+ */
+declare function table_getCellSelectionColumnIndexes<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>): Record<string, number>;
+/**
+ * Resolves the selected ranges into inclusive display-order index rectangles.
+ *
+ * This is the single cache every per-cell read goes through, so index lookups
+ * happen once per invalidation rather than once per cell. A range whose corners
+ * no longer resolve, for example because its anchor row was filtered out, is
+ * omitted rather than clamped, so it contributes nothing while remaining in
+ * state and returns intact when the filter clears.
+ *
+ * @example
+ * ```ts
+ * const bounds = table_getCellSelectionBounds(table)
+ * ```
+ */
+declare function table_getCellSelectionBounds<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>): Array<CellSelectionBounds>;
+/**
+ * Checks whether this cell can currently be selected.
+ *
+ * A column def opting out with `enableCellSelection: false` wins over the table
+ * option, matching how the other per-column enable flags resolve.
+ *
+ * @example
+ * ```ts
+ * const canSelect = cell_getCanSelect(cell)
+ * ```
+ */
+declare function cell_getCanSelect<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;
+/**
+ * Checks whether this cell falls inside any selected range.
+ *
+ * Deliberately not memoized. Registering this through `assignPrototypeAPIs`
+ * with `memoDeps` would allocate a memo closure and dependency array per cell,
+ * which costs more than the handful of integer comparisons it would save.
+ *
+ * @example
+ * ```ts
+ * const isSelected = cell_getIsSelected(cell)
+ * ```
+ */
+declare function cell_getIsSelected<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;
+/**
+ * Checks whether this cell is the active cell.
+ *
+ * @example
+ * ```ts
+ * const isFocused = cell_getIsFocused(cell)
+ * ```
+ */
+declare function cell_getIsFocused<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;
+/**
+ * Returns `0` for the focused cell and `-1` otherwise, for roving tabindex.
+ *
+ * @example
+ * ```ts
+ * const tabIndex = cell_getTabIndex(cell)
+ * ```
+ */
+declare function cell_getTabIndex<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): number;
+/**
+ * Returns which sides of this cell sit on the outer boundary of the selection.
+ *
+ * A side is an edge when the neighbouring cell in that direction is not itself
+ * covered by a range, which is what lets a consumer draw a single outline
+ * around an arbitrary union of rectangles.
+ *
+ * @example
+ * ```ts
+ * const { top, right, bottom, left } = cell_getSelectionEdges(cell)
+ * ```
+ */
+declare function cell_getSelectionEdges<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): CellSelectionEdges;
+/**
+ * Returns the active cell, i.e. the anchor of the most recent range.
+ *
+ * Focus is derived rather than stored: in spreadsheet semantics, dragging from
+ * A1 to C5 leaves the active cell at A1, so the active range's anchor already
+ * is the active cell.
+ *
+ * @example
+ * ```ts
+ * const cell = table_getFocusedCell(table)
+ * ```
+ */
+declare function table_getFocusedCell<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>): Cell<TFeatures, TData, any> | undefined;
+/**
+ * Collapses the selection to a single cell at the given coordinates.
+ *
+ * @example
+ * ```ts
+ * table_setFocusedCell(table, '3', 'firstName')
+ * ```
+ */
+declare function table_setFocusedCell<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>, rowId: string, columnId: string): void;
+/**
+ * Selects a rectangle, replacing the current selection unless `additive`.
+ *
+ * @example
+ * ```ts
+ * table_selectCellRange(table, range, { additive: true })
+ * ```
+ */
+declare function table_selectCellRange<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>, range: CellSelectionRange, opts?: SelectCellRangeOptions): void;
+/**
+ * Selects every selectable cell in the table as one range.
+ *
+ * @example
+ * ```ts
+ * table_selectAllCells(table)
+ * ```
+ */
+declare function table_selectAllCells<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>): void;
+/**
+ * Moves the selection one step in a direction, collapsing it to a single cell.
+ *
+ * With nothing selected, this selects the first selectable cell so keyboard
+ * navigation has somewhere to start.
+ *
+ * @example
+ * ```ts
+ * table_moveCellSelection(table, 'down')
+ * ```
+ */
+declare function table_moveCellSelection<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>, direction: CellSelectionDirection): void;
+/**
+ * Extends the active range one step in a direction, keeping its anchor fixed.
+ *
+ * @example
+ * ```ts
+ * table_extendCellSelection(table, 'right')
+ * ```
+ */
+declare function table_extendCellSelection<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>, direction: CellSelectionDirection): void;
+/**
+ * Returns the ids of all selected cells, in row-major order.
+ *
+ * Cells covered by overlapping ranges are returned once, at their first
+ * occurrence.
+ *
+ * @example
+ * ```ts
+ * const ids = table_getSelectedCellIds(table)
+ * ```
+ */
+declare function table_getSelectedCellIds<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>): Array<string>;
+/**
+ * Returns each selected range's values as a row-major grid.
+ *
+ * This is the raw material for clipboard export. Serializing it to text is left
+ * to userland, since the delimiter, the null representation, and whether values
+ * containing delimiters get quoted are all application decisions.
+ *
+ * @example
+ * ```ts
+ * const [firstRange] = table_getSelectedCellRangesData(table)
+ * ```
+ */
+declare function table_getSelectedCellRangesData<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>): Array<Array<Array<unknown>>>;
+/**
+ * Returns the number of selected cells.
+ *
+ * Uses rectangle arithmetic for a single range, which needs no expansion.
+ * Multiple ranges are enumerated so overlapping cells are counted once. A
+ * per-cell `enableCellSelection` predicate also requires enumeration.
+ *
+ * @example
+ * ```ts
+ * const count = table_getSelectedCellCount(table)
+ * ```
+ */
+declare function table_getSelectedCellCount<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>): number;
+/**
+ * Returns the ids of all rows intersected by the selection.
+ *
+ * @example
+ * ```ts
+ * const rowIds = table_getCellSelectionRowIds(table)
+ * ```
+ */
+declare function table_getCellSelectionRowIds<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>): Array<string>;
+/**
+ * Returns the ids of all columns intersected by the selection.
+ *
+ * @example
+ * ```ts
+ * const columnIds = table_getCellSelectionColumnIds(table)
+ * ```
+ */
+declare function table_getCellSelectionColumnIds<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>): Array<string>;
+/**
+ * Creates a handler that begins a selection at this cell.
+ *
+ * Follows `header_getResizeHandler`: the enable check is resolved once outside
+ * the returned closure and guarded again inside it, the document is injectable
+ * for SSR and cross-document rendering, and the document-level `mouseup`
+ * listener is attached here so a drag released outside the table still ends.
+ *
+ * @example
+ * ```tsx
+ * <td onMouseDown={cell.getSelectionStartHandler()} />
+ * ```
+ */
+declare function cell_getSelectionStartHandler<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>, _contextDocument?: Document): (e: unknown) => void;
+/**
+ * Creates a handler that extends the active range to this cell during a drag.
+ *
+ * No rAF coalescing is needed here, unlike the resize handler: `mouseenter`
+ * fires once per cell boundary crossed rather than continuously, and deferring
+ * it by a frame would only delay the highlight.
+ *
+ * @example
+ * ```tsx
+ * <td onMouseEnter={cell.getSelectionExtendHandler()} />
+ * ```
+ */
+declare function cell_getSelectionExtendHandler<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): (_e: unknown) => void;
+//#endregion
+export { 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 };