@c9up/nebula 0.1.0

package/src/molecules/InputOTP.ts

@@ -0,0 +1,166 @@
+/**
+ * InputOTP — a one-time code entered one character per box.
+ *
+ * The behaviour users expect from this control is entirely in the edge cases,
+ * and each one is a separate rule:
+ *
+ * - Typing advances to the next box; the last one stays put rather than
+ *   wrapping round to the first.
+ * - Backspace in an empty box clears the *previous* one and moves back, which
+ *   is what makes holding it down erase the whole code.
+ * - Pasting a code fills every box from wherever it was pasted, so the common
+ *   case — copy the code out of the email, click the first box, paste — works.
+ * - `inputmode="numeric"` and `autocomplete="one-time-code"` are what get the
+ *   numeric keypad on mobile and the OS's SMS autofill suggestion. Without the
+ *   second, a user has to leave the app to read the code.
+ *
+ * The joined value is mirrored into a hidden input so the control submits as
+ * one field, rather than six.
+ */
+
+import { component, html, signal } from "@c9up/aurora";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { type Reactive, read, readOr } from "../lib/props.js";
+
+export interface InputOTPProps {
+	/** Number of boxes. Default `6`. */
+	length?: number;
+	name?: string;
+	disabled?: Reactive<boolean>;
+	/** Insert a visual gap after this many boxes. `3` gives `123 456`. */
+	groupAfter?: number;
+	class?: Reactive<string>;
+	onValueChange?: (value: string) => void;
+	/** Fired once every box is filled. */
+	onComplete?: (value: string) => void;
+}
+
+const slotClasses =
+	"border-input relative flex size-9 items-center justify-center border-y border-r text-center text-sm shadow-xs transition-all outline-none first:rounded-l-md first:border-l last:rounded-r-md focus:border-ring focus:ring-ring/50 focus:z-10 focus:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50";
+
+export const InputOTP = component<InputOTPProps>((props) => {
+	const length = props.length ?? 6;
+	const groupId = uid("input-otp");
+	const characters = signal<readonly string[]>(new Array(length).fill(""));
+
+	function boxes(): HTMLInputElement[] {
+		const root = document.getElementById(groupId);
+		if (root === null) return [];
+		const found: HTMLInputElement[] = [];
+		for (const node of root.querySelectorAll("input[data-otp-index]")) {
+			if (node instanceof HTMLInputElement) found.push(node);
+		}
+		return found;
+	}
+
+	function focusBox(index: number): void {
+		const target = boxes()[Math.min(Math.max(index, 0), length - 1)];
+		target?.focus();
+		target?.select();
+	}
+
+	function commit(next: readonly string[]): void {
+		characters(next);
+		const joined = next.join("");
+		props.onValueChange?.(joined);
+		if (joined.length === length && !next.includes(""))
+			props.onComplete?.(joined);
+	}
+
+	function write(index: number, character: string): void {
+		const next = [...characters()];
+		next[index] = character;
+		commit(next);
+	}
+
+	function onInput(index: number, event: Event): void {
+		const target = event.target;
+		if (!(target instanceof HTMLInputElement)) return;
+
+		// A box already holding a character receives the new one appended; keep
+		// the last, which is what the user just typed.
+		const typed = target.value.slice(-1);
+		target.value = typed;
+		write(index, typed);
+		if (typed !== "" && index < length - 1) focusBox(index + 1);
+	}
+
+	function onKeyDown(index: number, event: KeyboardEvent): void {
+		if (event.key === "Backspace") {
+			if (characters()[index] === "" && index > 0) {
+				event.preventDefault();
+				write(index - 1, "");
+				focusBox(index - 1);
+			}
+			return;
+		}
+		if (event.key === "ArrowLeft") {
+			event.preventDefault();
+			focusBox(index - 1);
+			return;
+		}
+		if (event.key === "ArrowRight") {
+			event.preventDefault();
+			focusBox(index + 1);
+		}
+	}
+
+	function onPaste(index: number, event: ClipboardEvent): void {
+		const pasted = event.clipboardData?.getData("text") ?? "";
+		if (pasted === "") return;
+		event.preventDefault();
+
+		const next = [...characters()];
+		let cursor = index;
+		for (const character of pasted) {
+			if (cursor >= length) break;
+			next[cursor] = character;
+			cursor += 1;
+		}
+		commit(next);
+
+		// Reflect into the DOM: the boxes are uncontrolled between keystrokes, so
+		// writing the signal alone would leave the pasted characters invisible.
+		const inputs = boxes();
+		next.forEach((character, position) => {
+			const input = inputs[position];
+			if (input !== undefined) input.value = character;
+		});
+		focusBox(Math.min(cursor, length - 1));
+	}
+
+	const indices = Array.from({ length }, (_unused, index) => index);
+
+	return html`<div
+		data-slot="input-otp"
+		id="${groupId}"
+		class="${() => cn("flex items-center gap-2", read(props.class))}"
+	>
+		<div class="flex items-center">
+			${indices.map(
+				(index) => html`${
+					props.groupAfter !== undefined &&
+					index > 0 &&
+					index % props.groupAfter === 0
+						? html`<span aria-hidden="true" class="mx-1 text-muted-foreground">-</span>`
+						: null
+				}<input
+					data-slot="input-otp-slot"
+					data-otp-index="${index}"
+					type="text"
+					inputmode="numeric"
+					autocomplete="${index === 0 ? "one-time-code" : "off"}"
+					maxlength="1"
+					aria-label="${`Character ${index + 1} of ${length}`}"
+					?disabled="${() => readOr(props.disabled, false)}"
+					class="${slotClasses}"
+					@input="${(event: Event) => onInput(index, event)}"
+					@keydown="${(event: KeyboardEvent) => onKeyDown(index, event)}"
+					@paste="${(event: ClipboardEvent) => onPaste(index, event)}"
+				/>`,
+			)}
+		</div>
+		<input type="hidden" name="${props.name}" .value="${() => characters().join("")}" />
+	</div>`;
+});

