@trackunit/react-components 1.21.13 → 1.21.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "1.21.13",
+  "version": "1.21.15",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -13,10 +13,10 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.11.93",
-    "@trackunit/css-class-variance-utilities": "1.11.96",
-    "@trackunit/shared-utils": "1.13.96",
-    "@trackunit/ui-icons": "1.11.92",
+    "@trackunit/ui-design-tokens": "1.11.94",
+    "@trackunit/css-class-variance-utilities": "1.11.97",
+    "@trackunit/shared-utils": "1.13.97",
+    "@trackunit/ui-icons": "1.11.93",
     "es-toolkit": "^1.39.10",
     "@tanstack/react-virtual": "3.13.12",
     "fflate": "^0.8.2",

package/src/components/Sheet/Sheet.d.ts

@@ -0,0 +1,29 @@
+import { type ReactElement } from "react";
+import type { SheetProps } from "./sheet-types";
+/**
+ * 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.
+ */
+export declare const Sheet: ({ isOpen, state, snap, onGeometryChange, onSnap, onClickHandle, onCloseGesture, floatingUi, ref, anchor, snapping, resizable, variant, trapFocus, container, dockedContent, className, "data-testid": dataTestId, onCloseComplete, entryAnimation, children, }: SheetProps) => ReactElement | null;

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

