@c9up/nebula 0.1.0

package/src/organisms/CommandDialog.ts

@@ -0,0 +1,149 @@
+/**
+ * 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 { component, html, onMount, onUnmount } from "@c9up/aurora";
+import type { Child } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { fadeInOut, zoomInOut } from "../lib/motion.js";
+import { type Reactive, read } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.js";
+import { modalSurface } from "../primitives/modalSurface.js";
+import { Command, type CommandItem, type CommandProps } from "./Command.js";
+import { dialogBackdropClasses } from "./Dialog.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 const CommandDialog = component<CommandDialogProps>((props) => {
+	const panelId = uid("command-dialog-panel");
+	const titleId = uid("command-dialog-title");
+	const descriptionId = uid("command-dialog-description");
+
+	const state = controllable<boolean>({
+		value: props.open,
+		initial: props.defaultOpen ?? false,
+		onChange: props.onOpenChange,
+	});
+
+	/**
+	 * Toggle, not open — the same keystroke has to close it.
+	 *
+	 * Captured at the document, so a menu or popover that is already open does
+	 * not consume the key on its way up. `metaKey || ctrlKey` covers both
+	 * platforms without sniffing the user agent.
+	 */
+	function onKeyDown(event: KeyboardEvent): void {
+		if (props.shortcut === undefined) return;
+		if (event.key.toLowerCase() !== props.shortcut.toLowerCase()) return;
+		if (!event.metaKey && !event.ctrlKey) return;
+		event.preventDefault();
+		state.set(!state.current());
+	}
+
+	onMount(() => {
+		if (props.shortcut === undefined) return;
+		document.addEventListener("keydown", onKeyDown, true);
+	});
+	onUnmount(() => document.removeEventListener("keydown", onKeyDown, true));
+
+	function close(): void {
+		state.set(false);
+	}
+
+	function runAndClose(item: CommandItem): void {
+		props.onSelect?.(item);
+		// Closing after the action, not before: a handler that opens another
+		// surface should not have this one tearing down focus underneath it.
+		close();
+	}
+
+	modalSurface({
+		open: () => state.current(),
+		onClose: close,
+		panel: (root) => root.querySelector(`#${CSS.escape(panelId)}`),
+		// The search field, not the first focusable — the whole point of the
+		// palette is that you can start typing immediately.
+		initialFocus: (panel) => panel.querySelector("input"),
+		content: () =>
+			html`<div
+				data-slot="command-dialog-overlay"
+				class="${cn("fixed inset-0 z-50", fadeInOut)}"
+			>
+				<div class="${dialogBackdropClasses}"></div>
+				<div
+					data-slot="command-dialog"
+					id="${panelId}"
+					role="dialog"
+					aria-modal="true"
+					aria-labelledby="${titleId}"
+					aria-describedby="${props.description === undefined ? undefined : descriptionId}"
+					tabindex="-1"
+					class="${cn(
+						"bg-popover fixed top-[20%] left-1/2 z-50 w-full max-w-lg -translate-x-1/2 overflow-hidden rounded-lg border shadow-lg outline-none",
+						zoomInOut,
+						read(props.contentClass),
+					)}"
+				>
+					<h2
+						id="${titleId}"
+						class="${cn(
+							"px-4 pt-4 text-sm font-medium",
+							props.showTitle === true ? "" : "sr-only",
+						)}"
+					>${props.title ?? "Command palette"}</h2>
+					${
+						props.description === undefined
+							? null
+							: html`<p id="${descriptionId}" class="sr-only">${props.description}</p>`
+					}
+					${Command({
+						items: props.items,
+						placeholder: props.placeholder,
+						emptyMessage: props.emptyMessage,
+						filter: props.filter,
+						onSelect: runAndClose,
+					})}
+				</div>
+			</div>`,
+	});
+
+	// The palette has no trigger of its own — it is opened by the shortcut or
+	// by the `open` prop. Something still has to sit in the tree for the
+	// component to mount into; the surface itself lives in a portal.
+	return html`<span data-slot="command-dialog-root" hidden></span>`;
+});

package/src/organisms/ContextMenu.ts

