@octanejs/aria 0.0.1 → 0.0.4

package/src/focus/useFocusRing.ts

@@ -0,0 +1,125 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/focus/useFocusRing.ts).
+// octane adaptations:
+// - `DOMAttributes` from '@react-types/shared' drags React attribute types; a local
+//   structural alias replaces it (the focus props are octane NATIVE delegated event props).
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention; sibling
+//   ported hooks (useFocus, useFocusWithin, useFocusVisibleListener) are called with a
+//   trailing `subSlot(slot, ...)`. Explicit dep arrays are preserved exactly.
+
+import { useCallback, useRef, useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { isFocusVisible, useFocusVisibleListener } from '../interactions/useFocusVisible';
+import { useFocus } from '../interactions/useFocus';
+import { useFocusWithin } from '../interactions/useFocusWithin';
+
+// octane adaptation: minimal structural DOMAttributes (upstream's drags React attribute types).
+export type DOMAttributes = Record<string, any>;
+
+export interface AriaFocusRingProps {
+	/**
+	 * Whether to show the focus ring when something
+	 * inside the container element has focus (true), or
+	 * only if the container itself has focus (false).
+	 *
+	 * @default 'false'
+	 */
+	within?: boolean;
+
+	/** Whether the element is a text input. */
+	isTextInput?: boolean;
+
+	/** Whether the element will be auto focused. */
+	autoFocus?: boolean;
+}
+
+export interface FocusRingAria {
+	/** Whether the element is currently focused. */
+	isFocused: boolean;
+
+	/** Whether keyboard focus should be visible. */
+	isFocusVisible: boolean;
+
+	/** Props to apply to the container element with the focus ring. */
+	focusProps: DOMAttributes;
+}
+
+/**
+ * Determines whether a focus ring should be shown to indicate keyboard focus.
+ * Focus rings are visible only when the user is interacting with a keyboard,
+ * not with a mouse, touch, or other input methods.
+ */
+export function useFocusRing(props?: AriaFocusRingProps): FocusRingAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useFocusRing(
+	props: AriaFocusRingProps | undefined,
+	slot: symbol | undefined,
+): FocusRingAria;
+export function useFocusRing(...args: any[]): FocusRingAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useFocusRing');
+	const props = (user[0] as AriaFocusRingProps) ?? {};
+
+	let { autoFocus = false, isTextInput, within } = props;
+	let state = useRef(
+		{
+			isFocused: false,
+			isFocusVisible: autoFocus || isFocusVisible(),
+		},
+		subSlot(slot, 'state'),
+	);
+	let [isFocused, setFocused] = useState(false, subSlot(slot, 'focused'));
+	let [isFocusVisibleState, setFocusVisible] = useState(
+		() => state.current.isFocused && state.current.isFocusVisible,
+		subSlot(slot, 'visible'),
+	);
+
+	let updateState = useCallback(
+		() => setFocusVisible(state.current.isFocused && state.current.isFocusVisible),
+		[],
+		subSlot(slot, 'update'),
+	);
+
+	let onFocusChange = useCallback(
+		(isFocused: boolean) => {
+			state.current.isFocused = isFocused;
+			state.current.isFocusVisible = isFocusVisible();
+			setFocused(isFocused);
+			updateState();
+		},
+		[updateState],
+		subSlot(slot, 'change'),
+	);
+
+	useFocusVisibleListener(
+		(isFocusVisible) => {
+			state.current.isFocusVisible = isFocusVisible;
+			updateState();
+		},
+		[isTextInput, isFocused],
+		{ enabled: isFocused, isTextInput },
+		subSlot(slot, 'listener'),
+	);
+
+	let { focusProps } = useFocus(
+		{
+			isDisabled: within,
+			onFocusChange,
+		},
+		subSlot(slot, 'focus'),
+	);
+
+	let { focusWithinProps } = useFocusWithin(
+		{
+			isDisabled: !within,
+			onFocusWithinChange: onFocusChange,
+		},
+		subSlot(slot, 'within'),
+	);
+
+	return {
+		isFocused,
+		isFocusVisible: isFocusVisibleState,
+		focusProps: within ? focusWithinProps : focusProps,
+	};
+}

package/src/focus/useHasTabbableChild.ts

