@calliopelabs/ui 0.0.0-stage → 0.3.1

package/dist/appearance/brands.js

@@ -0,0 +1,150 @@
+/**
+ * The two consoles' brands, kept here so both apps and the catalog read the
+ * same values. An app adds its navigation:
+ *
+ *   export const astrolift = defineProduct({ ...astroliftBrand, nav: NAV });
+ */
+/**
+ * Astrolift AI: leaf green on the deep planet green sidebar. Graphite is the
+ * shipped dark ground (Astrolift #2286), with mist for people whose system
+ * runs light. The named themes are Astrolift's picker presets.
+ */
+export const astroliftBrand = {
+    id: "astrolift",
+    name: "Astrolift AI",
+    accent: "green",
+    sidebar: "#04231a",
+    grounds: ["black", "charcoal", "graphite", "emerald", "paper", "mist"],
+    defaultGround: { dark: "graphite", light: "mist" },
+    themes: [
+        { id: "orbit", name: "Orbit", hint: "Black · green", ground: "black", accent: "green" },
+        { id: "forge", name: "Forge", hint: "Black · copper", ground: "black", accent: "copper" },
+        { id: "console", name: "Console", hint: "Charcoal · ice", ground: "charcoal", accent: "ice" },
+        {
+            id: "dusk",
+            name: "Dusk",
+            hint: "Charcoal · periwinkle",
+            ground: "charcoal",
+            accent: "periwinkle",
+        },
+        {
+            id: "graphite",
+            name: "Graphite",
+            hint: "Graphite · green",
+            ground: "graphite",
+            accent: "green",
+        },
+        { id: "field", name: "Field", hint: "Emerald · green", ground: "emerald", accent: "green" },
+        { id: "daylight", name: "Daylight", hint: "Mist · green", ground: "mist", accent: "green" },
+        { id: "workshop", name: "Workshop", hint: "Paper · copper", ground: "paper", accent: "copper" },
+    ],
+};
+/**
+ * Zentinelle AI: teal on the navy sidebar, on a true black ground
+ * (ui-overhaul-ia §5). The family accents stay selectable beside teal. The
+ * emerald ground is Astrolift's planet green and is not offered.
+ */
+export const zentinelleBrand = {
+    id: "zentinelle",
+    name: "Zentinelle AI",
+    accent: {
+        key: "teal",
+        label: "Teal",
+        dark: "#37efed",
+        onDark: "#0b0b19",
+        light: "#0d7470",
+        onLight: "#f3fbf7",
+    },
+    sidebar: "#0b0b19",
+    grounds: ["black", "charcoal", "graphite", "paper", "mist"],
+    defaultGround: { dark: "black", light: "mist" },
+};
+/*
+ * The brands below are copied from what each product ships today, so nothing
+ * changes when an app moves onto the library. Where a product has no value
+ * the model needs (usually a light-ground accent), the nearest one that
+ * passes the contrast tests is used and marked "derived" for the designer.
+ */
+/**
+ * Calliope AI Workbench (JunoHub, the installer's default theme, the desktop
+ * splash): teal on navy. From junohub `custom.css` (--calliope-primary,
+ * --calliope-dark) and the installer's workbench theme. Dark only today.
+ */
+export const workbenchBrand = {
+    id: "workbench",
+    name: "Calliope AI Workbench",
+    accent: {
+        key: "workbench-teal",
+        label: "Workbench teal",
+        dark: "#0af0ce",
+        onDark: "#0b1120",
+        // derived: the hub has no light ground
+        light: "#0b7a69",
+        onLight: "#f3fbf7",
+    },
+    sidebar: "#0b1120",
+    grounds: ["black", "charcoal", "graphite", "paper", "mist"],
+    defaultGround: { dark: "charcoal", light: "mist" },
+};
+/**
+ * Calliope AI Chat Studio: blue, from `sql-agent-ui/src/index.css` (--brand
+ * in :root and .dark, --sidebar-background in .dark).
+ */
+export const chatStudioBrand = {
+    id: "chat-studio",
+    name: "Calliope AI Chat Studio",
+    accent: {
+        key: "studio-blue",
+        label: "Studio blue",
+        dark: "#8ab4f8",
+        onDark: "#0c0c0c",
+        light: "#1d4ed8",
+        onLight: "#ffffff",
+    },
+    sidebar: "#080808",
+    grounds: ["black", "charcoal", "graphite", "paper", "mist"],
+    defaultGround: { dark: "black", light: "paper" },
+};
+/**
+ * Calliope AI Loadr: Catppuccin blue, from `frontend/src/index.css`
+ * (--ctp-blue for Latte and Mocha, --accent-strong-fg). Sidebar is Mocha's
+ * mantle. Dark by default.
+ */
+export const loadrBrand = {
+    id: "loadr",
+    name: "Calliope AI Loadr",
+    accent: {
+        key: "loadr-blue",
+        label: "Loadr blue",
+        dark: "#89b4fa",
+        onDark: "#11111b",
+        light: "#1e66f5",
+        onLight: "#ffffff",
+    },
+    sidebar: "#181825",
+    grounds: ["black", "charcoal", "graphite", "paper", "mist"],
+    defaultGround: { dark: "charcoal", light: "paper" },
+};
+/**
+ * Cykick: cyan on near-black with square corners, from
+ * `ui/theme/native-themes.json` (primary, background, radius 0). Cykick's
+ * own plugins read tokens, not these components; the brand keeps the family
+ * values in one place.
+ */
+export const cykickBrand = {
+    id: "cykick",
+    name: "Cykick",
+    accent: {
+        key: "cykick-cyan",
+        label: "Cykick cyan",
+        dark: "#22d3ee",
+        onDark: "#07090e",
+        // derived: no light accent in native-themes.json
+        light: "#0e7490",
+        onLight: "#ffffff",
+    },
+    sidebar: "#07090e",
+    grounds: ["black", "charcoal", "graphite", "paper", "mist"],
+    defaultGround: { dark: "black", light: "mist" },
+    defaultCorners: 0,
+};

