@c9up/nebula 0.1.0

package/src/lib/motion.ts

@@ -0,0 +1,48 @@
+/**
+ * Enter and exit animations for overlays.
+ *
+ * shadcn drives these with `animate-in` / `animate-out` from `tw-animate-css`
+ * — a Tailwind plugin, and a dependency. nebula declares the four keyframes it
+ * needs in `theme.css` and references them through arbitrary animation values,
+ * which every one of the three adapters supports and none of them needs a
+ * plugin for.
+ *
+ * The durations are asymmetric on purpose: entering is slower than leaving.
+ * A surface appearing wants to be noticed, a surface dismissed wants to be out
+ * of the way — matching them makes closing feel sluggish.
+ *
+ * Every string ends in `motion-reduce:animate-none`. That is not only a
+ * courtesy: `onExitFinished` reads the computed style to decide whether to
+ * wait, sees no animation, and removes the node immediately. Reduced motion
+ * therefore gets an instant close rather than a delayed one, with no branch in
+ * the component.
+ */
+
+import type { Side } from "../primitives/floating.js";
+
+/** Popovers, menus, selects — scale up from the anchor. */
+export const zoomInOut =
+	"data-[state=open]:animate-[nebula-zoom-in_150ms_ease-out] data-[state=closed]:animate-[nebula-zoom-out_120ms_ease-in] motion-reduce:animate-none";
+
+/** Backdrops and tooltips — no movement, just opacity. */
+export const fadeInOut =
+	"data-[state=open]:animate-[nebula-fade-in_150ms_ease-out] data-[state=closed]:animate-[nebula-fade-out_120ms_ease-in] motion-reduce:animate-none";
+
+/**
+ * Panels that slide in from an edge — Sheet, Drawer.
+ *
+ * The transform is a utility pair rather than a keyframe, because the distance
+ * depends on the panel's own size and only `translate-x-full` knows that.
+ */
+export function slideFrom(side: Side): string {
+	const axis =
+		side === "left"
+			? "data-[state=closed]:-translate-x-full"
+			: side === "right"
+				? "data-[state=closed]:translate-x-full"
+				: side === "top"
+					? "data-[state=closed]:-translate-y-full"
+					: "data-[state=closed]:translate-y-full";
+
+	return `transition-transform duration-300 ease-in-out data-[state=open]:translate-x-0 data-[state=open]:translate-y-0 ${axis} motion-reduce:transition-none`;
+}

package/src/lib/props.ts

