@surdeddd/bottom-sheet 0.1.0 → 0.3.0

package/dist/react.d.cts

@@ -1,143 +1,79 @@
-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 { c as EngineOptions, E as EngineState, A as AnchorOptions, S as ScrimStagesOptions, p as ScrimStageDef, q as ScrimUpdate, m as ScrimOverlayOptions, B as BottomSheetEngine, a as SnapPointDef, b as SheetMode } from './BottomSheetEngine-CAymrH-P.cjs';
+export { d as SnapPoint } from './BottomSheetEngine-CAymrH-P.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';
+import './transform-jVfAikE9.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 EngineOptionsForProps = Omit<EngineOptions, "element" | "handle" | "scrollContainer" | "backdrop" | "scrim">;
 type HeaderProp = ReactNode | ((state: EngineState) => ReactNode);
+type BottomSheetAnchorProp = Omit<AnchorOptions, "element"> & {
+    node: ReactNode;
+};
+type BottomSheetScrimStageProp = Omit<ScrimStageDef, "element"> & {
+    node: ReactNode;
+};
+type BottomSheetScrimStagesProp = Omit<ScrimStagesOptions, "stages"> & {
+    stages: BottomSheetScrimStageProp[];
+};
 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. */
+    anchors?: BottomSheetAnchorProp[];
+    scrimStages?: BottomSheetScrimStagesProp;
     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;
+    setSnapPoints: (points: EngineOptions["snapPoints"], allowed?: string[]) => void;
+    setScrim: (opts: ScrimUpdate) => void;
+    setScrimOverlay: (opts: ScrimOverlayOptions) => () => void;
+    addAnchor: (opts: AnchorOptions) => () => void;
+    setScrimStages: (opts: ScrimStagesOptions | null) => () => void;
     state: EngineState & {
         activeId: TId;
     };
+    getEngine: () => BottomSheetEngine | null;
 };
-/**
- * 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. */
+    anchors?: BottomSheetAnchorProp[];
+    scrimStages?: BottomSheetScrimStagesProp;
     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>;
+    sheetRef: React.RefObject<HTMLElement | null>;
+    handleRef: React.RefObject<HTMLElement | null>;
+    contentRef: React.RefObject<HTMLElement | null>;
+    backdropRef: React.RefObject<HTMLElement | null>;
+    screenRef: React.RefObject<HTMLElement | null>;
 };
-/**
- * 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;
@@ -146,43 +82,21 @@ type UseBottomSheetReturn<TId extends string = string> = UseBottomSheetRefs & {
     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.
-     */
+    addAnchor: (opts: AnchorOptions) => () => void;
+    setScrimStages: (opts: ScrimStagesOptions | null) => () => void;
     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"> & {
+type HookOpts<TId extends string> = Omit<EngineOptions, "element" | "handle" | "scrollContainer" | "backdrop" | "scrim" | "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;
@@ -197,15 +111,8 @@ type OverlayHandle = {
     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. */
+declare const Overlay: react.ForwardRefExoticComponent<Omit<OverlayOptions, "backdrop" | "element"> & {
     open?: boolean;
-    /** Render the backdrop. Default: true. */
     backdrop?: boolean;
     className?: string;
     style?: CSSProperties;
@@ -216,52 +123,31 @@ declare const Overlay: react.ForwardRefExoticComponent<Omit<OverlayOptions, "ele
 } & react.RefAttributes<OverlayHandle>>;
 
 type UseOverlayReturn = {
-    panelRef: React.RefObject<HTMLElement>;
-    backdropRef: React.RefObject<HTMLElement>;
+    panelRef: React.RefObject<HTMLElement | null>;
+    backdropRef: React.RefObject<HTMLElement | null>;
     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;
@@ -269,11 +155,6 @@ type SheetConfig = {
         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;
@@ -288,12 +169,6 @@ type BottomSheetFromConfigProps = {
         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>>;

package/dist/react.d.ts

@@ -1,143 +1,79 @@
-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 { c as EngineOptions, E as EngineState, A as AnchorOptions, S as ScrimStagesOptions, p as ScrimStageDef, q as ScrimUpdate, m as ScrimOverlayOptions, B as BottomSheetEngine, a as SnapPointDef, b as SheetMode } from './BottomSheetEngine-DcqcuudN.js';
+export { d as SnapPoint } from './BottomSheetEngine-DcqcuudN.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';
+import './transform-jVfAikE9.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 EngineOptionsForProps = Omit<EngineOptions, "element" | "handle" | "scrollContainer" | "backdrop" | "scrim">;
 type HeaderProp = ReactNode | ((state: EngineState) => ReactNode);
+type BottomSheetAnchorProp = Omit<AnchorOptions, "element"> & {
+    node: ReactNode;
+};
+type BottomSheetScrimStageProp = Omit<ScrimStageDef, "element"> & {
+    node: ReactNode;
+};
+type BottomSheetScrimStagesProp = Omit<ScrimStagesOptions, "stages"> & {
+    stages: BottomSheetScrimStageProp[];
+};
 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. */
+    anchors?: BottomSheetAnchorProp[];
+    scrimStages?: BottomSheetScrimStagesProp;
     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;
+    setSnapPoints: (points: EngineOptions["snapPoints"], allowed?: string[]) => void;
+    setScrim: (opts: ScrimUpdate) => void;
+    setScrimOverlay: (opts: ScrimOverlayOptions) => () => void;
+    addAnchor: (opts: AnchorOptions) => () => void;
+    setScrimStages: (opts: ScrimStagesOptions | null) => () => void;
     state: EngineState & {
         activeId: TId;
     };
+    getEngine: () => BottomSheetEngine | null;
 };
-/**
- * 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. */
+    anchors?: BottomSheetAnchorProp[];
+    scrimStages?: BottomSheetScrimStagesProp;
     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>;
+    sheetRef: React.RefObject<HTMLElement | null>;
+    handleRef: React.RefObject<HTMLElement | null>;
+    contentRef: React.RefObject<HTMLElement | null>;
+    backdropRef: React.RefObject<HTMLElement | null>;
+    screenRef: React.RefObject<HTMLElement | null>;
 };
-/**
- * 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;
@@ -146,43 +82,21 @@ type UseBottomSheetReturn<TId extends string = string> = UseBottomSheetRefs & {
     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.
-     */
+    addAnchor: (opts: AnchorOptions) => () => void;
+    setScrimStages: (opts: ScrimStagesOptions | null) => () => void;
     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"> & {
+type HookOpts<TId extends string> = Omit<EngineOptions, "element" | "handle" | "scrollContainer" | "backdrop" | "scrim" | "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;
@@ -197,15 +111,8 @@ type OverlayHandle = {
     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. */
+declare const Overlay: react.ForwardRefExoticComponent<Omit<OverlayOptions, "backdrop" | "element"> & {
     open?: boolean;
-    /** Render the backdrop. Default: true. */
     backdrop?: boolean;
     className?: string;
     style?: CSSProperties;
@@ -216,52 +123,31 @@ declare const Overlay: react.ForwardRefExoticComponent<Omit<OverlayOptions, "ele
 } & react.RefAttributes<OverlayHandle>>;
 
 type UseOverlayReturn = {
-    panelRef: React.RefObject<HTMLElement>;
-    backdropRef: React.RefObject<HTMLElement>;
+    panelRef: React.RefObject<HTMLElement | null>;
+    backdropRef: React.RefObject<HTMLElement | null>;
     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;
@@ -269,11 +155,6 @@ type SheetConfig = {
         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;
@@ -288,12 +169,6 @@ type BottomSheetFromConfigProps = {
         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>>;