@octanejs/aria 0.0.1 → 0.0.4

package/src/select/HiddenSelect.ts

@@ -0,0 +1,261 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/select/HiddenSelect.tsx).
+// octane adaptations:
+// - `.tsx` → `.ts`, JSX → `createElement` (from 'octane'); the plain-`.ts` component uses the
+//   S()/subSlot component-slot convention and `useRef` from 'octane' (slot-threaded).
+// - Native events: the hidden `<select>`'s change handler stays a real native `change`
+//   listener — `onChange` on a `<select>` is a genuine DOM change event, so it is kept as-is
+//   (NOT converted to `onInput`, which is reserved for TEXT inputs). Upstream's mirror
+//   `onInput: onChange` is retained; both are native handlers here. React's synthetic
+//   `ChangeEvent` type → `any`.
+// - `SelectionMode`/`SelectState` from the ported stately select state; `JSX.Element` → `any`.
+import type { FocusableElement, Key, RefObject } from '@react-types/shared';
+import { getEventTarget } from '../utils/shadowdom/DOMFunctions';
+import { createElement, useCallback, useRef } from 'octane';
+import { selectData } from './useSelect';
+import type { SelectionMode, SelectState } from '../stately/select/useSelectState';
+import { useFormReset } from '../utils/useFormReset';
+import { useFormValidation } from '../form/useFormValidation';
+import { useVisuallyHidden } from '../visually-hidden/VisuallyHidden';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export interface AriaHiddenSelectProps {
+	/**
+	 * Describes the type of autocomplete functionality the input should provide if any. See
+	 * [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete).
+	 */
+	autoComplete?: string;
+
+	/** The text label for the select. */
+	label?: any;
+
+	/** HTML form input name. */
+	name?: string;
+
+	/**
+	 * The `<form>` element to associate the input with.
+	 * The value of this attribute must be the id of a `<form>` in the same document.
+	 * See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).
+	 */
+	form?: string;
+
+	/** Sets the disabled state of the select and input. */
+	isDisabled?: boolean;
+}
+
+export interface HiddenSelectProps<
+	T,
+	M extends SelectionMode = 'single',
+> extends AriaHiddenSelectProps {
+	/** State for the select. */
+	state: SelectState<T, M>;
+
+	/** A ref to the trigger element. */
+	triggerRef: RefObject<FocusableElement | null>;
+}
+
+export interface AriaHiddenSelectOptions extends AriaHiddenSelectProps {
+	/** A ref to the hidden `<select>` element. */
+	selectRef?: RefObject<HTMLSelectElement | HTMLInputElement | null>;
+}
+
+export interface HiddenSelectAria {
+	/** Props for the container element. */
+	containerProps: Record<string, any>;
+
+	/** Props for the hidden input element. */
+	inputProps: Record<string, any>;
+
+	/** Props for the hidden select element. */
+	selectProps: Record<string, any>;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a hidden `<select>` element, which
+ * can be used in combination with `useSelect` to support browser form autofill, mobile form
+ * navigation, and native HTML form submission.
+ */
+export function useHiddenSelect<T, M extends SelectionMode = 'single'>(
+	props: AriaHiddenSelectOptions,
+	state: SelectState<T, M>,
+	triggerRef: RefObject<FocusableElement | null>,
+): HiddenSelectAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useHiddenSelect<T, M extends SelectionMode = 'single'>(
+	props: AriaHiddenSelectOptions,
+	state: SelectState<T, M>,
+	triggerRef: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): HiddenSelectAria;
+export function useHiddenSelect(...args: any[]): HiddenSelectAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useHiddenSelect');
+	const props = user[0] as AriaHiddenSelectOptions;
+	const state = user[1] as SelectState<any, any>;
+	const triggerRef = user[2] as RefObject<FocusableElement | null>;
+
+	let data = selectData.get(state) || {};
+	let { autoComplete, name = data.name, form = data.form, isDisabled = data.isDisabled } = props;
+	let { validationBehavior, isRequired } = data;
+	let { visuallyHiddenProps } = useVisuallyHidden(
+		{
+			style: {
+				// Prevent page scrolling.
+				position: 'fixed',
+				top: 0,
+				left: 0,
+			},
+		},
+		subSlot(slot, 'visuallyHidden'),
+	);
+
+	useFormReset(props.selectRef, state.defaultValue, state.setValue, subSlot(slot, 'formReset'));
+	useFormValidation(
+		{
+			validationBehavior,
+			focus: () => triggerRef.current?.focus(),
+		},
+		state,
+		props.selectRef,
+		subSlot(slot, 'formValidation'),
+	);
+
+	let setValue = state.setValue;
+	let onChange = useCallback(
+		(e: any) => {
+			let eventTarget = getEventTarget(e) as HTMLSelectElement;
+			if (eventTarget.multiple) {
+				setValue(Array.from(eventTarget.selectedOptions, (option) => option.value) as any);
+			} else {
+				setValue(e.currentTarget.value as any);
+			}
+		},
+		[setValue],
+		subSlot(slot, 'onChange'),
+	);
+
+	// In Safari, the <select> cannot have `display: none` or `hidden` for autofill to work.
+	// In Firefox, there must be a <label> to identify the <select> whereas other browsers
+	// seem to identify it just by surrounding text.
+	// The solution is to use <VisuallyHidden> to hide the elements, which clips the elements to a
+	// 1px rectangle. In addition, we hide from screen readers with aria-hidden, and make the <select>
+	// non tabbable with tabIndex={-1}.
+	return {
+		containerProps: {
+			...visuallyHiddenProps,
+			'aria-hidden': true,
+			['data-react-aria-prevent-focus']: true,
+			['data-a11y-ignore']: 'aria-hidden-focus',
+		},
+		inputProps: {
+			style: { display: 'none' },
+		},
+		selectProps: {
+			tabIndex: -1,
+			autoComplete,
+			disabled: isDisabled,
+			multiple: state.selectionManager.selectionMode === 'multiple',
+			required: validationBehavior === 'native' && isRequired,
+			name,
+			form,
+			value: (state.value as string | string[]) ?? '',
+			onChange,
+			onInput: onChange,
+		},
+	};
+}
+
+/**
+ * Renders a hidden native `<select>` element, which can be used to support browser
+ * form autofill, mobile form navigation, and native form submission.
+ */
+export function HiddenSelect<T, M extends SelectionMode = 'single'>(
+	props: HiddenSelectProps<T, M>,
+): any {
+	const slot = S('HiddenSelect');
+	let { state, triggerRef, label, name, form, isDisabled } = props;
+	let selectRef = useRef(null, subSlot(slot, 'selectRef'));
+	let inputRef = useRef(null, subSlot(slot, 'inputRef'));
+	let { containerProps, selectProps } = useHiddenSelect(
+		{ ...props, selectRef: state.collection.size <= 300 ? selectRef : inputRef },
+		state,
+		triggerRef,
+		subSlot(slot, 'hidden'),
+	);
+
+	let values: (Key | null)[] = Array.isArray(state.value) ? state.value : [state.value];
+
+	// If used in a <form>, use a hidden input so the value can be submitted to a server.
+	// If the collection isn't too big, use a hidden <select> element for this so that browser
+	// autofill will work. Otherwise, use an <input type="hidden">.
+	if (state.collection.size <= 300) {
+		let optionEls = [...state.collection.getKeys()].map((key) => {
+			let item = state.collection.getItem(key);
+			if (item && item.type === 'item') {
+				return createElement('option', { key: item.key, value: item.key }, item.textValue);
+			}
+			return undefined;
+		});
+
+		return createElement(
+			'div',
+			{ ...containerProps, 'data-testid': 'hidden-select-container' },
+			createElement(
+				'label',
+				null,
+				label,
+				createElement('select', { ...selectProps, ref: selectRef }, [
+					createElement('option', { key: '__empty__', value: '', label: '\u00A0' }, '\u00A0'),
+					optionEls,
+					// The collection may be empty during the initial render.
+					// Rendering options for the current values ensures the select has a value immediately,
+					// making FormData reads consistent.
+					state.collection.size === 0 && name
+						? values.map((value, i) => createElement('option', { key: i, value: value ?? '' }))
+						: null,
+				]),
+			),
+		);
+	} else if (name) {
+		let data = selectData.get(state) || {};
+		let { validationBehavior } = data;
+
+		// Always render at least one hidden input to ensure required form submission.
+		if (values.length === 0) {
+			values = [null];
+		}
+
+		let res = values.map((value, i) => {
+			let inputProps: Record<string, any> = {
+				type: 'hidden',
+				autoComplete: selectProps.autoComplete,
+				name,
+				form,
+				disabled: isDisabled,
+				value: value ?? '',
+			};
+
+			if (validationBehavior === 'native') {
+				// Use a hidden <input type="text"> rather than <input type="hidden">
+				// so that an empty value blocks HTML form submission when the field is required.
+				return createElement('input', {
+					key: i,
+					...inputProps,
+					ref: i === 0 ? inputRef : null,
+					style: { display: 'none' },
+					type: 'text',
+					required: i === 0 ? selectProps.required : false,
+					onChange: () => {
+						/** Ignore react warning. */
+					},
+				});
+			}
+
+			return createElement('input', { key: i, ...inputProps, ref: i === 0 ? inputRef : null });
+		});
+
+		return res;
+	}
+
+	return null;
+}

