@surdeddd/bottom-sheet 0.1.0

package/dist/react.d.cts

@@ -0,0 +1,301 @@
+import { b as EngineOptions, E as EngineState, B as BottomSheetEngine, S as SnapPointDef, a as SheetMode } from './BottomSheetEngine-CvSVbo6c.cjs';
+export { c as SnapPoint } from './BottomSheetEngine-CvSVbo6c.cjs';
+import { OverlayOptions, OverlayState, Overlay as OverlayEngine } from './overlay.cjs';
+export { OverlayEdge } from './overlay.cjs';
+import * as react from 'react';
+import { CSSProperties, ReactNode } from 'react';
+import './transform-Brkf-wzo.cjs';
+
+type EngineOptionsForProps = Omit<EngineOptions, "element" | "handle" | "scrollContainer" | "backdrop" | "screenComponent">;
+/**
+ * Header content for the sheet. Two forms are supported:
+ *   - **Static node**: `header={<h2>Title</h2>}` — rendered once and never
+ *     updated when the active snap changes.
+ *   - **Render function**: `header={state => <h2>{state.activeId}</h2>}` —
+ *     called on every settled snap change with the current `EngineState`,
+ *     so the header can morph per snap (e.g. minimized header vs full
+ *     header). The function fires from the same `useSyncExternalStore`
+ *     subscription that drives the rest of the component, so identity is
+ *     stable between snaps and only re-renders on transitions.
+ */
+type HeaderProp = ReactNode | ((state: EngineState) => ReactNode);
+type BottomSheetProps = EngineOptionsForProps & {
+    /** Render the dimmed overlay behind the sheet. Default: true. */
+    backdrop?: boolean;
+    /** Close when the backdrop is clicked. Default: true. */
+    closeOnBackdrop?: boolean;
+    /** Optional className appended to the root sheet element. */
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * Header content (above the scrollable content; doubles as drag handle
+     * area). Accepts either a static `ReactNode` or a function
+     * `(state: EngineState) => ReactNode` that re-renders on every snap
+     * transition — letting consumers show different markup per snap state
+     * (e.g. minimized vs half vs full).
+     */
+    header?: HeaderProp;
+    /** Children become the scrollable content area. */
+    children?: ReactNode;
+    /** Slot above the sheet, anchored to the left. */
+    leftButton?: ReactNode;
+    /** Slot above the sheet, anchored to the right. */
+    rightButton?: ReactNode;
+    /** Element rendered behind the sheet, fading in with progress. */
+    screen?: ReactNode;
+    /** Fired whenever active snap changes. */
+    onChange?: (state: EngineState) => void;
+    /** Visually hidden label for screen readers. */
+    ariaLabel?: string;
+    /** ID of an existing heading element inside the sheet (preferred over ariaLabel). */
+    ariaLabelledBy?: string;
+    /** Skip rendering on the server to avoid hydration mismatches. Default: false. */
+    noSSR?: boolean;
+};
+/**
+ * Imperative handle returned by `<BottomSheet ref={…}>`.
+ *
+ * Opt-in literal-id typing — pass a string-literal union as `TId` to get
+ * compile-time errors on typos:
+ *
+ * ```ts
+ * // Default (back-compat): TId = string, anything goes
+ * const ref = useRef<BottomSheetHandle>(null);
+ * ref.current?.snapTo("anything"); // ✓ compiles, fails silently at runtime
+ *
+ * // Opt-in: typo-safe
+ * const ref = useRef<BottomSheetHandle<"min" | "half" | "full">>(null);
+ * ref.current?.snapTo("haf");   // ❌ TS2345
+ * ref.current?.snapTo("half");  // ✓
+ * ```
+ *
+ * `TId` defaults to `string` so existing call sites compile unchanged.
+ * The underlying engine stays `string`-typed; the literal narrowing is a
+ * TS-only convenience layered on top of the runtime.
+ */
+type BottomSheetHandle<TId extends string = string> = {
+    snapTo: (id: TId) => Promise<void>;
+    open: (id?: TId) => Promise<void>;
+    close: () => Promise<void>;
+    setAllowed: (ids: TId[], snap?: TId) => void;
+    state: EngineState & {
+        activeId: TId;
+    };
+};
+/**
+ * React component built on the headless engine. For full control, use
+ * `useBottomSheet` directly and assemble your own JSX.
+ */
+declare const BottomSheet: react.ForwardRefExoticComponent<EngineOptionsForProps & {
+    /** Render the dimmed overlay behind the sheet. Default: true. */
+    backdrop?: boolean;
+    /** Close when the backdrop is clicked. Default: true. */
+    closeOnBackdrop?: boolean;
+    /** Optional className appended to the root sheet element. */
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * Header content (above the scrollable content; doubles as drag handle
+     * area). Accepts either a static `ReactNode` or a function
+     * `(state: EngineState) => ReactNode` that re-renders on every snap
+     * transition — letting consumers show different markup per snap state
+     * (e.g. minimized vs half vs full).
+     */
+    header?: HeaderProp;
+    /** Children become the scrollable content area. */
+    children?: ReactNode;
+    /** Slot above the sheet, anchored to the left. */
+    leftButton?: ReactNode;
+    /** Slot above the sheet, anchored to the right. */
+    rightButton?: ReactNode;
+    /** Element rendered behind the sheet, fading in with progress. */
+    screen?: ReactNode;
+    /** Fired whenever active snap changes. */
+    onChange?: (state: EngineState) => void;
+    /** Visually hidden label for screen readers. */
+    ariaLabel?: string;
+    /** ID of an existing heading element inside the sheet (preferred over ariaLabel). */
+    ariaLabelledBy?: string;
+    /** Skip rendering on the server to avoid hydration mismatches. Default: false. */
+    noSSR?: boolean;
+} & react.RefAttributes<BottomSheetHandle<string>>>;
+
+type UseBottomSheetRefs = {
+    sheetRef: React.RefObject<HTMLElement>;
+    handleRef: React.RefObject<HTMLElement>;
+    contentRef: React.RefObject<HTMLElement>;
+    backdropRef: React.RefObject<HTMLElement>;
+    screenRef: React.RefObject<HTMLElement>;
+};
+/**
+ * Return shape of `useBottomSheet`. Optionally narrows to a literal-id union
+ * `TId` when the consumer explicitly types the call site:
+ *
+ * ```ts
+ * const sheet = useBottomSheet<"min" | "full">({ snapPoints: [...] });
+ * sheet.snapTo("min"); // ✓
+ * ```
+ *
+ * Without an explicit type argument `TId` defaults to `string`.
+ */
+type UseBottomSheetReturn<TId extends string = string> = UseBottomSheetRefs & {
+    state: EngineState & {
+        activeId: TId;
+    };
+    snapTo: (id: TId) => Promise<void>;
+    open: (id?: TId) => Promise<void>;
+    close: () => Promise<void>;
+    setAllowed: (ids: TId[], snap?: TId) => void;
+    /**
+     * @deprecated React Strict Mode double-invokes the layout effect — the
+     * effect tears down (engineRef.current = null), the next render reads
+     * this field as `null` for one frame, and only the second mount restores
+     * a live engine. Consumers calling methods through this field during that
+     * window get `null`. Use `getEngine()` instead — it lazy-reads the live
+     * ref and is safe across Strict Mode and across resize/setSnapPoints
+     * paths that don't fire React-tracked events. Will be removed in v2.
+     */
+    engine: BottomSheetEngine | null;
+    /** Lazy accessor — always reads the live engine, even after external
+     * mutations (resize, setSnapPoints) that don't fire React-tracked events.
+     * Strict-Mode-safe: returns the current ref at call time, not a stale
+     * snapshot from the last commit. */
+    getEngine: () => BottomSheetEngine | null;
+};
+/**
+ * Headless React hook. Wires the engine to refs and subscribes to its events
+ * via `useSyncExternalStore` for tear-free state in concurrent mode.
+ *
+ * The snapshot is cached in a ref and only refreshed when a notify fires,
+ * so React's identity check doesn't trigger an infinite loop (the engine's
+ * `state` getter constructs a fresh object every call).
+ */
+type HookOpts<TId extends string> = Omit<EngineOptions, "element" | "handle" | "scrollContainer" | "backdrop" | "screenComponent" | "snapPoints" | "allowed" | "initial"> & {
+    snapPoints: SnapPointDef<TId>[] | ReadonlyArray<SnapPointDef<TId>>;
+    allowed?: TId[] | ReadonlyArray<TId>;
+    initial?: TId;
+    /** Called after a snap commit settles. Mirrors the engine's `snap` event. */
+    onSnap?: (id: TId) => void;
+};
+declare function useBottomSheet<TId extends string = string>(opts: HookOpts<TId>): UseBottomSheetReturn<TId>;
+
+type OverlayProps = Omit<OverlayOptions, "element" | "backdrop"> & {
+    /** Controlled open state. If omitted, the overlay is uncontrolled. */
+    open?: boolean;
+    /** Render the backdrop. Default: true. */
+    backdrop?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+    ariaLabel?: string;
+    ariaLabelledBy?: string;
+    onChange?: (state: OverlayState) => void;
+};
+type OverlayHandle = {
+    open: () => Promise<void>;
+    close: () => Promise<void>;
+    toggle: () => Promise<void>;
+    state: OverlayState;
+};
+/**
+ * Bottom-anchored slide-up overlay panel. Distinct from `<BottomSheet>`:
+ * no drag, no snap points, single binary state. CSS-transition animated
+ * (no spring) — lighter weight, predictable timing.
+ */
+declare const Overlay: react.ForwardRefExoticComponent<Omit<OverlayOptions, "element" | "backdrop"> & {
+    /** Controlled open state. If omitted, the overlay is uncontrolled. */
+    open?: boolean;
+    /** Render the backdrop. Default: true. */
+    backdrop?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+    ariaLabel?: string;
+    ariaLabelledBy?: string;
+    onChange?: (state: OverlayState) => void;
+} & react.RefAttributes<OverlayHandle>>;
+
+type UseOverlayReturn = {
+    panelRef: React.RefObject<HTMLElement>;
+    backdropRef: React.RefObject<HTMLElement>;
+    state: OverlayState;
+    open: () => Promise<void>;
+    close: () => Promise<void>;
+    toggle: () => Promise<void>;
+    /**
+     * Lazy accessor for the underlying engine. Returns null on SSR or before
+     * the layout effect mounts the engine. Use this — not a snapshot — so you
+     * always read the current instance.
+     */
+    getEngine: () => OverlayEngine | null;
+};
+declare const useOverlay: (opts: Omit<OverlayOptions, "element" | "backdrop">) => UseOverlayReturn;
+
+/**
+ * JSON-serializable sheet configuration for CMS-driven / A-B / plugin /
+ * server-driven UI. Functions can't be JSON, so handlers live in the
+ * sibling `eventHandlers` prop keyed by `events.{onSnap,onOpen,onClose}`.
+ *
+ * Treat configs as immutable — derived props are memoized by config
+ * identity, mutating in place leaves stale snap geometry behind.
+ */
+type SheetConfig = {
+    /** Schema version. Must be `1` for the current wrapper. */
+    version: 1;
+    /** Ordered list of snap points (smallest → largest). Required. */
+    snapPoints: Array<{
+        id: string;
+        size: number | string;
+    }>;
+    /** Initial snap id. Falls back to first allowed (or first overall). */
+    initial?: string;
+    /** Subset of snap-point ids the sheet may settle on right now. */
+    allowed?: string[];
+    /** Direction the sheet expands from. Default: "bottom". */
+    mode?: SheetMode;
+    /** Animation strategy. Default: "spring". */
+    animation?: "spring" | "tween";
+    /** Spring config when `animation: "spring"`. */
+    spring?: {
+        stiffness?: number;
+        damping?: number;
+        mass?: number;
+    };
+    /** Behavior toggles. All optional; missing keys fall back to engine defaults. */
+    behavior?: {
+        focusTrap?: boolean;
+        closeOnEscape?: boolean;
+        closeOnBackdrop?: boolean;
+        lockBodyScroll?: boolean;
+        rubberBand?: boolean;
+    };
+    /**
+     * Map event name → handler key. The actual functions live in the
+     * `eventHandlers` prop on the wrapper component, keyed by the same
+     * string. Missing handler keys are tolerated (warn + no-op).
+     */
+    events?: {
+        onSnap?: string;
+        onOpen?: string;
+        onClose?: string;
+    };
+};
+type SheetEventHandler = ((id: string) => void) | (() => void);
+type BottomSheetFromConfigProps = {
+    config: SheetConfig;
+    eventHandlers?: Record<string, SheetEventHandler>;
+    slotContent?: {
+        header?: ReactNode;
+        body?: ReactNode;
+    };
+    /**
+     * Memoize derived props by content (JSON.stringify) instead of identity.
+     * Set when fetching via SWR / TanStack Query / RSC loaders that hand back
+     * a fresh object on every cache hit — prevents engine rebuilds on byte-
+     * identical revalidations. Default false keeps the cheap identity path.
+     */
+    stableContent?: boolean;
+};
+declare const BottomSheetFromConfig: react.ForwardRefExoticComponent<BottomSheetFromConfigProps & react.RefAttributes<BottomSheetHandle>>;
+
+export { BottomSheet, BottomSheetFromConfig, type BottomSheetFromConfigProps, type BottomSheetHandle, type BottomSheetProps, EngineState, type HeaderProp, Overlay, type OverlayHandle, OverlayOptions, type OverlayProps, OverlayState, type SheetConfig, SheetMode, SnapPointDef, type UseBottomSheetRefs, type UseBottomSheetReturn, type UseOverlayReturn, useBottomSheet, useOverlay };

