@octanejs/aria 0.0.5 → 0.0.7

package/src/stately/grid/useGridState.ts

@@ -0,0 +1,160 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/grid/useGridState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; upstream's conditional `useMultipleSelectionState` call (behind
+// `UNSAFE_selectionState`) is valid octane — hooks are slot-keyed, not order-keyed;
+// explicit dependency arrays are kept verbatim (they retain React's exact behavior
+// in octane).
+import type { Key } from '@react-types/shared';
+import { useEffect, useMemo, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { getChildNodes, getFirstItem, getLastItem } from '../collections/getChildNodes';
+import type { GridNode, IGridCollection } from './GridCollection';
+import type { MultipleSelectionState } from '../selection/types';
+import {
+	type MultipleSelectionStateProps,
+	useMultipleSelectionState,
+} from '../selection/useMultipleSelectionState';
+import { SelectionManager } from '../selection/SelectionManager';
+
+export interface GridState<T, C extends IGridCollection<T>> {
+	collection: C;
+	/** A set of keys for rows that are disabled. */
+	disabledKeys: Set<Key>;
+	/** A selection manager to read and update row selection state. */
+	selectionManager: SelectionManager;
+	/**
+	 * Whether keyboard navigation is disabled, such as when the arrow keys should be handled by a
+	 * component within a cell.
+	 */
+	isKeyboardNavigationDisabled: boolean;
+}
+
+export interface GridStateOptions<
+	T,
+	C extends IGridCollection<T>,
+> extends MultipleSelectionStateProps {
+	collection: C;
+	disabledKeys?: Iterable<Key>;
+	focusMode?: 'row' | 'cell';
+	/** @private - Do not use unless you know what you're doing. */
+	UNSAFE_selectionState?: MultipleSelectionState;
+}
+
+/**
+ * Provides state management for a grid component. Handles row selection and focusing a grid cell's
+ * focusable child if applicable.
+ */
+export function useGridState<T extends object, C extends IGridCollection<T>>(
+	props: GridStateOptions<T, C>,
+): GridState<T, C>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useGridState<T extends object, C extends IGridCollection<T>>(
+	props: GridStateOptions<T, C>,
+	slot: symbol | undefined,
+): GridState<T, C>;
+export function useGridState(...args: any[]): GridState<any, IGridCollection<any>> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useGridState');
+	const props = user[0] as GridStateOptions<any, IGridCollection<any>>;
+
+	let { collection, focusMode } = props;
+	let selectionState =
+		props.UNSAFE_selectionState || useMultipleSelectionState(props, subSlot(slot, 'selection'));
+	let disabledKeys = useMemo(
+		() => (props.disabledKeys ? new Set(props.disabledKeys) : new Set<Key>()),
+		[props.disabledKeys],
+		subSlot(slot, 'disabled'),
+	);
+
+	let setFocusedKey = selectionState.setFocusedKey;
+	selectionState.setFocusedKey = (key, child) => {
+		// If focusMode is cell and an item is focused, focus a child cell instead.
+		if (focusMode === 'cell' && key != null) {
+			let item = collection.getItem(key);
+			if (item?.type === 'item') {
+				let children = getChildNodes(item, collection);
+				if (child === 'last') {
+					key = getLastItem(children)?.key ?? null;
+				} else {
+					key = getFirstItem(children)?.key ?? null;
+				}
+			}
+		}
+
+		setFocusedKey(key, child);
+	};
+
+	let selectionManager = useMemo(
+		() => new SelectionManager(collection, selectionState),
+		[collection, selectionState],
+		subSlot(slot, 'manager'),
+	);
+
+	// Reset focused key if that item is deleted from the collection.
+	const cachedCollection = useRef<IGridCollection<any> | null>(null, subSlot(slot, 'cached'));
+	useEffect(
+		() => {
+			if (
+				selectionState.focusedKey != null &&
+				cachedCollection.current &&
+				!collection.getItem(selectionState.focusedKey)
+			) {
+				const node = cachedCollection.current.getItem(selectionState.focusedKey);
+				const parentNode =
+					node?.parentKey != null &&
+					(node.type === 'cell' || node.type === 'rowheader' || node.type === 'column')
+						? cachedCollection.current.getItem(node.parentKey)
+						: node;
+				if (!parentNode) {
+					selectionState.setFocusedKey(null);
+					return;
+				}
+				const cachedRows = cachedCollection.current.rows;
+				const rows = collection.rows;
+				const diff = cachedRows.length - rows.length;
+				let index = Math.min(
+					diff > 1 ? Math.max(parentNode.index - diff + 1, 0) : parentNode.index,
+					rows.length - 1,
+				);
+				let newRow: GridNode<any> | null = null;
+				while (index >= 0) {
+					if (!selectionManager.isDisabled(rows[index].key) && rows[index].type !== 'headerrow') {
+						newRow = rows[index];
+						break;
+					}
+					// Find next, not disabled row.
+					if (index < rows.length - 1) {
+						index++;
+						// Otherwise, find previous, not disabled row.
+					} else {
+						if (index > parentNode.index) {
+							index = parentNode.index;
+						}
+						index--;
+					}
+				}
+				if (newRow) {
+					const childNodes = newRow.hasChildNodes ? [...getChildNodes(newRow, collection)] : [];
+					const keyToFocus =
+						newRow.hasChildNodes && parentNode !== node && node && node.index < childNodes.length
+							? childNodes[node.index].key
+							: newRow.key;
+					selectionState.setFocusedKey(keyToFocus);
+				} else {
+					selectionState.setFocusedKey(null);
+				}
+			}
+			cachedCollection.current = collection;
+		},
+		[collection, selectionManager, selectionState, selectionState.focusedKey],
+		subSlot(slot, 'focusReset'),
+	);
+
+	return {
+		collection,
+		disabledKeys,
+		isKeyboardNavigationDisabled: false,
+		selectionManager,
+	};
+}

