@octanejs/aria 0.0.1 → 0.0.3

package/src/stately/tree/useTreeState.ts

@@ -0,0 +1,121 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/tree/useTreeState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; explicit dependency arrays are kept verbatim — including upstream's
+// eslint-suppressed `[tree, selectionState.focusedKey]` effect array (they retain React's
+// exact behavior in octane).
+import type {
+	Collection,
+	CollectionStateBase,
+	DisabledBehavior,
+	Expandable,
+	Key,
+	MultipleSelection,
+	Node,
+} from '@react-types/shared';
+import { useCallback, useEffect, useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { SelectionManager } from '../selection/SelectionManager';
+import { TreeCollection } from './TreeCollection';
+import { useCollection } from '../collections/useCollection';
+import { useControlledState } from '../utils/useControlledState';
+import { useMultipleSelectionState } from '../selection/useMultipleSelectionState';
+
+export interface TreeProps<T> extends CollectionStateBase<T>, Expandable, MultipleSelection {
+	/** Whether `disabledKeys` applies to all interactions, or only selection. */
+	disabledBehavior?: DisabledBehavior;
+}
+export interface TreeState<T> {
+	/** A collection of items in the tree. */
+	readonly collection: Collection<Node<T>>;
+
+	/** A set of keys for items that are disabled. */
+	readonly disabledKeys: Set<Key>;
+
+	/** A set of keys for items that are expanded. */
+	readonly expandedKeys: Set<Key>;
+
+	/** Toggles the expanded state for an item by its key. */
+	toggleKey(key: Key): void;
+
+	/** Replaces the set of expanded keys. */
+	setExpandedKeys(keys: Set<Key>): void;
+
+	/** A selection manager to read and update multiple selection state. */
+	readonly selectionManager: SelectionManager;
+}
+
+/**
+ * Provides state management for tree-like components. Handles building a collection
+ * of items from props, item expanded state, and manages multiple selection state.
+ */
+export function useTreeState<T>(props: TreeProps<T>): TreeState<T>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTreeState<T>(props: TreeProps<T>, slot: symbol | undefined): TreeState<T>;
+export function useTreeState(...args: any[]): TreeState<any> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTreeState');
+	const props = user[0] as TreeProps<any>;
+
+	let { onExpandedChange } = props;
+
+	let [expandedKeys, setExpandedKeys] = useControlledState(
+		props.expandedKeys ? new Set(props.expandedKeys) : undefined,
+		props.defaultExpandedKeys ? new Set(props.defaultExpandedKeys) : new Set<Key>(),
+		onExpandedChange,
+		subSlot(slot, 'expanded'),
+	);
+
+	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 tree = useCollection(
+		props,
+		useCallback(
+			(nodes: Iterable<Node<any>>) => new TreeCollection(nodes, { expandedKeys }),
+			[expandedKeys],
+			subSlot(slot, 'factory'),
+		),
+		null,
+		subSlot(slot, 'collection'),
+	);
+
+	// Reset focused key if that item is deleted from the collection.
+	useEffect(
+		() => {
+			if (selectionState.focusedKey != null && !tree.getItem(selectionState.focusedKey)) {
+				selectionState.setFocusedKey(null);
+			}
+		},
+		[tree, selectionState.focusedKey],
+		subSlot(slot, 'focusReset'),
+	);
+
+	let onToggle = (key: Key) => {
+		setExpandedKeys(toggleKey(expandedKeys, key));
+	};
+
+	return {
+		collection: tree,
+		expandedKeys,
+		disabledKeys,
+		toggleKey: onToggle,
+		setExpandedKeys,
+		selectionManager: new SelectionManager(tree, selectionState),
+	};
+}
+
+function toggleKey(set: Set<Key>, key: Key): Set<Key> {
+	let res = new Set(set);
+	if (res.has(key)) {
+		res.delete(key);
+	} else {
+		res.add(key);
+	}
+
+	return res;
+}

package/src/stately/utils/useControlledState.ts

