tera-system-ui 0.2.2 → 0.2.4

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;

package/dist/hooks/overlayLayer.svelte.js

@@ -0,0 +1,74 @@
+/**
+ * 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 { untrack } from 'svelte';
+import { overlayStack } from './overlayStack.svelte.js';
+// Module scope, monotonic per page load. NOT `$props.id()`: that rune is component-only and
+// is a hard compile error (`props_id_invalid_placement`) inside a `.svelte.ts` module.
+// Mirrors the counter in closeOnBackNavigation.svelte.ts.
+let counter = 0;
+export function overlayLayer(opts) {
+    const id = opts.id ?? `tera-overlay-${++counter}`;
+    // Non-reactive (the `poppedByBack` pattern from closeOnBackNavigation): the z this
+    // surface was last assigned. A bits-ui exit animation keeps painting for ~200ms AFTER
+    // `open` flips false and the entry is gone; without this the element would snap back to
+    // its recipe fallback (z-50) mid-fade and flash behind whatever it was sitting above.
+    // Safe as a plain `let` because z is assigned once and never changes while open, so this
+    // can never disagree with a live entry — and it is always written before the store
+    // invalidation that makes `getZIndex` return undefined.
+    // Stays `undefined` until the first open, so a never-opened surface gets NO inline z and
+    // its recipe class stands (which is also what SSR renders — effects don't run there).
+    let lastZIndex;
+    // A plain `$effect`, not `$effect.pre`: bits-ui's Portal mounts inside runed's `watch()`,
+    // which is a POST effect, so portal DOM can never exist before this has run. There is no
+    // first-paint flash to guard against.
+    //
+    // `untrack` is load-bearing, not defensive. push() READS the stack (to find the current
+    // top) and WRITES it — so without untrack this effect depends on the very state it
+    // mutates and re-runs itself forever (`effect_update_depth_exceeded`), which is doubly
+    // wrong here because the re-run would also re-push and hand out a new z. The ONLY thing
+    // this effect may depend on is `isOpen()`.
+    $effect(() => {
+        if (!opts.isOpen())
+            return;
+        untrack(() => {
+            lastZIndex = overlayStack.push(id, opts.kind);
+        });
+        // Runs on close AND on unmount — no leaks.
+        return () => untrack(() => overlayStack.remove(id));
+    });
+    return {
+        get zIndex() { return overlayStack.getZIndex(id) ?? lastZIndex; },
+        get isTopmost() { return overlayStack.isTopmost(id); },
+    };
+}
+/**
+ * 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 function withZIndex(style, z) {
+    const base = typeof style === 'string' ? style.trim().replace(/;$/, '') : undefined;
+    if (z === undefined)
+        return base || undefined;
+    return base ? `${base};z-index:${z}` : `z-index:${z}`;
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Overlay stacking authority — Svelte 5 runes singleton.
+ *
+ * THE single source of truth for how layered surfaces stack. Every overlay that owns a
+ * portal (dialog, drawer, bottom-sheet, popover, dropdown-menu, select, combobox,
+ * date-range-picker) pushes itself here on open and is removed on close/destroy; the z it
+ * gets back is applied as an INLINE z-index. That makes stacking deterministic and
+ * "last-opened is on top" for arbitrary nesting and mixed types — a dialog opened from
+ * inside a bottom sheet lands above it, which is the bug this exists to kill.
+ *
+ * WHY IT LIVES IN `hooks/` AND NOT `components/`: `scripts/tera-ui.mjs` COPIES component
+ * deps into a consuming app but only ever REWRITES `$lib/hooks` to the package path. A
+ * copied stacking store would mean two singletons, two stacks, and the bug straight back.
+ * This module must be shared, never copied.
+ *
+ * ## The scale
+ *
+ * | Layer                    | z                      |
+ * |--------------------------|------------------------|
+ * | interactive overlays     | 1000 + n*10 (≤ 7900)   |
+ * | toast (pinned)           | 8000                   |
+ * | tooltip (pinned)         | 9000                   |
+ * | third-party (MathLive VK)| ~10000 — headroom kept |
+ *
+ * Base 1000 clears typical app chrome and is byte-identical to the sheet formula this
+ * generalizes. Toast and tooltip are PINNED and never register: they are non-competing
+ * chrome that must always sit above the stack, so open-order is meaningless for them.
+ * Tiers are otherwise deliberately collapsed — among portal-owning overlays, open-order
+ * alone already yields the intuitive answer for every nesting case, so a tier base would
+ * only add machinery that never changes a result.
+ *
+ * ## z is assigned ONCE at push and never reindexed
+ *
+ * `z = max(base, topZ + step)`. Reindexing survivors on removal (what the sheet store used
+ * to do) collides with exit animations: a surface that is mid-fade still paints at the z it
+ * was given, and live entries shifting underneath it can tie or overtake it. Assign-once is
+ * self-bounding anyway — closing the top frees that z for the next push — so the ratchet
+ * can't run away.
+ *
+ * SSR-safe: no `window`/`document` at module load. Surfaces register on mount only.
+ */
+/** Which family a surface belongs to. Only used to project sheet-scoped views today. */
+export type OverlayKind = 'bottom-sheet' | 'dialog' | 'drawer' | 'popover' | 'menu' | 'other';
+export interface OverlayStackItem {
+    id: string;
+    zIndex: number;
+    kind: OverlayKind;
+}
+/** The shared singleton. */
+export declare const overlayStack: {
+    /** The live stack, bottom to top. Readonly — mutate via push/remove. */
+    readonly stack: OverlayStackItem[];
+    readonly hasOpenOverlays: boolean;
+    push: (id: string, kind?: OverlayKind) => number;
+    remove: (id: string) => void;
+    getZIndex: (id: string) => number | undefined;
+    has: (id: string) => boolean;
+    isTopmost: (id: string) => boolean;
+};

