@c9up/nebula 0.1.0

package/dist/primitives/floating.js

@@ -0,0 +1,289 @@
+/// <reference lib="dom" />
+/**
+ * Floating placement — where a popover, menu, select or tooltip goes.
+ *
+ * This is the piece Radix delegates to `@floating-ui/dom`. nebula computes it
+ * instead, because the alternative is a runtime dependency in a workspace
+ * whose stated position is that `cn` was worth reimplementing rather than
+ * pulling in clsx and tailwind-merge.
+ *
+ * Scope is chosen to make that defensible. Floating UI is a general middleware
+ * pipeline; this is the four behaviours the shadcn component set actually
+ * uses — `offset`, `flip`, `shift`, and arrow centring — plus the available
+ * height a scrollable menu needs for its `max-height`. No middleware
+ * abstraction, no virtual elements, no `autoPlacement`.
+ *
+ * The geometry lives in `resolvePosition`, a pure function over rectangles.
+ * Everything that touches the DOM — measuring, writing styles, watching for
+ * scroll — is in `autoPosition` around it. That split is what lets the flip
+ * and shift rules be tested exhaustively without a browser, which matters
+ * because they are where placement bugs actually live.
+ *
+ * Coordinates are viewport-relative and meant for `position: fixed`. Fixed
+ * positioning is what lets a portalled surface ignore every transformed or
+ * clipping ancestor between it and the root; an absolutely positioned popover
+ * has to find an offset parent, and gets it wrong the moment one appears.
+ */
+const DEFAULT_OFFSET = 4;
+const DEFAULT_PADDING = 8;
+/**
+ * Compute where the surface goes. Pure — no DOM, no side effects.
+ *
+ * Order matters and matches Floating UI's: offset, then flip, then shift.
+ * Shifting before flipping would slide a surface halfway off the anchor to
+ * make room on a side that should have been abandoned entirely.
+ */
+export function resolvePosition(anchor, floating, viewport, options = {}) {
+    const offset = options.offset ?? DEFAULT_OFFSET;
+    const padding = options.padding ?? DEFAULT_PADDING;
+    const requested = options.placement ?? "bottom";
+    const [physicalSide, physicalAlign] = splitPlacement(requested);
+    const [requestedSide, align] = options.rtl === true
+        ? mirrorForRtl(physicalSide, physicalAlign)
+        : [physicalSide, physicalAlign];
+    const side = options.flip === false
+        ? requestedSide
+        : bestSide(requestedSide, anchor, floating, viewport, offset, padding);
+    let { x, y } = coordsFor(side, align, anchor, floating, offset);
+    if (options.shift !== false) {
+        if (isVertical(side)) {
+            x = clamp(x, padding, viewport.width - floating.width - padding);
+        }
+        else {
+            y = clamp(y, padding, viewport.height - floating.height - padding);
+        }
+    }
+    const position = {
+        x,
+        y,
+        placement: align === "center" ? side : `${side}-${align}`,
+        side,
+        align,
+        availableHeight: spaceOn(side, anchor, viewport, offset, padding),
+    };
+    if (options.arrowSize === undefined)
+        return position;
+    return {
+        ...position,
+        arrow: arrowOffset(side, anchor, floating, { x, y }, options.arrowSize, padding),
+    };
+}
+// ─── geometry ────────────────────────────────────────────────────────
+function splitPlacement(placement) {
+    const dash = placement.indexOf("-");
+    if (dash === -1)
+        return [toSide(placement), "center"];
+    return [toSide(placement.slice(0, dash)), toAlign(placement.slice(dash + 1))];
+}
+/**
+ * Narrow a substring back to `Side` / `Align`.
+ *
+ * `splitPlacement` slices a string the type system already proved is a valid
+ * `Placement`, but slicing erases that. A guard restores it without a cast,
+ * and the fallback keeps a hand-built placement string from crashing the
+ * layout — it lands on the default instead.
+ */
+function toSide(value) {
+    return value === "top" || value === "right" || value === "left"
+        ? value
+        : "bottom";
+}
+function toAlign(value) {
+    return value === "start" || value === "end" ? value : "center";
+}
+function isVertical(side) {
+    return side === "top" || side === "bottom";
+}
+/**
+ * Flip a placement across the vertical axis.
+ *
+ * Which half moves depends on the side. For `left` / `right` the *side* is the
+ * horizontal thing, so it swaps and the alignment (top/bottom) is untouched.
+ * For `top` / `bottom` the side is unaffected and it is the *alignment* that
+ * refers to a horizontal edge, so that swaps instead. Mirroring both would put
+ * a `bottom-start` menu back where it started.
+ */
+function mirrorForRtl(side, align) {
+    if (!isVertical(side))
+        return [opposite(side), align];
+    if (align === "center")
+        return [side, align];
+    return [side, align === "start" ? "end" : "start"];
+}
+function opposite(side) {
+    if (side === "top")
+        return "bottom";
+    if (side === "bottom")
+        return "top";
+    if (side === "left")
+        return "right";
+    return "left";
+}
+/** Top-left corner of the surface for a given side and alignment. */
+function coordsFor(side, align, anchor, floating, offset) {
+    if (isVertical(side)) {
+        const y = side === "bottom"
+            ? anchor.y + anchor.height + offset
+            : anchor.y - floating.height - offset;
+        return {
+            x: alignedStart(anchor.x, anchor.width, floating.width, align),
+            y,
+        };
+    }
+    const x = side === "right"
+        ? anchor.x + anchor.width + offset
+        : anchor.x - floating.width - offset;
+    return {
+        x,
+        y: alignedStart(anchor.y, anchor.height, floating.height, align),
+    };
+}
+/** Where the surface starts along the cross axis, for one alignment. */
+function alignedStart(anchorStart, anchorSize, floatingSize, align) {
+    if (align === "start")
+        return anchorStart;
+    if (align === "end")
+        return anchorStart + anchorSize - floatingSize;
+    return anchorStart + (anchorSize - floatingSize) / 2;
+}
+/** Room between the anchor and the viewport edge on one side. */
+function spaceOn(side, anchor, viewport, offset, padding) {
+    const raw = side === "top"
+        ? anchor.y
+        : side === "bottom"
+            ? viewport.height - (anchor.y + anchor.height)
+            : side === "left"
+                ? anchor.x
+                : viewport.width - (anchor.x + anchor.width);
+    return Math.max(0, raw - offset - padding);
+}
+/**
+ * Keep the requested side unless the opposite one is genuinely better.
+ *
+ * "Better" is not "has more room": flipping a menu that overflows by two
+ * pixels is more disruptive than letting it shift. So the opposite side has to
+ * both fit and beat the requested one. When neither fits, the roomier side
+ * wins and `availableHeight` lets the surface scroll inside it.
+ */
+function bestSide(requested, anchor, floating, viewport, offset, padding) {
+    const needed = isVertical(requested) ? floating.height : floating.width;
+    const here = spaceOn(requested, anchor, viewport, offset, padding);
+    if (here >= needed)
+        return requested;
+    const other = opposite(requested);
+    const there = spaceOn(other, anchor, viewport, offset, padding);
+    if (there >= needed)
+        return other;
+    return there > here ? other : requested;
+}
+/**
+ * Centre the arrow on the anchor, then pull it back off the corners.
+ *
+ * The arrow tracks the *anchor*, not the surface: once shift has slid the
+ * surface sideways, an arrow centred on the surface points at empty space.
+ * The clamp keeps it clear of the rounded corners, where it would otherwise
+ * poke out of the border radius.
+ */
+function arrowOffset(side, anchor, floating, coords, arrowSize, padding) {
+    if (isVertical(side)) {
+        const centre = anchor.x + anchor.width / 2 - coords.x - arrowSize / 2;
+        const limit = floating.width - arrowSize - padding;
+        return { x: clamp(centre, padding, Math.max(padding, limit)) };
+    }
+    const centre = anchor.y + anchor.height / 2 - coords.y - arrowSize / 2;
+    const limit = floating.height - arrowSize - padding;
+    return { y: clamp(centre, padding, Math.max(padding, limit)) };
+}
+function clamp(value, min, max) {
+    // `max` can fall below `min` when the surface is wider than the viewport.
+    // Pinning to `min` keeps the leading edge visible, which is the readable
+    // half; honouring `max` instead would push the start off screen.
+    if (max < min)
+        return min;
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * Position `floating` against `anchor` and keep it there.
+ *
+ * Updates run on scroll (captured, so ancestor scroll containers are covered
+ * without walking the tree to find them) and on resize, plus whenever either
+ * element changes size where `ResizeObserver` exists. A menu whose content
+ * loads in and grows would otherwise stay positioned for its old height.
+ */
+export function autoPosition(anchor, floating, options = {}) {
+    function update() {
+        const anchorRect = anchor.getBoundingClientRect();
+        // Read per update, not once: a `dir` attribute can be toggled at runtime
+        // by a language switcher, and a surface open across that switch has to
+        // move with it.
+        const rtl = options.rtl ?? isRightToLeft(anchor);
+        if (options.matchWidth === true) {
+            floating.style.width = `${anchorRect.width}px`;
+        }
+        const floatingRect = floating.getBoundingClientRect();
+        const position = resolvePosition(anchorRect, floatingRect, { width: window.innerWidth, height: window.innerHeight }, { ...options, rtl });
+        floating.style.position = "fixed";
+        floating.style.left = `${Math.round(position.x)}px`;
+        floating.style.top = `${Math.round(position.y)}px`;
+        // Exposed as custom properties so the *stylesheet* decides what to do with
+        // them. shadcn's menus read the available height through
+        // `max-h-(--nebula-available-height)`, which keeps the scroll decision in
+        // CSS rather than hardcoding a pixel max-height from script.
+        floating.style.setProperty("--nebula-available-height", `${Math.round(position.availableHeight)}px`);
+        floating.style.setProperty("--nebula-anchor-width", `${Math.round(anchorRect.width)}px`);
+        floating.setAttribute("data-side", position.side);
+        floating.setAttribute("data-align", position.align);
+        const arrowEl = options.arrow?.();
+        if (arrowEl && position.arrow) {
+            const { x, y } = position.arrow;
+            arrowEl.style.position = "absolute";
+            arrowEl.style.left = x === undefined ? "" : `${Math.round(x)}px`;
+            arrowEl.style.top = y === undefined ? "" : `${Math.round(y)}px`;
+        }
+        options.onPositioned?.(position);
+    }
+    update();
+    const onScrollOrResize = () => update();
+    window.addEventListener("scroll", onScrollOrResize, true);
+    window.addEventListener("resize", onScrollOrResize);
+    const observer = observeSizes([anchor, floating], update);
+    let stopped = false;
+    return {
+        update,
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            window.removeEventListener("scroll", onScrollOrResize, true);
+            window.removeEventListener("resize", onScrollOrResize);
+            observer?.disconnect();
+        },
+    };
+}
+/**
+ * Is this element laid out right to left?
+ *
+ * The computed style rather than the `dir` attribute, so an element inheriting
+ * the direction from `<html dir="rtl">` is answered correctly without every
+ * anchor having to carry the attribute itself.
+ */
+function isRightToLeft(element) {
+    if (typeof getComputedStyle !== "function")
+        return false;
+    return getComputedStyle(element).direction === "rtl";
+}
+/**
+ * Watch elements for size changes, where the platform supports it.
+ *
+ * happy-dom (nebula's unit-test environment) has no `ResizeObserver`, and the
+ * scroll and resize listeners already cover the common cases, so its absence
+ * degrades rather than throws.
+ */
+function observeSizes(elements, onResize) {
+    if (typeof ResizeObserver !== "function")
+        return null;
+    const observer = new ResizeObserver(onResize);
+    for (const element of elements)
+        observer.observe(element);
+    return observer;
+}