@@ -0,0 +1,83 @@
+/**
+ * Reactive prop plumbing.
+ *
+ * React components take plain values and re-render. Aurora never re-renders —
+ * a binding stays live because the value handed to it is a signal or a plain
+ * accessor function, which the renderer wraps in an `effect()`. So every
+ * nebula prop that can change over time is typed `Reactive<T>`: pass a
+ * constant when it never moves, pass `() => count() > 3` when it does.
+ *
+ *   Button({ disabled: true })              // static
+ *   Button({ disabled: () => !form.valid })  // live
+ *
+ * `read()` collapses either form to a value. `accessor()` does the opposite —
+ * it hands the renderer something it can always subscribe to, which is what
+ * you want inside a template so the static case does not silently freeze a
+ * binding that a sibling prop makes dynamic.
+ */
+
+/** A prop value that may be constant or recomputed on demand. */
+export type Reactive<T> = T | (() => T);
+
+/**
+ * Is this prop the accessor form?
+ *
+ * A type predicate rather than a cast: `Reactive<T>` where `T` is itself a
+ * function type is genuinely ambiguous, and nebula resolves it one way on
+ * purpose — a function always means "call me". No nebula prop is typed to
+ * receive a function as its *value*; callbacks (`onClick`, `onValueChange`)
+ * have their own prop types and never pass through here.
+ */
+function isAccessor<T>(value: Reactive<T>): value is () => T {
+	return typeof value === "function";
+}
+
+/**
+ * Collapse a reactive prop to its current value.
+ *
+ * An absent prop stays `undefined` rather than throwing, because that is
+ * exactly what `cva` wants: an axis left `undefined` falls back to its default
+ * variant. It lets a component forward props straight through —
+ * `buttonVariants({ variant: read(props.variant) })` — with no per-prop
+ * presence check, which is the difference between two lines and ten in every
+ * component in the library.
+ */
+export function read<T>(value: Reactive<T>): T;
+export function read<T>(value: Reactive<T> | undefined): T | undefined;
+export function read<T>(value: Reactive<T> | undefined): T | undefined {
+	if (value === undefined) return undefined;
+	return isAccessor(value) ? value() : value;
+}
+
+/** Collapse an optional reactive prop, falling back when it is absent. */
+export function readOr<T>(value: Reactive<T> | undefined, fallback: T): T {
+	if (value === undefined) return fallback;
+	return isAccessor(value) ? value() : value;
+}
+
+/**
+ * Turn any prop into an accessor the renderer can subscribe to.
+ *
+ * Templates should bind `${accessor(props.disabled, false)}` rather than
+ * `${readOr(props.disabled, false)}`: the second reads once at construction
+ * and the attribute never updates again.
+ */
+export function accessor<T>(
+	value: Reactive<T> | undefined,
+	fallback: T,
+): () => T {
+	return () => readOr(value, fallback);
+}
+
+/**
+ * Call a handler if one was supplied.
+ *
+ * Saves every component the `props.onClick?.(event)` dance and keeps the
+ * optional-callback shape identical across the library.
+ */
+export function callHandler<A extends readonly unknown[]>(
+	handler: ((...args: A) => void) | undefined,
+	...args: A
+): void {
+	handler?.(...args);
+}

package/src/lib/styled.ts

@@ -0,0 +1,60 @@
+/**
+ * Purely presentational parts.
+ *
+ * A compound component like Card is one interesting element and half a dozen
+ * styled boxes — `CardHeader`, `CardContent`, `CardFooter` and friends carry a
+ * class string, a `data-slot`, and nothing else. Written out longhand that is
+ * eight near-identical lines each, thirty times over, and the differences that
+ * matter get lost in the repetition.
+ *
+ * So the boxes are declared, not written:
+ *
+ *   export const CardHeader = styledDiv("card-header", "flex flex-col gap-1.5 px-6")
+ *
+ * Only for parts with no behaviour. The moment one needs an event, a piece of
+ * state or an ARIA relationship it gets written out in full — hiding those
+ * behind a factory is how a component becomes hard to read, which matters
+ * doubly here because the registry copies this source into user projects for
+ * them to edit.
+ */
+
+import { component, html, type TemplateResult } from "@c9up/aurora";
+import { type Slot, slot } from "./children.js";
+import { cn } from "./cn.js";
+import { type Reactive, read } from "./props.js";
+
+export interface StyledProps {
+	children?: Slot;
+	class?: Reactive<string>;
+	id?: string;
+}
+
+/** A `<div>` carrying a `data-slot` and a base class list. */
+export function styledDiv(
+	name: string,
+	base: string,
+): (props?: StyledProps) => TemplateResult {
+	return component<StyledProps>(
+		(props) =>
+			html`<div
+				data-slot="${name}"
+				id="${props.id}"
+				class="${() => cn(base, read(props.class))}"
+			>${slot(props.children)}</div>`,
+	);
+}
+
+/** The same, as an inline `<span>`. */
+export function styledSpan(
+	name: string,
+	base: string,
+): (props?: StyledProps) => TemplateResult {
+	return component<StyledProps>(
+		(props) =>
+			html`<span
+				data-slot="${name}"
+				id="${props.id}"
+				class="${() => cn(base, read(props.class))}"
+			>${slot(props.children)}</span>`,
+	);
+}

package/src/molecules/Accordion.ts

