@calliopelabs/ui 0.0.0-stage → 0.1.0

package/dist/appearance/product.js

@@ -0,0 +1,96 @@
+import { ACCENTS, ACCENT_KEYS, GROUNDS, GROUND_KEYS, } from "../theme/tokens.js";
+export const CORNERS = [0, 2, 4, 10];
+const SLUG = /^[a-z][a-z0-9-]*$/;
+const HEX = /^#[0-9a-f]{6}$/;
+function fail(product, message) {
+    throw new Error(`@calliopelabs/ui: product "${product}": ${message}`);
+}
+/**
+ * Validate a product config and fill in its defaults. Throws on anything
+ * that would paint wrong or inject into the generated CSS: a key that is not
+ * a slug, a colour that is not lowercase `#rrggbb`, a default ground the
+ * product does not offer, or a default ground of the wrong mode.
+ */
+export function defineProduct(config) {
+    const { id } = config;
+    if (!SLUG.test(id))
+        fail(id, "id must be a lowercase slug");
+    if (!config.name.trim())
+        fail(id, "name is required");
+    if (!HEX.test(config.sidebar))
+        fail(id, `sidebar must be lowercase #rrggbb, got ${config.sidebar}`);
+    const grounds = config.grounds ? [...config.grounds] : [...GROUND_KEYS];
+    if (grounds.length === 0)
+        fail(id, "offer at least one ground");
+    for (const ground of grounds) {
+        if (!(ground in GROUNDS))
+            fail(id, `unknown ground ${ground}`);
+    }
+    const defaultGround = config.defaultGround ?? {
+        dark: grounds.find((g) => GROUNDS[g].mode === "dark") ?? fail(id, "offer a dark ground"),
+        light: grounds.find((g) => GROUNDS[g].mode === "light") ?? fail(id, "offer a light ground"),
+    };
+    for (const mode of ["dark", "light"]) {
+        const ground = defaultGround[mode];
+        if (!grounds.includes(ground))
+            fail(id, `default ${mode} ground ${ground} is not offered`);
+        if (GROUNDS[ground].mode !== mode)
+            fail(id, `default ${mode} ground ${ground} is a ${GROUNDS[ground].mode} ground`);
+    }
+    const family = ACCENT_KEYS.map((key) => ({
+        key,
+        ...ACCENTS[key],
+        brand: false,
+    }));
+    let brandAccent = null;
+    if (typeof config.accent === "string") {
+        if (!(config.accent in ACCENTS))
+            fail(id, `unknown accent ${config.accent}`);
+    }
+    else {
+        brandAccent = config.accent;
+        if (!SLUG.test(brandAccent.key))
+            fail(id, "brand accent key must be a lowercase slug");
+        if (brandAccent.key in ACCENTS || brandAccent.key === "custom") {
+            fail(id, `brand accent key ${brandAccent.key} is taken by the family`);
+        }
+        for (const field of ["dark", "onDark", "light", "onLight"]) {
+            if (!HEX.test(brandAccent[field]))
+                fail(id, `brand accent ${field} must be lowercase #rrggbb`);
+        }
+    }
+    const accents = brandAccent
+        ? [{ ...brandAccent, brand: true }, ...family]
+        : family;
+    const defaultAccent = typeof config.accent === "string" ? config.accent : config.accent.key;
+    const density = config.defaultDensity ?? "compact";
+    if (density !== "compact" && density !== "cards")
+        fail(id, `unknown density ${String(density)}`);
+    const corners = config.defaultCorners ?? 2;
+    if (!CORNERS.includes(corners))
+        fail(id, `corners must be one of ${CORNERS.join(", ")}`);
+    const themes = config.themes ?? [];
+    for (const theme of themes) {
+        if (!grounds.includes(theme.ground))
+            fail(id, `theme ${theme.id} uses ground ${theme.ground}, which is not offered`);
+        if (!accents.some((a) => a.key === theme.accent))
+            fail(id, `theme ${theme.id} uses unknown accent ${theme.accent}`);
+    }
+    return {
+        id,
+        name: config.name,
+        sidebar: config.sidebar,
+        grounds,
+        accents,
+        brandAccent,
+        defaults: {
+            ground: defaultGround,
+            accent: defaultAccent,
+            density,
+            corners,
+        },
+        themes,
+        nav: config.nav ?? [],
+        storageKey: `${id}.appearance`,
+    };
+}

package/dist/data/DataTable.d.ts

