@c9up/nebula 0.1.0

package/dist/primitives/modalSurface.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Modal surface — the lifecycle of a dialog-shaped overlay.
+ *
+ * Dialog, AlertDialog, Sheet and Drawer differ only in where they come from
+ * and how they animate. What they share is the modal contract, and every part
+ * of it is a thing an app gets wrong when it builds one by hand:
+ *
+ * - A backdrop, so the page behind reads as unavailable.
+ * - Focus trapped inside, and returned to the trigger on close.
+ * - Page scroll locked, without the sideways jump when the scrollbar goes.
+ * - Escape closes; a click on the backdrop closes, unless the surface is
+ *   asking a question that must be answered (AlertDialog).
+ * - The rest of the page hidden from assistive technology, so a screen reader
+ *   cannot wander out of the dialog while sighted users cannot.
+ *
+ * That last one is the one almost always missed. Trapping *keyboard* focus
+ * does nothing for a reader navigating by heading or landmark — it will read
+ * straight through the page behind the overlay. `aria-hidden` on the siblings
+ * of the portal is what actually makes the dialog modal.
+ */
+import { type TemplateResult } from "@c9up/aurora";
+import { type DismissReason } from "./dismissable.js";
+export interface ModalSurfaceOptions {
+    open: () => boolean;
+    onClose: (reason: DismissReason) => void;
+    /** The whole overlay: backdrop and panel. */
+    content: () => TemplateResult;
+    /**
+     * The panel within the content, when the content's root is a full-screen
+     * wrapper.
+     *
+     * Containment is answered against this, not the root. An overlay's root
+     * usually spans the viewport so the backdrop can, and a root-based check
+     * would report every click on the page as "inside" — outside-click dismissal
+     * would silently never fire. The focus trap needs the same distinction:
+     * trapping to the root would let Tab reach the backdrop.
+     *
+     * Defaults to the root, which is right for an overlay that is only a panel.
+     */
+    panel?: (root: HTMLElement) => HTMLElement | null;
+    /** Where focus lands. Defaults to the first focusable element. */
+    initialFocus?: (content: HTMLElement) => HTMLElement | null;
+    /** Where focus returns. Defaults to whatever was focused before opening. */
+    returnFocus?: () => HTMLElement | null;
+    /** A click outside closes. `false` for a decision that must be made. */
+    dismissOnOutside?: boolean;
+    /** Escape closes. `false` for the same reason. */
+    dismissOnEscape?: boolean;
+    /** Hold page scroll. Default `true`. */
+    lockScroll?: boolean;
+    onOpened?: (content: HTMLElement) => void;
+    onClosed?: () => void;
+}
+export declare function modalSurface(options: ModalSurfaceOptions): void;

package/dist/primitives/modalSurface.js

