@octanejs/aria 0.0.1 → 0.0.3

package/src/menu/useMenuTrigger.ts

@@ -0,0 +1,189 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/menu/useMenuTrigger.ts).
+// octane adaptations:
+// - `useOverlayTrigger` comes from the freshly-ported overlays glue
+//   (src/overlays/useOverlayTrigger.ts) — the rest of the overlays area (positioning,
+//   modal machinery) remains unported.
+// - The trigger `onKeyDown` receives either the NATIVE KeyboardEvent (when spread straight
+//   onto an element) or the ported BaseEvent Proxy wrapper (when routed through
+//   useButton/useKeyboard). Upstream detects the wrapper with `'continuePropagation' in e`;
+//   the ported wrapper is a Proxy with only a `get` trap, so detection uses
+//   `typeof e.continuePropagation === 'function'` (the same probe createEventHandler uses
+//   for nested wrappers). Upstream's synthetic `e.isDefaultPrevented()` becomes the native
+//   `e.defaultPrevented`.
+// - The Parcel glob intl import becomes the generated '../intl/menu' dictionary index.
+// - Public-hook slot threading (splitSlot/subSlot) per the binding convention.
+import type { AriaButtonProps } from '../button/useButton';
+import type { AriaMenuOptions } from './useMenu';
+import type { FocusableElement, RefObject } from '@react-types/shared';
+import { focusWithoutScrolling } from '../utils/focusWithoutScrolling';
+import intlMessages from '../intl/menu';
+import type { MenuTriggerState, MenuTriggerType } from '../stately/menu/useMenuTriggerState';
+import type { PressProps } from '../interactions/usePress';
+import { useId } from '../utils/useId';
+import { useLocalizedStringFormatter } from '../i18n/useLocalizedStringFormatter';
+import { useLongPress } from '../interactions/useLongPress';
+import { useOverlayTrigger } from '../overlays/useOverlayTrigger';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+export interface AriaMenuTriggerProps {
+	/** The type of menu that the menu trigger opens. */
+	type?: 'menu' | 'listbox';
+	/** Whether menu trigger is disabled. */
+	isDisabled?: boolean;
+	/** How menu is triggered. */
+	trigger?: MenuTriggerType;
+}
+
+export interface MenuTriggerAria<T> {
+	/** Props for the menu trigger element. */
+	menuTriggerProps: AriaButtonProps;
+
+	/** Props for the menu. */
+	menuProps: AriaMenuOptions<T>;
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a menu trigger.
+ *
+ * @param props - Props for the menu trigger.
+ * @param state - State for the menu trigger.
+ * @param ref - Ref to the HTML element trigger for the menu.
+ */
+export function useMenuTrigger<T>(
+	props: AriaMenuTriggerProps,
+	state: MenuTriggerState,
+	ref: RefObject<Element | null>,
+): MenuTriggerAria<T>;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useMenuTrigger<T>(
+	props: AriaMenuTriggerProps,
+	state: MenuTriggerState,
+	ref: RefObject<Element | null>,
+	slot: symbol | undefined,
+): MenuTriggerAria<T>;
+export function useMenuTrigger(...args: any[]): MenuTriggerAria<any> {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useMenuTrigger');
+	const props = user[0] as AriaMenuTriggerProps;
+	const state = user[1] as MenuTriggerState;
+	const ref = user[2] as RefObject<Element | null>;
+
+	let { type = 'menu', isDisabled, trigger = 'press' } = props;
+
+	let menuTriggerId = useId(subSlot(slot, 'triggerId'));
+	let { triggerProps, overlayProps } = useOverlayTrigger(
+		{ type },
+		state,
+		ref,
+		subSlot(slot, 'overlayTrigger'),
+	);
+
+	let onKeyDown = (e: any) => {
+		if (isDisabled) {
+			return;
+		}
+
+		if (trigger === 'longPress' && !e.altKey) {
+			return;
+		}
+
+		if (ref && ref.current) {
+			switch (e.key) {
+				case 'Enter':
+				case ' ':
+					// React puts listeners on the same root, so even if propagation was stopped, immediate propagation is still possible.
+					// useTypeSelect will handle the spacebar first if it's running, so we don't want to open if it's handled it already.
+					// We use isDefaultPrevented() instead of isPropagationStopped() because createEventHandler stops propagation by default.
+					// And default prevented means that the event was handled by something else (typeahead), so we don't want to open the menu.
+					// octane adaptation: the native `defaultPrevented` flag (forwarded by the
+					// BaseEvent Proxy wrapper) replaces the synthetic isDefaultPrevented().
+					if (trigger === 'longPress' || e.defaultPrevented) {
+						return;
+					}
+				// fallthrough
+				case 'ArrowDown':
+					// Stop propagation, unless it would already be handled by useKeyboard.
+					if (typeof e.continuePropagation !== 'function') {
+						e.stopPropagation();
+					}
+					e.preventDefault();
+					state.toggle('first');
+					break;
+				case 'ArrowUp':
+					if (typeof e.continuePropagation !== 'function') {
+						e.stopPropagation();
+					}
+					e.preventDefault();
+					state.toggle('last');
+					break;
+				default:
+					// Allow other keys.
+					if (typeof e.continuePropagation === 'function') {
+						e.continuePropagation();
+					}
+			}
+		}
+	};
+
+	let stringFormatter = useLocalizedStringFormatter(
+		intlMessages,
+		'@react-aria/menu',
+		subSlot(slot, 'formatter'),
+	);
+	let { longPressProps } = useLongPress(
+		{
+			isDisabled: isDisabled || trigger !== 'longPress',
+			accessibilityDescription: stringFormatter.format('longPressMessage'),
+			onLongPressStart() {
+				state.close();
+			},
+			onLongPress() {
+				state.open('first');
+			},
+		},
+		subSlot(slot, 'longPress'),
+	);
+
+	let pressProps: PressProps = {
+		preventFocusOnPress: true,
+		onPressStart(e) {
+			// For consistency with native, open the menu on mouse/key down, but touch up.
+			if (e.pointerType !== 'touch' && e.pointerType !== 'keyboard' && !isDisabled) {
+				// Ensure trigger has focus before opening the menu so it can be restored by FocusScope on close.
+				focusWithoutScrolling(e.target as FocusableElement);
+
+				// If opened with a screen reader, auto focus the first item.
+				// Otherwise, the menu itself will be focused.
+				state.open(e.pointerType === 'virtual' ? 'first' : null);
+			}
+		},
+		onPress(e) {
+			if (e.pointerType === 'touch' && !isDisabled) {
+				// Ensure trigger has focus before opening the menu so it can be restored by FocusScope on close.
+				focusWithoutScrolling(e.target as FocusableElement);
+
+				state.toggle();
+			}
+		},
+	};
+
+	// omit onPress from triggerProps since we override it above.
+	delete triggerProps.onPress;
+
+	return {
+		// @ts-ignore - TODO we pass out both DOMAttributes AND AriaButtonProps, but useButton will discard the longPress event handlers, it's only through PressResponder magic that this works for RSP and RAC. it does not work in aria examples
+		menuTriggerProps: {
+			...triggerProps,
+			...(trigger === 'press' ? pressProps : longPressProps),
+			id: menuTriggerId,
+			onKeyDown,
+		},
+		menuProps: {
+			...overlayProps,
+			'aria-labelledby': menuTriggerId,
+			autoFocus: state.focusStrategy || true,
+			onClose: state.close,
+		},
+	};
+}

package/src/menu/useSafelyMouseToSubmenu.ts

@@ -0,0 +1,236 @@
+// Ported from react-aria (source: .react-spectrum/packages/react-aria/src/menu/useSafelyMouseToSubmenu.ts).
+// octane adaptations: public-hook slot threading (splitSlot/subSlot) per the binding
+// convention; explicit dependency arrays are kept verbatim (`useResizeObserver` was ported
+// alongside — see src/utils/useResizeObserver.ts).
+import { nodeContains } from '../utils/shadowdom/DOMFunctions';
+import type { RefObject } from '@react-types/shared';
+import { useEffect, useRef, useState } from 'octane';
+import { useEffectEvent } from '../utils/useEffectEvent';
+import { useInteractionModality } from '../interactions/useFocusVisible';
+import { useLayoutEffect } from '../utils/useLayoutEffect';
+import { useResizeObserver } from '../utils/useResizeObserver';
+
+import { S, splitSlot, subSlot } from '../internal';
+
+interface SafelyMouseToSubmenuOptions {
+	/** Ref for the parent menu. */
+	menuRef: RefObject<Element | null>;
+	/** Ref for the submenu. */
+	submenuRef: RefObject<Element | null>;
+	/** Whether the submenu is open. */
+	isOpen: boolean;
+	/** Whether this feature is disabled. */
+	isDisabled?: boolean;
+}
+
+const ALLOWED_INVALID_MOVEMENTS = 2;
+const THROTTLE_TIME = 50;
+const TIMEOUT_TIME = 1000;
+const ANGLE_PADDING = Math.PI / 12; // 15°
+
+/**
+ * Allows the user to move their pointer to the submenu without it closing when their mouse leaves
+ * the trigger element. Prevents pointer events from going to the underlying menu if the user is
+ * moving their pointer towards the sub-menu.
+ */
+export function useSafelyMouseToSubmenu(options: SafelyMouseToSubmenuOptions): void;
+// Slot-threading form: sibling ported hooks pass their derived sub-slot as the trailing arg.
+export function useSafelyMouseToSubmenu(
+	options: SafelyMouseToSubmenuOptions,
+	slot: symbol | undefined,
+): void;
+export function useSafelyMouseToSubmenu(...args: any[]): void {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useSafelyMouseToSubmenu');
+	const options = user[0] as SafelyMouseToSubmenuOptions;
+
+	let { menuRef, submenuRef, isOpen, isDisabled } = options;
+	let prevPointerPos = useRef<{ x: number; y: number } | undefined>(
+		undefined,
+		subSlot(slot, 'prevPointerPos'),
+	);
+	let submenuRect = useRef<DOMRect | undefined>(undefined, subSlot(slot, 'submenuRect'));
+	let lastProcessedTime = useRef<number>(0, subSlot(slot, 'lastProcessedTime'));
+	let timeout = useRef<ReturnType<typeof setTimeout> | undefined>(
+		undefined,
+		subSlot(slot, 'timeout'),
+	);
+	let autoCloseTimeout = useRef<ReturnType<typeof setTimeout> | undefined>(
+		undefined,
+		subSlot(slot, 'autoCloseTimeout'),
+	);
+	let submenuSide = useRef<'left' | 'right' | undefined>(undefined, subSlot(slot, 'submenuSide'));
+	let movementsTowardsSubmenuCount = useRef<number>(2, subSlot(slot, 'movements'));
+	let [preventPointerEvents, setPreventPointerEvents] = useState(
+		false,
+		subSlot(slot, 'preventPointerEvents'),
+	);
+
+	let updateSubmenuRect = () => {
+		if (submenuRef.current) {
+			submenuRect.current = submenuRef.current.getBoundingClientRect();
+			submenuSide.current = undefined;
+		}
+	};
+	useResizeObserver(
+		{ ref: isOpen ? submenuRef : undefined, onResize: updateSubmenuRect },
+		subSlot(slot, 'resize'),
+	);
+
+	let reset = () => {
+		setPreventPointerEvents(false);
+		movementsTowardsSubmenuCount.current = ALLOWED_INVALID_MOVEMENTS;
+		prevPointerPos.current = undefined;
+	};
+
+	let modality = useInteractionModality(subSlot(slot, 'modality'));
+
+	// Prevent mouse down over safe triangle. Clicking while pointer-events: none is applied
+	// will cause focus to move unexpectedly since it will go to an element behind the menu.
+	let onPointerDown = useEffectEvent(
+		(e: PointerEvent) => {
+			if (preventPointerEvents) {
+				e.preventDefault();
+			}
+		},
+		subSlot(slot, 'pointerDown'),
+	);
+
+	useEffect(
+		() => {
+			if (preventPointerEvents && menuRef.current) {
+				(menuRef.current as HTMLElement).style.pointerEvents = 'none';
+			} else {
+				(menuRef.current as HTMLElement).style.pointerEvents = '';
+			}
+		},
+		[menuRef, preventPointerEvents],
+		subSlot(slot, 'pointerEvents'),
+	);
+
+	useLayoutEffect(
+		() => {
+			let submenu = submenuRef.current;
+			let menu = menuRef.current;
+
+			if (isDisabled || !submenu || !isOpen || modality !== 'pointer' || !menu) {
+				reset();
+				return;
+			}
+			submenuRect.current = submenu.getBoundingClientRect();
+
+			let onPointerMove = (e: PointerEvent) => {
+				if (e.pointerType === 'touch' || e.pointerType === 'pen') {
+					return;
+				}
+
+				let currentTime = Date.now();
+
+				// Throttle
+				if (currentTime - lastProcessedTime.current < THROTTLE_TIME) {
+					return;
+				}
+				clearTimeout(timeout.current);
+				clearTimeout(autoCloseTimeout.current);
+
+				let { clientX: mouseX, clientY: mouseY } = e;
+
+				if (!prevPointerPos.current) {
+					prevPointerPos.current = { x: mouseX, y: mouseY };
+					return;
+				}
+
+				if (!submenuRect.current) {
+					return;
+				}
+
+				if (!submenuSide.current) {
+					submenuSide.current = mouseX > submenuRect.current.right ? 'left' : 'right';
+				}
+
+				// Pointer is outside of parent menu
+				if (
+					mouseX < menu.getBoundingClientRect().left ||
+					mouseX > menu.getBoundingClientRect().right ||
+					mouseY < menu.getBoundingClientRect().top ||
+					mouseY > menu.getBoundingClientRect().bottom
+				) {
+					reset();
+					return;
+				}
+
+				/* Check if pointer is moving towards submenu.
+        Uses the 2-argument arctangent (https://en.wikipedia.org/wiki/Atan2) to calculate:
+          - angle between previous pointer and top of submenu
+          - angle between previous pointer and bottom of submenu
+          - angle between previous pointer and current pointer (delta)
+        If the pointer delta angle value is between the top and bottom angle values, we know the pointer is moving towards the submenu.
+      */
+				let prevMouseX = prevPointerPos.current.x;
+				let prevMouseY = prevPointerPos.current.y;
+				let toSubmenuX =
+					submenuSide.current === 'right'
+						? submenuRect.current.left - prevMouseX
+						: prevMouseX - submenuRect.current.right;
+				let angleTop = Math.atan2(prevMouseY - submenuRect.current.top, toSubmenuX) + ANGLE_PADDING;
+				let angleBottom =
+					Math.atan2(prevMouseY - submenuRect.current.bottom, toSubmenuX) - ANGLE_PADDING;
+				let anglePointer = Math.atan2(
+					prevMouseY - mouseY,
+					submenuSide.current === 'left' ? -(mouseX - prevMouseX) : mouseX - prevMouseX,
+				);
+				let isMovingTowardsSubmenu = anglePointer < angleTop && anglePointer > angleBottom;
+
+				movementsTowardsSubmenuCount.current = isMovingTowardsSubmenu
+					? Math.min(movementsTowardsSubmenuCount.current + 1, ALLOWED_INVALID_MOVEMENTS)
+					: Math.max(movementsTowardsSubmenuCount.current - 1, 0);
+
+				if (movementsTowardsSubmenuCount.current >= ALLOWED_INVALID_MOVEMENTS) {
+					setPreventPointerEvents(true);
+				} else {
+					setPreventPointerEvents(false);
+				}
+
+				lastProcessedTime.current = currentTime;
+				prevPointerPos.current = { x: mouseX, y: mouseY };
+
+				// If the pointer is moving towards the submenu, start a timeout to close if no other movements are made after 500ms.
+				if (isMovingTowardsSubmenu) {
+					timeout.current = setTimeout(() => {
+						reset();
+						autoCloseTimeout.current = setTimeout(() => {
+							// Fire a pointerover event to trigger the menu to close.
+							// Wait until pointer-events:none is no longer applied
+							let target = document.elementFromPoint(mouseX, mouseY);
+							if (target && nodeContains(menu, target)) {
+								target.dispatchEvent(
+									new PointerEvent('pointerover', { bubbles: true, cancelable: true }),
+								);
+							}
+						}, 100);
+					}, TIMEOUT_TIME);
+				}
+			};
+
+			window.addEventListener('pointermove', onPointerMove);
+
+			// Prevent pointer down over the safe triangle. See above comment.
+			// Do not enable in tests, because JSDom doesn't do hit testing.
+			if (process.env.NODE_ENV !== 'test') {
+				window.addEventListener('pointerdown', onPointerDown, true);
+			}
+
+			return () => {
+				window.removeEventListener('pointermove', onPointerMove);
+				if (process.env.NODE_ENV !== 'test') {
+					window.removeEventListener('pointerdown', onPointerDown, true);
+				}
+				clearTimeout(timeout.current);
+				clearTimeout(autoCloseTimeout.current);
+				movementsTowardsSubmenuCount.current = ALLOWED_INVALID_MOVEMENTS;
+			};
+		},
+		[isDisabled, isOpen, menuRef, modality, setPreventPointerEvents, submenuRef],
+		subSlot(slot, 'track'),
+	);
+}