package/src/stately/index.ts

@@ -116,3 +116,46 @@ export type { NumberFieldState, NumberFieldStateOptions } from './numberfield/us
 // slider
 export { useSliderState } from './slider/useSliderState';
 export type { SliderState, SliderStateOptions } from './slider/useSliderState';
+
+// grid — mirrors the @react-stately/grid shim surface.
+export { useGridState } from './grid/useGridState';
+export { GridCollection } from './grid/GridCollection';
+export type { GridStateOptions, GridState } from './grid/useGridState';
+export type { IGridCollection, GridNode, GridRow } from './grid/GridCollection';
+
+// table — mirrors the @react-stately/table shim surface (Section is already
+// exported from the collections section above).
+export { useTableState, UNSTABLE_useFilteredTableState } from './table/useTableState';
+export { useTableColumnResizeState } from './table/useTableColumnResizeState';
+export { UNSTABLE_useTreeGridState } from './table/useTreeGridState';
+export { TableHeader } from './table/TableHeader';
+export { TableBody } from './table/TableBody';
+export { Column } from './table/Column';
+export { Row } from './table/Row';
+export { Cell } from './table/Cell';
+export { TableCollection, buildHeaderRows } from './table/TableCollection';
+export { TableColumnLayout } from './table/TableColumnLayout';
+export type {
+	TableProps,
+	TableState,
+	TableStateProps,
+	CollectionBuilderContext,
+} from './table/useTableState';
+export type {
+	TableColumnResizeState,
+	TableColumnResizeStateProps,
+} from './table/useTableColumnResizeState';
+export type { TreeGridState, TreeGridStateProps } from './table/useTreeGridState';
+export type {
+	ColumnProps,
+	ColumnSize,
+	ColumnDynamicSize,
+	ColumnStaticSize,
+	ColumnElement,
+	ColumnRenderer,
+} from './table/Column';
+export type { TableHeaderProps } from './table/TableHeader';
+export type { TableBodyProps } from './table/TableBody';
+export type { RowProps, RowElement } from './table/Row';
+export type { CellProps, CellElement, CellRenderer } from './table/Cell';
+export type { ITableCollection } from './table/TableCollection';

package/src/stately/table/Cell.ts

