@octanejs/aria 0.0.5 → 0.0.7

package/src/table/useTableRow.ts

@@ -0,0 +1,198 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/table/useTableRow.ts).
+// octane adaptations:
+// - Handlers receive NATIVE events: the treegrid expansion keydown handler takes the
+//   native KeyboardEvent.
+// - `TableState`/`TreeGridState`/`ITableCollection` come from the ported stately hooks;
+//   `useGridRow` from the ported src/grid/; React's `HTMLAttributes` and `DOMAttributes`
+//   collapse to a structural prop bag.
+// - The Parcel glob intl import becomes the generated src/intl/table index (verbatim
+//   dictionaries).
+// - Public-hook slot threading (splitSlot/subSlot).
+import type { AriaButtonProps } from '../button/useButton';
+
+import type { Collection, FocusableElement, Node, RefObject } from '@react-types/shared';
+import { getRowLabelledBy } from './utils';
+import { GridRowAria, GridRowProps, useGridRow } from '../grid/useGridRow';
+import intlMessages from '../intl/table';
+import type { ITableCollection } from '../stately/table/TableCollection';
+import { mergeProps } from '../utils/mergeProps';
+import type { TableState } from '../stately/table/useTableState';
+import type { TreeGridState } from '../stately/table/useTreeGridState';
+import { useLabels } from '../utils/useLabels';
+import { useLocale } from '../i18n/I18nProvider';
+import { useLocalizedStringFormatter } from '../i18n/useLocalizedStringFormatter';
+import { useSyntheticLinkProps } from '../utils/openLink';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+const EXPANSION_KEYS = {
+	expand: {
+		ltr: 'ArrowRight',
+		rtl: 'ArrowLeft',
+	},
+	collapse: {
+		ltr: 'ArrowLeft',
+		rtl: 'ArrowRight',
+	},
+};
+
+export interface TableRowAria extends GridRowAria {
+	expandButtonProps: AriaButtonProps;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a row in a table.
+ *
+ * @param props - Props for the row.
+ * @param state - State of the table, as returned by `useTableState`.
+ */
+export function useTableRow<T>(
+	props: GridRowProps<T>,
+	state: TableState<T> | TreeGridState<T>,
+	ref: RefObject<FocusableElement | null>,
+): TableRowAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTableRow<T>(
+	props: GridRowProps<T>,
+	state: TableState<T> | TreeGridState<T>,
+	ref: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): TableRowAria;
+export function useTableRow(...args: any[]): TableRowAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTableRow');
+	const props = user[0] as GridRowProps<any>;
+	const state = user[1] as TableState<any> | TreeGridState<any>;
+	const ref = user[2] as RefObject<FocusableElement | null>;
+
+	let { node, isVirtualized } = props;
+	let { rowProps, ...states } = useGridRow<any, ITableCollection<any>, TableState<any>>(
+		props,
+		state as TableState<any>,
+		ref,
+		subSlot(slot, 'gridRow'),
+	);
+	let { direction } = useLocale(subSlot(slot, 'locale'));
+
+	if (isVirtualized && state.treeColumn == null) {
+		rowProps['aria-rowindex'] = node.index + 1 + state.collection.headerRows.length; // aria-rowindex is 1 based
+	} else {
+		delete rowProps['aria-rowindex'];
+	}
+
+	let isExpanded =
+		state.treeColumn != null && (state.expandedKeys === 'all' || state.expandedKeys.has(node.key));
+	let stringFormatter = useLocalizedStringFormatter(
+		intlMessages,
+		'@react-aria/table',
+		subSlot(slot, 'strings'),
+	);
+	let labelProps = useLabels(
+		{
+			'aria-label': isExpanded
+				? stringFormatter.format('collapse')
+				: stringFormatter.format('expand'),
+			'aria-labelledby': getRowLabelledBy(state as TableState<any>, node.key),
+		},
+		undefined,
+		subSlot(slot, 'labels'),
+	);
+
+	let treeGridRowProps: Record<string, any> = {};
+	let expandButtonProps: AriaButtonProps = {};
+	if (state.treeColumn != null) {
+		let treeNode = state.collection.getItem(node.key);
+		if (treeNode != null) {
+			let lastChild = getLastChild(state.collection, node);
+			let hasChildRows =
+				treeNode.props?.hasChildRows ||
+				treeNode.props?.UNSTABLE_childItems ||
+				lastChild?.type !== 'cell';
+			let parent = state.collection.getItem(node.parentKey!)!;
+			let isParentBody = parent.type === 'tablebody' || parent.type === 'body';
+			let lastSibling = getLastChild(state.collection, parent)!;
+			while (lastSibling && lastSibling.type !== 'item' && lastSibling.prevKey != null) {
+				lastSibling = state.collection.getItem(lastSibling.prevKey)!;
+			}
+
+			treeGridRowProps = {
+				onKeyDown: (e: KeyboardEvent) => {
+					if (
+						e.key === EXPANSION_KEYS['expand'][direction] &&
+						state.selectionManager.focusedKey === treeNode.key &&
+						hasChildRows &&
+						state.expandedKeys !== 'all' &&
+						!state.expandedKeys.has(treeNode.key)
+					) {
+						state.toggleKey(treeNode.key);
+						e.stopPropagation();
+					} else if (
+						e.key === EXPANSION_KEYS['collapse'][direction] &&
+						state.selectionManager.focusedKey === treeNode.key
+					) {
+						if (state.expandedKeys !== 'all') {
+							if (hasChildRows && state.expandedKeys.has(treeNode.key)) {
+								state.toggleKey(treeNode.key);
+								e.stopPropagation();
+							} else if (
+								!state.expandedKeys.has(treeNode.key) &&
+								treeNode.parentKey != null &&
+								treeNode.level > 0
+							) {
+								// Item is a leaf or already collapsed, move focus to parent
+								state.selectionManager.setFocusedKey(treeNode.parentKey);
+								e.stopPropagation();
+							}
+						} else if (state.expandedKeys === 'all') {
+							state.toggleKey(treeNode.key);
+							e.stopPropagation();
+						}
+					}
+				},
+				'aria-expanded': hasChildRows
+					? state.expandedKeys === 'all' || state.expandedKeys.has(node.key)
+					: undefined,
+				'aria-level': treeNode.level + 1,
+				'aria-posinset': treeNode.index - (isParentBody ? 0 : state.collection.columnCount) + 1,
+				'aria-setsize': lastSibling.index - (isParentBody ? 0 : state.collection.columnCount) + 1,
+			};
+
+			expandButtonProps = {
+				isDisabled: states.isDisabled,
+				onPress: () => {
+					if (!states.isDisabled) {
+						state.toggleKey(node.key);
+						state.selectionManager.setFocused(true);
+						state.selectionManager.setFocusedKey(node.key);
+					}
+				},
+				excludeFromTabOrder: true,
+				preventFocusOnPress: true,
+				// @ts-ignore
+				'data-react-aria-prevent-focus': true,
+				...labelProps,
+			};
+		}
+	}
+
+	let syntheticLinkProps = useSyntheticLinkProps(node.props);
+	let linkProps = states.hasAction ? syntheticLinkProps : {};
+	return {
+		rowProps: {
+			...mergeProps(rowProps, treeGridRowProps, linkProps),
+			'aria-labelledby': getRowLabelledBy(state as TableState<any>, node.key),
+		},
+		expandButtonProps,
+		...states,
+	};
+}
+
+function getLastChild(collection: Collection<Node<unknown>>, node: Node<unknown>) {
+	if ('lastChildKey' in node) {
+		return (node as any).lastChildKey != null
+			? collection.getItem((node as any).lastChildKey)
+			: null;
+	} else {
+		return Array.from(node.childNodes).findLast((item) => item.parentKey === node.key);
+	}
+}

