@c9up/nebula 0.1.0

package/src/primitives/floatingSurface.ts

@@ -0,0 +1,209 @@
+/// <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, type TemplateResult } from "@c9up/aurora";
+import {
+	type DismissableLayer,
+	type DismissReason,
+	dismissable,
+} from "./dismissable.js";
+import { type AutoPosition, autoPosition, type Placement } from "./floating.js";
+import { firstFocusable, focusSilently } from "./focusable.js";
+import { type FocusTrap, focusTrap } from "./focusTrap.js";
+import { type Portal, portal } from "./portal.js";
+import { onExitFinished } from "./presence.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;
+}
+
+interface Live {
+	readonly mount: Portal;
+	/**
+	 * The anchor this surface actually opened against.
+	 *
+	 * Held rather than re-read on close, because the accessor is often derived
+	 * from the open state — Menubar and NavigationMenu resolve theirs from the
+	 * index of the open menu, which is already cleared by the time the surface
+	 * tears down. Asking again at that point returns null and the focus
+	 * restoration silently does nothing.
+	 */
+	readonly anchor: HTMLElement;
+	readonly element: HTMLElement;
+	readonly position: AutoPosition;
+	readonly layer: DismissableLayer;
+	readonly trap: FocusTrap | null;
+	cancelExit: (() => void) | null;
+}
+
+/**
+ * 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: FloatingSurfaceOptions): void {
+	let live: Live | null = null;
+
+	function show(): void {
+		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: FocusTrap | null = 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(): void {
+		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: HTMLElement,
+		anchor: HTMLElement,
+	): void {
+		const active = document.activeElement;
+		if (!(active instanceof Node) || !surface.contains(active)) return;
+		focusSilently(anchor);
+	}
+
+	function teardown(): void {
+		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/src/primitives/focusTrap.ts

@@ -0,0 +1,132 @@
+/// <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";
+
+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 function focusTrap(
+	container: HTMLElement,
+	options: FocusTrapOptions = {},
+): FocusTrap {
+	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: KeyboardEvent): void {
+		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: FocusEvent): void {
+		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(): void {
+			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(): HTMLElement | null {
+	const active = document.activeElement;
+	return active instanceof HTMLElement ? active : null;
+}

package/src/primitives/focusable.ts

@@ -0,0 +1,108 @@
+/// <reference lib="dom" />
+/**
+ * Which elements can take focus.
+ *
+ * The focus trap, the roving-focus groups and every overlay that restores
+ * focus on close all need the same answer, and getting it slightly different
+ * in each place is how keyboard navigation rots. One implementation here.
+ *
+ * The selector is the standard tabbable set, but a selector alone is not the
+ * answer: it matches nodes that are disabled, `inert`, hidden by CSS, or
+ * inside a collapsed `<details>`. Those have to be filtered by asking the
+ * layout engine, which is why `isVisible` reads `offsetParent` and computed
+ * styles rather than trusting the markup.
+ */
+
+const FOCUSABLE_SELECTOR = [
+	"a[href]",
+	"area[href]",
+	"button:not([disabled])",
+	"input:not([disabled]):not([type='hidden'])",
+	"select:not([disabled])",
+	"textarea:not([disabled])",
+	"iframe",
+	"object",
+	"embed",
+	"audio[controls]",
+	"video[controls]",
+	"summary",
+	"[contenteditable]:not([contenteditable='false'])",
+	"[tabindex]",
+].join(",");
+
+/**
+ * Is the element rendered and interactive right now?
+ *
+ * `offsetParent === null` catches `display: none` on the element or any
+ * ancestor in one property read, which is much cheaper than walking the tree.
+ * It reports null for `position: fixed` elements too, so those fall through to
+ * the explicit style checks — that branch is why dialogs and popovers, which
+ * are routinely fixed, are not wrongly treated as hidden.
+ */
+export function isVisible(el: HTMLElement): boolean {
+	if (el.hasAttribute("inert")) return false;
+	if (el.closest("[inert]") !== null) return false;
+
+	if (el.offsetParent !== null) return true;
+
+	const style = getComputedStyle(el);
+	if (style.position !== "fixed") return false;
+	return style.display !== "none" && style.visibility !== "hidden";
+}
+
+/**
+ * Can this element receive focus via the keyboard?
+ *
+ * Focusability is decided from the selector match plus the `tabindex`
+ * *attribute* — deliberately not the `tabIndex` property. The property is
+ * derived: a browser reports `0` for a native `<button>` that never declared
+ * one, and DOM implementations disagree about which elements get that
+ * treatment. Reading the attribute asks what the markup actually says, and
+ * "natively focusable unless it opted out" is then a rule this function states
+ * rather than one it inherits from whichever DOM it is running in.
+ */
+export function isFocusable(el: Element): el is HTMLElement {
+	if (!(el instanceof HTMLElement)) return false;
+	if (!el.matches(FOCUSABLE_SELECTOR)) return false;
+	if (el.hasAttribute("disabled")) return false;
+	if (el.getAttribute("aria-hidden") === "true") return false;
+
+	const declared = el.getAttribute("tabindex");
+	if (declared !== null && Number.parseInt(declared, 10) < 0) return false;
+
+	return isVisible(el);
+}
+
+/**
+ * Every focusable descendant of `root`, in tab order.
+ *
+ * Document order is returned as-is. Honouring positive `tabindex` values would
+ * mean a second sort, and nebula never emits one — a positive tabindex breaks
+ * the tab order of the whole page, so the library treats its presence in host
+ * markup as the host's problem rather than reordering around it.
+ */
+export function focusableWithin(root: ParentNode): HTMLElement[] {
+	const found: HTMLElement[] = [];
+	for (const candidate of root.querySelectorAll(FOCUSABLE_SELECTOR)) {
+		if (isFocusable(candidate)) found.push(candidate);
+	}
+	return found;
+}
+
+/** First focusable descendant, or `null` when the subtree has none. */
+export function firstFocusable(root: ParentNode): HTMLElement | null {
+	for (const candidate of root.querySelectorAll(FOCUSABLE_SELECTOR)) {
+		if (isFocusable(candidate)) return candidate;
+	}
+	return null;
+}
+
+/**
+ * Focus an element without scrolling the page to it.
+ *
+ * Overlays position themselves; letting the browser scroll to the newly
+ * focused node fights that positioning and visibly jumps the page.
+ */
+export function focusSilently(el: HTMLElement | null | undefined): void {
+	el?.focus({ preventScroll: true });
+}

