@surdeddd/bottom-sheet 0.11.0 → 0.13.0

package/README.md

@@ -2,7 +2,8 @@
 
 > Universal, headless bottom-sheet engine. **One core, eight adapters, GPU-accelerated, fully tested.**
 
-![bundle](https://img.shields.io/badge/core-%E2%89%A422.5%20KB%20gzip%20budget-1a1614?style=flat-square)
+![bundle](https://img.shields.io/badge/core-%E2%89%A424%20KB%20gzip%20budget-1a1614?style=flat-square)
+![slim](https://img.shields.io/badge/slim%20core-%E2%89%A419.5%20KB%20gzip-1a1614?style=flat-square)
 ![tests](https://img.shields.io/badge/tests-500%2B%20unit-2ea44f?style=flat-square)
 ![ts](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white)
 ![license](https://img.shields.io/badge/license-MIT-dc3522?style=flat-square)
@@ -13,6 +14,8 @@ stacking — and the exact same engine behind every adapter.
 
 ## 🚀 [Live demo → bottom-sheet-demo.vercel.app](https://bottom-sheet-demo.vercel.app)
 
+📚 [API reference (typedoc) → surdeddd.github.io/BottomSheet](https://surdeddd.github.io/BottomSheet/)
+
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/sheet-dark.png" />
@@ -226,6 +229,8 @@ type SnapPoint =
 | `initial`            | first allowed | Snap id to start at                                                                                                        |
 | `mode`               | `"bottom"`    | `bottom`, `top`, `left`, `right`                                                                                           |
 | `animation`          | `"spring"`    | `spring`, `tween`, `ios-spring`, `material-bounce`, `linear`, `snappy`                                                     |
+| `settleAnimation`    | off           | `"waapi"` — settle runs as a compositor-driven Web Animation (pre-sampled spring keyframes); falls back to rAF automatically |
+| `features`           | all defaults  | `EngineFeature[]` — override/extend the composable feature set (see Slim core below)                                       |
 | `spring`             | snappy        | `{ stiffness, damping, mass }`                                                                                             |
 | `flickVelocity`      | `0.65 px/ms`  | Mobile flick threshold                                                                                                     |
 | `dragThreshold`      | `18 px`       | Below this, drag snaps back                                                                                                |
@@ -317,6 +322,14 @@ engine.depth(); // open sheets above this one
 engine.destroy(); // remove listeners + cancel animation
 ```
 
+`initial` starts the sheet **born open** at any snap whose size resolves `> 0`
+(no `open` / `opened` event fires — there is no transition to announce). Calling
+`open()` / `snapTo()` **synchronously in the mount tick is safe** — no
+`requestAnimationFrame` / `nextTick` delay is needed, including `fit` / `content`
+and teleported sheets. A sheet mounted hidden (`display:none` ancestor) heals
+and emits its open sequence once on reveal. See
+[Architecture → Opening at construction](docs/ARCHITECTURE.md).
+
 ### Scrim runtime API
 
 The scrim is the dim layer behind/around the sheet (`screenComponent`). All
@@ -380,6 +393,52 @@ Three deliberate choices keep things 60 fps even on mid-range Android:
    propagate via CSS variables (`--bs-progress`, `--bs-size`) and direct
    imperative subscriptions — no React re-renders on every frame.
 
+## Slim core & composable features
+
+The default `BottomSheetEngine` ships every optional behavior preinstalled.
+If you only need the essentials, import the slim core (~17.5 KB gzip vs
+~23 KB) and register just the features you use:
+
+```ts
+import { BottomSheetCore } from '@surdeddd/bottom-sheet/core';
+import { routeFeature, contentSwipeFeature } from '@surdeddd/bottom-sheet/features';
+
+const engine = new BottomSheetCore({
+  element, handle, snapPoints,
+  closeOnBack: true,
+  features: [routeFeature(), contentSwipeFeature()],
+});
+```
+
+Optional features: `routeFeature()` (`closeOnBack` / `routedTo` /
+`closeOnRouteChange`), `visualViewportFeature()` (soft-keyboard clamp),
+`contentSwipeFeature()`, `persistFeature()`, `autoCollapseFeature()`.
+Everything else (gestures, snap math, resize self-heal, a11y slider, focus
+trap, scroll lock, scrim, stacking) is core. Setting an option whose feature
+is missing dev-warns once and is ignored in production. Custom features
+implement `{ name, install(ctx) }` — the same seam the built-ins use.
+
+### Debug overlay
+
+```ts
+import { attachDebugOverlay } from '@surdeddd/bottom-sheet/debug';
+
+const detach = attachDebugOverlay(engine);
+```
+
+A fixed dev panel showing the active snap, live size/progress, drag/animate
+flags and the resolved snap list — driven purely by public engine events,
+shipped as its own entry so it costs nothing in app bundles.
+
+### Qwik SSR
+
+The package declares a `qwik` field pointing at
+`dist/qwik-lib/index.qwik.mjs`. Qwik apps pick the adapter up automatically
+as a vendor root: the consumer optimizer segments it into QRL chunks and
+`renderToString` emits a resumable (`q:container="paused"`) sheet. No extra
+configuration — `import { BottomSheet } from '@surdeddd/bottom-sheet/qwik'`
+keeps working for CSR, and Qwik City SSR now works out of the box.
+
 ## Theming
 
 All visuals are driven by CSS custom properties. Override anywhere:
@@ -408,6 +467,14 @@ element — drive any CSS animation from drag without touching JS:
 }
 ```
 
+> **z-index is engine-owned.** The stack controller rewrites inline `z-index` on
+> `.bs-sheet`, `.bs-backdrop` and anchor wrappers on every stack change (base
+> `100`, step `10` per depth), so a value you set is overwritten and races the
+> stack. To position the sheet layer against app UI, move the container
+> (teleport target / `.bs-root` parent) or change the open order — don't style
+> `z-index` on bs-managed elements. See
+> [Architecture → z-index & the sheet stack](docs/ARCHITECTURE.md).
+
 ### Scrim, blur & high contrast
 
 | Token                    | Default     | Region                                               |

package/dist/{BottomSheetEngine-DzsIwD28.d.cts → BottomSheetCore-CsIjyq7C.d.cts}

@@ -103,6 +103,7 @@ type EngineOptions = {
     scrimTapToClose?: boolean;
     scrimPreset?: ScrimPreset;
     animation?: "spring" | "tween" | "ios-spring" | "material-bounce" | "linear" | "snappy";
+    settleAnimation?: "waapi";
     spring?: {
         stiffness?: number;
         damping?: number;
@@ -127,15 +128,64 @@ type EngineOptions = {
     linkedSheets?: BottomSheetEngineLike[];
     viewTransitions?: boolean;
     stackEffect?: boolean;
+    features?: EngineFeature[];
 };
 
-type BottomSheetEngineLike = BottomSheetEngine;
+type BottomSheetEngineLike = BottomSheetCore;
+type EngineFeatureStage = "attach" | "post";
+type EngineFeatureOptions = {
+    routedTo?: string;
+    closeOnBack: boolean;
+    closeOnRouteChange: boolean;
+    persistKey?: string;
+    autoCollapseAfter?: number;
+};
+type EngineFeatureContext = {
+    element: HTMLElement;
+    scrollContainer?: HTMLElement;
+    sheetId: string;
+    options: EngineFeatureOptions;
+    isDestroyed: () => boolean;
+    isDragging: () => boolean;
+    isAnimating: () => boolean;
+    isTopSheet: () => boolean;
+    isVerticalAxis: () => boolean;
+    getSize: () => number;
+    getActiveId: () => string;
+    getAllowedIds: () => string[];
+    allowedIdsBySize: () => string[];
+    getMaxAxisSize: () => number;
+    resolveSnap: (id: string) => {
+        id: string;
+        size: number;
+    } | null;
+    resolveActiveSnap: () => {
+        id: string;
+        size: number;
+    } | null;
+    setSize: (size: number) => void;
+    setMaxAxisSize: (size: number) => void;
+    applySize: (size: number) => void;
+    recomputeSnaps: () => void;
+    newCycle: () => void;
+    cancelInFlight: () => void;
+    resyncAfterResize: () => void;
+    snapTo: (id: string) => void;
+    close: (reason?: CloseReason) => Promise<void>;
+    on: <K extends keyof SheetEventMap>(event: K, fn: (payload: SheetEventMap[K]) => void) => () => void;
+    addTeardown: (fn: (() => void) | null | undefined) => void;
+};
+type EngineFeature = {
+    name: string;
+    stage?: EngineFeatureStage;
+    install: (ctx: EngineFeatureContext) => (() => void) | void;
+};
 type TeardownScope = {
     add: (fn: (() => void) | null | undefined) => void;
 };
 type Plugin = {
     name: string;
-    install: (engine: BottomSheetEngine, scope: TeardownScope) => void | (() => void);
+    install: (engine: BottomSheetCore, scope: TeardownScope) => void | (() => void);
 };
 type EngineState = {
     size: number;
@@ -200,7 +250,7 @@ type ScrimStagesOptions = {
 };
 
 type Listener<K extends keyof SheetEventMap> = (payload: SheetEventMap[K]) => void;
-declare class BottomSheetEngine {
+declare class BottomSheetCore {
     private id;
     private element;
     private handle;
@@ -252,11 +302,16 @@ declare class BottomSheetEngine {
     private stackEffectPrimed;
     private fitDeps;
     private transformTemplate;
+    private featureList;
+    private featureCtx;
     constructor(opts: EngineOptions);
+    private buildFeatureContext;
+    private runFeatureStage;
+    private warnOrphanFeatureOptions;
     get state(): EngineState;
     on<K extends keyof SheetEventMap>(event: K, fn: Listener<K>): () => void;
     use(plugin: Plugin): this;
-    setLinkedSheets(sheets: BottomSheetEngine[]): void;
+    setLinkedSheets(sheets: BottomSheetCore[]): void;
     getAllowedIds(): string[];
     getResolvedSnaps(): readonly {
         id: string;
@@ -304,6 +359,7 @@ declare class BottomSheetEngine {
     };
     setSnapPoints(points: EngineOptions["snapPoints"], allowed?: string[]): void;
     recompute(): void;
+    private healActiveSnap;
     destroy(): void;
     private emit;
     private newCycle;
@@ -329,4 +385,4 @@ declare class BottomSheetEngine {
     private handleClose;
 }
 
-export { type AnchorOptions as A, BottomSheetEngine as B, type CloseReason as C, type EngineState as E, type Plugin as P, type ScrimStagesOptions as S, type TeardownScope as T, type SnapPointDef as a, type SheetMode as b, type EngineOptions as c, type SheetEventMap as d, type SnapPoint as e, type ScrimOverlayPosition as f, type AnchorAnimationPreset as g, type AnchorAnimationSpec as h, type AnchorHandle as i, type AnchorPosition as j, type AnchorState as k, SCRIM_PRESETS as l, type ScrimOverlayOptions as m, type ScrimPreset as n, type ScrimPresetConfig as o, type ScrimStageDef as p, type ScrimUpdate as q, type SnapId as r, runAnchorTransition as s };
+export { type AnchorOptions as A, BottomSheetCore as B, type CloseReason as C, type EngineState as E, type Plugin as P, type ScrimStagesOptions as S, type TeardownScope as T, type EngineOptions as a, type SnapPointDef as b, type SheetMode as c, type SheetEventMap as d, type SnapPoint as e, type ScrimOverlayPosition as f, type AnchorAnimationPreset as g, type AnchorAnimationSpec as h, type AnchorHandle as i, type AnchorPosition as j, type AnchorState as k, type EngineFeature as l, type EngineFeatureContext as m, type EngineFeatureOptions as n, type EngineFeatureStage as o, SCRIM_PRESETS as p, type ScrimOverlayOptions as q, type ScrimPreset as r, type ScrimPresetConfig as s, type ScrimStageDef as t, type ScrimUpdate as u, type SnapId as v, runAnchorTransition as w };

package/dist/{BottomSheetEngine-DRjCU73e.d.ts → BottomSheetCore-D16lsa6g.d.ts}

@@ -103,6 +103,7 @@ type EngineOptions = {
     scrimTapToClose?: boolean;
     scrimPreset?: ScrimPreset;
     animation?: "spring" | "tween" | "ios-spring" | "material-bounce" | "linear" | "snappy";
+    settleAnimation?: "waapi";
     spring?: {
         stiffness?: number;
         damping?: number;
@@ -127,15 +128,64 @@ type EngineOptions = {
     linkedSheets?: BottomSheetEngineLike[];
     viewTransitions?: boolean;
     stackEffect?: boolean;
+    features?: EngineFeature[];
 };
 
-type BottomSheetEngineLike = BottomSheetEngine;
+type BottomSheetEngineLike = BottomSheetCore;
+type EngineFeatureStage = "attach" | "post";
+type EngineFeatureOptions = {
+    routedTo?: string;
+    closeOnBack: boolean;
+    closeOnRouteChange: boolean;
+    persistKey?: string;
+    autoCollapseAfter?: number;
+};
+type EngineFeatureContext = {
+    element: HTMLElement;
+    scrollContainer?: HTMLElement;
+    sheetId: string;
+    options: EngineFeatureOptions;
+    isDestroyed: () => boolean;
+    isDragging: () => boolean;
+    isAnimating: () => boolean;
+    isTopSheet: () => boolean;
+    isVerticalAxis: () => boolean;
+    getSize: () => number;
+    getActiveId: () => string;
+    getAllowedIds: () => string[];
+    allowedIdsBySize: () => string[];
+    getMaxAxisSize: () => number;
+    resolveSnap: (id: string) => {
+        id: string;
+        size: number;
+    } | null;
+    resolveActiveSnap: () => {
+        id: string;
+        size: number;
+    } | null;
+    setSize: (size: number) => void;
+    setMaxAxisSize: (size: number) => void;
+    applySize: (size: number) => void;
+    recomputeSnaps: () => void;
+    newCycle: () => void;
+    cancelInFlight: () => void;
+    resyncAfterResize: () => void;
+    snapTo: (id: string) => void;
+    close: (reason?: CloseReason) => Promise<void>;
+    on: <K extends keyof SheetEventMap>(event: K, fn: (payload: SheetEventMap[K]) => void) => () => void;
+    addTeardown: (fn: (() => void) | null | undefined) => void;
+};
+type EngineFeature = {
+    name: string;
+    stage?: EngineFeatureStage;
+    install: (ctx: EngineFeatureContext) => (() => void) | void;
+};
 type TeardownScope = {
     add: (fn: (() => void) | null | undefined) => void;
 };
 type Plugin = {
     name: string;
-    install: (engine: BottomSheetEngine, scope: TeardownScope) => void | (() => void);
+    install: (engine: BottomSheetCore, scope: TeardownScope) => void | (() => void);
 };
 type EngineState = {
     size: number;
@@ -200,7 +250,7 @@ type ScrimStagesOptions = {
 };
 
 type Listener<K extends keyof SheetEventMap> = (payload: SheetEventMap[K]) => void;
-declare class BottomSheetEngine {
+declare class BottomSheetCore {
     private id;
     private element;
     private handle;
@@ -252,11 +302,16 @@ declare class BottomSheetEngine {
     private stackEffectPrimed;
     private fitDeps;
     private transformTemplate;
+    private featureList;
+    private featureCtx;
     constructor(opts: EngineOptions);
+    private buildFeatureContext;
+    private runFeatureStage;
+    private warnOrphanFeatureOptions;
     get state(): EngineState;
     on<K extends keyof SheetEventMap>(event: K, fn: Listener<K>): () => void;
     use(plugin: Plugin): this;
-    setLinkedSheets(sheets: BottomSheetEngine[]): void;
+    setLinkedSheets(sheets: BottomSheetCore[]): void;
     getAllowedIds(): string[];
     getResolvedSnaps(): readonly {
         id: string;
@@ -304,6 +359,7 @@ declare class BottomSheetEngine {
     };
     setSnapPoints(points: EngineOptions["snapPoints"], allowed?: string[]): void;
     recompute(): void;
+    private healActiveSnap;
     destroy(): void;
     private emit;
     private newCycle;
@@ -329,4 +385,4 @@ declare class BottomSheetEngine {
     private handleClose;
 }
 
-export { type AnchorOptions as A, BottomSheetEngine as B, type CloseReason as C, type EngineState as E, type Plugin as P, type ScrimStagesOptions as S, type TeardownScope as T, type SnapPointDef as a, type SheetMode as b, type EngineOptions as c, type SheetEventMap as d, type SnapPoint as e, type ScrimOverlayPosition as f, type AnchorAnimationPreset as g, type AnchorAnimationSpec as h, type AnchorHandle as i, type AnchorPosition as j, type AnchorState as k, SCRIM_PRESETS as l, type ScrimOverlayOptions as m, type ScrimPreset as n, type ScrimPresetConfig as o, type ScrimStageDef as p, type ScrimUpdate as q, type SnapId as r, runAnchorTransition as s };
+export { type AnchorOptions as A, BottomSheetCore as B, type CloseReason as C, type EngineState as E, type Plugin as P, type ScrimStagesOptions as S, type TeardownScope as T, type EngineOptions as a, type SnapPointDef as b, type SheetMode as c, type SheetEventMap as d, type SnapPoint as e, type ScrimOverlayPosition as f, type AnchorAnimationPreset as g, type AnchorAnimationSpec as h, type AnchorHandle as i, type AnchorPosition as j, type AnchorState as k, type EngineFeature as l, type EngineFeatureContext as m, type EngineFeatureOptions as n, type EngineFeatureStage as o, SCRIM_PRESETS as p, type ScrimOverlayOptions as q, type ScrimPreset as r, type ScrimPresetConfig as s, type ScrimStageDef as t, type ScrimUpdate as u, type SnapId as v, runAnchorTransition as w };

package/dist/BottomSheetEngine-BYjAVrmd.d.cts

@@ -0,0 +1,7 @@
+import { B as BottomSheetCore, a as EngineOptions } from './BottomSheetCore-CsIjyq7C.cjs';
+
+declare class BottomSheetEngine extends BottomSheetCore {
+    constructor(opts: EngineOptions);
+}
+
+export { BottomSheetEngine as B };

package/dist/BottomSheetEngine-YuCNugZn.d.ts

@@ -0,0 +1,7 @@
+import { B as BottomSheetCore, a as EngineOptions } from './BottomSheetCore-D16lsa6g.js';
+
+declare class BottomSheetEngine extends BottomSheetCore {
+    constructor(opts: EngineOptions);
+}
+
+export { BottomSheetEngine as B };