@octanejs/aria 0.0.1 → 0.0.3

package/src/selection/useSelectableItem.ts

@@ -0,0 +1,499 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/selection/useSelectableItem.ts).
+// octane adaptations:
+// - Handlers receive NATIVE events (there is no synthetic layer): the onFocus/onMouseDown/
+//   onDoubleClick/onDragStartCapture/onClick props take native FocusEvent/MouseEvent
+//   (octane maps onDoubleClick to the native dblclick event and the Capture suffix to the
+//   capture phase, so the upstream prop names port unchanged).
+// - `DOMAttributes` is a local structural prop-bag alias (upstream's is typed over React's
+//   synthetic handlers).
+// - MultipleSelectionManager type from the ported stately selection types.
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention; explicit
+//   dependency arrays are kept verbatim.
+import { chain } from '../utils/chain';
+
+import type {
+	DOMProps,
+	FocusableElement,
+	Key,
+	LongPressEvent,
+	PointerType,
+	PressEvent,
+	RefObject,
+} from '@react-types/shared';
+import { focusSafely } from '../interactions/focusSafely';
+import { getActiveElement, getEventTarget } from '../utils/shadowdom/DOMFunctions';
+import { getCollectionId, isNonContiguousSelectionModifier } from './utils';
+import { isCtrlKeyPressed } from '../utils/keyboard';
+import { mergeProps } from '../utils/mergeProps';
+import { moveVirtualFocus } from '../focus/virtualFocus';
+import type { MultipleSelectionManager } from '../stately/selection/types';
+import { openLink, useRouter } from '../utils/openLink';
+import { type PressHookProps, usePress } from '../interactions/usePress';
+import { useEffect, useRef } from 'octane';
+import { useId } from '../utils/useId';
+import { useLongPress } from '../interactions/useLongPress';
+
+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 SelectableItemOptions extends DOMProps {
+	/**
+	 * An interface for reading and updating multiple selection state.
+	 */
+	selectionManager: MultipleSelectionManager;
+	/**
+	 * A unique key for the item.
+	 */
+	key: Key;
+	/**
+	 * Ref to the item.
+	 */
+	ref: RefObject<FocusableElement | null>;
+	/**
+	 * By default, selection occurs on pointer down. This can be strange if selecting an
+	 * item causes the UI to disappear immediately (e.g. menus).
+	 */
+	shouldSelectOnPressUp?: boolean;
+	/**
+	 * Whether selection requires the pointer/mouse down and up events to occur on the same target or
+	 * triggers selection on the target of the pointer/mouse up event.
+	 */
+	allowsDifferentPressOrigin?: boolean;
+	/**
+	 * Whether the option is contained in a virtual scroller.
+	 */
+	isVirtualized?: boolean;
+	/**
+	 * Function to focus the item.
+	 */
+	focus?: () => void;
+	/**
+	 * Whether the option should use virtual focus instead of being focused directly.
+	 */
+	shouldUseVirtualFocus?: boolean;
+	/** Whether the item is disabled. */
+	isDisabled?: boolean;
+	/**
+	 * Handler that is called when a user performs an action on the item. The exact user event depends
+	 * on the collection's `selectionBehavior` prop and the interaction modality.
+	 */
+	onAction?: () => void;
+	/**
+	 * The behavior of links in the collection.
+	 * - 'action': link behaves like onAction.
+	 * - 'selection': link follows selection interactions (e.g. if URL drives selection).
+	 * - 'override': links override all other interactions (link items are not selectable).
+	 * - 'none': links are disabled for both selection and actions (e.g. handled elsewhere).
+	 *
+	 * @default 'action'
+	 */
+	linkBehavior?: 'action' | 'selection' | 'override' | 'none';
+}
+
+export interface SelectableItemStates {
+	/** Whether the item is currently in a pressed state. */
+	isPressed: boolean;
+	/** Whether the item is currently selected. */
+	isSelected: boolean;
+	/** Whether the item is currently focused. */
+	isFocused: boolean;
+	/**
+	 * Whether the item is non-interactive, i.e. both selection and actions are disabled and the item
+	 * may not be focused. Dependent on `disabledKeys` and `disabledBehavior`.
+	 */
+	isDisabled: boolean;
+	/**
+	 * Whether the item may be selected, dependent on `selectionMode`, `disabledKeys`, and
+	 * `disabledBehavior`.
+	 */
+	allowsSelection: boolean;
+	/**
+	 * Whether the item has an action, dependent on `onAction`, `disabledKeys`,
+	 * and `disabledBehavior`. It may also change depending on the current selection state
+	 * of the list (e.g. when selection is primary). This can be used to enable or disable hover
+	 * styles or other visual indications of interactivity.
+	 */
+	hasAction: boolean;
+}
+
+export interface SelectableItemAria extends SelectableItemStates {
+	/**
+	 * Props to be spread on the item root node.
+	 */
+	itemProps: DOMAttributes;
+}
+
+/**
+ * Handles interactions with an item in a selectable collection.
+ */
+export function useSelectableItem(options: SelectableItemOptions): SelectableItemAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSelectableItem(
+	options: SelectableItemOptions,
+	slot: symbol | undefined,
+): SelectableItemAria;
+export function useSelectableItem(...args: any[]): SelectableItemAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSelectableItem');
+	const options = user[0] as SelectableItemOptions;
+
+	let {
+		id,
+		selectionManager: manager,
+		key,
+		ref,
+		shouldSelectOnPressUp,
+		shouldUseVirtualFocus,
+		focus,
+		isDisabled,
+		onAction,
+		allowsDifferentPressOrigin,
+		linkBehavior = 'action',
+	} = options;
+	let router = useRouter();
+	id = useId(id, subSlot(slot, 'id'));
+	let onSelect = (e: PressEvent | LongPressEvent | PointerEvent) => {
+		if (e.pointerType === 'keyboard' && isNonContiguousSelectionModifier(e)) {
+			manager.toggleSelection(key);
+		} else {
+			if (manager.selectionMode === 'none') {
+				return;
+			}
+
+			if (manager.isLink(key)) {
+				if (linkBehavior === 'selection' && ref.current) {
+					let itemProps = manager.getItemProps(key);
+					router.open(ref.current, e, itemProps.href, itemProps.routerOptions);
+					// Always set selected keys back to what they were so that select and combobox close.
+					manager.setSelectedKeys(manager.selectedKeys);
+					return;
+				} else if (linkBehavior === 'override' || linkBehavior === 'none') {
+					return;
+				}
+			}
+
+			if (manager.selectionMode === 'single') {
+				if (manager.isSelected(key) && !manager.disallowEmptySelection) {
+					manager.toggleSelection(key);
+				} else {
+					manager.replaceSelection(key);
+				}
+			} else if (e && e.shiftKey) {
+				manager.extendSelection(key);
+			} else if (
+				manager.selectionBehavior === 'toggle' ||
+				(e && (isCtrlKeyPressed(e) || e.pointerType === 'touch' || e.pointerType === 'virtual'))
+			) {
+				// if touch or virtual (VO) then we just want to toggle, otherwise it's impossible to multi select because they don't have modifier keys
+				manager.toggleSelection(key);
+			} else {
+				manager.replaceSelection(key);
+			}
+		}
+	};
+
+	// Focus the associated DOM node when this item becomes the focusedKey
+	// TODO: can't make this useLayoutEffect bacause it breaks menus inside dialogs
+	// However, if this is a useEffect, it runs twice and dispatches two blur events and immediately sets
+	// aria-activeDescendant in useAutocomplete... I've worked around this for now
+	useEffect(
+		() => {
+			let isFocused = key === manager.focusedKey;
+			if (isFocused && manager.isFocused) {
+				if (!shouldUseVirtualFocus) {
+					if (focus) {
+						focus();
+					} else if (getActiveElement() !== ref.current && ref.current) {
+						focusSafely(ref.current);
+					}
+				} else {
+					moveVirtualFocus(ref.current);
+				}
+			}
+			// eslint-disable-next-line react-hooks/exhaustive-deps
+		},
+		[
+			ref,
+			key,
+			manager.focusedKey,
+			manager.childFocusStrategy,
+			manager.isFocused,
+			shouldUseVirtualFocus,
+		],
+		subSlot(slot, 'focusFx'),
+	);
+
+	isDisabled = isDisabled || manager.isDisabled(key);
+	// Set tabIndex to 0 if the element is focused, or -1 otherwise so that only the last focused
+	// item is tabbable.  If using virtual focus, don't set a tabIndex at all so that VoiceOver
+	// on iOS 14 doesn't try to move real DOM focus to the item anyway.
+	let itemProps: SelectableItemAria['itemProps'] = {};
+	if (!shouldUseVirtualFocus && !isDisabled) {
+		itemProps = {
+			tabIndex: key === manager.focusedKey ? 0 : -1,
+			onFocus(e: FocusEvent) {
+				if (getEventTarget(e) === ref.current) {
+					manager.setFocusedKey(key);
+				}
+			},
+		};
+	} else if (isDisabled) {
+		itemProps.onMouseDown = (e: MouseEvent) => {
+			// Prevent focus going to the body when clicking on a disabled item.
+			e.preventDefault();
+		};
+	}
+
+	useEffect(
+		() => {
+			if (isDisabled && manager.focusedKey === key) {
+				manager.setFocusedKey(null);
+			}
+		},
+		[manager, isDisabled, key],
+		subSlot(slot, 'disabledFx'),
+	);
+
+	// With checkbox selection, onAction (i.e. navigation) becomes primary, and occurs on a single click of the row.
+	// Clicking the checkbox enters selection mode, after which clicking anywhere on any row toggles selection for that row.
+	// With highlight selection, onAction is secondary, and occurs on double click. Single click selects the row.
+	// With touch, onAction occurs on single tap, and long press enters selection mode.
+	let isLinkOverride = manager.isLink(key) && linkBehavior === 'override';
+	let isActionOverride = onAction && (options as any)['UNSTABLE_itemBehavior'] === 'action';
+	let hasLinkAction =
+		manager.isLink(key) && linkBehavior !== 'selection' && linkBehavior !== 'none';
+	let allowsSelection =
+		!isDisabled && manager.canSelectItem(key) && !isLinkOverride && !isActionOverride;
+	let allowsActions = (onAction || hasLinkAction) && !isDisabled;
+	let hasPrimaryAction =
+		allowsActions &&
+		(manager.selectionBehavior === 'replace'
+			? !allowsSelection
+			: !allowsSelection || manager.isEmpty);
+	let hasSecondaryAction =
+		allowsActions && allowsSelection && manager.selectionBehavior === 'replace';
+	let hasAction = hasPrimaryAction || hasSecondaryAction;
+	let modality = useRef<PointerType | null>(null, subSlot(slot, 'modality'));
+
+	let longPressEnabled = hasAction && allowsSelection;
+	let longPressEnabledOnPressStart = useRef(false, subSlot(slot, 'lpOnStart'));
+	let hadPrimaryActionOnPressStart = useRef(false, subSlot(slot, 'primaryOnStart'));
+	let collectionItemProps = manager.getItemProps(key);
+
+	let performAction = (e: any) => {
+		if (onAction) {
+			onAction();
+			ref.current?.dispatchEvent(new CustomEvent('react-aria-item-action', { bubbles: true }));
+		}
+
+		if (hasLinkAction && ref.current) {
+			router.open(ref.current, e, collectionItemProps.href, collectionItemProps.routerOptions);
+		}
+	};
+
+	// By default, selection occurs on pointer down. This can be strange if selecting an
+	// item causes the UI to disappear immediately (e.g. menus).
+	// If shouldSelectOnPressUp is true, we use onPressUp instead of onPressStart.
+	// onPress requires a pointer down event on the same element as pointer up. For menus,
+	// we want to be able to have the pointer down on the trigger that opens the menu and
+	// the pointer up on the menu item rather than requiring a separate press.
+	// For keyboard events, selection still occurs on key down.
+	let itemPressProps: PressHookProps = { ref };
+	if (shouldSelectOnPressUp) {
+		itemPressProps.onPressStart = (e) => {
+			modality.current = e.pointerType;
+			longPressEnabledOnPressStart.current = longPressEnabled;
+			if (e.pointerType === 'keyboard' && (!hasAction || isSelectionKey(e.key))) {
+				onSelect(e);
+			}
+		};
+
+		// If allowsDifferentPressOrigin and interacting with mouse, make selection happen on pressUp (e.g. open menu on press down, selection on menu item happens on press up.)
+		// Otherwise, have selection happen onPress (prevents listview row selection when clicking on interactable elements in the row)
+		if (!allowsDifferentPressOrigin) {
+			itemPressProps.onPress = (e) => {
+				if (hasPrimaryAction || (hasSecondaryAction && e.pointerType !== 'mouse')) {
+					if (e.pointerType === 'keyboard' && !isActionKey(e.key)) {
+						return;
+					}
+
+					performAction(e);
+				} else if (e.pointerType !== 'keyboard' && allowsSelection) {
+					onSelect(e);
+				}
+			};
+		} else {
+			itemPressProps.onPressUp = hasPrimaryAction
+				? undefined
+				: (e) => {
+						if (e.pointerType === 'mouse' && allowsSelection) {
+							onSelect(e);
+						}
+					};
+
+			itemPressProps.onPress = hasPrimaryAction
+				? performAction
+				: (e) => {
+						if (e.pointerType !== 'keyboard' && e.pointerType !== 'mouse' && allowsSelection) {
+							onSelect(e);
+						}
+					};
+		}
+	} else {
+		itemPressProps.onPressStart = (e) => {
+			modality.current = e.pointerType;
+			longPressEnabledOnPressStart.current = longPressEnabled;
+			hadPrimaryActionOnPressStart.current = hasPrimaryAction;
+
+			// Select on mouse down unless there is a primary action which will occur on mouse up.
+			// For keyboard, select on key down. If there is an action, the Space key selects on key down,
+			// and the Enter key performs onAction on key up.
+			if (
+				allowsSelection &&
+				((e.pointerType === 'mouse' && !hasPrimaryAction) ||
+					(e.pointerType === 'keyboard' && (!allowsActions || isSelectionKey(e.key))))
+			) {
+				onSelect(e);
+			}
+		};
+
+		itemPressProps.onPress = (e) => {
+			// Selection occurs on touch up. Primary actions always occur on pointer up.
+			// Both primary and secondary actions occur on Enter key up. The only exception
+			// is secondary actions, which occur on double click with a mouse.
+			if (
+				e.pointerType === 'touch' ||
+				e.pointerType === 'pen' ||
+				e.pointerType === 'virtual' ||
+				(e.pointerType === 'keyboard' && hasAction && isActionKey(e.key)) ||
+				(e.pointerType === 'mouse' && hadPrimaryActionOnPressStart.current)
+			) {
+				if (hasAction) {
+					performAction(e);
+				} else if (allowsSelection) {
+					onSelect(e);
+				}
+			}
+		};
+	}
+
+	itemProps['data-collection'] = getCollectionId(manager.collection);
+	itemProps['data-key'] = key;
+	itemPressProps.preventFocusOnPress = shouldUseVirtualFocus;
+
+	// When using virtual focus, make sure the focused key gets updated on press.
+	if (shouldUseVirtualFocus) {
+		itemPressProps = mergeProps(itemPressProps, {
+			onPressStart(e: PressEvent) {
+				if (e.pointerType !== 'touch') {
+					manager.setFocused(true);
+					manager.setFocusedKey(key);
+				}
+			},
+			onPress(e: PressEvent) {
+				if (e.pointerType === 'touch') {
+					manager.setFocused(true);
+					manager.setFocusedKey(key);
+				}
+			},
+		});
+	}
+
+	if (collectionItemProps) {
+		for (let key of [
+			'onPressStart',
+			'onPressEnd',
+			'onPressChange',
+			'onPress',
+			'onPressUp',
+			'onClick',
+		]) {
+			if (collectionItemProps[key]) {
+				(itemPressProps as any)[key] = chain(
+					(itemPressProps as any)[key],
+					collectionItemProps[key],
+				);
+			}
+		}
+	}
+
+	let { pressProps, isPressed } = usePress(itemPressProps, subSlot(slot, 'press'));
+
+	// Double clicking with a mouse with selectionBehavior = 'replace' performs an action.
+	let onDoubleClick = hasSecondaryAction
+		? (e: MouseEvent) => {
+				if (modality.current === 'mouse') {
+					e.stopPropagation();
+					e.preventDefault();
+					performAction(e);
+				}
+			}
+		: undefined;
+
+	// Long pressing an item with touch when selectionBehavior = 'replace' switches the selection behavior
+	// to 'toggle'. This changes the single tap behavior from performing an action (i.e. navigating) to
+	// selecting, and may toggle the appearance of a UI affordance like checkboxes on each item.
+	let { longPressProps } = useLongPress(
+		{
+			isDisabled: !longPressEnabled,
+			onLongPress(e) {
+				if (e.pointerType === 'touch') {
+					onSelect(e);
+					manager.setSelectionBehavior('toggle');
+				}
+			},
+		},
+		subSlot(slot, 'longPress'),
+	);
+
+	// Prevent native drag and drop on long press if we also select on long press.
+	// Once the user is in selection mode, they can long press again to drag.
+	// Use a capturing listener to ensure this runs before useDrag, regardless of
+	// the order the props get merged.
+	let onDragStartCapture = (e: DragEvent) => {
+		if (modality.current === 'touch' && longPressEnabledOnPressStart.current) {
+			e.preventDefault();
+		}
+	};
+
+	// Prevent default on link clicks so that we control exactly
+	// when they open (to match selection behavior).
+	let onClick =
+		linkBehavior !== 'none' && manager.isLink(key)
+			? (e: MouseEvent) => {
+					if (!(openLink as any).isOpening) {
+						e.preventDefault();
+					}
+				}
+			: undefined;
+
+	return {
+		itemProps: mergeProps(
+			itemProps,
+			allowsSelection || hasPrimaryAction || (shouldUseVirtualFocus && !isDisabled)
+				? pressProps
+				: {},
+			longPressEnabled ? longPressProps : {},
+			{ onDoubleClick, onDragStartCapture, onClick, id },
+			// Prevent DOM focus from moving on mouse down when using virtual focus
+			shouldUseVirtualFocus ? { onMouseDown: (e: MouseEvent) => e.preventDefault() } : undefined,
+		),
+		isPressed,
+		isSelected: manager.isSelected(key),
+		isFocused: manager.isFocused && manager.focusedKey === key,
+		isDisabled,
+		allowsSelection,
+		hasAction,
+	};
+}
+
+function isActionKey(key: string | undefined) {
+	return key === 'Enter';
+}
+
+function isSelectionKey(key: string | undefined) {
+	return key === ' ';
+}

