@trackunit/react-components 1.21.13 → 1.21.15

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

@@ -0,0 +1,19 @@
+import { type RefObject } from "react";
+export type UseProximityAnimationReturn = {
+    /** Cancel any running proximity RAF loop and clear the CSS property. */
+    readonly cancelProximityAnimation: () => void;
+    /**
+     * Start a RAF loop that drives `--sheet-snap-proximity` as the sheet
+     * settles into a snap, then fades it back to 0.
+     */
+    readonly startProximityAnimation: (sheet: HTMLElement, targetHeight: number) => void;
+};
+/**
+ * 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.
+ */
+export declare const useProximityAnimation: (sheetRef: RefObject<HTMLElement | null>) => UseProximityAnimationReturn;

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

@@ -0,0 +1,27 @@
+import type { UseSheetProps, UseSheetReturnValue } from "./sheet-types";
+/**
+ * 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.
+ */
+export declare const useSheet: (props?: UseSheetProps) => UseSheetReturnValue;

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

@@ -0,0 +1,28 @@
+import { type RefObject } from "react";
+import type { SheetAnimationState } from "./sheet-animation-reducer";
+type UseSheetDismissIntentProps = {
+    /** Whether the sheet supports close gestures (onCloseGesture is defined). */
+    readonly closable: boolean;
+    /** Current close animation phase from the animation reducer. */
+    readonly closePhase: SheetAnimationState["closePhase"];
+    /** Ref to the panel element where `--sheet-dismiss-progress` is set. */
+    readonly panelRef: RefObject<HTMLElement | null>;
+};
+type UseSheetDismissIntentReturn = {
+    readonly onMouseEnter: () => void;
+    readonly onMouseLeave: () => void;
+};
+/**
+ * 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).
+ */
+export declare const useSheetDismissIntent: ({ closable, closePhase, panelRef, }: UseSheetDismissIntentProps) => UseSheetDismissIntentReturn;
+export {};

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

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

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

@@ -0,0 +1,49 @@
+import { type PointerEvent as ReactPointerEvent, type RefObject } from "react";
+/**
+ * Props for the useSheetGestures hook.
+ */
+export type UseSheetGesturesProps = {
+    /** Available snap heights in pixels, sorted ascending. */
+    readonly snapHeights: ReadonlyArray<number>;
+    /** Current active snap height in pixels. */
+    readonly activeSnapHeight: number;
+    /**
+     * Ref to the sheet panel element.
+     * The hook sets `--sheet-drag-height` CSS custom property and manages
+     * the `transition` inline style on this element during drag.
+     */
+    readonly sheetRef: RefObject<HTMLElement | null>;
+    /** Called with the target snap height (px) when the user releases. */
+    readonly onSnap: (snapHeight: number) => void;
+    /** Called when the sheet should close (dragged below close threshold). When absent, snaps to min instead. */
+    readonly onClose?: () => void;
+    /** Container height in pixels (used for close threshold calculation). */
+    readonly containerHeight: number;
+    /** Whether gesture handling is enabled. */
+    readonly enabled: boolean;
+};
+/**
+ * Return value of useSheetGestures.
+ * Attach all three pointer handlers to the drag handle element.
+ * The handle element MUST have `touch-action: none` in CSS.
+ */
+export type UseSheetGesturesReturn = {
+    readonly onPointerDown: (e: ReactPointerEvent) => void;
+    readonly onPointerMove: (e: ReactPointerEvent) => void;
+    readonly onPointerUp: (e: ReactPointerEvent) => void;
+    readonly onLostPointerCapture: () => void;
+    readonly isDragging: boolean;
+};
+/**
+ * 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.
+ */
+export declare const useSheetGestures: (props: UseSheetGesturesProps) => UseSheetGesturesReturn;

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

@@ -0,0 +1,35 @@
+import { type Dispatch, type RefObject, type TransitionEvent } from "react";
+import type { SheetAnimationAction } from "./sheet-animation-reducer";
+import type { SheetVariant } from "./sheet-types";
+type UseSheetLifecycleProps = {
+    readonly isOpen: boolean;
+    readonly entryAnimation: boolean;
+    readonly visuallyOpen: boolean;
+    readonly variant: SheetVariant;
+    readonly container: HTMLElement | null;
+    readonly panelRef: RefObject<HTMLDivElement | null>;
+    readonly panelEl: HTMLDivElement | null;
+    readonly dispatch: Dispatch<SheetAnimationAction>;
+    readonly onCloseComplete?: () => void;
+    /**
+     * True once the content height is known (or fit mode is inactive).
+     * The entry animation is deferred until this is true so the sheet
+     * slides in at the correct height without a visible jump.
+     */
+    readonly fitHeightReady: boolean;
+};
+/**
+ * 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.
+ */
+export declare const useSheetLifecycle: ({ isOpen, entryAnimation, visuallyOpen, variant, container, panelRef, panelEl, dispatch, onCloseComplete, fitHeightReady, }: UseSheetLifecycleProps) => {
+    readonly handleTransitionEnd: (e: TransitionEvent<HTMLDivElement>) => void;
+};
+export {};

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

