@octanejs/aria 0.0.1 → 0.0.3

package/src/selection/useTypeSelect.ts

@@ -0,0 +1,192 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/selection/useTypeSelect.ts).
+// octane adaptations:
+// - Handlers receive NATIVE KeyboardEvents (there is no synthetic layer). The
+//   `'continuePropagation' in e` probes port verbatim: they distinguish events wrapped by
+//   the ported useKeyboard machinery (whose BaseEvent shim carries continuePropagation/
+//   isPropagationStopped) from plain delegated events.
+// - `e.currentTarget` casts to Element (octane's delegated dispatch guarantees the
+//   per-handler currentTarget; native types say EventTarget | null).
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention.
+// - MultipleSelectionManager type from the ported stately selection types.
+import type { Key, KeyboardDelegate } from '@react-types/shared';
+import { getEventTarget, nodeContains } from '../utils/shadowdom/DOMFunctions';
+import { useEffect, useRef } from 'octane';
+import type { MultipleSelectionManager } from '../stately/selection/types';
+
+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>;
+
+/**
+ * Controls how long to wait before clearing the typeahead buffer.
+ */
+const TYPEAHEAD_DEBOUNCE_WAIT_MS = 1000; // 1 second
+
+export interface AriaTypeSelectOptions {
+	/**
+	 * A delegate that returns collection item keys with respect to visual layout.
+	 */
+	keyboardDelegate: KeyboardDelegate;
+	/**
+	 * An interface for reading and updating multiple selection state.
+	 */
+	selectionManager: MultipleSelectionManager;
+	/**
+	 * Called when an item is focused by typing.
+	 */
+	onTypeSelect?: (key: Key) => void;
+}
+
+export interface TypeSelectAria {
+	/**
+	 * Props to be spread on the owner of the options.
+	 */
+	typeSelectProps: DOMAttributes;
+}
+
+/**
+ * Handles typeahead interactions with collections.
+ */
+export function useTypeSelect(options: AriaTypeSelectOptions): TypeSelectAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useTypeSelect(
+	options: AriaTypeSelectOptions,
+	slot: symbol | undefined,
+): TypeSelectAria;
+export function useTypeSelect(...args: any[]): TypeSelectAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useTypeSelect');
+	const options = user[0] as AriaTypeSelectOptions;
+
+	let { keyboardDelegate, selectionManager, onTypeSelect } = options;
+	let state = useRef<{ search: string; timeout: ReturnType<typeof setTimeout> | undefined }>(
+		{
+			search: '',
+			timeout: undefined,
+		},
+		subSlot(slot, 'state'),
+	);
+
+	let onKeyDownCapture = (e: KeyboardEvent) => {
+		// if we're in the middle of a search, then a spacebar should be treated as a search and we should not propagate the event
+		// since we handle this one in a capture phase, we should ignore it in the bubble phase
+		if (state.current.search.length > 0 && e.key === ' ') {
+			e.preventDefault();
+			if (
+				!('continuePropagation' in e) ||
+				('continuePropagation' in e && !(e as any).isPropagationStopped())
+			) {
+				e.stopPropagation();
+			}
+			state.current.search += ' ';
+
+			if (keyboardDelegate.getKeyForSearch != null) {
+				// Use the delegate to find a key to focus.
+				// Prioritize items after the currently focused item, falling back to searching the whole list.
+				let key = keyboardDelegate.getKeyForSearch(
+					state.current.search,
+					selectionManager.focusedKey,
+				);
+
+				// If no key found, search from the top.
+				if (key == null) {
+					key = keyboardDelegate.getKeyForSearch(state.current.search);
+				}
+
+				if (key != null) {
+					selectionManager.setFocusedKey(key);
+					if (onTypeSelect) {
+						onTypeSelect(key);
+					}
+				}
+			}
+
+			clearTimeout(state.current.timeout);
+			state.current.timeout = setTimeout(() => {
+				state.current.search = '';
+			}, TYPEAHEAD_DEBOUNCE_WAIT_MS);
+		}
+	};
+
+	let onKeyDown = (e: KeyboardEvent) => {
+		let character = getStringForKey(e.key);
+		if (
+			!character ||
+			e.ctrlKey ||
+			e.metaKey ||
+			e.altKey ||
+			!nodeContains(e.currentTarget as Element, getEventTarget(e) as HTMLElement) ||
+			(state.current.search.length === 0 && character === ' ')
+		) {
+			return;
+		}
+
+		state.current.search += character;
+
+		if (keyboardDelegate.getKeyForSearch != null) {
+			// Use the delegate to find a key to focus.
+			// Prioritize items after the currently focused item, falling back to searching the whole list.
+			let key = keyboardDelegate.getKeyForSearch(state.current.search, selectionManager.focusedKey);
+
+			if (key == null) {
+				key = keyboardDelegate.getKeyForSearch(state.current.search);
+			}
+
+			if (key != null) {
+				selectionManager.setFocusedKey(key);
+				if (onTypeSelect) {
+					onTypeSelect(key);
+				}
+				e.preventDefault();
+				if (!('continuePropagation' in e)) {
+					e.stopPropagation();
+				}
+			} else {
+				// if still nothing then the type to select is done and everything is reset
+				state.current.search = '';
+				clearTimeout(state.current.timeout);
+				state.current.timeout = undefined;
+				return;
+			}
+		}
+
+		clearTimeout(state.current.timeout);
+		state.current.timeout = setTimeout(() => {
+			state.current.search = '';
+		}, TYPEAHEAD_DEBOUNCE_WAIT_MS);
+	};
+
+	useEffect(
+		() => {
+			let timeout = state.current.timeout;
+			return () => {
+				clearTimeout(timeout);
+			};
+		},
+		[state],
+		subSlot(slot, 'teardown'),
+	);
+
+	return {
+		typeSelectProps: {
+			// Using a capturing listener to catch the keydown event before
+			// other hooks in order to handle the Spacebar event.
+			onKeyDownCapture: keyboardDelegate.getKeyForSearch ? onKeyDownCapture : undefined,
+			onKeyDown: keyboardDelegate.getKeyForSearch ? onKeyDown : undefined,
+		},
+	};
+}
+
+function getStringForKey(key: string) {
+	// If the key is of length 1, it is an ASCII value.
+	// Otherwise, if there are no ASCII characters in the key name,
+	// it is a Unicode character.
+	// See https://www.w3.org/TR/uievents-key/
+	if (key.length === 1 || !/^[A-Z]/i.test(key)) {
+		return key;
+	}
+
+	return '';
+}

