@trackunit/react-drawer 2.6.71 → 2.6.73

package/index.cjs.js

@@ -308,7 +308,7 @@ const PANEL_FOCUSABLE_SELECTOR = [
  * ```
  * @param {DrawerProps} props - The props for the Drawer component
  */
-const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, children, "data-testid": dataTestId, className, renderInPortal = false, containerClassName, ariaLabel, ariaLabelledBy, }) => {
+const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, children, "data-testid": dataTestId, className, renderInPortal = false, containerClassName, ariaLabel, ariaLabelledBy, onExitComplete, }) => {
     const { isSm } = reactComponents.useViewportBreakpoints();
     const shouldUsePortal = !isSm || renderInPortal;
     const panelRef = react.useRef(null);
@@ -316,6 +316,10 @@ const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, children, "d
     // the portal (or first paint) has attached the DOM node — refs alone do not.
     const [panelElement, setPanelElement] = react.useState(null);
     const isOpenRef = react.useRef(isOpen);
+    const onExitCompleteRef = react.useRef(onExitComplete);
+    // Guards against firing onExitComplete twice for the same close cycle if the real
+    // transitionend and the headless RAF fallback both resolve the same exit-complete.
+    const hasFiredExitCompleteRef = react.useRef(false);
     const [drawerState, dispatch] = react.useReducer(drawerAnimationReducer, {
         ...INITIAL_DRAWER_ANIMATION_STATE,
         // Mount off-screen when initially open so the enter slide still plays.
@@ -325,7 +329,22 @@ const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, children, "d
     react.useEffect(() => {
         isOpenRef.current = isOpen;
     }, [isOpen]);
+    react.useEffect(() => {
+        onExitCompleteRef.current = onExitComplete;
+    }, [onExitComplete]);
+    const fireExitComplete = react.useCallback(() => {
+        if (hasFiredExitCompleteRef.current) {
+            return;
+        }
+        hasFiredExitCompleteRef.current = true;
+        onExitCompleteRef.current?.();
+    }, []);
     react.useLayoutEffect(() => {
+        if (!isOpen) {
+            // A new close cycle is starting — arm the guard so this cycle's genuine
+            // exit-complete (real transitionend or headless RAF fallback) can fire.
+            hasFiredExitCompleteRef.current = false;
+        }
         dispatch({ type: isOpen ? "open" : "close" });
     }, [isOpen]);
     // Defer the open flip until after paint. A single useLayoutEffect flip commits
@@ -360,9 +379,23 @@ const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, children, "d
             const runningAnimations = typeof panelNode.getAnimations === "function" ? panelNode.getAnimations() : [];
             if (runningAnimations.length === 0) {
                 dispatch({ type: "transitionEnd" });
+                fireExitComplete();
             }
         });
         return () => cancelAnimationFrame(rafId);
+    }, [drawerState.mode, drawerState.shouldRender, fireExitComplete]);
+    // If transitionend is suppressed while a CSS animation is reported as running
+    // (Playwright/iframe), unmount after the motion duration so close cannot stick.
+    react.useEffect(() => {
+        if (drawerState.mode !== "closed" || !drawerState.shouldRender) {
+            return;
+        }
+        const timeoutId = window.setTimeout(() => {
+            if (!isOpenRef.current) {
+                dispatch({ type: "transitionEnd" });
+            }
+        }, DRAWER_TRANSITION_DURATION_MS + 50);
+        return () => window.clearTimeout(timeoutId);
     }, [drawerState.mode, drawerState.shouldRender]);
     // If transitionend is suppressed, settle enter after the motion duration so focus
     // still activates. Do not use a zero-delay rAF here — getAnimations() can be empty
@@ -405,9 +438,20 @@ const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, children, "d
             return;
         }
         if (transitionEvent.propertyName === "transform") {
+            // A transform transitionend while mode is still "closed" but isOpen has already
+            // flipped back to true is an interrupted exit (the reopen's openVisual is still
+            // behind its double-rAF), not an exit-complete. Same guard the headless rAF
+            // fallback above already applies.
+            if (drawerState.mode === "closed" && isOpenRef.current) {
+                return;
+            }
+            const isGenuineExitComplete = drawerState.mode === "closed";
             dispatch({ type: "transitionEnd" });
+            if (isGenuineExitComplete) {
+                fireExitComplete();
+            }
         }
-    }, []);
+    }, [drawerState.mode, fireExitComplete]);
     if (!drawerState.shouldRender) {
         return null;
     }
@@ -477,6 +521,48 @@ const useDrawer = (props) => {
     }), [dismissProp]);
     const [internalIsOpen, setIsOpen] = react.useState(defaultOpen ?? false);
     const isOpen = typeof controlledIsOpen === "boolean" ? controlledIsOpen : internalIsOpen;
+    // `false` initially / whenever never opened. Flips to `true` the moment the
+    // resolved `isOpen` value above transitions `true -> false`, and back to
+    // `false` either when it transitions `false -> true` again or once Drawer's
+    // `onExitComplete` signals the panel has genuinely finished exiting
+    // (`handleExitComplete`). See `UseDrawerReturnValue.isExiting`.
+    const [isExiting, setIsExiting] = react.useState(false);
+    // Tracks the resolved `isOpen` value as of the last render for which
+    // `isExiting` was derived below, so the render-phase check can detect a
+    // transition without an effect.
+    const [prevIsOpen, setPrevIsOpen] = react.useState(isOpen);
+    // Derive `isExiting` from the resolved `isOpen` value's own transitions —
+    // the same value used everywhere else in this hook — rather than only from
+    // the imperative `close()` / `open()` call sites below. This is what covers
+    // a controlled consumer flipping the `isOpen` prop directly (the documented
+    // `useDrawer({ isOpen: Boolean(selectedId) })` pattern): `close()` / `open()`
+    // alone only ever observe imperative calls, not a controlled prop changing
+    // for some other reason (e.g. selecting a different row).
+    //
+    // This calls `setState` conditionally during the render body — React's
+    // "adjust state during render" pattern
+    // (https://react.dev/learn/you-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes)
+    // — rather than a passive `useEffect` (e.g. `useWatch`). A passive effect
+    // only runs one commit AFTER the render where `isOpen` changes, leaving an
+    // intermediate commit where `isOpen` has already changed but `isExiting`
+    // hasn't yet. `useHold` — `isExiting`'s primary documented consumer — reads
+    // both in its own effect and would observe that stale `isExiting: false`
+    // there, permanently overwriting its held ref with the already-changed
+    // value before `isExiting` ever flips `true`. Calling `setState` here
+    // instead makes React detect the change and re-render immediately, before
+    // committing or running any effects, so `isOpen` and `isExiting` always
+    // land together in the same effective commit that `useHold` observes.
+    //
+    // `handleExitComplete` (below) is a second, separate way `isExiting` flips
+    // back to `false` — the normal close -> fully-exited path. It never fights
+    // with this derivation: by the time it fires, `isOpen` has already settled
+    // to `false` and `prevIsOpen` has already caught up to it (from the render
+    // that flipped `isExiting` to `true` in the first place), so `isOpen ===
+    // prevIsOpen` and this block is a no-op on the next render either way.
+    if (isOpen !== prevIsOpen) {
+        setPrevIsOpen(isOpen);
+        setIsExiting(!isOpen); // true when transitioning to closed, false when transitioning to open
+    }
     const isPendingCloseRef = react.useRef(false);
     const onCloseRef = react.useRef(onClose);
     const onOpenRef = react.useRef(onOpen);
@@ -493,6 +579,11 @@ const useDrawer = (props) => {
         onCloseRef.current?.(event, reason);
         onOpenChangeRef.current?.(false, event, reason);
     }, []);
