@base-ui/react 1.5.0 → 1.6.0

package/drawer/popup/DrawerPopup.mjs

@@ -0,0 +1,356 @@
+'use client';
+
+import * as React from 'react';
+import { error } from '@base-ui/utils/error';
+import { SafeReact } from '@base-ui/utils/safeReact';
+import { useIsoLayoutEffect } from '@base-ui/utils/useIsoLayoutEffect';
+import { useStableCallback } from '@base-ui/utils/useStableCallback';
+import { EMPTY_OBJECT } from '@base-ui/utils/empty';
+import { FloatingFocusManager } from "../../floating-ui-react/index.mjs";
+import { useDialogRootContext } from "../../dialog/root/DialogRootContext.mjs";
+import { useRenderElement } from "../../internals/useRenderElement.mjs";
+import { popupStateMapping as baseMapping } from "../../utils/popupStateMapping.mjs";
+import { transitionStatusMapping } from "../../internals/stateAttributesMapping.mjs";
+import { DrawerBackdropCssVars } from "../backdrop/DrawerBackdropCssVars.mjs";
+import { DrawerPopupCssVars } from "./DrawerPopupCssVars.mjs";
+import { DrawerPopupDataAttributes } from "./DrawerPopupDataAttributes.mjs";
+import { useDialogPortalContext } from "../../dialog/portal/DialogPortalContext.mjs";
+import { useOpenChangeComplete } from "../../internals/useOpenChangeComplete.mjs";
+import { COMPOSITE_KEYS } from "../../internals/composite/composite.mjs";
+import { useDrawerRootContext } from "../root/DrawerRootContext.mjs";
+import { getSnapPointSwipeMovement, useDrawerSnapPoints } from "../root/useDrawerSnapPoints.mjs";
+import { useDrawerViewportContext } from "../viewport/DrawerViewportContext.mjs";
+import { FOCUSABLE_POPUP_PROPS } from "../../utils/popups/index.mjs";
+
+// Module-level flag to ensure we only register the CSS properties once,
+// regardless of how many Drawer components are mounted.
+import { jsx as _jsx } from "react/jsx-runtime";
+let drawerSwipeVarsRegistered = false;
+
+/**
+ * Removes inheritance of high-frequency drawer swipe CSS variables, which
+ * reduces style recalculation cost in complex drawers with deep subtrees.
+ * See https://motion.dev/blog/web-animation-performance-tier-list
+ * under the "Improving CSS variable performance" section.
+ */
+function removeCSSVariableInheritance() {
+  if (drawerSwipeVarsRegistered) {
+    return;
+  }
+
+  // Intentionally keep inheritance disabled on WebKit as well. Safari doesn't support
+  // opting descendants back in via `--var: inherit` for custom properties registered
+  // with `inherits: false`, but Drawer does not rely on descendant access to these vars
+  // (unlike ScrollArea), so we keep the performance optimization enabled.
+  if (typeof CSS !== 'undefined' && 'registerProperty' in CSS) {
+    [DrawerPopupCssVars.swipeMovementX, DrawerPopupCssVars.swipeMovementY, DrawerPopupCssVars.snapPointOffset].forEach(name => {
+      try {
+        CSS.registerProperty({
+          name,
+          syntax: '<length>',
+          inherits: false,
+          initialValue: '0px'
+        });
+      } catch {
+        /* ignore already-registered */
+      }
+    });
+    [{
+      name: DrawerBackdropCssVars.swipeProgress,
+      initialValue: '0'
+    }, {
+      name: DrawerPopupCssVars.swipeStrength,
+      initialValue: '1'
+    }].forEach(({
+      name,
+      initialValue
+    }) => {
+      try {
+        CSS.registerProperty({
+          name,
+          syntax: '<number>',
+          inherits: false,
+          initialValue
+        });
+      } catch {
+        /* ignore already-registered */
+      }
+    });
+  }
+  drawerSwipeVarsRegistered = true;
+}
+const stateAttributesMapping = {
+  ...baseMapping,
+  ...transitionStatusMapping,
+  expanded(value) {
+    return value ? {
+      [DrawerPopupDataAttributes.expanded]: ''
+    } : null;
+  },
+  nestedDrawerOpen(value) {
+    return value ? {
+      [DrawerPopupDataAttributes.nestedDrawerOpen]: ''
+    } : null;
+  },
+  nestedDrawerSwiping(value) {
+    return value ? {
+      [DrawerPopupDataAttributes.nestedDrawerSwiping]: ''
+    } : null;
+  },
+  swipeDirection(value) {
+    return value ? {
+      [DrawerPopupDataAttributes.swipeDirection]: value
+    } : null;
+  },
+  swiping(value) {
+    return value ? {
+      [DrawerPopupDataAttributes.swiping]: ''
+    } : null;
+  }
+};
+
+/**
+ * A container for the drawer contents.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Drawer](https://base-ui.com/react/components/drawer)
+ */
+export const DrawerPopup = /*#__PURE__*/React.forwardRef(function DrawerPopup(componentProps, forwardedRef) {
+  const {
+    render,
+    className,
+    style,
+    finalFocus,
+    initialFocus,
+    ...elementProps
+  } = componentProps;
+  const {
+    store
+  } = useDialogRootContext();
+  const popupRef = store.context.popupRef;
+  const {
+    swipeDirection,
+    frontmostHeight,
+    hasNestedDrawer,
+    nestedSwiping,
+    nestedSwipeProgressStore,
+    onPopupHeightChange,
+    notifyParentFrontmostHeight,
+    notifyParentHasNestedDrawer
+  } = useDrawerRootContext();
+  const descriptionElementId = store.useState('descriptionElementId');
+  const disablePointerDismissal = store.useState('disablePointerDismissal');
+  const floatingRootContext = store.useState('floatingRootContext');
+  const rootPopupProps = store.useState('popupProps');
+  const modal = store.useState('modal');
+  const mounted = store.useState('mounted');
+  const nested = store.useState('nested');
+  const nestedOpenDrawerCount = store.useState('nestedOpenDrawerCount');
+  const transitionStatus = store.useState('transitionStatus');
+  const open = store.useState('open');
+  const openMethod = store.useState('openMethod');
+  const titleElementId = store.useState('titleElementId');
+  const role = store.useState('role');
+  const floatingId = floatingRootContext.useState('floatingId');
+  const popupId = elementProps.id ?? floatingId;
+  const swipe = useDrawerViewportContext(true);
+  useDialogPortalContext();
+  const {
+    snapPoints,
+    activeSnapPoint,
+    activeSnapPointOffset
+  } = useDrawerSnapPoints();
+  const nestedDrawerOpen = nestedOpenDrawerCount > 0;
+  const swiping = swipe?.swiping ?? false;
+  const swipeStrength = swipe?.swipeStrength ?? null;
+  const [popupHeight, setPopupHeight] = React.useState(0);
+  const popupHeightRef = React.useRef(0);
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    React.useEffect(() => {
+      if (swipe) {
+        return;
+      }
+      const ownerStackMessage = SafeReact.captureOwnerStack?.() || '';
+      const message = '<Drawer.Popup> expected to be rendered within <Drawer.Viewport>. Omitting the ' + 'viewport disables drawer swipe handling and touch scroll locking. Wrap ' + '<Drawer.Popup> in <Drawer.Viewport>.';
+      error(`${message}${ownerStackMessage}`);
+    }, [swipe]);
+  }
+  const measureHeight = useStableCallback(() => {
+    const popupElement = popupRef.current;
+    if (!popupElement) {
+      return;
+    }
+    const offsetHeight = popupElement.offsetHeight;
+
+    // Only skip while the element is still actually stretched beyond its last measured height.
+    if (popupHeightRef.current > 0 && frontmostHeight > popupHeightRef.current && offsetHeight > popupHeightRef.current) {
+      return;
+    }
+    const keepHeightWhileNested = popupHeightRef.current > 0 && hasNestedDrawer;
+    if (keepHeightWhileNested) {
+      const oldHeight = popupHeightRef.current;
+      setPopupHeight(oldHeight);
+      onPopupHeightChange(oldHeight);
+      return;
+    }
+    const nextHeight = offsetHeight;
+    if (nextHeight === popupHeightRef.current) {
+      return;
+    }
+    popupHeightRef.current = nextHeight;
+    setPopupHeight(nextHeight);
+    onPopupHeightChange(nextHeight);
+  });
+  useIsoLayoutEffect(() => {
+    if (!mounted) {
+      popupHeightRef.current = 0;
+      setPopupHeight(0);
+      onPopupHeightChange(0);
+      return undefined;
+    }
+    const popupElement = popupRef.current;
+    if (!popupElement) {
+      return undefined;
+    }
+    removeCSSVariableInheritance();
+    measureHeight();
+    if (typeof ResizeObserver !== 'function') {
+      return undefined;
+    }
+    const resizeObserver = new ResizeObserver(measureHeight);
+    resizeObserver.observe(popupElement);
+    return () => {
+      resizeObserver.disconnect();
+    };
+  }, [measureHeight, mounted, nestedDrawerOpen, onPopupHeightChange, popupRef]);
+  useIsoLayoutEffect(() => {
+    const syncNestedSwipeProgress = () => {
+      const popupElement = popupRef.current;
+      if (!popupElement) {
+        return;
+      }
+      const progress = nestedSwipeProgressStore.getSnapshot();
+      if (progress > 0) {
+        popupElement.style.setProperty(DrawerBackdropCssVars.swipeProgress, `${progress}`);
+      } else {
+        popupElement.style.setProperty(DrawerBackdropCssVars.swipeProgress, '0');
+      }
+    };
+    syncNestedSwipeProgress();
+    const unsubscribe = nestedSwipeProgressStore.subscribe(syncNestedSwipeProgress);
+    const popupElement = popupRef.current;
+    return () => {
+      unsubscribe();
+      if (popupElement) {
+        popupElement.style.setProperty(DrawerBackdropCssVars.swipeProgress, '0');
+      }
+    };
+  }, [nestedSwipeProgressStore, popupRef]);
+  React.useEffect(() => {
+    if (!open) {
+      return undefined;
+    }
+    notifyParentFrontmostHeight?.(frontmostHeight);
+    return () => {
+      notifyParentFrontmostHeight?.(0);
+    };
+  }, [frontmostHeight, open, notifyParentFrontmostHeight]);
+  React.useEffect(() => {
+    if (!notifyParentHasNestedDrawer) {
+      return undefined;
+    }
+    const present = open || transitionStatus === 'ending';
+    notifyParentHasNestedDrawer(present);
+    return () => {
+      notifyParentHasNestedDrawer(false);
+    };
+  }, [notifyParentHasNestedDrawer, open, transitionStatus]);
+  useOpenChangeComplete({
+    open,
+    ref: popupRef,
+    onComplete() {
+      if (open) {
+        store.context.onOpenChangeComplete?.(true);
+      }
+    }
+  });
+  const resolvedInitialFocus = initialFocus === undefined ? popupRef : initialFocus;
+  const setPopupElement = store.useStateSetter('popupElement');
+  const state = {
+    open,
+    nested,
+    transitionStatus,
+    expanded: activeSnapPoint === 1,
+    nestedDrawerOpen,
+    nestedDrawerSwiping: nestedSwiping,
+    swipeDirection,
+    swiping
+  };
+  let popupHeightCssVarValue;
+  const shouldUseAutoHeight = !hasNestedDrawer && transitionStatus !== 'ending';
+  if (popupHeight && !shouldUseAutoHeight) {
+    popupHeightCssVarValue = `${popupHeight}px`;
+  }
+  const shouldApplySnapPoints = snapPoints && snapPoints.length > 0 && (swipeDirection === 'down' || swipeDirection === 'up');
+  let snapPointOffsetValue = null;
+  if (shouldApplySnapPoints && activeSnapPointOffset !== null) {
+    snapPointOffsetValue = swipeDirection === 'up' ? -activeSnapPointOffset : activeSnapPointOffset;
+  }
+  let dragStyles = swipe ? swipe.getDragStyles() : EMPTY_OBJECT;
+  if (shouldApplySnapPoints && swipeDirection === 'down') {
+    const baseOffset = activeSnapPointOffset ?? 0;
+    const movementValue = Number.parseFloat(String(dragStyles[DrawerPopupCssVars.swipeMovementY] ?? 0));
+    if (swiping && Number.isFinite(movementValue)) {
+      dragStyles = {
+        ...dragStyles,
+        transform: undefined,
+        [DrawerPopupCssVars.swipeMovementY]: `${getSnapPointSwipeMovement(baseOffset, movementValue)}px`
+      };
+    } else {
+      dragStyles = {
+        ...dragStyles,
+        transform: undefined
+      };
+    }
+  }
+  const element = useRenderElement('div', componentProps, {
+    state,
+    props: [rootPopupProps, {
+      id: popupId,
+      'aria-labelledby': titleElementId,
+      'aria-describedby': descriptionElementId,
+      role,
+      ...FOCUSABLE_POPUP_PROPS,
+      hidden: !mounted,
+      onKeyDown(event) {
+        if (COMPOSITE_KEYS.has(event.key)) {
+          event.stopPropagation();
+        }
+      },
+      style: {
+        ...dragStyles,
+        [DrawerBackdropCssVars.swipeProgress]: '0',
+        [DrawerPopupCssVars.nestedDrawers]: nestedOpenDrawerCount,
+        [DrawerPopupCssVars.height]: popupHeightCssVarValue,
+        [DrawerPopupCssVars.snapPointOffset]: typeof snapPointOffsetValue === 'number' ? `${snapPointOffsetValue}px` : '0px',
+        [DrawerPopupCssVars.frontmostHeight]: frontmostHeight ? `${frontmostHeight}px` : undefined,
+        [DrawerPopupCssVars.swipeStrength]: typeof swipeStrength === 'number' && Number.isFinite(swipeStrength) && swipeStrength > 0 ? `${swipeStrength}` : '1'
+      }
+    }, elementProps],
+    ref: [forwardedRef, popupRef, setPopupElement],
+    stateAttributesMapping
+  });
+  return /*#__PURE__*/_jsx(FloatingFocusManager, {
+    context: floatingRootContext,
+    openInteractionType: openMethod,
+    disabled: !mounted,
+    closeOnFocusOut: !disablePointerDismissal,
+    initialFocus: resolvedInitialFocus,
+    returnFocus: finalFocus,
+    modal: modal !== false,
+    restoreFocus: "popup",
+    children: element
+  });
+});
+if (process.env.NODE_ENV !== "production") DrawerPopup.displayName = "DrawerPopup";