@@ -23,6 +23,13 @@ export function useControlledState<T, C = T>(
 	defaultValue: Exclude<T, undefined>,
 	onChange?: (v: C, ...args: any[]) => void,
 ): [T, (value: SetStateAction<T>, ...args: any[]) => void];
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useControlledState<T, C = T>(
+	value: Exclude<T, undefined> | undefined,
+	defaultValue: Exclude<T, undefined> | undefined,
+	onChange: ((v: C, ...args: any[]) => void) | undefined,
+	slot: symbol | undefined,
+): [T, (value: SetStateAction<T>, ...args: any[]) => void];
 export function useControlledState(...args: any[]): any {
 	const [user, slotArg] = splitSlot(args);
 	const slot = slotArg ?? S('useControlledState');

package/src/switch/useSwitch.ts

@@ -0,0 +1,77 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/switch/useSwitch.ts).
+// octane adaptations: React's per-element attribute types → the structural bags the
+// ported useToggle returns; public-hook slot threading.
+import type { InputDOMProps, RefObject, ValidationResult } from '@react-types/shared';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { AriaToggleProps, useToggle } from '../toggle/useToggle';
+import type { ToggleProps, ToggleState } from '../stately/toggle/useToggleState';
+
+type DOMAttributes = Record<string, any>;
+
+export interface SwitchProps extends ToggleProps {}
+
+export interface AriaSwitchProps extends SwitchProps, InputDOMProps, AriaToggleProps {
+	/**
+	 * Identifies the element (or elements) whose contents or presence are controlled by the current
+	 * element.
+	 */
+	'aria-controls'?: string;
+}
+
+export interface SwitchAria extends ValidationResult {
+	/** Props for the label wrapper element. */
+	labelProps: DOMAttributes;
+	/** Props for the input element. */
+	inputProps: DOMAttributes;
+	/** Props for the switch description element, if any. */
+	descriptionProps: DOMAttributes;
+	/** Props for the switch error message element, if any. */
+	errorMessageProps: DOMAttributes;
+	/** Whether the switch is selected. */
+	isSelected: boolean;
+	/** Whether the switch is in a pressed state. */
+	isPressed: boolean;
+	/** Whether the switch is disabled. */
+	isDisabled: boolean;
+	/** Whether the switch is read only. */
+	isReadOnly: boolean;
+}
+
+export function useSwitch(
+	props: AriaSwitchProps,
+	state: ToggleState,
+	ref: RefObject<HTMLInputElement | null>,
+): SwitchAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSwitch(
+	props: AriaSwitchProps,
+	state: ToggleState,
+	ref: RefObject<HTMLInputElement | null>,
+	slot: symbol | undefined,
+): SwitchAria;
+export function useSwitch(...args: any[]): SwitchAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSwitch');
+	const props = user[0] as AriaSwitchProps;
+	const state = user[1] as ToggleState;
+	const ref = user[2] as RefObject<HTMLInputElement | null>;
+
+	let { labelProps, inputProps, isSelected, ...states } = useToggle(
+		props,
+		state,
+		ref,
+		subSlot(slot, 'toggle'),
+	);
+
+	return {
+		labelProps,
+		inputProps: {
+			...inputProps,
+			role: 'switch',
+			checked: isSelected,
+		},
+		isSelected,
+		...states,
+	};
+}

package/src/tabs/TabsKeyboardDelegate.ts

