@octanejs/aria 0.0.1 → 0.0.4

package/src/tag/useTag.ts

@@ -0,0 +1,162 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/tag/useTag.ts).
+// octane adaptations:
+// - Handlers receive NATIVE events: the Delete/Backspace removal handler takes the
+//   native KeyboardEvent.
+// - The Parcel glob intl import becomes the generated src/intl/tag index (verbatim
+//   dictionaries).
+// - `ListState` comes from the ported stately list hook; `DOMAttributes` is a local
+//   structural prop-bag alias.
+// - Public-hook slot threading (splitSlot/subSlot).
+import type { AriaButtonProps } from '../button/useButton';
+import type { FocusableElement, Node, RefObject } from '@react-types/shared';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { hookData } from './useTagGroup';
+import intlMessages from '../intl/tag';
+import type { ListState } from '../stately/list/useListState';
+import { mergeProps } from '../utils/mergeProps';
+import { SelectableItemStates } from '../selection/useSelectableItem';
+import { useDescription } from '../utils/useDescription';
+import { useFocusable } from '../interactions/useFocusable';
+import { useGridListItem } from '../gridlist/useGridListItem';
+import { useId } from '../utils/useId';
+import { useInteractionModality } from '../interactions/useFocusVisible';
+import { useLocalizedStringFormatter } from '../i18n/useLocalizedStringFormatter';
+import { useSyntheticLinkProps } from '../utils/openLink';
+
+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 TagAria extends SelectableItemStates {
+	/** Props for the tag row element. */
+	rowProps: DOMAttributes;
+	/** Props for the tag cell element. */
+	gridCellProps: DOMAttributes;
+	/** Props for the tag remove button. */
+	removeButtonProps: AriaButtonProps;
+	/** Whether the tag can be removed. */
+	allowsRemoving: boolean;
+}
+
+export interface AriaTagProps<T> {
+	/** An object representing the tag. Contains all the relevant information that makes up the tag. */
+	item: Node<T>;
+	// octane adaptation (part of upstream's surface via DOMProps/AriaLabelingProps reads
+	// below): optional aria attributes forwarded to the cell.
+	'aria-errormessage'?: string;
+	'aria-label'?: string;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a tag component.
+ *
+ * @param props - Props to be applied to the tag.
+ * @param state - State for the tag group, as returned by `useListState`.
+ * @param ref - A ref to a DOM element for the tag.
+ */
+export function useTag<T>(
+	props: AriaTagProps<T>,
+	state: ListState<T>,
+	ref: RefObject<FocusableElement | null>,
+): TagAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTag<T>(
+	props: AriaTagProps<T>,
+	state: ListState<T>,
+	ref: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): TagAria;
+export function useTag(...args: any[]): TagAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTag');
+	const props = user[0] as AriaTagProps<any>;
+	const state = user[1] as ListState<any>;
+	const ref = user[2] as RefObject<FocusableElement | null>;
+
+	let { item } = props;
+	let stringFormatter = useLocalizedStringFormatter(
+		intlMessages,
+		'@react-aria/tag',
+		subSlot(slot, 'strings'),
+	);
+	let buttonId = useId(subSlot(slot, 'buttonId'));
+
+	let { onRemove } = hookData.get(state) || {};
+	let { rowProps, gridCellProps, ...states } = useGridListItem(
+		{
+			node: item,
+		},
+		state,
+		ref,
+		subSlot(slot, 'gridListItem'),
+	);
+
+	let { descriptionProps: _, ...stateWithoutDescription } = states;
+
+	let isDisabled = state.disabledKeys.has(item.key) || item.props.isDisabled;
+	let onKeyDown = (e: KeyboardEvent) => {
+		if (e.key === 'Delete' || e.key === 'Backspace') {
+			if (isDisabled) {
+				return;
+			}
+
+			e.preventDefault();
+			if (state.selectionManager.isSelected(item.key)) {
+				onRemove?.(new Set(state.selectionManager.selectedKeys));
+			} else {
+				onRemove?.(new Set([item.key]));
+			}
+		}
+	};
+
+	let modality = useInteractionModality(subSlot(slot, 'modality'));
+	if (modality === 'virtual' && typeof window !== 'undefined' && 'ontouchstart' in window) {
+		modality = 'pointer';
+	}
+	let description =
+		onRemove && (modality === 'keyboard' || modality === 'virtual')
+			? stringFormatter.format('removeDescription')
+			: '';
+	let descProps = useDescription(description, subSlot(slot, 'description'));
+
+	let isItemFocused = item.key === state.selectionManager.focusedKey;
+	let isFocused = state.selectionManager.focusedKey != null;
+	let tabIndex = -1;
+	if (!isDisabled && (isItemFocused || !isFocused)) {
+		tabIndex = 0;
+	}
+
+	let domProps = filterDOMProps(item.props);
+	let linkProps = useSyntheticLinkProps(item.props);
+	let { focusableProps } = useFocusable(
+		{
+			...item.props,
+			isDisabled,
+		},
+		ref,
+		subSlot(slot, 'focusable'),
+	);
+
+	return {
+		removeButtonProps: {
+			'aria-label': stringFormatter.format('removeButtonLabel'),
+			'aria-labelledby': `${buttonId} ${rowProps.id}`,
+			isDisabled,
+			id: buttonId,
+			onPress: () => (onRemove ? onRemove(new Set([item.key])) : null),
+		},
+		rowProps: mergeProps(focusableProps, rowProps, domProps, linkProps, {
+			tabIndex,
+			onKeyDown: onRemove ? onKeyDown : undefined,
+			'aria-describedby': descProps['aria-describedby'],
+		}),
+		gridCellProps: mergeProps(gridCellProps, {
+			'aria-errormessage': props['aria-errormessage'],
+			'aria-label': props['aria-label'],
+		}),
+		...stateWithoutDescription,
+		allowsRemoving: !!onRemove,
+	};
+}