package/dist/hooks/overlayStack.svelte.js

@@ -0,0 +1,107 @@
+/**
+ * Overlay stacking authority — Svelte 5 runes singleton.
+ *
+ * THE single source of truth for how layered surfaces stack. Every overlay that owns a
+ * portal (dialog, drawer, bottom-sheet, popover, dropdown-menu, select, combobox,
+ * date-range-picker) pushes itself here on open and is removed on close/destroy; the z it
+ * gets back is applied as an INLINE z-index. That makes stacking deterministic and
+ * "last-opened is on top" for arbitrary nesting and mixed types — a dialog opened from
+ * inside a bottom sheet lands above it, which is the bug this exists to kill.
+ *
+ * WHY IT LIVES IN `hooks/` AND NOT `components/`: `scripts/tera-ui.mjs` COPIES component
+ * deps into a consuming app but only ever REWRITES `$lib/hooks` to the package path. A
+ * copied stacking store would mean two singletons, two stacks, and the bug straight back.
+ * This module must be shared, never copied.
+ *
+ * ## The scale
+ *
+ * | Layer                    | z                      |
+ * |--------------------------|------------------------|
+ * | interactive overlays     | 1000 + n*10 (≤ 7900)   |
+ * | toast (pinned)           | 8000                   |
+ * | tooltip (pinned)         | 9000                   |
+ * | third-party (MathLive VK)| ~10000 — headroom kept |
+ *
+ * Base 1000 clears typical app chrome and is byte-identical to the sheet formula this
+ * generalizes. Toast and tooltip are PINNED and never register: they are non-competing
+ * chrome that must always sit above the stack, so open-order is meaningless for them.
+ * Tiers are otherwise deliberately collapsed — among portal-owning overlays, open-order
+ * alone already yields the intuitive answer for every nesting case, so a tier base would
+ * only add machinery that never changes a result.
+ *
+ * ## z is assigned ONCE at push and never reindexed
+ *
+ * `z = max(base, topZ + step)`. Reindexing survivors on removal (what the sheet store used
+ * to do) collides with exit animations: a surface that is mid-fade still paints at the z it
+ * was given, and live entries shifting underneath it can tie or overtake it. Assign-once is
+ * self-bounding anyway — closing the top frees that z for the next push — so the ratchet
+ * can't run away.
+ *
+ * SSR-safe: no `window`/`document` at module load. Surfaces register on mount only.
+ */
+import { layer } from '../tokens/index.js';
+function createOverlayStack() {
+    // Ordered by push time. Because every push takes `topZ + step`, array order is always
+    // ascending z — so "last element" IS "topmost", with no re-sorting needed.
+    let stack = $state([]);
+    /** Highest z currently held, or `base - step` when empty (so the next push lands on base). */
+    function topZIndex() {
+        let max = layer.base - layer.step;
+        for (const item of stack) {
+            if (item.zIndex > max)
+                max = item.zIndex;
+        }
+        return max;
+    }
+    /**
+     * Add a surface to the top of the stack and return the z it owns for its lifetime.
+     * Idempotent: pushing an id that is already present returns its existing z rather than
+     * jumping it to the top.
+     */
+    function push(id, kind = 'other') {
+        const existing = stack.find(item => item.id === id);
+        if (existing)
+            return existing.zIndex;
+        const raw = Math.max(layer.base, topZIndex() + layer.step);
+        const zIndex = Math.min(layer.ceiling, raw);
+        if (raw > layer.ceiling) {
+            // Needs ~690 simultaneously-open overlays to reach. If it ever fires, ordering
+            // degrades to DOM order at the top of the stack rather than silently inverting.
+            console.warn(`[tera-ui] overlay stack saturated at z-index ${layer.ceiling}; ` +
+                `stacking order above this point falls back to DOM order.`);
+        }
+        stack = [...stack, { id, zIndex, kind }];
+        return zIndex;
+    }
+    /** Remove a surface. Survivors KEEP their z — see the assign-once note above. */
+    function remove(id) {
+        stack = stack.filter(item => item.id !== id);
+    }
+    /** The z a surface owns, or `undefined` if it is not open (→ caller falls back to its recipe class). */
+    function getZIndex(id) {
+        return stack.find(item => item.id === id)?.zIndex;
+    }
+    /** Whether a surface is open. */
+    function has(id) {
+        return stack.some(item => item.id === id);
+    }
+    /**
+     * Whether a surface is the topmost open overlay OF ANY TYPE. This is what should drive
+     * Escape / close-top, so a sheet and a dialog can't both claim the keypress.
+     */
+    function isTopmost(id) {
+        return stack[stack.length - 1]?.id === id;
+    }
+    return {
+        /** The live stack, bottom to top. Readonly — mutate via push/remove. */
+        get stack() { return stack; },
+        get hasOpenOverlays() { return stack.length > 0; },
+        push,
+        remove,
+        getZIndex,
+        has,
+        isTopmost,
+    };
+}
+/** The shared singleton. */
+export const overlayStack = createOverlayStack();