package/dist/react.d.ts

@@ -0,0 +1,301 @@
+import { b as EngineOptions, E as EngineState, B as BottomSheetEngine, S as SnapPointDef, a as SheetMode } from './BottomSheetEngine-DbO8rW_3.js';
+export { c as SnapPoint } from './BottomSheetEngine-DbO8rW_3.js';
+import { OverlayOptions, OverlayState, Overlay as OverlayEngine } from './overlay.js';
+export { OverlayEdge } from './overlay.js';
+import * as react from 'react';
+import { CSSProperties, ReactNode } from 'react';
+import './transform-Brkf-wzo.js';
+
+type EngineOptionsForProps = Omit<EngineOptions, "element" | "handle" | "scrollContainer" | "backdrop" | "screenComponent">;
+/**
+ * Header content for the sheet. Two forms are supported:
+ *   - **Static node**: `header={<h2>Title</h2>}` — rendered once and never
+ *     updated when the active snap changes.
+ *   - **Render function**: `header={state => <h2>{state.activeId}</h2>}` —
+ *     called on every settled snap change with the current `EngineState`,
+ *     so the header can morph per snap (e.g. minimized header vs full
+ *     header). The function fires from the same `useSyncExternalStore`
+ *     subscription that drives the rest of the component, so identity is
+ *     stable between snaps and only re-renders on transitions.
+ */
+type HeaderProp = ReactNode | ((state: EngineState) => ReactNode);
+type BottomSheetProps = EngineOptionsForProps & {
+    /** Render the dimmed overlay behind the sheet. Default: true. */
+    backdrop?: boolean;
+    /** Close when the backdrop is clicked. Default: true. */
+    closeOnBackdrop?: boolean;
+    /** Optional className appended to the root sheet element. */
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * Header content (above the scrollable content; doubles as drag handle
+     * area). Accepts either a static `ReactNode` or a function
+     * `(state: EngineState) => ReactNode` that re-renders on every snap
+     * transition — letting consumers show different markup per snap state
+     * (e.g. minimized vs half vs full).
+     */
+    header?: HeaderProp;
+    /** Children become the scrollable content area. */
+    children?: ReactNode;
+    /** Slot above the sheet, anchored to the left. */
+    leftButton?: ReactNode;
+    /** Slot above the sheet, anchored to the right. */
+    rightButton?: ReactNode;
+    /** Element rendered behind the sheet, fading in with progress. */
+    screen?: ReactNode;
+    /** Fired whenever active snap changes. */
+    onChange?: (state: EngineState) => void;
+    /** Visually hidden label for screen readers. */
+    ariaLabel?: string;
+    /** ID of an existing heading element inside the sheet (preferred over ariaLabel). */
+    ariaLabelledBy?: string;
+    /** Skip rendering on the server to avoid hydration mismatches. Default: false. */
+    noSSR?: boolean;
+};
+/**
+ * Imperative handle returned by `<BottomSheet ref={…}>`.
+ *
+ * Opt-in literal-id typing — pass a string-literal union as `TId` to get
+ * compile-time errors on typos:
+ *
+ * ```ts
+ * // Default (back-compat): TId = string, anything goes
+ * const ref = useRef<BottomSheetHandle>(null);
+ * ref.current?.snapTo("anything"); // ✓ compiles, fails silently at runtime
+ *
+ * // Opt-in: typo-safe
+ * const ref = useRef<BottomSheetHandle<"min" | "half" | "full">>(null);
+ * ref.current?.snapTo("haf");   // ❌ TS2345
+ * ref.current?.snapTo("half");  // ✓
+ * ```
+ *
+ * `TId` defaults to `string` so existing call sites compile unchanged.
+ * The underlying engine stays `string`-typed; the literal narrowing is a
+ * TS-only convenience layered on top of the runtime.
+ */
+type BottomSheetHandle<TId extends string = string> = {
+    snapTo: (id: TId) => Promise<void>;
+    open: (id?: TId) => Promise<void>;
+    close: () => Promise<void>;
+    setAllowed: (ids: TId[], snap?: TId) => void;
+    state: EngineState & {
+        activeId: TId;
+    };
+};
+/**
+ * React component built on the headless engine. For full control, use
+ * `useBottomSheet` directly and assemble your own JSX.
+ */
+declare const BottomSheet: react.ForwardRefExoticComponent<EngineOptionsForProps & {
+    /** Render the dimmed overlay behind the sheet. Default: true. */
+    backdrop?: boolean;
+    /** Close when the backdrop is clicked. Default: true. */
+    closeOnBackdrop?: boolean;
+    /** Optional className appended to the root sheet element. */
+    className?: string;
+    style?: CSSProperties;
+    /**
+     * Header content (above the scrollable content; doubles as drag handle
+     * area). Accepts either a static `ReactNode` or a function
+     * `(state: EngineState) => ReactNode` that re-renders on every snap
+     * transition — letting consumers show different markup per snap state
+     * (e.g. minimized vs half vs full).
+     */
+    header?: HeaderProp;
+    /** Children become the scrollable content area. */
+    children?: ReactNode;
+    /** Slot above the sheet, anchored to the left. */
+    leftButton?: ReactNode;
+    /** Slot above the sheet, anchored to the right. */
+    rightButton?: ReactNode;
+    /** Element rendered behind the sheet, fading in with progress. */
+    screen?: ReactNode;
+    /** Fired whenever active snap changes. */
+    onChange?: (state: EngineState) => void;
+    /** Visually hidden label for screen readers. */
+    ariaLabel?: string;
+    /** ID of an existing heading element inside the sheet (preferred over ariaLabel). */
+    ariaLabelledBy?: string;
+    /** Skip rendering on the server to avoid hydration mismatches. Default: false. */
+    noSSR?: boolean;
+} & react.RefAttributes<BottomSheetHandle<string>>>;
+
+type UseBottomSheetRefs = {
+    sheetRef: React.RefObject<HTMLElement>;
+    handleRef: React.RefObject<HTMLElement>;
+    contentRef: React.RefObject<HTMLElement>;
+    backdropRef: React.RefObject<HTMLElement>;
+    screenRef: React.RefObject<HTMLElement>;
+};
+/**
+ * Return shape of `useBottomSheet`. Optionally narrows to a literal-id union
+ * `TId` when the consumer explicitly types the call site:
+ *
+ * ```ts
+ * const sheet = useBottomSheet<"min" | "full">({ snapPoints: [...] });
+ * sheet.snapTo("min"); // ✓
+ * ```
+ *
+ * Without an explicit type argument `TId` defaults to `string`.
+ */
+type UseBottomSheetReturn<TId extends string = string> = UseBottomSheetRefs & {
+    state: EngineState & {
+        activeId: TId;
+    };
+    snapTo: (id: TId) => Promise<void>;
+    open: (id?: TId) => Promise<void>;
+    close: () => Promise<void>;
+    setAllowed: (ids: TId[], snap?: TId) => void;
+    /**
+     * @deprecated React Strict Mode double-invokes the layout effect — the
+     * effect tears down (engineRef.current = null), the next render reads
+     * this field as `null` for one frame, and only the second mount restores
+     * a live engine. Consumers calling methods through this field during that
+     * window get `null`. Use `getEngine()` instead — it lazy-reads the live
+     * ref and is safe across Strict Mode and across resize/setSnapPoints
+     * paths that don't fire React-tracked events. Will be removed in v2.
+     */
+    engine: BottomSheetEngine | null;
+    /** Lazy accessor — always reads the live engine, even after external
+     * mutations (resize, setSnapPoints) that don't fire React-tracked events.
+     * Strict-Mode-safe: returns the current ref at call time, not a stale
+     * snapshot from the last commit. */
+    getEngine: () => BottomSheetEngine | null;
+};
+/**
+ * Headless React hook. Wires the engine to refs and subscribes to its events
+ * via `useSyncExternalStore` for tear-free state in concurrent mode.
+ *
+ * The snapshot is cached in a ref and only refreshed when a notify fires,
+ * so React's identity check doesn't trigger an infinite loop (the engine's
+ * `state` getter constructs a fresh object every call).
+ */
+type HookOpts<TId extends string> = Omit<EngineOptions, "element" | "handle" | "scrollContainer" | "backdrop" | "screenComponent" | "snapPoints" | "allowed" | "initial"> & {
+    snapPoints: SnapPointDef<TId>[] | ReadonlyArray<SnapPointDef<TId>>;
+    allowed?: TId[] | ReadonlyArray<TId>;
+    initial?: TId;
+    /** Called after a snap commit settles. Mirrors the engine's `snap` event. */
+    onSnap?: (id: TId) => void;
+};
+declare function useBottomSheet<TId extends string = string>(opts: HookOpts<TId>): UseBottomSheetReturn<TId>;
+
+type OverlayProps = Omit<OverlayOptions, "element" | "backdrop"> & {
+    /** Controlled open state. If omitted, the overlay is uncontrolled. */
+    open?: boolean;
+    /** Render the backdrop. Default: true. */
+    backdrop?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+    ariaLabel?: string;
+    ariaLabelledBy?: string;
+    onChange?: (state: OverlayState) => void;
+};
+type OverlayHandle = {
+    open: () => Promise<void>;
+    close: () => Promise<void>;
+    toggle: () => Promise<void>;
+    state: OverlayState;
+};
+/**
+ * Bottom-anchored slide-up overlay panel. Distinct from `<BottomSheet>`:
+ * no drag, no snap points, single binary state. CSS-transition animated
+ * (no spring) — lighter weight, predictable timing.
+ */
+declare const Overlay: react.ForwardRefExoticComponent<Omit<OverlayOptions, "element" | "backdrop"> & {
+    /** Controlled open state. If omitted, the overlay is uncontrolled. */
+    open?: boolean;
+    /** Render the backdrop. Default: true. */
+    backdrop?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+    ariaLabel?: string;
+    ariaLabelledBy?: string;
+    onChange?: (state: OverlayState) => void;
+} & react.RefAttributes<OverlayHandle>>;
+
+type UseOverlayReturn = {
+    panelRef: React.RefObject<HTMLElement>;
+    backdropRef: React.RefObject<HTMLElement>;
+    state: OverlayState;
+    open: () => Promise<void>;
+    close: () => Promise<void>;
+    toggle: () => Promise<void>;
+    /**
+     * Lazy accessor for the underlying engine. Returns null on SSR or before
+     * the layout effect mounts the engine. Use this — not a snapshot — so you
+     * always read the current instance.
+     */
+    getEngine: () => OverlayEngine | null;
+};
+declare const useOverlay: (opts: Omit<OverlayOptions, "element" | "backdrop">) => UseOverlayReturn;
+
+/**
+ * JSON-serializable sheet configuration for CMS-driven / A-B / plugin /
+ * server-driven UI. Functions can't be JSON, so handlers live in the
+ * sibling `eventHandlers` prop keyed by `events.{onSnap,onOpen,onClose}`.
+ *
+ * Treat configs as immutable — derived props are memoized by config
+ * identity, mutating in place leaves stale snap geometry behind.
+ */
+type SheetConfig = {
+    /** Schema version. Must be `1` for the current wrapper. */
+    version: 1;
+    /** Ordered list of snap points (smallest → largest). Required. */
+    snapPoints: Array<{
+        id: string;
+        size: number | string;
+    }>;
+    /** Initial snap id. Falls back to first allowed (or first overall). */
+    initial?: string;
+    /** Subset of snap-point ids the sheet may settle on right now. */
+    allowed?: string[];
+    /** Direction the sheet expands from. Default: "bottom". */
+    mode?: SheetMode;
+    /** Animation strategy. Default: "spring". */
+    animation?: "spring" | "tween";
+    /** Spring config when `animation: "spring"`. */
+    spring?: {
+        stiffness?: number;
+        damping?: number;
+        mass?: number;
+    };
+    /** Behavior toggles. All optional; missing keys fall back to engine defaults. */
+    behavior?: {
+        focusTrap?: boolean;
+        closeOnEscape?: boolean;
+        closeOnBackdrop?: boolean;
+        lockBodyScroll?: boolean;
+        rubberBand?: boolean;
+    };
+    /**
+     * Map event name → handler key. The actual functions live in the
+     * `eventHandlers` prop on the wrapper component, keyed by the same
+     * string. Missing handler keys are tolerated (warn + no-op).
+     */
+    events?: {
+        onSnap?: string;
+        onOpen?: string;
+        onClose?: string;
+    };
+};
+type SheetEventHandler = ((id: string) => void) | (() => void);
+type BottomSheetFromConfigProps = {
+    config: SheetConfig;
+    eventHandlers?: Record<string, SheetEventHandler>;
+    slotContent?: {
+        header?: ReactNode;
+        body?: ReactNode;
+    };
+    /**
+     * Memoize derived props by content (JSON.stringify) instead of identity.
+     * Set when fetching via SWR / TanStack Query / RSC loaders that hand back
+     * a fresh object on every cache hit — prevents engine rebuilds on byte-
+     * identical revalidations. Default false keeps the cheap identity path.
+     */
+    stableContent?: boolean;
+};
+declare const BottomSheetFromConfig: react.ForwardRefExoticComponent<BottomSheetFromConfigProps & react.RefAttributes<BottomSheetHandle>>;
+
+export { BottomSheet, BottomSheetFromConfig, type BottomSheetFromConfigProps, type BottomSheetHandle, type BottomSheetProps, EngineState, type HeaderProp, Overlay, type OverlayHandle, OverlayOptions, type OverlayProps, OverlayState, type SheetConfig, SheetMode, SnapPointDef, type UseBottomSheetRefs, type UseBottomSheetReturn, type UseOverlayReturn, useBottomSheet, useOverlay };