@octanejs/aria 0.0.1 → 0.0.3

package/src/listbox/useOption.ts

@@ -0,0 +1,212 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/listbox/useOption.ts).
+// octane adaptations:
+// - `DOMAttributes` is a local structural prop-bag alias (upstream's is typed over React's
+//   synthetic handlers); `optionProps` is typed as that bag so the virtualized
+//   `aria-posinset`/`aria-setsize` assignments type-check.
+// - `getItemCount` / `ListState` from the ported stately collections/list.
+// - 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 { chain } from '../utils/chain';
+
+import type { FocusableElement, Key, RefObject } from '@react-types/shared';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { getItemCount } from '../stately/collections/getItemCount';
+import { getItemId, listData } from './utils';
+import { isFocusVisible } from '../interactions/useFocusVisible';
+import type { ListState } from '../stately/list/useListState';
+import { mergeProps } from '../utils/mergeProps';
+import { type SelectableItemStates, useSelectableItem } from '../selection/useSelectableItem';
+import { useHover } from '../interactions/useHover';
+import { useLinkProps } from '../utils/openLink';
+import { useSlotId } from '../utils/useId';
+
+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 OptionAria extends SelectableItemStates {
+	/** Props for the option element. */
+	optionProps: DOMAttributes;
+
+	/** Props for the main text element inside the option. */
+	labelProps: DOMAttributes;
+
+	/** Props for the description text element inside the option, if any. */
+	descriptionProps: DOMAttributes;
+
+	/** Whether the option is currently focused. */
+	isFocused: boolean;
+
+	/** Whether the option is keyboard focused. */
+	isFocusVisible: boolean;
+}
+
+export interface AriaOptionProps {
+	/**
+	 * Whether the option is disabled.
+	 *
+	 * @deprecated
+	 */
+	isDisabled?: boolean;
+
+	/**
+	 * Whether the option is selected.
+	 *
+	 * @deprecated
+	 */
+	isSelected?: boolean;
+
+	/** A screen reader only label for the option. */
+	'aria-label'?: string;
+
+	/** The unique key for the option. */
+	key: Key;
+
+	/**
+	 * Whether selection should occur on press up instead of press down.
+	 *
+	 * @deprecated
+	 */
+	shouldSelectOnPressUp?: boolean;
+
+	/**
+	 * Whether the option should be focused when the user hovers over it.
+	 *
+	 * @deprecated
+	 */
+	shouldFocusOnHover?: boolean;
+
+	/**
+	 * Whether the option is contained in a virtual scrolling listbox.
+	 *
+	 * @deprecated
+	 */
+	isVirtualized?: boolean;
+
+	/**
+	 * Whether the option should use virtual focus instead of being focused directly.
+	 *
+	 * @deprecated
+	 */
+	shouldUseVirtualFocus?: boolean;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for an option in a listbox.
+ * See `useListBox` for more details about listboxes.
+ *
+ * @param props - Props for the option.
+ * @param state - State for the listbox, as returned by `useListState`.
+ */
+export function useOption<T>(
+	props: AriaOptionProps,
+	state: ListState<T>,
+	ref: RefObject<FocusableElement | null>,
+): OptionAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useOption<T>(
+	props: AriaOptionProps,
+	state: ListState<T>,
+	ref: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): OptionAria;
+export function useOption(...args: any[]): OptionAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useOption');
+	const props = user[0] as AriaOptionProps;
+	const state = user[1] as ListState<unknown>;
+	const ref = user[2] as RefObject<FocusableElement | null>;
+
+	let { key } = props;
+
+	let data = listData.get(state);
+
+	let isDisabled = props.isDisabled ?? state.selectionManager.isDisabled(key);
+	let isSelected = props.isSelected ?? state.selectionManager.isSelected(key);
+	let shouldSelectOnPressUp = props.shouldSelectOnPressUp ?? data?.shouldSelectOnPressUp;
+	let shouldFocusOnHover = props.shouldFocusOnHover ?? data?.shouldFocusOnHover;
+	let shouldUseVirtualFocus = props.shouldUseVirtualFocus ?? data?.shouldUseVirtualFocus;
+	let isVirtualized = props.isVirtualized ?? data?.isVirtualized;
+
+	let labelId = useSlotId(undefined, subSlot(slot, 'labelId'));
+	let descriptionId = useSlotId(undefined, subSlot(slot, 'descriptionId'));
+
+	let optionProps: DOMAttributes = {
+		role: 'option',
+		'aria-disabled': isDisabled || undefined,
+		'aria-selected': state.selectionManager.selectionMode !== 'none' ? isSelected : undefined,
+		'aria-label': props['aria-label'],
+		'aria-labelledby': labelId,
+		'aria-describedby': descriptionId,
+	};
+
+	let item = state.collection.getItem(key);
+	if (isVirtualized) {
+		let index = Number(item?.index);
+		optionProps['aria-posinset'] = Number.isNaN(index) ? undefined : index + 1;
+		optionProps['aria-setsize'] = getItemCount(state.collection);
+	}
+
+	let onAction = data?.onAction ? () => data?.onAction?.(key) : undefined;
+	let id = getItemId(state, key);
+	let { itemProps, isPressed, isFocused, hasAction, allowsSelection } = useSelectableItem(
+		{
+			selectionManager: state.selectionManager,
+			key,
+			ref,
+			shouldSelectOnPressUp,
+			allowsDifferentPressOrigin: shouldSelectOnPressUp && shouldFocusOnHover,
+			isVirtualized,
+			shouldUseVirtualFocus,
+			isDisabled,
+			onAction:
+				onAction || item?.props?.onAction ? chain(item?.props?.onAction, onAction) : undefined,
+			linkBehavior: data?.linkBehavior,
+			// @ts-ignore
+			UNSTABLE_itemBehavior: data?.['UNSTABLE_itemBehavior'],
+			id,
+		},
+		subSlot(slot, 'item'),
+	);
+
+	let { hoverProps } = useHover(
+		{
+			isDisabled: isDisabled || !shouldFocusOnHover,
+			onHoverStart() {
+				if (!isFocusVisible()) {
+					state.selectionManager.setFocused(true);
+					state.selectionManager.setFocusedKey(key);
+				}
+			},
+		},
+		subSlot(slot, 'hover'),
+	);
+
+	let domProps = filterDOMProps(item?.props);
+	delete domProps.id;
+	let linkProps = useLinkProps(item?.props);
+
+	return {
+		optionProps: {
+			...optionProps,
+			...mergeProps(domProps, itemProps, hoverProps, linkProps),
+			id,
+		},
+		labelProps: {
+			id: labelId,
+		},
+		descriptionProps: {
+			id: descriptionId,
+		},
+		isFocused,
+		isFocusVisible: isFocused && state.selectionManager.isFocused && isFocusVisible(),
+		isSelected,
+		isDisabled,
+		isPressed,
+		allowsSelection,
+		hasAction,
+	};
+}