package/drawer/popup/DrawerPopupDataAttributes.mjs

@@ -0,0 +1,45 @@
+import { CommonPopupDataAttributes } from "../../utils/popupStateMapping.mjs";
+export let DrawerPopupDataAttributes = function (DrawerPopupDataAttributes) {
+  /**
+   * Present when the drawer is open.
+   */
+  DrawerPopupDataAttributes[DrawerPopupDataAttributes["open"] = CommonPopupDataAttributes.open] = "open";
+  /**
+   * Present when the drawer is closed.
+   */
+  DrawerPopupDataAttributes[DrawerPopupDataAttributes["closed"] = CommonPopupDataAttributes.closed] = "closed";
+  /**
+   * Present when the drawer is animating in.
+   */
+  DrawerPopupDataAttributes[DrawerPopupDataAttributes["startingStyle"] = CommonPopupDataAttributes.startingStyle] = "startingStyle";
+  /**
+   * Present when the drawer is animating out.
+   */
+  DrawerPopupDataAttributes[DrawerPopupDataAttributes["endingStyle"] = CommonPopupDataAttributes.endingStyle] = "endingStyle";
+  /**
+   * Present when the drawer is at the expanded (full-height) snap point.
+   */
+  DrawerPopupDataAttributes["expanded"] = "data-expanded";
+  /**
+   * Present when a nested drawer is open.
+   */
+  DrawerPopupDataAttributes["nestedDrawerOpen"] = "data-nested-drawer-open";
+  /**
+   * Present when a nested drawer is being swiped.
+   */
+  DrawerPopupDataAttributes["nestedDrawerSwiping"] = "data-nested-drawer-swiping";
+  /**
+   * Present when the drawer is dismissed by swiping.
+   */
+  DrawerPopupDataAttributes["swipeDismiss"] = "data-swipe-dismiss";
+  /**
+   * Indicates the swipe direction.
+   * @type {'up' | 'down' | 'left' | 'right'}
+   */
+  DrawerPopupDataAttributes["swipeDirection"] = "data-swipe-direction";
+  /**
+   * Present when the drawer is being swiped.
+   */
+  DrawerPopupDataAttributes["swiping"] = "data-swiping";
+  return DrawerPopupDataAttributes;
+}({});

