@base-ui/react 1.6.0 → 1.7.0

package/dialog/root/useDialogRoot.d.mts

@@ -1,10 +1,4 @@
-import { type DialogRoot } from "./DialogRoot.mjs";
 import { DialogStore } from "../store/DialogStore.mjs";
-export declare function useDialogRoot(params: UseDialogRootParameters): void;
-export interface UseDialogRootParameters {
-  store: DialogStore<any>;
-  actionsRef?: DialogRoot.Props['actionsRef'] | undefined;
-}
 export declare function DialogInteractions({
   store,
   parentContext,

package/dialog/root/useDialogRoot.d.ts

@@ -1,10 +1,4 @@
-import { type DialogRoot } from "./DialogRoot.js";
 import { DialogStore } from "../store/DialogStore.js";
-export declare function useDialogRoot(params: UseDialogRootParameters): void;
-export interface UseDialogRootParameters {
-  store: DialogStore<any>;
-  actionsRef?: DialogRoot.Props['actionsRef'] | undefined;
-}
 export declare function DialogInteractions({
   store,
   parentContext,

package/dialog/root/useDialogRoot.js

@@ -6,34 +6,12 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.DialogInteractions = DialogInteractions;
-exports.useDialogRoot = useDialogRoot;
 var React = _interopRequireWildcard(require("react"));
+var _useIsoLayoutEffect = require("@base-ui/utils/useIsoLayoutEffect");
 var _useScrollLock = require("@base-ui/utils/useScrollLock");
-var _empty = require("@base-ui/utils/empty");
 var _floatingUiReact = require("../../floating-ui-react");
 var _utils = require("../../floating-ui-react/utils");
-var _createBaseUIEventDetails = require("../../internals/createBaseUIEventDetails");
-var _reasons = require("../../internals/reasons");
 var _popups = require("../../utils/popups");
-function useDialogRoot(params) {
-  const {
-    store,
-    actionsRef
-  } = params;
-  const open = store.useState('open');
-  (0, _popups.usePopupRootSync)(store, open);
-  (0, _popups.useImplicitActiveTrigger)(store);
-  const {
-    forceUnmount
-  } = (0, _popups.useOpenStateTransitions)(open, store);
-  const handleImperativeClose = React.useCallback(() => {
-    store.setOpen(false, (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.imperativeAction));
-  }, [store]);
-  React.useImperativeHandle(actionsRef, () => ({
-    unmount: forceUnmount,
-    close: handleImperativeClose
-  }), [forceUnmount, handleImperativeClose]);
-}
 function DialogInteractions({
   store,
   parentContext,
@@ -69,8 +47,18 @@ function DialogInteractions({
       if ('button' in event && event.button !== 0) {
         return false;
       }
-      if ('touches' in event && event.touches.length !== 1) {
-        return false;
+      if ('touches' in event) {
+        // Outside press can be handled on `touchend`, where the lifted point is
+        // reported in `changedTouches` and `touches` contains any remaining
+        // active points. Treat it as a single-finger tap only when exactly one
+        // touch ended and no other fingers are still down.
+        if (event.type === 'touchend') {
+          if (event.changedTouches.length !== 1 || event.touches.length !== 0) {
+            return false;
+          }
+        } else if (event.touches.length !== 1) {
+          return false;
+        }
       }
       const target = (0, _utils.getTarget)(event);
       if (isTopmost && !disablePointerDismissal) {
@@ -78,7 +66,9 @@ function DialogInteractions({
         // This supports multiple modal dialogs that aren't nested in the React tree:
         // https://github.com/mui/base-ui/issues/1320
         if (modal) {
-          return store.context.internalBackdropRef.current || store.context.backdropRef.current ? store.context.internalBackdropRef.current === target || store.context.backdropRef.current === target || (0, _utils.contains)(target, popupElement) && !target?.hasAttribute('data-base-ui-portal') : true;
+          const internalBackdrop = store.context.internalBackdropRef.current;
+          const backdrop = store.context.backdropRef.current;
+          return internalBackdrop || backdrop ? internalBackdrop === target || backdrop === target || (0, _utils.contains)(target, popupElement) && !target?.hasAttribute('data-base-ui-portal') : true;
         }
         return true;
       }
@@ -89,38 +79,35 @@ function DialogInteractions({
   (0, _useScrollLock.useScrollLock)(open && modal === true, popupElement);
 
   // Listen for nested open/close events on this store to maintain the counts.
+  // A close notification is an open notification with zeroed counts.
   store.useContextCallback('onNestedDialogOpen', (dialogCount, drawerCount) => {
     setOwnNestedOpenDialogs(dialogCount);
     setOwnNestedOpenDrawers(drawerCount);
   });
-  store.useContextCallback('onNestedDialogClose', () => {
-    setOwnNestedOpenDialogs(0);
-    setOwnNestedOpenDrawers(0);
-  });
 
   // Notify parent of our open/close state using parent callbacks, if any
-  React.useEffect(() => {
-    if (parentContext?.onNestedDialogOpen && open) {
-      parentContext.onNestedDialogOpen(ownNestedOpenDialogs + 1, ownNestedOpenDrawers + (isDrawer ? 1 : 0));
-    }
-    if (parentContext?.onNestedDialogClose && !open) {
-      parentContext.onNestedDialogClose();
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    if (parentContext?.onNestedDialogOpen) {
+      if (open) {
+        parentContext.onNestedDialogOpen(ownNestedOpenDialogs + 1, ownNestedOpenDrawers + (isDrawer ? 1 : 0));
+      } else {
+        parentContext.onNestedDialogOpen(0, 0);
+      }
     }
     return () => {
-      if (parentContext?.onNestedDialogClose && open) {
-        parentContext.onNestedDialogClose();
+      if (parentContext?.onNestedDialogOpen && open) {
+        parentContext.onNestedDialogOpen(0, 0);
       }
     };
   }, [isDrawer, open, ownNestedOpenDialogs, ownNestedOpenDrawers, parentContext]);
-  const activeTriggerProps = dismiss.reference ?? _empty.EMPTY_OBJECT;
-  const inactiveTriggerProps = dismiss.trigger ?? _empty.EMPTY_OBJECT;
-  // Consumers (DialogPopup/DrawerPopup) already spread `FOCUSABLE_POPUP_PROPS`
-  // directly, so the popup props only need to carry the dismiss handlers.
-  const popupProps = dismiss.floating ?? _empty.EMPTY_OBJECT;
   (0, _popups.usePopupInteractionProps)(store, {
-    activeTriggerProps,
-    inactiveTriggerProps,
-    popupProps,
+    // `enabled` is not passed to `useDismiss`, so its props are always defined,
+    // and `trigger` is the same object as `reference`.
+    activeTriggerProps: dismiss.reference,
+    inactiveTriggerProps: dismiss.trigger,
+    // DialogPopup and DrawerPopup spread `FOCUSABLE_POPUP_PROPS` directly, so
+    // this only needs to carry the dismiss handlers.
+    popupProps: dismiss.floating,
     nestedOpenDialogCount: ownNestedOpenDialogs,
     nestedOpenDrawerCount: ownNestedOpenDrawers
   });

package/dialog/root/useDialogRoot.mjs

@@ -1,32 +1,11 @@
 'use client';
 
 import * as React from 'react';
+import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
 import { useScrollLock } from '@base-ui/utils/useScrollLock';
-import { EMPTY_OBJECT } from '@base-ui/utils/empty';
 import { useDismiss } from "../../floating-ui-react/index.mjs";
 import { contains, getTarget } from "../../floating-ui-react/utils.mjs";
-import { createChangeEventDetails } from "../../internals/createBaseUIEventDetails.mjs";
-import { REASONS } from "../../internals/reasons.mjs";
-import { useImplicitActiveTrigger, useOpenStateTransitions, usePopupInteractionProps, usePopupRootSync } from "../../utils/popups/index.mjs";
-export function useDialogRoot(params) {
-  const {
-    store,
-    actionsRef
-  } = params;
-  const open = store.useState('open');
-  usePopupRootSync(store, open);
-  useImplicitActiveTrigger(store);
-  const {
-    forceUnmount
-  } = useOpenStateTransitions(open, store);
-  const handleImperativeClose = React.useCallback(() => {
-    store.setOpen(false, createChangeEventDetails(REASONS.imperativeAction));
-  }, [store]);
-  React.useImperativeHandle(actionsRef, () => ({
-    unmount: forceUnmount,
-    close: handleImperativeClose
-  }), [forceUnmount, handleImperativeClose]);
-}
+import { usePopupInteractionProps } from "../../utils/popups/index.mjs";
 export function DialogInteractions({
   store,
   parentContext,
@@ -62,8 +41,18 @@ export function DialogInteractions({
       if ('button' in event && event.button !== 0) {
         return false;
       }
-      if ('touches' in event && event.touches.length !== 1) {
-        return false;
+      if ('touches' in event) {
+        // Outside press can be handled on `touchend`, where the lifted point is
+        // reported in `changedTouches` and `touches` contains any remaining
+        // active points. Treat it as a single-finger tap only when exactly one
+        // touch ended and no other fingers are still down.
+        if (event.type === 'touchend') {
+          if (event.changedTouches.length !== 1 || event.touches.length !== 0) {
+            return false;
+          }
+        } else if (event.touches.length !== 1) {
+          return false;
+        }
       }
       const target = getTarget(event);
       if (isTopmost && !disablePointerDismissal) {
@@ -71,7 +60,9 @@ export function DialogInteractions({
         // This supports multiple modal dialogs that aren't nested in the React tree:
         // https://github.com/mui/base-ui/issues/1320
         if (modal) {
-          return store.context.internalBackdropRef.current || store.context.backdropRef.current ? store.context.internalBackdropRef.current === target || store.context.backdropRef.current === target || contains(target, popupElement) && !target?.hasAttribute('data-base-ui-portal') : true;
+          const internalBackdrop = store.context.internalBackdropRef.current;
+          const backdrop = store.context.backdropRef.current;
+          return internalBackdrop || backdrop ? internalBackdrop === target || backdrop === target || contains(target, popupElement) && !target?.hasAttribute('data-base-ui-portal') : true;
         }
         return true;
       }
@@ -82,38 +73,35 @@ export function DialogInteractions({
   useScrollLock(open && modal === true, popupElement);
 
   // Listen for nested open/close events on this store to maintain the counts.
+  // A close notification is an open notification with zeroed counts.
   store.useContextCallback('onNestedDialogOpen', (dialogCount, drawerCount) => {
     setOwnNestedOpenDialogs(dialogCount);
     setOwnNestedOpenDrawers(drawerCount);
   });
-  store.useContextCallback('onNestedDialogClose', () => {
-    setOwnNestedOpenDialogs(0);
-    setOwnNestedOpenDrawers(0);
-  });
 
   // Notify parent of our open/close state using parent callbacks, if any
-  React.useEffect(() => {
-    if (parentContext?.onNestedDialogOpen && open) {
-      parentContext.onNestedDialogOpen(ownNestedOpenDialogs + 1, ownNestedOpenDrawers + (isDrawer ? 1 : 0));
-    }
-    if (parentContext?.onNestedDialogClose && !open) {
-      parentContext.onNestedDialogClose();
+  useIsoLayoutEffect(() => {
+    if (parentContext?.onNestedDialogOpen) {
+      if (open) {
+        parentContext.onNestedDialogOpen(ownNestedOpenDialogs + 1, ownNestedOpenDrawers + (isDrawer ? 1 : 0));
+      } else {
+        parentContext.onNestedDialogOpen(0, 0);
+      }
     }
     return () => {
-      if (parentContext?.onNestedDialogClose && open) {
-        parentContext.onNestedDialogClose();
+      if (parentContext?.onNestedDialogOpen && open) {
+        parentContext.onNestedDialogOpen(0, 0);
       }
     };
   }, [isDrawer, open, ownNestedOpenDialogs, ownNestedOpenDrawers, parentContext]);
-  const activeTriggerProps = dismiss.reference ?? EMPTY_OBJECT;
-  const inactiveTriggerProps = dismiss.trigger ?? EMPTY_OBJECT;
-  // Consumers (DialogPopup/DrawerPopup) already spread `FOCUSABLE_POPUP_PROPS`
-  // directly, so the popup props only need to carry the dismiss handlers.
-  const popupProps = dismiss.floating ?? EMPTY_OBJECT;
   usePopupInteractionProps(store, {
-    activeTriggerProps,
-    inactiveTriggerProps,
-    popupProps,
+    // `enabled` is not passed to `useDismiss`, so its props are always defined,
+    // and `trigger` is the same object as `reference`.
+    activeTriggerProps: dismiss.reference,
+    inactiveTriggerProps: dismiss.trigger,
+    // DialogPopup and DrawerPopup spread `FOCUSABLE_POPUP_PROPS` directly, so
+    // this only needs to carry the dismiss handlers.
+    popupProps: dismiss.floating,
     nestedOpenDialogCount: ownNestedOpenDialogs,
     nestedOpenDrawerCount: ownNestedOpenDrawers
   });

package/dialog/root/useRenderDialogRoot.d.mts

@@ -1,4 +1,4 @@
 import type { DialogRootProps } from "./DialogRoot.mjs";
-export declare function useRenderDialogRoot<Payload>(props: DialogRootProps<Payload>, mode?: DialogRootMode): import("react/jsx-runtime").JSX.Element;
+export declare function useRenderDialogRoot<Payload>(mode: DialogRootMode, props: DialogRootProps<Payload>): import("react/jsx-runtime").JSX.Element;
 type DialogRootMode = 'dialog' | 'drawer' | 'alert-dialog';
 export {};

package/dialog/root/useRenderDialogRoot.d.ts

@@ -1,4 +1,4 @@
 import type { DialogRootProps } from "./DialogRoot.js";
-export declare function useRenderDialogRoot<Payload>(props: DialogRootProps<Payload>, mode?: DialogRootMode): import("react/jsx-runtime").JSX.Element;
+export declare function useRenderDialogRoot<Payload>(mode: DialogRootMode, props: DialogRootProps<Payload>): import("react/jsx-runtime").JSX.Element;
 type DialogRootMode = 'dialog' | 'drawer' | 'alert-dialog';
 export {};

package/dialog/root/useRenderDialogRoot.js

@@ -7,12 +7,14 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.useRenderDialogRoot = useRenderDialogRoot;
 var React = _interopRequireWildcard(require("react"));
-var _useOnFirstRender = require("@base-ui/utils/useOnFirstRender");
 var _useDialogRoot = require("./useDialogRoot");
 var _DialogRootContext = require("./DialogRootContext");
 var _DialogStore = require("../store/DialogStore");
+var _createBaseUIEventDetails = require("../../internals/createBaseUIEventDetails");
+var _reasons = require("../../internals/reasons");
+var _popups = require("../../utils/popups");
 var _jsxRuntime = require("react/jsx-runtime");
-function useRenderDialogRoot(props, mode = 'dialog') {
+function useRenderDialogRoot(mode, props) {
   const {
     children,
     open: openProp,
@@ -31,38 +33,26 @@ function useRenderDialogRoot(props, mode = 'dialog') {
   const modal = isAlertDialog ? true : modalProp;
   const disablePointerDismissal = isAlertDialog || disablePointerDismissalProp;
   const role = isAlertDialog ? 'alertdialog' : 'dialog';
-  const parentDialogRootContext = (0, _DialogRootContext.useDialogRootContext)(true);
-  const nested = Boolean(parentDialogRootContext);
+  const parentStore = (0, _DialogRootContext.useDialogRootContext)(true);
+  const nested = parentStore != null;
   const rootState = {
     modal,
     disablePointerDismissal,
     nested,
     role
   };
-  const store = _DialogStore.DialogStore.useStore(handle?.store, {
+
+  // The store is owned by this Root instance and created exactly once. It is not tied to the handle:
+  // the handle attaches to it, so swapping the handle re-attaches rather than recreating state.
+  // Default values are only initial values; controlled values and root state are synced after creation.
+  // Dialogs pass the popup element to Floating UI as the floating element (`treatPopupAsFloatingElement`).
+  const store = (0, _popups.usePopupRootStore)((floatingId, floatingNested) => new _DialogStore.DialogStore({
     open: defaultOpen,
     openProp,
     activeTriggerId: defaultTriggerIdProp,
     triggerIdProp,
     ...rootState
-  });
-
-  // Support initially open state when uncontrolled
-  (0, _useOnFirstRender.useOnFirstRender)(() => {
-    const nextState = openProp === undefined && store.state.open === false && defaultOpen === true ? {
-      open: true,
-      activeTriggerId: defaultTriggerIdProp
-    } : null;
-    if (isAlertDialog) {
-      // Handles can reuse plain Dialog stores; alert dialog invariants must exist immediately.
-      store.update(nextState ? {
-        ...rootState,
-        ...nextState
-      } : rootState);
-    } else if (nextState) {
-      store.update(nextState);
-    }
-  });
+  }, floatingId, floatingNested), true);
   store.useControlledProp('openProp', openProp);
   store.useControlledProp('triggerIdProp', triggerIdProp);
   store.useSyncedValues(rootState);
@@ -71,25 +61,27 @@ function useRenderDialogRoot(props, mode = 'dialog') {
   const open = store.useState('open');
   const mounted = store.useState('mounted');
   const payload = store.useState('payload');
-  (0, _useDialogRoot.useDialogRoot)({
-    store,
-    actionsRef
-  });
+  (0, _popups.usePopupRootSync)(store, open);
+  (0, _popups.useImplicitActiveTrigger)(store);
+  const {
+    forceUnmount
+  } = (0, _popups.useOpenStateTransitions)(open, store);
+  React.useImperativeHandle(actionsRef, () => ({
+    unmount: forceUnmount,
+    close: () => store.setOpen(false, (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.imperativeAction))
+  }), [forceUnmount, store]);
   const shouldRenderInteractions = open || mounted;
-  const contextValue = React.useMemo(() => ({
-    store
-  }), [store]);
-  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_DialogRootContext.IsDrawerContext.Provider, {
-    value: false,
-    children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_DialogRootContext.DialogRootContext.Provider, {
-      value: contextValue,
-      children: [shouldRenderInteractions && /*#__PURE__*/(0, _jsxRuntime.jsx)(_useDialogRoot.DialogInteractions, {
-        store: store,
-        parentContext: parentDialogRootContext?.store.context,
-        isDrawer: isDrawer
-      }), typeof children === 'function' ? children({
-        payload
-      }) : children]
-    })
+  return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_DialogRootContext.DialogRootContext.Provider, {
+    value: store,
+    children: [handle && /*#__PURE__*/(0, _jsxRuntime.jsx)(_popups.PopupHandleAttachment, {
+      handle: handle,
+      store: store
+    }), shouldRenderInteractions && /*#__PURE__*/(0, _jsxRuntime.jsx)(_useDialogRoot.DialogInteractions, {
+      store: store,
+      parentContext: parentStore?.context,
+      isDrawer: isDrawer
+    }), typeof children === 'function' ? children({
+      payload
+    }) : children]
   });
 }

package/dialog/root/useRenderDialogRoot.mjs

@@ -1,12 +1,14 @@
 'use client';
 
 import * as React from 'react';
-import { useOnFirstRender } from '@base-ui/utils/useOnFirstRender';
-import { DialogInteractions, useDialogRoot } from "./useDialogRoot.mjs";
-import { DialogRootContext, IsDrawerContext, useDialogRootContext } from "./DialogRootContext.mjs";
+import { DialogInteractions } from "./useDialogRoot.mjs";
+import { DialogRootContext, useDialogRootContext } from "./DialogRootContext.mjs";
 import { DialogStore } from "../store/DialogStore.mjs";
+import { createChangeEventDetails } from "../../internals/createBaseUIEventDetails.mjs";
+import { REASONS } from "../../internals/reasons.mjs";
+import { useImplicitActiveTrigger, useOpenStateTransitions, PopupHandleAttachment, usePopupRootStore, usePopupRootSync } from "../../utils/popups/index.mjs";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-export function useRenderDialogRoot(props, mode = 'dialog') {
+export function useRenderDialogRoot(mode, props) {
   const {
     children,
     open: openProp,
@@ -25,38 +27,26 @@ export function useRenderDialogRoot(props, mode = 'dialog') {
   const modal = isAlertDialog ? true : modalProp;
   const disablePointerDismissal = isAlertDialog || disablePointerDismissalProp;
   const role = isAlertDialog ? 'alertdialog' : 'dialog';
-  const parentDialogRootContext = useDialogRootContext(true);
-  const nested = Boolean(parentDialogRootContext);
+  const parentStore = useDialogRootContext(true);
+  const nested = parentStore != null;
   const rootState = {
     modal,
     disablePointerDismissal,
     nested,
     role
   };
-  const store = DialogStore.useStore(handle?.store, {
+
+  // The store is owned by this Root instance and created exactly once. It is not tied to the handle:
+  // the handle attaches to it, so swapping the handle re-attaches rather than recreating state.
+  // Default values are only initial values; controlled values and root state are synced after creation.
+  // Dialogs pass the popup element to Floating UI as the floating element (`treatPopupAsFloatingElement`).
+  const store = usePopupRootStore((floatingId, floatingNested) => new DialogStore({
     open: defaultOpen,
     openProp,
     activeTriggerId: defaultTriggerIdProp,
     triggerIdProp,
     ...rootState
-  });
-
-  // Support initially open state when uncontrolled
-  useOnFirstRender(() => {
-    const nextState = openProp === undefined && store.state.open === false && defaultOpen === true ? {
-      open: true,
-      activeTriggerId: defaultTriggerIdProp
-    } : null;
-    if (isAlertDialog) {
-      // Handles can reuse plain Dialog stores; alert dialog invariants must exist immediately.
-      store.update(nextState ? {
-        ...rootState,
-        ...nextState
-      } : rootState);
-    } else if (nextState) {
-      store.update(nextState);
-    }
-  });
+  }, floatingId, floatingNested), true);
   store.useControlledProp('openProp', openProp);
   store.useControlledProp('triggerIdProp', triggerIdProp);
   store.useSyncedValues(rootState);
@@ -65,25 +55,27 @@ export function useRenderDialogRoot(props, mode = 'dialog') {
   const open = store.useState('open');
   const mounted = store.useState('mounted');
   const payload = store.useState('payload');
-  useDialogRoot({
-    store,
-    actionsRef
-  });
+  usePopupRootSync(store, open);
+  useImplicitActiveTrigger(store);
+  const {
+    forceUnmount
+  } = useOpenStateTransitions(open, store);
+  React.useImperativeHandle(actionsRef, () => ({
+    unmount: forceUnmount,
+    close: () => store.setOpen(false, createChangeEventDetails(REASONS.imperativeAction))
+  }), [forceUnmount, store]);
   const shouldRenderInteractions = open || mounted;
-  const contextValue = React.useMemo(() => ({
-    store
-  }), [store]);
-  return /*#__PURE__*/_jsx(IsDrawerContext.Provider, {
-    value: false,
-    children: /*#__PURE__*/_jsxs(DialogRootContext.Provider, {
-      value: contextValue,
-      children: [shouldRenderInteractions && /*#__PURE__*/_jsx(DialogInteractions, {
-        store: store,
-        parentContext: parentDialogRootContext?.store.context,
-        isDrawer: isDrawer
-      }), typeof children === 'function' ? children({
-        payload
-      }) : children]
-    })
+  return /*#__PURE__*/_jsxs(DialogRootContext.Provider, {
+    value: store,
+    children: [handle && /*#__PURE__*/_jsx(PopupHandleAttachment, {
+      handle: handle,
+      store: store
+    }), shouldRenderInteractions && /*#__PURE__*/_jsx(DialogInteractions, {
+      store: store,
+      parentContext: parentStore?.context,
+      isDrawer: isDrawer
+    }), typeof children === 'function' ? children({
+      payload
+    }) : children]
   });
 }

package/dialog/store/DialogHandle.d.mts

@@ -1,36 +1,40 @@
-import { DialogStore } from "./DialogStore.mjs";
+import { DialogStore, type DialogHandleStore } from "./DialogStore.mjs";
+import { BasePopupHandle } from "../../utils/popups/popupHandle.mjs";
 /**
- * A handle to control a Dialog imperatively and to associate detached triggers with it.
+ * Controls a Dialog imperatively and associates detached `Dialog.Trigger` components with a
+ * `Dialog.Root`. Create one with `Dialog.createHandle()` and pass it to the `handle` prop of the
+ * root and of any triggers rendered outside of it.
+ *
+ * The imperative methods take effect only while a root using this handle is mounted; calls made
+ * before a root attaches (or after it unmounts) are ignored.
  */
-export declare class DialogHandle<Payload> {
+export declare class DialogHandle<Payload> extends BasePopupHandle<DialogHandleStore<Payload>, DialogStore<Payload>> {
+  constructor();
   /**
-   * Internal store holding the dialog state.
-   * @internal
-   */
-  readonly store: DialogStore<Payload>;
-  constructor(store?: DialogStore<Payload>);
-  /**
-   * Opens the dialog and associates it with the trigger with the given id.
-   * The trigger, if provided, must be a matching Trigger component with this handle passed as a prop.
+   * Opens the dialog, optionally associating it with a trigger.
    *
    * 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 dialog. If null, the dialog will open without a trigger association.
+   * @param triggerId ID of the trigger to associate with the dialog. The trigger must be a matching
+   * `Dialog.Trigger` with this handle passed as a prop. Pass `null` to open without associating any trigger.
    */
   open(triggerId: string | null): void;
   /**
-   * Opens the dialog and sets the payload.
-   * Does not associate the dialog with any trigger.
+   * Opens the dialog with the given payload, without associating it with any trigger.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
    *
-   * @param payload Payload to set when opening the dialog.
+   * @param payload Payload to set when opening the dialog. It is exposed to the root's render-prop children.
    */
   openWithPayload(payload: Payload): void;
   /**
    * Closes the dialog.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
    */
   close(): void;
   /**
-   * Indicates whether the dialog is currently open.
+   * Whether the dialog is currently open. Returns `false` while no root is attached to the handle.
    */
   get isOpen(): boolean;
 }

package/dialog/store/DialogHandle.d.ts

@@ -1,36 +1,40 @@
-import { DialogStore } from "./DialogStore.js";
+import { DialogStore, type DialogHandleStore } from "./DialogStore.js";
+import { BasePopupHandle } from "../../utils/popups/popupHandle.js";
 /**
- * A handle to control a Dialog imperatively and to associate detached triggers with it.
+ * Controls a Dialog imperatively and associates detached `Dialog.Trigger` components with a
+ * `Dialog.Root`. Create one with `Dialog.createHandle()` and pass it to the `handle` prop of the
+ * root and of any triggers rendered outside of it.
+ *
+ * The imperative methods take effect only while a root using this handle is mounted; calls made
+ * before a root attaches (or after it unmounts) are ignored.
  */
-export declare class DialogHandle<Payload> {
+export declare class DialogHandle<Payload> extends BasePopupHandle<DialogHandleStore<Payload>, DialogStore<Payload>> {
+  constructor();
   /**
-   * Internal store holding the dialog state.
-   * @internal
-   */
-  readonly store: DialogStore<Payload>;
-  constructor(store?: DialogStore<Payload>);
-  /**
-   * Opens the dialog and associates it with the trigger with the given id.
-   * The trigger, if provided, must be a matching Trigger component with this handle passed as a prop.
+   * Opens the dialog, optionally associating it with a trigger.
    *
    * 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 dialog. If null, the dialog will open without a trigger association.
+   * @param triggerId ID of the trigger to associate with the dialog. The trigger must be a matching
+   * `Dialog.Trigger` with this handle passed as a prop. Pass `null` to open without associating any trigger.
    */
   open(triggerId: string | null): void;
   /**
-   * Opens the dialog and sets the payload.
-   * Does not associate the dialog with any trigger.
+   * Opens the dialog with the given payload, without associating it with any trigger.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
    *
-   * @param payload Payload to set when opening the dialog.
+   * @param payload Payload to set when opening the dialog. It is exposed to the root's render-prop children.
    */
   openWithPayload(payload: Payload): void;
   /**
    * Closes the dialog.
+   *
+   * This method should only be called in an event handler or an effect (not during rendering).
    */
   close(): void;
   /**
-   * Indicates whether the dialog is currently open.
+   * Whether the dialog is currently open. Returns `false` while no root is attached to the handle.
    */
   get isOpen(): boolean;
 }