@octanejs/aria 0.0.1 → 0.0.3

package/src/grid/useGridSelectionCheckbox.ts

@@ -0,0 +1,86 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/grid/useGridSelectionCheckbox.ts).
+// GRID SUBSET: see useGridSelectionAnnouncement.ts — only the grid-area hooks the
+// gridlist area imports are ported.
+// octane adaptations:
+// - Upstream types the state over `GridState<T, C>`; the full grid state area is not
+//   ported, and only `state.selectionManager` is read, so the parameter is a structural
+//   `{ selectionManager }` bag (the gridlist caller already passed `state as any`
+//   upstream).
+// - The checkbox `onChange` here is the value-level AriaCheckboxProps callback (not DOM
+//   wiring), so it ports unchanged.
+// - The Parcel glob intl import becomes the generated src/intl/grid index (verbatim
+//   dictionaries).
+// - Public-hook slot threading (splitSlot/subSlot).
+import type { AriaCheckboxProps } from '../checkbox/useCheckbox';
+import intlMessages from '../intl/grid';
+import type { Key } from '@react-types/shared';
+import type { MultipleSelectionManager } from '../stately/selection/types';
+import { useId } from '../utils/useId';
+import { useLocalizedStringFormatter } from '../i18n/useLocalizedStringFormatter';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export interface AriaGridSelectionCheckboxProps {
+	/** A unique key for the checkbox. */
+	key: Key;
+}
+
+export interface GridSelectionCheckboxAria {
+	/** Props for the row selection checkbox element. */
+	checkboxProps: AriaCheckboxProps;
+}
+
+// octane adaptation: structural stand-in for upstream's GridState (only the selection
+// manager is consumed here).
+interface GridSelectionCheckboxState {
+	selectionManager: MultipleSelectionManager;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a selection checkbox in a grid.
+ *
+ * @param props - Props for the selection checkbox.
+ * @param state - State of the grid, as returned by `useGridState`.
+ */
+export function useGridSelectionCheckbox(
+	props: AriaGridSelectionCheckboxProps,
+	state: GridSelectionCheckboxState,
+): GridSelectionCheckboxAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useGridSelectionCheckbox(
+	props: AriaGridSelectionCheckboxProps,
+	state: GridSelectionCheckboxState,
+	slot: symbol | undefined,
+): GridSelectionCheckboxAria;
+export function useGridSelectionCheckbox(...args: any[]): GridSelectionCheckboxAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useGridSelectionCheckbox');
+	const props = user[0] as AriaGridSelectionCheckboxProps;
+	const state = user[1] as GridSelectionCheckboxState;
+
+	let { key } = props;
+
+	let manager = state.selectionManager;
+	let checkboxId = useId(subSlot(slot, 'checkboxId'));
+	let isDisabled = !state.selectionManager.canSelectItem(key);
+	let isSelected = state.selectionManager.isSelected(key);
+
+	// Checkbox should always toggle selection, regardless of selectionBehavior.
+	let onChange = () => manager.toggleSelection(key);
+
+	const stringFormatter = useLocalizedStringFormatter(
+		intlMessages,
+		'@react-aria/grid',
+		subSlot(slot, 'strings'),
+	);
+
+	return {
+		checkboxProps: {
+			id: checkboxId,
+			'aria-label': stringFormatter.format('select'),
+			isSelected,
+			isDisabled,
+			onChange,
+		},
+	};
+}

package/src/grid/useHighlightSelectionDescription.ts