package/src/molecules/Item.ts

@@ -0,0 +1,89 @@
+/**
+ * Item — one row in a list of things.
+ *
+ * The generic list row: a leading media slot, a title and description, and a
+ * trailing action. Sidebar entries, settings rows, search results and command
+ * results are all this shape, and each of them growing its own version is how
+ * a list of things ends up with four different vertical rhythms.
+ *
+ * `ItemContent` takes `min-w-0` so a long title truncates instead of pushing
+ * the trailing action off the row — the single most common bug in a flex row
+ * built by hand.
+ */
+
+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 } from "../lib/props.js";
+import { styledDiv } from "../lib/styled.js";
+
+export const itemVariants = cva(
+	"group/item flex flex-wrap items-center rounded-md border border-transparent text-sm outline-none transition-colors focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] [a&]:hover:bg-accent/50",
+	{
+		variants: {
+			variant: {
+				default: "bg-transparent",
+				outline: "border-border",
+				muted: "bg-muted/50",
+			},
+			size: {
+				default: "gap-4 p-4",
+				sm: "gap-2.5 px-4 py-3",
+			},
+		},
+		defaultVariants: { variant: "default", size: "default" },
+	},
+);
+
+export type ItemVariants = VariantProps<typeof itemVariants>;
+
+export interface ItemProps {
+	children?: Slot;
+	variant?: Reactive<ItemVariants["variant"]>;
+	size?: Reactive<ItemVariants["size"]>;
+	class?: Reactive<string>;
+}
+
+export const Item = component<ItemProps>((props) => {
+	return html`<div
+		data-slot="item"
+		class="${() =>
+			itemVariants({
+				variant: read(props.variant),
+				size: read(props.size),
+				class: read(props.class),
+			})}"
+	>${slot(props.children)}</div>`;
+});
+
+export const ItemGroup = styledDiv(
+	"item-group",
+	"group/item-group flex flex-col",
+);
+
+export const ItemMedia = styledDiv(
+	"item-media",
+	"flex shrink-0 items-center justify-center gap-2 [&_svg:not([class*='size-'])]:size-4",
+);
+
+export const ItemContent = styledDiv(
+	"item-content",
+	"flex flex-1 flex-col gap-1 [&+[data-slot=item-content]]:flex-none min-w-0",
+);
+
+export const ItemTitle = styledDiv(
+	"item-title",
+	"flex w-fit items-center gap-2 text-sm leading-snug font-medium",
+);
+
+export const ItemDescription = styledDiv(
+	"item-description",
+	"text-muted-foreground line-clamp-2 text-sm leading-normal font-normal text-balance",
+);
+
+export const ItemActions = styledDiv("item-actions", "flex items-center gap-2");
+
+export const ItemSeparator = styledDiv(
+	"item-separator",
+	"bg-border my-0 h-px w-full",
+);