@@ -0,0 +1,63 @@
+import type { CSSProperties } from "react";
+import type { SheetAnimationState } from "./sheet-animation-reducer";
+import type { SheetVariant } from "./sheet-types";
+/**
+ * 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.
+ */
+export declare const cvaSheetContainer: (props?: ({
+    docked?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * Sheet panel — the main content surface, always positioned at the bottom
+ * of the container.
+ *
+ * Height and vertical positioning are controlled via inline styles returned
+ * by `getSheetPanelStyle()`:
+ *
+ * - `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)
+ *
+ * During drag, the gesture hook sets `--sheet-drag-height` and `transition: none`
+ * directly on the element for immediate visual feedback, then restores on release.
+ */
+export declare const cvaSheetPanel: (props?: ({
+    anchor?: "center" | "start" | "end" | null | undefined;
+    variant?: "default" | "modal" | "floating" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * 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.
+ */
+export declare const cvaSheetScrollArea: (props?: ({
+    fillHeight?: boolean | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * 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.
+ */
+export declare const getSheetPanelStyle: ({ snapHeight, isOpen, closePhase, variant, autoHeight, maxHeight, isDragging, suppressTransition, }: {
+    readonly snapHeight: string;
+    readonly isOpen: boolean;
+    readonly closePhase: SheetAnimationState["closePhase"];
+    readonly variant: SheetVariant;
+    readonly autoHeight?: boolean;
+    readonly maxHeight?: string;
+    readonly isDragging?: boolean;
+    readonly suppressTransition?: boolean;
+}) => CSSProperties;

package/src/components/Sheet/SheetHandle.d.ts

@@ -0,0 +1,64 @@
+import type { MouseEventHandler, ReactElement, PointerEvent as ReactPointerEvent } from "react";
+/**
+ * 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`.
+ */
+export declare const HANDLE_VISUALS: {
+    readonly line: {
+        readonly base: "var(--color-neutral-300)";
+        readonly emphasized: "var(--color-neutral-600)";
+        readonly interaction: {
+            readonly idle: 0;
+            readonly hover: 0.15;
+            readonly dragging: 0.25;
+            readonly pressed: 0.5;
+        };
+        readonly proximityWeight: 0.5;
+    };
+};
+/**
+ * Props for the SheetHandle component.
+ */
+export type SheetHandleProps = {
+    /** Pointer event handler from useSheetGestures. */
+    readonly onPointerDown?: (e: ReactPointerEvent) => void;
+    /** Pointer event handler from useSheetGestures. */
+    readonly onPointerMove?: (e: ReactPointerEvent) => void;
+    /** Pointer event handler from useSheetGestures. */
+    readonly onPointerUp?: (e: ReactPointerEvent) => void;
+    /** Resets drag state when the browser cancels the pointer stream (e.g. tab switch, touch interruption). */
+    readonly onLostPointerCapture?: () => void;
+    /** Click handler for cycling snap levels and modifier-based actions. */
+    readonly onClick?: MouseEventHandler<HTMLDivElement>;
+    /** Whether the handle is currently being dragged. Controls visual state. */
+    readonly isDragging?: boolean;
+    /** Mouse enter handler (from useHover). */
+    readonly onMouseEnter?: () => void;
+    /** Mouse leave handler (from useHover). */
+    readonly onMouseLeave?: () => void;
+    /** Test ID for the handle element. */
+    readonly "data-testid"?: string;
+};
+/**
+ * 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.
+ */
+export declare const SheetHandle: ({ onPointerDown, onPointerMove, onPointerUp, onLostPointerCapture, onClick, isDragging, onMouseEnter, onMouseLeave, "data-testid": dataTestId, }: SheetHandleProps) => ReactElement;

package/src/components/Sheet/SheetOverlay.d.ts

@@ -0,0 +1,20 @@
+import type { ReactElement } from "react";
+/**
+ * Props for the SheetOverlay component.
+ */
+export type SheetOverlayProps = {
+    /** Whether the overlay is visible. */
+    readonly visible: boolean;
+    /** Test ID for the overlay element. */
+    readonly "data-testid"?: string;
+};
+/**
+ * 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.
+ */
+export declare const SheetOverlay: ({ visible, "data-testid": dataTestId }: SheetOverlayProps) => ReactElement;

package/src/components/Sheet/sheet-animation-reducer.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Animation lifecycle reducer for the Sheet component.
+ * Manages mount/unmount transitions and close animation phases.
+ *
+ * Since snap state no longer resets on close, Sheet reads level/sizingMode
+ * directly from SheetState during close animations — no need to freeze
+ * display values here.
+ */
+export type SheetAnimationState = {
+    readonly shouldRender: boolean;
+    readonly visuallyOpen: boolean;
+    readonly closePhase: "idle" | "collapsing" | "vanishing";
+    readonly prevIsOpen: boolean;
+};
+export declare const INITIAL_ANIMATION_STATE: SheetAnimationState;
+export type SheetAnimationAction = {
+    readonly type: "SYNC_OPEN";
+    readonly isOpen: boolean;
+    readonly skipEntryAnimation: boolean;
+} | {
+    readonly type: "SET_VISUALLY_OPEN";
+} | {
+    readonly type: "UNMOUNT";
+} | {
+    readonly type: "ENSURE_RENDER";
+} | {
+    readonly type: "START_VANISH";
+};
+/** Reducer managing the Sheet component's mount/unmount animation lifecycle. */
+export declare const sheetAnimationReducer: (state: SheetAnimationState, action: SheetAnimationAction) => SheetAnimationState;

package/src/components/Sheet/sheet-gesture-utils.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Recorded pointer position for velocity calculation.
+ */
+export type PointerSample = {
+    readonly y: number;
+    readonly timestamp: number;
+};
+/** Minimum velocity (px/ms) to trigger directional snap selection. */
+export declare const VELOCITY_THRESHOLD = 0.5;
+/** Dampening factor for rubber-band effect past snap bounds. */
+export declare const RUBBER_BAND_FACTOR = 0.3;
+/**
+ * Calculates vertical velocity from pointer position history.
+ * Positive = downward, negative = upward.
+ */
+export declare const calculateVelocity: (samples: ReadonlyArray<PointerSample>) => number;
+/**
+ * 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.
+ */
+export declare const computeConstrainedEffectiveHeight: (rawDelta: number, activeSnapHeight: number, minSnap: number, maxSnap: number, closable: boolean) => number;
+/**
+ * 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.
+ */
+export declare const computeDismissProgress: (rawEffectiveHeight: number, minSnap: number, containerHeight: number, closeThresholdFraction: number, dismissDeadZonePx: number) => number;
+/**
+ * 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.
+ */
+export declare const computeSnapProximity: (constrainedHeight: number, snapHeights: ReadonlyArray<number>, direction: -1 | 0 | 1, proximityRange: number) => number;
+/**
+ * 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.
+ */
+export declare const resolveSnapTarget: (effectiveHeight: number, snapHeights: ReadonlyArray<number>, velocity: number) => number;

package/src/components/Sheet/sheet-height-utils.d.ts

@@ -0,0 +1,20 @@
+import type { SheetSizingMode } from "./sheet-types";
+/**
+ * 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.
+ */
+export declare const computeActiveSnapHeight: (sizingMode: SheetSizingMode, fitHeight: number, levelHeights: ReadonlyArray<number>, displayLevel: number, dockedHeightPx?: number) => number;
+/**
+ * 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.
+ */
+export declare const computeGestureSnapHeights: (effectiveSnapping: boolean, sizingMode: SheetSizingMode, fitHeight: number, levelHeights: ReadonlyArray<number>, dockingEnabled: boolean, dockedHeightPx?: number) => ReadonlyArray<number>;

package/src/components/Sheet/sheet-snap-config.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Width constraint for anchored sheets (start/end positioning).
+ * Uses container-relative units with a pixel cap.
+ */
+export declare const ANCHORED_SHEET_MAX_WIDTH: "min(90cqw, 420px)";
+/**
+ * Margin from container edges for anchored sheets.
+ */
+export declare const ANCHORED_SHEET_MARGIN: "12px";
+/**
+ * Transition timing for snap animations — gentle deceleration with minimal overshoot.
+ */
+export declare const SHEET_TRANSITION_DURATION_MS: 300;
+export declare const SHEET_TRANSITION_DURATION: "300ms";
+export declare 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.
+ */
+export declare 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.
+ */
+export declare 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.
+ */
+export declare const SNAP_PROXIMITY_RANGE_PX = 50;
+/** Fallback pixel height for the docked state. */
+export declare 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).
+ */
+export declare const FULL_HEIGHT_TOP_MARGIN_PX = 40;
+/**
+ * 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.
+ *
+ * The resulting heights are sorted ascending (smallest first).
+ *
+ * @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.
+ */
+export declare const computeSnapLevelHeights: (containerHeight: number, dockingEnabled: boolean, dockedHeightPx?: number) => ReadonlyArray<number>;
+/**
+ * Converts a snap level index to a CSS height string using container-relative units.
+ *
+ * When docking is enabled the height range starts from the docked height
+ * so the CSS value reflects the shifted distribution.
+ *
+ * @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).
+ */
+export declare const getSnapLevelCssHeight: (levelIndex: number, totalLevels: number, dockingEnabled: boolean, dockedHeightPx?: number) => string;

package/src/components/Sheet/sheet-types.d.ts

@@ -0,0 +1,209 @@
+import type { UseFloatingReturn } from "@floating-ui/react";
+import type { ReactNode, Ref, RefObject } from "react";
+import type { UseOverlayDismissibleProps } from "../../overlay-dismissible/types";
+/**
+ * Horizontal positioning of the bottom sheet.
+ * - center: Full container width (default bottom sheet)
+ * - start: Anchored to inline-start (left in LTR), constrained width
+ * - end: Anchored to inline-end (right in LTR), constrained width
+ */
+export type SheetAnchor = "center" | "start" | "end";
+/**
+ * Initial size when the sheet opens.
+ * - fit: Open at content height (fit-content). Supports dismiss via gesture and docking.
+ * - collapsed: Open at the smallest non-docked snap level.
+ * - expanded: Open at the largest snap level.
+ * - docked: Open in docked mode (requires dockedContent on Sheet).
+ */
+export type SheetDefaultSize = "fit" | "collapsed" | "expanded" | "docked";
+/**
+ * Variant controlling the sheet's appearance, backdrop, and modal behavior.
+ * - default: Standard panel, no backdrop, flush to container bottom, top-only rounded corners.
+ * - modal: Dimming backdrop that blocks background interaction, focus-trapped dialog
+ *   with `role="dialog"` and `aria-modal`. Flush bottom, top-only rounded corners.
+ * - floating: No backdrop, rounded corners on all sides, offset from the container bottom (iPad slideover style).
+ */
+export type SheetVariant = "default" | "modal" | "floating";
+/**
+ * Entry animation behavior when the sheet opens.
+ * - always: Animate every open.
+ * - subsequent: Skip the animation on the very first open, animate thereafter.
+ * - never: No entry animation; the sheet appears instantly.
+ */
+export type SheetEntryAnimation = "always" | "subsequent" | "never";
+/**
+ * Discriminant for how the sheet determines its height.
+ * Prevents impossible states (e.g. fit + docked simultaneously).
+ */
+export type SheetSizingMode = "fit" | "level" | "docked";
+/**
+ * Unified read-only state of the Sheet.
+ * Does NOT reset on close — reflects the last known position.
+ * Replaces both the old `SheetSizeInfo` and `SheetSnapDisplay`.
+ */
+export type SheetState = {
+    readonly sizingMode: SheetSizingMode;
+    /** Current snap level index (0 = collapsed). Excludes docked. */
+    readonly level: number;
+    /** Total number of snap levels available (excludes docked). */
+    readonly totalLevels: number;
+    /** Only meaningful when `sizingMode === "level"`. */
+    readonly isExpanded: boolean;
+    /** Only meaningful when `sizingMode === "level"`. */
+    readonly isCollapsed: boolean;
+    /**
+     * Measured height of the docked content in pixels. Always reflects the
+     * docked size — does not change when the sheet expands. Falls back to the
+     * default docked height (64px) before the first measurement.
+     * Zero when the sheet has no dockedContent.
+     */
+    readonly dockedHeight: number;
+    readonly levelHeights: ReadonlyArray<number>;
+    readonly effectiveDockedHeight: number;
+};
+/**
+ * Measurement data reported by Sheet to the snap system.
+ * Sent via `onGeometryChange` whenever container or content geometry changes.
+ */
+export type SheetGeometry = {
+    readonly containerHeight: number;
+    readonly fitHeight: number;
+    readonly dockedHeight: number;
+};
+/** Navigation commands returned by `useSheetSnap` and accepted by Sheet. */
+export type SheetSnapActions = {
+    readonly snapUp: () => void;
+    readonly snapDown: () => void;
+    readonly expand: () => void;
+    readonly collapse: () => void;
+    readonly dock: () => void;
+    readonly fit: () => void;
+};
+/**
+ * Floating UI props returned by `useSheet` for Sheet's focus management
+ * and dismiss interaction binding. Mirrors `useModal`'s `floatingUi` shape.
+ */
+export type SheetFloatingUiProps = {
+    readonly refs: UseFloatingReturn["refs"];
+    readonly context: UseFloatingReturn["context"];
+    readonly getFloatingProps: (userProps?: Record<string, unknown>) => Record<string, unknown>;
+};
+/** Props for the useSheet hook. */
+export type UseSheetProps = UseOverlayDismissibleProps & {
+    /**
+     * Variant controlling appearance and dismiss behavior.
+     * Outside-press dismiss is only active when `"modal"`.
+     * Flows through to the Sheet component via spread.
+     *
+     * @default "default"
+     */
+    readonly variant?: SheetVariant;
+    /** Where the sheet opens. Default: 'fit' (opens at content height). */
+    readonly defaultSize?: SheetDefaultSize;
+    /** Called when the sheet's state changes (snap level, sizing mode, etc.). */
+    readonly onStateChange?: (state: SheetState) => void;
+    /** Called when container/fit/docked geometry changes. */
+    readonly onGeometryChange?: (geometry: SheetGeometry) => void;
+};
+/** Return value of the useSheet hook. */
+export type UseSheetReturnValue = {
+    readonly isOpen: boolean;
+    readonly ref: RefObject<HTMLDivElement | null>;
+    /** Unified sheet state. Does NOT reset on close. */
+    readonly state: SheetState;
+    /** Resolved variant, passed through to Sheet via spread. */
+    readonly variant: SheetVariant;
+    readonly open: () => void;
+    readonly close: () => void;
+    /** Snap navigation commands. */
+    readonly snap: SheetSnapActions;
+    /**
+     * Floating UI props for Sheet's focus management and dismiss binding.
+     * Sheet uses `context` for FloatingFocusManager and merges
+     * `refs.setFloating` onto the panel. ESC dismiss is always active;
+     * outside-press is only active when `variant="modal"`.
+     */
+    readonly floatingUi: SheetFloatingUiProps;
+    readonly onGeometryChange: (geometry: SheetGeometry, dockingEnabled: boolean) => void;
+    readonly onSnap: (heightPx: number, useLevelSnap: boolean) => void;
+    readonly onClickHandle: () => void;
+    /** Gesture close handler for Sheet. Undefined when dismiss.gesture is false. */
+    readonly onCloseGesture: (() => void) | undefined;
+};
+/** Return value of the useSheetSnap hook. */
+export type UseSheetSnapReturn = {
+    readonly state: SheetState;
+    readonly snap: SheetSnapActions;
+    readonly onGeometryChange: (geometry: SheetGeometry, dockingEnabled: boolean) => void;
+    readonly onSnap: (heightPx: number, useLevelSnap: boolean) => void;
+    readonly onClickHandle: () => void;
+};
+/**
+ * Props for the Sheet component.
+ *
+ * Decoupled from UseSheetReturnValue — Sheet only declares the props it
+ * actually reads. Consumers spread the hook return (`{...sheet}`) and
+ * TypeScript allows extra properties on spread expressions.
+ */
+export type SheetProps = {
+    readonly isOpen: boolean;
+    /** Unified sheet state from useSheetSnap. */
+    readonly state: SheetState;
+    /** Snap navigation commands from useSheetSnap. */
+    readonly snap: SheetSnapActions;
+    readonly onGeometryChange: (geometry: SheetGeometry, dockingEnabled: boolean) => void;
+    readonly onSnap: (heightPx: number, useLevelSnap: boolean) => void;
+    readonly onClickHandle: () => void;
+    /** Gesture close handler. Undefined when gesture dismiss is disabled. */
+    readonly onCloseGesture: (() => void) | undefined;
+    /**
+     * Floating UI props for focus management and dismiss interaction binding.
+     * Provided by `useSheet`. When omitted (e.g. Modal in sheet mode),
+     * Sheet skips its own focus trap and dismiss — the parent owns those.
+     */
+    readonly floatingUi?: SheetFloatingUiProps;
+    readonly ref?: Ref<HTMLDivElement>;
+    /** Horizontal positioning of the sheet. */
+    readonly anchor?: SheetAnchor;
+    /** Enable/disable drag-to-snap between levels. Default: true. */
+    readonly snapping?: boolean;
+    /** Show the drag handle and enable all resize interactions (drag, click-to-cycle). Default: true. When false, the handle is hidden and snapping is implicitly disabled. */
+    readonly resizable?: boolean;
+    /** Variant controlling appearance, backdrop, and modal behavior. When "modal", the sheet traps focus and sets dialog ARIA attributes (unless `trapFocus` is false). Default: "default". */
+    readonly variant?: SheetVariant;
+    /**
+     * Whether the sheet should manage its own focus trap when `variant="modal"`.
+     * When true (default for modal variant), the sheet activates a
+     * FloatingFocusManager to trap keyboard focus inside the panel.
+     * Set to false when a parent component (e.g. Modal) provides its own
+     * focus management.
+     *
+     * Ignored when variant is not "modal".
+     *
+     * @default true
+     */
+    readonly trapFocus?: boolean;
+    /** The container element the sheet renders into via Portal. Required. Use a callback ref (useState setter) so mounting triggers a re-render. */
+    readonly container: HTMLElement | null;
+    /** Content rendered when in docked mode. Presence enables docking behavior. */
+    readonly dockedContent?: ReactNode;
+    /** Custom class name. */
+    readonly className?: string;
+    /** Test ID for the sheet. */
+    readonly "data-testid"?: string;
+    /** Sheet content. */
+    readonly children?: ReactNode;
+    /** Called after the close CSS transition completes (transitionend on transform). */
+    readonly onCloseComplete?: () => void;
+    /**
+     * Controls how the sheet animates when opening.
+     *
+     * - `"always"` — slide-up animation every time the sheet opens.
+     * - `"subsequent"` — skip the animation on the very first open (e.g. page
+     *   load / refresh) but animate on every subsequent open.
+     * - `"never"` — no entry animation; the sheet appears instantly.
+     *
+     * Default: `"subsequent"`.
+     */
+    readonly entryAnimation?: SheetEntryAnimation;
+};

package/src/components/Sheet/snap-reducer.d.ts

@@ -0,0 +1,48 @@
+import type { SheetDefaultSize, SheetSizingMode } from "./sheet-types";
+export type SnapState = {
+    readonly currentLevel: number;
+    readonly sizingMode: SheetSizingMode;
+    readonly initialSizeApplied: boolean;
+    readonly prevIsOpen: boolean;
+    readonly totalLevels: number;
+    readonly dockingEnabled: boolean;
+    readonly levelHeights: ReadonlyArray<number>;
+    readonly effectiveDockedHeight: number;
+    readonly fitHeight: number;
+};
+export declare const INITIAL_SNAP_STATE: SnapState;
+export type SnapAction = {
+    readonly type: "SYNC_OPEN";
+    readonly isOpen: boolean;
+} | {
+    readonly type: "SYNC_MEASUREMENTS";
+    readonly measurements: {
+        readonly fitHeight: number;
+        readonly dockedHeight: number;
+        readonly dockingEnabled: boolean;
+    };
+    readonly levelHeights: ReadonlyArray<number>;
+} | {
+    readonly type: "APPLY_INITIAL_SIZE";
+    readonly defaultSize: SheetDefaultSize;
+} | {
+    readonly type: "SNAP_UP";
+} | {
+    readonly type: "SNAP_DOWN";
+} | {
+    readonly type: "EXPAND";
+} | {
+    readonly type: "COLLAPSE";
+} | {
+    readonly type: "DOCK";
+} | {
+    readonly type: "FIT";
+} | {
+    readonly type: "GESTURE_SNAP";
+    readonly heightPx: number;
+    readonly useLevelSnap: boolean;
+} | {
+    readonly type: "CYCLE_SNAP";
+};
+/** Reducer managing snap-level positioning and measurement-derived state. */
+export declare const snapReducer: (state: SnapState, action: SnapAction) => SnapState;

package/src/components/Sheet/useDockedContentHeight.d.ts

@@ -0,0 +1,26 @@
+import type { SheetSizingMode } from "./sheet-types";
+/**
+ * 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.
+ */
+export declare const useDockedContentHeight: (element: HTMLDivElement | null, shouldRender: boolean, sizingMode: SheetSizingMode) => number;