package/src/tag/useTagGroup.ts

@@ -0,0 +1,192 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/tag/useTagGroup.ts).
+// octane adaptations:
+// - `ListState` comes from the ported stately list hook; `DOMAttributes` is a local
+//   structural prop-bag alias; React's `ReactNode` errorMessage type → `any` (octane
+//   renderables).
+// - Public-hook slot threading (splitSlot/subSlot); explicit dependency arrays are kept
+//   verbatim.
+import { AriaGridListProps, useGridList } from '../gridlist/useGridList';
+
+import type {
+	AriaLabelingProps,
+	CollectionBase,
+	DOMProps,
+	HelpTextProps,
+	Key,
+	KeyboardDelegate,
+	LabelableProps,
+	MultipleSelection,
+	RefObject,
+	SelectionBehavior,
+} from '@react-types/shared';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { ListKeyboardDelegate } from '../selection/ListKeyboardDelegate';
+import type { ListState } from '../stately/list/useListState';
+import { mergeProps } from '../utils/mergeProps';
+import { useEffect, useRef, useState } from 'octane';
+import { useField } from '../label/useField';
+import { useFocusWithin } from '../interactions/useFocusWithin';
+import { useLocale } from '../i18n/I18nProvider';
+
+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 TagGroupAria {
+	/** Props for the tag grouping element. */
+	gridProps: DOMAttributes;
+	/** Props for the tag group's visible label (if any). */
+	labelProps: DOMAttributes;
+	/** Props for the tag group description element, if any. */
+	descriptionProps: DOMAttributes;
+	/** Props for the tag group error message element, if any. */
+	errorMessageProps: DOMAttributes;
+}
+
+export interface AriaTagGroupProps<T>
+	extends
+		CollectionBase<T>,
+		MultipleSelection,
+		Pick<AriaGridListProps<T>, 'escapeKeyBehavior' | 'onAction'>,
+		DOMProps,
+		LabelableProps,
+		AriaLabelingProps,
+		Omit<HelpTextProps, 'errorMessage'> {
+	/**
+	 * How multiple selection should behave in the collection.
+	 *
+	 * @default 'toggle'
+	 */
+	selectionBehavior?: SelectionBehavior;
+	/** Whether selection should occur on press up instead of press down. */
+	shouldSelectOnPressUp?: boolean;
+	/** Handler that is called when a user deletes a tag. */
+	onRemove?: (keys: Set<Key>) => void;
+	/** An error message for the field. */
+	errorMessage?: any;
+	/**
+	 * Whether pressing the escape key should clear selection in the TagGroup 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 AriaTagGroupOptions<T> extends Omit<AriaTagGroupProps<T>, 'children'> {
+	/**
+	 * An optional keyboard delegate to handle arrow key navigation,
+	 * to override the default.
+	 */
+	keyboardDelegate?: KeyboardDelegate;
+}
+
+interface HookData {
+	onRemove?: (keys: Set<Key>) => void;
+}
+
+export const hookData: WeakMap<ListState<any>, HookData> = new WeakMap<ListState<any>, HookData>();
+
+/**
+ * Provides the behavior and accessibility implementation for a tag group component. A tag group is
+ * a focusable list of labels, categories, keywords, filters, or other items, with support for
+ * keyboard navigation, selection, and removal.
+ *
+ * @param props - Props to be applied to the tag group.
+ * @param state - State for the tag group, as returned by `useListState`.
+ * @param ref - A ref to a DOM element for the tag group.
+ */
+export function useTagGroup<T>(
+	props: AriaTagGroupOptions<T>,
+	state: ListState<T>,
+	ref: RefObject<HTMLElement | null>,
+): TagGroupAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTagGroup<T>(
+	props: AriaTagGroupOptions<T>,
+	state: ListState<T>,
+	ref: RefObject<HTMLElement | null>,
+	slot: symbol | undefined,
+): TagGroupAria;
+export function useTagGroup(...args: any[]): TagGroupAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTagGroup');
+	const props = user[0] as AriaTagGroupOptions<any>;
+	const state = user[1] as ListState<any>;
+	const ref = user[2] as RefObject<HTMLElement | null>;
+
+	let { direction } = useLocale(subSlot(slot, 'locale'));
+	let keyboardDelegate =
+		props.keyboardDelegate ||
+		new ListKeyboardDelegate({
+			collection: state.collection,
+			ref,
+			orientation: 'horizontal',
+			direction,
+			disabledKeys: state.disabledKeys,
+			disabledBehavior: state.selectionManager.disabledBehavior,
+		});
+	let { labelProps, fieldProps, descriptionProps, errorMessageProps } = useField(
+		{
+			...props,
+			labelElementType: 'span',
+		},
+		subSlot(slot, 'field'),
+	);
+	let { gridProps } = useGridList(
+		{
+			...props,
+			...fieldProps,
+			keyboardDelegate,
+			shouldFocusWrap: true,
+			linkBehavior: 'override',
+			keyboardNavigationBehavior: 'tab',
+		},
+		state,
+		ref,
+		subSlot(slot, 'gridList'),
+	);
+
+	let [isFocusWithin, setFocusWithin] = useState(false, subSlot(slot, 'focusWithin'));
+	let { focusWithinProps } = useFocusWithin(
+		{
+			onFocusWithinChange: setFocusWithin,
+		},
+		subSlot(slot, 'focusWithinHook'),
+	);
+	let domProps = filterDOMProps(props);
+
+	// If the last tag is removed, focus the container.
+	let prevCount = useRef(state.collection.size, subSlot(slot, 'prevCount'));
+	useEffect(
+		() => {
+			if (ref.current && prevCount.current > 0 && state.collection.size === 0 && isFocusWithin) {
+				ref.current.focus();
+			}
+			prevCount.current = state.collection.size;
+		},
+		[state.collection.size, isFocusWithin, ref],
+		subSlot(slot, 'focusContainerFx'),
+	);
+
+	hookData.set(state, { onRemove: props.onRemove });
+
+	return {
+		gridProps: mergeProps(gridProps, domProps, {
+			role: state.collection.size ? 'grid' : 'group',
+			'aria-atomic': false,
+			'aria-relevant': 'additions',
+			'aria-live': isFocusWithin ? 'polite' : 'off',
+			...focusWithinProps,
+			...fieldProps,
+		}),
+		labelProps,
+		descriptionProps,
+		errorMessageProps,
+	};
+}