package/src/molecules/Message.ts

@@ -0,0 +1,127 @@
+/**
+ * Message — one turn in a conversation.
+ *
+ * Avatar, author, timestamp and a `Bubble`, laid out in reading order and
+ * mirrored for an outgoing turn. `align: "end"` uses `flex-row-reverse`, so
+ * the avatar moves to the inline end and the whole row follows the writing
+ * direction — the same logical treatment as the bubble itself.
+ *
+ * The timestamp is a `<time datetime>`, always. The visible text is formatted
+ * for the reader and may be relative ("2 min ago"), which a machine cannot
+ * parse; `datetime` carries the ISO instant alongside it so a screen reader,
+ * a scraper or a copy-paste keeps the real value.
+ *
+ * `role="article"` groups the parts, so a screen reader announces the author
+ * once rather than reading a loose avatar, a name, a time and a paragraph as
+ * four unrelated things.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { Avatar } from "../atoms/Avatar.js";
+import type { Child } from "../lib/children.js";
+import { type Slot, slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { type Reactive, read } from "../lib/props.js";
+import { Bubble, type BubbleProps, type BubbleReaction } from "./Bubble.js";
+
+export interface MessageProps {
+	/** The turn's content. Rendered inside a `Bubble`. */
+	children?: Slot;
+	author?: Child;
+	avatarSrc?: string;
+	/** Initials, when there is no picture. */
+	avatarFallback?: Child;
+	/** A `Date`, or an ISO string. Rendered as `<time datetime>`. */
+	timestamp?: Date | string;
+	/** How the timestamp reads. Defaults to a short local time. */
+	formatTime?: (date: Date) => string;
+	/** `"end"` for the current user's own turn. */
+	align?: BubbleProps["align"];
+	variant?: BubbleProps["variant"];
+	reactions?: readonly BubbleReaction[];
+	/** `Attachment`s, under the bubble. */
+	attachments?: Slot;
+	/** Shown under the bubble in place of a timestamp — "Sending…", "Failed". */
+	status?: Child;
+	class?: Reactive<string>;
+}
+
+/** Accept both shapes without making every caller construct a `Date`. */
+function asDate(value: Date | string): Date | undefined {
+	const date = value instanceof Date ? value : new Date(value);
+	return Number.isNaN(date.getTime()) ? undefined : date;
+}
+
+export const Message = component<MessageProps>((props) => {
+	const outgoing = props.align === "end";
+	const time =
+		props.timestamp === undefined ? undefined : asDate(props.timestamp);
+	const timeFormat = new Intl.DateTimeFormat(undefined, { timeStyle: "short" });
+
+	const hasAvatar =
+		props.avatarSrc !== undefined || props.avatarFallback !== undefined;
+
+	return html`<div
+		data-slot="message"
+		role="article"
+		data-align="${outgoing ? "end" : "start"}"
+		class="${() =>
+			cn(
+				"flex w-full items-end gap-2",
+				outgoing ? "flex-row-reverse" : "flex-row",
+				read(props.class),
+			)}"
+	>
+		${
+			hasAvatar
+				? Avatar({
+						src: props.avatarSrc,
+						alt: typeof props.author === "string" ? props.author : "",
+						fallback: props.avatarFallback,
+						class: "size-7 shrink-0",
+					})
+				: null
+		}
+		<div class="${cn("flex min-w-0 flex-1 flex-col gap-1", outgoing ? "items-end" : "items-start")}">
+			${
+				props.author === undefined
+					? null
+					: html`<span data-slot="message-author" class="text-muted-foreground px-1 text-xs font-medium"
+						>${props.author}</span
+					>`
+			}
+			${Bubble({
+				variant: props.variant,
+				align: props.align,
+				reactions: props.reactions,
+				children: props.children,
+			})}
+			${
+				props.attachments === undefined
+					? null
+					: html`<div data-slot="message-attachments" class="flex flex-wrap gap-2">
+						${slot(props.attachments)}
+					</div>`
+			}
+			${renderFooter(props, time, timeFormat)}
+		</div>
+	</div>`;
+});
+
+function renderFooter(
+	props: MessageProps,
+	time: Date | undefined,
+	timeFormat: Intl.DateTimeFormat,
+): Child {
+	if (props.status !== undefined) {
+		return html`<span data-slot="message-status" class="text-muted-foreground px-1 text-xs"
+			>${props.status}</span
+		>`;
+	}
+	if (time === undefined) return null;
+	return html`<time
+		data-slot="message-time"
+		datetime="${time.toISOString()}"
+		class="text-muted-foreground px-1 text-xs tabular-nums"
+	>${(props.formatTime ?? ((date: Date) => timeFormat.format(date)))(time)}</time>`;
+}

