@octanejs/aria 0.0.5 → 0.0.7

package/src/stately/table/TableUtils.ts

@@ -0,0 +1,269 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/table/TableUtils.ts).
+// Verbatim (no React surface).
+import type { Key } from '@react-types/shared';
+
+import type { ColumnSize } from './Column';
+
+// numbers and percents are considered static. *fr units or a lack of units are considered dynamic.
+export function isStatic(width?: ColumnSize | null): boolean {
+	return width != null && (!isNaN(width as number) || String(width).match(/^(\d+)(?=%$)/) !== null);
+}
+
+export function parseFractionalUnit(width?: ColumnSize | null): number {
+	if (!width || typeof width === 'number') {
+		return 1;
+	}
+	let match = width.match(/^(.+)(?=fr$)/);
+	// if width is the incorrect format, just default it to a 1fr
+	if (!match) {
+		if (process.env.NODE_ENV !== 'production') {
+			console.warn(
+				`width: ${width} is not a supported format, width should be a number (ex. 150), percentage (ex. '50%') or fr unit (ex. '2fr')`,
+				"defaulting to '1fr'",
+			);
+		}
+		return 1;
+	}
+	return parseFloat(match[0]);
+}
+
+export function parseStaticWidth(width: number | string, tableWidth: number): number {
+	if (typeof width === 'string') {
+		let match = width.match(/^(\d+)(?=%$)/);
+		if (!match) {
+			throw new Error('Only percentages or numbers are supported for static column widths');
+		}
+		return tableWidth * (parseFloat(match[0]) / 100);
+	}
+	return width;
+}
+
+export function getMaxWidth(
+	maxWidth: number | string | null | undefined,
+	tableWidth: number,
+): number {
+	return maxWidth != null ? parseStaticWidth(maxWidth, tableWidth) : Number.MAX_SAFE_INTEGER;
+}
+
+// cannot support FR units, we'd need to know everything else in the table to do that
+export function getMinWidth(minWidth: number | string, tableWidth: number): number {
+	return minWidth != null ? parseStaticWidth(minWidth, tableWidth) : 0;
+}
+
+export interface IColumn {
+	minWidth?: number | string;
+	maxWidth?: number | string;
+	width?: number | string;
+	defaultWidth?: number | string;
+	key: Key;
+}
+
+interface FlexItem {
+	frozen: boolean;
+	baseSize: number;
+	hypotheticalMainSize: number;
+	min: number;
+	max: number;
+	flex: number;
+	targetMainSize: number;
+	violation: number;
+}
+
+/**
+ * Implements the flex algorithm described in https://www.w3.org/TR/css-flexbox-1/#layout-algorithm
+ * It makes a few constraint/assumptions: 1. All basis values are 0 unless it is a static width,
+ * then the basis is the static width 2. All flex grow and shrink values are equal to the FR
+ * specified on the column, grow and shrink for the same column are equal 3. We only have one row An
+ * example of the setup can be seen here https://jsfiddle.net/snowystinger/wv0ymjaf/61/ where I let
+ * the browser figure out the flex of the columns. Note: We differ in one key aspect, all of our
+ * column widths must be whole numbers, so we avoid browser sub pixel rounding errors. To do this,
+ * we use a cascading rounding algorithm to ensure that the sum of the widths is maintained while
+ * distributing the rounding remainder across the columns.
+ *
+ * As noted in the chrome source code, this algorithm is very accurate, but has the potential to be
+ * quadratic. They have deemed this to be acceptable because the number of elements is usually small
+ * and the flex factors are usually not high variance. I believe we can make the same assumptions.
+ * Particularly once resizing is started, it will convert all columns to the left to static widths,
+ * so it will cut down on the number of FR columns.
+ *
+ * There are likely faster ways to do this, I've chosen to stick to the spec as closely as possible
+ * for readability, accuracy, and for the note that this behaving quadratically is unlikely to be a
+ * problem.
+ *
+ * @param availableWidth - The visible width of the table.
+ * @param columns - The table defined columns.
+ * @param changedColumns - Any columns we want to override, for example, during resizing.
+ * @param getDefaultWidth - A function that returns the default width of a column by its index.
+ * @param getDefaultMinWidth - A function that returns the default min width of a column by its
+ *   index.
+ */
+export function calculateColumnSizes(
+	availableWidth: number,
+	columns: IColumn[],
+	changedColumns: Map<Key, ColumnSize>,
+	getDefaultWidth?: (index: number) => ColumnSize | null | undefined,
+	getDefaultMinWidth?: (index: number) => ColumnSize | null | undefined,
+): number[] {
+	let hasNonFrozenItems = false;
+	let flexItems: FlexItem[] = columns.map((column, index) => {
+		let width: ColumnSize = (
+			changedColumns.get(column.key) != null
+				? (changedColumns.get(column.key) ?? '1fr')
+				: (column.width ?? column.defaultWidth ?? getDefaultWidth?.(index) ?? '1fr')
+		) as ColumnSize;
+		let frozen = false;
+		let baseSize = 0;
+		let flex = 0;
+		let targetMainSize = 0;
+		if (isStatic(width)) {
+			baseSize = parseStaticWidth(width, availableWidth);
+			frozen = true;
+		} else {
+			flex = parseFractionalUnit(width);
+			if (flex <= 0) {
+				frozen = true;
+			}
+		}
+
+		let min = getMinWidth(column.minWidth ?? getDefaultMinWidth?.(index) ?? 0, availableWidth);
+		let max = getMaxWidth(column.maxWidth, availableWidth);
+		let hypotheticalMainSize = Math.max(min, Math.min(baseSize, max));
+
+		// 9.7.1
+		// We don't make use of flex basis, it's always 0, so we are always in 'grow' mode.
+		// 9.7.2
+		if (frozen) {
+			targetMainSize = hypotheticalMainSize;
+		} else if (baseSize > hypotheticalMainSize) {
+			frozen = true;
+			targetMainSize = hypotheticalMainSize;
+		}
+
+		// 9.7.3
+		if (!frozen) {
+			hasNonFrozenItems = true;
+		}
+		return {
+			frozen,
+			baseSize,
+			hypotheticalMainSize,
+			min,
+			max,
+			flex,
+			targetMainSize,
+			violation: 0,
+		};
+	});
+
+	// 9.7.4
+	// 9.7.4.a
+	while (hasNonFrozenItems) {
+		// 9.7.4.b
+		/**
+		 * Calculate the remaining free space as for initial free space,
+		 * above (9.7.3). If the sum of the unfrozen flex items’ flex factors is
+		 * less than one, multiply the initial free space by this sum (of flex factors).
+		 * If the magnitude of this value is less than the magnitude of
+		 * the remaining free space, use this as the remaining free space.
+		 */
+		let usedWidth = 0;
+		let flexFactors = 0;
+		flexItems.forEach((item) => {
+			if (item.frozen) {
+				usedWidth += item.targetMainSize;
+			} else {
+				usedWidth += item.baseSize;
+				flexFactors += item.flex;
+			}
+		});
+
+		let remainingFreeSpace = availableWidth - usedWidth;
+		// we only support integer FR's, and because of hasNonFrozenItems, we know that flexFactors > 0
+		// so no need to check for flexFactors < 1
+		// 9.7.4.c
+		/**
+		 * If the remaining free space is zero
+		 * - Do nothing.
+		 * Else // remember, we're always in grow mode
+		 * - Find the ratio of the item’s flex grow factor to the
+		 * sum of the flex grow factors of all unfrozen items on
+		 * the line. Set the item’s target main size to its flex
+		 * base size plus a fraction of the remaining free space
+		 * proportional to the ratio.
+		 */
+		if (remainingFreeSpace > 0) {
+			flexItems.forEach((item) => {
+				if (!item.frozen) {
+					let ratio = item.flex / flexFactors;
+					item.targetMainSize = item.baseSize + ratio * remainingFreeSpace;
+				}
+			});
+		}
+
+		// 9.7.4.d
+		/**
+		 * Fix min/max violations. Clamp each non-frozen item’s
+		 * target main size by its used min and max main sizes
+		 * and floor its content-box size at zero. If the item’s
+		 * target main size was made smaller by this, it’s a max
+		 * violation. If the item’s target main size was made
+		 * larger by this, it’s a min violation.
+		 */
+		let totalViolation = 0;
+		flexItems.forEach((item) => {
+			item.violation = 0;
+			if (!item.frozen) {
+				let { min, max, targetMainSize } = item;
+				item.targetMainSize = Math.max(min, Math.min(targetMainSize, max));
+
+				item.violation = item.targetMainSize - targetMainSize;
+				totalViolation += item.violation;
+			}
+		});
+
+		// 9.7.4.e
+		/**
+		 * Freeze over-flexed items. The total violation is the
+		 * sum of the adjustments from the previous step
+		 * ∑(clamped size - unclamped size). If the total violation is:
+		 * Zero
+		 * - Freeze all items.
+		 *
+		 * Positive
+		 * - Freeze all the items with min violations.
+		 *
+		 * Negative
+		 * - Freeze all the items with max violations.
+		 */
+		hasNonFrozenItems = false;
+		flexItems.forEach((item) => {
+			if (totalViolation === 0 || Math.sign(totalViolation) === Math.sign(item.violation)) {
+				item.frozen = true;
+			} else if (!item.frozen) {
+				hasNonFrozenItems = true;
+			}
+		});
+	}
+
+	return cascadeRounding(flexItems);
+}
+
+function cascadeRounding(flexItems: FlexItem[]): number[] {
+	/*
+  Given an array of floats that sum to an integer, this rounds the floats
+  and returns an array of integers with the same sum.
+  */
+
+	let fpTotal = 0;
+	let intTotal = 0;
+	let roundedArray: number[] = [];
+	flexItems.forEach(function (item) {
+		let float = item.targetMainSize;
+		let integer = Math.round(float + fpTotal) - intTotal;
+		fpTotal += float;
+		intTotal += integer;
+		roundedArray.push(integer);
+	});
+
+	return roundedArray;
+}