@@ -0,0 +1,49 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/table/Cell.ts).
+// octane adaptations: React element types → `any` (octane element descriptors). `<Cell>` is
+// a collection DESCRIPTOR component — it renders nothing; CollectionBuilder walks it via
+// the static `getCollectionNode` generator.
+import type { Key } from '@react-types/shared';
+import type { PartialNode } from '../collections/types';
+
+export interface CellProps {
+	/** The contents of the cell. */
+	children: any;
+	/** A string representation of the cell's contents, used for features like typeahead. */
+	textValue?: string;
+	/** Indicates how many columns the data cell spans. */
+	colSpan?: number;
+}
+
+export type CellElement = any;
+export type CellRenderer = (columnKey: Key) => CellElement;
+
+function Cell(props: CellProps): any {
+	return null;
+}
+
+Cell.getCollectionNode = function* getCollectionNode<T>(
+	props: CellProps,
+): Generator<PartialNode<T>> {
+	let { children } = props;
+
+	let textValue =
+		props.textValue ||
+		(typeof children === 'string' ? children : '') ||
+		(props as any)['aria-label'] ||
+		'';
+	yield {
+		type: 'cell',
+		props: props,
+		rendered: children,
+		textValue,
+		'aria-label': (props as any)['aria-label'],
+		hasChildNodes: false,
+	};
+};
+
+/**
+ * A Cell represents the value of a single Column within a Table Row.
+ */
+// We don't want getCollectionNode to show up in the type definition
+let _Cell = Cell as unknown as (props: CellProps) => any;
+export { _Cell as Cell };

package/src/stately/table/Column.ts

@@ -0,0 +1,121 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/table/Column.ts).
+// octane adaptations: React.Children → octane Children (descriptor arrays); React element
+// types → `any` descriptors. Renders nothing; walked via static `getCollectionNode`.
+import { Children } from 'octane';
+
+import type { CollectionBuilderContext } from './useTableState';
+import type { GridNode } from '../grid/GridCollection';
+import type { PartialNode } from '../collections/types';
+
+/** Widths that result in a constant pixel value for the same Table width. */
+export type ColumnStaticSize = number | `${number}` | `${number}%`; // match regex: /^(\d+)(?=%$)/
+/**
+ * Widths that change size in relation to the remaining space and in ratio to other dynamic columns.
+ * All numbers must be integers and greater than 0.
+ * FR units take up remaining, if any, space in the table.
+ */
+export type ColumnDynamicSize = `${number}fr`; // match regex: /^(\d+)(?=fr$)/
+/** All possible sizes a column can be assigned. */
+export type ColumnSize = ColumnStaticSize | ColumnDynamicSize;
+
+export type ColumnElement<T> = any;
+export type ColumnRenderer<T> = (item: T) => ColumnElement<T>;
+export interface ColumnProps<T> {
+	/** Rendered contents of the column if `children` contains child columns. */
+	title?: any;
+	/** Static child columns or content to render as the column header. */
+	children: any;
+	/** A list of child columns used when dynamically rendering nested child columns. */
+	childColumns?: T[];
+	/** The width of the column. */
+	width?: ColumnSize | null;
+	/** The minimum width of the column. */
+	minWidth?: ColumnStaticSize | null;
+	/** The maximum width of the column. */
+	maxWidth?: ColumnStaticSize | null;
+	/** The default width of the column. */
+	defaultWidth?: ColumnSize | null;
+	/** Whether the column allows resizing. */
+	allowsResizing?: boolean;
+	/** Whether the column allows sorting. */
+	allowsSorting?: boolean;
+	/**
+	 * Whether a column is a [row header](https://www.w3.org/TR/wai-aria-1.1/#rowheader) and should be
+	 * announced by assistive technology during row navigation.
+	 */
+	isRowHeader?: boolean;
+	/** A string representation of the column's contents, used for accessibility announcements. */
+	textValue?: string;
+}
+
+function Column<T>(props: ColumnProps<T>): any {
+	return null;
+}
+
+Column.getCollectionNode = function* getCollectionNode<T>(
+	props: ColumnProps<T>,
+	context: CollectionBuilderContext<T>,
+): Generator<PartialNode<T>, void, GridNode<T>[]> {
+	let { title, children, childColumns } = props;
+
+	let rendered = title || children;
+	let textValue =
+		props.textValue ||
+		(typeof rendered === 'string' ? rendered : '') ||
+		(props as any)['aria-label'];
+
+	let fullNodes = yield {
+		type: 'column',
+		hasChildNodes: !!childColumns || (!!title && Children.count(children) > 0),
+		rendered,
+		textValue,
+		props,
+		*childNodes() {
+			if (childColumns) {
+				for (let child of childColumns) {
+					yield {
+						type: 'column',
+						value: child,
+					};
+				}
+			} else if (title) {
+				let childColumns: PartialNode<T>[] = [];
+				Children.forEach(children, (child: any) => {
+					childColumns.push({
+						type: 'column',
+						element: child,
+					});
+				});
+
+				yield* childColumns;
+			}
+		},
+		shouldInvalidate(newContext: CollectionBuilderContext<T>) {
+			// This is a bit of a hack, but it works.
+			// If this method is called, then there's a cached version of this node available.
+			// But, we need to keep the list of columns in the new context up to date.
+			updateContext(newContext);
+			return false;
+		},
+	};
+
+	let updateContext = (context: CollectionBuilderContext<T>) => {
+		// register leaf columns on the context so that <Row> can access them
+		for (let node of fullNodes) {
+			if (!node.hasChildNodes) {
+				context.columns.push(node);
+			}
+		}
+	};
+
+	updateContext(context);
+};
+
+/**
+ * A Column represents a field of each item within a Table. Columns may also contain nested
+ * Column elements to represent column groups. Nested columns can be statically defined as
+ * children, or dynamically generated using a function based on the `childColumns` prop.
+ */
+// We don't want getCollectionNode to show up in the type definition
+let _Column = Column as unknown as <T>(props: ColumnProps<T>) => any;
+export { _Column as Column };