package/dist/primitives/floatingSurface.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Floating surface — the whole lifecycle of a popover-shaped overlay.
+ *
+ * Popover, Tooltip, HoverCard, DropdownMenu, ContextMenu, Menubar, Select and
+ * Combobox are the same machine with different contents and different opening
+ * gestures. That machine is: portal out of the tree, position against an
+ * anchor, register as a dismissable layer, optionally trap focus, and on close
+ * let the exit animation finish before removing anything.
+ *
+ * Five primitives in a fixed order, and the order is the part that is easy to
+ * get wrong. The layer must register *after* the content exists, or its
+ * containment check has nothing to test against and the opening click closes
+ * it again. The focus trap must run after the first position pass, or it
+ * focuses a surface still sitting at (0,0) and the browser scrolls to it.
+ *
+ * Written once here so eight components cannot each get that order slightly
+ * different.
+ */
+import { type TemplateResult } from "@c9up/aurora";
+import { type DismissReason } from "./dismissable.js";
+import { type Placement } from "./floating.js";
+export interface FloatingSurfaceOptions {
+    /** What the surface is positioned against — usually the trigger. */
+    anchor: () => HTMLElement | null;
+    /** Should the surface be showing? Read reactively. */
+    open: () => boolean;
+    /** The surface wants to close. Flip whatever drives `open`. */
+    onClose: (reason: DismissReason) => void;
+    /** The surface's markup. Built fresh on each open. */
+    content: () => TemplateResult;
+    placement?: Placement;
+    offset?: number;
+    /** Size the surface to the anchor. Select and Combobox want this. */
+    matchWidth?: boolean;
+    /** Keep keyboard focus inside while open. */
+    trapFocus?: boolean;
+    /** Move focus into the surface on open. Implied by `trapFocus`. */
+    autoFocus?: boolean;
+    /** Where focus goes first. Defaults to the first focusable element. */
+    initialFocus?: (content: HTMLElement) => HTMLElement | null;
+    escapeKey?: boolean;
+    outsidePointer?: boolean;
+    /** Default `false` — a surface that opened on hover should not steal focus. */
+    outsideFocus?: boolean;
+    /** The surface is live and positioned. Wire item handlers here. */
+    onOpened?: (content: HTMLElement) => void;
+    /** The surface is about to be removed. */
+    onClosed?: () => void;
+}
+/**
+ * Wire a floating surface into the surrounding component.
+ *
+ * Call from a component setup. It registers its own mount and unmount hooks,
+ * so there is nothing to dispose by hand.
+ */
+export declare function floatingSurface(options: FloatingSurfaceOptions): void;

