@c9up/nebula 0.1.0

package/dist/organisms/CommandDialog.js

@@ -0,0 +1,116 @@
+/**
+ * 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 { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { fadeInOut, zoomInOut } from "../lib/motion.js";
+import { read } from "../lib/props.js";
+import { controllable } from "../primitives/controllable.js";
+import { modalSurface } from "../primitives/modalSurface.js";
+import { Command } from "./Command.js";
+import { dialogBackdropClasses } from "./Dialog.js";
+export const CommandDialog = component((props) => {
+    const panelId = uid("command-dialog-panel");
+    const titleId = uid("command-dialog-title");
+    const descriptionId = uid("command-dialog-description");
+    const state = controllable({
+        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) {
+        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() {
+        state.set(false);
+    }
+    function runAndClose(item) {
+        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/dist/organisms/ContextMenu.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 { type Slot } from "../lib/children.js";
+import { type Reactive } from "../lib/props.js";
+import { type MenuEntry } from "../primitives/menu.js";
+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 declare const ContextMenu: (props?: ContextMenuProps | undefined) => import("@c9up/aurora").TemplateResult;

package/dist/organisms/ContextMenu.js

@@ -0,0 +1,102 @@
+/**
+ * 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 { slot } from "../lib/children.js";
+import { cn } from "../lib/cn.js";
+import { uid } from "../lib/id.js";
+import { read } from "../lib/props.js";
+import { floatingSurface } from "../primitives/floatingSurface.js";
+import { menuPanel, wireMenu } from "../primitives/menu.js";
+const LONG_PRESS_MS = 500;
+export const ContextMenu = component((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 = null;
+    let pressTimer;
+    function setOpen(next) {
+        open(next);
+        props.onOpenChange?.(next);
+    }
+    function moveAnchorTo(x, y) {
+        const anchor = document.getElementById(anchorId);
+        if (anchor === null)
+            return;
+        anchor.style.left = `${x}px`;
+        anchor.style.top = `${y}px`;
+    }
+    function openAt(x, y) {
+        moveAnchorTo(x, y);
+        setOpen(true);
+    }
+    function onContextMenu(event) {
+        event.preventDefault();
+        openAt(event.clientX, event.clientY);
+    }
+    function onPointerDown(event) {
+        if (event.pointerType !== "touch")
+            return;
+        cancelPress();
+        pressTimer = setTimeout(() => openAt(event.clientX, event.clientY), LONG_PRESS_MS);
+    }
+    function cancelPress() {
+        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/dist/organisms/DataTable.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 { type TemplateResult } from "@c9up/aurora";
+import type { Child } from "../lib/children.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;
+}
+export declare function DataTable<Row>(props: DataTableProps<Row>): TemplateResult;

package/dist/organisms/DataTable.js

@@ -0,0 +1,257 @@
+/**
+ * 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 } from "@c9up/aurora";
+import { Checkbox } from "../atoms/Checkbox.js";
+import { Input } from "../atoms/Input.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 function DataTable(props) {
+    const sortKey = signal(undefined);
+    const sortDirection = signal("asc");
+    const query = signal("");
+    const page = signal(1);
+    const selected = signal([]);
+    function readCell(row, column) {
+        if (column.cell !== undefined)
+            return column.cell(row);
+        return propertyOf(row, column.key);
+    }
+    function sortableValue(row, column) {
+        if (column.sortValue !== undefined)
+            return column.sortValue(row);
+        const value = propertyOf(row, column.key);
+        return typeof value === "number" ? value : String(value ?? "");
+    }
+    function filtered() {
+        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() {
+        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() {
+        if (props.pageSize === undefined)
+            return 1;
+        return Math.max(1, Math.ceil(sorted().length / props.pageSize));
+    }
+    function visible() {
+        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) {
+        if (column.sortable === false)
+            return;
+        if (sortKey() === column.key) {
+            sortDirection(sortDirection() === "asc" ? "desc" : "asc");
+            return;
+        }
+        sortKey(column.key);
+        sortDirection("asc");
+    }
+    function setSelection(keys) {
+        selected(keys);
+        props.onSelectionChange?.(keys);
+    }
+    function toggleRow(key) {
+        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() {
+        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) {
+        if (column.sortable === false)
+            return undefined;
+        if (sortKey() !== column.key)
+            return "none";
+        return sortDirection() === "asc" ? "ascending" : "descending";
+    }
+    function sortIcon(column) {
+        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) {
+        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, key) {
+    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);
+}

package/dist/organisms/DatePicker.d.ts

@@ -0,0 +1,34 @@
+/**
+ * DatePicker — a Calendar in a popover, behind a button.
+ *
+ * shadcn composes this out of Popover, Button and Calendar rather than
+ * shipping it; nebula ships it, because the composition has three details that
+ * are easy to get wrong and pointless to rediscover per project.
+ *
+ * The popover closes on selection — a date picker that stays open after a
+ * choice leaves the user hunting for the way out. Focus returns to the
+ * trigger, so the tab order does not restart at the top of the page. And the
+ * trigger reads the chosen date through `Intl.DateTimeFormat`, so it renders
+ * in the user's locale rather than an American ordering everyone else has to
+ * decode.
+ *
+ * A hidden input carries the value as ISO `YYYY-MM-DD`, which is what a server
+ * wants — never the localised string on the button.
+ */
+import { type Reactive } from "../lib/props.js";
+export interface DatePickerProps {
+    name?: string;
+    value?: Reactive<Date | undefined>;
+    defaultValue?: Date;
+    placeholder?: string;
+    min?: Date;
+    max?: Date;
+    disabled?: Reactive<boolean>;
+    invalid?: Reactive<boolean>;
+    locale?: string;
+    class?: Reactive<string>;
+    onValueChange?: (date: Date) => void;
+}
+/** `YYYY-MM-DD` from a local date, without a timezone round-trip. */
+export declare function toISODate(date: Date): string;
+export declare const DatePicker: (props?: DatePickerProps | undefined) => import("@c9up/aurora").TemplateResult;