+    // Fired by `Drawer`'s internal `onExitComplete` prop exactly once per genuine
+    // close→fully-exited cycle — the normal path back to `isExiting: false`.
+    const handleExitComplete = react.useCallback(() => {
+        setIsExiting(false);
+    }, []);
     const requestClose = react.useCallback((event, reason) => {
         if (onBeforeCloseRef.current) {
             if (isPendingCloseRef.current) {
@@ -517,6 +608,12 @@ const useDrawer = (props) => {
         onOpenRef.current?.();
         onOpenChangeRef.current?.(true);
         setIsOpen(true);
+        // `isExiting` releases automatically here via the render-phase derivation
+        // above (the resolved `isOpen` transitioning back to `true`) — a reopen
+        // before the exit signal fires releases any hold right away, since the
+        // interrupted exit's transitionend resolves as an enter-settle, so
+        // `onExitComplete` correctly never fires for that cycle. See
+        // `UseDrawerReturnValue.isExiting`.
     }, []);
     const toggle = react.useCallback(() => {
         if (isOpen) {
@@ -551,7 +648,21 @@ const useDrawer = (props) => {
         trapFocus,
         position,
         floatingUi,
-    }), [isOpen, open, close, toggle, requestClose, variant, trapFocus, position, floatingUi]);
+        isExiting,
+        onExitComplete: handleExitComplete,
+    }), [
+        isOpen,
+        open,
+        close,
+        toggle,
+        requestClose,
+        variant,
+        trapFocus,
+        position,
+        floatingUi,
+        isExiting,
+        handleExitComplete,
+    ]);
 };
 
 /**

package/index.esm.js

@@ -2,7 +2,7 @@ import { jsx, jsxs } from 'react/jsx-runtime';
 import { registerTranslations, useNamespaceTranslation } from '@trackunit/i18n-library-translation';
 import { useMergeRefs, FloatingFocusManager, useFloating, useDismiss, useInteractions } from '@floating-ui/react';
 import { useViewportBreakpoints, Portal, IconButton, Icon, MoreMenu } from '@trackunit/react-components';
-import { useRef, useState, useReducer, useEffect, useLayoutEffect, useCallback, useMemo } from 'react';
+import { useRef, useState, useReducer, useEffect, useCallback, useLayoutEffect, useMemo } from 'react';
 import { cva } from '@trackunit/css-class-variance-utilities';
 import { twMerge } from 'tailwind-merge';
 
@@ -306,7 +306,7 @@ const PANEL_FOCUSABLE_SELECTOR = [
  * ```
  * @param {DrawerProps} props - The props for the Drawer component
  */
