@octanejs/aria 0.0.46 → 0.0.48

package/src/gridlist/{useGridListItem.ts → useGridListItem.tsx}

@@ -1,23 +1,20 @@
-// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/gridlist/useGridListItem.ts).
-// octane adaptations:
-// - Handlers receive NATIVE events (there is no synthetic layer): keydown handlers take
-//   the native KeyboardEvent, `e.nativeEvent` reads collapse to the event itself (the
-//   ArrowUp/ArrowDown re-dispatch builds `new KeyboardEvent(e.type, e)` — WebIDL
-//   dictionary conversion reads the inherited native-event accessors), and upstream's
-//   synthetic `e.isPropagationStopped()` reads the native `cancelBubble` flag (same
-//   source of truth the ported interactions/utils shim uses). `onKeyDownCapture` maps to
-//   the capture phase natively in octane, matching upstream's React capture prop.
-// - `ListState`/`TreeState` come from the ported stately hooks; `HTMLAttributes` /
-//   `DOMAttributes` collapse to a structural prop bag.
-// - Public-hook slot threading (splitSlot/subSlot).
+/** @jsxImportSource octane */
+type DOMAttributes = Record<string, any>;
+// Ported from adobe/react-spectrum@5ecb3333001313e83898cd07644227897e3bae1f (packages/react-aria/src/gridlist/useGridListItem.ts).
+/*
+ * Copyright 2022 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
 import { chain } from '../utils/chain';
-import type {
-	Collection,
-	FocusableElement,
-	Key,
-	RefObject,
-	Node as RSNode,
-} from '@react-types/shared';
+import { Collection, FocusableElement, Key, RefObject, Node as RSNode } from '@react-types/shared';
 import { focusSafely } from '../interactions/focusSafely';
 import {
 	getActiveElement,
@@ -26,26 +23,21 @@ import {
 	nodeContains,
 } from '../utils/shadowdom/DOMFunctions';
 import { getFocusableTreeWalker } from '../focus/FocusScope';
+import { getOwnerDocument } from '../utils/domHelpers';
 import { getRowId, listMap } from './utils';
 import { getScrollParent } from '../utils/getScrollParent';
-import { useRef } from 'octane';
+import { HTMLAttributes, KeyboardEvent as ReactKeyboardEvent, useRef } from '../compat/react';
+import { withSlot } from 'octane';
 import { isFocusVisible } from '../interactions/useFocusVisible';
-import { isTabbable } from '../utils/isFocusable';
-import type { ListState } from '../stately/list/useListState';
+import type { ListState } from '../upstream-exports/react-stately/useListState';
 import { mergeProps } from '../utils/mergeProps';
 import { scrollIntoViewport } from '../utils/scrollIntoView';
 import { SelectableItemStates, useSelectableItem } from '../selection/useSelectableItem';
-import type { TreeState } from '../stately/tree/useTreeState';
+import type { TreeState } from '../upstream-exports/react-stately/useTreeState';
 import { useLocale } from '../i18n/I18nProvider';
 import { useSlotId } from '../utils/useId';
 import { useSyntheticLinkProps } from '../utils/openLink';
 
-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 AriaGridListItemOptions {
 	/**
 	 * An object representing the list item. Contains all the relevant information that makes up the
@@ -58,6 +50,19 @@ export interface AriaGridListItemOptions {
 	shouldSelectOnPressUp?: boolean;
 	/** Whether this item has children, even if not loaded yet. */
 	hasChildItems?: boolean;
