@box/blueprint-web 18.2.2 → 18.3.0

package/dist/lib-esm/large-list-item/types.d.ts

@@ -5,7 +5,7 @@ export type LargeListSubtitleProps = BaseGridListSubtitleProps;
 export type LargeListDescriptionProps = BaseGridListDescriptionProps;
 export type LargeListActionsProps = BaseGridListActionsProps;
 export type LargeListActionIconButtonProps = BaseGridListActionIconButtonProps;
-export type LargeListProps = Omit<BaseGridListProps, 'layoutStyle'>;
+export type LargeListProps = Omit<BaseGridListProps, 'layoutStyle' | 'selectionVisibility'>;
 export type LargeListItemProps = BaseGridListItemProps;
 export interface LargeListSnippetProps {
     /** Regular expression pattern to be highlighted in snippetText */

package/dist/lib-esm/modal/constants.d.ts

@@ -1 +1,2 @@
 export declare const MODAL_LOADING_ANIMATION_DURATION = 200;
+export declare const MODAL_SMALL_VIEWPORT_MAX_WIDTH = 459;

package/dist/lib-esm/modal/constants.js

@@ -1,3 +1,5 @@
 const MODAL_LOADING_ANIMATION_DURATION = 200; // 200ms
+// Mirrors the breakpoint at which Modal.Close switches to the small-utility variant
+const MODAL_SMALL_VIEWPORT_MAX_WIDTH = 459;
 
-export { MODAL_LOADING_ANIMATION_DURATION };
+export { MODAL_LOADING_ANIMATION_DURATION, MODAL_SMALL_VIEWPORT_MAX_WIDTH };

package/dist/lib-esm/modal/index.d.ts

@@ -1,4 +1,4 @@
 export { AlertModal } from './alert-modal';
 export type { AlertModalProps } from './alert-modal.types';
 export { Modal } from './modal';
-export type { ModalCloseProps, ModalContentProps, ModalHeaderProps, ModalHeaderTitleAddonRenderProps, ModalLoadingProps, ModalProps, ModalTriggerProps, } from './types';
+export type { ModalCloseProps, ModalContentProps, ModalHeaderActionProps, ModalHeaderActionsProps, ModalHeaderProps, ModalHeaderTitleAddonRenderProps, ModalLoadingProps, ModalProps, ModalTriggerProps, } from './types';

package/dist/lib-esm/modal/modal-header-actions.d.ts

@@ -0,0 +1,12 @@
+import { type ModalHeaderActionProps, type ModalHeaderActionsProps } from './types';
+/**
+ * Container for actions pinned next to Modal.Close. They are out of the header flow, so the header reserves space
+ * for them next to the title, for up to 2 Modal.Header.Action elements.
+ * Only the first action is shown on small viewports, so the second one must not be essential.
+ */
+export declare const ModalHeaderActions: ({ children }: ModalHeaderActionsProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Icon button rendered in Modal.Header.Actions. Like Modal.Close, it switches to the `small-utility` variant
+ * on small viewports. Can be wrapped in triggers using `asChild`, such as DropdownMenu.Trigger or Tooltip.
+ */
+export declare const ModalHeaderAction: import("react").ForwardRefExoticComponent<Omit<ModalHeaderActionProps, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/lib-esm/modal/modal-header-actions.js

@@ -0,0 +1,57 @@
+import { jsx } from 'react/jsx-runtime';
+import { forwardRef, useContext, createContext, Children, isValidElement } from 'react';
+import { IconButton } from '../primitives/icon-button/icon-button.js';
+import { useMedia } from '../utils/useMedia.js';
+import { MODAL_SMALL_VIEWPORT_MAX_WIDTH } from './constants.js';
+import styles from './modal.module.js';
+
+const MAX_HEADER_ACTIONS = 2;
+// Undefined outside of Modal.Header.Actions, to detect actions rendered without it
+const IsSmallViewportContext = /*#__PURE__*/createContext(undefined);
+/**
+ * Container for actions pinned next to Modal.Close. They are out of the header flow, so the header reserves space
+ * for them next to the title, for up to 2 Modal.Header.Action elements.
+ * Only the first action is shown on small viewports, so the second one must not be essential.
+ */
+const ModalHeaderActions = ({
+  children
+}) => {
+  const isSmallViewport = useMedia(`(max-width: ${MODAL_SMALL_VIEWPORT_MAX_WIDTH}px)`);
+  if (process.env.NODE_ENV !== 'production') {
+    const elementsCount = Children.toArray(children).filter(isValidElement).length;
+    if (elementsCount > MAX_HEADER_ACTIONS) {
+      // eslint-disable-next-line no-console
+      console.warn(`Modal.Header.Actions supports at most ${MAX_HEADER_ACTIONS} actions, as the title reserves space only for them. ` + `Received ${elementsCount}. Render a single "More options" action that opens a DropdownMenu instead.`);
+    }
+  }
+  return jsx(IsSmallViewportContext.Provider, {
+    value: isSmallViewport,
+    children: jsx("div", {
+      className: styles.modalHeaderActions,
+      children: children
+    })
+  });
+};
+/**
+ * Icon button rendered in Modal.Header.Actions. Like Modal.Close, it switches to the `small-utility` variant
+ * on small viewports. Can be wrapped in triggers using `asChild`, such as DropdownMenu.Trigger or Tooltip.
+ */
+const ModalHeaderAction = /*#__PURE__*/forwardRef((props, forwardedRef) => {
+  const isSmallViewport = useContext(IsSmallViewportContext);
+  if (process.env.NODE_ENV !== 'production' && isSmallViewport === undefined) {
+    // eslint-disable-next-line no-console
+    console.warn('Modal.Header.Action must be rendered inside Modal.Header.Actions, ' + 'which pins it next to Modal.Close and reserves space for it next to the title.');
+  }
+  return isSmallViewport ? jsx(IconButton, {
+    ...props,
+    ref: forwardedRef,
+    variant: "small-utility"
+  }) : jsx(IconButton, {
+    ...props,
+    ref: forwardedRef,
+    size: "large"
+  });
+});
+ModalHeaderAction.displayName = 'ModalHeaderAction';
+
+export { ModalHeaderAction, ModalHeaderActions };

package/dist/lib-esm/modal/modal-header.d.ts

@@ -1,5 +1,5 @@
 import { type ModalHeaderProps } from './types';
-/**
- * Header of the Modal
- */
-export declare const ModalHeader: import("react").ForwardRefExoticComponent<ModalHeaderProps & import("react").RefAttributes<HTMLHeadingElement>>;
+export declare const ModalHeader: import("react").ForwardRefExoticComponent<ModalHeaderProps & import("react").RefAttributes<HTMLHeadingElement>> & {
+    Action: import("react").ForwardRefExoticComponent<Omit<import("./types").ModalHeaderActionProps, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
+    Actions: ({ children }: import("./types").ModalHeaderActionsProps) => import("react/jsx-runtime").JSX.Element;
+};

package/dist/lib-esm/modal/modal-header.js

@@ -6,6 +6,7 @@ import { TooltipWrapper } from '../utils/TooltipWrapper.js';
 import { useIsEllipsized } from '../utils/useIsEllipsized.js';
 import { Text } from '../text/text.js';
 import { ModalDescription } from './modal-description.js';
+import { ModalHeaderActions, ModalHeaderAction } from './modal-header-actions.js';
 import { ModalTitle } from './modal-title.js';
 import styles from './modal.module.js';
 
@@ -35,7 +36,8 @@ const ModalHeaderTruncatableTitle = ({
 /**
  * Header of the Modal
  */
-const ModalHeader = /*#__PURE__*/forwardRef(({
+const ModalHeaderComponent = /*#__PURE__*/forwardRef(({
+  actions,
   backButton,
   children,
   className,
@@ -49,7 +51,8 @@ const ModalHeader = /*#__PURE__*/forwardRef(({
   const titleContainerRef = useRef(null);
   const headerClasses = clsx({
     [styles.headerDividerLine]: isScrolledUnderHeader,
-    [styles.modalHeaderWithAddon]: renderTitleAddon
+    [styles.modalHeaderWithAddon]: renderTitleAddon,
+    [styles.modalHeaderWithActions]: actions
   }, styles.modalHeader);
   const title = jsx(ModalTitle, {
     ...rest,
@@ -92,8 +95,12 @@ const ModalHeader = /*#__PURE__*/forwardRef(({
           })
         })
       })]
-    }) : title]
+    }) : title, actions]
   });
 });
+const ModalHeader = Object.assign(ModalHeaderComponent, {
+  Action: ModalHeaderAction,
+  Actions: ModalHeaderActions
+});
 
 export { ModalHeader };

package/dist/lib-esm/modal/modal.d.ts

@@ -50,7 +50,10 @@ export declare const Modal: (({ children, modal, ...props }: ModalProps) => impo
             startIcon?: import("../button/types").SvgIconComponent;
         }, "ref">) & import("react").RefAttributes<HTMLButtonElement>>;
     };