package/drawer/portal/DrawerPortal.d.mts

@@ -0,0 +1,29 @@
+import type * as React from 'react';
+import type { FloatingPortal } from "../../floating-ui-react/index.mjs";
+/**
+ * A portal element that moves the popup to a different part of the DOM.
+ * By default, the portal element is appended to `<body>`.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Drawer](https://base-ui.com/react/components/drawer)
+ */
+export declare const DrawerPortal: DrawerPortal;
+export interface DrawerPortalState {}
+export interface DrawerPortalProps extends FloatingPortal.Props<DrawerPortalState> {
+  /**
+   * Whether to keep the portal mounted in the DOM while the popup is hidden.
+   * @default false
+   */
+  keepMounted?: boolean | undefined;
+  /**
+   * A parent element to render the portal element into.
+   */
+  container?: FloatingPortal.Props<DrawerPortalState>['container'] | undefined;
+}
+export interface DrawerPortal {
+  (componentProps: DrawerPortalProps & React.RefAttributes<HTMLDivElement>): React.JSX.Element | null;
+}
+export declare namespace DrawerPortal {
+  type Props = DrawerPortalProps;
+  type State = DrawerPortalState;
+}

package/drawer/portal/DrawerPortal.mjs

@@ -0,0 +1,11 @@
+'use client';
+
+import { DialogPortal } from "../../dialog/portal/DialogPortal.mjs";
+/**
+ * A portal element that moves the popup to a different part of the DOM.
+ * By default, the portal element is appended to `<body>`.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Drawer](https://base-ui.com/react/components/drawer)
+ */
+export const DrawerPortal = DialogPortal;

