@c9up/nebula 0.1.0

package/dist/organisms/Chart.js

@@ -0,0 +1,189 @@
+/**
+ * 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 { read } from "../lib/props.js";
+const VIEWBOX_WIDTH = 600;
+const PADDING = { top: 8, right: 8, bottom: 24, left: 40 };
+function colorFor(series, index) {
+    return series.color ?? `var(--chart-${(index % 5) + 1})`;
+}
+function numberAt(datum, key) {
+    const value = datum[key];
+    return typeof value === "number" ? value : 0;
+}
+function categoryAt(datum, key) {
+    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, series) {
+    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((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) => PADDING.top + plotHeight - ((value - min) / (max - min)) * plotHeight;
+    /** Centre of the slot for index `i`, so points sit above their labels. */
+    const x = (index) => {
+        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) {
+        return props.data
+            .map((datum, index) => `${index === 0 ? "M" : "L"}${x(index)},${y(numberAt(datum, series.key))}`)
+            .join(" ");
+    }
+    function areaPath(series) {
+        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, index) {
+        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, seriesIndex) {
+        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() {
+        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/dist/organisms/Combobox.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 { type Reactive } from "../lib/props.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 declare const Combobox: (props?: ComboboxProps | undefined) => import("@c9up/aurora").TemplateResult;

package/dist/organisms/Combobox.js

@@ -0,0 +1,102 @@
+/**
+ * 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 { 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 } from "./Command.js";
+import { selectTriggerClasses } from "./Select.js";
+export const Combobox = component((props) => {
+    const triggerId = uid("combobox-trigger");
+    const contentId = uid("combobox-content");
+    const open = signal(false);
+    const selection = controllable({
+        value: props.value,
+        initial: props.defaultValue,
+        onChange: (next) => {
+            if (next !== undefined)
+                props.onValueChange?.(next);
+        },
+    });
+    function labelFor(value) {
+        return props.options.find((option) => option.value === value)?.label;
+    }
+    const items = () => props.options.map((option) => ({
+        value: option.value,
+        label: option.label,
+        keywords: option.keywords,
+        disabled: option.disabled,
+        group: option.group,
+    }));
+    function choose(item) {
+        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/dist/organisms/Command.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 type { Child } from "../lib/children.js";
+import { type Reactive } 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 declare function defaultFilter(item: CommandItem, query: string): boolean;
+export declare const Command: (props?: CommandProps | undefined) => import("@c9up/aurora").TemplateResult;

package/dist/organisms/Command.js

@@ -0,0 +1,171 @@
+/**
+ * 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 { cn } from "../lib/cn.js";
+import { SearchIcon } from "../lib/icons.js";
+import { uid } from "../lib/id.js";
+import { read } from "../lib/props.js";
+/** Substring over the label, then over each keyword. */
+export function defaultFilter(item, query) {
+    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((props) => {
+    const inputId = uid("command-input");
+    const listId = uid("command-list");
+    const itemIds = new Map();
+    for (const item of props.items)
+        itemIds.set(item.value, uid("command-item"));
+    const query = signal("");
+    const active = signal(undefined);
+    function matches() {
+        const filter = props.filter ?? defaultFilter;
+        return props.items.filter((item) => item.disabled !== true && filter(item, query()));
+    }
+    function run(item) {
+        if (item.disabled === true)
+            return;
+        item.onSelect?.();
+        props.onSelect?.(item);
+    }
+    function move(delta) {
+        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) {
+        const id = itemIds.get(value);
+        if (id === undefined)
+            return;
+        document.getElementById(id)?.scrollIntoView({ block: "nearest" });
+    }
+    function onKeyDown(event) {
+        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) {
+        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() {
+        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;
+        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) {
+        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>`;
+    }
+});

package/dist/organisms/CommandDialog.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CommandDialog — the command palette, full screen.
+ *
+ * `Command` on its own is a list you place somewhere. This is the form people
+ * mean by "command palette": a modal over the page, opened by a keyboard
+ * shortcut, dismissed by Escape or a click outside.
+ *
+ * An organism composing another organism — `Command` inside `modalSurface`.
+ * Nothing about the palette's behaviour is re-implemented here; the filter,
+ * the highlight and the keyboard model stay in `Command`, and this file adds
+ * only the modal shell and the shortcut.
+ *
+ * The shortcut is opt-in but built in, because binding it correctly is
+ * fiddlier than it looks: it has to be a capturing document listener (a menu
+ * or a dialog already open would otherwise swallow it), it has to preventDefault
+ * (⌘K is "focus the search bar" in several browsers), and it has to toggle
+ * rather than open, so the same keystroke closes it.
+ *
+ * The title is present but visually hidden. A dialog with no accessible name
+ * is announced as just "dialog"; giving it one costs nothing and the palette's
+ * own search field is the visible affordance.
+ */
+import type { Child } from "../lib/children.js";
+import { type Reactive } from "../lib/props.js";
+import { type CommandProps } from "./Command.js";
+export interface CommandDialogProps extends Omit<CommandProps, "class"> {
+    /** Announced on open. Hidden visually unless `showTitle`. */
+    title?: Child;
+    description?: Child;
+    showTitle?: boolean;
+    open?: Reactive<boolean>;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * A single character that opens the palette with the platform's command
+     * modifier — `"k"` gives ⌘K on macOS and Ctrl+K elsewhere. Omit for a
+     * palette opened only from your own code.
+     */
+    shortcut?: string;
+    contentClass?: Reactive<string>;
+}
+export declare const CommandDialog: (props?: CommandDialogProps | undefined) => import("@c9up/aurora").TemplateResult;