package/src/primitives/index.ts

@@ -0,0 +1,88 @@
+/**
+ * Headless primitives — the behaviour layer nebula owns instead of Radix.
+ *
+ * shadcn/ui is styling on top of Radix. Radix is React-only, so porting the
+ * styling alone would leave every interactive component inert. These modules
+ * are that missing half, written against Aurora's signals and DOM: focus
+ * management, layer dismissal, placement, presence, roving focus, type-ahead
+ * and controlled/uncontrolled state.
+ *
+ * They are deliberately usable on their own. A component the registry does not
+ * ship — an app's own combobox, a bespoke overlay — should be able to reach
+ * for the same trap and the same layer stack rather than growing a second,
+ * subtly different implementation next door.
+ */
+
+export {
+	type Controllable,
+	type ControllableOptions,
+	controllable,
+} from "./controllable.js";
+export {
+	type DismissableLayer,
+	type DismissableOptions,
+	type DismissReason,
+	dismissable,
+	layerCount,
+} from "./dismissable.js";
+export {
+	type Align,
+	type AutoPosition,
+	type AutoPositionOptions,
+	autoPosition,
+	type Placement,
+	type Position,
+	type PositionOptions,
+	type Rect,
+	resolvePosition,
+	type Side,
+	type Viewport,
+} from "./floating.js";
+export {
+	type FloatingSurfaceOptions,
+	floatingSurface,
+} from "./floatingSurface.js";
+export {
+	firstFocusable,
+	focusableWithin,
+	focusSilently,
+	isFocusable,
+	isVisible,
+} from "./focusable.js";
+export {
+	type FocusTrap,
+	type FocusTrapOptions,
+	focusTrap,
+} from "./focusTrap.js";
+export {
+	type MenuAction,
+	type MenuCheckbox,
+	type MenuEntry,
+	type MenuLabel,
+	type MenuRadioGroup,
+	type MenuSeparator,
+	type MenuSubmenu,
+	menuPanel,
+	menuPanelClasses,
+	wireMenu,
+} from "./menu.js";
+export { type ModalSurfaceOptions, modalSurface } from "./modalSurface.js";
+export { type Portal, type PortalOptions, portal } from "./portal.js";
+export {
+	onExitFinished,
+	type Presence,
+	type PresenceState,
+	presence,
+} from "./presence.js";
+export {
+	type Orientation,
+	type RovingFocus,
+	type RovingFocusOptions,
+	rovingFocus,
+} from "./rovingFocus.js";
+export { isScrollLocked, lockScroll } from "./scrollLock.js";
+export {
+	type Typeahead,
+	type TypeaheadOptions,
+	typeahead,
+} from "./typeahead.js";