+	/**
+	 * Whether the row or its first focusable child element should be focused when the row is
+	 * focused.
+	 *
+	 * @default 'row'
+	 */
+	focusMode?: 'child' | 'row';
+	/**
+	 * Whether the row should support arrow key navigation even when the containing collection uses
+	 * tab keyboard navigation. Allows users to navigate between rows with arrow keys while
+	 * focus is on an interactive child element within the row.
+	 */
+	allowsArrowNavigation?: boolean;
 }
 
 export interface GridListItemAria extends SelectableItemStates {
@@ -91,46 +96,58 @@ export function useGridListItem<T>(
 	props: AriaGridListItemOptions,
 	state: ListState<T> | TreeState<T>,
 	ref: RefObject<FocusableElement | null>,
-): GridListItemAria;
-// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
-export function useGridListItem<T>(
-	props: AriaGridListItemOptions,
-	state: ListState<T> | TreeState<T>,
-	ref: RefObject<FocusableElement | null>,
-	slot: symbol | undefined,
-): GridListItemAria;
-export function useGridListItem(...args: any[]): GridListItemAria {
-	const [user, slotArg] = splitSlot(args);
-	const slot = slotArg ?? S('useGridListItem');
-	const props = user[0] as AriaGridListItemOptions;
-	const state = user[1] as ListState<any> | TreeState<any>;
-	const ref = user[2] as RefObject<FocusableElement | null>;
+	_slot?: symbol,
+): GridListItemAria {
+	if (_slot !== undefined) {
+		return withSlot(_slot, useGridListItem<T>, props, state, ref);
+	}
 
 	// Copied from useGridCell + some modifications to make it not so grid specific
-	let { node, isVirtualized } = props;
+	let { node, isVirtualized, focusMode = 'row', allowsArrowNavigation } = props;
 
 	// let stringFormatter = useLocalizedStringFormatter(intlMessages, '@react-aria/gridlist');
-	let { direction } = useLocale(subSlot(slot, 'locale'));
+	let { direction } = useLocale();
 	let { onAction, linkBehavior, keyboardNavigationBehavior, shouldSelectOnPressUp } =
 		listMap.get(state)!;
-	let descriptionId = useSlotId(undefined, subSlot(slot, 'descriptionId'));
+	let descriptionId = useSlotId();
 
 	// 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'));
+	let keyWhenFocused = useRef<Key | null>(null);
 	let focus = () => {
+		if (ref.current === null) {
+			return;
+		}
+
+		if (focusMode === 'child') {
+			// If focus is already on a focusable child within the row, early return so we don't shift focus
+			if (
+				isFocusWithin(ref.current) &&
+				ref.current !== getActiveElement(getOwnerDocument(ref.current))
+			) {
+				return;
+			}
+
+			let treeWalker = getFocusableTreeWalker(ref.current, { tabbable: true });
+			let focusable = treeWalker.firstChild() as FocusableElement;
+			if (focusable) {
+				focusSafely(focusable);
+				scrollIntoViewport(focusable, { containingElement: getScrollParent(focusable) });
+				return;
+			}
+		}
+
 		// Don't shift focus to the row if the active element is a element within the row already
 		// (e.g. clicking on a row button)
 		if (
-			ref.current !== null &&
-			((keyWhenFocused.current != null && node.key !== keyWhenFocused.current) ||
-				!isFocusWithin(ref.current))
+			(keyWhenFocused.current != null && node.key !== keyWhenFocused.current) ||
+			!isFocusWithin(ref.current)
 		) {
 			focusSafely(ref.current);
 		}
 	};
 
-	let treeGridRowProps: DOMAttributes = {};
+	let treeGridRowProps: HTMLAttributes<HTMLElement> = {};
 	let hasChildRows = props.hasChildItems;
 	let hasLink = state.selectionManager.isLink(node.key);
 	if (node != null && 'expandedKeys' in state) {
@@ -175,27 +192,24 @@ export function useGridListItem(...args: any[]): GridListItemAria {
 		};
 	}
 
-	let { itemProps, ...itemStates } = useSelectableItem(
-		{
-			selectionManager: state.selectionManager,
-			key: node.key,
-			ref,
-			isVirtualized,
-			shouldSelectOnPressUp: props.shouldSelectOnPressUp || shouldSelectOnPressUp,
-			onAction:
-				onAction || node.props?.onAction
-					? chain(node.props?.onAction, onAction ? () => onAction(node.key) : undefined)
-					: undefined,
-			focus,
-			linkBehavior,
-		},
-		subSlot(slot, 'selectableItem'),
-	);
+	let { itemProps, ...itemStates } = useSelectableItem({
+		selectionManager: state.selectionManager,
+		key: node.key,
+		ref,
+		isVirtualized,
+		shouldSelectOnPressUp: props.shouldSelectOnPressUp || shouldSelectOnPressUp,
+		onAction:
+			onAction || node.props?.onAction
+				? chain(node.props?.onAction, onAction ? () => onAction(node.key) : undefined)
+				: undefined,
+		focus,
+		linkBehavior,
+	});
 
-	let onKeyDownCapture = (e: KeyboardEvent) => {
-		let activeElement = getActiveElement();
+	let onKeyDownCapture = (e: ReactKeyboardEvent) => {
+		let activeElement = getActiveElement(getOwnerDocument(ref.current));
 		if (
-			!nodeContains(e.currentTarget as Element, getEventTarget(e) as Element) ||
+			!nodeContains(e.currentTarget as Node, getEventTarget(e) as Element) ||
 			!ref.current ||
 			!activeElement
 		) {
@@ -206,7 +220,16 @@ export function useGridListItem(...args: any[]): GridListItemAria {
 		walker.currentNode = activeElement;
 
 		if (
-			handleTreeExpansionKeys(e, state, node, hasChildRows, direction, activeElement, ref.current)
+			handleTreeExpansionKeys(
+				e,
+				state,
+				node,
+				hasChildRows,
+				direction,
+				activeElement,
+				ref.current,
+				allowsArrowNavigation,
+			)
 		) {
 			return;
 		}
@@ -235,6 +258,7 @@ export function useGridListItem(...args: any[]): GridListItemAria {
 						} else {
 							walker.currentNode = ref.current;
 							let lastElement = last(walker);
+							// oxlint-disable-next-line max-depth
 							if (lastElement) {
 								focusSafely(lastElement);
 								scrollIntoViewport(lastElement, {
@@ -267,6 +291,7 @@ export function useGridListItem(...args: any[]): GridListItemAria {
 						} else {
 							walker.currentNode = ref.current;
 							let lastElement = last(walker);
+							// oxlint-disable-next-line max-depth
 							if (lastElement) {
 								focusSafely(lastElement);
 								scrollIntoViewport(lastElement, {
@@ -286,7 +311,6 @@ export function useGridListItem(...args: any[]): GridListItemAria {
 				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;
@@ -307,12 +331,33 @@ export function useGridListItem(...args: any[]): GridListItemAria {
 			}
 			return;
 		}
+
+		// if focus goes back to cell from child, make sure we don't refocus the cell if we are in focusMode=child
+		// since that would be a focus trap
+		if (
+			focusMode === 'child' &&
+			e.relatedTarget &&
+			nodeContains(ref.current, e.relatedTarget as Element)
+		) {
+			return;
+		}
+
+		// If the cell itself is focused, wait a frame so that focus finishes propagating
+		// up to the tree, and move focus to a focusable child if possible.
+		requestAnimationFrame(() => {
+			if (
+				focusMode === 'child' &&
+				getActiveElement(getOwnerDocument(ref.current)) === ref.current
+			) {
+				focus();
+			}
+		});
 	};
 
-	let onKeyDown = (e: KeyboardEvent) => {
-		let activeElement = getActiveElement();
+	let onKeyDown = (e: ReactKeyboardEvent) => {
+		let activeElement = getActiveElement(getOwnerDocument(ref.current));
 		if (
-			!nodeContains(e.currentTarget as Element, getEventTarget(e) as Element) ||
+			!nodeContains(e.currentTarget as Node, getEventTarget(e) as Element) ||
 			!ref.current ||
 			!activeElement
 		) {
@@ -329,7 +374,16 @@ export function useGridListItem(...args: any[]): GridListItemAria {
 			}
 
 			if (
-				handleTreeExpansionKeys(e, state, node, hasChildRows, direction, activeElement, ref.current)
+				handleTreeExpansionKeys(
+					e,
+					state,
+					node,
+					hasChildRows,
+					direction,
+					activeElement,
+					ref.current,
+					allowsArrowNavigation,
+				)
 			) {
 				return;
 			}
@@ -364,56 +418,41 @@ export function useGridListItem(...args: any[]): GridListItemAria {
 	//   });
 	// }
 
+	// oxlint-disable-next-line react/react-compiler
 	let rowProps: DOMAttributes = mergeProps(itemProps, linkProps, {
 		role: 'row',
-		onKeyDownCapture: keyboardNavigationBehavior === 'arrow' ? onKeyDownCapture : undefined,
+		onKeyDownCapture:
+			keyboardNavigationBehavior === 'arrow' || allowsArrowNavigation
+				? onKeyDownCapture
+				: undefined,
 		onFocus,
 		// 'aria-label': [(node.textValue || undefined), rowAnnouncement].filter(Boolean).join(', '),
-		'aria-label': (node as any)['aria-label'] || node.textValue || undefined,
+		'aria-label': node['aria-label'] || node.textValue || undefined,
 		'aria-selected': state.selectionManager.canSelectItem(node.key)
 			? state.selectionManager.isSelected(node.key)
 			: undefined,
 		'aria-disabled': state.selectionManager.isDisabled(node.key) || undefined,
 		'aria-labelledby':
-			descriptionId && ((node as any)['aria-label'] || node.textValue)
+			descriptionId && (node['aria-label'] || node.textValue)
 				? `${getRowId(state, node.key)} ${descriptionId}`
 				: undefined,
 		id: getRowId(state, node.key),
 	});
 
-	// we need to guard against space/enter triggering selection/row link via usePress (from itemProps) so check if propagation
-	// is stopped. this also fixes space not working in a textfield in a tree parent row
+	if (focusMode === 'child' && allowsArrowNavigation && keyboardNavigationBehavior === 'tab') {
+		rowProps.tabIndex = -1;
+	}
+
+	// Keep Space/Enter on a child control from reaching the row's usePress handler. With native
+	// events, stopPropagation() marks cancelBubble rather than exposing isPropagationStopped().
 	let baseOnKeyDown = rowProps.onKeyDown;
-	rowProps.onKeyDown = (e: KeyboardEvent) => {
-		onKeyDown(e);
-		// octane adaptation: synthetic isPropagationStopped() → the native cancelBubble flag.
-		if (!(e as any).cancelBubble) {
+	rowProps.onKeyDown = (e: ReactKeyboardEvent<FocusableElement>) => {
+		onKeyDown(e as ReactKeyboardEvent);
+		if (!e.cancelBubble) {
 			baseOnKeyDown?.(e);
 		}
 	};
 
-	// guard against presses triggering row selecition when they happen on elements within the row
-	// am currently assuming if it is tabbable it is interactive, but maybe can use a different kind of check
-	let baseOnPointerDown = rowProps.onPointerDown;
-	rowProps.onPointerDown = (e: PointerEvent) => {
-		let target = getEventTarget(e) as Element | null;
-		if (target && target !== ref.current && isTabbable(target)) {
-			e.stopPropagation();
-			return;
-		}
-		baseOnPointerDown?.(e);
-	};
-
-	let baseOnMouseDown = rowProps.onMouseDown;
-	rowProps.onMouseDown = (e: MouseEvent) => {
-		let target = getEventTarget(e) as Element | null;
-		if (target && target !== ref.current && isTabbable(target)) {
-			e.stopPropagation();
-			return;
-		}
-		baseOnMouseDown?.(e);
-	};
-
 	if (isVirtualized) {
 		let { collection } = state;
 		let nodes = [...collection];
@@ -431,6 +470,7 @@ export function useGridListItem(...args: any[]): GridListItemAria {
 	};
 
 	// TODO: should isExpanded and hasChildRows be a item state that gets returned by the hook?
+	// oxlint-disable react/react-compiler
 	return {
 		rowProps: { ...mergeProps(rowProps, treeGridRowProps) },
 		gridCellProps,
@@ -439,22 +479,24 @@ export function useGridListItem(...args: any[]): GridListItemAria {
 		},
 		...itemStates,
 	};
+	// oxlint-enable react/react-compiler
 }
 
 function handleTreeExpansionKeys<T>(
-	e: KeyboardEvent,
+	e: ReactKeyboardEvent,
 	state: ListState<T> | TreeState<T>,
 	node: RSNode<unknown>,
 	hasChildRows: boolean | undefined,
-	direction: string,
+	direction: 'ltr' | 'rtl',
 	activeElement: Element | null,
 	rowRef: FocusableElement | null,
+	allowsArrowNavigation: boolean | undefined,
 ): boolean {
-	if (!('expandedKeys' in state) || activeElement !== rowRef) {
+	if (!('expandedKeys' in state) || (!allowsArrowNavigation && activeElement !== rowRef)) {
 		return false;
 	}
 	if (
-		e.key === (EXPANSION_KEYS['expand'] as Record<string, string>)[direction] &&
+		e.key === EXPANSION_KEYS['expand'][direction] &&
 		state.selectionManager.focusedKey === node.key &&
 		hasChildRows &&
 		!state.expandedKeys.has(node.key)
@@ -463,7 +505,7 @@ function handleTreeExpansionKeys<T>(
 		e.stopPropagation();
 		return true;
 	} else if (
-		e.key === (EXPANSION_KEYS['collapse'] as Record<string, string>)[direction] &&
+		e.key === EXPANSION_KEYS['collapse'][direction] &&
 		state.selectionManager.focusedKey === node.key
 	) {
 		// If item is collapsible, collapse it; else move to parent

package/src/index.ts

@@ -359,3 +359,25 @@ export type {
 } from './table/useTableColumnResize';
 export type { GridAria, GridProps } from './grid/useGrid';
 export type { GridRowAria, GridRowProps } from './grid/useGridRow';
+
+export { useContextMenu } from './interactions/useContextMenu';
+export type {
+	ContextMenuProps,
+	ContextMenuAria,
+	ContextMenuEvent,
+} from './interactions/useContextMenu';
+export type { KeyboardShortcutBindings } from './interactions/createKeyboardShortcutHandler';
+export { usePreviewTrigger } from './tooltip/usePreviewTrigger';
+export type {
+	AriaPreviewTriggerProps,
+	PreviewTriggerTriggerAria,
+} from './tooltip/usePreviewTrigger';
+export {
+	useTokenField,
+	tokenFieldPositionToDOMRange,
+	setTokenFieldSelection,
+	getSelection,
+} from './tokenfield/useTokenField';
+export type { AriaTokenFieldProps, TokenFieldAria } from './tokenfield/useTokenField';
+export { useToken } from './tokenfield/useToken';
+export type { TokenProps, TokenAria } from './tokenfield/useToken';

package/src/interactions/createEventHandler.ts

@@ -20,6 +20,8 @@ export type BaseEvent<T extends Event> = T & {
 	 */
 	stopPropagation(): void;
 	continuePropagation(): void;
+	isDefaultPrevented(): boolean;
+	isPropagationStopped(): boolean;
 };
 
 const hasOwn = Object.prototype.hasOwnProperty;
@@ -35,14 +37,8 @@ export function createEventHandler<T extends Event>(
 		return undefined;
 	}
 
-	// NB: the flag deliberately lives on the WRAPPER closure, not per dispatch — after a
-	// handler calls continuePropagation(), a later event on the same wrapper instance does
-	// not re-arm stop-by-default. That is upstream's exact (and admittedly surprising)
-	// contract at the pinned version; the differential KeyLatch fixture pins octane to
-	// React's observable behavior across consecutive dispatches, so an upstream semantics
-	// change will surface at the next pin bump rather than silently diverging here.
-	let shouldStopPropagation = true;
 	return (e: T) => {
+		let shouldStopPropagation = true;
 		const overrides: Record<PropertyKey, any> = {
 			preventDefault() {
 				e.preventDefault();
@@ -87,7 +83,14 @@ export function createEventHandler<T extends Event>(
 
 		handler(event);
 
-		if (shouldStopPropagation) {
+		if (
+			shouldStopPropagation &&
+			!(
+				'isPropagationStopped' in e &&
+				typeof e.isPropagationStopped === 'function' &&
+				e.isPropagationStopped()
+			)
+		) {
 			e.stopPropagation();
 		}
 	};