@octanejs/aria 0.0.1 → 0.0.3

package/src/stately/list/ListCollection.ts

@@ -0,0 +1,104 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/list/ListCollection.ts).
+// Verbatim (no React surface).
+import type { Collection, Key, Node } from '@react-types/shared';
+
+export class ListCollection<T> implements Collection<Node<T>> {
+	private keyMap: Map<Key, Node<T>> = new Map();
+	private iterable: Iterable<Node<T>>;
+	private firstKey: Key | null = null;
+	private lastKey: Key | null = null;
+	private _size: number;
+
+	constructor(nodes: Iterable<Node<T>>) {
+		this.iterable = nodes;
+
+		let visit = (node: Node<T>) => {
+			this.keyMap.set(node.key, node);
+
+			if (node.childNodes && node.type === 'section') {
+				for (let child of node.childNodes) {
+					visit(child);
+				}
+			}
+		};
+
+		for (let node of nodes) {
+			visit(node);
+		}
+
+		let last: Node<T> | null = null;
+		let index = 0;
+		let size = 0;
+		for (let [key, node] of this.keyMap) {
+			if (last) {
+				last.nextKey = key;
+				node.prevKey = last.key;
+			} else {
+				this.firstKey = key;
+				node.prevKey = undefined;
+			}
+
+			if (node.type === 'item') {
+				node.index = index++;
+			}
+
+			// Only count sections and items when determining size so that
+			// loaders and separators in RAC/S2 don't influence the emptyState determination
+			if (node.type === 'section' || node.type === 'item') {
+				size++;
+			}
+
+			last = node;
+
+			// Set nextKey as undefined since this might be the last node
+			// If it isn't the last node, last.nextKey will properly set at start of new loop
+			last.nextKey = undefined;
+		}
+		this._size = size;
+		this.lastKey = last?.key ?? null;
+	}
+
+	*[Symbol.iterator](): IterableIterator<Node<T>> {
+		yield* this.iterable;
+	}
+
+	get size(): number {
+		return this._size;
+	}
+
+	getKeys(): IterableIterator<Key> {
+		return this.keyMap.keys();
+	}
+
+	getKeyBefore(key: Key): Key | null {
+		let node = this.keyMap.get(key);
+		return node ? (node.prevKey ?? null) : null;
+	}
+
+	getKeyAfter(key: Key): Key | null {
+		let node = this.keyMap.get(key);
+		return node ? (node.nextKey ?? null) : null;
+	}
+
+	getFirstKey(): Key | null {
+		return this.firstKey;
+	}
+
+	getLastKey(): Key | null {
+		return this.lastKey;
+	}
+
+	getItem(key: Key): Node<T> | null {
+		return this.keyMap.get(key) ?? null;
+	}
+
+	at(idx: number): Node<T> | null {
+		const keys = [...this.getKeys()];
+		return this.getItem(keys[idx]);
+	}
+
+	getChildren(key: Key): Iterable<Node<T>> {
+		let node = this.keyMap.get(key);
+		return node?.childNodes || [];
+	}
+}

package/src/stately/list/useListState.ts

