@surdeddd/bottom-sheet 0.1.0 → 0.2.0

package/dist/vue.js

@@ -1,4 +1,4 @@
-import { ref, reactive, onMounted, onBeforeUnmount, openBlock, createElementBlock, createCommentVNode, renderSlot, createElementVNode, normalizeClass, toDisplayString, defineComponent, watch, computed, readonly } from 'vue';
+import { ref, reactive, onMounted, onBeforeUnmount, openBlock, createElementBlock, createCommentVNode, createElementVNode, renderSlot, normalizeClass, toDisplayString, defineComponent, watch, computed, readonly } from 'vue';
 
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -230,11 +230,6 @@ var SnapResolver = class {
     this.allowedIds = allowed ?? raw.map((p) => p.id);
     this.recompute();
   }
-  /**
-   * Re-resolve raw → resolved against the current viewport / fit-measure,
-   * recompute maxAxisSize, invalidate range cache, notify engine. Called on
-   * resize, orientationchange, visualViewport changes, and snap-list swaps.
-   */
   recompute() {
     this.resolved = resolveSnapList(this.raw, this.mode, this.measureFit);
     this.maxAxisSize = this.resolved.reduce(
@@ -244,15 +239,10 @@ var SnapResolver = class {
     this.rangeCache = null;
     this.onMaxAxisSizeChange?.(this.maxAxisSize);
   }
-  /** Replace the raw snap list and recompute. Engine calls on `setSnapPoints`. */
   setRaw(raw) {
     this.raw = raw;
     this.recompute();
   }
-  /**
-   * Replace the allow-list. Range cache depends on `(resolvedSnaps ×
-   * allowedIds)` so flipping ids alone invalidates without a full recompute.
-   */
   setAllowedIds(ids) {
     this.allowedIds = ids;
     this.rangeCache = null;
@@ -260,11 +250,6 @@ var SnapResolver = class {
   findById(id) {
     return findById(id, this.resolved);
   }
-  /**
-   * Pure drag-settle target resolution. Engine passes the gesture-specific
-   * fields (delta, velocity, pointerKind, flickVelocity, dragThreshold) plus
-   * `size`/`activeId` since those are still engine-owned.
-   */
   findDragSettleTarget(args) {
     return findDragSettleTarget({
       ...args,
@@ -273,18 +258,9 @@ var SnapResolver = class {
       maxAxisSize: this.maxAxisSize
     });
   }
-  /**
-   * Memoised allowed-range query. Twice-per-drag-frame (gesture onMove +
-   * applySize→computeProgress); cache collapses 2× iteration of resolvedSnaps
-   * to one recompute per geometry/allow-list change.
-   */
   getAllowedRange() {
     return this.rangeCache ?? (this.rangeCache = allowedRange(this.resolved, this.allowedIds));
   }
-  /**
-   * Read-only view of resolved snaps. Returned as `readonly` to discourage
-   * accidental mutation by feature install sites that close over this list.
-   */
   getResolvedSnaps() {
     return this.resolved;
   }
@@ -294,18 +270,6 @@ var SnapResolver = class {
   getMaxAxisSize() {
     return this.maxAxisSize;
   }
-  /**
-   * External clamp override. The resize-observer feature compares
-   * `getMaxAxisSize()` against the live viewport and shrinks if the largest
-   * resolved snap exceeds it (mobile address-bar collapse / soft-keyboard
-   * window resize). The next `recompute()` overwrites this clamp from the
-   * resolved-snap reduction.
-   *
-   * Does NOT invalidate the range cache — viewport clamping doesn't change
-   * `(resolvedSnaps × allowedIds) → range`. DOES fire `onMaxAxisSizeChange`
-   * so the resolver owns the layout-axis style write end-to-end (symmetric
-   * with `recompute()` — feature call sites no longer duplicate the write).
-   */
   setMaxAxisSize(n) {
     this.maxAxisSize = n;
     this.onMaxAxisSizeChange?.(n);
@@ -680,73 +644,49 @@ var WriteSentinel = class {
   constructor() {
     __publicField(this, "last", -1);
   }
-  /**
-   * Returns `true` (and updates the cached value) if `next` differs from the
-   * cached `last` by more than `epsilon`. Returns `false` (and leaves the
-   * cache untouched) when the delta is within epsilon — caller skips the
-   * CSSOM write.
-   */
   shouldWrite(next, epsilon) {
     if (Math.abs(next - this.last) <= epsilon) return false;
     this.last = next;
     return true;
   }
-  /**
-   * Force the next `shouldWrite` to pass. Resets the cache to `-1` so any
-   * non-negative `next` exceeds the epsilon comparison. Called from setters
-   * that mutate state under the cache (range/mode/enabled flips that change
-   * the progress→opacity mapping but don't move `progress` itself).
-   */
   invalidate() {
     this.last = -1;
   }
-  /**
-   * Record `value` as the last-written without performing a write. Used
-   * when a setter writes a literal value through a different path (e.g.
-   * `setScrimMode("off")` writes `opacity: "0"` inline) and wants future
-   * `shouldWrite` calls to short-circuit against that known cached state.
-   */
   setLastWritten(value) {
     this.last = value;
   }
-  /** Read-only accessor for diagnostic / dedup-aware peek. */
   get value() {
     return this.last;
   }
 };
 
+// src/core/primitives/devWarn.ts
+function devWarn(...args) {
+  if (typeof process !== "undefined" && process.env && process.env.NODE_ENV !== "production" && typeof console !== "undefined") {
+    console.warn(...args);
+  }
+}
+
 // src/core/controllers/scrim-controller.ts
+var VALID_CSS_LENGTH = /^-?\d+(?:\.\d+)?(?:px|em|rem|%)$/;
 var ScrimController = class {
   constructor(deps, opts) {
-    // ── DOM refs (mirror engine's; cached for hot path) ─────────────────
     __publicField(this, "screenComponent");
     __publicField(this, "backdrop");
     __publicField(this, "mode");
-    // ── Engine callbacks ────────────────────────────────────────────────
     __publicField(this, "isDestroyed");
     __publicField(this, "isTopSheet");
     __publicField(this, "getAllowedIds");
     __publicField(this, "getResolvedSnaps");
     __publicField(this, "snapToFn");
-    // ── Mode + state ────────────────────────────────────────────────────
     __publicField(this, "scrimMode");
     __publicField(this, "backdropRange");
     __publicField(this, "screenRange");
-    // setScrimEnabled toggle — gated through `scrimEnabled` rather than nuking
-    // ranges so re-enable can restore prior values without a remount. Public
-    // so tests / introspection can read it without an `as any` cast.
     __publicField(this, "scrimEnabled", true);
     __publicField(this, "savedScrimRanges", null);
-    // ── Tap-to-close ────────────────────────────────────────────────────
     __publicField(this, "scrimTapToCloseEnabled", false);
     __publicField(this, "detachScrimTap", null);
-    // ── Scrim overlay slot (positioned floating element) ────────────────
     __publicField(this, "scrimOverlayTeardown", null);
-    // ── Hot-path opacity dedup caches (per-frame writes) ────────────────
-    // Numeric sentinels migrated to WriteSentinel primitive — single
-    // invalidation surface, shared with the engine's size/progress sentinels.
-    // The two string-typed sentinels (`Pointer`, `Display`) keep their inline
-    // pattern: equality on string union, no epsilon, different reset semantics.
     __publicField(this, "backdropOpacitySentinel", new WriteSentinel());
     __publicField(this, "screenOpacitySentinel", new WriteSentinel());
     __publicField(this, "lastBackdropPointer", "");
@@ -781,41 +721,15 @@ var ScrimController = class {
       }
     }
   }
-  /**
-   * Invalidate the opacity dedup caches. Called from any setter that mutates
-   * range/mode/enabled — opacity is a pure function of (progress, range,
-   * enabled), so a config change makes the cached values stale even if
-   * `progress` itself didn't move. Next `applyOpacity(progress, false)` call
-   * sees the -1 sentinel and re-runs the math instead of short-circuiting.
-   *
-   * Public for the engine: `setSnapPoints` mutates resolved geometry which
-   * shifts `progress→opacity` mapping under the cache; engine calls this to
-   * keep the next render frame correct on a static sheet.
-   * @internal
-   */
   invalidateOpacityCache() {
     this.backdropOpacitySentinel.invalidate();
     this.screenOpacitySentinel.invalidate();
   }
-  /** Engine calls this when its `attach()` runs — installs scrim-tap-click if requested. */
   attach() {
     if (this.scrimTapToCloseEnabled) {
       this.setScrimTapToClose(true);
     }
   }
-  // ── Hot-path: opacity computation called per-frame from engine.applySize ──
-  /**
-   * Per-frame opacity writer. Computes backdrop + screen opacity from the
-   * sheet's progress (0..1 within allowed range), gated by sub-pixel dedup
-   * caches so steady-state frames don't trigger style recalc.
-   *
-   * `progressChanged` is the engine's already-computed dedup gate — when
-   * `false`, opacity is by construction a pure function of `progress` so
-   * cached values are still valid; we short-circuit the Math.min/max +
-   * division work entirely. Setters that mutate ranges/mode/enabled
-   * invalidate the cache by writing -1 sentinels so the next call re-runs
-   * the math.
-   */
   applyOpacity(progress, progressChanged) {
     if (!progressChanged && this.backdropOpacitySentinel.value !== -1 && this.screenOpacitySentinel.value !== -1) {
       return;
@@ -861,80 +775,30 @@ var ScrimController = class {
       }
     }
   }
-  // ── Public setters (engine forwards these 1:1) ─────────────────────
-  /**
-   * Replace the [start, end] progress window in which the backdrop fades 0→1.
-   * @param range - Tuple of two progress values in 0..1 (start <= end).
-   * @param applySize - Engine-supplied recompute hook; runs one applyOpacity pass.
-   * @example
-   *   // Backdrop only starts darkening after the sheet crosses 30% open.
-   *   engine.setBackdropRange([0.3, 1]);
-   */
   setBackdropRange(range, applySize) {
     if (this.isDestroyed()) return;
     this.backdropRange = range;
     this.invalidateOpacityCache();
     applySize();
   }
-  /**
-   * Replace the [start, end] progress window in which the screen scrim fades 0→1.
-   * @param range - Tuple of two progress values in 0..1 (start <= end).
-   * @param applySize - Engine-supplied recompute hook; runs one applyOpacity pass.
-   * @example
-   *   // Scrim is fully opaque only when the sheet is past 50% — softer feel.
-   *   engine.setScreenRange([0, 0.5]);
-   */
   setScreenRange(range, applySize) {
     if (this.isDestroyed()) return;
     this.screenRange = range;
     this.invalidateOpacityCache();
     applySize();
   }
-  /**
-   * Set the scrim background color. Pass `null`/`undefined` to clear the
-   * inline write and let consumer CSS take over.
-   * @param color - Any valid CSS color string, or `null`/`undefined` to clear.
-   * @example
-   *   engine.setScrimColor("rgba(0, 0, 0, 0.6)");
-   *   engine.setScrimColor(null); // hand back to consumer CSS
-   */
   setScrimColor(color) {
     if (this.isDestroyed()) return;
     this.applyScrimStyles({ color: color === void 0 ? null : color });
   }
-  /**
-   * Set the scrim backdrop-filter blur radius. Pass `null`/`undefined` to clear.
-   * @param blur - CSS length (e.g. `"8px"`) consumed as `blur(<value>)`, or
-   *               `null`/`undefined` to remove the filter.
-   * @example
-   *   engine.setScrimBlur("12px"); // frosted-glass effect
-   *   engine.setScrimBlur(null);    // disable blur
-   */
   setScrimBlur(blur) {
     if (this.isDestroyed()) return;
     this.applyScrimStyles({ blur: blur === void 0 ? null : blur });
   }
-  /**
-   * Toggle whether the scrim layer captures pointer events.
-   * @param interactive - `true` → `pointer-events: auto`; `false` → `none`.
-   * @example
-   *   engine.setScrimInteractive(true);  // scrim swallows clicks
-   *   engine.setScrimInteractive(false); // clicks pass through to content below
-   */
   setScrimInteractive(interactive) {
     if (this.isDestroyed()) return;
     this.applyScrimStyles({ interactive });
   }
-  /**
-   * Switch scrim positioning at runtime.
-   * @param mode - `"full"` (consumer CSS), `"above-sheet"` (engine-pinned inset
-   *               so only the area NOT covered by the sheet is dimmed), or
-   *               `"off"` (display:none + opacity:0 — no remount needed).
-   * @param applySize - Engine-supplied recompute hook; runs one applyOpacity pass.
-   * @example
-   *   engine.setScrimMode("above-sheet"); // dim only the area above the sheet
-   *   engine.setScrimMode("off");          // disable scrim layer
-   */
   setScrimMode(mode, applySize) {
     if (this.isDestroyed()) return;
     if (mode === this.scrimMode) return;
@@ -964,15 +828,6 @@ var ScrimController = class {
     }
     applySize();
   }
-  /**
-   * Enable or disable click-on-scrim → snap to first non-zero allowed snap.
-   * Auto-promotes `pointer-events: auto` when scrim is non-interactive so the
-   * click listener actually fires.
-   * @param enabled - `true` installs the click listener; `false` removes it.
-   * @example
-   *   engine.setScrimTapToClose(true);  // tap outside sheet collapses it
-   *   engine.setScrimTapToClose(false); // require explicit close button
-   */
   setScrimTapToClose(enabled) {
     if (this.isDestroyed()) return;
     if (!this.screenComponent) return;
@@ -1002,16 +857,6 @@ var ScrimController = class {
       this.scrimTapToCloseEnabled = false;
     }
   }
-  /**
-   * Toggle the scrim layer without remounting. Disabling stashes current
-   * `screenRange`/`backdropRange` and degenerates them to `[1, 1]` (opacity
-   * formula → 0 across the whole range); re-enabling restores the saved values.
-   * @param enabled - `false` hides scrim, `true` restores prior ranges.
-   * @param applySize - Engine-supplied recompute hook; runs one applyOpacity pass.
-   * @example
-   *   engine.setScrimEnabled(false); // hide scrim, ranges remembered
-   *   engine.setScrimEnabled(true);  // restore prior ranges (no remount)
-   */
   setScrimEnabled(enabled, applySize) {
     if (this.isDestroyed()) return;
     if (enabled === this.scrimEnabled) return;
@@ -1030,20 +875,6 @@ var ScrimController = class {
     }
     applySize();
   }
-  /**
-   * Batch-update multiple scrim fields with a single applySize() at the end.
-   * If `preset` is set, it seeds color/blur/interactive/range first; explicit
-   * fields override.
-   * @param opts - Partial scrim config: preset, mode, enabled, tapToClose,
-   *               color, blur, interactive, range.
-   * @param applySize - Engine-supplied recompute hook; runs ONCE per call.
-   * @example
-   *   engine.setScrim({
-   *     preset: "frosted",
-   *     mode: "above-sheet",
-   *     tapToClose: true,
-   *   });
-   */
   setScrim(opts, applySize) {
     if (this.isDestroyed()) return;
     if (opts.preset) {
@@ -1066,27 +897,18 @@ var ScrimController = class {
       interactive: opts.interactive
     });
     if (opts.range !== void 0) {
-      this.screenRange = opts.range;
+      if (!this.scrimEnabled && this.savedScrimRanges) {
+        this.savedScrimRanges = {
+          screen: opts.range,
+          backdrop: this.savedScrimRanges.backdrop
+        };
+      } else {
+        this.screenRange = opts.range;
+      }
     }
     this.invalidateOpacityCache();
     applySize();
   }
-  /**
-   * Inject a positioned floating element into the scrim layer (e.g. a close
-   * button anchored top-right). Replaces any prior overlay so repeated calls
-   * (reactive effects re-running) don't accumulate wrappers.
-   * @param opts - Children element, optional `inset` (default `"16px"`),
-   *               `position` (9-way grid, default `"top-right"`), and
-   *               `interactive` flag (default `true`).
-   * @returns Teardown function that removes the wrapper from the DOM.
-   * @example
-   *   const teardown = engine.setScrimOverlay({
-   *     children: closeBtn,
-   *     position: "top-right",
-   *     inset: "20px",
-   *   });
-   *   // later: teardown(); // remove the floating button
-   */
   setScrimOverlay(opts) {
     if (this.isDestroyed()) return () => {
     };
@@ -1094,7 +916,18 @@ var ScrimController = class {
     };
     this.scrimOverlayTeardown?.();
     const screen = this.screenComponent;
-    const inset = opts.inset ?? "16px";
+    const insetRaw = opts.inset ?? "16px";
+    const inset = VALID_CSS_LENGTH.test(insetRaw) ? insetRaw : "16px";
+    if (inset !== insetRaw) {
+      devWarn(
+        `[bottom-sheet] setScrimOverlay: invalid inset ${JSON.stringify(insetRaw)}; expected a CSS length like "16px" / "1rem" / "5%". Falling back to "16px".`
+      );
+    }
+    if (opts.children.ownerDocument && opts.children.ownerDocument !== screen.ownerDocument) {
+      devWarn(
+        "[bottom-sheet] setScrimOverlay: children belong to a different document than the scrim. Cross-document adoption can drop event listeners; construct children via the same document as the sheet root."
+      );
+    }
     const position = opts.position ?? "top-right";
     const interactive = opts.interactive ?? true;
     const wrapper = screen.ownerDocument.createElement("div");
@@ -1143,12 +976,30 @@ var ScrimController = class {
         ws.bottom = inset;
         ws.right = inset;
         break;
+      case "sheet-top-left":
+      case "sheet-top-center":
+      case "sheet-top-right":
+        applySheetAnchoredPosition(
+          ws,
+          this.mode,
+          position,
+          inset
+        );
+        break;
     }
     if (interactive) {
       ws.pointerEvents = "auto";
     }
     wrapper.appendChild(opts.children);
-    screen.appendChild(wrapper);
+    const host = screen.parentElement;
+    if (!host) {
+      devWarn(
+        "[bottom-sheet] setScrimOverlay: scrim element has no parent, skipping overlay injection. Mount the sheet root before calling setScrimOverlay."
+      );
+      return () => {
+      };
+    }
+    host.appendChild(wrapper);
     const teardown = () => {
       if (wrapper.parentNode) wrapper.parentNode.removeChild(wrapper);
       if (this.scrimOverlayTeardown === teardown) {
@@ -1158,7 +1009,6 @@ var ScrimController = class {
     this.scrimOverlayTeardown = teardown;
     return teardown;
   }
-  /** Tear down toggle-state listeners + remove any injected overlay wrapper. */
   destroy() {
     this.detachScrimTap?.();
     this.detachScrimTap = null;
@@ -1177,8 +1027,6 @@ var ScrimController = class {
     this.lastBackdropPointer = "";
     this.lastScreenDisplay = "";
   }
-  // ── Private helpers ────────────────────────────────────────────────
-  /** Centralized scrim style writer — atomic 3-property write across all setters. */
   applyScrimStyles(opts) {
     if (!this.screenComponent) return;
     const s = this.screenComponent.style;
@@ -1200,7 +1048,6 @@ var ScrimController = class {
       s.pointerEvents = opts.interactive ? "auto" : "none";
     }
   }
-  /** Pin the screen overlay to the area NOT occupied by the sheet. */
   applyAboveSheetInset() {
     if (!this.screenComponent) return;
     const insetByMode = {
@@ -1215,6 +1062,35 @@ var ScrimController = class {
     s.pointerEvents = "none";
   }
 };
+function resolveSheetAnchoredStyle(mode, position, inset) {
+  const sizeOffset = `calc(var(--bs-size, 0px) + ${inset})`;
+  switch (mode) {
+    case "bottom":
+      if (position === "sheet-top-left") return { bottom: sizeOffset, left: inset };
+      if (position === "sheet-top-right") return { bottom: sizeOffset, right: inset };
+      return { bottom: sizeOffset, left: "50%", transform: "translateX(-50%)" };
+    case "top":
+      if (position === "sheet-top-left") return { top: sizeOffset, left: inset };
+      if (position === "sheet-top-right") return { top: sizeOffset, right: inset };
+      return { top: sizeOffset, left: "50%", transform: "translateX(-50%)" };
+    case "left":
+      if (position === "sheet-top-left") return { left: sizeOffset, top: inset };
+      if (position === "sheet-top-right") return { left: sizeOffset, bottom: inset };
+      return { left: sizeOffset, top: "50%", transform: "translateY(-50%)" };
+    case "right":
+      if (position === "sheet-top-left") return { right: sizeOffset, top: inset };
+      if (position === "sheet-top-right") return { right: sizeOffset, bottom: inset };
+      return { right: sizeOffset, top: "50%", transform: "translateY(-50%)" };
+  }
+}
+function applySheetAnchoredPosition(ws, mode, position, inset) {
+  const style = resolveSheetAnchoredStyle(mode, position, inset);
+  if (style.top !== void 0) ws.top = style.top;
+  if (style.bottom !== void 0) ws.bottom = style.bottom;
+  if (style.left !== void 0) ws.left = style.left;
+  if (style.right !== void 0) ws.right = style.right;
+  if (style.transform !== void 0) ws.transform = style.transform;
+}
 
 // src/core/animation/animation.ts
 var easeOutBack = (t) => {
@@ -1367,13 +1243,9 @@ var AnimationRunner = class {
     __publicField(this, "duration");
     __publicField(this, "easing");
     __publicField(this, "respectReducedMotion");
-    /** Live-tracked via mq listener so animateTo skips matchMedia per snap. */
     __publicField(this, "reducedMotion", false);
-    /** Disposes the matchMedia change listener — drained from destroy(). */
     __publicField(this, "detachReducedMotion", null);
-    /** Computed once — both inputs (option + API presence) stable for life. */
     __publicField(this, "viewTransitionsAvailable");
-    /** In-flight handles. Public for tests / debugging only — engine drives via cancel(). */
     __publicField(this, "currentTween", null);
     __publicField(this, "currentSpring", null);
     this.element = deps.element;
@@ -1404,26 +1276,13 @@ var AnimationRunner = class {
       }
     }
   }
-  /**
-   * Live derived flag — `true` whenever a spring/tween handle is in flight.
-   * Reading the canonical handles (instead of mirroring into a separate
-   * boolean) eliminates the reduced-motion early-return latent bug where
-   * the flag stayed true forever, and removes the cross-controller
-   * setIsAnimating callback.
-   */
   get isAnimating() {
     return this.currentTween !== null || this.currentSpring !== null;
   }
-  /** Cancel any in-flight tween/spring without touching engine state. */
   cancel() {
     this.currentTween?.cancel();
     this.currentSpring?.cancel();
   }
-  /**
-   * Animate from current size to `target`. Resolves when the animation
-   * completes; resolves early if cancelled mid-flight (caller checks an
-   * abort signal post-await for cycle-invariant correctness).
-   */
   async animateTo(target, velocityPxPerMs) {
     if (target === this.getSize()) return;
     this.currentTween?.cancel();
@@ -1464,7 +1323,6 @@ var AnimationRunner = class {
       if (!this.isDragging()) this.element.style.willChange = "auto";
     }
   }
-  /** Tear down the matchMedia listener. Engine calls from destroy(). */
   destroy() {
     this.detachReducedMotion?.();
     this.detachReducedMotion = null;
@@ -1624,12 +1482,8 @@ var LifecycleController = class {
     __publicField(this, "inertSiblings");
     __publicField(this, "shouldApplyInertSiblings");
     __publicField(this, "returnFocus");
-    /** Toggle-state teardowns — fire on close, NOT in destroy-only stack. */
     __publicField(this, "releaseFocusTrap", null);
     __publicField(this, "releaseScrollLock", null);
-    /** True between install() and release(). Guards release()/destroy() from
-     *  re-running side effects (notably `returnFocus.focus()`) on already-
-     *  released or never-installed instances. */
     __publicField(this, "installed", false);
     __publicField(this, "destroyed", false);
     this.element = deps.element;
@@ -1643,14 +1497,6 @@ var LifecycleController = class {
     this.returnFocus = opts.returnFocus;
     this.inertSiblings = createInertSiblings(() => this.element);
   }
-  /**
-   * Run the open-time install steps. Idempotent: each step checks its
-   * existing teardown ref so a re-open during a half-cancelled close
-   * doesn't double-install. Sets `installed=true` BEFORE the first side
-   * effect so a partial throw (detached / shadow-DOM target) leaves the
-   * caller's `release()` rollback path armed to undo whatever did succeed.
-   * No-op when destroyed.
-   */
   install() {
     if (this.destroyed) return;
     this.installed = true;
@@ -1667,22 +1513,10 @@ var LifecycleController = class {
       this.inertSiblings.apply();
     }
   }
-  /**
-   * Update the post-release focus target. Overlay re-binds this when the
-   * consumer changes `returnFocus` after construction; the new value applies
-   * on the next `release()`. No-op when destroyed.
-   */
   setReturnFocus(target) {
     if (this.destroyed) return;
     this.returnFocus = target;
   }
-  /**
-   * Release all install-time teardowns. Short-circuits when not installed,
-   * so `close() → destroy()` (each routing through here) only restores
-   * focus once. The `installed` guard lets `inertSiblings.remove()` and
-   * the focus-trap/scroll-lock teardown nullings stay simple — they were
-   * already idempotent, but `returnFocus.focus()` was firing on every call.
-   */
   release() {
     if (!this.installed) return;
     this.installed = false;
@@ -1696,12 +1530,6 @@ var LifecycleController = class {
       target?.focus?.();
     }
   }
-  /**
-   * Final teardown — releases any still-installed listeners and seals the
-   * controller. After destroy(), install() is a no-op and setReturnFocus()
-   * is rejected, so post-destroy mutations can't queue up a stale focus
-   * restore.
-   */
   destroy() {
     this.release();
     this.destroyed = true;
@@ -1711,12 +1539,10 @@ var LifecycleController = class {
 // src/core/gestures.ts
 var isAxisVertical = (mode) => mode === "bottom" || mode === "top";
 var SampleRing = class {
-  // current count, ≤ capacity
   constructor(capacity) {
     __publicField(this, "slots");
     __publicField(this, "capacity");
     __publicField(this, "head", 0);
-    // next write index
     __publicField(this, "size", 0);
     this.capacity = capacity;
     this.slots = new Array(capacity);
@@ -1729,12 +1555,6 @@ var SampleRing = class {
     this.head = (this.head + 1) % this.capacity;
     if (this.size < this.capacity) this.size++;
   }
-  /**
-   * Drop oldest entries whose timestamp is below `cutoff`, but never shrink
-   * below `minKeep`. Mirrors the original
-   *   `while (samples.length > minKeep && samples[0].t < cutoff) samples.shift()`
-   * but without copying — just advances the logical tail.
-   */
   pruneBefore(cutoff, minKeep) {
     while (this.size > minKeep) {
       const oldestIdx = (this.head - this.size + this.capacity) % this.capacity;
@@ -1870,28 +1690,14 @@ var GestureController = class {
     __publicField(this, "detach", null);
     __publicField(this, "isDragging_", false);
     __publicField(this, "dragStartSize", 0);
-    // Only "touch" gestures are eligible for soft-keyboard dismissal —
-    // mouse/trackpad users don't have a keyboard to dismiss.
     __publicField(this, "currentPointerKind", "touch");
-    // One blur per drag — flipping focus every move event races the keyboard's
-    // own animations on iOS and makes the page jitter.
     __publicField(this, "keyboardDismissed", false);
-    // Reused payload object for the "drag" event — mutated each onMove instead
-    // of allocating a fresh `{size, delta}` per frame. At 60-120Hz a long drag
-    // would otherwise churn tens of KB through the GC. Mirrors browser
-    // PointerEvent semantics: consumers must NOT retain the reference across
-    // frames (clone if needed). See SheetEventMap.drag JSDoc.
     __publicField(this, "dragPayload", { size: 0, delta: 0 });
     this.deps = deps;
   }
-  /** True between `dragstart` and `dragend`/`onCancel`. */
   get isDragging() {
     return this.isDragging_;
   }
-  /**
-   * Bind pointer listeners on the handle and return a teardown. Engine pushes
-   * the teardown into its TeardownStack so destroy() drains it once.
-   */
   install() {
     if (this.detach) return this.detach;
     this.detach = installGestures(this.deps.handle, this.deps.mode, {
@@ -1948,11 +1754,6 @@ var GestureController = class {
     });
     return this.detach;
   }
-  /**
-   * Force-clear drag visual state. Engine calls from destroy() when destroyed
-   * mid-drag — gesture detach won't synthesize an onCancel, so we have to
-   * roll back the data-attribute + will-change ourselves.
-   */
   forceClearDragState() {
     if (!this.isDragging_) return;
     this.isDragging_ = false;
@@ -1971,11 +1772,6 @@ var AriaSliderWriter = class {
       mode === "bottom" || mode === "top" ? "vertical" : "horizontal"
     );
   }
-  /**
-   * Update slider position. `allowedIds` length determines `aria-valuemax`;
-   * `activeId` indexes into it for `aria-valuenow` + `aria-valuetext`.
-   * Empty list → strip every dynamic attr so AT skips the handle entirely.
-   */
   setValue(allowedIds, activeId) {
     if (allowedIds.length === 0) {
       this.handle.removeAttribute("aria-valuemin");
@@ -2049,9 +1845,6 @@ function resolveEngineOptions(opts, extras) {
       scrimMode: opts.scrimMode,
       scrimColor: opts.scrimColor,
       scrimBlur: opts.scrimBlur,
-      // Auto-promote pointer-events when tap-to-close is on so the click
-      // listener actually receives events. Caller can still force `false`
-      // explicitly to opt out — `??` only kicks in for `undefined`.
       scrimInteractive: opts.scrimInteractive ?? (opts.scrimTapToClose ? true : void 0),
       scrimTapToClose: opts.scrimTapToClose,
       scrimPreset: opts.scrimPreset,
@@ -2072,10 +1865,6 @@ function resolveEngineOptions(opts, extras) {
       closeOnEscape: opts.closeOnEscape,
       lockBodyScroll: opts.lockBodyScroll,
       inertSiblings: opts.inertSiblings,
-      // Folded in from `extras` so the lifecycle bag is fully assembled at
-      // the call site — engine no longer needs a spread+override at
-      // controller construction. When `extras` is omitted, the field stays
-      // undefined and the controller uses its own default predicate.
       shouldApplyInertSiblings: extras?.shouldApplyInertSiblings
     }
   };
@@ -2110,6 +1899,7 @@ var BottomSheetEngine = class {
     __publicField(this, "scrollContainer");
     __publicField(this, "backdrop");
     __publicField(this, "screenComponent");
+    __publicField(this, "scrimParent", null);
     __publicField(this, "mode");
     __publicField(this, "flickVelocity");
     __publicField(this, "dragThreshold");
@@ -2120,40 +1910,22 @@ var BottomSheetEngine = class {
     __publicField(this, "lifecycle");
     __publicField(this, "closeOnBack");
     __publicField(this, "routedTo");
-    // Engine retains `snapPointsRaw` for the "find a closed-id" query in
-    // close() (raw input, not resolved geometry). Resolver owns geometry.
     __publicField(this, "snapPointsRaw");
     __publicField(this, "snaps");
     __publicField(this, "activeId");
     __publicField(this, "size", 0);
-    // Constructed in attach(); a plugin's install() could read `state` before
-    // attach completes if the constructor throws partway through. State getter
-    // null-guards via `this.gesture?.isDragging ?? false`.
     __publicField(this, "gesture");
     __publicField(this, "rootEl", null);
     __publicField(this, "destroyed", false);
-    // In-flight ViewTransition handle. A second snapTo while a VT is in flight
-    // would otherwise let Chromium reject the second's promise and flicker —
-    // newCycle() calls skipTransition() to abort cleanly.
     __publicField(this, "currentViewTransition", null);
-    // Each cycle captures the signal at entry; when a newer cycle aborts the
-    // controller, the captured signal flips to `aborted=true` and post-await
-    // guards short-circuit (prevents stale snap/open/close emits).
     __publicField(this, "currentAbort", new AbortController());
-    // Sub-pixel `--bs-size` deltas and <1% `--bs-progress` deltas are not
-    // visually distinguishable; gating CSSOM writes drops 30-50% of writes
-    // during the spring's settle tail.
     __publicField(this, "sizeWriteSentinel", new WriteSentinel());
     __publicField(this, "progressWriteSentinel", new WriteSentinel());
     __publicField(this, "isTopSheet", true);
-    // Pooled payload — identity documented in SheetEventMap.progress JSDoc;
-    // consumers must not retain across frames.
     __publicField(this, "progressPayload", {
       value: 0,
       size: 0
     });
-    // Pooled buffer for `getDragContext()` — onMove calls this 60-120×/s.
-    // Inner `range` object identity is also stable (mutated in place).
     __publicField(this, "dragContextBuf", {
       size: 0,
       maxAxisSize: 0,
@@ -2164,13 +1936,7 @@ var BottomSheetEngine = class {
     __publicField(this, "persistKey");
     __publicField(this, "linkedSheets", []);
     __publicField(this, "scrollCache");
-    // Single LIFO stack for ALL destroy-only teardowns. Plugins (added last)
-    // tear down first before the infrastructure they depend on. Toggle-semantic
-    // listeners (focus-trap / scroll-lock / scrim tap-to-close) stay as named
-    // fields on their controllers.
     __publicField(this, "teardowns", new TeardownStack());
-    // Pre-computed transform template — built once per engine since `mode` is
-    // fixed for its lifetime. Avoids the 4-arm switch at 60-120 Hz.
     __publicField(this, "transformTemplate");
     const resolved = resolveEngineOptions(opts, {
       shouldApplyInertSiblings: () => {
@@ -2185,7 +1951,8 @@ var BottomSheetEngine = class {
     this.handle = opts.handle ?? opts.element;
     this.scrollContainer = opts.scrollContainer;
     this.backdrop = opts.backdrop;
-    this.screenComponent = opts.screenComponent;
+    this.screenComponent = opts.scrim ?? opts.screenComponent;
+    this.scrimParent = this.screenComponent?.parentElement ?? null;
     this.mode = resolved.mode;
     this.transformTemplate = buildTransformTemplate(this.mode);
     this.aria = new AriaSliderWriter(this.handle, this.mode);
@@ -2213,8 +1980,6 @@ var BottomSheetEngine = class {
         getRootEl: () => this.rootEl,
         applySize: (size) => this.applySize(size),
         getSize: () => this.size,
-        // Optional chain protects synthetic test paths that drive animateTo
-        // before attach() (gesture is constructed there).
         isDragging: () => this.gesture?.isDragging ?? false
       },
       resolved.animation
@@ -2319,21 +2084,6 @@ var BottomSheetEngine = class {
   on(event, fn) {
     return this.bus.on(event, fn);
   }
-  /**
-   * Register a plugin. `install` runs synchronously; if it returns a function,
-   * it's captured for teardown during `destroy()`. No-op if already destroyed
-   * — installing into a torn-down engine would leak listeners.
-   *
-   * Throws from `plugin.install` are caught and rethrown via `queueMicrotask`
-   * so a buggy plugin can't take the engine down with it: the engine stays
-   * usable, sibling plugins still install, and the error surfaces in dev tools
-   * on the next tick instead of being swallowed. Mirrors the per-fn isolation
-   * model used for teardowns.
-   *
-   * Plugins that accept the second `scope` argument get transactional cleanup:
-   * push partial-install cleanups via `scope.add(fn)` and the engine drains
-   * them on throw, OR merges them into destroy-time teardowns on success.
-   */
   use(plugin) {
     if (this.destroyed) {
       console.warn(
@@ -2343,9 +2093,6 @@ var BottomSheetEngine = class {
     }
     const scoped = [];
     const scope = {
-      // typeof check — not just truthiness — so a JS-only plugin pushing a
-      // bogus value is silently rejected instead of queueing a confusing
-      // TypeError on destroy() drain.
       add: (fn) => {
         if (typeof fn === "function") scoped.push(fn);
       }
@@ -2374,36 +2121,13 @@ var BottomSheetEngine = class {
     }
     return this;
   }
-  /**
-   * Replace the linked-sheets list at runtime. Use when peer engines aren't
-   * available at construction time (mounted later in the tree). The wiring
-   * to the `open` event is independent of this list — it reads `linkedSheets`
-   * lazily on emit, so this setter is a simple field swap.
-   */
   setLinkedSheets(sheets) {
     if (this.destroyed) return;
     this.linkedSheets = sheets;
   }
-  /** Read-only view of the current allow-list, for cross-sheet target negotiation. */
   getAllowedIds() {
     return this.snaps.getAllowedIds().slice();
   }
-  /**
-   * Animate to a snap point by id. Resolves when the animation completes.
-   *
-   * Two call shapes:
-   * ```ts
-   * engine.snapTo("full");                           // default velocity
-   * engine.snapTo("full", 0.5);                      // px/ms initial velocity
-   * engine.snapTo("full", { velocity: 0.5, signal }); // abortable
-   * ```
-   *
-   * When `opts.signal` is provided, calling `controller.abort()` cancels the
-   * in-flight tween/spring and the returned promise resolves without firing
-   * `snap`. The captured `AbortSignal` is checked after each await so external
-   * aborts ride the same cycle invariant as internal ones (resize, destroy,
-   * concurrent snapTo).
-   */
   async snapTo(id, velocityOrOpts = 0, _skipBeforeSnap = false) {
     if (this.destroyed) return;
     const opts = typeof velocityOrOpts === "object" ? velocityOrOpts : { velocity: velocityOrOpts };
@@ -2462,16 +2186,6 @@ var BottomSheetEngine = class {
       this.handleClose();
     }
   }
-  /**
-   * Drive the sheet to an arbitrary px size, bypassing snap matching.
-   * Useful for preview scrubs, animation chaining, or programmatic gestures.
-   * Animates with the configured spring/tween. Resolves when the animation
-   * completes. Does NOT update `activeId` — call `snapTo(id)` after to commit.
-   *
-   * Unlike `snapTo`, this does not fire `before-snap` (it isn't a snap commit)
-   * nor `snap` (the sheet isn't settling to a known snap). `progress` events
-   * still fire via applySize. Target is clamped to `[0, maxAxisSize]`.
-   */
   async dragTo(targetSize, velocityOrOpts = 0) {
     if (this.destroyed) return;
     const opts = typeof velocityOrOpts === "object" ? velocityOrOpts : { velocity: velocityOrOpts };
@@ -2509,20 +2223,10 @@ var BottomSheetEngine = class {
     this.snaps.setAllowedIds(ids);
     this.updateAriaSlider();
     if (snap && ids.includes(snap)) {
-      void this.snapTo(
-        snap,
-        0,
-        /* internal */
-        true
-      );
+      void this.snapTo(snap, 0, true);
     } else if (!ids.includes(this.activeId)) {
       const fallback = ids[0];
-      if (fallback) void this.snapTo(
-        fallback,
-        0,
-        /* internal */
-        true
-      );
+      if (fallback) void this.snapTo(fallback, 0, true);
     }
   }
   setBackdropRange(range) {
@@ -2540,21 +2244,6 @@ var BottomSheetEngine = class {
   setScrimInteractive(interactive) {
     this.scrim.setScrimInteractive(interactive);
   }
-  /**
-   * Batch-update multiple scrim fields in one call. Apply order is:
-   *   1. `preset` — fills baseline color/blur/range/interactive.
-   *   2. `mode` — re-positions the scrim (fixed inset / clear / hide).
-   *   3. `enabled` — flips the opacity contribution on/off.
-   *   4. `tapToClose` — installs/tears the click listener.
-   *   5. `color` / `blur` / `interactive` / `range` — explicit overrides.
-   *   6. ONE `applySize` so the per-frame opacity stays consistent.
-   *
-   * Performance: collecting changes here (vs calling individual setters)
-   * avoids repeated `applySize` calls during a multi-field swap. Setters
-   * called here suppress their own internal `applySize` either by passing
-   * through fast-paths (mode/enabled no-op when value unchanged) or by
-   * being visual-only (color/blur/interactive don't influence opacity).
-   */
   setScrim(opts) {
     this.scrim.setScrim(opts, () => this.applySize(this.size));
   }
@@ -2570,11 +2259,6 @@ var BottomSheetEngine = class {
   setScrimOverlay(opts) {
     return this.scrim.setScrimOverlay(opts);
   }
-  /**
-   * Read-only snapshot of scrim state. Use the `setScrim*` setters to mutate.
-   * Stable public API — internals (e.g. cached opacity sentinels) are NOT
-   * exposed so consumers can't accidentally couple to ScrimController shape.
-   */
   getScrimState() {
     return { mode: this.scrim.scrimMode, enabled: this.scrim.scrimEnabled };
   }
@@ -2620,24 +2304,11 @@ var BottomSheetEngine = class {
   emit(event, payload) {
     this.bus.emit(event, payload);
   }
-  /**
-   * Abort the current cycle's signal and replace the controller. Returns the
-   * fresh signal so the caller can capture it locally before any await — when
-   * a future newCycle() / destroy aborts our controller, the captured signal
-   * flips to aborted and post-await guards short-circuit.
-   */
   newCycle() {
     this.currentAbort.abort();
     this.currentAbort = new AbortController();
     return this.currentAbort.signal;
   }
-  /**
-   * Fire `before-snap` and report whether a listener cancelled it. The
-   * `cancel()` callback exposed to listeners is frozen after the synchronous
-   * emit phase so async callers can't silently miss — they get a console
-   * warning. Returns `true` when cancelled so callers can early-return /
-   * spring-back without re-implementing the cancel/frozen pattern.
-   */
   emitBeforeSnap(target, previousId) {
     let cancelled = false;
     let frozen = false;
@@ -2671,30 +2342,9 @@ var BottomSheetEngine = class {
     this.snaps.setRaw(this.snapPointsRaw);
     this.scrim.invalidateOpacityCache();
   }
-  /**
-   * Memoised `allowedRange()` — delegates to SnapResolver which owns the cache.
-   * Engine wrapper kept so existing call sites don't all need updating;
-   * resolver-level memoization survives across method invocations.
-   */
   getAllowedRange() {
     return this.snaps.getAllowedRange();
   }
-  /**
-   * Write ARIA slider value attributes onto the handle so the engine itself
-   * is the source of truth for screen-reader announcements. Called from the
-   * constructor and from every code path that mutates `activeId` /
-   * `allowedIds`. WAI-ARIA 1.2 requires `aria-valuenow` for `role="slider"` —
-   * without it screen readers can't announce drag/snap progress to keyboard
-   * + AT users (WCAG 4.1.2 Name, Role, Value).
-   *
-   * Engine does NOT set `role="slider"` itself — that's the adapter's or
-   * consumer markup's responsibility. We only decorate with dynamic values.
-   *
-   * Empty allowed-list is malformed input (settable via `setAllowed([])`);
-   * short-circuit to remove ARIA value attributes so screen readers see a
-   * no-value slider rather than a degenerate `min=max=now=0` (WAI-ARIA 1.2
-   * requires `valuemax > valuemin` for `role="slider"`).
-   */
   updateAriaSlider() {
     this.aria.setValue(this.snaps.getAllowedIds(), this.activeId);
   }
@@ -2719,11 +2369,6 @@ var BottomSheetEngine = class {
       element: this.element,
       mode: this.mode,
       getRoot: () => this.rootEl,
-      // Single coalesced reader — narrows the DI surface and removes 3 getter
-      // dispatches per onMove frame at 60-120Hz. Returns a SHARED buffer
-      // (this.dragContextBuf) — see field JSDoc for the retention contract.
-      // Inner `range` object is mutated in place too so callers caching its
-      // identity between frames stay valid.
       getDragContext: () => {
         const buf = this.dragContextBuf;
         const r = this.getAllowedRange();
@@ -2889,7 +2534,6 @@ var BottomSheetEngine = class {
       }
     });
   }
-  /** Trigger a brief haptic tick (iOS Safari + Android Chrome support). */
   haptic() {
     if (typeof navigator !== "undefined" && "vibrate" in navigator) {
       try {
@@ -2905,6 +2549,9 @@ var BottomSheetEngine = class {
     style.transform = this.transformTemplate(offset);
     if (this.sizeWriteSentinel.shouldWrite(size, SIZE_WRITE_EPSILON)) {
       style.setProperty("--bs-size", `${size}px`);
+      if (this.scrimParent) {
+        this.scrimParent.style.setProperty("--bs-size", `${size}px`);
+      }
     }
     const progress = this.computeProgress(size);
     const progressChanged = this.progressWriteSentinel.shouldWrite(
@@ -2974,7 +2621,7 @@ function useBottomSheet(opts) {
       handle: handleRef.value ?? void 0,
       scrollContainer: contentRef.value ?? void 0,
       backdrop: backdropRef.value ?? void 0,
-      screenComponent: screenRef.value ?? void 0
+      scrim: screenRef.value ?? void 0
     });
     sync();
     engine.on("snap", (payload) => {
@@ -3007,6 +2654,9 @@ function useBottomSheet(opts) {
     close: () => engine?.close() ?? Promise.resolve(),
     setAllowed: (ids, snap) => engine?.setAllowed(ids, snap),
     setSnapPoints: (points, allowed) => engine?.setSnapPoints(points, allowed),
+    setScrim: (opts2) => engine?.setScrim(opts2),
+    setScrimOverlay: (opts2) => engine?.setScrimOverlay(opts2) ?? (() => {
+    }),
     on: (event, fn) => {
       if (engine) return engine.on(event, fn);
       const entry = {
@@ -3024,7 +2674,8 @@ function useBottomSheet(opts) {
           if (idx !== -1) pending.splice(idx, 1);
         }
       };
-    }
+    },
+    getEngine: () => engine
   };
 }
 
@@ -3041,6 +2692,10 @@ var export_helper_default = (sfc, props) => {
 var _sfc_main = /* @__PURE__ */ defineComponent({
   __name: "BottomSheet",
   props: {
+    screenComponent: {
+      type: null,
+      required: false
+    },
     mode: {
       type: String,
       required: false
@@ -3194,7 +2849,7 @@ var _sfc_main = /* @__PURE__ */ defineComponent({
   setup(__props, { expose: __expose, emit: __emit }) {
     const props = __props;
     const emit = __emit;
-    const { sheetRef, handleRef, contentRef, backdropRef, screenRef, state, snapTo, open, close, setAllowed, setSnapPoints, on } = useBottomSheet(props);
+    const { sheetRef, handleRef, contentRef, backdropRef, screenRef, state, snapTo, open, close, setAllowed, setSnapPoints, setScrim, setScrimOverlay, on, getEngine } = useBottomSheet(props);
     watch(() => ({ ...state }), (next) => emit("change", next), { deep: false });
     on("snap", (payload) => emit("snap", payload.id));
     on("open", (payload) => emit("open", payload.id));
@@ -3215,10 +2870,10 @@ var _sfc_main = /* @__PURE__ */ defineComponent({
       close,
       setAllowed,
       setSnapPoints,
+      setScrim,
+      setScrimOverlay,
       on,
-      // readonly() prevents external write-through (e.g. `bsRef.value.state.size = 999`)
-      // that would desync the local view-state proxy from the engine's truth.
-      // Mirrors React's getter-based exposure and Svelte's getState() snapshot.
+      getEngine,
       state: readonly(state)
     });
     const __returned__ = {
@@ -3235,7 +2890,10 @@ var _sfc_main = /* @__PURE__ */ defineComponent({
       close,
       setAllowed,
       setSnapPoints,
+      setScrim,
+      setScrimOverlay,
       on,
+      getEngine,
       isVerticalAxis,
       allowedIds,
       activeIdx,
@@ -3250,7 +2908,6 @@ var _sfc_main = /* @__PURE__ */ defineComponent({
 });
 var _hoisted_1 = { class: "bs-root" };
 var _hoisted_2 = {
-  key: 1,
   ref: "screenRef",
   class: "bs-screen"
 };
@@ -3304,13 +2961,14 @@ function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
       512
       /* NEED_PATCH */
     )) : createCommentVNode("v-if", true),
-    _ctx.$slots.screen ? (openBlock(), createElementBlock(
+    createCommentVNode("\n      Scrim surface always renders so the engine can host scrim presets\n      (color/blur via setScrim), overlay injections (setScrimOverlay),\n      and progress-driven opacity. The `screen` slot, when used, renders\n      inside as user content. Without a slot it stays an empty positioning\n      context.\n    "),
+    createElementVNode(
       "div",
       _hoisted_2,
       [renderSlot(_ctx.$slots, "screen")],
       512
       /* NEED_PATCH */
-    )) : createCommentVNode("v-if", true),
+    ),
     createElementVNode("section", {
       ref: "sheetRef",
       class: normalizeClass(["bs-sheet"]),