@@ -0,0 +1,66 @@
+import * as React from "react";
+import type { Density } from "../theme/tokens.js";
+import { type Column, type EmptyStateSpec, type TableController } from "./types.js";
+import type { RowSelection } from "./use-row-selection.js";
+type RowActivation<TRow> = {
+    /** Rows that navigate are real links: middle-click, open in a new tab and copy link all work. */
+    rowHref: (row: TRow) => string;
+    onRowActivate?: never;
+    /** Names a row for its checkbox and its menu ("run 7f3c2a91"). Defaults to the row id. */
+    rowLabel?: (row: TRow) => string;
+} | {
+    /** Rows that act in place are buttons, never fake links. */
+    onRowActivate: (row: TRow) => void;
+    /**
+     * The activator's accessible name, and the name of the row's checkbox
+     * and menu. Identify the row ("run 7f3c2a91"); the role supplies the verb.
+     */
+    rowLabel: (row: TRow) => string;
+    rowHref?: never;
+} | {
+    rowHref?: never;
+    onRowActivate?: never;
+    rowLabel?: (row: TRow) => string;
+};
+interface DataTableBaseProps<TRow> {
+    /** Names the table for screen readers and in the state copy ("Could not load runs"). */
+    label: string;
+    controller: TableController<TRow>;
+    columns: readonly Column<TRow>[];
+    getRowId: (row: TRow) => string;
+    /** The list is genuinely empty. Required: a table never renders nothing. */
+    empty: EmptyStateSpec;
+    /** The search or filters excluded everything. Defaults to a clear-search prompt. */
+    emptyFiltered?: Pick<EmptyStateSpec, "title" | "description">;
+    /** Turns on the row and page checkboxes. */
+    selection?: RowSelection;
+    /** Shown in a bar above the table while rows are selected. */
+    bulkActions?: (selection: RowSelection) => React.ReactNode;
+    /** Items for each row's `⋯` menu (`DropdownMenuItem`s). */
+    rowActions?: (row: TRow) => React.ReactNode;
+    searchPlaceholder?: string;
+    /** Filters and actions beside the search box. */
+    toolbar?: React.ReactNode;
+    rowClassName?: (row: TRow) => string | undefined;
+    /**
+     * The card for a row, drawn when the density is `cards`: the content only;
+     * the table draws the box. Without it, cards density keeps the table with
+     * roomier rows. Cards carry no checkboxes and no row menu.
+     */
+    renderCard?: (row: TRow) => React.ReactNode;
+    /** Overrides the person's density for this table. */
+    density?: Density;
+    /** `table` draws the table alone, for a page that draws its own filter bar and paging. */
+    chrome?: "full" | "table";
+    className?: string;
+}
+export type DataTableProps<TRow> = DataTableBaseProps<TRow> & RowActivation<TRow>;
+/**
+ * The house list surface (Astrolift #1231), with its guarantees in the
+ * types: `label` and `empty` are required, `empty` and `emptyFiltered` are
+ * different states, rows are links or buttons and never both, loading draws
+ * skeleton rows inside the real table, and sorting is the server's. Density
+ * is real: compact rows, or boxed cards when the table has a card renderer.
+ */
+export declare function DataTable<TRow>({ label, controller, columns, getRowId, empty, emptyFiltered, selection, bulkActions, rowActions, searchPlaceholder, toolbar, rowClassName, renderCard, density: densityProp, chrome, className, rowHref, onRowActivate, rowLabel, }: DataTableProps<TRow>): React.JSX.Element;
+export {};

package/dist/data/DataTable.js