package/src/selection/useSelectableList.ts

@@ -0,0 +1,132 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/selection/useSelectableList.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; explicit dependency arrays are kept verbatim; `DOMAttributes` is a local
+// structural prop-bag alias (upstream's is typed over React's synthetic handlers).
+import {
+	type AriaSelectableCollectionOptions,
+	useSelectableCollection,
+} from './useSelectableCollection';
+import type {
+	Collection,
+	Key,
+	KeyboardDelegate,
+	LayoutDelegate,
+	Node,
+	Orientation,
+} from '@react-types/shared';
+import { ListKeyboardDelegate } from './ListKeyboardDelegate';
+import { useCollator } from '../i18n/useCollator';
+import { useMemo } from 'octane';
+
+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 AriaSelectableListOptions extends Omit<
+	AriaSelectableCollectionOptions,
+	'keyboardDelegate'
+> {
+	/**
+	 * State of the collection.
+	 */
+	collection: Collection<Node<unknown>>;
+	/**
+	 * A delegate object that implements behavior for keyboard focus movement.
+	 */
+	keyboardDelegate?: KeyboardDelegate;
+	/**
+	 * A delegate object that provides layout information for items in the collection.
+	 * By default this uses the DOM, but this can be overridden to implement things like
+	 * virtualized scrolling.
+	 */
+	layoutDelegate?: LayoutDelegate;
+	/**
+	 * The item keys that are disabled. These items cannot be selected, focused, or otherwise
+	 * interacted with.
+	 */
+	disabledKeys: Set<Key>;
+	/**
+	 * The primary orientation of the items. Usually this is the direction that the collection
+	 * scrolls.
+	 *
+	 * @default 'vertical'
+	 */
+	orientation?: Orientation;
+}
+
+export interface SelectableListAria {
+	/**
+	 * Props for the option element.
+	 */
+	listProps: DOMAttributes;
+}
+
+/**
+ * Handles interactions with a selectable list.
+ */
+export function useSelectableList(props: AriaSelectableListOptions): SelectableListAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSelectableList(
+	props: AriaSelectableListOptions,
+	slot: symbol | undefined,
+): SelectableListAria;
+export function useSelectableList(...args: any[]): SelectableListAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSelectableList');
+	const props = user[0] as AriaSelectableListOptions;
+
+	let {
+		selectionManager,
+		collection,
+		disabledKeys,
+		ref,
+		keyboardDelegate,
+		layoutDelegate,
+		orientation,
+	} = props;
+
+	// 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 disabledBehavior = selectionManager.disabledBehavior;
+	let delegate = useMemo(
+		() =>
+			keyboardDelegate ||
+			new ListKeyboardDelegate({
+				collection,
+				disabledKeys,
+				disabledBehavior,
+				ref,
+				collator,
+				layoutDelegate,
+				orientation,
+			}),
+		[
+			keyboardDelegate,
+			layoutDelegate,
+			collection,
+			disabledKeys,
+			ref,
+			collator,
+			disabledBehavior,
+			orientation,
+		],
+		subSlot(slot, 'delegate'),
+	);
+
+	let { collectionProps } = useSelectableCollection(
+		{
+			...props,
+			ref,
+			selectionManager,
+			keyboardDelegate: delegate,
+		},
+		subSlot(slot, 'collection'),
+	);
+
+	return {
+		listProps: collectionProps,
+	};
+}