@@ -0,0 +1,178 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/list/useListState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; the private `useFocusedKeyReset` helper hook takes the caller's derived
+// sub-slot as an ordinary parameter; explicit dependency arrays are kept verbatim (they
+// retain React's exact behavior in octane).
+import type {
+	Collection,
+	CollectionStateBase,
+	Key,
+	LayoutDelegate,
+	Node,
+} from '@react-types/shared';
+import { useCallback, useEffect, useMemo, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { ListCollection } from './ListCollection';
+import {
+	type MultipleSelectionStateProps,
+	useMultipleSelectionState,
+} from '../selection/useMultipleSelectionState';
+import { SelectionManager } from '../selection/SelectionManager';
+import { useCollection } from '../collections/useCollection';
+
+export interface ListProps<T> extends CollectionStateBase<T>, MultipleSelectionStateProps {
+	/** Filter function to generate a filtered list of nodes. */
+	filter?: (nodes: Iterable<Node<T>>) => Iterable<Node<T>>;
+	/** @private */
+	suppressTextValueWarning?: boolean;
+	/**
+	 * A delegate object that provides layout information for items in the collection.
+	 * This can be used to override the behavior of shift selection.
+	 */
+	layoutDelegate?: LayoutDelegate;
+}
+
+export interface ListState<T> {
+	/** A collection of items in the list. */
+	collection: Collection<Node<T>>;
+
+	/** A set of items that are disabled. */
+	disabledKeys: Set<Key>;
+
+	/** A selection manager to read and update multiple selection state. */
+	selectionManager: SelectionManager;
+}
+
+/**
+ * Provides state management for list-like components. Handles building a collection
+ * of items from props, and manages multiple selection state.
+ */
+export function useListState<T>(props: ListProps<T>): ListState<T>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useListState<T>(props: ListProps<T>, slot: symbol | undefined): ListState<T>;
+export function useListState(...args: any[]): ListState<any> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useListState');
+	const props = user[0] as ListProps<any>;
+
+	let { filter, layoutDelegate } = props;
+
+	let selectionState = useMultipleSelectionState(props, subSlot(slot, 'selection'));
+	let disabledKeys = useMemo(
+		() => (props.disabledKeys ? new Set(props.disabledKeys) : new Set<Key>()),
+		[props.disabledKeys],
+		subSlot(slot, 'disabled'),
+	);
+
+	let factory = useCallback(
+		(nodes: Iterable<Node<any>>) =>
+			filter ? new ListCollection(filter(nodes)) : new ListCollection(nodes as Iterable<Node<any>>),
+		[filter],
+		subSlot(slot, 'factory'),
+	);
+	let context = useMemo(
+		() => ({ suppressTextValueWarning: props.suppressTextValueWarning }),
+		[props.suppressTextValueWarning],
+		subSlot(slot, 'context'),
+	);
+
+	let collection = useCollection(props, factory, context, subSlot(slot, 'collection'));
+
+	let selectionManager = useMemo(
+		() => new SelectionManager(collection, selectionState, { layoutDelegate }),
+		[collection, selectionState, layoutDelegate],
+		subSlot(slot, 'manager'),
+	);
+
+	useFocusedKeyReset(collection, selectionManager, subSlot(slot, 'focusReset'));
+
+	return {
+		collection,
+		disabledKeys,
+		selectionManager,
+	};
+}
+
+/**
+ * Filters a collection using the provided filter function and returns a new ListState.
+ */
+export function UNSTABLE_useFilteredListState<T>(
+	state: ListState<T>,
+	filterFn: ((nodeValue: string, node: Node<T>) => boolean) | null | undefined,
+): ListState<T>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function UNSTABLE_useFilteredListState<T>(
+	state: ListState<T>,
+	filterFn: ((nodeValue: string, node: Node<T>) => boolean) | null | undefined,
+	slot: symbol | undefined,
+): ListState<T>;
+export function UNSTABLE_useFilteredListState(...args: any[]): ListState<any> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('UNSTABLE_useFilteredListState');
+	const state = user[0] as ListState<any>;
+	const filterFn = user[1] as ((nodeValue: string, node: Node<any>) => boolean) | null | undefined;
+
+	let collection = useMemo(
+		() => (filterFn ? state.collection.filter!(filterFn) : state.collection),
+		[state.collection, filterFn],
+		subSlot(slot, 'collection'),
+	);
+	let selectionManager = state.selectionManager.withCollection(collection);
+	useFocusedKeyReset(collection, selectionManager, subSlot(slot, 'focusReset'));
+	return {
+		collection,
+		selectionManager,
+		disabledKeys: state.disabledKeys,
+	};
+}
+
+function useFocusedKeyReset<T>(
+	collection: Collection<Node<T>>,
+	selectionManager: SelectionManager,
+	slot: symbol | undefined,
+) {
+	// Reset focused key if that item is deleted from the collection.
+	const cachedCollection = useRef<Collection<Node<T>> | null>(null, subSlot(slot, 'cached'));
+	useEffect(
+		() => {
+			if (
+				selectionManager.focusedKey != null &&
+				!collection.getItem(selectionManager.focusedKey) &&
+				cachedCollection.current
+			) {
+				// Walk forward in the old collection to find the next key that still exists in the new collection.
+				let key = cachedCollection.current.getKeyAfter(selectionManager.focusedKey);
+				let nextFocusedKey: Key | null = null;
+				while (key != null) {
+					let node = collection.getItem(key);
+					if (node && node.type === 'item' && !selectionManager.isDisabled(key)) {
+						nextFocusedKey = key;
+						break;
+					}
+
+					key = cachedCollection.current.getKeyAfter(key);
+				}
+
+				// If no such key exists, walk backward.
+				if (nextFocusedKey == null) {
+					key = cachedCollection.current.getKeyBefore(selectionManager.focusedKey);
+					while (key != null) {
+						let node = collection.getItem(key);
+						if (node && node.type === 'item' && !selectionManager.isDisabled(key)) {
+							nextFocusedKey = key;
+							break;
+						}
+
+						key = cachedCollection.current.getKeyBefore(key);
+					}
+				}
+
+				selectionManager.setFocusedKey(nextFocusedKey);
+			}
+			cachedCollection.current = collection;
+		},
+		[collection, selectionManager],
+		subSlot(slot, 'reset'),
+	);
+}