@@ -0,0 +1,148 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ArrowDownIcon, ArrowUpIcon, ChevronLeftIcon, ChevronRightIcon, ChevronsUpDownIcon, MoreHorizontalIcon, SearchIcon, SearchXIcon, TriangleAlertIcon, XIcon, } from "lucide-react";
+import * as React from "react";
+import { useDensity } from "../appearance/AppearanceProvider.js";
+import { cn } from "../lib/cn.js";
+import { Button } from "../primitives/Button.js";
+import { Checkbox } from "../primitives/Checkbox.js";
+import { DropdownMenu, DropdownMenuContent, DropdownMenuTrigger, } from "../primitives/DropdownMenu.js";
+import { Input } from "../primitives/Input.js";
+import { Skeleton } from "../primitives/Skeleton.js";
+import { useUI } from "../provider/UIProvider.js";
+import { EmptyState } from "../states/EmptyState.js";
+import { PAGE_SIZES, } from "./types.js";
+const ALIGN = { left: "text-left", right: "text-right", center: "text-center" };
+const CELL = "px-(--row-pad-x) py-(--row-pad-y) align-middle whitespace-nowrap";
+function sortKeys(sort) {
+    if (!sort)
+        return [];
+    return Array.isArray(sort) ? sort : [sort];
+}
+/**
+ * The house list surface (Astrolift #1231), with its guarantees in the
+ * types: `label` and `empty` are required, `empty` and `emptyFiltered` are
+ * different states, rows are links or buttons and never both, loading draws
+ * skeleton rows inside the real table, and sorting is the server's. Density
+ * is real: compact rows, or boxed cards when the table has a card renderer.
+ */
+export function DataTable({ label, controller, columns, getRowId, empty, emptyFiltered, selection, bulkActions, rowActions, searchPlaceholder, toolbar, rowClassName, renderCard, density: densityProp, chrome = "full", className, rowHref, onRowActivate, rowLabel, }) {
+    const { Link, messages } = useUI();
+    const t = messages.table;
+    const contextDensity = useDensity();
+    const density = densityProp ?? contextDensity;
+    const { rows, state, error, retry, pageSize, clearFilters } = controller;
+    const cards = density === "cards" && Boolean(renderCard);
+    const pageIds = React.useMemo(() => rows.map(getRowId), [rows, getRowId]);
+    const visibleColumns = rowActions
+        ? [
+            ...columns,
+            {
+                id: "__actions",
+                header: _jsx("span", { className: "sr-only", children: t.actions }),
+                width: "w-10",
+                align: "right",
+                // Above the row's stretched link, so the menu opens instead of the row.
+                cellClassName: "relative z-10",
+                cell: (row) => (_jsx(RowMenu, { label: t.rowActions(rowLabel?.(row) ?? getRowId(row)), children: rowActions(row) })),
+            },
+        ]
+        : [...columns];
+    const columnCount = visibleColumns.length + (selection ? 1 : 0);
+    const firstColumnId = visibleColumns[0]?.id;
+    const sorts = sortKeys(controller.sort);
+    const message = (icon, title, body, action, alert = false) => (_jsxs("div", { role: alert ? "alert" : undefined, className: "flex flex-col items-center gap-3 px-6 text-center", children: [icon, _jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "font-medium", children: title }), _jsx("p", { className: "mt-1 max-w-md text-sm [overflow-wrap:anywhere] text-muted-foreground", children: body })] }), action] }));
+    const errorMessage = message(_jsx(TriangleAlertIcon, { className: "size-5 text-danger", "aria-hidden": true }), t.loadFailed(label), error?.message || t.requestFailed, _jsx(Button, { size: "sm", variant: "outline", onClick: retry, children: t.retry }), true);
+    const filteredMessage = message(_jsx(SearchXIcon, { className: "size-5 text-muted-foreground", "aria-hidden": true }), emptyFiltered?.title ?? t.noMatches, emptyFiltered?.description ?? t.noMatchesDescription(label), _jsx(Button, { size: "sm", variant: "outline", onClick: clearFilters, children: t.clearSearch }));
+    // A message spanning the row stays in view when a wide table scrolls
+    // sideways: it is as wide as the scroll container (100cqw), pinned left.
+    const fullRow = (content, padded = true) => (_jsx("tr", { children: _jsx("td", { colSpan: columnCount, className: "p-0", children: _jsx("div", { className: cn("sticky left-0 w-[100cqw] max-w-full", padded && "py-10"), children: content }) }) }));
+    const tableBody = (() => {
+        switch (state) {
+            case "loading":
+                // Skeleton rows inside the real table, sized from the columns, so the
+                // first paint has the geometry the rows will have.
+                return Array.from({ length: Math.min(pageSize, 8) }, (_, i) => (_jsxs("tr", { className: "border-b last:border-0", children: [selection && (_jsx("td", { className: cn(CELL, "w-10"), children: _jsx(Skeleton, { className: "size-4" }) })), visibleColumns.map((column) => (_jsx("td", { className: cn(CELL, column.width), children: _jsx(Skeleton, { className: "h-4 w-full" }) }, column.id)))] }, `skeleton-${i}`)));
+            case "error":
+                return fullRow(errorMessage);
+            case "emptyFiltered":
+                return fullRow(filteredMessage);
+            case "empty":
+                return fullRow(_jsx(EmptyState, { ...empty, className: "rounded-none border-0" }), false);
+            case "ready":
+                return rows.map((row) => {
+                    const id = getRowId(row);
+                    const selected = selection?.isSelected(id) ?? false;
+                    return (_jsxs("tr", { "data-state": selected ? "selected" : undefined, 
+                        // `relative`: the activator is stretched with `after:inset-0`,
+                        // which reaches the nearest positioned ancestor; without it the
+                        // last row's overlay would swallow every click (Astrolift #1502).
+                        className: cn("border-b transition-colors last:border-0 hover:bg-muted/50 data-[state=selected]:bg-muted", (rowHref || onRowActivate) && "relative cursor-pointer", rowClassName?.(row)), children: [selection && (_jsx("td", { className: cn(CELL, "relative z-10 w-10"), children: _jsx(Checkbox, { checked: selected, onCheckedChange: () => selection.toggle(id), "aria-label": t.selectRow(rowLabel?.(row) ?? id) }) })), visibleColumns.map((column) => (_jsx("td", { className: cn(CELL, column.width, column.align && ALIGN[column.align], column.cellClassName), children: column.id === firstColumnId && rowHref ? (_jsx(Link, { href: rowHref(row), className: "outline-none after:absolute after:inset-0 focus-visible:after:ring-2 focus-visible:after:ring-ring focus-visible:after:ring-inset", children: column.cell(row) })) : column.id === firstColumnId && onRowActivate ? (_jsx("button", { type: "button", "aria-label": rowLabel?.(row), onClick: () => onRowActivate(row), className: "text-left outline-none after:absolute after:inset-0 focus-visible:after:ring-2 focus-visible:after:ring-ring focus-visible:after:ring-inset", children: column.cell(row) })) : (column.cell(row)) }, column.id)))] }, id));
+                });
+        }
+    })();
+    const table = (_jsxs("div", { className: "relative overflow-hidden rounded-lg border", "aria-busy": state === "loading" || controller.isStale || undefined, children: [controller.isStale && _jsx(StaleBar, {}), _jsx("div", { className: "[container-type:inline-size] relative w-full overflow-x-auto", children: _jsxs("table", { className: "w-full caption-bottom text-sm", children: [_jsx("caption", { className: "sr-only", children: label }), _jsx("thead", { children: _jsxs("tr", { className: "border-b", children: [selection && (_jsx("th", { scope: "col", className: "h-10 w-10 px-(--row-pad-x) align-middle", children: _jsx(Checkbox, { checked: selection.pageSelectionState(pageIds), onCheckedChange: () => selection.togglePage(pageIds), "aria-label": t.selectPage(label), disabled: pageIds.length === 0 }) })), visibleColumns.map((column) => (_jsx("th", { scope: "col", "aria-sort": ariaSort(column.sortKey, sorts), className: cn("h-10 px-(--row-pad-x) text-left align-middle text-2xs font-semibold tracking-[0.08em] whitespace-nowrap text-muted-foreground uppercase", column.width, column.align && ALIGN[column.align], column.headClassName), children: column.sortKey && controller.sortEnabled ? (_jsx(SortHeader, { sortKey: column.sortKey, sorts: sorts, onToggle: controller.toggleSort, children: column.header })) : (column.header) }, column.id)))] }) }), _jsx("tbody", { children: tableBody })] }) })] }));
+    const cardGrid = (() => {
+        const grid = "grid min-w-0 grid-cols-(--list-columns) gap-(--list-gap)";
+        const box = "relative min-w-0 rounded-(--list-item-radius) border-(length:--list-item-border) bg-(--list-item-bg) [padding:var(--list-item-pad)]";
+        switch (state) {
+            case "loading":
+                return (_jsx("div", { className: grid, "aria-busy": true, children: Array.from({ length: Math.min(pageSize, 6) }, (_, i) => (_jsx(Skeleton, { className: "h-28 w-full" }, i))) }));
+            case "error":
+                return _jsx("div", { className: "rounded-lg border py-10", children: errorMessage });
+            case "emptyFiltered":
+                return _jsx("div", { className: "rounded-lg border py-10", children: filteredMessage });
+            case "empty":
+                return _jsx(EmptyState, { ...empty });
+            case "ready":
+                return (_jsxs("div", { className: "relative", "aria-busy": controller.isStale || undefined, children: [controller.isStale && _jsx(StaleBar, { className: "-top-1.5" }), _jsx("ul", { "aria-label": label, className: grid, children: rows.map((row) => (_jsx("li", { className: cn(box, rowClassName?.(row)), children: rowHref ? (_jsx(Link, { href: rowHref(row), className: "block h-full rounded-lg outline-none after:absolute after:inset-0 focus-visible:after:ring-2 focus-visible:after:ring-ring", children: renderCard?.(row) })) : onRowActivate ? (_jsx("button", { type: "button", "aria-label": rowLabel?.(row), onClick: () => onRowActivate(row), className: "block h-full w-full text-left outline-none after:absolute after:inset-0 focus-visible:after:ring-2 focus-visible:after:ring-ring", children: renderCard?.(row) })) : (renderCard?.(row)) }, getRowId(row)))) })] }));
+        }
+    })();
+    return (_jsxs("div", { "data-slot": "data-table", "data-density": densityProp, className: cn("flex min-w-0 flex-col gap-3", className), children: [chrome === "full" && (_jsx(Toolbar, { controller: controller, placeholder: searchPlaceholder, children: toolbar })), selection && selection.selectedCount > 0 && bulkActions && !cards && (_jsxs("div", { className: "flex flex-wrap items-center gap-3 rounded-lg border bg-muted/50 px-3 py-2", children: [_jsx("span", { className: "text-sm font-medium tabular-nums", children: t.selected(selection.selectedCount) }), _jsx(Button, { variant: "ghost", size: "sm", onClick: selection.clear, children: t.clearSelection }), _jsx("div", { className: "ml-auto flex flex-wrap items-center gap-2", children: bulkActions(selection) })] })), cards ? cardGrid : table, chrome === "full" && _jsx(Pagination, { controller: controller }), state === "loading" && (_jsx("p", { role: "status", className: "sr-only", children: t.loading }))] }));
+}
+/**
+ * The rows on screen answer the previous question while the next answer is
+ * on its way. They stay at full contrast; this line across the top of the
+ * frame says they are being replaced. With reduced motion it holds still.
+ */
+function StaleBar({ className }) {
+    return (_jsx("div", { "aria-hidden": true, className: cn("pointer-events-none absolute inset-x-0 top-0 z-20 h-0.5 overflow-hidden", className), children: _jsx("div", { className: "h-full w-1/3 animate-cui-progress rounded-full bg-primary motion-reduce:animate-none" }) }));
+}
+function ariaSort(sortKey, sorts) {
+    const primary = sorts[0];
+    if (!sortKey || primary?.key !== sortKey)
+        return undefined;
+    return primary.dir === "asc" ? "ascending" : "descending";
+}
+function SortHeader({ sortKey, sorts, onToggle, children, }) {
+    const { messages } = useUI();
+    const index = sorts.findIndex((s) => s.key === sortKey);
+    const dir = index === -1 ? undefined : sorts[index]?.dir;
+    return (_jsxs("button", { type: "button", onClick: (event) => onToggle(sortKey, event.shiftKey), className: cn("inline-flex items-center gap-1 rounded-lg uppercase transition-colors hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", dir ? "text-foreground" : "text-muted-foreground"), children: [children, dir === "asc" ? (_jsx(ArrowUpIcon, { className: "size-3.5", "aria-hidden": true })) : dir === "desc" ? (_jsx(ArrowDownIcon, { className: "size-3.5", "aria-hidden": true })) : (_jsx(ChevronsUpDownIcon, { className: "size-3.5 opacity-40", "aria-hidden": true })), index !== -1 && sorts.length > 1 && (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, className: "font-mono text-2xs tabular-nums", children: index + 1 }), _jsxs("span", { className: "sr-only", children: [", ", messages.table.sortKey(index + 1)] })] }))] }));
+}
+function Toolbar({ controller, placeholder, children, }) {
+    const { messages } = useUI();
+    const t = messages.table;
+    const { search, setSearch, searchEnabled, totalCount } = controller;
+    if (!searchEnabled && !children && totalCount === null)
+        return null;
+    const searchLabel = placeholder ?? t.search;
+    return (_jsxs("div", { className: "flex flex-wrap items-center gap-2", children: [searchEnabled && (_jsxs("div", { className: "relative min-w-56 flex-1 sm:max-w-xs", children: [_jsx(SearchIcon, { className: "pointer-events-none absolute top-1/2 left-2 size-4 -translate-y-1/2 text-muted-foreground", "aria-hidden": true }), _jsx(Input, { type: "search", value: search, onChange: (event) => setSearch(event.target.value), placeholder: searchLabel, "aria-label": searchLabel, className: "pr-8 pl-8 [&::-webkit-search-cancel-button]:appearance-none" }), search && (_jsx(Button, { variant: "ghost", size: "icon-xs", onClick: () => setSearch(""), "aria-label": t.clearSearch, className: "absolute top-1/2 right-1 -translate-y-1/2", children: _jsx(XIcon, { "aria-hidden": true }) }))] })), children, totalCount !== null && (_jsx("span", { className: "ml-auto text-sm text-muted-foreground tabular-nums", children: t.results(totalCount) }))] }));
+}
+/**
+ * Previous and next, never a page number to jump to: a keyset walk has no
+ * "page 7", so the control cannot be rendered honestly.
+ */
+function Pagination({ controller }) {
+    const { messages } = useUI();
+    const t = messages.table;
+    const selectId = React.useId();
+    const { pageIndex, hasNext, hasPrev, next, prev, pageSize, setPageSize } = controller;
+    const sizes = controller.pageSizes ?? PAGE_SIZES;
+    if (!hasNext && !hasPrev)
+        return null;
+    return (_jsxs("div", { className: "flex flex-wrap items-center justify-end gap-4", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsx("label", { htmlFor: selectId, className: "text-sm text-muted-foreground", children: t.rowsPerPage }), _jsx("select", { id: selectId, value: pageSize, onChange: (event) => setPageSize(Number(event.target.value)), className: "h-7 rounded-lg border border-input bg-transparent px-2 text-sm outline-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50", children: sizes.map((size) => (_jsx("option", { value: size, children: size }, size))) })] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx("span", { className: "text-sm text-muted-foreground tabular-nums", children: t.page(pageIndex + 1) }), _jsx(Button, { variant: "outline", size: "icon", onClick: prev, disabled: !hasPrev, "aria-label": t.previousPage, children: _jsx(ChevronLeftIcon, { "aria-hidden": true }) }), _jsx(Button, { variant: "outline", size: "icon", onClick: next, disabled: !hasNext, "aria-label": t.nextPage, children: _jsx(ChevronRightIcon, { "aria-hidden": true }) })] })] }));
+}
+function RowMenu({ label, children }) {
+    return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": label, children: _jsx(MoreHorizontalIcon, { "aria-hidden": true }) }) }), _jsx(DropdownMenuContent, { align: "end", className: "min-w-40", children: children })] }));
+}