@@ -0,0 +1,146 @@
+/// <reference lib="dom" />
+/**
+ * Modal surface — the lifecycle of a dialog-shaped overlay.
+ *
+ * Dialog, AlertDialog, Sheet and Drawer differ only in where they come from
+ * and how they animate. What they share is the modal contract, and every part
+ * of it is a thing an app gets wrong when it builds one by hand:
+ *
+ * - A backdrop, so the page behind reads as unavailable.
+ * - Focus trapped inside, and returned to the trigger on close.
+ * - Page scroll locked, without the sideways jump when the scrollbar goes.
+ * - Escape closes; a click on the backdrop closes, unless the surface is
+ *   asking a question that must be answered (AlertDialog).
+ * - The rest of the page hidden from assistive technology, so a screen reader
+ *   cannot wander out of the dialog while sighted users cannot.
+ *
+ * That last one is the one almost always missed. Trapping *keyboard* focus
+ * does nothing for a reader navigating by heading or landmark — it will read
+ * straight through the page behind the overlay. `aria-hidden` on the siblings
+ * of the portal is what actually makes the dialog modal.
+ */
+import { effect, onMount } from "@c9up/aurora";
+import { dismissable, } from "./dismissable.js";
+import { focusTrap } from "./focusTrap.js";
+import { portal } from "./portal.js";
+import { onExitFinished } from "./presence.js";
+import { lockScroll } from "./scrollLock.js";
+export function modalSurface(options) {
+    let live = null;
+    function show() {
+        if (live !== null) {
+            live.cancelExit?.();
+            live.cancelExit = null;
+            live.element.setAttribute("data-state", "open");
+            return;
+        }
+        const mount = portal(options.content());
+        const element = mount.host.firstElementChild;
+        if (!(element instanceof HTMLElement)) {
+            mount.close();
+            return;
+        }
+        element.setAttribute("data-state", "open");
+        const panel = options.panel?.(element) ?? element;
+        const unlock = options.lockScroll === false ? () => { } : lockScroll();
+        const restoreSiblings = hideSiblingsFrom(mount.host);
+        const trap = focusTrap(panel, {
+            initialFocus: () => options.initialFocus?.(panel) ?? null,
+            returnFocus: options.returnFocus,
+        });
+        const layer = dismissable({
+            element: () => panel,
+            onDismiss: options.onClose,
+            escapeKey: options.dismissOnEscape !== false,
+            outsidePointer: options.dismissOnOutside !== false,
+            outsideFocus: false,
+        });
+        live = {
+            mount,
+            element,
+            layer,
+            trap,
+            unlock,
+            restoreSiblings,
+            cancelExit: null,
+        };
+        options.onOpened?.(panel);
+    }
+    function hide() {
+        const current = live;
+        if (current === null)
+            return;
+        current.layer.remove();
+        current.trap.release();
+        current.restoreSiblings();
+        current.element.setAttribute("data-state", "closed");
+        options.onClosed?.();
+        // Scroll stays locked through the exit animation. Releasing it first
+        // lets the page jump back under a panel that is still sliding away.
+        current.cancelExit = onExitFinished(current.element, () => {
+            current.unlock();
+            current.mount.close();
+            if (live === current)
+                live = null;
+        });
+    }
+    function teardown() {
+        const current = live;
+        if (current === null)
+            return;
+        live = null;
+        current.cancelExit?.();
+        current.layer.remove();
+        current.trap.release();
+        current.restoreSiblings();
+        current.unlock();
+        current.mount.close();
+    }
+    onMount(() => {
+        const stop = effect(() => {
+            if (options.open())
+                show();
+            else
+                hide();
+        });
+        return () => {
+            stop();
+            teardown();
+        };
+    });
+}
+/**
+ * Hide everything except the overlay from assistive technology.
+ *
+ * Marks each sibling of the portal host, and restores exactly what was there
+ * before — an element that was *already* `aria-hidden` for its own reasons
+ * must stay that way after the dialog closes, so the previous value is saved
+ * rather than the attribute simply removed.
+ *
+ * Only siblings of the host, not the whole page: a second modal opening over
+ * the first must not hide it, and it will not, because it appends its own host
+ * after the first one and only touches what is beside it.
+ */
+function hideSiblingsFrom(host) {
+    const parent = host.parentElement;
+    if (parent === null)
+        return () => { };
+    const saved = [];
+    for (const sibling of parent.children) {
+        if (sibling === host)
+            continue;
+        // A live region announcing outside the dialog (a toast) is deliberate.
+        if (sibling.hasAttribute("data-nebula-live"))
+            continue;
+        saved.push([sibling, sibling.getAttribute("aria-hidden")]);
+        sibling.setAttribute("aria-hidden", "true");
+    }
+    return () => {
+        for (const [element, previous] of saved) {
+            if (previous === null)
+                element.removeAttribute("aria-hidden");
+            else
+                element.setAttribute("aria-hidden", previous);
+        }
+    };
+}

