tera-system-ui 0.2.3 → 0.2.5

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

@@ -130,6 +130,15 @@ export interface BottomSheetProps {
      * 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

@@ -43,6 +43,7 @@ function releaseOverscrollGuard() {
 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
@@ -91,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, preventPullToRefresh = 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
 // ============================================
@@ -173,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);
@@ -1090,11 +1102,31 @@ 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))
+        return;
+    // dragToClose=false locks the sheet against user dismissal: if a drag can't close it,
+    // Escape shouldn't either. Still swallow the key (preventDefault + stopPropagation) so a
+    // locked topmost sheet ABSORBS Escape instead of letting it fall through and close an
+    // overlay beneath it — the sheet on top owns the keypress.
+    if (!dragToClose) {
         e.preventDefault();
-        doClose();
+        e.stopPropagation();
+        return;
     }
+    e.preventDefault();
+    doClose();
 }
 // Svelte action for touch events
 function touchEvents(node) {
@@ -1111,7 +1143,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>

package/dist/components/select/Select.svelte

@@ -3,6 +3,7 @@ import { selectRecipe } from './Select.recipe';
 import { IconCheck, IconChevronDown } from '../../internal/icons';
 import IconChevronsUp from '@tabler/icons-svelte/icons/chevrons-up';
 import IconChevronsDown from '@tabler/icons-svelte/icons/chevrons-down';
+import { overlayLayer, withZIndex } from '../../hooks';
 let { type = 'single', options = [], groups, value = $bindable(), placeholder = 'Select…', variant, size, disabled, status, loop, allowDeselect, required, name, class: className, checkIcon, onchange, } = $props();
 // All options flat — used for label lookup in multiple mode
 const allOptions = $derived(groups ? groups.flatMap(g => g.options) : options);
@@ -18,7 +19,16 @@ const selectedChips = $derived(Array.isArray(value)
     ? value.map(v => ({ value: v, label: allOptions.find(o => o.value === v)?.label ?? v }))
     : []);
 const r = $derived(selectRecipe({ variant, size, disabled, status }));
+// Internal only — Select exposes no `open` prop, but the shared stacking authority needs
+// to know when the listbox is up so a Select inside a Dialog/BottomSheet lands above it
+// instead of behind. `bind:open` on SelectPrimitive.Root is purely observational here.
+let open = $state(false);
+const layer = overlayLayer({ isOpen: () => open, kind: 'menu' });
+const contentZIndex = $derived(layer.zIndex === undefined ? undefined : layer.zIndex + 1);
 const minHeight = "21rem";
+// The content already carries a `style` (max-height); z-index must be CONCATENATED onto
+// it, not added as a second `style` attribute.
+const contentStyle = $derived(withZIndex(`max-height: min(${minHeight}, var(--bits-select-content-available-height))`, contentZIndex));
 </script>
 
 {#snippet itemList()}
@@ -48,6 +58,7 @@ const minHeight = "21rem";
     <SelectPrimitive.Root
         type="multiple"
         bind:value={value as string[] | undefined}
+        bind:open
         onValueChange={(v) => onchange?.(v)}
         {disabled}
         {loop}
@@ -79,7 +90,7 @@ const minHeight = "21rem";
             <SelectPrimitive.Content
                 sideOffset={4}
                 class={r.content()}
-                style="max-height: min({minHeight}, var(--bits-select-content-available-height))"
+                style={contentStyle}
             >
                 <SelectPrimitive.ScrollUpButton class="flex w-full items-center justify-center pt-1 text-text-tertiary cursor-default hover:text-text-primary transition-colors">
                     <IconChevronsUp class="size-3.5" />
@@ -96,6 +107,7 @@ const minHeight = "21rem";
     <SelectPrimitive.Root
         type="single"
         bind:value={value as string | undefined}
+        bind:open
         onValueChange={(v) => onchange?.(v)}
         {disabled}
         {loop}
@@ -116,7 +128,7 @@ const minHeight = "21rem";
             <SelectPrimitive.Content
                 sideOffset={6}
                 class={r.content()}
-                style="max-height: min({minHeight}, var(--bits-select-content-available-height))"
+                style={contentStyle}
             >
                 <SelectPrimitive.ScrollUpButton class="flex w-full items-center justify-center pt-1 text-text-tertiary cursor-default hover:text-text-primary transition-colors">
                     <IconChevronsUp class="size-3.5" />

package/dist/components/toast/ToastContainer.svelte

@@ -12,10 +12,17 @@ const iconSymbol = {
 };
 </script>
 
+<!--
+    z-[8000] = the PINNED toast layer (`layer.toast` in tera-system-ui/tokens — keep in sync;
+    Tailwind can only emit a class it reads as literal text). Toasts don't register with the
+    overlay stack: a notification must sit above modals regardless of open order, so ordering
+    it by open time would be wrong. It was z-[60], which put it BEHIND an open BottomSheet
+    (z 1000/1001) — a toast fired over a sheet was simply invisible. It now floats above.
+-->
 <div
     aria-live="polite"
     aria-label="Notifications"
-    class="fixed bottom-4 right-4 z-[60] flex flex-col gap-2 max-sm:right-1/2 max-sm:translate-x-1/2"
+    class="fixed bottom-4 right-4 z-[8000] flex flex-col gap-2 max-sm:right-1/2 max-sm:translate-x-1/2"
 >
     {#each toast.items as item (item.id)}
         <div

package/dist/components/tooltip/Tooltip.recipe.js

@@ -17,7 +17,12 @@ import { tv } from "tailwind-variants";
 export const tooltipRecipe = tv({
     slots: {
         trigger: 'inline-flex',
-        content: `z-50 max-w-[220px] px-2.5 py-1.5 text-xs leading-snug font-mono font-medium tracking-tight rounded-[var(--tera-tooltip-radius,var(--tera-radius-sm))]
+        // z-[9000] = the PINNED tooltip layer (`layer.tooltip` in tera-system-ui/tokens —
+        // keep in sync; Tailwind can only emit a class it reads as literal text). Tooltips
+        // don't register with the overlay stack: they're transient, pointer-events:none
+        // chrome that belongs above any modal regardless of open order, so ordering them by
+        // open time would be meaningless. 9000 stays clear of third-party peaks (~10000).
+        content: `z-[9000] max-w-[220px] px-2.5 py-1.5 text-xs leading-snug font-mono font-medium tracking-tight rounded-[var(--tera-tooltip-radius,var(--tera-radius-sm))]
                     bg-neutral-token-13 text-neutral-token-1 shadow-lg
                     animate-in fade-in zoom-in-95 duration-[var(--tera-duration-fast)] ease-ui
                     data-[state=closed]:animate-out data-[state=closed]:fade-out data-[state=closed]:zoom-out-95`,

package/dist/hooks/index.d.ts

@@ -1 +1,5 @@
 export { closeOnBackNavigation } from './closeOnBackNavigation.svelte';
+export { overlayStack } from './overlayStack.svelte.js';
+export type { OverlayKind, OverlayStackItem } from './overlayStack.svelte.js';
+export { overlayLayer, withZIndex } from './overlayLayer.svelte.js';
+export type { OverlayLayer } from './overlayLayer.svelte.js';

package/dist/hooks/index.js

@@ -1 +1,4 @@
 export { closeOnBackNavigation } from './closeOnBackNavigation.svelte';
+// The layering scale itself lives in the token contract: `tera-system-ui/tokens` → `layer`.
+export { overlayStack } from './overlayStack.svelte.js';
+export { overlayLayer, withZIndex } from './overlayLayer.svelte.js';

package/dist/hooks/overlayLayer.svelte.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Registers a layered surface with the shared {@link overlayStack} and reports the z-index
+ * it should paint at.
+ *
+ * Call once per surface that OWNS A PORTAL, from a component init scope:
+ *
+ *   const layer = overlayLayer({ isOpen: () => open, kind: 'dialog' });
+ *   // ...then apply layer.zIndex inline (style:z-index, or withZIndex for a bits-ui prop)
+ *
+ * Wrappers that merely delegate to another Tera overlay (PopoverResponsive, and
+ * DateRangePicker's mobile branch, which both render a real `<Dialog>`) must NOT call this —
+ * the child already registers, and a wrapper entry would consume a stack slot while owning
+ * no element to receive z, shifting every later overlay's depth for nothing.
+ *
+ * Must live in a `.svelte.ts` module so it can use `$effect`.
+ */
+import { type OverlayKind } from './overlayStack.svelte.js';
+export interface OverlayLayer {
+    /** The z to paint at, or `undefined` before this surface has ever opened (→ use the recipe's class). */
+    readonly zIndex: number | undefined;
+    /** Whether this surface is the topmost open overlay of ANY type. Drives Escape. */
+    readonly isTopmost: boolean;
+}
+export declare function overlayLayer(opts: {
+    /** Stable id. Defaults to an auto-generated one; pass it only if you already have one (BottomSheet). */
+    id?: string;
+    /** Current open state of the surface. */
+    isOpen: () => boolean;
+    /** Which family this surface belongs to. */
+    kind?: OverlayKind;
+}): OverlayLayer;
+/**
+ * Merge a runtime z-index into an existing `style` string.
+ *
+ * For bits-ui components, which take `style` as a PROP (so Svelte's `style:z-index`
+ * directive isn't available). Needed because several call sites spread `{...props}` last —
+ * a bare `style={...}` before the spread would be clobbered by an app-supplied one — and
+ * because Select's content already carries a `style` that must be concatenated, not
+ * duplicated. Apply AFTER the rest-spread.
+ *
+ * Returns `style` untouched when `z` is undefined (surface not open → recipe class stands).
+ */
+export declare function withZIndex(style: unknown, z: number | undefined): string | undefined;