@c9up/nebula 0.1.0

package/src/organisms/Chart.ts

@@ -0,0 +1,257 @@
+/**
+ * Chart — line, area and bar charts drawn as inline SVG.
+ *
+ * shadcn's Chart is a theming wrapper around Recharts. nebula cannot follow it
+ * there — Recharts is React — and a zero-dependency port of a full charting
+ * library is not a thing to promise. So the scope is stated plainly: three
+ * chart types over one categorical axis and one numeric axis, which is what
+ * the shadcn chart examples are and what dashboards overwhelmingly need.
+ *
+ * Anything beyond that — stacked bars with negative values, dual axes, brushes,
+ * candlesticks — is a charting library's job, and an app needing one should
+ * install one rather than have this component grow into a bad copy.
+ *
+ * The colours come from `--chart-1` … `--chart-5`, so a chart re-themes with
+ * the rest of the design system instead of carrying its own palette.
+ *
+ * An SVG chart is invisible to a screen reader whatever ARIA is put on it, so
+ * the same data is emitted as a real `<table>`, visually hidden. That is the
+ * only approach that actually works: the reader gets rows and values it can
+ * navigate, not a described picture.
+ */
+
+import { component, html } from "@c9up/aurora";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { type Reactive, read } from "../lib/props.js";
+
+export interface ChartSeries {
+	key: string;
+	label: string;
+	/** Any CSS colour. Defaults to `--chart-1`…`--chart-5` by position. */
+	color?: string;
+}
+
+/** One row: a category plus one numeric value per series key. */
+export type ChartDatum = Record<string, string | number>;
+
+export interface ChartProps {
+	data: readonly ChartDatum[];
+	series: readonly ChartSeries[];
+	/** Key in each datum holding the category label. */
+	categoryKey: string;
+	type?: "line" | "area" | "bar";
+	height?: number;
+	/** Announced as the chart's name, and used as the data table's caption. */
+	label: string;
+	/** Draw horizontal gridlines. Default `true`. */
+	grid?: boolean;
+	class?: Reactive<string>;
+}
+
+const VIEWBOX_WIDTH = 600;
+const PADDING = { top: 8, right: 8, bottom: 24, left: 40 };
+
+function colorFor(series: ChartSeries, index: number): string {
+	return series.color ?? `var(--chart-${(index % 5) + 1})`;
+}
+
+function numberAt(datum: ChartDatum, key: string): number {
+	const value = datum[key];
+	return typeof value === "number" ? value : 0;
+}
+
+function categoryAt(datum: ChartDatum, key: string): string {
+	const value = datum[key];
+	return typeof value === "string" ? value : String(value ?? "");
+}
+
+/**
+ * The value range the Y axis covers.
+ *
+ * Anchored at zero whenever the data is non-negative. A bar chart whose axis
+ * starts at the minimum value exaggerates every difference — the classic
+ * misleading chart — and it is not a choice worth exposing as an option.
+ */
+export function valueRange(
+	data: readonly ChartDatum[],
+	series: readonly ChartSeries[],
+): { min: number; max: number } {
+	let min = 0;
+	let max = 0;
+	for (const datum of data) {
+		for (const entry of series) {
+			const value = numberAt(datum, entry.key);
+			if (value < min) min = value;
+			if (value > max) max = value;
+		}
+	}
+	// A flat all-zero dataset would divide by zero when scaling.
+	if (min === max) return { min, max: max + 1 };
+	return { min, max };
+}
+
+export const Chart = component<ChartProps>((props) => {
+	const titleId = uid("chart-title");
+	const height = props.height ?? 240;
+	const type = props.type ?? "line";
+	const { min, max } = valueRange(props.data, props.series);
+
+	const plotWidth = VIEWBOX_WIDTH - PADDING.left - PADDING.right;
+	const plotHeight = height - PADDING.top - PADDING.bottom;
+
+	const y = (value: number): number =>
+		PADDING.top + plotHeight - ((value - min) / (max - min)) * plotHeight;
+
+	/** Centre of the slot for index `i`, so points sit above their labels. */
+	const x = (index: number): number => {
+		const count = Math.max(props.data.length, 1);
+		const step = plotWidth / count;
+		return PADDING.left + step * index + step / 2;
+	};
+
+	const gridLines = [0, 0.25, 0.5, 0.75, 1].map(
+		(fraction) => PADDING.top + plotHeight * fraction,
+	);
+
+	function linePath(series: ChartSeries): string {
+		return props.data
+			.map(
+				(datum, index) =>
+					`${index === 0 ? "M" : "L"}${x(index)},${y(numberAt(datum, series.key))}`,
+			)
+			.join(" ");
+	}
+
+	function areaPath(series: ChartSeries): string {
+		if (props.data.length === 0) return "";
+		const baseline = y(Math.max(min, 0));
+		return `${linePath(series)} L${x(props.data.length - 1)},${baseline} L${x(0)},${baseline} Z`;
+	}
+
+	return html`<figure
+		data-slot="chart"
+		class="${() => cn("w-full", read(props.class))}"
+	>
+		<svg
+			viewBox="${`0 0 ${VIEWBOX_WIDTH} ${height}`}"
+			role="img"
+			aria-labelledby="${titleId}"
+			preserveAspectRatio="none"
+			class="h-auto w-full overflow-visible"
+		>
+			<title id="${titleId}">${props.label}</title>
+			${
+				props.grid === false
+					? null
+					: gridLines.map(
+							(position) => html`<line
+							x1="${PADDING.left}"
+							x2="${VIEWBOX_WIDTH - PADDING.right}"
+							y1="${position}"
+							y2="${position}"
+							stroke="var(--border)"
+							stroke-width="1"
+						/>`,
+						)
+			}
+			${props.series.map((series, seriesIndex) =>
+				type === "bar"
+					? renderBars(series, seriesIndex)
+					: renderCurve(series, seriesIndex),
+			)}
+			${props.data.map(
+				(datum, index) => html`<text
+					x="${x(index)}"
+					y="${height - 6}"
+					text-anchor="middle"
+					font-size="10"
+					fill="var(--muted-foreground)"
+				>${categoryAt(datum, props.categoryKey)}</text>`,
+			)}
+		</svg>
+		<figcaption class="sr-only">${renderDataTable()}</figcaption>
+		<div data-slot="chart-legend" class="mt-2 flex flex-wrap justify-center gap-4 text-xs">
+			${props.series.map(
+				(series, index) => html`<span class="flex items-center gap-1.5">
+					<span
+						aria-hidden="true"
+						class="size-2 shrink-0 rounded-[2px]"
+						style="${`background:${colorFor(series, index)}`}"
+					></span>
+					<span class="text-muted-foreground">${series.label}</span>
+				</span>`,
+			)}
+		</div>
+	</figure>`;
+
+	function renderCurve(
+		series: ChartSeries,
+		index: number,
+	): ReturnType<typeof html> {
+		const color = colorFor(series, index);
+		return html`<g>
+			${
+				type === "area"
+					? html`<path d="${areaPath(series)}" fill="${color}" fill-opacity="0.15" />`
+					: null
+			}
+			<path
+				d="${linePath(series)}"
+				fill="none"
+				stroke="${color}"
+				stroke-width="2"
+				stroke-linecap="round"
+				stroke-linejoin="round"
+			/>
+		</g>`;
+	}
+
+	function renderBars(
+		series: ChartSeries,
+		seriesIndex: number,
+	): ReturnType<typeof html> {
+		const count = Math.max(props.data.length, 1);
+		const slot = plotWidth / count;
+		// Share each slot between the series so grouped bars sit side by side,
+		// with a quarter of the slot left as the gap between groups.
+		const barWidth = (slot * 0.75) / props.series.length;
+		const baseline = y(Math.max(min, 0));
+
+		return html`<g fill="${colorFor(series, seriesIndex)}">
+			${props.data.map((datum, index) => {
+				const top = y(numberAt(datum, series.key));
+				const left =
+					PADDING.left + slot * index + slot * 0.125 + barWidth * seriesIndex;
+				return html`<rect
+					x="${left}"
+					y="${Math.min(top, baseline)}"
+					width="${barWidth}"
+					height="${Math.abs(baseline - top)}"
+					rx="2"
+				/>`;
+			})}
+		</g>`;
+	}
+
+	/** The same numbers as a real table, for anything that cannot see the SVG. */
+	function renderDataTable(): ReturnType<typeof html> {
+		return html`<table>
+			<caption>${props.label}</caption>
+			<thead>
+				<tr>
+					<th scope="col">${props.categoryKey}</th>
+					${props.series.map((series) => html`<th scope="col">${series.label}</th>`)}
+				</tr>
+			</thead>
+			<tbody>
+				${props.data.map(
+					(datum) => html`<tr>
+						<th scope="row">${categoryAt(datum, props.categoryKey)}</th>
+						${props.series.map((series) => html`<td>${numberAt(datum, series.key)}</td>`)}
+					</tr>`,
+				)}
+			</tbody>
+		</table>`;
+	}
+});