@@ -0,0 +1,125 @@
+/**
+ * ContextMenu — a menu opened by right-clicking a region.
+ *
+ * Same panel as DropdownMenu; the difference is the anchor. There is no
+ * trigger element to position against — the menu belongs at the pointer, which
+ * could be anywhere inside the region.
+ *
+ * So a zero-size element is parked at the click coordinates and used as the
+ * anchor. It is a real element on purpose: `autoPosition` measures its rect,
+ * and that rect flips and shifts exactly like a button's would, which is what
+ * gets a menu opened near the bottom of the window to open upwards instead of
+ * off screen.
+ *
+ * Long-press opens it on touch, where there is no right button. The 500ms
+ * threshold matches the platform convention, and any movement cancels it so a
+ * scroll gesture does not surface a menu.
+ */
+
+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 { type Reactive, read } from "../lib/props.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+import { type MenuEntry, menuPanel, wireMenu } from "../primitives/menu.js";
+
+const LONG_PRESS_MS = 500;
+
+export interface ContextMenuProps {
+	/** The region that answers to right-click. */
+	children?: Slot;
+	entries: readonly MenuEntry[];
+	onOpenChange?: (open: boolean) => void;
+	class?: Reactive<string>;
+	contentClass?: Reactive<string>;
+}
+
+export const ContextMenu = component<ContextMenuProps>((props) => {
+	const regionId = uid("context-menu-region");
+	const anchorId = uid("context-menu-anchor");
+	const contentId = uid("context-menu-content");
+	const open = signal(false);
+
+	let unwire: (() => void) | null = null;
+	let pressTimer: ReturnType<typeof setTimeout> | undefined;
+
+	function setOpen(next: boolean): void {
+		open(next);
+		props.onOpenChange?.(next);
+	}
+
+	function moveAnchorTo(x: number, y: number): void {
+		const anchor = document.getElementById(anchorId);
+		if (anchor === null) return;
+		anchor.style.left = `${x}px`;
+		anchor.style.top = `${y}px`;
+	}
+
+	function openAt(x: number, y: number): void {
+		moveAnchorTo(x, y);
+		setOpen(true);
+	}
+
+	function onContextMenu(event: MouseEvent): void {
+		event.preventDefault();
+		openAt(event.clientX, event.clientY);
+	}
+
+	function onPointerDown(event: PointerEvent): void {
+		if (event.pointerType !== "touch") return;
+		cancelPress();
+		pressTimer = setTimeout(
+			() => openAt(event.clientX, event.clientY),
+			LONG_PRESS_MS,
+		);
+	}
+
+	function cancelPress(): void {
+		if (pressTimer !== undefined) clearTimeout(pressTimer);
+		pressTimer = undefined;
+	}
+
+	onUnmount(cancelPress);
+
+	floatingSurface({
+		anchor: () => document.getElementById(anchorId),
+		open: () => open(),
+		onClose: () => setOpen(false),
+		placement: "bottom-start",
+		offset: 2,
+		content: () =>
+			menuPanel({
+				id: contentId,
+				entries: props.entries,
+				onCloseAll: () => setOpen(false),
+				class: read(props.contentClass),
+			}),
+		onOpened: (panel) => {
+			unwire = wireMenu(panel, { onCloseAll: () => setOpen(false) });
+			panel.focus({ preventScroll: true });
+		},
+		onClosed: () => {
+			unwire?.();
+			unwire = null;
+		},
+	});
+
+	return html`<div
+		data-slot="context-menu"
+		id="${regionId}"
+		class="${() => cn(read(props.class))}"
+		@contextmenu="${onContextMenu}"
+		@pointerdown="${onPointerDown}"
+		@pointerup="${cancelPress}"
+		@pointermove="${cancelPress}"
+		@pointercancel="${cancelPress}"
+	>
+		${slot(props.children)}
+		<span
+			id="${anchorId}"
+			aria-hidden="true"
+			class="pointer-events-none fixed size-0"
+		></span>
+	</div>`;
+});

package/src/organisms/DataTable.ts