package/src/select/useSelect.ts

@@ -0,0 +1,332 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/select/useSelect.ts).
+// octane adaptations:
+// - `useMemo` comes from 'octane'; React's synthetic `FocusEvent` type → `any` (native
+//   focus/blur events are passed straight through).
+// - `SelectionMode`/`SelectProps`/`SelectState` from the ported stately select state
+//   (`../stately/select/useSelectState`).
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention: every
+//   composed base/sibling hook (useCollator, useMemo, useMenuTrigger, useTypeSelect,
+//   useField, useId) receives an explicit derived sub-slot.
+// - `selectData` WeakMap is exported for HiddenSelect to read the shared disabled/name/
+//   form/validationBehavior data.
+import type { AriaButtonProps } from '../button/useButton';
+
+import type {
+	AriaLabelingProps,
+	DOMAttributes,
+	DOMProps,
+	FocusableDOMProps,
+	KeyboardDelegate,
+	RefObject,
+	ValidationResult,
+} from '@react-types/shared';
+import type { AriaListBoxOptions } from '../listbox/useListBox';
+import { chain } from '../utils/chain';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { useMemo } from 'octane';
+import type { HiddenSelectProps } from './HiddenSelect';
+import { ListKeyboardDelegate } from '../selection/ListKeyboardDelegate';
+import { mergeProps } from '../utils/mergeProps';
+import { nodeContains } from '../utils/shadowdom/DOMFunctions';
+import type { SelectionMode, SelectProps, SelectState } from '../stately/select/useSelectState';
+import { setInteractionModality } from '../interactions/useFocusVisible';
+import { useCollator } from '../i18n/useCollator';
+import { useField } from '../label/useField';
+import { useId } from '../utils/useId';
+import { useMenuTrigger } from '../menu/useMenuTrigger';
+import { useTypeSelect } from '../selection/useTypeSelect';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export interface AriaSelectProps<T, M extends SelectionMode = 'single'>
+	extends SelectProps<T, M>, DOMProps, AriaLabelingProps, FocusableDOMProps {
+	/**
+	 * Describes the type of autocomplete functionality the input should provide if any. See
+	 * [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete).
+	 */
+	autoComplete?: string;
+	/**
+	 * The name of the input, used when submitting an HTML form.
+	 */
+	name?: string;
+	/**
+	 * The `<form>` element to associate the input with.
+	 * The value of this attribute must be the id of a `<form>` in the same document.
+	 * See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).
+	 */
+	form?: string;
+}
+
+export interface AriaSelectOptions<T, M extends SelectionMode = 'single'> extends Omit<
+	AriaSelectProps<T, M>,
+	'children'
+> {
+	/**
+	 * An optional keyboard delegate implementation for type to select,
+	 * to override the default.
+	 */
+	keyboardDelegate?: KeyboardDelegate;
+}
+
+export interface SelectAria<T, M extends SelectionMode = 'single'> extends ValidationResult {
+	/** Props for the label element. */
+	labelProps: DOMAttributes;
+
+	/** Props for the popup trigger element. */
+	triggerProps: AriaButtonProps;
+
+	/** Props for the element representing the selected value. */
+	valueProps: DOMAttributes;
+
+	/** Props for the popup. */
+	menuProps: AriaListBoxOptions<T>;
+
+	/** Props for the select's description element, if any. */
+	descriptionProps: DOMAttributes;
+
+	/** Props for the select's error message element, if any. */
+	errorMessageProps: DOMAttributes;
+
+	/** Props for the hidden select element. */
+	hiddenSelectProps: HiddenSelectProps<T, M>;
+}
+
+interface SelectData {
+	isDisabled?: boolean;
+	isRequired?: boolean;
+	name?: string;
+	form?: string;
+	validationBehavior?: 'aria' | 'native';
+}
+
+export const selectData: WeakMap<SelectState<any, any>, SelectData> = new WeakMap<
+	SelectState<any>,
+	SelectData
+>();
+
+/**
+ * Provides the behavior and accessibility implementation for a select component.
+ * A select displays a collapsible list of options and allows a user to select one of them.
+ *
+ * @param props - Props for the select.
+ * @param state - State for the select, as returned by `useListState`.
+ */
+export function useSelect<T, M extends SelectionMode = 'single'>(
+	props: AriaSelectOptions<T, M>,
+	state: SelectState<T, M>,
+	ref: RefObject<HTMLElement | null>,
+): SelectAria<T, M>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSelect<T, M extends SelectionMode = 'single'>(
+	props: AriaSelectOptions<T, M>,
+	state: SelectState<T, M>,
+	ref: RefObject<HTMLElement | null>,
+	slot: symbol | undefined,
+): SelectAria<T, M>;
+export function useSelect(...args: any[]): SelectAria<any, any> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSelect');
+	const props = user[0] as AriaSelectOptions<any, any>;
+	const state = user[1] as SelectState<any, any>;
+	const ref = user[2] as RefObject<HTMLElement | null>;
+
+	let { keyboardDelegate, isDisabled, isRequired, name, form, validationBehavior = 'aria' } = 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 delegate = useMemo(
+		() =>
+			keyboardDelegate ||
+			new ListKeyboardDelegate(state.collection, state.disabledKeys, ref, collator),
+		[keyboardDelegate, state.collection, state.disabledKeys, collator, ref],
+		subSlot(slot, 'delegate'),
+	);
+
+	let { menuTriggerProps, menuProps } = useMenuTrigger(
+		{
+			isDisabled,
+			type: 'listbox',
+		},
+		state,
+		ref,
+		subSlot(slot, 'menuTrigger'),
+	);
+
+	let onKeyDown = (e: KeyboardEvent) => {
+		if (state.selectionManager.selectionMode === 'multiple') {
+			return;
+		}
+
+		switch (e.key) {
+			case 'ArrowLeft': {
+				// prevent scrolling containers
+				e.preventDefault();
+
+				let key =
+					state.selectedKey != null
+						? delegate.getKeyAbove?.(state.selectedKey)
+						: delegate.getFirstKey?.();
+				if (key != null) {
+					state.setSelectedKey(key);
+				}
+				break;
+			}
+			case 'ArrowRight': {
+				// prevent scrolling containers
+				e.preventDefault();
+
+				let key =
+					state.selectedKey != null
+						? delegate.getKeyBelow?.(state.selectedKey)
+						: delegate.getFirstKey?.();
+				if (key != null) {
+					state.setSelectedKey(key);
+				}
+				break;
+			}
+		}
+	};
+
+	let { typeSelectProps } = useTypeSelect(
+		{
+			keyboardDelegate: delegate,
+			selectionManager: state.selectionManager,
+			onTypeSelect(key) {
+				state.setSelectedKey(key);
+			},
+		},
+		subSlot(slot, 'typeSelect'),
+	);
+
+	let { isInvalid, validationErrors, validationDetails } = state.displayValidation;
+	let { labelProps, fieldProps, descriptionProps, errorMessageProps } = useField(
+		{
+			...props,
+			labelElementType: 'span',
+			isInvalid,
+			errorMessage: props.errorMessage || validationErrors,
+		},
+		subSlot(slot, 'field'),
+	);
+
+	if (state.selectionManager.selectionMode === 'multiple') {
+		typeSelectProps = {};
+	}
+
+	let domProps = filterDOMProps(props, { labelable: true });
+	let triggerProps = mergeProps(typeSelectProps, menuTriggerProps, fieldProps);
+
+	let valueId = useId(subSlot(slot, 'valueId'));
+
+	selectData.set(state, {
+		isDisabled,
+		isRequired,
+		name,
+		form,
+		validationBehavior,
+	});
+
+	return {
+		labelProps: {
+			...labelProps,
+			onClick: () => {
+				if (!props.isDisabled) {
+					ref.current?.focus();
+
+					// Show the focus ring so the user knows where focus went
+					setInteractionModality('keyboard');
+				}
+			},
+		},
+		triggerProps: mergeProps(domProps, {
+			...triggerProps,
+			isDisabled,
+			onKeyDown: chain(triggerProps.onKeyDown, onKeyDown, props.onKeyDown),
+			onKeyUp: props.onKeyUp,
+			'aria-labelledby': [
+				valueId,
+				triggerProps['aria-labelledby'],
+				triggerProps['aria-label'] && !triggerProps['aria-labelledby'] ? triggerProps.id : null,
+			]
+				.filter(Boolean)
+				.join(' '),
+			onFocus(e: any) {
+				if (state.isFocused) {
+					return;
+				}
+
+				if (props.onFocus) {
+					props.onFocus(e);
+				}
+
+				if (props.onFocusChange) {
+					props.onFocusChange(true);
+				}
+
+				state.setFocused(true);
+			},
+			onBlur(e: any) {
+				if (state.isOpen) {
+					return;
+				}
+
+				if (props.onBlur) {
+					props.onBlur(e);
+				}
+
+				if (props.onFocusChange) {
+					props.onFocusChange(false);
+				}
+
+				state.setFocused(false);
+			},
+		}),
+		valueProps: {
+			id: valueId,
+		},
+		menuProps: {
+			...menuProps,
+			onAction: undefined,
+			autoFocus: state.focusStrategy || true,
+			shouldSelectOnPressUp: true,
+			shouldFocusOnHover: true,
+			disallowEmptySelection: true,
+			linkBehavior: 'selection',
+			onBlur: (e: any) => {
+				if (nodeContains(e.currentTarget, e.relatedTarget as Node)) {
+					return;
+				}
+
+				if (props.onBlur) {
+					props.onBlur(e);
+				}
+
+				if (props.onFocusChange) {
+					props.onFocusChange(false);
+				}
+
+				state.setFocused(false);
+			},
+			'aria-labelledby': [
+				fieldProps['aria-labelledby'],
+				triggerProps['aria-label'] && !fieldProps['aria-labelledby'] ? triggerProps.id : null,
+			]
+				.filter(Boolean)
+				.join(' '),
+		},
+		descriptionProps,
+		errorMessageProps,
+		isInvalid,
+		validationErrors,
+		validationDetails,
+		hiddenSelectProps: {
+			isDisabled,
+			name,
+			label: props.label,
+			state,
+			triggerRef: ref,
+			form,
+		},
+	};
+}