package/dist/primitives/portal.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Portal — mount a template outside the component's own DOM position.
+ *
+ * Overlays have to escape their parent. A Popover rendered where it is
+ * declared inherits every `overflow: hidden`, `transform` and `z-index` stack
+ * between it and the root, and any one of those will clip it or bury it. The
+ * fix is universal: render into `<body>` and position with fixed coordinates.
+ *
+ * Aurora's `render()` already mounts a `TemplateResult` anywhere and hands
+ * back a disposer, so a portal is that call plus a host element to hold the
+ * content and the discipline to tear both down together.
+ */
+import { type TemplateResult } from "@c9up/aurora";
+export interface PortalOptions {
+    /** Where to mount. Defaults to `document.body`. */
+    container?: () => Element | null;
+    /** Extra classes for the host element. */
+    class?: string;
+}
+export interface Portal {
+    /** The element holding the portalled content. */
+    readonly host: HTMLElement;
+    /** Unmount the content and remove the host. Safe to call twice. */
+    close(): void;
+}
+/**
+ * Mount `content` into a fresh host element appended to the container.
+ *
+ * A host element rather than mounting straight into `<body>`: it gives the
+ * content one node to be removed as a unit, keeps sibling portals from
+ * interleaving, and gives the layer a place to hang `data-nebula-portal` so a
+ * test — or a developer in the inspector — can see what put it there.
+ */
+export declare function portal(content: TemplateResult, options?: PortalOptions): Portal;

package/dist/primitives/portal.js

@@ -0,0 +1,42 @@
+/// <reference lib="dom" />
+/**
+ * Portal — mount a template outside the component's own DOM position.
+ *
+ * Overlays have to escape their parent. A Popover rendered where it is
+ * declared inherits every `overflow: hidden`, `transform` and `z-index` stack
+ * between it and the root, and any one of those will clip it or bury it. The
+ * fix is universal: render into `<body>` and position with fixed coordinates.
+ *
+ * Aurora's `render()` already mounts a `TemplateResult` anywhere and hands
+ * back a disposer, so a portal is that call plus a host element to hold the
+ * content and the discipline to tear both down together.
+ */
+import { render } from "@c9up/aurora";
+/**
+ * Mount `content` into a fresh host element appended to the container.
+ *
+ * A host element rather than mounting straight into `<body>`: it gives the
+ * content one node to be removed as a unit, keeps sibling portals from
+ * interleaving, and gives the layer a place to hang `data-nebula-portal` so a
+ * test — or a developer in the inspector — can see what put it there.
+ */
+export function portal(content, options = {}) {
+    const container = options.container?.() ?? document.body;
+    const host = document.createElement("div");
+    host.setAttribute("data-nebula-portal", "");
+    if (options.class !== undefined)
+        host.className = options.class;
+    container.appendChild(host);
+    const dispose = render(content, host);
+    let closed = false;
+    return {
+        host,
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            dispose();
+            host.remove();
+        },
+    };
+}

