@surdeddd/bottom-sheet 0.10.0 → 0.12.0

package/README.md

@@ -2,8 +2,8 @@
 
 > Universal, headless bottom-sheet engine. **One core, eight adapters, GPU-accelerated, fully tested.**
 
-![bundle](https://img.shields.io/badge/core-16.8%20KB%20gzip-1a1614?style=flat-square)
-![tests](https://img.shields.io/badge/tests-501%20unit-2ea44f?style=flat-square)
+![bundle](https://img.shields.io/badge/core-%E2%89%A422.5%20KB%20gzip%20budget-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)
 
@@ -14,40 +14,41 @@ stacking — and the exact same engine behind every adapter.
 ## 🚀 [Live demo → bottom-sheet-demo.vercel.app](https://bottom-sheet-demo.vercel.app)
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Surdeddd/BottomSheet/main/docs/gifs/01-drag-to-close.gif" alt="drag to close — spring physics" width="380" />
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/sheet-dark.png" />
+    <img src="docs/screenshots/sheet-light.png" alt="bottom sheet at a mid snap point over a dimmed page" width="420" />
+  </picture>
 </p>
 
-```
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Surdeddd/BottomSheet/main/docs/gifs/01-drag-to-close.gif" alt="drag to close — spring physics" width="380" />
+</p>
 
-                       ┌───────────────────────────────────────┐
-                       │           ENGINE (~9.15 KB gzip)      │
-                       │   spring · gestures · snap math       │
-                       │   focus trap · scroll lock · stack    │
-                       └────────────┬──────────────────────────┘
-                                    │
-       ┌──────┬──────┬──────┬──────┬──────┬─────────────┬─────────┐
-       ▼      ▼      ▼      ▼      ▼      ▼             ▼         ▼
-    React  Vue 3  Svelte  Solid  Lit   Web Comp.    Vanilla   Angular
-                                                              (recipe)
-```
+<p align="center">
+  <img src="docs/assets/architecture.svg" alt="One engine core feeding eight adapters — React, Preact, Vue 3, Svelte, Solid, Qwik, Web Component and Vanilla — plus a standalone /overlay subpath" width="720" />
+</p>
 
-## Why another bottom-sheet?
-
-| Feature                              | vaul    | react-modal-sheet | **this lib**  |
-| ------------------------------------ | ------- | ----------------- | ------------- |
-| React adapter                        | ✓       | ✓                 | ✓             |
-| Vue / Svelte / Web Component         | —       | —                 | **✓ ✓ ✓**     |
-| Vanilla / no framework               | —       | —                 | **✓**         |
-| `bottom` mode                        | ✓       | ✓                 | ✓             |
-| `top` / `left` / `right` / overlay   | —       | —                 | **✓**         |
-| Spring physics with velocity carry   | ✓       | partial           | **✓**         |
-| Pointer-type-aware tuning            | —       | —                 | **✓**         |
-| Hardware-back interception (Android) | —       | —                 | **✓**         |
-| `env(safe-area-inset-*)`             | partial | —                 | **✓**         |
-| WCAG 2.1 AA keyboard slider          | partial | —                 | **✓**         |
-| Multi-sheet stacking                 | —       | —                 | **✓**         |
-| Sheet-manager registry (typed)       | —       | —                 | **✓**         |
-| Tests (unit + e2e)                   | partial | partial           | **501 + 195** |
+## What it does
+
+Every item below is verifiable in this repo's `src/`:
+
+- **8 build targets** — React, Preact, Vue 3, Svelte 5, Solid, Qwik, Web
+  Component (Lit-compatible `<bottom-sheet>`) and the vanilla core, plus an
+  `/overlay` subpath (standalone slide-up panel).
+- **4 axes** — `bottom`, `top`, `left`, `right` (via `mode`).
+- **Spring physics with velocity carry**, plus pointer-type-aware tuning
+  (separate touch / mouse / pen drag thresholds).
+- **Hardware-back interception** on Android — opt-in via `closeOnBack`.
+- **`env(safe-area-inset-*)`-aware padding** so action rows clear the home
+  indicator.
+- **WCAG 2.1 AA keyboard slider** — Arrow/Home/End/Esc stepping, focus trap
+  with restore.
+- **Multi-sheet stacking** plus a typed sheet-manager registry.
+- **Cancelable `before-snap` / `before-close`** — veto a transition
+  synchronously.
+- Backed by 500+ unit tests across the suite and ~200 Playwright e2e runs
+  across three browser engines (`mobile-chrome` / `mobile-safari` /
+  `firefox`).
 
 ## Install
 
@@ -316,6 +317,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
@@ -407,6 +416,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                                               |
@@ -456,19 +473,19 @@ npm run demo
 # http://localhost:5173
 ```
 
-The editorial demo showcases all five adapters, every gesture, every mode
+The editorial demo showcases the adapters, every gesture, every mode
 (`bottom · top · left · right · overlay`), and live engine readouts (active
 snap, progress, velocity, FPS). EN/RU and light/dark toggles in the corner.
 
 ## Testing
 
 ```bash
-npm test                 # 501 unit tests via vitest + happy-dom (~6s)
+npm test                 # 500+ unit tests via vitest + happy-dom
 npx playwright test      # e2e via Playwright on mobile-Chrome / mobile-Safari / Firefox
 npm run typecheck        # TypeScript --noEmit
 ```
 
-CI runs all three across Node 20/22 on every PR and tag.
+CI runs all three across Node 20.19 / 22 on every PR and tag.
 
 ## Contributing
 

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

@@ -304,6 +304,7 @@ declare class BottomSheetEngine {
     };
     setSnapPoints(points: EngineOptions["snapPoints"], allowed?: string[]): void;
     recompute(): void;
+    private healActiveSnap;
     destroy(): void;
     private emit;
     private newCycle;

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

@@ -304,6 +304,7 @@ declare class BottomSheetEngine {
     };
     setSnapPoints(points: EngineOptions["snapPoints"], allowed?: string[]): void;
     recompute(): void;
+    private healActiveSnap;
     destroy(): void;
     private emit;
     private newCycle;

package/dist/element.cjs

@@ -504,6 +504,206 @@ var init_linked_sheets = __esm({
   }
 });
 
+// src/core/features/history-coordinator.ts
+function onPopState() {
+  if (suppress > 0) {
+    suppress -= 1;
+    const rebrand = pendingRebrand;
+    pendingRebrand = null;
+    if (rebrand) rebrand();
+    maybeTeardownListener();
+    return;
+  }
+  if (entries.length === 0) {
+    notifyRouteChange();
+    maybeTeardownListener();
+    return;
+  }
+  let target = null;
+  let targetIdx = -1;
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const entry = entries[i];
+    if (!entry.surface.isOpen()) continue;
+    if (!target) {
+      target = entry;
+      targetIdx = i;
+    }
+    if (entry.surface.isTop()) {
+      target = entry;
+      targetIdx = i;
+      break;
+    }
+  }
+  if (!target) {
+    const removed = entries.pop();
+    if (removed) removed.live = false;
+    maybeTeardownListener();
+    return;
+  }
+  target.live = false;
+  entries.splice(targetIdx, 1);
+  const settled = target;
+  void Promise.resolve(settled.surface.close()).then(() => {
+    if (settled.surface.isOpen()) restore(settled);
+  });
+  maybeTeardownListener();
+}
+function restore(entry) {
+  if (!hasWindow() || !hasHistory()) return;
+  entry.live = true;
+  runInternal(() => {
+    try {
+      history.pushState(brandMarker(entry.surface), "", entry.surface.url);
+    } catch {
+      entry.live = false;
+    }
+  });
+  if (entry.live) {
+    entries.push(entry);
+    ensureListener();
+  }
+}
+function pushBackMarker(surface) {
+  const entry = { surface, priorUrl: void 0, live: false };
+  if (!hasWindow() || !hasHistory()) {
+    return entry;
+  }
+  entry.priorUrl = surface.url !== void 0 ? location.href : void 0;
+  runInternal(() => {
+    try {
+      history.pushState(brandMarker(surface), "", surface.url);
+      entry.live = true;
+    } catch {
+      entry.live = false;
+    }
+  });
+  if (entry.live) {
+    entries.push(entry);
+    ensureListener();
+  }
+  return entry;
+}
+function popBackMarker(handle) {
+  if (!hasWindow() || !hasHistory()) return;
+  const entry = handle;
+  const idx = entries.indexOf(entry);
+  if (idx === -1 || !entry.live) return;
+  const last = entries.length - 1;
+  entry.live = false;
+  entries.splice(idx, 1);
+  if (idx !== last) {
+    const rebrandSurface = entries[entries.length - 1].surface;
+    const rebrandUrl = entry.priorUrl;
+    pendingRebrand = () => {
+      runInternal(() => {
+        history.replaceState(
+          brandMarker(rebrandSurface),
+          "",
+          rebrandUrl !== void 0 ? rebrandUrl : location.href
+        );
+      });
+    };
+  }
+  suppress += 1;
+  runInternal(() => {
+    try {
+      history.back();
+    } catch {
+      suppress = Math.max(0, suppress - 1);
+      pendingRebrand = null;
+    }
+  });
+  maybeTeardownListener();
+}
+function subscribeRouteChange(fn) {
+  if (!hasWindow() || !hasHistory()) return () => {
+  };
+  subscribers.add(fn);
+  if (subscribers.size === 1) installPatch();
+  ensureListener();
+  return () => {
+    if (!subscribers.has(fn)) return;
+    subscribers.delete(fn);
+    if (subscribers.size === 0) removePatch();
+    maybeTeardownListener();
+  };
+}
+var entries, subscribers, suppress, internalDepth, pendingRebrand, listenerInstalled, patchInstalled, origPushState, origReplaceState, patchedPushState, patchedReplaceState, hasWindow, hasHistory, brandMarker, runInternal, notifyRouteChange, ensureListener, maybeTeardownListener, installPatch, removePatch;
+var init_history_coordinator = __esm({
+  "src/core/features/history-coordinator.ts"() {
+    entries = [];
+    subscribers = /* @__PURE__ */ new Set();
+    suppress = 0;
+    internalDepth = 0;
+    pendingRebrand = null;
+    listenerInstalled = false;
+    patchInstalled = false;
+    origPushState = null;
+    origReplaceState = null;
+    patchedPushState = null;
+    patchedReplaceState = null;
+    hasWindow = () => typeof window !== "undefined";
+    hasHistory = () => typeof history !== "undefined";
+    brandMarker = (surface) => ({
+      ...surface.markerState(),
+      __bs: true
+    });
+    runInternal = (fn) => {
+      internalDepth += 1;
+      try {
+        fn();
+      } finally {
+        internalDepth -= 1;
+      }
+    };
+    notifyRouteChange = () => {
+      const snapshot = Array.from(subscribers);
+      for (const fn of snapshot) fn();
+    };
+    ensureListener = () => {
+      if (listenerInstalled || !hasWindow()) return;
+      window.addEventListener("popstate", onPopState);
+      listenerInstalled = true;
+    };
+    maybeTeardownListener = () => {
+      if (!listenerInstalled) return;
+      if (entries.length > 0 || subscribers.size > 0 || suppress > 0) return;
+      if (hasWindow()) window.removeEventListener("popstate", onPopState);
+      listenerInstalled = false;
+    };
+    installPatch = () => {
+      if (patchInstalled || !hasHistory()) return;
+      origPushState = history.pushState;
+      origReplaceState = history.replaceState;
+      patchedPushState = function(...args) {
+        origPushState.apply(this, args);
+        if (internalDepth === 0) notifyRouteChange();
+      };
+      patchedReplaceState = function(...args) {
+        origReplaceState.apply(this, args);
+        if (internalDepth === 0) notifyRouteChange();
+      };
+      history.pushState = patchedPushState;
+      history.replaceState = patchedReplaceState;
+      patchInstalled = true;
+    };
+    removePatch = () => {
+      if (!patchInstalled) return;
+      if (history.pushState === patchedPushState && origPushState) {
+        history.pushState = origPushState;
+      }
+      if (history.replaceState === patchedReplaceState && origReplaceState) {
+        history.replaceState = origReplaceState;
+      }
+      origPushState = null;
+      origReplaceState = null;
+      patchedPushState = null;
+      patchedReplaceState = null;
+      patchInstalled = false;
+    };
+  }
+});
+
 // src/core/features/route.ts
 function installRoute(deps) {
   if (typeof window === "undefined") {
@@ -514,135 +714,43 @@ function installRoute(deps) {
     return () => {
     };
   }
-  let pushed = false;
-  let closer = null;
-  const teardownEntry = () => {
-    if (closer) {
-      const idx = closers.indexOf(closer);
-      if (idx !== -1) closers.splice(idx, 1);
-    }
-    const wasConsumed = closer?.consumed ?? false;
-    closer = null;
-    if (pushed && !wasConsumed) {
-      pushed = false;
-      programmaticBack();
-    } else {
-      pushed = false;
-    }
-  };
-  const pushEntry = () => {
-    try {
-      if (deps.routedTo !== void 0) {
-        history.pushState({ __bsRouted: deps.sheetId }, "", deps.routedTo);
-      } else {
-        history.pushState({ __bsSheet: deps.sheetId }, "");
-      }
-      pushed = true;
-    } catch {
-      pushed = false;
-    }
-  };
+  let handle = null;
   const onOpen = () => {
-    if (closer) return;
-    const self = {
+    if (handle) return;
+    handle = pushBackMarker({
       isOpen: () => !deps.isDestroyed() && deps.getSize() > 0,
-      isTop: () => deps.isTopSheet(),
-      close: () => deps.close(),
-      restore: () => {
-        if (deps.isDestroyed() || closer !== self) return;
-        self.consumed = false;
-        if (!closers.includes(self)) closers.push(self);
-        pushEntry();
-      },
-      consumed: false
-    };
-    closer = self;
-    ensureHandler();
-    closers.push(self);
-    pushEntry();
+      isTop: deps.isTopSheet,
+      close: deps.close,
+      markerState: () => deps.routedTo !== void 0 ? { __bsRouted: deps.sheetId } : { __bsSheet: deps.sheetId },
+      url: deps.routedTo
+    });
+  };
+  const onClose = () => {
+    if (!handle) return;
+    popBackMarker(handle);
+    handle = null;
   };
   const unsubscribeOpen = deps.on("open", onOpen);
-  const unsubscribeClose = deps.on("close", teardownEntry);
+  const unsubscribeClose = deps.on("close", onClose);
   if (deps.getSize() > 0) onOpen();
   return () => {
     unsubscribeOpen();
     unsubscribeClose();
-    teardownEntry();
+    if (handle) {
+      popBackMarker(handle);
+      handle = null;
+    }
   };
 }
 function installRouteChange(deps) {
-  if (typeof window === "undefined" || typeof history === "undefined") {
-    return () => {
-    };
-  }
-  const onChange = () => {
+  return subscribeRouteChange(() => {
     if (deps.isDestroyed() || deps.getSize() <= 0) return;
     void deps.close();
-  };
-  const wrap = (key) => {
-    const original = history[key];
-    const patched = function(...args) {
-      original.apply(this, args);
-      onChange();
-    };
-    history[key] = patched;
-    return () => {
-      if (history[key] === patched) {
-        history[key] = original;
-      }
-    };
-  };
-  window.addEventListener("popstate", onChange);
-  const restorePush = wrap("pushState");
-  const restoreReplace = wrap("replaceState");
-  return () => {
-    window.removeEventListener("popstate", onChange);
-    restorePush();
-    restoreReplace();
-  };
+  });
 }
-var closers, handlerInstalled, suppress, ensureHandler, programmaticBack;
 var init_route = __esm({
   "src/core/features/route.ts"() {
-    closers = [];
-    handlerInstalled = false;
-    suppress = 0;
-    ensureHandler = () => {
-      if (handlerInstalled || typeof window === "undefined") return;
-      handlerInstalled = true;
-      window.addEventListener("popstate", () => {
-        if (suppress > 0) {
-          suppress -= 1;
-          return;
-        }
-        let target = null;
-        for (let i = closers.length - 1; i >= 0; i -= 1) {
-          const c = closers[i];
-          if (!c.isOpen()) continue;
-          if (!target) target = c;
-          if (c.isTop()) {
-            target = c;
-            break;
-          }
-        }
-        if (!target) return;
-        target.consumed = true;
-        const idx = closers.indexOf(target);
-        if (idx !== -1) closers.splice(idx, 1);
-        const settled = target;
-        void Promise.resolve(settled.close()).then(() => {
-          if (settled.isOpen()) settled.restore();
-        });
-      });
-    };
-    programmaticBack = () => {
-      suppress += 1;
-      try {
-        history.back();
-      } catch {
-        suppress = Math.max(0, suppress - 1);
-      }
-    };
+    init_history_coordinator();
   }
 });
 
@@ -942,11 +1050,15 @@ var init_fit_measurement = __esm({
   "src/core/features/fit-measurement.ts"() {
     init_transform();
     measureSheetNatural = (element, content, vertical) => {
-      if (!content) {
-        return vertical ? element.offsetHeight : element.offsetWidth;
-      }
       const axis = vertical ? "height" : "width";
       const sheetStyle = element.style;
+      if (!content) {
+        const prev = sheetStyle[axis];
+        sheetStyle[axis] = "auto";
+        const poked2 = vertical ? element.offsetHeight : element.offsetWidth;
+        sheetStyle[axis] = prev;
+        return poked2;
+      }
       const cs = content.style;
       const prevSheet = sheetStyle[axis];
       const prevFlex = cs.flex;
@@ -2640,7 +2752,7 @@ var init_sheet_anchors = __esm({
 // src/core/features/scrim-stages.ts
 function installScrimStages(deps, opts) {
   const doc = deps.host.ownerDocument;
-  const entries = opts.stages.map((def) => {
+  const entries2 = opts.stages.map((def) => {
     const wrapper = doc.createElement("div");
     wrapper.className = "bs-scrim-stage";
     const ws = wrapper.style;
@@ -2661,9 +2773,9 @@ function installScrimStages(deps, opts) {
   const resolveActive = () => {
     const state = deps.getState();
     if (state.size === 0) {
-      return entries.find((e) => matchesId(e.def, state.activeId)) ?? null;
+      return entries2.find((e) => matchesId(e.def, state.activeId)) ?? null;
     }
-    return entries.find((e) => matchesId(e.def, state.activeId)) ?? entries.find((e) => matchesRange(e.def, state.progress)) ?? null;
+    return entries2.find((e) => matchesId(e.def, state.activeId)) ?? entries2.find((e) => matchesRange(e.def, state.progress)) ?? null;
   };
   const hide = (entry, animate) => {
     entry.inFlight?.cancel();
@@ -2712,13 +2824,13 @@ function installScrimStages(deps, opts) {
     deps.on("open", () => update(true)),
     deps.on("close", () => update(true))
   ];
-  if (entries.some((e) => e.def.forRange)) {
+  if (entries2.some((e) => e.def.forRange)) {
     offs.push(deps.on("progress", () => update(true)));
   }
   update(false);
   return () => {
     offs.forEach((off) => off());
-    for (const entry of entries) {
+    for (const entry of entries2) {
       entry.inFlight?.cancel();
       entry.inFlight = null;
       if (entry.wrapper.parentNode) {
@@ -3038,17 +3150,12 @@ var init_BottomSheetEngine = __esm({
         this.attach();
         this.registerInStack();
         if (this.snaps.getMaxAxisSize() === 0 && typeof IntersectionObserver !== "undefined" && typeof document !== "undefined") {
-          const io = new IntersectionObserver((entries) => {
-            for (const entry of entries) {
+          const io = new IntersectionObserver((entries2) => {
+            for (const entry of entries2) {
               if (!entry.isIntersecting) continue;
               if (this.destroyed) return;
               this.snaps.recompute();
-              const current = this.snaps.findById(this.activeId);
-              if (current) {
-                this.size = current.size;
-                this.applySize(this.size);
-                this.updateAriaSlider();
-              }
+              this.healActiveSnap();
               io.disconnect();
               return;
             }
@@ -3212,6 +3319,8 @@ var init_BottomSheetEngine = __esm({
           const vt = document.startViewTransition(() => {
             this.applySize(target.size);
           });
+          vt.ready?.catch(() => {
+          });
           this.currentViewTransition = vt;
           try {
             await vt.finished;
@@ -3463,11 +3572,16 @@ var init_BottomSheetEngine = __esm({
         this.maxHeight.clampTo();
         this.scrim.invalidateOpacityCache();
         if (this.gesture?.isDragging) return;
+        this.healActiveSnap();
+      }
+      healActiveSnap() {
         const current = this.snaps.findById(this.activeId);
-        if (current) {
-          this.size = current.size;
-          this.applySize(this.size);
-          this.updateAriaSlider();
+        if (!current) return;
+        this.size = current.size;
+        this.applySize(this.size);
+        this.updateAriaSlider();
+        if (this.size > 0 && !this.lifecycle.isInstalled && !this.opening && !this.animation.isAnimating) {
+          this.emitOpenSequence(this.activeId);
         }
       }
       destroy() {
@@ -3756,9 +3870,9 @@ var init_BottomSheetEngine = __esm({
           return;
         }
         if (this.emitBeforeSnap(target, previousId)) {
-          const restore = this.snaps.findById(previousId);
-          if (restore) {
-            void this.animation.animateTo(restore.size, 0);
+          const restore2 = this.snaps.findById(previousId);
+          if (restore2) {
+            void this.animation.animateTo(restore2.size, 0);
           }
           return;
         }

package/dist/element.d.cts

@@ -1,4 +1,4 @@
-import { B as BottomSheetEngine, C as CloseReason, A as AnchorOptions, S as ScrimStagesOptions, E as EngineState } from './BottomSheetEngine-DzsIwD28.cjs';
+import { B as BottomSheetEngine, C as CloseReason, A as AnchorOptions, S as ScrimStagesOptions, E as EngineState } from './BottomSheetEngine-D6oiEfZ4.cjs';
 import './transform-jVfAikE9.cjs';
 
 declare const BaseHTMLElement: typeof HTMLElement;

package/dist/element.d.ts

@@ -1,4 +1,4 @@
-import { B as BottomSheetEngine, C as CloseReason, A as AnchorOptions, S as ScrimStagesOptions, E as EngineState } from './BottomSheetEngine-DRjCU73e.js';
+import { B as BottomSheetEngine, C as CloseReason, A as AnchorOptions, S as ScrimStagesOptions, E as EngineState } from './BottomSheetEngine-Dhy0X_e9.js';
 import './transform-jVfAikE9.js';
 
 declare const BaseHTMLElement: typeof HTMLElement;