@surdeddd/bottom-sheet 0.1.0

package/dist/overlay.d.cts

@@ -0,0 +1,282 @@
+import { T as TransformAxis } from './transform-Brkf-wzo.cjs';
+
+/**
+ * Slide-up panel without gestures. CSS-transition-driven, single-state.
+ * Distinct from `BottomSheetEngine`, which is gesture-driven and multi-snap.
+ *
+ * Shares scroll-lock / focus-trap / sheet-stack / inert-siblings / transform
+ * primitives with the engine so z-indices orchestrate automatically when
+ * sheets and overlays mix and feature behaviour stays consistent.
+ */
+type OverlayEdge = TransformAxis;
+type OverlayAnimation = "slide" | "fade" | "scale";
+type OverlayCloseReason = "escape" | "backdrop" | "swipe" | "back" | "programmatic" | "outside-pointer";
+type SwipeToCloseConfig = {
+    enabled?: boolean;
+    threshold?: number;
+    velocityThreshold?: number;
+};
+type OverlayMountTarget = HTMLElement | "body" | "parent";
+/**
+ * Named overlay archetypes — bundle the common animation + dim + gesture
+ * combinations so consumers can opt into a "mode" without restating every
+ * field. Applied BEFORE individual options at construction, and as the
+ * first step of `setOverlay()` so individual overrides win.
+ */
+type OverlayPreset = "sheet" | "dialog" | "sidebar" | "toast";
+type OverlayPresetConfig = {
+    enterAnimation: OverlayAnimation;
+    exitAnimation: OverlayAnimation;
+    backdropOpacity: number;
+    backdropFilter?: string;
+    swipeToClose: boolean | SwipeToCloseConfig;
+};
+declare const OVERLAY_PRESETS: Readonly<Record<OverlayPreset, Readonly<OverlayPresetConfig>>>;
+/**
+ * Batch payload for `setOverlay()`. `null` on `backdropFilter` clears it
+ * (distinct from `undefined` which means "leave as-is" in the diff). Apply
+ * order: preset first, then individual overrides — single DOM-write phase
+ * if the overlay is currently open.
+ */
+type OverlayUpdate = {
+    backdropOpacity?: number;
+    backdropFilter?: string | null;
+    swipeToClose?: boolean | SwipeToCloseConfig;
+    enterAnimation?: OverlayAnimation;
+    exitAnimation?: OverlayAnimation;
+    preset?: OverlayPreset;
+    /**
+     * Runtime children swap. `null` clears the panel's contents. A function is
+     * called once to lazy-resolve dynamic content. Applied LAST in the batch so
+     * style mutations finish before the DOM swap.
+     */
+    children?: HTMLElement | DocumentFragment | (() => HTMLElement | DocumentFragment) | null;
+};
+type OverlayOptions = {
+    /** The panel element — gets transform/opacity inline writes. */
+    element: HTMLElement;
+    /** Optional dimmed backdrop element. */
+    backdrop?: HTMLElement;
+    /** Edge the panel slides in from. Default: "bottom". */
+    edge?: OverlayEdge;
+    /** Open immediately on construction. Default: false. */
+    initialOpen?: boolean;
+    /** Listen for Escape key. Default: true. */
+    closeOnEscape?: boolean;
+    /** Tap on backdrop closes. Default: true. */
+    closeOnBackdrop?: boolean;
+    /** Trap Tab focus inside the panel. Default: true. */
+    focusTrap?: boolean;
+    /** Selector or HTMLElement focused on open. */
+    initialFocus?: string | HTMLElement;
+    /**
+     * Element to focus after close. By default the focus trap restores
+     * whatever was focused before open. Pass an element or a getter for
+     * explicit control (e.g. focus a status banner instead of the trigger).
+     */
+    returnFocus?: HTMLElement | (() => HTMLElement | null);
+    /** Lock body scroll while open. Default: true. */
+    lockBodyScroll?: boolean;
+    /** Mark page siblings `inert` while open (full a11y modal). Default: false. */
+    inertSiblings?: boolean;
+    /** Push history state so Android back closes the overlay. Default: false. */
+    closeOnBack?: boolean;
+    /** Animation duration in ms. Default: 320. */
+    duration?: number;
+    /** CSS easing for the slide-in. Default matches monitoring's bezier. */
+    enterEasing?: string;
+    /** CSS easing for the slide-out. Default: ease-in. */
+    exitEasing?: string;
+    /**
+     * Peak backdrop opacity when open. Useful when `backdropFilter` blur
+     * already darkens enough and the dim should be light (e.g. 0.3).
+     * Default: 1.
+     */
+    backdropOpacity?: number;
+    /**
+     * CSS `backdrop-filter` value applied to the backdrop while open
+     * (e.g. `"blur(8px)"`, `"blur(12px) saturate(140%)"`). Cleared on close.
+     */
+    backdropFilter?: string;
+    /**
+     * Allow drag-to-dismiss along the entry edge — pointer-driven. The panel
+     * follows the finger past the closed-edge axis and dismisses if the user
+     * crosses 30% of the panel size or releases with > 0.5 px/ms velocity.
+     *
+     * Pass a config object to tune thresholds:
+     *   `{ enabled: true, threshold: 0.5, velocityThreshold: 1.0 }`.
+     * Default: false (CSS-only transition).
+     */
+    swipeToClose?: boolean | SwipeToCloseConfig;
+    /**
+     * Entry animation. `"slide"` (default) translates from the edge.
+     * `"fade"` is opacity-only (no transform). `"scale"` fades + scales
+     * from 0.94 — best for centred dialogs.
+     */
+    enterAnimation?: OverlayAnimation;
+    /** Exit animation. Defaults to `enterAnimation`. */
+    exitAnimation?: OverlayAnimation;
+    /**
+     * Move `element` to a different container on first open. `'parent'`
+     * (default) leaves it in place. `'body'` appends to `document.body`.
+     * Pass an explicit `HTMLElement` for any other portal target.
+     *
+     * Restored to its original parent on `destroy()`. Move is deferred to
+     * first `open()` so SSR / pre-mount construction doesn't crash.
+     */
+    mountTo?: OverlayMountTarget;
+    /**
+     * `peek` keeps part of the panel visible when closed instead of
+     * translating fully off-screen. Number is treated as pixels; strings
+     * accept any CSS length (`"10dvh"`, `"clamp(40px, 8vh, 80px)"`).
+     * Only honoured when `edge: 'bottom'` — warns and falls back otherwise.
+     */
+    peek?: number | string;
+    /**
+     * Close when a pointerdown lands outside `element` AND outside `backdrop`.
+     * Distinct from `closeOnBackdrop` — this fires even when no backdrop is
+     * mounted. Single document-level listener, removed on close.
+     */
+    closeOnOutsidePointer?: boolean;
+    /**
+     * Named archetype — bundles `enterAnimation`/`exitAnimation`/
+     * `backdropOpacity`/`backdropFilter`/`swipeToClose` defaults. Applied
+     * BEFORE the individual options on this object, so any explicit field
+     * still wins over the preset's default.
+     */
+    preset?: OverlayPreset;
+    /** Lifecycle callbacks. */
+    onOpen?: () => void;
+    onClose?: () => void;
+};
+type OverlayState = {
+    isOpen: boolean;
+    isAnimating: boolean;
+};
+type OverlayEventMap = {
+    open: void;
+    close: {
+        reason: OverlayCloseReason;
+    };
+    "before-open": void;
+    "before-close": void;
+};
+type Listener<K extends keyof OverlayEventMap> = (payload: OverlayEventMap[K]) => void;
+declare class OverlayEngine {
+    private id;
+    private element;
+    private backdrop?;
+    private edge;
+    private closeOnEscape;
+    private closeOnBackdropEnabled;
+    private focusTrapEnabled;
+    private initialFocus?;
+    private bodyScrollLockEnabled;
+    private inertSiblingsEnabled;
+    private closeOnBackEnabled;
+    private duration;
+    private enterEasing;
+    private exitEasing;
+    private backdropOpacity;
+    private backdropFilter?;
+    private swipeToCloseEnabled;
+    private swipeThreshold;
+    private swipeVelocityThreshold;
+    private enterAnimation;
+    private exitAnimation;
+    private mountTarget?;
+    private originalParent;
+    private originalNextSibling;
+    private mounted;
+    private peekRaw?;
+    private peekPx?;
+    private closeOnOutsidePointerEnabled;
+    private detachOutsidePointer;
+    private detachSwipe;
+    private onOpenCb?;
+    private onCloseCb?;
+    private isOpen_;
+    private isAnimating_;
+    private destroyed;
+    private hasInjectedChildren;
+    private cycleNonce;
+    private bus;
+    private detachEscape;
+    private detachBackdrop;
+    private detachHardwareBack;
+    private releaseStackEntry;
+    private lifecycle;
+    constructor(opts: OverlayOptions);
+    get state(): OverlayState;
+    on<K extends keyof OverlayEventMap>(event: K, fn: Listener<K>): () => void;
+    open(): Promise<void>;
+    close(reason?: OverlayCloseReason): Promise<void>;
+    toggle(): Promise<void>;
+    destroy(): void;
+    /**
+     * Runtime visual setter — opacity is applied immediately when open so a
+     * live-controls panel can preview the change without re-opening. When
+     * closed we only stash the field; next open() picks it up so we don't
+     * mutate hidden DOM (avoids paint thrash on detached panels).
+     */
+    setBackdropOpacity(opacity: number): void;
+    /**
+     * Runtime visual setter for `backdrop-filter`. `undefined` clears the
+     * filter (mirrors the close() behaviour). Defers to next open() when the
+     * overlay is currently closed.
+     */
+    setBackdropFilter(filter: string | undefined): void;
+    /**
+     * Toggle / reconfigure swipe-to-close at runtime. Re-resolves the flat
+     * threshold fields, then installs or tears down the pointer listener so
+     * the change applies to the CURRENT open cycle. Idempotent: safe to call
+     * with the same config repeatedly.
+     */
+    setSwipeToClose(config: boolean | SwipeToCloseConfig): void;
+    /** Animation setters only stage the field — applied on next open/close. */
+    setEnterAnimation(animation: OverlayAnimation): void;
+    setExitAnimation(animation: OverlayAnimation): void;
+    /** Updates the field used at next close() — no immediate side effect. */
+    setReturnFocus(target: HTMLElement | (() => HTMLElement | null) | undefined): void;
+    /**
+     * Batch update — preset first, then individual overrides. Applied as a
+     * single DOM-write phase when open so live-controls don't trigger
+     * cascading reflows. Safe to call when closed (defers to next open).
+     */
+    setOverlay(opts: OverlayUpdate): void;
+    /**
+     * Runtime children injection — replace the panel's contents without
+     * unmounting the engine. `replaceChildren()` is a single atomic DOM op,
+     * so callers can swap content rapidly without intermediate flicker.
+     * Function form is resolved exactly ONCE per call (cheap lazy content).
+     */
+    setOverlayChildren(children: HTMLElement | DocumentFragment | (() => HTMLElement | DocumentFragment)): void;
+    /**
+     * Clear injected children. No-op when nothing was injected so consumers
+     * who never used setOverlayChildren can call this defensively without
+     * paying for a DOM mutation.
+     */
+    clearOverlayChildren(): void;
+    private assignSwipeFromConfig;
+    private emit;
+    private resolvePeekPx;
+    private maybeMount;
+    private restoreMount;
+    private applyClosedStyles;
+    private awaitTransition;
+    private installInteractiveListeners;
+    private releaseInteractiveListeners;
+    /**
+     * Light pointer-driven dismiss. Tracks finger along the edge axis, follows
+     * with translate, dismisses if past `swipeThreshold` (fraction of panel
+     * size) or release velocity exceeds `swipeVelocityThreshold` (px/ms).
+     * Pure CSS-transform during drag — no rAF or physics required since the
+     * panel only moves one direction.
+     */
+    private installSwipeToClose;
+    private registerInStack;
+}
+
+declare const createOverlay: (opts: OverlayOptions) => OverlayEngine;
+
+export { OVERLAY_PRESETS, OverlayEngine as Overlay, type OverlayAnimation, type OverlayCloseReason, type OverlayEdge, OverlayEngine, type OverlayEventMap, type OverlayMountTarget, type OverlayOptions, type OverlayPreset, type OverlayState, type OverlayUpdate, type SwipeToCloseConfig, createOverlay };