package/src/table/useTableRowGroup.ts

@@ -0,0 +1,13 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/table/useTableRowGroup.ts).
+// octane adaptations: composes the ported src/grid/useGridRowGroup; the optional trailing
+// slot is forwarded (uniform calling convention).
+import { GridRowGroupAria, useGridRowGroup } from '../grid/useGridRowGroup';
+
+import { restSlot } from '../internal';
+
+export function useTableRowGroup(): GridRowGroupAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTableRowGroup(slot: symbol | undefined): GridRowGroupAria;
+export function useTableRowGroup(...args: any[]): GridRowGroupAria {
+	return useGridRowGroup(restSlot(args));
+}

package/src/table/useTableSelectionCheckbox.ts

@@ -0,0 +1,105 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/table/useTableSelectionCheckbox.ts).
+// octane adaptations:
+// - `TableState` comes from the ported stately table hook; `useGridSelectionCheckbox`
+//   from the ported src/grid/.
+// - The checkbox `onChange` is the value-level AriaCheckboxProps callback (not DOM
+//   wiring), so it ports unchanged — consumers wire it to the native checkbox `change`
+//   event.
+// - The Parcel glob intl import becomes the generated src/intl/table index (verbatim
+//   dictionaries).
+// - Public-hook slot threading (splitSlot/subSlot).
+import type { AriaCheckboxProps } from '../checkbox/useCheckbox';
+import { getRowLabelledBy } from './utils';
+import intlMessages from '../intl/table';
+import type { Key } from '@react-types/shared';
+import type { TableState } from '../stately/table/useTableState';
+import { useGridSelectionCheckbox } from '../grid/useGridSelectionCheckbox';
+import { useLocalizedStringFormatter } from '../i18n/useLocalizedStringFormatter';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export interface AriaTableSelectionCheckboxProps {
+	/** A unique key for the checkbox. */
+	key: Key;
+}
+
+export interface TableSelectionCheckboxAria {
+	/** Props for the row selection checkbox element. */
+	checkboxProps: AriaCheckboxProps;
+}
+
+export interface TableSelectAllCheckboxAria {
+	/** Props for the select all checkbox element. */
+	checkboxProps: AriaCheckboxProps;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a selection checkbox in a table.
+ *
+ * @param props - Props for the selection checkbox.
+ * @param state - State of the table, as returned by `useTableState`.
+ */
+export function useTableSelectionCheckbox<T>(
+	props: AriaTableSelectionCheckboxProps,
+	state: TableState<T>,
+): TableSelectionCheckboxAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTableSelectionCheckbox<T>(
+	props: AriaTableSelectionCheckboxProps,
+	state: TableState<T>,
+	slot: symbol | undefined,
+): TableSelectionCheckboxAria;
+export function useTableSelectionCheckbox(...args: any[]): TableSelectionCheckboxAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTableSelectionCheckbox');
+	const props = user[0] as AriaTableSelectionCheckboxProps;
+	const state = user[1] as TableState<any>;
+
+	let { key } = props;
+	const { checkboxProps } = useGridSelectionCheckbox(props, state, subSlot(slot, 'gridCheckbox'));
+
+	return {
+		checkboxProps: {
+			...checkboxProps,
+			'aria-labelledby': `${checkboxProps.id} ${getRowLabelledBy(state, key)}`,
+		},
+	};
+}
+
+/**
+ * Provides the behavior and accessibility implementation for the select all checkbox in a table.
+ *
+ * @param props - Props for the select all checkbox.
+ * @param state - State of the table, as returned by `useTableState`.
+ */
+export function useTableSelectAllCheckbox<T>(state: TableState<T>): TableSelectAllCheckboxAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTableSelectAllCheckbox<T>(
+	state: TableState<T>,
+	slot: symbol | undefined,
+): TableSelectAllCheckboxAria;
+export function useTableSelectAllCheckbox(...args: any[]): TableSelectAllCheckboxAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTableSelectAllCheckbox');
+	const state = user[0] as TableState<any>;
+
+	let { isEmpty, isSelectAll, selectionMode } = state.selectionManager;
+	const stringFormatter = useLocalizedStringFormatter(
+		intlMessages,
+		'@react-aria/table',
+		subSlot(slot, 'strings'),
+	);
+
+	return {
+		checkboxProps: {
+			'aria-label': stringFormatter.format(selectionMode === 'single' ? 'select' : 'selectAll'),
+			isSelected: isSelectAll,
+			isDisabled:
+				selectionMode !== 'multiple' ||
+				state.collection.size === 0 ||
+				(state.collection.rows.length === 1 && state.collection.rows[0].type === 'loader'),
+			isIndeterminate: !isEmpty && !isSelectAll,
+			onChange: () => state.selectionManager.toggleSelectAll(),
+		},
+	};
+}