package/dist/primitives/floatingSurface.js

@@ -0,0 +1,142 @@
+/// <reference lib="dom" />
+/**
+ * Floating surface — the whole lifecycle of a popover-shaped overlay.
+ *
+ * Popover, Tooltip, HoverCard, DropdownMenu, ContextMenu, Menubar, Select and
+ * Combobox are the same machine with different contents and different opening
+ * gestures. That machine is: portal out of the tree, position against an
+ * anchor, register as a dismissable layer, optionally trap focus, and on close
+ * let the exit animation finish before removing anything.
+ *
+ * Five primitives in a fixed order, and the order is the part that is easy to
+ * get wrong. The layer must register *after* the content exists, or its
+ * containment check has nothing to test against and the opening click closes
+ * it again. The focus trap must run after the first position pass, or it
+ * focuses a surface still sitting at (0,0) and the browser scrolls to it.
+ *
+ * Written once here so eight components cannot each get that order slightly
+ * different.
+ */
+import { effect, onMount } from "@c9up/aurora";
+import { dismissable, } from "./dismissable.js";
+import { autoPosition } from "./floating.js";
+import { firstFocusable, focusSilently } from "./focusable.js";
+import { focusTrap } from "./focusTrap.js";
+import { portal } from "./portal.js";
+import { onExitFinished } from "./presence.js";
+/**
+ * Wire a floating surface into the surrounding component.
+ *
+ * Call from a component setup. It registers its own mount and unmount hooks,
+ * so there is nothing to dispose by hand.
+ */
+export function floatingSurface(options) {
+    let live = null;
+    function show() {
+        if (live !== null) {
+            // Already open and mid-exit: cancel the teardown and reuse the node
+            // rather than stacking a second copy on top of the one fading out.
+            live.cancelExit?.();
+            live.cancelExit = null;
+            live.element.setAttribute("data-state", "open");
+            return;
+        }
+        const anchor = options.anchor();
+        if (anchor === null)
+            return;
+        const mount = portal(options.content());
+        const element = mount.host.firstElementChild;
+        if (!(element instanceof HTMLElement)) {
+            mount.close();
+            return;
+        }
+        element.setAttribute("data-state", "open");
+        const position = autoPosition(anchor, element, {
+            placement: options.placement,
+            offset: options.offset,
+            matchWidth: options.matchWidth,
+        });
+        const layer = dismissable({
+            element: () => element,
+            exclude: () => [anchor],
+            onDismiss: options.onClose,
+            escapeKey: options.escapeKey,
+            outsidePointer: options.outsidePointer,
+            outsideFocus: options.outsideFocus ?? false,
+        });
+        let trap = null;
+        if (options.trapFocus === true) {
+            trap = focusTrap(element, {
+                initialFocus: () => options.initialFocus?.(element) ?? null,
+            });
+        }
+        else if (options.autoFocus === true) {
+            focusSilently(options.initialFocus?.(element) ?? firstFocusable(element));
+        }
+        live = { mount, anchor, element, position, layer, trap, cancelExit: null };
+        options.onOpened?.(element);
+    }
+    function hide() {
+        const current = live;
+        if (current === null)
+            return;
+        // Detach behaviour first, then animate out. A surface that is fading
+        // should not still be answering Escape or repositioning itself.
+        current.layer.remove();
+        current.position.stop();
+        current.trap?.release();
+        returnFocusToAnchor(current.element, current.anchor);
+        current.element.setAttribute("data-state", "closed");
+        options.onClosed?.();
+        current.cancelExit = onExitFinished(current.element, () => {
+            current.mount.close();
+            if (live === current)
+                live = null;
+        });
+    }
+    /**
+     * Hand focus back to the anchor when the surface held it.
+     *
+     * Dismissal by keyboard leaves focus inside a subtree that is about to be
+     * removed; without this it falls to `<body>` and the next Tab restarts at
+     * the top of the page. `dismissable` handles Escape from a *captured*
+     * document listener and stops propagation, so a component cannot do this in
+     * its own keydown handler — the event never reaches it.
+     *
+     * Guarded on containment, so a dismissal caused by clicking somewhere else
+     * does not steal focus back from wherever the user just put it. A trapped
+     * surface has already restored focus by the time this runs, and the guard
+     * makes it a no-op there too.
+     */
+    function returnFocusToAnchor(surface, anchor) {
+        const active = document.activeElement;
+        if (!(active instanceof Node) || !surface.contains(active))
+            return;
+        focusSilently(anchor);
+    }
+    function teardown() {
+        const current = live;
+        if (current === null)
+            return;
+        live = null;
+        current.cancelExit?.();
+        current.layer.remove();
+        current.position.stop();
+        current.trap?.release();
+        current.mount.close();
+    }
+    onMount(() => {
+        const stop = effect(() => {
+            if (options.open())
+                show();
+            else
+                hide();
+        });
+        // The component is going away, so the exit animation has nobody left to
+        // play for — drop the node immediately rather than orphaning it in body.
+        return () => {
+            stop();
+            teardown();
+        };
+    });
+}

