@base-ui/react 1.6.0 → 1.7.0

package/utils/popupStateMapping.d.ts

@@ -1,3 +1,4 @@
+import type { TransitionStatus } from "../internals/useTransitionStatus.js";
 export declare enum CommonPopupDataAttributes {
   /**
    * Present when the popup is open.
@@ -8,7 +9,7 @@ export declare enum CommonPopupDataAttributes {
    */
   closed = "data-closed",
   /**
-   * Present when the popup is animating in.
+   * Present when the popup begins animating in.
    */
   startingStyle = "data-starting-style",
   /**
@@ -42,22 +43,33 @@ export declare enum CommonTriggerDataAttributes {
 }
 export declare const triggerOpenStateMapping: {
   open(value: boolean): {
-    "data-popup-open": string;
+    'data-popup-open': string;
   } | null;
 };
 export declare const pressableTriggerOpenStateMapping: {
   open(value: boolean): {
-    "data-popup-open": string;
-    "data-pressed": string;
+    'data-popup-open': string;
+    'data-pressed': string;
   } | null;
 };
 export declare const popupStateMapping: {
   open(value: boolean): {
-    "data-open": string;
+    'data-open': string;
   } | {
-    "data-closed": string;
+    'data-closed': string;
   };
   anchorHidden(value: boolean): {
-    "data-anchor-hidden": string;
+    'data-anchor-hidden': string;
+  } | null;
+};
+export declare const popupTransitionStateMapping: {
+  transitionStatus(value: TransitionStatus): Record<string, string> | null;
+  open(value: boolean): {
+    'data-open': string;
+  } | {
+    'data-closed': string;
+  };
+  anchorHidden(value: boolean): {
+    'data-anchor-hidden': string;
   } | null;
 };

package/utils/popupStateMapping.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.triggerOpenStateMapping = exports.pressableTriggerOpenStateMapping = exports.popupStateMapping = exports.CommonTriggerDataAttributes = exports.CommonPopupDataAttributes = void 0;
+exports.triggerOpenStateMapping = exports.pressableTriggerOpenStateMapping = exports.popupTransitionStateMapping = exports.popupStateMapping = exports.CommonTriggerDataAttributes = exports.CommonPopupDataAttributes = void 0;
 var _stateAttributesMapping = require("../internals/stateAttributesMapping");
 let CommonPopupDataAttributes = exports.CommonPopupDataAttributes = function (CommonPopupDataAttributes) {
   /**
@@ -15,7 +15,7 @@ let CommonPopupDataAttributes = exports.CommonPopupDataAttributes = function (Co
    */
   CommonPopupDataAttributes["closed"] = "data-closed";
   /**
-   * Present when the popup is animating in.
+   * Present when the popup begins animating in.
    */
   CommonPopupDataAttributes[CommonPopupDataAttributes["startingStyle"] = _stateAttributesMapping.TransitionStatusDataAttributes.startingStyle] = "startingStyle";
   /**
@@ -48,22 +48,23 @@ let CommonTriggerDataAttributes = exports.CommonTriggerDataAttributes = /*#__PUR
    */
   CommonTriggerDataAttributes["pressed"] = "data-pressed";
   return CommonTriggerDataAttributes;
-}({});
+}({}); // Literal keys (instead of enum member references) keep the docs-only enums above
+// tree-shakeable: a runtime reference would retain the whole enum IIFE in every bundle.
 const TRIGGER_HOOK = {
-  [CommonTriggerDataAttributes.popupOpen]: ''
+  'data-popup-open': ''
 };
 const PRESSABLE_TRIGGER_HOOK = {
-  [CommonTriggerDataAttributes.popupOpen]: '',
-  [CommonTriggerDataAttributes.pressed]: ''
+  'data-popup-open': '',
+  'data-pressed': ''
 };
 const POPUP_OPEN_HOOK = {
-  [CommonPopupDataAttributes.open]: ''
+  'data-open': ''
 };
 const POPUP_CLOSED_HOOK = {
-  [CommonPopupDataAttributes.closed]: ''
+  'data-closed': ''
 };
 const ANCHOR_HIDDEN_HOOK = {
-  [CommonPopupDataAttributes.anchorHidden]: ''
+  'data-anchor-hidden': ''
 };
 const triggerOpenStateMapping = exports.triggerOpenStateMapping = {
   open(value) {
@@ -94,4 +95,8 @@ const popupStateMapping = exports.popupStateMapping = {
     }
     return null;
   }
+};
+const popupTransitionStateMapping = exports.popupTransitionStateMapping = {
+  ...popupStateMapping,
+  ..._stateAttributesMapping.transitionStatusMapping
 };

