@base-ui/react 1.7.0 → 1.8.0

package/utils/popups/popupStoreUtils.d.mts

@@ -1,9 +1,10 @@
 import * as React from 'react';
 import { ReactStore } from '@base-ui/utils/store';
 import type { InteractionType } from '@base-ui/utils/useEnhancedClickHandler';
+import { type SyncedFloatingRootContextStore } from "../../floating-ui-react/hooks/useSyncedFloatingRootContext.mjs";
 import { type BaseUIChangeEventDetails } from "../../internals/createBaseUIEventDetails.mjs";
 import { REASONS } from "../../internals/reasons.mjs";
-import { PopupStoreState, PopupStoreContext, popupStoreSelectors, PopupStoreSelectors, PopupTriggerDataStore } from "./store.mjs";
+import { PopupStoreState, PopupStoreContext, popupStoreSelectors, PopupTriggerDataStore } from "./store.mjs";
 export declare const FOCUSABLE_POPUP_PROPS: {
   tabIndex: number;
   "data-base-ui-focusable": string;
@@ -14,7 +15,7 @@ export declare const FOCUSABLE_POPUP_PROPS: {
  * specifically; iOS handles this automatically). Otherwise it falls back to the default behavior.
  */
 export declare function createDefaultInitialFocus(popupRef: React.RefObject<HTMLElement | null>): (interactionType: InteractionType) => true | HTMLElement | null;
-type PopupStoreWithOpen<State extends PopupStoreState<unknown>, SetOpenEventDetails extends BaseUIChangeEventDetails<string>> = ReactStore<State, PopupStoreContext<never>, PopupStoreSelectors> & {
+type PopupStoreWithOpen<State extends PopupStoreState<unknown>, SetOpenEventDetails extends BaseUIChangeEventDetails<string>> = PopupTriggerDataStore<State> & Pick<SyncedFloatingRootContextStore<State>, 'useSyncedValue'> & {
   setOpen(open: boolean, eventDetails: SetOpenEventDetails): void;
 };
 /**
@@ -53,12 +54,23 @@ export declare function PopupHandleAttachment<Store>({
   store: Store;
 }): null;
 /**
- * Returns a callback ref that registers/unregisters the trigger element in the store.
+ * 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 declare function useTriggerRegistration<State extends PopupStoreState<unknown>>(id: string | undefined, store: PopupTriggerDataStore<State>): (element: Element | null) => void;
-export declare function setPopupOpenState(state: Partial<PopupStoreState<unknown>>, open: boolean, trigger: Element | undefined, preventUnmountOnClose?: boolean): void;
+type PopupOpenState = Pick<PopupStoreState<unknown>, 'open' | 'preventUnmountingOnClose' | 'activeTriggerId' | 'activeTriggerElement'>;
+export declare function createPopupOpenState(state: PopupOpenState, open: boolean, trigger: Element | undefined, preventUnmountOnClose?: boolean): PopupOpenState;
 export declare function attachPreventUnmountOnClose(eventDetails: {
   preventUnmountOnClose(): void;
 }): () => boolean;
@@ -72,15 +84,15 @@ export declare function attachPreventUnmountOnClose(eventDetails: {
  */
 export declare function applyPopupOpenChange<State extends PopupStoreState<unknown> & {
   instantType?: 'delay' | 'dismiss' | 'focus' | undefined;
-}, EventDetails extends BaseUIChangeEventDetails<string>>(store: {
+}, EventDetails extends BaseUIChangeEventDetails<string>, ExtraKey extends keyof State = never>(store: {
   readonly context: Pick<PopupStoreContext<EventDetails>, 'onOpenChange'>;
-  readonly state: Pick<PopupStoreState<unknown>, 'floatingRootContext'>;
-  update(state: Partial<State>): void;
+  readonly state: State;
+  update<const Key extends keyof State>(state: Pick<State, Key>): void;
 }, nextOpen: boolean, eventDetails: EventDetails & {
   preventUnmountOnClose(): void;
 }, options?: {
   onBeforeDispatch?: (() => void) | undefined;
-  extraState?: Partial<State> | undefined;
+  extraState?: Pick<State, ExtraKey> | undefined;
 }): void;
 /**
  * Sets up trigger data forwarding to the store.
@@ -90,7 +102,7 @@ export declare function applyPopupOpenChange<State extends PopupStoreState<unkno
  * @param store The Store instance managing the popup state.
  * @param stateUpdates An object with state updates to apply when the trigger is active.
  */
-export declare function useTriggerDataForwarding<State extends PopupStoreState<unknown>>(triggerId: string | undefined, triggerElementRef: React.RefObject<Element | null>, store: PopupTriggerDataStore<State>, stateUpdates: Omit<Partial<State>, 'activeTriggerId' | 'activeTriggerElement'>): {
+export declare function useTriggerDataForwarding<State extends PopupStoreState<unknown>, const Key extends keyof Omit<State, 'activeTriggerId' | 'activeTriggerElement'>>(triggerId: string | undefined, triggerElementRef: React.RefObject<Element | null>, store: PopupTriggerDataStore<State>, stateUpdates: Pick<State, Key>): {
   registerTrigger: (element: Element | null) => void;
   isMountedByThisTrigger: boolean;
 };
@@ -130,14 +142,19 @@ export declare function useImplicitActiveTrigger<State extends PopupStoreState<u
  * @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 declare function useOpenStateTransitions<State extends PopupStoreState<unknown>>(open: boolean, store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>, onUnmount?: () => void): {
+export declare function useOpenStateTransitions<State extends PopupStoreState<unknown>>(open: boolean, store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>, onUnmount?: () => void, animateInitialOpen?: boolean): {
   forceUnmount: () => void;
   transitionStatus: import("../../internals/useTransitionStatus.mjs").TransitionStatus;
 };
-export declare function usePopupInteractionProps<State extends PopupStoreState<unknown>>(store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>, statePart: Partial<State> & Pick<State, 'activeTriggerProps' | 'inactiveTriggerProps' | 'popupProps'>): void;
+type PopupInteractionPropKey = 'activeTriggerProps' | 'inactiveTriggerProps' | 'popupProps';
+export declare function usePopupInteractionProps<State extends PopupStoreState<unknown>, const Key extends keyof State>(store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>, statePart: Pick<State, Key | PopupInteractionPropKey>): void;
 export declare function usePopupRootSync<State extends PopupStoreState<unknown> & {
   openMethod: InteractionType | null;
 }>(store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>, open: boolean): void;

package/utils/popups/popupStoreUtils.d.ts

@@ -1,9 +1,10 @@
 import * as React from 'react';
 import { ReactStore } from '@base-ui/utils/store';
 import type { InteractionType } from '@base-ui/utils/useEnhancedClickHandler';
+import { type SyncedFloatingRootContextStore } from "../../floating-ui-react/hooks/useSyncedFloatingRootContext.js";
 import { type BaseUIChangeEventDetails } from "../../internals/createBaseUIEventDetails.js";
 import { REASONS } from "../../internals/reasons.js";
-import { PopupStoreState, PopupStoreContext, popupStoreSelectors, PopupStoreSelectors, PopupTriggerDataStore } from "./store.js";
+import { PopupStoreState, PopupStoreContext, popupStoreSelectors, PopupTriggerDataStore } from "./store.js";
 export declare const FOCUSABLE_POPUP_PROPS: {
   tabIndex: number;
   "data-base-ui-focusable": string;
@@ -14,7 +15,7 @@ export declare const FOCUSABLE_POPUP_PROPS: {
  * specifically; iOS handles this automatically). Otherwise it falls back to the default behavior.
  */
 export declare function createDefaultInitialFocus(popupRef: React.RefObject<HTMLElement | null>): (interactionType: InteractionType) => true | HTMLElement | null;
-type PopupStoreWithOpen<State extends PopupStoreState<unknown>, SetOpenEventDetails extends BaseUIChangeEventDetails<string>> = ReactStore<State, PopupStoreContext<never>, PopupStoreSelectors> & {
+type PopupStoreWithOpen<State extends PopupStoreState<unknown>, SetOpenEventDetails extends BaseUIChangeEventDetails<string>> = PopupTriggerDataStore<State> & Pick<SyncedFloatingRootContextStore<State>, 'useSyncedValue'> & {
   setOpen(open: boolean, eventDetails: SetOpenEventDetails): void;
 };
 /**
@@ -53,12 +54,23 @@ export declare function PopupHandleAttachment<Store>({
   store: Store;
 }): null;
 /**
- * Returns a callback ref that registers/unregisters the trigger element in the store.
+ * 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 declare function useTriggerRegistration<State extends PopupStoreState<unknown>>(id: string | undefined, store: PopupTriggerDataStore<State>): (element: Element | null) => void;
-export declare function setPopupOpenState(state: Partial<PopupStoreState<unknown>>, open: boolean, trigger: Element | undefined, preventUnmountOnClose?: boolean): void;
+type PopupOpenState = Pick<PopupStoreState<unknown>, 'open' | 'preventUnmountingOnClose' | 'activeTriggerId' | 'activeTriggerElement'>;
+export declare function createPopupOpenState(state: PopupOpenState, open: boolean, trigger: Element | undefined, preventUnmountOnClose?: boolean): PopupOpenState;
 export declare function attachPreventUnmountOnClose(eventDetails: {
   preventUnmountOnClose(): void;
 }): () => boolean;
@@ -72,15 +84,15 @@ export declare function attachPreventUnmountOnClose(eventDetails: {
  */
 export declare function applyPopupOpenChange<State extends PopupStoreState<unknown> & {
   instantType?: 'delay' | 'dismiss' | 'focus' | undefined;
-}, EventDetails extends BaseUIChangeEventDetails<string>>(store: {
+}, EventDetails extends BaseUIChangeEventDetails<string>, ExtraKey extends keyof State = never>(store: {
   readonly context: Pick<PopupStoreContext<EventDetails>, 'onOpenChange'>;
-  readonly state: Pick<PopupStoreState<unknown>, 'floatingRootContext'>;
-  update(state: Partial<State>): void;
+  readonly state: State;
+  update<const Key extends keyof State>(state: Pick<State, Key>): void;
 }, nextOpen: boolean, eventDetails: EventDetails & {
   preventUnmountOnClose(): void;
 }, options?: {
   onBeforeDispatch?: (() => void) | undefined;
-  extraState?: Partial<State> | undefined;
+  extraState?: Pick<State, ExtraKey> | undefined;
 }): void;
 /**
  * Sets up trigger data forwarding to the store.
@@ -90,7 +102,7 @@ export declare function applyPopupOpenChange<State extends PopupStoreState<unkno
  * @param store The Store instance managing the popup state.
  * @param stateUpdates An object with state updates to apply when the trigger is active.
  */
-export declare function useTriggerDataForwarding<State extends PopupStoreState<unknown>>(triggerId: string | undefined, triggerElementRef: React.RefObject<Element | null>, store: PopupTriggerDataStore<State>, stateUpdates: Omit<Partial<State>, 'activeTriggerId' | 'activeTriggerElement'>): {
+export declare function useTriggerDataForwarding<State extends PopupStoreState<unknown>, const Key extends keyof Omit<State, 'activeTriggerId' | 'activeTriggerElement'>>(triggerId: string | undefined, triggerElementRef: React.RefObject<Element | null>, store: PopupTriggerDataStore<State>, stateUpdates: Pick<State, Key>): {
   registerTrigger: (element: Element | null) => void;
   isMountedByThisTrigger: boolean;
 };
@@ -130,14 +142,19 @@ export declare function useImplicitActiveTrigger<State extends PopupStoreState<u
  * @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 declare function useOpenStateTransitions<State extends PopupStoreState<unknown>>(open: boolean, store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>, onUnmount?: () => void): {
+export declare function useOpenStateTransitions<State extends PopupStoreState<unknown>>(open: boolean, store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>, onUnmount?: () => void, animateInitialOpen?: boolean): {
   forceUnmount: () => void;
   transitionStatus: import("../../internals/useTransitionStatus.js").TransitionStatus;
 };
-export declare function usePopupInteractionProps<State extends PopupStoreState<unknown>>(store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>, statePart: Partial<State> & Pick<State, 'activeTriggerProps' | 'inactiveTriggerProps' | 'popupProps'>): void;
+type PopupInteractionPropKey = 'activeTriggerProps' | 'inactiveTriggerProps' | 'popupProps';
+export declare function usePopupInteractionProps<State extends PopupStoreState<unknown>, const Key extends keyof State>(store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>, statePart: Pick<State, Key | PopupInteractionPropKey>): void;
 export declare function usePopupRootSync<State extends PopupStoreState<unknown> & {
   openMethod: InteractionType | null;
 }>(store: ReactStore<State, PopupStoreContext<never>, typeof popupStoreSelectors>, open: boolean): void;

package/utils/popups/popupStoreUtils.js

@@ -10,7 +10,7 @@ exports.PopupHandleAttachment = PopupHandleAttachment;
 exports.applyPopupOpenChange = applyPopupOpenChange;
 exports.attachPreventUnmountOnClose = attachPreventUnmountOnClose;
 exports.createDefaultInitialFocus = createDefaultInitialFocus;
-exports.setPopupOpenState = setPopupOpenState;
+exports.createPopupOpenState = createPopupOpenState;
 exports.useImplicitActiveTrigger = useImplicitActiveTrigger;
 exports.useOpenStateTransitions = useOpenStateTransitions;
 exports.usePopupInteractionProps = usePopupInteractionProps;
@@ -95,61 +95,79 @@ function PopupHandleAttachment({
   }, [handle, store]);
   return null;
 }
+function syncTriggerCount(store) {
+  const triggerCount = store.context.triggerElements.size;
+  if (store.select('open') && store.state.triggerCount !== triggerCount) {
+    store.set('triggerCount', triggerCount);
+  }
+}
 
 /**
- * Returns a callback ref that registers/unregisters the trigger element in the store.
+ * 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.
  */
 function useTriggerRegistration(id, store) {
-  // Keep track of the currently registered element to unregister it on unmount or id change.
-  const registeredElementIdRef = React.useRef(null);
-  const registeredElementRef = React.useRef(null);
-  return React.useCallback(element => {
-    if (id === undefined) {
-      return;
-    }
-    let shouldSyncTriggerCount = false;
-    if (registeredElementIdRef.current !== null) {
-      const registeredId = registeredElementIdRef.current;
-      const registeredElement = registeredElementRef.current;
-      const currentElement = store.context.triggerElements.getById(registeredId);
-      if (registeredElement && currentElement === registeredElement) {
-        store.context.triggerElements.delete(registeredId);
-        shouldSyncTriggerCount = true;
+  const registrationRef = React.useRef(null);
+  return (0, _useStableCallback.useStableCallback)(element => {
+    const registration = registrationRef.current;
+    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;
+      }
+      registrationRef.current = null;
+      const registeredStore = registration.store;
+      if (registeredStore.context.triggerElements.getById(registration.id) === registration.element) {
+        registeredStore.context.triggerElements.delete(registration.id);
+        syncTriggerCount(registeredStore);
       }
-      registeredElementIdRef.current = null;
-      registeredElementRef.current = null;
     }
-    if (element !== null) {
-      registeredElementIdRef.current = id;
-      registeredElementRef.current = element;
+    if (element !== null && id !== undefined) {
+      registrationRef.current = {
+        store,
+        id,
+        element
+      };
       store.context.triggerElements.add(id, element);
-      shouldSyncTriggerCount = true;
-    }
-    if (shouldSyncTriggerCount) {
-      const triggerCount = store.context.triggerElements.size;
-      if (store.select('open') && store.state.triggerCount !== triggerCount) {
-        store.set('triggerCount', triggerCount);
-      }
+      syncTriggerCount(store);
     }
-  }, [store, id]);
+  });
 }
-function setPopupOpenState(state, open, trigger, preventUnmountOnClose = false) {
+function createPopupOpenState(state, open, trigger, preventUnmountOnClose = false) {
+  let preventUnmountingOnClose = state.preventUnmountingOnClose;
   if (open) {
     // Opening starts a new close cycle, so clear any previous request to keep the popup mounted.
-    state.preventUnmountingOnClose = false;
+    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
+  };
 }
 function attachPreventUnmountOnClose(eventDetails) {
   let preventUnmountOnClose = false;
@@ -180,11 +198,10 @@ function applyPopupOpenChange(store, nextOpen, eventDetails, options = {}) {
   options.onBeforeDispatch?.();
   store.state.floatingRootContext.dispatchOpenChange(nextOpen, eventDetails);
   const changeState = () => {
-    // Spread `extraState` first so `open` always reflects `nextOpen`, keeping it in
-    // sync with the value already passed to `dispatchOpenChange`/`setPopupOpenState`.
+    const popupOpenState = createPopupOpenState(store.state, nextOpen, eventDetails.trigger, shouldPreventUnmountOnClose());
     const updatedState = {
       ...options.extraState,
-      open: nextOpen
+      ...popupOpenState
     };
     if (isFocusOpen) {
       updatedState.instantType = 'focus';
@@ -193,7 +210,6 @@ function applyPopupOpenChange(store, nextOpen, eventDetails, options = {}) {
     } else if (isHover) {
       updatedState.instantType = undefined;
     }
-    setPopupOpenState(updatedState, nextOpen, eventDetails.trigger, shouldPreventUnmountOnClose());
     store.update(updatedState);
   };
   if (isHover) {
@@ -223,41 +239,48 @@ function useTriggerDataForwarding(triggerId, triggerElementRef, store, stateUpda
     const open = store.select('open');
     const activeTriggerId = store.select('activeTriggerId');
     if (activeTriggerId === triggerId) {
-      store.update({
+      const changes = {
         activeTriggerElement: element,
         ...(open ? stateUpdates : null)
-      });
+      };
+      store.update(changes);
       return;
     }
     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.
-      store.update({
-        activeTriggerId: triggerId,
+      const changes = {
+        activeTriggerId: triggerId ?? null,
         activeTriggerElement: element,
         ...stateUpdates
-      });
+      };
+      store.update(changes);
     }
   });
 
-  // Intentionally NOT stable. Its identity is derived from `baseRegisterTrigger`, which is keyed on
-  // `[store, id]`, so when a handle-backed trigger's store pointer swaps the merged ref re-fires —
-  // unregistering from the previous store and registering into the new one. This lets a detached
-  // trigger follow its handle's currently-attached store across attach/detach/remount. (A stable
-  // callback would keep its identity and never re-fire on a store swap.)
-  const registerTrigger = React.useCallback(element => {
+  // Stable, so the merged ref on the rendered element keeps its identity for the trigger's whole
+  // lifetime.
+  const registerTrigger = (0, _useStableCallback.useStableCallback)(element => {
     baseRegisterTrigger(element);
     if (element) {
       applyTriggerData(element);
     }
-  }, [baseRegisterTrigger, applyTriggerData]);
+  });
+
+  // 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.
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    registerTrigger(triggerElementRef.current);
+    return () => registerTrigger(null);
+  }, [registerTrigger, triggerElementRef, store, triggerId]);
   (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
     if (isMountedByThisTrigger) {
-      store.update({
+      const changes = {
         activeTriggerElement: triggerElementRef.current,
         ...stateUpdates
-      });
+      };
+      store.update(changes);
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [isMountedByThisTrigger, store, triggerElementRef, ...Object.values(stateUpdates)]);
@@ -389,15 +412,19 @@ function useImplicitActiveTrigger(store, options = {}) {
  * @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.
  */
-function useOpenStateTransitions(open, store, onUnmount) {
+function useOpenStateTransitions(open, store, onUnmount, animateInitialOpen) {
   const {
     mounted,
     setMounted,
     transitionStatus
-  } = (0, _useTransitionStatus.useTransitionStatus)(open);
+  } = (0, _useTransitionStatus.useTransitionStatus)(open, 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.

package/utils/popups/popupStoreUtils.mjs

@@ -77,61 +77,79 @@ export function PopupHandleAttachment({
   }, [handle, store]);
   return null;
 }
+function syncTriggerCount(store) {
+  const triggerCount = store.context.triggerElements.size;
+  if (store.select('open') && store.state.triggerCount !== triggerCount) {
+    store.set('triggerCount', triggerCount);
+  }
+}
 
 /**
- * Returns a callback ref that registers/unregisters the trigger element in the store.
+ * 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(id, store) {
-  // Keep track of the currently registered element to unregister it on unmount or id change.
-  const registeredElementIdRef = React.useRef(null);
-  const registeredElementRef = React.useRef(null);
-  return React.useCallback(element => {
-    if (id === undefined) {
-      return;
-    }
-    let shouldSyncTriggerCount = false;
-    if (registeredElementIdRef.current !== null) {
-      const registeredId = registeredElementIdRef.current;
-      const registeredElement = registeredElementRef.current;
-      const currentElement = store.context.triggerElements.getById(registeredId);
-      if (registeredElement && currentElement === registeredElement) {
-        store.context.triggerElements.delete(registeredId);
-        shouldSyncTriggerCount = true;
+  const registrationRef = React.useRef(null);
+  return useStableCallback(element => {
+    const registration = registrationRef.current;
+    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;
+      }
+      registrationRef.current = null;
+      const registeredStore = registration.store;
+      if (registeredStore.context.triggerElements.getById(registration.id) === registration.element) {
+        registeredStore.context.triggerElements.delete(registration.id);
+        syncTriggerCount(registeredStore);
       }
-      registeredElementIdRef.current = null;
-      registeredElementRef.current = null;
     }
-    if (element !== null) {
-      registeredElementIdRef.current = id;
-      registeredElementRef.current = element;
+    if (element !== null && id !== undefined) {
+      registrationRef.current = {
+        store,
+        id,
+        element
+      };
       store.context.triggerElements.add(id, element);
-      shouldSyncTriggerCount = true;
-    }
-    if (shouldSyncTriggerCount) {
-      const triggerCount = store.context.triggerElements.size;
-      if (store.select('open') && store.state.triggerCount !== triggerCount) {
-        store.set('triggerCount', triggerCount);
-      }
+      syncTriggerCount(store);
     }
-  }, [store, id]);
+  });
 }
-export function setPopupOpenState(state, open, trigger, preventUnmountOnClose = false) {
+export function createPopupOpenState(state, open, trigger, preventUnmountOnClose = false) {
+  let preventUnmountingOnClose = state.preventUnmountingOnClose;
   if (open) {
     // Opening starts a new close cycle, so clear any previous request to keep the popup mounted.
-    state.preventUnmountingOnClose = false;
+    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) {
   let preventUnmountOnClose = false;
@@ -162,11 +180,10 @@ export function applyPopupOpenChange(store, nextOpen, eventDetails, options = {}
   options.onBeforeDispatch?.();
   store.state.floatingRootContext.dispatchOpenChange(nextOpen, eventDetails);
   const changeState = () => {
-    // Spread `extraState` first so `open` always reflects `nextOpen`, keeping it in
-    // sync with the value already passed to `dispatchOpenChange`/`setPopupOpenState`.
+    const popupOpenState = createPopupOpenState(store.state, nextOpen, eventDetails.trigger, shouldPreventUnmountOnClose());
     const updatedState = {
       ...options.extraState,
-      open: nextOpen
+      ...popupOpenState
     };
     if (isFocusOpen) {
       updatedState.instantType = 'focus';
@@ -175,7 +192,6 @@ export function applyPopupOpenChange(store, nextOpen, eventDetails, options = {}
     } else if (isHover) {
       updatedState.instantType = undefined;
     }
-    setPopupOpenState(updatedState, nextOpen, eventDetails.trigger, shouldPreventUnmountOnClose());
     store.update(updatedState);
   };
   if (isHover) {
@@ -205,41 +221,48 @@ export function useTriggerDataForwarding(triggerId, triggerElementRef, store, st
     const open = store.select('open');
     const activeTriggerId = store.select('activeTriggerId');
     if (activeTriggerId === triggerId) {
-      store.update({
+      const changes = {
         activeTriggerElement: element,
         ...(open ? stateUpdates : null)
-      });
+      };
+      store.update(changes);
       return;
     }
     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.
-      store.update({
-        activeTriggerId: triggerId,
+      const changes = {
+        activeTriggerId: triggerId ?? null,
         activeTriggerElement: element,
         ...stateUpdates
-      });
+      };
+      store.update(changes);
     }
   });
 
-  // Intentionally NOT stable. Its identity is derived from `baseRegisterTrigger`, which is keyed on
-  // `[store, id]`, so when a handle-backed trigger's store pointer swaps the merged ref re-fires —
-  // unregistering from the previous store and registering into the new one. This lets a detached
-  // trigger follow its handle's currently-attached store across attach/detach/remount. (A stable
-  // callback would keep its identity and never re-fire on a store swap.)
-  const registerTrigger = React.useCallback(element => {
+  // Stable, so the merged ref on the rendered element keeps its identity for the trigger's whole
+  // lifetime.
+  const registerTrigger = useStableCallback(element => {
     baseRegisterTrigger(element);
     if (element) {
       applyTriggerData(element);
     }
-  }, [baseRegisterTrigger, applyTriggerData]);
+  });
+
+  // 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) {
-      store.update({
+      const changes = {
         activeTriggerElement: triggerElementRef.current,
         ...stateUpdates
-      });
+      };
+      store.update(changes);
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [isMountedByThisTrigger, store, triggerElementRef, ...Object.values(stateUpdates)]);
@@ -371,15 +394,19 @@ export function useImplicitActiveTrigger(store, options = {}) {
  * @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(open, store, onUnmount) {
+export function useOpenStateTransitions(open, store, onUnmount, animateInitialOpen) {
   const {
     mounted,
     setMounted,
     transitionStatus
-  } = useTransitionStatus(open);
+  } = useTransitionStatus(open, 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.