@octanejs/aria 0.0.1 → 0.0.3

package/src/button/useToggleButtonGroup.ts

@@ -0,0 +1,131 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/button/useToggleButtonGroup.ts).
+// octane adaptations: React's per-element attribute overloads collapse into the shared
+// structural result (same as useButton/useToggleButton); public-hook slot threading.
+import type {
+	AriaLabelingProps,
+	DOMAttributes,
+	Key,
+	Orientation,
+	RefObject,
+} from '@react-types/shared';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { AriaToggleButtonProps, ToggleButtonAria, useToggleButton } from './useToggleButton';
+import type { ElementType } from './useButton';
+import type { ToggleGroupProps, ToggleGroupState } from '../stately/toggle/useToggleGroupState';
+import type { ToggleState } from '../stately/toggle/useToggleState';
+import { useToolbar } from '../toolbar/useToolbar';
+
+export interface AriaToggleButtonGroupProps extends ToggleGroupProps, AriaLabelingProps {
+	/**
+	 * The orientation of the the toggle button group.
+	 *
+	 * @default 'horizontal'
+	 */
+	orientation?: Orientation;
+}
+
+export interface ToggleButtonGroupAria {
+	/**
+	 * Props for the toggle button group container.
+	 */
+	groupProps: DOMAttributes;
+}
+
+export function useToggleButtonGroup(
+	props: AriaToggleButtonGroupProps,
+	state: ToggleGroupState,
+	ref: RefObject<HTMLElement | null>,
+): ToggleButtonGroupAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useToggleButtonGroup(
+	props: AriaToggleButtonGroupProps,
+	state: ToggleGroupState,
+	ref: RefObject<HTMLElement | null>,
+	slot: symbol | undefined,
+): ToggleButtonGroupAria;
+export function useToggleButtonGroup(...args: any[]): ToggleButtonGroupAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useToggleButtonGroup');
+	const props = user[0] as AriaToggleButtonGroupProps;
+	const state = user[1] as ToggleGroupState;
+	const ref = user[2] as RefObject<HTMLElement | null>;
+
+	let { isDisabled } = props;
+	let { toolbarProps } = useToolbar(props, ref, subSlot(slot, 'toolbar'));
+
+	return {
+		groupProps: {
+			...toolbarProps,
+			role: state.selectionMode === 'single' ? 'radiogroup' : toolbarProps.role,
+			'aria-disabled': isDisabled,
+		},
+	};
+}
+
+export interface AriaToggleButtonGroupItemProps<E extends ElementType = 'button'> extends Omit<
+	AriaToggleButtonProps<E>,
+	'id' | 'isSelected' | 'defaultSelected' | 'onChange'
+> {
+	/** An identifier for the item in the `selectedKeys` of a ToggleButtonGroup. */
+	id: Key;
+}
+
+export interface AriaToggleButtonGroupItemOptions<E extends ElementType> extends Omit<
+	AriaToggleButtonGroupItemProps<E>,
+	'children'
+> {}
+
+export function useToggleButtonGroupItem(
+	props: AriaToggleButtonGroupItemOptions<ElementType>,
+	state: ToggleGroupState,
+	ref: RefObject<any>,
+): ToggleButtonAria<DOMAttributes>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useToggleButtonGroupItem(
+	props: AriaToggleButtonGroupItemOptions<ElementType>,
+	state: ToggleGroupState,
+	ref: RefObject<any>,
+	slot: symbol | undefined,
+): ToggleButtonAria<DOMAttributes>;
+export function useToggleButtonGroupItem(...args: any[]): ToggleButtonAria<DOMAttributes> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useToggleButtonGroupItem');
+	const props = user[0] as AriaToggleButtonGroupItemOptions<ElementType>;
+	const state = user[1] as ToggleGroupState;
+	const ref = user[2] as RefObject<any>;
+
+	let toggleState: ToggleState = {
+		isSelected: state.selectedKeys.has(props.id),
+		defaultSelected: false,
+		setSelected(isSelected: boolean) {
+			state.setSelected(props.id, isSelected);
+		},
+		toggle() {
+			state.toggleKey(props.id);
+		},
+	};
+
+	let { isPressed, isSelected, isDisabled, buttonProps } = useToggleButton(
+		{
+			...props,
+			id: undefined,
+			isDisabled: props.isDisabled || state.isDisabled,
+		} as any,
+		toggleState,
+		ref,
+		subSlot(slot, 'toggleButton'),
+	);
+	if (state.selectionMode === 'single') {
+		buttonProps.role = 'radio';
+		(buttonProps as any)['aria-checked'] = toggleState.isSelected;
+		delete (buttonProps as any)['aria-pressed'];
+	}
+
+	return {
+		isPressed,
+		isSelected,
+		isDisabled,
+		buttonProps,
+	};
+}