package/src/textfield/useFormattedTextField.ts

@@ -0,0 +1,203 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/textfield/useFormattedTextField.ts).
+// octane adaptations:
+// - Handlers receive NATIVE events: octane's `onBeforeInput` prop IS the native
+//   `beforeinput` event, so the upstream "React polyfill" fallback branch (for browsers
+//   without native beforeinput support) receives the same native InputEvent as the
+//   directly-attached listener; the handler logic ports unchanged.
+// - `InputEventHandler` React type → a plain native-InputEvent handler.
+// - Public-hook slot threading; explicit dependency arrays are kept verbatim.
+import { AriaTextFieldProps, TextFieldAria, useTextField } from './useTextField';
+import { getEventTarget } from '../utils/shadowdom/DOMFunctions';
+import { useEffect, useRef } from 'octane';
+import { mergeProps } from '../utils/mergeProps';
+import type { RefObject } from '@react-types/shared';
+import { useEffectEvent } from '../utils/useEffectEvent';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+interface FormattedTextFieldState {
+	validate: (val: string) => boolean;
+	setInputValue: (val: string) => void;
+}
+
+function supportsNativeBeforeInputEvent() {
+	return (
+		typeof window !== 'undefined' &&
+		window.InputEvent &&
+		typeof InputEvent.prototype.getTargetRanges === 'function'
+	);
+}
+
+export function useFormattedTextField(
+	props: AriaTextFieldProps,
+	state: FormattedTextFieldState,
+	inputRef: RefObject<HTMLInputElement | null>,
+): TextFieldAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useFormattedTextField(
+	props: AriaTextFieldProps,
+	state: FormattedTextFieldState,
+	inputRef: RefObject<HTMLInputElement | null>,
+	slot: symbol | undefined,
+): TextFieldAria;
+export function useFormattedTextField(...args: any[]): TextFieldAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useFormattedTextField');
+	const props = user[0] as AriaTextFieldProps;
+	const state = user[1] as FormattedTextFieldState;
+	const inputRef = user[2] as RefObject<HTMLInputElement | null>;
+
+	// All browsers implement the 'beforeinput' event natively except Firefox
+	// (currently behind a flag as of Firefox 84). React's polyfill does not
+	// run in all cases that the native event fires, e.g. when deleting text.
+	// Use the native event if available so that we can prevent invalid deletions.
+	// We do not attempt to polyfill this in Firefox since it would be very complicated,
+	// the benefit of doing so is fairly minor, and it's going to be natively supported soon.
+	let onBeforeInputFallback = useEffectEvent(
+		(e: InputEvent) => {
+			let input = inputRef.current;
+			if (!input) {
+				return;
+			}
+
+			// Compute the next value of the input if the event is allowed to proceed.
+			// See https://www.w3.org/TR/input-events-2/#interface-InputEvent-Attributes for a full list of input types.
+			let nextValue: string | null = null;
+			switch (e.inputType) {
+				case 'historyUndo':
+				case 'historyRedo':
+					// Explicitly allow undo/redo. e.data is null in this case, but there's no need to validate,
+					// because presumably the input would have already been validated previously.
+					return;
+				case 'insertLineBreak':
+					// Explicitly allow "insertLineBreak" event, to allow onSubmit for "enter" key. e.data is null in this case.
+					return;
+				case 'deleteContent':
+				case 'deleteByCut':
+				case 'deleteByDrag':
+					nextValue =
+						input.value.slice(0, input.selectionStart!) + input.value.slice(input.selectionEnd!);
+					break;
+				case 'deleteContentForward':
+					// This is potentially incorrect, since the browser may actually delete more than a single UTF-16
+					// character. In reality, a full Unicode grapheme cluster consisting of multiple UTF-16 characters
+					// or code points may be deleted. However, in our currently supported locales, there are no such cases.
+					// If we support additional locales in the future, this may need to change.
+					nextValue =
+						input.selectionEnd === input.selectionStart
+							? input.value.slice(0, input.selectionStart!) +
+								input.value.slice(input.selectionEnd! + 1)
+							: input.value.slice(0, input.selectionStart!) +
+								input.value.slice(input.selectionEnd!);
+					break;
+				case 'deleteContentBackward':
+					nextValue =
+						input.selectionEnd === input.selectionStart
+							? input.value.slice(0, input.selectionStart! - 1) +
+								input.value.slice(input.selectionStart!)
+							: input.value.slice(0, input.selectionStart!) +
+								input.value.slice(input.selectionEnd!);
+					break;
+				case 'deleteSoftLineBackward':
+				case 'deleteHardLineBackward':
+					nextValue = input.value.slice(input.selectionStart!);
+					break;
+				default:
+					if (e.data != null) {
+						nextValue =
+							input.value.slice(0, input.selectionStart!) +
+							e.data +
+							input.value.slice(input.selectionEnd!);
+					}
+					break;
+			}
+
+			// If we did not compute a value, or the new value is invalid, prevent the event
+			// so that the browser does not update the input text, move the selection, or add to
+			// the undo/redo stack.
+			if (nextValue == null || !state.validate(nextValue)) {
+				e.preventDefault();
+			}
+		},
+		subSlot(slot, 'beforeInputFallback'),
+	);
+
+	useEffect(
+		() => {
+			if (!supportsNativeBeforeInputEvent() || !inputRef.current) {
+				return;
+			}
+
+			let input = inputRef.current;
+			input.addEventListener('beforeinput', onBeforeInputFallback, false);
+			return () => {
+				input.removeEventListener('beforeinput', onBeforeInputFallback, false);
+			};
+		},
+		[inputRef],
+		subSlot(slot, 'beforeInputFx'),
+	);
+
+	let onBeforeInput: ((e: InputEvent) => void) | null = !supportsNativeBeforeInputEvent()
+		? (e: InputEvent) => {
+				let target = getEventTarget(e) as HTMLInputElement;
+				let nextValue =
+					target.value.slice(0, target.selectionStart!) +
+					e.data +
+					target.value.slice(target.selectionEnd!);
+
+				if (!state.validate(nextValue)) {
+					e.preventDefault();
+				}
+			}
+		: null;
+
+	let {
+		labelProps,
+		inputProps: textFieldProps,
+		descriptionProps,
+		errorMessageProps,
+		...validation
+	} = useTextField(props, inputRef, subSlot(slot, 'textField'));
+
+	let compositionStartState = useRef<{
+		value: string;
+		selectionStart: number | null;
+		selectionEnd: number | null;
+	} | null>(null, subSlot(slot, 'compositionStart'));
+	return {
+		inputProps: mergeProps(textFieldProps, {
+			onBeforeInput,
+			onCompositionStart() {
+				// Chrome does not implement Input Events Level 2, which specifies the insertFromComposition
+				// and deleteByComposition inputType values for the beforeinput event. These are meant to occur
+				// at the end of a composition (e.g. Pinyin IME, Android auto correct, etc.), and crucially, are
+				// cancelable. The insertCompositionText and deleteCompositionText input types are not cancelable,
+				// nor would we want to cancel them because the input from the user is incomplete at that point.
+				// In Safari, insertFromComposition/deleteFromComposition will fire, however, allowing us to cancel
+				// the final composition result if it is invalid. As a fallback for Chrome and Firefox, which either
+				// don't support Input Events Level 2, or beforeinput at all, we store the state of the input when
+				// the compositionstart event fires, and undo the changes in compositionend (below) if it is invalid.
+				// Unfortunately, this messes up the undo/redo stack, but until insertFromComposition/deleteByComposition
+				// are implemented, there is no other way to prevent composed input.
+				// See https://bugs.chromium.org/p/chromium/issues/detail?id=1022204
+				let { value, selectionStart, selectionEnd } = inputRef.current!;
+				compositionStartState.current = { value, selectionStart, selectionEnd };
+			},
+			onCompositionEnd() {
+				if (inputRef.current && !state.validate(inputRef.current.value)) {
+					// Restore the input value in the DOM immediately so we can synchronously update the selection position.
+					// But also update the value in state as well so it is correct for future updates.
+					let { value, selectionStart, selectionEnd } = compositionStartState.current!;
+					inputRef.current.value = value;
+					inputRef.current.setSelectionRange(selectionStart, selectionEnd);
+					state.setInputValue(value);
+				}
+			},
+		}),
+		labelProps,
+		descriptionProps,
+		errorMessageProps,
+		...validation,
+	};
+}