package/dist/llms/bottom-sheet.md

@@ -28,6 +28,8 @@ BottomSheet recipe — the canonical styled layer for the draggable sheet. An iO
   dragToClose               boolean                                 optional  Allow dragging down past the lowest snap point to close.
   closeOnBackdrop           boolean                                 optional  Close when the backdrop is tapped.
   showCloseButton           boolean                                 optional  Show a close (X) button in the header (requires the `header` snippet).
+  syncThemeColor            boolean                                 optional  Keep the browser UI tint (iOS Safari status bar / Android address bar) matching the page while the sheet is open. The full-screen backdrop darkens the area behind the status bar; iOS Safari, when the page declares no `<meta name="theme-color">`, re-samples that area and flips the status bar dark — losing the immersive look. When true (the default) the sheet, only if the page has no `theme-color` of its own, adds one pinned to the page background for its open lifetime and removes it on close. A page that sets its own tint is left untouched.
+  preventPullToRefresh      boolean                                 optional  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.
   onClose                   () => void                              optional  Called after the sheet finishes closing.
   onOpenChange              (open: boolean) => void                 optional  Called whenever the open state changes.
   children                  Snippet                                 optional  Main body content.

package/dist/tokens/index.d.ts

@@ -72,6 +72,40 @@ export declare const token: {
         readonly display: string;
     };
 };