-const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, children, "data-testid": dataTestId, className, renderInPortal = false, containerClassName, ariaLabel, ariaLabelledBy, }) => {
+const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, children, "data-testid": dataTestId, className, renderInPortal = false, containerClassName, ariaLabel, ariaLabelledBy, onExitComplete, }) => {
     const { isSm } = useViewportBreakpoints();
     const shouldUsePortal = !isSm || renderInPortal;
     const panelRef = useRef(null);
@@ -314,6 +314,10 @@ const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, children, "d
     // the portal (or first paint) has attached the DOM node — refs alone do not.
     const [panelElement, setPanelElement] = useState(null);
     const isOpenRef = useRef(isOpen);
+    const onExitCompleteRef = useRef(onExitComplete);
+    // Guards against firing onExitComplete twice for the same close cycle if the real
+    // transitionend and the headless RAF fallback both resolve the same exit-complete.
+    const hasFiredExitCompleteRef = useRef(false);
     const [drawerState, dispatch] = useReducer(drawerAnimationReducer, {
         ...INITIAL_DRAWER_ANIMATION_STATE,
         // Mount off-screen when initially open so the enter slide still plays.
@@ -323,7 +327,22 @@ const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, children, "d
     useEffect(() => {
         isOpenRef.current = isOpen;
     }, [isOpen]);
+    useEffect(() => {
+        onExitCompleteRef.current = onExitComplete;
+    }, [onExitComplete]);
+    const fireExitComplete = useCallback(() => {
+        if (hasFiredExitCompleteRef.current) {
+            return;
+        }
+        hasFiredExitCompleteRef.current = true;
+        onExitCompleteRef.current?.();
+    }, []);
     useLayoutEffect(() => {
+        if (!isOpen) {
+            // A new close cycle is starting — arm the guard so this cycle's genuine
+            // exit-complete (real transitionend or headless RAF fallback) can fire.
+            hasFiredExitCompleteRef.current = false;
+        }
         dispatch({ type: isOpen ? "open" : "close" });
     }, [isOpen]);
     // Defer the open flip until after paint. A single useLayoutEffect flip commits
@@ -358,9 +377,23 @@ const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, children, "d
             const runningAnimations = typeof panelNode.getAnimations === "function" ? panelNode.getAnimations() : [];
             if (runningAnimations.length === 0) {
                 dispatch({ type: "transitionEnd" });
+                fireExitComplete();
             }
         });
         return () => cancelAnimationFrame(rafId);
+    }, [drawerState.mode, drawerState.shouldRender, fireExitComplete]);
+    // If transitionend is suppressed while a CSS animation is reported as running
+    // (Playwright/iframe), unmount after the motion duration so close cannot stick.
+    useEffect(() => {
+        if (drawerState.mode !== "closed" || !drawerState.shouldRender) {
+            return;
+        }
+        const timeoutId = window.setTimeout(() => {
+            if (!isOpenRef.current) {
+                dispatch({ type: "transitionEnd" });
+            }
+        }, DRAWER_TRANSITION_DURATION_MS + 50);
+        return () => window.clearTimeout(timeoutId);
     }, [drawerState.mode, drawerState.shouldRender]);
     // If transitionend is suppressed, settle enter after the motion duration so focus
     // still activates. Do not use a zero-delay rAF here — getAnimations() can be empty
