@trackunit/react-components 1.21.14 → 1.21.17

package/index.esm.js

@@ -10,7 +10,7 @@ import IconSpriteSolid from '@trackunit/ui-icons/icons-sprite-solid.svg';
 import { snakeCase, titleCase } from 'string-ts';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
 import { Slot, Slottable } from '@radix-ui/react-slot';
-import { Link, useBlocker, useSearch, useNavigate } from '@tanstack/react-router';
+import { Link, useBlocker, useNavigate, useLocation, useSearch } from '@tanstack/react-router';
 import { isEqual, omit } from 'es-toolkit';
 import { useFloating, offset, flip, shift, size, autoUpdate, useClick, useDismiss, useHover as useHover$1, safePolygon, useRole, useInteractions, FloatingPortal, useMergeRefs as useMergeRefs$1, FloatingFocusManager, arrow, useTransitionStatus, FloatingArrow } from '@floating-ui/react';
 import { twMerge } from 'tailwind-merge';
@@ -18,8 +18,9 @@ import { useVirtualizer } from '@tanstack/react-virtual';
 import { HelmetProvider, Helmet } from 'react-helmet-async';
 import { Trigger, Content as Content$1, List as List$1, Root } from '@radix-ui/react-tabs';
 import { gzipSync, gunzipSync } from 'fflate';
-import { z } from 'zod';
 import superjson from 'superjson';