-    Header: import("react").ForwardRefExoticComponent<import("./types").ModalHeaderProps & import("react").RefAttributes<HTMLHeadingElement>>;
+    Header: import("react").ForwardRefExoticComponent<import("./types").ModalHeaderProps & import("react").RefAttributes<HTMLHeadingElement>> & {
+        Action: import("react").ForwardRefExoticComponent<Omit<import("./types").ModalHeaderActionProps, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
+        Actions: ({ children }: import("./types").ModalHeaderActionsProps) => import("react/jsx-runtime").JSX.Element;
+    };
     Loading: import("react").ForwardRefExoticComponent<import("./types").ModalLoadingProps & import("react").RefAttributes<HTMLDivElement>>;
     ScrollableContainer: import("react").ForwardRefExoticComponent<import("./types").ModalScrollableContainerProps & {
         'data-testid'?: string;

package/dist/lib-esm/modal/modal.module.js

@@ -1,4 +1,4 @@
 import '../index.css';
-var styles = {"overlay":"bp_modal_module_overlay--aa987","headerDividerLine":"bp_modal_module_headerDividerLine--aa987","footerDividerLine":"bp_modal_module_footerDividerLine--aa987","content":"bp_modal_module_content--aa987","smallSizeModal":"bp_modal_module_smallSizeModal--aa987","mediumSizeModal":"bp_modal_module_mediumSizeModal--aa987","largeSizeModal":"bp_modal_module_largeSizeModal--aa987","xlargeSizeModal":"bp_modal_module_xlargeSizeModal--aa987","loadingContainerActive":"bp_modal_module_loadingContainerActive--aa987","popup_bounce_in":"bp_modal_module_popup_bounce_in--aa987","bpModalEnter":"bp_modal_module_bpModalEnter--aa987","bpModalExit":"bp_modal_module_bpModalExit--aa987","scrollableContainer":"bp_modal_module_scrollableContainer--aa987","close":"bp_modal_module_close--aa987","onColor":"bp_modal_module_onColor--aa987","backButton":"bp_modal_module_backButton--aa987","modalHeader":"bp_modal_module_modalHeader--aa987","modalTitle":"bp_modal_module_modalTitle--aa987","modalHeaderWithAddon":"bp_modal_module_modalHeaderWithAddon--aa987","modalTitleWithAddon":"bp_modal_module_modalTitleWithAddon--aa987","modalTitleLabel":"bp_modal_module_modalTitleLabel--aa987","modalTitleAddon":"bp_modal_module_modalTitleAddon--aa987","modalTitleText":"bp_modal_module_modalTitleText--aa987","modalTitleWithSubtitle":"bp_modal_module_modalTitleWithSubtitle--aa987","body":"bp_modal_module_body--aa987","footer":"bp_modal_module_footer--aa987","footerButton":"bp_modal_module_footerButton--aa987","loadingContainer":"bp_modal_module_loadingContainer--aa987","loading":"bp_modal_module_loading--aa987","loadingOverlay":"bp_modal_module_loadingOverlay--aa987","loadingContent":"bp_modal_module_loadingContent--aa987","loadingContentVisible":"bp_modal_module_loadingContentVisible--aa987"};
+var styles = {"overlay":"bp_modal_module_overlay--ecdb9","headerDividerLine":"bp_modal_module_headerDividerLine--ecdb9","footerDividerLine":"bp_modal_module_footerDividerLine--ecdb9","content":"bp_modal_module_content--ecdb9","smallSizeModal":"bp_modal_module_smallSizeModal--ecdb9","mediumSizeModal":"bp_modal_module_mediumSizeModal--ecdb9","largeSizeModal":"bp_modal_module_largeSizeModal--ecdb9","xlargeSizeModal":"bp_modal_module_xlargeSizeModal--ecdb9","loadingContainerActive":"bp_modal_module_loadingContainerActive--ecdb9","popup_bounce_in":"bp_modal_module_popup_bounce_in--ecdb9","bpModalEnter":"bp_modal_module_bpModalEnter--ecdb9","bpModalExit":"bp_modal_module_bpModalExit--ecdb9","scrollableContainer":"bp_modal_module_scrollableContainer--ecdb9","close":"bp_modal_module_close--ecdb9","modalHeaderActions":"bp_modal_module_modalHeaderActions--ecdb9","onColor":"bp_modal_module_onColor--ecdb9","backButton":"bp_modal_module_backButton--ecdb9","modalHeader":"bp_modal_module_modalHeader--ecdb9","modalTitle":"bp_modal_module_modalTitle--ecdb9","modalHeaderWithActions":"bp_modal_module_modalHeaderWithActions--ecdb9","modalHeaderWithAddon":"bp_modal_module_modalHeaderWithAddon--ecdb9","modalTitleWithAddon":"bp_modal_module_modalTitleWithAddon--ecdb9","modalTitleLabel":"bp_modal_module_modalTitleLabel--ecdb9","modalTitleAddon":"bp_modal_module_modalTitleAddon--ecdb9","modalTitleText":"bp_modal_module_modalTitleText--ecdb9","modalTitleWithSubtitle":"bp_modal_module_modalTitleWithSubtitle--ecdb9","body":"bp_modal_module_body--ecdb9","footer":"bp_modal_module_footer--ecdb9","footerButton":"bp_modal_module_footerButton--ecdb9","loadingContainer":"bp_modal_module_loadingContainer--ecdb9","loading":"bp_modal_module_loading--ecdb9","loadingOverlay":"bp_modal_module_loadingOverlay--ecdb9","loadingContent":"bp_modal_module_loadingContent--ecdb9","loadingContentVisible":"bp_modal_module_loadingContentVisible--ecdb9"};
 
 export { styles as default };

package/dist/lib-esm/modal/types.d.ts

@@ -2,6 +2,7 @@ import { type DialogContentProps, type DialogDescriptionProps, type DialogPortal
 import { type FunctionComponent, type HTMLAttributes, type PropsWithChildren, type ReactElement, type ReactNode, type RefObject, type SVGProps } from 'react';
 import { type LoadingIndicatorProps } from '../loading-indicator/loading-indicator';
 import { type IconButtonProps } from '../primitives/icon-button';
+import { type IconButtonVariantsProps } from '../primitives/icon-button/types';
 export type ModalProps = DialogProps;
 /** The size of the modal content.
  * small: max-width: 460px
@@ -58,7 +59,18 @@ export interface ModalHeaderTitleAddonRenderProps {
     /** Ref to the title area container, for observing changes to its size. */
     containerRef: RefObject<HTMLDivElement>;
 }
+export interface ModalHeaderActionsProps {
+    /**
+     * Up to 2 Modal.Header.Action elements, which can be wrapped in triggers using `asChild`.
+     * Only the first one is shown on small viewports, so the second one must not be essential.
+     */
+    children: ReactNode;
+}
+/** The size and variant are set by Blueprint, to match Modal.Close. */
+export type ModalHeaderActionProps = Omit<IconButtonVariantsProps, 'size' | 'variant'>;
 export interface ModalHeaderProps extends HTMLAttributes<HTMLHeadingElement> {
+    /** Actions next to the Close button, rendered with Modal.Header.Actions. */
+    actions?: ReactNode;
     backButton?: ReactElement;
     /** Content of the Header element */
     children: ReactNode;

package/dist/lib-esm/primitives/notification/hooks/use-hover-focus-expand.d.ts

@@ -0,0 +1,17 @@
+import { type FocusEvent, type MouseEvent, type PointerEvent as ReactPointerEvent } from 'react';
+export interface HoverFocusExpandResult {
+    isExpanded: boolean;
+    stackRef: {
+        current: HTMLElement | null;
+    };
+    handleMouseEnter: () => void;
+    handleMouseLeave: (event: MouseEvent<HTMLElement>) => void;
+    handlePointerLeave: (event: ReactPointerEvent<HTMLElement>) => void;
+    handleFocus: (event: FocusEvent<HTMLElement>) => void;
+    handleBlur: (event: FocusEvent<HTMLElement>) => void;
+}
+/**
+ * Expanded/collapsed deck from hover (fine pointer), keyboard focus, or a pointer outside the stack.
+ * `canExpand` is false for a single toast; `isAnimationEnabled` false turns expansion off entirely.
+ */
+export declare const useHoverFocusExpand: (canExpand: boolean, isAnimationEnabled: boolean) => HoverFocusExpandResult;

package/dist/lib-esm/primitives/notification/hooks/use-hover-focus-expand.js

@@ -0,0 +1,85 @@
+import { useState, useRef, useEffect } from 'react';
+
+const FINE_POINTER_HOVER_QUERY = '(hover: hover) and (pointer: fine)';
+const canHoverWithFinePointer = () => typeof window !== 'undefined' && window.matchMedia(FINE_POINTER_HOVER_QUERY).matches;
+/** Blur pointer-focus on the toast (not `:focus-visible`) so TTL can restart on leave. */
+const releasePointerFocus = container => {
+  const {
+    activeElement
+  } = document;
+  if (container instanceof HTMLElement && activeElement instanceof HTMLElement && container.contains(activeElement) && !activeElement.matches(':focus-visible')) {
+    activeElement.blur();
+  }
+};
+/**
+ * Expanded/collapsed deck from hover (fine pointer), keyboard focus, or a pointer outside the stack.
+ * `canExpand` is false for a single toast; `isAnimationEnabled` false turns expansion off entirely.
+ */
+const useHoverFocusExpand = (canExpand, isAnimationEnabled) => {
+  const canExpandWhenAnimated = canExpand && isAnimationEnabled;
+  const [isExpanded, setIsExpanded] = useState(false);
+  const stackRef = useRef(null);
+  const isListExpanded = isExpanded && canExpandWhenAnimated;
+  useEffect(() => {
+    if (!canExpandWhenAnimated && isExpanded) {
+      setIsExpanded(false);
+    }
+  }, [canExpandWhenAnimated, isExpanded]);
+  useEffect(() => {
+    if (!isListExpanded) {
+      return undefined;
+    }
+    const handlePointerDownOutside = event => {
+      const stack = stackRef.current;
+      if (stack && event.target instanceof Node && !stack.contains(event.target)) {
+        setIsExpanded(false);
+      }
+    };
+    document.addEventListener('pointerdown', handlePointerDownOutside);
+    return () => document.removeEventListener('pointerdown', handlePointerDownOutside);
+  }, [isListExpanded]);
+  const expand = () => {
+    if (canExpandWhenAnimated) {
+      setIsExpanded(true);
+    }
+  };
+  return {
+    isExpanded: isListExpanded,
+    stackRef,
+    handleMouseEnter: () => {
+      if (canHoverWithFinePointer()) {
+        expand();
+      }
+    },
+    handlePointerLeave: event => {
+      // Fires on the viewport <ol> before Radix's wrapper `pointerleave`.
+      releasePointerFocus(event.currentTarget);
+    },
+    handleMouseLeave: event => {
+      const {
+        activeElement
+      } = document;
+      if (activeElement instanceof HTMLElement && event.currentTarget.contains(activeElement) && activeElement.matches(':focus-visible')) {
+        return;
+      }
+      releasePointerFocus(event.currentTarget);
+      setIsExpanded(false);
+    },
+    handleFocus: event => {
+      if (event.target instanceof HTMLElement && event.target.matches(':focus-visible')) {
+        expand();
+      }
+    },
+    handleBlur: event => {
+      if (event.currentTarget.contains(event.relatedTarget)) {
+        return;
+      }
+      if (canHoverWithFinePointer() && event.currentTarget.matches(':hover')) {
+        return;
+      }
+      setIsExpanded(false);
+    }
+  };
+};
+
+export { useHoverFocusExpand };

package/dist/lib-esm/primitives/notification/hooks/use-notification-exit-animation.d.ts

@@ -0,0 +1,21 @@
+import { type Dispatch, type SetStateAction, type TransitionEvent } from 'react';
+type SetOpen = Dispatch<SetStateAction<boolean | undefined>>;
+/**
+ * Defers `setOpen(false)` until the exit CSS transition finishes. `removeNotification`
+ * unmounts immediately, so without this the stack never gets a chance to reflow.
+ */
+export declare function useNotificationExitAnimation({ open, setOpen, isAnimationEnabled, onExitStart, }: {
+    open: boolean;
+    setOpen: SetOpen;
+    isAnimationEnabled: boolean;
+    /** Fires when exit begins so the stack can drop this layer from layout. */
+    onExitStart?: () => void;
+}): {
+    radixOpen: boolean;
+    isExiting: boolean;
+    hasExitStyles: boolean;
+    handleOpenChange: (nextOpen: boolean) => void;
+    completeExit: () => void;
+};
+export declare function handleNotificationExitTransitionEnd(event: TransitionEvent<HTMLElement>, isExiting: boolean, completeExit: () => void): void;
+export {};

package/dist/lib-esm/primitives/notification/hooks/use-notification-exit-animation.js

@@ -0,0 +1,141 @@
+import { bpDurationMedium } from '@box/blueprint-web-assets/tokens/tokens';
+import { useState, useRef, useCallback, useEffect } from 'react';
+import { noop } from '../../../utils/noop.js';
+import { prefersReducedMotion } from '../notification-stack-utils.js';
+
+const EXIT_DURATION_MS = Number.parseFloat(bpDurationMedium);
+/** Safety net only — primary completion is `transitionend` on opacity/transform. */
+const NOTIFICATION_EXIT_ANIMATION_FALLBACK_MS = EXIT_DURATION_MS + 50;
+const EXIT_TRANSITION_PROPERTIES = new Set(['opacity', 'transform']);
+/**
+ * Defers `setOpen(false)` until the exit CSS transition finishes. `removeNotification`
+ * unmounts immediately, so without this the stack never gets a chance to reflow.
+ */
+function useNotificationExitAnimation({
+  open,
+  setOpen,
+  isAnimationEnabled,
+  onExitStart
+}) {
+  const [isExiting, setIsExiting] = useState(false);
+  // Keep exit styles applied through the final unmount frame to avoid a visible flash.
+  const [hasExitStyles, setHasExitStyles] = useState(false);
+  const exitFallbackTimerRef = useRef(null);
+  const exitCommitRafRef = useRef(null);
+  const isExitingRef = useRef(isExiting);
+  isExitingRef.current = isExiting;
+  const clearExitTimers = useCallback(() => {
+    if (exitFallbackTimerRef.current !== null) {
+      clearTimeout(exitFallbackTimerRef.current);
+      exitFallbackTimerRef.current = null;
+    }
+    if (exitCommitRafRef.current !== null) {
+      cancelAnimationFrame(exitCommitRafRef.current);
+      exitCommitRafRef.current = null;
+    }
+  }, []);
+  const clearExitState = useCallback(() => {
+    clearExitTimers();
+    isExitingRef.current = false;
+    setIsExiting(false);
+    setHasExitStyles(false);
+  }, [clearExitTimers]);
+  useEffect(() => {
+    if (!isAnimationEnabled) {
+      const shouldCommit = isExitingRef.current || exitCommitRafRef.current !== null;
+      clearExitState();
+      if (shouldCommit) {
+        setOpen(false);
+      }
+    }
+  }, [clearExitState, isAnimationEnabled, setOpen]);
+  useEffect(() => {
+    if (!open && isExiting) {
+      clearExitState();
+    }
+  }, [clearExitState, isExiting, open]);
+  useEffect(() => () => clearExitTimers(), [clearExitTimers]);
+  const handleOpenChange = useCallback(nextOpen => {
+    if (!isAnimationEnabled) {
+      setOpen(nextOpen);
+      return;
+    }
+    if (nextOpen) {
+      clearExitState();
+      setOpen(true);
+      return;
+    }
+    if (isExiting) {
+      return;
+    }
+    // Reduced-motion CSS drops the transition, so `transitionend` would never fire.
+    if (open && !prefersReducedMotion()) {
+      setIsExiting(true);
+      setHasExitStyles(true);
+      onExitStart?.();
+      return;
+    }
+    setIsExiting(false);
+    setHasExitStyles(false);
+    setOpen(false);
+  }, [clearExitState, isAnimationEnabled, isExiting, onExitStart, open, setOpen]);
+  const completeExit = useCallback(() => {
+    if (!isAnimationEnabled || !isExitingRef.current) {
+      return;
+    }
+    clearExitTimers();
+    isExitingRef.current = false;
+    setIsExiting(false);
+    // Next frame so opacity/transform paint before Radix unmounts.
+    exitCommitRafRef.current = requestAnimationFrame(() => {
+      exitCommitRafRef.current = null;
+      setOpen(false);
+      setHasExitStyles(false);
+    });
+  }, [clearExitTimers, isAnimationEnabled, setOpen]);
+  const completeExitRef = useRef(completeExit);
+  completeExitRef.current = completeExit;
+  useEffect(() => {
+    if (!isAnimationEnabled || !isExiting) {
+      return undefined;
+    }
+    clearExitTimers();
+    exitFallbackTimerRef.current = setTimeout(() => {
+      exitFallbackTimerRef.current = null;
+      completeExitRef.current();
+    }, NOTIFICATION_EXIT_ANIMATION_FALLBACK_MS);
+    return () => {
+      if (exitFallbackTimerRef.current !== null) {
+        clearTimeout(exitFallbackTimerRef.current);
+        exitFallbackTimerRef.current = null;
+      }
+    };
+  }, [clearExitTimers, isAnimationEnabled, isExiting]);
+  if (!isAnimationEnabled) {
+    return {
+      radixOpen: open,
+      isExiting: false,
+      hasExitStyles: false,
+      handleOpenChange: setOpen,
+      completeExit: noop
+    };
+  }
+  return {
+    radixOpen: isExiting ? true : open,
+    isExiting,
+    hasExitStyles,
+    handleOpenChange,
+    completeExit
+  };
+}
+function handleNotificationExitTransitionEnd(event, isExiting, completeExit) {
+  if (event.target !== event.currentTarget || !isExiting || event.type === 'transitioncancel') {
+    return;
+  }
+  if (!EXIT_TRANSITION_PROPERTIES.has(event.propertyName)) {
+    return;
+  }
+  completeExit();
+}
+
+export { handleNotificationExitTransitionEnd, useNotificationExitAnimation };

package/dist/lib-esm/primitives/notification/hooks/use-stack-layer-metrics.d.ts

@@ -0,0 +1,19 @@
+export interface StackMetrics {
+    offsets: number[];
+    collapsedHeight: number;
+    expandedHeight: number;
+}
+interface StackLayerMetricsResult {
+    metrics: StackMetrics;
+    getLayerRef: (depth: number) => (node: HTMLLIElement | null) => void;
+}
+/**
+ * Measures each layer's height so the deck can report collapsed (peek) vs expanded (full list)
+ * size, and re-measures on resize. `depthOffsetPx`/`gapPx` are injected so this stays token-agnostic.
+ *
+ * Layers are observed from their ref callbacks, not from an effect keyed on `layerCount`:
+ * Radix portals toast content only once the viewport node is known, so layer nodes can attach
+ * (or be replaced) a commit after the count changed.
+ */
+export declare const useStackLayerMetrics: (layerCount: number, depthOffsetPx: number, gapPx: number) => StackLayerMetricsResult;
+export {};

package/dist/lib-esm/primitives/notification/hooks/use-stack-layer-metrics.js

@@ -0,0 +1,96 @@
+import { useState, useRef, useLayoutEffect } from 'react';
+import { NOTIFICATION_STACK_VISIBLE_DEPTH } from '../notification-stack-utils.js';
+
+const emptyMetrics = {
+  offsets: [],
+  collapsedHeight: 0,
+  expandedHeight: 0
+};
+const metricsEqual = (left, right) => left.collapsedHeight === right.collapsedHeight && left.expandedHeight === right.expandedHeight && left.offsets.length === right.offsets.length && left.offsets.every((value, index) => value === right.offsets[index]);
+/**
+ * Measures each layer's height so the deck can report collapsed (peek) vs expanded (full list)
+ * size, and re-measures on resize. `depthOffsetPx`/`gapPx` are injected so this stays token-agnostic.
+ *
+ * Layers are observed from their ref callbacks, not from an effect keyed on `layerCount`:
+ * Radix portals toast content only once the viewport node is known, so layer nodes can attach
+ * (or be replaced) a commit after the count changed.
+ */
+const useStackLayerMetrics = (layerCount, depthOffsetPx, gapPx) => {
+  const [metrics, setMetrics] = useState(emptyMetrics);
+  const layerRefs = useRef([]);
+  const layerRefCallbacks = useRef(new Map());
+  const observerRef = useRef(null);
+  const measureRef = useRef(() => undefined);
+  measureRef.current = () => {
+    const heights = layerRefs.current.slice(0, layerCount).map(node => node?.offsetHeight ?? 0);
+    let cumulative = 0;
+    const offsets = heights.map(height => {
+      const offset = cumulative;
+      cumulative += height + gapPx;
+      return offset;
+    });
+    const collapsedVisible = Math.min(layerCount, NOTIFICATION_STACK_VISIBLE_DEPTH);
+    setMetrics(previous => {
+      const nextMetrics = {
+        offsets,
+        collapsedHeight: (heights[0] ?? 0) + Math.max(0, collapsedVisible - 1) * depthOffsetPx,
+        expandedHeight: Math.max(0, cumulative - gapPx)
+      };
+      return metricsEqual(previous, nextMetrics) ? previous : nextMetrics;
+    });
+  };
+  const getLayerRef = depth => {
+    let callback = layerRefCallbacks.current.get(depth);
+    if (!callback) {
+      callback = node => {
+        const previous = layerRefs.current[depth];
+        if (previous === node) {
+          return;
+        }
+        const observer = observerRef.current;
+        const isPreviousStillLayer = layerRefs.current.some((other, index) => index !== depth && other === previous);
+        if (previous && observer && !isPreviousStillLayer) {
+          observer.unobserve(previous);
+        }
+        layerRefs.current[depth] = node;
+        if (!node) {
+          return;
+        }
+        // ResizeObserver reports the initial size on observe; without it, measure now.
+        if (observer) {
+          observer.observe(node);
+        } else {
+          measureRef.current();
+        }
+      };
+      layerRefCallbacks.current.set(depth, callback);
+    }
+    return callback;
+  };
+  useLayoutEffect(() => {
+    if (typeof ResizeObserver === 'undefined') {
+      return undefined;
+    }
+    const observer = new ResizeObserver(() => measureRef.current());
+    observerRef.current = observer;
+    layerRefs.current.forEach(node => {
+      if (node) {
+        observer.observe(node);
+      }
+    });
+    return () => {
+      observer.disconnect();
+      observerRef.current = null;
+    };
+  }, []);
+  useLayoutEffect(() => {
+    layerRefs.current.length = layerCount;
+    measureRef.current();
+  }, [layerCount, depthOffsetPx, gapPx]);
+  return {
+    metrics,
+    getLayerRef
+  };
+};
+
+export { useStackLayerMetrics };

package/dist/lib-esm/primitives/notification/hooks/use-staggered-notification-admission.d.ts

@@ -0,0 +1,10 @@
+export interface AdmissionResult<TValue> {
+    visibleNotifications: Map<string, TValue> | undefined;
+    enteringId: string | null;
+}
+/**
+ * Admits burst arrivals one at a time (`NOTIFICATION_STACK_STAGGER_MS` apart), in the
+ * iteration order of `notifications` — pass it oldest-first so the newest lands on top last.
+ * First-mount ids, `isAnimationEnabled === false`, and `prefers-reduced-motion` skip the stagger.
+ */
+export declare const useStaggeredNotificationAdmission: <TValue>(notifications: Map<string, TValue> | undefined, isAnimationEnabled: boolean) => AdmissionResult<TValue>;