@@ -0,0 +1,99 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/tabs/TabsKeyboardDelegate.ts).
+// No octane adaptations required: a plain class over @react-types/shared types.
+import type {
+	Collection,
+	Direction,
+	Key,
+	KeyboardDelegate,
+	Node,
+	Orientation,
+} from '@react-types/shared';
+
+export class TabsKeyboardDelegate<T> implements KeyboardDelegate {
+	private collection: Collection<Node<T>>;
+	private flipDirection: boolean;
+	private disabledKeys: Set<Key>;
+	private tabDirection: boolean;
+
+	constructor(
+		collection: Collection<Node<T>>,
+		direction: Direction,
+		orientation: Orientation,
+		disabledKeys: Set<Key> = new Set(),
+	) {
+		this.collection = collection;
+		this.flipDirection = direction === 'rtl' && orientation === 'horizontal';
+		this.disabledKeys = disabledKeys;
+		this.tabDirection = orientation === 'horizontal';
+	}
+
+	getKeyLeftOf(key: Key): Key | null {
+		if (this.flipDirection) {
+			return this.getNextKey(key);
+		}
+		return this.getPreviousKey(key);
+	}
+
+	getKeyRightOf(key: Key): Key | null {
+		if (this.flipDirection) {
+			return this.getPreviousKey(key);
+		}
+		return this.getNextKey(key);
+	}
+
+	private isDisabled(key: Key) {
+		return this.disabledKeys.has(key) || !!this.collection.getItem(key)?.props?.isDisabled;
+	}
+
+	getFirstKey(): Key | null {
+		let key = this.collection.getFirstKey();
+		if (key != null && this.isDisabled(key)) {
+			key = this.getNextKey(key);
+		}
+		return key;
+	}
+
+	getLastKey(): Key | null {
+		let key = this.collection.getLastKey();
+		if (key != null && this.isDisabled(key)) {
+			key = this.getPreviousKey(key);
+		}
+		return key;
+	}
+
+	getKeyAbove(key: Key): Key | null {
+		if (this.tabDirection) {
+			return null;
+		}
+		return this.getPreviousKey(key);
+	}
+
+	getKeyBelow(key: Key): Key | null {
+		if (this.tabDirection) {
+			return null;
+		}
+		return this.getNextKey(key);
+	}
+
+	getNextKey(startKey: Key): Key | null {
+		let key: Key | null = startKey;
+		do {
+			key = this.collection.getKeyAfter(key);
+			if (key == null) {
+				key = this.collection.getFirstKey();
+			}
+		} while (key != null && this.isDisabled(key) && key !== startKey);
+		return key;
+	}
+
+	getPreviousKey(startKey: Key): Key | null {
+		let key: Key | null = startKey;
+		do {
+			key = this.collection.getKeyBefore(key);
+			if (key == null) {
+				key = this.collection.getLastKey();
+			}
+		} while (key != null && this.isDisabled(key) && key !== startKey);
+		return key;
+	}
+}

package/src/tabs/useTab.ts

@@ -0,0 +1,117 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/tabs/useTab.ts).
+// octane adaptations:
+// - `DOMAttributes` is a local structural prop-bag alias (upstream's is typed over React's
+//   synthetic handlers); `TabListState` from the ported stately tabs state.
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention
+//   (`useLinkProps` composes only context-reading hooks and takes no slot, matching the
+//   ported useLink).
+import type { AriaLabelingProps, FocusableElement, Key, RefObject } from '@react-types/shared';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { generateId } from './utils';
+import { mergeProps } from '../utils/mergeProps';
+import type { TabListState } from '../stately/tabs/useTabListState';
+import { useFocusable } from '../interactions/useFocusable';
+import { useLinkProps } from '../utils/openLink';
+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 AriaTabProps extends AriaLabelingProps {
+	/** The key of the tab. */
+	key: Key;
+	/** Whether the tab should be disabled. */
+	isDisabled?: boolean;
+	/** Whether the tab selection should occur on press up instead of press down. */
+	shouldSelectOnPressUp?: boolean;
+}
+
+export interface TabAria {
+	/** Props for the tab element. */
+	tabProps: DOMAttributes;
+	/** Whether the tab is currently selected. */
+	isSelected: boolean;
+	/** Whether the tab is disabled. */
+	isDisabled: boolean;
+	/** Whether the tab is currently in a pressed state. */
+	isPressed: boolean;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a tab.
+ * When selected, the associated tab panel is shown.
+ */
+export function useTab<T>(
+	props: AriaTabProps,
+	state: TabListState<T>,
+	ref: RefObject<FocusableElement | null>,
+): TabAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTab<T>(
+	props: AriaTabProps,
+	state: TabListState<T>,
+	ref: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): TabAria;
+export function useTab(...args: any[]): TabAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTab');
+	const props = user[0] as AriaTabProps;
+	const state = user[1] as TabListState<unknown>;
+	const ref = user[2] as RefObject<FocusableElement | null>;
+
+	let { key, isDisabled: propsDisabled, shouldSelectOnPressUp } = props;
+	let { selectionManager: manager, selectedKey } = state;
+
+	let isSelected = key === selectedKey;
+
+	let isDisabled = propsDisabled || state.isDisabled || state.selectionManager.isDisabled(key);
+	let item = state.collection.getItem(key);
+	let { itemProps, isPressed } = useSelectableItem(
+		{
+			selectionManager: manager,
+			key,
+			ref,
+			isDisabled,
+			// Link tabs should behave like native anchors (navigate on press up)
+			// This avoids reopening beforeunload dialogs when browsers replay
+			// queued pointer enter/leave events after cancellation.
+			shouldSelectOnPressUp: shouldSelectOnPressUp ?? item?.props.href != null,
+			linkBehavior: 'selection',
+		},
+		subSlot(slot, 'item'),
+	);
+
+	let tabId = generateId(state, key, 'tab');
+	let tabPanelId = generateId(state, key, 'tabpanel');
+	let { tabIndex } = itemProps;
+
+	let domProps = filterDOMProps(item?.props, { labelable: true });
+	delete domProps.id;
+	let linkProps = useLinkProps(item?.props);
+	let { focusableProps } = useFocusable(
+		{
+			...item?.props,
+			isDisabled,
+		},
+		ref,
+		subSlot(slot, 'focusable'),
+	);
+
+	return {
+		tabProps: mergeProps(domProps, focusableProps, linkProps, itemProps, {
+			id: tabId,
+			'aria-selected': isSelected,
+			'aria-disabled': isDisabled || undefined,
+			'aria-controls': isSelected ? tabPanelId : undefined,
+			tabIndex: isDisabled ? undefined : tabIndex,
+			role: 'tab',
+		}),
+		isSelected,
+		isDisabled,
+		isPressed,
+	};
+}

