@tanstack/table-core 9.0.0-beta.65 → 9.0.0-beta.69

package/README.md

@@ -35,6 +35,8 @@
 >
 > - [Angular Table](https://tanstack.com/table/alpha/docs/framework/angular/angular-table)
 > - [Lit Table](https://tanstack.com/table/alpha/docs/framework/lit/lit-table)
+> - [Octane Table](https://tanstack.com/table/beta/docs/framework/octane/quick-start)
+> - [Preact Table](https://tanstack.com/table/beta/docs/framework/preact/quick-start)
 > - [React Table](https://tanstack.com/table/alpha/docs/framework/react/react-table)
 > - [Solid Table](https://tanstack.com/table/alpha/docs/framework/solid/solid-table)
 > - [Svelte Table](https://tanstack.com/table/alpha/docs/framework/svelte/svelte-table)
@@ -44,7 +46,7 @@
 
 A headless table library for building powerful datagrids with full control over markup, styles, and behavior.
 
-- Framework‑agnostic core with bindings for React, Vue & Solid
+- Framework-agnostic core with bindings for React, Preact, Octane, Vue, Solid, Svelte, Angular, Ember, Lit, and Alpine
 - 100% customizable — bring your own UI, components, and styles
 - Sorting, filtering, grouping, aggregation & row selection
 - Lightweight, virtualizable & server‑side friendly

package/dist/core/cells/constructCell.d.ts

@@ -4,7 +4,6 @@ import { Column } from "../../types/Column.js";
 import { Row } from "../../types/Row.js";
 import { Cell } from "../../types/Cell.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/cells/constructCell.d.ts
 /**
  * Constructs a cell instance from normalized table internals.

package/dist/core/cells/coreCellsFeature.d.ts

@@ -1,5 +1,4 @@
 import { TableFeature } from "../../types/TableFeatures.js";
-
 //#region src/core/cells/coreCellsFeature.d.ts
 /**
  * Core feature that adds cell value, render, and context APIs.

package/dist/core/cells/coreCellsFeature.types.d.ts

@@ -4,7 +4,6 @@ import { Column } from "../../types/Column.js";
 import { Row } from "../../types/Row.js";
 import { Cell } from "../../types/Cell.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/cells/coreCellsFeature.types.d.ts
 interface CellContext<in out TFeatures extends TableFeatures, in out TData extends RowData, TValue extends CellData = CellData> {
   cell: Cell<TFeatures, TData, TValue>;

package/dist/core/cells/coreCellsFeature.utils.d.ts

@@ -4,6 +4,7 @@ import { Column } from "../../types/Column.js";
 import { Row } from "../../types/Row.js";
 import { Cell } from "../../types/Cell.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
+import "../../index.js";
 //#region src/core/cells/coreCellsFeature.utils.d.ts
 /**
  * Reads this cell's accessor value from its owning row and column.

package/dist/core/columns/constructColumn.d.ts

@@ -3,7 +3,6 @@ import { ColumnDef } from "../../types/ColumnDef.js";
 import { Table } from "../../types/Table.js";
 import { Column } from "../../types/Column.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/columns/constructColumn.d.ts
 /**
  * Constructs a column instance from normalized table internals.

package/dist/core/columns/coreColumnsFeature.d.ts

@@ -1,5 +1,4 @@
 import { TableFeature } from "../../types/TableFeatures.js";
-
 //#region src/core/columns/coreColumnsFeature.d.ts
 /**
  * Core feature that builds the column tree and exposes table/column column APIs.

package/dist/core/columns/coreColumnsFeature.types.d.ts

@@ -3,7 +3,6 @@ import { AccessorFn, ColumnDef } from "../../types/ColumnDef.js";
 import { Table } from "../../types/Table.js";
 import { Column } from "../../types/Column.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/columns/coreColumnsFeature.types.d.ts
 interface Column_CoreProperties<in out TFeatures extends TableFeatures, in out TData extends RowData, TValue extends CellData = CellData> {
   /**
@@ -23,11 +22,11 @@ interface Column_CoreProperties<in out TFeatures extends TableFeatures, in out T
    */
   depth: number;
   /**
-   * The resolved unique identifier for the column resolved in this priority:
-      - A manual `id` property from the column def
-      - The accessor key from the column def
-      - The header string from the column def
-   */
+     * The resolved unique identifier for the column resolved in this priority:
+        - A manual `id` property from the column def
+        - The accessor key from the column def
+        - The header string from the column def
+     */
   id: string;
   /**
    * The parent column for this column. Will be undefined if this is a root column.

package/dist/core/columns/coreColumnsFeature.utils.d.ts

@@ -3,7 +3,6 @@ import { ColumnDef } from "../../types/ColumnDef.js";
 import { Table } from "../../types/Table.js";
 import { Column } from "../../types/Column.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/columns/coreColumnsFeature.utils.d.ts
 /**
  * Flattens this column and every descendant column into a single array.

package/dist/core/coreFeatures.d.ts

@@ -5,6 +5,7 @@ import { coreRowModelsFeature } from "./row-models/coreRowModelsFeature.js";
 import { coreRowsFeature } from "./rows/coreRowsFeature.js";
 import { coreTablesFeature } from "./table/coreTablesFeature.js";
 import { TableReactivityBindings } from "./reactivity/coreReactivityFeature.types.js";
+import "../reactivity.js";
 //#region src/core/coreFeatures.d.ts
 interface CoreFeatures {
   coreReactivityFeature?: TableReactivityBindings;

package/dist/core/headers/buildHeaderGroups.d.ts

@@ -3,7 +3,6 @@ import { HeaderGroup } from "../../types/HeaderGroup.js";
 import { Table } from "../../types/Table.js";
 import { Column } from "../../types/Column.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/headers/buildHeaderGroups.d.ts
 /**
  * Builds the nested header group structure for a table.

package/dist/core/headers/buildHeaderGroups.js

@@ -69,21 +69,25 @@ function updateHeaderSpans(headers) {
 		const header = headers[i];
 		if (!callMemoOrStaticFn(header.column, "getIsVisible", column_getIsVisible)) continue;
 		let colSpan = 0;
-		let minChildRowSpan = Infinity;
 		if (header.subHeaders.length) {
 			updateHeaderSpans(header.subHeaders);
 			for (let j = 0; j < header.subHeaders.length; j++) {
 				const child = header.subHeaders[j];
 				if (!callMemoOrStaticFn(child.column, "getIsVisible", column_getIsVisible)) continue;
 				colSpan += child.colSpan;
-				if (child.rowSpan < minChildRowSpan) minChildRowSpan = child.rowSpan;
 			}
-		} else {
-			colSpan = 1;
-			minChildRowSpan = 0;
-		}
+		} else colSpan = 1;
 		header.colSpan = colSpan;
-		header.rowSpan = minChildRowSpan;
+		if (header.isPlaceholder && header.subHeaders.length === 1 && header.subHeaders[0].column === header.column) {
+			let rowSpan = 1;
+			let chainChild = header.subHeaders[0];
+			while (chainChild) {
+				chainChild.rowSpan = 0;
+				rowSpan++;
+				chainChild = chainChild.subHeaders.length === 1 && chainChild.subHeaders[0].column === header.column ? chainChild.subHeaders[0] : void 0;
+			}
+			header.rowSpan = rowSpan;
+		} else header.rowSpan = 1;
 	}
 }
 /**

package/dist/core/headers/constructHeader.d.ts

@@ -3,7 +3,6 @@ import { Header } from "../../types/Header.js";
 import { Table } from "../../types/Table.js";
 import { Column } from "../../types/Column.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/headers/constructHeader.d.ts
 /**
  * Constructs a header instance from normalized table internals.

package/dist/core/headers/coreHeadersFeature.d.ts

@@ -1,5 +1,4 @@
 import { TableFeature } from "../../types/TableFeatures.js";
-
 //#region src/core/headers/coreHeadersFeature.d.ts
 /**
  * Core feature that builds header groups and exposes header context APIs.

package/dist/core/headers/coreHeadersFeature.types.d.ts

@@ -4,7 +4,6 @@ import { Header } from "../../types/Header.js";
 import { Table } from "../../types/Table.js";
 import { Column } from "../../types/Column.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/headers/coreHeadersFeature.types.d.ts
 interface Table_Headers<in out TFeatures extends TableFeatures, in out TData extends RowData> {
   /**
@@ -66,7 +65,11 @@ interface Header_CoreProperties<in out TFeatures extends TableFeatures, in out T
    */
   index: number;
   /**
-   * A boolean denoting if the header is a placeholder header.
+   * A boolean denoting if the header is a placeholder header. Placeholder
+   * headers fill the rows above a shallow leaf column's real header so that
+   * every header group row accounts for every visible column. Render them as
+   * empty cells, or use `header.rowSpan` to merge each chain of placeholders
+   * into one vertically spanning header cell.
    */
   isPlaceholder: boolean;
   /**
@@ -74,7 +77,15 @@ interface Header_CoreProperties<in out TFeatures extends TableFeatures, in out T
    */
   placeholderId?: string;
   /**
-   * The row-span for the header.
+   * The number of header group rows the header should span when merging header
+   * cells vertically. A leaf column that is shallower than the deepest leaf
+   * column produces a chain of placeholder headers above its real header; the
+   * placeholder at the top of the chain reports the chain's full span, and
+   * every header it covers (including the real leaf header in the bottom row)
+   * reports 0. To merge vertically, skip headers with a rowSpan of 0 and
+   * render every other header with the `rowSpan` attribute and its column's
+   * header content, even when it is a placeholder. Headers in even column
+   * trees always report 1.
    */
   rowSpan: number;
   /**

package/dist/core/headers/coreHeadersFeature.utils.d.ts

@@ -4,6 +4,7 @@ import { Header } from "../../types/Header.js";
 import { Table } from "../../types/Table.js";
 import { Column } from "../../types/Column.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
+import "../../index.js";
 //#region src/core/headers/coreHeadersFeature.utils.d.ts
 /**
  * Walks a header tree and collects all descendant leaf headers.

package/dist/core/reactivity/coreReactivityFeature.types.d.ts

@@ -1,5 +1,4 @@
 import { Atom, AtomOptions, ReadonlyAtom, Subscription } from "@tanstack/store";
-
 //#region src/core/reactivity/coreReactivityFeature.types.d.ts
 interface TableAtomOptions<T> extends AtomOptions<T> {
   /**

package/dist/core/reactivity/coreReactivityFeature.utils.d.ts

@@ -1,5 +1,4 @@
 import { Atom, ReadonlyAtom, ReadonlyStore, Store } from "@tanstack/store";
-
 //#region src/core/reactivity/coreReactivityFeature.utils.d.ts
 /**
  * Converts a writable atom to the store-compatible shape expected by core.

package/dist/core/reactivity/renderPhaseReactivity.d.ts

@@ -1,6 +1,5 @@
 import { TableReactivityBindings } from "./coreReactivityFeature.types.js";
 import { Atom, AtomOptions, ReadonlyAtom } from "@tanstack/store";
-
 //#region src/core/reactivity/renderPhaseReactivity.d.ts
 /**
  * Reactivity bindings for adapters whose options are plain values synchronized

package/dist/core/row-models/coreRowModelsFeature.d.ts

@@ -1,5 +1,4 @@
 import { TableFeature } from "../../types/TableFeatures.js";
-
 //#region src/core/row-models/coreRowModelsFeature.d.ts
 /**
  * Core feature that wires table row-model accessors and row-model caches.

package/dist/core/row-models/coreRowModelsFeature.types.d.ts

@@ -7,7 +7,6 @@ import { Row } from "../../types/Row.js";
 import { Table_RowModels_Filtered } from "../../features/column-filtering/columnFilteringFeature.types.js";
 import { Table_RowModels_Grouped } from "../../features/column-grouping/columnGroupingFeature.types.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/row-models/coreRowModelsFeature.types.d.ts
 interface RowModel<in out TFeatures extends TableFeatures, in out TData extends RowData> {
   rows: Array<Row<TFeatures, TData>>;

package/dist/core/row-models/coreRowModelsFeature.utils.d.ts

@@ -2,7 +2,6 @@ import { RowData } from "../../types/type-utils.js";
 import { Table } from "../../types/Table.js";
 import { RowModel } from "./coreRowModelsFeature.types.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/row-models/coreRowModelsFeature.utils.d.ts
 /**
  * Resolves the table's unmodified core row model.

package/dist/core/row-models/createCoreRowModel.d.ts

@@ -2,7 +2,6 @@ import { RowData } from "../../types/type-utils.js";
 import { Table } from "../../types/Table.js";
 import { RowModel } from "./coreRowModelsFeature.types.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/row-models/createCoreRowModel.d.ts
 /**
  * Creates a memoized core row model factory.

package/dist/core/rows/constructRow.d.ts

@@ -2,7 +2,6 @@ import { RowData } from "../../types/type-utils.js";
 import { Table } from "../../types/Table.js";
 import { Row } from "../../types/Row.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/rows/constructRow.d.ts
 /**
  * Constructs a row instance from normalized table internals.

package/dist/core/rows/coreRowsFeature.d.ts

@@ -1,5 +1,4 @@
 import { TableFeature } from "../../types/TableFeatures.js";
-
 //#region src/core/rows/coreRowsFeature.d.ts
 /**
  * Core feature that creates row APIs for values, cells, and tree traversal.

package/dist/core/rows/coreRowsFeature.types.d.ts

@@ -4,7 +4,6 @@ import { Column } from "../../types/Column.js";
 import { Row } from "../../types/Row.js";
 import { Cell } from "../../types/Cell.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/rows/coreRowsFeature.types.d.ts
 interface Row_CoreProperties<in out TFeatures extends TableFeatures, in out TData extends RowData> {
   _cellsCache?: WeakMap<Column<TFeatures, TData, unknown>, Cell<TFeatures, TData, unknown>>;

package/dist/core/rows/coreRowsFeature.utils.d.ts

@@ -3,7 +3,6 @@ import { Table } from "../../types/Table.js";
 import { Row } from "../../types/Row.js";
 import { Cell } from "../../types/Cell.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/rows/coreRowsFeature.utils.d.ts
 /**
  * Returns this row's zero-based position in the current pre-pagination row

package/dist/core/table/constructTable.d.ts

@@ -3,7 +3,6 @@ import { TableState } from "../../types/TableState.js";
 import { TableOptions } from "../../types/TableOptions.js";
 import { Table } from "../../types/Table.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/table/constructTable.d.ts
 /**
  * Builds the initial table state from registered features and user initial state.

package/dist/core/table/coreTablesFeature.d.ts

@@ -1,5 +1,4 @@
 import { TableFeature } from "../../types/TableFeatures.js";
-
 //#region src/core/table/coreTablesFeature.d.ts
 /**
  * Core feature that adds base table instance APIs such as reset and setOptions.

package/dist/core/table/coreTablesFeature.types.d.ts

@@ -7,7 +7,6 @@ import { TableState, TableState_All } from "../../types/TableState.js";
 import { TableOptions } from "../../types/TableOptions.js";
 import { IsAny, TableFeature, TableFeatures, ValidateFeatureSlots } from "../../types/TableFeatures.js";
 import { Atom, ReadonlyAtom, ReadonlyStore } from "@tanstack/store";
-
 //#region src/core/table/coreTablesFeature.types.d.ts
 interface TableMeta<in out TFeatures extends TableFeatures, in out TData extends RowData> {}
 /**
@@ -25,7 +24,7 @@ type ExtractTableMeta<TFeatures extends TableFeatures, TData extends RowData> =
  * A map of writable atoms, one per `TableState` slice. These are the internal
  * writable atoms that the library always writes to via `makeStateUpdater`.
  */
-type BaseAtoms<TFeatures extends TableFeatures> = { [K in keyof TableState<TFeatures>]-?: Atom<TableState<TFeatures>[K]> };
+type BaseAtoms<TFeatures extends TableFeatures> = { [K in keyof TableState<TFeatures>]-?: Atom<TableState<TFeatures>[K]>; };
 /**
  * A map of readonly derived atoms, one per `TableState` slice. Each derives
  * from its corresponding `baseAtom` plus, optionally, a per-slice external
@@ -33,13 +32,13 @@ type BaseAtoms<TFeatures extends TableFeatures> = { [K in keyof TableState<TFeat
  *
  * Precedence: `options.atoms[key]` > `options.state[key]` > `baseAtoms[key]`.
  */
-type Atoms<TFeatures extends TableFeatures> = { [K in keyof TableState<TFeatures>]-?: ReadonlyAtom<TableState<TFeatures>[K]> };
+type Atoms<TFeatures extends TableFeatures> = { [K in keyof TableState<TFeatures>]-?: ReadonlyAtom<TableState<TFeatures>[K]>; };
 /**
  * A map of optional external atoms, one per `TableState` slice. Consumers can
  * provide their own writable atom for any state slice to take over ownership
  * of that slice.
  */
-type ExternalAtoms<TFeatures extends TableFeatures> = Partial<{ [K in keyof TableState<TFeatures>]: Atom<TableState<TFeatures>[K]> }>;
+type ExternalAtoms<TFeatures extends TableFeatures> = Partial<{ [K in keyof TableState<TFeatures>]: Atom<TableState<TFeatures>[K]>; }>;
 /**
  * Internal "all features" flat variants of the atom types. `Table`
  * uses these so feature code (written generically over `TFeatures`) can access
@@ -50,9 +49,9 @@ type ExternalAtoms<TFeatures extends TableFeatures> = Partial<{ [K in keyof Tabl
  * but those slices may not be registered on the current table. Consumers must
  * use optional chaining (`table.atoms.columnPinning?.get() ?? default`).
  */
-type BaseAtoms_All = { [K in keyof TableState_All]?: Atom<Exclude<TableState_All[K], undefined>> };
-type Atoms_All = { [K in keyof TableState_All]?: ReadonlyAtom<TableState_All[K]> };
-type ExternalAtoms_All = Partial<{ [K in keyof TableState_All]: Atom<Exclude<TableState_All[K], undefined>> }>;
+type BaseAtoms_All = { [K in keyof TableState_All]?: Atom<Exclude<TableState_All[K], undefined>>; };
+type Atoms_All = { [K in keyof TableState_All]?: ReadonlyAtom<TableState_All[K]>; };
+type ExternalAtoms_All = Partial<{ [K in keyof TableState_All]: Atom<Exclude<TableState_All[K], undefined>>; }>;
 interface TableOptions_Table<in out TFeatures extends TableFeatures, in out TData extends RowData> {
   /**
    * The feature modules registered on this table instance.

package/dist/core/table/coreTablesFeature.utils.d.ts

@@ -3,7 +3,6 @@ import { TableState } from "../../types/TableState.js";
 import { TableOptions } from "../../types/TableOptions.js";
 import { Table } from "../../types/Table.js";
 import { TableFeatures } from "../../types/TableFeatures.js";
-
 //#region src/core/table/coreTablesFeature.utils.d.ts
 /**
  * Synchronizes externally controlled state slices into the table's base atoms.

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

@@ -1,5 +1,4 @@
 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.

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

@@ -1,7 +1,6 @@
 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.
@@ -17,10 +16,16 @@ interface CellSelectionRange {
   anchorRowId: string;
   focusColumnId: string;
   focusRowId: string;
+  /**
+   * How this range changes the selection produced by the ranges before it.
+   * Defaults to `include`.
+   */
+  operation?: CellSelectionRangeOperation;
 }
+type CellSelectionRangeOperation = 'include' | 'exclude';
 /**
- * The selected rectangles. The last entry is the active one that shift-extend
- * and drag operate on.
+ * Ordered range operations that produce the final selection. The last entry is
+ * the active operation 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
@@ -52,10 +57,18 @@ interface CellSelectionEdges {
   top: boolean;
 }
 type CellSelectionDirection = 'up' | 'down' | 'left' | 'right';
+type CellSelectionRangeMode = 'replace' | 'include' | 'exclude';
 interface SelectCellRangeOptions {
+  /**
+   * Whether to replace the selection, add the range, or subtract the range.
+   * Defaults to `replace`.
+   */
+  mode?: CellSelectionRangeMode;
   /**
    * Whether the range should be added alongside existing ranges rather than
    * replacing them. Defaults to `false`.
+   *
+   * @deprecated Use `mode: 'include'` instead.
    */
   additive?: boolean;
 }
@@ -87,8 +100,7 @@ interface TableOptions_CellSelection<in out TFeatures extends TableFeatures, in
    */
   enableCellSelectionDrag?: boolean;
   /**
-   * Allows multiple disjoint rectangles to be selected at once. Defaults to
-   * `true`.
+   * Allows modifier interactions to add or subtract ranges. Defaults to `true`.
    */
   enableMultiCellRangeSelection?: boolean;
   /**
@@ -100,8 +112,8 @@ interface TableOptions_CellSelection<in out TFeatures extends TableFeatures, in
    */
   isCellRangeSelectionEvent?: (event: unknown) => boolean;
   /**
-   * Determines whether a selection-start event should add a new rectangle
-   * alongside the existing ones.
+   * Determines whether a selection-start event should add or subtract a new
+   * rectangle. The operation depends on whether the starting cell is selected.
    *
    * By default, events with `ctrlKey` or `metaKey` directly on the event or on
    * `event.nativeEvent` are treated as multi-range events.
@@ -134,7 +146,7 @@ interface Cell_CellSelection {
    */
   getIsFocused: () => boolean;
   /**
-   * Checks whether this cell falls inside any selected range.
+   * Checks whether this cell falls inside the final positive selection.
    */
   getIsSelected: () => boolean;
   /**
@@ -192,7 +204,8 @@ interface Table_CellSelection<in out TFeatures extends TableFeatures, in out TDa
    */
   extendCellSelection: (direction: CellSelectionDirection) => void;
   /**
-   * Returns the selected ranges resolved into inclusive display-order indexes.
+   * Returns the final positive selection as disjoint, inclusive display-order
+   * index rectangles after all include and exclude operations are applied.
    *
    * This is the memoized cache every per-cell read goes through. Ranges whose
    * corners no longer resolve are omitted.
@@ -216,14 +229,15 @@ interface Table_CellSelection<in out TFeatures extends TableFeatures, in out TDa
    */
   getCellSelectionRowIds: () => Array<string>;
   /**
-   * Returns the active cell, i.e. the anchor of the most recent range.
+   * Returns the active cell, i.e. the anchor of the most recent operation.
+   * An exclusion's active cell is focused even though it is not selected.
    */
   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.
+   * Computed with rectangle arithmetic unless a per-cell
+   * `enableCellSelection` predicate requires enumeration.
    */
   getSelectedCellCount: () => number;
   /**
@@ -234,9 +248,9 @@ interface Table_CellSelection<in out TFeatures extends TableFeatures, in out TDa
    */
   getSelectedCellIds: () => Array<string>;
   /**
-   * Returns each selected range's values as a row-major grid.
+   * Returns each final positive selection region's values as a row-major grid.
    *
-   * Indexed as `[rangeIndex][rowIndex][columnIndex]`. Serializing this to
+   * Indexed as `[regionIndex][rowIndex][columnIndex]`. Serializing this to
    * clipboard text is left to userland, since the delimiter, the null
    * representation, and any quoting rules are application decisions.
    */
@@ -257,7 +271,7 @@ interface Table_CellSelection<in out TFeatures extends TableFeatures, in out TDa
    */
   selectAllCells: () => void;
   /**
-   * Selects a rectangle, replacing the current selection unless `additive`.
+   * Selects a rectangle using the requested replace/include/exclude mode.
    */
   selectCellRange: (range: CellSelectionRange, opts?: SelectCellRangeOptions) => void;
   /**
@@ -270,4 +284,4 @@ interface Table_CellSelection<in out TFeatures extends TableFeatures, in out TDa
   setFocusedCell: (rowId: string, columnId: string) => void;
 }
 //#endregion
-export { CellSelectionBounds, CellSelectionDirection, CellSelectionEdges, CellSelectionRange, CellSelectionState, Cell_CellSelection, ColumnDef_CellSelection, SelectCellRangeOptions, TableOptions_CellSelection, TableState_CellSelection, Table_CellSelection };
+export { CellSelectionBounds, CellSelectionDirection, CellSelectionEdges, CellSelectionRange, CellSelectionRangeMode, CellSelectionRangeOperation, CellSelectionState, Cell_CellSelection, ColumnDef_CellSelection, SelectCellRangeOptions, TableOptions_CellSelection, TableState_CellSelection, Table_CellSelection };

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

@@ -3,7 +3,6 @@ import { CellSelectionBounds, CellSelectionDirection, CellSelectionEdges, CellSe
 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.
@@ -70,7 +69,8 @@ declare function table_autoResetCellSelection<TFeatures extends TableFeatures, T
  */
 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.
+ * Resolves ordered range operations into disjoint, positive 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
@@ -97,7 +97,7 @@ declare function table_getCellSelectionBounds<TFeatures extends TableFeatures, T
  */
 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.
+ * Checks whether this cell falls inside the final positive selection.
  *
  * Deliberately not memoized. Registering this through `assignPrototypeAPIs`
  * with `memoDeps` would allocate a memo closure and dependency array per cell,
@@ -141,7 +141,7 @@ declare function cell_getTabIndex<TFeatures extends TableFeatures, TData extends
  */
 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.
+ * Returns the active cell, i.e. the anchor of the most recent operation.
  *
  * 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
@@ -163,11 +163,11 @@ declare function table_getFocusedCell<TFeatures extends TableFeatures, TData ext
  */
 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`.
+ * Selects a rectangle using replace, include, or exclude semantics.
  *
  * @example
  * ```ts
- * table_selectCellRange(table, range, { additive: true })
+ * table_selectCellRange(table, range, { mode: 'exclude' })
  * ```
  */
 declare function table_selectCellRange<TFeatures extends TableFeatures, TData extends RowData>(table: Table<TFeatures, TData>, range: CellSelectionRange, opts?: SelectCellRangeOptions): void;
@@ -214,7 +214,7 @@ declare function table_extendCellSelection<TFeatures extends TableFeatures, TDat
  */
 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.
+ * Returns each final positive region'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
@@ -229,9 +229,8 @@ declare function table_getSelectedCellRangesData<TFeatures extends TableFeatures
 /**
  * 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.
+ * Uses rectangle arithmetic over the normalized, disjoint positive regions.
+ * A per-cell `enableCellSelection` predicate requires enumeration.
  *
  * @example
  * ```ts