@octanejs/base-ui 0.1.49 → 0.1.51

package/src/utils/popups/popupStoreUtils.ts

@@ -1,172 +1,261 @@
-// Ported from .base-ui/packages/react/src/utils/popups/popupStoreUtils.ts (v1.6.0), octane-adapted.
-// The shared hooks + helpers every popup Root/Trigger/Popup routes through: store creation +
-// floating-root sync (`usePopupStore`), trigger registration, the open-change sequence
-// (`applyPopupOpenChange`), mounted/transition management (`useOpenStateTransitions`), and interaction-
-// prop syncing. octane adaptations: every hook threads an explicit slot; `useIsoLayoutEffect` →
-// `useLayoutEffect`; `ReactDOM.flushSync` → octane `flushSync`; `useId` → `useBaseUiId`.
-import { useRef, useCallback, useLayoutEffect, flushSync, useId } from 'octane';
-
-import { subSlot } from '../../internal';
-import { useStableCallback } from '../useStableCallback';
-import { useOnFirstRender } from '../useOnFirstRender';
-import { useTransitionStatus } from '../useTransitionStatus';
-import { useOpenChangeComplete } from '../useOpenChangeComplete';
-import { EMPTY_OBJECT } from '../empty';
-import { FOCUSABLE_ATTRIBUTE } from '../floating/constants';
-import { useFloatingParentNodeId } from '../floating/FloatingTree';
-import { useSyncedFloatingRootContext } from '../floating/useSyncedFloatingRootContext';
-import { createChangeEventDetails, REASONS } from '../createChangeEventDetails';
-import type { ReactStore } from '../store/ReactStore';
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import * as ReactDOM from 'octane';
+import type { ReactStore } from '@octanejs/base-ui-utils/store';
+import { EMPTY_OBJECT } from '@octanejs/base-ui-utils/empty';
+import type { InteractionType } from '@octanejs/base-ui-utils/useEnhancedClickHandler';
+import { useId } from '@octanejs/base-ui-utils/useId';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useRefWithInit } from '@octanejs/base-ui-utils/useRefWithInit';
+import { FOCUSABLE_ATTRIBUTE } from '../../floating-ui-react/utils/constants';
+import { useFloatingParentNodeId } from '../../floating-ui-react/components/FloatingTree.tsrx';
 import {
+	useSyncedFloatingRootContext,
+	type SyncedFloatingRootContextStore,
+} from '../../floating-ui-react/hooks/useSyncedFloatingRootContext';
+import { useTransitionStatus } from '../../internals/useTransitionStatus';
+import { useOpenChangeComplete } from '../../internals/useOpenChangeComplete.tsrx';
+import type { HTMLProps } from '../../internals/types';
+import {
+	createChangeEventDetails,
+	type BaseUIChangeEventDetails,
+} from '../../internals/createBaseUIEventDetails';
+import { REASONS } from '../../internals/reasons';
+import type {
 	PopupStoreState,
 	PopupStoreContext,
 	popupStoreSelectors,
-	PopupStoreSelectors,
+	PopupTriggerDataStore,
 } from './store';
 
-export type InteractionType = 'mouse' | 'touch' | 'pen' | 'keyboard';
-
 export const FOCUSABLE_POPUP_PROPS = {
 	tabIndex: -1,
 	[FOCUSABLE_ATTRIBUTE]: '',
-};
-
-/** The default `initialFocus` resolver: focus the popup itself when opened by touch, else default. */
-export function createDefaultInitialFocus(popupRef: { current: HTMLElement | null }) {
+} satisfies HTMLProps<HTMLElement> & Record<typeof FOCUSABLE_ATTRIBUTE, string>;
+
+/**
+ * Returns the default `initialFocus` resolver for a popup. When opened by touch it focuses the
+ * popup element itself to prevent the virtual keyboard from opening (required for Android
+ * specifically; iOS handles this automatically). Otherwise it falls back to the default behavior.
+ */
+export function createDefaultInitialFocus(popupRef: React.RefObject<HTMLElement | null>) {
 	return (interactionType: InteractionType) =>
 		interactionType === 'touch' ? popupRef.current : true;
 }
 
-type AnyPopupStore = ReactStore<any, PopupStoreContext<any>, PopupStoreSelectors> & {
-	setOpen(open: boolean, eventDetails: any): void;
-};
+type PopupStoreWithOpen<
+	State extends PopupStoreState<unknown>,
+	SetOpenEventDetails extends BaseUIChangeEventDetails<string>,
+> = PopupTriggerDataStore<State> &
+	Pick<SyncedFloatingRootContextStore<State>, 'useSyncedValue'> & {
+		setOpen(open: boolean, eventDetails: SetOpenEventDetails): void;
+	};
+
+/**
+ * The subset of a popup handle that a Root needs to bind its store to. Both the real handle classes
+ * and any test double satisfy it.
+ */
+export interface PopupRootStoreHandle<Store> {
+	attachStore(store: Store): () => void;
+}
 
