@c9up/nebula 0.1.0

package/src/organisms/DropdownMenu.ts

@@ -0,0 +1,112 @@
+/**
+ * DropdownMenu — a menu opened from a button.
+ *
+ * The panel, its entries and its keyboard model all come from `./menu.js`;
+ * this component contributes the trigger and the open/close state.
+ *
+ * Two behaviours are specific to a button-opened menu:
+ *
+ * - Opening with the keyboard focuses the first item; opening with the pointer
+ *   does not. A keyboard user has no other way in, while pre-highlighting an
+ *   item for a mouse user suggests it is about to be chosen.
+ * - ArrowDown on the trigger opens the menu *and* enters it, which is the
+ *   behaviour of every native menu button and the one users try first.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { type Slot, slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { type Reactive, read } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.js";
+import type { Placement } from "../primitives/floating.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+import { type MenuEntry, menuPanel, wireMenu } from "../primitives/menu.js";
+
+export interface DropdownMenuProps {
+	trigger?: Slot;
+	entries: readonly MenuEntry[];
+	open?: Reactive<boolean>;
+	defaultOpen?: boolean;
+	onOpenChange?: (open: boolean) => void;
+	placement?: Placement;
+	class?: Reactive<string>;
+	triggerClass?: Reactive<string>;
+	contentClass?: Reactive<string>;
+}
+
+export const DropdownMenu = component<DropdownMenuProps>((props) => {
+	const triggerId = uid("dropdown-trigger");
+	const contentId = uid("dropdown-content");
+
+	const state = controllable<boolean>({
+		value: props.open,
+		initial: props.defaultOpen ?? false,
+		onChange: props.onOpenChange,
+	});
+
+	// Set by the trigger's key handler just before opening, and consumed by
+	// `onOpened`. The panel does not exist yet at the moment of the keypress, so
+	// the intent has to survive the gap.
+	let enterOnOpen = false;
+	let unwire: (() => void) | null = null;
+
+	function close(): void {
+		state.set(false);
+	}
+
+	floatingSurface({
+		anchor: () => document.getElementById(triggerId),
+		open: () => state.current(),
+		onClose: close,
+		placement: props.placement ?? "bottom-start",
+		offset: 4,
+		content: () =>
+			menuPanel({
+				id: contentId,
+				entries: props.entries,
+				onCloseAll: close,
+				labelledBy: triggerId,
+				class: read(props.contentClass),
+			}),
+		onOpened: (panel) => {
+			const enterItems = enterOnOpen;
+			enterOnOpen = false;
+			unwire = wireMenu(panel, {
+				onCloseAll: close,
+				autoFocusFirst: enterItems,
+			});
+			// The panel takes focus only when no item did — it needs to hold focus
+			// so Escape and the arrows reach it rather than the page behind, but
+			// focusing it unconditionally steals focus straight back from the item
+			// `autoFocusFirst` just landed on, and opening with the keyboard would
+			// never reach the first entry.
+			if (!enterItems) panel.focus({ preventScroll: true });
+		},
+		onClosed: () => {
+			unwire?.();
+			unwire = null;
+		},
+	});
+
+	function onTriggerKeyDown(event: KeyboardEvent): void {
+		if (event.key !== "ArrowDown" && event.key !== "Enter" && event.key !== " ")
+			return;
+		event.preventDefault();
+		enterOnOpen = true;
+		state.set(true);
+	}
+
+	return html`<button
+		type="button"
+		data-slot="dropdown-menu-trigger"
+		id="${triggerId}"
+		aria-haspopup="menu"
+		aria-expanded="${() => (state.current() ? "true" : "false")}"
+		aria-controls="${() => (state.current() ? contentId : undefined)}"
+		data-state="${() => (state.current() ? "open" : "closed")}"
+		class="${() => cn(read(props.triggerClass))}"
+		@click="${() => state.set(!state.current())}"
+		@keydown="${onTriggerKeyDown}"
+	>${slot(props.trigger)}</button>`;
+});

package/src/organisms/Form.ts

@@ -0,0 +1,217 @@
+/**
+ * Form — binding between Aurora's form controller and nebula's field markup.
+ *
+ * shadcn's Form is a set of adapters over `react-hook-form`, and none of that
+ * layer is needed here: Aurora already ships `form()`, a reactive controller
+ * with values, per-field errors, touched state, submit-in-flight and optional
+ * rune/zod-shaped validation. Reimplementing it would be a second source of
+ * truth for the same thing.
+ *
+ * So this file is only the join. It wires one field to one `Field` plus one
+ * control, and takes care of the three things that otherwise get forgotten:
+ * `aria-invalid` when the field has an error, `aria-describedby` pointing at
+ * the error element, and marking the field touched on blur so an error appears
+ * after leaving a field rather than while typing in it.
+ *
+ *   const login = form({
+ *     initial: { email: "", password: "" },
+ *     validate: (values) => (values.email === "" ? { email: "Required" } : {}),
+ *     submit: (values) => http.post("/login", values),
+ *   })
+ *
+ *   Form({
+ *     form: login,
+ *     children: [
+ *       TextField({ bind: bind(login, "email"), label: "Email", type: "email" }),
+ *       TextField({ bind: bind(login, "password"), label: "Password", type: "password" }),
+ *       SubmitButton({ form: login, label: "Sign in" }),
+ *     ],
+ *   })
+ */
+
+import type { Form as AuroraForm, FormField } from "@c9up/aurora";
+import { component, html } from "@c9up/aurora";
+import { Button } from "../atoms/Button.js";
+import { Input } from "../atoms/Input.js";
+import { Spinner } from "../atoms/Spinner.js";
+import { Textarea } from "../atoms/Textarea.js";
+import type { Child, Slot } from "../lib/children.js";
+import { slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { type Reactive, read } from "../lib/props.js";
+import { Field, fieldIds } from "../molecules/Field.js";
+
+/**
+ * One field, with a setter that already knows which key it writes to.
+ *
+ * This shape exists so the input components are not generic over the form.
+ * Inside a function generic in `T`, TypeScript cannot prove a `string` is
+ * assignable to `T[K]`, and the usual escape is a cast. `bind()` is called at
+ * a *concrete* call site, where `K` is a literal and `T[K]` resolves to a real
+ * type — so `bind(login, "email")` is a `FieldBinding<string>` and handing it
+ * to a numeric input is a compile error rather than a runtime surprise.
+ */
+export interface FieldBinding<V> {
+	readonly name: string;
+	readonly field: FormField<V>;
+	set(value: V): void;
+}
+
+/** Bind one key of a form. Call it at the field's own call site. */
+export function bind<T, K extends keyof T & string>(
+	form: AuroraForm<T>,
+	name: K,
+): FieldBinding<T[K]> {
+	return {
+		name,
+		field: form.field(name),
+		set: (value: T[K]) => form.set(name, value),
+	};
+}
+
+export interface FormProps<T> {
+	form: AuroraForm<T>;
+	children?: Slot;
+	class?: Reactive<string>;
+}
+
+/**
+ * The `<form>` element itself.
+ *
+ * `novalidate` on purpose. The browser's own validation bubbles cannot be
+ * styled, appear one at a time, and vanish on scroll — and they would fire
+ * before the controller's validation ever runs, so the user would see two
+ * different error presentations for the same field.
+ */
+export function Form<T>(props: FormProps<T>): ReturnType<typeof html> {
+	return html`<form
+		data-slot="form"
+		novalidate
+		class="${() => cn("flex flex-col gap-6", read(props.class))}"
+		@submit="${(event: Event) => {
+			void props.form.handleSubmit(event);
+		}}"
+	>${slot(props.children)}</form>`;
+}
+
+interface FieldShellProps {
+	bind: FieldBinding<string>;
+	label: Child;
+	description?: Child;
+	placeholder?: string;
+	required?: boolean;
+	disabled?: Reactive<boolean>;
+}
+
+export interface TextFieldProps extends FieldShellProps {
+	type?: string;
+	autocomplete?: string;
+}
+
+/**
+ * A labelled text input bound to one field.
+ *
+ * The error is shown only once the field has been touched, which is what stops
+ * a pristine form opening with "Required" under every empty box.
+ *
+ * When errors actually appear is Aurora's decision, not this file's, and it is
+ * worth knowing: `form()` populates them on `validate()` — which `handleSubmit`
+ * calls — and clears a field's error as soon as it is written to. So the
+ * sequence is: submit, see every problem at once, and watch each one disappear
+ * as it is fixed. Typing into an untouched field does not raise an error, and
+ * `markTouched` on blur does not validate; it only lifts the gate for an error
+ * that validation has already found.
+ */
+export const TextField = component<TextFieldProps>((props) => {
+	const ids = fieldIds();
+	const { field, set, name } = props.bind;
+	const visibleError = (): string | undefined =>
+		field.touched() ? (field.error() ?? undefined) : undefined;
+
+	return Field({
+		ids,
+		label: props.label,
+		description: props.description,
+		error: visibleError,
+		required: props.required,
+		disabled: props.disabled,
+		children: Input({
+			id: ids.control,
+			name,
+			type: props.type ?? "text",
+			placeholder: props.placeholder,
+			autocomplete: props.autocomplete,
+			required: props.required,
+			disabled: props.disabled,
+			invalid: () => visibleError() !== undefined,
+			describedBy: ids.describedBy,
+			value: () => field.value(),
+			onInput: set,
+			onBlur: () => field.markTouched(),
+		}),
+	});
+});
+
+export interface TextAreaFieldProps extends FieldShellProps {
+	rows?: number;
+}
+
+/** The same, with a multi-line control. */
+export const TextAreaField = component<TextAreaFieldProps>((props) => {
+	const ids = fieldIds();
+	const { field, set, name } = props.bind;
+	const visibleError = (): string | undefined =>
+		field.touched() ? (field.error() ?? undefined) : undefined;
+
+	return Field({
+		ids,
+		label: props.label,
+		description: props.description,
+		error: visibleError,
+		required: props.required,
+		disabled: props.disabled,
+		children: Textarea({
+			id: ids.control,
+			name,
+			rows: props.rows,
+			placeholder: props.placeholder,
+			required: props.required,
+			disabled: props.disabled,
+			invalid: () => visibleError() !== undefined,
+			describedBy: ids.describedBy,
+			value: () => field.value(),
+			onInput: set,
+			onBlur: () => field.markTouched(),
+		}),
+	});
+});
+
+export interface SubmitButtonProps<T> {
+	form: AuroraForm<T>;
+	label: Child;
+	/** Replaces the label while the submit is in flight. */
+	pendingLabel?: Child;
+	class?: Reactive<string>;
+}
+
+/**
+ * A submit button that disables itself while the submit is in flight.
+ *
+ * Disabled on `submitting` only — never on `!valid`. A submit button that is
+ * dead until the form is correct gives the user nothing to press and no
+ * explanation; pressing it and seeing every error at once is how a form tells
+ * you what is wrong.
+ */
+export function SubmitButton<T>(
+	props: SubmitButtonProps<T>,
+): ReturnType<typeof html> {
+	return Button({
+		type: "submit",
+		disabled: () => props.form.submitting(),
+		class: props.class,
+		children: () =>
+			props.form.submitting()
+				? [Spinner({ class: "mr-2" }), props.pendingLabel ?? props.label]
+				: props.label,
+	});
+}

package/src/organisms/HoverCard.ts

@@ -0,0 +1,92 @@
+/**
+ * HoverCard — a rich preview shown on hover.
+ *
+ * A Tooltip carries a phrase; a HoverCard carries content — an avatar, a
+ * summary, a link. That difference drives every behavioural difference between
+ * the two.
+ *
+ * It opens more slowly, because the payload is heavier and a card flashing
+ * past is worse than a tooltip flashing past. It closes more slowly, because
+ * the user is expected to move the pointer *into* it. And it is never the only
+ * route to what it contains: pointer-only content is unreachable by keyboard
+ * and touch, so a hover card must preview something a click already reaches.
+ *
+ * `role="dialog"` rather than `tooltip`, since it holds interactive content —
+ * a tooltip's contents are announced as a description, which is wrong for
+ * something containing a link.
+ */
+
+import { component, html, onUnmount, signal } from "@c9up/aurora";
+import { type Slot, slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { zoomInOut } from "../lib/motion.js";
+import { type Reactive, read } from "../lib/props.js";
+import type { Placement } from "../primitives/floating.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+
+const OPEN_DELAY_MS = 700;
+const CLOSE_DELAY_MS = 300;
+
+export interface HoverCardProps {
+	trigger?: Slot;
+	children?: Slot;
+	placement?: Placement;
+	openDelay?: number;
+	closeDelay?: number;
+	class?: Reactive<string>;
+	contentClass?: Reactive<string>;
+}
+
+export const HoverCard = component<HoverCardProps>((props) => {
+	const triggerId = uid("hover-card-trigger");
+	const contentId = uid("hover-card-content");
+	const open = signal(false);
+
+	let timer: ReturnType<typeof setTimeout> | undefined;
+
+	function clear(): void {
+		if (timer !== undefined) clearTimeout(timer);
+		timer = undefined;
+	}
+
+	function schedule(next: boolean, delay: number): void {
+		clear();
+		timer = setTimeout(() => open(next), delay);
+	}
+
+	onUnmount(clear);
+
+	floatingSurface({
+		anchor: () => document.getElementById(triggerId),
+		open: () => open(),
+		onClose: () => {
+			clear();
+			open(false);
+		},
+		placement: props.placement ?? "bottom",
+		offset: 8,
+		content: () =>
+			html`<div
+				data-slot="hover-card-content"
+				id="${contentId}"
+				role="dialog"
+				aria-labelledby="${triggerId}"
+				class="${cn(
+					"bg-popover text-popover-foreground z-50 w-64 rounded-md border p-4 shadow-md outline-none",
+					zoomInOut,
+					read(props.contentClass),
+				)}"
+				@pointerenter="${clear}"
+				@pointerleave="${() => schedule(false, props.closeDelay ?? CLOSE_DELAY_MS)}"
+			>${slot(props.children)}</div>`,
+	});
+
+	return html`<span
+		data-slot="hover-card-trigger"
+		id="${triggerId}"
+		class="${() => cn("inline-flex", read(props.class))}"
+		@pointerenter="${() => schedule(true, props.openDelay ?? OPEN_DELAY_MS)}"
+		@pointerleave="${() => schedule(false, props.closeDelay ?? CLOSE_DELAY_MS)}"
+	>${slot(props.trigger)}</span>`;
+});

package/src/organisms/Menubar.ts

@@ -0,0 +1,167 @@
+/**
+ * Menubar — an application menu bar.
+ *
+ * A row of menu buttons where at most one menu is open. The behaviour that
+ * makes it a menubar rather than a row of independent dropdowns is the
+ * handover: once a menu is open, moving the pointer onto a neighbouring button
+ * switches to it without a click, and ArrowLeft/ArrowRight do the same from
+ * the keyboard. That is how every desktop menu bar behaves, and a row of
+ * dropdowns that each need their own click is the thing users notice.
+ *
+ * One `floatingSurface` for the bar, not one per menu. The open menu is an
+ * index, so switching moves the same surface to a new anchor instead of
+ * closing one and opening another — which would flash, and would lose the
+ * exit animation into the entry animation.
+ */
+
+import { component, html, signal } from "@c9up/aurora";
+import type { Child } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { type Reactive, read } from "../lib/props.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+import { type MenuEntry, menuPanel, wireMenu } from "../primitives/menu.js";
+
+export interface MenubarMenu {
+	label: Child;
+	entries: readonly MenuEntry[];
+	disabled?: boolean;
+}
+
+export interface MenubarProps {
+	menus: readonly MenubarMenu[];
+	class?: Reactive<string>;
+}
+
+export const Menubar = component<MenubarProps>((props) => {
+	const contentId = uid("menubar-content");
+	const triggerIds = props.menus.map(() => uid("menubar-trigger"));
+	/** Index of the open menu, or `-1`. */
+	const openIndex = signal(-1);
+
+	let unwire: (() => void) | null = null;
+	let focusFirstOnOpen = false;
+
+	function close(): void {
+		openIndex(-1);
+	}
+
+	function openAt(index: number, withKeyboard: boolean): void {
+		if (props.menus[index]?.disabled === true) return;
+		focusFirstOnOpen = withKeyboard;
+		openIndex(index);
+	}
+
+	function move(delta: number): void {
+		const count = props.menus.length;
+		if (count === 0) return;
+		const from = openIndex();
+		if (from === -1) return;
+		openAt((from + delta + count) % count, true);
+	}
+
+	floatingSurface({
+		anchor: () => {
+			const id = triggerIds[openIndex()];
+			return id === undefined ? null : document.getElementById(id);
+		},
+		open: () => openIndex() !== -1,
+		onClose: close,
+		placement: "bottom-start",
+		offset: 4,
+		content: () =>
+			menuPanel({
+				id: contentId,
+				entries: props.menus[openIndex()]?.entries ?? [],
+				onCloseAll: close,
+				labelledBy: triggerIds[openIndex()],
+			}),
+		onOpened: (panel) => {
+			const enterItems = focusFirstOnOpen;
+			focusFirstOnOpen = false;
+			unwire = wireMenu(panel, {
+				onCloseAll: close,
+				autoFocusFirst: enterItems,
+			});
+			// Only when no item took focus. Focusing the panel unconditionally
+			// steals focus back from the item `autoFocusFirst` just landed on, and
+			// opening a menu with the keyboard would never reach its first entry.
+			if (!enterItems) panel.focus({ preventScroll: true });
+			// Left/right walk the bar from inside the open panel. `menu.js` claims
+			// ArrowLeft for closing a submenu and stops propagation when it does,
+			// so this only fires at the top level.
+			panel.addEventListener("keydown", onPanelKeyDown);
+		},
+		onClosed: () => {
+			unwire?.();
+			unwire = null;
+		},
+	});
+
+	function onPanelKeyDown(event: KeyboardEvent): void {
+		if (event.key === "ArrowRight") {
+			event.preventDefault();
+			move(1);
+		} else if (event.key === "ArrowLeft") {
+			event.preventDefault();
+			move(-1);
+		}
+	}
+
+	return html`<div
+		data-slot="menubar"
+		role="menubar"
+		class="${() =>
+			cn(
+				"bg-background flex h-9 items-center gap-1 rounded-md border p-1 shadow-xs",
+				read(props.class),
+			)}"
+	>
+		${props.menus.map((menu, index) => renderTrigger(menu, index))}
+	</div>`;
+
+	function renderTrigger(menu: MenubarMenu, index: number): Child {
+		return html`<button
+			type="button"
+			role="menuitem"
+			data-slot="menubar-trigger"
+			id="${triggerIds[index]}"
+			aria-haspopup="menu"
+			aria-expanded="${() => (openIndex() === index ? "true" : "false")}"
+			aria-controls="${() => (openIndex() === index ? contentId : undefined)}"
+			data-state="${() => (openIndex() === index ? "open" : "closed")}"
+			?disabled="${menu.disabled === true}"
+			class="focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground flex select-none items-center rounded-sm px-2 py-1 text-sm font-medium outline-none disabled:pointer-events-none disabled:opacity-50"
+			@click="${() => (openIndex() === index ? close() : openAt(index, false))}"
+			@pointerenter="${() => {
+				// Hover switches menus only while one is already open — otherwise
+				// the bar would spring menus at a pointer merely passing over it.
+				if (openIndex() !== -1) openAt(index, false);
+			}}"
+			@keydown="${(event: KeyboardEvent) => {
+				if (
+					event.key === "ArrowDown" ||
+					event.key === "Enter" ||
+					event.key === " "
+				) {
+					event.preventDefault();
+					openAt(index, true);
+				} else if (event.key === "ArrowRight") {
+					event.preventDefault();
+					focusTrigger(index + 1);
+				} else if (event.key === "ArrowLeft") {
+					event.preventDefault();
+					focusTrigger(index - 1);
+				}
+			}}"
+		>${menu.label}</button>`;
+	}
+
+	function focusTrigger(index: number): void {
+		const count = props.menus.length;
+		if (count === 0) return;
+		const id = triggerIds[(index + count) % count];
+		if (id === undefined) return;
+		document.getElementById(id)?.focus({ preventScroll: true });
+	}
+});