@octanejs/aria 0.0.1 → 0.0.4

package/src/intl/tag/it-IT.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Rimuovi",
+  "removeDescription": "Premi Elimina per rimuovere il tag."
+}

package/src/intl/tag/ja-JP.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "削除",
+  "removeDescription": "タグを削除するには、Delete キーを押します。"
+}

package/src/intl/tag/ko-KR.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "제거",
+  "removeDescription": "태그를 제거하려면 Delete 키를 누르십시오."
+}

package/src/intl/tag/lt-LT.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Pašalinti",
+  "removeDescription": "Norėdami pašalinti žymą, paspauskite „Delete“ klavišą."
+}

package/src/intl/tag/lv-LV.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Noņemt",
+  "removeDescription": "Nospiediet Delete [Dzēst], lai noņemtu tagu."
+}

package/src/intl/tag/nb-NO.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Fjern",
+  "removeDescription": "Trykk på Slett for å fjerne taggen."
+}

package/src/intl/tag/nl-NL.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Verwijderen",
+  "removeDescription": "Druk op Verwijderen om de tag te verwijderen."
+}

package/src/intl/tag/pl-PL.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Usuń",
+  "removeDescription": "Naciśnij Usuń, aby usunąć znacznik."
+}

package/src/intl/tag/pt-BR.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Remover",
+  "removeDescription": "Pressione Delete para remover a tag."
+}

package/src/intl/tag/pt-PT.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Eliminar",
+  "removeDescription": "Prima Delete para eliminar a tag."
+}

package/src/intl/tag/ro-RO.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Îndepărtaţi",
+  "removeDescription": "Apăsați pe Delete (Ștergere) pentru a elimina eticheta."
+}

package/src/intl/tag/ru-RU.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Удалить",
+  "removeDescription": "Нажмите DELETE, чтобы удалить тег."
+}

package/src/intl/tag/sk-SK.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Odstrániť",
+  "removeDescription": "Ak chcete odstrániť značku, stlačte kláves Delete."
+}

package/src/intl/tag/sl-SI.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Odstrani",
+  "removeDescription": "Pritisnite Delete, da odstranite oznako."
+}

package/src/intl/tag/sr-SP.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Ukloni",
+  "removeDescription": "Pritisnite Obriši da biste uklonili oznaku."
+}

package/src/intl/tag/sv-SE.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Ta bort",
+  "removeDescription": "Tryck på Radera för att ta bort taggen."
+}

package/src/intl/tag/tr-TR.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Kaldır",
+  "removeDescription": "Etiketi kaldırmak için Sil tuşuna basın."
+}

package/src/intl/tag/uk-UA.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "Вилучити",
+  "removeDescription": "Натисніть Delete, щоб вилучити тег."
+}

package/src/intl/tag/zh-CN.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "删除",
+  "removeDescription": "按下“删除”以删除标记。"
+}

package/src/intl/tag/zh-TW.json

@@ -0,0 +1,4 @@
+{
+  "removeButtonLabel": "移除",
+  "removeDescription": "按 Delete 鍵以移除標記。"
+}

package/src/label/useField.ts

@@ -0,0 +1,67 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/label/useField.ts).
+import type { DOMAttributes, HelpTextProps, Validation } from '@react-types/shared';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { LabelAria, LabelAriaProps, useLabel } from './useLabel';
+import { mergeProps } from '../utils/mergeProps';
+import { useSlotId } from '../utils/useId';
+
+export interface AriaFieldProps
+	extends LabelAriaProps, HelpTextProps, Omit<Validation<any>, 'isRequired'> {}
+
+export interface FieldAria extends LabelAria {
+	/** Props for the description element, if any. */
+	descriptionProps: DOMAttributes;
+	/** Props for the error message element, if any. */
+	errorMessageProps: DOMAttributes;
+}
+
+/**
+ * Provides the accessibility implementation for input fields. Fields accept user input, gain
+ * context from their label, and may display a description or error message.
+ *
+ * @param props - Props for the Field.
+ */
+export function useField(props: AriaFieldProps): FieldAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useField(props: AriaFieldProps, slot: symbol | undefined): FieldAria;
+export function useField(...args: any[]): FieldAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useField');
+	const props = user[0] as AriaFieldProps;
+
+	let { description, errorMessage, isInvalid, validationState } = props;
+	let { labelProps, fieldProps } = useLabel(props, subSlot(slot, 'label'));
+
+	let descriptionId = useSlotId(
+		[Boolean(description), Boolean(errorMessage), isInvalid, validationState],
+		subSlot(slot, 'descriptionId'),
+	);
+	let errorMessageId = useSlotId(
+		[Boolean(description), Boolean(errorMessage), isInvalid, validationState],
+		subSlot(slot, 'errorMessageId'),
+	);
+
+	fieldProps = mergeProps(fieldProps, {
+		'aria-describedby':
+			[
+				descriptionId,
+				// Use aria-describedby for error message because aria-errormessage is unsupported using VoiceOver or NVDA. See https://github.com/adobe/react-spectrum/issues/1346#issuecomment-740136268
+				errorMessageId,
+				props['aria-describedby'],
+			]
+				.filter(Boolean)
+				.join(' ') || undefined,
+	});
+
+	return {
+		labelProps,
+		fieldProps,
+		descriptionProps: {
+			id: descriptionId,
+		},
+		errorMessageProps: {
+			id: errorMessageId,
+		},
+	};
+}