package/dist/data/List.d.ts

@@ -0,0 +1,55 @@
+import type * as React from "react";
+import type { Density } from "../theme/tokens.js";
+import type { EmptyStateSpec } from "./types.js";
+export interface ListProps<TItem> {
+    /** Names the list for screen readers and in its error copy. */
+    label: string;
+    items: readonly TItem[];
+    getKey: (item: TItem) => string;
+    /** One item's content, usually a ListItem. The list draws the row or the card around it. */
+    renderItem: (item: TItem) => React.ReactNode;
+    /** Overrides the person's density for this list. */
+    density?: Density;
+    loading?: boolean;
+    /** How many placeholder items to draw while loading. */
+    loadingCount?: number;
+    error?: {
+        message: string;
+    } | null;
+    onRetry?: () => void;
+    /** Required: a list never renders nothing. */
+    empty: EmptyStateSpec;
+    className?: string;
+}
+/**
+ * A short, fixed list (integrations, links, a summary's top five) in the
+ * person's density: compact is one panel of hairline rows; cards boxes each
+ * item and flows them into responsive columns. Six links with a name and a
+ * sentence are a list, not six cards, until someone asks for cards.
+ *
+ * The layout is driven by CSS variables that `data-density` sets, so the
+ * first paint already has the right one and a subtree can override it. A
+ * list that can grow without bound is a DataTable, with server paging.
+ */
+export declare function List<TItem>({ label, items, getKey, renderItem, density, loading, loadingCount, error, onRetry, empty, className, }: ListProps<TItem>): React.JSX.Element;
+export interface ListItemProps {
+    title: React.ReactNode;
+    /** The whole item links here; the title is the link, stretched over the item. */
+    href?: string;
+    description?: React.ReactNode;
+    /** Leading: an icon or a logo. */
+    icon?: React.ReactNode;
+    /** Trailing data: mono values, counts, times. */
+    meta?: React.ReactNode;
+    /** A StatusBadge. */
+    status?: React.ReactNode;
+    /** Controls, kept above the item's stretched link. */
+    actions?: React.ReactNode;
+    className?: string;
+}
+/**
+ * One item's content: a row in compact density (icon, title and description,
+ * then meta, status and actions on the right) and a card in cards density
+ * (the same parts stacked).
+ */
+export declare function ListItem({ title, href, description, icon, meta, status, actions, className, }: ListItemProps): React.JSX.Element;

