@octanejs/base-ui 0.1.14 → 0.1.16

package/src/utils/floating/useHoverReferenceInteraction.ts

@@ -1,17 +1,510 @@
-// STUB — the full open-on-hover interaction (Base UI's useHoverReferenceInteraction + useHover +
-// safePolygon, ~1400 lines) is deferred. It is only active when a trigger sets `openOnHover` (off by
-// default), so returning `{}` here leaves click-to-open Popover/Tooltip fully functional. `safePolygon`
-// is a placeholder passed to `handleClose` (ignored while the hook is inert). TODO: port the real
-// hover (useHover pointer tracking + safePolygon "safe area" close intent) when hover-open tests land.
-
-export function safePolygon(): (...args: any[]) => any {
-	return () => undefined;
+// Ported from .base-ui/packages/react/src/floating-ui-react/hooks/useHoverReferenceInteraction.ts
+// (v1.6.0). The trigger side of open-on-hover: `mouseenter`/`mouseleave` listeners bound directly
+// to the trigger element (bypassing delegation, so entering from a disabled neighbour still fires),
+// plus the `onMouseMove` rest-delay path returned as props.
+//
+// octane adaptations: handlers receive the NATIVE event, so `event.nativeEvent` collapses to
+// `event`; `ReactDOM.flushSync` → octane's `flushSync`; every composed hook threads an explicit
+// slot. Behavior is otherwise transcribed.
+//
+// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
+import { useEffect, useMemo, useRef, flushSync } from 'octane';
+
+import { S, splitSlot, subSlot } from '../../internal';
+import { addEventListener } from '../addEventListener';
+import { mergeCleanups } from '../mergeCleanups';
+import { ownerDocument } from '../owner';
+import { useStableCallback } from '../useStableCallback';
+import { useValueAsRef } from '../useValueAsRef';
+import { isElement } from '../dom';
+import { createChangeEventDetails, REASONS } from '../createChangeEventDetails';
+import { useFloatingTree } from './FloatingTree';
+import { contains, getTarget } from './element';
+import { isMouseLikePointerType } from './event';
+import {
+	applySafePolygonPointerEventsMutation,
+	clearSafePolygonPointerEventsMutation,
+	useHoverInteractionSharedState,
+} from './useHoverInteractionSharedState';
+import {
+	getDelay,
+	getRestMs,
+	isClickLikeOpenEvent as isClickLikeOpenEventShared,
+	isInsideEnabledTrigger,
+} from './useHoverShared';
+import type { HandleClose, HandleCloseContextBase, HoverDelay } from './useHoverShared';
+
+export { safePolygon } from './safePolygon';
+
+export interface UseHoverReferenceInteractionProps {
+	enabled?: boolean | undefined;
+	handleClose?: HandleClose | null | undefined;
+	restMs?: number | (() => number) | undefined;
+	delay?: HoverDelay | (() => HoverDelay) | undefined;
+	move?: boolean | undefined;
+	mouseOnly?: boolean | undefined;
+	externalTree?: any;
+	/**
+	 * Whether the hook controls the active trigger. When false, the props are returned so they
+	 * can be applied to inactive triggers via `getTriggerProps`.
+	 * @default true
+	 */
+	isActiveTrigger?: boolean | undefined;
+	triggerElementRef?: { current: Element | null } | undefined;
+	getHandleCloseContext?: (() => HandleCloseContextBase | null) | undefined;
+	isClosing?: (() => boolean) | undefined;
+	/**
+	 * Called before each hover-driven open attempt (immediate, delayed, and rest-ms paths).
+	 * Return `false` to veto; any other return value permits the open.
+	 */
+	shouldOpen?: (() => boolean) | undefined;
 }
 
-export function useHoverReferenceInteraction(
-	_context: any,
-	_props: any,
-	_slot?: symbol | undefined,
-): Record<string, any> {
-	return {};
+const EMPTY_REF: { current: Element | null } = { current: null };
+
+export function useHoverReferenceInteraction(...args: any[]): Record<string, any> | undefined {
+	const [user, slotArg] = splitSlot(args);
+	const slot = slotArg ?? S('useHoverReferenceInteraction');
+	const context = user[0] as any;
+	const props = (user[1] as UseHoverReferenceInteractionProps) ?? {};
+
+	const {
+		enabled = true,
+		delay = 0,
+		handleClose = null,
+		mouseOnly = false,
+		restMs = 0,
+		move = true,
+		triggerElementRef = EMPTY_REF,
+		externalTree,
+		isActiveTrigger = true,
+		getHandleCloseContext,
+		isClosing,
+		shouldOpen: shouldOpenProp,
+	} = props;
+
+	const store = context != null && 'rootStore' in context ? context.rootStore : context;
+	const dataRef = store?.context.dataRef;
+	const events = store?.context.events;
+
+	const tree = useFloatingTree(externalTree);
+
+	const instance = useHoverInteractionSharedState(store, subSlot(slot, 'shared'));
+	const isHoverCloseActiveRef = useRef(false, subSlot(slot, 'hca'));
+
+	const handleCloseRef = useValueAsRef<HandleClose | null>(handleClose, subSlot(slot, 'hc'));
+	const delayRef = useValueAsRef<HoverDelay | (() => HoverDelay)>(delay, subSlot(slot, 'delay'));
+	const restMsRef = useValueAsRef<number | (() => number)>(restMs, subSlot(slot, 'rest'));
+	const enabledRef = useValueAsRef<boolean>(enabled, subSlot(slot, 'en'));
+	const shouldOpenRef = useValueAsRef<(() => boolean) | undefined>(
+		shouldOpenProp,
+		subSlot(slot, 'so'),
+	);
+	const isClosingRef = useValueAsRef<(() => boolean) | undefined>(isClosing, subSlot(slot, 'cl'));
+
+	const isClickLikeOpenEvent = useStableCallback(
+		() => {
+			return isClickLikeOpenEventShared(dataRef.current.openEvent?.type, instance.interactedInside);
+		},
+		subSlot(slot, 'iclo'),
+	);
+
+	const checkShouldOpen = useStableCallback(
+		() => {
+			return shouldOpenRef.current?.() !== false;
+		},
+		subSlot(slot, 'cso'),
+	);
+
+	const isOverInactiveTrigger = useStableCallback(
+		(
+			currentDomReference: Element | null,
+			currentTarget: Element,
+			target: EventTarget | null,
+		): boolean => {
+			const allTriggers = store.context.triggerElements;
+
+			// Fast path for normal usage where handlers are attached directly to triggers.
+			if (allTriggers.hasElement(currentTarget)) {
+				return !currentDomReference || !contains(currentDomReference, currentTarget);
+			}
+
+			// Fallback for delegated/wrapper usage where currentTarget may be outside the map.
+			if (!isElement(target)) {
+				return false;
+			}
+
+			const targetElement = target as Element;
+			return (
+				allTriggers.hasMatchingElement((trigger: Element) => contains(trigger, targetElement)) &&
+				(!currentDomReference || !contains(currentDomReference, targetElement))
+			);
+		},
+		subSlot(slot, 'ooit'),
+	);
+
+	const cleanupMouseMoveHandler = useStableCallback(
+		() => {
+			if (!instance.handler) {
+				return;
+			}
+			const doc = ownerDocument(store.select('domReferenceElement'));
+			doc.removeEventListener('mousemove', instance.handler);
+			instance.handler = undefined;
+		},
+		subSlot(slot, 'cmmh'),
+	);
+
+	const clearPointerEvents = useStableCallback(
+		() => {
+			clearSafePolygonPointerEventsMutation(instance);
+		},
+		subSlot(slot, 'cpe'),
+	);
+
+	if (isActiveTrigger) {
+		instance.handleCloseOptions = handleCloseRef.current?.__options;
+	}
+
+	useEffect(() => cleanupMouseMoveHandler, [cleanupMouseMoveHandler], subSlot(slot, 'e:cleanup'));
+
+	// When closing before opening, clear the delay timeouts to cancel it from showing.
+	useEffect(
+		() => {
+			if (!enabled) {
+				return undefined;
+			}
+
+			function onOpenChangeLocal(details: any) {
+				if (!details.open) {
+					isHoverCloseActiveRef.current = details.reason === REASONS.triggerHover;
+					cleanupMouseMoveHandler();
+					instance.openChangeTimeout.clear();
+					instance.restTimeout.clear();
+					instance.blockMouseMove = true;
+					instance.restTimeoutPending = false;
+				} else {
+					isHoverCloseActiveRef.current = false;
+				}
+			}
+
+			events.on('openchange', onOpenChangeLocal);
+			return () => {
+				events.off('openchange', onOpenChangeLocal);
+			};
+		},
+		[enabled, events, instance, cleanupMouseMoveHandler],
+		subSlot(slot, 'e:openchange'),
+	);
+
+	useEffect(
+		() => {
+			if (!enabled) {
+				return undefined;
+			}
+
+			function closeWithDelay(event: MouseEvent, runElseBranch = true) {
+				const closeDelay = getDelay(delayRef.current, 'close', instance.pointerType);
+				if (closeDelay) {
+					instance.openChangeTimeout.start(closeDelay, () => {
+						store.setOpen(false, createChangeEventDetails(REASONS.triggerHover, event));
+						tree?.events.emit('floating.closed', event);
+					});
+				} else if (runElseBranch) {
+					instance.openChangeTimeout.clear();
+					store.setOpen(false, createChangeEventDetails(REASONS.triggerHover, event));
+					tree?.events.emit('floating.closed', event);
+				}
+			}
+
+			const trigger =
+				(triggerElementRef.current as HTMLElement | null) ??
+				(isActiveTrigger ? (store.select('domReferenceElement') as HTMLElement | null) : null);
+
+			if (!isElement(trigger)) {
+				return undefined;
+			}
+
+			function onMouseEnter(event: MouseEvent) {
+				instance.openChangeTimeout.clear();
+				instance.blockMouseMove = false;
+
+				if (mouseOnly && !isMouseLikePointerType(instance.pointerType)) {
+					return;
+				}
+
+				// Only a rest delay is set; there's no fallback delay. `onMouseMove` handles it.
+				const restMsValue = getRestMs(restMsRef.current);
+				const openDelay = getDelay(delayRef.current, 'open', instance.pointerType);
+				const eventTarget = getTarget(event);
+				const currentTarget = (event.currentTarget as HTMLElement) ?? null;
+				const currentDomReference = store.select('domReferenceElement');
+				let triggerNode = currentTarget;
+
+				// Wrapper/delegated mode: resolve the actual trigger from the event target.
+				if (isElement(eventTarget) && !store.context.triggerElements.hasElement(eventTarget)) {
+					for (const triggerElement of store.context.triggerElements.elements()) {
+						if (contains(triggerElement, eventTarget)) {
+							triggerNode = triggerElement as HTMLElement;
+							break;
+						}
+					}
+				}
+
+				// Wrapper/delegated fallback: if the wrapper contains the active trigger, treat this
+				// as re-entering that active trigger.
+				if (
+					isElement(currentTarget) &&
+					isElement(currentDomReference) &&
+					!store.context.triggerElements.hasElement(currentTarget) &&
+					contains(currentTarget, currentDomReference)
+				) {
+					triggerNode = currentDomReference as HTMLElement;
+				}
+
+				const isOverInactive =
+					triggerNode == null
+						? false
+						: isOverInactiveTrigger(currentDomReference, triggerNode, eventTarget);
+				const isOpen = store.select('open');
+				const isInClosingTransition =
+					isClosingRef.current?.() ?? store.select('transitionStatus') === 'ending';
+				const isHoverCloseTransition =
+					!isOpen && isInClosingTransition && isHoverCloseActiveRef.current;
+				const isReenteringSameTriggerDuringCloseTransition =
+					!isOverInactive &&
+					isElement(triggerNode) &&
+					isElement(currentDomReference) &&
+					contains(currentDomReference, triggerNode) &&
+					isHoverCloseTransition;
+				const isRestOnlyDelay = restMsValue > 0 && !openDelay;
+				const shouldOpenImmediately =
+					(isOverInactive && (isOpen || isHoverCloseTransition)) ||
+					isReenteringSameTriggerDuringCloseTransition;
+
+				const shouldOpen = !isOpen || isOverInactive;
+
+				// Open immediately when moving between triggers while open, or during a hover-driven
+				// close transition (including same-trigger re-entry).
+				if (shouldOpenImmediately) {
+					if (checkShouldOpen()) {
+						store.setOpen(true, createChangeEventDetails(REASONS.triggerHover, event, triggerNode));
+					}
+					return;
+				}
+
+				if (isRestOnlyDelay) {
+					return;
+				}
+
+				if (openDelay) {
+					instance.openChangeTimeout.start(openDelay, () => {
+						if (shouldOpen && checkShouldOpen()) {
+							store.setOpen(
+								true,
+								createChangeEventDetails(REASONS.triggerHover, event, triggerNode),
+							);
+						}
+					});
+				} else if (shouldOpen) {
+					if (checkShouldOpen()) {
+						store.setOpen(true, createChangeEventDetails(REASONS.triggerHover, event, triggerNode));
+					}
+				}
+			}
+
+			function onMouseLeave(event: MouseEvent) {
+				if (isClickLikeOpenEvent()) {
+					clearPointerEvents();
+					return;
+				}
+
+				cleanupMouseMoveHandler();
+
+				const domReferenceElement = store.select('domReferenceElement');
+				const doc = ownerDocument(domReferenceElement);
+				instance.restTimeout.clear();
+				instance.restTimeoutPending = false;
+
+				const handleCloseContextBase = dataRef.current.floatingContext ?? getHandleCloseContext?.();
+
+				if (isInsideEnabledTrigger(event.relatedTarget, store.context.triggerElements)) {
+					return;
+				}
+
+				if (handleCloseRef.current && handleCloseContextBase) {
+					if (!store.select('open')) {
+						instance.openChangeTimeout.clear();
+					}
+
+					const currentTrigger = triggerElementRef.current;
+
+					instance.handler = handleCloseRef.current({
+						...handleCloseContextBase,
+						tree,
+						x: event.clientX,
+						y: event.clientY,
+						onClose() {
+							clearPointerEvents();
+							cleanupMouseMoveHandler();
+							if (
+								enabledRef.current &&
+								!isClickLikeOpenEvent() &&
+								currentTrigger === store.select('domReferenceElement')
+							) {
+								closeWithDelay(event, true);
+							}
+						},
+					});
+
+					const activeHandler = instance.handler;
+					doc.addEventListener('mousemove', activeHandler as EventListener);
+					activeHandler(event);
+
+					return;
+				}
+
+				const shouldClose =
+					instance.pointerType === 'touch'
+						? !contains(store.select('floatingElement'), event.relatedTarget as Element | null)
+						: true;
+
+				if (shouldClose) {
+					closeWithDelay(event);
+				}
+			}
+
+			if (move) {
+				return mergeCleanups(
+					addEventListener(trigger, 'mousemove', onMouseEnter as EventListener, { once: true }),
+					addEventListener(trigger, 'mouseenter', onMouseEnter as EventListener),
+					addEventListener(trigger, 'mouseleave', onMouseLeave as EventListener),
+				);
+			}
+
+			return mergeCleanups(
+				addEventListener(trigger, 'mouseenter', onMouseEnter as EventListener),
+				addEventListener(trigger, 'mouseleave', onMouseLeave as EventListener),
+			);
+		},
+		[
+			cleanupMouseMoveHandler,
+			clearPointerEvents,
+			dataRef,
+			delayRef,
+			store,
+			enabled,
+			handleCloseRef,
+			instance,
+			isActiveTrigger,
+			isOverInactiveTrigger,
+			isClickLikeOpenEvent,
+			mouseOnly,
+			move,
+			restMsRef,
+			triggerElementRef,
+			tree,
+			enabledRef,
+			getHandleCloseContext,
+			isClosingRef,
+			checkShouldOpen,
+		],
+		subSlot(slot, 'e:listeners'),
+	);
+
+	return useMemo(
+		() => {
+			if (!enabled) {
+				return undefined;
+			}
+
+			function setPointerRef(event: PointerEvent) {
+				instance.pointerType = event.pointerType;
+			}
+
+			return {
+				onPointerDown: setPointerRef,
+				onPointerEnter: setPointerRef,
+				onMouseMove(event: MouseEvent) {
+					const trigger = event.currentTarget as HTMLElement;
+
+					const currentDomReference = store.select('domReferenceElement');
+					const currentOpen = store.select('open');
+					const isOverInactive = isOverInactiveTrigger(currentDomReference, trigger, event.target);
+
+					if (mouseOnly && !isMouseLikePointerType(instance.pointerType)) {
+						return;
+					}
+
+					if (currentOpen && isOverInactive && instance.handleCloseOptions?.blockPointerEvents) {
+						const floatingElement = store.select('floatingElement');
+
+						if (floatingElement) {
+							const scopeElement =
+								instance.handleCloseOptions?.getScope?.() ?? trigger.ownerDocument.body;
+
+							applySafePolygonPointerEventsMutation(instance, {
+								scopeElement,
+								referenceElement: trigger,
+								floatingElement,
+							});
+						}
+					}
+
+					const restMsValue = getRestMs(restMsRef.current);
+					if ((currentOpen && !isOverInactive) || restMsValue === 0) {
+						return;
+					}
+
+					if (
+						!isOverInactive &&
+						instance.restTimeoutPending &&
+						event.movementX ** 2 + event.movementY ** 2 < 2
+					) {
+						return;
+					}
+
+					instance.restTimeout.clear();
+
+					function handleMouseMove() {
+						instance.restTimeoutPending = false;
+
+						// A delayed hover open must not override a click-like open that happened while
+						// the hover delay was pending.
+						if (isClickLikeOpenEvent()) {
+							return;
+						}
+
+						const latestOpen = store.select('open');
+
+						if (!instance.blockMouseMove && (!latestOpen || isOverInactive) && checkShouldOpen()) {
+							store.setOpen(true, createChangeEventDetails(REASONS.triggerHover, event, trigger));
+						}
+					}
+
+					if (instance.pointerType === 'touch') {
+						flushSync(() => {
+							handleMouseMove();
+						});
+					} else if (isOverInactive && currentOpen) {
+						handleMouseMove();
+					} else {
+						instance.restTimeoutPending = true;
+						instance.restTimeout.start(restMsValue, handleMouseMove);
+					}
+				},
+			};
+		},
+		[
+			enabled,
+			instance,
+			isClickLikeOpenEvent,
+			isOverInactiveTrigger,
+			mouseOnly,
+			store,
+			restMsRef,
+			checkShouldOpen,
+		],
+		subSlot(slot, 'props'),
+	);
 }

package/src/utils/floating/useHoverShared.ts

@@ -0,0 +1,78 @@
+// Ported from .base-ui/packages/react/src/floating-ui-react/hooks/useHoverShared.ts (v1.6.0).
+// Pure helpers shared by the reference-side and floating-side hover interactions: delay
+// resolution (a hover delay may be a number, a {open, close} pair, or a getter), and the
+// open-event classification that decides whether a hover close is allowed to run.
+import { isMouseLikePointerType } from './event';
+import type { PopupTriggerMap } from '../popups/popupTriggerMap';
+
+export { isTargetInsideEnabledTrigger as isInsideEnabledTrigger } from './element';
+export type { PopupTriggerMap };
+
+export interface HandleCloseOptions {
+	blockPointerEvents?: boolean | undefined;
+	getScope?: (() => HTMLElement | SVGSVGElement | null) | undefined;
+}
+
+export interface HandleCloseContext {
+	x: number | null;
+	y: number | null;
+	placement: string | null;
+	elements: { domReference: Element | null; floating: HTMLElement | null };
+	onClose: () => void;
+	nodeId?: string | undefined;
+	tree?: any;
+	leave?: boolean | undefined;
+}
+
+export type HandleCloseContextBase = Omit<HandleCloseContext, 'onClose' | 'tree' | 'x' | 'y'>;
+
+export interface HandleClose {
+	(context: HandleCloseContext): (event: MouseEvent) => void;
+	__options?: HandleCloseOptions | undefined;
+}
+
+export type HoverDelay = number | Partial<{ open: number; close: number }>;
+
+function resolveValue<T>(
+	value: T | (() => T) | undefined,
+	pointerType?: string | undefined,
+): T | 0 | undefined {
+	// Touch and pen never wait: a hover delay only makes sense for a cursor.
+	if (pointerType != null && !isMouseLikePointerType(pointerType)) {
+		return 0;
+	}
+	if (typeof value === 'function') {
+		return (value as () => T)();
+	}
+	return value;
+}
+
+export function getDelay(
+	value: HoverDelay | (() => HoverDelay) | undefined,
+	prop: 'open' | 'close',
+	pointerType?: string | undefined,
+): number | undefined {
+	const result = resolveValue(value, pointerType);
+	if (typeof result === 'number') {
+		return result;
+	}
+	return (result as Partial<{ open: number; close: number }> | undefined)?.[prop];
+}
+
+export function getRestMs(value: number | (() => number)): number {
+	if (typeof value === 'function') {
+		return value();
+	}
+	return value;
+}
+
+export function isClickLikeOpenEvent(
+	openEventType: string | undefined,
+	interactedInside: boolean,
+): boolean {
+	return interactedInside || openEventType === 'click' || openEventType === 'mousedown';
+}
+
+export function isHoverOpenEvent(openEventType: string | undefined): boolean {
+	return Boolean(openEventType?.includes('mouse')) && openEventType !== 'mousedown';
+}