package/src/tabs/useTabList.ts

@@ -0,0 +1,105 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/tabs/useTabList.ts).
+// octane adaptations:
+// - `DOMAttributes` is a local structural prop-bag alias (upstream's is typed over React's
+//   synthetic handlers); `TabListProps`/`TabListState` from the ported stately tabs state.
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention; the
+//   explicit `useMemo` dependency array is kept verbatim.
+import type { AriaLabelingProps, DOMProps, Orientation, RefObject } from '@react-types/shared';
+import { mergeProps } from '../utils/mergeProps';
+import type { TabListProps, TabListState } from '../stately/tabs/useTabListState';
+import { tabsIds } from './utils';
+import { TabsKeyboardDelegate } from './TabsKeyboardDelegate';
+import { useId } from '../utils/useId';
+import { useLabels } from '../utils/useLabels';
+import { useLocale } from '../i18n/I18nProvider';
+import { useMemo } from 'octane';
+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 AriaTabListProps<T> extends TabListProps<T>, DOMProps, AriaLabelingProps {
+	/**
+	 * Whether tabs are activated automatically on focus or manually.
+	 *
+	 * @default 'automatic'
+	 */
+	keyboardActivation?: 'automatic' | 'manual';
+	/**
+	 * The orientation of the tabs.
+	 *
+	 * @default 'horizontal'
+	 */
+	orientation?: Orientation;
+}
+
+export interface AriaTabListOptions<T> extends Omit<AriaTabListProps<T>, 'children'> {}
+
+export interface TabListAria {
+	/** Props for the tablist container. */
+	tabListProps: DOMAttributes;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a tab list.
+ * Tabs organize content into multiple sections and allow users to navigate between them.
+ */
+export function useTabList<T>(
+	props: AriaTabListOptions<T>,
+	state: TabListState<T>,
+	ref: RefObject<HTMLElement | null>,
+): TabListAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTabList<T>(
+	props: AriaTabListOptions<T>,
+	state: TabListState<T>,
+	ref: RefObject<HTMLElement | null>,
+	slot: symbol | undefined,
+): TabListAria;
+export function useTabList(...args: any[]): TabListAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTabList');
+	const props = user[0] as AriaTabListOptions<unknown>;
+	const state = user[1] as TabListState<unknown>;
+	const ref = user[2] as RefObject<HTMLElement | null>;
+
+	let { orientation = 'horizontal', keyboardActivation = 'automatic' } = props;
+	let { collection, selectionManager: manager, disabledKeys } = state;
+	let { direction } = useLocale(subSlot(slot, 'locale'));
+	let delegate = useMemo(
+		() => new TabsKeyboardDelegate(collection, direction, orientation, disabledKeys),
+		[collection, disabledKeys, orientation, direction],
+		subSlot(slot, 'delegate'),
+	);
+
+	let { collectionProps } = useSelectableCollection(
+		{
+			ref,
+			selectionManager: manager,
+			keyboardDelegate: delegate,
+			selectOnFocus: keyboardActivation === 'automatic',
+			disallowEmptySelection: true,
+			scrollRef: ref,
+			linkBehavior: 'selection',
+		},
+		subSlot(slot, 'collection'),
+	);
+
+	// Compute base id for all tabs
+	let tabsId = useId(subSlot(slot, 'tabsId'));
+	tabsIds.set(state, tabsId);
+
+	let tabListLabelProps = useLabels({ ...props, id: tabsId }, undefined, subSlot(slot, 'labels'));
+
+	return {
+		tabListProps: {
+			...mergeProps(collectionProps, tabListLabelProps),
+			role: 'tablist',
+			'aria-orientation': orientation,
+			tabIndex: undefined,
+		},
+	};
+}