package/src/selection/utils.ts

@@ -0,0 +1,50 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/selection/utils.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) for useCollectionId per
+// the binding convention; RefObject type from @react-types/shared (upstream: React's RefObject).
+import type { Collection, Key, RefObject } from '@react-types/shared';
+import { isAppleDevice } from '../utils/platform';
+
+import { S, splitSlot, subSlot } from '../internal';
+import { useId } from '../utils/useId';
+
+interface Event {
+	altKey: boolean;
+	ctrlKey: boolean;
+	metaKey: boolean;
+}
+
+export function isNonContiguousSelectionModifier(e: Event): boolean {
+	// Ctrl + Arrow Up/Arrow Down has a system wide meaning on macOS, so use Alt instead.
+	// On Windows and Ubuntu, Alt + Space has a system wide meaning.
+	return isAppleDevice() ? e.altKey : e.ctrlKey;
+}
+
+export function getItemElement(
+	collectionRef: RefObject<HTMLElement | null>,
+	key: Key,
+): Element | null | undefined {
+	let selector = `[data-key="${CSS.escape(String(key))}"]`;
+	let collection = collectionRef.current?.dataset.collection;
+	if (collection) {
+		selector = `[data-collection="${CSS.escape(collection)}"]${selector}`;
+	}
+	return collectionRef.current?.querySelector(selector);
+}
+
+const collectionMap = new WeakMap<Collection<any>, string>();
+export function useCollectionId(collection: Collection<any>): string;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useCollectionId(collection: Collection<any>, slot: symbol | undefined): string;
+export function useCollectionId(...args: any[]): string {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useCollectionId');
+	const collection = user[0] as Collection<any>;
+
+	let id = useId(undefined, subSlot(slot, 'id'));
+	collectionMap.set(collection, id);
+	return id;
+}
+
+export function getCollectionId(collection: Collection<any>): string {
+	return collectionMap.get(collection)!;
+}