package/src/organisms/Combobox.ts

@@ -0,0 +1,140 @@
+/**
+ * Combobox — a select you can type into.
+ *
+ * Structurally a Select whose panel holds a search field, which is exactly how
+ * shadcn builds it (a Popover wrapping a Command). nebula does the same, so
+ * the filtering, the highlight and the keyboard model are `Command`'s and are
+ * not written twice.
+ *
+ * The one addition over Command is selection: a combobox remembers what was
+ * picked, shows it on the trigger, and posts it with the form. Command runs an
+ * action and forgets.
+ *
+ * Focus moves into the panel's search field on open — that is the point of the
+ * control — and returns to the trigger on close, so the tab order does not
+ * jump to the top of the page after choosing.
+ */
+
+import { component, html, signal } from "@c9up/aurora";
+import { cn } from "../lib/cn.js";
+import { ChevronsUpDownIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { zoomInOut } from "../lib/motion.js";
+import { type Reactive, read, readOr } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+import { focusSilently } from "../primitives/focusable.js";
+import { Command, type CommandItem } from "./Command.js";
+import { selectTriggerClasses } from "./Select.js";
+
+export interface ComboboxOption {
+	value: string;
+	label: string;
+	keywords?: readonly string[];
+	disabled?: boolean;
+	group?: string;
+}
+
+export interface ComboboxProps {
+	options: readonly ComboboxOption[];
+	name?: string;
+	value?: Reactive<string | undefined>;
+	defaultValue?: string;
+	/** Trigger text when nothing is chosen. */
+	placeholder?: string;
+	/** Placeholder inside the search field. */
+	searchPlaceholder?: string;
+	emptyMessage?: string;
+	disabled?: Reactive<boolean>;
+	invalid?: Reactive<boolean>;
+	class?: Reactive<string>;
+	contentClass?: Reactive<string>;
+	onValueChange?: (value: string) => void;
+}
+
+export const Combobox = component<ComboboxProps>((props) => {
+	const triggerId = uid("combobox-trigger");
+	const contentId = uid("combobox-content");
+	const open = signal(false);
+
+	const selection = controllable<string | undefined>({
+		value: props.value,
+		initial: props.defaultValue,
+		onChange: (next) => {
+			if (next !== undefined) props.onValueChange?.(next);
+		},
+	});
+
+	function labelFor(value: string | undefined): string | undefined {
+		return props.options.find((option) => option.value === value)?.label;
+	}
+
+	const items = (): readonly CommandItem[] =>
+		props.options.map((option) => ({
+			value: option.value,
+			label: option.label,
+			keywords: option.keywords,
+			disabled: option.disabled,
+			group: option.group,
+		}));
+
+	function choose(item: CommandItem): void {
+		selection.set(item.value);
+		open(false);
+		focusSilently(document.getElementById(triggerId));
+	}
+
+	floatingSurface({
+		anchor: () => document.getElementById(triggerId),
+		open: () => open(),
+		onClose: () => open(false),
+		placement: "bottom-start",
+		offset: 4,
+		matchWidth: true,
+		trapFocus: true,
+		// Focus the search field, not the first result — the user opened this to
+		// type. `firstFocusable` would land on whichever element comes first in
+		// the DOM, which is only the input by accident.
+		initialFocus: (content) => content.querySelector("input"),
+		content: () =>
+			html`<div
+				data-slot="combobox-content"
+				id="${contentId}"
+				class="${cn(
+					"bg-popover text-popover-foreground z-50 min-w-(--nebula-anchor-width) overflow-hidden rounded-md border shadow-md",
+					zoomInOut,
+					read(props.contentClass),
+				)}"
+			>
+				${Command({
+					items: items(),
+					placeholder: props.searchPlaceholder ?? "Search…",
+					emptyMessage: props.emptyMessage ?? "No results found.",
+					onSelect: choose,
+				})}
+			</div>`,
+	});
+
+	return html`<div data-slot="combobox" class="${() => cn("inline-flex", read(props.class))}">
+		<button
+			type="button"
+			data-slot="combobox-trigger"
+			id="${triggerId}"
+			role="combobox"
+			aria-haspopup="listbox"
+			aria-expanded="${() => (open() ? "true" : "false")}"
+			aria-controls="${() => (open() ? contentId : undefined)}"
+			aria-invalid="${() => (read(props.invalid) === true ? "true" : undefined)}"
+			data-placeholder="${() => (selection.current() === undefined ? "" : undefined)}"
+			?disabled="${() => readOr(props.disabled, false)}"
+			class="${() => cn(selectTriggerClasses, "justify-between")}"
+			@click="${() => open(!open())}"
+		>
+			<span class="truncate"
+				>${() => labelFor(selection.current()) ?? props.placeholder ?? "Select…"}</span
+			>
+			${ChevronsUpDownIcon({ class: "size-4 opacity-50" })}
+		</button>
+		<input type="hidden" name="${props.name}" .value="${() => selection.current() ?? ""}" />
+	</div>`;
+});

package/src/organisms/Command.ts

@@ -0,0 +1,211 @@
+/**
+ * Command — a searchable list of actions.
+ *
+ * The palette pattern: type to filter, arrows to move, Enter to run. Used on
+ * its own — inside a Popover, a Sheet, or a page — while `CommandDialog` wraps
+ * this same component in a modal for the full-screen palette.
+ *
+ * The filter is the interesting decision. `cmdk`, which shadcn wraps, scores
+ * matches with a fuzzy algorithm; nebula matches on substring, plus an
+ * optional `keywords` list per item. Fuzzy matching is impressive on a demo
+ * and frustrating in use — it surfaces items the user did not type anything
+ * resembling, and the ranking is impossible to predict. Substring plus
+ * keywords is predictable, and "s" reaching "Settings" is a keyword, not an
+ * algorithm.
+ *
+ * Focus stays in the search input the whole time; the highlighted item is
+ * named with `aria-activedescendant`. Moving DOM focus onto the list would
+ * take it out of the input and the next keystroke would go nowhere.
+ */
+
+import { component, html, signal } from "@c9up/aurora";
+import type { Child } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { SearchIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { type Reactive, read } from "../lib/props.js";
+
+export interface CommandItem {
+	/** Stable key. */
+	value: string;
+	label: string;
+	icon?: Child;
+	/** Extra terms that should match this item. */
+	keywords?: readonly string[];
+	shortcut?: string;
+	disabled?: boolean;
+	group?: string;
+	onSelect?: () => void;
+}
+
+export interface CommandProps {
+	items: readonly CommandItem[];
+	placeholder?: string;
+	/** Shown when the filter matches nothing. */
+	emptyMessage?: Child;
+	/** Replace the built-in substring filter. */
+	filter?: (item: CommandItem, query: string) => boolean;
+	class?: Reactive<string>;
+	onSelect?: (item: CommandItem) => void;
+}
+
+/** Substring over the label, then over each keyword. */
+export function defaultFilter(item: CommandItem, query: string): boolean {
+	if (query === "") return true;
+	const needle = query.toLowerCase();
+	if (item.label.toLowerCase().includes(needle)) return true;
+	return (item.keywords ?? []).some((keyword) =>
+		keyword.toLowerCase().includes(needle),
+	);
+}
+
+export const Command = component<CommandProps>((props) => {
+	const inputId = uid("command-input");
+	const listId = uid("command-list");
+	const itemIds = new Map<string, string>();
+	for (const item of props.items) itemIds.set(item.value, uid("command-item"));
+
+	const query = signal("");
+	const active = signal<string | undefined>(undefined);
+
+	function matches(): readonly CommandItem[] {
+		const filter = props.filter ?? defaultFilter;
+		return props.items.filter(
+			(item) => item.disabled !== true && filter(item, query()),
+		);
+	}
+
+	function run(item: CommandItem): void {
+		if (item.disabled === true) return;
+		item.onSelect?.();
+		props.onSelect?.(item);
+	}
+
+	function move(delta: number): void {
+		const list = matches();
+		if (list.length === 0) return;
+		const from = list.findIndex((item) => item.value === active());
+		const next = from === -1 ? (delta > 0 ? 0 : list.length - 1) : from + delta;
+		// Wrapping is right here, unlike in a menu: a palette is a search result
+		// list and the user is scanning it, not navigating a fixed structure.
+		const target = list[(next + list.length) % list.length];
+		if (target !== undefined) {
+			active(target.value);
+			scrollIntoView(target.value);
+		}
+	}
+
+	function scrollIntoView(value: string): void {
+		const id = itemIds.get(value);
+		if (id === undefined) return;
+		document.getElementById(id)?.scrollIntoView({ block: "nearest" });
+	}
+
+	function onKeyDown(event: KeyboardEvent): void {
+		if (event.key === "ArrowDown") {
+			event.preventDefault();
+			move(1);
+		} else if (event.key === "ArrowUp") {
+			event.preventDefault();
+			move(-1);
+		} else if (event.key === "Enter") {
+			event.preventDefault();
+			const current = matches().find((item) => item.value === active());
+			if (current !== undefined) run(current);
+		}
+	}
+
+	function onInput(event: Event): void {
+		const target = event.target;
+		if (!(target instanceof HTMLInputElement)) return;
+		query(target.value);
+		// Re-point the highlight at the first result: leaving it on an item the
+		// new query filtered out means Enter runs something invisible.
+		active(matches()[0]?.value);
+	}
+
+	return html`<div
+		data-slot="command"
+		class="${() =>
+			cn(
+				"bg-popover text-popover-foreground flex size-full flex-col overflow-hidden rounded-md",
+				read(props.class),
+			)}"
+	>
+		<div data-slot="command-input-wrapper" class="flex h-9 items-center gap-2 border-b px-3">
+			${SearchIcon({ class: "size-4 shrink-0 opacity-50" })}
+			<input
+				data-slot="command-input"
+				id="${inputId}"
+				type="text"
+				role="combobox"
+				autocomplete="off"
+				aria-expanded="true"
+				aria-controls="${listId}"
+				aria-activedescendant="${() => {
+					const current = active();
+					return current === undefined ? undefined : itemIds.get(current);
+				}}"
+				placeholder="${props.placeholder ?? "Type a command or search…"}"
+				class="placeholder:text-muted-foreground flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-none disabled:cursor-not-allowed disabled:opacity-50"
+				@input="${onInput}"
+				@keydown="${onKeyDown}"
+			/>
+		</div>
+		<div
+			data-slot="command-list"
+			id="${listId}"
+			role="listbox"
+			class="max-h-[300px] scroll-py-1 overflow-x-hidden overflow-y-auto p-1"
+		>
+			${() => renderResults()}
+		</div>
+	</div>`;
+
+	function renderResults(): Child {
+		const list = matches();
+		if (list.length === 0) {
+			return html`<div
+				data-slot="command-empty"
+				role="presentation"
+				class="py-6 text-center text-sm"
+			>${props.emptyMessage ?? "No results found."}</div>`;
+		}
+
+		let lastGroup: string | undefined;
+		return list.map((item) => {
+			const heading =
+				item.group !== undefined && item.group !== lastGroup
+					? html`<div
+							role="presentation"
+							class="text-muted-foreground px-2 py-1.5 text-xs font-medium"
+						>${item.group}</div>`
+					: null;
+			lastGroup = item.group;
+			return [heading, renderItem(item)];
+		});
+	}
+
+	function renderItem(item: CommandItem): Child {
+		return html`<div
+			role="option"
+			data-slot="command-item"
+			id="${itemIds.get(item.value)}"
+			aria-selected="${() => (active() === item.value ? "true" : "false")}"
+			data-active="${() => (active() === item.value ? "" : undefined)}"
+			class="relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none data-[active]:bg-accent data-[active]:text-accent-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4"
+			@click="${() => run(item)}"
+			@pointerenter="${() => active(item.value)}"
+		>
+			${item.icon}
+			<span class="flex-1 truncate">${item.label}</span>
+			${
+				item.shortcut === undefined
+					? null
+					: html`<span class="text-muted-foreground ml-auto text-xs tracking-widest"
+						>${item.shortcut}</span
+					>`
+			}
+		</div>`;
+	}
+});