package/src/table/utils.ts

@@ -0,0 +1,42 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/table/utils.ts).
+// octane adaptations: `TableState` type comes from the ported stately table hook.
+import type { Key } from '@react-types/shared';
+import type { TableState } from '../stately/table/useTableState';
+
+export const gridIds: WeakMap<TableState<unknown>, string> = new WeakMap<
+	TableState<unknown>,
+	string
+>();
+
+function normalizeKey(key: Key): string {
+	if (typeof key === 'string') {
+		return key.replace(/\s*/g, '');
+	}
+
+	return '' + key;
+}
+
+export function getColumnHeaderId<T>(state: TableState<T>, columnKey: Key): string {
+	let gridId = gridIds.get(state);
+	if (!gridId) {
+		throw new Error('Unknown grid');
+	}
+
+	return `${gridId}-${normalizeKey(columnKey)}`;
+}
+
+export function getCellId<T>(state: TableState<T>, rowKey: Key, columnKey: Key): string {
+	let gridId = gridIds.get(state);
+	if (!gridId) {
+		throw new Error('Unknown grid');
+	}
+
+	return `${gridId}-${normalizeKey(rowKey)}-${normalizeKey(columnKey)}`;
+}
+
+export function getRowLabelledBy<T>(state: TableState<T>, rowKey: Key): string {
+	// A row is labelled by it's row headers.
+	return [...state.collection.rowHeaderColumnKeys]
+		.map((columnKey) => getCellId(state, rowKey, columnKey))
+		.join(' ');
+}