package/src/separator/useSeparator.ts

@@ -0,0 +1,41 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/separator/useSeparator.ts).
+import type { AriaLabelingProps, DOMAttributes, DOMProps, Orientation } from '@react-types/shared';
+
+import { filterDOMProps } from '../utils/filterDOMProps';
+
+export interface SeparatorProps extends DOMProps, AriaLabelingProps {
+	/**
+	 * The orientation of the separator.
+	 *
+	 * @default 'horizontal'
+	 */
+	orientation?: Orientation;
+	/** The HTML element type that will be used to render the separator. */
+	elementType?: string;
+}
+
+export interface SeparatorAria {
+	/** Props for the separator element. */
+	separatorProps: DOMAttributes;
+}
+
+export function useSeparator(props: SeparatorProps): SeparatorAria {
+	let domProps = filterDOMProps(props, { labelable: true });
+	let ariaOrientation: 'vertical' | undefined;
+	// if orientation is horizontal, aria-orientation default is horizontal, so we leave it undefined
+	// if it's vertical, we need to specify it
+	if (props.orientation === 'vertical') {
+		ariaOrientation = 'vertical';
+	}
+	// hr elements implicitly have role = separator and a horizontal orientation
+	if (props.elementType !== 'hr') {
+		return {
+			separatorProps: {
+				...domProps,
+				role: 'separator',
+				'aria-orientation': ariaOrientation,
+			},
+		};
+	}
+	return { separatorProps: domProps };
+}

package/src/slider/useSlider.ts