package/src/tabs/useTabPanel.ts

@@ -0,0 +1,75 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/tabs/useTabPanel.ts).
+// octane adaptations: `DOMAttributes` is a local structural prop-bag alias (upstream's is
+// typed over React's synthetic handlers); `TabListState` from the ported stately tabs state;
+// public-hook slot threading (splitSlot/subSlot) per the binding convention.
+import type { AriaLabelingProps, DOMProps, Key, RefObject } from '@react-types/shared';
+import { generateId } from './utils';
+import { mergeProps } from '../utils/mergeProps';
+import type { TabListState } from '../stately/tabs/useTabListState';
+import { useHasTabbableChild } from '../focus/useHasTabbableChild';
+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 AriaTabPanelProps extends Omit<DOMProps, 'id'>, AriaLabelingProps {
+	/** The unique id of the tab. */
+	id?: Key;
+}
+
+export interface TabPanelAria {
+	/** Props for the tab panel element. */
+	tabPanelProps: DOMAttributes;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a tab panel. A tab panel is a
+ * container for the contents of a tab, and is shown when the tab is selected.
+ */
+export function useTabPanel<T>(
+	props: AriaTabPanelProps,
+	state: TabListState<T> | null,
+	ref: RefObject<Element | null>,
+): TabPanelAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTabPanel<T>(
+	props: AriaTabPanelProps,
+	state: TabListState<T> | null,
+	ref: RefObject<Element | null>,
+	slot: symbol | undefined,
+): TabPanelAria;
+export function useTabPanel(...args: any[]): TabPanelAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTabPanel');
+	const props = user[0] as AriaTabPanelProps;
+	const state = user[1] as TabListState<unknown> | null;
+	const ref = user[2] as RefObject<Element | null>;
+
+	// The tabpanel should have tabIndex=0 when there are no tabbable elements within it.
+	// Otherwise, tabbing from the focused tab should go directly to the first tabbable element
+	// within the tabpanel.
+	let tabIndex = useHasTabbableChild(ref, undefined, subSlot(slot, 'tabbable')) ? undefined : 0;
+
+	const id = generateId(state, props.id ?? state?.selectedKey, 'tabpanel');
+	const tabPanelProps = useLabels(
+		{
+			...props,
+			id,
+			'aria-labelledby': generateId(state, state?.selectedKey, 'tab'),
+		},
+		undefined,
+		subSlot(slot, 'labels'),
+	);
+
+	return {
+		tabPanelProps: mergeProps(tabPanelProps, {
+			tabIndex,
+			role: 'tabpanel',
+			'aria-describedby': props['aria-describedby'],
+			'aria-details': props['aria-details'],
+		}),
+	};
+}

package/src/tabs/utils.ts

@@ -0,0 +1,32 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/tabs/utils.ts).
+// octane adaptations: `TabListState` type from the ported stately tabs state (upstream:
+// 'react-stately/useTabListState').
+import type { Key } from '@react-types/shared';
+import type { TabListState } from '../stately/tabs/useTabListState';
+
+export const tabsIds: WeakMap<TabListState<unknown>, string> = new WeakMap<
+	TabListState<unknown>,
+	string
+>();
+
+export function generateId<T>(
+	state: TabListState<T> | null,
+	key: Key | null | undefined,
+	role: string,
+): string {
+	if (!state) {
+		// this case should only happen in the first render before the tabs are registered
+		return '';
+	}
+	if (typeof key === 'string') {
+		key = key.replace(/\s+/g, '');
+	}
+
+	let baseId = tabsIds.get(state);
+	if (process.env.NODE_ENV !== 'production' && !baseId) {
+		console.error(
+			'There is no tab id, please check if you have rendered the tab panel before the tab list.',
+		);
+	}
+	return `${baseId}-${role}-${key}`;
+}