+/**
+ * Layering scale — the shared z-index contract every layered surface resolves against.
+ *
+ * There is exactly ONE stacking authority (`overlayStack`, see `tera-system-ui/hooks`).
+ * Overlays that own a portal push themselves onto it on open and are assigned
+ * `base + n*step` (clamped to `ceiling`) as an INLINE z-index, so "last-opened is on top"
+ * holds for arbitrary nesting and mixed types. `toast` and `tooltip` are PINNED above the
+ * stack — they're non-competing chrome, so open-order is meaningless for them.
+ *
+ *   overlays  1000, 1010, 1020 … ≤ 7900   (backdrop = z, content = z + 1)
+ *   toast     8000
+ *   tooltip   9000
+ *   ~10000    third-party peaks (e.g. a MathLive virtual keyboard) — headroom kept, so an
+ *             input that owns its own keyboard still layers above our overlays.
+ *
+ * `base` is high enough to clear typical app chrome. Plain numbers, not CSS vars: z is
+ * assigned at runtime from a live stack, not by the cascade.
+ *
+ * NOTE: the pinned layers are also written as LITERAL Tailwind classes in
+ * `Tooltip.recipe.ts` (`z-[9000]`) and `ToastContainer.svelte` (`z-[8000]`) — Tailwind only
+ * emits utilities it can read as text, so it cannot see these constants. Keep them in sync.
+ */
+export declare const layer: {
+    /** First interactive overlay. */
+    readonly base: 1000;
+    /** Gap between stacked overlays — leaves room for backdrop `z` + content `z+1`. */
+    readonly step: 10;
+    /** Ratchet clamp; stays below `toast` so a saturated stack can never bury chrome. */
+    readonly ceiling: 7900;
+    /** Pinned: notifications sit above modals regardless of open order. */
+    readonly toast: 8000;
+    /** Pinned: transient, pointer-events:none, always on top. */
+    readonly tooltip: 9000;
+};
 /**
  * Per-component override hooks — the raw CSS custom-property names. Set these
  * (not the values above) to restyle a single component's internals. Each
@@ -166,3 +200,4 @@ export declare const componentVars: {
 };
 export type Token = typeof token;
 export type ComponentVars = typeof componentVars;
+export type Layer = typeof layer;

package/dist/tokens/index.js

@@ -79,6 +79,40 @@ export const token = {
         display: cssVar("--font-display"),
     },
 };
+/**
+ * Layering scale — the shared z-index contract every layered surface resolves against.
+ *
+ * There is exactly ONE stacking authority (`overlayStack`, see `tera-system-ui/hooks`).
+ * Overlays that own a portal push themselves onto it on open and are assigned
+ * `base + n*step` (clamped to `ceiling`) as an INLINE z-index, so "last-opened is on top"
+ * holds for arbitrary nesting and mixed types. `toast` and `tooltip` are PINNED above the
+ * stack — they're non-competing chrome, so open-order is meaningless for them.
+ *
+ *   overlays  1000, 1010, 1020 … ≤ 7900   (backdrop = z, content = z + 1)
+ *   toast     8000
+ *   tooltip   9000
+ *   ~10000    third-party peaks (e.g. a MathLive virtual keyboard) — headroom kept, so an
+ *             input that owns its own keyboard still layers above our overlays.
+ *
+ * `base` is high enough to clear typical app chrome. Plain numbers, not CSS vars: z is
+ * assigned at runtime from a live stack, not by the cascade.
+ *
+ * NOTE: the pinned layers are also written as LITERAL Tailwind classes in
+ * `Tooltip.recipe.ts` (`z-[9000]`) and `ToastContainer.svelte` (`z-[8000]`) — Tailwind only
+ * emits utilities it can read as text, so it cannot see these constants. Keep them in sync.
+ */
+export const layer = {
+    /** First interactive overlay. */
+    base: 1000,
+    /** Gap between stacked overlays — leaves room for backdrop `z` + content `z+1`. */
+    step: 10,
+    /** Ratchet clamp; stays below `toast` so a saturated stack can never bury chrome. */
+    ceiling: 7900,
+    /** Pinned: notifications sit above modals regardless of open order. */
+    toast: 8000,
+    /** Pinned: transient, pointer-events:none, always on top. */
+    tooltip: 9000,
+};
 /**
  * Per-component override hooks — the raw CSS custom-property names. Set these
  * (not the values above) to restyle a single component's internals. Each

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tera-system-ui",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "scripts": {
     "dev": "vite dev",
     "build": "npm run customPrepublish && npm run generate-index && npm run generate-registry && npm run generate-llms && vite build && npm run package && npm run copy-docs && npm run copy-llms && npm run postpublish",
@@ -58,6 +58,11 @@
       "types": "./dist/utils/index.d.ts",
       "default": "./dist/utils/index.js"
     },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "svelte": "./dist/hooks/index.js",
+      "default": "./dist/hooks/index.js"
+    },
     "./recipes": {
       "types": "./dist/recipes/index.d.ts",
       "svelte": "./dist/recipes/index.js",