package/src/stately/table/Row.ts

@@ -0,0 +1,145 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/table/Row.ts).
+// octane adaptations: React.Children → octane Children (descriptor arrays); React element
+// types → `any` descriptors. Renders nothing; walked via static `getCollectionNode`.
+// The `node.type === Row` check compares against the INTERNAL function identity, which is
+// what descriptor `.type` carries for `<Row>` used at a value position.
+import type { LinkDOMProps } from '@react-types/shared';
+import { Children } from 'octane';
+
+import type { CellElement, CellRenderer } from './Cell';
+import type { CollectionBuilderContext } from './useTableState';
+import type { PartialNode } from '../collections/types';
+
+export type RowElement<T> = any;
+export interface RowProps<T> extends LinkDOMProps {
+	/**
+	 * A list of child item objects used when dynamically rendering row children. Requires the feature
+	 * flag to be enabled along with UNSTABLE_allowsExpandableRows, see
+	 * https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows.
+	 *
+	 * @private
+	 * @version alpha
+	 */
+	UNSTABLE_childItems?: Iterable<T>;
+	// TODO: update when async loading is supported for expandable rows
+	// /** Whether this row has children, even if not loaded yet. */
+	// hasChildItems?: boolean,
+	/** Rendered contents of the row or row child items. */
+	children: CellElement | CellElement[] | CellRenderer;
+	/** A string representation of the row's contents, used for features like typeahead. */
+	textValue?: string; // ???
+}
+
+function Row<T>(props: RowProps<T>): any {
+	return null;
+}
+
+Row.getCollectionNode = function* getCollectionNode<T>(
+	props: RowProps<T>,
+	context: CollectionBuilderContext<T>,
+): Generator<PartialNode<T>> {
+	let { children, textValue, UNSTABLE_childItems } = props;
+
+	yield {
+		type: 'item',
+		props: props,
+		textValue,
+		'aria-label': (props as any)['aria-label'],
+		hasChildNodes: true,
+		*childNodes() {
+			// Process cells first
+			if (context.showDragButtons) {
+				yield {
+					type: 'cell',
+					key: 'header-drag', // this is combined with the row key by CollectionBuilder
+					props: {
+						isDragButtonCell: true,
+					},
+				};
+			}
+
+			if (context.showSelectionCheckboxes && context.selectionMode !== 'none') {
+				yield {
+					type: 'cell',
+					key: 'header', // this is combined with the row key by CollectionBuilder
+					props: {
+						isSelectionCell: true,
+					},
+				};
+			}
+
+			if (typeof children === 'function') {
+				for (let column of context.columns) {
+					yield {
+						type: 'cell',
+						element: children(column.key),
+						key: column.key, // this is combined with the row key by CollectionBuilder
+					};
+				}
+
+				if (UNSTABLE_childItems) {
+					for (let child of UNSTABLE_childItems) {
+						// Note: in order to reuse the render function of TableBody for our child rows, we just need to yield a type and a value here. CollectionBuilder will then look up
+						// the parent renderer and use that to build the full node of this child row, using the value provided here to generate the cells
+						yield {
+							type: 'item',
+							value: child,
+						};
+					}
+				}
+			} else {
+				let cells: PartialNode<T>[] = [];
+				let childRows: PartialNode<T>[] = [];
+				let columnCount = 0;
+				Children.forEach(children, (node: any) => {
+					if (node.type === Row) {
+						if (cells.length < context.columns.length) {
+							throw new Error(
+								"All of a Row's child Cells must be positioned before any child Rows.",
+							);
+						}
+
+						childRows.push({
+							type: 'item',
+							element: node,
+						});
+					} else {
+						cells.push({
+							type: 'cell',
+							element: node,
+						});
+						columnCount += node.props.colSpan ?? 1;
+					}
+				});
+
+				if (columnCount !== context.columns.length) {
+					throw new Error(
+						`Cell count must match column count. Found ${columnCount} cells and ${context.columns.length} columns.`,
+					);
+				}
+
+				yield* cells;
+				yield* childRows;
+			}
+		},
+		shouldInvalidate(newContext: CollectionBuilderContext<T>) {
+			// Invalidate all rows if the columns changed.
+			return (
+				newContext.columns.length !== context.columns.length ||
+				newContext.columns.some((c, i) => c.key !== context.columns[i].key) ||
+				newContext.showSelectionCheckboxes !== context.showSelectionCheckboxes ||
+				newContext.showDragButtons !== context.showDragButtons ||
+				newContext.selectionMode !== context.selectionMode
+			);
+		},
+	};
+};
+
+/**
+ * A Row represents a single item in a Table and contains Cell elements for each column.
+ * Cells can be statically defined as children, or generated dynamically using a function
+ * based on the columns defined in the TableHeader.
+ */
+// We don't want getCollectionNode to show up in the type definition
+let _Row = Row as unknown as <T>(props: RowProps<T>) => any;
+export { _Row as Row };