package/src/listbox/utils.ts

@@ -0,0 +1,38 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/listbox/utils.ts).
+// octane adaptations: `ListState` type from the ported stately list state (upstream:
+// 'react-stately/useListState').
+import type { Key } from '@react-types/shared';
+import type { ListState } from '../stately/list/useListState';
+
+interface ListData {
+	id?: string;
+	shouldSelectOnPressUp?: boolean;
+	shouldFocusOnHover?: boolean;
+	shouldUseVirtualFocus?: boolean;
+	isVirtualized?: boolean;
+	onAction?: (key: Key) => void;
+	linkBehavior?: 'action' | 'selection' | 'override';
+}
+
+export const listData: WeakMap<ListState<unknown>, ListData> = new WeakMap<
+	ListState<unknown>,
+	ListData
+>();
+
+function normalizeKey(key: Key): string {
+	if (typeof key === 'string') {
+		return key.replace(/\s*/g, '');
+	}
+
+	return '' + key;
+}
+
+export function getItemId<T>(state: ListState<T>, itemKey: Key): string {
+	let data = listData.get(state);
+
+	if (!data) {
+		throw new Error('Unknown list');
+	}
+
+	return `${data.id}-option-${normalizeKey(itemKey)}`;
+}

package/src/live-announcer/LiveAnnouncer.ts

