@astryxdesign/core 0.4.3 → 0.4.4-canary.0e8af82

package/dist/BottomSheet/useSheetGestures.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @file useSheetGestures.ts
+ * @input Uses React (useCallback, useEffect, useMemo, useRef, useState) and
+ *   the core useMediaQuery hook
+ * @output Exports useSheetGestures hook and its option/result types
+ * @position Internal to BottomSheet; not exported from the core entry point
+ *
+ * Drag + snap machinery for the bottom sheet. Tracks a pointer drag down the
+ * block axis, translates the sliding surface live, and on release either
+ * settles to the nearest snap detent (a slow drag) or dismisses (a fast flick
+ * down). A fast flick up expands to the tallest detent. This is the core
+ * behavior split the sheet needs: DRAG places, SWIPE closes.
+ *
+ * A settled detent is split across two properties: `settledLayoutOffset` is
+ * the part the scrolling area gives up as layout height, and the remainder is
+ * a transform. Gestures and snaps only ever move the transform, so they stay
+ * on the compositor; layout height changes at rest, in one transition-free
+ * render whose visible geometry is identical. A peek detent — a stop that is
+ * only a sliver of the sheet — keeps the full height and slides below the
+ * viewport instead of reflowing to that sliver.
+ *
+ * Those are pixels, and the stops behind them are relative to the viewport, so
+ * a sheet at rest re-resolves its detent on `resize` / `orientationchange`,
+ * and whenever the host swaps the snap points, and re-anchors to the new
+ * geometry without animating. The detent it returns to is tracked by index:
+ * the pixels stop meaning the same thing when the viewport changes, the stop
+ * the user chose does not.
+ *
+ * On touch, the scrolling body hands the gesture to the sheet at a scroll
+ * edge. Two shapes, because the browser only offers one of them a choice: a
+ * finger that lands on an edge and pulls away from it promotes by cancelling
+ * the first, still-cancelable touchmove; a finger that scrolls INTO the end of
+ * the content mid-gesture cannot, since the browser has committed the gesture
+ * to scrolling and every remaining event is non-cancelable. The second shape
+ * needs no cancelling — the scroller is clamped at its end, so there is
+ * nothing left to scroll — and instead anchors at the point where the content
+ * ran out and drives the sheet from the travel beyond it.
+ *
+ * Kept private to BottomSheet: a dismiss edge + detents on a bottom-anchored
+ * surface are inherently sheet concepts. It is not a general primitive and is
+ * intentionally not exported.
+ *
+ * SSR-safe: no window/document access at module scope; all measurement
+ * happens inside handlers. Respects prefers-reduced-motion by skipping the
+ * settle transition.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/BottomSheet/useSheetGestures.test.ts
+ */
+import { type CSSProperties, type MouseEvent as ReactMouseEvent, type PointerEvent as ReactPointerEvent, type RefObject, type UIEvent as ReactUIEvent } from 'react';
+export interface UseSheetGesturesOptions {
+    /** Whether the owning sheet is open. Drag state resets when it closes. */
+    isOpen: boolean;
+    /**
+     * Whether a downward swipe may dismiss the sheet. When false, a gesture
+     * past the dismiss threshold settles at the shortest detent instead.
+     * @default true
+     */
+    canDismiss?: boolean;
+    /**
+     * Portion of the measured sheet border box reserved below the viewport.
+     * Excluded from detent heights so a 50vh snap has 50vh of visible sheet.
+     * @default 0
+     */
+    offscreenBlockEndInset?: number;
+    /** Called on a swipe-to-close (fast downward flick, or drag past the floor). */
+    onDismiss: () => void;
+    /**
+     * Resolver for candidate visible detent heights in px below the fully open
+     * visible height. Called at the start of each drag, and again whenever the
+     * viewport changes while the sheet rests, so the detents track the window
+     * (rotation, a resized desktop window, collapsing browser chrome). The fully
+     * open height is always the tallest detent. Omit for a single-height sheet
+     * (a drag then only dismisses or springs back).
+     *
+     * Keep the identity stable: a new function is read as new stops, and
+     * re-anchors a resting sheet to them.
+     */
+    snapHeights?: () => number[];
+    /** Notified when the settled visible detent height (px) changes. */
+    onSnap?: (heightPx: number) => void;
+    /**
+     * Called with the scrim opacity the sheet should show (1 = fully visible,
+     * 0 = hidden) as the drag moves and on settle. Full while the sheet is at
+     * or above its mid detent, fading to 0 as it collapses onto the shortest
+     * "peek" detent — thinning to a faint glance state without fully clearing — and
+     * on the dismiss overshoot. Lets the owner mirror it onto the scrim.
+     */
+    onScrimOpacity?: (opacity: number) => void;
+}
+export interface SheetContentProps {
+    style: CSSProperties;
+}
+export interface SheetHandleProps {
+    style: CSSProperties;
+    onContextMenu: (event: ReactMouseEvent) => void;
+    onLostPointerCapture: (event: ReactPointerEvent) => void;
+    onPointerDown: (event: ReactPointerEvent) => void;
+    onPointerMove: (event: ReactPointerEvent) => void;
+    onPointerUp: (event: ReactPointerEvent) => void;
+    onPointerCancel: (event: ReactPointerEvent) => void;
+}
+export interface SheetBodyProps {
+    ref: (node: HTMLElement | null) => void;
+    onContextMenu: (event: ReactMouseEvent) => void;
+    onLostPointerCapture: (event: ReactPointerEvent) => void;
+    onPointerDown: (event: ReactPointerEvent) => void;
+    onPointerMove: (event: ReactPointerEvent) => void;
+    onPointerUp: (event: ReactPointerEvent) => void;
+    onPointerCancel: (event: ReactPointerEvent) => void;
+    onScroll: (event: ReactUIEvent<HTMLElement>) => void;
+}
+export interface UseSheetGesturesResult {
+    /**
+     * Callback ref for the sheet surface. The hook observes it (ResizeObserver)
+     * to keep the fully-open height current, so detents stay correct across
+     * rotation / viewport changes without re-measuring mid-drag.
+     */
+    sheetRef: (node: HTMLElement | null) => void;
+    /** Spread on the sliding surface: live translate + touch-action guard. */
+    contentProps: SheetContentProps;
+    /** Spread on the grab-handle element: pointer drag handlers. */
+    handleProps: SheetHandleProps;
+    /**
+     * Spread on the scrollable body. An overscroll-at-top pull-down starts a
+     * sheet drag (a larger, more forgiving target when the content isn't itself
+     * scrolling); normal scrolling passes through untouched.
+     */
+    bodyProps: SheetBodyProps;
+    /**
+     * The body element `bodyProps.ref` is attached to. The hook tracks the node
+     * anyway (it owns the non-passive touch listeners on it), so a host that
+     * also needs the element reads it here rather than wrapping `bodyProps.ref`
+     * in a second callback ref.
+     */
+    bodyElementRef: RefObject<HTMLElement | null>;
+    /** Current live drag translate in px (0 = fully expanded, larger = collapsed). */
+    dragOffset: number;
+    /** Translate of the resting detent in px (0 = tallest detent). */
+    settledOffset: number;
+    /** Whether a drag is currently in progress. */
+    isDragging: boolean;
+    /** Measured height of the fully expanded sheet. */
+    sheetHeight: number;
+    /** End padding that preserves the scroll position across height changes. */
+    scrollPreservationInset: number;
+    /** Layout offset retained until the transform-only snap finishes. */
+    settlingLayoutOffset: number | null;
+    /**
+     * Reconciles the final layout once the transform-only snap finishes. The
+     * panel decides WHEN a snap is over (it owns the element and its computed
+     * transition), so completion cannot be driven from a `transitionend`
+     * listener alone: with transitions disabled — inline `transition: none`, a
+     * `0s` duration token, a test harness turning animation off — no event ever
+     * arrives and the scroll area would keep its full height forever.
+     */
+    completeScrollAreaSettle: () => void;
+    /**
+     * How much of `settledOffset` is expressed as layout height rather than as a
+     * transform. Equals `settledOffset` at the resizing detents; 0 at fully open
+     * and at the peek, which keep the sheet's full height (see peekOffsetFor).
+     */
+    settledLayoutOffset: number;
+}
+/**
+ * Drag + snap machinery for the bottom sheet. Returns props to spread on the
+ * grab handle and the sliding surface, plus live drag state. A slow drag
+ * settles to the nearest detent; a fast downward flick dismisses; a fast
+ * upward flick expands to the tallest detent.
+ *
+ * @example
+ * ```
+ * const {contentProps, handleProps} = useSheetGestures({
+ *   isOpen,
+ *   onDismiss: () => onOpenChange(false),
+ *   snapHeights: () => [240, 0.5 * (window.visualViewport?.height ?? 0)],
+ * });
+ * <div {...contentProps}>
+ *   <div {...handleProps} />
+ *   {children}
+ * </div>
+ * ```
+ */
+export declare function useSheetGestures({ isOpen, canDismiss, offscreenBlockEndInset, onDismiss, snapHeights, onSnap, onScrimOpacity, }: UseSheetGesturesOptions): UseSheetGesturesResult;
+//# sourceMappingURL=useSheetGestures.d.ts.map

package/dist/BottomSheet/useSheetGestures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSheetGestures.d.ts","sourceRoot":"","sources":["../../src/BottomSheet/useSheetGestures.ts"],"names":[],"mappings":"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"}