@@ -0,0 +1,82 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/focus/useHasTabbableChild.ts).
+// octane adaptations:
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention.
+// - Upstream's no-deps `useLayoutEffect` (re-runs after every render) becomes an explicit
+//   `null` deps argument — octane's convention for run-every-render effects.
+
+import { getFocusableTreeWalker } from './FocusScope';
+import type { RefObject } from '@react-types/shared';
+import { useState } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useLayoutEffect } from '../utils/useLayoutEffect';
+
+interface AriaHasTabbableChildOptions {
+	isDisabled?: boolean;
+}
+
+// This was created for a special empty case of a component that can have child or
+// be empty, like Collection/Virtualizer/Table/ListView/etc. When these components
+// are empty they can have a message with a tabbable element, which is like them
+// being not empty, when it comes to focus and tab order.
+
+/**
+ * Returns whether an element has a tabbable child, and updates as children change.
+ *
+ * @private
+ */
+export function useHasTabbableChild(
+	ref: RefObject<Element | null>,
+	options?: AriaHasTabbableChildOptions,
+): boolean;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useHasTabbableChild(
+	ref: RefObject<Element | null>,
+	options: AriaHasTabbableChildOptions | undefined,
+	slot: symbol | undefined,
+): boolean;
+export function useHasTabbableChild(...args: any[]): boolean {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useHasTabbableChild');
+	const ref = user[0] as RefObject<Element | null>;
+	const options = user[1] as AriaHasTabbableChildOptions | undefined;
+
+	let isDisabled = options?.isDisabled;
+	let [hasTabbableChild, setHasTabbableChild] = useState(false, subSlot(slot, 'has'));
+
+	useLayoutEffect(
+		() => {
+			if (ref?.current && !isDisabled) {
+				let update = () => {
+					if (ref.current) {
+						let walker = getFocusableTreeWalker(ref.current, { tabbable: true });
+						setHasTabbableChild(!!walker.nextNode());
+					}
+				};
+
+				update();
+
+				// Update when new elements are inserted, or the tabIndex/disabled attribute updates.
+				let observer = new MutationObserver(update);
+				observer.observe(ref.current, {
+					subtree: true,
+					childList: true,
+					attributes: true,
+					attributeFilter: ['tabIndex', 'disabled'],
+				});
+
+				return () => {
+					// Disconnect mutation observer when an update occurs on the top-level component
+					// so we update synchronously after re-rendering. Otherwise React will emit act warnings
+					// in tests since mutation observers fire asynchronously. The mutation observer is necessary
+					// so we also update if a child component re-renders and adds/removes something tabbable.
+					observer.disconnect();
+				};
+			}
+		},
+		null,
+		subSlot(slot, 'observe'),
+	);
+
+	return isDisabled ? false : hasTabbableChild;
+}

package/src/focus/virtualFocus.ts

@@ -0,0 +1,38 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/focus/virtualFocus.ts).
+// Verbatim — no octane adaptations. The dispatched FocusEvents are real native events, so
+// octane's capture-delegated focus handlers observe them exactly like browser-initiated ones.
+
+import { getActiveElement } from '../utils/shadowdom/DOMFunctions';
+import { getOwnerDocument } from '../utils/domHelpers';
+
+export function moveVirtualFocus(to: Element | null): void {
+	let from = getVirtuallyFocusedElement(getOwnerDocument(to));
+	if (from !== to) {
+		if (from) {
+			dispatchVirtualBlur(from, to);
+		}
+		if (to) {
+			dispatchVirtualFocus(to, from);
+		}
+	}
+}
+
+export function dispatchVirtualBlur(from: Element, to: Element | null): void {
+	from.dispatchEvent(new FocusEvent('blur', { relatedTarget: to }));
+	from.dispatchEvent(new FocusEvent('focusout', { bubbles: true, relatedTarget: to }));
+}
+
+export function dispatchVirtualFocus(to: Element, from: Element | null): void {
+	to.dispatchEvent(new FocusEvent('focus', { relatedTarget: from }));
+	to.dispatchEvent(new FocusEvent('focusin', { bubbles: true, relatedTarget: from }));
+}
+
+export function getVirtuallyFocusedElement(document: Document): Element | null {
+	let activeElement = getActiveElement(document);
+	let activeDescendant = activeElement?.getAttribute('aria-activedescendant');
+	if (activeDescendant) {
+		return document.getElementById(activeDescendant) || activeElement;
+	}
+
+	return activeElement;
+}

package/src/form/useFormValidation.ts

