@surdeddd/bottom-sheet 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,184 @@
+import { c as SnapPoint, a as SheetMode, S as SnapPointDef, b as EngineOptions } from './BottomSheetEngine-CvSVbo6c.cjs';
+export { B as BottomSheetEngine, E as EngineState, P as Plugin, e as SCRIM_PRESETS, f as ScrimOverlayOptions, g as ScrimOverlayPosition, h as ScrimPreset, i as ScrimPresetConfig, j as ScrimUpdate, d as SheetEventMap, k as SnapId, T as TeardownScope } from './BottomSheetEngine-CvSVbo6c.cjs';
+export { OVERLAY_PRESETS, Overlay, OverlayAnimation, OverlayCloseReason, OverlayEdge, Overlay as OverlayEngine, OverlayEventMap, OverlayMountTarget, OverlayOptions, OverlayPreset, OverlayState, OverlayUpdate, SwipeToCloseConfig, createOverlay } from './overlay.cjs';
+import './transform-Brkf-wzo.cjs';
+
+declare const easeOutBack: (t: number) => number;
+declare const easeOutCubic: (t: number) => number;
+type Tween = {
+    cancel: () => void;
+    promise: Promise<void>;
+};
+type TweenOptions = {
+    from: number;
+    to: number;
+    duration: number;
+    easing?: (t: number) => number;
+    onUpdate: (value: number) => void;
+};
+/**
+ * rAF tween. Promise resolves both on natural completion AND on cancel so
+ * callers awaiting it always settle; they're expected to cycle-nonce-check
+ * after the await before running post-settle effects.
+ */
+declare const tween: ({ from, to, duration, easing, onUpdate, }: TweenOptions) => Tween;
+declare const prefersReducedMotion: () => boolean;
+
+/**
+ * Damped harmonic oscillator: x'' = -k(x - target)/m - c*x'/m
+ * Integrated with semi-implicit Euler at variable dt; settles when both
+ * displacement and velocity drop below epsilon.
+ */
+type SpringConfig = {
+    stiffness: number;
+    damping: number;
+    mass: number;
+    /** Stop animation when |x - target| < restDelta AND |v| < restSpeed. */
+    restDelta?: number;
+    restSpeed?: number;
+};
+declare const DEFAULT_SPRING: SpringConfig;
+type SpringRunOptions = {
+    from: number;
+    to: number;
+    velocity?: number;
+    config?: Partial<SpringConfig>;
+    onUpdate: (value: number, velocity: number) => void;
+};
+type SpringHandle = {
+    cancel: () => void;
+    promise: Promise<void>;
+};
+/**
+ * Run a spring animation from `from` to `to` with initial velocity. The
+ * promise resolves on natural settle AND on cancel so awaiters always
+ * settle; callers cycle-nonce-check after the await before running
+ * post-settle effects.
+ */
+declare const runSpring: ({ from, to, velocity, config, onUpdate, }: SpringRunOptions) => SpringHandle;
+
+/**
+ * Resolve a `SnapPoint` to pixels.
+ *
+ *   number       → as-is
+ *   "full"       → viewport along the axis
+ *   "fit"        → measureFit() — handle/header offset
+ *   "30%"        → percent of viewport along axis (fast path)
+ *   any other    → CSS length resolved via probe element (dvh, vmin,
+ *                  clamp(), env(safe-area-inset-bottom), ...)
+ */
+declare const resolveSnap: (point: SnapPoint | string, mode: SheetMode, measureFit?: () => number) => number;
+
+type ResolvedSnap = {
+    id: string;
+    size: number;
+};
+declare const resolveSnapList: (points: SnapPointDef[], mode: SheetMode, measureFit?: () => number) => ResolvedSnap[];
+/**
+ * Finds the snap point closest to `size`, optionally biased by drag
+ * direction (positive = expanding) so flicks settle on the next-up snap
+ * even when geometrically closer to the previous one.
+ */
+declare const findNearest: (size: number, resolved: ResolvedSnap[], allowed: string[], direction?: 1 | -1 | 0, bias?: number) => ResolvedSnap | null;
+declare const allowedRange: (resolved: ResolvedSnap[], allowed: string[]) => {
+    min: number;
+    max: number;
+};
+declare const findById: (id: string, resolved: ResolvedSnap[]) => ResolvedSnap | null;
+
+type PointerKind = "touch" | "mouse" | "pen";
+type GestureCallbacks = {
+    onStart: (axisCoord: number, pointerType: PointerKind) => void;
+    onMove: (delta: number) => void;
+    onEnd: (delta: number, velocity: number, pointerType: PointerKind) => void;
+    onCancel?: () => void;
+};
+/**
+ * Pointer Events handler with velocity tracking. Listens on `handle` for the
+ * initial press, then captures the pointer so movement outside the element is
+ * still tracked. Multi-touch is ignored: only the first pointer drives the gesture.
+ *
+ * Velocity is computed from the last ~80ms of samples for stable flick detection.
+ */
+declare const installGestures: (handle: HTMLElement, mode: SheetMode, callbacks: GestureCallbacks) => (() => void);
+/**
+ * @deprecated Renamed to `installGestures` for naming consistency with the
+ * other `installX` feature factories. Will be removed in v2 — see
+ * `docs/migration-v2.md`.
+ */
+declare const attachGestures: (handle: HTMLElement, mode: SheetMode, callbacks: GestureCallbacks) => (() => void);
+
+/**
+ * Trap Tab focus inside `container`. Calls `onEscape` when Esc is pressed
+ * (caller decides whether to close the sheet). Returns a teardown function
+ * that releases the trap and restores focus to the previously-active element.
+ *
+ * SSR-safe: if `document` is unavailable, returns a no-op teardown.
+ */
+declare const installFocusTrap: (container: HTMLElement, options?: {
+    initialFocus?: HTMLElement | string;
+    onEscape?: () => void;
+}) => (() => void);
+
+declare const lockBodyScroll: () => (() => void);
+
+/**
+ * Multi-sheet z-index orchestration.
+ *
+ * When you have a sheet that itself opens another sheet (e.g. menu → detail),
+ * naive rendering stacks them at the same z-index and the second one is
+ * obscured. The stack assigns ascending z-indices and notifies the topmost
+ * sheet so it can render its backdrop while inner sheets skip theirs.
+ */
+type StackEntry = {
+    id: string;
+    setZIndex: (z: number) => void;
+    setIsTop: (isTop: boolean) => void;
+};
+declare class SheetStack {
+    private entries;
+    push(entry: StackEntry): () => void;
+    remove(id: string): void;
+    size(): number;
+    clear(): void;
+    private recompute;
+}
+/** Process-wide singleton so any adapter can reach the same stack. */
+declare const sheetStack: SheetStack;
+
+/**
+ * Route-based / context-based sheet config registry. Caller maps a key
+ * (route name, screen id, modal kind, anything) to a partial engine config;
+ * `manager.resolve(key)` returns the merged options ready to feed into
+ * `BottomSheetEngine` or any adapter.
+ *
+ * Lifecycle hooks (`onOpen`, `onClose`) are stored alongside the config so
+ * the consumer can attach them via `engine.on(...)` without ceremony.
+ *
+ *   const manager = createSheetManager({
+ *     home:   { snapPoints: [...], allowed: ["min","half","full"], onOpen: load },
+ *     marker: { snapPoints: [...], allowed: ["half","full"],       onOpen: focus },
+ *   });
+ *   manager.resolve("home"); // → { snapPoints, allowed, onOpen, onClose }
+ */
+type SheetConfig<Key extends string = string> = Partial<Omit<EngineOptions, "element" | "handle" | "scrollContainer" | "backdrop">> & {
+    /** Logical key (route name, modal kind, ...) — useful for telemetry. */
+    key?: Key;
+    onOpen?: (key: Key) => void;
+    onClose?: (key: Key) => void;
+};
+type SheetManager<Key extends string = string> = {
+    /** Register or replace a config. */
+    register(key: Key, config: SheetConfig<Key>): void;
+    /** Remove a registered config. */
+    unregister(key: Key): void;
+    /** Look up a config by key. Returns null if absent. */
+    resolve(key: Key): SheetConfig<Key> | null;
+    /** Get all registered keys. */
+    keys(): Key[];
+    /** Run `onClose(prev)` then `onOpen(next)` — for route transitions. */
+    transition(prev: Key | null, next: Key | null): void;
+};
+declare const createSheetManager: <Key extends string = string>(initial?: Record<Key, SheetConfig<Key>>) => SheetManager<Key>;
+
+export { DEFAULT_SPRING, EngineOptions, type ResolvedSnap, type SheetConfig, type SheetManager, SheetMode, SnapPoint, SnapPointDef, type SpringConfig, type SpringHandle, type SpringRunOptions, type StackEntry, type Tween, type TweenOptions, allowedRange, attachGestures, createSheetManager, easeOutBack, easeOutCubic, findById, findNearest, installFocusTrap, installGestures, lockBodyScroll, prefersReducedMotion, resolveSnap, resolveSnapList, runSpring, sheetStack, tween };