package/src/molecules/Pagination.ts

@@ -0,0 +1,197 @@
+/**
+ * Pagination — page links for a long list.
+ *
+ * The interesting part is `pageWindow`, which decides which page numbers to
+ * show. Rendering all of them breaks at a few hundred pages; the usual fix is
+ * a fixed window around the current page, which then jitters in width as you
+ * approach either end — the control visibly reflows while you click through
+ * it. `pageWindow` keeps the count constant instead, so the row stays the same
+ * size from page 1 to page 500.
+ *
+ * `aria-current="page"` marks the current page. Without it the only signal is
+ * the highlight, which a screen-reader user does not get.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { buttonVariants } from "../atoms/Button.js";
+import type { Child } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import {
+	ChevronLeftIcon,
+	ChevronRightIcon,
+	MoreHorizontalIcon,
+} from "../lib/icons.js";
+import { type Reactive, read } from "../lib/props.js";
+
+export interface PaginationProps {
+	page: Reactive<number>;
+	pageCount: Reactive<number>;
+	/** How many numbered links to show, ellipses included. Default `7`. */
+	window?: number;
+	/** Build an href per page. Omit for a button-driven pagination. */
+	href?: (page: number) => string;
+	onPageChange?: (page: number) => void;
+	class?: Reactive<string>;
+}
+
+/** `null` marks a gap that renders as an ellipsis. */
+export type PageSlot = number | null;
+
+/**
+ * Which page numbers to show, at a fixed total width.
+ *
+ * Always the first page, the last page, a run around the current one, and one
+ * or two gaps — adding up to exactly `size` slots wherever the current page
+ * sits. The constant width is the whole reason this is computed rather than a
+ * range being sliced: a window that simply narrows near the ends makes the
+ * control reflow as you click through it, and the buttons move under the
+ * pointer.
+ *
+ * Near an end there is only one gap, so the run is one slot wider to make up
+ * for it. That is the case a naive implementation gets wrong.
+ */
+export function pageWindow(
+	page: number,
+	pageCount: number,
+	size = 7,
+): readonly PageSlot[] {
+	if (pageCount <= size) return range(1, pageCount);
+
+	// Below five slots there is no room for first, last, a gap and a run, so
+	// the shape this function promises cannot be built.
+	const slots = Math.max(size, 5);
+	const current = Math.min(Math.max(page, 1), pageCount);
+
+	// Near an end the run absorbs the first (or last) page and there is a
+	// single gap, so it holds `slots - 2` entries. In the middle the first and
+	// last pages are separate and there are two gaps, leaving `slots - 4`.
+	const runNearEnd = slots - 2;
+	const runInMiddle = slots - 4;
+
+	if (current <= runNearEnd - 1) {
+		return [...range(1, runNearEnd), null, pageCount];
+	}
+	if (current >= pageCount - runNearEnd + 2) {
+		return [1, null, ...range(pageCount - runNearEnd + 1, pageCount)];
+	}
+
+	const before = Math.floor((runInMiddle - 1) / 2);
+	const start = current - before;
+	return [1, null, ...range(start, start + runInMiddle - 1), null, pageCount];
+}
+
+function range(from: number, to: number): number[] {
+	const out: number[] = [];
+	for (let value = from; value <= to; value += 1) out.push(value);
+	return out;
+}
+
+export const Pagination = component<PaginationProps>((props) => {
+	const page = (): number => read(props.page) ?? 1;
+	const pageCount = (): number => Math.max(1, read(props.pageCount) ?? 1);
+
+	const go = (target: number) => (event: MouseEvent) => {
+		if (props.onPageChange === undefined) return;
+		// Only intercept when the caller wants callback-driven paging. With an
+		// `href` and no handler the link must navigate normally.
+		event.preventDefault();
+		props.onPageChange(Math.min(Math.max(target, 1), pageCount()));
+	};
+
+	return html`<nav
+		data-slot="pagination"
+		role="navigation"
+		aria-label="pagination"
+		class="${() => cn("mx-auto flex w-full justify-center", read(props.class))}"
+	>
+		<ul data-slot="pagination-content" class="flex flex-row items-center gap-1">
+			<li>
+				${link({
+					label: html`${ChevronLeftIcon({ class: "size-4" })}<span class="hidden sm:block">Previous</span>`,
+					ariaLabel: "Go to previous page",
+					href: props.href?.(page() - 1),
+					disabled: () => page() <= 1,
+					onClick: go(page() - 1),
+					size: "default",
+					extra: "gap-1 px-2.5 sm:pl-2.5",
+				})}
+			</li>
+			${() =>
+				pageWindow(page(), pageCount(), props.window ?? 7).map(
+					(entry, index) =>
+						entry === null
+							? html`<li aria-hidden="true">
+								<span class="flex size-9 items-center justify-center">
+									${MoreHorizontalIcon({ class: "size-4" })}
+									<span class="sr-only">More pages</span>
+								</span>
+							</li>`
+							: html`<li>
+								${link({
+									label: String(entry),
+									ariaLabel: `Go to page ${entry}`,
+									href: props.href?.(entry),
+									current: entry === page(),
+									onClick: go(entry),
+									size: "icon",
+									key: index,
+								})}
+							</li>`,
+				)}
+			<li>
+				${link({
+					label: html`<span class="hidden sm:block">Next</span>${ChevronRightIcon({ class: "size-4" })}`,
+					ariaLabel: "Go to next page",
+					href: props.href?.(page() + 1),
+					disabled: () => page() >= pageCount(),
+					onClick: go(page() + 1),
+					size: "default",
+					extra: "gap-1 px-2.5 sm:pr-2.5",
+				})}
+			</li>
+		</ul>
+	</nav>`;
+});
+
+interface LinkSpec {
+	label: Child;
+	ariaLabel: string;
+	href?: string;
+	current?: boolean;
+	disabled?: () => boolean;
+	onClick: (event: MouseEvent) => void;
+	size: "default" | "icon";
+	extra?: string;
+	key?: number;
+}
+
+/**
+ * One page link.
+ *
+ * Always an `<a>`, even without an `href`: pagination is navigation, and the
+ * role is what a screen reader uses to offer "list of links" here. The
+ * disabled ends carry `aria-disabled` plus `pointer-events-none` rather than
+ * being removed, so the control keeps its width at both ends of the range.
+ */
+function link(spec: LinkSpec): Child {
+	const disabled = (): boolean => spec.disabled?.() === true;
+
+	return html`<a
+		data-slot="pagination-link"
+		href="${spec.href}"
+		aria-label="${spec.ariaLabel}"
+		aria-current="${spec.current === true ? "page" : undefined}"
+		aria-disabled="${() => (disabled() ? "true" : undefined)}"
+		tabindex="${() => (disabled() ? -1 : 0)}"
+		class="${() =>
+			cn(
+				buttonVariants({
+					variant: spec.current === true ? "outline" : "ghost",
+					size: spec.size,
+				}),
+				spec.extra,
+				disabled() ? "pointer-events-none opacity-50" : "",
+			)}"
+		@click="${spec.onClick}"
+	>${spec.label}</a>`;
+}