@@ -0,0 +1,31 @@
+import { type Ref, type RefCallback, type RefObject } from "react";
+import type { SheetGeometry, SheetState } from "./sheet-types";
+type UseSheetMeasurementsProps = {
+    readonly shouldRender: boolean;
+    readonly state: SheetState;
+    readonly dockingEnabled: boolean;
+    readonly snapping: boolean;
+    readonly externalRef: Ref<HTMLDivElement> | undefined;
+    readonly onGeometryChange: (geometry: SheetGeometry, dockingEnabled: boolean) => void;
+    readonly onSnap: (heightPx: number, useLevelSnap: boolean) => void;
+};
+type UseSheetMeasurementsReturn = {
+    readonly containerRef: RefCallback<HTMLElement>;
+    readonly mergedPanelRef: RefCallback<HTMLDivElement> | null;
+    readonly panelRefObj: RefObject<HTMLDivElement | null>;
+    readonly panelEl: HTMLDivElement | null;
+    readonly containerHeight: number;
+    readonly activeSnapHeightPx: number;
+    readonly gestureSnapHeights: ReadonlyArray<number>;
+    readonly cappedFitHeight: number;
+    readonly fitHeightReady: boolean;
+    readonly fitHeight: number;
+    readonly handleGestureSnap: (heightPx: number) => void;
+};
+/**
+ * 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.
+ */
+export declare const useSheetMeasurements: ({ shouldRender, state, dockingEnabled, snapping, externalRef, onGeometryChange, onSnap, }: UseSheetMeasurementsProps) => UseSheetMeasurementsReturn;
+export {};

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

@@ -0,0 +1,30 @@
+type UseSheetMotionOverflowProps = {
+    readonly panelEl: HTMLDivElement | null;
+    readonly isDragging: boolean;
+    readonly scrollAreaEl: HTMLDivElement | null;
+    readonly separatorEl: HTMLElement | null;
+    readonly isDocked: boolean;
+    readonly isClosing: boolean;
+};
+/**
+ * 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).
+ */
+export declare const useSheetMotionOverflow: ({ panelEl, isDragging, scrollAreaEl, separatorEl, isDocked, isClosing, }: UseSheetMotionOverflowProps) => void;
+export {};

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

@@ -0,0 +1,14 @@
+import type { SheetDefaultSize, UseSheetSnapReturn } from "./sheet-types";
+type UseSheetSnapProps = {
+    readonly defaultSize: SheetDefaultSize;
+    readonly isOpen: boolean;
+};
+/**
+ * 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.
+ */
+export declare const useSheetSnap: ({ defaultSize, isOpen }: UseSheetSnapProps) => UseSheetSnapReturn;
+export {};

package/src/index.d.ts

@@ -77,6 +77,11 @@ export * from "./components/PreferenceCard/PreferenceCard.variants";
 export * from "./components/PreferenceCard/PreferenceCardSkeleton";
 export * from "./components/Prompt/Prompt";
 export * from "./components/SectionHeader/SectionHeader";
+export { Sheet } from "./components/Sheet/Sheet";
+export { SHEET_TRANSITION_DURATION, SHEET_TRANSITION_DURATION_MS, SHEET_TRANSITION_EASING, } from "./components/Sheet/sheet-snap-config";
+export type { SheetAnchor, SheetDefaultSize, SheetEntryAnimation, SheetFloatingUiProps, SheetGeometry, SheetProps, SheetSizingMode, SheetSnapActions, SheetState, SheetVariant, UseSheetProps, UseSheetReturnValue, UseSheetSnapReturn, } from "./components/Sheet/sheet-types";
+export { useSheet } from "./components/Sheet/useSheet";
+export { useSheetSnap } from "./components/Sheet/useSheetSnap";
 export * from "./components/Sidebar/Sidebar";
 export * from "./components/Sidebar/useOverflowItems";
 export { useRandomCSSLengths } from "./components/Skeleton/Skeleton.helpers";