@calliopelabs/ui 0.0.0-stage → 0.3.1

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, chatStudioBrand, cykickBrand, loadrBrand, workbenchBrand, 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";

package/dist/index.js

@@ -0,0 +1,61 @@
+/**
+ * @calliopelabs/ui: the Calliope AI operator UI, shared by Astrolift AI and
+ * Zentinelle AI. Styles: `@import "@calliopelabs/ui/preset.css"` after Tailwind.
+ */
+// Environment
+export { UIProvider, useUI, } from "./provider/UIProvider.js";
+export { defaultMessages, mergeMessages, } from "./provider/messages.js";
+export { cn } from "./lib/cn.js";
+// Tokens
+export { ACCENTS, ACCENT_KEYS, DENSITIES, DENSITY_KEYS, GROUNDS, GROUND_KEYS, MODE_TOKENS, SURFACES, } from "./theme/tokens.js";
+export { MIN_NON_TEXT_CONTRAST, MIN_TEXT_CONTRAST, contrastRatio, luminance, } from "./theme/contrast.js";
+// Product and appearance
+export { CORNERS, defineProduct, } from "./appearance/product.js";
+export { astroliftBrand, chatStudioBrand, cykickBrand, loadrBrand, workbenchBrand, zentinelleBrand, } from "./appearance/brands.js";
+export { accentContrast, appearanceFromServer, applyAppearance, clearAppearance, inkFor, isCustomAccent, modeFor, normalize, normalizePartial, parseCustomAccent, readAppearance, resolveAppearance, writeAppearance, } from "./appearance/appearance.js";
+export { appearanceScript, productStyles } from "./appearance/boot.js";
+export { AppearanceScript } from "./appearance/AppearanceScript.js";
+export { AppearanceProvider, useAppearance, useDensity, useProduct, } from "./appearance/AppearanceProvider.js";
+export { AppearancePicker } from "./appearance/AppearancePicker.js";
+// Navigation
+export { activeFor, areaSwitcher, localizeNav, visibleNav, } from "./nav/model.js";
+export { Nav } from "./nav/Nav.js";
+// Shell
+export { AppShell } from "./shell/AppShell.js";
+export { Sidebar } from "./shell/Sidebar.js";
+export { BrandMark } from "./shell/BrandMark.js";
+export { UserMenu } from "./shell/UserMenu.js";
+export { RailPanel } from "./shell/RailPanel.js";
+export { RailTree, } from "./shell/RailTree.js";
+export { useRailState, useRailWidth } from "./shell/rail-state.js";
+// Page
+export { PageFrame } from "./page/PageFrame.js";
+export { PageHeader } from "./page/PageHeader.js";
+export { Breadcrumbs } from "./page/Breadcrumbs.js";
+export { TabNav } from "./page/TabNav.js";
+export { Section } from "./page/Section.js";
+// Data
+export { DataTable } from "./data/DataTable.js";
+export { List, ListItem } from "./data/List.js";
+export { useRowSelection } from "./data/use-row-selection.js";
+export { DEFAULT_PAGE_SIZE, PAGE_SIZES, } from "./data/types.js";
+// Status
+export { StatusBadge } from "./status/StatusBadge.js";
+export { StatusDot } from "./status/StatusDot.js";
+export { DOT_TONE, IN_FLIGHT, PILL_TONE, STATUS_TONES, TONE_TOKEN, } from "./status/tones.js";
+// States
+export { EmptyState } from "./states/EmptyState.js";
+export { ErrorState } from "./states/ErrorState.js";
+export { LoadingState } from "./states/LoadingState.js";
+// Overlays
+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, } from "./overlays/ConfirmDialog.js";
+// Primitives
+export { Button, buttonVariants } 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";

package/dist/lib/cn.d.ts

@@ -0,0 +1,3 @@
+import { type ClassValue } from "clsx";
+/** Join class names, letting a later Tailwind utility override an earlier one. */
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/lib/cn.js

@@ -0,0 +1,6 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+/** Join class names, letting a later Tailwind utility override an earlier one. */
+export function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}

package/dist/lib/local-store.d.ts

