@tanstack/table-core 9.0.0-alpha.6 → 9.0.0-beta.1

package/dist/features/row-selection/rowSelectionFeature.types.d.ts

@@ -0,0 +1,136 @@
+import { OnChangeFn, RowData, Updater } from "../../types/type-utils.js";
+import { Row } from "../../types/Row.js";
+import { TableFeatures } from "../../types/TableFeatures.js";
+import { RowModel } from "../../core/row-models/coreRowModelsFeature.types.js";
+
+//#region src/features/row-selection/rowSelectionFeature.types.d.ts
+type RowSelectionState = Record<string, boolean | undefined>;
+interface TableState_RowSelection {
+  rowSelection: RowSelectionState;
+}
+interface TableOptions_RowSelection<TFeatures extends TableFeatures, TData extends RowData> {
+  /**
+   * Allows rows to be selected alongside other rows.
+   *
+   * Provide a predicate to decide per row. Defaults to `true`.
+   */
+  enableMultiRowSelection?: boolean | ((row: Row<TFeatures, TData>) => boolean);
+  /**
+   * Allows rows to be selected.
+   *
+   * Provide a predicate to decide per row. Defaults to `true`.
+   */
+  enableRowSelection?: boolean | ((row: Row<TFeatures, TData>) => boolean);
+  /**
+   * Controls whether selecting a parent row also selects its subRows.
+   *
+   * Provide a predicate to decide per row. This is most useful with expanding or
+   * grouping features and defaults to `true`.
+   */
+  enableSubRowSelection?: boolean | ((row: Row<TFeatures, TData>) => boolean);
+  /**
+   * Called with an updater when row selection state changes. Pair this with
+   * `state.rowSelection` when using external state; external atoms can own the
+   * slice without this callback.
+   */
+  onRowSelectionChange?: OnChangeFn<RowSelectionState>;
+}
+interface Row_RowSelection {
+  /**
+   * Checks whether this row can be selected alongside other rows.
+   */
+  getCanMultiSelect: () => boolean;
+  /**
+   * Checks whether this row can currently be selected.
+   */
+  getCanSelect: () => boolean;
+  /**
+   * Checks whether selecting this row should also select its subRows.
+   */
+  getCanSelectSubRows: () => boolean;
+  /**
+   * Checks whether all selectable descendants are selected.
+   */
+  getIsAllSubRowsSelected: () => boolean;
+  /**
+   * Checks whether this row id is selected.
+   */
+  getIsSelected: () => boolean;
+  /**
+   * Checks whether some selectable descendants are selected.
+   */
+  getIsSomeSelected: () => boolean;
+  /**
+   * Creates a checkbox-style handler that toggles this row's selected state.
+   */
+  getToggleSelectedHandler: () => (event: unknown) => void;
+  /**
+   * Selects/deselects the row.
+   */
+  toggleSelected: (value?: boolean, opts?: {
+    selectChildren?: boolean;
+  }) => void;
+}
+interface Table_RowSelection<TFeatures extends TableFeatures, TData extends RowData> {
+  /**
+   * Builds a selected-row model from rows after filtering.
+   */
+  getFilteredSelectedRowModel: () => RowModel<TFeatures, TData>;
+  /**
+   * Builds a selected-row model from rows after grouping.
+   */
+  getGroupedSelectedRowModel: () => RowModel<TFeatures, TData>;
+  /**
+   * Checks whether every selectable row on the current page is selected.
+   */
+  getIsAllPageRowsSelected: () => boolean;
+  /**
+   * Checks whether every selectable filtered row is selected.
+   */
+  getIsAllRowsSelected: () => boolean;
+  /**
+   * Checks whether the current page has a partial row selection.
+   */
+  getIsSomePageRowsSelected: () => boolean;
+  /**
+   * Checks whether filtered rows have a partial row selection.
+   */
+  getIsSomeRowsSelected: () => boolean;
+  /**
+   * Returns the core row model of all rows before row selection has been applied.
+   */
+  getPreSelectedRowModel: () => RowModel<TFeatures, TData>;
+  /**
+   * Builds a selected-row model from the core row model.
+   */
+  getSelectedRowModel: () => RowModel<TFeatures, TData>;
+  /**
+   * Creates a checkbox-style handler that toggles all current-page rows.
+   */
+  getToggleAllPageRowsSelectedHandler: () => (event: unknown) => void;
+  /**
+   * Creates a checkbox-style handler that toggles all selectable rows.
+   */
+  getToggleAllRowsSelectedHandler: () => (event: unknown) => void;
+  /**
+   * Resets `rowSelection` to `initialState.rowSelection`.
+   *
+   * Pass `true` to ignore initial state and reset to `{}`.
+   */
+  resetRowSelection: (defaultState?: boolean) => void;
+  /**
+   * Updates row selection state with a next map or updater function.
+   */
+  setRowSelection: (updater: Updater<RowSelectionState>) => void;
+  /**
+   * Selects/deselects all rows on the current page.
+   */
+  toggleAllPageRowsSelected: (value?: boolean) => void;
+  /**
+   * Selects/deselects all rows in the table.
+   */
+  toggleAllRowsSelected: (value?: boolean) => void;
+}
+//#endregion
+export { RowSelectionState, Row_RowSelection, TableOptions_RowSelection, TableState_RowSelection, Table_RowSelection };
+//# sourceMappingURL=rowSelectionFeature.types.d.ts.map

