tera-system-ui 0.2.3 → 0.2.5

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/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.3",
+  "version": "0.2.5",
   "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",