@marianmeres/stuic 3.151.0 → 3.152.0

package/dist/actions/dim-behind/dim-behind.fixture.svelte

@@ -0,0 +1,54 @@
+<script lang="ts">
+	import { dimBehind } from "./dim-behind.svelte.js";
+
+	let {
+		aOpen = false,
+		bOpen = false,
+		useContainers = false,
+		sameContainer = false,
+	}: {
+		aOpen?: boolean;
+		bOpen?: boolean;
+		useContainers?: boolean;
+		sameContainer?: boolean;
+	} = $props();
+
+	let containerA = $state<HTMLDivElement>();
+	let containerB = $state<HTMLDivElement>();
+</script>
+
+<!-- Two independent shells, each a fixed containing block + stacking context
+(the framed-app case the `container` option exists for). -->
+<div
+	bind:this={containerA}
+	data-testid="container-a"
+	style="contain: layout paint; width: 200px; height: 120px;"
+>
+	<div
+		data-testid="target-a"
+		use:dimBehind={() => ({
+			open: aOpen,
+			container: useContainers ? () => containerA ?? null : undefined,
+		})}
+	>
+		A
+	</div>
+</div>
+
+<div
+	bind:this={containerB}
+	data-testid="container-b"
+	style="contain: layout paint; width: 200px; height: 120px;"
+>
+	<div
+		data-testid="target-b"
+		use:dimBehind={() => ({
+			open: bOpen,
+			container: useContainers
+				? () => (sameContainer ? (containerA ?? null) : (containerB ?? null))
+				: undefined,
+		})}
+	>
+		B
+	</div>
+</div>

package/dist/actions/dim-behind/dim-behind.fixture.svelte.d.ts

@@ -0,0 +1,9 @@
+type $$ComponentProps = {
+    aOpen?: boolean;
+    bOpen?: boolean;
+    useContainers?: boolean;
+    sameContainer?: boolean;
+};
+declare const DimBehind: import("svelte").Component<$$ComponentProps, {}, "">;
+type DimBehind = ReturnType<typeof DimBehind>;
+export default DimBehind;

package/dist/actions/dim-behind/dim-behind.svelte.d.ts

@@ -48,6 +48,16 @@ export interface DimBehindOptions {
     onHide?: () => void;
     /** Debug mode */
     debug?: boolean;
+    /**
+     * Where to append the backdrop. Defaults to the current behavior:
+     * `document.body`. Pass a bounded shell (framed app, embedded widget,
+     * dashboard pane) to keep the backdrop inside it — required when that shell
+     * is a stacking context, since the elevated target's z-index can then only
+     * compete with a backdrop living in the same context. Each distinct
+     * container gets its own ref-counted backdrop. A function returning `null`
+     * falls back to the default.
+     */
+    container?: HTMLElement | (() => HTMLElement | null);
 }
 /**
  * A Svelte action that dims everything behind a target element.

package/dist/actions/dim-behind/dim-behind.svelte.js

@@ -1,46 +1,60 @@
 import { BodyScroll } from "../../utils/body-scroll-locker.js";
-// --- Singleton Backdrop Manager ---
-let backdropEl = null;
-let activeCount = 0;
+import { resolveContainerOption } from "../../utils/overlay-container.js";
+// --- Shared Backdrop Manager (one ref-counted backdrop per container) ---
+const backdrops = new Map();
 const TRANSITION_SAFETY_MARGIN = 50;
-function getTransitionDuration() {
-    const raw = getComputedStyle(document.documentElement)
-        .getPropertyValue("--stuic-dim-behind-transition-duration")
-        .trim();
-    return parseFloat(raw) || 150;
+/**
+ * Actual transition duration of the backdrop element in ms — read from its
+ * computed style, which resolves the whole var chain
+ * (`--stuic-dim-behind-transition-duration`, `--stuic-transition`, …), unlike
+ * reading a single custom property off the root. Computed values serialize in
+ * seconds ("0.15s").
+ */
+function getTransitionDurationMs(el) {
+    const raw = getComputedStyle(el).transitionDuration;
+    const v = parseFloat(raw);
+    if (!Number.isFinite(v) || v < 0)
+        return 150;
+    return raw.trim().endsWith("ms") ? v : v * 1000;
 }
 function getElementZIndex() {
     return (getComputedStyle(document.documentElement)
         .getPropertyValue("--stuic-dim-behind-element-z-index")
         .trim() || "41");
 }