package/src/tree/useTree.ts

@@ -0,0 +1,76 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/tree/useTree.ts).
+// octane adaptations:
+// - `TreeState` comes from the ported stately tree hook; `DOMAttributes` is a local
+//   structural prop-bag alias (upstream's is typed over React's synthetic handlers).
+// - Public-hook slot threading (splitSlot/subSlot).
+import type { KeyboardDelegate, RefObject } from '@react-types/shared';
+import {
+	type AriaGridListOptions,
+	type AriaGridListProps,
+	type GridListProps,
+	useGridList,
+} from '../gridlist/useGridList';
+import type { TreeState } from '../stately/tree/useTreeState';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+// octane adaptation: minimal structural DOMAttributes (upstream's drags React's synthetic
+// handler types along).
+type DOMAttributes = Record<string, any>;
+
+export interface TreeProps<T> extends GridListProps<T> {}
+
+export interface AriaTreeProps<T> extends AriaGridListProps<T> {}
+export interface AriaTreeOptions<T> extends Omit<
+	AriaGridListOptions<T>,
+	'children' | 'shouldFocusWrap'
+> {
+	/**
+	 * An optional keyboard delegate implementation for type to select,
+	 * to override the default.
+	 */
+	keyboardDelegate?: KeyboardDelegate;
+}
+
+export interface TreeAria {
+	/** Props for the treegrid element. */
+	gridProps: DOMAttributes;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a single column treegrid component
+ * with interactive children. A tree grid provides users with a way to navigate nested hierarchical
+ * information.
+ *
+ * @param props - Props for the treegrid.
+ * @param state - State for the treegrid, as returned by `useTreeState`.
+ * @param ref - The ref attached to the treegrid element.
+ */
+export function useTree<T>(
+	props: AriaTreeOptions<T>,
+	state: TreeState<T>,
+	ref: RefObject<HTMLElement | null>,
+): TreeAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTree<T>(
+	props: AriaTreeOptions<T>,
+	state: TreeState<T>,
+	ref: RefObject<HTMLElement | null>,
+	slot: symbol | undefined,
+): TreeAria;
+export function useTree(...args: any[]): TreeAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTree');
+	const props = user[0] as AriaTreeOptions<any>;
+	const state = user[1] as TreeState<any>;
+	const ref = user[2] as RefObject<HTMLElement | null>;
+
+	// TreeState is a structural superset of ListState (collection/disabledKeys/selectionManager),
+	// exactly like upstream's call into useGridList.
+	let { gridProps } = useGridList(props as any, state as any, ref, subSlot(slot, 'gridList'));
+	gridProps.role = 'treegrid';
+
+	return {
+		gridProps,
+	};
+}

package/src/tree/useTreeItem.ts