package/utils/popupStateMapping.mjs

@@ -1,4 +1,4 @@
-import { TransitionStatusDataAttributes } from "../internals/stateAttributesMapping.mjs";
+import { TransitionStatusDataAttributes, transitionStatusMapping } from "../internals/stateAttributesMapping.mjs";
 export let CommonPopupDataAttributes = function (CommonPopupDataAttributes) {
   /**
    * Present when the popup is open.
@@ -9,7 +9,7 @@ export let CommonPopupDataAttributes = function (CommonPopupDataAttributes) {
    */
   CommonPopupDataAttributes["closed"] = "data-closed";
   /**
-   * Present when the popup is animating in.
+   * Present when the popup begins animating in.
    */
   CommonPopupDataAttributes[CommonPopupDataAttributes["startingStyle"] = TransitionStatusDataAttributes.startingStyle] = "startingStyle";
   /**
@@ -43,21 +43,24 @@ export let CommonTriggerDataAttributes = /*#__PURE__*/function (CommonTriggerDat
   CommonTriggerDataAttributes["pressed"] = "data-pressed";
   return CommonTriggerDataAttributes;
 }({});
+
+// Literal keys (instead of enum member references) keep the docs-only enums above
+// tree-shakeable: a runtime reference would retain the whole enum IIFE in every bundle.
 const TRIGGER_HOOK = {
-  [CommonTriggerDataAttributes.popupOpen]: ''
+  'data-popup-open': ''
 };
 const PRESSABLE_TRIGGER_HOOK = {
-  [CommonTriggerDataAttributes.popupOpen]: '',
-  [CommonTriggerDataAttributes.pressed]: ''
+  'data-popup-open': '',
+  'data-pressed': ''
 };
 const POPUP_OPEN_HOOK = {
-  [CommonPopupDataAttributes.open]: ''
+  'data-open': ''
 };
 const POPUP_CLOSED_HOOK = {
-  [CommonPopupDataAttributes.closed]: ''
+  'data-closed': ''
 };
 const ANCHOR_HIDDEN_HOOK = {
-  [CommonPopupDataAttributes.anchorHidden]: ''
+  'data-anchor-hidden': ''
 };
 export const triggerOpenStateMapping = {
   open(value) {
@@ -88,4 +91,8 @@ export const popupStateMapping = {
     }
     return null;
   }
+};
+export const popupTransitionStateMapping = {
+  ...popupStateMapping,
+  ...transitionStatusMapping
 };

package/utils/popups/index.d.mts

@@ -1,4 +1,6 @@
 export * from "./inlineRect.mjs";
+export * from "./popupHandle.mjs";
 export * from "./popupStoreUtils.mjs";
 export * from "./popupTriggerMap.mjs";
-export * from "./store.mjs";
+export * from "./store.mjs";
+export * from "./usePopupHandleStore.mjs";

package/utils/popups/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./inlineRect.js";
+export * from "./popupHandle.js";
 export * from "./popupStoreUtils.js";
 export * from "./popupTriggerMap.js";
-export * from "./store.js";
+export * from "./store.js";
+export * from "./usePopupHandleStore.js";

package/utils/popups/index.js

@@ -14,6 +14,17 @@ Object.keys(_inlineRect).forEach(function (key) {
     }
   });
 });