@@ -0,0 +1,81 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/grid/useHighlightSelectionDescription.ts).
+// GRID SUBSET: see useGridSelectionAnnouncement.ts — only the grid-area hooks the
+// gridlist area imports are ported.
+// octane adaptations:
+// - `MultipleSelectionManager` comes from the ported stately selection types.
+// - 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 type { AriaLabelingProps } from '@react-types/shared';
+import intlMessages from '../intl/grid';
+import type { MultipleSelectionManager } from '../stately/selection/types';
+import { useDescription } from '../utils/useDescription';
+import { useInteractionModality } from '../interactions/useFocusVisible';
+import { useLocalizedStringFormatter } from '../i18n/useLocalizedStringFormatter';
+import { useMemo } from 'octane';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export interface HighlightSelectionDescriptionProps {
+	selectionManager: MultipleSelectionManager;
+	hasItemActions?: boolean;
+}
+
+/**
+ * Computes the description for a grid selectable collection.
+ *
+ * @param props
+ */
+export function useHighlightSelectionDescription(
+	props: HighlightSelectionDescriptionProps,
+): AriaLabelingProps;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useHighlightSelectionDescription(
+	props: HighlightSelectionDescriptionProps,
+	slot: symbol | undefined,
+): AriaLabelingProps;
+export function useHighlightSelectionDescription(...args: any[]): AriaLabelingProps {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useHighlightSelectionDescription');
+	const props = user[0] as HighlightSelectionDescriptionProps;
+
+	let stringFormatter = useLocalizedStringFormatter(
+		intlMessages,
+		'@react-aria/grid',
+		subSlot(slot, 'strings'),
+	);
+	let modality = useInteractionModality(subSlot(slot, 'modality'));
+	// null is the default if the user hasn't interacted with the table at all yet or the rest of the page
+	let shouldLongPress =
+		(modality === 'pointer' || modality === 'virtual' || modality == null) &&
+		typeof window !== 'undefined' &&
+		'ontouchstart' in window;
+
+	let interactionDescription = useMemo(
+		() => {
+			let selectionMode = props.selectionManager.selectionMode;
+			let selectionBehavior = props.selectionManager.selectionBehavior;
+
+			let message: string | undefined;
+			if (shouldLongPress) {
+				message = stringFormatter.format('longPressToSelect');
+			}
+
+			return selectionBehavior === 'replace' && selectionMode !== 'none' && props.hasItemActions
+				? message
+				: undefined;
+		},
+		[
+			props.selectionManager.selectionMode,
+			props.selectionManager.selectionBehavior,
+			props.hasItemActions,
+			stringFormatter,
+			shouldLongPress,
+		],
+		subSlot(slot, 'description'),
+	);
+
+	let descriptionProps = useDescription(interactionDescription, subSlot(slot, 'describe'));
+	return descriptionProps;
+}

package/src/gridlist/useGridList.ts