package/dist/overlay.d.ts

@@ -0,0 +1,282 @@
+import { T as TransformAxis } from './transform-Brkf-wzo.js';
+
+/**
+ * Slide-up panel without gestures. CSS-transition-driven, single-state.
+ * Distinct from `BottomSheetEngine`, which is gesture-driven and multi-snap.
+ *
+ * Shares scroll-lock / focus-trap / sheet-stack / inert-siblings / transform
+ * primitives with the engine so z-indices orchestrate automatically when
+ * sheets and overlays mix and feature behaviour stays consistent.
+ */
+type OverlayEdge = TransformAxis;
+type OverlayAnimation = "slide" | "fade" | "scale";
+type OverlayCloseReason = "escape" | "backdrop" | "swipe" | "back" | "programmatic" | "outside-pointer";
+type SwipeToCloseConfig = {
+    enabled?: boolean;
+    threshold?: number;
+    velocityThreshold?: number;
+};
+type OverlayMountTarget = HTMLElement | "body" | "parent";
+/**
+ * Named overlay archetypes — bundle the common animation + dim + gesture
+ * combinations so consumers can opt into a "mode" without restating every
+ * field. Applied BEFORE individual options at construction, and as the
+ * first step of `setOverlay()` so individual overrides win.
+ */
+type OverlayPreset = "sheet" | "dialog" | "sidebar" | "toast";
+type OverlayPresetConfig = {
+    enterAnimation: OverlayAnimation;
+    exitAnimation: OverlayAnimation;
+    backdropOpacity: number;
+    backdropFilter?: string;
+    swipeToClose: boolean | SwipeToCloseConfig;
+};
+declare const OVERLAY_PRESETS: Readonly<Record<OverlayPreset, Readonly<OverlayPresetConfig>>>;
+/**
+ * Batch payload for `setOverlay()`. `null` on `backdropFilter` clears it
+ * (distinct from `undefined` which means "leave as-is" in the diff). Apply
+ * order: preset first, then individual overrides — single DOM-write phase
+ * if the overlay is currently open.
+ */
+type OverlayUpdate = {
+    backdropOpacity?: number;
+    backdropFilter?: string | null;
+    swipeToClose?: boolean | SwipeToCloseConfig;
+    enterAnimation?: OverlayAnimation;
+    exitAnimation?: OverlayAnimation;
+    preset?: OverlayPreset;
+    /**
+     * Runtime children swap. `null` clears the panel's contents. A function is
+     * called once to lazy-resolve dynamic content. Applied LAST in the batch so
+     * style mutations finish before the DOM swap.
+     */
+    children?: HTMLElement | DocumentFragment | (() => HTMLElement | DocumentFragment) | null;
+};
+type OverlayOptions = {
+    /** The panel element — gets transform/opacity inline writes. */
+    element: HTMLElement;
+    /** Optional dimmed backdrop element. */
+    backdrop?: HTMLElement;
+    /** Edge the panel slides in from. Default: "bottom". */
+    edge?: OverlayEdge;
+    /** Open immediately on construction. Default: false. */
+    initialOpen?: boolean;
+    /** Listen for Escape key. Default: true. */
+    closeOnEscape?: boolean;
+    /** Tap on backdrop closes. Default: true. */
+    closeOnBackdrop?: boolean;
+    /** Trap Tab focus inside the panel. Default: true. */
+    focusTrap?: boolean;
+    /** Selector or HTMLElement focused on open. */
+    initialFocus?: string | HTMLElement;
+    /**
+     * Element to focus after close. By default the focus trap restores
+     * whatever was focused before open. Pass an element or a getter for
+     * explicit control (e.g. focus a status banner instead of the trigger).
+     */
+    returnFocus?: HTMLElement | (() => HTMLElement | null);
+    /** Lock body scroll while open. Default: true. */
+    lockBodyScroll?: boolean;
+    /** Mark page siblings `inert` while open (full a11y modal). Default: false. */
+    inertSiblings?: boolean;
+    /** Push history state so Android back closes the overlay. Default: false. */
+    closeOnBack?: boolean;
+    /** Animation duration in ms. Default: 320. */
+    duration?: number;
+    /** CSS easing for the slide-in. Default matches monitoring's bezier. */
+    enterEasing?: string;
+    /** CSS easing for the slide-out. Default: ease-in. */
+    exitEasing?: string;
+    /**
+     * Peak backdrop opacity when open. Useful when `backdropFilter` blur
+     * already darkens enough and the dim should be light (e.g. 0.3).
+     * Default: 1.
+     */
+    backdropOpacity?: number;
+    /**
+     * CSS `backdrop-filter` value applied to the backdrop while open
+     * (e.g. `"blur(8px)"`, `"blur(12px) saturate(140%)"`). Cleared on close.
+     */
+    backdropFilter?: string;
+    /**
+     * Allow drag-to-dismiss along the entry edge — pointer-driven. The panel
+     * follows the finger past the closed-edge axis and dismisses if the user
+     * crosses 30% of the panel size or releases with > 0.5 px/ms velocity.
+     *
+     * Pass a config object to tune thresholds:
+     *   `{ enabled: true, threshold: 0.5, velocityThreshold: 1.0 }`.
+     * Default: false (CSS-only transition).
+     */
+    swipeToClose?: boolean | SwipeToCloseConfig;
+    /**
+     * Entry animation. `"slide"` (default) translates from the edge.
+     * `"fade"` is opacity-only (no transform). `"scale"` fades + scales
+     * from 0.94 — best for centred dialogs.
+     */
+    enterAnimation?: OverlayAnimation;
+    /** Exit animation. Defaults to `enterAnimation`. */
+    exitAnimation?: OverlayAnimation;
+    /**
+     * Move `element` to a different container on first open. `'parent'`
+     * (default) leaves it in place. `'body'` appends to `document.body`.
+     * Pass an explicit `HTMLElement` for any other portal target.
+     *
+     * Restored to its original parent on `destroy()`. Move is deferred to
+     * first `open()` so SSR / pre-mount construction doesn't crash.
+     */
+    mountTo?: OverlayMountTarget;
+    /**
+     * `peek` keeps part of the panel visible when closed instead of
+     * translating fully off-screen. Number is treated as pixels; strings
+     * accept any CSS length (`"10dvh"`, `"clamp(40px, 8vh, 80px)"`).
+     * Only honoured when `edge: 'bottom'` — warns and falls back otherwise.
+     */
+    peek?: number | string;
+    /**
+     * Close when a pointerdown lands outside `element` AND outside `backdrop`.
+     * Distinct from `closeOnBackdrop` — this fires even when no backdrop is
+     * mounted. Single document-level listener, removed on close.
+     */
+    closeOnOutsidePointer?: boolean;
+    /**
+     * Named archetype — bundles `enterAnimation`/`exitAnimation`/
+     * `backdropOpacity`/`backdropFilter`/`swipeToClose` defaults. Applied
+     * BEFORE the individual options on this object, so any explicit field
+     * still wins over the preset's default.
+     */
+    preset?: OverlayPreset;
+    /** Lifecycle callbacks. */
+    onOpen?: () => void;
+    onClose?: () => void;
+};
+type OverlayState = {
+    isOpen: boolean;
+    isAnimating: boolean;
+};
+type OverlayEventMap = {
+    open: void;
+    close: {
+        reason: OverlayCloseReason;
+    };
+    "before-open": void;
+    "before-close": void;
+};
+type Listener<K extends keyof OverlayEventMap> = (payload: OverlayEventMap[K]) => void;
+declare class OverlayEngine {
+    private id;
+    private element;
+    private backdrop?;
+    private edge;
+    private closeOnEscape;
+    private closeOnBackdropEnabled;
+    private focusTrapEnabled;
+    private initialFocus?;
+    private bodyScrollLockEnabled;
+    private inertSiblingsEnabled;
+    private closeOnBackEnabled;
+    private duration;
+    private enterEasing;
+    private exitEasing;
+    private backdropOpacity;
+    private backdropFilter?;
+    private swipeToCloseEnabled;
+    private swipeThreshold;
+    private swipeVelocityThreshold;
+    private enterAnimation;
+    private exitAnimation;
+    private mountTarget?;
+    private originalParent;
+    private originalNextSibling;
+    private mounted;
+    private peekRaw?;
+    private peekPx?;
+    private closeOnOutsidePointerEnabled;
+    private detachOutsidePointer;
+    private detachSwipe;
+    private onOpenCb?;
+    private onCloseCb?;
+    private isOpen_;
+    private isAnimating_;
+    private destroyed;
+    private hasInjectedChildren;
+    private cycleNonce;
+    private bus;
+    private detachEscape;
+    private detachBackdrop;
+    private detachHardwareBack;
+    private releaseStackEntry;
+    private lifecycle;
+    constructor(opts: OverlayOptions);
+    get state(): OverlayState;
+    on<K extends keyof OverlayEventMap>(event: K, fn: Listener<K>): () => void;
+    open(): Promise<void>;
+    close(reason?: OverlayCloseReason): Promise<void>;
+    toggle(): Promise<void>;
+    destroy(): void;
+    /**
+     * Runtime visual setter — opacity is applied immediately when open so a
+     * live-controls panel can preview the change without re-opening. When
+     * closed we only stash the field; next open() picks it up so we don't
+     * mutate hidden DOM (avoids paint thrash on detached panels).
+     */
+    setBackdropOpacity(opacity: number): void;
+    /**
+     * Runtime visual setter for `backdrop-filter`. `undefined` clears the
+     * filter (mirrors the close() behaviour). Defers to next open() when the
+     * overlay is currently closed.
+     */
+    setBackdropFilter(filter: string | undefined): void;
+    /**
+     * Toggle / reconfigure swipe-to-close at runtime. Re-resolves the flat
+     * threshold fields, then installs or tears down the pointer listener so
+     * the change applies to the CURRENT open cycle. Idempotent: safe to call
+     * with the same config repeatedly.
+     */
+    setSwipeToClose(config: boolean | SwipeToCloseConfig): void;
+    /** Animation setters only stage the field — applied on next open/close. */
+    setEnterAnimation(animation: OverlayAnimation): void;
+    setExitAnimation(animation: OverlayAnimation): void;
+    /** Updates the field used at next close() — no immediate side effect. */
+    setReturnFocus(target: HTMLElement | (() => HTMLElement | null) | undefined): void;
+    /**
+     * Batch update — preset first, then individual overrides. Applied as a
+     * single DOM-write phase when open so live-controls don't trigger
+     * cascading reflows. Safe to call when closed (defers to next open).
+     */
+    setOverlay(opts: OverlayUpdate): void;
+    /**
+     * Runtime children injection — replace the panel's contents without
+     * unmounting the engine. `replaceChildren()` is a single atomic DOM op,
+     * so callers can swap content rapidly without intermediate flicker.
+     * Function form is resolved exactly ONCE per call (cheap lazy content).
+     */
+    setOverlayChildren(children: HTMLElement | DocumentFragment | (() => HTMLElement | DocumentFragment)): void;
+    /**
+     * Clear injected children. No-op when nothing was injected so consumers
+     * who never used setOverlayChildren can call this defensively without
+     * paying for a DOM mutation.
+     */
+    clearOverlayChildren(): void;
+    private assignSwipeFromConfig;
+    private emit;
+    private resolvePeekPx;
+    private maybeMount;
+    private restoreMount;
+    private applyClosedStyles;
+    private awaitTransition;
+    private installInteractiveListeners;
+    private releaseInteractiveListeners;
+    /**
+     * Light pointer-driven dismiss. Tracks finger along the edge axis, follows
+     * with translate, dismisses if past `swipeThreshold` (fraction of panel
+     * size) or release velocity exceeds `swipeVelocityThreshold` (px/ms).
+     * Pure CSS-transform during drag — no rAF or physics required since the
+     * panel only moves one direction.
+     */
+    private installSwipeToClose;
+    private registerInStack;
+}
+
+declare const createOverlay: (opts: OverlayOptions) => OverlayEngine;
+
+export { OVERLAY_PRESETS, OverlayEngine as Overlay, type OverlayAnimation, type OverlayCloseReason, type OverlayEdge, OverlayEngine, type OverlayEventMap, type OverlayMountTarget, type OverlayOptions, type OverlayPreset, type OverlayState, type OverlayUpdate, type SwipeToCloseConfig, createOverlay };