+var _popupHandle = require("./popupHandle");
+Object.keys(_popupHandle).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _popupHandle[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _popupHandle[key];
+    }
+  });
+});
 var _popupStoreUtils = require("./popupStoreUtils");
 Object.keys(_popupStoreUtils).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
@@ -46,4 +57,15 @@ Object.keys(_store).forEach(function (key) {
       return _store[key];
     }
   });
+});
+var _usePopupHandleStore = require("./usePopupHandleStore");
+Object.keys(_usePopupHandleStore).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _usePopupHandleStore[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _usePopupHandleStore[key];
+    }
+  });
 });

package/utils/popups/index.mjs

@@ -1,4 +1,6 @@
 export * from "./inlineRect.mjs";
+export * from "./popupHandle.mjs";
 export * from "./popupStoreUtils.mjs";
 export * from "./popupTriggerMap.mjs";
-export * from "./store.mjs";
+export * from "./store.mjs";
+export * from "./usePopupHandleStore.mjs";

package/utils/popups/popupHandle.d.mts

@@ -0,0 +1,113 @@
+import { type BaseUIChangeEventDetails } from "../../internals/createBaseUIEventDetails.mjs";
+import { REASONS } from "../../internals/reasons.mjs";
+import type { PopupTriggerMap } from "./popupTriggerMap.mjs";
+/**
+ * Minimal store contract exposed by popup handles to detached triggers.
+ *
+ * Detached triggers read `store` during render and subscribe to be notified when the handle switches
+ * between its fallback store and a root's live store.
+ *
+ * @template HandleStore Store shape exposed to detached triggers.
+ */
+export interface PopupHandleStoreProvider<HandleStore> {
+  /**
+   * Store currently exposed by the handle.
+   */
+  readonly store: HandleStore;
+  /**
+   * Subscribes to changes of the exposed store pointer.
+   *
+   * @param listener Callback fired when the handle starts or stops pointing at a root store.
+   * @returns Cleanup function that removes the listener.
+   */
+  subscribeStore(listener: () => void): () => void;
+}
+/**
+ * Store shape holding a trigger registry, required by `BasePopupHandle.openByTrigger` to resolve a
+ * trigger element by id on both the attached root's store and the fallback store.
+ */
+export interface PopupHandleStoreWithTriggers {
+  readonly context: {
+    readonly triggerElements: PopupTriggerMap;
+  };
+}
+/**
+ * Store shape required by `BasePopupHandle.openByTrigger`/`closePopup` to drive open/close state.
+ * Only the root-owned `Store` needs this — the `HandleStore` view exposed to detached triggers may
+ * omit `setOpen` entirely (as Dialog and PreviewCard's do) since it is never called while detached.
+ */
+export interface PopupHandleStoreWithOpen extends PopupHandleStoreWithTriggers {
+  setOpen(open: boolean, eventDetails: BaseUIChangeEventDetails<typeof REASONS.imperativeAction>): void;
+}
+/**
+ * Shared implementation for popup handles that coordinate detached triggers with a mounted root.
+ *
+ * Subclasses provide the component-specific imperative methods, while this base class owns the
+ * fallback store, root store attachment stack, subscriber notifications, and development warning for
+ * overlapping roots.
+ *
+ * @template HandleStore Store shape exposed to detached triggers.
+ * @template Store Root-owned store attached by the component root.
+ */
+export declare class BasePopupHandle<HandleStore extends PopupHandleStoreWithTriggers, Store extends HandleStore & PopupHandleStoreWithOpen> {
+  protected readonly fallbackStore: HandleStore;
+  private readonly componentName;
+  private readonly throwOnMissingTrigger;
+  /**
+   * Stores of every root currently using this handle, in attach order. A handle is meant to be used
+   * by a single mounted root, but roots can transiently overlap (e.g. during an animated route
+   * transition), so this stack lets `attachStore`'s cleanup restore the previous root instead of
+   * leaving a still-mounted root uncontrollable when a newer overlapping root detaches first.
+   */
+  private readonly attachedStores;
+  /**
+   * Store of the root that currently controls the handle: the most recently attached one still
+   * mounted, or `null` when no root is attached. Imperative methods are no-ops while this is `null`.
+   */
+  private attachedStoreValue;
+  /**
+   * Listeners notified when `attachedStore` changes, so detached triggers can follow the store pointer.
+   */
+  private readonly storeListeners;
+  /**
+   * Creates a handle backed by the store used while no root is attached.
+   *
+   * @param fallbackStore Inert, closed store handed to detached triggers while no root is attached,
+   * so they can render and register without a mounted root. Triggers register into whichever store
+   * `store` currently resolves to, so while detached they live in this store's trigger map and
+   * migrate themselves to the root's store (and back) as it attaches/detaches.
+   * @param componentName Component name used to prefix dev warnings, e.g. `'Menu'` produces
+   * `MenuHandle.open()` in warning text.
+   * @param throwOnMissingTrigger Whether `open(triggerId)` throws when no trigger with that id is
+   * registered. Anchored popups (Menu, Popover, Tooltip, PreviewCard) need a trigger to anchor to,
+   * so they throw; Dialog is not anchored and instead opens unassociated with a dev warning.
+   */
+  constructor(fallbackStore: HandleStore, componentName: string, throwOnMissingTrigger?: boolean);
+  protected get attachedStore(): Store | null;
+  /**
+   * Sets the store that currently controls the handle and notifies subscribers when it changes, so
+   * detached triggers re-render and migrate their registration to the new store.
+   */
+  private setActiveStore;
+  /**
+   * Opens the attached root's store and associates it with the trigger with the given id, or a
+   * no-op (with a dev warning) while no root is attached. Shared by every concrete handle's public
+   * `open()` method, which only narrows the parameter type.
+   *
+   * When a trigger id is given but no matching trigger is registered, anchored popups throw (see
+   * `throwOnMissingTrigger`); Dialog opens unassociated with a dev warning instead.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
+   *
+   * @param triggerId ID of the trigger to associate with the popup, or `null`/`undefined` to open
+   * without associating any trigger.
+   */
+  protected openByTrigger(triggerId: string | null | undefined): void;
+  /**
+   * Closes the popup by setting the attached root's store to closed, or a no-op (with a dev warning)
+   * while no root is attached. Shared by every concrete handle's public `close()` method.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
+   */
+  protected closePopup(): void;
+}

