@trackunit/react-drawer 2.6.6 → 2.6.9

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@trackunit/react-drawer",
-  "version": "2.6.6",
+  "version": "2.6.9",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "2.10.1",
-    "@trackunit/css-class-variance-utilities": "1.14.15",
-    "@trackunit/ui-icons": "1.14.14",
-    "@trackunit/i18n-library-translation": "2.4.11"
+    "@trackunit/react-components": "2.10.4",
+    "@trackunit/css-class-variance-utilities": "1.14.17",
+    "@trackunit/i18n-library-translation": "2.4.13",
+    "@floating-ui/react": "^0.26.25",
+    "tailwind-merge": "^2.0.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.114.29",

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

@@ -1,43 +1,17 @@
 import { CommonProps } from "@trackunit/react-components";
-import { ReactNode, Ref, RefObject } from "react";
-import type { DrawerPosition } from "../../types";
-export declare const TRANSITION_DURATION = 100;
-export interface DrawerRefsHandle {
-    dialogRef: RefObject<HTMLDivElement>;
-    dialogContentRef: RefObject<HTMLDivElement>;
-}
-export interface DrawerProps extends CommonProps {
-    /**
-     * Specifies whether the sidebar drawer is open or not.
-     */
-    open?: boolean;
-    /**
-     * The handler for closing the drawer. If not provided, the drawer will dock when closed.=
-     */
-    onClose?: () => void;
-    /**
-     * The handler for opening the drawer. Called when the drawer transitions to open state.
-     */
-    onOpen?: () => void;
-    /**
-     * Whether the drawer needs an overlay or not. Without the overlay, user will have to handle mechanism for closing the drawer.
-     * Default is true.
-     */
-    hasOverlay?: boolean;
-    /**
-     * The position of the drawer.
-     */
-    position?: DrawerPosition;
+import { ReactElement, ReactNode } from "react";
+import type { UseDrawerReturnValue } from "./useDrawer";
+/**
+ * Presentational props for `Drawer`. State, dismiss wiring, variant, focus-trap
+ * opt-in, and position all flow in via {@link UseDrawerReturnValue} — call
+ * `useDrawer()` and spread its return onto `<Drawer>`.
+ */
+export interface DrawerProps extends CommonProps, UseDrawerReturnValue {
     /**
-     * The child node that will be rendered inside the drawer.
+     * Content rendered inside the drawer panel. Compose layout parts explicitly — typically
+     * `<DrawerHeader />` (or a custom header such as `CardHeader`) followed by the body.
      */
     children?: ReactNode;
-    /**
-     * Determines whether the drawer component should remain mounted in the DOM when it is closed.
-     * If set to true, the drawer will not be unmounted when closed
-     * Default is false.
-     */
-    keepMountedWhenClosed?: boolean;
     /**
      * Whether to render the drawer in a portal or not.
      * Default is false.
@@ -51,68 +25,80 @@ export interface DrawerProps extends CommonProps {
      */
     containerClassName?: string;
     /**
-     * A ref for the component
+     * Accessible name for the drawer's panel, forwarded as `aria-label`. Strongly recommended:
+     * without either this or `ariaLabelledBy`, assistive technology has no name for the panel and
+     * will announce it as an unnamed dialog / region. Mutually exclusive in intent with
+     * `ariaLabelledBy` — set one or the other, not both.
      */
-    ref?: Ref<HTMLDivElement>;
+    ariaLabel?: string;
+    /**
+     * Id of an existing element (typically a heading rendered inside the drawer body) whose text
+     * names the drawer's panel, forwarded as `aria-labelledby`. Prefer this over `ariaLabel` when
+     * the drawer body renders a visible heading so the two stay in sync.
+     */
+    ariaLabelledBy?: string;
 }
 /**
- * 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.
+ * 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)
+ *
+ * ### 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 drawer with content
+ * @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
  */
 export declare const Drawer: {
-    ({ open, onClose, onOpen, hasOverlay, position, children, "data-testid": dataTestId, className, renderInPortal, keepMountedWhenClosed, containerClassName, ref, ...others }: DrawerProps): import("react/jsx-runtime").JSX.Element | null;
+    ({ isOpen, variant, trapFocus, position, floatingUi, open: _open, close: _close, toggle: _toggle, requestClose: _requestClose, children, "data-testid": dataTestId, className, renderInPortal, containerClassName, ariaLabel, ariaLabelledBy, ...others }: DrawerProps): ReactElement | null;
     displayName: string;
 };

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

@@ -1,7 +1,17 @@
+/**
+ * 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`)
+ */
+export declare const cvaDrawerViewport: (props?: ({
+    portaled?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export declare const cvaDrawer: (props?: ({
-    position?: "left" | "right" | "top" | "bottom" | null | undefined;
-    mode?: "closed" | "open" | null | undefined;
+    position?: "left" | "right" | null | undefined;
+    mode?: "open" | "closed" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export declare const cvaDrawerContent: (props?: ({
-    position?: "left" | "right" | "top" | "bottom" | null | undefined;
+    position?: "left" | "right" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;

package/src/components/Drawer/drawer-animation-reducer.d.ts

@@ -0,0 +1,27 @@
+import type { DrawerMode } from "../../types";
+/**
+ * Animation lifecycle for Drawer mount / unmount.
+ *
+ * Open always mounts (or re-opens) in `mode: "closed"` so the panel starts off-screen
+ * for its `position`. A follow-up `openVisual` after layout reflow flips to `"open"`
+ * and the CSS transform transition plays the slide-in. `enterSettled` flips true only
+ * after that enter transition ends — focus must wait until then, otherwise
+ * `scrollIntoView` on an off-screen panel shoves the layout (gap + bounce on the right).
+ */
+export type DrawerAnimationState = {
+    readonly shouldRender: boolean;
+    readonly mode: DrawerMode;
+    readonly enterSettled: boolean;
+};
+export type DrawerAnimationAction = {
+    readonly type: "open";
+} | {
+    readonly type: "openVisual";
+} | {
+    readonly type: "close";
+} | {
+    readonly type: "transitionEnd";
+};
+export declare const INITIAL_DRAWER_ANIMATION_STATE: DrawerAnimationState;
+/** Reducer managing the Drawer panel's mount / enter / exit animation lifecycle. */
+export declare const drawerAnimationReducer: (state: DrawerAnimationState, action: DrawerAnimationAction) => DrawerAnimationState;

package/src/components/Drawer/drawer-motion-style.d.ts

@@ -0,0 +1,24 @@
+import type { CSSProperties } from "react";
+import type { DrawerMode, DrawerPosition } from "../../types";
+/**
+ * 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.
+ */
+export declare const DRAWER_TRANSITION_DURATION_MS: 400;
+export declare const DRAWER_TRANSITION_EASING: "cubic-bezier(0.4, 0, 0.2, 1)";
+/**
+ * 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.
+ */
+export declare const getDrawerMotionStyle: ({ mode, position, }: {
+    readonly mode: DrawerMode;
+    readonly position: DrawerPosition;
+}) => CSSProperties;

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

@@ -0,0 +1,121 @@
+import { type UseFloatingReturn } from "@floating-ui/react";
+import { type CloseReason, type DismissOptions, type UseOverlayDismissibleProps } from "@trackunit/react-components";
+import type { DrawerPosition } from "../../types";
+/**
+ * Semantic variant controlling the drawer's dismiss behavior, backdrop, and dialog ARIA.
+ * - `"default"` — non-overlay, non-focus-trapping panel; the surrounding page stays
+ *   interactive. Panel gets `role="complementary"` so it participates in the page's
+ *   landmark tree. ESC still calls `onClose` when provided.
+ * - `"modal"` — dimming backdrop, `role="dialog"` + `aria-modal`, focus trap (via
+ *   `FloatingFocusManager`) that returns focus to the trigger on close, and
+ *   outside-press dismiss.
+ */
+export type DrawerVariant = "default" | "modal";
+/**
+ * Dismiss options honored by Drawer. Reuses the shared {@link DismissOptions} shape
+ * for API parity with `useSheet` / `useModal`; the `gesture` option has no effect
+ * on Drawer (which has no swipe gesture) and is ignored.
+ */
+export type DrawerDismissOptions = Pick<DismissOptions, "escapeKey" | "outsidePress">;
+/**
+ * Floating UI wiring produced by `useDrawer` and consumed by `Drawer` for its
+ * focus manager and dismiss interaction bindings. Mirrors `useSheet`'s
+ * `floatingUi` shape.
+ */
+export type DrawerFloatingUiProps = {
+    readonly context: UseFloatingReturn["context"];
+    readonly refs: UseFloatingReturn["refs"];
+    readonly getFloatingProps: (userProps?: Record<string, unknown>) => Record<string, unknown>;
+};
+/** Props for the {@link useDrawer} hook. */
+export type UseDrawerProps = UseOverlayDismissibleProps & {
+    /**
+     * Semantic variant controlling backdrop, focus trap, and dismiss behavior.
+     *
+     * - `"default"` — no backdrop, no focus trap, `role="complementary"`. The
+     *   surrounding page stays interactive. ESC still calls `onClose` when
+     *   provided; outside-press does not close the drawer.
+     * - `"modal"` — dimming backdrop, `role="dialog"` + `aria-modal`, focus trap
+     *   that returns focus to the trigger on close, and outside-press dismiss.
+     *
+     * @default "modal"
+     */
+    readonly variant?: DrawerVariant;
+    /**
+     * Opt out of the focus trap when `variant="modal"`. Use this only when a
+     * parent component already manages focus for the drawer's subtree. Ignored
+     * when `variant="default"` — the default variant never traps focus.
+     *
+     * @default true
+     */
+    readonly trapFocus?: boolean;
+    /**
+     * The position of the drawer.
+     *
+     * @default "left"
+     */
+    readonly position?: DrawerPosition;
+};
+/** Return value of the {@link useDrawer} hook. */
+export type UseDrawerReturnValue = {
+    readonly isOpen: boolean;
+    readonly open: () => void;
+    readonly close: () => void;
+    readonly toggle: () => void;
+    /**
+     * Close the drawer with a specific reason. Runs `onBeforeClose` first
+     * (when provided) and only fires `onClose` / flips state if the guard
+     * resolves to `true`.
+     */
+    readonly requestClose: (event: Event | undefined, reason: CloseReason) => void;
+    /** Resolved variant, spread onto `Drawer`. */
+    readonly variant: DrawerVariant;
+    /** Resolved focus-trap opt-in, spread onto `Drawer`. */
+    readonly trapFocus: boolean;
+    /** Resolved position, spread onto `Drawer`. */
+    readonly position: DrawerPosition;
+    /**
+     * Floating UI wiring for the drawer's focus manager and dismiss bindings.
+     * `Drawer` merges `refs.setFloating` onto the panel and uses `context` for
+     * its `FloatingFocusManager`.
+     */
+    readonly floatingUi: DrawerFloatingUiProps;
+};
+/**
+ * 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>
+ *   </>
+ * );
+ * ```
+ */
+export declare const useDrawer: (props?: UseDrawerProps) => UseDrawerReturnValue;

package/src/components/DrawerHeader/DrawerHeader.d.ts

@@ -0,0 +1,67 @@
+import { CommonProps, PopoverContentChildren, Refable, Styleable } from "@trackunit/react-components";
+import { ReactElement } from "react";
+export interface DrawerHeaderProps extends CommonProps, Styleable, Refable<HTMLDivElement> {
+    /**
+     * Renders the toolbar close (X) button and is invoked when it is clicked. Omit this prop
+     * (or set `hideCloseButton`) to hide the X.
+     *
+     * Pass `useDrawer`'s `close` so the X routes through the same dismiss pipeline
+     * (including any `onBeforeClose` guard) as Escape and outside-press.
+     *
+     * ```tsx
+     * const drawer = useDrawer({ position: "right" });
+     *
+     * <Drawer {...drawer}>
+     *   <DrawerHeader onClickClose={drawer.close} />
+     *   {\/* body *\/}
+     * </Drawer>
+     * ```
+     */
+    onClickClose?: () => void;
+    /**
+     * Called when the user clicks the back-navigation arrow. When omitted, the back arrow is not
+     * rendered.
+     */
+    onClickBack?: () => void;
+    /**
+     * Called when the user clicks the forward-navigation arrow. When omitted, the forward arrow is
+     * not rendered.
+     */
+    onClickForward?: () => void;
+    /**
+     * Overflow-menu content, rendered inside a kebab (three-dot) popover placed before the close
+     * button. Typically a `<MenuContent>` with `<MenuItem>` children. Accepts either a static node or a
+     * render prop that receives a `close` callback, matching `<MoreMenu />`. When omitted, the
+     * kebab menu is not rendered.
+     */
+    menuContent?: PopoverContentChildren;
+    /**
+     * Hide the built-in close button. Use for read-only drawers, or drawers whose parent already
+     * provides an equivalent affordance elsewhere.
+     *
+     * @default false
+     */
+    hideCloseButton?: boolean;
+}
+/**
+ * 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.
+ *
+ * Button labels come from this library's translation namespace and cannot be overridden — the
+ * affordances are universal ("Close", "Back", "Forward", "More actions").
+ */
+export declare const DrawerHeader: {
+    ({ onClickClose, onClickBack, onClickForward, menuContent, hideCloseButton, "data-testid": dataTestId, className, style, ref, }: DrawerHeaderProps): ReactElement;
+    displayName: string;
+};

package/src/components/Overlay/Overlay.d.ts

@@ -1,15 +1,19 @@
 import { ReactElement } from "react";
 interface OverlayProps {
     open: boolean;
-    onClose?: () => void;
 }
 /**
  * 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
  */
-export declare const Overlay: ({ open, onClose }: OverlayProps) => ReactElement | null;
+export declare const Overlay: ({ open }: OverlayProps) => ReactElement;
 export {};

package/src/index.d.ts

@@ -1,2 +1,4 @@
 export * from "./components/Drawer/Drawer";
-export * from "./components/DrawerToggle/DrawerToggle";
+export * from "./components/Drawer/useDrawer";
+export * from "./components/DrawerHeader/DrawerHeader";
+export type { DrawerPosition } from "./types";

package/src/translation.d.ts

@@ -14,8 +14,8 @@ export declare const translations: TranslationResource<TranslationKeys>;
 /**
  *  Local useTranslation for this specific library
  */
-export declare const useTranslation: () => [TransForLibs<never>, import("i18next").i18n, boolean] & {
-    t: TransForLibs<never>;
+export declare const useTranslation: () => [TransForLibs<"drawer.header.back" | "drawer.header.close" | "drawer.header.forward" | "drawer.header.moreMenu">, import("i18next").i18n, boolean] & {
+    t: TransForLibs<"drawer.header.back" | "drawer.header.close" | "drawer.header.forward" | "drawer.header.moreMenu">;
     i18n: import("i18next").i18n;
     ready: boolean;
 };

package/src/types.d.ts

@@ -1,2 +1,2 @@
-export type DrawerPosition = "left" | "right" | "top" | "bottom";
+export type DrawerPosition = "left" | "right";
 export type DrawerMode = "closed" | "open";

package/src/components/DrawerToggle/DrawerToggle.d.ts

@@ -1,23 +0,0 @@
-import { Refable, type Styleable } from "@trackunit/react-components";
-import { MouseEvent } from "react";
-import { type DrawerPosition } from "../../types";
-interface DrawerToggleProps extends Refable<HTMLDivElement>, Styleable {
-    open: boolean;
-    onClick?: (event: MouseEvent) => void;
-    position: DrawerPosition;
-}
-/**
- * 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.
- *
- * @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
- */
-export declare const DrawerToggle: ({ open, position, onClick, ref, style }: DrawerToggleProps) => import("react/jsx-runtime").JSX.Element;
-export {};