package/dist/data/List.js

@@ -0,0 +1,41 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/cn.js";
+import { Skeleton } from "../primitives/Skeleton.js";
+import { useUI } from "../provider/UIProvider.js";
+import { EmptyState } from "../states/EmptyState.js";
+import { ErrorState } from "../states/ErrorState.js";
+/**
+ * A short, fixed list (integrations, links, a summary's top five) in the
+ * person's density: compact is one panel of hairline rows; cards boxes each
+ * item and flows them into responsive columns. Six links with a name and a
+ * sentence are a list, not six cards, until someone asks for cards.
+ *
+ * The layout is driven by CSS variables that `data-density` sets, so the
+ * first paint already has the right one and a subtree can override it. A
+ * list that can grow without bound is a DataTable, with server paging.
+ */
+export function List({ label, items, getKey, renderItem, density, loading = false, loadingCount = 4, error, onRetry, empty, className, }) {
+    const { messages } = useUI();
+    const frame = "grid min-w-0 grid-cols-(--list-columns) gap-(--list-gap) overflow-hidden rounded-(--list-frame-radius) border-(length:--list-frame-border)";
+    const box = "relative min-w-0 rounded-(--list-item-radius) border-(length:--list-item-border) bg-(--list-item-bg) [padding:var(--list-item-pad)] not-first:border-t";
+    if (error) {
+        return (_jsx(ErrorState, { title: messages.table.loadFailed(label), error: error, onRetry: onRetry, className: className }));
+    }
+    if (loading) {
+        return (_jsxs("div", { "data-slot": "list", "data-density": density, "aria-busy": true, className: cn(frame, className), children: [_jsx("p", { role: "status", className: "sr-only", children: messages.states.loading }), Array.from({ length: loadingCount }, (_, i) => (_jsxs("div", { className: cn(box, "flex items-center gap-3"), children: [_jsx(Skeleton, { className: "size-4 shrink-0" }), _jsx(Skeleton, { className: "h-4 flex-1" })] }, i)))] }));
+    }
+    if (items.length === 0) {
+        return _jsx(EmptyState, { ...empty, className: className });
+    }
+    return (_jsx("ul", { "data-slot": "list", "data-density": density, "aria-label": label, className: cn(frame, className), children: items.map((item) => (_jsx("li", { className: box, children: renderItem(item) }, getKey(item)))) }));
+}
+/**
+ * One item's content: a row in compact density (icon, title and description,
+ * then meta, status and actions on the right) and a card in cards density
+ * (the same parts stacked).
+ */
+export function ListItem({ title, href, description, icon, meta, status, actions, className, }) {
+    const { Link } = useUI();
+    return (_jsxs("div", { "data-slot": "list-item", className: cn("flex min-w-0 [flex-direction:var(--list-item-direction)] [align-items:var(--list-item-align)] gap-3", className), children: [_jsxs("div", { className: "flex min-w-0 flex-1 items-start gap-3", children: [icon && (_jsx("span", { "aria-hidden": true, className: "mt-0.5 shrink-0 text-muted-foreground [&_svg]:size-4", children: icon })), _jsxs("div", { className: "min-w-0", children: [_jsx("p", { className: "truncate text-sm font-medium", children: href ? (_jsx(Link, { href: href, className: "outline-none after:absolute after:inset-0 after:rounded-(--list-item-radius) hover:underline focus-visible:after:ring-2 focus-visible:after:ring-ring focus-visible:after:ring-inset", children: title })) : (title) }), description && (_jsx("p", { className: "mt-0.5 line-clamp-2 text-sm [overflow-wrap:anywhere] text-muted-foreground", children: description }))] })] }), (meta || status || actions) && (_jsxs("div", { className: "[margin-inline-start:var(--list-item-trail)] flex shrink-0 flex-wrap items-center gap-2", children: [meta && (_jsx("span", { className: "font-mono text-xs text-muted-foreground tabular-nums", children: meta })), status, actions && _jsx("span", { className: "relative z-10 flex items-center gap-1", children: actions })] }))] }));
+}