+import { z } from 'zod';
+import { dequal } from 'dequal';
 
 const cvaIcon = cvaMerge(["aspect-square", "inline-grid", "relative", "shrink-0"], {
     variants: {
@@ -7544,245 +7545,2284 @@ const SectionHeader = ({ title, subtitle, "data-testid": dataTestId, addons, ref
     return (jsxs("div", { className: "flex flex-col", ref: ref, children: [jsx(HelmetProvider, { children: jsx(Helmet, { title: title }) }), jsxs("div", { className: "mb-2 flex flex-row gap-2", children: [jsxs("div", { className: "flex grow flex-col gap-2", children: [jsx(Heading, { "data-testid": dataTestId, variant: "secondary", children: title }), subtitle ? (jsx(Heading, { subtle: true, variant: "subtitle", children: subtitle })) : null] }), addons !== null && addons !== undefined ? jsx("div", { className: "flex gap-2", children: addons }) : null] }), jsx(Spacer, { size: "small" })] }));
 };
 
-const cvaSidebar = cvaMerge(["apply", "grid", "grid-cols-fr-min", "items-center"]);
-const cvaSidebarChildContainer = cvaMerge(["apply", "flex", "overflow-hidden", "gap-2", "p-1", "max-w-full"], {
-    variants: {
-        breakpoint: {
-            xs: ["xs:overflow-visible", "xs:p-0", "xs:grid", "xs:grid-cols-1", "xs:w-full"],
-            sm: ["sm:overflow-visible", "sm:p-0", "sm:grid", "sm:grid-cols-1", "sm:w-full"],
-            md: ["md:overflow-visible", "md:p-0", "md:grid", "md:grid-cols-1", "md:w-full"],
-            lg: ["lg:overflow-visible", "lg:p-0", "lg:grid", "lg:grid-cols-1", "lg:w-full"],
-            xl: ["xl:overflow-visible", "xl:p-0", "xl:grid", "xl:grid-cols-1", "xl:w-full"],
-            "2xl": ["2xl:overflow-visible", "2xl:p-0", "2xl:grid", "2xl:grid-cols-1", "2xl:w-full"],
-            "3xl": ["3xl:overflow-visible", "3xl:p-0", "3xl:grid", "3xl:grid-cols-1", "3xl:w-full"],
-        },
-    },
-});
-
 /**
- * A hook used to detect what children are overflowing a container.
+ * Differentiate between the first and subsequent renders.
  *
- * @param {OverflowItemsOptions} root0  The options for the hook.
- * @param {number | Array<number>} root0.threshold The threshold for the intersection observer.
- * @returns {object} The overflow items and the ref to the container.
+ * @returns {boolean} Returns true if it is the first render, false otherwise.
  */
-const useOverflowItems = ({ threshold = 1, childUniqueIdentifierAttribute = "id", children, }) => {
-    const [itemOverflowMap, setItemOverflowMap] = useState({});
-    const overflowContainerRef = useRef(null);
-    const observerRef = useRef(null);
-    const handleIntersection = useCallback(entries => {
-        const updatedEntries = {};
-        entries.forEach(entry => {
-            // @ts-expect-error - suppressImplicitAnyIndexErrors
-            const targetElementId = entry.target[childUniqueIdentifierAttribute];
-            if (targetElementId !== null && targetElementId !== undefined && targetElementId !== "") {
-                updatedEntries[targetElementId] = entry.isIntersecting ? false : true;
-            }
+const useIsFirstRender = () => {
+    const [isFirstRender, setIsFirstRender] = useState(true);
+    useLayoutEffect(() => {
+        queueMicrotask(() => {
+            setIsFirstRender(false);
         });
-        setItemOverflowMap(prev => ({ ...prev, ...updatedEntries }));
-    }, [childUniqueIdentifierAttribute]);
-    const observe = useCallback(() => {
-        const node = overflowContainerRef.current;
-        if (node) {
-            const root = overflowContainerRef.current;
-            const options = { root, threshold };
-            const observer = new IntersectionObserver(handleIntersection, options);
-            Array.from(node.children).forEach(child => {
-                observer.observe(child);
-            });
-            observer.observe(node);
-            observerRef.current = observer;
-        }
-    }, [handleIntersection, threshold]);
-    const unobserve = useCallback(() => {
-        const currentObserver = observerRef.current;
-        currentObserver?.disconnect();
-        observerRef.current = null;
     }, []);
-    const initializeObserver = useCallback(() => {
-        unobserve();
-        observe();
-    }, [observe, unobserve]);
-    useEffect(() => {
-        initializeObserver();
-        return () => {
-            unobserve();
-        };
-    }, [initializeObserver, unobserve, children]);
-    return useMemo(() => ({ overflowContainerRef, itemOverflowMap }), [overflowContainerRef, itemOverflowMap]);
+    return isFirstRender;
 };
 
 /**
- * Sidebar renders a responsive horizontal/vertical navigation bar that automatically collapses overflowing items into a MoreMenu.
- * It is rendered horizontally until a given breakpoint, then stacks vertically.
- *
- * **Important:** The Sidebar is just a layout wrapper. You are responsible for styling the children.
- * For the overflow functionality, use `min-w-[*]` or `flex-shrink-0` on child elements.
+ * Width constraint for anchored sheets (start/end positioning).
+ * Uses container-relative units with a pixel cap.
+ */
+/**
+ * Transition timing for snap animations — gentle deceleration with minimal overshoot.
+ */
+const SHEET_TRANSITION_DURATION_MS = 300;
+const SHEET_TRANSITION_DURATION = `${SHEET_TRANSITION_DURATION_MS}ms`;
+const SHEET_TRANSITION_EASING = "cubic-bezier(0.2, 0.0, 0.0, 1.0)";
+/**
+ * Threshold (as a fraction of container height) below the smallest snap
+ * at which the sheet will close on release.
+ */
+const CLOSE_THRESHOLD_FRACTION = 0.15;
+/**
+ * Dead zone in pixels below the smallest snap before the dismiss
+ * visual indicator starts showing. Prevents the cross from appearing
+ * too early when the user barely drags past the lowest snap.
+ */
+const DISMISS_DEAD_ZONE_PX = 20;
+/**
+ * Pixel range within which the snap-proximity visual feedback activates.
+ * The handle widens and darkens as the sheet approaches a snap point.
+ */
+const SNAP_PROXIMITY_RANGE_PX = 50;
+/** Fallback pixel height for the docked state. */
+const DOCKED_HEIGHT_PX = 64;
+/**
+ * Top margin subtracted from the largest snap level so the sheet never
+ * fully covers the container (leaves a small gap at the top).
+ */
+const FULL_HEIGHT_TOP_MARGIN_PX = 40;
+/** Minimum pixel spacing between adjacent snap points (and between dock and first level). */
+const MIN_SNAP_SPACING_PX = 120;
+/** Maximum number of snap levels regardless of available height. */
+const MAX_SNAP_LEVELS = 5;
+/** Minimum number of snap levels when there is enough space. */
+const MIN_SNAP_LEVELS = 2;
+/**
+ * Determines the number of snap levels based on container height.
  *
- * When testing, add `setupIntersectionObserver();` to your `jest.setup.ts` file.
+ * When docking is enabled the dock height is treated as an anchor
+ * and only the space above it is divided into adaptive levels, ensuring
+ * the minimum spacing guarantee applies between dock and first snap too.
+ */
+const getAdaptiveLevelCount = (containerHeight, dockingEnabled, dockedHeightPx = DOCKED_HEIGHT_PX) => {
+    const maxHeight = Math.max(0, containerHeight - FULL_HEIGHT_TOP_MARGIN_PX);
+    if (maxHeight <= 0)
+        return 0;
+    const availableSpace = dockingEnabled ? maxHeight - dockedHeightPx : maxHeight;
+    if (availableSpace <= 0)
+        return 0;
+    const bySpacing = Math.floor(availableSpace / MIN_SNAP_SPACING_PX);
+    return Math.max(MIN_SNAP_LEVELS, Math.min(MAX_SNAP_LEVELS, bySpacing));
+};
+/**
+ * Computes an array of snap level heights in pixels, evenly distributed
+ * across the available space. When docking is enabled the distribution
+ * starts from the docked height rather than 0, so the first level is
+ * always at least `MIN_SNAP_SPACING_PX` above the dock.
  *
- * ### When to use
- * Use Sidebar for secondary in-page navigation (e.g., switching between views within a page). Works well with `Tabs` for page-level navigation.
+ * The resulting heights are sorted ascending (smallest first).
  *
- * ### When not to use
- * Do not use Sidebar for primary app navigation (the main menu). For top-level navigation, use the app shell navigation.
+ * @param containerHeight - Container height in pixels.
+ * @param dockingEnabled - Whether docked mode is available.
+ * @param dockedHeightPx - Pixel height of the docked state (measured from content).
+ * @returns {ReadonlyArray<number>} Array of pixel heights for each snap level.
+ */
+const computeSnapLevelHeights = (containerHeight, dockingEnabled, dockedHeightPx = DOCKED_HEIGHT_PX) => {
+    const levelCount = getAdaptiveLevelCount(containerHeight, dockingEnabled, dockedHeightPx);
+    const maxHeight = Math.max(0, containerHeight - FULL_HEIGHT_TOP_MARGIN_PX);
+    const base = dockingEnabled ? dockedHeightPx : 0;
+    const range = maxHeight - base;
+    if (levelCount <= 0 || range <= 0) {
+        return maxHeight > 0 ? [maxHeight] : [];
+    }
+    const levels = [];
+    for (let i = 0; i < levelCount; i++) {
+        const fraction = (i + 1) / levelCount;
+        levels.push(Math.round(base + fraction * range));
+    }
+    return levels;
+};
+/**
+ * Converts a snap level index to a CSS height string using container-relative units.
  *
- * @example Responsive sidebar with navigation items
- * ```tsx
- * import { Sidebar, Button } from "@trackunit/react-components";
+ * When docking is enabled the height range starts from the docked height
+ * so the CSS value reflects the shifted distribution.
  *
- * const NavigationSidebar = () => (
- *   <Sidebar breakpoint="lg">
- *     <Button id="overview" variant="ghost-neutral" className="min-w-[100px]">
- *       Overview
- *     </Button>
- *     <Button id="assets" variant="ghost-neutral" className="min-w-[100px]">
- *       Assets
- *     </Button>
- *     <Button id="reports" variant="ghost-neutral" className="min-w-[100px]">
- *       Reports
- *     </Button>
- *     <Button id="settings" variant="ghost-neutral" className="min-w-[100px]">
- *       Settings
- *     </Button>
- *   </Sidebar>
- * );
- * ```
- * @param {SidebarProps} props - The props for the Sidebar component
- * @returns {ReactElement} Sidebar component
+ * @param levelIndex - Zero-based snap level index.
+ * @param totalLevels - Total number of snap levels.
+ * @param dockingEnabled - Whether docked mode is available.
+ * @param dockedHeightPx - Pixel height of the docked state (measured from content).
  */
-const Sidebar = ({ childContainerClassName, children, breakpoint = "lg", className, "data-testid": dataTestId = "sidebar", moreMenuProps, menuListProps, overflowThreshold, ref, }) => {
-    const { overflowContainerRef, itemOverflowMap } = useOverflowItems({
-        children,
-        childUniqueIdentifierAttribute: "id",
-        threshold: overflowThreshold ?? 0.8,
-    });
-    const overflowItemCount = objectValues(itemOverflowMap).filter(isOverflowing => isOverflowing).length;
-    const itemVisibilityClassName = (id) => {
-        if (itemOverflowMap[id] === true) {
-            return "invisible";
-        }
-        return "visible";
-    };
-    return (jsxs("div", { className: cvaSidebar({ className }), "data-testid": dataTestId, ref: ref, children: [jsx("div", { className: cvaSidebarChildContainer({ breakpoint, className: childContainerClassName }), "data-testid": `${dataTestId}-child-container`, ref: overflowContainerRef, children: Children.map(children, child => {
-                    return cloneElement(child, {
-                        className: twMerge(child.props.className, itemVisibilityClassName(child.props.id)),
-                    });
-                }) }), overflowItemCount > 0 ? (jsx(MoreMenu, { iconButtonProps: {
-                    variant: "ghost-neutral",
-                }, ...moreMenuProps, className: moreMenuProps?.className, "data-testid": `${dataTestId}-more-menu`, children: close => (jsx(MenuList, { ...menuListProps, "data-testid": dataTestId, children: Children.map(children, child => {
-                        return itemOverflowMap[child.props.id] === true
-                            ? cloneElement(child, {
-                                onClick: e => {
-                                    child.props.onClick?.(e);
-                                    close();
-                                },
-                                className: "w-full",
-                            })
-                            : null;
-                    }) })) })) : null] }));
+const getSnapLevelCssHeight = (levelIndex, totalLevels, dockingEnabled, dockedHeightPx = DOCKED_HEIGHT_PX) => {
+    if (totalLevels <= 0)
+        return "0px";
+    const fraction = (levelIndex + 1) / totalLevels;
+    if (fraction >= 1) {
+        return `calc(100cqh - ${FULL_HEIGHT_TOP_MARGIN_PX}px)`;
+    }
+    if (dockingEnabled) {
+        return `calc(${dockedHeightPx}px + ${fraction} * (100cqh - ${FULL_HEIGHT_TOP_MARGIN_PX + dockedHeightPx}px))`;
+    }
+    return `calc(${fraction} * (100cqh - ${FULL_HEIGHT_TOP_MARGIN_PX}px))`;
 };
 
-const cvaTabsRoot = cvaMerge([]);
-const cvaTabList = cvaMerge([
-    "flex",
-    "flex-row",
-    "border-b",
-    "border-b-neutral-200",
-    "overflow-auto",
-    "no-scrollbar",
-]);
-const cvaTabContent = cvaMerge([]);
-const cvaTab = cvaMerge([
-    "flex",
-    "items-center",
-    "justify-center",
-    "gap-2",
-    "text-sm",
-    "px-6",
-    "py-2",
-    "cursor-pointer",
-    "transition",
-    "duration-200",
-    "ease-in-out",
-    "whitespace-nowrap",
-    "border-b-2",
-    "border-b-transparent",
-    "hover:border-b-transparent",
-    "data-[state=active]:border-b-primary-600",
-    "data-[state=active]:font-semibold",
-    "data-[state=active]:text-neutral-900",
-    "data-[state=inactive]:font-medium",
-    "data-[state=inactive]:text-neutral-700",
-    "data-[state=inactive]:hover:text-neutral-900",
-    "disabled:cursor-not-allowed",
-    "data-[state=active]disabled:text-neutral-400",
-    "data-[state=inactive]:disabled:text-neutral-400",
-], {
+/**
+ * Container wrapper that creates the positioning context and container query
+ * context for the Sheet. Sets `container-type: size` so cqh and cqw units
+ * resolve against this wrapper's dimensions.
+ *
+ * Always absolutely positioned within the provided container element.
+ */
+const cvaSheetContainer = cvaMerge(["absolute", "inset-0", "z-overlay", "overflow-clip", "[container-type:size]"], {
     variants: {
-        isFullWidth: {
-            true: "w-full",
-            false: "",
+        docked: {
+            true: ["pointer-events-none"],
+            false: [],
         },
     },
     defaultVariants: {
-        isFullWidth: false,
+        docked: false,
     },
 });
-
 /**
- * Tab is an individual tab trigger within a TabList.
- * Each Tab requires a unique `value` prop that corresponds to a TabContent with the same value.
- * Supports optional icons, suffixes (e.g., badges), and rendering as a custom child element via `asChild`.
- *
- * ### When to use
- * Use Tab inside a `TabList` to create clickable tab triggers. Each Tab maps to a `TabContent` panel.
+ * Sheet panel — the main content surface, always positioned at the bottom
+ * of the container.
  *
- * ### When not to use
- * Do not use Tab outside of a `TabList`/`Tabs` context. For standalone buttons, use `Button`.
+ * Height and vertical positioning are controlled via inline styles returned
+ * by `getSheetPanelStyle()`:
  *
- * @example Tab with icon and badge suffix
- * ```tsx
- * import { Tabs, TabList, Tab, TabContent, Badge } from "@trackunit/react-components";
+ * - `height`: Target height for the current snap (e.g., "50cqh"), or
+ *   `--sheet-drag-height` during drag so the sheet stays anchored at the bottom
+ * - `transform`: translateY for entry slide-up animation
+ * - `transition`: separate curves for entry (transform), close (height collapse),
+ *    and snap changes (height)
  *
- * const TabsWithBadge = () => (
- *   <Tabs defaultValue="alerts">
- *     <TabList>
- *       <Tab value="alerts" iconName="Bell" suffix={<Badge count={3} color="danger" />}>
- *         Alerts
- *       </Tab>
- *       <Tab value="history" iconName="Clock">History</Tab>
- *     </TabList>
- *     <TabContent value="alerts">Active alerts</TabContent>
- *     <TabContent value="history">Event history</TabContent>
- *   </Tabs>
- * );
- * ```
- * @param {TabProps} props - The props for the Tab component
- * @returns {ReactElement} Tab component
+ * During drag, the gesture hook sets `--sheet-drag-height` and `transition: none`
+ * directly on the element for immediate visual feedback, then restores on release.
  */
-const Tab = ({ value, isFullWidth = false, iconName = undefined, "data-testid": dataTestId, className, children, suffix, asChild = false, appendTabStylesToChildIfAsChild = true, ref, ...rest }) => {
-    const renderContent = () => (jsxs(Fragment, { children: [iconName !== undefined ? jsx(Icon, { name: iconName, size: "small" }) : null, isValidElement(children) ? children.props.children : children, suffix] }));
-    const commonProps = {
-        className: appendTabStylesToChildIfAsChild ? cvaTab({ className, isFullWidth }) : className,
-        ...rest,
-    };
-    return (jsx(Trigger, { asChild: true, ref: ref, value: value, children: asChild && typeof children !== "string" ? (cloneElement(children, {
-            ...commonProps,
-            children: renderContent(),
-        })) : (jsx("button", { ...commonProps, "data-testid": dataTestId, children: renderContent() })) }));
-};
-
+const cvaSheetPanel = cvaMerge(["absolute", "bottom-0", "flex", "flex-col", "pointer-events-auto", "rounded-b-none", "rounded-t-xl", "z-overlay"], {
+    variants: {
+        anchor: {
+            center: ["inset-x-0", "mx-auto", "max-w-3xl"],
+            start: ["left-[12px]", "max-w-[min(90cqw,420px)]"],
+            end: ["right-[12px]", "max-w-[min(90cqw,420px)]"],
+        },
+        variant: {
+            default: [],
+            modal: [],
+            floating: ["rounded-b-xl", "bottom-[12px]"],
+        },
+    },
+    defaultVariants: {
+        anchor: "center",
+        variant: "default",
+    },
+});
 /**
- * TabContent is the content panel displayed when its corresponding Tab is active.
- * Each TabContent must have a `value` prop that matches the `value` of its corresponding Tab trigger.
- * TabContent is only rendered when its tab is selected (unless `forceMount` is set).
- *
- * ### When to use
- * Use TabContent inside a `Tabs` component, one for each `Tab` trigger.
- *
- * ### When not to use
- * Do not use TabContent outside of a `Tabs` context. For conditionally shown content, use standard conditional rendering.
+ * Scrollable area below the drag handle. Nested inside the Sheet panel (Card)
+ * so the Card's base `overflow-clip` clips this element's scrollbar at the
+ * rounded corners. The handle stays fixed above, outside the scroll context.
+ *
+ * `fillHeight` controls whether the scroll area stretches to fill available
+ * panel space. Enabled for level/docked modes (fixed panel height); disabled
+ * for fit mode so that `scrollHeight` reflects natural content height rather
+ * than the stretched layout — critical for correct fit-height measurement.
+ */
+const cvaSheetScrollArea = cvaMerge(["flex", "flex-col", "min-h-0", "overflow-x-hidden", "overflow-y-auto"], {
+    variants: {
+        fillHeight: {
+            true: ["flex-grow"],
+            false: [],
+        },
+    },
+    defaultVariants: {
+        fillHeight: true,
+    },
+});
+/**
+ * CSS transition shorthand for the sheet panel during normal (open) state.
+ * Animates both `transform` (entry slide-up) and `height` (snap changes).
+ */
+const SHEET_OPEN_TRANSITION = `transform ${SHEET_TRANSITION_DURATION} ${SHEET_TRANSITION_EASING}, height ${SHEET_TRANSITION_DURATION} ${SHEET_TRANSITION_EASING}`;
+/**
+ * Transform-only transition for auto-height mode during entry. Height is
+ * excluded because modern browsers (Chrome 129+) can transition `fit-content`
+ * via `interpolate-size: allow-keywords`, which causes unwanted height
+ * animation as content mounts during the slide-up.
+ */
+const SHEET_TRANSFORM_TRANSITION = `transform ${SHEET_TRANSITION_DURATION} ${SHEET_TRANSITION_EASING}`;
+/**
+ * Height-only transition for the collapse phase of the close animation.
+ */
+const SHEET_CLOSE_TRANSITION = `height ${SHEET_TRANSITION_DURATION} ${SHEET_TRANSITION_EASING}`;
+// ---------------------------------------------------------------------------
+// Close animation strategies (per variant)
+// ---------------------------------------------------------------------------
+/** Height the floating variant collapses to before the vanish phase. */
+const FLOATING_COLLAPSE_HEIGHT_PX = 20;
+/** Snappy transition for the floating vanish phase (scale + fade). */
+const FLOATING_VANISH_TRANSITION = `opacity 120ms ease-out, transform 120ms ease-out`;
+/**
+ * default / modal — single-phase collapse to zero height.
+ * Unmounts when height reaches 0.
+ */
+const getDefaultCloseStyle = () => ({
+    height: "0",
+    overflow: "hidden",
+    transition: SHEET_CLOSE_TRANSITION,
+});
+/**
+ * floating — two-phase close:
+ * 1. "collapsing" shrinks height to a small pill.
+ * 2. "vanishing" scales down and fades out the remaining pill.
+ */
+const getFloatingCloseStyle = (phase) => {
+    switch (phase) {
+        case "collapsing":
+            return {
+                height: `${FLOATING_COLLAPSE_HEIGHT_PX}px`,
+                overflow: "hidden",
+                transition: SHEET_CLOSE_TRANSITION,
+            };
+        case "vanishing":
+            return {
+                height: `${FLOATING_COLLAPSE_HEIGHT_PX}px`,
+                opacity: 0,
+                overflow: "hidden",
+                transform: "scale(0.8)",
+                transition: FLOATING_VANISH_TRANSITION,
+            };
+        default:
+            return {};
+    }
+};
+/**
+ * Resolves the close-animation CSS for the given variant and phase.
+ */
+const getCloseStyle = (variant, phase) => {
+    switch (variant) {
+        case "floating":
+            return getFloatingCloseStyle(phase);
+        case "default":
+        case "modal":
+            return getDefaultCloseStyle();
+        default:
+            return getDefaultCloseStyle();
+    }
+};
+// ---------------------------------------------------------------------------
+/**
+ * Returns inline styles for the sheet panel element.
+ *
+ * Entry animation uses a transform slide-up (translateY 100% → 0).
+ * Close animation is variant-aware — see `getCloseStyle` for details.
+ * Snap-level changes animate height while the sheet is open.
+ */
+const getSheetPanelStyle = ({ snapHeight, isOpen, closePhase, variant, autoHeight, maxHeight, isDragging, suppressTransition = false, }) => {
+    if (closePhase !== "idle") {
+        return getCloseStyle(variant, closePhase);
+    }
+    return {
+        height: autoHeight ? "fit-content" : `var(--sheet-drag-height, ${snapHeight})`,
+        maxHeight: maxHeight ?? `calc(100cqh - ${FULL_HEIGHT_TOP_MARGIN_PX}px)`,
+        pointerEvents: "auto",
+        transform: isOpen
+            ? "translateY(0) scale(var(--sheet-stack-scale, 1))"
+            : "translateY(100%) scale(var(--sheet-stack-scale, 1))",
+        transformOrigin: "bottom center",
+        transition: isDragging
+            ? "none"
+            : suppressTransition || autoHeight || !isOpen
+                ? SHEET_TRANSFORM_TRANSITION
+                : SHEET_OPEN_TRANSITION,
+    };
+};
+
+/**
+ * Centralized visual intensity parameters for the sheet handle line.
+ *
+ * All values control the handle bar (line) color, which mixes between
+ * `base` and `emphasized` colors. The mixing factor is the maximum of:
+ * - `--sheet-dismiss-progress` (0-1, set on the panel by gesture hook or Sheet effect)
+ * - `--sheet-snap-proximity` * proximityWeight (approaching a snap point)
+ * - `--handle-interaction` (hover / dragging / pressed states below)
+ *
+ * Interaction values are set via CSS custom property on the handle div
+ * (Tailwind arbitrary properties + pseudo-classes). Keep these in sync
+ * with the CVA class strings in `cvaSheetHandle`.
+ */
+const HANDLE_VISUALS = {
+    line: {
+        base: "var(--color-neutral-300)",
+        emphasized: "var(--color-neutral-600)",
+        proximityWeight: 0.5,
+    },
+};
+const cvaSheetHandle = cvaMerge([
+    "flex",
+    "items-center",
+    "justify-center",
+    "w-full",
+    "py-3",
+    "touch-action-none",
+    "select-none",
+    "shrink-0",
+    "bg-white",
+], {
+    variants: {
+        isDragging: {
+            true: ["cursor-grabbing", "[--handle-interaction:0.25]"],
+            false: [
+                "cursor-grab",
+                "[--handle-interaction:0]",
+                "hover:[--handle-interaction:0.15]",
+                "active:[--handle-interaction:0.5]",
+            ],
+        },
+    },
+    defaultVariants: {
+        isDragging: false,
+    },
+});
+const cvaSheetHandleLine = cvaMerge(["w-8", "h-1", "rounded-full", "origin-center"], {
+    variants: {
+        isDragging: {
+            true: [],
+            false: ["[transition:width_150ms_ease,background-color_150ms_ease]"],
+        },
+    },
+    defaultVariants: {
+        isDragging: false,
+    },
+});
+const handleBackgroundColor = `color-mix(in srgb, ${HANDLE_VISUALS.line.base} calc(100% - 100% * max(var(--sheet-dismiss-progress, 0), var(--sheet-snap-proximity, 0) * ${HANDLE_VISUALS.line.proximityWeight}, var(--handle-interaction, 0))), ${HANDLE_VISUALS.line.emphasized} calc(100% * max(var(--sheet-dismiss-progress, 0), var(--sheet-snap-proximity, 0) * ${HANDLE_VISUALS.line.proximityWeight}, var(--handle-interaction, 0))))`;
+/**
+ * Visual drag indicator at the top of the Sheet.
+ *
+ * Renders a single handle line that narrows into a short stub as the user
+ * drags toward the dismiss threshold, with color fading from neutral to dark.
+ * The dismiss visual is driven entirely by the `--sheet-dismiss-progress`
+ * CSS custom property set on the parent panel element — this component
+ * has no dismiss-related state or logic.
+ *
+ * Accepts pointer event handlers from useSheetGestures and forwards them
+ * to the handle element. The element has `touch-action: none` so pointer
+ * events work reliably on touch devices.
+ */
+const SheetHandle = ({ onPointerDown, onPointerMove, onPointerUp, onLostPointerCapture, onClick, isDragging = false, onMouseEnter, onMouseLeave, "data-testid": dataTestId, }) => {
+    // Reaches 1 before dismiss-progress does (×1.3) so the visual
+    // completes early, giving a snappy feel before the sheet actually closes.
+    const dismissIntensity = "min(1, var(--sheet-dismiss-progress, 0) * 1.3)";
+    // Width multiplier components (base 2rem = 32px, height is h-1 = 4px):
+    //   1                          → resting width: 32px
+    //   + stretch  * 0.5           → widens up to 48px when over-pulling upward
+    //   - dismiss  * 0.75          → shrinks to 0.25× = 8px at full dismiss (2× height, short stub)
+    //   + snap     * 0.15          → subtle widen when approaching a snap point
+    const handleWidth = `calc(2rem * (1 + var(--sheet-stretch-progress, 0) * 0.5 - ${dismissIntensity} * 0.75 + var(--sheet-snap-proximity, 0) * 0.15))`;
+    return (jsx("div", { "aria-label": "Sheet drag handle", className: cvaSheetHandle({ isDragging }), "data-sheet-handle": true, "data-testid": dataTestId, onClick: onClick, onLostPointerCapture: onLostPointerCapture, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, onPointerDown: onPointerDown, onPointerMove: onPointerMove, onPointerUp: onPointerUp, role: "separator", children: jsx("div", { className: cvaSheetHandleLine({ isDragging }), style: {
+                backgroundColor: handleBackgroundColor,
+                width: handleWidth,
+            } }) }));
+};
+
+const cvaSheetOverlay = cvaMerge(["absolute", "inset-0", "transition-opacity", "duration-300", "[transition-timing-function:cubic-bezier(0.2,0,0,1)]"], {
+    variants: {
+        visible: {
+            true: ["bg-black/50", "pointer-events-auto"],
+            false: ["bg-transparent", "pointer-events-none"],
+        },
+    },
+    defaultVariants: {
+        visible: false,
+    },
+});
+/**
+ * Semi-transparent backdrop overlay for the Sheet.
+ *
+ * Fades in/out using CSS transitions. When not visible, the overlay is
+ * transparent with pointer-events disabled so the background remains
+ * interactable. Dismiss is handled by Floating UI's `useDismiss`
+ * outside-press detection — clicks on the visible overlay bubble to the
+ * document where `useDismiss` triggers the close flow.
+ */
+const SheetOverlay = ({ visible, "data-testid": dataTestId }) => (jsx("div", { "aria-hidden": "true", className: cvaSheetOverlay({ visible }), "data-testid": dataTestId }));
+
+const INITIAL_ANIMATION_STATE = {
+    shouldRender: false,
+    visuallyOpen: false,
+    closePhase: "idle",
+    prevIsOpen: false,
+};
+/** Reducer managing the Sheet component's mount/unmount animation lifecycle. */
+const sheetAnimationReducer = (state, action) => {
+    switch (action.type) {
+        case "SYNC_OPEN": {
+            if (action.isOpen === state.prevIsOpen)
+                return state;
+            if (action.isOpen) {
+                return {
+                    ...state,
+                    prevIsOpen: true,
+                    shouldRender: true,
+                    visuallyOpen: action.skipEntryAnimation,
+                    closePhase: "idle",
+                };
+            }
+            return {
+                ...state,
+                prevIsOpen: false,
+                visuallyOpen: false,
+                closePhase: "collapsing",
+            };
+        }
+        case "SET_VISUALLY_OPEN":
+            return state.visuallyOpen ? state : { ...state, visuallyOpen: true };
+        case "UNMOUNT":
+            return state.shouldRender ? { ...state, shouldRender: false, closePhase: "idle" } : state;
+        case "ENSURE_RENDER":
+            return state.shouldRender ? state : { ...state, shouldRender: true };
+        case "START_VANISH":
+            return state.closePhase === "collapsing" ? { ...state, closePhase: "vanishing" } : state;
+        default:
+            return state;
+    }
+};
+
+/**
+ * Manages the dismiss-intent visual on the sheet handle.
+ *
+ * Sets `--sheet-dismiss-progress: 1` on the panel element when the user
+ * signals dismiss intent — either by holding Cmd/Ctrl+Shift while hovering
+ * the handle, or while the close animation is in progress.
+ *
+ * This is the single owner of `--sheet-dismiss-progress` outside of the
+ * gesture hook's drag flow. The gesture hook manages the property during
+ * active drag (continuous 0-1 values); this hook manages it for the
+ * binary on/off dismiss visual (modifier+hover, close animation).
+ */
+const useSheetDismissIntent = ({ closable, closePhase, panelRef, }) => {
+    const [closeModifierHeld, setCloseModifierHeld] = useState(false);
+    const { hovering, onMouseEnter, onMouseLeave } = useHover({ debounced: false });
+    useEffect(() => {
+        if (!closable)
+            return;
+        const update = (e) => {
+            setCloseModifierHeld((e.metaKey || e.ctrlKey) && e.shiftKey);
+        };
+        const reset = () => setCloseModifierHeld(false);
+        window.addEventListener("keydown", update);
+        window.addEventListener("keyup", update);
+        window.addEventListener("blur", reset);
+        return () => {
+            window.removeEventListener("keydown", update);
+            window.removeEventListener("keyup", update);
+            window.removeEventListener("blur", reset);
+        };
+    }, [closable]);
+    const showDismiss = closePhase !== "idle" || (closeModifierHeld && hovering && closable);
+    useEffect(() => {
+        const panel = panelRef.current;
+        if (!panel)
+            return;
+        if (showDismiss) {
+            panel.style.setProperty("--sheet-dismiss-progress", "1");
+        }
+        else {
+            panel.style.removeProperty("--sheet-dismiss-progress");
+        }
+    }, [showDismiss, panelRef]);
+    return useMemo(() => ({ onMouseEnter, onMouseLeave }), [onMouseEnter, onMouseLeave]);
+};
+
+/** Minimum velocity (px/ms) to trigger directional snap selection. */
+const VELOCITY_THRESHOLD = 0.5;
+/** Dampening factor for rubber-band effect past snap bounds. */
+const RUBBER_BAND_FACTOR = 0.3;
+/**
+ * Calculates vertical velocity from pointer position history.
+ * Positive = downward, negative = upward.
+ */
+const calculateVelocity = (samples) => {
+    if (samples.length < 2)
+        return 0;
+    const first = samples[0];
+    const last = samples[samples.length - 1];
+    if (!first || !last)
+        return 0;
+    const dt = last.timestamp - first.timestamp;
+    if (dt === 0)
+        return 0;
+    return (last.y - first.y) / dt;
+};
+/**
+ * Applies rubber-band dampening when the effective height exceeds snap bounds.
+ *
+ * Within [minSnap, maxSnap] the raw drag delta passes through unchanged.
+ * Beyond maxSnap the excess movement is dampened by RUBBER_BAND_FACTOR.
+ *
+ * Below minSnap behaviour depends on `closable`:
+ * - **closable = true** — the sheet follows the finger freely (clamped at 0)
+ *   so the user can always reach the close threshold.
+ * - **closable = false** — rubber-band dampening is applied (same feel as
+ *   the upward over-stretch) because the sheet cannot be dismissed.
+ *
+ * Returns the constrained effective height in pixels.
+ */
+const computeConstrainedEffectiveHeight = (rawDelta, activeSnapHeight, minSnap, maxSnap, closable) => {
+    const effectiveHeight = activeSnapHeight - rawDelta;
+    if (effectiveHeight > maxSnap) {
+        const excess = effectiveHeight - maxSnap;
+        return maxSnap + excess * RUBBER_BAND_FACTOR;
+    }
+    if (effectiveHeight < minSnap) {
+        if (closable) {
+            return Math.max(0, effectiveHeight);
+        }
+        const deficit = minSnap - effectiveHeight;
+        return minSnap - deficit * RUBBER_BAND_FACTOR;
+    }
+    return effectiveHeight;
+};
+/**
+ * Computes how far the sheet has progressed toward dismissal (0 = at min snap, 1 = at close threshold).
+ *
+ * A dead zone below the min snap absorbs small overdrags before the dismiss
+ * indicator starts. Returns 0 when close is not available.
+ */
+const computeDismissProgress = (rawEffectiveHeight, minSnap, containerHeight, closeThresholdFraction, dismissDeadZonePx) => {
+    const closeThreshold = minSnap - containerHeight * closeThresholdFraction;
+    const adjustedMinSnap = minSnap - dismissDeadZonePx;
+    const range = adjustedMinSnap - closeThreshold;
+    if (range <= 0)
+        return 0;
+    return Math.max(0, Math.min(1, (adjustedMinSnap - rawEffectiveHeight) / range));
+};
+/**
+ * Computes a 0-1 proximity value indicating how close the drag position is
+ * to the nearest snap point in the current drag direction.
+ *
+ * 1 = directly at a snap point, 0 = further than `proximityRange` away.
+ */
+const computeSnapProximity = (constrainedHeight, snapHeights, direction, proximityRange) => {
+    let nearestApproachingDist = Infinity;
+    for (const h of snapHeights) {
+        const snapDir = h - constrainedHeight;
+        if (direction * snapDir > 0) {
+            const d = Math.abs(constrainedHeight - h);
+            if (d < nearestApproachingDist)
+                nearestApproachingDist = d;
+        }
+    }
+    return nearestApproachingDist < Infinity ? Math.max(0, 1 - nearestApproachingDist / proximityRange) : 0;
+};
+/**
+ * Resolves the target snap height based on effective position and velocity.
+ *
+ * - High upward velocity -> next larger snap above the current effective height
+ * - High downward velocity -> next smaller snap below the current effective height
+ * - Low velocity -> snap to the nearest point
+ *
+ * snapHeights must be sorted ascending.
+ */
+const resolveSnapTarget = (effectiveHeight, snapHeights, velocity) => {
+    if (snapHeights.length === 0)
+        return 0;
+    if (snapHeights.length === 1)
+        return snapHeights[0] ?? 0;
+    if (velocity < -VELOCITY_THRESHOLD) {
+        for (const height of snapHeights) {
+            if (height > effectiveHeight)
+                return height;
+        }
+        return snapHeights[snapHeights.length - 1] ?? 0;
+    }
+    if (velocity > VELOCITY_THRESHOLD) {
+        for (let i = snapHeights.length - 1; i >= 0; i--) {
+            const height = snapHeights[i];
+            if (height !== undefined && height < effectiveHeight)
+                return height;
+        }
+        return snapHeights[0] ?? 0;
+    }
+    let nearest = snapHeights[0] ?? 0;
+    let minDistance = Math.abs(effectiveHeight - nearest);
+    for (const height of snapHeights) {
+        const distance = Math.abs(effectiveHeight - height);
+        if (distance < minDistance) {
+            minDistance = distance;
+            nearest = height;
+        }
+    }
+    return nearest;
+};
+
+/** Duration (ms) of the fade-out after the sheet arrives at a snap point. */
+const PROXIMITY_FADE_OUT_MS = 150;
+/**
+ * Manages the `--sheet-snap-proximity` CSS custom property animation
+ * during post-release snap transitions.
+ *
+ * Tracks the sheet height via `getBoundingClientRect` each frame,
+ * computes proximity to the target snap, and fades the value out once
+ * the sheet has arrived.
+ */
+const useProximityAnimation = (sheetRef) => {
+    const proximityRafRef = useRef(0);
+    const cancelProximityAnimation = useCallback(() => {
+        if (proximityRafRef.current !== 0) {
+            cancelAnimationFrame(proximityRafRef.current);
+            proximityRafRef.current = 0;
+        }
+        const sheet = sheetRef.current;
+        if (sheet) {
+            sheet.style.removeProperty("--sheet-snap-proximity");
+        }
+    }, [sheetRef]);
+    const startProximityAnimation = useCallback((sheet, targetHeight) => {
+        let fadeOutStart = null;
+        const tick = (timestamp) => {
+            const currentHeight = sheet.getBoundingClientRect().height;
+            const distance = Math.abs(currentHeight - targetHeight);
+            const proximity = Math.max(0, 1 - distance / SNAP_PROXIMITY_RANGE_PX);
+            if (proximity >= 0.95 && fadeOutStart === null) {
+                fadeOutStart = timestamp;
+            }
+            if (fadeOutStart !== null) {
+                const elapsed = timestamp - fadeOutStart;
+                const fadeProgress = Math.min(1, elapsed / PROXIMITY_FADE_OUT_MS);
+                const fadedProximity = proximity * (1 - fadeProgress);
+                if (fadeProgress >= 1) {
+                    sheet.style.removeProperty("--sheet-snap-proximity");
+                    proximityRafRef.current = 0;
+                    return;
+                }
+                sheet.style.setProperty("--sheet-snap-proximity", String(fadedProximity));
+            }
+            else {
+                sheet.style.setProperty("--sheet-snap-proximity", String(proximity));
+            }
+            proximityRafRef.current = requestAnimationFrame(tick);
+        };
+        proximityRafRef.current = requestAnimationFrame(tick);
+    }, []);
+    useEffect(() => cancelProximityAnimation, [cancelProximityAnimation]);
+    return useMemo(() => ({ cancelProximityAnimation, startProximityAnimation }), [cancelProximityAnimation, startProximityAnimation]);
+};
+
+/** Number of pointer samples retained for velocity calculation. */
+const MAX_POINTER_SAMPLES = 5;
+/**
+ * Maximum absolute pointer displacement (in px) for a gesture to qualify
+ * as a tap/click rather than a drag. Keeps click detection robust on
+ * touch screens where fingers wobble slightly.
+ */
+const CLICK_MOVEMENT_THRESHOLD_PX = 5;
+/**
+ * Minimum displacement (px) from the last direction-change position before
+ * the committed drag direction flips. Prevents sub-pixel pointer jitter
+ * from causing rapid direction toggles and visual flickering.
+ */
+const DIRECTION_HYSTERESIS_PX = 2;
+/**
+ * Prevents the spurious native click event that fires after a drag gesture.
+ *
+ * Pointer capture retargets mouseup to the same element as mousedown, so the
+ * browser synthesizes a click even when the pointer traveled far. A one-time
+ * capturing listener stops propagation before React's root delegation sees it.
+ */
+const suppressNextClick = (target) => {
+    target.addEventListener("click", ev => {
+        ev.stopPropagation();
+    }, { once: true, capture: true });
+};
+/**
+ * Hook providing pointer-event-based drag gesture handling for a bottom sheet.
+ *
+ * Uses native Pointer Events with pointer capture for reliable cross-device
+ * tracking. During drag, the hook directly manipulates the sheet element's
+ * `--sheet-drag-height` CSS custom property and disables transitions for
+ * immediate visual feedback. On release, it restores CSS transitions and
+ * calls `onSnap` or `onClose` based on position and velocity.
+ *
+ * The consuming Sheet component should use `height: var(--sheet-drag-height, <snapHeight>)`
+ * so the sheet stays anchored at the bottom while its height changes during drag.
+ */
+const useSheetGestures = (props) => {
+    const { snapHeights, activeSnapHeight, sheetRef, onSnap, onClose, containerHeight, enabled } = props;
+    const [isDragging, setIsDragging] = useState(false);
+    const isDraggingRef = useRef(false);
+    const dragStartYRef = useRef(0);
+    const maxDisplacementRef = useRef(0);
+    const directionAnchorRef = useRef(0);
+    const dragDirectionRef = useRef(0);
+    const pointerSamplesRef = useRef([]);
+    const onSnapRef = useRef(onSnap);
+    const onCloseRef = useRef(onClose);
+    const snapHeightsRef = useRef(snapHeights);
+    const activeSnapHeightRef = useRef(activeSnapHeight);
+    const containerHeightRef = useRef(containerHeight);
+    useLayoutEffect(() => {
+        onSnapRef.current = onSnap;
+        onCloseRef.current = onClose;
+        snapHeightsRef.current = snapHeights;
+        if (!isDraggingRef.current) {
+            activeSnapHeightRef.current = activeSnapHeight;
+        }
+        containerHeightRef.current = containerHeight;
+    });
+    const { cancelProximityAnimation, startProximityAnimation } = useProximityAnimation(sheetRef);
+    const resetDragState = useCallback(() => {
+        if (!isDraggingRef.current)
+            return;
+        isDraggingRef.current = false;
+        setIsDragging(false);
+        pointerSamplesRef.current = [];
+        const sheet = sheetRef.current;
+        if (sheet) {
+            sheet.style.removeProperty("transition");
+            sheet.style.removeProperty("--sheet-drag-height");
+            sheet.style.removeProperty("--sheet-stretch-progress");
+            sheet.style.removeProperty("--sheet-snap-proximity");
+            sheet.style.removeProperty("--sheet-dismiss-progress");
+        }
+    }, [sheetRef]);
+    const onLostPointerCapture = useCallback(() => {
+        resetDragState();
+    }, [resetDragState]);
+    const onPointerDown = useCallback((e) => {
+        if (!enabled || e.button !== 0 || snapHeightsRef.current.length === 0) {
+            return;
+        }
+        e.currentTarget.setPointerCapture(e.pointerId);
+        cancelProximityAnimation();
+        dragStartYRef.current = e.clientY;
+        maxDisplacementRef.current = 0;
+        directionAnchorRef.current = activeSnapHeightRef.current;
+        dragDirectionRef.current = 0;
+        pointerSamplesRef.current = [{ y: e.clientY, timestamp: e.timeStamp }];
+        isDraggingRef.current = true;
+        setIsDragging(true);
+        const sheet = sheetRef.current;
+        if (sheet) {
+            sheet.style.transition = "none";
+        }
+    }, [enabled, sheetRef, cancelProximityAnimation]);
+    const onPointerMove = useCallback((e) => {
+        if (!isDraggingRef.current)
+            return;
+        const rawDelta = e.clientY - dragStartYRef.current;
+        maxDisplacementRef.current = Math.max(maxDisplacementRef.current, Math.abs(rawDelta));
+        const samples = pointerSamplesRef.current;
+        samples.push({ y: e.clientY, timestamp: e.timeStamp });
+        if (samples.length > MAX_POINTER_SAMPLES) {
+            samples.shift();
+        }
+        const snaps = snapHeightsRef.current;
+        const minSnap = snaps[0] ?? 0;
+        const maxSnap = snaps[snaps.length - 1] ?? 0;
+        const closable = onCloseRef.current !== undefined;
+        const constrainedHeight = computeConstrainedEffectiveHeight(rawDelta, activeSnapHeightRef.current, minSnap, maxSnap, closable);
+        const sheet = sheetRef.current;
+        if (sheet) {
+            sheet.style.setProperty("--sheet-drag-height", `${constrainedHeight}px`);
+            const rawEffective = activeSnapHeightRef.current - rawDelta;
+            if (rawEffective > maxSnap) {
+                const stretchAmount = rawEffective - maxSnap;
+                const stretchProgress = Math.min(1, stretchAmount / 80);
+                sheet.style.setProperty("--sheet-stretch-progress", String(stretchProgress));
+                sheet.style.removeProperty("--sheet-dismiss-progress");
+                sheet.style.removeProperty("--sheet-snap-proximity");
+            }
+            else if (rawEffective < minSnap && !closable) {
+                const stretchAmount = minSnap - rawEffective;
+                const stretchProgress = Math.min(1, stretchAmount / 80);
+                sheet.style.setProperty("--sheet-stretch-progress", String(stretchProgress));
+                sheet.style.removeProperty("--sheet-dismiss-progress");
+                sheet.style.removeProperty("--sheet-snap-proximity");
+            }
+            else {
+                sheet.style.removeProperty("--sheet-stretch-progress");
+                let dismissProgress = 0;
+                if (closable) {
+                    dismissProgress = computeDismissProgress(rawEffective, minSnap, containerHeightRef.current, CLOSE_THRESHOLD_FRACTION, DISMISS_DEAD_ZONE_PX);
+                    sheet.style.setProperty("--sheet-dismiss-progress", String(dismissProgress));
+                }
+                const displacement = constrainedHeight - directionAnchorRef.current;
+                if (displacement > DIRECTION_HYSTERESIS_PX && dragDirectionRef.current !== 1) {
+                    dragDirectionRef.current = 1;
+                    directionAnchorRef.current = constrainedHeight;
+                }
+                else if (displacement < -DIRECTION_HYSTERESIS_PX && dragDirectionRef.current !== -1) {
+                    dragDirectionRef.current = -1;
+                    directionAnchorRef.current = constrainedHeight;
+                }
+                if (dismissProgress > 0) {
+                    sheet.style.removeProperty("--sheet-snap-proximity");
+                }
+                else {
+                    const snapProximity = computeSnapProximity(constrainedHeight, snaps, dragDirectionRef.current, SNAP_PROXIMITY_RANGE_PX);
+                    sheet.style.setProperty("--sheet-snap-proximity", String(snapProximity));
+                }
+            }
+        }
+    }, [sheetRef]);
+    const onPointerUp = useCallback((e) => {
+        if (!isDraggingRef.current)
+            return;
+        isDraggingRef.current = false;
+        setIsDragging(false);
+        const sheet = sheetRef.current;
+        const wasClick = maxDisplacementRef.current < CLICK_MOVEMENT_THRESHOLD_PX;
+        if (wasClick) {
+            pointerSamplesRef.current = [];
+            if (sheet) {
+                sheet.style.removeProperty("transition");
+                sheet.style.removeProperty("--sheet-drag-height");
+                sheet.style.removeProperty("--sheet-stretch-progress");
+                sheet.style.removeProperty("--sheet-snap-proximity");
+            }
+            return;
+        }
+        suppressNextClick(e.currentTarget);
+        const rawDelta = e.clientY - dragStartYRef.current;
+        const velocity = calculateVelocity(pointerSamplesRef.current);
+        pointerSamplesRef.current = [];
+        const effectiveHeight = activeSnapHeightRef.current - rawDelta;
+        const snaps = snapHeightsRef.current;
+        const minSnap = snaps[0] ?? 0;
+        const closeThreshold = minSnap - containerHeightRef.current * CLOSE_THRESHOLD_FRACTION;
+        if (effectiveHeight < closeThreshold || (velocity > VELOCITY_THRESHOLD && effectiveHeight < minSnap)) {
+            if (sheet) {
+                sheet.style.removeProperty("--sheet-drag-height");
+                sheet.style.removeProperty("--sheet-stretch-progress");
+                sheet.style.removeProperty("--sheet-snap-proximity");
+                sheet.style.setProperty("--sheet-dismiss-progress", "1");
+            }
+            const closeHandler = onCloseRef.current;
+            if (closeHandler) {
+                closeHandler();
+                return;
+            }
+            onSnapRef.current(minSnap);
+            return;
+        }
+        const targetHeight = resolveSnapTarget(effectiveHeight, snaps, velocity);
+        if (sheet) {
+            sheet.style.removeProperty("--sheet-drag-height");
+            sheet.style.removeProperty("--sheet-dismiss-progress");
+            sheet.style.removeProperty("--sheet-stretch-progress");
+            startProximityAnimation(sheet, targetHeight);
+        }
+        onSnapRef.current(targetHeight);
+    }, [sheetRef, startProximityAnimation]);
+    return useMemo(() => ({
+        onPointerDown,
+        onPointerMove,
+        onPointerUp,
+        onLostPointerCapture,
+        isDragging,
+    }), [onPointerDown, onPointerMove, onPointerUp, onLostPointerCapture, isDragging]);
+};
+
+/**
+ * Manages the Sheet's mount/unmount animation lifecycle.
+ *
+ * - Ensures `shouldRender` is set when re-opening after a stale transitionend closure.
+ * - Triggers the open animation by forcing the browser to acknowledge the
+ *   off-screen `translateY(100%)` position (via `getComputedStyle`) before
+ *   dispatching `SET_VISUALLY_OPEN`, which changes the inline transform to
+ *   `translateY(0)`. The existing CSS transition on `transform` then animates
+ *   the slide-up smoothly.
+ * - Handles `transitionend` on the panel to unmount after the close transition.
+ */
+const useSheetLifecycle = ({ isOpen, entryAnimation, visuallyOpen, variant, container, panelRef, panelEl, dispatch, onCloseComplete, fitHeightReady, }) => {
+    useWatch({
+        value: isOpen,
+        onChange: value => {
+            if (value === true) {
+                dispatch({ type: "ENSURE_RENDER" });
+            }
+        },
+        immediate: true,
+    });
+    useLayoutEffect(() => {
+        if (!isOpen || !entryAnimation || visuallyOpen || !container || !fitHeightReady)
+            return;
+        const panel = panelRef.current;
+        if (!panel)
+            return;
+        void getComputedStyle(panel).transform;
+        dispatch({ type: "SET_VISUALLY_OPEN" });
+    }, [isOpen, entryAnimation, visuallyOpen, container, fitHeightReady, dispatch, panelRef, panelEl]);
+    const isOpenRef = useRef(isOpen);
+    useEffect(() => {
+        isOpenRef.current = isOpen;
+    }, [isOpen]);
+    const variantRef = useRef(variant);
+    useEffect(() => {
+        variantRef.current = variant;
+    }, [variant]);
+    const onCloseCompleteRef = useRef(onCloseComplete);
+    useEffect(() => {
+        onCloseCompleteRef.current = onCloseComplete;
+    }, [onCloseComplete]);
+    const handleTransitionEnd = useCallback((e) => {
+        if (e.target !== e.currentTarget || isOpenRef.current)
+            return;
+        switch (e.propertyName) {
+            case "height":
+                if (variantRef.current === "floating") {
+                    dispatch({ type: "START_VANISH" });
+                }
+                else {
+                    dispatch({ type: "UNMOUNT" });
+                    onCloseCompleteRef.current?.();
+                }
+                break;
+            case "opacity":
+                dispatch({ type: "UNMOUNT" });
+                onCloseCompleteRef.current?.();
+                break;
+        }
+    }, [dispatch]);
+    return useMemo(() => ({ handleTransitionEnd }), [handleTransitionEnd]);
+};
+
+const EMPTY_SNAP_HEIGHTS = [];
+const sortAscending = (a, b) => a - b;
+/**
+ * Computes the active snap height in pixels for the current display state.
+ *
+ * Docked → measured docked height.
+ * Fit mode with a measured height → use that height.
+ * Otherwise → look up the level height from the precomputed array.
+ */
+const computeActiveSnapHeight = (sizingMode, fitHeight, levelHeights, displayLevel, dockedHeightPx = DOCKED_HEIGHT_PX) => {
+    if (sizingMode === "docked")
+        return dockedHeightPx;
+    if (sizingMode === "fit" && fitHeight > 0)
+        return fitHeight;
+    return levelHeights[displayLevel] ?? 0;
+};
+/**
+ * Builds the set of pixel heights the gesture system snaps to.
+ *
+ * - Snapping disabled → empty array.
+ * - Fit mode with measured height → `[dockedHeight?, fitHeight]`.
+ * - Fit mode before measurement → falls back to level-based snaps.
+ * - Normal mode → level heights with optional docked height prepended.
+ *
+ * The returned array is always sorted ascending.
+ */
+const computeGestureSnapHeights = (effectiveSnapping, sizingMode, fitHeight, levelHeights, dockingEnabled, dockedHeightPx = DOCKED_HEIGHT_PX) => {
+    if (!effectiveSnapping)
+        return EMPTY_SNAP_HEIGHTS;
+    if (sizingMode === "fit") {
+        if (fitHeight <= 0) {
+            const fallbackHeights = [...levelHeights];
+            if (dockingEnabled) {
+                fallbackHeights.unshift(dockedHeightPx);
+            }
+            return fallbackHeights.length > 0 ? fallbackHeights.toSorted(sortAscending) : EMPTY_SNAP_HEIGHTS;
+        }
+        const fitHeights = [fitHeight, ...levelHeights];
+        if (dockingEnabled) {
+            fitHeights.push(dockedHeightPx);
+        }
+        return fitHeights.toSorted(sortAscending);
+    }
+    const heights = [...levelHeights];
+    if (dockingEnabled) {
+        heights.unshift(dockedHeightPx);
+    }
+    return heights.toSorted(sortAscending);
+};
+
+/**
+ * Temporarily overrides an element's styles to measure its natural content
+ * height, then restores the originals. Extracted from the hook body so the
+ * lint rule for hook-parameter immutability does not flag the mutations.
+ */
+const measureFallback = (el) => {
+    const prevHeight = el.style.height;
+    const prevOverflow = el.style.overflow;
+    const prevTransition = el.style.transition;
+    el.style.height = "auto";
+    el.style.overflow = "visible";
+    el.style.transition = "none";
+    const height = el.scrollHeight;
+    const fallbackStyle = getComputedStyle(el);
+    const totalBorder = (parseFloat(fallbackStyle.borderTopWidth) || 0) + (parseFloat(fallbackStyle.borderBottomWidth) || 0);
+    el.style.height = prevHeight;
+    el.style.overflow = prevOverflow;
+    el.style.transition = prevTransition;
+    return height + totalBorder;
+};
+/**
+ * Clones the element, measures its natural content height via scrollHeight,
+ * and commits the result to the provided setter. Falls back to a temporary
+ * inline-style override if the clone reports zero (e.g. in jsdom).
+ */
+const measureAndCommit = (element, commit) => {
+    const clone = element.cloneNode(true);
+    if (!(clone instanceof HTMLDivElement))
+        return;
+    clone.style.cssText = `
+    position: absolute;
+    visibility: hidden;
+    height: auto;
+    overflow: visible;
+    pointer-events: none;
+  `;
+    const container = element.parentElement ?? document.body;
+    container.appendChild(clone);
+    const cloneScrollH = clone.scrollHeight;
+    let measured;
+    if (cloneScrollH > 0) {
+        const cloneStyle = getComputedStyle(clone);
+        measured =
+            cloneScrollH + (parseFloat(cloneStyle.borderTopWidth) || 0) + (parseFloat(cloneStyle.borderBottomWidth) || 0);
+    }
+    else {
+        measured = measureFallback(element);
+    }
+    clone.remove();
+    commit(measured);
+};
+/**
+ * Measures the panel's natural content height when docked and persists it for
+ * the next dock transition.
+ *
+ * The stored "last measured" height is used as the animation target when
+ * transitioning from expanded to docked, so the sheet animates smoothly to
+ * the correct height. If no value has been stored yet (first dock), the
+ * consumer falls back to DOCKED_HEIGHT_PX — no animation is acceptable.
+ *
+ * When transitioning from expanded to docked, the panel retains its previous
+ * height during layout, so scrollHeight returns the expanded value. We measure
+ * via a hidden clone (height: auto) so we never mutate the panel — the height
+ * transition runs without disruption.
+ *
+ * The value is intentionally NOT reset when leaving docked mode, so re-entry
+ * always has the correct target for the animation.
+ *
+ * Does NOT use a ResizeObserver because the gesture system manipulates the
+ * element's CSS height during drag, which inflates `scrollHeight` beyond the
+ * true content size and would create a feedback loop.
+ *
+ * Returns 0 before the first measurement. The consumer falls back to
+ * DOCKED_HEIGHT_PX until a positive value is available.
+ */
+const useDockedContentHeight = (element, shouldRender, sizingMode) => {
+    const [lastMeasuredHeight, setLastMeasuredHeight] = useState(0);
+    useLayoutEffect(() => {
+        if (!shouldRender || sizingMode !== "docked" || !element)
+            return undefined;
+        measureAndCommit(element, setLastMeasuredHeight);
+        return undefined;
+    }, [shouldRender, sizingMode, element]);
+    return lastMeasuredHeight;
+};
+
+/**
+ * Measures the panel's natural content height for fit mode via ResizeObserver.
+ *
+ * Only active when `sizingMode` is `"fit"` and the panel is visible (docked
+ * height is measured separately by useDockedContentHeight).
+ *
+ * Measures the sum of children's `scrollHeight` rather than the panel's own
+ * `scrollHeight`. This is necessary because children with their own scroll
+ * context absorb overflow, which would make the panel's `scrollHeight` equal
+ * its `clientHeight` (creating a feedback loop where the height shrinks by
+ * the border size each cycle).
+ *
+ * Relies on the scroll area not having `flex-grow` in fit mode (controlled
+ * by the `fillHeight` CVA variant on the scroll area element). Without this,
+ * a flex-grown scroll area at expanded height would report its stretched
+ * `clientHeight` as `scrollHeight`, making the measured fit height equal
+ * the expanded height.
+ *
+ * The initial measurement sets the height directly. Subsequent
+ * ResizeObserver callbacks only allow the height to increase, preventing
+ * stacking overrides or other transient constraints from permanently
+ * reducing the measured height.
+ *
+ * Accepts the DOM element directly (rather than a RefObject) so that the
+ * layoutEffect re-runs whenever the element becomes available — critical
+ * because FloatingPortal defers its first render, meaning the element is
+ * null on the first layout pass and only non-null after FloatingPortal's
+ * own layoutEffect fires and the Card mounts.
+ */
+const useSheetFitHeight = (element, sizingMode, shouldRender) => {
+    const [fitHeight, setFitHeight] = useState(0);
+    useLayoutEffect(() => {
+        if (sizingMode !== "fit" || !shouldRender || !element)
+            return undefined;
+        const measureChildren = () => {
+            let total = 0;
+            for (let i = 0; i < element.children.length; i++) {
+                total += element.children[i]?.scrollHeight ?? 0;
+            }
+            const style = getComputedStyle(element);
+            total += parseFloat(style.borderTopWidth) + parseFloat(style.borderBottomWidth);
+            return total;
+        };
+        let isInitialObservation = true;
+        const observer = new ResizeObserver(() => {
+            const height = measureChildren();
+            if (isInitialObservation) {
+                isInitialObservation = false;
+                setFitHeight(height);
+            }
+            else {
+                setFitHeight(prev => Math.max(prev, height));
+            }
+        });
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [sizingMode, shouldRender, element]);
+    // Return 0 when the panel element is not mounted so that fitHeightReady stays
+    // false until the panel is actually in the DOM. Without this, a stale fitHeight
+    // from a previous open would make fitHeightReady=true immediately on re-open,
+    // causing SET_VISUALLY_OPEN to dispatch before the browser has painted the
+    // initial translateY(100%) baseline — resulting in no visible animation
+    // (sheet just appears at the open position) on subsequent opens.
+    return element !== null ? fitHeight : 0;
+};
+
+/**
+ * Consolidates container/panel measurement, docked/fit height tracking,
+ * the `onGeometryChange` feedback loop, and all derived snap geometry that Sheet
+ * needs for gestures and CSS sizing.
+ */
+const useSheetMeasurements = ({ shouldRender, state, dockingEnabled, snapping, externalRef, onGeometryChange, onSnap, }) => {
+    const { geometry: containerGeometry, ref: containerRef } = useMeasure();
+    const containerHeight = containerGeometry?.height ?? 0;
+    const { ref: panelRef, element: panelEl } = useMeasure({ skip: !shouldRender });
+    const mergedPanelRef = useMergeRefs([panelRef, externalRef]);
+    const panelRefObj = useRef(null);
+    useLayoutEffect(() => {
+        panelRefObj.current = panelEl ?? null;
+    }, [panelEl]);
+    const lastMeasuredDockedHeight = useDockedContentHeight(panelEl, shouldRender, state.sizingMode);
+    const fitHeight = useSheetFitHeight(panelEl, state.sizingMode, shouldRender);
+    const fitHeightReady = state.sizingMode !== "fit" || fitHeight > 0;
+    useEffect(() => {
+        onGeometryChange({ containerHeight, fitHeight, dockedHeight: lastMeasuredDockedHeight }, dockingEnabled);
+    }, [onGeometryChange, containerHeight, fitHeight, lastMeasuredDockedHeight, dockingEnabled]);
+    const maxSheetHeightPx = Math.max(0, containerHeight - FULL_HEIGHT_TOP_MARGIN_PX);
+    const cappedFitHeight = containerHeight > 0 && fitHeight > 0 ? Math.min(fitHeight, maxSheetHeightPx) : fitHeight;
+    const activeSnapHeightPx = computeActiveSnapHeight(state.sizingMode, cappedFitHeight, state.levelHeights, state.level, state.effectiveDockedHeight);
+    const gestureSnapHeights = useMemo(() => computeGestureSnapHeights(snapping, state.sizingMode, cappedFitHeight, state.levelHeights, dockingEnabled, state.effectiveDockedHeight), [snapping, state.sizingMode, cappedFitHeight, state.levelHeights, dockingEnabled, state.effectiveDockedHeight]);
+    const handleGestureSnap = useCallback((heightPx) => {
+        onSnap(heightPx, state.sizingMode === "fit" && fitHeight <= 0);
+    }, [onSnap, state.sizingMode, fitHeight]);
+    return useMemo(() => ({
+        containerRef,
+        mergedPanelRef,
+        panelRefObj,
+        panelEl: panelEl ?? null,
+        containerHeight,
+        activeSnapHeightPx,
+        gestureSnapHeights,
+        cappedFitHeight,
+        fitHeightReady,
+        fitHeight,
+        handleGestureSnap,
+    }), [
+        containerRef,
+        mergedPanelRef,
+        panelRefObj,
+        panelEl,
+        containerHeight,
+        activeSnapHeightPx,
+        gestureSnapHeights,
+        cappedFitHeight,
+        fitHeightReady,
+        fitHeight,
+        handleGestureSnap,
+    ]);
+};
+
+/**
+ * Blocks scrolling on the document and compensates for scrollbar width to prevent layout shift.
+ * Uses scrollbar-gutter: stable to reserve space for the scrollbar when hiding overflow,
+ * but only if a scrollbar was actually visible before blocking.
+ * This only has an effect with classic scrollbars - overlay scrollbars (macOS default) are unaffected.
+ * Returns the original styles so they can be restored later.
+ *
+ * @returns {OriginalStyles} The original styles before blocking
+ */
+const blockDocumentScroll = () => {
+    const { body } = document;
+    const html = document.documentElement;
+    // Check if there's a visible scrollbar before we hide it
+    // The scrollbar can be on either <html> or <body> depending on CSS setup
+    // (e.g., Storybook sets overflow:hidden on html and overflow:auto on body)
+    // Check html scrollbar: window.innerWidth includes scrollbar, clientWidth doesn't
+    const htmlScrollbarWidth = window.innerWidth - html.clientWidth;
+    // Check body scrollbar: offsetWidth includes border+scrollbar, clientWidth excludes both
+    const bodyStyle = window.getComputedStyle(body);
+    const bodyBorderLeft = parseInt(bodyStyle.borderLeftWidth) || 0;
+    const bodyBorderRight = parseInt(bodyStyle.borderRightWidth) || 0;
+    const bodyScrollbarWidth = body.offsetWidth - bodyBorderLeft - bodyBorderRight - body.clientWidth;
+    // Use whichever scrollbar is present
+    const hasVisibleScrollbar = htmlScrollbarWidth > 0 || bodyScrollbarWidth > 0;
+    // Store original values before modifying
+    const originalStyles = {
+        html: {
+            position: html.style.position,
+            overflow: html.style.overflow,
+        },
+        body: {
+            position: body.style.position,
+            overflow: body.style.overflow,
+            scrollbarGutter: body.style.scrollbarGutter,
+        },
+    };
+    // Block scroll on both html and body for cross-browser compatibility
+    html.style.position = "relative";
+    html.style.overflow = "hidden";
+    body.style.position = "relative";
+    body.style.overflow = "hidden";
+    // Apply scrollbar-gutter on body (where the scrollbar typically lives when content scrolls)
+    // This reserves space for the scrollbar even when overflow is hidden, preventing layout shift.
+    // Only has effect with classic scrollbars - overlay scrollbars (macOS default) are unaffected.
+    if (hasVisibleScrollbar) {
+        body.style.scrollbarGutter = "stable";
+    }
+    return originalStyles;
+};
+/**
+ * Restores document scrolling by restoring the provided original styles.
+ *
+ * @param originalStyles - The original styles to restore
+ */
+const restoreDocumentScroll = (originalStyles) => {
+    const { body } = document;
+    const html = document.documentElement;
+    // Restore original values instead of just clearing
+    if (originalStyles.html) {
+        html.style.position = originalStyles.html.position;
+        html.style.overflow = originalStyles.html.overflow;
+    }
+    if (originalStyles.body) {
+        body.style.position = originalStyles.body.position;
+        body.style.overflow = originalStyles.body.overflow;
+        body.style.scrollbarGutter = originalStyles.body.scrollbarGutter;
+    }
+};
+/**
+ * Blocks scrolling on a custom container element.
+ * Uses scrollbar-gutter: stable to reserve space for the scrollbar when hiding overflow,
+ * but only if a scrollbar was actually visible before blocking.
+ * This only has an effect with classic scrollbars - overlay scrollbars (macOS default) are unaffected.
+ * Returns the original styles so they can be restored later.
+ *
+ * @param container - The container element to block scroll on
+ * @returns {OriginalStyles} The original styles before blocking
+ */
+const blockContainerScroll = (container) => {
+    // Check if there's a visible scrollbar before we hide it
+    // offsetWidth includes border + scrollbar, clientWidth excludes both
+    // We need to subtract borders to isolate the scrollbar width
+    const style = window.getComputedStyle(container);
+    const borderLeft = parseInt(style.borderLeftWidth) || 0;
+    const borderRight = parseInt(style.borderRightWidth) || 0;
+    const scrollbarWidth = container.offsetWidth - borderLeft - borderRight - container.clientWidth;
+    const hasVisibleScrollbar = scrollbarWidth > 0;
+    const originalStyles = {
+        container: {
+            overflow: container.style.overflow,
+            scrollbarGutter: container.style.scrollbarGutter,
+        },
+    };
+    container.style.overflow = "hidden";
+    // Only add scrollbar-gutter if there was a visible scrollbar to preserve space for
+    // This prevents adding unnecessary space when content doesn't overflow
+    if (hasVisibleScrollbar) {
+        container.style.scrollbarGutter = "stable";
+    }
+    return originalStyles;
+};
+/**
+ * Restores container scrolling by restoring the provided original styles.
+ *
+ * @param container - The container element to restore scroll on
+ * @param originalStyles - The original styles to restore
+ */
+const restoreContainerScroll = (container, originalStyles) => {
+    if (originalStyles.container) {
+        container.style.overflow = originalStyles.container.overflow;
+        container.style.scrollbarGutter = originalStyles.container.scrollbarGutter;
+    }
+};
+/**
+ * Hook that provides scroll blocking functionality.
+ * This properly accounts for existing body padding to prevent layout shifts.
+ *
+ * Each instance gets its own stored original styles via refs, preventing
+ * conflicts when multiple components are used on the same page. The hook also ensures
+ * cleanup on unmount if scroll is still blocked.
+ *
+ * @param scrollContainer - The DOM element whose scroll should be blocked. Defaults to document.body.
+ * @returns {{blockScroll: () => void, restoreScroll: () => void}} Object containing blockScroll and restoreScroll functions
+ */
+const useScrollBlock = (scrollContainer = typeof document !== "undefined" ? document.body : null // default to document.body if no scroll container is provided
+) => {
+    const originalStylesRef = useRef(null);
+    const isBlockedRef = useRef(false);
+    /**
+     * Blocks scrolling and stores original styles for restoration.
+     * Blocks the document (body/html) if scroll container is the document body,
+     * or blocks the custom container if a custom container is provided.
+     */
+    const blockScroll = useCallback(() => {
+        if (isBlockedRef.current || !scrollContainer) {
+            return; // Already blocked or no scroll container
+        }
+        if (scrollContainer === document.body) {
+            originalStylesRef.current = blockDocumentScroll();
+        }
+        else {
+            originalStylesRef.current = blockContainerScroll(scrollContainer);
+        }
+        isBlockedRef.current = true;
+    }, [scrollContainer]);
+    /**
+     * Restores scrolling using the previously stored original styles.
+     */
+    const restoreScroll = useCallback(() => {
+        if (!isBlockedRef.current || !scrollContainer || !originalStylesRef.current) {
+            return;
+        }
+        if (scrollContainer === document.body) {
+            restoreDocumentScroll(originalStylesRef.current);
+        }
+        else {
+            restoreContainerScroll(scrollContainer, originalStylesRef.current);
+        }
+        originalStylesRef.current = null;
+        isBlockedRef.current = false;
+    }, [scrollContainer]);
+    // Cleanup: restore scroll if component unmounts while scroll is blocked
+    useEffect(() => {
+        return () => {
+            if (isBlockedRef.current && scrollContainer && originalStylesRef.current) {
+                if (scrollContainer === document.body) {
+                    restoreDocumentScroll(originalStylesRef.current);
+                }
+                else {
+                    restoreContainerScroll(scrollContainer, originalStylesRef.current);
+                }
+                isBlockedRef.current = false;
+            }
+        };
+    }, [scrollContainer]);
+    return useMemo(() => ({ blockScroll, restoreScroll }), [blockScroll, restoreScroll]);
+};
+
+/**
+ * Manages scrollbar and separator-line visibility during sheet motion (drag
+ * and CSS height transitions), freezing both to the state captured at motion
+ * start to avoid visual flashing.
+ *
+ * Freeze rules:
+ * - **Was overflowing at motion start** — scrollbar is forced visible
+ *   (`overflow-y: scroll`) and separator stays opaque throughout the motion.
+ * - **Was NOT overflowing at motion start** — scrollbar is hidden via
+ *   `useScrollBlock` (overflow hidden + scrollbar-gutter to prevent reflow)
+ *   and separator stays transparent throughout the motion.
+ * - **Was docked at motion start** — always treated as "not overflowing"
+ *   because the scroll area is not visible in docked state.  Overflow is
+ *   hidden directly (no scrollbar-gutter) so no space is reserved for a
+ *   scrollbar that was never visible.
+ *
+ * At rest, overflow is detected via ResizeObserver + MutationObserver and
+ * the separator's `style.opacity` is toggled (CSS transition on the element
+ * provides the fade).
+ */
+const useSheetMotionOverflow = ({ panelEl, isDragging, scrollAreaEl, separatorEl, isDocked, isClosing, }) => {
+    const isTransitioningRef = useRef(false);
+    const isDraggingRef = useRef(isDragging);
+    const isMotionActiveRef = useRef(false);
+    const wasOverflowingAtStartRef = useRef(false);
+    const frozeFromDockedRef = useRef(false);
+    const originalOverflowYRef = useRef("");
+    const isDockedRef = useRef(isDocked);
+    const isClosingRef = useRef(isClosing);
+    const settledDockedRef = useRef(isDocked);
+    const { blockScroll, restoreScroll } = useScrollBlock(scrollAreaEl);
+    const blockScrollRef = useRef(blockScroll);
+    const restoreScrollRef = useRef(restoreScroll);
+    const scrollAreaElRef = useRef(scrollAreaEl);
+    const separatorElRef = useRef(separatorEl);
+    const checkOverflow = useCallback(() => {
+        const el = scrollAreaElRef.current;
+        if (!el)
+            return false;
+        return el.scrollHeight > el.clientHeight;
+    }, []);
+    const syncSeparator = useCallback(() => {
+        if (isMotionActiveRef.current)
+            return;
+        const sep = separatorElRef.current;
+        if (!sep)
+            return;
+        sep.style.opacity = checkOverflow() ? "1" : "";
+    }, [checkOverflow]);
+    const freeze = useCallback((forceHideOverflow = false) => {
+        if (isMotionActiveRef.current)
+            return;
+        isMotionActiveRef.current = true;
+        const fromDocked = settledDockedRef.current;
+        const wasOverflowing = forceHideOverflow ? false : fromDocked ? false : checkOverflow();
+        wasOverflowingAtStartRef.current = wasOverflowing;
+        frozeFromDockedRef.current = fromDocked;
+        const area = scrollAreaElRef.current;
+        const sep = separatorElRef.current;
+        if (wasOverflowing) {
+            if (area) {
+                originalOverflowYRef.current = area.style.overflowY;
+                area.style.overflowY = "scroll";
+            }
+            if (sep)
+                sep.style.opacity = "1";
+        }
+        else if (fromDocked) {
+            if (area) {
+                originalOverflowYRef.current = area.style.overflowY;
+                area.style.overflowY = "hidden";
+            }
+            if (sep)
+                sep.style.opacity = "";
+        }
+        else {
+            blockScrollRef.current();
+            if (sep)
+                sep.style.opacity = "";
+        }
+    }, [checkOverflow]);
+    const unfreeze = useCallback(() => {
+        if (!isMotionActiveRef.current)
+            return;
+        isMotionActiveRef.current = false;
+        const area = scrollAreaElRef.current;
+        if (wasOverflowingAtStartRef.current || frozeFromDockedRef.current) {
+            if (area) {
+                area.style.overflowY = originalOverflowYRef.current;
+                originalOverflowYRef.current = "";
+            }
+        }
+        else {
+            restoreScrollRef.current();
+        }
+        settledDockedRef.current = isDockedRef.current;
+        syncSeparator();
+    }, [syncSeparator]);
+    useLayoutEffect(() => {
+        const wasDocked = isDockedRef.current;
+        const wasClosing = isClosingRef.current;
+        blockScrollRef.current = blockScroll;
+        restoreScrollRef.current = restoreScroll;
+        scrollAreaElRef.current = scrollAreaEl;
+        separatorElRef.current = separatorEl;
+        isDockedRef.current = isDocked;
+        isClosingRef.current = isClosing;
+        if (wasDocked && !isDocked) {
+            freeze();
+        }
+        if (!wasClosing && isClosing) {
+            freeze(true);
+        }
+        syncSeparator();
+    });
+    useEffect(() => {
+        isDraggingRef.current = isDragging;
+        if (isDragging) {
+            freeze();
+        }
+        else if (!isTransitioningRef.current) {
+            unfreeze();
+        }
+    }, [isDragging, freeze, unfreeze]);
+    useEffect(() => {
+        if (!panelEl)
+            return;
+        const onStart = (e) => {
+            if (e.target !== panelEl || e.propertyName !== "height")
+                return;
+            isTransitioningRef.current = true;
+            freeze();
+        };
+        const onEnd = (e) => {
+            if (e.target !== panelEl || e.propertyName !== "height")
+                return;
+            isTransitioningRef.current = false;
+            if (!isDraggingRef.current)
+                unfreeze();
+        };
+        const onCancel = (e) => {
+            if (e.target !== panelEl || e.propertyName !== "height")
+                return;
+            isTransitioningRef.current = false;
+            if (!isDraggingRef.current)
+                unfreeze();
+        };
+        panelEl.addEventListener("transitionstart", onStart);
+        panelEl.addEventListener("transitionend", onEnd);
+        panelEl.addEventListener("transitioncancel", onCancel);
+        return () => {
+            panelEl.removeEventListener("transitionstart", onStart);
+            panelEl.removeEventListener("transitionend", onEnd);
+            panelEl.removeEventListener("transitioncancel", onCancel);
+        };
+    }, [panelEl, freeze, unfreeze]);
+    useEffect(() => {
+        if (!scrollAreaEl)
+            return;
+        const update = () => {
+            syncSeparator();
+        };
+        update();
+        const ro = new ResizeObserver(update);
+        ro.observe(scrollAreaEl);
+        const mo = new MutationObserver(update);
+        mo.observe(scrollAreaEl, { childList: true, subtree: true, characterData: true });
+        scrollAreaEl.addEventListener("scroll", update, { passive: true });
+        return () => {
+            ro.disconnect();
+            mo.disconnect();
+            scrollAreaEl.removeEventListener("scroll", update);
+        };
+    }, [scrollAreaEl, syncSeparator]);
+};
+
+/**
+ * Container-scoped bottom sheet with adaptive snap levels and gesture support.
+ *
+ * Use Sheet for contextual surfaces that slide up from the bottom of a
+ * container -- action menus, detail panels, element settings, or filters.
+ * Every Sheet renders via Portal into a required `container` element.
+ * On small screens, consider using Sheet instead of a Popover for better
+ * touch UX. For app-level blocking dialogs, use Modal instead (which
+ * automatically renders as a Sheet on small screens).
+ *
+ * When `variant="modal"`, the sheet behaves as a dialog: it renders a
+ * dimming backdrop, sets `role="dialog"` and `aria-modal` on the panel,
+ * and traps keyboard focus via FloatingFocusManager. Pass
+ * `trapFocus={false}` when a parent component provides its own focus
+ * management (e.g. Modal in sheet mode).
+ *
+ * Snap levels are adaptive: the Sheet measures the container and creates
+ * fewer stops in shorter containers. Consumers navigate with directional
+ * methods (`snapUp`, `snapDown`, `expand`, `collapse`, `dock`) instead of
+ * naming specific snap points.
+ *
+ * The outermost wrapper sets `container-type: size` so cqh/cqw units
+ * resolve against the container's dimensions. Open/close animations use
+ * CSS transitions on transform; the component stays mounted during the
+ * close animation and unmounts after the transition completes.
+ */
+const Sheet = ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, onCloseGesture, floatingUi, ref, anchor = "center", snapping = true, resizable = true, variant = "default", trapFocus = true, container, dockedContent, className, "data-testid": dataTestId, onCloseComplete, entryAnimation = "subsequent", children, }) => {
+    const isFirstRender = useIsFirstRender();
+    const skipEntryAnimation = entryAnimation === "never" || (entryAnimation === "subsequent" && isFirstRender);
+    const effectiveSnapping = resizable && snapping;
+    const [animState, animDispatch] = useReducer(sheetAnimationReducer, INITIAL_ANIMATION_STATE);
+    if (isOpen !== animState.prevIsOpen) {
+        animDispatch({
+            type: "SYNC_OPEN",
+            isOpen,
+            skipEntryAnimation,
+        });
+    }
+    const measurements = useSheetMeasurements({
+        shouldRender: animState.shouldRender,
+        state,
+        dockingEnabled: dockedContent !== undefined,
+        snapping: effectiveSnapping,
+        externalRef: ref,
+        onGeometryChange,
+        onSnap,
+    });
+    const { containerRef, mergedPanelRef, panelRefObj, panelEl, containerHeight, activeSnapHeightPx, gestureSnapHeights, cappedFitHeight, fitHeightReady, fitHeight, handleGestureSnap, } = measurements;
+    const gestures = useSheetGestures({
+        activeSnapHeight: activeSnapHeightPx,
+        containerHeight,
+        enabled: animState.shouldRender && containerHeight > 0 && effectiveSnapping,
+        onClose: onCloseGesture,
+        onSnap: handleGestureSnap,
+        sheetRef: panelRefObj,
+        snapHeights: gestureSnapHeights,
+    });
+    const [scrollAreaEl, setScrollAreaEl] = useState(null);
+    const [separatorEl, setSeparatorEl] = useState(null);
+    useSheetMotionOverflow({
+        panelEl,
+        isDragging: gestures.isDragging,
+        scrollAreaEl,
+        separatorEl,
+        isDocked: state.sizingMode === "docked",
+        isClosing: animState.closePhase !== "idle",
+    });
+    const { onMouseEnter, onMouseLeave } = useSheetDismissIntent({
+        closable: onCloseGesture !== undefined,
+        closePhase: animState.closePhase,
+        panelRef: panelRefObj,
+    });
+    const shouldTrapFocus = variant === "modal" && trapFocus && floatingUi !== undefined;
+    const panelRefWithFloating = useMergeRefs$1([mergedPanelRef, floatingUi?.refs.setFloating ?? null]);
+    const handleClick = useCallback((e) => {
+        const mod = e.metaKey || e.ctrlKey;
+        if (mod && e.shiftKey) {
+            onCloseGesture?.();
+            return;
+        }
+        if (mod) {
+            snap.fit();
+            return;
+        }
+        if (e.altKey) {
+            snap.dock();
+            return;
+        }
+        if (e.shiftKey) {
+            snap.expand();
+            return;
+        }
+        if (state.sizingMode === "docked") {
+            snap.fit();
+            return;
+        }
+        onClickHandle();
+    }, [onClickHandle, snap, onCloseGesture, state.sizingMode]);
+    const { handleTransitionEnd } = useSheetLifecycle({
+        isOpen,
+        entryAnimation: entryAnimation !== "never",
+        visuallyOpen: animState.visuallyOpen,
+        variant,
+        container,
+        panelRef: panelRefObj,
+        panelEl,
+        dispatch: animDispatch,
+        onCloseComplete,
+        fitHeightReady,
+    });
+    const showOverlay = variant === "modal" && state.sizingMode !== "docked" && animState.visuallyOpen;
+    const fitHeightMeasured = state.sizingMode === "fit" && fitHeight > 0;
+    const snapHeightCss = state.sizingMode === "docked"
+        ? `${state.effectiveDockedHeight}px`
+        : fitHeightMeasured
+            ? `${cappedFitHeight}px`
+            : getSnapLevelCssHeight(state.level, state.totalLevels, dockedContent !== undefined, state.effectiveDockedHeight);
+    const fitMaxHeight = state.sizingMode === "fit" ? `calc(100cqh - ${FULL_HEIGHT_TOP_MARGIN_PX}px)` : undefined;
+    if (!animState.shouldRender)
+        return null;
+    if (!container) {
+        return null;
+    }
+    const gestureHandlers = effectiveSnapping
+        ? {
+            onPointerDown: gestures.onPointerDown,
+            onPointerMove: gestures.onPointerMove,
+            onPointerUp: gestures.onPointerUp,
+            onLostPointerCapture: gestures.onLostPointerCapture,
+        }
+        : {};
+    const panel = (jsxs(Card, { ...(shouldTrapFocus === true ? { "aria-modal": true, role: "dialog" } : {}), ...(floatingUi?.getFloatingProps() ?? {}), className: cvaSheetPanel({ anchor, variant, className }), "data-testid": dataTestId, onTransitionEnd: handleTransitionEnd, ref: panelRefWithFloating, style: getSheetPanelStyle({
+            autoHeight: state.sizingMode === "fit" && !fitHeightMeasured,
+            closePhase: animState.closePhase,
+            isDragging: gestures.isDragging,
+            isOpen: animState.visuallyOpen,
+            maxHeight: fitMaxHeight,
+            snapHeight: snapHeightCss,
+            suppressTransition: skipEntryAnimation && animState.visuallyOpen,
+            variant,
+        }), children: [resizable ? (jsx(SheetHandle, { "data-testid": dataTestId !== undefined ? `${dataTestId}-handle` : undefined, isDragging: gestures.isDragging, onClick: handleClick, onMouseEnter: onMouseEnter, onMouseLeave: onMouseLeave, ...gestureHandlers })) : null, jsx("div", { className: "h-px shrink-0 bg-neutral-200 opacity-0 transition-opacity duration-200", ref: setSeparatorEl }), jsx("div", { className: cvaSheetScrollArea({ fillHeight: state.sizingMode !== "fit" }), "data-sheet-scroll-area": true, ref: setScrollAreaEl, children: state.sizingMode === "docked" ? dockedContent : children })] }));
+    return (jsx(Portal, { root: container, children: jsxs("div", { className: cvaSheetContainer({
+                docked: state.sizingMode === "docked",
+            }), "data-testid": dataTestId !== undefined ? `${dataTestId}-container` : undefined, ref: containerRef, children: [jsx(SheetOverlay, { "data-testid": dataTestId !== undefined ? `${dataTestId}-overlay` : undefined, visible: showOverlay }), shouldTrapFocus === true ? (jsx(FloatingFocusManager, { context: floatingUi.context, children: panel })) : (panel)] }) }));
+};
+
+/** Resolves DismissOptions with defaults (all true when omitted). */
+const DEFAULT_DISMISS_OPTIONS = {
+    escapeKey: true,
+    outsidePress: true,
+    gesture: true,
+};
+/** Merges caller-supplied DismissOptions with defaults, returning a fully-resolved options object. */
+function resolveDismissOptions(dismiss) {
+    return {
+        escapeKey: dismiss?.escapeKey ?? DEFAULT_DISMISS_OPTIONS.escapeKey,
+        outsidePress: dismiss?.outsidePress ?? DEFAULT_DISMISS_OPTIONS.outsidePress,
+        gesture: dismiss?.gesture ?? DEFAULT_DISMISS_OPTIONS.gesture,
+    };
+}
+
+const INITIAL_SNAP_STATE = {
+    currentLevel: 0,
+    sizingMode: "level",
+    initialSizeApplied: false,
+    prevIsOpen: false,
+    totalLevels: 0,
+    dockingEnabled: false,
+    levelHeights: [],
+    effectiveDockedHeight: 0,
+    fitHeight: 0,
+};
+const findLevelByHeight = (heightPx, levelHeights) => {
+    let closestIndex = 0;
+    let closestDistance = Infinity;
+    for (let i = 0; i < levelHeights.length; i++) {
+        const h = levelHeights[i];
+        if (h === undefined)
+            continue;
+        const distance = Math.abs(h - heightPx);
+        if (distance < closestDistance) {
+            closestDistance = distance;
+            closestIndex = i;
+        }
+    }
+    return closestIndex;
+};
+const withSnapSync = (state, currentLevel, sizingMode) => ({
+    ...state,
+    currentLevel,
+    sizingMode,
+});
+/** Reducer managing snap-level positioning and measurement-derived state. */
+const snapReducer = (state, action) => {
+    switch (action.type) {
+        case "SYNC_OPEN": {
+            if (action.isOpen === state.prevIsOpen)
+                return state;
+            if (action.isOpen) {
+                return {
+                    ...state,
+                    prevIsOpen: true,
+                    currentLevel: 0,
+                    sizingMode: "level",
+                    initialSizeApplied: false,
+                };
+            }
+            return {
+                ...state,
+                prevIsOpen: false,
+                initialSizeApplied: false,
+            };
+        }
+        case "SYNC_MEASUREMENTS": {
+            return {
+                ...state,
+                totalLevels: action.levelHeights.length,
+                dockingEnabled: action.measurements.dockingEnabled,
+                levelHeights: action.levelHeights,
+                effectiveDockedHeight: action.measurements.dockedHeight,
+                fitHeight: action.measurements.fitHeight,
+            };
+        }
+        case "APPLY_INITIAL_SIZE": {
+            if (state.initialSizeApplied)
+                return state;
+            if (action.defaultSize === "fit") {
+                return { ...state, initialSizeApplied: true, sizingMode: "fit" };
+            }
+            if (action.defaultSize === "collapsed") {
+                return withSnapSync({ ...state, initialSizeApplied: true }, 0, "level");
+            }
+            if (action.defaultSize === "expanded") {
+                return withSnapSync({ ...state, initialSizeApplied: true }, state.totalLevels - 1, "level");
+            }
+            if (state.dockingEnabled) {
+                return withSnapSync({ ...state, initialSizeApplied: true }, 0, "docked");
+            }
+            return state;
+        }
+        case "SNAP_UP": {
+            if (state.sizingMode === "docked") {
+                return withSnapSync(state, 0, "level");
+            }
+            const nextUp = Math.min(state.currentLevel + 1, state.totalLevels - 1);
+            return nextUp === state.currentLevel && state.sizingMode !== "fit" ? state : withSnapSync(state, nextUp, "level");
+        }
+        case "SNAP_DOWN": {
+            if (state.sizingMode === "docked")
+                return state;
+            if (state.currentLevel === 0 && state.dockingEnabled) {
+                return withSnapSync(state, state.currentLevel, "docked");
+            }
+            const nextDown = Math.max(state.currentLevel - 1, 0);
+            return nextDown === state.currentLevel && state.sizingMode !== "fit"
+                ? state
+                : withSnapSync(state, nextDown, "level");
+        }
+        case "EXPAND":
+            return withSnapSync(state, state.totalLevels - 1, "level");
+        case "COLLAPSE":
+            return withSnapSync(state, 0, "level");
+        case "DOCK":
+            return state.dockingEnabled ? withSnapSync(state, state.currentLevel, "docked") : state;
+        case "FIT":
+            return { ...state, sizingMode: "fit" };
+        case "GESTURE_SNAP": {
+            if (state.dockingEnabled && Math.abs(action.heightPx - state.effectiveDockedHeight) < 1) {
+                return withSnapSync(state, state.currentLevel, "docked");
+            }
+            if (state.sizingMode === "fit" && !action.useLevelSnap) {
+                if (state.fitHeight > 0 && Math.abs(action.heightPx - state.fitHeight) < 1) {
+                    return state;
+                }
+                const fitLevel = findLevelByHeight(action.heightPx, state.levelHeights);
+                return withSnapSync(state, fitLevel, "level");
+            }
+            const level = findLevelByHeight(action.heightPx, state.levelHeights);
+            return withSnapSync(state, level, "level");
+        }
+        case "CYCLE_SNAP": {
+            if (state.sizingMode === "fit")
+                return state;
+            if (state.sizingMode === "docked")
+                return withSnapSync(state, 0, "level");
+            const nextCycle = state.currentLevel + 1;
+            if (nextCycle >= state.totalLevels) {
+                return state.dockingEnabled
+                    ? withSnapSync(state, state.currentLevel, "docked")
+                    : withSnapSync(state, 0, "level");
+            }
+            return withSnapSync(state, nextCycle, "level");
+        }
+        default:
+            return state;
+    }
+};
+
+const buildState = (snapState, dockedHeight) => ({
+    sizingMode: snapState.sizingMode,
+    level: snapState.currentLevel,
+    totalLevels: snapState.totalLevels,
+    isExpanded: snapState.sizingMode === "level" &&
+        snapState.totalLevels > 0 &&
+        snapState.currentLevel === snapState.totalLevels - 1,
+    isCollapsed: snapState.sizingMode === "level" && snapState.currentLevel === 0,
+    dockedHeight,
+    levelHeights: snapState.levelHeights,
+    effectiveDockedHeight: snapState.effectiveDockedHeight,
+});
+/**
+ * Composable hook managing snap-level state for the Sheet component.
+ *
+ * Owns the snap reducer, processes measurements from Sheet via `onGeometryChange`,
+ * and provides stable navigation methods. Used by `useSheet` internally and
+ * can be used directly by Modal for independent snap management.
+ */
+const useSheetSnap = ({ defaultSize, isOpen }) => {
+    const [state, dispatch] = useReducer(snapReducer, INITIAL_SNAP_STATE);
+    if (isOpen !== state.prevIsOpen) {
+        dispatch({ type: "SYNC_OPEN", isOpen });
+    }
+    if (isOpen && !state.initialSizeApplied && (state.totalLevels > 0 || defaultSize === "fit")) {
+        dispatch({ type: "APPLY_INITIAL_SIZE", defaultSize });
+    }
+    const dockedHeightForSize = state.dockingEnabled ? state.effectiveDockedHeight : 0;
+    const sheetState = useMemo(() => buildState(state, dockedHeightForSize), [state, dockedHeightForSize]);
+    const onGeometryChange = useCallback((m, dockingEnabled) => {
+        const effectiveDockedHeight = m.dockedHeight > 0 ? m.dockedHeight : DOCKED_HEIGHT_PX;
+        const levelHeights = computeSnapLevelHeights(m.containerHeight, dockingEnabled, effectiveDockedHeight);
+        dispatch({
+            type: "SYNC_MEASUREMENTS",
+            measurements: {
+                fitHeight: m.fitHeight,
+                dockedHeight: effectiveDockedHeight,
+                dockingEnabled,
+            },
+            levelHeights,
+        });
+    }, []);
+    const onSnap = useCallback((heightPx, useLevelSnap) => {
+        dispatch({ type: "GESTURE_SNAP", heightPx, useLevelSnap });
+    }, []);
+    const onClickHandle = useCallback(() => {
+        dispatch({ type: "CYCLE_SNAP" });
+    }, []);
+    const snapUp = useCallback(() => {
+        dispatch({ type: "SNAP_UP" });
+    }, []);
+    const snapDown = useCallback(() => {
+        dispatch({ type: "SNAP_DOWN" });
+    }, []);
+    const expand = useCallback(() => {
+        dispatch({ type: "EXPAND" });
+    }, []);
+    const collapse = useCallback(() => {
+        dispatch({ type: "COLLAPSE" });
+    }, []);
+    const dock = useCallback(() => {
+        dispatch({ type: "DOCK" });
+    }, []);
+    const fit = useCallback(() => {
+        dispatch({ type: "FIT" });
+    }, []);
+    const snap = useMemo(() => ({ snapUp, snapDown, expand, collapse, dock, fit }), [snapUp, snapDown, expand, collapse, dock, fit]);
+    return useMemo(() => ({ state: sheetState, snap, onGeometryChange, onSnap, onClickHandle }), [sheetState, snap, onGeometryChange, onSnap, onClickHandle]);
+};
+
+/**
+ * Hook for managing Sheet open/close state and directional snap navigation.
+ *
+ * Consumers navigate via `snap.snapUp()` / `snap.snapDown()` /
+ * `snap.expand()` / `snap.collapse()` / `snap.dock()` instead of
+ * naming specific snap points. The snap state is managed by the composable
+ * `useSheetSnap` hook internally.
+ *
+ * Owns all dismiss handling (ESC, outside-press, gesture) via Floating UI's
+ * `useDismiss`. Each dismiss path goes through `onOpenChange` →
+ * `requestClose` with the correct `CloseReason`, then through
+ * `onBeforeClose` guard, then `handleClose`. The public `close()` is a
+ * no-arg wrapper that tags the reason as `"programmatic"`.
+ *
+ * Outside-press dismiss is only active when `variant="modal"` — the only
+ * variant that renders a backdrop overlay. For `"default"` and `"floating"`
+ * variants, clicks outside the panel do not close the sheet.
+ *
+ * Returns a `floatingUi` object (context, refs, getFloatingProps) that the
+ * Sheet component uses for focus management and dismiss interaction binding,
+ * mirroring `useModal`'s architecture.
+ *
+ * Supports controlled (isOpen) and uncontrolled (defaultOpen) modes, stores
+ * external callbacks in refs for stability.
+ */
+const useSheet = (props) => {
+    const { isOpen: controlledIsOpen, defaultOpen, onClose, onOpen, onOpenChange, onBeforeClose, dismiss: dismissProp, variant = "default", defaultSize = "fit", onStateChange, onGeometryChange: onGeometryChangeProp, } = props ?? {};
+    const dismiss = useMemo(() => resolveDismissOptions(dismissProp), [dismissProp]);
+    const [internalIsOpen, setIsOpen] = useState(defaultOpen ?? false);
+    const isOpen = typeof controlledIsOpen === "boolean" ? controlledIsOpen : internalIsOpen;
+    const ref = useRef(null);
+    const isPendingCloseRef = useRef(false);
+    const onCloseRef = useRef(onClose);
+    const onOpenRef = useRef(onOpen);
+    const onOpenChangeRef = useRef(onOpenChange);
+    const onBeforeCloseRef = useRef(onBeforeClose);
+    const onStateChangeRef = useRef(onStateChange);
+    const onGeometryChangeRef = useRef(onGeometryChangeProp);
+    useLayoutEffect(() => {
+        onCloseRef.current = onClose;
+        onOpenRef.current = onOpen;
+        onOpenChangeRef.current = onOpenChange;
+        onBeforeCloseRef.current = onBeforeClose;
+        onStateChangeRef.current = onStateChange;
+        onGeometryChangeRef.current = onGeometryChangeProp;
+    });
+    const { state, snap, onGeometryChange: snapOnGeometryChange, onSnap, onClickHandle, } = useSheetSnap({ defaultSize, isOpen });
+    useEffect(() => {
+        onStateChangeRef.current?.(state);
+    }, [state]);
+    const onGeometryChange = useCallback((geometry, dockingEnabled) => {
+        snapOnGeometryChange(geometry, dockingEnabled);
+        onGeometryChangeRef.current?.(geometry);
+    }, [snapOnGeometryChange]);
+    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 { context: floatingContext, refs: floatingRefs } = useFloating({
+        open: isOpen,
+        onOpenChange: (newIsOpen, event, reason) => {
+            if (newIsOpen)
+                return;
+            const closeReason = reason === "escape-key" || reason === "outside-press" ? reason : undefined;
+            requestClose(event, closeReason);
+        },
+    });
+    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]);
+    const onCloseGesture = useMemo(() => (dismiss.gesture ? () => requestClose(undefined, "gesture") : undefined), [dismiss.gesture, requestClose]);
+    return useMemo(() => ({
+        isOpen,
+        ref,
+        state,
+        variant,
+        open,
+        close,
+        snap,
+        floatingUi,
+        onGeometryChange,
+        onSnap,
+        onClickHandle,
+        onCloseGesture,
+    }), [isOpen, state, variant, open, close, snap, floatingUi, onGeometryChange, onSnap, onClickHandle, onCloseGesture]);
+};
+
+const cvaSidebar = cvaMerge(["apply", "grid", "grid-cols-fr-min", "items-center"]);
+const cvaSidebarChildContainer = cvaMerge(["apply", "flex", "overflow-hidden", "gap-2", "p-1", "max-w-full"], {
+    variants: {
+        breakpoint: {
+            xs: ["xs:overflow-visible", "xs:p-0", "xs:grid", "xs:grid-cols-1", "xs:w-full"],
+            sm: ["sm:overflow-visible", "sm:p-0", "sm:grid", "sm:grid-cols-1", "sm:w-full"],
+            md: ["md:overflow-visible", "md:p-0", "md:grid", "md:grid-cols-1", "md:w-full"],
+            lg: ["lg:overflow-visible", "lg:p-0", "lg:grid", "lg:grid-cols-1", "lg:w-full"],
+            xl: ["xl:overflow-visible", "xl:p-0", "xl:grid", "xl:grid-cols-1", "xl:w-full"],
+            "2xl": ["2xl:overflow-visible", "2xl:p-0", "2xl:grid", "2xl:grid-cols-1", "2xl:w-full"],
+            "3xl": ["3xl:overflow-visible", "3xl:p-0", "3xl:grid", "3xl:grid-cols-1", "3xl:w-full"],
+        },
+    },
+});
+
+/**
+ * A hook used to detect what children are overflowing a container.
+ *
+ * @param {OverflowItemsOptions} root0  The options for the hook.
+ * @param {number | Array<number>} root0.threshold The threshold for the intersection observer.
+ * @returns {object} The overflow items and the ref to the container.
+ */
+const useOverflowItems = ({ threshold = 1, childUniqueIdentifierAttribute = "id", children, }) => {
+    const [itemOverflowMap, setItemOverflowMap] = useState({});
+    const overflowContainerRef = useRef(null);
+    const observerRef = useRef(null);
+    const handleIntersection = useCallback(entries => {
+        const updatedEntries = {};
+        entries.forEach(entry => {
+            // @ts-expect-error - suppressImplicitAnyIndexErrors
+            const targetElementId = entry.target[childUniqueIdentifierAttribute];
+            if (targetElementId !== null && targetElementId !== undefined && targetElementId !== "") {
+                updatedEntries[targetElementId] = entry.isIntersecting ? false : true;
+            }
+        });
+        setItemOverflowMap(prev => ({ ...prev, ...updatedEntries }));
+    }, [childUniqueIdentifierAttribute]);
+    const observe = useCallback(() => {
+        const node = overflowContainerRef.current;
+        if (node) {
+            const root = overflowContainerRef.current;
+            const options = { root, threshold };
+            const observer = new IntersectionObserver(handleIntersection, options);
+            Array.from(node.children).forEach(child => {
+                observer.observe(child);
+            });
+            observer.observe(node);
+            observerRef.current = observer;
+        }
+    }, [handleIntersection, threshold]);
+    const unobserve = useCallback(() => {
+        const currentObserver = observerRef.current;
+        currentObserver?.disconnect();
+        observerRef.current = null;
+    }, []);
+    const initializeObserver = useCallback(() => {
+        unobserve();
+        observe();
+    }, [observe, unobserve]);
+    useEffect(() => {
+        initializeObserver();
+        return () => {
+            unobserve();
+        };
+    }, [initializeObserver, unobserve, children]);
+    return useMemo(() => ({ overflowContainerRef, itemOverflowMap }), [overflowContainerRef, itemOverflowMap]);
+};
+
+/**
+ * Sidebar renders a responsive horizontal/vertical navigation bar that automatically collapses overflowing items into a MoreMenu.
+ * It is rendered horizontally until a given breakpoint, then stacks vertically.
+ *
+ * **Important:** The Sidebar is just a layout wrapper. You are responsible for styling the children.
+ * For the overflow functionality, use `min-w-[*]` or `flex-shrink-0` on child elements.
+ *
+ * When testing, add `setupIntersectionObserver();` to your `jest.setup.ts` file.
+ *
+ * ### When to use
+ * Use Sidebar for secondary in-page navigation (e.g., switching between views within a page). Works well with `Tabs` for page-level navigation.
+ *
+ * ### When not to use
+ * Do not use Sidebar for primary app navigation (the main menu). For top-level navigation, use the app shell navigation.
+ *
+ * @example Responsive sidebar with navigation items
+ * ```tsx
+ * import { Sidebar, Button } from "@trackunit/react-components";
+ *
+ * const NavigationSidebar = () => (
+ *   <Sidebar breakpoint="lg">
+ *     <Button id="overview" variant="ghost-neutral" className="min-w-[100px]">
+ *       Overview
+ *     </Button>
+ *     <Button id="assets" variant="ghost-neutral" className="min-w-[100px]">
+ *       Assets
+ *     </Button>
+ *     <Button id="reports" variant="ghost-neutral" className="min-w-[100px]">
+ *       Reports
+ *     </Button>
+ *     <Button id="settings" variant="ghost-neutral" className="min-w-[100px]">
+ *       Settings
+ *     </Button>
+ *   </Sidebar>
+ * );
+ * ```
+ * @param {SidebarProps} props - The props for the Sidebar component
+ * @returns {ReactElement} Sidebar component
+ */
+const Sidebar = ({ childContainerClassName, children, breakpoint = "lg", className, "data-testid": dataTestId = "sidebar", moreMenuProps, menuListProps, overflowThreshold, ref, }) => {
+    const { overflowContainerRef, itemOverflowMap } = useOverflowItems({
+        children,
+        childUniqueIdentifierAttribute: "id",
+        threshold: overflowThreshold ?? 0.8,
+    });
+    const overflowItemCount = objectValues(itemOverflowMap).filter(isOverflowing => isOverflowing).length;
+    const itemVisibilityClassName = (id) => {
+        if (itemOverflowMap[id] === true) {
+            return "invisible";
+        }
+        return "visible";
+    };
+    return (jsxs("div", { className: cvaSidebar({ className }), "data-testid": dataTestId, ref: ref, children: [jsx("div", { className: cvaSidebarChildContainer({ breakpoint, className: childContainerClassName }), "data-testid": `${dataTestId}-child-container`, ref: overflowContainerRef, children: Children.map(children, child => {
+                    return cloneElement(child, {
+                        className: twMerge(child.props.className, itemVisibilityClassName(child.props.id)),
+                    });
+                }) }), overflowItemCount > 0 ? (jsx(MoreMenu, { iconButtonProps: {
+                    variant: "ghost-neutral",
+                }, ...moreMenuProps, className: moreMenuProps?.className, "data-testid": `${dataTestId}-more-menu`, children: close => (jsx(MenuList, { ...menuListProps, "data-testid": dataTestId, children: Children.map(children, child => {
+                        return itemOverflowMap[child.props.id] === true
+                            ? cloneElement(child, {
+                                onClick: e => {
+                                    child.props.onClick?.(e);
+                                    close();
+                                },
+                                className: "w-full",
+                            })
+                            : null;
+                    }) })) })) : null] }));
+};
+
+const cvaTabsRoot = cvaMerge([]);
+const cvaTabList = cvaMerge([
+    "flex",
+    "flex-row",
+    "border-b",
+    "border-b-neutral-200",
+    "overflow-auto",
+    "no-scrollbar",
+]);
+const cvaTabContent = cvaMerge([]);
+const cvaTab = cvaMerge([
+    "flex",
+    "items-center",
+    "justify-center",
+    "gap-2",
+    "text-sm",
+    "px-6",
+    "py-2",
+    "cursor-pointer",
+    "transition",
+    "duration-200",
+    "ease-in-out",
+    "whitespace-nowrap",
+    "border-b-2",
+    "border-b-transparent",
+    "hover:border-b-transparent",
+    "data-[state=active]:border-b-primary-600",
+    "data-[state=active]:font-semibold",
+    "data-[state=active]:text-neutral-900",
+    "data-[state=inactive]:font-medium",
+    "data-[state=inactive]:text-neutral-700",
+    "data-[state=inactive]:hover:text-neutral-900",
+    "disabled:cursor-not-allowed",
+    "data-[state=active]disabled:text-neutral-400",
+    "data-[state=inactive]:disabled:text-neutral-400",
+], {
+    variants: {
+        isFullWidth: {
+            true: "w-full",
+            false: "",
+        },
+    },
+    defaultVariants: {
+        isFullWidth: false,
+    },
+});
+
+/**
+ * Tab is an individual tab trigger within a TabList.
+ * Each Tab requires a unique `value` prop that corresponds to a TabContent with the same value.
+ * Supports optional icons, suffixes (e.g., badges), and rendering as a custom child element via `asChild`.
+ *
+ * ### When to use
+ * Use Tab inside a `TabList` to create clickable tab triggers. Each Tab maps to a `TabContent` panel.
+ *
+ * ### When not to use
+ * Do not use Tab outside of a `TabList`/`Tabs` context. For standalone buttons, use `Button`.
+ *
+ * @example Tab with icon and badge suffix
+ * ```tsx
+ * import { Tabs, TabList, Tab, TabContent, Badge } from "@trackunit/react-components";
+ *
+ * const TabsWithBadge = () => (
+ *   <Tabs defaultValue="alerts">
+ *     <TabList>
+ *       <Tab value="alerts" iconName="Bell" suffix={<Badge count={3} color="danger" />}>
+ *         Alerts
+ *       </Tab>
+ *       <Tab value="history" iconName="Clock">History</Tab>
+ *     </TabList>
+ *     <TabContent value="alerts">Active alerts</TabContent>
+ *     <TabContent value="history">Event history</TabContent>
+ *   </Tabs>
+ * );
+ * ```
+ * @param {TabProps} props - The props for the Tab component
+ * @returns {ReactElement} Tab component
+ */
+const Tab = ({ value, isFullWidth = false, iconName = undefined, "data-testid": dataTestId, className, children, suffix, asChild = false, appendTabStylesToChildIfAsChild = true, ref, ...rest }) => {
+    const renderContent = () => (jsxs(Fragment, { children: [iconName !== undefined ? jsx(Icon, { name: iconName, size: "small" }) : null, isValidElement(children) ? children.props.children : children, suffix] }));
+    const commonProps = {
+        className: appendTabStylesToChildIfAsChild ? cvaTab({ className, isFullWidth }) : className,
+        ...rest,
+    };
+    return (jsx(Trigger, { asChild: true, ref: ref, value: value, children: asChild && typeof children !== "string" ? (cloneElement(children, {
+            ...commonProps,
+            children: renderContent(),
+        })) : (jsx("button", { ...commonProps, "data-testid": dataTestId, children: renderContent() })) }));
+};
+
+/**
+ * TabContent is the content panel displayed when its corresponding Tab is active.
+ * Each TabContent must have a `value` prop that matches the `value` of its corresponding Tab trigger.
+ * TabContent is only rendered when its tab is selected (unless `forceMount` is set).
+ *
+ * ### When to use
+ * Use TabContent inside a `Tabs` component, one for each `Tab` trigger.
+ *
+ * ### When not to use
+ * Do not use TabContent outside of a `Tabs` context. For conditionally shown content, use standard conditional rendering.
  *
  * @example Tabs with styled content panels
  * ```tsx
@@ -8276,8 +10316,11 @@ const useCustomEncoding = () => {
             // If it's already a string, use it directly; otherwise stringify the object
             const json = typeof input === "string" ? input : JSON.stringify(input);
             const textInput = new TextEncoder().encode(json);
-            // Use fflate for synchronous gzip compression
-            const compressed = gzipSync(textInput);
+            // Use fflate for synchronous gzip compression.
+            // mtime: 0 ensures deterministic output — without it the gzip header
+            // includes the current timestamp, making the same input produce a
+            // different encoded string on every call.
+            const compressed = gzipSync(textInput, { mtime: 0 });
             return b64urlEncode(compressed);
         }
         catch (_) {
@@ -8329,6 +10372,36 @@ const useCustomEncoding = () => {
     return useMemo(() => ({ encode, decode }), [encode, decode]);
 };
 
+/**
+ * Internal envelope used to tag superjson-serialized data in web storage.
+ *
+ * `__serializer` is a **reserved internal key** — consumer state objects must
+ * not include it as a top-level key. The double-underscore prefix is a
+ * deliberate signal that this is a private implementation detail.
+ *
+ * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
+ * detected in the value being written.
+ */
+const taggedSuperjsonEnvelopeSchema = z.object({
+    __serializer: z.literal("superjson"),
+    json: z.custom(),
+    meta: z.custom().optional(),
+});
+const storageSerializer = {
+    serialize: (value) => {
+        const serialized = superjson.serialize(value);
+        return JSON.stringify({ __serializer: "superjson", ...serialized });
+    },
+    deserialize: (value) => {
+        const parsed = JSON.parse(value);
+        const result = taggedSuperjsonEnvelopeSchema.safeParse(parsed);
+        if (result.success) {
+            return superjson.deserialize({ json: result.data.json, meta: result.data.meta });
+        }
+        return parsed;
+    },
+};
+
 /**
  * Runs a sequential migration pipeline on the provided data, applying
  * each migration whose version is in the range (fromVersion, toVersion].
@@ -8434,36 +10507,6 @@ const salvageState = (schema, rawData, defaultState) => {
     }
 };
 
-/**
- * Internal envelope used to tag superjson-serialized data in web storage.
- *
- * `__serializer` is a **reserved internal key** — consumer state objects must
- * not include it as a top-level key. The double-underscore prefix is a
- * deliberate signal that this is a private implementation detail.
- *
- * A runtime warning is emitted (via `writeToStorage`) if reserved keys are
- * detected in the value being written.
- */
-const taggedSuperjsonEnvelopeSchema = z.object({
-    __serializer: z.literal("superjson"),
-    json: z.custom(),
-    meta: z.custom().optional(),
-});
-const storageSerializer = {
-    serialize: (value) => {
-        const serialized = superjson.serialize(value);
-        return JSON.stringify({ __serializer: "superjson", ...serialized });
-    },
-    deserialize: (value) => {
-        const parsed = JSON.parse(value);
-        const result = taggedSuperjsonEnvelopeSchema.safeParse(parsed);
-        if (result.success) {
-            return superjson.deserialize({ json: result.data.json, meta: result.data.meta });
-        }
-        return parsed;
-    },
-};
-
 /**
  * Internal envelope that pairs stored data with a schema version number.
  *
@@ -8891,53 +10934,249 @@ const useWebStorageReducer = (storage, { key, defaultState, schema, migration, r
 };
 
 /**
- * Works like useReducer, but persists to localStorage with Zod schema validation
- * and superjson serialization (supports Date, Map, Set, BigInt, etc.).
+ * Works like useReducer, but persists to localStorage with Zod schema validation
+ * and superjson serialization (supports Date, Map, Set, BigInt, etc.).
+ *
+ * @template TState - The type of the stored state.
+ * @template TAction - The type of the reducer action.
+ * @param options - Key, defaultState, schema, reducer, and optional callbacks.
+ * @param options.key - The storage key.
+ * @param options.defaultState - Fallback value when no stored data exists.
+ * @param options.schema - Zod schema for validation.
+ * @param options.reducer - The reducer function.
+ * @param options.onValidationFailed - Optional error callback.
+ * @param options.onValidationSuccessful - Optional success callback.
+ * @returns {Array} A tuple of [state, dispatch].
+ */
+const useLocalStorageReducer = (options) => useWebStorageReducer(globalThis.localStorage, options);
+
+/**
+ * Works like useState, but persists to sessionStorage with Zod schema validation
+ * and superjson serialization (supports Date, Map, Set, BigInt, etc.).
+ *
+ * @template TState - The type of the stored state.
+ * @param options - Key, defaultState, schema, and optional callbacks.
+ * @param options.key - The storage key.
+ * @param options.defaultState - Fallback value when no stored data exists.
+ * @param options.schema - Zod schema for validation.
+ * @param options.onValidationFailed - Optional error callback.
+ * @param options.onValidationSuccessful - Optional success callback.
+ * @returns {Array} A tuple of [state, setState, reset].
+ */
+const useSessionStorage = (options) => useWebStorage(globalThis.sessionStorage, options);
+
+/**
+ * Works like useReducer, but persists to sessionStorage with Zod schema validation
+ * and superjson serialization (supports Date, Map, Set, BigInt, etc.).
+ *
+ * @template TState - The type of the stored state.
+ * @template TAction - The type of the reducer action.
+ * @param options - Key, defaultState, schema, reducer, and optional callbacks.
+ * @param options.key - The storage key.
+ * @param options.defaultState - Fallback value when no stored data exists.
+ * @param options.schema - Zod schema for validation.
+ * @param options.reducer - The reducer function.
+ * @param options.onValidationFailed - Optional error callback.
+ * @param options.onValidationSuccessful - Optional success callback.
+ * @returns {Array} A tuple of [state, dispatch].
+ */
+const useSessionStorageReducer = (options) => useWebStorageReducer(globalThis.sessionStorage, options);
+
+const MAX_URL_LENGTH = 5000;
+/**
+ * Syncs an encoded string value with a URL search parameter via Tanstack Router.
+ *
+ * Provides a write function that updates the URL through the application
+ * router (preserving other search params), guards against exceeding
+ * {@link MAX_URL_LENGTH}, and detects external URL changes (browser
+ * back/forward, shared links) via an optional callback.
+ *
+ * @param options - Configuration for the search param sync.
+ * @param options.key - The URL search parameter name.
+ * @param options.enabled - Set to `false` to disable all URL interaction (default `true`).
+ * @param options.onExternalChange - Called when the param changes externally.
+ * @param options.replace - `true` to always use `replaceState`.
+ */
+const useSearchParamSync = ({ key, enabled = true, onExternalChange, replace: replaceOption, }) => {
+    const navigate = useNavigate();
+    const location = useLocation();
+    const search = useSearch({ strict: false, shouldThrow: false });
+    const lastWrittenRef = useRef(undefined);
+    const onExternalChangeRef = useRef(onExternalChange);
+    useEffect(() => {
+        onExternalChangeRef.current = onExternalChange;
+    }, [onExternalChange]);
+    const currentSearchValue = useMemo(() => {
+        if (!enabled) {
+            return undefined;
+        }
+        const value = search?.[key];
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            return String(value);
+        }
+        return undefined;
+    }, [enabled, search, key]);
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        if (currentSearchValue === undefined) {
+            return;
+        }
+        if (currentSearchValue === lastWrittenRef.current) {
+            return;
+        }
+        if (lastWrittenRef.current === undefined) {
+            return;
+        }
+        requestAnimationFrame(() => {
+            onExternalChangeRef.current?.();
+        });
+    }, [currentSearchValue, enabled]);
+    const getUrlLengthWithSearchParam = useCallback((paramKey, paramValue, params) => {
+        const otherParamsLength = objectKeys(params)
+            .filter(k => k !== paramKey)
+            .reduce((totalLength, k) => {
+            const kLen = encodeURIComponent(String(k)).length;
+            const v = params[k];
+            const vLen = v !== null && v !== undefined ? encodeURIComponent(String(v)).length : 0;
+            return totalLength + kLen + vLen + (totalLength > 0 ? 2 : 1);
+        }, 0);
+        const urlBase = location.href.length - (location.searchStr.length || 0) + (location.hash.length || 0);
+        return urlBase + otherParamsLength + 1 + paramKey.length + 1 + paramValue.length;
+    }, [location]);
+    const updateSearchParam = useCallback((encodedValue) => {
+        if (!enabled) {
+            return;
+        }
+        if (encodedValue !== undefined && encodedValue === lastWrittenRef.current) {
+            return;
+        }
+        lastWrittenRef.current = encodedValue;
+        if (currentSearchValue === encodedValue) {
+            return;
+        }
+        requestAnimationFrame(() => {
+            const shouldReplace = replaceOption ?? !Boolean(currentSearchValue);
+            void navigate({
+                to: ".",
+                search: (prev) => {
+                    if (getUrlLengthWithSearchParam(key, encodedValue || "", prev) <= MAX_URL_LENGTH) {
+                        return { ...prev, [key]: encodedValue };
+                    }
+                    else {
+                        return { ...prev, [key]: undefined };
+                    }
+                },
+                hash: location.hash,
+                replace: shouldReplace,
+            });
+        });
+    }, [enabled, navigate, key, replaceOption, location.hash, getUrlLengthWithSearchParam, currentSearchValue]);
+    return useMemo(() => ({ searchValue: currentSearchValue, updateSearchParam }), [currentSearchValue, updateSearchParam]);
+};
+
+/**
+ * Generates a localStorage key, optionally scoped to a specific user.
  *
- * @template TState - The type of the stored state.
- * @template TAction - The type of the reducer action.
- * @param options - Key, defaultState, schema, reducer, and optional callbacks.
- * @param options.key - The storage key.
- * @param options.defaultState - Fallback value when no stored data exists.
- * @param options.schema - Zod schema for validation.
- * @param options.reducer - The reducer function.
- * @param options.onValidationFailed - Optional error callback.
- * @param options.onValidationSuccessful - Optional success callback.
- * @returns {Array} A tuple of [state, dispatch].
- */
-const useLocalStorageReducer = (options) => useWebStorageReducer(globalThis.localStorage, options);
-
-/**
- * Works like useState, but persists to sessionStorage with Zod schema validation
- * and superjson serialization (supports Date, Map, Set, BigInt, etc.).
+ * When `userId` is provided the key is `"key-userId"`.
+ * When omitted the key is returned as-is (unscoped).
  *
- * @template TState - The type of the stored state.
- * @param options - Key, defaultState, schema, and optional callbacks.
- * @param options.key - The storage key.
- * @param options.defaultState - Fallback value when no stored data exists.
- * @param options.schema - Zod schema for validation.
- * @param options.onValidationFailed - Optional error callback.
- * @param options.onValidationSuccessful - Optional success callback.
- * @returns {Array} A tuple of [state, setState, reset].
+ * @param key - Unique persistence identifier.
+ * @param userId - Client-side user id to scope storage per user.
+ * @returns {string} The combined storage key.
  */
-const useSessionStorage = (options) => useWebStorage(globalThis.sessionStorage, options);
+const useStorageKey = (key, userId) => {
+    return useMemo(() => (userId ? `${key}-${userId}` : key), [key, userId]);
+};
 
 /**
- * Works like useReducer, but persists to sessionStorage with Zod schema validation
- * and superjson serialization (supports Date, Map, Set, BigInt, etc.).
+ * Generic persistence hook that loads state from URL search params (with
+ * localStorage fallback) and writes changes to both.
  *
- * @template TState - The type of the stored state.
- * @template TAction - The type of the reducer action.
- * @param options - Key, defaultState, schema, reducer, and optional callbacks.
- * @param options.key - The storage key.
- * @param options.defaultState - Fallback value when no stored data exists.
- * @param options.schema - Zod schema for validation.
- * @param options.reducer - The reducer function.
- * @param options.onValidationFailed - Optional error callback.
- * @param options.onValidationSuccessful - Optional success callback.
- * @returns {Array} A tuple of [state, dispatch].
+ * On mount the hook tries, in order:
+ *  1. Decode the URL search param and pass it through `validate`.
+ *  2. If that yields nothing, read localStorage and pass the parsed JSON through `validate`.
+ *
+ * `persistState` writes the state to localStorage (via `serialize`, default
+ * `JSON.stringify`) and syncs to the URL (via `toUrlValue` + encoding).
+ * Duplicate writes where the state has not changed (deep equality) are skipped.
+ *
+ * @param options - Configuration for the persisted state.
+ * @param options.key - Unique identifier used for both the URL search param and the localStorage key.
+ * @param options.validate - Called with the decoded/parsed value; must return `TState` or `undefined`.
+ * @param options.serialize - Custom localStorage serialiser (default `storageSerializer.serialize`).
+ * @param options.toUrlValue - Transform applied before URL encoding (default: encode state as-is).
+ * @param options.fromUrlValue - Transform applied after URL decoding, before validation (default: identity).
+ * @param options.enabled - When `false` the URL is neither read nor written (default `true`).
+ * @param options.onExternalChange - Fired when the URL param changes externally (e.g. browser back).
+ * @param options.replace - Forwarded to `useSearchParamSync`.
+ * @param options.clientSideUserId - The user ID to use for the localStorage key.
  */
-const useSessionStorageReducer = (options) => useWebStorageReducer(globalThis.sessionStorage, options);
+const usePersistedState = ({ key, validate, serialize, toUrlValue, fromUrlValue, enabled = true, onExternalChange, replace, clientSideUserId, }) => {
+    const { encode, decode } = useCustomEncoding();
+    const { searchValue, updateSearchParam } = useSearchParamSync({
+        key,
+        enabled,
+        onExternalChange,
+        replace,
+    });
+    const storageKey = useStorageKey(key, clientSideUserId);
+    const validateRef = useRef(validate);
+    useEffect(() => {
+        validateRef.current = validate;
+    }, [validate]);
+    const toUrlValueRef = useRef(toUrlValue);
+    useEffect(() => {
+        toUrlValueRef.current = toUrlValue;
+    }, [toUrlValue]);
+    const fromUrlValueRef = useRef(fromUrlValue);
+    useEffect(() => {
+        fromUrlValueRef.current = fromUrlValue;
+    }, [fromUrlValue]);
+    const serializeRef = useRef(serialize);
+    useEffect(() => {
+        serializeRef.current = serialize;
+    }, [serialize]);
+    const [initialState] = useState(() => {
+        if (enabled && searchValue) {
+            try {
+                const decoded = decode(searchValue);
+                const transformed = fromUrlValue ? fromUrlValue(decoded) : decoded;
+                const validated = validate(transformed);
+                if (validated !== undefined) {
+                    return validated;
+                }
+            }
+            catch {
+                // fall through to localStorage
+            }
+        }
+        try {
+            const raw = localStorage.getItem(storageKey);
+            if (raw) {
+                const parsed = storageSerializer.deserialize(raw);
+                return validate(parsed);
+            }
+        }
+        catch {
+            // no valid stored state
+        }
+        return undefined;
+    });
+    const lastPersistedRef = useRef(initialState);
+    const persistState = useCallback((state) => {
+        if (dequal(lastPersistedRef.current, state)) {
+            return;
+        }
+        lastPersistedRef.current = state;
+        const serialized = serializeRef.current ? serializeRef.current(state) : storageSerializer.serialize(state);
+        localStorage.setItem(storageKey, serialized);
+        const urlValue = toUrlValueRef.current ? toUrlValueRef.current(state) : state;
+        updateSearchParam(encode(urlValue));
+    }, [storageKey, encode, updateSearchParam]);
+    return useMemo(() => ({ initialState, persistState }), [initialState, persistState]);
+};
 
 const OVERSCAN = 10;
 const DEFAULT_ROW_HEIGHT = 50;
@@ -9348,21 +11587,6 @@ const useElevatedState = (initialState, customState) => {
     return useMemo(() => customState ?? [fallbackValue, fallbackSetter], [customState, fallbackValue, fallbackSetter]);
 };
 
-/**
- * Differentiate between the first and subsequent renders.
- *
- * @returns {boolean} Returns true if it is the first render, false otherwise.
- */
-const useIsFirstRender = () => {
-    const [isFirstRender, setIsFirstRender] = useState(true);
-    useLayoutEffect(() => {
-        queueMicrotask(() => {
-            setIsFirstRender(false);
-        });
-    }, []);
-    return isFirstRender;
-};
-
 /**
  * Custom hook for checking if the browser is in fullscreen mode.
  */
@@ -10031,184 +12255,6 @@ const getWindowSize = () => {
     }
 };
 
-/**
- * Blocks scrolling on the document and compensates for scrollbar width to prevent layout shift.
- * Uses scrollbar-gutter: stable to reserve space for the scrollbar when hiding overflow,
- * but only if a scrollbar was actually visible before blocking.
- * This only has an effect with classic scrollbars - overlay scrollbars (macOS default) are unaffected.
- * Returns the original styles so they can be restored later.
- *
- * @returns {OriginalStyles} The original styles before blocking
- */
-const blockDocumentScroll = () => {
-    const { body } = document;
-    const html = document.documentElement;
-    // Check if there's a visible scrollbar before we hide it
-    // The scrollbar can be on either <html> or <body> depending on CSS setup
-    // (e.g., Storybook sets overflow:hidden on html and overflow:auto on body)
-    // Check html scrollbar: window.innerWidth includes scrollbar, clientWidth doesn't
-    const htmlScrollbarWidth = window.innerWidth - html.clientWidth;
-    // Check body scrollbar: offsetWidth includes border+scrollbar, clientWidth excludes both
-    const bodyStyle = window.getComputedStyle(body);
-    const bodyBorderLeft = parseInt(bodyStyle.borderLeftWidth) || 0;
-    const bodyBorderRight = parseInt(bodyStyle.borderRightWidth) || 0;
-    const bodyScrollbarWidth = body.offsetWidth - bodyBorderLeft - bodyBorderRight - body.clientWidth;
-    // Use whichever scrollbar is present
-    const hasVisibleScrollbar = htmlScrollbarWidth > 0 || bodyScrollbarWidth > 0;
-    // Store original values before modifying
-    const originalStyles = {
-        html: {
-            position: html.style.position,
-            overflow: html.style.overflow,
-        },
-        body: {
-            position: body.style.position,
-            overflow: body.style.overflow,
-            scrollbarGutter: body.style.scrollbarGutter,
-        },
-    };
-    // Block scroll on both html and body for cross-browser compatibility
-    html.style.position = "relative";
-    html.style.overflow = "hidden";
-    body.style.position = "relative";
-    body.style.overflow = "hidden";
-    // Apply scrollbar-gutter on body (where the scrollbar typically lives when content scrolls)
-    // This reserves space for the scrollbar even when overflow is hidden, preventing layout shift.
-    // Only has effect with classic scrollbars - overlay scrollbars (macOS default) are unaffected.
-    if (hasVisibleScrollbar) {
-        body.style.scrollbarGutter = "stable";
-    }
-    return originalStyles;
-};
-/**
- * Restores document scrolling by restoring the provided original styles.
- *
- * @param originalStyles - The original styles to restore
- */
-const restoreDocumentScroll = (originalStyles) => {
-    const { body } = document;
-    const html = document.documentElement;
-    // Restore original values instead of just clearing
-    if (originalStyles.html) {
-        html.style.position = originalStyles.html.position;
-        html.style.overflow = originalStyles.html.overflow;
-    }
-    if (originalStyles.body) {
-        body.style.position = originalStyles.body.position;
-        body.style.overflow = originalStyles.body.overflow;
-        body.style.scrollbarGutter = originalStyles.body.scrollbarGutter;
-    }
-};
-/**
- * Blocks scrolling on a custom container element.
- * Uses scrollbar-gutter: stable to reserve space for the scrollbar when hiding overflow,
- * but only if a scrollbar was actually visible before blocking.
- * This only has an effect with classic scrollbars - overlay scrollbars (macOS default) are unaffected.
- * Returns the original styles so they can be restored later.
- *
- * @param container - The container element to block scroll on
- * @returns {OriginalStyles} The original styles before blocking
- */
-const blockContainerScroll = (container) => {
-    // Check if there's a visible scrollbar before we hide it
-    // offsetWidth includes border + scrollbar, clientWidth excludes both
-    // We need to subtract borders to isolate the scrollbar width
-    const style = window.getComputedStyle(container);
-    const borderLeft = parseInt(style.borderLeftWidth) || 0;
-    const borderRight = parseInt(style.borderRightWidth) || 0;
-    const scrollbarWidth = container.offsetWidth - borderLeft - borderRight - container.clientWidth;
-    const hasVisibleScrollbar = scrollbarWidth > 0;
-    const originalStyles = {
-        container: {
-            overflow: container.style.overflow,
-            scrollbarGutter: container.style.scrollbarGutter,
-        },
-    };
-    container.style.overflow = "hidden";
-    // Only add scrollbar-gutter if there was a visible scrollbar to preserve space for
-    // This prevents adding unnecessary space when content doesn't overflow
-    if (hasVisibleScrollbar) {
-        container.style.scrollbarGutter = "stable";
-    }
-    return originalStyles;
-};
-/**
- * Restores container scrolling by restoring the provided original styles.
- *
- * @param container - The container element to restore scroll on
- * @param originalStyles - The original styles to restore
- */
-const restoreContainerScroll = (container, originalStyles) => {
-    if (originalStyles.container) {
-        container.style.overflow = originalStyles.container.overflow;
-        container.style.scrollbarGutter = originalStyles.container.scrollbarGutter;
-    }
-};
-/**
- * Hook that provides scroll blocking functionality.
- * This properly accounts for existing body padding to prevent layout shifts.
- *
- * Each instance gets its own stored original styles via refs, preventing
- * conflicts when multiple components are used on the same page. The hook also ensures
- * cleanup on unmount if scroll is still blocked.
- *
- * @param scrollContainer - The DOM element whose scroll should be blocked. Defaults to document.body.
- * @returns {{blockScroll: () => void, restoreScroll: () => void}} Object containing blockScroll and restoreScroll functions
- */
-const useScrollBlock = (scrollContainer = typeof document !== "undefined" ? document.body : null // default to document.body if no scroll container is provided
-) => {
-    const originalStylesRef = useRef(null);
-    const isBlockedRef = useRef(false);
-    /**
-     * Blocks scrolling and stores original styles for restoration.
-     * Blocks the document (body/html) if scroll container is the document body,
-     * or blocks the custom container if a custom container is provided.
-     */
-    const blockScroll = useCallback(() => {
-        if (isBlockedRef.current || !scrollContainer) {
-            return; // Already blocked or no scroll container
-        }
-        if (scrollContainer === document.body) {
-            originalStylesRef.current = blockDocumentScroll();
-        }
-        else {
-            originalStylesRef.current = blockContainerScroll(scrollContainer);
-        }
-        isBlockedRef.current = true;
-    }, [scrollContainer]);
-    /**
-     * Restores scrolling using the previously stored original styles.
-     */
-    const restoreScroll = useCallback(() => {
-        if (!isBlockedRef.current || !scrollContainer || !originalStylesRef.current) {
-            return;
-        }
-        if (scrollContainer === document.body) {
-            restoreDocumentScroll(originalStylesRef.current);
-        }
-        else {
-            restoreContainerScroll(scrollContainer, originalStylesRef.current);
-        }
-        originalStylesRef.current = null;
-        isBlockedRef.current = false;
-    }, [scrollContainer]);
-    // Cleanup: restore scroll if component unmounts while scroll is blocked
-    useEffect(() => {
-        return () => {
-            if (isBlockedRef.current && scrollContainer && originalStylesRef.current) {
-                if (scrollContainer === document.body) {
-                    restoreDocumentScroll(originalStylesRef.current);
-                }
-                else {
-                    restoreContainerScroll(scrollContainer, originalStylesRef.current);
-                }
-                isBlockedRef.current = false;
-            }
-        };
-    }, [scrollContainer]);
-    return useMemo(() => ({ blockScroll, restoreScroll }), [blockScroll, restoreScroll]);
-};
-
 /**
  * A useRef that updates its given value whenever it changes.
  *
@@ -10276,4 +12322,4 @@ const useWindowActivity = ({ onFocus, onBlur, skip = false } = { onBlur: undefin
     return useMemo(() => ({ focused }), [focused]);
 };
 
-export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, List, ListItem, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SectionHeader, SegmentedValueBar, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGridAreas, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowBorder, useOverflowItems, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSelfUpdatingRef, useSessionStorage, useSessionStorageReducer, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };
+export { ActionRenderer, Alert, Badge, Breadcrumb, BreadcrumbContainer, Button, Card, CardBody, CardFooter, CardHeader, Collapse, CompletionStatusIndicator, CopyableText, DEFAULT_SKELETON_PREFERENCE_CARD_PROPS, DetailsList, EmptyState, EmptyValue, ExternalLink, GridAreas, Heading, Highlight, HorizontalOverflowScroller, Icon, IconButton, Indicator, KPI, KPICard, KPICardSkeleton, KPISkeleton, List, ListItem, MAX_URL_LENGTH, MenuDivider, MenuItem, MenuList, MoreMenu, Notice, PackageNameStoryComponent, Page, PageContent, PageHeader, PageHeaderKpiMetrics, PageHeaderSecondaryActions, PageHeaderTitle, Pagination, Polygon, Popover, PopoverContent, PopoverTitle, PopoverTrigger, Portal, PreferenceCard, PreferenceCardSkeleton, Prompt, ROLE_CARD, SHEET_TRANSITION_DURATION, SHEET_TRANSITION_DURATION_MS, SHEET_TRANSITION_EASING, SectionHeader, SegmentedValueBar, Sheet, Sidebar, SkeletonBlock, SkeletonLabel, SkeletonLines, Spacer, Spinner, StarButton, Tab, TabContent, TabList, Tabs, Tag, Text, ToggleGroup, Tooltip, TrendIndicator, TrendIndicators, ValueBar, ZStack, createGrid, cvaButton, cvaButtonPrefixSuffix, cvaButtonSpinner, cvaButtonSpinnerContainer, cvaClickable, cvaContainerStyles, cvaContentContainer, cvaContentWrapper, cvaDescriptionCard, cvaIconBackground, cvaIconButton, cvaImgStyles, cvaIndicator, cvaIndicatorIcon, cvaIndicatorIconBackground, cvaIndicatorLabel, cvaIndicatorPing, cvaInputContainer, cvaInteractableItem, cvaList, cvaListContainer, cvaListItem$1 as cvaListItem, cvaMenu, cvaMenuItem, cvaMenuItemLabel, cvaMenuItemPrefix, cvaMenuItemStyle, cvaMenuItemSuffix, cvaMenuList, cvaMenuListDivider, cvaMenuListItem, cvaMenuListMultiSelect, cvaPageHeader, cvaPageHeaderContainer, cvaPageHeaderHeading, cvaPreferenceCard, cvaTitleCard, cvaToggleGroup, cvaToggleGroupWithSlidingBackground, cvaToggleItem, cvaToggleItemContent, cvaToggleItemText, cvaZStackContainer, cvaZStackItem, defaultPageSize, docs, getDevicePixelRatio, getValueBarColorByValue, iconColorNames, iconPalette, noPagination, preferenceCardGrid, storageSerializer, useBidirectionalScroll, useClickOutside, useContainerBreakpoints, useContinuousTimeout, useCopyToClipboard, useCursorUrlSync, useCustomEncoding, useDebounce, useDevicePixelRatio, useElevatedReducer, useElevatedState, useGridAreas, useHover, useInfiniteScroll, useIsFirstRender, useIsFullscreen, useIsTextTruncated, useKeyboardShortcut, useList, useListItemHeight, useLocalStorage, useLocalStorageReducer, useMeasure, useMergeRefs, useModifierKey, useOverflowBorder, useOverflowItems, usePersistedState, usePopoverContext, usePrevious, usePrompt, useRandomCSSLengths, useRelayPagination, useResize, useScrollBlock, useScrollDetection, useSearchParamSync, useSelfUpdatingRef, useSessionStorage, useSessionStorageReducer, useSheet, useSheetSnap, useStorageKey, useTextSearch, useTimeout, useViewportBreakpoints, useWatch, useWindowActivity };