package/src/stately/list/useSingleSelectListState.ts

@@ -0,0 +1,101 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/list/useSingleSelectListState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; explicit dependency arrays are kept verbatim (they retain React's exact
+// behavior in octane).
+import type {
+	CollectionStateBase,
+	Key,
+	Node,
+	Selection,
+	SingleSelection,
+} from '@react-types/shared';
+import { useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { type ListState, useListState } from './useListState';
+import { useControlledState } from '../utils/useControlledState';
+
+export interface SingleSelectListProps<T>
+	extends CollectionStateBase<T>, Omit<SingleSelection, 'disallowEmptySelection'> {
+	/** Filter function to generate a filtered list of nodes. */
+	filter?: (nodes: Iterable<Node<T>>) => Iterable<Node<T>>;
+	/** @private */
+	suppressTextValueWarning?: boolean;
+}
+
+export interface SingleSelectListState<T> extends ListState<T> {
+	/** The key for the currently selected item. */
+	readonly selectedKey: Key | null;
+
+	/** Sets the selected key. */
+	setSelectedKey(key: Key | null): void;
+
+	/** The value of the currently selected item. */
+	readonly selectedItem: Node<T> | null;
+}
+
+/**
+ * Provides state management for list-like components with single selection.
+ * Handles building a collection of items from props, and manages selection state.
+ */
+export function useSingleSelectListState<T extends object>(
+	props: SingleSelectListProps<T>,
+): SingleSelectListState<T>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSingleSelectListState<T extends object>(
+	props: SingleSelectListProps<T>,
+	slot: symbol | undefined,
+): SingleSelectListState<T>;
+export function useSingleSelectListState(...args: any[]): SingleSelectListState<any> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSingleSelectListState');
+	const props = user[0] as SingleSelectListProps<any>;
+
+	let [selectedKey, setSelectedKey] = useControlledState(
+		props.selectedKey,
+		props.defaultSelectedKey ?? null,
+		props.onSelectionChange,
+		subSlot(slot, 'selectedKey'),
+	);
+	let selectedKeys = useMemo(
+		() => (selectedKey != null ? [selectedKey] : []),
+		[selectedKey],
+		subSlot(slot, 'selectedKeys'),
+	);
+	let { collection, disabledKeys, selectionManager } = useListState(
+		{
+			...props,
+			selectionMode: 'single',
+			disallowEmptySelection: true,
+			allowDuplicateSelectionEvents: true,
+			selectedKeys,
+			onSelectionChange: (keys: Selection) => {
+				// impossible, but TS doesn't know that
+				if (keys === 'all') {
+					return;
+				}
+				let key = keys.values().next().value ?? null;
+
+				// Always fire onSelectionChange, even if the key is the same
+				// as the current key (useControlledState does not).
+				if (key === selectedKey && props.onSelectionChange) {
+					props.onSelectionChange(key);
+				}
+
+				setSelectedKey(key);
+			},
+		},
+		subSlot(slot, 'list'),
+	);
+
+	let selectedItem = selectedKey != null ? collection.getItem(selectedKey) : null;
+
+	return {
+		collection,
+		disabledKeys,
+		selectionManager,
+		selectedKey,
+		setSelectedKey,
+		selectedItem,
+	};
+}

package/src/stately/menu/useMenuTriggerState.ts

@@ -0,0 +1,120 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/menu/useMenuTriggerState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention.
+import type { FocusStrategy, Key } from '@react-types/shared';
+import { useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import {
+	type OverlayTriggerProps,
+	type OverlayTriggerState,
+	useOverlayTriggerState,
+} from '../overlays/useOverlayTriggerState';
+
+export type MenuTriggerType = 'press' | 'longPress';
+
+export interface MenuTriggerProps extends OverlayTriggerProps {
+	/**
+	 * How the menu is triggered.
+	 *
+	 * @default 'press'
+	 */
+	trigger?: MenuTriggerType;
+}
+
+export interface MenuTriggerState extends OverlayTriggerState {
+	/** Controls which item will be auto focused when the menu opens. */
+	readonly focusStrategy: FocusStrategy | null;
+
+	/** Opens the menu. */
+	open(focusStrategy?: FocusStrategy | null): void;
+
+	/** Toggles the menu. */
+	toggle(focusStrategy?: FocusStrategy | null): void;
+}
+
+export interface RootMenuTriggerState extends MenuTriggerState {
+	/** Opens a specific submenu tied to a specific menu item at a specific level. */
+	openSubmenu: (triggerKey: Key, level: number) => void;
+
+	/** Closes a specific submenu tied to a specific menu item at a specific level. */
+	closeSubmenu: (triggerKey: Key, level: number) => void;
+
+	/**
+	 * An array of open submenu trigger keys within the menu tree.
+	 * The index of key within array matches the submenu level in the tree.
+	 */
+	expandedKeysStack: Key[];
+
+	/** Closes the menu and all submenus in the menu tree. */
+	close: () => void;
+}
+
+/**
+ * Manages state for a menu trigger. Tracks whether the menu is currently open,
+ * and controls which item will receive focus when it opens. Also tracks the open submenus within
+ * the menu tree via their trigger keys.
+ */
+export function useMenuTriggerState(props: MenuTriggerProps): RootMenuTriggerState;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useMenuTriggerState(
+	props: MenuTriggerProps,
+	slot: symbol | undefined,
+): RootMenuTriggerState;
+export function useMenuTriggerState(...args: any[]): RootMenuTriggerState {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useMenuTriggerState');
+	const props = user[0] as MenuTriggerProps;
+
+	let overlayTriggerState = useOverlayTriggerState(props, subSlot(slot, 'overlay'));
+	let [focusStrategy, setFocusStrategy] = useState<FocusStrategy | null>(
+		null,
+		subSlot(slot, 'focusStrategy'),
+	);
+	let [expandedKeysStack, setExpandedKeysStack] = useState<Key[]>([], subSlot(slot, 'expanded'));
+
+	let closeAll = () => {
+		setExpandedKeysStack([]);
+		overlayTriggerState.close();
+	};
+
+	let openSubmenu = (triggerKey: Key, level: number) => {
+		setExpandedKeysStack((oldStack) => {
+			if (level > oldStack.length) {
+				return oldStack;
+			}
+
+			return [...oldStack.slice(0, level), triggerKey];
+		});
+	};
+
+	let closeSubmenu = (triggerKey: Key, level: number) => {
+		setExpandedKeysStack((oldStack) => {
+			let key = oldStack[level];
+			if (key === triggerKey) {
+				return oldStack.slice(0, level);
+			} else {
+				return oldStack;
+			}
+		});
+	};
+
+	return {
+		focusStrategy,
+		...overlayTriggerState,
+		open(focusStrategy: FocusStrategy | null = null) {
+			setFocusStrategy(focusStrategy);
+			overlayTriggerState.open();
+		},
+		toggle(focusStrategy: FocusStrategy | null = null) {
+			setFocusStrategy(focusStrategy);
+			overlayTriggerState.toggle();
+		},
+		close() {
+			closeAll();
+		},
+		expandedKeysStack,
+		openSubmenu,
+		closeSubmenu,
+	};
+}

package/src/stately/menu/useSubmenuTriggerState.ts

@@ -0,0 +1,116 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/menu/useSubmenuTriggerState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; explicit dependency arrays are kept verbatim (they retain React's exact
+// behavior in octane).
+import type { FocusStrategy, Key } from '@react-types/shared';
+import { useCallback, useMemo, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import type { OverlayTriggerState } from '../overlays/useOverlayTriggerState';
+import type { RootMenuTriggerState } from './useMenuTriggerState';
+
+export interface SubmenuTriggerProps {
+	/** Key of the trigger item. */
+	triggerKey: Key;
+}
+
+export interface SubmenuTriggerState extends OverlayTriggerState {
+	/** Whether the submenu is currently open. */
+	isOpen: boolean;
+	/** Controls which item will be auto focused when the submenu opens. */
+	focusStrategy: FocusStrategy | null;
+	/** Opens the submenu. */
+	open: (focusStrategy?: FocusStrategy | null) => void;
+	/** Closes the submenu. */
+	close: () => void;
+	/** Closes all menus and submenus in the menu tree. */
+	closeAll: () => void;
+	/** The level of the submenu. */
+	submenuLevel: number;
+	/** Toggles the submenu. */
+	toggle: (focusStrategy?: FocusStrategy | null) => void;
+	/** @private */
+	setOpen: () => void;
+}
+
+/**
+ * Manages state for a submenu trigger. Tracks whether the submenu is currently open, the level of
+ * the submenu, and controls which item will receive focus when it opens.
+ */
+export function useSubmenuTriggerState(
+	props: SubmenuTriggerProps,
+	state: RootMenuTriggerState,
+): SubmenuTriggerState;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSubmenuTriggerState(
+	props: SubmenuTriggerProps,
+	state: RootMenuTriggerState,
+	slot: symbol | undefined,
+): SubmenuTriggerState;
+export function useSubmenuTriggerState(...args: any[]): SubmenuTriggerState {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSubmenuTriggerState');
+	const props = user[0] as SubmenuTriggerProps;
+	const state = user[1] as RootMenuTriggerState;
+
+	let { triggerKey } = props;
+	let { expandedKeysStack, openSubmenu, closeSubmenu, close: closeAll } = state;
+	let [submenuLevel] = useState(expandedKeysStack?.length, subSlot(slot, 'level'));
+	let isOpen = useMemo(
+		() => expandedKeysStack[submenuLevel] === triggerKey,
+		[expandedKeysStack, triggerKey, submenuLevel],
+		subSlot(slot, 'isOpen'),
+	);
+	let [focusStrategy, setFocusStrategy] = useState<FocusStrategy | null>(
+		null,
+		subSlot(slot, 'focusStrategy'),
+	);
+
+	let open = useCallback(
+		(focusStrategy?: FocusStrategy | null) => {
+			setFocusStrategy(focusStrategy ?? null);
+			openSubmenu(triggerKey, submenuLevel);
+		},
+		[openSubmenu, submenuLevel, triggerKey],
+		subSlot(slot, 'open'),
+	);
+
+	let close = useCallback(
+		() => {
+			setFocusStrategy(null);
+			closeSubmenu(triggerKey, submenuLevel);
+		},
+		[closeSubmenu, submenuLevel, triggerKey],
+		subSlot(slot, 'close'),
+	);
+
+	let toggle = useCallback(
+		(focusStrategy?: FocusStrategy | null) => {
+			setFocusStrategy(focusStrategy ?? null);
+			if (isOpen) {
+				close();
+			} else {
+				open(focusStrategy);
+			}
+		},
+		[close, open, isOpen],
+		subSlot(slot, 'toggle'),
+	);
+
+	return useMemo(
+		() => ({
+			focusStrategy,
+			isOpen,
+			open,
+			close,
+			closeAll,
+			submenuLevel,
+			// TODO: Placeholders that aren't used but give us parity with OverlayTriggerState so we can use this in Popover. Refactor if we update Popover via
+			// https://github.com/adobe/react-spectrum/pull/4976#discussion_r1336472863
+			setOpen: () => {},
+			toggle,
+		}),
+		[isOpen, open, close, closeAll, focusStrategy, toggle, submenuLevel],
+		subSlot(slot, 'state'),
+	);
+}