@@ -403,9 +436,20 @@ const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, children, "d
             return;
         }
         if (transitionEvent.propertyName === "transform") {
+            // A transform transitionend while mode is still "closed" but isOpen has already
+            // flipped back to true is an interrupted exit (the reopen's openVisual is still
+            // behind its double-rAF), not an exit-complete. Same guard the headless rAF
+            // fallback above already applies.
+            if (drawerState.mode === "closed" && isOpenRef.current) {
+                return;
+            }
+            const isGenuineExitComplete = drawerState.mode === "closed";
             dispatch({ type: "transitionEnd" });
+            if (isGenuineExitComplete) {
+                fireExitComplete();
+            }
         }
-    }, []);
+    }, [drawerState.mode, fireExitComplete]);
     if (!drawerState.shouldRender) {
         return null;
     }
@@ -475,6 +519,48 @@ const useDrawer = (props) => {
     }), [dismissProp]);
     const [internalIsOpen, setIsOpen] = useState(defaultOpen ?? false);
     const isOpen = typeof controlledIsOpen === "boolean" ? controlledIsOpen : internalIsOpen;
+    // `false` initially / whenever never opened. Flips to `true` the moment the
+    // resolved `isOpen` value above transitions `true -> false`, and back to
+    // `false` either when it transitions `false -> true` again or once Drawer's
+    // `onExitComplete` signals the panel has genuinely finished exiting
+    // (`handleExitComplete`). See `UseDrawerReturnValue.isExiting`.
+    const [isExiting, setIsExiting] = useState(false);
+    // Tracks the resolved `isOpen` value as of the last render for which
+    // `isExiting` was derived below, so the render-phase check can detect a
+    // transition without an effect.
+    const [prevIsOpen, setPrevIsOpen] = useState(isOpen);
+    // Derive `isExiting` from the resolved `isOpen` value's own transitions —
+    // the same value used everywhere else in this hook — rather than only from
+    // the imperative `close()` / `open()` call sites below. This is what covers
+    // a controlled consumer flipping the `isOpen` prop directly (the documented
+    // `useDrawer({ isOpen: Boolean(selectedId) })` pattern): `close()` / `open()`
+    // alone only ever observe imperative calls, not a controlled prop changing
+    // for some other reason (e.g. selecting a different row).
+    //
+    // This calls `setState` conditionally during the render body — React's
+    // "adjust state during render" pattern
+    // (https://react.dev/learn/you-might-not-need-an-effect#adjusting-some-state-when-a-prop-changes)
+    // — rather than a passive `useEffect` (e.g. `useWatch`). A passive effect
+    // only runs one commit AFTER the render where `isOpen` changes, leaving an
+    // intermediate commit where `isOpen` has already changed but `isExiting`
+    // hasn't yet. `useHold` — `isExiting`'s primary documented consumer — reads
+    // both in its own effect and would observe that stale `isExiting: false`
+    // there, permanently overwriting its held ref with the already-changed
+    // value before `isExiting` ever flips `true`. Calling `setState` here
+    // instead makes React detect the change and re-render immediately, before
+    // committing or running any effects, so `isOpen` and `isExiting` always
+    // land together in the same effective commit that `useHold` observes.
+    //
+    // `handleExitComplete` (below) is a second, separate way `isExiting` flips
+    // back to `false` — the normal close -> fully-exited path. It never fights
+    // with this derivation: by the time it fires, `isOpen` has already settled
+    // to `false` and `prevIsOpen` has already caught up to it (from the render
+    // that flipped `isExiting` to `true` in the first place), so `isOpen ===
+    // prevIsOpen` and this block is a no-op on the next render either way.
+    if (isOpen !== prevIsOpen) {
+        setPrevIsOpen(isOpen);
+        setIsExiting(!isOpen); // true when transitioning to closed, false when transitioning to open
+    }
     const isPendingCloseRef = useRef(false);
     const onCloseRef = useRef(onClose);
     const onOpenRef = useRef(onOpen);