package/src/label/useLabel.ts

@@ -0,0 +1,78 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/label/useLabel.ts).
+// octane adaptations: React's ElementType/LabelHTMLAttributes → local structural types;
+// the dev-only missing-label console.warn is not ported (repo policy).
+import type {
+	AriaLabelingProps,
+	DOMAttributes,
+	DOMProps,
+	LabelableProps,
+} from '@react-types/shared';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useId } from '../utils/useId';
+import { useLabels } from '../utils/useLabels';
+
+export interface LabelAriaProps extends LabelableProps, DOMProps, AriaLabelingProps {
+	/**
+	 * The HTML element used to render the label, e.g. 'label', or 'span'.
+	 *
+	 * @default 'label'
+	 */
+	labelElementType?: string;
+}
+
+export interface LabelAria {
+	/** Props to apply to the label container element. */
+	labelProps: DOMAttributes & { htmlFor?: string };
+	/** Props to apply to the field container element being labeled. */
+	fieldProps: AriaLabelingProps & DOMProps;
+}
+
+/**
+ * Provides the accessibility implementation for labels and their associated elements.
+ * Labels provide context for user inputs.
+ *
+ * @param props - The props for labels and fields.
+ */
+export function useLabel(props: LabelAriaProps): LabelAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useLabel(props: LabelAriaProps, slot: symbol | undefined): LabelAria;
+export function useLabel(...args: any[]): LabelAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useLabel');
+	const props = user[0] as LabelAriaProps;
+
+	let {
+		id,
+		label,
+		'aria-labelledby': ariaLabelledby,
+		'aria-label': ariaLabel,
+		labelElementType = 'label',
+	} = props;
+
+	id = useId(id, subSlot(slot, 'id'));
+	let labelId = useId(subSlot(slot, 'labelId'));
+	let labelProps = {};
+	if (label) {
+		ariaLabelledby = ariaLabelledby ? `${labelId} ${ariaLabelledby}` : labelId;
+		labelProps = {
+			id: labelId,
+			htmlFor: labelElementType === 'label' ? id : undefined,
+		};
+	}
+
+	let fieldProps = useLabels(
+		{
+			id,
+			'aria-label': ariaLabel,
+			'aria-labelledby': ariaLabelledby,
+		},
+		undefined,
+		subSlot(slot, 'fieldProps'),
+	);
+
+	return {
+		labelProps,
+		fieldProps,
+	};
+}

package/src/link/useLink.ts

