@octanejs/aria 0.0.5 → 0.0.7

package/src/grid/useGrid.ts

@@ -0,0 +1,263 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/grid/useGrid.ts).
+// octane adaptations:
+// - Handlers receive NATIVE events: React's `FocusEventHandler` becomes a native
+//   FocusEvent handler and `e.currentTarget` casts to Element for the shadow-DOM
+//   helpers (octane's delegated dispatch guarantees the per-handler currentTarget).
+// - `GridState`/`IGridCollection` come from the ported stately grid hooks;
+//   `DOMAttributes` is a local structural prop-bag alias (upstream's is typed over
+//   React's synthetic handlers).
+// - Public-hook slot threading (splitSlot/subSlot); explicit dependency arrays are kept
+//   verbatim.
+import type {
+	AriaLabelingProps,
+	DOMProps,
+	Key,
+	KeyboardDelegate,
+	RefObject,
+} from '@react-types/shared';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { useCallback, useMemo } from 'octane';
+import { getEventTarget, nodeContains } from '../utils/shadowdom/DOMFunctions';
+import type { IGridCollection as GridCollection } from '../stately/grid/GridCollection';
+import { GridKeyboardDelegate } from './GridKeyboardDelegate';
+import { gridMap } from './utils';
+import type { GridState } from '../stately/grid/useGridState';
+import { mergeProps } from '../utils/mergeProps';
+import { useCollator } from '../i18n/useCollator';
+import { useGridSelectionAnnouncement } from './useGridSelectionAnnouncement';
+import { useHasTabbableChild } from '../focus/useHasTabbableChild';
+import { useHighlightSelectionDescription } from './useHighlightSelectionDescription';
+import { useId } from '../utils/useId';
+import { useLocale } from '../i18n/I18nProvider';
+import { useSelectableCollection } from '../selection/useSelectableCollection';
+
+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 GridProps extends DOMProps, AriaLabelingProps {
+	/** Whether the grid uses virtual scrolling. */
+	isVirtualized?: boolean;
+	/**
+	 * Whether typeahead navigation is disabled.
+	 *
+	 * @default false
+	 */
+	disallowTypeAhead?: boolean;
+	/**
+	 * An optional keyboard delegate implementation for type to select,
+	 * to override the default.
+	 */
+	keyboardDelegate?: KeyboardDelegate;
+	/**
+	 * Whether initial grid focus should be placed on the grid row or grid cell.
+	 *
+	 * @default 'row'
+	 */
+	focusMode?: 'row' | 'cell';
+	/**
+	 * A function that returns the text that should be announced by assistive technology when a row is
+	 * added or removed from selection.
+	 *
+	 * @default (key) => state.collection.getItem(key)?.textValue
+	 */
+	getRowText?: (key: Key) => string;
+	/**
+	 * The ref attached to the scrollable body. Used to provided automatic scrolling on item focus for
+	 * non-virtualized grids.
+	 */
+	scrollRef?: RefObject<HTMLElement | null>;
+	/** Handler that is called when a user performs an action on the row. */
+	onRowAction?: (key: Key) => void;
+	/** Handler that is called when a user performs an action on the cell. */
+	onCellAction?: (key: Key) => void;
+	/**
+	 * Whether pressing the escape key should clear selection in the grid 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;
+}
+
+export interface GridAria {
+	/** Props for the grid element. */
+	gridProps: DOMAttributes;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a grid component. A grid displays data
+ * in one or more rows and columns and enables a user to navigate its contents via directional
+ * navigation keys.
+ *
+ * @param props - Props for the grid.
+ * @param state - State for the grid, as returned by `useGridState`.
+ * @param ref - The ref attached to the grid element.
+ */
+export function useGrid<T>(
+	props: GridProps,
+	state: GridState<T, GridCollection<T>>,
+	ref: RefObject<HTMLElement | null>,
+): GridAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useGrid<T>(
+	props: GridProps,
+	state: GridState<T, GridCollection<T>>,
+	ref: RefObject<HTMLElement | null>,
+	slot: symbol | undefined,
+): GridAria;
+export function useGrid(...args: any[]): GridAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useGrid');
+	const props = user[0] as GridProps;
+	const state = user[1] as GridState<any, GridCollection<any>>;
+	const ref = user[2] as RefObject<HTMLElement | null>;
+
+	let {
+		isVirtualized,
+		disallowTypeAhead,
+		keyboardDelegate,
+		focusMode,
+		scrollRef,
+		getRowText,
+		onRowAction,
+		onCellAction,
+		escapeKeyBehavior = 'clearSelection',
+		shouldSelectOnPressUp,
+	} = props;
+	let { selectionManager: manager } = state;
+
+	if (!props['aria-label'] && !props['aria-labelledby']) {
+		console.warn('An aria-label or aria-labelledby prop is required for accessibility.');
+	}
+
+	// By default, a KeyboardDelegate is provided which uses the DOM to query layout information (e.g. for page up/page down).
+	// When virtualized, the layout object will be passed in as a prop and override this.
+	let collator = useCollator({ usage: 'search', sensitivity: 'base' }, subSlot(slot, 'collator'));
+	let { direction } = useLocale(subSlot(slot, 'locale'));
+	let disabledBehavior = state.selectionManager.disabledBehavior;
+	let delegate = useMemo(
+		() =>
+			keyboardDelegate ||
+			new GridKeyboardDelegate({
+				collection: state.collection,
+				disabledKeys: state.disabledKeys,
+				disabledBehavior,
+				ref,
+				direction,
+				collator,
+				focusMode,
+			}),
+		[
+			keyboardDelegate,
+			state.collection,
+			state.disabledKeys,
+			disabledBehavior,
+			ref,
+			direction,
+			collator,
+			focusMode,
+		],
+		subSlot(slot, 'delegate'),
+	);
+
+	let { collectionProps } = useSelectableCollection(
+		{
+			ref,
+			selectionManager: manager,
+			keyboardDelegate: delegate,
+			isVirtualized,
+			scrollRef,
+			disallowTypeAhead,
+			escapeKeyBehavior,
+		},
+		subSlot(slot, 'selectableCollection'),
+	);
+
+	let id = useId(props.id, subSlot(slot, 'id'));
+	gridMap.set(state, {
+		keyboardDelegate: delegate,
+		actions: { onRowAction, onCellAction },
+		shouldSelectOnPressUp,
+	});
+
+	let descriptionProps = useHighlightSelectionDescription(
+		{
+			selectionManager: manager,
+			hasItemActions: !!(onRowAction || onCellAction),
+		},
+		subSlot(slot, 'highlightDescription'),
+	);
+
+	let domProps = filterDOMProps(props, { labelable: true });
+
+	let onFocus = useCallback(
+		(e: FocusEvent) => {
+			if (manager.isFocused) {
+				// If a focus event bubbled through a portal, reset focus state.
+				if (!nodeContains(e.currentTarget as Element, getEventTarget(e) as Element)) {
+					manager.setFocused(false);
+				}
+
+				return;
+			}
+
+			// Focus events can bubble through portals. Ignore these events.
+			if (!nodeContains(e.currentTarget as Element, getEventTarget(e) as Element)) {
+				return;
+			}
+
+			manager.setFocused(true);
+		},
+		[manager],
+		subSlot(slot, 'onFocus'),
+	);
+
+	// Continue to track collection focused state even if keyboard navigation is disabled
+	let navDisabledHandlers = useMemo(
+		() => ({
+			onBlur: collectionProps.onBlur,
+			onFocus,
+		}),
+		[onFocus, collectionProps.onBlur],
+		subSlot(slot, 'navDisabled'),
+	);
+
+	let hasTabbableChild = useHasTabbableChild(
+		ref,
+		{
+			isDisabled: state.collection.size !== 0,
+		},
+		subSlot(slot, 'hasTabbableChild'),
+	);
+
+	let gridProps: DOMAttributes = mergeProps(
+		domProps,
+		{
+			role: 'grid',
+			id,
+			'aria-multiselectable': manager.selectionMode === 'multiple' ? 'true' : undefined,
+		},
+		state.isKeyboardNavigationDisabled ? navDisabledHandlers : collectionProps,
+		// If collection is empty, make sure the grid is tabbable unless there is a child tabbable element.
+		(state.collection.size === 0 && { tabIndex: hasTabbableChild ? -1 : 0 }) || undefined,
+		descriptionProps,
+	);
+
+	if (isVirtualized) {
+		gridProps['aria-rowcount'] = state.collection.size;
+		gridProps['aria-colcount'] = state.collection.columnCount;
+	}
+
+	useGridSelectionAnnouncement({ getRowText }, state, subSlot(slot, 'selectionAnnouncement'));
+	return {
+		gridProps,
+	};
+}