@@ -491,6 +577,11 @@ const useDrawer = (props) => {
         onCloseRef.current?.(event, reason);
         onOpenChangeRef.current?.(false, event, reason);
     }, []);
+    // Fired by `Drawer`'s internal `onExitComplete` prop exactly once per genuine
+    // close→fully-exited cycle — the normal path back to `isExiting: false`.
+    const handleExitComplete = useCallback(() => {
+        setIsExiting(false);
+    }, []);
     const requestClose = useCallback((event, reason) => {
         if (onBeforeCloseRef.current) {
             if (isPendingCloseRef.current) {
@@ -515,6 +606,12 @@ const useDrawer = (props) => {
         onOpenRef.current?.();
         onOpenChangeRef.current?.(true);
         setIsOpen(true);
+        // `isExiting` releases automatically here via the render-phase derivation
+        // above (the resolved `isOpen` transitioning back to `true`) — a reopen
+        // before the exit signal fires releases any hold right away, since the
+        // interrupted exit's transitionend resolves as an enter-settle, so
+        // `onExitComplete` correctly never fires for that cycle. See
+        // `UseDrawerReturnValue.isExiting`.
     }, []);
     const toggle = useCallback(() => {
         if (isOpen) {
@@ -549,7 +646,21 @@ const useDrawer = (props) => {
         trapFocus,
         position,
         floatingUi,
-    }), [isOpen, open, close, toggle, requestClose, variant, trapFocus, position, floatingUi]);
+        isExiting,
+        onExitComplete: handleExitComplete,
+    }), [
+        isOpen,
+        open,
+        close,
+        toggle,
+        requestClose,
+        variant,
+        trapFocus,
+        position,
+        floatingUi,
+        isExiting,
+        handleExitComplete,
+    ]);
 };
 
 /**

package/migrations/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../../../../libs/react/drawer/migrations/entry.ts"],"names":[],"mappings":"","sourcesContent":["export {};\n"]}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@trackunit/react-drawer",
-  "version": "2.6.71",
+  "version": "2.6.73",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "2.13.24",
+    "@trackunit/react-components": "2.13.25",
     "@trackunit/css-class-variance-utilities": "2.0.14",
     "@trackunit/i18n-library-translation": "2.4.63",
     "@floating-ui/react": "^0.26.25",

package/src/components/Drawer/Drawer.d.ts

@@ -73,6 +73,17 @@ export interface DrawerProps extends CommonProps {
      * the drawer body renders a visible heading so the two stay in sync.
      */
     ariaLabelledBy?: string;
