tera-system-ui 0.2.2 → 0.2.4

package/dist/components/bottom-sheet/BottomSheet.recipe.d.ts

@@ -119,6 +119,26 @@ export interface BottomSheetProps {
      * its open lifetime and removes it on close. A page that sets its own tint is left untouched.
      */
     syncThemeColor?: boolean;
+    /**
+     * Prevent the browser's native pull-to-refresh / overscroll-reload from hijacking a downward
+     * drag that starts on an interactive element inside the sheet. The two-phase gesture only
+     * claims the touch (`preventDefault`) once the drag commits past its activation threshold, so a
+     * *slow* pull can let the browser start pull-to-refresh first (a quick flick clears the
+     * threshold immediately and does not). When true (the default) the sheet pins
+     * `overscroll-behavior-y: contain` on the document root for its open lifetime — reference-counted
+     * across stacked sheets, the page's original value restored on close. Reliable on Android and
+     * iOS 16+. Set false if the host app manages page overscroll itself.
+     */
+    preventPullToRefresh?: boolean;
+    /**
+     * Whether pressing the browser Back button closes the sheet. Default true (matching Dialog).
+     *
+     * While open, the sheet pushes a dummy history entry (same URL); Back pops it and closes the
+     * sheet instead of navigating. This is also what makes "Back closes the TOPMOST overlay" work
+     * across types: entries are LIFO, so a sheet opened over a Dialog takes the Back press rather
+     * than letting it close the dialog underneath — but only because the sheet pushes one too.
+     */
+    closeOnNavigateBack?: boolean;
     /** Called after the sheet finishes closing. */
     onClose?: () => void;
     /** Called whenever the open state changes. */

package/dist/components/bottom-sheet/BottomSheet.svelte

@@ -1,7 +1,49 @@
+<script module lang="ts">"use strict";
+// ============================================
+// PAGE-ROOT OVERSCROLL GUARD (native pull-to-refresh)
+// ============================================
+// The two-phase drag doesn't preventDefault() until a gesture commits past the ~10px
+// activation threshold, so a SLOW downward pull that STARTS on an interactive element
+// (button / input / link / [tabindex]) leaves a window where the browser can claim the
+// gesture as native pull-to-refresh / overscroll-reload before the sheet does — which is
+// why only a *slow* pull triggers it (a quick flick clears the threshold on the first
+// touchmove and preventDefault()s first). `overscroll-behavior-y: contain` on the document
+// root closes that window for the sheet's whole open lifetime WITHOUT touching the gesture
+// logic. Shared + reference-counted across every mounted sheet so stacked sheets apply it
+// once and the page's original inline value is restored only when the last sheet releases.
+let overscrollGuardCount = 0;
+let savedRootOverscrollY = '';
+let savedBodyOverscrollY = '';
+function acquireOverscrollGuard() {
+    if (typeof document === 'undefined')
+        return;
+    if (overscrollGuardCount === 0) {
+        const root = document.documentElement;
+        const { body } = document;
+        savedRootOverscrollY = root.style.overscrollBehaviorY;
+        savedBodyOverscrollY = body.style.overscrollBehaviorY;
+        // Set both: browsers disagree on whether html or body is the root scroller.
+        root.style.overscrollBehaviorY = 'contain';
+        body.style.overscrollBehaviorY = 'contain';
+    }
+    overscrollGuardCount++;
+}
+function releaseOverscrollGuard() {
+    if (typeof document === 'undefined' || overscrollGuardCount === 0)
+        return;
+    overscrollGuardCount--;
+    if (overscrollGuardCount === 0) {
+        document.documentElement.style.overscrollBehaviorY = savedRootOverscrollY;
+        document.body.style.overscrollBehaviorY = savedBodyOverscrollY;
+    }
+}
+</script>
+
 <script lang="ts">import { onDestroy, onMount } from 'svelte';
 import { bottomSheetStore } from './bottomSheetStore.svelte.js';
 import { bottomSheetRecipe } from './BottomSheet.recipe';
 import { IconX } from "../../internal/icons";
+import { closeOnBackNavigation, overlayStack } from '../../hooks';
 // ============================================
 // CONFIGURABLE CONSTANTS
 // Adjust these values to customize the bottom sheet behavior
@@ -42,6 +84,7 @@ const CONFIG = {
         lockedDragResistance: 0.3, // Resistance when dragToClose disabled
         // Two-phase gesture recognition for interactive elements (iOS-style)
         dragActivationThreshold: 10, // Vertical px to commit to drag from interactive element
+        pullClaimThreshold: 3, // Vertical px to CLAIM the gesture (preventDefault) BEFORE commit, so iOS Safari can't start pull-to-refresh during a slow pull. Below dragActivationThreshold; tune on-device.
         horizontalDeadZone: 1.2, // If abs(dx)/abs(dy) > this, abort drag (let native horizontal win)
         tapDistanceThreshold: 6 // Max total movement (px) to still count as a tap
     }
@@ -49,7 +92,7 @@ const CONFIG = {
 // ============================================
 // COMPONENT PROPS
 // ============================================
-let { id, open = $bindable(false), snapPoints = [0.9], defaultSnapPoint = 0, containerRef = null, scaleTargetRef = null, constrainToContainer = false, scaleBackground = true, dragToClose = true, closeOnBackdrop = true, showCloseButton = false, syncThemeColor = true, onClose, onOpenChange, children, header } = $props();
+let { id, open = $bindable(false), snapPoints = [0.9], defaultSnapPoint = 0, containerRef = null, scaleTargetRef = null, constrainToContainer = false, scaleBackground = true, dragToClose = true, closeOnBackdrop = true, showCloseButton = false, syncThemeColor = true, preventPullToRefresh = true, closeOnNavigateBack = true, onClose, onOpenChange, children, header } = $props();
 // ============================================
 // INTERNAL STATE
 // ============================================
@@ -82,6 +125,10 @@ let scaleTargetPrimed = false; // static scale-target styles set once per open c
 // background) for the sheet's open lifetime and remove it on close; a page that sets its own
 // theme-color is left alone — Safari honors it, so the backdrop can't flip it.
 let themeColorMeta = null;
+// Whether THIS sheet currently holds the shared page-root overscroll guard (see the module
+// script). Kept per-instance so acquire/release stay balanced — restore is called from both
+// the close completion and onDestroy, and must be a no-op the second time.
+let heldOverscrollGuard = false;
 // Drag tracking
 let dragState = {
     startY: 0,
@@ -127,6 +174,17 @@ const allSnapPoints = $derived([0, ...snapPoints].sort((a, b) => a - b));
 // ============================================
 // LIFECYCLE
 // ============================================
+// Browser Back closes the sheet, so a sheet opened over a Dialog takes the Back press
+// instead of letting it close the dialog underneath (history entries are LIFO, so this
+// resolves "topmost wins" on its own — but only once every modal pushes one).
+// Setting `open = false` (rather than doClose()) keeps the single close path in the
+// `open` effect; the hook's teardown then fires at the END of the close spring, where
+// `poppedByBack` correctly suppresses the compensating history.back().
+closeOnBackNavigation({
+    enabled: () => closeOnNavigateBack,
+    isOpen: () => open,
+    close: () => { open = false; },
+});
 onMount(() => {
     bottomSheetStore.register(id, { snapPoints, defaultSnapPoint, closeOnBackdrop });
     window.addEventListener('resize', handleWindowResize);
@@ -139,6 +197,7 @@ onDestroy(() => {
     containerResizeObserver?.disconnect();
     cancelAnimations();
     restoreThemeColor();
+    restoreOverscrollGuard();
 });
 // Motion is driven by direct writes (drag) and Web Animations (open/close/snap), so keep
 // the recipe's CSS `transition` OFF on these elements — otherwise the CSS transition would
@@ -405,6 +464,7 @@ function doOpen() {
     isClosing = false;
     backdropPressPointerId = null; // fresh open — ignore any stale backdrop press id
     applyThemeColor(); // hold the iOS status bar at the page color before the backdrop darkens it
+    applyOverscrollGuard(); // stop the page pull-to-refresh from hijacking a slow drag off an interactive element
     bottomSheetStore.open(id);
     requestAnimationFrame(() => {
         // sheetRef is bound by this rAF tick.
@@ -433,6 +493,7 @@ function animateSheetClose(initialVelocity) {
         open = false;
         resetScaleTarget();
         restoreThemeColor();
+        restoreOverscrollGuard();
         onClose?.();
         onOpenChange?.(false);
     }, true); // hideOnArrival — finalize as soon as it's offscreen, no spring tail
@@ -536,6 +597,24 @@ function restoreThemeColor() {
     themeColorMeta?.remove();
     themeColorMeta = null;
 }
+/**
+ * Guard the page against native pull-to-refresh while this sheet is open (see the module
+ * script). Balanced + idempotent per instance so the shared reference count stays correct
+ * even though restore fires from both the close completion and onDestroy.
+ */
+function applyOverscrollGuard() {
+    if (!preventPullToRefresh || heldOverscrollGuard)
+        return;
+    heldOverscrollGuard = true;
+    acquireOverscrollGuard();
+}
+/** Release this sheet's hold on the page overscroll guard (no-op if not held). */
+function restoreOverscrollGuard() {
+    if (!heldOverscrollGuard)
+        return;
+    heldOverscrollGuard = false;
+    releaseOverscrollGuard();
+}
 // ============================================
 // GESTURE UTILITIES
 // ============================================
@@ -805,7 +884,26 @@ function handleTouchMove(e) {
             dragState.isInteractiveStart = false;
             return;
         }
-        // Still pending — do nothing, let native behavior continue
+        // Still pending (under the commit threshold). Claim a downward, vertical-leaning pull
+        // NOW so iOS Safari can't start its native pull-to-refresh during this slow pre-commit
+        // window — overscroll-behavior does NOT stop Safari's UA refresh; only preventDefault
+        // does. Stay PENDING (the sheet doesn't start moving until the >=10px commit), but deny
+        // the browser the gesture. Skip when a scroll region under the finger should scroll
+        // instead (pulling down while not at its top), and skip horizontal-leaning moves so
+        // native sliders keep working. Touch-only: desktop has no pull-to-refresh.
+        const claimDx = Math.abs(clientX - dragState.startX);
+        const claimDy = Math.abs(clientY - dragState.startY);
+        if (clientY - dragState.startY > 0 && claimDy >= CONFIG.gesture.pullClaimThreshold && claimDy >= claimDx) {
+            let claimGesture = true;
+            if (dragState.inScrollable) {
+                if (scrollableElement)
+                    isScrolledToTop = scrollableElement.scrollTop <= 1;
+                if (!isScrolledToTop)
+                    claimGesture = false; // let the content scroll natively
+            }
+            if (claimGesture && e.cancelable)
+                e.preventDefault();
+        }
         return;
     }
     // ── Normal drag logic (committed) ──
@@ -1004,8 +1102,19 @@ function handleBackdropClick(e) {
         return;
     doClose();
 }
+/**
+ * Escape — CAPTURE phase (see the `onkeydowncapture` binding below), which is load-bearing.
+ *
+ * Topmost is resolved across EVERY overlay type, not just among sheets: a Dialog opened
+ * from inside this sheet should take the keypress alone. But bits-ui listens on `document`
+ * while this listens on `window`, so on the bubble path bits-ui always runs FIRST — and
+ * Svelte flushes effects synchronously at the end of its handler, dropping the dialog from
+ * the stack. This handler would then find ITSELF topmost and close too: one Escape, both
+ * gone. Capturing at window means we run before anything else can mutate the stack, so the
+ * check reads the state as it was when the key was pressed.
+ */
 function handleKeydown(e) {
-    if (e.key === 'Escape' && isVisible && bottomSheetStore.isTopmost(id)) {
+    if (e.key === 'Escape' && isVisible && overlayStack.isTopmost(id)) {
         e.preventDefault();
         doClose();
     }
@@ -1025,7 +1134,7 @@ function touchEvents(node) {
 }
 </script>
 
-<svelte:window onkeydown={handleKeydown}/>
+<svelte:window onkeydowncapture={handleKeydown}/>
 
 {#if isVisible}
     <!-- Backdrop -->

package/dist/components/bottom-sheet/bottomSheetStore.svelte.d.ts

@@ -6,6 +6,28 @@
  * sheet is topmost (for Escape handling). Sheets register on mount and push/pop
  * themselves from the stack as they open/close. Exposed publicly so apps can
  * drive sheets programmatically (open/close/closeTop) in addition to `bind:open`.
+ *
+ * ## Now a SHEET-SCOPED VIEW over the shared overlay stack
+ *
+ * This store used to be the library's only runtime z authority, which is exactly why an
+ * overlay opened from inside a sheet (a `z-50` dialog vs. the sheet's 1001) painted behind
+ * it. Layering now lives in the shared `overlayStack` (`$lib/hooks`), which every
+ * portal-owning overlay registers with; this store keeps sheet-specific concerns (config,
+ * drag progress, container refs) and PROJECTS the shared stack down to just the sheets.
+ *
+ * The public API is unchanged. `stack` / `getStack` / `isTopmost` / `closeTop` /
+ * `hasOpenSheets` / `getCombinedBackdropOpacity` still mean "among bottom sheets".
+ *
+ * Two behavior notes:
+ * - `getZIndex` now returns a z resolved against ALL overlays, not just sheets. Ordering
+ *   between sheets is unchanged (still base + 10 per stacked sheet).
+ * - `close()` no longer reindexes the survivors, so a sheet's z can stay higher than its
+ *   position implies after a sheet below it closes. Relative ORDER is still exact; only the
+ *   absolute number differs. Reindexing live entries collides with close animations, which
+ *   paint for ~260ms after the entry is gone.
+ *
+ * For "topmost across ALL overlay types" (what Escape should use), read
+ * `overlayStack.isTopmost(id)` directly — `BottomSheet.svelte` does.
  */
 export interface BottomSheetConfig {
     id: string;
@@ -20,7 +42,12 @@ export interface SheetStackItem {
     config: BottomSheetConfig;
 }
 export declare const bottomSheetStore: {
-    readonly stack: SheetStackItem[];
+    readonly stack: {
+        id: string;
+        zIndex: number;
+        progress: number;
+        config: BottomSheetConfig;
+    }[];
     readonly hasOpenSheets: boolean;
     register: (id: string, config: Omit<BottomSheetConfig, "id">) => void;
     unregister: (id: string) => void;

package/dist/components/bottom-sheet/bottomSheetStore.svelte.js

@@ -6,16 +6,54 @@
  * sheet is topmost (for Escape handling). Sheets register on mount and push/pop
  * themselves from the stack as they open/close. Exposed publicly so apps can
  * drive sheets programmatically (open/close/closeTop) in addition to `bind:open`.
+ *
+ * ## Now a SHEET-SCOPED VIEW over the shared overlay stack
+ *
+ * This store used to be the library's only runtime z authority, which is exactly why an
+ * overlay opened from inside a sheet (a `z-50` dialog vs. the sheet's 1001) painted behind
+ * it. Layering now lives in the shared `overlayStack` (`$lib/hooks`), which every
+ * portal-owning overlay registers with; this store keeps sheet-specific concerns (config,
+ * drag progress, container refs) and PROJECTS the shared stack down to just the sheets.
+ *
+ * The public API is unchanged. `stack` / `getStack` / `isTopmost` / `closeTop` /
+ * `hasOpenSheets` / `getCombinedBackdropOpacity` still mean "among bottom sheets".
+ *
+ * Two behavior notes:
+ * - `getZIndex` now returns a z resolved against ALL overlays, not just sheets. Ordering
+ *   between sheets is unchanged (still base + 10 per stacked sheet).
+ * - `close()` no longer reindexes the survivors, so a sheet's z can stay higher than its
+ *   position implies after a sheet below it closes. Relative ORDER is still exact; only the
+ *   absolute number differs. Reindexing live entries collides with close animations, which
+ *   paint for ~260ms after the entry is gone.
+ *
+ * For "topmost across ALL overlay types" (what Escape should use), read
+ * `overlayStack.isTopmost(id)` directly — `BottomSheet.svelte` does.
  */
-const BASE_Z_INDEX = 1000;
-const Z_INDEX_INCREMENT = 10;
+import { SvelteMap } from 'svelte/reactivity';
+import { overlayStack } from '../../hooks/overlayStack.svelte.js';
+import { layer } from '../../tokens/index.js';
+const BASE_Z_INDEX = layer.base;
 function createBottomSheetStore() {
-    // Stack of active sheets (bottom to top)
-    let sheetStack = $state([]);
+    // SvelteMap, not `$state(new Map())`: `$state` proxies the object but NOT a Map's
+    // internals, so `.set()` on a plain $state Map notifies nobody — the `sheetStack`
+    // derived below would never see a config or progress change.
     // Registry of all sheet configs
-    let registry = $state(new Map());
-    // Container refs for scale effect
-    let containerRefs = $state(new Map());
+    const registry = new SvelteMap();
+    // Drag progress per sheet (0-1). Written ~120×/s during a drag; `sheetStack` is lazy, so
+    // this costs one signal write per frame unless something actually reads the stack.
+    const progressById = new SvelteMap();
+    // Container refs for scale effect. Plain Map — only ever read imperatively.
+    const containerRefs = new Map();
+    // The shared stack, projected down to just the sheets — bottom to top, in the shared
+    // stack's own order, so a sheet opened above another still reads as being above it.
+    const sheetStack = $derived(overlayStack.stack
+        .filter(item => item.kind === 'bottom-sheet' && registry.has(item.id))
+        .map(item => ({
+        id: item.id,
+        zIndex: item.zIndex,
+        progress: progressById.get(item.id) ?? 0,
+        config: registry.get(item.id)
+    })));
     /**
      * Register a sheet with its config
      */
@@ -28,41 +66,27 @@ function createBottomSheetStore() {
     function unregister(id) {
         registry.delete(id);
         containerRefs.delete(id);
+        progressById.delete(id);
         // Remove from stack if present
-        sheetStack = sheetStack.filter(s => s.id !== id);
+        overlayStack.remove(id);
     }
     /**
      * Open a sheet by ID
      */
     function open(id) {
-        const config = registry.get(id);
-        if (!config) {
+        if (!registry.has(id)) {
             // Sheet was not registered (component not mounted yet) — ignore.
             return;
         }
-        // Check if already in stack
-        if (sheetStack.some(s => s.id === id)) {
-            return;
-        }
-        // Calculate z-index based on stack position
-        const zIndex = BASE_Z_INDEX + (sheetStack.length * Z_INDEX_INCREMENT);
-        sheetStack = [...sheetStack, {
-                id,
-                zIndex,
-                progress: 0,
-                config
-            }];
+        // push() is idempotent — an already-open sheet keeps its z rather than jumping.
+        overlayStack.push(id, 'bottom-sheet');
     }
     /**
      * Close a sheet by ID
      */
     function close(id) {
-        sheetStack = sheetStack.filter(s => s.id !== id);
-        // Recalculate z-indices for remaining sheets
-        sheetStack = sheetStack.map((sheet, index) => ({
-            ...sheet,
-            zIndex: BASE_Z_INDEX + (index * Z_INDEX_INCREMENT)
-        }));
+        overlayStack.remove(id);
+        progressById.delete(id);
     }
     /**
      * Close the topmost sheet
@@ -77,27 +101,25 @@ function createBottomSheetStore() {
      * Update progress for a sheet (0-1)
      */
     function updateProgress(id, progress) {
-        const index = sheetStack.findIndex(s => s.id === id);
-        const sheet = sheetStack[index];
-        if (sheet) {
-            sheet.progress = Math.max(0, Math.min(1, progress));
-        }
+        if (!overlayStack.has(id))
+            return;
+        progressById.set(id, Math.max(0, Math.min(1, progress)));
     }
     /**
      * Get z-index for a sheet
      */
     function getZIndex(id) {
-        const sheet = sheetStack.find(s => s.id === id);
-        return sheet?.zIndex ?? BASE_Z_INDEX;
+        return overlayStack.getZIndex(id) ?? BASE_Z_INDEX;
     }
     /**
      * Check if a sheet is open
      */
     function isOpen(id) {
-        return sheetStack.some(s => s.id === id);
+        return overlayStack.has(id);
     }
     /**
-     * Check if a sheet is the topmost
+     * Check if a sheet is the topmost SHEET. For "topmost across every overlay type"
+     * (Escape, close-top), use `overlayStack.isTopmost(id)` instead.
      */
     function isTopmost(id) {
         return sheetStack[sheetStack.length - 1]?.id === id;
@@ -106,8 +128,7 @@ function createBottomSheetStore() {
      * Get progress for a sheet
      */
     function getProgress(id) {
-        const sheet = sheetStack.find(s => s.id === id);
-        return sheet?.progress ?? 0;
+        return progressById.get(id) ?? 0;
     }
     /**
      * Attach container ref for scale effect

package/dist/components/combobox/Combobox.svelte

@@ -3,9 +3,14 @@ import { comboboxRecipe } from './Combobox.recipe';
 import { cn } from '../../utils/utils.js';
 import { IconCheck, IconChevronDown } from '../../internal/icons';
 import IconX from '@tabler/icons-svelte/icons/x';
+import { overlayLayer, withZIndex } from '../../hooks';
 let { type, items = [], value = $bindable(undefined), placeholder = 'Search…', disabled, loop, allowDeselect, onchange, class: className, ref = $bindable(null), name, required, scrollAlignment, freeInput = false, checkIcon, chevronIcon, clearIcon, } = $props();
 let searchText = $state('');
 let open = $state(false);
+// Shared stacking authority — a combobox opened inside a Dialog/BottomSheet must land
+// above it, which its hardcoded z-50 could not do.
+const layer = overlayLayer({ isOpen: () => open, kind: 'menu' });
+const contentZIndex = $derived(layer.zIndex === undefined ? undefined : layer.zIndex + 1);
 const filteredItems = $derived(searchText.trim()
     ? items.filter(i => i.label.toLowerCase().includes(searchText.trim().toLowerCase()))
     : items);
@@ -118,6 +123,7 @@ const r = $derived(comboboxRecipe({ open, disabled }));
                     sideOffset={4}
                     customAnchor={ref}
                     class={r.content({class: 'min-w-[var(--bits-combobox-anchor-width)]'})}
+                    style={withZIndex(undefined, contentZIndex)}
                 >
                     <ComboboxPrimitive.Viewport class={r.viewport()}>
                         {#each filteredItems as item (item.value)}

package/dist/components/date-range-picker/DateRangePicker.svelte

@@ -8,6 +8,7 @@ import { cn } from '../../utils/utils.js';
 import { untrack } from 'svelte';
 import { innerWidth } from 'svelte/reactivity/window';
 import { Dialog } from '../dialog/index.js';
+import { overlayLayer, withZIndex } from '../../hooks';
 import { dateRangePickerRecipe } from './DateRangePicker.recipe.js';
 let { dateRange = $bindable([]), onchange, enableTime = false, placeholder = 'Select date range', disabled = false, class: className, minValue, maxValue, isDateDisabled, numberOfMonths: numberOfMonthsProp, weekStartsOn, calendarIcon, clearIcon, prevIcon, nextIcon, closeIcon, } = $props();
 const styles = dateRangePickerRecipe();
@@ -181,6 +182,12 @@ const iconBtnStyles = styles.iconBtn();
 const segmentStyles = styles.segment();
 const dayStyles = styles.day();
 const popoverContentStyles = styles.panel();
+// Shared stacking authority — gated on the DESKTOP branch only. On mobile this component
+// renders a real <Dialog>, which registers itself; a second entry here would own no
+// element to receive z (the `panel` slot only exists on the desktop popover) while still
+// consuming a stack slot and shifting every later overlay's depth for nothing.
+const layer = overlayLayer({ isOpen: () => open && isDesktop, kind: 'popover' });
+const panelZIndex = $derived(layer.zIndex === undefined ? undefined : layer.zIndex + 1);
 </script>
 
 <!-- ─── Shared snippets ──────────────────────────────────────────────────── -->
@@ -378,7 +385,13 @@ const popoverContentStyles = styles.panel();
             </PopoverPrimitive.Trigger>
 
             <PopoverPrimitive.Portal>
-                <PopoverPrimitive.Content sideOffset={4} align="start" class={popoverContentStyles}>
+                <PopoverPrimitive.Content
+                        sideOffset={4}
+                        align="start"
+                        class={popoverContentStyles}
+                        style={withZIndex(undefined, panelZIndex)}
+                        escapeKeydownBehavior={layer.isTopmost ? 'close' : 'ignore'}
+                >
                     <div class="flex">
                         <!-- Quick-select sidebar -->
                         <div class={styles.presetSidebar()}>

package/dist/components/dialog/Dialog.svelte

@@ -2,8 +2,14 @@
 import { dialogRecipe } from './Dialog.recipe';
 import { IconX } from '../../internal/icons';
 import { cn } from '../../utils/index.js';
-import { closeOnBackNavigation } from '../../hooks';
+import { closeOnBackNavigation, overlayLayer, withZIndex } from '../../hooks';
 let { children, open = $bindable(false), ref = $bindable(null), closeOnClickOutside = true, closeOnNavigateBack = true, closeButton = true, size = 'sm', header, footer, class: className, position = 'center', padding, staticRender = false, preventScroll, onOpenChangeComplete, triggerRef, focusTriggerAfterClose = true, containerClass, headerClass, bodyClass, footerClass, closeIcon, ...props } = $props();
+// Registers with the shared stacking authority so a dialog opened from INSIDE another
+// layered surface (the canonical case: a BottomSheet at z 1000/1001) lands above it
+// instead of losing the race with its own hardcoded z-50. Undefined until first open, so
+// SSR / never-opened dialogs keep the recipe's class exactly as before.
+const layer = overlayLayer({ isOpen: () => open, kind: 'dialog' });
+const contentZIndex = $derived(layer.zIndex === undefined ? undefined : layer.zIndex + 1);
 const isFull = $derived(size === 'full');
 const r = $derived(dialogRecipe({
     size,
@@ -27,7 +33,7 @@ closeOnBackNavigation({
 <DialogPrimitive.Root bind:open onOpenChangeComplete={onOpenChangeComplete}>
     <DialogPrimitive.Portal>
         <!-- Backdrop -->
-        <DialogPrimitive.Overlay class={r.overlay()} />
+        <DialogPrimitive.Overlay class={r.overlay()} style={withZIndex(undefined, layer.zIndex)} />
 
         <!--
             We use the `child` snippet (bits-ui "asChild" pattern) so that bits-ui gates its
@@ -40,12 +46,19 @@ closeOnBackNavigation({
             forceMount={staticRender || undefined}
             interactOutsideBehavior={closeOnClickOutside ? 'close' : 'ignore'}
             preventScroll={preventScroll}
+            escapeKeydownBehavior={layer.isTopmost ? 'close' : 'ignore'}
             onCloseAutoFocus={handleCloseAutoFocus}
             {...props}
         >
             {#snippet child({ props: contentProps })}
+                <!--
+                    `style:z-index` (a directive, not an attribute) so it merges with — rather
+                    than clobbers — whatever bits-ui and the app put in `style`, and wins over
+                    the recipe's z-50 class. To override it from an app, use `z-[…]!`.
+                -->
                 <div
                     {...contentProps}
+                    style:z-index={contentZIndex}
                     inert={staticRender && !open ? true : undefined}
                     class={cn(
                         contentProps.class,

package/dist/components/drawer/Drawer.svelte

@@ -1,24 +1,46 @@
 <script lang="ts">import { drawerRecipe } from './Drawer.recipe';
+import { overlayLayer } from '../../hooks';
 let { open = $bindable(false), side = 'right', size = 'md', closeOnClickOutside = true, header, footer, children, closeIcon, onclose, } = $props();
+// Shared stacking authority. The drawer renders IN PLACE (no portal), but it still takes
+// a slot so overlays opened from inside it stack above, and so Escape can resolve a
+// single topmost across every overlay type.
+const layer = overlayLayer({ isOpen: () => open, kind: 'drawer' });
+const contentZIndex = $derived(layer.zIndex === undefined ? undefined : layer.zIndex + 1);
 const r = $derived(drawerRecipe({ side, size }));
 function close() {
     open = false;
     onclose?.();
 }
+// Escape was documented on `closeOnClickOutside` but never actually worked: the handler
+// lived on a <div role="presentation"> with no tabindex, which can't receive keydown.
+// It has to work now — a registered surface that swallows its slot without honouring
+// Escape would turn Escape off for everything beneath it (bits-ui overlays below defer
+// to whoever is topmost). Window CAPTURE + topmost-gated, mirroring BottomSheet: capture
+// runs before bits-ui's document listener, so `isTopmost` is read as of the keypress
+// rather than after another overlay has already closed and left this one on top.
+function handleKeydown(e) {
+    if (e.key === 'Escape' && open && closeOnClickOutside && layer.isTopmost) {
+        e.preventDefault();
+        close();
+    }
+}
 </script>
 
+<svelte:window onkeydowncapture={handleKeydown}/>
+
 {#if open}
     <!-- Backdrop -->
     <div
         role="presentation"
         class={r.overlay()}
+        style:z-index={layer.zIndex}
         onclick={() => closeOnClickOutside && close()}
-        onkeydown={(e) => e.key === 'Escape' && closeOnClickOutside && close()}
     ></div>
 
     <!-- Drawer panel -->
     <div
         class={r.content()}
+        style:z-index={contentZIndex}
         role="dialog"
         aria-modal="true"
     >

package/dist/components/dropdown-menu/components/DropdownMenu.svelte

@@ -1,6 +1,11 @@
 <script lang="ts">import { DropdownMenu as DropdownMenuPrimitive } from 'bits-ui';
 import { dropdownMenuRecipe } from '../DropdownMenu.recipe';
+import { overlayLayer, withZIndex } from '../../../hooks';
 let { children, trigger, class: className, open = $bindable(false), side = 'bottom', sideOffset = 4, align = 'start', loop, preventScroll, ...props } = $props();
+// Shared stacking authority — a menu opened from inside a Dialog or BottomSheet must
+// land above it, which its hardcoded z-50 could not do.
+const layer = overlayLayer({ isOpen: () => open, kind: 'menu' });
+const contentZIndex = $derived(layer.zIndex === undefined ? undefined : layer.zIndex + 1);
 const r = dropdownMenuRecipe();
 </script>
 
@@ -22,8 +27,10 @@ const r = dropdownMenuRecipe();
             {align}
             {loop}
             {preventScroll}
+            escapeKeydownBehavior={layer.isTopmost ? 'close' : 'ignore'}
             {...props}
             class={r.content({ class: className })}
+            style={withZIndex(props.style, contentZIndex)}
         >
             {@render children?.()}
         </DropdownMenuPrimitive.Content>

package/dist/components/popover/Popover.svelte

@@ -1,6 +1,12 @@
 <script lang="ts">import { Popover as PopoverPrimitive } from 'bits-ui';
 import { popoverRecipe } from './Popover.recipe';
+import { overlayLayer, withZIndex } from '../../hooks';
 let { children, trigger, class: className, open = $bindable(false), side = 'bottom', sideOffset = 4, align = 'start', alignOffset, closeOnClickOutside = true, closeOnEscape = true, trapFocus, preventScroll, onInteractOutside, ref = $bindable(null), ...props } = $props();
+// Shared stacking authority — a popover opened from inside a BottomSheet must land above
+// it rather than behind, which its hardcoded z-50 could never do. Content sits at z+1,
+// the slot's content rung (backdrop-owning overlays put their backdrop on z).
+const layer = overlayLayer({ isOpen: () => open, kind: 'popover' });
+const contentZIndex = $derived(layer.zIndex === undefined ? undefined : layer.zIndex + 1);
 const r = $derived(popoverRecipe());
 </script>
 
@@ -25,10 +31,11 @@ const r = $derived(popoverRecipe());
             {trapFocus}
             {preventScroll}
             interactOutsideBehavior={closeOnClickOutside ? 'close' : 'ignore'}
-            escapeKeydownBehavior={closeOnEscape ? 'close' : 'ignore'}
+            escapeKeydownBehavior={closeOnEscape && layer.isTopmost ? 'close' : 'ignore'}
             onInteractOutside={() => onInteractOutside?.()}
             class={r.content({ class: className })}
             {...props}
+            style={withZIndex(props.style, contentZIndex)}
         >
             {@render children?.()}
         </PopoverPrimitive.Content>