package/src/grid/useGridCell.ts

@@ -0,0 +1,346 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/grid/useGridCell.ts).
+// octane adaptations:
+// - Handlers receive NATIVE events (there is no synthetic layer): keydown handlers take
+//   the native KeyboardEvent, and the ArrowUp/ArrowDown/edge re-dispatch builds
+//   `new KeyboardEvent(e.type, e)` — upstream's `e.nativeEvent` IS the event here.
+//   `onKeyDownCapture` maps to the capture phase natively in octane, matching
+//   upstream's React capture prop.
+// - `GridState`/`IGridCollection`/`GridNode` come from the ported stately grid hooks;
+//   `DOMAttributes` is a local structural prop-bag alias.
+// - Public-hook slot threading (splitSlot/subSlot).
+import type { FocusableElement, Key, RefObject } from '@react-types/shared';
+import { focusSafely } from '../interactions/focusSafely';
+import {
+	getActiveElement,
+	getEventTarget,
+	isFocusWithin,
+	nodeContains,
+} from '../utils/shadowdom/DOMFunctions';
+import { getFocusableTreeWalker } from '../focus/FocusScope';
+import { getScrollParent } from '../utils/getScrollParent';
+import type { IGridCollection as GridCollection, GridNode } from '../stately/grid/GridCollection';
+import { gridMap } from './utils';
+import type { GridState } from '../stately/grid/useGridState';
+import { isFocusVisible } from '../interactions/useFocusVisible';
+import { mergeProps } from '../utils/mergeProps';
+import { useRef } from 'octane';
+import { scrollIntoViewport } from '../utils/scrollIntoView';
+import { useLocale } from '../i18n/I18nProvider';
+import { useSelectableItem } from '../selection/useSelectableItem';
+
+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 GridCellProps {
+	/**
+	 * An object representing the grid cell. Contains all the relevant information that makes up the
+	 * grid cell.
+	 */
+	node: GridNode<unknown>;
+	/** Whether the grid cell is contained in a virtual scroller. */
+	isVirtualized?: boolean;
+	/**
+	 * Whether the cell or its first focusable child element should be focused when the grid cell is
+	 * focused.
+	 */
+	focusMode?: 'child' | 'cell';
+	/** Whether selection should occur on press up instead of press down. */
+	shouldSelectOnPressUp?: boolean;
+	/** Indicates how many columns the data cell spans. */
+	colSpan?: number;
+	/**
+	 * Handler that is called when a user performs an action on the cell.
+	 * Please use onCellAction at the collection level instead.
+	 *
+	 * @deprecated
+	 */
+	onAction?: () => void;
+}
+
+export interface GridCellAria {
+	/** Props for the grid cell element. */
+	gridCellProps: DOMAttributes;
+	/** Whether the cell is currently in a pressed state. */
+	isPressed: boolean;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a cell in a grid.
+ *
+ * @param props - Props for the cell.
+ * @param state - State of the parent grid, as returned by `useGridState`.
+ */
+export function useGridCell<T, C extends GridCollection<T>>(
+	props: GridCellProps,
+	state: GridState<T, C>,
+	ref: RefObject<FocusableElement | null>,
+): GridCellAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useGridCell<T, C extends GridCollection<T>>(
+	props: GridCellProps,
+	state: GridState<T, C>,
+	ref: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): GridCellAria;
+export function useGridCell(...args: any[]): GridCellAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useGridCell');
+	const props = user[0] as GridCellProps;
+	const state = user[1] as GridState<any, GridCollection<any>>;
+	const ref = user[2] as RefObject<FocusableElement | null>;
+
+	let { node, isVirtualized, focusMode = 'child', shouldSelectOnPressUp, onAction } = props;
+
+	let { direction } = useLocale(subSlot(slot, 'locale'));
+	let {
+		keyboardDelegate,
+		actions: { onCellAction },
+	} = gridMap.get(state)!;
+
+	// We need to track the key of the item at the time it was last focused so that we force
+	// focus to go to the item when the DOM node is reused for a different item in a virtualizer.
+	let keyWhenFocused = useRef<Key | null>(null, subSlot(slot, 'keyWhenFocused'));
+
+	// Handles focusing the cell. If there is a focusable child,
+	// it is focused, otherwise the cell itself is focused.
+	let focus = () => {
+		if (ref.current) {
+			let treeWalker = getFocusableTreeWalker(ref.current);
+			if (focusMode === 'child') {
+				// If focus is already on a focusable child within the cell, early return so we don't shift focus
+				if (isFocusWithin(ref.current) && ref.current !== getActiveElement()) {
+					return;
+				}
+
+				let focusable =
+					state.selectionManager.childFocusStrategy === 'last'
+						? last(treeWalker)
+						: (treeWalker.firstChild() as FocusableElement);
+				if (focusable) {
+					focusSafely(focusable);
+					return;
+				}
+			}
+
+			if (
+				(keyWhenFocused.current != null && node.key !== keyWhenFocused.current) ||
+				!isFocusWithin(ref.current)
+			) {
+				focusSafely(ref.current);
+			}
+		}
+	};
+
+	let { itemProps, isPressed } = useSelectableItem(
+		{
+			selectionManager: state.selectionManager,
+			key: node.key,
+			ref,
+			isVirtualized,
+			focus,
+			shouldSelectOnPressUp,
+			onAction: onCellAction ? () => onCellAction(node.key) : onAction,
+			isDisabled: state.collection.size === 0,
+		},
+		subSlot(slot, 'selectableItem'),
+	);
+
+	let onKeyDownCapture = (e: KeyboardEvent) => {
+		let activeElement = getActiveElement();
+		if (
+			!nodeContains(e.currentTarget as Element, getEventTarget(e) as Element) ||
+			state.isKeyboardNavigationDisabled ||
+			!ref.current ||
+			!activeElement
+		) {
+			return;
+		}
+
+		let walker = getFocusableTreeWalker(ref.current);
+		walker.currentNode = activeElement;
+
+		switch (e.key) {
+			case 'ArrowLeft': {
+				// Find the next focusable element within the cell.
+				let focusable: FocusableElement | null =
+					direction === 'rtl'
+						? (walker.nextNode() as FocusableElement)
+						: (walker.previousNode() as FocusableElement);
+
+				// Don't focus the cell itself if focusMode is "child"
+				if (focusMode === 'child' && focusable === ref.current) {
+					focusable = null;
+				}
+
+				e.preventDefault();
+				e.stopPropagation();
+				if (focusable) {
+					focusSafely(focusable);
+					scrollIntoViewport(focusable, { containingElement: getScrollParent(ref.current) });
+				} else {
+					// If there is no next focusable child, then move to the next cell to the left of this one.
+					// This will be handled by useSelectableCollection. However, if there is no cell to the left
+					// of this one, only one column, and the grid doesn't focus rows, then the next key will be the
+					// same as this one. In that case we need to handle focusing either the cell or the first/last
+					// child, depending on the focus mode.
+					let prev = keyboardDelegate.getKeyLeftOf?.(node.key);
+					if (prev !== node.key) {
+						// We prevent the capturing event from reaching children of the cell, e.g. pickers.
+						// We want arrow keys to navigate to the next cell instead. We need to re-dispatch
+						// the event from a higher parent so it still bubbles and gets handled by useSelectableCollection.
+						// octane adaptation: the native event IS `e.nativeEvent`.
+						ref.current.parentElement?.dispatchEvent(new KeyboardEvent(e.type, e));
+						break;
+					}
+
+					if (focusMode === 'cell' && direction === 'rtl') {
+						focusSafely(ref.current);
+						scrollIntoViewport(ref.current, { containingElement: getScrollParent(ref.current) });
+					} else {
+						walker.currentNode = ref.current;
+						focusable =
+							direction === 'rtl' ? (walker.firstChild() as FocusableElement) : last(walker);
+						if (focusable) {
+							focusSafely(focusable);
+							scrollIntoViewport(focusable, { containingElement: getScrollParent(ref.current) });
+						}
+					}
+				}
+				break;
+			}
+			case 'ArrowRight': {
+				let focusable: FocusableElement | null =
+					direction === 'rtl'
+						? (walker.previousNode() as FocusableElement)
+						: (walker.nextNode() as FocusableElement);
+
+				if (focusMode === 'child' && focusable === ref.current) {
+					focusable = null;
+				}
+
+				e.preventDefault();
+				e.stopPropagation();
+				if (focusable) {
+					focusSafely(focusable);
+					scrollIntoViewport(focusable, { containingElement: getScrollParent(ref.current) });
+				} else {
+					let next = keyboardDelegate.getKeyRightOf?.(node.key);
+					if (next !== node.key) {
+						// We prevent the capturing event from reaching children of the cell, e.g. pickers.
+						// We want arrow keys to navigate to the next cell instead. We need to re-dispatch
+						// the event from a higher parent so it still bubbles and gets handled by useSelectableCollection.
+						// octane adaptation: the native event IS `e.nativeEvent`.
+						ref.current.parentElement?.dispatchEvent(new KeyboardEvent(e.type, e));
+						break;
+					}
+
+					if (focusMode === 'cell' && direction === 'ltr') {
+						focusSafely(ref.current);
+						scrollIntoViewport(ref.current, { containingElement: getScrollParent(ref.current) });
+					} else {
+						walker.currentNode = ref.current;
+						focusable =
+							direction === 'rtl' ? last(walker) : (walker.firstChild() as FocusableElement);
+						if (focusable) {
+							focusSafely(focusable);
+							scrollIntoViewport(focusable, { containingElement: getScrollParent(ref.current) });
+						}
+					}
+				}
+				break;
+			}
+			case 'ArrowUp':
+			case 'ArrowDown':
+				// Prevent this event from reaching cell children, e.g. menu buttons. We want arrow keys to navigate
+				// to the cell above/below instead. We need to re-dispatch the event from a higher parent so it still
+				// bubbles and gets handled by useSelectableCollection.
+				if (!e.altKey && nodeContains(ref.current, getEventTarget(e) as Element)) {
+					e.stopPropagation();
+					e.preventDefault();
+					// octane adaptation: the native event IS `e.nativeEvent`.
+					ref.current.parentElement?.dispatchEvent(new KeyboardEvent(e.type, e));
+				}
+				break;
+		}
+	};
+
+	// Grid cells can have focusable elements inside them. In this case, focus should
+	// be marshalled to that element rather than focusing the cell itself.
+	let onFocus = (e: FocusEvent) => {
+		keyWhenFocused.current = node.key;
+		if (getEventTarget(e) !== ref.current) {
+			// useSelectableItem only handles setting the focused key when
+			// the focused element is the gridcell itself. We also want to
+			// set the focused key when a child element receives focus.
+			// If focus is currently visible (e.g. the user is navigating with the keyboard),
+			// then skip this. We want to restore focus to the previously focused row/cell
+			// in that case since the table should act like a single tab stop.
+			if (!isFocusVisible()) {
+				state.selectionManager.setFocusedKey(node.key);
+			}
+			return;
+		}
+
+		// If the cell itself is focused, wait a frame so that focus finishes propagatating
+		// up to the tree, and move focus to a focusable child if possible.
+		requestAnimationFrame(() => {
+			if (focusMode === 'child' && getActiveElement() === ref.current) {
+				focus();
+			}
+		});
+	};
+
+	let gridCellProps: DOMAttributes = mergeProps(itemProps, {
+		role: 'gridcell',
+		onKeyDownCapture,
+		'aria-colspan': node.colSpan,
+		'aria-colindex': node.colIndex != null ? node.colIndex + 1 : undefined, // aria-colindex is 1-based
+		colSpan: isVirtualized ? undefined : node.colSpan,
+		onFocus,
+	});
+
+	if (isVirtualized) {
+		gridCellProps['aria-colindex'] = (node.colIndex ?? node.index) + 1; // aria-colindex is 1-based
+	}
+
+	// When pressing with a pointer and cell selection is not enabled, usePress will be applied to the
+	// row rather than the cell. However, when the row is draggable, usePress cannot preventDefault
+	// on pointer down, so the browser will try to focus the cell which has a tabIndex applied.
+	// To avoid this, remove the tabIndex from the cell briefly on pointer down.
+	if (
+		shouldSelectOnPressUp &&
+		gridCellProps.tabIndex != null &&
+		gridCellProps.onPointerDown == null
+	) {
+		gridCellProps.onPointerDown = (e: PointerEvent) => {
+			let el = e.currentTarget as Element;
+			let tabindex = el.getAttribute('tabindex');
+			el.removeAttribute('tabindex');
+			requestAnimationFrame(() => {
+				if (tabindex != null) {
+					el.setAttribute('tabindex', tabindex);
+				}
+			});
+		};
+	}
+
+	return {
+		gridCellProps,
+		isPressed,
+	};
+}
+
+function last(walker: TreeWalker) {
+	let next: FocusableElement | null = null;
+	let last: FocusableElement | null = null;
+	do {
+		last = walker.lastChild() as FocusableElement | null;
+		if (last) {
+			next = last;
+		}
+	} while (last);
+	return next;
+}