package/src/stately/table/useTableColumnResizeState.ts

@@ -0,0 +1,202 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/table/useTableColumnResizeState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; explicit dependency arrays are kept verbatim (they retain React's exact
+// behavior in octane). Upstream's render-phase "reset uncontrolled widths when the
+// columns changed" adjustment is kept verbatim (React's setState-during-render pattern;
+// octane re-runs the component the same way).
+import type { Key } from '@react-types/shared';
+import { useCallback, useMemo, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import type { ColumnSize } from './Column';
+import type { GridNode } from '../grid/GridCollection';
+import { TableColumnLayout } from './TableColumnLayout';
+import type { TableState } from './useTableState';
+
+export interface TableColumnResizeStateProps<T> {
+	/**
+	 * Current width of the table or table viewport that the columns
+	 * should be calculated against.
+	 */
+	tableWidth: number;
+	/** A function that is called to find the default width for a given column. */
+	getDefaultWidth?: (node: GridNode<T>) => ColumnSize | null | undefined;
+	/** A function that is called to find the default minWidth for a given column. */
+	getDefaultMinWidth?: (node: GridNode<T>) => ColumnSize | null | undefined;
+}
+
+export interface TableColumnResizeState<T> {
+	/**
+	 * Called to update the state that a resize event has occurred.
+	 * Returns the new widths for all columns based on the resized column.
+	 */
+	updateResizedColumns: (key: Key, width: number) => Map<Key, ColumnSize>;
+	/** Callback for when onColumnResize has started. */
+	startResize: (key: Key) => void;
+	/** Callback for when onColumnResize has ended. */
+	endResize: () => void;
+	/** Gets the current width for the specified column. */
+	getColumnWidth: (key: Key) => number;
+	/** Gets the current minWidth for the specified column. */
+	getColumnMinWidth: (key: Key) => number;
+	/** Gets the current maxWidth for the specified column. */
+	getColumnMaxWidth: (key: Key) => number;
+	/** Key of the currently resizing column. */
+	resizingColumn: Key | null;
+	/** A reference to the table state. */
+	tableState: TableState<T>;
+	/** A map of the current column widths. */
+	columnWidths: Map<Key, number>;
+}
+
+/**
+ * Provides column width state management for a table component with column resizing support.
+ * Handles building a map of column widths calculated from the table's width and any provided column
+ * width information from the collection. In addition, it tracks the currently resizing column and
+ * provides callbacks for updating the widths upon resize operations.
+ *
+ * @param props - Props for the table.
+ * @param state - State for the table, as returned by `useTableState`.
+ */
+export function useTableColumnResizeState<T>(
+	props: TableColumnResizeStateProps<T>,
+	state: TableState<T>,
+): TableColumnResizeState<T>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTableColumnResizeState<T>(
+	props: TableColumnResizeStateProps<T>,
+	state: TableState<T>,
+	slot: symbol | undefined,
+): TableColumnResizeState<T>;
+export function useTableColumnResizeState(...args: any[]): TableColumnResizeState<any> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTableColumnResizeState');
+	const props = user[0] as TableColumnResizeStateProps<any>;
+	const state = user[1] as TableState<any>;
+
+	let { getDefaultWidth, getDefaultMinWidth, tableWidth = 0 } = props;
+
+	let [resizingColumn, setResizingColumn] = useState<Key | null>(null, subSlot(slot, 'resizing'));
+	let columnLayout = useMemo(
+		() =>
+			new TableColumnLayout({
+				getDefaultWidth,
+				getDefaultMinWidth,
+			}),
+		[getDefaultWidth, getDefaultMinWidth],
+		subSlot(slot, 'layout'),
+	);
+
+	let [controlledColumns, uncontrolledColumns] = useMemo(
+		() => columnLayout.splitColumnsIntoControlledAndUncontrolled(state.collection.columns),
+		[state.collection.columns, columnLayout],
+		subSlot(slot, 'split'),
+	);
+
+	// uncontrolled column widths
+	let [uncontrolledWidths, setUncontrolledWidths] = useState(
+		() => columnLayout.getInitialUncontrolledWidths(uncontrolledColumns),
+		subSlot(slot, 'uncontrolled'),
+	);
+
+	// Update uncontrolled widths if the columns changed.
+	let [lastColumns, setLastColumns] = useState(state.collection.columns, subSlot(slot, 'last'));
+	if (state.collection.columns !== lastColumns) {
+		if (
+			state.collection.columns.length !== lastColumns.length ||
+			state.collection.columns.some((c, i) => c.key !== lastColumns[i].key)
+		) {
+			let newUncontrolledWidths = columnLayout.getInitialUncontrolledWidths(uncontrolledColumns);
+			setUncontrolledWidths(newUncontrolledWidths);
+		}
+		setLastColumns(state.collection.columns);
+	}
+
+	// combine columns back into one map that maintains same order as the columns
+	let colWidths = useMemo(
+		() =>
+			columnLayout.recombineColumns(
+				state.collection.columns,
+				uncontrolledWidths,
+				uncontrolledColumns,
+				controlledColumns,
+			),
+		[
+			state.collection.columns,
+			uncontrolledWidths,
+			uncontrolledColumns,
+			controlledColumns,
+			columnLayout,
+		],
+		subSlot(slot, 'colWidths'),
+	);
+
+	let startResize = useCallback(
+		(key: Key) => {
+			setResizingColumn(key);
+		},
+		[setResizingColumn],
+		subSlot(slot, 'start'),
+	);
+
+	let updateResizedColumns = useCallback(
+		(key: Key, width: number): Map<Key, ColumnSize> => {
+			let newSizes = columnLayout.resizeColumnWidth(
+				state.collection,
+				uncontrolledWidths,
+				key,
+				width,
+			);
+			let map = new Map(Array.from(uncontrolledColumns).map(([key]) => [key, newSizes.get(key)!]));
+			map.set(key, width);
+			setUncontrolledWidths(map);
+			return newSizes;
+		},
+		[
+			uncontrolledColumns,
+			setUncontrolledWidths,
+			columnLayout,
+			state.collection,
+			uncontrolledWidths,
+		],
+		subSlot(slot, 'update'),
+	);
+
+	let endResize = useCallback(
+		() => {
+			setResizingColumn(null);
+		},
+		[setResizingColumn],
+		subSlot(slot, 'end'),
+	);
+
+	let columnWidths = useMemo(
+		() => columnLayout.buildColumnWidths(tableWidth, state.collection, colWidths),
+		[tableWidth, state.collection, colWidths, columnLayout],
+		subSlot(slot, 'widths'),
+	);
+
+	return useMemo(
+		() => ({
+			resizingColumn,
+			updateResizedColumns,
+			startResize,
+			endResize,
+			getColumnWidth: (key: Key) => columnLayout.getColumnWidth(key),
+			getColumnMinWidth: (key: Key) => columnLayout.getColumnMinWidth(key),
+			getColumnMaxWidth: (key: Key) => columnLayout.getColumnMaxWidth(key),
+			tableState: state,
+			columnWidths,
+		}),
+		[
+			columnLayout,
+			columnWidths,
+			resizingColumn,
+			updateResizedColumns,
+			startResize,
+			endResize,
+			state,
+		],
+		subSlot(slot, 'result'),
+	);
+}

package/src/stately/table/useTableState.ts

@@ -0,0 +1,235 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/table/useTableState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; React element types → `any` descriptors (`children` is a
+// [<TableHeader>, <TableBody>] descriptor pair); explicit dependency arrays are kept
+// verbatim (they retain React's exact behavior in octane).
+import type {
+	Expandable,
+	Key,
+	MultipleSelection,
+	Node,
+	SelectionMode,
+	Sortable,
+	SortDescriptor,
+	SortDirection,
+} from '@react-types/shared';
+import { useCallback, useMemo, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { type GridState, useGridState } from '../grid/useGridState';
+import { type ITableCollection, TableCollection } from './TableCollection';
+import type { MultipleSelectionState } from '../selection/types';
+import type { MultipleSelectionStateProps } from '../selection/useMultipleSelectionState';
+import { useCollection } from '../collections/useCollection';
+import { useControlledState } from '../utils/useControlledState';
+
+export interface TableProps<T> extends MultipleSelection, Sortable, Expandable {
+	/** The elements that make up the table. Includes the TableHeader, TableBody, Columns, and Rows. */
+	children: [any, any];
+	/** A list of row keys to disable. */
+	disabledKeys?: Iterable<Key>;
+	/**
+	 * Whether pressing the escape key should clear selection in the table or not.
+	 *
+	 * Most experiences should not modify this option as it eliminates a keyboard user's ability to
+	 * easily clear selection. Only use if the escape key is being handled externally or should not
+	 * trigger selection clearing contextually.
+	 *
+	 * @default 'clearSelection'
+	 */
+	escapeKeyBehavior?: 'clearSelection' | 'none';
+	/** Whether selection should occur on press up instead of press down. */
+	shouldSelectOnPressUp?: boolean;
+	/** The id of the column that displays hierarchical data. */
+	treeColumn?: Key;
+}
+
+export interface TableState<T> extends GridState<T, ITableCollection<T>> {
+	/** A collection of rows and columns in the table. */
+	collection: ITableCollection<T>;
+	/** Whether the row selection checkboxes should be displayed. */
+	showSelectionCheckboxes: boolean;
+	/** The current sorted column and direction. */
+	sortDescriptor: SortDescriptor | null;
+	/** Calls the provided onSortChange handler with the provided column key and sort direction. */
+	sort(columnKey: Key, direction?: 'ascending' | 'descending'): void;
+	/**
+	 * Whether keyboard navigation is disabled, such as when the arrow keys should be handled by a
+	 * component within a cell.
+	 */
+	isKeyboardNavigationDisabled: boolean;
+	/**
+	 * Set whether keyboard navigation is disabled, such as when the arrow keys should be handled by a
+	 * component within a cell.
+	 */
+	setKeyboardNavigationDisabled: (val: boolean) => void;
+	/** A set of keys for items that are expanded. */
+	expandedKeys: Set<Key>;
+	/** Toggles the expanded state for a row by its key. */
+	toggleKey(key: Key): void;
+	/** The id of the column that displays hierarchical data. */
+	treeColumn: Key | null;
+}
+
+export interface CollectionBuilderContext<T> {
+	showSelectionCheckboxes: boolean;
+	showDragButtons: boolean;
+	selectionMode: SelectionMode;
+	columns: Node<T>[];
+}
+
+export interface TableStateProps<T> extends MultipleSelectionStateProps, Expandable, Sortable {
+	/** The elements that make up the table. Includes the TableHeader, TableBody, Columns, and Rows. */
+	children?: [any, any];
+	/** A pre-constructed collection to use instead of building one from items and children. */
+	collection?: ITableCollection<T>;
+	/** Whether the row selection checkboxes should be displayed. */
+	showSelectionCheckboxes?: boolean;
+	/**
+	 * Whether the row drag button should be displayed.
+	 *
+	 * @private
+	 */
+	showDragButtons?: boolean;
+	/** @private - Do not use unless you know what you're doing. */
+	UNSAFE_selectionState?: MultipleSelectionState;
+	/** The id of the column that displays hierarchical data. */
+	treeColumn?: Key;
+}
+
+const OPPOSITE_SORT_DIRECTION = {
+	ascending: 'descending' as SortDirection,
+	descending: 'ascending' as SortDirection,
+};
+
+/**
+ * Provides state management for a table component. Handles building a collection of columns and
+ * rows from props. In addition, it tracks row selection and manages sort order changes.
+ */
+export function useTableState<T extends object>(props: TableStateProps<T>): TableState<T>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTableState<T extends object>(
+	props: TableStateProps<T>,
+	slot: symbol | undefined,
+): TableState<T>;
+export function useTableState(...args: any[]): TableState<any> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTableState');
+	const props = user[0] as TableStateProps<any>;
+
+	let [isKeyboardNavigationDisabled, setKeyboardNavigationDisabled] = useState(
+		false,
+		subSlot(slot, 'kbdNav'),
+	);
+	let {
+		selectionMode = 'none',
+		showSelectionCheckboxes,
+		showDragButtons,
+		treeColumn = null,
+	} = props;
+
+	let context = useMemo(
+		() => ({
+			showSelectionCheckboxes: showSelectionCheckboxes && selectionMode !== 'none',
+			showDragButtons: showDragButtons,
+			selectionMode,
+			columns: [],
+		}),
+		[props.children, showSelectionCheckboxes, selectionMode, showDragButtons],
+		subSlot(slot, 'context'),
+	);
+
+	let collection = useCollection<any, ITableCollection<any>>(
+		props,
+		useCallback(
+			(nodes) => new TableCollection(nodes, null, context),
+			[context],
+			subSlot(slot, 'factory'),
+		),
+		context,
+		subSlot(slot, 'collection'),
+	);
+	let { disabledKeys, selectionManager } = useGridState(
+		{
+			...props,
+			collection,
+			disabledBehavior: props.disabledBehavior || 'selection',
+		},
+		subSlot(slot, 'grid'),
+	);
+
+	let [expandedKeys, setExpandedKeys] = useControlledState(
+		props.expandedKeys ? new Set(props.expandedKeys) : undefined,
+		props.defaultExpandedKeys ? new Set(props.defaultExpandedKeys) : new Set(),
+		props.onExpandedChange,
+		subSlot(slot, 'expanded'),
+	);
+
+	return {
+		collection,
+		disabledKeys,
+		selectionManager,
+		showSelectionCheckboxes: props.showSelectionCheckboxes || false,
+		sortDescriptor: props.sortDescriptor ?? null,
+		isKeyboardNavigationDisabled: collection.size === 0 || isKeyboardNavigationDisabled,
+		setKeyboardNavigationDisabled,
+		sort(columnKey: Key, direction?: 'ascending' | 'descending') {
+			props.onSortChange?.({
+				column: columnKey,
+				direction:
+					direction ??
+					(props.sortDescriptor?.column === columnKey
+						? OPPOSITE_SORT_DIRECTION[props.sortDescriptor.direction]
+						: 'ascending'),
+			});
+		},
+		expandedKeys,
+		toggleKey(key) {
+			setExpandedKeys((keys) => {
+				let newKeys = new Set(keys);
+				if (newKeys.has(key)) {
+					newKeys.delete(key);
+				} else {
+					newKeys.add(key);
+				}
+
+				return newKeys;
+			});
+		},
+		treeColumn,
+	};
+}
+
+/**
+ * Filters a collection using the provided filter function and returns a new TableState.
+ */
+export function UNSTABLE_useFilteredTableState<T extends object>(
+	state: TableState<T>,
+	filterFn: ((nodeValue: string, node: Node<T>) => boolean) | null | undefined,
+): TableState<T>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function UNSTABLE_useFilteredTableState<T extends object>(
+	state: TableState<T>,
+	filterFn: ((nodeValue: string, node: Node<T>) => boolean) | null | undefined,
+	slot: symbol | undefined,
+): TableState<T>;
+export function UNSTABLE_useFilteredTableState(...args: any[]): TableState<any> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('UNSTABLE_useFilteredTableState');
+	const state = user[0] as TableState<any>;
+	const filterFn = user[1] as ((nodeValue: string, node: Node<any>) => boolean) | null | undefined;
+
+	let collection = useMemo(
+		() => (filterFn ? state.collection.filter!(filterFn) : state.collection),
+		[state.collection, filterFn],
+		subSlot(slot, 'collection'),
+	) as ITableCollection<any>;
+	let selectionManager = state.selectionManager.withCollection(collection);
+	// TODO: handle focus key reset? That logic is in useGridState
+
+	return {
+		...state,
+		collection,
+		selectionManager,
+	};
+}