@trackunit/react-drawer 2.6.6 → 2.6.9

package/index.esm.js

@@ -1,11 +1,16 @@
 import { jsx, jsxs } from 'react/jsx-runtime';
-import { registerTranslations } from '@trackunit/i18n-library-translation';
-import { useViewportBreakpoints, Portal, Icon } from '@trackunit/react-components';
-import { useEffect, useReducer, useRef, useCallback } from 'react';
+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 { cvaMerge } from '@trackunit/css-class-variance-utilities';
+import { twMerge } from 'tailwind-merge';
 
 var defaultTranslations = {
-	
+	"drawer.header.back": "Back",
+	"drawer.header.close": "Close",
+	"drawer.header.forward": "Forward",
+	"drawer.header.moreMenu": "More actions"
 };
 
 /** The translation namespace for this library */
@@ -39,6 +44,10 @@ const translations = {
         th: () => import('./translation17.esm.js'),
     },
 };
+/**
+ *  Local useTranslation for this specific library
+ */
+const useTranslation = () => useNamespaceTranslation(namespace);
 /**
  * Registers the translations for this library
  */
@@ -49,34 +58,18 @@ const setupLibraryTranslations = () => {
 /**
  * Overlay Component
  *
+ * Purely visual dimming backdrop rendered behind an open modal `<Drawer />`. Dismiss
+ * handling (Escape, outside-press) is owned by `<Drawer />`'s Floating UI wiring —
+ * clicking the overlay dispatches `onClose` via `useDismiss`'s `outsidePress`
+ * detection, not via a click handler on this component. Rendered only when the parent
+ * drawer resolves to `variant="modal"`.
+ *
  * @param {object} props - The Overlay component properties
  * @param {boolean} props.open - Open status of the Overlay
- * @param {Function} props.onClose - Callback function when Overlay is closed
- * @returns {ReactElement|null} The Overlay component
+ * @returns {ReactElement} The Overlay component
  */
-const Overlay = ({ open, onClose }) => {
-    useEffect(() => {
-        if (!onClose) {
-            return;
-        }
-        const handleEscape = (event) => {
-            if (event.key === "Escape") {
-                onClose();
-            }
-        };
-        if (open) {
-            window.addEventListener("keyup", handleEscape);
-        }
-        return () => {
-            window.removeEventListener("keyup", handleEscape);
-        };
-    }, [open, onClose]);
-    const handleClick = () => {
-        if (onClose) {
-            onClose();
-        }
-    };
-    return (jsx("div", { "aria-hidden": open, className: cvaOverlayContainer({ open }), "data-testid": "drawer-overlay", onClick: handleClick }));
+const Overlay = ({ open }) => {
+    return jsx("div", { "aria-hidden": open, className: cvaOverlayContainer({ open }), "data-testid": "drawer-overlay" });
 };
 const cvaOverlayContainer = cvaMerge([
     "absolute",
@@ -84,281 +77,499 @@ const cvaOverlayContainer = cvaMerge([
     "items-center",
     "justify-center",
     "inset-0",
-    "bg-black/30",
-    "bg-opacity-50",
+    "bg-black/50",
     "transition-opacity",
-    "duration-500",
-    "ease-[cubic-bezier(0.32_0.72_0_1)]",
+    // Match panel motion so backdrop and slide stay in sync.
+    "duration-400",
+    "[transition-timing-function:cubic-bezier(0.4,0,0.2,1)]",
     "opacity-0",
+    // Parent viewport is pointer-events-none; re-enable so modal dismiss works.
+    "pointer-events-none",
 ], {
     variants: {
         open: {
-            true: "z-overlay opacity-100",
-            false: "z-hidden pointer-events-none opacity-0",
+            true: "z-overlay pointer-events-auto opacity-100",
+            false: "z-hidden opacity-0",
         },
     },
 });
 
+/**
+ * Clip layer for the slide. Right-side enter uses `translateX(100%)`, which would
+ * otherwise extend past the edge and expand scroll width — shifting the page.
+ *
+ * - `portaled` → `fixed` (viewport-relative; escapes parent layout)
+ * - in-tree → `absolute` (parent must establish a containing block, e.g. `relative`)
+ */
+const cvaDrawerViewport = cvaMerge([
+    "inset-0",
+    "z-overlay",
+    "overflow-hidden",
+    "overscroll-none",
+    // Let non-modal drawers keep the page interactive; panel/overlay opt back in.
+    "pointer-events-none",
+], {
+    variants: {
+        portaled: {
+            true: ["fixed"],
+            false: ["absolute"],
+        },
+    },
+    defaultVariants: {
+        portaled: true,
+    },
+});
 const cvaDrawer = cvaMerge([
     "z-overlay",
     "pointer-events-auto",
     "absolute",
     "flex-col",
-    "transition-all",
-    "duration-300",
-    "ease-in-out",
     "bg-white",
+    // Transform + transition are applied via getDrawerMotionStyle (inline) so
+    // motion does not depend on host Tailwind picking up arbitrary utilities.
+    //
+    // Width contract: every drawer opens at the same width at the same viewport.
+    // On mobile the panel spans the viewport; from `sm` (480 px in this repo)
+    // up it locks to a fixed 28rem regardless of viewport size. Consumers that
+    // genuinely need a different width pass a width utility via `className` and
+    // `twMerge` (inside `cvaMerge`) lets the caller's utility win at its
+    // breakpoint. `max-w` is a safety cap so no override can exceed the
+    // viewport.
+    "w-full",
+    "sm:w-[28rem]",
+    "max-w-[100dvw]",
 ], {
     variants: {
         position: {
-            left: ["left-0", "top-0", "h-full", "w-fit"],
-            right: ["right-0", "top-0", "h-full", "w-fit"],
-            top: ["left-0", "top-0", "h-fit", "w-full", "pb-2"],
-            bottom: ["bottom-0", "left-0", "right-0", "max-h-screen", "w-full", "pt-3"],
+            left: ["left-0", "top-0", "h-full"],
+            right: ["right-0", "top-0", "h-full"],
         },
         mode: {
-            open: [], // No additional classes needed; position determines translation
-            closed: [], // Translation handled in compoundVariants
+            // shadow toggles with mode so it fades out alongside the slide-out
+            // transform and doesn't leave a residual band bleeding into the
+            // viewport once the drawer is fully off-screen.
+            open: ["shadow-lg"],
+            closed: ["shadow-none"],
         },
     },
-    compoundVariants: [
-        {
-            mode: "open",
-            position: "left",
-            className: ["translate-x-0"],
-        },
-        {
-            mode: "closed",
-            position: "left",
-            className: ["-translate-x-full"],
-        },
-        {
-            mode: "open",
-            position: "right",
-            className: "translate-x-0",
-        },
-        {
-            mode: "closed",
-            position: "right",
-            className: "translate-x-full",
-        },
-        {
-            mode: "open",
-            position: "top",
-            className: "translate-y-0",
-        },
-        {
-            mode: "closed",
-            position: "top",
-            className: "-translate-y-full",
-        },
-        {
-            mode: "open",
-            position: "bottom",
-            className: "translate-y-0",
-        },
-        {
-            mode: "closed",
-            position: "bottom",
-            className: "translate-y-full",
-        },
-    ],
     defaultVariants: {
         position: "left",
         mode: "closed",
     },
 });
-const cvaDrawerContent = cvaMerge(["flex", "flex-col", "h-full", "shadow-lg"], {
+const cvaDrawerContent = cvaMerge(["flex", "flex-col", "h-full"], {
     variants: {
         position: {
             left: "rounded-r-lg",
             right: "rounded-l-lg",
-            top: "rounded-b-lg",
-            bottom: ["max-h-[calc(100dvh-10px)]", "rounded-t-lg"],
         },
     },
 });
 
-const TRANSITION_DURATION = 100;
-const DEFAULT_POSITION = "left";
-const NOOP$1 = () => void 0;
-const drawerReducer = (state, action) => {
+const INITIAL_DRAWER_ANIMATION_STATE = {
+    shouldRender: false,
+    mode: "closed",
+    enterSettled: false,
+};
+/** Reducer managing the Drawer panel's mount / enter / exit animation lifecycle. */
+const drawerAnimationReducer = (state, action) => {
     switch (action.type) {
         case "open":
-            return { shouldRender: true, mode: "open" };
+            // Already fully open — ignore duplicate syncs (avoids a closed flash).
+            if (state.shouldRender && state.mode === "open") {
+                return state;
+            }
+            // Already mounted off-screen (initial enter frame or mid-close) — keep it;
+            // `openVisual` after reflow drives the slide-in.
+            if (state.shouldRender) {
+                return { ...state, enterSettled: false };
+            }
+            // Fresh mount: render off-screen first so the enter transition has a from-state.
+            return { shouldRender: true, mode: "closed", enterSettled: false };
+        case "openVisual":
+            return state.mode === "open" ? state : { ...state, mode: "open", enterSettled: false };
         case "close":
-            return { ...state, mode: "closed" };
+            return state.mode === "closed" && !state.enterSettled ? state : { ...state, mode: "closed", enterSettled: false };
         case "transitionEnd":
-            return state.mode === "closed" ? { ...state, shouldRender: false } : state;
+            if (state.mode === "closed") {
+                return { shouldRender: false, mode: "closed", enterSettled: false };
+            }
+            // Enter finished — safe to activate focus without scrollIntoView fighting the slide.
+            return state.enterSettled ? state : { ...state, enterSettled: true };
         default:
             return state;
     }
 };
+
+/**
+ * Side drawers travel farther than sheets (often 400px+). Use a standard
+ * decelerate curve with no overshoot (y-values stay in 0–1) so the panel does
+ * not slide past flush and bounce back — that looked like a gap on the right.
+ */
+const DRAWER_TRANSITION_DURATION_MS = 400;
+const DRAWER_TRANSITION_EASING = "cubic-bezier(0.4, 0, 0.2, 1)";
+const DRAWER_MOTION_TRANSITION = `transform ${DRAWER_TRANSITION_DURATION_MS}ms ${DRAWER_TRANSITION_EASING}`;
 /**
- * Drawers components can be switched between open and closed states.
- * They start closed but can be temporarily opened, appearing on top of other content until the user chooses a section.
- * To close the drawer, users can either click outside of it or press the Esc key.
+ * Inline transform/transition for the drawer panel.
+ *
+ * Kept as inline styles (same approach as Sheet) so enter/exit motion does not
+ * depend on Tailwind emitting arbitrary `transition-[…]` utilities into the
+ * host app's CSS bundle — missing those utilities makes the panel appear/disappear
+ * with no slide.
+ *
+ * Only `transform` is transitioned — animating `box-shadow` alongside a wide
+ * slide makes the stop feel abrupt when the shadow pops in.
+ */
+const getDrawerMotionStyle = ({ mode, position, }) => ({
+    transform: mode === "open" ? "translateX(0)" : position === "left" ? "translateX(-100%)" : "translateX(100%)",
+    transition: DRAWER_MOTION_TRANSITION,
+});
+
+/** First tabbable control inside the panel — used after enter settles (preventScroll). */
+const PANEL_FOCUSABLE_SELECTOR = [
+    "button:not([disabled])",
+    "a[href]",
+    "input:not([disabled])",
+    "select:not([disabled])",
+    "textarea:not([disabled])",
+    '[tabindex]:not([tabindex="-1"])',
+].join(", ");
+/**
+ * Drawers slide in from the left or right edge of the viewport as either a modal
+ * dialog or a docked inspector panel.
  *
  * ### When to use
- * - For secondary content or navigation that doesn't need to be always visible
- * - For filters, settings panels, or detail views that slide in from the side
+ * - For secondary content that doesn't need to be always visible
+ * - For inspector panels or item detail views that slide in from the side
  * - When you need to preserve context of the underlying page
  *
  * ### When not to use
  * - For critical actions requiring user confirmation (use Modal instead)
  * - For simple tooltips or small contextual information (use Popover)
+ * - To show a table selection and bulk actions (use ActionSheet instead)
  *
- * @example Basic drawer with content
+ * ### API
+ * `Drawer` is a presentation component. Call `useDrawer()` to own the drawer's
+ * open state, dismiss handling, and (optional) `onBeforeClose` guard, then spread
+ * its return value onto `<Drawer>`.
+ *
+ * @example Basic modal drawer with the standard toolbar
  * ```tsx
- * import { Drawer } from "@trackunit/react-drawer";
+ * import { Drawer, DrawerHeader, useDrawer } from "@trackunit/react-drawer";
  * import { Button } from "@trackunit/react-components";
- * import { useState } from "react";
  *
  * const FilterDrawer = () => {
- *   const [isOpen, setIsOpen] = useState(false);
+ *   const drawer = useDrawer({ position: "right", variant: "modal" });
  *
  *   return (
  *     <>
- *       <Button onClick={() => setIsOpen(true)}>Open Filters</Button>
- *       <Drawer
- *         open={isOpen}
- *         onClose={() => setIsOpen(false)}
- *         position="right"
- *       >
- *         <div className="p-4">
- *           <h2>Filter Options</h2>
- *           <p>Filter controls go here</p>
- *         </div>
+ *       <Button onClick={drawer.open}>Open Filters</Button>
+ *       <Drawer {...drawer} ariaLabel="Filters">
+ *         <DrawerHeader onClickClose={drawer.close} />
+ *         <div className="p-4">Filter controls go here</div>
  *       </Drawer>
  *     </>
  *   );
  * };
  * ```
- * @example Drawer without overlay for side panels
+ * @example Guard dismissal with `onBeforeClose`
+ * ```tsx
+ * const drawer = useDrawer({
+ *   variant: "modal",
+ *   onBeforeClose: async () => (await confirmDiscard()) === "discard",
+ * });
+ * ```
+ * @example Non-modal inspector — background stays interactive
  * ```tsx
- * import { Drawer } from "@trackunit/react-drawer";
+ * const drawer = useDrawer({
+ *   isOpen: Boolean(selectedAssetId),
+ *   onClose: () => setSelectedAssetId(null),
+ *   position: "right",
+ *   variant: "default",
+ * });
  *
- * const SidePanel = ({ isOpen, content }) => (
- *   <Drawer
- *     open={isOpen}
- *     hasOverlay={false}
- *     position="left"
- *     keepMountedWhenClosed={true}
- *   >
- *     {content}
- *   </Drawer>
- * );
+ * <Drawer {...drawer} ariaLabelledBy="asset-inspector-title">
+ *   <h2 id="asset-inspector-title">{selectedAsset?.name}</h2>
+ * </Drawer>
  * ```
  * @param {DrawerProps} props - The props for the Drawer component
  */
-const Drawer = ({ open = false, // Default to closed
-onClose = NOOP$1, onOpen = NOOP$1, hasOverlay = true, position = DEFAULT_POSITION, children, "data-testid": dataTestId, className, renderInPortal = false, keepMountedWhenClosed = false, containerClassName, ref, ...others }) => {
+const Drawer = ({ isOpen, variant, trapFocus, position, floatingUi, open: _open, close: _close, toggle: _toggle, requestClose: _requestClose, children, "data-testid": dataTestId, className, renderInPortal = false, containerClassName, ariaLabel, ariaLabelledBy, ...others }) => {
     const { isSm } = useViewportBreakpoints();
     const shouldUsePortal = !isSm || renderInPortal;
-    const [drawerState, dispatch] = useReducer(drawerReducer, {
-        shouldRender: open,
-        mode: open ? "open" : "closed",
+    const panelRef = useRef(null);
+    // State copy of the panel node so the enter-animation layout effect re-runs once
+    // the portal (or first paint) has attached the DOM node — refs alone do not.
+    const [panelElement, setPanelElement] = useState(null);
+    const isOpenRef = useRef(isOpen);
+    const [drawerState, dispatch] = useReducer(drawerAnimationReducer, {
+        ...INITIAL_DRAWER_ANIMATION_STATE,
+        // Mount off-screen when initially open so the enter slide still plays.
+        shouldRender: isOpen,
+        mode: "closed",
     });
-    const onOpenRef = useRef(onOpen);
     useEffect(() => {
-        onOpenRef.current = onOpen;
-    }, [onOpen]);
+        isOpenRef.current = isOpen;
+    }, [isOpen]);
+    useLayoutEffect(() => {
+        dispatch({ type: isOpen ? "open" : "close" });
+    }, [isOpen]);
+    // Defer the open flip until after paint. A single useLayoutEffect flip commits
+    // the open transform before the first paint (no slide). Double-rAF waits until
+    // the off-screen baseline has been painted, then opens.
     useEffect(() => {
-        if (open) {
-            dispatch({ type: "open" });
-            setTimeout(() => {
-                onOpenRef.current();
-            }, TRANSITION_DURATION);
+        if (!isOpen || !drawerState.shouldRender || drawerState.mode === "open" || !panelElement) {
+            return;
         }
-        else {
-            dispatch({ type: "close" });
+        let raf2Id = 0;
+        const raf1Id = requestAnimationFrame(() => {
+            raf2Id = requestAnimationFrame(() => {
+                dispatch({ type: "openVisual" });
+            });
+        });
+        return () => {
+            cancelAnimationFrame(raf1Id);
+            cancelAnimationFrame(raf2Id);
+        };
+    }, [isOpen, drawerState.shouldRender, drawerState.mode, panelElement]);
+    // Headless / test environments suppress CSS transitions, so transitionend never
+    // fires on close. After one frame, unmount when no transform animation ran.
+    useEffect(() => {
+        if (drawerState.mode !== "closed" || !drawerState.shouldRender) {
+            return;
+        }
+        const rafId = requestAnimationFrame(() => {
+            const panelNode = panelRef.current;
+            if (!panelNode || isOpenRef.current) {
+                return;
+            }
+            const runningAnimations = typeof panelNode.getAnimations === "function" ? panelNode.getAnimations() : [];
+            if (runningAnimations.length === 0) {
+                dispatch({ type: "transitionEnd" });
+            }
+        });
+        return () => cancelAnimationFrame(rafId);
+    }, [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
+    // for a frame before the CSS transition starts, which would focus mid-slide and
+    // reintroduce the right-edge scrollIntoView gap/bounce.
+    useEffect(() => {
+        if (drawerState.mode !== "open" || drawerState.enterSettled) {
+            return;
         }
-    }, [open]);
+        const timeoutId = window.setTimeout(() => {
+            dispatch({ type: "transitionEnd" });
+        }, DRAWER_TRANSITION_DURATION_MS + 50);
+        return () => window.clearTimeout(timeoutId);
+    }, [drawerState.mode, drawerState.enterSettled]);
+    // Keep FloatingFocusManager enabled (so outside stays aria-hidden during enter) but
+    // skip its autofocus via initialFocus={-1}. After the slide settles, move focus
+    // ourselves with preventScroll so the browser does not scrollIntoView an off-screen panel.
+    // Bail out if focus is already inside the panel — the panel is interactive during the
+    // slide, so a user who clicked or typed into a control in the first ~400ms would
+    // otherwise have focus yanked to the first tabbable element mid-interaction.
+    useEffect(() => {
+        if (!drawerState.enterSettled || variant !== "modal" || !trapFocus) {
+            return;
+        }
+        const panelNode = panelRef.current;
+        if (!panelNode || panelNode.contains(document.activeElement)) {
+            return;
+        }
+        const focusTarget = panelNode.querySelector(PANEL_FOCUSABLE_SELECTOR);
+        if (focusTarget instanceof HTMLElement) {
+            focusTarget.focus({ preventScroll: true });
+        }
+    }, [drawerState.enterSettled, variant, trapFocus]);
+    const handlePanelElement = useCallback((node) => {
+        setPanelElement(node instanceof HTMLDivElement ? node : null);
+    }, []);
+    const mergedPanelRef = useMergeRefs([panelRef, floatingUi.refs.setFloating, handlePanelElement]);
     const handleAnimationEnd = useCallback((transitionEvent) => {
+        if (transitionEvent.target !== transitionEvent.currentTarget) {
+            return;
+        }
         if (transitionEvent.propertyName === "transform") {
             dispatch({ type: "transitionEnd" });
         }
     }, []);
-    if (!drawerState.shouldRender && !keepMountedWhenClosed) {
+    if (!drawerState.shouldRender) {
         return null;
     }
-    const content = (jsxs("div", { className: containerClassName, children: [hasOverlay ? jsx(Overlay, { onClose: onClose, open: drawerState.mode === "open" }) : null, jsx("div", { className: cvaDrawer({
-                    mode: drawerState.mode,
-                    position: position,
-                    className,
-                }), "data-testid": dataTestId, onTransitionEnd: handleAnimationEnd, ref: ref, ...others, children: jsx("div", { className: cvaDrawerContent({ position }), children: children }) })] }));
+    const isModal = variant === "modal";
+    // Keep FloatingFocusManager mounted for the whole shouldRender lifetime so the
+    // panel DOM node is not remounted when mode flips (which would cancel the CSS
+    // transition). Autofocus is deferred via initialFocus={-1} + preventScroll focus
+    // after enterSettled — focusing mid-slide triggers scrollIntoView (right-edge bounce).
+    const showFocusManager = isModal && trapFocus && drawerState.shouldRender;
+    const floatingProps = floatingUi.getFloatingProps();
+    const panel = (jsx("div", { "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, "aria-modal": isModal ? true : undefined, className: cvaDrawer({
+            mode: drawerState.mode,
+            position: position,
+            className,
+        }), "data-testid": dataTestId, onTransitionEnd: handleAnimationEnd, ref: mergedPanelRef, role: isModal ? "dialog" : "complementary", ...floatingProps, ...others, style: {
+            ...getDrawerMotionStyle({ mode: drawerState.mode, position }),
+        }, children: jsx("div", { className: cvaDrawerContent({ position }), children: children }) }));
+    const content = (jsxs("div", { className: cvaDrawerViewport({ portaled: shouldUsePortal, className: containerClassName }), "data-testid": "drawer-viewport", children: [isModal ? jsx(Overlay, { open: isOpen ? drawerState.mode === "open" : false }) : null, showFocusManager ? (jsx(FloatingFocusManager, { context: floatingUi.context, initialFocus: -1, returnFocus: true, children: panel })) : (panel)] }));
     return shouldUsePortal ? jsx(Portal, { children: content }) : content;
 };
 Drawer.displayName = "Drawer";
 
-const NOOP = () => void 0;
-const getIconName = (open, position) => {
-    switch (position) {
-        case "left":
-            return open ? "ChevronLeft" : "ChevronRight";
-        case "right":
-            return open ? "ChevronRight" : "ChevronLeft";
-        case "top":
-            return open ? "ChevronUp" : "ChevronDown";
-        case "bottom":
-            return open ? "ChevronDown" : "ChevronUp";
-        default:
-            return open ? "ChevronLeft" : "ChevronRight";
-    }
+const DEFAULT_POSITION = "left";
+const DEFAULT_VARIANT = "modal";
+/**
+ * Hook for managing Drawer open/close state, dismiss handling, and floating UI wiring.
+ *
+ * Aligns with `useSheet` and `useModal`: consumers use `useDrawer()` to own the
+ * drawer's state and callbacks, then spread the return value onto `Drawer`.
+ *
+ * Supports controlled (`isOpen`) and uncontrolled (`defaultOpen`) modes, stable
+ * `open` / `close` / `toggle` identities (latest-ref pattern for callbacks), and
+ * an `onBeforeClose` guard that can be sync or async — return `false` (or a
+ * `Promise<false>`) to keep the drawer open in response to a close attempt.
+ *
+ * Owns ESC and outside-press dismiss via Floating UI's `useDismiss`. Outside-press
+ * is only active when `variant === "modal"` (the only variant with a backdrop).
+ * The `gesture` field of `DismissOptions` is accepted for API parity with Sheet
+ * but has no effect — Drawer has no swipe gesture.
+ *
+ * @example Controlled
+ * ```tsx
+ * const drawer = useDrawer({ isOpen, onClose: () => setOpen(false), position: "right" });
+ * return <Drawer {...drawer}>...</Drawer>;
+ * ```
+ * @example Uncontrolled with a beforeClose guard
+ * ```tsx
+ * const drawer = useDrawer({
+ *   variant: "modal",
+ *   onBeforeClose: async () => (await confirmDiscard()) === "discard",
+ * });
+ * return (
+ *   <>
+ *     <Button onClick={drawer.open}>Open</Button>
+ *     <Drawer {...drawer}>
+ *       <DrawerHeader onClickClose={drawer.close} />
+ *     </Drawer>
+ *   </>
+ * );
+ * ```
+ */
+const useDrawer = (props) => {
+    const { isOpen: controlledIsOpen, defaultOpen, onClose, onOpen, onOpenChange, onBeforeClose, dismiss: dismissProp, variant = DEFAULT_VARIANT, trapFocus = true, position = DEFAULT_POSITION, } = props ?? {};
+    const dismiss = useMemo(() => ({
+        escapeKey: dismissProp?.escapeKey ?? true,
+        outsidePress: dismissProp?.outsidePress ?? true,
+    }), [dismissProp]);
+    const [internalIsOpen, setIsOpen] = useState(defaultOpen ?? false);
+    const isOpen = typeof controlledIsOpen === "boolean" ? controlledIsOpen : internalIsOpen;
+    const isPendingCloseRef = useRef(false);
+    const onCloseRef = useRef(onClose);
+    const onOpenRef = useRef(onOpen);
+    const onOpenChangeRef = useRef(onOpenChange);
+    const onBeforeCloseRef = useRef(onBeforeClose);
+    useLayoutEffect(() => {
+        onCloseRef.current = onClose;
+        onOpenRef.current = onOpen;
+        onOpenChangeRef.current = onOpenChange;
+        onBeforeCloseRef.current = onBeforeClose;
+    });
+    const handleClose = useCallback((event, reason) => {
+        setIsOpen(false);
+        onCloseRef.current?.(event, reason);
+        onOpenChangeRef.current?.(false, event, reason);
+    }, []);
+    const requestClose = useCallback((event, reason) => {
+        if (onBeforeCloseRef.current) {
+            if (isPendingCloseRef.current) {
+                return;
+            }
+            isPendingCloseRef.current = true;
+            void Promise.resolve(onBeforeCloseRef.current(event, reason))
+                .then(shouldClose => {
+                if (shouldClose) {
+                    handleClose(event, reason);
+                }
+            })
+                .finally(() => {
+                isPendingCloseRef.current = false;
+            });
+            return;
+        }
+        handleClose(event, reason);
+    }, [handleClose]);
+    const close = useCallback(() => requestClose(undefined, "programmatic"), [requestClose]);
+    const open = useCallback(() => {
+        onOpenRef.current?.();
+        onOpenChangeRef.current?.(true);
+        setIsOpen(true);
+    }, []);
+    const toggle = useCallback(() => {
+        if (isOpen) {
+            close();
+        }
+        else {
+            open();
+        }
+    }, [isOpen, open, close]);
+    const { context: floatingContext, refs: floatingRefs } = useFloating({
+        open: isOpen,
+        onOpenChange: (nextOpen, event, reason) => {
+            if (nextOpen)
+                return;
+            const closeReason = reason === "escape-key" || reason === "outside-press" ? reason : undefined;
+            requestClose(event, closeReason ?? "programmatic");
+        },
+    });
+    const dismissInteraction = useDismiss(floatingContext, {
+        escapeKey: dismiss.escapeKey,
+        outsidePress: variant === "modal" && dismiss.outsidePress,
+    });
+    const { getFloatingProps } = useInteractions([dismissInteraction]);
+    const floatingUi = useMemo(() => ({ context: floatingContext, refs: floatingRefs, getFloatingProps }), [floatingContext, floatingRefs, getFloatingProps]);
+    return useMemo(() => ({
+        isOpen,
+        open,
+        close,
+        toggle,
+        requestClose,
+        variant,
+        trapFocus,
+        position,
+        floatingUi,
+    }), [isOpen, open, close, toggle, requestClose, variant, trapFocus, position, floatingUi]);
 };
+
 /**
- * DrawerToggle is a React functional component that returns a button with a chevron icon.
- * The direction of the chevron changes depending on the state of the 'open' prop and
- * the side the button is positioned ('position' prop).
- * The button might be disabled based on the 'disableButton' prop.
+ * Standard drawer toolbar header. Compose it as a child of `<Drawer />`:
+ *
+ * ```tsx
+ * const drawer = useDrawer({ position: "right" });
+ *
+ * <Drawer {...drawer}>
+ *   <DrawerHeader menuContent={…} onClickBack={goBack} onClickClose={drawer.close} />
+ *   {\/* body *\/}
+ * </Drawer>
+ * ```
+ *
+ * Wire the X button to `useDrawer`'s `close` so it shares the same dismiss pipeline
+ * (Escape, outside-press, `onBeforeClose` guard) as the rest of the drawer.
  *
- * @param {object} props - The properties passed to the component
- * @param {Function} [props.onClick] - Optional callback function for when the button is clicked
- * @param {boolean} props.open - Indicates if the button is in "open" state
- * @param {DrawerPosition} props.position - The position of the button relative to its container
- * @param props.ref - Ref forwarded to the root DOM element
- * @param props.style - Inline styles applied to the root DOM element
+ * Button labels come from this library's translation namespace and cannot be overridden — the
+ * affordances are universal ("Close", "Back", "Forward", "More actions").
  */
-const DrawerToggle = ({ open, position, onClick = NOOP, ref, style }) => {
-    const name = getIconName(open, position);
-    return (jsx("div", { className: cvaToggleContainer({ position }), ref: ref, style: style, children: jsx("button", { className: cvaDrawerToggle({ position }), "data-testid": "toggle-button", onClick: onClick, children: jsx(Icon, { name: name }) }) }));
+const DrawerHeader = ({ onClickClose, onClickBack, onClickForward, menuContent, hideCloseButton = false, "data-testid": dataTestId, className, style, ref, }) => {
+    const [t] = useTranslation();
+    const showCloseButton = !hideCloseButton && onClickClose !== undefined;
+    const showMoreMenu = menuContent !== undefined;
+    const handleClickClose = () => onClickClose?.();
+    const testId = (suffix) => (dataTestId !== undefined ? `${dataTestId}-${suffix}` : `drawer-${suffix}`);
+    return (jsxs("div", { className: twMerge("flex items-center justify-between gap-2 border-b border-neutral-200 bg-white px-4 py-1", className), "data-testid": dataTestId, ref: ref, style: style, children: [jsxs("div", { className: "flex items-center gap-0", children: [onClickBack ? (jsx(IconButton, { "data-testid": testId("back-button"), icon: jsx(Icon, { name: "ArrowLeft", size: "small" }), onClick: onClickBack, title: t("drawer.header.back"), variant: "ghost-neutral" })) : null, onClickForward ? (jsx(IconButton, { "data-testid": testId("forward-button"), icon: jsx(Icon, { name: "ArrowRight", size: "small" }), onClick: onClickForward, title: t("drawer.header.forward"), variant: "ghost-neutral" })) : null] }), jsxs("div", { className: "flex items-center gap-0", children: [showMoreMenu ? (jsx(MoreMenu, { buttonLabel: t("drawer.header.moreMenu"), "data-testid": testId("more-menu"), iconButtonProps: {
+                            "data-testid": testId("more-menu-button"),
+                            variant: "ghost-neutral",
+                        }, iconProps: { size: "small" }, children: menuContent })) : null, showCloseButton ? (jsx(IconButton, { "data-testid": testId("close-button"), icon: jsx(Icon, { name: "XMark", size: "small" }), onClick: handleClickClose, title: t("drawer.header.close"), variant: "ghost-neutral" })) : null] })] }));
 };
-const cvaDrawerToggle = cvaMerge([
-    "flex",
-    "cursor-pointer",
-    "items-center",
-    "justify-center",
-    "border-neutral-300",
-    "bg-neutral-50",
-    "bg-center",
-    "bg-no-repeat",
-    "shadow-md",
-], {
-    variants: {
-        position: {
-            left: "h-12 w-6 rounded-r-lg",
-            right: "h-12 w-6 rounded-l-lg",
-            top: "h-6 w-12 rounded-b-lg",
-            bottom: "h-6 w-12 rounded-t-lg",
-        },
-    },
-    defaultVariants: {
-        position: "left",
-    },
-});
-const cvaToggleContainer = cvaMerge(["z-8", "absolute"], {
-    variants: {
-        position: {
-            left: "right-[-24px] top-[calc(50%-24px)]",
-            right: "left-[-24px] top-[calc(50%-24px)]",
-            top: "bottom-[-24px] left-[calc(50%-24px)]",
-            bottom: "left-[calc(50%-24px)] top-[-24px]",
-        },
-    },
-    defaultVariants: {
-        position: "left",
-    },
-});
+DrawerHeader.displayName = "DrawerHeader";
 
 /*
  * ----------------------------
@@ -369,4 +580,4 @@ const cvaToggleContainer = cvaMerge(["z-8", "absolute"], {
  */
 setupLibraryTranslations();
 
-export { Drawer, DrawerToggle, TRANSITION_DURATION };
+export { Drawer, DrawerHeader, useDrawer };