@@ -0,0 +1,108 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/link/useLink.ts).
+// octane adaptations: `FocusableProps` is the ported native-event version; the wrapped
+// `onClick` receives the NATIVE MouseEvent; public-hook slot threading per convention.
+import type {
+	AriaLabelingProps,
+	FocusableElement,
+	LinkDOMProps,
+	PressEvents,
+	RefObject,
+} from '@react-types/shared';
+
+// octane adaptation: structural prop bag (upstream's DOMAttributes drags React handler
+// types; the wrapped onClick is a native MouseEvent handler).
+type DOMAttributes = Record<string, any>;
+
+import type { FocusableProps } from '../interactions/useFocusable';
+import { S, splitSlot, subSlot } from '../internal';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { handleLinkClick, useLinkProps, useRouter } from '../utils/openLink';
+import { mergeProps } from '../utils/mergeProps';
+import { useFocusable } from '../interactions/useFocusable';
+import { usePress } from '../interactions/usePress';
+
+export interface LinkProps extends Omit<PressEvents, 'onClick'>, FocusableProps {}
+
+export interface AriaLinkProps extends LinkProps, LinkDOMProps, AriaLabelingProps {}
+
+export interface AriaLinkOptions extends AriaLinkProps {
+	/** Whether the link is disabled. */
+	isDisabled?: boolean;
+	/**
+	 * The HTML element used to render the link, e.g. 'a', or 'span'.
+	 *
+	 * @default 'a'
+	 */
+	elementType?: string;
+	/** Handler called on the native click event (octane native MouseEvent). */
+	onClick?: (e: MouseEvent) => void;
+}
+
+export interface LinkAria {
+	/** Props for the link element. */
+	linkProps: DOMAttributes;
+	/** Whether the link is currently pressed. */
+	isPressed: boolean;
+}
+
+export function useLink(props: AriaLinkOptions, ref: RefObject<FocusableElement | null>): LinkAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useLink(
+	props: AriaLinkOptions,
+	ref: RefObject<FocusableElement | null>,
+	slot: symbol | undefined,
+): LinkAria;
+export function useLink(...args: any[]): LinkAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useLink');
+	const props = user[0] as AriaLinkOptions;
+	const ref = user[1] as RefObject<FocusableElement | null>;
+
+	let {
+		elementType = 'a',
+		onPress,
+		onPressStart,
+		onPressEnd,
+		onClick,
+		isDisabled,
+		...otherProps
+	} = props;
+
+	let linkProps: DOMAttributes = {};
+	if (elementType !== 'a') {
+		linkProps = {
+			role: 'link',
+			tabIndex: !isDisabled ? 0 : undefined,
+		};
+	}
+	let { focusableProps } = useFocusable(props, ref, subSlot(slot, 'focusable'));
+	let { pressProps, isPressed } = usePress(
+		{
+			onPress,
+			onPressStart,
+			onPressEnd,
+			onClick,
+			isDisabled,
+			ref,
+		},
+		subSlot(slot, 'press'),
+	);
+	let domProps = filterDOMProps(otherProps as any, { labelable: true });
+	let interactionHandlers = mergeProps(focusableProps, pressProps);
+	let router = useRouter();
+	let routerLinkProps = useLinkProps(props);
+
+	return {
+		isPressed, // Used to indicate press state for visual
+		linkProps: mergeProps(domProps, routerLinkProps, {
+			...interactionHandlers,
+			...linkProps,
+			'aria-disabled': isDisabled || undefined,
+			'aria-current': (props as any)['aria-current'],
+			onClick: (e: MouseEvent) => {
+				(pressProps as any).onClick?.(e);
+				handleLinkClick(e, router, props.href, props.routerOptions);
+			},
+		}),
+	};
+}

package/src/listbox/useListBox.ts