package/dist/features/row-selection/rowSelectionFeature.utils.cjs

@@ -0,0 +1,514 @@
+const require_utils = require('../../utils.cjs');
+
+//#region src/features/row-selection/rowSelectionFeature.utils.ts
+/**
+* Creates the default row selection state.
+*
+* The feature default is an empty map, meaning no rows are selected. Reset APIs
+* use this value when `defaultState` is `true`.
+*
+* @example
+* ```ts
+* const selection = getDefaultRowSelectionState()
+* ```
+*/
+function getDefaultRowSelectionState() {
+	return {};
+}
+/**
+* Routes a row selection updater through the table's selection change handler.
+*
+* The updater may be a next selection map or a function of the previous map,
+* matching the instance `table.setRowSelection` behavior.
+*
+* @example
+* ```ts
+* table_setRowSelection(table, (old) => ({ ...old, [rowId]: true }))
+* ```
+*/
+function table_setRowSelection(table, updater) {
+	var _table$options$onRowS, _table$options;
+	(_table$options$onRowS = (_table$options = table.options).onRowSelectionChange) === null || _table$options$onRowS === void 0 || _table$options$onRowS.call(_table$options, updater);
+}
+/**
+* Resets `rowSelection` to the configured initial state or feature default.
+*
+* With no argument, the reset clones `table.initialState.rowSelection` when it
+* exists. Passing `true` ignores initial state and resets to `{}`.
+*
+* @example
+* ```ts
+* table_resetRowSelection(table)
+* table_resetRowSelection(table, true)
+* ```
+*/
+function table_resetRowSelection(table, defaultState) {
+	table_setRowSelection(table, defaultState ? {} : require_utils.cloneState(table.initialState.rowSelection ?? {}));
+}
+/**
+* Selects or deselects every selectable row before grouping.
+*
+* Omitting `value` toggles based on `table_getIsAllRowsSelected(table)`.
+* Deselecting removes matching ids from the existing selection map.
+*
+* @example
+* ```ts
+* table_toggleAllRowsSelected(table)
+* ```
+*/
+function table_toggleAllRowsSelected(table, value) {
+	table_setRowSelection(table, (old) => {
+		value = typeof value !== "undefined" ? value : !table_getIsAllRowsSelected(table);
+		const rowSelection = { ...old };
+		const preGroupedFlatRows = table.getPreGroupedRowModel().flatRows;
+		if (value) preGroupedFlatRows.forEach((row) => {
+			if (!row_getCanSelect(row)) return;
+			rowSelection[row.id] = true;
+		});
+		else preGroupedFlatRows.forEach((row) => {
+			delete rowSelection[row.id];
+		});
+		return rowSelection;
+	});
+}
+/**
+* Selects or deselects every selectable row on the current page.
+*
+* Omitting `value` toggles based on `table_getIsAllPageRowsSelected(table)`.
+* Child rows are included when sub-row selection allows it.
+*
+* @example
+* ```ts
+* table_toggleAllPageRowsSelected(table)
+* ```
+*/
+function table_toggleAllPageRowsSelected(table, value) {
+	table_setRowSelection(table, (old) => {
+		const resolvedValue = typeof value !== "undefined" ? value : !table_getIsAllPageRowsSelected(table);
+		const rowSelection = { ...old };
+		table.getRowModel().rows.forEach((row) => {
+			mutateRowIsSelected(rowSelection, row.id, resolvedValue, true, table);
+		});
+		return rowSelection;
+	});
+}
+/**
+* Reads the row model before row selection is projected into selected rows.
+*
+* Selection does not alter the base row pipeline, so this returns the core row
+* model.
+*
+* @example
+* ```ts
+* const rowsBeforeSelection = table_getPreSelectedRowModel(table)
+* ```
+*/
+function table_getPreSelectedRowModel(table) {
+	return table.getCoreRowModel();
+}
+/**
+* Builds a row model containing selected rows from the core row model.
+*
+* If no row ids are selected, an empty row model is returned without walking
+* the rows.
+*
+* @example
+* ```ts
+* const selectedRows = table_getSelectedRowModel(table)
+* ```
+*/
+function table_getSelectedRowModel(table) {
+	var _table$atoms$rowSelec;
+	const rowModel = table.getCoreRowModel();
+	if (!Object.keys(((_table$atoms$rowSelec = table.atoms.rowSelection) === null || _table$atoms$rowSelec === void 0 ? void 0 : _table$atoms$rowSelec.get()) ?? {}).length) return {
+		rows: [],
+		flatRows: [],
+		rowsById: {}
+	};
+	return selectRowsFn(rowModel);
+}
+/**
+* Builds a row model containing selected rows from the filtered row model.
+*
+* If no row ids are selected, an empty row model is returned without walking
+* the rows.
+*
+* @example
+* ```ts
+* const selectedRows = table_getFilteredSelectedRowModel(table)
+* ```
+*/
+function table_getFilteredSelectedRowModel(table) {
+	var _table$atoms$rowSelec2;
+	const rowModel = table.getCoreRowModel();
+	if (!Object.keys(((_table$atoms$rowSelec2 = table.atoms.rowSelection) === null || _table$atoms$rowSelec2 === void 0 ? void 0 : _table$atoms$rowSelec2.get()) ?? {}).length) return {
+		rows: [],
+		flatRows: [],
+		rowsById: {}
+	};
+	return selectRowsFn(rowModel);
+}
+/**
+* Builds a row model containing selected rows from the grouped row model.
+*
+* If no row ids are selected, an empty row model is returned without walking
+* the rows.
+*
+* @example
+* ```ts
+* const selectedRows = table_getGroupedSelectedRowModel(table)
+* ```
+*/
+function table_getGroupedSelectedRowModel(table) {
+	var _table$atoms$rowSelec3;
+	const rowModel = table.getCoreRowModel();
+	if (!Object.keys(((_table$atoms$rowSelec3 = table.atoms.rowSelection) === null || _table$atoms$rowSelec3 === void 0 ? void 0 : _table$atoms$rowSelec3.get()) ?? {}).length) return {
+		rows: [],
+		flatRows: [],
+		rowsById: {}
+	};
+	return selectRowsFn(rowModel);
+}
+/**
+* Checks whether every selectable filtered row is selected.
+*
+* The result is false when there are no filtered rows or when selection state is
+* empty.
+*
+* @example
+* ```ts
+* const allSelected = table_getIsAllRowsSelected(table)
+* ```
+*/
+function table_getIsAllRowsSelected(table) {
+	var _table$atoms$rowSelec4;
+	const preGroupedFlatRows = table.getFilteredRowModel().flatRows;
+	const rowSelection = ((_table$atoms$rowSelec4 = table.atoms.rowSelection) === null || _table$atoms$rowSelec4 === void 0 ? void 0 : _table$atoms$rowSelec4.get()) ?? {};
+	let isAllRowsSelected = Boolean(preGroupedFlatRows.length && Object.keys(rowSelection).length);
+	if (isAllRowsSelected) {
+		if (preGroupedFlatRows.some((row) => row_getCanSelect(row) && !rowSelection[row.id])) isAllRowsSelected = false;
+	}
+	return isAllRowsSelected;
+}
+/**
+* Checks whether every selectable row on the current page is selected.
+*
+* Non-selectable rows are ignored for this calculation.
+*
+* @example
+* ```ts
+* const allPageRowsSelected = table_getIsAllPageRowsSelected(table)
+* ```
+*/
+function table_getIsAllPageRowsSelected(table) {
+	var _table$atoms$rowSelec5;
+	const paginationFlatRows = table.getPaginatedRowModel().flatRows.filter((row) => row_getCanSelect(row));
+	const rowSelection = ((_table$atoms$rowSelec5 = table.atoms.rowSelection) === null || _table$atoms$rowSelec5 === void 0 ? void 0 : _table$atoms$rowSelec5.get()) ?? {};
+	let isAllPageRowsSelected = !!paginationFlatRows.length;
+	if (isAllPageRowsSelected && paginationFlatRows.some((row) => !rowSelection[row.id])) isAllPageRowsSelected = false;
+	return isAllPageRowsSelected;
+}
+/**
+* Checks whether selection is partially applied across filtered rows.
+*
+* The result is true when at least one row id is selected but fewer ids are
+* selected than the current filtered flat row count.
+*
+* @example
+* ```ts
+* const someRowsSelected = table_getIsSomeRowsSelected(table)
+* ```
+*/
+function table_getIsSomeRowsSelected(table) {
+	var _table$atoms$rowSelec6;
+	const totalSelected = Object.keys(((_table$atoms$rowSelec6 = table.atoms.rowSelection) === null || _table$atoms$rowSelec6 === void 0 ? void 0 : _table$atoms$rowSelec6.get()) ?? {}).length;
+	return totalSelected > 0 && totalSelected < table.getFilteredRowModel().flatRows.length;
+}
+/**
+* Checks whether the current page has a partial selection.
+*
+* This is false when all selectable page rows are selected. Otherwise it is true
+* if any selectable page row or descendant is selected.
+*
+* @example
+* ```ts
+* const somePageRowsSelected = table_getIsSomePageRowsSelected(table)
+* ```
+*/
+function table_getIsSomePageRowsSelected(table) {
+	const paginationFlatRows = table.getPaginatedRowModel().flatRows;
+	return table_getIsAllPageRowsSelected(table) ? false : paginationFlatRows.filter((row) => row_getCanSelect(row)).some((row) => row_getIsSelected(row) || row_getIsSomeSelected(row));
+}
+/**
+* Creates a checkbox-style handler that selects or deselects all rows.
+*
+* The handler reads `event.target.checked`, so it is intended for controls whose
+* checked state means "all rows selected".
+*
+* @example
+* ```ts
+* const onChange = table_getToggleAllRowsSelectedHandler(table)
+* ```
+*/
+function table_getToggleAllRowsSelectedHandler(table) {
+	return (e) => {
+		table_toggleAllRowsSelected(table, e.target.checked);
+	};
+}
+/**
+* Creates a checkbox-style handler that selects or deselects current page rows.
+*
+* The handler reads `event.target.checked`, so it is intended for controls whose
+* checked state means "all page rows selected".
+*
+* @example
+* ```ts
+* const onChange = table_getToggleAllPageRowsSelectedHandler(table)
+* ```
+*/
+function table_getToggleAllPageRowsSelectedHandler(table) {
+	return (e) => {
+		table_toggleAllPageRowsSelected(table, e.target.checked);
+	};
+}
+/**
+* Selects or deselects this row.
+*
+* Omitting `value` toggles the row. Child rows are selected recursively unless
+* `opts.selectChildren` is `false` or sub-row selection is disabled.
+*
+* @example
+* ```ts
+* row_toggleSelected(row)
+* ```
+*/
+function row_toggleSelected(row, value, opts) {
+	const isSelected = row_getIsSelected(row);
+	table_setRowSelection(row.table, (old) => {
+		value = typeof value !== "undefined" ? value : !isSelected;
+		if (row_getCanSelect(row) && isSelected === value) return old;
+		const selectedRowIds = { ...old };
+		mutateRowIsSelected(selectedRowIds, row.id, value, (opts === null || opts === void 0 ? void 0 : opts.selectChildren) ?? true, row.table);
+		return selectedRowIds;
+	});
+}
+/**
+* Checks whether this row id is selected in `state.rowSelection`.
+*
+* Missing row ids are treated as not selected.
+*
+* @example
+* ```ts
+* const selected = row_getIsSelected(row)
+* ```
+*/
+function row_getIsSelected(row) {
+	return isRowSelected(row);
+}
+/**
+* Checks whether some, but not all, selectable descendants are selected.
+*
+* This supports indeterminate selection UI for parent rows.
+*
+* @example
+* ```ts
+* const partial = row_getIsSomeSelected(row)
+* ```
+*/
+function row_getIsSomeSelected(row) {
+	return isSubRowSelected(row) === "some";
+}
+/**
+* Checks whether all selectable descendants are selected.
+*
+* Rows without selectable descendants return false.
+*
+* @example
+* ```ts
+* const allChildrenSelected = row_getIsAllSubRowsSelected(row)
+* ```
+*/
+function row_getIsAllSubRowsSelected(row) {
+	return isSubRowSelected(row) === "all";
+}
+/**
+* Checks whether this row can be selected.
+*
+* `options.enableRowSelection` may be a boolean or a row predicate; it defaults
+* to `true`.
+*
+* @example
+* ```ts
+* const canSelect = row_getCanSelect(row)
+* ```
+*/
+function row_getCanSelect(row) {
+	const options = row.table.options;
+	if (typeof options.enableRowSelection === "function") return options.enableRowSelection(row);
+	return options.enableRowSelection ?? true;
+}
+/**
+* Checks whether selecting this row should also select its subRows.
+*
+* `options.enableSubRowSelection` may be a boolean or a row predicate; it
+* defaults to `true`.
+*
+* @example
+* ```ts
+* const canSelectChildren = row_getCanSelectSubRows(row)
+* ```
+*/
+function row_getCanSelectSubRows(row) {
+	const options = row.table.options;
+	if (typeof options.enableSubRowSelection === "function") return options.enableSubRowSelection(row);
+	return options.enableSubRowSelection ?? true;
+}
+/**
+* Checks whether this row can be selected alongside other rows.
+*
+* `options.enableMultiRowSelection` may be a boolean or a row predicate; it
+* defaults to `true`.
+*
+* @example
+* ```ts
+* const canMultiSelect = row_getCanMultiSelect(row)
+* ```
+*/
+function row_getCanMultiSelect(row) {
+	const options = row.table.options;
+	if (typeof options.enableMultiRowSelection === "function") return options.enableMultiRowSelection(row);
+	return options.enableMultiRowSelection ?? true;
+}
+/**
+* Creates a checkbox-style handler that selects or deselects this row.
+*
+* The handler is a no-op when the row cannot be selected and reads
+* `event.target.checked`.
+*
+* @example
+* ```ts
+* const onChange = row_getToggleSelectedHandler(row)
+* ```
+*/
+function row_getToggleSelectedHandler(row) {
+	const canSelect = row_getCanSelect(row);
+	return (e) => {
+		if (!canSelect) return;
+		row_toggleSelected(row, e.target.checked);
+	};
+}
+const mutateRowIsSelected = (selectedRowIds, rowId, value, includeChildren, table) => {
+	const row = table.getRow(rowId, true);
+	if (value) {
+		if (!row_getCanMultiSelect(row)) Object.keys(selectedRowIds).forEach((key) => delete selectedRowIds[key]);
+		if (row_getCanSelect(row)) selectedRowIds[rowId] = true;
+	} else delete selectedRowIds[rowId];
+	if (includeChildren && row.subRows.length && row_getCanSelectSubRows(row)) row.subRows.forEach((r) => mutateRowIsSelected(selectedRowIds, r.id, value, includeChildren, table));
+};
+/**
+* Builds a row model containing rows selected by the current row selection state.
+*
+* The result is derived from the supplied row model, so selected ids absent from
+* that model are not materialized as rows.
+*
+* @example
+* ```ts
+* const selectedRows = selectRowsFn(rowModel)
+* ```
+*/
+function selectRowsFn(rowModel) {
+	const newSelectedFlatRows = [];
+	const newSelectedRowsById = {};
+	const recurseRows = (rows, depth = 0) => {
+		const result = [];
+		for (let i = 0; i < rows.length; i++) {
+			let row = rows[i];
+			const isSelected = isRowSelected(row);
+			if (isSelected) {
+				newSelectedFlatRows.push(row);
+				newSelectedRowsById[row.id] = row;
+			}
+			if (row.subRows.length) row = {
+				...row,
+				subRows: recurseRows(row.subRows, depth + 1)
+			};
+			if (isSelected) result.push(row);
+		}
+		return result;
+	};
+	return {
+		rows: recurseRows(rowModel.rows),
+		flatRows: newSelectedFlatRows,
+		rowsById: newSelectedRowsById
+	};
+}
+/**
+* Returns whether a row id is selected in the current row selection state.
+*
+* @example
+* ```ts
+* const selected = isRowSelected(row)
+* ```
+*/
+function isRowSelected(row) {
+	var _row$table$atoms$rowS;
+	return (((_row$table$atoms$rowS = row.table.atoms.rowSelection) === null || _row$table$atoms$rowS === void 0 ? void 0 : _row$table$atoms$rowS.get()) ?? {})[row.id] ?? false;
+}
+/**
+* Returns whether all, some, or none of a row's selectable descendants are selected.
+*
+* The result is used to drive indeterminate row selection UI.
+*
+* @example
+* ```ts
+* const selectedState = isSubRowSelected(row)
+* ```
+*/
+function isSubRowSelected(row) {
+	if (!row.subRows.length) return false;
+	let allChildrenSelected = true;
+	let someSelected = false;
+	row.subRows.forEach((subRow) => {
+		if (someSelected && !allChildrenSelected) return;
+		if (row_getCanSelect(subRow)) if (isRowSelected(subRow)) someSelected = true;
+		else allChildrenSelected = false;
+		if (subRow.subRows.length) {
+			const subRowChildrenSelected = isSubRowSelected(subRow);
+			if (subRowChildrenSelected === "all") someSelected = true;
+			else if (subRowChildrenSelected === "some") {
+				someSelected = true;
+				allChildrenSelected = false;
+			} else allChildrenSelected = false;
+		}
+	});
+	return allChildrenSelected ? "all" : someSelected ? "some" : false;
+}
+
+//#endregion
+exports.getDefaultRowSelectionState = getDefaultRowSelectionState;
+exports.isRowSelected = isRowSelected;
+exports.isSubRowSelected = isSubRowSelected;
+exports.row_getCanMultiSelect = row_getCanMultiSelect;
+exports.row_getCanSelect = row_getCanSelect;
+exports.row_getCanSelectSubRows = row_getCanSelectSubRows;
+exports.row_getIsAllSubRowsSelected = row_getIsAllSubRowsSelected;
+exports.row_getIsSelected = row_getIsSelected;
+exports.row_getIsSomeSelected = row_getIsSomeSelected;
+exports.row_getToggleSelectedHandler = row_getToggleSelectedHandler;
+exports.row_toggleSelected = row_toggleSelected;
+exports.selectRowsFn = selectRowsFn;
+exports.table_getFilteredSelectedRowModel = table_getFilteredSelectedRowModel;
+exports.table_getGroupedSelectedRowModel = table_getGroupedSelectedRowModel;
+exports.table_getIsAllPageRowsSelected = table_getIsAllPageRowsSelected;
+exports.table_getIsAllRowsSelected = table_getIsAllRowsSelected;
+exports.table_getIsSomePageRowsSelected = table_getIsSomePageRowsSelected;
+exports.table_getIsSomeRowsSelected = table_getIsSomeRowsSelected;
+exports.table_getPreSelectedRowModel = table_getPreSelectedRowModel;
+exports.table_getSelectedRowModel = table_getSelectedRowModel;
+exports.table_getToggleAllPageRowsSelectedHandler = table_getToggleAllPageRowsSelectedHandler;
+exports.table_getToggleAllRowsSelectedHandler = table_getToggleAllRowsSelectedHandler;
+exports.table_resetRowSelection = table_resetRowSelection;
+exports.table_setRowSelection = table_setRowSelection;
+exports.table_toggleAllPageRowsSelected = table_toggleAllPageRowsSelected;
+exports.table_toggleAllRowsSelected = table_toggleAllRowsSelected;
+//# sourceMappingURL=rowSelectionFeature.utils.cjs.map