package/dist/primitives/focusTrap.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Focus trap — keyboard focus cannot leave a subtree while it is active.
+ *
+ * Required by every modal surface (Dialog, AlertDialog, Sheet, Drawer). The
+ * WAI-ARIA dialog pattern is specific about it: Tab from the last focusable
+ * element wraps to the first, Shift+Tab from the first wraps to the last, and
+ * focus returns to whatever opened the dialog when it closes.
+ *
+ * Two mechanisms, deliberately both:
+ *
+ * - A `keydown` handler implements the wrap. This is the path that runs for
+ *   ordinary keyboard use, and it is the only one that can put focus on the
+ *   *correct* end of the trap.
+ * - A `focusin` handler on the document catches everything else — a click on
+ *   the page behind, a screen reader jumping by landmark, a browser find bar
+ *   handing focus back somewhere else. It pulls focus back into the trap.
+ *
+ * The keydown handler alone leaks; the focusin handler alone produces the
+ * classic bug where Tab escapes and is yanked back a frame later, which reads
+ * as a flicker and confuses assistive technology.
+ */
+export interface FocusTrapOptions {
+    /**
+     * Where focus goes when the trap activates. Defaults to the first focusable
+     * descendant, then the container itself.
+     */
+    initialFocus?: () => HTMLElement | null;
+    /**
+     * Where focus goes when it releases. Defaults to whatever was focused when
+     * the trap activated — which is nearly always the trigger.
+     */
+    returnFocus?: () => HTMLElement | null;
+    /** Skip moving focus on activation. For surfaces that focus themselves. */
+    skipInitialFocus?: boolean;
+}
+export interface FocusTrap {
+    /** Tear the trap down and restore focus. Safe to call twice. */
+    release(): void;
+}
+/**
+ * Trap focus inside `container` until the returned handle is released.
+ *
+ * The container is made focusable with `tabindex="-1"` if it is not already,
+ * so an empty surface still has somewhere to put focus. Without it, focus
+ * would fall to `<body>` and the next Tab would land outside the trap.
+ */
+export declare function focusTrap(container: HTMLElement, options?: FocusTrapOptions): FocusTrap;