@@ -0,0 +1,236 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/gridlist/useGridList.ts).
+// octane adaptations:
+// - `ListState` comes from the ported stately list hook; `DOMAttributes` is a local
+//   structural prop-bag alias (upstream's is typed over React's synthetic handlers).
+// - The grid-area imports resolve to the ported GRID SUBSET (useGridSelectionAnnouncement
+//   and useHighlightSelectionDescription — see src/grid/).
+// - Public-hook slot threading (splitSlot/subSlot).
+import type {
+	AriaLabelingProps,
+	CollectionBase,
+	DisabledBehavior,
+	DOMProps,
+	FocusStrategy,
+	Key,
+	KeyboardDelegate,
+	LayoutDelegate,
+	MultipleSelection,
+	RefObject,
+} from '@react-types/shared';
+import { filterDOMProps } from '../utils/filterDOMProps';
+import { listMap } from './utils';
+import type { ListState } from '../stately/list/useListState';
+import { mergeProps } from '../utils/mergeProps';
+import { useGridSelectionAnnouncement } from '../grid/useGridSelectionAnnouncement';
+import { useHasTabbableChild } from '../focus/useHasTabbableChild';
+import { useHighlightSelectionDescription } from '../grid/useHighlightSelectionDescription';
+import { useId } from '../utils/useId';
+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 GridListProps<T> extends CollectionBase<T>, MultipleSelection {
+	/** Whether to auto focus the gridlist or an option. */
+	autoFocus?: boolean | FocusStrategy;
+	/**
+	 * 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;
+	/**
+	 * Whether `disabledKeys` applies to all interactions, or only selection.
+	 *
+	 * @default 'all'
+	 */
+	disabledBehavior?: DisabledBehavior;
+	/** Whether selection should occur on press up instead of press down. */
+	shouldSelectOnPressUp?: boolean;
+}
+
+export interface AriaGridListProps<T> extends GridListProps<T>, DOMProps, AriaLabelingProps {
+	/**
+	 * Whether keyboard navigation to focusable elements within grid list items is
+	 * via the left/right arrow keys or the tab key.
+	 *
+	 * @default 'arrow'
+	 */
+	keyboardNavigationBehavior?: 'arrow' | 'tab';
+	/**
+	 * Whether pressing the escape key should clear selection in the grid list 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 AriaGridListOptions<T> extends Omit<AriaGridListProps<T>, 'children'> {
+	/** Whether the list uses virtual scrolling. */
+	isVirtualized?: boolean;
+	/**
+	 * Whether typeahead navigation is disabled.
+	 *
+	 * @default false
+	 */
+	disallowTypeAhead?: 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 focus should wrap around when the end/start is reached.
+	 *
+	 * @default false
+	 */
+	shouldFocusWrap?: 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 'action'
+	 */
+	linkBehavior?: 'action' | 'selection' | 'override';
+	/**
+	 * Which item in the collection to focus when tabbing into the collection. Overrides default
+	 * roving tab index like behavior.
+	 *
+	 * @private
+	 */
+	UNSTABLE_focusOnEntry?: 'first' | 'last';
+}
+
+export interface GridListAria {
+	/** Props for the grid element. */
+	gridProps: DOMAttributes;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a list component with interactive
+ * children. A grid list displays data in a single column and enables a user to navigate its
+ * contents via directional navigation keys.
+ *
+ * @param props - Props for the list.
+ * @param state - State for the list, as returned by `useListState`.
+ * @param ref - The ref attached to the list element.
+ */
+export function useGridList<T>(
+	props: AriaGridListOptions<T>,
+	state: ListState<T>,
+	ref: RefObject<HTMLElement | null>,
+): GridListAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useGridList<T>(
+	props: AriaGridListOptions<T>,
+	state: ListState<T>,
+	ref: RefObject<HTMLElement | null>,
+	slot: symbol | undefined,
+): GridListAria;
+export function useGridList(...args: any[]): GridListAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useGridList');
+	const props = user[0] as AriaGridListOptions<any>;
+	const state = user[1] as ListState<any>;
+	const ref = user[2] as RefObject<HTMLElement | null>;
+
+	let {
+		isVirtualized,
+		keyboardDelegate,
+		layoutDelegate,
+		onAction,
+		disallowTypeAhead,
+		linkBehavior = 'action',
+		keyboardNavigationBehavior = 'arrow',
+		escapeKeyBehavior = 'clearSelection',
+		shouldSelectOnPressUp,
+	} = props;
+
+	if (!props['aria-label'] && !props['aria-labelledby']) {
+		console.warn('An aria-label or aria-labelledby prop is required for accessibility.');
+	}
+
+	let { listProps } = useSelectableList(
+		{
+			selectionManager: state.selectionManager,
+			collection: state.collection,
+			disabledKeys: state.disabledKeys,
+			ref,
+			keyboardDelegate,
+			layoutDelegate,
+			isVirtualized,
+			selectOnFocus: state.selectionManager.selectionBehavior === 'replace',
+			shouldFocusWrap: props.shouldFocusWrap,
+			linkBehavior,
+			disallowTypeAhead,
+			autoFocus: props.autoFocus,
+			escapeKeyBehavior,
+			UNSTABLE_focusOnEntry: props.UNSTABLE_focusOnEntry,
+		},
+		subSlot(slot, 'selectableList'),
+	);
+
+	let id = useId(props.id, subSlot(slot, 'id'));
+	listMap.set(state, {
+		id,
+		onAction,
+		linkBehavior,
+		keyboardNavigationBehavior,
+		shouldSelectOnPressUp,
+	});
+
+	let descriptionProps = useHighlightSelectionDescription(
+		{
+			selectionManager: state.selectionManager,
+			hasItemActions: !!onAction,
+		},
+		subSlot(slot, 'highlightDescription'),
+	);
+
+	let hasTabbableChild = useHasTabbableChild(
+		ref,
+		{
+			isDisabled: state.collection.size !== 0,
+		},
+		subSlot(slot, 'hasTabbableChild'),
+	);
+
+	let domProps = filterDOMProps(props, { labelable: true });
+	let gridProps: DOMAttributes = mergeProps(
+		domProps,
+		{
+			role: 'grid',
+			id,
+			'aria-multiselectable':
+				state.selectionManager.selectionMode === 'multiple' ? 'true' : undefined,
+		},
+		// If collection is empty, make sure the grid is tabbable unless there is a child tabbable element.
+		state.collection.size === 0 ? { tabIndex: hasTabbableChild ? -1 : 0 } : listProps,
+		descriptionProps,
+	);
+
+	if (isVirtualized) {
+		gridProps['aria-rowcount'] = state.collection.size;
+		gridProps['aria-colcount'] = 1;
+	}
+
+	useGridSelectionAnnouncement({}, state, subSlot(slot, 'selectionAnnouncement'));
+
+	return {
+		gridProps,
+	};
+}