package/dist/data/types.d.ts

@@ -0,0 +1,92 @@
+import type * as React from "react";
+/**
+ * What a table is showing. A union rather than a bag of booleans, so the
+ * render is a total switch: every "renders nothing" bug Astrolift's audit
+ * found was a missing branch.
+ */
+export type PageState = "loading" | "error"
+/** No rows and no filter narrowing them: the list is genuinely empty. */
+ | "empty"
+/** No rows because the search or filters excluded them all. */
+ | "emptyFiltered" | "ready";
+export type SortDirection = "asc" | "desc";
+export interface SortState {
+    key: string;
+    dir: SortDirection;
+}
+export interface Column<TRow> {
+    /** Stable identity; also the React key. */
+    id: string;
+    header: React.ReactNode;
+    /** Plain-text name where a node will not do. Defaults to `header` when that is a string. */
+    label?: string;
+    cell: (row: TRow) => React.ReactNode;
+    /** A Tailwind width class (`w-32`); it also sizes the column's loading skeleton. */
+    width?: string;
+    align?: "left" | "right" | "center";
+    headClassName?: string;
+    cellClassName?: string;
+    /**
+     * The server's sort key. Present, the header is a sort control; absent, a
+     * plain header. There is no client sort: reordering one page while the rest
+     * of the result set sits on the server is wrong at every page boundary.
+     */
+    sortKey?: string;
+}
+/** Copy for a genuinely empty list: what is missing, and how to change that. */
+export interface EmptyStateSpec {
+    icon?: React.ReactNode;
+    title: string;
+    description?: string;
+    actionHref?: string;
+    actionLabel?: string;
+    learnMoreHref?: string;
+    learnMoreLabel?: string;
+}
+/**
+ * The data side of a DataTable: rows, state, paging, search and sort, with
+ * the server doing the work. The package fetches nothing, so each app
+ * implements this over its own data layer; Astrolift's `useCursorTable`
+ * (Apollo, keyset cursors, debounced server search) already satisfies it.
+ * Rules the type cannot hold: paging is server-side; the search box shows only
+ * when the query takes a search argument (`searchEnabled`); search is
+ * debounced by the controller, never per keystroke; rows from the previous
+ * question stay on screen (`isStale`, drawn with a progress line, at full
+ * contrast) until the next answer lands.
+ */
+export interface TableController<TRow> {
+    rows: readonly TRow[];
+    state: PageState;
+    error?: {
+        message: string;
+    } | null;
+    retry: () => void;
+    /** The exact count when the server knows it cheaply; null otherwise. */
+    totalCount: number | null;
+    /** 0-based index of the page on screen. */
+    pageIndex: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+    next: () => void;
+    prev: () => void;
+    pageSize: number;
+    /** The page sizes offered. Defaults to 10, 25, 50 and 100. */
+    pageSizes?: readonly number[];
+    setPageSize: (size: number) => void;
+    /** The live input value: it updates on every keystroke; the query does not. */
+    search: string;
+    setSearch: (search: string) => void;
+    searchEnabled: boolean;
+    /** The rows on screen answer a previous question (a search still debouncing, a page in flight). */
+    isStale: boolean;
+    /** One key, or the ordered keys of a multi-key sort. */
+    sort: SortState | readonly SortState[] | undefined;
+    /** `additive` is true on shift-click: add the column as the next key. */
+    toggleSort: (key: string, additive: boolean) => void;
+    sortEnabled: boolean;
+    /** True when a search or filter is narrowing the result set. */
+    isFiltered: boolean;
+    clearFilters: () => void;
+}
+export declare const PAGE_SIZES: readonly number[];
+export declare const DEFAULT_PAGE_SIZE = 25;