package/utils/popups/popupHandle.d.ts

@@ -0,0 +1,113 @@
+import { type BaseUIChangeEventDetails } from "../../internals/createBaseUIEventDetails.js";
+import { REASONS } from "../../internals/reasons.js";
+import type { PopupTriggerMap } from "./popupTriggerMap.js";
+/**
+ * Minimal store contract exposed by popup handles to detached triggers.
+ *
+ * Detached triggers read `store` during render and subscribe to be notified when the handle switches
+ * between its fallback store and a root's live store.
+ *
+ * @template HandleStore Store shape exposed to detached triggers.
+ */
+export interface PopupHandleStoreProvider<HandleStore> {
+  /**
+   * Store currently exposed by the handle.
+   */
+  readonly store: HandleStore;
+  /**
+   * Subscribes to changes of the exposed store pointer.
+   *
+   * @param listener Callback fired when the handle starts or stops pointing at a root store.
+   * @returns Cleanup function that removes the listener.
+   */
+  subscribeStore(listener: () => void): () => void;
+}
+/**
+ * Store shape holding a trigger registry, required by `BasePopupHandle.openByTrigger` to resolve a
+ * trigger element by id on both the attached root's store and the fallback store.
+ */
+export interface PopupHandleStoreWithTriggers {
+  readonly context: {
+    readonly triggerElements: PopupTriggerMap;
+  };
+}
+/**
+ * Store shape required by `BasePopupHandle.openByTrigger`/`closePopup` to drive open/close state.
+ * Only the root-owned `Store` needs this — the `HandleStore` view exposed to detached triggers may
+ * omit `setOpen` entirely (as Dialog and PreviewCard's do) since it is never called while detached.
+ */
+export interface PopupHandleStoreWithOpen extends PopupHandleStoreWithTriggers {
+  setOpen(open: boolean, eventDetails: BaseUIChangeEventDetails<typeof REASONS.imperativeAction>): void;
+}
+/**
+ * Shared implementation for popup handles that coordinate detached triggers with a mounted root.
+ *
+ * Subclasses provide the component-specific imperative methods, while this base class owns the
+ * fallback store, root store attachment stack, subscriber notifications, and development warning for
+ * overlapping roots.
+ *
+ * @template HandleStore Store shape exposed to detached triggers.
+ * @template Store Root-owned store attached by the component root.
+ */
+export declare class BasePopupHandle<HandleStore extends PopupHandleStoreWithTriggers, Store extends HandleStore & PopupHandleStoreWithOpen> {
+  protected readonly fallbackStore: HandleStore;
+  private readonly componentName;
+  private readonly throwOnMissingTrigger;
+  /**
+   * Stores of every root currently using this handle, in attach order. A handle is meant to be used
+   * by a single mounted root, but roots can transiently overlap (e.g. during an animated route
+   * transition), so this stack lets `attachStore`'s cleanup restore the previous root instead of
+   * leaving a still-mounted root uncontrollable when a newer overlapping root detaches first.
+   */
+  private readonly attachedStores;
+  /**
+   * Store of the root that currently controls the handle: the most recently attached one still
+   * mounted, or `null` when no root is attached. Imperative methods are no-ops while this is `null`.
+   */
+  private attachedStoreValue;
+  /**
+   * Listeners notified when `attachedStore` changes, so detached triggers can follow the store pointer.
+   */
+  private readonly storeListeners;
+  /**
+   * Creates a handle backed by the store used while no root is attached.
+   *
+   * @param fallbackStore Inert, closed store handed to detached triggers while no root is attached,
+   * so they can render and register without a mounted root. Triggers register into whichever store
+   * `store` currently resolves to, so while detached they live in this store's trigger map and
+   * migrate themselves to the root's store (and back) as it attaches/detaches.
+   * @param componentName Component name used to prefix dev warnings, e.g. `'Menu'` produces
+   * `MenuHandle.open()` in warning text.
+   * @param throwOnMissingTrigger Whether `open(triggerId)` throws when no trigger with that id is
+   * registered. Anchored popups (Menu, Popover, Tooltip, PreviewCard) need a trigger to anchor to,
+   * so they throw; Dialog is not anchored and instead opens unassociated with a dev warning.
+   */
+  constructor(fallbackStore: HandleStore, componentName: string, throwOnMissingTrigger?: boolean);
+  protected get attachedStore(): Store | null;
+  /**
+   * Sets the store that currently controls the handle and notifies subscribers when it changes, so
+   * detached triggers re-render and migrate their registration to the new store.
+   */
+  private setActiveStore;
+  /**
+   * Opens the attached root's store and associates it with the trigger with the given id, or a
+   * no-op (with a dev warning) while no root is attached. Shared by every concrete handle's public
+   * `open()` method, which only narrows the parameter type.
+   *
+   * When a trigger id is given but no matching trigger is registered, anchored popups throw (see
+   * `throwOnMissingTrigger`); Dialog opens unassociated with a dev warning instead.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
+   *
+   * @param triggerId ID of the trigger to associate with the popup, or `null`/`undefined` to open
+   * without associating any trigger.
+   */
+  protected openByTrigger(triggerId: string | null | undefined): void;
+  /**
+   * Closes the popup by setting the attached root's store to closed, or a no-op (with a dev warning)
+   * while no root is attached. Shared by every concrete handle's public `close()` method.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
+   */
+  protected closePopup(): void;
+}