+    /**
+     * Internal signal fired exactly once per genuine open→close→fully-exited cycle,
+     * once the panel has actually finished animating (or would have, in headless /
+     * test environments where CSS transitions are suppressed) off-screen. Spread from
+     * `useDrawer()`, which uses it to flip its `isExiting` state back to `false`.
+     *
+     * Does not fire for the enter-settle transitionend, on initial mount, while
+     * remaining closed, or more than once for the same close cycle even if both the
+     * real `transitionend` and the headless RAF fallback resolve it.
+     */
+    readonly onExitComplete?: () => void;
 }
 /**
  * Drawers slide in from the left or right edge of the viewport as either a modal
@@ -135,6 +146,6 @@ export interface DrawerProps extends CommonProps {
  * @param {DrawerProps} props - The props for the Drawer component
  */
 export declare const Drawer: {
-    ({ isOpen, variant, trapFocus, position, floatingUi, children, "data-testid": dataTestId, className, renderInPortal, containerClassName, ariaLabel, ariaLabelledBy, }: DrawerProps): ReactElement | null;
+    ({ isOpen, variant, trapFocus, position, floatingUi, children, "data-testid": dataTestId, className, renderInPortal, containerClassName, ariaLabel, ariaLabelledBy, onExitComplete, }: DrawerProps): ReactElement | null;
     displayName: string;
 };

package/src/components/Drawer/useDrawer.d.ts

@@ -98,6 +98,33 @@ export type UseDrawerReturnValue = {
      * its `FloatingFocusManager`.
      */
     readonly floatingUi: DrawerFloatingUiProps;
+    /**
+     * Whether the drawer is currently in its close→fully-exited cycle. `false`
+     * initially and whenever the drawer has never been opened.
+     *
+     * Derived from the resolved `isOpen` value's own transitions (the same value
+     * used everywhere else in the hook — `controlledIsOpen ?? internalIsOpen`),
+     * not merely from the imperative `open()` / `close()` call sites. Flips to
+     * `true` the moment `isOpen` transitions `true -> false` — whether via
+     * `close()` / `requestClose()` committing (after any `onBeforeClose` guard
+     * has resolved `true`) or a controlled consumer flipping its `isOpen` prop
+     * directly — and back to `false` the moment `isOpen` transitions
+     * `false -> true` again (an interrupted exit releases any hold immediately,
+     * since the interrupted exit's `transitionend` resolves as an enter-settle
+     * and never signals exit-complete), or when the panel has genuinely finished
+     * animating off-screen (wired internally via `onExitComplete`, below).
+     *
+     * Useful for content that wants to survive the exit animation — e.g. via the
+     * shared `useHold(value, isExiting)` primitive — by holding its last non-null
+     * value while `isExiting` is `true`.
+     */
+    readonly isExiting: boolean;
+    /**
+     * Internal signal spread onto `Drawer`'s `onExitComplete` prop. `Drawer` calls
+     * this exactly once per genuine close→fully-exited cycle, which flips
+     * `isExiting` back to `false`. Not intended for direct use by consumers.
+     */
+    readonly onExitComplete: () => void;
 };
 /**
  * Hook for managing Drawer open/close state, dismiss handling, and floating UI wiring.