package/src/checkbox/useCheckbox.ts

@@ -0,0 +1,114 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/checkbox/useCheckbox.ts).
+// octane adaptations: React's per-element attribute types → the structural bags the
+// ported useToggle returns; the label's onMouseDown receives the NATIVE MouseEvent;
+// public-hook slot threading.
+import type { InputDOMProps, RefObject, ValidationResult } from '@react-types/shared';
+import { useEffect, useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { AriaToggleProps, useToggle } from '../toggle/useToggle';
+import { mergeProps } from '../utils/mergeProps';
+import type { ToggleProps, ToggleState } from '../stately/toggle/useToggleState';
+
+type DOMAttributes = Record<string, any>;
+
+export interface CheckboxProps extends ToggleProps {
+	/**
+	 * Indeterminism is presentational only.
+	 * The indeterminate visual representation remains regardless of user interaction.
+	 */
+	isIndeterminate?: boolean;
+}
+
+export interface AriaCheckboxProps extends CheckboxProps, InputDOMProps, AriaToggleProps {}
+
+export interface CheckboxAria extends ValidationResult {
+	/** Props for the label wrapper element. */
+	labelProps: DOMAttributes;
+	/** Props for the input element. */
+	inputProps: DOMAttributes;
+	/** Props for the checkbox description element, if any. */
+	descriptionProps: DOMAttributes;
+	/** Props for the checkbox error message element, if any. */
+	errorMessageProps: DOMAttributes;
+	/** Whether the checkbox is selected. */
+	isSelected: boolean;
+	/** Whether the checkbox is in a pressed state. */
+	isPressed: boolean;
+	/** Whether the checkbox is disabled. */
+	isDisabled: boolean;
+	/** Whether the checkbox is read only. */
+	isReadOnly: boolean;
+}
+
+export function useCheckbox(
+	props: AriaCheckboxProps,
+	state: ToggleState,
+	inputRef: RefObject<HTMLInputElement | null>,
+): CheckboxAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useCheckbox(
+	props: AriaCheckboxProps,
+	state: ToggleState,
+	inputRef: RefObject<HTMLInputElement | null>,
+	slot: symbol | undefined,
+): CheckboxAria;
+export function useCheckbox(...args: any[]): CheckboxAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useCheckbox');
+	const props = user[0] as AriaCheckboxProps;
+	const state = user[1] as ToggleState;
+	const inputRef = user[2] as RefObject<HTMLInputElement | null>;
+
+	let {
+		labelProps,
+		inputProps,
+		descriptionProps,
+		errorMessageProps,
+		isSelected,
+		isPressed,
+		isDisabled,
+		isReadOnly,
+		isInvalid,
+		validationErrors,
+		validationDetails,
+	} = useToggle(props, state, inputRef, subSlot(slot, 'toggle'));
+
+	let { isIndeterminate } = props;
+	useEffect(
+		() => {
+			// indeterminate is a property, but it can only be set via javascript
+			// https://css-tricks.com/indeterminate-checkboxes/
+			if (inputRef.current) {
+				inputRef.current.indeterminate = !!isIndeterminate;
+			}
+		},
+		null,
+		subSlot(slot, 'indeterminate'),
+	);
+
+	return {
+		labelProps: mergeProps(
+			labelProps,
+			useMemo(
+				() => ({
+					// Prevent label from being focused when mouse down on it.
+					// Note, this does not prevent the input from being focused in the `click` event.
+					onMouseDown: (e: MouseEvent) => e.preventDefault(),
+				}),
+				[],
+				subSlot(slot, 'labelDown'),
+			),
+		),
+		inputProps,
+		descriptionProps,
+		errorMessageProps,
+		isSelected,
+		isPressed,
+		isDisabled,
+		isReadOnly,
+		isInvalid,
+		validationErrors,
+		validationDetails,
+	};
+}

package/src/checkbox/useCheckboxGroup.ts