package/dist/data/types.js

@@ -0,0 +1,2 @@
+export const PAGE_SIZES = [10, 25, 50, 100];
+export const DEFAULT_PAGE_SIZE = 25;

package/dist/data/use-row-selection.d.ts

@@ -0,0 +1,17 @@
+export interface RowSelection {
+    selectedIds: readonly string[];
+    selectedCount: number;
+    isSelected: (id: string) => boolean;
+    toggle: (id: string) => void;
+    /** Select, or clear, every row on the current page. */
+    togglePage: (ids: readonly string[]) => void;
+    /** `true`, `false` or `"indeterminate"`, for the header box. */
+    pageSelectionState: (ids: readonly string[]) => boolean | "indeterminate";
+    clear: () => void;
+}
+/**
+ * Row selection that survives paging (Astrolift #1231): the selected ids are
+ * kept across pages, so the count in the bulk bar means what it says, while
+ * the header box answers for the page on screen only.
+ */
+export declare function useRowSelection(): RowSelection;

package/dist/data/use-row-selection.js

@@ -0,0 +1,51 @@
+"use client";
+import * as React from "react";
+/**
+ * Row selection that survives paging (Astrolift #1231): the selected ids are
+ * kept across pages, so the count in the bulk bar means what it says, while
+ * the header box answers for the page on screen only.
+ */
+export function useRowSelection() {
+    const [selected, setSelected] = React.useState(() => new Set());
+    const toggle = React.useCallback((id) => {
+        setSelected((previous) => {
+            const next = new Set(previous);
+            if (!next.delete(id))
+                next.add(id);
+            return next;
+        });
+    }, []);
+    const togglePage = React.useCallback((ids) => {
+        setSelected((previous) => {
+            const next = new Set(previous);
+            const allOn = ids.length > 0 && ids.every((id) => next.has(id));
+            for (const id of ids) {
+                if (allOn)
+                    next.delete(id);
+                else
+                    next.add(id);
+            }
+            return next;
+        });
+    }, []);
+    const pageSelectionState = React.useCallback((ids) => {
+        if (ids.length === 0)
+            return false;
+        const on = ids.filter((id) => selected.has(id)).length;
+        if (on === 0)
+            return false;
+        return on === ids.length ? true : "indeterminate";
+    }, [selected]);
+    const isSelected = React.useCallback((id) => selected.has(id), [selected]);
+    const clear = React.useCallback(() => setSelected(new Set()), []);
+    const selectedIds = React.useMemo(() => [...selected], [selected]);
+    return {
+        selectedIds,
+        selectedCount: selected.size,
+        isSelected,
+        toggle,
+        togglePage,
+        pageSelectionState,
+        clear,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @calliopelabs/ui: the Calliope AI operator UI, shared by Astrolift AI and
+ * Zentinelle AI. Styles: `@import "@calliopelabs/ui/preset.css"` after Tailwind.
+ */
+export { UIProvider, useUI, type LinkComponent, type LinkProps, type UIProviderProps, } from "./provider/UIProvider.js";
+export { defaultMessages, mergeMessages, type MessageOverrides, type Messages, } from "./provider/messages.js";
+export { cn } from "./lib/cn.js";
+export { ACCENTS, ACCENT_KEYS, DENSITIES, DENSITY_KEYS, GROUNDS, GROUND_KEYS, MODE_TOKENS, SURFACES, type AccentSpec, type Density, type FamilyAccent, type Ground, type Mode, type StatusName, } from "./theme/tokens.js";
+export { MIN_NON_TEXT_CONTRAST, MIN_TEXT_CONTRAST, contrastRatio, luminance, } from "./theme/contrast.js";
+export { CORNERS, defineProduct, type BrandAccent, type Corners, type Product, type ProductAccent, type ProductConfig, type ProductTheme, } from "./appearance/product.js";
+export { astroliftBrand, zentinelleBrand } from "./appearance/brands.js";
+export { accentContrast, appearanceFromServer, applyAppearance, clearAppearance, inkFor, isCustomAccent, modeFor, normalize, normalizePartial, parseCustomAccent, readAppearance, resolveAppearance, writeAppearance, type Appearance, type CustomAccent, type OrgAppearancePolicy, type ResolvedAppearance, } from "./appearance/appearance.js";
+export { appearanceScript, productStyles } from "./appearance/boot.js";
+export { AppearanceScript, type AppearanceScriptProps } from "./appearance/AppearanceScript.js";
+export { AppearanceProvider, useAppearance, useDensity, useProduct, type AppearanceContextValue, type AppearanceProviderProps, } from "./appearance/AppearanceProvider.js";
+export { AppearancePicker } from "./appearance/AppearancePicker.js";
+export { activeFor, areaSwitcher, localizeNav, visibleNav, type CrumbSwitchOption, type NavActive, type NavArea, type NavFunction, type NavGroup, type NavIcon, type NavModel, } from "./nav/model.js";
+export { Nav, type NavProps } from "./nav/Nav.js";
+export { AppShell, type AppShellProps } from "./shell/AppShell.js";
+export { Sidebar, type SidebarProps } from "./shell/Sidebar.js";
+export { BrandMark, type BrandMarkProps } from "./shell/BrandMark.js";
+export { UserMenu, type UserMenuItem, type UserMenuProps } from "./shell/UserMenu.js";
+export { RailPanel, type RailPanelProps } from "./shell/RailPanel.js";
+export { RailTree, type RailTreeGroup, type RailTreeItem, type RailTreeProps, } from "./shell/RailTree.js";
+export { useRailState, useRailWidth } from "./shell/rail-state.js";
+export { PageFrame, type PageFrameProps } from "./page/PageFrame.js";
+export { PageHeader, type PageHeaderProps } from "./page/PageHeader.js";
+export { Breadcrumbs, type BreadcrumbsProps, type Crumb } from "./page/Breadcrumbs.js";
+export { TabNav, type TabNavItem, type TabNavProps } from "./page/TabNav.js";
+export { Section, type SectionProps } from "./page/Section.js";
+export { DataTable, type DataTableProps } from "./data/DataTable.js";
+export { List, ListItem, type ListItemProps, type ListProps } from "./data/List.js";
+export { useRowSelection, type RowSelection } from "./data/use-row-selection.js";
+export { DEFAULT_PAGE_SIZE, PAGE_SIZES, type Column, type EmptyStateSpec, type PageState, type SortDirection, type SortState, type TableController, } from "./data/types.js";
+export { StatusBadge, type StatusBadgeProps } from "./status/StatusBadge.js";
+export { StatusDot, type StatusDotProps } from "./status/StatusDot.js";
+export { DOT_TONE, IN_FLIGHT, PILL_TONE, STATUS_TONES, TONE_TOKEN, type StatusTone, } from "./status/tones.js";
+export { EmptyState, type EmptyStateProps } from "./states/EmptyState.js";
+export { ErrorState, type ErrorStateProps } from "./states/ErrorState.js";
+export { LoadingState, type LoadingStateProps } from "./states/LoadingState.js";
+export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, } from "./overlays/Dialog.js";
+export { Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger, } from "./overlays/Drawer.js";
+export { ConfirmDialog, type ConfirmDialogProps, type ConfirmReason, } from "./overlays/ConfirmDialog.js";
+export { Button, buttonVariants, type ButtonProps } from "./primitives/Button.js";
+export { Input } from "./primitives/Input.js";
+export { Checkbox } from "./primitives/Checkbox.js";
+export { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, } from "./primitives/DropdownMenu.js";
+export { Popover, PopoverContent, PopoverTrigger } from "./primitives/Popover.js";
+export { Tabs, TabsContent, TabsList, TabsTrigger } from "./primitives/Tabs.js";
+export { Skeleton } from "./primitives/Skeleton.js";