@@ -0,0 +1,109 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/tree/useTreeItem.ts).
+// octane adaptations:
+// - The Parcel glob intl import becomes the generated src/intl/tree index (verbatim
+//   locale JSONs from the pinned checkout).
+// - `TreeState` comes from the ported stately tree hook; `DOMAttributes` is a local
+//   structural prop-bag alias (upstream's is typed over React's synthetic handlers).
+// - Public-hook slot threading (splitSlot/subSlot).
+import type { FocusableElement, Node, RefObject } from '@react-types/shared';
+import type { AriaButtonProps } from '../button/useButton';
+import {
+	type AriaGridListItemOptions,
+	type GridListItemAria,
+	useGridListItem,
+} from '../gridlist/useGridListItem';
+import { useLocalizedStringFormatter } from '../i18n/useLocalizedStringFormatter';
+import intlMessages from '../intl/tree';
+import type { TreeState } from '../stately/tree/useTreeState';
+import { useLabels } from '../utils/useLabels';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+// octane adaptation: minimal structural DOMAttributes (upstream's drags React's synthetic
+// handler types along).
+type DOMAttributes = Record<string, any>;
+
+export interface AriaTreeItemOptions extends Omit<AriaGridListItemOptions, 'isVirtualized'> {
+	/**
+	 * An object representing the treegrid item. Contains all the relevant information that makes up
+	 * the treegrid row.
+	 */
+	node: Node<unknown>;
+}
+
+export interface TreeItemAria extends GridListItemAria {
+	/** Props for the tree grid row element. */
+	rowProps: DOMAttributes;
+	/** Props for the tree grid cell element within the tree grid list row. */
+	gridCellProps: DOMAttributes;
+	/** Props for the tree grid row description element, if any. */
+	descriptionProps: DOMAttributes;
+	/** Props for the tree grid row expand button. */
+	expandButtonProps: AriaButtonProps;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a row in a tree grid list.
+ *
+ * @param props - Props for the row.
+ * @param state - State of the parent list, as returned by `useTreeState`.
+ * @param ref - The ref attached to the row element.
+ */
+export function useTreeItem<T>(
+	props: AriaTreeItemOptions,
+	state: TreeState<T>,
+	ref: RefObject<FocusableElement | null>,
+): TreeItemAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTreeItem<T>(
+	props: AriaTreeItemOptions,
+	state: TreeState<T>,
+	ref: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): TreeItemAria;
+export function useTreeItem(...args: any[]): TreeItemAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTreeItem');
+	const props = user[0] as AriaTreeItemOptions;
+	const state = user[1] as TreeState<any>;
+	const ref = user[2] as RefObject<FocusableElement | null>;
+
+	let { node } = props;
+	let gridListAria = useGridListItem(props, state, ref, subSlot(slot, 'gridListItem'));
+	let isExpanded = gridListAria.rowProps['aria-expanded'] === true;
+	let stringFormatter = useLocalizedStringFormatter(
+		intlMessages,
+		'@react-aria/tree',
+		subSlot(slot, 'strings'),
+	);
+	let labelProps = useLabels(
+		{
+			'aria-label': isExpanded
+				? stringFormatter.format('collapse')
+				: stringFormatter.format('expand'),
+			'aria-labelledby': gridListAria.rowProps.id,
+		},
+		undefined,
+		subSlot(slot, 'labels'),
+	);
+
+	let expandButtonProps = {
+		onPress: () => {
+			if (!gridListAria.isDisabled) {
+				state.toggleKey(node.key);
+				state.selectionManager.setFocused(true);
+				state.selectionManager.setFocusedKey(node.key);
+			}
+		},
+		excludeFromTabOrder: true,
+		preventFocusOnPress: true,
+		'data-react-aria-prevent-focus': true,
+		...labelProps,
+	};
+
+	// TODO: should it return a state specifically for isExpanded? Or is aria attribute sufficient?
+	return {
+		...gridListAria,
+		expandButtonProps,
+	};
+}

package/src/utils/mergeRefs.ts

@@ -3,10 +3,7 @@
 // (callback ref with optional cleanup, or object ref), passed as ordinary props.
 
 export type MergableRef<T> =
-	| ((value: T | null) => void | (() => void))
-	| { current: T | null }
-	| null
-	| undefined;
+	((value: T | null) => void | (() => void)) | { current: T | null } | null | undefined;
 
 /**
  * Merges multiple refs into one. Works with either callback or object refs.

package/src/utils/useFormReset.ts

@@ -25,8 +25,7 @@ export function useFormReset(...args: any[]): void {
 	const [user, slotArg] = splitSlot(args);
 	const slot = slotArg ?? S('useFormReset');
 	const ref = user[0] as
-		| { current: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | null }
-		| undefined;
+		{ current: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement | null } | undefined;
 	const initialValue = user[1];
 	const onReset = user[2] as (value: any) => void;
 

package/src/utils/useObjectRef.ts

@@ -21,20 +21,14 @@ export function useObjectRef<T>(
 // Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
 export function useObjectRef<T>(
 	ref:
-		| ((instance: T | null) => (() => void) | void)
-		| MutableRefObject<T | null>
-		| null
-		| undefined,
+		((instance: T | null) => (() => void) | void) | MutableRefObject<T | null> | null | undefined,
 	slot: symbol | undefined,
 ): MutableRefObject<T | null>;
 export function useObjectRef(...args: any[]): any {
 	const [user, slotArg] = splitSlot(args);
 	const slot = slotArg ?? S('useObjectRef');
 	const ref = user[0] as
-		| ((instance: any) => (() => void) | void)
-		| MutableRefObject<any>
-		| null
-		| undefined;
+		((instance: any) => (() => void) | void) | MutableRefObject<any> | null | undefined;
 
 	const objRef: MutableRefObject<any> = useRef(null, subSlot(slot, 'obj'));
 	const cleanupRef: MutableRefObject<(() => void) | void> = useRef(