package/src/stately/table/TableBody.ts

@@ -0,0 +1,66 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/table/TableBody.ts).
+// octane adaptations: React.Children → octane Children (descriptor arrays); React element
+// types → `any` descriptors. Renders nothing; walked via static `getCollectionNode`.
+import type { AsyncLoadable, LoadingState } from '@react-types/shared';
+import { Children } from 'octane';
+
+import type { PartialNode } from '../collections/types';
+import type { RowElement } from './Row';
+
+export interface TableBodyProps<T> extends Omit<AsyncLoadable, 'isLoading'> {
+	/** The contents of the table body. Supports static items or a function for dynamic rendering. */
+	children: RowElement<T> | RowElement<T>[] | ((item: T) => RowElement<T>);
+	/** A list of row objects in the table body used when dynamically rendering rows. */
+	items?: Iterable<T>;
+	/** The current loading state of the table. */
+	loadingState?: LoadingState;
+}
+
+function TableBody<T>(props: TableBodyProps<T>): any {
+	return null;
+}
+
+TableBody.getCollectionNode = function* getCollectionNode<T>(
+	props: TableBodyProps<T>,
+): Generator<PartialNode<T>> {
+	let { children, items } = props;
+	yield {
+		type: 'body',
+		hasChildNodes: true,
+		props,
+		*childNodes() {
+			if (typeof children === 'function') {
+				if (!items) {
+					throw new Error('props.children was a function but props.items is missing');
+				}
+
+				for (let item of items) {
+					yield {
+						type: 'item',
+						value: item,
+						renderer: children,
+					};
+				}
+			} else {
+				let items: PartialNode<T>[] = [];
+				Children.forEach(children, (item: any) => {
+					items.push({
+						type: 'item',
+						element: item,
+					});
+				});
+
+				yield* items;
+			}
+		},
+	};
+};
+
+/**
+ * A TableBody is a container for the Row elements of a Table. Rows can be statically defined as
+ * children, or generated dynamically using a function based on the data passed to the `items`
+ * prop.
+ */
+// We don't want getCollectionNode to show up in the type definition
+let _TableBody = TableBody as unknown as <T>(props: TableBodyProps<T>) => any;
+export { _TableBody as TableBody };