package/src/selection/DOMLayoutDelegate.ts

@@ -0,0 +1,51 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/selection/DOMLayoutDelegate.ts).
+// Verbatim (no React surface); RefObject type from @react-types/shared.
+import { getItemElement } from './utils';
+import type { Key, LayoutDelegate, Rect, RefObject, Size } from '@react-types/shared';
+
+export class DOMLayoutDelegate implements LayoutDelegate {
+	private ref: RefObject<HTMLElement | null>;
+
+	constructor(ref: RefObject<HTMLElement | null>) {
+		this.ref = ref;
+	}
+
+	getItemRect(key: Key): Rect | null {
+		let container = this.ref.current;
+		if (!container) {
+			return null;
+		}
+		let item = key != null ? getItemElement(this.ref, key) : null;
+		if (!item) {
+			return null;
+		}
+
+		let containerRect = container.getBoundingClientRect();
+		let itemRect = item.getBoundingClientRect();
+
+		return {
+			x: itemRect.left - containerRect.left - container.clientLeft + container.scrollLeft,
+			y: itemRect.top - containerRect.top - container.clientTop + container.scrollTop,
+			width: itemRect.width,
+			height: itemRect.height,
+		};
+	}
+
+	getContentSize(): Size {
+		let container = this.ref.current;
+		return {
+			width: container?.scrollWidth ?? 0,
+			height: container?.scrollHeight ?? 0,
+		};
+	}
+
+	getVisibleRect(): Rect {
+		let container = this.ref.current;
+		return {
+			x: container?.scrollLeft ?? 0,
+			y: container?.scrollTop ?? 0,
+			width: container?.clientWidth ?? 0,
+			height: container?.clientHeight ?? 0,
+		};
+	}
+}