package/dist/index.d.ts

@@ -0,0 +1,184 @@
+import { c as SnapPoint, a as SheetMode, S as SnapPointDef, b as EngineOptions } from './BottomSheetEngine-DbO8rW_3.js';
+export { B as BottomSheetEngine, E as EngineState, P as Plugin, e as SCRIM_PRESETS, f as ScrimOverlayOptions, g as ScrimOverlayPosition, h as ScrimPreset, i as ScrimPresetConfig, j as ScrimUpdate, d as SheetEventMap, k as SnapId, T as TeardownScope } from './BottomSheetEngine-DbO8rW_3.js';
+export { OVERLAY_PRESETS, Overlay, OverlayAnimation, OverlayCloseReason, OverlayEdge, Overlay as OverlayEngine, OverlayEventMap, OverlayMountTarget, OverlayOptions, OverlayPreset, OverlayState, OverlayUpdate, SwipeToCloseConfig, createOverlay } from './overlay.js';
+import './transform-Brkf-wzo.js';
+
+declare const easeOutBack: (t: number) => number;
+declare const easeOutCubic: (t: number) => number;
+type Tween = {
+    cancel: () => void;
+    promise: Promise<void>;
+};
+type TweenOptions = {
+    from: number;
+    to: number;
+    duration: number;
+    easing?: (t: number) => number;
+    onUpdate: (value: number) => void;
+};
+/**
+ * rAF tween. Promise resolves both on natural completion AND on cancel so
+ * callers awaiting it always settle; they're expected to cycle-nonce-check
+ * after the await before running post-settle effects.
+ */
+declare const tween: ({ from, to, duration, easing, onUpdate, }: TweenOptions) => Tween;
+declare const prefersReducedMotion: () => boolean;
+
+/**
+ * Damped harmonic oscillator: x'' = -k(x - target)/m - c*x'/m
+ * Integrated with semi-implicit Euler at variable dt; settles when both
+ * displacement and velocity drop below epsilon.
+ */
+type SpringConfig = {
+    stiffness: number;
+    damping: number;
+    mass: number;
+    /** Stop animation when |x - target| < restDelta AND |v| < restSpeed. */
+    restDelta?: number;
+    restSpeed?: number;
+};
+declare const DEFAULT_SPRING: SpringConfig;
+type SpringRunOptions = {
+    from: number;
+    to: number;
+    velocity?: number;
+    config?: Partial<SpringConfig>;
+    onUpdate: (value: number, velocity: number) => void;
+};
+type SpringHandle = {
+    cancel: () => void;
+    promise: Promise<void>;
+};
+/**
+ * Run a spring animation from `from` to `to` with initial velocity. The
+ * promise resolves on natural settle AND on cancel so awaiters always
+ * settle; callers cycle-nonce-check after the await before running
+ * post-settle effects.
+ */
+declare const runSpring: ({ from, to, velocity, config, onUpdate, }: SpringRunOptions) => SpringHandle;
+
+/**
+ * Resolve a `SnapPoint` to pixels.
+ *
+ *   number       → as-is
+ *   "full"       → viewport along the axis
+ *   "fit"        → measureFit() — handle/header offset
+ *   "30%"        → percent of viewport along axis (fast path)
+ *   any other    → CSS length resolved via probe element (dvh, vmin,
+ *                  clamp(), env(safe-area-inset-bottom), ...)
+ */
+declare const resolveSnap: (point: SnapPoint | string, mode: SheetMode, measureFit?: () => number) => number;
+
+type ResolvedSnap = {
+    id: string;
+    size: number;
+};
+declare const resolveSnapList: (points: SnapPointDef[], mode: SheetMode, measureFit?: () => number) => ResolvedSnap[];
+/**
+ * Finds the snap point closest to `size`, optionally biased by drag
+ * direction (positive = expanding) so flicks settle on the next-up snap
+ * even when geometrically closer to the previous one.
+ */
+declare const findNearest: (size: number, resolved: ResolvedSnap[], allowed: string[], direction?: 1 | -1 | 0, bias?: number) => ResolvedSnap | null;
+declare const allowedRange: (resolved: ResolvedSnap[], allowed: string[]) => {
+    min: number;
+    max: number;
+};
+declare const findById: (id: string, resolved: ResolvedSnap[]) => ResolvedSnap | null;
+
+type PointerKind = "touch" | "mouse" | "pen";
+type GestureCallbacks = {
+    onStart: (axisCoord: number, pointerType: PointerKind) => void;
+    onMove: (delta: number) => void;
+    onEnd: (delta: number, velocity: number, pointerType: PointerKind) => void;
+    onCancel?: () => void;
+};
+/**
+ * Pointer Events handler with velocity tracking. Listens on `handle` for the
+ * initial press, then captures the pointer so movement outside the element is
+ * still tracked. Multi-touch is ignored: only the first pointer drives the gesture.
+ *
+ * Velocity is computed from the last ~80ms of samples for stable flick detection.
+ */
+declare const installGestures: (handle: HTMLElement, mode: SheetMode, callbacks: GestureCallbacks) => (() => void);
+/**
+ * @deprecated Renamed to `installGestures` for naming consistency with the
+ * other `installX` feature factories. Will be removed in v2 — see
+ * `docs/migration-v2.md`.
+ */
+declare const attachGestures: (handle: HTMLElement, mode: SheetMode, callbacks: GestureCallbacks) => (() => void);
+
+/**
+ * Trap Tab focus inside `container`. Calls `onEscape` when Esc is pressed
+ * (caller decides whether to close the sheet). Returns a teardown function
+ * that releases the trap and restores focus to the previously-active element.
+ *
+ * SSR-safe: if `document` is unavailable, returns a no-op teardown.
+ */
+declare const installFocusTrap: (container: HTMLElement, options?: {
+    initialFocus?: HTMLElement | string;
+    onEscape?: () => void;
+}) => (() => void);
+
+declare const lockBodyScroll: () => (() => void);
+
+/**
+ * Multi-sheet z-index orchestration.
+ *
+ * When you have a sheet that itself opens another sheet (e.g. menu → detail),
+ * naive rendering stacks them at the same z-index and the second one is
+ * obscured. The stack assigns ascending z-indices and notifies the topmost
+ * sheet so it can render its backdrop while inner sheets skip theirs.
+ */
+type StackEntry = {
+    id: string;
+    setZIndex: (z: number) => void;
+    setIsTop: (isTop: boolean) => void;
+};
+declare class SheetStack {
+    private entries;
+    push(entry: StackEntry): () => void;
+    remove(id: string): void;
+    size(): number;
+    clear(): void;
+    private recompute;
+}
+/** Process-wide singleton so any adapter can reach the same stack. */
+declare const sheetStack: SheetStack;
+
+/**
+ * Route-based / context-based sheet config registry. Caller maps a key
+ * (route name, screen id, modal kind, anything) to a partial engine config;
+ * `manager.resolve(key)` returns the merged options ready to feed into
+ * `BottomSheetEngine` or any adapter.
+ *
+ * Lifecycle hooks (`onOpen`, `onClose`) are stored alongside the config so
+ * the consumer can attach them via `engine.on(...)` without ceremony.
+ *
+ *   const manager = createSheetManager({
+ *     home:   { snapPoints: [...], allowed: ["min","half","full"], onOpen: load },
+ *     marker: { snapPoints: [...], allowed: ["half","full"],       onOpen: focus },
+ *   });
+ *   manager.resolve("home"); // → { snapPoints, allowed, onOpen, onClose }
+ */
+type SheetConfig<Key extends string = string> = Partial<Omit<EngineOptions, "element" | "handle" | "scrollContainer" | "backdrop">> & {
+    /** Logical key (route name, modal kind, ...) — useful for telemetry. */
+    key?: Key;
+    onOpen?: (key: Key) => void;
+    onClose?: (key: Key) => void;
+};
+type SheetManager<Key extends string = string> = {
+    /** Register or replace a config. */
+    register(key: Key, config: SheetConfig<Key>): void;
+    /** Remove a registered config. */
+    unregister(key: Key): void;
+    /** Look up a config by key. Returns null if absent. */
+    resolve(key: Key): SheetConfig<Key> | null;
+    /** Get all registered keys. */
+    keys(): Key[];
+    /** Run `onClose(prev)` then `onOpen(next)` — for route transitions. */
+    transition(prev: Key | null, next: Key | null): void;
+};
+declare const createSheetManager: <Key extends string = string>(initial?: Record<Key, SheetConfig<Key>>) => SheetManager<Key>;
+
+export { DEFAULT_SPRING, EngineOptions, type ResolvedSnap, type SheetConfig, type SheetManager, SheetMode, SnapPoint, SnapPointDef, type SpringConfig, type SpringHandle, type SpringRunOptions, type StackEntry, type Tween, type TweenOptions, allowedRange, attachGestures, createSheetManager, easeOutBack, easeOutCubic, findById, findNearest, installFocusTrap, installGestures, lockBodyScroll, prefersReducedMotion, resolveSnap, resolveSnapList, runSpring, sheetStack, tween };