fancy-ui-svelte 0.11.0 → 0.12.0

package/README.md

@@ -9,7 +9,7 @@ Beautiful animation and UI components for **Svelte 5**.
 ![Svelte 5](https://img.shields.io/badge/Svelte-5-FF3E00?logo=svelte&logoColor=white)
 ![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-4-06B6D4?logo=tailwindcss&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript&logoColor=white)
-![Components](https://img.shields.io/badge/Components-133-8B5CF6)
+![Components](https://img.shields.io/badge/Components-145-8B5CF6)
 ![MIT License](https://img.shields.io/badge/License-MIT-green)
 
 <p align="center">
@@ -36,10 +36,10 @@ Beautiful animation and UI components for **Svelte 5**.
 - **Svelte 5 Runes** &mdash; Built with `$state`, `$derived`, `$effect`, and `$props`
 - **Tailwind CSS 4** &mdash; Utility-first styling with theme tokens
 - **TypeScript** &mdash; Fully typed props and events
-- **133 Components** &mdash; Core primitives (forms, navigation, overlays) alongside buttons, text animations, backgrounds and effects
+- **145 Components** &mdash; Core primitives (forms, navigation, overlays) alongside buttons, text animations, backgrounds, effects and a micro-interactions collection
 - **Dark Mode** &mdash; All components support light and dark themes
 - **Opt-in Sound** &mdash; Eleven synthesised interface cues, a `SoundToggle` switch and a `soundFeedback` action; silent until the user turns it on
-- **Tested** &mdash; 2,900+ unit tests with Vitest and Testing Library
+- **Tested** &mdash; 3,700+ unit tests with Vitest and Testing Library
 
 ## Quick Start
 
@@ -152,7 +152,7 @@ Component tests are colocated with their component (see `RainbowButton.test.ts`
 
 ## Contributing
 
-Contributions are welcome! 133 components and counting — PRs for new components, bug fixes, and improvements are appreciated.
+Contributions are welcome! 145 components and counting — PRs for new components, bug fixes, and improvements are appreciated.
 
 ### Adding a new component
 

package/dist/fancy-ui/_internals/ScrollLockHarness.test.svelte

@@ -0,0 +1,29 @@
+<!--
+  Test-only rig, half one of two. The PARENT: it owns the `{#if}`, and the
+  element that transitions lives one component down, in
+  `ScrollLockPanel.test.svelte`. See that file for what this pair proves.
+
+  `open` is held as local `$state` and flipped from a button inside this
+  component, deliberately, rather than driven from the test through
+  `rerender()`: `rerender` awaits a tick of its own, so a test using it can
+  never observe the ONE flush the proof is about — by the time it returns, the
+  stubbed animation has already resolved and the panel has left either way.
+  A click flips the state synchronously, so a single `await tick()` after it
+  lands exactly inside the exit window.
+
+  Not exported from index.ts, and not collected by Vitest directly (the run
+  includes `*.test.ts` only) — imported and rendered from scroll-lock.test.ts.
+-->
+<script lang="ts">
+	import ScrollLockPanel from "./ScrollLockPanel.test.svelte";
+
+	// Always starts closed, so the first click is a genuine (non-first-mount)
+	// intro and the second a genuine exit — the pair the proof needs.
+	let isOpen = $state(false);
+</script>
+
+<button type="button" data-testid="toggle" onclick={() => (isOpen = !isOpen)}>toggle</button>
+
+{#if isOpen}
+	<ScrollLockPanel open={isOpen} />
+{/if}

package/dist/fancy-ui/_internals/ScrollLockHarness.test.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const ScrollLockHarness: import("svelte").Component<Record<string, never>, {}, "">;
+type ScrollLockHarness = ReturnType<typeof ScrollLockHarness>;
+export default ScrollLockHarness;

package/dist/fancy-ui/_internals/ScrollLockPanel.test.svelte

@@ -0,0 +1,43 @@
+<!--
+  Test-only rig, half two of two. The CHILD component: its root element
+  carries the exit transition and `use:scrollLock`, exactly as a real panel
+  does, while the `{#if}` that mounts and unmounts it lives in its PARENT
+  (`ScrollLockHarness.test.svelte`).
+
+  That split is the whole point. Five Tier-2 panels are shaped this way, and
+  the campaign's design rests on a claim about Svelte's internals: a LOCAL
+  transition on a child component's root element is still collected by the
+  parent's `{#if}` when that branch closes, because the child compiles to a
+  transparent effect the collector walks through. If the claim is wrong the
+  transition is skipped, the branch is destroyed synchronously, and the scroll
+  lock releases the instant `open` flips rather than when the surface is
+  actually gone. `scroll-lock.test.ts` proves it rather than assuming it.
+
+  Not exported from index.ts, and not collected by Vitest directly (the run
+  includes `*.test.ts` only) — imported and rendered from scroll-lock.test.ts.
+-->
+<script lang="ts">
+	import { scrollLock } from "./scroll-lock.js";
+	import { anchored } from "./motion/anchored.js";
+	import { DURATIONS } from "./motion/tokens.js";
+
+	interface Props {
+		/** The parent's own `{#if}` condition, forwarded so the one
+		 * bidirectional directive can tell an entrance from an exit. */
+		open: boolean;
+	}
+
+	let { open }: Props = $props();
+</script>
+
+<div
+	data-testid="panel"
+	use:scrollLock
+	transition:anchored={{
+		entering: open,
+		duration: DURATIONS.base,
+		exitDuration: DURATIONS.exit,
+	}}
+>
+	panel
+</div>

package/dist/fancy-ui/_internals/ScrollLockPanel.test.svelte.d.ts

@@ -0,0 +1,8 @@
+interface Props {
+    /** The parent's own `{#if}` condition, forwarded so the one
+     * bidirectional directive can tell an entrance from an exit. */
+    open: boolean;
+}
+declare const ScrollLockPanel: import("svelte").Component<Props, {}, "">;
+type ScrollLockPanel = ReturnType<typeof ScrollLockPanel>;
+export default ScrollLockPanel;

package/dist/fancy-ui/_internals/anchor-position.d.ts

@@ -21,6 +21,13 @@ export interface ComputePositionResult {
     y: number;
     /** The side actually used, which may differ from the requested one when flipped. */
     side: Side;
+    /**
+     * The cross-axis alignment the element actually ended up with, which
+     * differs from the requested one whenever clamping slid it along that
+     * axis. Read it — not the requested `align` — for anything that has to
+     * point back at the anchor, such as a transform origin or a caret.
+     */
+    align: Align;
 }
 /**
  * Computes where to place a floating element relative to an anchor rect.
@@ -40,15 +47,19 @@ export interface AnchorPositionOptions {
     offset?: number;
     /**
      * Called with the side the element was actually placed on, which differs
-     * from the requested `side` whenever a flip occurred. Fires once on the
-     * initial placement and thereafter only when the resolved side changes,
-     * so a consumer can react (move a caret, mirror a submenu's open
-     * direction) without re-rendering on every scroll frame.
+     * from the requested `side` whenever a flip occurred, and with the
+     * cross-axis alignment it actually ended up with, which differs from the
+     * requested `align` whenever clamping slid it along that axis. Fires once
+     * on the initial placement and thereafter only when either resolved value
+     * changes, so a consumer can react (move a caret, set a transform origin,
+     * mirror a submenu's open direction) without re-rendering on every scroll
+     * frame.
      *
-     * Without this, `computePosition`'s resolved side is computed and
-     * discarded here, and a consumer has no way to learn a flip happened.
+     * Without this, `computePosition`'s resolved placement is computed and
+     * discarded here, and a consumer has no way to learn a flip or a clamp
+     * happened.
      */
-    onPlacement?: (side: Side) => void;
+    onPlacement?: (side: Side, align: Align) => void;
 }
 /**
  * Svelte action that positions `node` with `position: fixed` against a live

package/dist/fancy-ui/_internals/anchor-position.js

@@ -75,6 +75,34 @@ function placeAt(side, anchor, floating, align, offset) {
     }
     return { x, y };
 }
+/**
+ * Where the anchor's cross-axis centre falls inside the element as finally
+ * placed, expressed in the same vocabulary as the requested `align`.
+ *
+ * The requested alignment cannot answer this: clamping moves x/y without
+ * touching either input, so a menu asked for `align: "start"` next to the
+ * viewport's right edge is reported as `start` while the anchor now sits by
+ * its right edge. Deriving from the clamped coordinates keeps that honest.
+ * The thirds are the natural split of the three-value vocabulary.
+ */
+function resolveAlign(side, anchor, floating, x, y, requested) {
+    const horizontal = isHorizontalSide(side);
+    const extent = horizontal ? floating.width : floating.height;
+    // A zero-size element has no inside for the anchor to fall in — an
+    // unlaid-out first frame, a `display: none` ancestor, or jsdom, where
+    // every element measures zero. Nothing was clamped in that state either,
+    // so the requested alignment is both the honest answer and the one that
+    // keeps a never-measured panel behaving exactly as it did before.
+    if (extent <= 0)
+        return requested;
+    const anchorCentre = horizontal ? anchor.left + anchor.width / 2 : anchor.top + anchor.height / 2;
+    const ratio = (anchorCentre - (horizontal ? x : y)) / extent;
+    if (ratio < 1 / 3)
+        return "start";
+    if (ratio > 2 / 3)
+        return "end";
+    return "center";
+}
 /**
  * Computes where to place a floating element relative to an anchor rect.
  *
@@ -88,10 +116,13 @@ export function computePosition(anchor, floating, opts = {}) {
     const { x, y } = placeAt(resolvedSide, anchor, floating, align, offset);
     const maxX = Math.max(0, viewport.width - floating.width);
     const maxY = Math.max(0, viewport.height - floating.height);
+    const clampedX = clamp(x, 0, maxX);
+    const clampedY = clamp(y, 0, maxY);
     return {
-        x: clamp(x, 0, maxX),
-        y: clamp(y, 0, maxY),
+        x: clampedX,
+        y: clampedY,
         side: resolvedSide,
+        align: resolveAlign(resolvedSide, anchor, floating, clampedX, clampedY, align),
     };
 }
 /**
@@ -107,18 +138,19 @@ export const anchorPosition = (node, opts) => {
         return {};
     }
     let options = opts;
-    // The last side reported through `onPlacement`, so a scroll or resize that
-    // recomputes to the same side stays silent. `null` means "nothing reported
-    // yet", which is distinct from any real side and makes the first placement
-    // always fire.
+    // The last placement reported through `onPlacement`, so a scroll or resize
+    // that recomputes to the same one stays silent. `null` means "nothing
+    // reported yet", which is distinct from any real value and makes the first
+    // placement always fire.
     let reportedSide = null;
+    let reportedAlign = null;
     function update() {
         const anchorEl = options.anchor();
         if (!anchorEl)
             return;
         const anchorRect = anchorEl.getBoundingClientRect();
         const floatingRect = node.getBoundingClientRect();
-        const { x, y, side } = computePosition(anchorRect, { width: floatingRect.width, height: floatingRect.height }, {
+        const { x, y, side, align } = computePosition(anchorRect, { width: floatingRect.width, height: floatingRect.height }, {
             side: options.side,
             align: options.align,
             offset: options.offset,
@@ -127,9 +159,10 @@ export const anchorPosition = (node, opts) => {
         node.style.position = "fixed";
         node.style.left = `${x}px`;
         node.style.top = `${y}px`;
-        if (side !== reportedSide) {
+        if (side !== reportedSide || align !== reportedAlign) {
             reportedSide = side;
-            options.onPlacement?.(side);
+            reportedAlign = align;
+            options.onPlacement?.(side, align);
         }
     }
     update();
@@ -145,8 +178,10 @@ export const anchorPosition = (node, opts) => {
             // scoped to the node, not to the callback, so the gate that exists
             // to suppress duplicate reports to the *same* listener ends up
             // suppressing the first report to a *different* one.
-            if (newOpts.onPlacement !== options.onPlacement)
+            if (newOpts.onPlacement !== options.onPlacement) {
                 reportedSide = null;
+                reportedAlign = null;
+            }
             options = newOpts;
             update();
         },

package/dist/fancy-ui/_internals/anchor-position.test.js

@@ -89,6 +89,53 @@ describe("computePosition", () => {
         expect(() => computePosition(anchor, { width: 10, height: 10 }, { viewport: { width: 100, height: 100 } })).not.toThrow();
     });
 });
+// The requested alignment says which corner the caller ASKED for; only the
+// clamped coordinates say which corner the anchor actually ends up near. A
+// transform origin taken from the request grows the panel out of the corner
+// farthest from the click whenever a clamp moved it.
+describe("computePosition — resolved cross-axis align", () => {
+    it("reports the requested align back when nothing clamped it", () => {
+        // Mid-viewport on purpose: at x=100 the end-aligned panel would start at
+        // -50 and be clamped to 0, which is the very case the tests below cover.
+        const anchor = rect({ x: 400, y: 100, width: 50, height: 20 });
+        expect(computePosition(anchor, { width: 200, height: 40 }, { align: "start", viewport }).align).toBe("start");
+        expect(computePosition(anchor, { width: 200, height: 40 }, { align: "center", viewport }).align).toBe("center");
+        expect(computePosition(anchor, { width: 200, height: 40 }, { align: "end", viewport }).align).toBe("end");
+    });
+    // The reported case: a right-click near the viewport's right edge, opened
+    // bottom/start. The panel is clamped leftward until its RIGHT edge is the
+    // one at the pointer, so the origin has to be "end", not the requested
+    // "start".
+    it("reports 'end' when a start-aligned panel is clamped off the right edge", () => {
+        const anchor = rect({ x: 1010, y: 100, width: 0, height: 0 });
+        const result = computePosition(anchor, { width: 200, height: 40 }, { side: "bottom", align: "start", viewport });
+        expect(result.x).toBe(viewport.width - 200); // clamped, not anchor.left
+        expect(result.align).toBe("end");
+    });
+    it("reports 'start' when an end-aligned panel is clamped off the left edge", () => {
+        const anchor = rect({ x: 4, y: 100, width: 0, height: 0 });
+        const result = computePosition(anchor, { width: 200, height: 40 }, { side: "bottom", align: "end", viewport });
+        expect(result.x).toBe(0);
+        expect(result.align).toBe("start");
+    });
+    // Same failure on the other axis: a side-placed panel clamped against the
+    // bottom of the viewport.
+    it("resolves against the vertical axis for left/right sides", () => {
+        const anchor = rect({ x: 100, y: 760, width: 20, height: 0 });
+        const result = computePosition(anchor, { width: 200, height: 300 }, { side: "right", align: "start", viewport });
+        expect(result.y).toBe(viewport.height - 300);
+        expect(result.align).toBe("end");
+    });
+    // Every element measures zero in jsdom, so this is the path the component
+    // tests take. With no measurable box nothing was clamped either, so the
+    // requested alignment is the honest answer — and the one that keeps an
+    // unlaid-out first frame pointing where the caller asked.
+    it("falls back to the requested align for a zero-size element", () => {
+        const anchor = rect({ x: 100, y: 100, width: 50, height: 20 });
+        expect(computePosition(anchor, { width: 0, height: 0 }, { align: "start", viewport }).align).toBe("start");
+        expect(computePosition(anchor, { width: 0, height: 0 }, { align: "end", viewport }).align).toBe("end");
+    });
+});
 describe("anchorPosition — onPlacement", () => {
     afterEach(() => {
         document.body.innerHTML = "";
@@ -189,7 +236,7 @@ describe("anchorPosition — onPlacement", () => {
             onPlacement: second,
         });
         expect(second).toHaveBeenCalledTimes(1);
-        expect(second).toHaveBeenCalledWith("bottom");
+        expect(second).toHaveBeenCalledWith("bottom", "center");
         expect(first).toHaveBeenCalledTimes(1);
         action?.destroy?.();
     });

package/dist/fancy-ui/_internals/dismissable.d.ts

@@ -8,5 +8,21 @@ export interface DismissableOptions {
     outsideClick?: boolean;
     /** Elements to ignore when detecting outside clicks (e.g. a trigger button). */
     exclude?: () => (HTMLElement | null)[];
+    /**
+     * Whether this layer is still the live one. A GETTER, not a boolean, and
+     * read fresh on every Escape and every outside pointerdown — because an
+     * action's `update()` never runs again once its owning `{#if}` branch
+     * starts closing (Svelte marks the branch INERT before it plays the outro,
+     * and the scheduler skips inert effects). A changed param would never
+     * arrive; a getter captured at creation always reads the current value.
+     *
+     * Every overlay that animates its exit passes `() => open`. The moment
+     * `open` flips false the layer stops answering Escape AND stops counting
+     * as the top layer, so a second Escape during the fade is a no-op and the
+     * dialog underneath gets it instead of having it swallowed by a panel that
+     * is already leaving. Defaults to always-active, which is exactly the
+     * behaviour every caller had before this option existed.
+     */
+    active?: () => boolean;
 }
 export declare const dismissable: Action<HTMLElement, DismissableOptions>;

package/dist/fancy-ui/_internals/dismissable.js

@@ -3,9 +3,6 @@
 // disabled individually. `exclude` lets callers ignore extra elements that
 // live outside the node but should not count as "outside" (e.g. a trigger
 // button that toggles the dismissable element).
-// Stack of currently mounted dismissable layers. With nested overlays (e.g. a
-// popover inside a dialog) only the top-most layer reacts to Escape or an
-// outside pointerdown, so one interaction closes one layer at a time.
 const layers = [];
 export const dismissable = (node, opts) => {
     // Actions only run in the browser, but stay defensive for SSR contexts.
@@ -16,10 +13,23 @@ export const dismissable = (node, opts) => {
     let escape = opts.escape ?? true;
     let outsideClick = opts.outsideClick ?? true;
     let exclude = opts.exclude;
+    let isActive = opts.active ?? (() => true);
+    // Scans DOWN past inactive layers rather than testing only the last entry:
+    // a closing panel is still ON the stack (its `destroy()` is delayed by the
+    // outro), it just must not be TOP of it. The first live layer found from
+    // the top is the one that owns the interaction.
     function isTopLayer() {
-        return layers[layers.length - 1] === node;
+        for (let i = layers.length - 1; i >= 0; i -= 1) {
+            if (layers[i].isActive())
+                return layers[i].node === node;
+        }
+        return false;
     }
     function handleKeydown(event) {
+        // Before `stopImmediatePropagation()`, deliberately: an inactive layer
+        // must not swallow the key on its way to whatever is underneath.
+        if (!isActive())
+            return;
         if (!escape)
             return;
         if (event.key !== "Escape")
@@ -30,6 +40,8 @@ export const dismissable = (node, opts) => {
         onDismiss();
     }
     function handlePointerdown(event) {
+        if (!isActive())
+            return;
         if (!outsideClick)
             return;
         if (!isTopLayer())
@@ -42,7 +54,8 @@ export const dismissable = (node, opts) => {
             return;
         onDismiss();
     }
-    layers.push(node);
+    const layer = { node, isActive: () => isActive() };
+    layers.push(layer);
     document.addEventListener("keydown", handleKeydown);
     document.addEventListener("pointerdown", handlePointerdown);
     return {
@@ -51,9 +64,13 @@ export const dismissable = (node, opts) => {
             escape = newOpts.escape ?? true;
             outsideClick = newOpts.outsideClick ?? true;
             exclude = newOpts.exclude;
+            // The update path still matters for a panel whose `active` source
+            // changes while it is genuinely open. It is the CLOSE that never
+            // reaches here — hence the getter above, not this line.
+            isActive = newOpts.active ?? (() => true);
         },
         destroy() {
-            const i = layers.indexOf(node);
+            const i = layers.indexOf(layer);
             if (i !== -1)
                 layers.splice(i, 1);
             document.removeEventListener("keydown", handleKeydown);

package/dist/fancy-ui/_internals/dismissable.test.js

@@ -21,41 +21,46 @@ describe("dismissable", () => {
     it("calls onDismiss on Escape by default", () => {
         const onDismiss = vi.fn();
         setup();
-        dismissable(node, { onDismiss });
+        const action = dismissable(node, { onDismiss });
         pressEscape();
         expect(onDismiss).toHaveBeenCalledTimes(1);
+        action?.destroy?.();
     });
     it("does not call onDismiss on Escape when escape is false", () => {
         const onDismiss = vi.fn();
         setup();
-        dismissable(node, { onDismiss, escape: false });
+        const action = dismissable(node, { onDismiss, escape: false });
         pressEscape();
         expect(onDismiss).not.toHaveBeenCalled();
+        action?.destroy?.();
     });
     it("calls onDismiss on pointerdown outside the node by default", () => {
         const onDismiss = vi.fn();
         setup();
         const outside = document.createElement("button");
         document.body.appendChild(outside);
-        dismissable(node, { onDismiss });
+        const action = dismissable(node, { onDismiss });
         pointerDownOn(outside);
         expect(onDismiss).toHaveBeenCalledTimes(1);
+        action?.destroy?.();
     });
     it("does not call onDismiss on pointerdown inside the node", () => {
         const onDismiss = vi.fn();
         setup();
-        dismissable(node, { onDismiss });
+        const action = dismissable(node, { onDismiss });
         pointerDownOn(node.querySelector("#inner"));
         expect(onDismiss).not.toHaveBeenCalled();
+        action?.destroy?.();
     });
     it("does not call onDismiss on outside pointerdown when outsideClick is false", () => {
         const onDismiss = vi.fn();
         setup();
         const outside = document.createElement("button");
         document.body.appendChild(outside);
-        dismissable(node, { onDismiss, outsideClick: false });
+        const action = dismissable(node, { onDismiss, outsideClick: false });
         pointerDownOn(outside);
         expect(onDismiss).not.toHaveBeenCalled();
+        action?.destroy?.();
     });
     it("does not call onDismiss on pointerdown on an excluded element", () => {
         const onDismiss = vi.fn();
@@ -63,9 +68,10 @@ describe("dismissable", () => {
         const trigger = document.createElement("button");
         trigger.id = "trigger";
         document.body.appendChild(trigger);
-        dismissable(node, { onDismiss, exclude: () => [trigger] });
+        const action = dismissable(node, { onDismiss, exclude: () => [trigger] });
         pointerDownOn(trigger);
         expect(onDismiss).not.toHaveBeenCalled();
+        action?.destroy?.();
     });
     it("removes listeners on destroy", () => {
         const onDismiss = vi.fn();
@@ -87,6 +93,7 @@ describe("dismissable", () => {
         pressEscape();
         expect(onDismiss).not.toHaveBeenCalled();
         expect(onDismissUpdated).toHaveBeenCalledTimes(1);
+        action?.destroy?.();
     });
 });
 describe("dismissable — stacked layers", () => {
@@ -126,3 +133,105 @@ describe("dismissable — stacked layers", () => {
         a?.destroy?.();
     });
 });
+// `active` is what makes an ANIMATED close safe. A panel that is fading out
+// still holds its layer — its `destroy()` is delayed by the outro — so
+// without a liveness signal it would keep swallowing Escape for the whole
+// fade. It is a getter, not a boolean, because an action's `update()` never
+// runs again once its owning branch starts closing.
+describe("dismissable — the active gate", () => {
+    afterEach(() => {
+        document.body.innerHTML = "";
+    });
+    function layer(active) {
+        const node = document.createElement("div");
+        document.body.appendChild(node);
+        const onDismiss = vi.fn();
+        const action = dismissable(node, { onDismiss, active });
+        return { node, onDismiss, action };
+    }
+    it("an inactive layer ignores Escape — and does not swallow it on the way past", () => {
+        const { onDismiss, action } = layer(() => false);
+        const stopped = vi.fn();
+        const event = new KeyboardEvent("keydown", {
+            key: "Escape",
+            bubbles: true,
+            cancelable: true,
+        });
+        event.stopImmediatePropagation = stopped;
+        document.dispatchEvent(event);
+        expect(onDismiss).not.toHaveBeenCalled();
+        // The guard runs BEFORE stopImmediatePropagation, deliberately: a
+        // layer on its way out must let the key through to whatever is
+        // underneath rather than eating it.
+        expect(stopped).not.toHaveBeenCalled();
+        action?.destroy?.();
+    });
+    it("Escape falls through an inactive top layer to the live one beneath it", () => {
+        const bottom = layer();
+        const top = layer(() => false);
+        pressEscape();
+        expect(bottom.onDismiss).toHaveBeenCalledTimes(1);
+        expect(top.onDismiss).not.toHaveBeenCalled();
+        top.action?.destroy?.();
+        bottom.action?.destroy?.();
+    });
+    it("an outside pointerdown falls through an inactive top layer the same way", () => {
+        const bottom = layer();
+        const top = layer(() => false);
+        const outside = document.createElement("div");
+        document.body.appendChild(outside);
+        pointerDownOn(outside);
+        expect(bottom.onDismiss).toHaveBeenCalledTimes(1);
+        expect(top.onDismiss).not.toHaveBeenCalled();
+        top.action?.destroy?.();
+        bottom.action?.destroy?.();
+    });
+    it("reads the getter fresh on every event, so a layer going inactive stops answering", () => {
+        let live = true;
+        const { onDismiss, action } = layer(() => live);
+        pressEscape();
+        expect(onDismiss).toHaveBeenCalledTimes(1);
+        // The close instant: `open` flips, the action is never updated again
+        // (its branch is inert), and the captured getter is what notices.
+        live = false;
+        pressEscape();
+        pressEscape();
+        expect(onDismiss).toHaveBeenCalledTimes(1);
+        action?.destroy?.();
+    });
+    it("update() swaps active in place: active → inactive → active behaves at each step", () => {
+        const node = document.createElement("div");
+        document.body.appendChild(node);
+        const onDismiss = vi.fn();
+        const action = dismissable(node, { onDismiss });
+        pressEscape();
+        expect(onDismiss).toHaveBeenCalledTimes(1);
+        action?.update?.({ onDismiss, active: () => false });
+        pressEscape();
+        expect(onDismiss).toHaveBeenCalledTimes(1);
+        action?.update?.({ onDismiss, active: () => true });
+        pressEscape();
+        expect(onDismiss).toHaveBeenCalledTimes(2);
+        action?.destroy?.();
+    });
+    it("omitting active is byte-identical to always-active, at the top and underneath", () => {
+        const bottom = layer();
+        const top = layer();
+        pressEscape();
+        expect(top.onDismiss).toHaveBeenCalledTimes(1);
+        expect(bottom.onDismiss).not.toHaveBeenCalled();
+        top.action?.destroy?.();
+        pressEscape();
+        expect(bottom.onDismiss).toHaveBeenCalledTimes(1);
+        bottom.action?.destroy?.();
+    });
+    it("an inactive layer is not top even when every layer above it is gone", () => {
+        const { onDismiss, action } = layer(() => false);
+        const outside = document.createElement("div");
+        document.body.appendChild(outside);
+        pressEscape();
+        pointerDownOn(outside);
+        expect(onDismiss).not.toHaveBeenCalled();
+        action?.destroy?.();
+    });
+});

package/dist/fancy-ui/_internals/focus-trap.d.ts

@@ -14,5 +14,41 @@ export interface FocusTrapOptions {
      * still connected — that element always wins first, unconditionally.
      */
     fallbackFocus?: () => HTMLElement | null | undefined;
+    /**
+     * Called once, synchronously, as the trap activates, with two functions:
+     *
+     * 1. `returnFocusNow` — runs the return chain IMMEDIATELY and disarms
+     *    `destroy()`'s own return. Idempotent: calling it twice, or letting
+     *    `destroy()` follow it, returns focus exactly once. Overlays call it
+     *    from `onoutrostart`.
+     * 2. `rearm` — undoes that latch and puts focus back inside the trap.
+     *    Overlays call it from `onintrostart`.
+     *
+     * The first exists because an animated exit delays `destroy()` by the
+     * length of the fade. Without it a keyboard user pressing Escape waits
+     * 200 ms for focus to come back — and worse, Svelte sets `inert` on the
+     * panel the instant the exit starts, which drops focus to `<body>` for
+     * that whole window. `outrostart` is the one event that fires on every
+     * close path (Escape, outside click, close button, a caller's own
+     * `bind:open` write) and fires before the node is removed.
+     *
+     * The second exists because a surface reopened DURING its exit is not a
+     * new mount. Svelte reverses the outro and resumes the same branch
+     * (`reactivity/effects.js`'s `resume_children` clears INERT and calls
+     * `transition.in()`; the action factory in `dom/elements/actions.js` runs
+     * once per mount, untracked), so this action is never re-created, the
+     * initial focus move never re-runs, and the latch below stays set. Without
+     * `rearm` the reopened panel would be `aria-modal` and interactive again
+     * with focus sitting on the trigger *behind* it — untrapped, because the
+     * Tab handler is bound to the panel — and its next dismiss would return
+     * focus nowhere at all, the handle and `destroy()` both being permanently
+     * disarmed for the life of the instance.
+     *
+     * A caller that passes both `onActivate` and `returnFocus: false` is
+     * contradicting itself, and the handle wins: asking for the handle IS
+     * asking for the return. `returnFocus: false` governs the *unmount* path
+     * only.
+     */
+    onActivate?: (returnFocusNow: () => void, rearm: () => void) => void;
 }
 export declare const focusTrap: Action<HTMLElement, FocusTrapOptions | undefined>;