package/dist/appearance/product.d.ts

@@ -0,0 +1,89 @@
+import type { NavModel } from "../nav/model.js";
+import { type Density, type FamilyAccent, type Ground, type Mode } from "../theme/tokens.js";
+export type Corners = 0 | 2 | 4 | 10;
+export declare const CORNERS: readonly Corners[];
+/** A product's own accent, offered first in the picker (Zentinelle teal). */
+export interface BrandAccent {
+    /** Lowercase slug, stored in the preference and set as `data-accent`. */
+    key: string;
+    label: string;
+    /** The accent on dark grounds, and the ink on it. */
+    dark: string;
+    onDark: string;
+    /** The accent on light grounds, and the ink on it. */
+    light: string;
+    onLight: string;
+}
+/** A named ground and accent, so the picker offers a decision rather than two lists. */
+export interface ProductTheme {
+    id: string;
+    name: string;
+    hint: string;
+    ground: Ground;
+    accent: string;
+}
+/**
+ * Everything that makes one console look like itself: its name, its accent,
+ * its sidebar and its navigation. The family palette, the status colours and
+ * the layout are shared.
+ */
+export interface ProductConfig {
+    /** Lowercase slug: the storage namespace and `data-product` on <html>. */
+    id: string;
+    /** The full product name, as the brand mark shows it ("Astrolift AI"). */
+    name: string;
+    /** The default accent: a family accent, or the product's own. */
+    accent: FamilyAccent | BrandAccent;
+    /** The brand surface: the sidebar on dark grounds (graphite and light grounds stay neutral). */
+    sidebar: string;
+    /** The grounds offered, in picker order. All six when absent. */
+    grounds?: readonly Ground[];
+    /** The ground until someone chooses: one per mode, following the operating system. */
+    defaultGround?: {
+        dark: Ground;
+        light: Ground;
+    };
+    defaultDensity?: Density;
+    defaultCorners?: Corners;
+    themes?: readonly ProductTheme[];
+    /** The navigation model, before it is filtered by what the viewer may open. */
+    nav?: NavModel;
+}
+export interface ProductAccent {
+    key: string;
+    label: string;
+    dark: string;
+    onDark: string;
+    light: string;
+    onLight: string;
+    /** True for the product's own accent. */
+    brand: boolean;
+}
+/** A validated product config with its defaults filled in. */
+export interface Product {
+    id: string;
+    name: string;
+    sidebar: string;
+    grounds: readonly Ground[];
+    /** The product's accent first, then the family accents. */
+    accents: readonly ProductAccent[];
+    /** The product's own accent when it has one; null when it uses a family accent. */
+    brandAccent: BrandAccent | null;
+    defaults: {
+        ground: Record<Mode, Ground>;
+        accent: string;
+        density: Density;
+        corners: Corners;
+    };
+    themes: readonly ProductTheme[];
+    nav: NavModel;
+    /** localStorage key of the personal appearance preference. */
+    storageKey: string;
+}
+/**
+ * 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 declare function defineProduct(config: ProductConfig): Product;

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;