@@ -0,0 +1,161 @@
+/**
+ * Accordion — a stack of collapsible sections.
+ *
+ * Data-driven rather than composed: an accordion is a list, and describing it
+ * as one is both shorter to write and the only shape that lets the group
+ * enforce `type: "single"` — which needs to know about every section at once,
+ * something Radix can only do through context.
+ *
+ * The keyboard behaviour is the WAI-ARIA accordion pattern, delegated to
+ * `rovingFocus` over the headers: arrows move between sections, Home and End
+ * jump to the ends, and the headers are one tab stop rather than one each.
+ */
+
+import { component, html, onMount, onUnmount, signal } from "@c9up/aurora";
+import type { Child, Slot } from "../lib/children.js";
+import { slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { ChevronDownIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { type Reactive, read } from "../lib/props.js";
+import { type RovingFocus, rovingFocus } from "../primitives/rovingFocus.js";
+
+export interface AccordionItem {
+	/** Stable key. Used for the open-state set and for the ARIA ids. */
+	value: string;
+	/** The header content. */
+	trigger: Child;
+	/** The panel content. */
+	content: Slot;
+	disabled?: boolean;
+}
+
+export interface AccordionProps {
+	items: readonly AccordionItem[];
+	/** `"single"` closes the open section when another opens. Default `"single"`. */
+	type?: "single" | "multiple";
+	/** Open at first render. A string, or several for `type: "multiple"`. */
+	defaultValue?: string | readonly string[];
+	/** `"single"` accordions can normally be closed entirely. */
+	collapsible?: boolean;
+	onValueChange?: (open: readonly string[]) => void;
+	class?: Reactive<string>;
+}
+
+export const Accordion = component<AccordionProps>((props) => {
+	const type = props.type ?? "single";
+	const open = signal<readonly string[]>(normaliseInitial(props.defaultValue));
+	const rootId = uid("accordion");
+
+	function isOpen(value: string): boolean {
+		return open().includes(value);
+	}
+
+	function toggle(value: string): void {
+		const current = open();
+		const next = nextOpenSet(current, value, type, props.collapsible !== false);
+		open(next);
+		props.onValueChange?.(next);
+	}
+
+	// Roving focus is attached after mount because it queries the container for
+	// its items, and the container does not exist until then.
+	let group: RovingFocus | undefined;
+	onMount(() => {
+		group = rovingFocus({
+			container: () => document.getElementById(rootId),
+			itemSelector: "[data-slot='accordion-trigger']",
+			orientation: "vertical",
+		});
+		group.sync();
+	});
+	onUnmount(() => group?.destroy());
+
+	return html`<div
+		data-slot="accordion"
+		id="${rootId}"
+		class="${() => cn("flex w-full flex-col", read(props.class))}"
+	>
+		${props.items.map((item) => renderItem(item, isOpen, toggle))}
+	</div>`;
+});
+
+function renderItem(
+	item: AccordionItem,
+	isOpen: (value: string) => boolean,
+	toggle: (value: string) => void,
+): Child {
+	const triggerId = uid("accordion-trigger");
+	const panelId = uid("accordion-panel");
+	const state = (): string => (isOpen(item.value) ? "open" : "closed");
+
+	return html`<div
+		data-slot="accordion-item"
+		data-state="${state}"
+		class="border-b last:border-b-0"
+	>
+		<h3 class="flex">
+			<button
+				type="button"
+				data-slot="accordion-trigger"
+				data-nebula-item
+				data-state="${state}"
+				data-disabled="${item.disabled === true ? "" : undefined}"
+				id="${triggerId}"
+				aria-expanded="${() => (isOpen(item.value) ? "true" : "false")}"
+				aria-controls="${panelId}"
+				?disabled="${item.disabled === true}"
+				class="focus-visible:border-ring focus-visible:ring-ring/50 flex flex-1 items-start justify-between gap-4 rounded-md py-4 text-left text-sm font-medium outline-none transition-all hover:underline focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 [&[data-state=open]>svg]:rotate-180"
+				@click="${() => toggle(item.value)}"
+			>
+				${item.trigger}
+				${ChevronDownIcon({
+					class:
+						"text-muted-foreground pointer-events-none size-4 shrink-0 translate-y-0.5 transition-transform duration-200",
+				})}
+			</button>
+		</h3>
+		<div
+			data-slot="accordion-content"
+			id="${panelId}"
+			role="region"
+			aria-labelledby="${triggerId}"
+			?inert="${() => !isOpen(item.value)}"
+			class="grid text-sm transition-[grid-template-rows] duration-200 ease-out motion-reduce:transition-none"
+			style="${() => `grid-template-rows: ${isOpen(item.value) ? "1fr" : "0fr"}`}"
+		>
+			<div class="overflow-hidden"><div class="pt-0 pb-4">${slot(item.content)}</div></div>
+		</div>
+	</div>`;
+}
+
+function normaliseInitial(
+	value: string | readonly string[] | undefined,
+): readonly string[] {
+	if (value === undefined) return [];
+	return typeof value === "string" ? [value] : value;
+}
+
+/**
+ * The open set after activating `value`.
+ *
+ * `collapsible: false` on a single accordion is what stops the last open
+ * section from closing — the pattern used when one section must always be
+ * showing, and the reason this is not simply a toggle.
+ */
+function nextOpenSet(
+	current: readonly string[],
+	value: string,
+	type: "single" | "multiple",
+	collapsible: boolean,
+): readonly string[] {
+	const isOpen = current.includes(value);
+
+	if (type === "multiple") {
+		return isOpen
+			? current.filter((entry) => entry !== value)
+			: [...current, value];
+	}
+	if (isOpen) return collapsible ? [] : current;
+	return [value];
+}

package/src/molecules/Alert.ts

@@ -0,0 +1,58 @@
+/**
+ * Alert — an inline message about the surrounding content.
+ *
+ * `role="alert"` only for the destructive variant. The role is a live region:
+ * it interrupts a screen reader the moment the element appears. That is right
+ * for an error and wrong for the informational variant, which would talk over
+ * whatever the user was reading to announce something they did not ask about.
+ *
+ * The grid layout is what lets an optional leading icon align with the title
+ * while the description wraps under both, without either part knowing whether
+ * the other is present.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { type Slot, slot } from "../lib/children.js";
+import { cva, type VariantProps } from "../lib/cva.js";
+import { type Reactive, read, readOr } from "../lib/props.js";
+import { styledDiv } from "../lib/styled.js";
+
+export const alertVariants = cva(
+	"relative grid w-full grid-cols-[0_1fr] items-start gap-y-0.5 rounded-lg border px-4 py-3 text-sm has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] has-[>svg]:gap-x-3 [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current",
+	{
+		variants: {
+			variant: {
+				default: "bg-card text-card-foreground",
+				destructive:
+					"text-destructive bg-card [&>svg]:text-current *:data-[slot=alert-description]:text-destructive/90",
+			},
+		},
+		defaultVariants: { variant: "default" },
+	},
+);
+
+export type AlertVariants = VariantProps<typeof alertVariants>;
+
+export interface AlertProps {
+	children?: Slot;
+	variant?: Reactive<AlertVariants["variant"]>;
+	class?: Reactive<string>;
+}
+
+export const Alert = component<AlertProps>((props) => {
+	return html`<div
+		data-slot="alert"
+		role="${() => (readOr(props.variant, "default") === "destructive" ? "alert" : "note")}"
+		class="${() => alertVariants({ variant: read(props.variant), class: read(props.class) })}"
+	>${slot(props.children)}</div>`;
+});
+
+export const AlertTitle = styledDiv(
+	"alert-title",
+	"col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight",
+);
+
+export const AlertDescription = styledDiv(
+	"alert-description",
+	"text-muted-foreground col-start-2 grid justify-items-start gap-1 text-sm [&_p]:leading-relaxed",
+);

package/src/molecules/Attachment.ts

@@ -0,0 +1,132 @@
+/**
+ * Attachment — a file carried by a message.
+ *
+ * Two shapes from one component: an image renders as a thumbnail, anything
+ * else as a chip with a name and a size. Splitting them into two components
+ * would push the choice onto the caller, who usually has a MIME type and no
+ * opinion.
+ *
+ * The size is formatted in binary units because that is what a file manager
+ * shows for the same file — a "1.2 MB" here and a "1.1 MiB" there for one
+ * upload reads as a bug.
+ *
+ * A removable attachment is a `<button>` beside the link, never a click
+ * handler on the chip itself. Merging the two makes "open" and "delete" the
+ * same gesture, distinguished only by where you land.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { cn } from "../lib/cn.js";
+import { XIcon } from "../lib/icons.js";
+import { type Reactive, read } from "../lib/props.js";
+
+export interface AttachmentProps {
+	name: string;
+	/** Bytes. Omitted for something not yet uploaded. */
+	size?: number;
+	/** MIME type. Anything under `image/` renders as a thumbnail. */
+	type?: string;
+	/** Opens the file. Without it the chip is inert. */
+	href?: string;
+	/** Thumbnail source, for an image. Defaults to `href`. */
+	previewSrc?: string;
+	/** Shows a remove button. */
+	onRemove?: () => void;
+	class?: Reactive<string>;
+}
+
+/**
+ * Human-readable byte count, binary units.
+ *
+ * Deliberately not `Intl.NumberFormat`'s `unit: "byte"` style: it only speaks
+ * decimal units (kB, MB), which disagrees with every desktop file manager.
+ */
+export function formatBytes(bytes: number): string {
+	if (!Number.isFinite(bytes) || bytes < 0) return "";
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["KB", "MB", "GB", "TB"];
+	let value = bytes / 1024;
+	let unit = 0;
+	while (value >= 1024 && unit < units.length - 1) {
+		value /= 1024;
+		unit += 1;
+	}
+	// One decimal below 10, none above — "9.4 MB" is useful, "941.3 MB" is noise.
+	return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+}
+
+export const Attachment = component<AttachmentProps>((props) => {
+	const isImage = props.type?.startsWith("image/") === true;
+	const preview = props.previewSrc ?? props.href;
+
+	const removeButton =
+		props.onRemove === undefined
+			? null
+			: html`<button
+					type="button"
+					data-slot="attachment-remove"
+					aria-label="${`Remove ${props.name}`}"
+					class="text-muted-foreground hover:text-foreground absolute end-1 top-1 rounded-sm bg-background/80 p-0.5 transition-colors"
+					@click="${() => props.onRemove?.()}"
+				>${XIcon({ class: "size-3.5" })}</button>`;
+
+	if (isImage && preview !== undefined) {
+		return html`<div
+			data-slot="attachment"
+			data-kind="image"
+			class="${() => cn("relative w-fit overflow-hidden rounded-md border", read(props.class))}"
+		>
+			<a href="${props.href}" class="block">
+				<img
+					src="${preview}"
+					alt="${props.name}"
+					loading="lazy"
+					class="max-h-48 max-w-64 object-cover"
+				/>
+			</a>
+			${removeButton}
+		</div>`;
+	}
+
+	const body = html`<span
+			data-slot="attachment-icon"
+			aria-hidden="true"
+			class="bg-muted text-muted-foreground flex size-8 shrink-0 items-center justify-center rounded text-[0.625rem] font-medium uppercase"
+		>${extensionOf(props.name)}</span>
+		<span class="flex min-w-0 flex-col">
+			<span class="truncate text-sm font-medium">${props.name}</span>
+			${
+				props.size === undefined
+					? null
+					: html`<span class="text-muted-foreground text-xs tabular-nums"
+						>${formatBytes(props.size)}</span
+					>`
+			}
+		</span>`;
+
+	return html`<div
+		data-slot="attachment"
+		data-kind="file"
+		class="${() =>
+			cn(
+				"bg-background relative flex w-fit max-w-64 items-center gap-2 rounded-md border p-2 pe-7",
+				read(props.class),
+			)}"
+	>
+		${
+			props.href === undefined
+				? html`<span class="flex min-w-0 items-center gap-2">${body}</span>`
+				: html`<a href="${props.href}" class="flex min-w-0 items-center gap-2 hover:underline"
+					>${body}</a
+				>`
+		}
+		${removeButton}
+	</div>`;
+});
+
+/** The extension, for the icon tile. `"report.final.pdf"` → `"pdf"`. */
+function extensionOf(name: string): string {
+	const dot = name.lastIndexOf(".");
+	if (dot <= 0 || dot === name.length - 1) return "?";
+	return name.slice(dot + 1).slice(0, 4);
+}

package/src/molecules/Breadcrumb.ts

@@ -0,0 +1,107 @@
+/**
+ * Breadcrumb — the trail back up the hierarchy.
+ *
+ * `aria-label="breadcrumb"` on the `<nav>` and `aria-current="page"` on the
+ * last entry. Both matter: the label is how a screen reader distinguishes this
+ * navigation from the other landmarks on the page, and `aria-current` is what
+ * tells the user which crumb is where they are — the visual weight change does
+ * not carry that.
+ *
+ * The separators are `aria-hidden` and marked `role="presentation"`. Read
+ * aloud, a chevron between every crumb is noise; the list structure already
+ * conveys the sequence.
+ */
+
+import { component, html } from "@c9up/aurora";
+import type { Child } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { ChevronRightIcon, MoreHorizontalIcon } from "../lib/icons.js";
+import { type Reactive, read } from "../lib/props.js";
+
+export interface Crumb {
+	label: Child;
+	/** Absent on the current page, and on a collapsed ellipsis. */
+	href?: string;
+	/** Renders an ellipsis standing in for hidden ancestors. */
+	ellipsis?: boolean;
+}
+
+export interface BreadcrumbProps {
+	items: readonly Crumb[];
+	/** Replaces the chevron between entries. */
+	separator?: Child;
+	class?: Reactive<string>;
+}
+
+export const Breadcrumb = component<BreadcrumbProps>((props) => {
+	return html`<nav
+		data-slot="breadcrumb"
+		aria-label="breadcrumb"
+		class="${() => cn(read(props.class))}"
+	>
+		<ol
+			data-slot="breadcrumb-list"
+			class="text-muted-foreground flex flex-wrap items-center gap-1.5 text-sm break-words sm:gap-2.5"
+		>
+			${props.items.map((item, index) =>
+				renderCrumb(
+					item,
+					index === props.items.length - 1,
+					index > 0,
+					props.separator,
+				),
+			)}
+		</ol>
+	</nav>`;
+});
+
+function renderCrumb(
+	item: Crumb,
+	isLast: boolean,
+	needsSeparator: boolean,
+	separator: Child,
+): Child {
+	return [
+		needsSeparator
+			? html`<li
+					data-slot="breadcrumb-separator"
+					role="presentation"
+					aria-hidden="true"
+					class="[&>svg]:size-3.5"
+				>${separator ?? ChevronRightIcon()}</li>`
+			: null,
+		html`<li data-slot="breadcrumb-item" class="inline-flex items-center gap-1.5">
+			${renderCrumbBody(item, isLast)}
+		</li>`,
+	];
+}
+
+function renderCrumbBody(item: Crumb, isLast: boolean): Child {
+	if (item.ellipsis === true) {
+		return html`<span
+			data-slot="breadcrumb-ellipsis"
+			role="presentation"
+			aria-hidden="true"
+			class="flex size-9 items-center justify-center"
+		>
+			${MoreHorizontalIcon({ class: "size-4" })}
+			<span class="sr-only">More</span>
+		</span>`;
+	}
+
+	if (isLast || item.href === undefined) {
+		return html`<span
+			data-slot="breadcrumb-page"
+			role="link"
+			aria-disabled="true"
+			aria-current="page"
+			class="text-foreground font-normal"
+		>${item.label}</span>`;
+	}
+
+	return html`<a
+		data-slot="breadcrumb-link"
+		href="${item.href}"
+		class="hover:text-foreground transition-colors"
+	>${item.label}</a>`;
+}