@@ -0,0 +1,328 @@
+/**
+ * DataTable — a table with sorting, filtering, paging and row selection.
+ *
+ * shadcn wraps `@tanstack/react-table`, a headless engine with column
+ * grouping, virtualisation, pinning and faceted filters. nebula implements the
+ * four features its own examples actually use, over the `Table` molecule.
+ *
+ * The scope line is drawn where the data does. Everything here operates on an
+ * in-memory array: sorting compares values, filtering scans rows, paging
+ * slices. That is the right answer up to a few thousand rows and the wrong one
+ * beyond, where the work belongs on the server — so rather than growing a
+ * half-server-side mode, the component stays client-side and honest about it.
+ *
+ * A generic function rather than `component<P>`: `component` needs a concrete
+ * prop type, and `Row` has to stay open so `cell` receives the caller's own
+ * row type instead of a record of unknowns.
+ *
+ * `aria-sort` on the sorted column is the part hand-rolled tables always miss.
+ * The little chevron says which column is sorted to anyone who can see it; the
+ * attribute is what says it to everyone else.
+ */
+
+import { html, signal, type TemplateResult } from "@c9up/aurora";
+import { Checkbox } from "../atoms/Checkbox.js";
+import { Input } from "../atoms/Input.js";
+import type { Child } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import {
+	ChevronDownIcon,
+	ChevronsUpDownIcon,
+	ChevronUpIcon,
+} from "../lib/icons.js";
+import { Pagination } from "../molecules/Pagination.js";
+import {
+	Table,
+	TableBody,
+	TableCell,
+	TableHead,
+	TableHeader,
+	TableRow,
+} from "../molecules/Table.js";
+
+export interface Column<Row> {
+	key: string;
+	header: Child;
+	/** Renders the cell. Defaults to the row's property of the same key. */
+	cell?: (row: Row) => Child;
+	sortable?: boolean;
+	/** What to compare when sorting. Defaults to the rendered property. */
+	sortValue?: (row: Row) => string | number;
+	class?: string;
+}
+
+export interface DataTableProps<Row> {
+	columns: readonly Column<Row>[];
+	rows: readonly Row[];
+	/** Stable identity per row — used for selection and as the render key. */
+	rowKey: (row: Row) => string;
+	/** Rows per page. Omit to show everything. */
+	pageSize?: number;
+	/** Show a filter box. Provide `filterMatch` to say what it searches. */
+	filterPlaceholder?: string;
+	filterMatch?: (row: Row, query: string) => boolean;
+	/** Add a checkbox column. */
+	selectable?: boolean;
+	onSelectionChange?: (keys: readonly string[]) => void;
+	emptyMessage?: Child;
+	class?: string;
+}
+
+type SortDirection = "asc" | "desc";
+
+export function DataTable<Row>(props: DataTableProps<Row>): TemplateResult {
+	const sortKey = signal<string | undefined>(undefined);
+	const sortDirection = signal<SortDirection>("asc");
+	const query = signal("");
+	const page = signal(1);
+	const selected = signal<readonly string[]>([]);
+
+	function readCell(row: Row, column: Column<Row>): Child {
+		if (column.cell !== undefined) return column.cell(row);
+		return propertyOf(row, column.key);
+	}
+
+	function sortableValue(row: Row, column: Column<Row>): string | number {
+		if (column.sortValue !== undefined) return column.sortValue(row);
+		const value = propertyOf(row, column.key);
+		return typeof value === "number" ? value : String(value ?? "");
+	}
+
+	function filtered(): readonly Row[] {
+		const needle = query().trim().toLowerCase();
+		if (needle === "" || props.filterMatch === undefined) return props.rows;
+		return props.rows.filter(
+			(row) => props.filterMatch?.(row, needle) === true,
+		);
+	}
+
+	function sorted(): readonly Row[] {
+		const key = sortKey();
+		const rows = filtered();
+		if (key === undefined) return rows;
+
+		const column = props.columns.find((entry) => entry.key === key);
+		if (column === undefined) return rows;
+
+		const direction = sortDirection() === "asc" ? 1 : -1;
+		// A copy: sorting the caller's array in place would reorder their data as
+		// a side effect of rendering it.
+		return [...rows].sort((left, right) => {
+			const a = sortableValue(left, column);
+			const b = sortableValue(right, column);
+			if (typeof a === "number" && typeof b === "number")
+				return (a - b) * direction;
+			return String(a).localeCompare(String(b)) * direction;
+		});
+	}
+
+	function pageCount(): number {
+		if (props.pageSize === undefined) return 1;
+		return Math.max(1, Math.ceil(sorted().length / props.pageSize));
+	}
+
+	function visible(): readonly Row[] {
+		const rows = sorted();
+		if (props.pageSize === undefined) return rows;
+		// Clamp: filtering down to fewer pages while on the last one would
+		// otherwise show an empty table with no way back.
+		const current = Math.min(page(), pageCount());
+		const from = (current - 1) * props.pageSize;
+		return rows.slice(from, from + props.pageSize);
+	}
+
+	function toggleSort(column: Column<Row>): void {
+		if (column.sortable === false) return;
+		if (sortKey() === column.key) {
+			sortDirection(sortDirection() === "asc" ? "desc" : "asc");
+			return;
+		}
+		sortKey(column.key);
+		sortDirection("asc");
+	}
+
+	function setSelection(keys: readonly string[]): void {
+		selected(keys);
+		props.onSelectionChange?.(keys);
+	}
+
+	function toggleRow(key: string): void {
+		const current = selected();
+		setSelection(
+			current.includes(key)
+				? current.filter((entry) => entry !== key)
+				: [...current, key],
+		);
+	}
+
+	/**
+	 * The header checkbox acts on the *visible* page, not the whole dataset.
+	 *
+	 * Selecting rows the user cannot see — and may have filtered away on
+	 * purpose — is the behaviour behind every "I deleted more than I meant to"
+	 * story about a bulk action.
+	 */
+	function toggleAllVisible(): void {
+		const keys = visible().map(props.rowKey);
+		const allSelected = keys.every((key) => selected().includes(key));
+		if (allSelected) {
+			setSelection(selected().filter((key) => !keys.includes(key)));
+		} else {
+			const merged = new Set([...selected(), ...keys]);
+			setSelection([...merged]);
+		}
+	}
+
+	function ariaSortFor(
+		column: Column<Row>,
+	): "ascending" | "descending" | "none" | undefined {
+		if (column.sortable === false) return undefined;
+		if (sortKey() !== column.key) return "none";
+		return sortDirection() === "asc" ? "ascending" : "descending";
+	}
+
+	function sortIcon(column: Column<Row>): Child {
+		if (column.sortable === false) return null;
+		if (sortKey() !== column.key) {
+			return ChevronsUpDownIcon({ class: "ml-2 size-3.5 opacity-50" });
+		}
+		return sortDirection() === "asc"
+			? ChevronUpIcon({ class: "ml-2 size-3.5" })
+			: ChevronDownIcon({ class: "ml-2 size-3.5" });
+	}
+
+	const columnCount =
+		props.columns.length + (props.selectable === true ? 1 : 0);
+
+	return html`<div data-slot="data-table" class="${cn("flex flex-col gap-4", props.class)}">
+		${
+			props.filterMatch === undefined
+				? null
+				: Input({
+						type: "search",
+						placeholder: props.filterPlaceholder ?? "Filter…",
+						class: "max-w-sm",
+						onInput: (value) => {
+							query(value);
+							page(1);
+						},
+					})
+		}
+		${Table({
+			children: [
+				TableHeader({
+					children: TableRow({
+						children: [
+							props.selectable === true
+								? TableHead({
+										class: "w-10",
+										children: Checkbox({
+											label: "Select all rows on this page",
+											checked: () => {
+												const keys = visible().map(props.rowKey);
+												return (
+													keys.length > 0 &&
+													keys.every((key) => selected().includes(key))
+												);
+											},
+											indeterminate: () => {
+												const keys = visible().map(props.rowKey);
+												const chosen = keys.filter((key) =>
+													selected().includes(key),
+												).length;
+												return chosen > 0 && chosen < keys.length;
+											},
+											onCheckedChange: toggleAllVisible,
+										}),
+									})
+								: null,
+							...props.columns.map((column) =>
+								TableHead({
+									class: cn(
+										column.sortable === false
+											? ""
+											: "cursor-pointer select-none",
+										column.class,
+									),
+									sort: () => ariaSortFor(column),
+									onClick: () => toggleSort(column),
+									children: html`<span class="inline-flex items-center"
+										>${column.header}${() => sortIcon(column)}</span
+									>`,
+								}),
+							),
+						],
+					}),
+				}),
+				TableBody({
+					children: () => {
+						const rows = visible();
+						if (rows.length === 0) {
+							return TableRow({
+								children: TableCell({
+									colspan: columnCount,
+									class: "h-24 text-center",
+									children: props.emptyMessage ?? "No results.",
+								}),
+							});
+						}
+						return rows.map((row) => renderRow(row));
+					},
+				}),
+			],
+		})}
+		${
+			props.pageSize === undefined
+				? null
+				: Pagination({
+						page: () => Math.min(page(), pageCount()),
+						pageCount,
+						onPageChange: (next) => page(next),
+					})
+		}
+	</div>`;
+
+	function renderRow(row: Row): Child {
+		const key = props.rowKey(row);
+		return TableRow({
+			selected: () => selected().includes(key),
+			children: [
+				props.selectable === true
+					? TableCell({
+							children: Checkbox({
+								label: `Select row ${key}`,
+								checked: () => selected().includes(key),
+								onCheckedChange: () => toggleRow(key),
+							}),
+						})
+					: null,
+				...props.columns.map((column) =>
+					TableCell({ class: column.class, children: readCell(row, column) }),
+				),
+			],
+		});
+	}
+}
+
+/**
+ * Read a property by name from a row of unknown shape.
+ *
+ * `Row` is the caller's own type and may be an interface, which cannot be
+ * indexed by an arbitrary string. The guard turns the lookup into a checked
+ * read that yields `undefined` for a missing key — a blank cell — instead of
+ * an assertion that it exists.
+ */
+function propertyOf(row: unknown, key: string): Child {
+	if (typeof row !== "object" || row === null) return null;
+	if (!(key in row)) return null;
+	const value = Reflect.get(row, key);
+	if (value === null || value === undefined) return null;
+	if (
+		typeof value === "string" ||
+		typeof value === "number" ||
+		typeof value === "boolean"
+	) {
+		return value;
+	}
+	return String(value);
+}