@@ -0,0 +1,205 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/form/useFormValidation.ts).
+// octane adaptations:
+// - `react-stately/private/form/useFormValidationState` → the ported
+//   `../stately/form/useFormValidationState`.
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention; upstream's
+//   dep-less `useLayoutEffect` becomes an explicit `null`; the explicit
+//   `[ref, validationBehavior]` effect deps are preserved exactly.
+// - The native `invalid`/`change`/`reset` listeners are direct `addEventListener` wiring
+//   (never a synthetic layer), exactly like upstream: native `change` is the platform's
+//   value-commit event, so it is NOT renamed to `input` (the onInput rule covers event
+//   *props* on text controls, not native commit listeners).
+// - The `form.reset` interception ports verbatim: upstream added it to ignore React
+//   server-action auto-resets; in octane it still (harmlessly) ignores programmatic
+//   `form.reset()` calls that occur outside a user event.
+import type { RefObject, Validation, ValidationResult } from '@react-types/shared';
+import { useEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import type { FormValidationState } from '../stately/form/useFormValidationState';
+import { setInteractionModality } from '../interactions/useFocusVisible';
+import { getEventTarget } from '../utils/shadowdom/DOMFunctions';
+import { useEffectEvent } from '../utils/useEffectEvent';
+import { useLayoutEffect } from '../utils/useLayoutEffect';
+
+type ValidatableElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+
+interface FormValidationProps<T> extends Validation<T> {
+	focus?: () => void;
+}
+
+export function useFormValidation<T>(
+	props: FormValidationProps<T>,
+	state: FormValidationState,
+	ref: RefObject<ValidatableElement | null> | undefined,
+): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useFormValidation<T>(
+	props: FormValidationProps<T>,
+	state: FormValidationState,
+	ref: RefObject<ValidatableElement | null> | undefined,
+	slot: symbol | undefined,
+): void;
+export function useFormValidation(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useFormValidation');
+	const props = user[0] as FormValidationProps<any>;
+	const state = user[1] as FormValidationState;
+	const ref = user[2] as RefObject<ValidatableElement | null> | undefined;
+
+	let { validationBehavior, focus } = props;
+
+	// This is a useLayoutEffect so that it runs before the useEffect in useFormValidationState, which commits the validation change.
+	useLayoutEffect(
+		() => {
+			if (
+				validationBehavior === 'native' &&
+				ref?.current &&
+				'setCustomValidity' in ref.current &&
+				!ref.current.disabled
+			) {
+				let errorMessage = state.realtimeValidation.isInvalid
+					? state.realtimeValidation.validationErrors.join(' ') || 'Invalid value.'
+					: '';
+				ref.current.setCustomValidity(errorMessage);
+
+				// Prevent default tooltip for validation message.
+				// https://bugzilla.mozilla.org/show_bug.cgi?id=605277
+				if (!ref.current.hasAttribute('title')) {
+					ref.current.title = '';
+				}
+
+				if (!state.realtimeValidation.isInvalid) {
+					state.updateValidation(getNativeValidity(ref.current));
+				}
+			}
+		},
+		null,
+		subSlot(slot, 'native'),
+	);
+
+	let isIgnoredReset = useRef(false, subSlot(slot, 'ignoredReset'));
+	let onReset = useEffectEvent(
+		() => {
+			if (!isIgnoredReset.current) {
+				state.resetValidation();
+			}
+		},
+		subSlot(slot, 'reset'),
+	);
+
+	let onInvalid = useEffectEvent(
+		(e: Event) => {
+			// Only commit validation if we are not already displaying one.
+			// This avoids clearing server errors that the user didn't actually fix.
+			if (!state.displayValidation.isInvalid) {
+				state.commitValidation();
+			}
+
+			// Auto focus the first invalid input in a form, unless the error already had its default prevented.
+			let form = ref?.current?.form;
+			if (!e.defaultPrevented && ref && form && getFirstInvalidInput(form) === ref.current) {
+				if (focus) {
+					focus();
+				} else {
+					ref.current?.focus();
+				}
+
+				// Always show focus ring.
+				setInteractionModality('keyboard');
+			}
+
+			// Prevent default browser error UI from appearing.
+			e.preventDefault();
+		},
+		subSlot(slot, 'invalid'),
+	);
+
+	let onChange = useEffectEvent(
+		() => {
+			state.commitValidation();
+		},
+		subSlot(slot, 'change'),
+	);
+
+	useEffect(
+		() => {
+			let input = ref?.current;
+			if (!input) {
+				return;
+			}
+
+			let form = input.form;
+
+			let reset = form?.reset;
+			if (form) {
+				// Try to detect React's automatic form reset behavior so we don't clear
+				// validation errors that are returned by server actions.
+				// To do this, we ignore programmatic form resets that occur outside a user event.
+				// This is best-effort. There may be false positives, e.g. setTimeout.
+				form.reset = () => {
+					// React uses MessageChannel for scheduling, so ignore 'message' events.
+					isIgnoredReset.current =
+						!window.event ||
+						(window.event.type === 'message' &&
+							getEventTarget(window.event) instanceof MessagePort);
+					reset?.call(form);
+					isIgnoredReset.current = false;
+				};
+			}
+
+			input.addEventListener('invalid', onInvalid);
+			input.addEventListener('change', onChange);
+			form?.addEventListener('reset', onReset);
+			return () => {
+				input!.removeEventListener('invalid', onInvalid);
+				input!.removeEventListener('change', onChange);
+				form?.removeEventListener('reset', onReset);
+				if (form) {
+					// @ts-ignore
+					form.reset = reset;
+				}
+			};
+		},
+		[ref, validationBehavior],
+		subSlot(slot, 'listen'),
+	);
+}
+
+function getValidity(input: ValidatableElement) {
+	// The native ValidityState object is live, meaning each property is a getter that returns the current state.
+	// We need to create a snapshot of the validity state at the time this function is called to avoid unpredictable React renders.
+	let validity = input.validity;
+	return {
+		badInput: validity.badInput,
+		customError: validity.customError,
+		patternMismatch: validity.patternMismatch,
+		rangeOverflow: validity.rangeOverflow,
+		rangeUnderflow: validity.rangeUnderflow,
+		stepMismatch: validity.stepMismatch,
+		tooLong: validity.tooLong,
+		tooShort: validity.tooShort,
+		typeMismatch: validity.typeMismatch,
+		valueMissing: validity.valueMissing,
+		valid: validity.valid,
+	};
+}
+
+function getNativeValidity(input: ValidatableElement): ValidationResult {
+	return {
+		isInvalid: !input.validity.valid,
+		validationDetails: getValidity(input),
+		validationErrors: input.validationMessage ? [input.validationMessage] : [],
+	};
+}
+
+function getFirstInvalidInput(form: HTMLFormElement): ValidatableElement | null {
+	for (let i = 0; i < form.elements.length; i++) {
+		let element = form.elements[i] as ValidatableElement;
+		if (element.validity?.valid === false) {
+			return element;
+		}
+	}
+
+	return null;
+}

package/src/grid/useGridSelectionAnnouncement.ts

@@ -0,0 +1,177 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/grid/useGridSelectionAnnouncement.ts).
+// GRID SUBSET: only the grid-area hooks that the gridlist area actually imports are
+// ported (this file, useHighlightSelectionDescription, useGridSelectionCheckbox) — the
+// rest of the grid area (useGrid/useGridRow/useGridCell/GridKeyboardDelegate/…) is out
+// of scope until a table/grid port needs it.
+// octane adaptations:
+// - `SelectionManager` comes from the ported stately selection engine.
+// - The Parcel glob intl import becomes the generated src/intl/grid index (verbatim
+//   dictionaries).
+// - Public-hook slot threading (splitSlot/subSlot); explicit dependency arrays are kept
+//   verbatim.
+import { announce } from '../live-announcer/LiveAnnouncer';
+import type { Collection, Key, Node, Selection } from '@react-types/shared';
+import intlMessages from '../intl/grid';
+import type { SelectionManager } from '../stately/selection/SelectionManager';
+import { useCallback, useRef } from 'octane';
+import { useLocalizedStringFormatter } from '../i18n/useLocalizedStringFormatter';
+import { useUpdateEffect } from '../utils/useUpdateEffect';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export interface GridSelectionAnnouncementProps {
+	/**
+	 * A function that returns the text that should be announced by assistive technology when a row is
+	 * added or removed from selection.
+	 *
+	 * @default (key) => state.collection.getItem(key)?.textValue
+	 */
+	getRowText?: (key: Key) => string;
+}
+
+interface GridSelectionState<T> {
+	/** A collection of items in the grid. */
+	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;
+}
+
+export function useGridSelectionAnnouncement<T>(
+	props: GridSelectionAnnouncementProps,
+	state: GridSelectionState<T>,
+): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useGridSelectionAnnouncement<T>(
+	props: GridSelectionAnnouncementProps,
+	state: GridSelectionState<T>,
+	slot: symbol | undefined,
+): void;
+export function useGridSelectionAnnouncement(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useGridSelectionAnnouncement');
+	const props = user[0] as GridSelectionAnnouncementProps;
+	const state = user[1] as GridSelectionState<any>;
+
+	let {
+		getRowText = (key) =>
+			(state.collection as any).getTextValue?.(key) ?? state.collection.getItem(key)?.textValue,
+	} = props;
+	let stringFormatter = useLocalizedStringFormatter(
+		intlMessages,
+		'@react-aria/grid',
+		subSlot(slot, 'strings'),
+	);
+
+	// Many screen readers do not announce when items in a grid are selected/deselected.
+	// We do this using an ARIA live region.
+	let selection = state.selectionManager.rawSelection;
+	let lastSelection = useRef(selection, subSlot(slot, 'lastSelection'));
+	let announceSelectionChange = useCallback(
+		() => {
+			if (!state.selectionManager.isFocused || selection === lastSelection.current) {
+				lastSelection.current = selection;
+
+				return;
+			}
+
+			let addedKeys = diffSelection(selection, lastSelection.current);
+			let removedKeys = diffSelection(lastSelection.current, selection);
+
+			// If adding or removing a single row from the selection, announce the name of that item.
+			let isReplace = state.selectionManager.selectionBehavior === 'replace';
+			let messages: string[] = [];
+
+			if (state.selectionManager.selectedKeys.size === 1 && isReplace) {
+				let firstKey = state.selectionManager.selectedKeys.keys().next().value;
+				if (firstKey != null && state.collection.getItem(firstKey)) {
+					let currentSelectionText = getRowText(firstKey);
+					if (currentSelectionText) {
+						messages.push(stringFormatter.format('selectedItem', { item: currentSelectionText }));
+					}
+				}
+			} else if (addedKeys.size === 1 && removedKeys.size === 0) {
+				let firstKey = addedKeys.keys().next().value;
+				if (firstKey != null) {
+					let addedText = getRowText(firstKey);
+					if (addedText) {
+						messages.push(stringFormatter.format('selectedItem', { item: addedText }));
+					}
+				}
+			} else if (removedKeys.size === 1 && addedKeys.size === 0) {
+				let firstKey = removedKeys.keys().next().value;
+				if (firstKey != null && state.collection.getItem(firstKey)) {
+					let removedText = getRowText(firstKey);
+					if (removedText) {
+						messages.push(stringFormatter.format('deselectedItem', { item: removedText }));
+					}
+				}
+			}
+
+			// Announce how many items are selected, except when selecting the first item.
+			if (state.selectionManager.selectionMode === 'multiple') {
+				if (
+					messages.length === 0 ||
+					selection === 'all' ||
+					selection.size > 1 ||
+					lastSelection.current === 'all' ||
+					(lastSelection.current as any)?.size > 1
+				) {
+					messages.push(
+						selection === 'all'
+							? stringFormatter.format('selectedAll')
+							: stringFormatter.format('selectedCount', { count: selection.size }),
+					);
+				}
+			}
+
+			if (messages.length > 0) {
+				announce(messages.join(' '));
+			}
+
+			lastSelection.current = selection;
+		},
+		[
+			selection,
+			state.selectionManager.selectedKeys,
+			state.selectionManager.isFocused,
+			state.selectionManager.selectionBehavior,
+			state.selectionManager.selectionMode,
+			state.collection,
+			getRowText,
+			stringFormatter,
+		],
+		subSlot(slot, 'announceChange'),
+	);
+
+	// useUpdateEffect will handle using useEffectEvent, no need to stabilize anything on this end
+	useUpdateEffect(
+		() => {
+			if (state.selectionManager.isFocused) {
+				announceSelectionChange();
+			} else {
+				// Wait a frame in case the collection is about to become focused (e.g. on mouse down).
+				let raf = requestAnimationFrame(announceSelectionChange);
+				return () => cancelAnimationFrame(raf);
+			}
+		},
+		[selection, state.selectionManager.isFocused],
+		subSlot(slot, 'updateFx'),
+	);
+}
+
+function diffSelection(a: Selection, b: Selection): Set<Key> {
+	let res = new Set<Key>();
+	if (a === 'all' || b === 'all') {
+		return res;
+	}
+
+	for (let key of a.keys()) {
+		if (!b.has(key)) {
+			res.add(key);
+		}
+	}
+
+	return res;
+}