@@ -0,0 +1,172 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/live-announcer/LiveAnnouncer.tsx).
+// octane adaptations:
+// - This is a plain-DOM utility upstream too (no React), so the port is verbatim apart
+//   from the test-environment probe: upstream checks React's IS_REACT_ACT_ENVIRONMENT /
+//   the jest global to skip the Safari announce delay under test; octane's suite runs
+//   under vitest, so the probe also treats a defined `process.env.VITEST` as a test
+//   environment. The 100ms first-announce delay for real browsers is preserved.
+// - `.tsx` → `.ts` (there was never any JSX in the file).
+
+type Assertiveness = 'assertive' | 'polite';
+
+/* Inspired by https://github.com/AlmeroSteyn/react-aria-live */
+const LIVEREGION_TIMEOUT_DELAY = 7000;
+
+let liveAnnouncer: LiveAnnouncer | null = null;
+
+type Message = string | { 'aria-labelledby': string };
+
+function isTestEnvironment(): boolean {
+	const g = globalThis as any;
+	if (typeof g.IS_REACT_ACT_ENVIRONMENT === 'boolean') {
+		return g.IS_REACT_ACT_ENVIRONMENT;
+	}
+	return typeof g.jest !== 'undefined' || g.process?.env?.VITEST !== undefined;
+}
+
+/**
+ * Announces the message using screen reader technology.
+ */
+export function announce(
+	message: Message,
+	assertiveness: Assertiveness = 'assertive',
+	timeout: number = LIVEREGION_TIMEOUT_DELAY,
+): void {
+	if (!liveAnnouncer) {
+		liveAnnouncer = new LiveAnnouncer();
+		// wait for the live announcer regions to be added to the dom, then announce
+		// otherwise Safari won't announce the message if it's added too quickly
+		// found most times less than 100ms were not consistent when announcing with Safari
+
+		// if we're in a test environment, announce without waiting
+		if (!isTestEnvironment()) {
+			setTimeout(() => {
+				if (liveAnnouncer?.isAttached()) {
+					liveAnnouncer?.announce(message, assertiveness, timeout);
+				}
+			}, 100);
+		} else {
+			liveAnnouncer.announce(message, assertiveness, timeout);
+		}
+	} else {
+		liveAnnouncer.announce(message, assertiveness, timeout);
+	}
+}
+
+/**
+ * Stops all queued announcements.
+ */
+export function clearAnnouncer(assertiveness: Assertiveness): void {
+	if (liveAnnouncer) {
+		liveAnnouncer.clear(assertiveness);
+	}
+}
+
+/**
+ * Removes the announcer from the DOM.
+ */
+export function destroyAnnouncer(): void {
+	if (liveAnnouncer) {
+		liveAnnouncer.destroy();
+		liveAnnouncer = null;
+	}
+}
+
+// LiveAnnouncer is implemented using vanilla DOM, not the framework. Upstream keeps it
+// framework-free so the global announce() API works without a root or portal; the same
+// reasoning applies verbatim in octane.
+class LiveAnnouncer {
+	node: HTMLElement | null = null;
+	assertiveLog: HTMLElement | null = null;
+	politeLog: HTMLElement | null = null;
+
+	constructor() {
+		if (typeof document !== 'undefined') {
+			this.node = document.createElement('div');
+			this.node.dataset.liveAnnouncer = 'true';
+			// copied from VisuallyHidden
+			Object.assign(this.node.style, {
+				border: 0,
+				clip: 'rect(0 0 0 0)',
+				clipPath: 'inset(50%)',
+				height: '1px',
+				margin: '-1px',
+				overflow: 'hidden',
+				padding: 0,
+				position: 'absolute',
+				width: '1px',
+				whiteSpace: 'nowrap',
+			});
+
+			this.assertiveLog = this.createLog('assertive');
+			this.node.appendChild(this.assertiveLog);
+
+			this.politeLog = this.createLog('polite');
+			this.node.appendChild(this.politeLog);
+
+			document.body.prepend(this.node);
+		}
+	}
+
+	isAttached() {
+		return this.node?.isConnected;
+	}
+
+	createLog(ariaLive: string) {
+		let node = document.createElement('div');
+		node.setAttribute('role', 'log');
+		node.setAttribute('aria-live', ariaLive);
+		node.setAttribute('aria-relevant', 'additions');
+		return node;
+	}
+
+	destroy() {
+		if (!this.node) {
+			return;
+		}
+
+		document.body.removeChild(this.node);
+		this.node = null;
+	}
+
+	announce(message: Message, assertiveness = 'assertive', timeout = LIVEREGION_TIMEOUT_DELAY) {
+		if (!this.node) {
+			return;
+		}
+
+		let node = document.createElement('div');
+		if (typeof message === 'object') {
+			// To read an aria-labelledby, the element must have an appropriate role, such as img.
+			node.setAttribute('role', 'img');
+			node.setAttribute('aria-labelledby', message['aria-labelledby']);
+		} else {
+			node.textContent = message;
+		}
+
+		if (assertiveness === 'assertive') {
+			this.assertiveLog?.appendChild(node);
+		} else {
+			this.politeLog?.appendChild(node);
+		}
+
+		if (message !== '') {
+			setTimeout(() => {
+				node.remove();
+			}, timeout);
+		}
+	}
+
+	clear(assertiveness: Assertiveness) {
+		if (!this.node) {
+			return;
+		}
+
+		if ((!assertiveness || assertiveness === 'assertive') && this.assertiveLog) {
+			this.assertiveLog.innerHTML = '';
+		}
+
+		if ((!assertiveness || assertiveness === 'polite') && this.politeLog) {
+			this.politeLog.innerHTML = '';
+		}
+	}
+}