@@ -0,0 +1,277 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/slider/useSlider.ts).
+// octane adaptations:
+// - Handlers receive NATIVE events (there is no synthetic layer): the track's
+//   onMouseDown/onPointerDown/onTouchStart props take native MouseEvent/PointerEvent/
+//   TouchEvent, and `onDownTrack`'s event parameter is the native event union.
+// - React's LabelHTMLAttributes/OutputHTMLAttributes element types collapse to the local
+//   structural `DOMAttributes` prop bag.
+// - `clamp` comes from the ported stately number utils; `SliderProps`/`SliderState` from
+//   the ported stately slider hook.
+// - Public-hook slot threading (splitSlot/subSlot).
+import type { AriaLabelingProps, DOMProps, RefObject } from '@react-types/shared';
+import { clamp } from '../stately/utils/number';
+import { getSliderThumbId, sliderData } from './utils';
+import { mergeProps } from '../utils/mergeProps';
+import { useRef } from 'octane';
+import { setInteractionModality } from '../interactions/useFocusVisible';
+import type { SliderProps, SliderState } from '../stately/slider/useSliderState';
+import { useGlobalListeners } from '../utils/useGlobalListeners';
+import { useLabel } from '../label/useLabel';
+import { useLocale } from '../i18n/I18nProvider';
+import { useMove } from '../interactions/useMove';
+
+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 AriaSliderProps<T = number | number[]>
+	extends SliderProps<T>, DOMProps, AriaLabelingProps {}
+
+export interface SliderAria {
+	/** Props for the label element. */
+	labelProps: DOMAttributes;
+
+	/** Props for the root element of the slider component; groups slider inputs. */
+	groupProps: DOMAttributes;
+
+	/** Props for the track element. */
+	trackProps: DOMAttributes;
+
+	/** Props for the output element, displaying the value of the slider thumbs. */
+	outputProps: DOMAttributes;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a slider component representing one or
+ * more values.
+ *
+ * @param props Props for the slider.
+ * @param state State for the slider, as returned by `useSliderState`.
+ * @param trackRef Ref for the "track" element.  The width of this element provides the "length"
+ *   of the track -- the span of one dimensional space that the slider thumb can be.  It also
+ *   accepts click and drag motions, so that the closest thumb will follow clicks and drags on
+ *   the track.
+ */
+export function useSlider<T extends number | number[]>(
+	props: AriaSliderProps<T>,
+	state: SliderState,
+	trackRef: RefObject<Element | null>,
+): SliderAria;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSlider<T extends number | number[]>(
+	props: AriaSliderProps<T>,
+	state: SliderState,
+	trackRef: RefObject<Element | null>,
+	slot: symbol | undefined,
+): SliderAria;
+export function useSlider(...args: any[]): SliderAria {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSlider');
+	const props = user[0] as AriaSliderProps<any>;
+	const state = user[1] as SliderState;
+	const trackRef = user[2] as RefObject<Element | null>;
+
+	let { labelProps, fieldProps } = useLabel(props, subSlot(slot, 'label'));
+
+	let isVertical = props.orientation === 'vertical';
+
+	// Attach id of the label to the state so it can be accessed by useSliderThumb.
+	sliderData.set(state, {
+		id: (labelProps.id ?? fieldProps.id)!,
+		'aria-describedby': props['aria-describedby'],
+		'aria-details': props['aria-details'],
+	});
+
+	let { direction } = useLocale(subSlot(slot, 'locale'));
+
+	let { addGlobalListener, removeGlobalListener } = useGlobalListeners(
+		subSlot(slot, 'globalListeners'),
+	);
+
+	// When the user clicks or drags the track, we want the motion to set and drag the
+	// closest thumb.  Hence we also need to install useMove() on the track element.
+	// Here, we keep track of which index is the "closest" to the drag start point.
+	// It is set onMouseDown/onTouchDown; see trackProps below.
+	const realTimeTrackDraggingIndex = useRef<number | null>(null, subSlot(slot, 'dragIndex'));
+
+	const reverseX = direction === 'rtl';
+	const currentPosition = useRef<number | null>(null, subSlot(slot, 'position'));
+	const { moveProps } = useMove(
+		{
+			onMoveStart() {
+				currentPosition.current = null;
+			},
+			onMove({ deltaX, deltaY }) {
+				if (!trackRef.current) {
+					return;
+				}
+				let { height, width } = trackRef.current.getBoundingClientRect();
+				let size = isVertical ? height : width;
+
+				if (currentPosition.current == null && realTimeTrackDraggingIndex.current != null) {
+					currentPosition.current =
+						state.getThumbPercent(realTimeTrackDraggingIndex.current) * size;
+				}
+
+				let delta = isVertical ? deltaY : deltaX;
+				if (isVertical || reverseX) {
+					delta = -delta;
+				}
+
+				currentPosition.current! += delta;
+
+				if (realTimeTrackDraggingIndex.current != null && trackRef.current) {
+					const percent = clamp(currentPosition.current! / size, 0, 1);
+					state.setThumbPercent(realTimeTrackDraggingIndex.current, percent);
+				}
+			},
+			onMoveEnd() {
+				if (realTimeTrackDraggingIndex.current != null) {
+					state.setThumbDragging(realTimeTrackDraggingIndex.current, false);
+					realTimeTrackDraggingIndex.current = null;
+				}
+			},
+		},
+		subSlot(slot, 'move'),
+	);
+
+	let currentPointer = useRef<number | null | undefined>(undefined, subSlot(slot, 'pointer'));
+	let onDownTrack = (
+		e: MouseEvent | PointerEvent | TouchEvent,
+		id: number | undefined,
+		clientX: number,
+		clientY: number,
+	) => {
+		// We only trigger track-dragging if the user clicks on the track itself and nothing is currently being dragged.
+		if (
+			trackRef.current &&
+			!props.isDisabled &&
+			state.values.every((_, i) => !state.isThumbDragging(i))
+		) {
+			let { height, width, top, left } = trackRef.current.getBoundingClientRect();
+			let size = isVertical ? height : width;
+			// Find the closest thumb
+			const trackPosition = isVertical ? top : left;
+			const clickPosition = isVertical ? clientY : clientX;
+			const offset = clickPosition - trackPosition;
+			let percent = offset / size;
+			if (direction === 'rtl' || isVertical) {
+				percent = 1 - percent;
+			}
+			let value = state.getPercentValue(percent);
+
+			// to find the closet thumb we split the array based on the first thumb position to the "right/end" of the click.
+			let closestThumb;
+			let split = state.values.findIndex((v) => value - v < 0);
+			if (split === 0) {
+				// If the index is zero then the closetThumb is the first one
+				closestThumb = split;
+			} else if (split === -1) {
+				// If no index is found they've clicked past all the thumbs
+				closestThumb = state.values.length - 1;
+			} else {
+				let lastLeft = state.values[split - 1];
+				let firstRight = state.values[split];
+				// Pick the last left/start thumb, unless they are stacked on top of each other, then pick the right/end one
+				if (Math.abs(lastLeft - value) < Math.abs(firstRight - value)) {
+					closestThumb = split - 1;
+				} else {
+					closestThumb = split;
+				}
+			}
+
+			// Confirm that the found closest thumb is editable, not disabled, and move it
+			if (closestThumb >= 0 && state.isThumbEditable(closestThumb)) {
+				// Don't unfocus anything
+				e.preventDefault();
+
+				realTimeTrackDraggingIndex.current = closestThumb;
+				state.setFocusedThumb(closestThumb);
+				currentPointer.current = id;
+
+				state.setThumbDragging(realTimeTrackDraggingIndex.current!, true);
+				state.setThumbValue(closestThumb, value);
+
+				addGlobalListener(window, 'mouseup', onUpTrack, false);
+				addGlobalListener(window, 'touchend', onUpTrack, false);
+				addGlobalListener(window, 'pointerup', onUpTrack, false);
+			} else {
+				realTimeTrackDraggingIndex.current = null;
+			}
+		}
+	};
+
+	let onUpTrack = (e: any) => {
+		let id = e.pointerId ?? e.changedTouches?.[0].identifier;
+		if (id === currentPointer.current) {
+			if (realTimeTrackDraggingIndex.current != null) {
+				state.setThumbDragging(realTimeTrackDraggingIndex.current, false);
+				realTimeTrackDraggingIndex.current = null;
+			}
+
+			removeGlobalListener(window, 'mouseup', onUpTrack, false);
+			removeGlobalListener(window, 'touchend', onUpTrack, false);
+			removeGlobalListener(window, 'pointerup', onUpTrack, false);
+		}
+	};
+
+	if ('htmlFor' in labelProps && labelProps.htmlFor) {
+		// Ideally the `for` attribute should point to the first thumb, but VoiceOver on iOS
+		// causes this to override the `aria-labelledby` on the thumb. This causes the first
+		// thumb to only be announced as the slider label rather than its individual name as well.
+		// See https://bugs.webkit.org/show_bug.cgi?id=172464.
+		delete labelProps.htmlFor;
+		labelProps.onClick = () => {
+			// Safari does not focus <input type="range"> elements when clicking on an associated <label>,
+			// so do it manually. In addition, make sure we show the focus ring.
+			document.getElementById(getSliderThumbId(state, 0))?.focus();
+			setInteractionModality('keyboard');
+		};
+	}
+
+	return {
+		labelProps,
+		// The root element of the Slider will have role="group" to group together
+		// all the thumb inputs in the Slider.  The label of the Slider will
+		// be used to label the group.
+		groupProps: {
+			role: 'group',
+			...fieldProps,
+		},
+		trackProps: mergeProps(
+			{
+				onMouseDown(e: MouseEvent) {
+					if (e.button !== 0 || e.altKey || e.ctrlKey || e.metaKey) {
+						return;
+					}
+					onDownTrack(e, undefined, e.clientX, e.clientY);
+				},
+				onPointerDown(e: PointerEvent) {
+					if (e.pointerType === 'mouse' && (e.button !== 0 || e.altKey || e.ctrlKey || e.metaKey)) {
+						return;
+					}
+					onDownTrack(e, e.pointerId, e.clientX, e.clientY);
+				},
+				onTouchStart(e: TouchEvent) {
+					onDownTrack(
+						e,
+						e.changedTouches[0].identifier,
+						e.changedTouches[0].clientX,
+						e.changedTouches[0].clientY,
+					);
+				},
+				style: {
+					position: 'relative',
+					touchAction: 'none',
+				},
+			},
+			moveProps,
+		),
+		outputProps: {
+			htmlFor: state.values.map((_, index) => getSliderThumbId(state, index)).join(' '),
+			'aria-live': 'off',
+		},
+	};
+}