-function showBackdrop(classBackdrop) {
-    activeCount++;
-    if (activeCount === 1) {
-        backdropEl = document.createElement("div");
-        backdropEl.classList.add("stuic-dim-behind-backdrop");
+function showBackdrop(container, classBackdrop) {
+    let entry = backdrops.get(container);
+    if (!entry) {
+        const el = document.createElement("div");
+        el.classList.add("stuic-dim-behind-backdrop");
         if (classBackdrop) {
-            backdropEl.classList.add(...classBackdrop.split(/\s+/).filter(Boolean));
+            el.classList.add(...classBackdrop.split(/\s+/).filter(Boolean));
         }
-        document.body.appendChild(backdropEl);
+        container.appendChild(el);
         // Force reflow for transition
-        void backdropEl.offsetHeight;
-        backdropEl.classList.add("dim-visible");
+        void el.offsetHeight;
+        el.classList.add("dim-visible");
+        entry = { el, count: 0 };
+        backdrops.set(container, entry);
     }
+    entry.count++;
+    return entry.el;
 }
-function hideBackdrop() {
-    activeCount = Math.max(0, activeCount - 1);
-    if (activeCount === 0 && backdropEl) {
-        const el = backdropEl;
+function hideBackdrop(container) {
+    const entry = backdrops.get(container);
+    if (!entry)
+        return;
+    entry.count = Math.max(0, entry.count - 1);
+    if (entry.count === 0) {
+        // Drop the registry entry immediately so a show() during the fade-out
+        // creates a fresh backdrop instead of resurrecting the dying one.
+        backdrops.delete(container);
+        const el = entry.el;
         el.classList.remove("dim-visible");
-        const cleanup = () => {
-            el.remove();
-            if (backdropEl === el)
-                backdropEl = null;
-        };
+        const cleanup = () => el.remove();
         el.addEventListener("transitionend", cleanup, { once: true });
         // Safety fallback in case transitionend doesn't fire
-        setTimeout(cleanup, getTransitionDuration() + TRANSITION_SAFETY_MARGIN);
+        setTimeout(cleanup, getTransitionDurationMs(el) + TRANSITION_SAFETY_MARGIN);
     }
 }
 // --- Registry ---
@@ -115,6 +129,12 @@ export function dimBehind(node, fn) {
     let savedZIndex = "";
     let currentOptions = {};
     let do_debug = false;
+    // The container/backdrop/locks this instance acquired — captured at show()
+    // time so hide() releases exactly what was acquired even if options changed
+    // while visible.
+    let myContainer = null;
+    let myBackdropEl = null;
+    let myScrollLocked = false;
     const debug = (...args) => {
         if (do_debug)
             console.debug("[dimBehind]", ...args);
@@ -128,7 +148,7 @@ export function dimBehind(node, fn) {
         }
     }
     function onBackdropClick(e) {
-        if (e.target === backdropEl) {
+        if (e.target === myBackdropEl) {
             hide();
         }
     }
@@ -151,18 +171,20 @@ export function dimBehind(node, fn) {
             : getElementZIndex();
         node.style.position = "relative";
         node.style.zIndex = zIndex;
-        // Show singleton backdrop
-        showBackdrop(currentOptions.classBackdrop);
+        // Show the (per-container, ref-counted) shared backdrop
+        myContainer = resolveContainerOption(currentOptions.container) ?? document.body;
+        myBackdropEl = showBackdrop(myContainer, currentOptions.classBackdrop);
         // Optional scroll lock
         if (currentOptions.scrollLock) {
             BodyScroll.lock();
+            myScrollLocked = true;
         }
         // Event listeners
         if (currentOptions.closeOnEscape !== false) {
             document.addEventListener("keydown", onEscape);
         }
-        if (currentOptions.closeOnBackdropClick !== false && backdropEl) {
-            backdropEl.addEventListener("click", onBackdropClick);
+        if (currentOptions.closeOnBackdropClick !== false) {
+            myBackdropEl.addEventListener("click", onBackdropClick);
         }
         currentOptions.onShow?.();
     }
@@ -179,15 +201,18 @@ export function dimBehind(node, fn) {
         node.style.zIndex = savedZIndex;
         // Remove event listeners
         document.removeEventListener("keydown", onEscape);
-        if (backdropEl) {
-            backdropEl.removeEventListener("click", onBackdropClick);
-        }
-        // Optional scroll unlock
-        if (currentOptions.scrollLock) {
+        myBackdropEl?.removeEventListener("click", onBackdropClick);
+        // Release the scroll lock iff THIS instance acquired one (the option may
+        // have changed while visible)
+        if (myScrollLocked) {
             BodyScroll.unlock();
+            myScrollLocked = false;
         }
-        // Hide singleton backdrop
-        hideBackdrop();
+        // Release the shared backdrop
+        if (myContainer)
+            hideBackdrop(myContainer);
+        myContainer = null;
+        myBackdropEl = null;
         currentOptions.onHide?.();
     }
     // Reactive params effect
@@ -205,6 +230,7 @@ export function dimBehind(node, fn) {
             onShow: opts.onShow,
             onHide: opts.onHide,
             debug: opts.debug,
+            container: opts.container,
         };
         do_debug = !!opts.debug;
         // Register in global registry if id provided
@@ -229,10 +255,15 @@ export function dimBehind(node, fn) {
             if (isVisible) {
                 node.style.position = savedPosition;
                 node.style.zIndex = savedZIndex;
-                if (currentOptions.scrollLock) {
+                if (myScrollLocked) {
                     BodyScroll.unlock();
+                    myScrollLocked = false;
                 }
-                hideBackdrop();
+                myBackdropEl?.removeEventListener("click", onBackdropClick);
+                if (myContainer)
+                    hideBackdrop(myContainer);
+                myContainer = null;
+                myBackdropEl = null;
                 document.removeEventListener("keydown", onEscape);
             }
             // Unregister from registry

package/dist/actions/popover/README.md

@@ -4,23 +4,24 @@ A Svelte action that displays an anchored popover using CSS Anchor Positioning,
 
 ## Options
 
-| Option                | Type                 | Default     | Description                                           |
-| --------------------- | -------------------- | ----------- | ----------------------------------------------------- |
-| `enabled`             | `boolean`            | `true`      | Enable/disable popover                                |
-| `content`             | `THC \| null`        | -           | Popover content (string, HTML, component, or snippet) |
-| `position`            | `PopoverPosition`    | `"bottom"`  | Placement relative to anchor                          |
-| `trigger`             | `"click" \| "hover"` | `"click"`   | Trigger mode                                          |
-| `showDelay`           | `number`             | `100`       | Delay before showing (ms)                             |
-| `hideDelay`           | `number`             | `200`       | Delay before hiding (ms)                              |
-| `class`               | `string`             | -           | Custom CSS for popover container                      |
-| `offset`              | `string`             | `"0.25rem"` | Margin from anchor (CSS value)                        |
-| `closeOthers`         | `boolean`            | `false`     | Close other open popovers                             |
-| `closeOnClickOutside` | `boolean`            | `true`      | Close on outside click (click trigger)                |
-| `closeOnEscape`       | `boolean`            | `true`      | Close on Escape key                                   |
-| `showBackdrop`        | `boolean`            | `true`      | Show backdrop in fallback mode                        |
-| `forceFallback`       | `boolean`            | `false`     | Force centered modal mode                             |
-| `onShow`              | `() => void`         | -           | Callback when popover opens                           |
-| `onHide`              | `() => void`         | -           | Callback when popover closes                          |
+| Option                | Type                                         | Default                                       | Description                                                                                        |
+| --------------------- | -------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `enabled`             | `boolean`                                    | `true`                                        | Enable/disable popover                                                                             |
+| `content`             | `THC \| null`                                | -                                             | Popover content (string, HTML, component, or snippet)                                              |
+| `position`            | `PopoverPosition`                            | `"bottom"`                                    | Placement relative to anchor                                                                       |
+| `trigger`             | `"click" \| "hover"`                         | `"click"`                                     | Trigger mode                                                                                       |
+| `showDelay`           | `number`                                     | `100`                                         | Delay before showing (ms)                                                                          |
+| `hideDelay`           | `number`                                     | `200`                                         | Delay before hiding (ms)                                                                           |
+| `class`               | `string`                                     | -                                             | Custom CSS for popover container                                                                   |
+| `offset`              | `string`                                     | `"0.25rem"`                                   | Margin from anchor (CSS value)                                                                     |
+| `closeOthers`         | `boolean`                                    | `false`                                       | Close other open popovers                                                                          |
+| `closeOnClickOutside` | `boolean`                                    | `true`                                        | Close on outside click (click trigger)                                                             |
+| `closeOnEscape`       | `boolean`                                    | `true`                                        | Close on Escape key                                                                                |
+| `showBackdrop`        | `boolean`                                    | `true`                                        | Show backdrop in fallback mode                                                                     |
+| `forceFallback`       | `boolean`                                    | `false`                                       | Force centered modal mode                                                                          |
+| `onShow`              | `() => void`                                 | -                                             | Callback when popover opens                                                                        |
+| `onHide`              | `() => void`                                 | -                                             | Callback when popover closes                                                                       |
+| `container`           | `HTMLElement \| (() => HTMLElement \| null)` | closest open `<dialog>`, else `document.body` | Where to append the popover — pass a bounded shell to keep the overlay inside its stacking context |
 
 ## Positions
 
@@ -139,6 +140,25 @@ bottom-left   bottom    bottom-right
 </button>
 ```
 
+### Custom Container (Bounded Shells)
+
+When the app renders inside a bounded shell that is a stacking context and/or a
+fixed containing block (e.g. a centered frame with `contain: layout paint`, an
+embedded widget, a transformed wrapper), a body-level popover can only paint
+entirely above or below that shell. Pass `container` to keep the overlay inside
+it:
+
+```svelte
+<button
+	use:popover={() => ({
+		content: "Stays inside the frame",
+		container: () => document.querySelector(".app-frame"),
+	})}
+>
+	Framed
+</button>
+```
+
 ## Helper Function
 
 ```ts

package/dist/actions/popover/popover.container.fixture.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+	import { popover } from "./popover.svelte.js";
+
+	let { open = false, useContainer = false }: { open?: boolean; useContainer?: boolean } =
+		$props();
+
+	let shell = $state<HTMLDivElement>();
+</script>
+
+<!-- A bounded shell that is a fixed containing block + stacking context. -->
+<div
+	bind:this={shell}
+	data-testid="shell"
+	style="contain: layout paint; width: 300px; height: 200px;"
+></div>
+
+<button
+	data-testid="trigger"
+	use:popover={() => ({
+		content: "Hello",
+		open,
+		container: useContainer ? () => shell ?? null : undefined,
+	})}
+>
+	trigger
+</button>

package/dist/actions/popover/popover.container.fixture.svelte.d.ts

@@ -0,0 +1,7 @@
+type $$ComponentProps = {
+    open?: boolean;
+    useContainer?: boolean;
+};
+declare const Popover: import("svelte").Component<$$ComponentProps, {}, "">;
+type Popover = ReturnType<typeof Popover>;
+export default Popover;

package/dist/actions/popover/popover.svelte.d.ts

@@ -101,6 +101,16 @@ export interface PopoverOptions {
     open?: boolean;
     /** Unique ID for registry-based programmatic control (use with openPopover/closePopover/togglePopover) */
     id?: string;
+    /**
+     * Where to append the popover (and its fallback backdrop/wrapper). Defaults
+     * to the current behavior: the closest open `<dialog>` ancestor, else
+     * `document.body`. Pass a bounded shell (framed app, embedded widget,
+     * dashboard pane) to keep the overlay inside it — required when that shell
+     * is a stacking context, since a body-level overlay can then only paint
+     * entirely above or entirely below it. A function returning `null` falls
+     * back to the default.
+     */
+    container?: HTMLElement | (() => HTMLElement | null);
 }
 /**
  * A Svelte action that displays a popover anchored to an element using CSS Anchor Positioning.

package/dist/actions/popover/popover.svelte.js

@@ -2,6 +2,8 @@ import { mount, unmount } from "svelte";
 import { twMerge } from "../../utils/tw-merge.js";
 import { addAnchorName, removeAnchorName } from "../../utils/anchor-name.js";
 import { clampIntoViewport } from "../../utils/anchor-position.js";
+import { fixedContainingBlockRect } from "../../utils/containing-block.js";
+import { resolveContainerOption } from "../../utils/overlay-container.js";
 import { iconX } from "../../icons/index.js";
 import { BodyScroll } from "../../utils/body-scroll-locker.js";
 import PopoverContent from "./PopoverContent.svelte";
@@ -342,14 +344,19 @@ export function popover(anchorEl, fn) {
         anchorEl.setAttribute("aria-expanded", "true");
         const offsetValue = currentOptions.offset || "0.25rem";
         const useAnchorPositioning = isSupported && !currentOptions.forceFallback;
-        // Get appropriate container (dialog if inside one, otherwise body)
-        // This ensures popover renders in same stacking context as modal dialogs
-        const container = getPopoverContainer(anchorEl);
+        // Get appropriate container (explicit option, else dialog if inside one,
+        // otherwise body). This ensures popover renders in the same stacking
+        // context as modal dialogs / the consumer's bounded shell.
+        const container = resolveContainerOption(currentOptions.container) ?? getPopoverContainer(anchorEl);
         if (useAnchorPositioning) {
             // CSS Anchor Positioning mode
             popoverEl = document.createElement("div");
             popoverEl.setAttribute("id", id);
             popoverEl.setAttribute("role", "dialog");
+            // NOTE: keep `vw`/`vh` here — this is the ANCHORED branch, where the
+            // element's containing block is the `position-area` region (a slice of
+            // the CB, often much smaller than it), so `%` would shrink the popover.
+            // Overflow is handled by @position-try + the CB-aware runtime check.
             popoverEl.style.cssText = `
 				position: fixed;
 				position-anchor: ${anchorName};
@@ -390,10 +397,13 @@ export function popover(anchorEl, fn) {
             popoverEl = document.createElement("div");
             popoverEl.setAttribute("id", id);
             popoverEl.setAttribute("role", "dialog");
+            // `90%` (not `90vw/90vh`): resolves against the inset-0 wrapper, which
+            // spans the containing block — identical to viewport units when the CB
+            // is the viewport, correct inside a contained/transformed shell.
             popoverEl.style.cssText = `
 				position: relative;
-				max-width: 90vw;
-				max-height: 90vh;
+				max-width: 90%;
+				max-height: 90%;
 				overflow: auto;
 				transition-duration: ${TRANSITION}ms;
 				pointer-events: auto;
@@ -440,11 +450,13 @@ export function popover(anchorEl, fn) {
                     // sub-pixel/vertical cases); clamping keeps small edge-anchored
                     // popovers anchored instead of switching them to a modal.
                     clampIntoViewport(popoverEl);
+                    // Compare against the containing block (the viewport, unless an
+                    // ancestor with `transform`/`contain` establishes one).
                     const rect = popoverEl.getBoundingClientRect();
-                    const viewportWidth = window.innerWidth;
+                    const cb = fixedContainingBlockRect(popoverEl);
                     // If it STILL overflows horizontally after clamping, the content
                     // is too wide to fit anchored — fall back to the centered modal.
-                    if (rect.left < 0 || rect.right > viewportWidth) {
+                    if (rect.left < cb.left || rect.right > cb.right) {
                         debug("overflow detected, switching to fallback mode");
                         switchingToFallback = true;
                         // Quick cleanup (skip transition)
@@ -556,6 +568,7 @@ export function popover(anchorEl, fn) {
             onHide: opts.onHide,
             debug: opts.debug,
             id: opts.id,
+            container: opts.container,
         };
         do_debug = !!opts.debug;
         // Register in global registry if id provided

package/dist/actions/spotlight/spotlight.container.fixture.svelte

@@ -0,0 +1,33 @@
+<script lang="ts">
+	import { spotlight } from "./spotlight.svelte.js";
+
+	let { open = false, useContainer = false }: { open?: boolean; useContainer?: boolean } =
+		$props();
+
+	let shell = $state<HTMLDivElement>();
+</script>
+
+<!-- A bounded shell that is a fixed containing block + stacking context. The
+target sits at a known offset inside it so the clip-path hole coordinates can
+be asserted container-locally. -->
+<div
+	bind:this={shell}
+	data-testid="shell"
+	style="contain: layout paint; width: 240px; height: 180px; position: relative;"
+>
+	<button
+		data-testid="target"
+		style="position: absolute; left: 40px; top: 30px; width: 60px; height: 20px;"
+		use:spotlight={() => ({
+			content: "hi",
+			open,
+			padding: 4,
+			borderRadius: 0,
+			scrollIntoView: false,
+			autoTrack: false,
+			container: useContainer ? () => shell ?? null : undefined,
+		})}
+	>
+		x
+	</button>
+</div>

package/dist/actions/spotlight/spotlight.container.fixture.svelte.d.ts

@@ -0,0 +1,7 @@
+type $$ComponentProps = {
+    open?: boolean;
+    useContainer?: boolean;
+};
+declare const Spotlight: import("svelte").Component<$$ComponentProps, {}, "">;
+type Spotlight = ReturnType<typeof Spotlight>;
+export default Spotlight;

package/dist/actions/spotlight/spotlight.svelte.d.ts

@@ -98,6 +98,15 @@ export interface SpotlightOptions {
     autoTrack?: boolean;
     /** Debug mode */
     debug?: boolean;
+    /**
+     * Where to append the overlay elements (backdrop, anchor, annotation).
+     * Defaults to the current behavior: `document.body`. Pass a bounded shell
+     * (framed app, embedded widget, dashboard pane) to keep the overlay inside
+     * it — required when that shell is a stacking context, since a body-level
+     * overlay can then only paint entirely above or entirely below it. A
+     * function returning `null` falls back to the default.
+     */
+    container?: HTMLElement | (() => HTMLElement | null);
 }
 /**
  * A Svelte action that highlights a target element with a spotlight effect.