@octanejs/aria 0.0.1 → 0.0.3

package/src/stately/disclosure/useDisclosureGroupState.ts

@@ -0,0 +1,108 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/disclosure/useDisclosureGroupState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; upstream's dep-less `useEffect` becomes an explicit `null` (run after every
+// render); explicit `Set<Key>` element types on the default-set constructions (strict
+// inference).
+import type { Key } from '@react-types/shared';
+import { useEffect, useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { useControlledState } from '../utils/useControlledState';
+
+export interface DisclosureGroupProps {
+	/** Whether multiple items can be expanded at the same time. */
+	allowsMultipleExpanded?: boolean;
+	/** Whether all items are disabled. */
+	isDisabled?: boolean;
+	/** The currently expanded keys in the group (controlled). */
+	expandedKeys?: Iterable<Key>;
+	/** The initial expanded keys in the group (uncontrolled). */
+	defaultExpandedKeys?: Iterable<Key>;
+	/** Handler that is called when items are expanded or collapsed. */
+	onExpandedChange?: (keys: Set<Key>) => any;
+}
+
+export interface DisclosureGroupState {
+	/** Whether multiple items can be expanded at the same time. */
+	readonly allowsMultipleExpanded: boolean;
+
+	/** Whether all items are disabled. */
+	readonly isDisabled: boolean;
+
+	/** 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;
+}
+
+/**
+ * Manages state for a group of disclosures, e.g. an accordion.
+ * It supports both single and multiple expanded items.
+ */
+export function useDisclosureGroupState(props: DisclosureGroupProps): DisclosureGroupState;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useDisclosureGroupState(
+	props: DisclosureGroupProps,
+	slot: symbol | undefined,
+): DisclosureGroupState;
+export function useDisclosureGroupState(...args: any[]): DisclosureGroupState {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useDisclosureGroupState');
+	const props = user[0] as DisclosureGroupProps;
+
+	let { allowsMultipleExpanded = false, isDisabled = false } = props;
+	let [expandedKeys, setExpandedKeys] = useControlledState(
+		useMemo(
+			() => (props.expandedKeys ? new Set(props.expandedKeys) : undefined),
+			[props.expandedKeys],
+			subSlot(slot, 'controlled'),
+		),
+		useMemo(
+			() => (props.defaultExpandedKeys ? new Set(props.defaultExpandedKeys) : new Set<Key>()),
+			[props.defaultExpandedKeys],
+			subSlot(slot, 'default'),
+		),
+		props.onExpandedChange,
+		subSlot(slot, 'keys'),
+	);
+
+	useEffect(
+		() => {
+			// Ensure only one item is expanded if allowsMultipleExpanded is false.
+			if (!allowsMultipleExpanded && expandedKeys.size > 1) {
+				let firstKey = expandedKeys.values().next().value;
+				if (firstKey != null) {
+					setExpandedKeys(new Set([firstKey]));
+				}
+			}
+		},
+		null,
+		subSlot(slot, 'single'),
+	);
+
+	return {
+		allowsMultipleExpanded,
+		isDisabled,
+		expandedKeys,
+		setExpandedKeys,
+		toggleKey(key) {
+			let keys: Set<Key>;
+			if (allowsMultipleExpanded) {
+				keys = new Set(expandedKeys);
+				if (keys.has(key)) {
+					keys.delete(key);
+				} else {
+					keys.add(key);
+				}
+			} else {
+				keys = new Set(expandedKeys.has(key) ? [] : [key]);
+			}
+
+			setExpandedKeys(keys);
+		},
+	};
+}

package/src/stately/disclosure/useDisclosureState.ts

@@ -0,0 +1,84 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/disclosure/useDisclosureState.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; explicit useCallback dep arrays preserved exactly.
+import { useCallback } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { useControlledState } from '../utils/useControlledState';
+
+export interface DisclosureProps {
+	/** Whether the disclosure is expanded (controlled). */
+	isExpanded?: boolean;
+	/** Whether the disclosure is expanded by default (uncontrolled). */
+	defaultExpanded?: boolean;
+	/** Handler that is called when the disclosure expanded state changes. */
+	onExpandedChange?: (isExpanded: boolean) => void;
+}
+
+export interface DisclosureState {
+	/** Whether the disclosure is currently expanded. */
+	readonly isExpanded: boolean;
+	/** Sets whether the disclosure is expanded. */
+	setExpanded(isExpanded: boolean): void;
+	/** Expand the disclosure. */
+	expand(): void;
+	/** Collapse the disclosure. */
+	collapse(): void;
+	/** Toggles the disclosure's visibility. */
+	toggle(): void;
+}
+
+/**
+ * Manages state for a disclosure widget. Tracks whether the disclosure is expanded, and provides
+ * methods to toggle this state.
+ */
+export function useDisclosureState(props: DisclosureProps): DisclosureState;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useDisclosureState(
+	props: DisclosureProps,
+	slot: symbol | undefined,
+): DisclosureState;
+export function useDisclosureState(...args: any[]): DisclosureState {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useDisclosureState');
+	const props = user[0] as DisclosureProps;
+
+	let [isExpanded, setExpanded] = useControlledState(
+		props.isExpanded,
+		props.defaultExpanded || false,
+		props.onExpandedChange,
+		subSlot(slot, 'expanded'),
+	);
+
+	const expand = useCallback(
+		() => {
+			setExpanded(true);
+		},
+		[setExpanded],
+		subSlot(slot, 'expand'),
+	);
+
+	const collapse = useCallback(
+		() => {
+			setExpanded(false);
+		},
+		[setExpanded],
+		subSlot(slot, 'collapse'),
+	);
+
+	const toggle = useCallback(
+		() => {
+			setExpanded(!isExpanded);
+		},
+		[setExpanded, isExpanded],
+		subSlot(slot, 'toggle'),
+	);
+
+	return {
+		isExpanded,
+		setExpanded,
+		expand,
+		collapse,
+		toggle,
+	};
+}

package/src/stately/form/useFormValidationState.ts

@@ -0,0 +1,331 @@
+// Ported from react-stately (source: .react-spectrum/packages/react-stately/src/form/useFormValidationState.ts).
+// octane adaptations:
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention; explicit dep
+//   arrays are preserved exactly, and upstream's dep-less `useEffect(commitValidation)`
+//   becomes an explicit `null` (run after every render).
+// - The private group-state prop path returns before any hooks run — legal in octane
+//   (hooks are slot-keyed, not order-keyed), so upstream's eslint-suppressed structure
+//   ports as-is. `privateValidationStateProp` keeps upstream's exact string: it must be
+//   stable across server/client module evaluation for SSR hydration.
+// - `ValidityState` writes/reads through dynamic keys cast via `Record<string, any>`
+//   (upstream relies on looser index typing).
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from 'octane';
+import type {
+	Validation,
+	ValidationErrors,
+	ValidationFunction,
+	ValidationResult,
+} from '@react-types/shared';
+
+import { S, splitSlot, subSlot } from '../../internal';
+
+export const VALID_VALIDITY_STATE: ValidityState = {
+	badInput: false,
+	customError: false,
+	patternMismatch: false,
+	rangeOverflow: false,
+	rangeUnderflow: false,
+	stepMismatch: false,
+	tooLong: false,
+	tooShort: false,
+	typeMismatch: false,
+	valueMissing: false,
+	valid: true,
+};
+
+const CUSTOM_VALIDITY_STATE: ValidityState = {
+	...VALID_VALIDITY_STATE,
+	customError: true,
+	valid: false,
+};
+
+export const DEFAULT_VALIDATION_RESULT: ValidationResult = {
+	isInvalid: false,
+	validationDetails: VALID_VALIDITY_STATE,
+	validationErrors: [],
+};
+
+export const FormValidationContext = createContext<ValidationErrors>({});
+
+// Private props that we pass from useFormValidationState to children.
+// Ideally we'd use a Symbol for this, but React doesn't support them: https://github.com/facebook/react/issues/7552
+// This needs to be stable across server and client module evaluation for SSR hydration.
+export const privateValidationStateProp: string = '__reactAriaFormValidationState';
+
+interface FormValidationProps<T> extends Validation<T> {
+	builtinValidation?: ValidationResult;
+	name?: string | string[];
+	value: T | null;
+}
+
+export interface FormValidationState {
+	/** Realtime validation results, updated as the user edits the value. */
+	realtimeValidation: ValidationResult;
+	/** Currently displayed validation results, updated when the user commits their changes. */
+	displayValidation: ValidationResult;
+	/**
+	 * Updates the current validation result. Not displayed to the user until `commitValidation` is
+	 * called.
+	 */
+	updateValidation(result: ValidationResult): void;
+	/** Resets the displayed validation state to valid when the user resets the form. */
+	resetValidation(): void;
+	/** Commits the realtime validation so it is displayed to the user. */
+	commitValidation(): void;
+}
+
+export function useFormValidationState<T>(props: FormValidationProps<T>): FormValidationState;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useFormValidationState<T>(
+	props: FormValidationProps<T>,
+	slot: symbol | undefined,
+): FormValidationState;
+export function useFormValidationState(...args: any[]): FormValidationState {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useFormValidationState');
+	const props = user[0] as FormValidationProps<any>;
+
+	// Private prop for parent components to pass state to children.
+	if ((props as any)[privateValidationStateProp]) {
+		let {
+			realtimeValidation,
+			displayValidation,
+			updateValidation,
+			resetValidation,
+			commitValidation,
+		} = (props as any)[privateValidationStateProp] as FormValidationState;
+		return {
+			realtimeValidation,
+			displayValidation,
+			updateValidation,
+			resetValidation,
+			commitValidation,
+		};
+	}
+
+	return useFormValidationStateImpl(props, slot);
+}
+
+function useFormValidationStateImpl<T>(
+	props: FormValidationProps<T>,
+	slot: symbol | undefined,
+): FormValidationState {
+	let {
+		isInvalid,
+		validationState,
+		name,
+		value,
+		builtinValidation,
+		validate,
+		validationBehavior = 'aria',
+	} = props;
+
+	// backward compatibility.
+	if (validationState) {
+		isInvalid ||= validationState === 'invalid';
+	}
+
+	// If the isInvalid prop is controlled, update validation result in realtime.
+	let controlledError: ValidationResult | null =
+		isInvalid !== undefined
+			? {
+					isInvalid,
+					validationErrors: [],
+					validationDetails: CUSTOM_VALIDITY_STATE,
+				}
+			: null;
+
+	// Perform custom client side validation.
+	let clientError: ValidationResult | null = useMemo(
+		() => {
+			if (!validate || value == null) {
+				return null;
+			}
+			let validateErrors = runValidate(validate, value);
+			return getValidationResult(validateErrors);
+		},
+		[validate, value],
+		subSlot(slot, 'client'),
+	);
+
+	if (builtinValidation?.validationDetails.valid) {
+		builtinValidation = undefined;
+	}
+
+	// Get relevant server errors from the form.
+	let serverErrors = useContext(FormValidationContext);
+	let serverErrorMessages = useMemo(
+		() => {
+			if (name) {
+				return Array.isArray(name)
+					? name.flatMap((name) => asArray(serverErrors[name]))
+					: asArray(serverErrors[name]);
+			}
+			return [];
+		},
+		[serverErrors, name],
+		subSlot(slot, 'serverMessages'),
+	);
+
+	// Show server errors when the form gets a new value, and clear when the user changes the value.
+	let [lastServerErrors, setLastServerErrors] = useState(serverErrors, subSlot(slot, 'lastServer'));
+	let [isServerErrorCleared, setServerErrorCleared] = useState(
+		false,
+		subSlot(slot, 'serverCleared'),
+	);
+	if (serverErrors !== lastServerErrors) {
+		setLastServerErrors(serverErrors);
+		setServerErrorCleared(false);
+	}
+
+	let serverError: ValidationResult | null = useMemo(
+		() => getValidationResult(isServerErrorCleared ? [] : serverErrorMessages),
+		[isServerErrorCleared, serverErrorMessages],
+		subSlot(slot, 'server'),
+	);
+
+	// Track the next validation state in a ref until commitValidation is called.
+	let nextValidation = useRef(DEFAULT_VALIDATION_RESULT, subSlot(slot, 'next'));
+	let [currentValidity, setCurrentValidity] = useState(
+		DEFAULT_VALIDATION_RESULT,
+		subSlot(slot, 'current'),
+	);
+
+	let lastError = useRef(DEFAULT_VALIDATION_RESULT, subSlot(slot, 'lastError'));
+	let commitValidation = () => {
+		if (!commitQueued) {
+			return;
+		}
+
+		setCommitQueued(false);
+		let error = clientError || builtinValidation || nextValidation.current;
+		if (!isEqualValidation(error, lastError.current)) {
+			lastError.current = error;
+			setCurrentValidity(error);
+		}
+	};
+
+	let [commitQueued, setCommitQueued] = useState(false, subSlot(slot, 'queued'));
+	useEffect(commitValidation, null, subSlot(slot, 'commit'));
+
+	// realtimeValidation is used to update the native input element's state based on custom validation logic.
+	// displayValidation is the currently displayed validation state that the user sees (e.g. on input change/form submit).
+	// With validationBehavior="aria", all errors are displayed in realtime rather than on submit.
+	let realtimeValidation =
+		controlledError || serverError || clientError || builtinValidation || DEFAULT_VALIDATION_RESULT;
+	let displayValidation =
+		validationBehavior === 'native'
+			? controlledError || serverError || currentValidity
+			: controlledError || serverError || clientError || builtinValidation || currentValidity;
+
+	return {
+		realtimeValidation,
+		displayValidation,
+		updateValidation(value) {
+			// If validationBehavior is 'aria', update in realtime. Otherwise, store in a ref until commit.
+			if (validationBehavior === 'aria' && !isEqualValidation(currentValidity, value)) {
+				setCurrentValidity(value);
+			} else {
+				nextValidation.current = value;
+			}
+		},
+		resetValidation() {
+			// Update the currently displayed validation state to valid on form reset,
+			// even if the native validity says it isn't. It'll show again on the next form submit.
+			let error = DEFAULT_VALIDATION_RESULT;
+			if (!isEqualValidation(error, lastError.current)) {
+				lastError.current = error;
+				setCurrentValidity(error);
+			}
+
+			// Do not commit validation after the next render. This avoids a condition where
+			// useSelect calls commitValidation inside an onReset handler.
+			if (validationBehavior === 'native') {
+				setCommitQueued(false);
+			}
+
+			setServerErrorCleared(true);
+		},
+		commitValidation() {
+			// Commit validation state so the user sees it on blur/change/submit. Also clear any server errors.
+			// Wait until after the next render to commit so that the latest value has been validated.
+			if (validationBehavior === 'native') {
+				setCommitQueued(true);
+			}
+			setServerErrorCleared(true);
+		},
+	};
+}
+
+function asArray<T>(v: T | T[]): T[] {
+	if (!v) {
+		return [];
+	}
+
+	return Array.isArray(v) ? v : [v];
+}
+
+function runValidate<T>(validate: ValidationFunction<T>, value: T): string[] {
+	if (typeof validate === 'function') {
+		let e = validate(value);
+		if (e && typeof e !== 'boolean') {
+			return asArray(e);
+		}
+	}
+
+	return [];
+}
+
+function getValidationResult(errors: string[]): ValidationResult | null {
+	return errors.length
+		? {
+				isInvalid: true,
+				validationErrors: errors,
+				validationDetails: CUSTOM_VALIDITY_STATE,
+			}
+		: null;
+}
+
+function isEqualValidation(a: ValidationResult | null, b: ValidationResult | null): boolean {
+	if (a === b) {
+		return true;
+	}
+
+	return (
+		!!a &&
+		!!b &&
+		a.isInvalid === b.isInvalid &&
+		a.validationErrors.length === b.validationErrors.length &&
+		a.validationErrors.every((a, i) => a === b.validationErrors[i]) &&
+		Object.entries(a.validationDetails).every(
+			([k, v]) => (b.validationDetails as unknown as Record<string, any>)[k] === v,
+		)
+	);
+}
+
+export function mergeValidation(...results: ValidationResult[]): ValidationResult {
+	let errors = new Set<string>();
+	let isInvalid = false;
+	let validationDetails: Record<string, any> = {
+		...VALID_VALIDITY_STATE,
+	};
+
+	for (let v of results) {
+		for (let e of v.validationErrors) {
+			errors.add(e);
+		}
+
+		// Only these properties apply for checkboxes.
+		isInvalid ||= v.isInvalid;
+		for (let key in validationDetails) {
+			validationDetails[key] ||= (v.validationDetails as unknown as Record<string, any>)[key];
+		}
+	}
+
+	validationDetails.valid = !isInvalid;
+	return {
+		isInvalid,
+		validationErrors: [...errors],
+		validationDetails: validationDetails as unknown as ValidityState,
+	};
+}

package/src/stately/index.ts

@@ -5,3 +5,114 @@
 // utils
 export { useControlledState } from './utils/useControlledState';
 export type { SetStateAction } from './utils/useControlledState';
+
+// toggle
+export { useToggleState } from './toggle/useToggleState';
+export { useToggleGroupState } from './toggle/useToggleGroupState';
+export type { ToggleProps, ToggleState, ToggleStateOptions } from './toggle/useToggleState';
+export type { ToggleGroupProps, ToggleGroupState } from './toggle/useToggleGroupState';
+
+// checkbox
+export { useCheckboxGroupState } from './checkbox/useCheckboxGroupState';
+export type { CheckboxGroupProps, CheckboxGroupState } from './checkbox/useCheckboxGroupState';
+
+// radio
+export { useRadioGroupState } from './radio/useRadioGroupState';
+export type { RadioGroupProps, RadioGroupState } from './radio/useRadioGroupState';
+
+// searchfield
+export { useSearchFieldState } from './searchfield/useSearchFieldState';
+export type { SearchFieldProps, SearchFieldState } from './searchfield/useSearchFieldState';
+
+// disclosure
+export { useDisclosureState } from './disclosure/useDisclosureState';
+export { useDisclosureGroupState } from './disclosure/useDisclosureGroupState';
+export type { DisclosureProps, DisclosureState } from './disclosure/useDisclosureState';
+export type {
+	DisclosureGroupProps,
+	DisclosureGroupState,
+} from './disclosure/useDisclosureGroupState';
+
+// form — mirrors the @react-stately/form shim surface.
+export {
+	FormValidationContext,
+	useFormValidationState,
+	DEFAULT_VALIDATION_RESULT,
+	VALID_VALIDITY_STATE,
+	privateValidationStateProp,
+	mergeValidation,
+} from './form/useFormValidationState';
+export type { FormValidationState } from './form/useFormValidationState';
+
+// selection — mirrors the @react-stately/selection shim surface.
+export { useMultipleSelectionState } from './selection/useMultipleSelectionState';
+export { SelectionManager } from './selection/SelectionManager';
+export { Selection } from './selection/Selection';
+export type { MultipleSelectionStateProps } from './selection/useMultipleSelectionState';
+export type {
+	FocusState,
+	SingleSelectionState,
+	MultipleSelectionState,
+	MultipleSelectionManager,
+} from './selection/types';
+
+// collections — mirrors the @react-stately/collections shim surface.
+export { Item } from './collections/Item';
+export { Section } from './collections/Section';
+export { CollectionBuilder } from './collections/CollectionBuilder';
+export { useCollection } from './collections/useCollection';
+export { getItemCount } from './collections/getItemCount';
+export {
+	getChildNodes,
+	getFirstItem,
+	getLastItem,
+	getNthItem,
+	compareNodeOrder,
+} from './collections/getChildNodes';
+export type { PartialNode } from './collections/types';
+
+// list
+export { useListState, UNSTABLE_useFilteredListState } from './list/useListState';
+export { useSingleSelectListState } from './list/useSingleSelectListState';
+export { ListCollection } from './list/ListCollection';
+export type { ListProps, ListState } from './list/useListState';
+export type { SingleSelectListProps, SingleSelectListState } from './list/useSingleSelectListState';
+
+// tree
+export { useTreeState } from './tree/useTreeState';
+export { TreeCollection } from './tree/TreeCollection';
+export type { TreeProps, TreeState } from './tree/useTreeState';
+
+// menu
+export { useMenuTriggerState } from './menu/useMenuTriggerState';
+export { useSubmenuTriggerState } from './menu/useSubmenuTriggerState';
+export type { MenuTriggerState } from './menu/useMenuTriggerState';
+export type { SubmenuTriggerState } from './menu/useSubmenuTriggerState';
+
+// overlays
+export { useOverlayTriggerState } from './overlays/useOverlayTriggerState';
+export type { OverlayTriggerProps, OverlayTriggerState } from './overlays/useOverlayTriggerState';
+
+// tooltip
+export { useTooltipTriggerState } from './tooltip/useTooltipTriggerState';
+export type { TooltipTriggerProps, TooltipTriggerState } from './tooltip/useTooltipTriggerState';
+
+// select
+export { useSelectState } from './select/useSelectState';
+export type { SelectState, SelectStateOptions } from './select/useSelectState';
+
+// combobox
+export { useComboBoxState } from './combobox/useComboBoxState';
+export type { ComboBoxState, ComboBoxStateOptions } from './combobox/useComboBoxState';
+
+// tabs
+export { useTabListState } from './tabs/useTabListState';
+export type { TabListProps, TabListState, TabListStateOptions } from './tabs/useTabListState';
+
+// numberfield
+export { useNumberFieldState } from './numberfield/useNumberFieldState';
+export type { NumberFieldState, NumberFieldStateOptions } from './numberfield/useNumberFieldState';
+
+// slider
+export { useSliderState } from './slider/useSliderState';
+export type { SliderState, SliderStateOptions } from './slider/useSliderState';