@@ -0,0 +1,224 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/listbox/useListBox.ts).
+// octane adaptations:
+// - `FocusEvents` handler props are the ported NATIVE-event versions (from useFocus);
+//   `DOMAttributes` is a local structural prop-bag alias (upstream's is typed over React's
+//   synthetic handlers); `ReactNode` label → `any` (octane descriptors).
+// - `ListState` type from the ported stately list state.
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention.
+import type {
+	AriaLabelingProps,
+	CollectionBase,
+	DOMProps,
+	FocusStrategy,
+	Key,
+	KeyboardDelegate,
+	LayoutDelegate,
+	MultipleSelection,
+	Orientation,
+	RefObject,
+	SelectionBehavior,
+} from '@react-types/shared';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import type { FocusEvents } from '../interactions/useFocus';
+import { listData } from './utils';
+import type { ListState } from '../stately/list/useListState';
+import { mergeProps } from '../utils/mergeProps';
+import { useFocusWithin } from '../interactions/useFocusWithin';
+import { useId } from '../utils/useId';
+import { useLabel } from '../label/useLabel';
+import { useSelectableList } from '../selection/useSelectableList';
+
+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 ListBoxProps<T> extends CollectionBase<T>, MultipleSelection, FocusEvents {
+	/** Whether to auto focus the listbox or an option. */
+	autoFocus?: boolean | FocusStrategy;
+	/** Whether focus should wrap around when the end/start is reached. */
+	shouldFocusWrap?: boolean;
+}
+
+export interface AriaListBoxPropsBase<T> extends ListBoxProps<T>, DOMProps, AriaLabelingProps {
+	/**
+	 * Whether pressing the escape key should clear selection in the listbox 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 AriaListBoxProps<T> extends AriaListBoxPropsBase<T> {
+	/**
+	 * An optional visual label for the listbox.
+	 */
+	label?: any;
+	/** How multiple selection should behave in the collection. */
+	selectionBehavior?: SelectionBehavior;
+	/** Whether selection should occur on press up instead of press down. */
+	shouldSelectOnPressUp?: boolean;
+	/** Whether options should be focused when the user hovers over them. */
+	shouldFocusOnHover?: boolean;
+	/**
+	 * Handler that is called when a user performs an action on an item. The exact user event depends
+	 * on the collection's `selectionBehavior` prop and the interaction modality.
+	 */
+	onAction?: (key: Key) => void;
+}
+
+export interface ListBoxAria {
+	/** Props for the listbox element. */
+	listBoxProps: DOMAttributes;
+	/** Props for the listbox's visual label element (if any). */
+	labelProps: DOMAttributes;
+}
+
+export interface AriaListBoxOptions<T> extends Omit<AriaListBoxProps<T>, 'children'> {
+	/** Whether the listbox uses virtual scrolling. */
+	isVirtualized?: boolean;
+
+	/**
+	 * An optional keyboard delegate implementation for type to select,
+	 * to override the default.
+	 */
+	keyboardDelegate?: KeyboardDelegate;
+
+	/**
+	 * A delegate object that provides layout information for items in the collection.
+	 * By default this uses the DOM, but this can be overridden to implement things like
+	 * virtualized scrolling.
+	 */
+	layoutDelegate?: LayoutDelegate;
+
+	/**
+	 * Whether the listbox items should use virtual focus instead of being focused directly.
+	 */
+	shouldUseVirtualFocus?: boolean;
+
+	/**
+	 * The behavior of links in the collection.
+	 * - 'action': link behaves like onAction.
+	 * - 'selection': link follows selection interactions (e.g. if URL drives selection).
+	 * - 'override': links override all other interactions (link items are not selectable).
+	 *
+	 * @default 'override'
+	 */
+	linkBehavior?: 'action' | 'selection' | 'override';
+
+	/**
+	 * The primary orientation of the items. Usually this is the direction that the collection
+	 * scrolls.
+	 *
+	 * @default 'vertical'
+	 */
+	orientation?: Orientation;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a listbox component.
+ * A listbox displays a list of options and allows a user to select one or more of them.
+ *
+ * @param props - Props for the listbox.
+ * @param state - State for the listbox, as returned by `useListState`.
+ */
+export function useListBox<T>(
+	props: AriaListBoxOptions<T>,
+	state: ListState<T>,
+	ref: RefObject<HTMLElement | null>,
+): ListBoxAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useListBox<T>(
+	props: AriaListBoxOptions<T>,
+	state: ListState<T>,
+	ref: RefObject<HTMLElement | null>,
+	slot: symbol | undefined,
+): ListBoxAria;
+export function useListBox(...args: any[]): ListBoxAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useListBox');
+	const props = user[0] as AriaListBoxOptions<unknown>;
+	const state = user[1] as ListState<unknown>;
+	const ref = user[2] as RefObject<HTMLElement | null>;
+
+	let domProps = filterDOMProps(props, { labelable: true });
+	// Use props instead of state here. We don't want this to change due to long press.
+	let selectionBehavior = props.selectionBehavior || 'toggle';
+	let orientation = props.orientation || 'vertical';
+	let linkBehavior =
+		props.linkBehavior || (selectionBehavior === 'replace' ? 'action' : 'override');
+	if (selectionBehavior === 'toggle' && linkBehavior === 'action') {
+		// linkBehavior="action" does not work with selectionBehavior="toggle" because there is no way
+		// to initiate selection (checkboxes are not allowed inside a listbox). Link items will not be
+		// selectable in this configuration.
+		linkBehavior = 'override';
+	}
+
+	let { listProps } = useSelectableList(
+		{
+			...props,
+			ref,
+			selectionManager: state.selectionManager,
+			collection: state.collection,
+			disabledKeys: state.disabledKeys,
+			linkBehavior,
+		},
+		subSlot(slot, 'list'),
+	);
+
+	let { focusWithinProps } = useFocusWithin(
+		{
+			onFocusWithin: props.onFocus,
+			onBlurWithin: props.onBlur,
+			onFocusWithinChange: props.onFocusChange,
+		},
+		subSlot(slot, 'focusWithin'),
+	);
+
+	// Share list id and some props with child options.
+	let id = useId(props.id, subSlot(slot, 'id'));
+	listData.set(state, {
+		id,
+		shouldUseVirtualFocus: props.shouldUseVirtualFocus,
+		shouldSelectOnPressUp: props.shouldSelectOnPressUp,
+		shouldFocusOnHover: props.shouldFocusOnHover,
+		isVirtualized: props.isVirtualized,
+		onAction: props.onAction,
+		linkBehavior,
+		// @ts-ignore
+		UNSTABLE_itemBehavior: (props as any)['UNSTABLE_itemBehavior'],
+	});
+
+	let { labelProps, fieldProps } = useLabel(
+		{
+			...props,
+			id,
+			// listbox is not an HTML input element so it
+			// shouldn't be labeled by a <label> element.
+			labelElementType: 'span',
+		},
+		subSlot(slot, 'label'),
+	);
+
+	return {
+		labelProps,
+		listBoxProps: mergeProps(
+			domProps,
+			focusWithinProps,
+			state.selectionManager.selectionMode === 'multiple'
+				? {
+						'aria-multiselectable': 'true',
+					}
+				: {},
+			{
+				role: 'listbox',
+				'aria-orientation': orientation,
+				...mergeProps(fieldProps, listProps),
+			},
+		),
+	};
+}