package/src/molecules/RadioGroup.ts

@@ -0,0 +1,104 @@
+/**
+ * RadioGroup — pick exactly one option.
+ *
+ * Native `<input type="radio">` throughout. The browser already implements the
+ * radio group pattern on a shared `name`: arrows move and select, only one can
+ * be checked, and the group is one tab stop. Radix reimplements all of that
+ * because it needs a stylable element; `appearance-none` gets nebula the same
+ * styling freedom while the behaviour stays the browser's.
+ *
+ * The indicator dot is a sibling shown by `peer-checked:`, so selecting a
+ * radio runs no JavaScript at all.
+ */
+
+import { component, html } 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, readOr } from "../lib/props.js";
+
+export interface RadioOption {
+	value: string;
+	label: Child;
+	description?: Child;
+	disabled?: boolean;
+}
+
+export interface RadioGroupProps {
+	/** Shared `name`, which is what makes the browser treat these as one group. */
+	name: string;
+	options: readonly RadioOption[];
+	value?: Reactive<string | undefined>;
+	defaultValue?: string;
+	disabled?: Reactive<boolean>;
+	orientation?: "vertical" | "horizontal";
+	class?: Reactive<string>;
+	onValueChange?: (value: string) => void;
+}
+
+const radioClasses =
+	"peer size-4 shrink-0 appearance-none rounded-full border border-input bg-transparent shadow-xs outline-none transition-shadow dark:bg-input/30 checked:border-primary focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50";
+
+export const RadioGroup = component<RadioGroupProps>((props) => {
+	const selected = (): string | undefined => {
+		const controlled = read(props.value);
+		return controlled === undefined ? props.defaultValue : controlled;
+	};
+
+	return html`<div
+		role="radiogroup"
+		data-slot="radio-group"
+		aria-orientation="${props.orientation ?? "vertical"}"
+		class="${() =>
+			cn(
+				"grid gap-3",
+				props.orientation === "horizontal" ? "grid-flow-col auto-cols-max" : "",
+				read(props.class),
+			)}"
+	>
+		${props.options.map((option) => renderOption(option, props, selected))}
+	</div>`;
+});
+
+function renderOption(
+	option: RadioOption,
+	props: RadioGroupProps,
+	selected: () => string | undefined,
+): Child {
+	const id = uid("radio");
+	const descriptionId =
+		option.description === undefined ? undefined : uid("radio-description");
+
+	return html`<div class="flex items-start gap-3">
+		<span class="relative flex size-4 shrink-0 items-center justify-center">
+			<input
+				type="radio"
+				data-slot="radio-group-item"
+				id="${id}"
+				name="${props.name}"
+				value="${option.value}"
+				aria-describedby="${descriptionId}"
+				?disabled="${() => option.disabled === true || readOr(props.disabled, false)}"
+				.checked="${() => selected() === option.value}"
+				class="${radioClasses}"
+				@change="${() => props.onValueChange?.(option.value)}"
+			/>
+			<span
+				class="bg-primary pointer-events-none absolute size-2 rounded-full opacity-0 transition-opacity peer-checked:opacity-100"
+			></span>
+		</span>
+		<div class="grid gap-1 leading-none">
+			<label
+				for="${id}"
+				class="text-sm leading-none font-medium select-none peer-disabled:cursor-not-allowed peer-disabled:opacity-50"
+			>${option.label}</label>
+			${
+				option.description === undefined
+					? null
+					: html`<p id="${descriptionId}" class="text-muted-foreground text-sm">
+						${option.description}
+					</p>`
+			}
+		</div>
+	</div>`;
+}