@@ -0,0 +1,107 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/checkbox/useCheckboxGroup.ts).
+// octane adaptations: `FocusEvents` is the ported native-event version (from
+// interactions/useFocus); public-hook slot threading.
+import type {
+	AriaLabelingProps,
+	AriaValidationProps,
+	DOMAttributes,
+	DOMProps,
+	InputDOMProps,
+	ValidationResult,
+} from '@react-types/shared';
+
+import type { FocusEvents } from '../interactions/useFocus';
+import { S, splitSlot, subSlot } from '../internal';
+import { checkboxGroupData } from './utils';
+import type {
+	CheckboxGroupProps,
+	CheckboxGroupState,
+} from '../stately/checkbox/useCheckboxGroupState';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { mergeProps } from '../utils/mergeProps';
+import { useField } from '../label/useField';
+import { useFocusWithin } from '../interactions/useFocusWithin';
+
+export interface AriaCheckboxGroupProps
+	extends
+		CheckboxGroupProps,
+		InputDOMProps,
+		DOMProps,
+		AriaLabelingProps,
+		AriaValidationProps,
+		FocusEvents {}
+
+export interface CheckboxGroupAria extends ValidationResult {
+	/** Props for the checkbox group wrapper element. */
+	groupProps: DOMAttributes;
+	/** Props for the checkbox group's visible label (if any). */
+	labelProps: DOMAttributes;
+	/** Props for the checkbox group description element, if any. */
+	descriptionProps: DOMAttributes;
+	/** Props for the checkbox group error message element, if any. */
+	errorMessageProps: DOMAttributes;
+}
+
+export function useCheckboxGroup(
+	props: AriaCheckboxGroupProps,
+	state: CheckboxGroupState,
+): CheckboxGroupAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useCheckboxGroup(
+	props: AriaCheckboxGroupProps,
+	state: CheckboxGroupState,
+	slot: symbol | undefined,
+): CheckboxGroupAria;
+export function useCheckboxGroup(...args: any[]): CheckboxGroupAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useCheckboxGroup');
+	const props = user[0] as AriaCheckboxGroupProps;
+	const state = user[1] as CheckboxGroupState;
+
+	let { isDisabled, name, form, validationBehavior = 'aria' } = props;
+	let { isInvalid, validationErrors, validationDetails } = state.displayValidation;
+	let { labelProps, fieldProps, descriptionProps, errorMessageProps } = useField(
+		{
+			...props,
+			// Checkbox group is not an HTML input element so it
+			// shouldn't be labeled by a <label> element.
+			labelElementType: 'span',
+			isInvalid,
+			errorMessage: props.errorMessage || validationErrors,
+		},
+		subSlot(slot, 'field'),
+	);
+
+	checkboxGroupData.set(state, {
+		name,
+		form,
+		descriptionId: (descriptionProps as any).id,
+		errorMessageId: (errorMessageProps as any).id,
+		validationBehavior,
+	});
+
+	let domProps = filterDOMProps(props, { labelable: true });
+	let { focusWithinProps } = useFocusWithin(
+		{
+			onBlurWithin: props.onBlur,
+			onFocusWithin: props.onFocus,
+			onFocusWithinChange: props.onFocusChange,
+		},
+		subSlot(slot, 'focusWithin'),
+	);
+
+	return {
+		groupProps: mergeProps(domProps, {
+			role: 'group',
+			'aria-disabled': isDisabled || undefined,
+			...fieldProps,
+			...focusWithinProps,
+		}),
+		labelProps,
+		descriptionProps,
+		errorMessageProps,
+		isInvalid,
+		validationErrors,
+		validationDetails,
+	};
+}

package/src/checkbox/useCheckboxGroupItem.ts