-export function usePopupStore<Store extends AnyPopupStore>(
-	externalStore: Store | undefined,
+/**
+ * Creates and owns a popup store on behalf of a Root part. The store is created exactly once, with
+ * controlled props and root state synced separately after creation. Sets up the synced floating
+ * root context and returns the store.
+ *
+ * @param createStore Factory that builds the store. Called exactly once, receiving the floating id
+ * and whether the popup is nested inside another floating element, both resolved on the first render.
+ * @param treatPopupAsFloatingElement Whether the popup element is passed to Floating UI as the
+ * floating element instead of the default positioner.
+ */
+export function usePopupRootStore<
+	State extends PopupStoreState<unknown>,
+	SetOpenEventDetails extends BaseUIChangeEventDetails<string>,
+	Store extends PopupStoreWithOpen<State, SetOpenEventDetails>,
+>(
 	createStore: (floatingId: string | undefined, nested: boolean) => Store,
-	treatPopupAsFloatingElement: boolean,
-	slot: symbol | undefined,
-): { store: Store; internalStore: Store | null } {
-	// Raw `useId` (no `base-ui-` prefix), matching Base UI's `@base-ui/utils/useId`.
-	const floatingId = useId(subSlot(slot, 'fid'));
+	treatPopupAsFloatingElement = false,
+): Store {
+	const floatingId = useId();
 	const nested = useFloatingParentNodeId() != null;
 
-	const internalStoreRef = useRef<Store | null>(null, subSlot(slot, 'store'));
-	if (externalStore === undefined && internalStoreRef.current === null) {
-		internalStoreRef.current = createStore(floatingId, nested);
-	}
+	const store = useRefWithInit(() => createStore(floatingId, nested)).current;
 
-	const store = externalStore ?? internalStoreRef.current!;
+	useSyncedFloatingRootContext({
+		popupStore: store,
+		treatPopupAsFloatingElement,
+		floatingRootContext: store.state.floatingRootContext,
+		floatingId,
+		nested,
+		onOpenChange: store.setOpen,
+	});
 
-	useSyncedFloatingRootContext(
-		{
-			popupStore: store,
-			treatPopupAsFloatingElement,
-			floatingRootContext: store.state.floatingRootContext,
-			floatingId,
-			nested,
-			onOpenChange: store.setOpen,
-		},
-		subSlot(slot, 'synced'),
-	);
+	return store;
+}
 
-	return { store, internalStore: internalStoreRef.current };
+/**
+ * Attaches a Root's store to a handle for this component's committed lifetime. Popup Roots render
+ * it before their interactions and user children so its layout effect runs before descendant layout
+ * effects. This lets descendants call the handle during the Root's initial commit without attaching
+ * during render, which would leak suspended or abandoned stores. Store subscribers are notified by
+ * `attachStore` in this ordinary layout phase, where React permits synchronous updates.
+ *
+ * Popup Roots must render this component only when a handle is present so handle-less Roots avoid
+ * mounting an extra fiber and layout effect.
+ */
+export function PopupHandleAttachment<Store>({
+	handle,
+	store,
+}: {
+	handle: PopupRootStoreHandle<Store>;
+	store: Store;
+}) {
+	useIsoLayoutEffect(() => {
+		return handle.attachStore(store);
+	}, [handle, store]);
+
+	return null;
 }
 
-/** A callback ref that registers/unregisters the trigger element in the store. */
+function syncTriggerCount(store: PopupTriggerDataStore<PopupStoreState<unknown>>) {
+	const triggerCount = store.context.triggerElements.size;
+	if (store.select('open') && store.state.triggerCount !== triggerCount) {
+		store.set('triggerCount', triggerCount);
+	}
+}
+
+/**
+ * Returns a stable callback ref that registers/unregisters the trigger element in the store.
+ *
+ * Stable so a downstream ref merger that retains the callback it was first given still reaches the
+ * trigger's current store. The registration is tracked as a `(store, id, element)` triple, so
+ * unregistering targets the store the element was actually registered in.
+ *
+ * Since the callback never changes, the caller must re-run it from a layout effect keyed on
+ * `[store, id]` to migrate an already-registered element. That effect is also what registers the
+ * element in the first place when `id` only resolves after the first commit (React 17's `useId`
+ * fallback), because the register call made while the id is still `undefined` does nothing.
+ *
+ * @param id Id of the trigger.
+ * @param store The Store instance where the trigger should be registered.
+ */
 export function useTriggerRegistration<State extends PopupStoreState<unknown>>(
 	id: string | undefined,
-	store: ReactStore<State, PopupStoreContext<never>, PopupStoreSelectors>,
-	slot: symbol | undefined,
-): (element: Element | null) => void {
-	const registeredElementIdRef = useRef<string | null>(null, subSlot(slot, 'rid'));
-	const registeredElementRef = useRef<Element | null>(null, subSlot(slot, 'rel'));
-
-	return useCallback(
-		(element: Element | null) => {
-			if (id === undefined) {
-				return;
-			}
-
-			let shouldSyncTriggerCount = false;
+	store: PopupTriggerDataStore<State>,
+) {
+	const registrationRef = React.useRef<{
+		store: PopupTriggerDataStore<State>;
+		id: string;
+		element: Element;
+	} | null>(null);
 
-			if (registeredElementIdRef.current !== null) {
-				const registeredId = registeredElementIdRef.current;
-				const registeredElement = registeredElementRef.current;
-				const currentElement = store.context.triggerElements.getById(registeredId);
+	return useStableCallback((element: Element | null) => {
+		const registration = registrationRef.current;
 
-				if (registeredElement && currentElement === registeredElement) {
-					store.context.triggerElements.delete(registeredId);
-					shouldSyncTriggerCount = true;
-				}
-
-				registeredElementIdRef.current = null;
-				registeredElementRef.current = null;
+		if (registration !== null) {
+			if (
+				registration.element === element &&
+				registration.store === store &&
+				registration.id === id
+			) {
+				// Already registered where it belongs, so the caller's migration effect is free on mount.
+				return;
 			}
 
-			if (element !== null) {
-				registeredElementIdRef.current = id;
-				registeredElementRef.current = element;
-				store.context.triggerElements.add(id, element);
-				shouldSyncTriggerCount = true;
+			registrationRef.current = null;
+			const registeredStore = registration.store;
+			if (
+				registeredStore.context.triggerElements.getById(registration.id) === registration.element
+			) {
+				registeredStore.context.triggerElements.delete(registration.id);
+				syncTriggerCount(registeredStore);
 			}
+		}
 
-			if (shouldSyncTriggerCount) {
-				const triggerCount = store.context.triggerElements.size;
-				if (store.select('open') && store.state.triggerCount !== triggerCount) {
-					store.set('triggerCount', triggerCount);
-				}
-			}
-		},
-		[store, id],
-		subSlot(slot, 'cb'),
-	);
+		if (element !== null && id !== undefined) {
+			registrationRef.current = { store, id, element };
+			store.context.triggerElements.add(id, element);
+			syncTriggerCount(store);
+		}
+	});
 }
 
-export function setPopupOpenState(
-	state: Partial<PopupStoreState<unknown>>,
+type PopupOpenState = Pick<
+	PopupStoreState<unknown>,
+	'open' | 'preventUnmountingOnClose' | 'activeTriggerId' | 'activeTriggerElement'
+>;
+
+export function createPopupOpenState(
+	state: PopupOpenState,
 	open: boolean,
 	trigger: Element | undefined,
 	preventUnmountOnClose = false,
-) {
+): PopupOpenState {
+	let preventUnmountingOnClose = state.preventUnmountingOnClose;
 	if (open) {
-		state.preventUnmountingOnClose = false;
+		// Opening starts a new close cycle, so clear any previous request to keep the popup mounted.
+		preventUnmountingOnClose = false;
 	} else if (preventUnmountOnClose) {
-		state.preventUnmountingOnClose = true;
+		preventUnmountingOnClose = true;
 	}
 
 	const triggerId = trigger?.id ?? null;
+	let activeTriggerId = state.activeTriggerId;
+	let activeTriggerElement = state.activeTriggerElement;
 
+	// If a popup is closing, the `trigger` may be undefined.
+	// We want to keep the previous value so that exit animations are played and focus is returned correctly.
 	if (triggerId || open) {
-		state.activeTriggerId = triggerId;
-		state.activeTriggerElement = trigger ?? null;
+		activeTriggerId = triggerId;
+		activeTriggerElement = trigger ?? null;
 	}
+
+	return {
+		open,
+		preventUnmountingOnClose,
+		activeTriggerId,
+		activeTriggerElement,
+	};
 }
 
 export function attachPreventUnmountOnClose(eventDetails: { preventUnmountOnClose(): void }) {
 	let preventUnmountOnClose = false;
+
 	eventDetails.preventUnmountOnClose = () => {
 		preventUnmountOnClose = true;
 	};
+
 	return () => preventUnmountOnClose;
 }
 
-/** The shared open-change sequence (notify → cancel-check → dispatch → commit). Non-hook. */
+/**
+ * Runs the shared open-change sequence for a popup store: notifies `onOpenChange`,
+ * honors cancellation, dispatches the floating root change, maps the reason to an
+ * `instantType`, and commits the state update (synchronously for hover so
+ * `getAnimations()` observes it). Stores supply their own differences via
+ * `extraState` (e.g. the last change reason) and `onBeforeDispatch` (e.g. updating
+ * inline-rect coordinates).
+ */
 export function applyPopupOpenChange<
 	State extends PopupStoreState<unknown> & {
 		instantType?: 'delay' | 'dismiss' | 'focus' | undefined;
 	},
+	EventDetails extends BaseUIChangeEventDetails<string>,
+	ExtraKey extends keyof State = never,
 >(
 	store: {
-		readonly context: Pick<PopupStoreContext<any>, 'onOpenChange'>;
-		readonly state: Pick<PopupStoreState<unknown>, 'floatingRootContext'>;
-		update(state: Partial<State>): void;
+		readonly context: Pick<PopupStoreContext<EventDetails>, 'onOpenChange'>;
+		readonly state: State;
+		update<const Key extends keyof State>(state: Pick<State, Key>): void;
 	},
 	nextOpen: boolean,
-	eventDetails: any & { preventUnmountOnClose(): void },
+	eventDetails: EventDetails & { preventUnmountOnClose(): void },
 	options: {
 		onBeforeDispatch?: (() => void) | undefined;
-		extraState?: Partial<State> | undefined;
+		extraState?: Pick<State, ExtraKey> | undefined;
 	} = {},
 ): void {
 	const reason = eventDetails.reason;
@@ -188,9 +277,17 @@ export function applyPopupOpenChange<
 	store.state.floatingRootContext.dispatchOpenChange(nextOpen, eventDetails);
 
 	const changeState = () => {
-		const updatedState: Partial<PopupStoreState<unknown>> & {
-			instantType?: 'delay' | 'dismiss' | 'focus' | undefined;
-		} = { ...options.extraState, open: nextOpen };
+		const popupOpenState = createPopupOpenState(
+			store.state,
+			nextOpen,
+			eventDetails.trigger,
+			shouldPreventUnmountOnClose(),
+		);
+
+		const updatedState = { ...options.extraState, ...popupOpenState } as Pick<
+			State,
+			keyof PopupOpenState | ExtraKey | 'instantType'
+		>;
 
 		if (isFocusOpen) {
 			updatedState.instantType = 'focus';
@@ -200,285 +297,350 @@ export function applyPopupOpenChange<
 			updatedState.instantType = undefined;
 		}
 
-		setPopupOpenState(updatedState, nextOpen, eventDetails.trigger, shouldPreventUnmountOnClose());
-		store.update(updatedState as Partial<State>);
+		store.update(updatedState);
 	};
 
 	if (isHover) {
-		flushSync(changeState);
+		// Flush synchronously for hover so `node.getAnimations()` sees the new state.
+		ReactDOM.flushSync(changeState);
 	} else {
 		changeState();
 	}
 }
 
-export function useInitialOpenSync<State extends PopupStoreState<unknown>>(
-	store: ReactStore<State, PopupStoreContext<never>, PopupStoreSelectors>,
-	openProp: boolean | undefined,
-	defaultOpen: boolean,
-	defaultTriggerId: string | null,
-	slot: symbol | undefined,
-) {
-	useOnFirstRender(
-		() => {
-			if (openProp === undefined && store.state.open === false && defaultOpen) {
-				store.state = {
-					...store.state,
-					open: true,
-					activeTriggerId: defaultTriggerId,
-					preventUnmountingOnClose: false,
-				};
-			}
-		},
-		subSlot(slot, 'first'),
-	);
-}
-
-export function useTriggerDataForwarding<State extends PopupStoreState<unknown>>(
+/**
+ * Sets up trigger data forwarding to the store.
+ *
+ * @param triggerId Id of the trigger.
+ * @param triggerElementRef Ref for the trigger DOM element.
+ * @param store The Store instance managing the popup state.
+ * @param stateUpdates An object with state updates to apply when the trigger is active.
+ */
+export function useTriggerDataForwarding<
+	State extends PopupStoreState<unknown>,
+	const Key extends keyof Omit<State, 'activeTriggerId' | 'activeTriggerElement'>,
+>(
 	triggerId: string | undefined,
-	triggerElementRef: { current: Element | null },
-	store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>,
-	stateUpdates: Partial<State>,
-	slot: symbol | undefined,
+	triggerElementRef: React.RefObject<Element | null>,
+	store: PopupTriggerDataStore<State>,
+	stateUpdates: Pick<State, Key>,
 ) {
-	const isMountedByThisTrigger = store.useState(
-		'isMountedByTrigger',
-		subSlot(slot, 'mbt'),
-		triggerId,
-	);
-
-	const baseRegisterTrigger = useTriggerRegistration(triggerId, store, subSlot(slot, 'reg'));
-
-	const registerTrigger = useStableCallback(
-		(element: Element | null) => {
-			baseRegisterTrigger(element);
-
-			if (!element) {
-				return;
-			}
-
-			const open = store.select('open');
-			const activeTriggerId = store.select('activeTriggerId');
-
-			if (activeTriggerId === triggerId) {
-				store.update({
-					activeTriggerElement: element,
-					...(open ? stateUpdates : null),
-				} as Partial<State>);
-				return;
-			}
-
-			if (activeTriggerId == null && open) {
-				store.update({
-					activeTriggerId: triggerId,
-					activeTriggerElement: element,
-					...stateUpdates,
-				} as Partial<State>);
-			}
-		},
-		subSlot(slot, 'regcb'),
-	);
+	const isMountedByThisTrigger = store.useState('isMountedByTrigger', triggerId);
+
+	const baseRegisterTrigger = useTriggerRegistration(triggerId, store);
+
+	// Applies trigger-owned state (active-trigger ownership and payload) when the trigger registers.
+	// Stable so payload/`stateUpdates` changes do not change the ref identity (which would needlessly
+	// churn registration); it reads the latest closure values when invoked.
+	const applyTriggerData = useStableCallback((element: Element) => {
+		const open = store.select('open');
+		const activeTriggerId = store.select('activeTriggerId');
+
+		if (activeTriggerId === triggerId) {
+			const changes = {
+				activeTriggerElement: element,
+				...(open ? stateUpdates : null),
+			} as Pick<Readonly<State>, Key | 'activeTriggerElement'>;
+			store.update(changes);
+			return;
+		}
 
-	useLayoutEffect(
-		() => {
-			if (isMountedByThisTrigger) {
-				store.update({
-					activeTriggerElement: triggerElementRef.current,
-					...stateUpdates,
-				} as Partial<State>);
-			}
-		},
-		[isMountedByThisTrigger, store, triggerElementRef, ...Object.values(stateUpdates)],
-		subSlot(slot, 'e'),
-	);
+		if (activeTriggerId == null && open) {
+			// If a popup is already open, a detached trigger can mount before any active trigger
+			// has been established. Claim the first registered trigger so trigger-owned focus
+			// management and ARIA relationships work.
+			const changes = {
+				activeTriggerId: triggerId ?? null,
+				activeTriggerElement: element,
+				...stateUpdates,
+			} as Pick<Readonly<State>, Key | 'activeTriggerId' | 'activeTriggerElement'>;
+			store.update(changes);
+		}
+	});
+
+	// Stable, so the merged ref on the rendered element keeps its identity for the trigger's whole
+	// lifetime.
+	const registerTrigger = useStableCallback((element: Element | null) => {
+		baseRegisterTrigger(element);
+		if (element) {
+			applyTriggerData(element);
+		}
+	});
+
+	// A stable ref does not re-fire on a store or id change, so migrate here instead: unregister from
+	// the previous store, then register the element the trigger still renders into the current one.
+	useIsoLayoutEffect(() => {
+		registerTrigger(triggerElementRef.current);
+		return () => registerTrigger(null);
+	}, [registerTrigger, triggerElementRef, store, triggerId]);
+
+	useIsoLayoutEffect(() => {
+		if (isMountedByThisTrigger) {
+			const changes = {
+				activeTriggerElement: triggerElementRef.current,
+				...stateUpdates,
+			} as Pick<Readonly<State>, Key | 'activeTriggerElement'>;
+			store.update(changes);
+		}
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [isMountedByThisTrigger, store, triggerElementRef, ...Object.values(stateUpdates)]);
 
 	return { registerTrigger, isMountedByThisTrigger };
 }
 
+export type PayloadChildRenderFunction<Payload> = (arg: {
+	payload: Payload | undefined;
+}) => React.OctaneNode;
+
+/**
+ * Keeps trigger registration state synchronized while the popup is open.
+ *
+ * When a popup opens without an explicit trigger id and exactly one trigger is registered, that
+ * trigger is claimed as the active trigger. When the active trigger id is still registered but its
+ * element changed, the active element is refreshed. When the active trigger id is missing from the
+ * registry but the same element is still registered under a different id (e.g. the rendered trigger
+ * carries its own DOM `id` that differs from Base UI's internal trigger id), the active id is
+ * reassociated to the registered id instead of being treated as lost. When the active trigger
+ * unregisters, the default path preserves existing ownership so non-closing popup families do not
+ * silently claim a different trigger while staying open.
+ *
+ * If `closeOnActiveTriggerUnmount` is enabled, unregistering a previously resolved active trigger
+ * requests a close after a microtask so a same-tick replacement trigger with the same id can
+ * register first. An active trigger id that has not matched a registered trigger yet is treated as
+ * pending and does not request a close.
+ *
+ * This should be called on the Root part.
+ *
+ * @param store The Store instance managing the popup state.
+ * @param options Options for active trigger unmount behavior.
+ */
 export function useImplicitActiveTrigger<State extends PopupStoreState<unknown>>(
-	store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors> & {
-		setOpen(open: boolean, eventDetails: any): void;
-	},
-	options: { closeOnActiveTriggerUnmount?: boolean | undefined },
-	slot: symbol | undefined,
+	store: PopupStoreWithOpen<State, BaseUIChangeEventDetails<typeof REASONS.none>>,
+	options: {
+		closeOnActiveTriggerUnmount?: boolean | undefined;
+	} = {},
 ) {
 	const { closeOnActiveTriggerUnmount = false } = options;
-	const open = store.useState('open', subSlot(slot, 'open'));
-	const reactiveTriggerCount = store.useState('triggerCount', subSlot(slot, 'tc'));
-
-	useLayoutEffect(
-		() => {
-			if (!open) {
-				if (store.state.triggerCount !== 0) {
-					store.set('triggerCount', 0);
-				}
-				return;
+	// Distinguishes a trigger that unmounted from a new active trigger that has not hydrated yet.
+	const resolvedActiveTriggerIdRef = React.useRef<string | null>(null);
+	const open = store.useState('open');
+	const reactiveTriggerCount = store.useState('triggerCount');
+	// Subscribe to the active trigger id so the reconciliation below reruns when ownership moves to
+	// another trigger while the popup stays open (e.g. a focus/hover handoff between triggers).
+	const activeTriggerId = store.useState('activeTriggerId');
+	// Subscribe to the active trigger element so the reconciliation reruns when a pending active
+	// trigger registers in a commit where the trigger count nets out unchanged (registration
+	// forwards the element to the store when the registering trigger matches the active id).
+	// Without this, the id would never be marked resolved and a later genuine unmount would be
+	// misclassified as pending, disabling `closeOnActiveTriggerUnmount`.
+	const reactiveActiveTriggerElement = store.useState('activeTriggerElement');
+
+	useIsoLayoutEffect(() => {
+		if (!open) {
+			resolvedActiveTriggerIdRef.current = null;
+			if (store.state.triggerCount !== 0) {
+				store.set('triggerCount', 0);
 			}
+			return;
+		}
 
-			const triggerCount = store.context.triggerElements.size;
-			const stateUpdates: Partial<PopupStoreState<unknown>> = {};
+		const triggerCount = store.context.triggerElements.size;
+		const stateUpdates = {} as Pick<
+			State,
+			'triggerCount' | 'activeTriggerId' | 'activeTriggerElement'
+		>;
 
-			if (store.state.triggerCount !== triggerCount) {
-				stateUpdates.triggerCount = triggerCount;
-			}
+		if (store.state.triggerCount !== triggerCount) {
+			stateUpdates.triggerCount = triggerCount;
+		}
 
-			const activeTriggerId = store.select('activeTriggerId');
-			let lostActiveTriggerId: string | null = null;
+		const currentActiveTriggerId = store.select('activeTriggerId');
+		let lostActiveTriggerId: string | null = null;
+
+		if (currentActiveTriggerId) {
+			const activeTriggerElement = store.context.triggerElements.getById(currentActiveTriggerId);
+			if (!activeTriggerElement) {
+				for (const [triggerId, triggerElement] of store.context.triggerElements.entries()) {
+					if (triggerElement === store.state.activeTriggerElement) {
+						stateUpdates.activeTriggerId = triggerId;
+						stateUpdates.activeTriggerElement = triggerElement;
+						resolvedActiveTriggerIdRef.current = triggerId;
+						break;
+					}
+				}
 
-			if (activeTriggerId) {
-				const activeTriggerElement = store.context.triggerElements.getById(activeTriggerId);
-				if (!activeTriggerElement) {
-					lostActiveTriggerId = activeTriggerId;
-				} else if (activeTriggerElement !== store.state.activeTriggerElement) {
+				if (stateUpdates.activeTriggerId === undefined) {
+					if (resolvedActiveTriggerIdRef.current === currentActiveTriggerId) {
+						lostActiveTriggerId = currentActiveTriggerId;
+					} else {
+						resolvedActiveTriggerIdRef.current = null;
+					}
+				}
+			} else {
+				resolvedActiveTriggerIdRef.current = currentActiveTriggerId;
+				if (activeTriggerElement !== store.state.activeTriggerElement) {
 					stateUpdates.activeTriggerElement = activeTriggerElement;
 				}
 			}
+		} else {
+			resolvedActiveTriggerIdRef.current = null;
+		}
 
-			if (!lostActiveTriggerId && !activeTriggerId && triggerCount === 1) {
-				const iteratorResult = store.context.triggerElements.entries().next();
-				if (!iteratorResult.done) {
-					const [implicitTriggerId, implicitTriggerElement] = iteratorResult.value;
-					stateUpdates.activeTriggerId = implicitTriggerId;
-					stateUpdates.activeTriggerElement = implicitTriggerElement;
-				}
+		if (!lostActiveTriggerId && !currentActiveTriggerId && triggerCount === 1) {
+			const iteratorResult = store.context.triggerElements.entries().next();
+			if (!iteratorResult.done) {
+				const [implicitTriggerId, implicitTriggerElement] = iteratorResult.value;
+				stateUpdates.activeTriggerId = implicitTriggerId;
+				stateUpdates.activeTriggerElement = implicitTriggerElement;
+				resolvedActiveTriggerIdRef.current = implicitTriggerId;
 			}
+		}
 
-			if (
-				stateUpdates.triggerCount !== undefined ||
-				stateUpdates.activeTriggerId !== undefined ||
-				stateUpdates.activeTriggerElement !== undefined
-			) {
-				store.update(stateUpdates as Partial<State>);
-			}
+		if (
+			stateUpdates.triggerCount !== undefined ||
+			stateUpdates.activeTriggerId !== undefined ||
+			stateUpdates.activeTriggerElement !== undefined
+		) {
+			store.update(stateUpdates);
+		}
 
-			if (lostActiveTriggerId) {
-				if (closeOnActiveTriggerUnmount) {
-					queueMicrotask(() => {
-						if (
-							store.select('open') &&
-							store.select('activeTriggerId') === lostActiveTriggerId &&
-							!store.context.triggerElements.getById(lostActiveTriggerId)
-						) {
-							const eventDetails = createChangeEventDetails(REASONS.none);
-							store.setOpen(false, eventDetails);
-							if (!eventDetails.isCanceled) {
-								store.update({
-									activeTriggerId: null,
-									activeTriggerElement: null,
-								} as Partial<State>);
-							}
+		if (lostActiveTriggerId) {
+			if (closeOnActiveTriggerUnmount) {
+				// Defer so a same-tick replacement trigger with the same id can register first.
+				queueMicrotask(() => {
+					if (
+						store.select('open') &&
+						store.select('activeTriggerId') === lostActiveTriggerId &&
+						!store.context.triggerElements.getById(lostActiveTriggerId)
+					) {
+						const eventDetails = createChangeEventDetails(REASONS.none);
+						store.setOpen(false, eventDetails);
+						// If closing is canceled, keep the previous active trigger ownership for the
+						// still-open popup instead of claiming another trigger implicitly.
+						if (!eventDetails.isCanceled) {
+							store.update({
+								activeTriggerId: null,
+								activeTriggerElement: null,
+							});
 						}
-					});
-				}
+					}
+				});
 			}
-		},
-		[open, store, reactiveTriggerCount, closeOnActiveTriggerUnmount],
-		subSlot(slot, 'e'),
-	);
+		}
+	}, [
+		open,
+		store,
+		reactiveTriggerCount,
+		activeTriggerId,
+		reactiveActiveTriggerElement,
+		closeOnActiveTriggerUnmount,
+	]);
 }
 
+/**
+ * Manages the mounted state of the popup.
+ * Sets up the transition status listeners and handles unmounting when needed.
+ * Updates the `mounted`, `transitionStatus`, and `preventUnmountingOnClose` states in the store.
+ *
+ * @param open Whether the popup is open.
+ * @param store The Store instance managing the popup state.
+ * @param onUnmount Optional callback to be called when the popup is unmounted.
+ * @param animateInitialOpen Whether a popup that mounts already open should still play its enter
+ *   transition. Defaults to `false`, so content that was open on the first render (a `defaultOpen`
+ *   popup on page load, SSR'd markup) appears without animating. Opt in for popups whose subtree
+ *   only mounts in response to something the user did, such as a submenu inside a menu popup.
+ *
+ * @returns A function to forcibly unmount the popup.
+ */
 export function useOpenStateTransitions<State extends PopupStoreState<unknown>>(
 	open: boolean,
 	store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>,
-	onUnmount: (() => void) | undefined,
-	slot: symbol | undefined,
+	onUnmount?: () => void,
+	animateInitialOpen?: boolean,
 ) {
 	const { mounted, setMounted, transitionStatus } = useTransitionStatus(
 		open,
-		undefined,
-		undefined,
-		subSlot(slot, 'ts'),
-	);
-	const preventUnmountingOnClose = store.useState(
-		'preventUnmountingOnClose',
-		subSlot(slot, 'puoc'),
+		false,
+		false,
+		animateInitialOpen,
 	);
+	const preventUnmountingOnClose = store.useState('preventUnmountingOnClose');
+	// Opening starts a new close cycle. Clear during render so the close-completion hook below
+	// reads the synchronized value on the same pass.
 	const syncedPreventUnmountingOnClose = open ? false : preventUnmountingOnClose;
 
-	store.useSyncedValues(
-		{
-			mounted,
-			transitionStatus,
-			preventUnmountingOnClose: syncedPreventUnmountingOnClose,
-		} as Partial<State>,
-		subSlot(slot, 'sync'),
-	);
-
-	const forceUnmount = useStableCallback(
-		() => {
-			setMounted(false);
-			store.update({
-				activeTriggerId: null,
-				activeTriggerElement: null,
-				mounted: false,
-				preventUnmountingOnClose: false,
-			} as Partial<State>);
-			onUnmount?.();
-			store.context.onOpenChangeComplete?.(false);
+	store.useSyncedValues({
+		mounted,
+		transitionStatus,
+		preventUnmountingOnClose: syncedPreventUnmountingOnClose,
+	});
+
+	const forceUnmount = useStableCallback(() => {
+		setMounted(false);
+		store.update({
+			activeTriggerId: null,
+			activeTriggerElement: null,
+			mounted: false,
+			preventUnmountingOnClose: false,
+		});
+		onUnmount?.();
+		store.context.onOpenChangeComplete?.(false);
+	});
+
+	useOpenChangeComplete({
+		enabled: mounted && !open && !syncedPreventUnmountingOnClose,
+		open,
+		ref: store.context.popupRef,
+		onComplete() {
+			if (!open) {
+				forceUnmount();
+			}
 		},
-		subSlot(slot, 'fu'),
-	);
-
-	useOpenChangeComplete(
-		{
-			enabled: mounted && !open && !syncedPreventUnmountingOnClose,
-			open,
-			ref: store.context.popupRef,
-			onComplete() {
-				if (!open) {
-					forceUnmount();
-				}
-			},
-		},
-		subSlot(slot, 'occ'),
-	);
+	});
 
 	return { forceUnmount, transitionStatus };
 }
 
-export function usePopupInteractionProps<State extends PopupStoreState<unknown>>(
+type PopupInteractionPropKey = 'activeTriggerProps' | 'inactiveTriggerProps' | 'popupProps';
+
+export function usePopupInteractionProps<
+	State extends PopupStoreState<unknown>,
+	const Key extends keyof State,
+>(
 	store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>,
-	statePart: Partial<State>,
-	slot: symbol | undefined,
+	statePart: Pick<State, Key | PopupInteractionPropKey>,
 ) {
-	store.useSyncedValues(statePart, subSlot(slot, 'sync'));
+	store.useSyncedValues(statePart);
 
-	useLayoutEffect(
+	useIsoLayoutEffect(
 		() => () => {
 			store.update({
 				activeTriggerProps: EMPTY_OBJECT,
 				inactiveTriggerProps: EMPTY_OBJECT,
 				popupProps: EMPTY_OBJECT,
-			} as unknown as Partial<State>);
+			});
 		},
 		[store],
-		subSlot(slot, 'e'),
 	);
 }
 
 export function usePopupRootSync<
-	State extends PopupStoreState<unknown> & { openMethod: InteractionType | null },
->(
-	store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>,
-	open: boolean,
-	slot: symbol | undefined,
-) {
-	useLayoutEffect(
-		() => {
-			if (!open && store.state.openMethod !== null) {
-				store.set('openMethod', null);
-			}
-		},
-		[open, store],
-		subSlot(slot, 'e1'),
-	);
+	State extends PopupStoreState<unknown> & {
+		openMethod: InteractionType | null;
+	},
+>(store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>, open: boolean) {
+	useIsoLayoutEffect(() => {
+		if (!open && store.state.openMethod !== null) {
+			store.set('openMethod', null);
+		}
+	}, [open, store]);
 
-	useLayoutEffect(
+	useIsoLayoutEffect(
 		() => () => {
 			if (store.state.openMethod !== null) {
 				store.set('openMethod', null);
 			}
 		},
 		[store],
-		subSlot(slot, 'e2'),
 	);
 }