package/src/menu/useMenu.ts

@@ -0,0 +1,139 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/menu/useMenu.ts).
+// octane adaptations:
+// - `KeyboardEvents` is the ported NATIVE-event version (from useKeyboard); the menu-level
+//   onKeyDown wrapper receives the native KeyboardEvent; `DOMAttributes` is a local
+//   structural prop-bag alias (upstream's is typed over React's synthetic handlers).
+// - `TreeState` type from the ported stately tree state.
+// - The dev-only missing-label console.warn is not ported (repo policy, per useLabel).
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention.
+import type {
+	AriaLabelingProps,
+	CollectionBase,
+	DOMProps,
+	FocusStrategy,
+	Key,
+	KeyboardDelegate,
+	MultipleSelection,
+	RefObject,
+} from '@react-types/shared';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import type { KeyboardEvents } from '../interactions/useKeyboard';
+import { menuData } from './utils';
+import { mergeProps } from '../utils/mergeProps';
+import type { TreeState } from '../stately/tree/useTreeState';
+import { useSelectableList } from '../selection/useSelectableList';
+
+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 MenuProps<T> extends CollectionBase<T>, MultipleSelection {
+	/** Where the focus should be set. */
+	autoFocus?: boolean | FocusStrategy;
+	/** Whether keyboard navigation is circular. */
+	shouldFocusWrap?: boolean;
+	/** Handler that is called when an item is selected. */
+	onAction?: (key: Key, value: T) => void;
+	/** Handler that is called when the menu should close after selecting an item. */
+	onClose?: () => void;
+}
+
+export interface AriaMenuProps<T> extends MenuProps<T>, DOMProps, AriaLabelingProps {
+	/**
+	 * Whether pressing the escape key should clear selection in the menu 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';
+}
+
+export interface MenuAria {
+	/** Props for the menu element. */
+	menuProps: DOMAttributes;
+}
+
+export interface AriaMenuOptions<T> extends Omit<AriaMenuProps<T>, 'children'>, KeyboardEvents {
+	/** Whether the menu uses virtual scrolling. */
+	isVirtualized?: boolean;
+	/**
+	 * An optional keyboard delegate implementation for type to select,
+	 * to override the default.
+	 */
+	keyboardDelegate?: KeyboardDelegate;
+	/**
+	 * Whether the menu items should use virtual focus instead of being focused directly.
+	 */
+	shouldUseVirtualFocus?: boolean;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a menu component.
+ * A menu displays a list of actions or options that a user can choose.
+ *
+ * @param props - Props for the menu.
+ * @param state - State for the menu, as returned by `useListState`.
+ */
+export function useMenu<T>(
+	props: AriaMenuOptions<T>,
+	state: TreeState<T>,
+	ref: RefObject<HTMLElement | null>,
+): MenuAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useMenu<T>(
+	props: AriaMenuOptions<T>,
+	state: TreeState<T>,
+	ref: RefObject<HTMLElement | null>,
+	slot: symbol | undefined,
+): MenuAria;
+export function useMenu(...args: any[]): MenuAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useMenu');
+	const props = user[0] as AriaMenuOptions<unknown>;
+	const state = user[1] as TreeState<unknown>;
+	const ref = user[2] as RefObject<HTMLElement | null>;
+
+	let { shouldFocusWrap = true, onKeyDown, onKeyUp, ...otherProps } = props;
+
+	let domProps = filterDOMProps(props, { labelable: true });
+	let { listProps } = useSelectableList(
+		{
+			...otherProps,
+			ref,
+			selectionManager: state.selectionManager,
+			collection: state.collection,
+			disabledKeys: state.disabledKeys,
+			shouldFocusWrap,
+			linkBehavior: 'override',
+		},
+		subSlot(slot, 'list'),
+	);
+
+	menuData.set(state, {
+		onClose: props.onClose,
+		onAction: props.onAction,
+		shouldUseVirtualFocus: props.shouldUseVirtualFocus,
+	});
+
+	return {
+		menuProps: mergeProps(
+			domProps,
+			{ onKeyDown, onKeyUp },
+			{
+				role: 'menu',
+				...listProps,
+				onKeyDown: (e: KeyboardEvent) => {
+					// don't clear the menu selected keys if the user is presses escape since escape closes the menu
+					if (e.key !== 'Escape' || props.shouldUseVirtualFocus) {
+						listProps.onKeyDown?.(e);
+					}
+				},
+			},
+		),
+	};
+}