@@ -0,0 +1,132 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/checkbox/useCheckboxGroupItem.ts).
+// octane adaptation: public-hook slot threading; upstream's dep-less `useEffect` →
+// explicit `null` deps (run every render).
+import type { RefObject, ValidationResult } from '@react-types/shared';
+import { useEffect, useRef } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { AriaCheckboxProps, CheckboxAria, useCheckbox } from './useCheckbox';
+import { checkboxGroupData } from './utils';
+import type { CheckboxGroupState } from '../stately/checkbox/useCheckboxGroupState';
+import {
+	DEFAULT_VALIDATION_RESULT,
+	privateValidationStateProp,
+	useFormValidationState,
+} from '../stately/form/useFormValidationState';
+import { useToggleState } from '../stately/toggle/useToggleState';
+
+export interface AriaCheckboxGroupItemProps extends Omit<
+	AriaCheckboxProps,
+	'isSelected' | 'defaultSelected'
+> {
+	value: string;
+}
+
+export function useCheckboxGroupItem(
+	props: AriaCheckboxGroupItemProps,
+	state: CheckboxGroupState,
+	inputRef: RefObject<HTMLInputElement | null>,
+): CheckboxAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useCheckboxGroupItem(
+	props: AriaCheckboxGroupItemProps,
+	state: CheckboxGroupState,
+	inputRef: RefObject<HTMLInputElement | null>,
+	slot: symbol | undefined,
+): CheckboxAria;
+export function useCheckboxGroupItem(...args: any[]): CheckboxAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useCheckboxGroupItem');
+	const props = user[0] as AriaCheckboxGroupItemProps;
+	const state = user[1] as CheckboxGroupState;
+	const inputRef = user[2] as RefObject<HTMLInputElement | null>;
+
+	const toggleState = useToggleState(
+		{
+			isReadOnly: props.isReadOnly || state.isReadOnly,
+			isSelected: state.isSelected(props.value),
+			defaultSelected: state.defaultValue.includes(props.value),
+			onChange(isSelected: boolean) {
+				if (isSelected) {
+					state.addValue(props.value);
+				} else {
+					state.removeValue(props.value);
+				}
+				if (props.onChange) {
+					props.onChange(isSelected);
+				}
+			},
+		},
+		subSlot(slot, 'toggleState'),
+	);
+
+	let { name, form, descriptionId, errorMessageId, validationBehavior } =
+		checkboxGroupData.get(state)!;
+	validationBehavior = props.validationBehavior ?? validationBehavior;
+
+	// Local validation for this checkbox.
+	let { realtimeValidation } = useFormValidationState(
+		{
+			...props,
+			value: toggleState.isSelected,
+			// Server validation is handled at the group level.
+			name: undefined,
+			validationBehavior: 'aria',
+		},
+		subSlot(slot, 'validation'),
+	);
+
+	// Update the checkbox group state when realtime validation changes.
+	let nativeValidation = useRef(DEFAULT_VALIDATION_RESULT, subSlot(slot, 'nativeValidation'));
+	let updateValidation = () => {
+		state.setInvalid(
+			props.value,
+			realtimeValidation.isInvalid ? realtimeValidation : nativeValidation.current,
+		);
+	};
+
+	useEffect(updateValidation, null, subSlot(slot, 'updateValidation'));
+
+	// Combine group and checkbox level validation.
+	let combinedRealtimeValidation = state.realtimeValidation.isInvalid
+		? state.realtimeValidation
+		: realtimeValidation;
+	let displayValidation =
+		validationBehavior === 'native' ? state.displayValidation : combinedRealtimeValidation;
+
+	let res = useCheckbox(
+		{
+			...props,
+			isReadOnly: props.isReadOnly || state.isReadOnly,
+			isDisabled: props.isDisabled || state.isDisabled,
+			name: props.name || name,
+			form: props.form || form,
+			isRequired: props.isRequired ?? state.isRequired,
+			validationBehavior,
+			[privateValidationStateProp]: {
+				realtimeValidation: combinedRealtimeValidation,
+				displayValidation,
+				resetValidation: state.resetValidation,
+				commitValidation: state.commitValidation,
+				updateValidation(v: ValidationResult) {
+					nativeValidation.current = v;
+					updateValidation();
+				},
+			},
+		} as any,
+		toggleState,
+		inputRef,
+		subSlot(slot, 'checkbox'),
+	);
+
+	return {
+		...res,
+		inputProps: {
+			...res.inputProps,
+			'aria-describedby':
+				[res.inputProps['aria-describedby'], state.isInvalid ? errorMessageId : null, descriptionId]
+					.filter(Boolean)
+					.join(' ') || undefined,
+		},
+	};
+}

package/src/checkbox/utils.ts

@@ -0,0 +1,15 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/checkbox/utils.ts).
+import type { CheckboxGroupState } from '../stately/checkbox/useCheckboxGroupState';
+
+interface CheckboxGroupData {
+	name?: string;
+	form?: string;
+	descriptionId?: string;
+	errorMessageId?: string;
+	validationBehavior: 'aria' | 'native';
+}
+
+export const checkboxGroupData: WeakMap<CheckboxGroupState, CheckboxGroupData> = new WeakMap<
+	CheckboxGroupState,
+	CheckboxGroupData
+>();