@@ -0,0 +1,12 @@
+/**
+ * localStorage as a React external store, for per-person display
+ * preferences (appearance, rail state). Reads and writes never throw: Safari
+ * private mode and embedded webviews throw on storage access. A write that
+ * storage refuses is held for the rest of the page, so the choice still
+ * applies until reload.
+ */
+/** Dispatched on window after every write in this tab; other tabs hear `storage`. */
+export declare const LOCAL_STORE_EVENT = "calliope-ui:storage";
+export declare function readLocal(key: string): string | null;
+export declare function writeLocal(key: string, value: string | null): void;
+export declare function subscribeLocal(onChange: () => void): () => void;

package/dist/lib/local-store.js

@@ -0,0 +1,54 @@
+/**
+ * localStorage as a React external store, for per-person display
+ * preferences (appearance, rail state). Reads and writes never throw: Safari
+ * private mode and embedded webviews throw on storage access. A write that
+ * storage refuses is held for the rest of the page, so the choice still
+ * applies until reload.
+ */
+/** Dispatched on window after every write in this tab; other tabs hear `storage`. */
+export const LOCAL_STORE_EVENT = "calliope-ui:storage";
+const unsaved = new Map();
+function storage() {
+    try {
+        return typeof window === "undefined" ? null : window.localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+export function readLocal(key) {
+    if (unsaved.has(key))
+        return unsaved.get(key) ?? null;
+    try {
+        return storage()?.getItem(key) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeLocal(key, value) {
+    try {
+        const s = storage();
+        if (!s)
+            throw new Error("storage unavailable");
+        if (value === null)
+            s.removeItem(key);
+        else
+            s.setItem(key, value);
+        unsaved.delete(key);
+    }
+    catch {
+        unsaved.set(key, value);
+    }
+    if (typeof window !== "undefined") {
+        window.dispatchEvent(new CustomEvent(LOCAL_STORE_EVENT, { detail: key }));
+    }
+}
+export function subscribeLocal(onChange) {
+    window.addEventListener("storage", onChange);
+    window.addEventListener(LOCAL_STORE_EVENT, onChange);
+    return () => {
+        window.removeEventListener("storage", onChange);
+        window.removeEventListener(LOCAL_STORE_EVENT, onChange);
+    };
+}

package/dist/nav/Nav.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+import type { NavActive, NavModel } from "./model.js";
+export interface NavProps {
+    /** The model, already filtered to what the viewer may open (`visibleNav`). */
+    nav: NavModel;
+    /** The row the current page belongs to (`activeFor`). */
+    active: NavActive | null;
+    /** Icons only, with each area's functions in a flyout. */
+    collapsed?: boolean;
+    /** Called when a row is followed, so a drawer holding the nav can close. */
+    onNavigate?: () => void;
+    className?: string;
+}
+/**
+ * The areas and their functions (Astrolift spec 44 §4.1). Expanded, each area
+ * is a heading that folds, over its groups and rows; a flat area (Home,
+ * Overview) is just its rows. Collapsed, each area is an icon, and hovering,
+ * focusing or pressing it opens its rows as a flyout. The current row is the
+ * one lit row: an accent tint and a 2px accent edge.
+ */
+export declare function Nav({ nav, active, collapsed, onNavigate, className }: NavProps): React.JSX.Element;

package/dist/nav/Nav.js

@@ -0,0 +1,97 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { ChevronDownIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { Popover, PopoverContent, PopoverTrigger } from "../primitives/Popover.js";
+import { useUI } from "../provider/UIProvider.js";
+/**
+ * The areas and their functions (Astrolift spec 44 §4.1). Expanded, each area
+ * is a heading that folds, over its groups and rows; a flat area (Home,
+ * Overview) is just its rows. Collapsed, each area is an icon, and hovering,
+ * focusing or pressing it opens its rows as a flyout. The current row is the
+ * one lit row: an accent tint and a 2px accent edge.
+ */
+export function Nav({ nav, active, collapsed = false, onNavigate, className }) {
+    return (_jsx("div", { className: cn("flex flex-col", collapsed ? "items-center gap-1" : "gap-2", className), children: nav.map((area) => collapsed ? (_jsx(CollapsedArea, { area: area, active: active, onNavigate: onNavigate }, area.key)) : (_jsx(ExpandedArea, { area: area, active: active, onNavigate: onNavigate }, area.key))) }));
+}
+function FunctionLink({ fn, isActive, onNavigate, }) {
+    const { Link } = useUI();
+    const Icon = fn.icon;
+    return (_jsxs(Link, { href: fn.href, onClick: onNavigate, "aria-current": isActive ? "page" : undefined, ...fn.attributes, className: cn("flex h-8 min-w-0 items-center gap-2 rounded-lg px-2 text-sm focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", isActive
+            ? "bg-primary/15 font-medium text-sidebar-foreground shadow-[inset_2px_0_0_var(--primary)]"
+            : "text-sidebar-foreground/80 hover:bg-sidebar-accent/60 hover:text-sidebar-foreground"), children: [Icon && _jsx(Icon, { className: "size-4 shrink-0 opacity-80", "aria-hidden": true }), _jsx("span", { className: "truncate", children: fn.label })] }));
+}
+function Rows({ area, active, onNavigate, }) {
+    return (_jsx(_Fragment, { children: area.groups.map((group, i) => (_jsxs("div", { className: "flex flex-col gap-0.5", children: [group.label && (_jsx("div", { className: "px-2 pt-2 pb-1 text-2xs text-muted-foreground", children: group.label })), group.functions.map((fn) => (_jsx(FunctionLink, { fn: fn, isActive: active?.area === area.key && active.fn === fn.key, onNavigate: onNavigate }, fn.key)))] }, group.key ?? group.label ?? i))) }));
+}
+function ExpandedArea({ area, active, onNavigate, }) {
+    const [open, setOpen] = React.useState(true);
+    const regionId = React.useId();
+    if (area.flat) {
+        return (_jsx("div", { className: "flex flex-col gap-0.5", children: _jsx(Rows, { area: area, active: active, onNavigate: onNavigate }) }));
+    }
+    return (_jsxs("div", { className: "flex flex-col", children: [_jsxs("button", { type: "button", onClick: () => setOpen((o) => !o), "aria-expanded": open, "aria-controls": regionId, className: "flex h-7 w-full items-center justify-between rounded-lg px-2 text-2xs font-semibold tracking-wider text-muted-foreground uppercase hover:text-sidebar-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", children: [area.label, _jsx(ChevronDownIcon, { className: cn("size-3 transition-transform", !open && "-rotate-90"), "aria-hidden": true })] }), _jsx("div", { id: regionId, hidden: !open, className: "flex flex-col gap-0.5", children: _jsx(Rows, { area: area, active: active, onNavigate: onNavigate }) })] }));
+}
+/** How long the pointer may be away from a flyout before it closes. */
+const FLYOUT_GRACE_MS = 150;
+function CollapsedArea({ area, active, onNavigate, }) {
+    const { Link } = useUI();
+    const [open, setOpen] = React.useState(false);
+    const pointerOpened = React.useRef(false);
+    const closeTimer = React.useRef(null);
+    const isActive = active?.area === area.key;
+    const Icon = area.icon;
+    const only = area.groups.length === 1 && area.groups[0]?.functions.length === 1
+        ? area.groups[0].functions[0]
+        : null;
+    React.useEffect(() => {
+        const timer = closeTimer;
+        return () => {
+            if (timer.current)
+                clearTimeout(timer.current);
+        };
+    }, []);
+    const tile = (_jsx("span", { className: cn("flex size-8 items-center justify-center rounded-lg", isActive
+            ? "bg-primary/15 text-sidebar-foreground shadow-[inset_2px_0_0_var(--primary)]"
+            : "text-sidebar-foreground/80 hover:bg-sidebar-accent/60"), children: _jsx(Icon, { className: "size-4", "aria-hidden": true }) }));
+    // One row: the icon is that row's link, no flyout needed.
+    if (only) {
+        return (_jsx(Link, { href: only.href, onClick: onNavigate, "aria-label": area.flat ? only.label : area.label, title: area.flat ? only.label : area.label, "aria-current": isActive ? "page" : undefined, ...only.attributes, className: "flex rounded-lg focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", children: tile }));
+    }
+    const cancelClose = () => {
+        if (closeTimer.current)
+            clearTimeout(closeTimer.current);
+        closeTimer.current = null;
+    };
+    const scheduleClose = () => {
+        cancelClose();
+        closeTimer.current = setTimeout(() => setOpen(false), FLYOUT_GRACE_MS);
+    };
+    return (_jsxs(Popover, { open: open, onOpenChange: (next) => {
+            if (!next)
+                pointerOpened.current = false;
+            setOpen(next);
+        }, children: [_jsx(PopoverTrigger, { "aria-label": area.label, title: area.label, className: "flex rounded-lg focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", onPointerEnter: (event) => {
+                    if (event.pointerType !== "mouse")
+                        return;
+                    cancelClose();
+                    pointerOpened.current = true;
+                    setOpen(true);
+                }, onPointerLeave: (event) => {
+                    if (event.pointerType === "mouse")
+                        scheduleClose();
+                }, children: tile }), _jsxs(PopoverContent, { side: "right", align: "start", className: "w-56 gap-0 p-2", 
+                // Opened by hovering: leave focus where the person is. Opened from the
+                // keyboard: move it in, to the first row.
+                onOpenAutoFocus: (event) => {
+                    if (pointerOpened.current)
+                        event.preventDefault();
+                }, onPointerEnter: cancelClose, onPointerLeave: (event) => {
+                    if (event.pointerType === "mouse")
+                        scheduleClose();
+                }, children: [_jsx("div", { className: "px-2 pb-1 text-2xs font-semibold tracking-wider text-muted-foreground uppercase", children: area.label }), _jsx(Rows, { area: area, active: active, onNavigate: () => {
+                            setOpen(false);
+                            onNavigate?.();
+                        } })] })] }));
+}

package/dist/nav/model.d.ts

@@ -0,0 +1,77 @@
+import type * as React from "react";
+/**
+ * The navigation model (Astrolift spec 44 §4.1 and §4.4; Zentinelle
+ * ui-overhaul-ia §4.1): areas, optional groups inside an area, and the
+ * functions in each group. A function is one sidebar row; its tabs, views
+ * and actions live inside its pages. Pure data plus pure functions, so the
+ * sidebar, the breadcrumb switcher and the tests read the same model, and a
+ * Server Component can compute the active row.
+ */
+/** Any icon component: lucide-react's, or an app's own SVG. */
+export type NavIcon = React.ComponentType<{
+    className?: string;
+    "aria-hidden"?: boolean;
+}>;
+export interface NavFunction {
+    key: string;
+    label: string;
+    href: string;
+    icon?: NavIcon;
+    /**
+     * Capabilities that show this row; any one of them is enough. Absent means
+     * always shown. The app decides what a capability is: Astrolift passes
+     * module keys (`me.modules.<key>.canView`), Zentinelle passes roles.
+     */
+    requires?: string | readonly string[];
+    /** Other path prefixes this row owns, for pages that sit under several routes. */
+    also?: readonly string[];
+    /** Extra attributes on the row's link, such as a tour anchor (`data-tour`). */
+    attributes?: Readonly<Record<`data-${string}`, string>>;
+}
+export interface NavGroup {
+    key?: string;
+    label?: string;
+    functions: readonly NavFunction[];
+}
+export interface NavArea {
+    key: string;
+    label: string;
+    icon: NavIcon;
+    /** Render the area's functions as top-level rows, with no area heading (Home, Overview). */
+    flat?: boolean;
+    groups: readonly NavGroup[];
+}
+export type NavModel = readonly NavArea[];
+/** The row the current page belongs to. */
+export interface NavActive {
+    area: string;
+    fn: string;
+}
+/** The model with every row the viewer may not open removed, and empty groups and areas dropped. */
+export declare function visibleNav(nav: NavModel, can: (capability: string) => boolean): NavArea[];
+/**
+ * Which area and function own `pathname`: the function whose href (or `also`
+ * prefix) is the longest prefix of it, so /agents/skills/42 is Skills, not
+ * Agents. Query strings and fragments are ignored.
+ */
+export declare function activeFor(nav: NavModel, pathname: string): NavActive | null;
+export interface CrumbSwitchOption {
+    label: string;
+    href: string;
+    active?: boolean;
+}
+/**
+ * The first crumb of a page inside an area: the area's name, switching
+ * between its functions with the current one checked. Read from the model,
+ * so the sidebar and the breadcrumb always agree.
+ */
+export declare function areaSwitcher(nav: NavModel, area: string, activeFn: string): {
+    label: string;
+    switcher: CrumbSwitchOption[];
+};
+/**
+ * The model with every label passed through `translate`, for apps whose
+ * copy lives in a message catalog. `fallback` is the model's own label;
+ * return it when the catalog has no entry.
+ */
+export declare function localizeNav(nav: NavModel, translate: (kind: "area" | "group" | "function", key: string, fallback: string) => string): NavArea[];