package/src/listbox/useListBoxSection.ts

@@ -0,0 +1,74 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/listbox/useListBoxSection.ts).
+// octane adaptations: `ReactNode` heading → `any` (octane descriptors); the heading's
+// `onMouseDown` receives the NATIVE MouseEvent; `DOMAttributes` is a local structural
+// prop-bag alias; public-hook slot threading (splitSlot/subSlot) per the binding convention.
+import { useId } from '../utils/useId';
+
+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 AriaListBoxSectionProps {
+	/** The heading for the section. */
+	heading?: any;
+	/** An accessibility label for the section. Required if `heading` is not present. */
+	'aria-label'?: string;
+}
+
+export interface ListBoxSectionAria {
+	/** Props for the wrapper list item. */
+	itemProps: DOMAttributes;
+
+	/** Props for the heading element, if any. */
+	headingProps: DOMAttributes;
+
+	/** Props for the group element. */
+	groupProps: DOMAttributes;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a section in a listbox.
+ * See `useListBox` for more details about listboxes.
+ *
+ * @param props - Props for the section.
+ */
+export function useListBoxSection(props: AriaListBoxSectionProps): ListBoxSectionAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useListBoxSection(
+	props: AriaListBoxSectionProps,
+	slot: symbol | undefined,
+): ListBoxSectionAria;
+export function useListBoxSection(...args: any[]): ListBoxSectionAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useListBoxSection');
+	const props = user[0] as AriaListBoxSectionProps;
+
+	let { heading, 'aria-label': ariaLabel } = props;
+	let headingId = useId(subSlot(slot, 'headingId'));
+
+	return {
+		itemProps: {
+			role: 'presentation',
+		},
+		headingProps: heading
+			? {
+					// Technically, listbox cannot contain headings according to ARIA.
+					// We hide the heading from assistive technology, using role="presentation",
+					// and only use it as a visual label for the nested group.
+					id: headingId,
+					role: 'presentation',
+					onMouseDown: (e: MouseEvent) => {
+						// Prevent DOM focus from moving on mouse down when using virtual focus
+						e.preventDefault();
+					},
+				}
+			: {},
+		groupProps: {
+			role: 'group',
+			'aria-label': ariaLabel,
+			'aria-labelledby': heading ? headingId : undefined,
+		},
+	};
+}