package/drawer/provider/DrawerProvider.mjs

@@ -0,0 +1,95 @@
+'use client';
+
+import * as React from 'react';
+import { useStableCallback } from '@base-ui/utils/useStableCallback';
+import { DrawerProviderContext } from "./DrawerProviderContext.mjs";
+
+/**
+ * Provides a shared context for coordinating global Drawer UI, such as indent/background effects based on whether any Drawer is open.
+ * Doesn't render its own HTML element.
+ *
+ * Documentation: [Base UI Drawer](https://base-ui.com/react/components/drawer)
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+export function DrawerProvider(props) {
+  const {
+    children
+  } = props;
+  const [openById, setOpenById] = React.useState(() => new Map());
+  const [visualStateStore] = React.useState(createVisualStateStore);
+  const setDrawerOpen = useStableCallback((drawerId, open) => {
+    setOpenById(prev => {
+      const prevOpen = prev.get(drawerId);
+      if (prevOpen === open) {
+        return prev;
+      }
+      const next = new Map(prev);
+      next.set(drawerId, open);
+      return next;
+    });
+  });
+  const removeDrawer = useStableCallback(drawerId => {
+    setOpenById(prev => {
+      if (!prev.has(drawerId)) {
+        return prev;
+      }
+      const next = new Map(prev);
+      next.delete(drawerId);
+      return next;
+    });
+  });
+  const active = React.useMemo(() => {
+    for (const open of openById.values()) {
+      if (open) {
+        return true;
+      }
+    }
+    return false;
+  }, [openById]);
+  const contextValue = React.useMemo(() => ({
+    setDrawerOpen,
+    removeDrawer,
+    active,
+    visualStateStore
+  }), [active, removeDrawer, setDrawerOpen, visualStateStore]);
+  return /*#__PURE__*/_jsx(DrawerProviderContext.Provider, {
+    value: contextValue,
+    children: children
+  });
+}
+function createVisualStateStore() {
+  let state = {
+    swipeProgress: 0,
+    frontmostHeight: 0
+  };
+  const listeners = new Set();
+  return {
+    getSnapshot: () => state,
+    set(nextState) {
+      let nextSwipeProgress = state.swipeProgress;
+      if (nextState.swipeProgress !== undefined) {
+        nextSwipeProgress = Number.isFinite(nextState.swipeProgress) ? nextState.swipeProgress : 0;
+      }
+      let nextFrontmostHeight = state.frontmostHeight;
+      if (nextState.frontmostHeight !== undefined) {
+        nextFrontmostHeight = Number.isFinite(nextState.frontmostHeight) ? nextState.frontmostHeight : 0;
+      }
+      if (nextSwipeProgress === state.swipeProgress && nextFrontmostHeight === state.frontmostHeight) {
+        return;
+      }
+      state = {
+        swipeProgress: nextSwipeProgress,
+        frontmostHeight: nextFrontmostHeight
+      };
+      listeners.forEach(listener => {
+        listener();
+      });
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}

package/drawer/root/DrawerRoot.d.mts

@@ -0,0 +1,126 @@
+import * as React from 'react';
+import { type DrawerSwipeDirection, type DrawerSnapPoint } from "./DrawerRootContext.mjs";
+import { type BaseUIChangeEventDetails } from "../../internals/createBaseUIEventDetails.mjs";
+import { REASONS } from "../../internals/reasons.mjs";
+import type { DialogHandle } from "../../dialog/store/DialogHandle.mjs";
+import type { PayloadChildRenderFunction } from "../../utils/popups/index.mjs";
+/**
+ * Groups all parts of the drawer.
+ * Doesn't render its own HTML element.
+ *
+ * Documentation: [Base UI Drawer](https://base-ui.com/react/components/drawer)
+ */
+export declare function DrawerRoot<Payload = unknown>(props: DrawerRoot.Props<Payload>): import("react/jsx-runtime").JSX.Element;
+export interface DrawerRootState {}
+export interface DrawerRootProps<Payload = unknown> {
+  /**
+   * Whether the drawer is currently open.
+   */
+  open?: boolean | undefined;
+  /**
+   * Whether the drawer is initially open.
+   *
+   * To render a controlled drawer, use the `open` prop instead.
+   * @default false
+   */
+  defaultOpen?: boolean | undefined;
+  /**
+   * Determines if the drawer enters a modal state when open.
+   * - `true`: user interaction is limited to just the drawer: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled.
+   * - `false`: user interaction with the rest of the document is allowed.
+   * - `'trap-focus'`: focus is trapped inside the drawer, but document page scroll is not locked and pointer interactions outside of it remain enabled.
+   * @default true
+   */
+  modal?: boolean | 'trap-focus' | undefined;
+  /**
+   * Event handler called when the drawer is opened or closed.
+   */
+  onOpenChange?: ((open: boolean, eventDetails: DrawerRoot.ChangeEventDetails) => void) | undefined;
+  /**
+   * Event handler called after any animations complete when the drawer is opened or closed.
+   */
+  onOpenChangeComplete?: ((open: boolean) => void) | undefined;
+  /**
+   * Whether to prevent the drawer from closing on outside presses.
+   * For non-modal drawers, this also prevents the drawer from closing when focus moves outside of it.
+   * @default false
+   */
+  disablePointerDismissal?: boolean | undefined;
+  /**
+   * A ref to imperative actions.
+   * - `unmount`: Manually unmounts the drawer.
+   * Call this after any externally controlled closing animation finishes.
+   * - `close`: Closes the drawer imperatively when called.
+   */
+  actionsRef?: React.RefObject<DrawerRoot.Actions | null> | undefined;
+  /**
+   * A handle to associate the drawer with a trigger.
+   * If specified, allows detached triggers to control the drawer's open state.
+   * Can be created with the Drawer.createHandle() method.
+   */
+  handle?: DialogHandle<Payload> | undefined;
+  /**
+   * ID of the trigger that the drawer is associated with.
+   * This is useful in conjunction with the `open` prop to create a controlled drawer.
+   * There's no need to specify this prop when the drawer is uncontrolled (that is, when the `open` prop is not set).
+   */
+  triggerId?: string | null | undefined;
+  /**
+   * ID of the trigger that the drawer is associated with.
+   * This is useful in conjunction with the `defaultOpen` prop to create an initially open drawer.
+   */
+  defaultTriggerId?: string | null | undefined;
+  /**
+   * The content of the drawer.
+   */
+  children?: React.ReactNode | PayloadChildRenderFunction<Payload>;
+  /**
+   * The swipe direction used to dismiss the drawer.
+   * @default 'down'
+   */
+  swipeDirection?: DrawerSwipeDirection | undefined;
+  /**
+   * Snap points used to position the drawer.
+   * Use numbers between 0 and 1 to represent fractions of the viewport height,
+   * numbers greater than 1 as pixel values, or strings in `px`/`rem` units
+   * (for example, `'148px'` or `'30rem'`).
+   */
+  snapPoints?: DrawerSnapPoint[] | undefined;
+  /**
+   * Disables velocity-based snap skipping so drag distance determines the next snap point.
+   * @default false
+   */
+  snapToSequentialPoints?: boolean | undefined;
+  /**
+   * The currently active snap point. Use with `onSnapPointChange` to control the snap point.
+   */
+  snapPoint?: DrawerSnapPoint | null | undefined;
+  /**
+   * The initial snap point value when uncontrolled.
+   */
+  defaultSnapPoint?: DrawerSnapPoint | null | undefined;
+  /**
+   * Callback fired when the snap point changes.
+   */
+  onSnapPointChange?: ((snapPoint: DrawerSnapPoint | null, eventDetails: DrawerRoot.SnapPointChangeEventDetails) => void) | undefined;
+}
+export interface DrawerRootActions {
+  unmount: () => void;
+  close: () => void;
+}
+export type DrawerRootChangeEventReason = typeof REASONS.triggerPress | typeof REASONS.outsidePress | typeof REASONS.escapeKey | typeof REASONS.closeWatcher | typeof REASONS.closePress | typeof REASONS.focusOut | typeof REASONS.imperativeAction | typeof REASONS.swipe | typeof REASONS.none;
+export type DrawerRootChangeEventDetails = BaseUIChangeEventDetails<DrawerRoot.ChangeEventReason> & {
+  preventUnmountOnClose(): void;
+};
+export type DrawerRootSnapPointChangeEventReason = DrawerRootChangeEventReason;
+export type DrawerRootSnapPointChangeEventDetails = BaseUIChangeEventDetails<DrawerRootSnapPointChangeEventReason>;
+export declare namespace DrawerRoot {
+  type State = DrawerRootState;
+  type Props<Payload = unknown> = DrawerRootProps<Payload>;
+  type Actions = DrawerRootActions;
+  type ChangeEventReason = DrawerRootChangeEventReason;
+  type ChangeEventDetails = DrawerRootChangeEventDetails;
+  type SnapPointChangeEventReason = DrawerRootSnapPointChangeEventReason;
+  type SnapPointChangeEventDetails = DrawerRootSnapPointChangeEventDetails;
+  type SnapPoint = DrawerSnapPoint;
+}

package/drawer/root/DrawerRoot.d.ts

@@ -41,15 +41,15 @@ export interface DrawerRootProps<Payload = unknown> {
    */
   onOpenChangeComplete?: ((open: boolean) => void) | undefined;
   /**
-   * Determines whether the drawer should close on outside clicks.
+   * Whether to prevent the drawer from closing on outside presses.
+   * For non-modal drawers, this also prevents the drawer from closing when focus moves outside of it.
    * @default false
    */
   disablePointerDismissal?: boolean | undefined;
   /**
    * A ref to imperative actions.
-   * - `unmount`: When specified, the drawer will not be unmounted when closed.
-   * Instead, the `unmount` function must be called to unmount the drawer manually.
-   * Useful when the drawer's animation is controlled by an external library.
+   * - `unmount`: Manually unmounts the drawer.
+   * Call this after any externally controlled closing animation finishes.
    * - `close`: Closes the drawer imperatively when called.
    */
   actionsRef?: React.RefObject<DrawerRoot.Actions | null> | undefined;