package/dist/primitives/presence.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Presence — keep a node mounted until its exit animation has finished.
+ *
+ * Closing an overlay by removing it from the DOM cancels any exit animation:
+ * the node is gone before the first frame plays. Radix solves this with a
+ * `Presence` wrapper, and shadcn's markup depends on it — the `data-[state=
+ * closed]:animate-out` utilities on every overlay assume something is holding
+ * the node on screen while that animation runs.
+ *
+ * `presence()` owns a `state` signal that leads the DOM: it flips to `closed`
+ * immediately so the exit animation can start, and only reports `mounted`
+ * false once the animation ends. A surface with no animation unmounts on the
+ * next tick, so the abstraction costs nothing when unused.
+ */
+import { type ReadSignal } from "@c9up/aurora";
+export type PresenceState = "open" | "closed";
+export interface Presence {
+    /** Should the node be in the DOM right now? */
+    readonly mounted: ReadSignal<boolean>;
+    /** The value for `data-state` — drives the enter/exit utility classes. */
+    readonly state: ReadSignal<PresenceState>;
+    /** Show the node. Cancels a pending unmount. */
+    open(): void;
+    /** Start the exit animation. Unmount follows when it finishes. */
+    close(): void;
+    /**
+     * Hand over the element once it is live. Presence watches it for the end of
+     * the exit animation; until it is given one, close() unmounts immediately.
+     */
+    attach(element: HTMLElement | null): void;
+    /** Drop listeners and timers. */
+    dispose(): void;
+}
+export declare function presence(initiallyOpen?: boolean): Presence;
+/**
+ * Run `done` once the element's exit animation finishes, or immediately when
+ * there is none. Returns a cancel function.
+ *
+ * The portalled surfaces do not use `presence()` — they own their own mounting
+ * through `portal()`, so a second `mounted` signal would just be a shadow of
+ * the portal's own lifetime. What they do need is this: the answer to "may I
+ * remove the node yet". Call it *after* flipping `data-state` to `closed`, so
+ * the computed style already reflects the closing rules.
+ */
+export declare function onExitFinished(element: HTMLElement, done: () => void): () => void;

package/dist/primitives/presence.js

@@ -0,0 +1,152 @@
+/// <reference lib="dom" />
+/**
+ * Presence — keep a node mounted until its exit animation has finished.
+ *
+ * Closing an overlay by removing it from the DOM cancels any exit animation:
+ * the node is gone before the first frame plays. Radix solves this with a
+ * `Presence` wrapper, and shadcn's markup depends on it — the `data-[state=
+ * closed]:animate-out` utilities on every overlay assume something is holding
+ * the node on screen while that animation runs.
+ *
+ * `presence()` owns a `state` signal that leads the DOM: it flips to `closed`
+ * immediately so the exit animation can start, and only reports `mounted`
+ * false once the animation ends. A surface with no animation unmounts on the
+ * next tick, so the abstraction costs nothing when unused.
+ */
+import { signal } from "@c9up/aurora";
+export function presence(initiallyOpen = false) {
+    const mounted = signal(initiallyOpen);
+    const state = signal(initiallyOpen ? "open" : "closed");
+    let element = null;
+    let pendingUnmount = false;
+    function finishClose() {
+        if (!pendingUnmount)
+            return;
+        pendingUnmount = false;
+        mounted(false);
+    }
+    /**
+     * The animation is only ours if it played on the surface itself.
+     *
+     * Events bubble, so a child's animation would otherwise unmount the parent
+     * mid-flight — a spinner inside a closing dialog is enough to trigger it.
+     */
+    function onAnimationEnd(event) {
+        if (event.target !== element)
+            return;
+        finishClose();
+    }
+    function detach() {
+        if (element === null)
+            return;
+        element.removeEventListener("animationend", onAnimationEnd);
+        element.removeEventListener("animationcancel", onAnimationEnd);
+        element.removeEventListener("transitionend", onAnimationEnd);
+        element.removeEventListener("transitioncancel", onAnimationEnd);
+        element = null;
+    }
+    return {
+        mounted,
+        state,
+        open() {
+            pendingUnmount = false;
+            mounted(true);
+            state("open");
+        },
+        close() {
+            if (!mounted())
+                return;
+            state("closed");
+            // No element yet means nothing can be animating — unmount now rather
+            // than waiting for an event that will never arrive.
+            if (element === null) {
+                mounted(false);
+                return;
+            }
+            pendingUnmount = true;
+            if (!isAnimating(element))
+                finishClose();
+        },
+        attach(next) {
+            detach();
+            element = next;
+            if (element === null)
+                return;
+            element.addEventListener("animationend", onAnimationEnd);
+            element.addEventListener("animationcancel", onAnimationEnd);
+            element.addEventListener("transitionend", onAnimationEnd);
+            element.addEventListener("transitioncancel", onAnimationEnd);
+        },
+        dispose() {
+            pendingUnmount = false;
+            detach();
+        },
+    };
+}
+/**
+ * Run `done` once the element's exit animation finishes, or immediately when
+ * there is none. Returns a cancel function.
+ *
+ * The portalled surfaces do not use `presence()` — they own their own mounting
+ * through `portal()`, so a second `mounted` signal would just be a shadow of
+ * the portal's own lifetime. What they do need is this: the answer to "may I
+ * remove the node yet". Call it *after* flipping `data-state` to `closed`, so
+ * the computed style already reflects the closing rules.
+ */
+export function onExitFinished(element, done) {
+    if (!isAnimating(element)) {
+        done();
+        return () => { };
+    }
+    function finish(event) {
+        // Bubbled events from children would cut the parent's exit short.
+        if (event.target !== element)
+            return;
+        cancel();
+        done();
+    }
+    function cancel() {
+        element.removeEventListener("animationend", finish);
+        element.removeEventListener("animationcancel", finish);
+        element.removeEventListener("transitionend", finish);
+        element.removeEventListener("transitioncancel", finish);
+    }
+    element.addEventListener("animationend", finish);
+    element.addEventListener("animationcancel", finish);
+    element.addEventListener("transitionend", finish);
+    element.addEventListener("transitioncancel", finish);
+    return cancel;
+}
+/**
+ * Is an exit animation actually running?
+ *
+ * Read after `data-state` has flipped, so the computed style already reflects
+ * the closing rules. `animationName: none` and a zero transition duration both
+ * mean there is nothing to wait for, and waiting anyway would strand the node
+ * in the DOM forever — the failure mode this check exists to prevent.
+ */
+function isAnimating(element) {
+    if (typeof getComputedStyle !== "function")
+        return false;
+    const style = getComputedStyle(element);
+    const hasAnimation = style.animationName !== "" && style.animationName !== "none";
+    if (hasAnimation)
+        return true;
+    return parseDuration(style.transitionDuration) > 0;
+}
+/** Longest duration in a comma-separated CSS time list, in milliseconds. */
+function parseDuration(value) {
+    let longest = 0;
+    for (const part of value.split(",")) {
+        const trimmed = part.trim();
+        if (trimmed === "")
+            continue;
+        const numeric = Number.parseFloat(trimmed);
+        if (Number.isNaN(numeric))
+            continue;
+        const ms = trimmed.endsWith("ms") ? numeric : numeric * 1000;
+        if (ms > longest)
+            longest = ms;
+    }
+    return longest;
+}

package/dist/primitives/rovingFocus.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Roving focus — arrow-key navigation over a group of items.
+ *
+ * The WAI-ARIA composite-widget pattern: a menu, listbox, tab list or toolbar
+ * is *one* tab stop, and arrows move within it. Exactly one item carries
+ * `tabindex="0"` at a time; the rest are `-1`. That is what stops a 40-item
+ * menu from swallowing 40 presses of Tab.
+ *
+ * Used by DropdownMenu, ContextMenu, Menubar, Select, Combobox, Command, Tabs
+ * and ToggleGroup. The differences between them are configuration, not
+ * behaviour: orientation, whether the ends wrap, and whether moving focus also
+ * selects.
+ *
+ * Items are found by querying the container on each keypress rather than being
+ * registered up front. Menu contents are reactive — filtered by a Command
+ * input, grown by a loaded page — and a registry captured at mount goes stale
+ * the moment they change. The query costs a few microseconds per keypress,
+ * which is not a budget worth optimising against correctness.
+ */
+export type Orientation = "vertical" | "horizontal" | "both";
+export interface RovingFocusOptions {
+    /** The group element. Read lazily — it mounts after the group registers. */
+    container: () => HTMLElement | null;
+    /** Which descendants are navigable. Default: nebula's own item marker. */
+    itemSelector?: string;
+    /** Which arrows move focus. Default `"vertical"`. */
+    orientation?: Orientation;
+    /** Wrap from last to first and back. Default `true`. */
+    loop?: boolean;
+    /** Enter / Space on the focused item. */
+    onSelect?: (item: HTMLElement, event: KeyboardEvent) => void;
+    /** Focus moved to a new item — used by menus that highlight on navigate. */
+    onFocusChange?: (item: HTMLElement) => void;
+}
+export interface RovingFocus {
+    /** Focus the first enabled item. */
+    focusFirst(): void;
+    /** Focus the last enabled item. */
+    focusLast(): void;
+    /** The navigable items, in document order. */
+    items(): HTMLElement[];
+    /** Re-apply `tabindex` after the item list changes. */
+    sync(): void;
+    /** Detach the key handler. Safe to call twice. */
+    destroy(): void;
+}
+export declare function rovingFocus(options: RovingFocusOptions): RovingFocus;