package/dist/primitives/focusTrap.js

@@ -0,0 +1,101 @@
+/// <reference lib="dom" />
+/**
+ * Focus trap — keyboard focus cannot leave a subtree while it is active.
+ *
+ * Required by every modal surface (Dialog, AlertDialog, Sheet, Drawer). The
+ * WAI-ARIA dialog pattern is specific about it: Tab from the last focusable
+ * element wraps to the first, Shift+Tab from the first wraps to the last, and
+ * focus returns to whatever opened the dialog when it closes.
+ *
+ * Two mechanisms, deliberately both:
+ *
+ * - A `keydown` handler implements the wrap. This is the path that runs for
+ *   ordinary keyboard use, and it is the only one that can put focus on the
+ *   *correct* end of the trap.
+ * - A `focusin` handler on the document catches everything else — a click on
+ *   the page behind, a screen reader jumping by landmark, a browser find bar
+ *   handing focus back somewhere else. It pulls focus back into the trap.
+ *
+ * The keydown handler alone leaks; the focusin handler alone produces the
+ * classic bug where Tab escapes and is yanked back a frame later, which reads
+ * as a flicker and confuses assistive technology.
+ */
+import { firstFocusable, focusableWithin, focusSilently } from "./focusable.js";
+/**
+ * Trap focus inside `container` until the returned handle is released.
+ *
+ * The container is made focusable with `tabindex="-1"` if it is not already,
+ * so an empty surface still has somewhere to put focus. Without it, focus
+ * would fall to `<body>` and the next Tab would land outside the trap.
+ */
+export function focusTrap(container, options = {}) {
+    const previouslyFocused = activeElement();
+    if (!container.hasAttribute("tabindex")) {
+        container.setAttribute("tabindex", "-1");
+    }
+    if (!options.skipInitialFocus) {
+        const target = options.initialFocus?.() ?? firstFocusable(container) ?? container;
+        focusSilently(target);
+    }
+    function onKeyDown(event) {
+        if (event.key !== "Tab")
+            return;
+        const focusables = focusableWithin(container);
+        if (focusables.length === 0) {
+            // Nothing to cycle through: hold focus on the container so Tab cannot
+            // walk out into the page behind.
+            event.preventDefault();
+            focusSilently(container);
+            return;
+        }
+        const first = focusables[0];
+        const last = focusables[focusables.length - 1];
+        const current = activeElement();
+        if (event.shiftKey && (current === first || current === container)) {
+            event.preventDefault();
+            focusSilently(last);
+        }
+        else if (!event.shiftKey && current === last) {
+            event.preventDefault();
+            focusSilently(first);
+        }
+    }
+    /**
+     * Pull focus back when it lands outside by any route other than Tab.
+     *
+     * Guarded on `contains`, and only ever moves focus *into* the trap, so it
+     * cannot fight a nested trap: an inner dialog's container is a descendant
+     * of the outer one, so the outer handler sees the focus as already inside.
+     */
+    function onFocusIn(event) {
+        const target = event.target;
+        if (!(target instanceof Node))
+            return;
+        if (container.contains(target))
+            return;
+        focusSilently(firstFocusable(container) ?? container);
+    }
+    document.addEventListener("keydown", onKeyDown, true);
+    document.addEventListener("focusin", onFocusIn, true);
+    let released = false;
+    return {
+        release() {
+            if (released)
+                return;
+            released = true;
+            document.removeEventListener("keydown", onKeyDown, true);
+            document.removeEventListener("focusin", onFocusIn, true);
+            const target = options.returnFocus?.() ?? previouslyFocused;
+            // Only restore focus if it is still inside the trap. If something else
+            // has already claimed it — a second dialog, a toast action — stealing it
+            // back would be the wrong call.
+            if (container.contains(activeElement()))
+                focusSilently(target);
+        },
+    };
+}
+/** The focused element, narrowed to something we can call `.focus()` on. */
+function activeElement() {
+    const active = document.activeElement;
+    return active instanceof HTMLElement ? active : null;
+}