@tristan2828/ui-foundation 3.28.1 → 3.30.0

package/conventions/AGENTS.md

@@ -77,6 +77,8 @@ is right. Do not disable, skip, or work around it.
 Every data view handles: loading, empty, error, and success. Use
 `<Skeleton>`, `<Empty>`, and the error boundary — `DataTable` already does,
 and `EntityView` (one record) adds not found: a plain 404, never a retry.
+A small widget on a hub page is a `WidgetCard`, which holds all four for
+its own data, its error inside the card.
 Every screen has one Playwright test per state, forced via MSW overrides
 (`@tristan2828/ui-foundation/testing`).
 

package/conventions/docs/design-language.md

@@ -271,3 +271,74 @@ set, not a `DataTable` prop:
   shows the primitives, `DataTable` and the sidebar at each. Its checks
   measure that every step changes what it should, and that the default
   keeps today's sizes.
+
+## Widget cards (hub pages)
+
+A hub page (an app's home screen) shows a few small widgets from
+different parts of the app, usually above a grid of navigation tiles.
+Each widget is a `WidgetCard`: a titled card holding a short list,
+loading its own data. Use one when a screen samples several lists at
+once and each links on to the full list. A list someone works through
+belongs on its own screen, in a `DataTable`.
+
+```tsx
+const { data, isLoading, error, refetch } = useReadyTasksQuery() // one page of 5
+
+<div className="grid grid-cols-[repeat(auto-fill,minmax(min(100%,--spacing(72)),1fr))] gap-4">
+  <WidgetCard
+    title="Ready to start"
+    icon={ListChecksIcon}
+    link={{ to: '/tasks?status=ready', label: 'All' }}
+    isLoading={isLoading}
+    error={error}
+    onRetry={() => refetch()}
+    isEmpty={data?.items.length === 0}
+    emptyMessage="Nothing waiting"
+    skeletonRows={3}
+  >
+    <WidgetList>
+      {data?.items.map((task) => (
+        <WidgetListItem
+          key={task.id}
+          to={`/tasks/${task.id}`}
+          trailing={<Badge variant={READINESS_VARIANT[task.readiness]}>{READINESS_LABEL[task.readiness]}</Badge>}
+        >
+          {task.title}
+        </WidgetListItem>
+      ))}
+    </WidgetList>
+  </WidgetCard>
+</div>
+```
+
+- **Three to six rows.** A widget is a sample, not the list: ask the API
+  for that many (the query's page size) and put the rest behind the
+  header `link` ("All", "All doing"), which goes to the full list
+  filtered the same way. Set `skeletonRows` to the number it usually holds, so the card
+  keeps its height when the data arrives.
+- **Each widget owns its four states.** Loading is a skeleton of rows,
+  empty is one quiet line the app writes ("Nothing waiting", not "No
+  data"), and **an error stays inside the card**: the compact
+  `ErrorState` with a retry, so one failing widget never takes the page
+  down. Never let a widget's error reach the route's error boundary.
+- **The title is a heading** (`headingLevel`, h2 under the page's h1 by
+  default) and names the card's region, so the page's outline and its
+  landmarks list every widget. Give each widget on a page a different
+  title.
+- **A row is one line:** its text is a link (`to` for a route in the
+  app, `href` for an external address, which opens in a new tab with the
+  external-link mark) or plain text, cut with an ellipsis, the whole of
+  it in the link's name and its tooltip. After it, an optional `note`
+  (muted, small: "2 h ago", "holds 2") and an optional `trailing`
+  element: a tone badge (pattern 5's mapping) or a control.
+- **A control in a row is named by the row's text.** Pass `trailing` as
+  a function and put the id it gets in the control's `aria-labelledby`:
+  `trailing={(id) => <Switch aria-labelledby={id} … />}`. A switch saves
+  the way any row's switch does (`useRecordUpdate`, pattern 15).
+- **Equal widths, height from content.** Put the cards in a grid of
+  equal columns that wraps (the class above: one column on a phone, as
+  many 288px-or-wider columns as fit). Each card is as tall as its rows;
+  it doesn't stretch to its tallest neighbour.
+- Storybook's `app/WidgetCard` shows three widgets on a page and every
+  one in each state; its checks run axe and the token and glyph checks in
+  both themes and at `large`.

package/dist/components/app/app-shell-nav.d.ts

@@ -0,0 +1,34 @@
+import type { ComponentType } from 'react';
+export type NavItem = {
+    /** The route this entry links to. */
+    to: string;
+    label: string;
+    icon: ComponentType;
+    /** Active only on an exact match (use for '/'); otherwise on any sub-path too. */
+    end?: boolean;
+};
+/** A labelled group of sidebar entries: one module's pages, say. */
+export type NavSection = {
+    label: string;
+    items: readonly NavItem[];
+};
+/** One entry of `AppShell`'s `nav`: a page, or a labelled section of pages. */
+export type NavEntry = NavItem | NavSection;
+export declare function isNavSection(entry: NavEntry): entry is NavSection;
+/** A sidebar group as rendered: an optional label over its items. */
+export type NavGroup = {
+    label?: string;
+    items: readonly NavItem[];
+};
+/**
+ * The sidebar groups for a nav, in order. A flat nav (no sections) is the
+ * one "Navigation" group it always was. Otherwise each section is its own
+ * labelled group, and each run of plain items between them an unlabelled one.
+ */
+export declare function navGroups(nav: readonly NavEntry[]): NavGroup[];
+/**
+ * The `to` of the one entry to mark active: the most specific that matches.
+ * With '/tasks' and '/tasks/categories' both in the nav, '/tasks/categories/2'
+ * marks Categories only, and '/tasks/3' marks Tasks.
+ */
+export declare function activeNavTo(nav: readonly NavEntry[], pathname: string): string | undefined;

package/dist/components/app/app-shell-nav.js

@@ -0,0 +1,52 @@
+export function isNavSection(entry) {
+    return 'items' in entry;
+}
+/**
+ * The sidebar groups for a nav, in order. A flat nav (no sections) is the
+ * one "Navigation" group it always was. Otherwise each section is its own
+ * labelled group, and each run of plain items between them an unlabelled one.
+ */
+export function navGroups(nav) {
+    if (!nav.some(isNavSection))
+        return [{ label: 'Navigation', items: nav }];
+    const groups = [];
+    let run = [];
+    for (const entry of nav) {
+        if (isNavSection(entry)) {
+            if (run.length)
+                groups.push({ items: run });
+            run = [];
+            groups.push({ label: entry.label, items: entry.items });
+        }
+        else {
+            run.push(entry);
+        }
+    }
+    if (run.length)
+        groups.push({ items: run });
+    return groups;
+}
+function matches(item, pathname) {
+    if (item.end)
+        return pathname === item.to;
+    if (pathname === item.to)
+        return true;
+    // On a path-segment boundary: '/tasks' is active on '/tasks/3', not on
+    // '/tasks-archive'.
+    return pathname.startsWith(item.to.endsWith('/') ? item.to : `${item.to}/`);
+}
+/**
+ * The `to` of the one entry to mark active: the most specific that matches.
+ * With '/tasks' and '/tasks/categories' both in the nav, '/tasks/categories/2'
+ * marks Categories only, and '/tasks/3' marks Tasks.
+ */
+export function activeNavTo(nav, pathname) {
+    let best;
+    for (const entry of nav) {
+        for (const item of isNavSection(entry) ? entry.items : [entry]) {
+            if (matches(item, pathname) && (best === undefined || item.to.length > best.length))
+                best = item.to;
+        }
+    }
+    return best;
+}

package/dist/components/app/app-shell.d.ts

@@ -1,17 +1,17 @@
-import { type ComponentType, type ReactNode } from 'react';
-export type NavItem = {
-    /** The route this entry links to. */
-    to: string;
-    label: string;
-    icon: ComponentType;
-    /** Active only on an exact match (use for '/'); otherwise on any sub-path too. */
-    end?: boolean;
-};
+import { type ReactNode } from 'react';
+import { type NavEntry } from './app-shell-nav.js';
+export type { NavEntry, NavItem, NavSection } from './app-shell-nav.js';
 export type AppShellProps = {
     /** Shown at the top of the sidebar (hidden on the collapsed icon rail). */
     title: string;
-    /** The app's primary navigation, in order. */
-    nav: readonly NavItem[];
+    /**
+     * The app's primary navigation, in order: pages, and labelled sections of
+     * pages (`{ label, items }`, one per module, say). A nav with no sections
+     * is the single "Navigation" group. One entry is marked active: the most
+     * specific whose route matches, so '/tasks' and '/tasks/categories' can
+     * both be listed.
+     */
+    nav: readonly NavEntry[];
     /**
      * More sidebar groups under the primary nav — reference links, say. Built
      * from the sidebar primitives (`@tristan2828/ui-foundation/ui/sidebar`).

package/dist/components/app/app-shell.js

@@ -2,8 +2,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { LogOutIcon, MoonIcon, SunIcon } from 'lucide-react';
 import { useTheme } from 'next-themes';
 import { useEffect, useState } from 'react';
-import { NavLink, Navigate, Outlet, useLocation } from 'react-router';
+import { Link, Navigate, Outlet, useLocation } from 'react-router';
 import { useAuth } from '../../auth/use-auth.js';
+import { activeNavTo, navGroups } from './app-shell-nav.js';
 import { ErrorState } from './error-state.js';
 import { Button } from '../ui/button.js';
 import { Skeleton } from '../ui/skeleton.js';
@@ -64,12 +65,14 @@ export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true }
         const from = `${location.pathname}${location.search}${location.hash}`;
         return _jsx(Navigate, { to: "/login", replace: true, state: isLoggingOut ? undefined : { from } });
     }
-    return (_jsxs(TooltipProvider, { children: [_jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [_jsxs(SidebarGroup, { children: [_jsx(SidebarGroupLabel, { children: "Navigation" }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: nav.map(({ to, label, icon: Icon, end }) => {
-                                                            const isActive = end
-                                                                ? location.pathname === to
-                                                                : location.pathname.startsWith(to);
-                                                            return (_jsx(SidebarMenuItem, { children: _jsxs(SidebarMenuButton, { isActive: isActive, tooltip: label, render: _jsx(NavLink, { to: to, end: end }), children: [_jsx(Icon, {}), _jsx("span", { children: label })] }) }, to));
-                                                        }) }) })] }), sidebarExtra] }), _jsx(SidebarFooter, { children: _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
+    const activeTo = activeNavTo(nav, location.pathname);
+    return (_jsxs(TooltipProvider, { children: [_jsxs(SidebarProvider, { defaultOpen: storedSidebarOpen(defaultSidebarOpen), children: [_jsx(CloseMobileSidebarOnNavigate, {}), _jsx("nav", { "aria-label": "Primary", children: _jsxs(Sidebar, { collapsible: "icon", children: [_jsx(SidebarHeader, { children: _jsx("span", { className: "px-2 text-sm font-semibold text-sidebar-foreground group-data-[collapsible=icon]:hidden", children: title }) }), _jsxs(SidebarContent, { children: [navGroups(nav).map((group, groupIndex) => (_jsxs(SidebarGroup, { children: [group.label !== undefined && _jsx(SidebarGroupLabel, { children: group.label }), _jsx(SidebarGroupContent, { children: _jsx(SidebarMenu, { children: group.items.map(({ to, label, icon: Icon }) => {
+                                                            // A plain Link, not NavLink: NavLink marks every
+                                                            // matching entry current, and only the most specific
+                                                            // one should be (activeNavTo).
+                                                            const isActive = to === activeTo;
+                                                            return (_jsx(SidebarMenuItem, { children: _jsxs(SidebarMenuButton, { isActive: isActive, tooltip: label, render: _jsx(Link, { to: to, "aria-current": isActive ? 'page' : undefined }), children: [_jsx(Icon, {}), _jsx("span", { children: label })] }) }, to));
+                                                        }) }) })] }, `${groupIndex}:${group.label ?? ''}`))), sidebarExtra] }), _jsx(SidebarFooter, { children: _jsxs("div", { className: "flex items-center justify-between gap-2 px-2 group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:px-0", children: [_jsx("span", { className: "truncate type-caption text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
                                                     setIsLoggingOut(true);
                                                     // A failed request still ends the session on screen
                                                     // (AuthProvider), so this stays a deliberate logout: a

package/dist/components/app/error-state.d.ts

@@ -1,6 +1,8 @@
 import type { AppError } from '../../api/contracts.js';
-export declare function ErrorState({ error, onRetry, className, }: {
+export declare function ErrorState({ error, onRetry, size, className, }: {
     error: AppError;
     onRetry?: () => void;
+    /** `compact` inside a small container such as a WidgetCard. */
+    size?: 'default' | 'compact';
     className?: string;
 }): import("react").JSX.Element;

package/dist/components/app/error-state.js

@@ -1,11 +1,16 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 // The composite AGENTS.md's "Correct Patterns" section names directly:
 // `if (error) return <ErrorState error={error} />`. Renders an AppError —
 // never a raw response (the gateway translates every failure) —
 // using the same <Empty> primitive the "no rows" state uses, so a screen's
 // error and empty states read as one family instead of two unrelated
 // widgets.
+//
+// `compact` is the same state for a small container (a WidgetCard): less
+// padding and the icon beside the title instead of in a box above it, so
+// one failing widget reads as that widget's problem, not the page's.
 import { AlertCircleIcon } from 'lucide-react';
+import { cn } from 'cn';
 import { Button } from '../ui/button.js';
 import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle, } from '../ui/empty.js';
 const TITLE_BY_KIND = {
@@ -15,6 +20,7 @@ const TITLE_BY_KIND = {
     auth: 'Not authorized',
     validation: 'Check the form',
 };
-export function ErrorState({ error, onRetry, className, }) {
-    return (_jsxs(Empty, { className: className, "data-state": "error", children: [_jsxs(EmptyHeader, { children: [_jsx(EmptyMedia, { variant: "icon", children: _jsx(AlertCircleIcon, { className: "text-destructive" }) }), _jsx(EmptyTitle, { children: TITLE_BY_KIND[error.kind] }), _jsx(EmptyDescription, { children: error.message })] }), onRetry && (_jsx(EmptyContent, { children: _jsx(Button, { size: "sm", variant: "outline", onClick: onRetry, children: "Try again" }) }))] }));
+export function ErrorState({ error, onRetry, size = 'default', className, }) {
+    const compact = size === 'compact';
+    return (_jsxs(Empty, { className: cn(compact && 'gap-3 p-4', className), "data-state": "error", "data-size": size, children: [_jsxs(EmptyHeader, { className: cn(compact && 'gap-1'), children: [compact ? (_jsxs(EmptyTitle, { className: "flex items-center gap-1.5", children: [_jsx(AlertCircleIcon, { "aria-hidden": "true", className: "size-4 shrink-0 text-destructive-text" }), TITLE_BY_KIND[error.kind]] })) : (_jsxs(_Fragment, { children: [_jsx(EmptyMedia, { variant: "icon", children: _jsx(AlertCircleIcon, { className: "text-destructive" }) }), _jsx(EmptyTitle, { children: TITLE_BY_KIND[error.kind] })] })), _jsx(EmptyDescription, { children: error.message })] }), onRetry && (_jsx(EmptyContent, { children: _jsx(Button, { size: "sm", variant: "outline", onClick: onRetry, children: "Try again" }) }))] }));
 }

package/dist/components/app/secondary-filters.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 // A table toolbar's less-used filters behind one "Filters" button, so a
 // table with many filters still starts near the top of the page (issue
 // #93). The primary filters (search, status, whatever most visits use)
@@ -26,7 +26,7 @@ export function SecondaryFilters({ children, active, onClear, label = 'Filters'
     const isMobile = useIsMobile();
     const [open, setOpen] = useState(false);
     const count = active.length;
-    const trigger = (_jsxs(Button, { variant: "outline", "aria-label": count > 0 ? `${label}, ${count} active` : label, children: [_jsx(SlidersHorizontalIcon, { "aria-hidden": "true" }), label, count > 0 && (_jsx("span", { "aria-hidden": "true", className: "rounded-full bg-primary px-1.5 type-caption text-primary-foreground tabular-nums", children: count }))] }));
+    const trigger = (_jsxs(Button, { variant: "outline", children: [_jsx(SlidersHorizontalIcon, { "aria-hidden": "true" }), _jsxs("span", { children: [label, count > 0 && _jsx("span", { className: "text-[0px]", children: "," })] }), count > 0 && (_jsxs(_Fragment, { children: [_jsx("span", { className: "rounded-full bg-primary px-1.5 type-caption text-primary-foreground tabular-nums", children: count }), _jsx("span", { className: "sr-only", children: " active" })] }))] }));
     const footer = (_jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "ghost", size: "sm", disabled: count === 0, onClick: onClear, children: "Clear filters" }), _jsx(Button, { size: "sm", onClick: () => setOpen(false), children: "Done" })] }));
     return (_jsxs("div", { "data-slot": "secondary-filters", className: "flex flex-wrap items-center gap-2", children: [isMobile ? (_jsxs(Sheet, { open: open, onOpenChange: setOpen, children: [_jsx(SheetTrigger, { render: trigger }), _jsxs(SheetContent, { side: "bottom", className: "max-h-[85svh] overflow-y-auto", children: [_jsx(SheetHeader, { children: _jsx(SheetTitle, { children: label }) }), _jsx("div", { className: "flex flex-col gap-3 px-4 [&>*]:w-full", children: children }), _jsx(SheetFooter, { children: footer })] })] })) : (_jsxs(Popover, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverTrigger, { render: trigger }), _jsxs(PopoverContent, { align: "start", className: "w-auto min-w-64 gap-3 p-3", children: [_jsx(PopoverTitle, { children: label }), _jsx("div", { className: "flex flex-col gap-3", children: children }), footer] })] })), active.map((filter) => (_jsxs("span", { "data-slot": "secondary-filter-chip", className: "inline-flex h-7 items-center gap-0.5 rounded-md bg-muted pr-0.5 pl-2 type-caption text-foreground", children: [filter.label, _jsx(Button, { variant: "ghost", size: "icon-xs", "aria-label": `Remove filter: ${filter.label}`, onClick: filter.onRemove, children: _jsx(XIcon, { "aria-hidden": "true" }) })] }, filter.id))), count > 1 && (_jsx(Button, { variant: "ghost", size: "sm", onClick: onClear, children: "Clear filters" }))] }));
 }

package/dist/components/app/widget-card.d.ts

@@ -0,0 +1,56 @@
+import { type ReactNode } from 'react';
+import { type To } from 'react-router';
+import { type LucideIcon } from 'lucide-react';
+import type { AppError } from '../../api/contracts.js';
+export interface WidgetCardProps {
+    title: string;
+    /** A Lucide icon shown before the title. Decorative: the title names the card. */
+    icon?: LucideIcon;
+    /** The title's heading level: 2 under the page's h1 (the default), deeper under a section. */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /**
+     * A link on the right of the header to everything the widget samples:
+     * `{ to: '/tasks?status=doing', label: 'All doing' }`. Its accessible
+     * name is `label`, described by the title, so several "All" links on one
+     * page stay distinct.
+     */
+    link?: {
+        to: To;
+        label: string;
+    };
+    isLoading: boolean;
+    error?: AppError | null;
+    onRetry?: () => void;
+    /** True once loaded with nothing to show. Ignored while loading or failed. */
+    isEmpty: boolean;
+    /** The empty state's one line: "Nothing waiting". */
+    emptyMessage: string;
+    /** How many rows the loading skeleton shows: the number the widget usually holds. */
+    skeletonRows?: number;
+    children?: ReactNode;
+    className?: string;
+}
+export declare function WidgetCard({ title, icon: Icon, headingLevel, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows, children, className, }: WidgetCardProps): import("react").JSX.Element;
+/** The rows of a WidgetCard: a list with a divider between rows. */
+export declare function WidgetList({ children, className }: {
+    children: ReactNode;
+    className?: string;
+}): import("react").JSX.Element;
+export interface WidgetListItemProps {
+    /** The row's text: one line, cut with an ellipsis, the whole of it in the link's name and its tooltip. */
+    children: string;
+    /** An app route: the row is a link to it. */
+    to?: To;
+    /** An external address: the row is a link that opens in a new tab. Without `to` or `href` the row is plain text. */
+    href?: string;
+    /** A small muted note after the text: "2 h ago", "holds 2". */
+    note?: ReactNode;
+    /**
+     * What ends the row: a badge, or a control. A control needs a name: pass
+     * a function, and put the id it gets in the control's `aria-labelledby`,
+     * so the row's text names it.
+     */
+    trailing?: ReactNode | ((rowTextId: string) => ReactNode);
+    className?: string;
+}
+export declare function WidgetListItem({ children, to, href, note, trailing, className }: WidgetListItemProps): import("react").JSX.Element;

package/dist/components/app/widget-card.js

@@ -0,0 +1,57 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A small titled card on a hub page (issue #121): a few rows from one part
+// of the app, loaded on their own. It owns the four required states the
+// way DataTable and EntityView do, so every widget on a page skeletons,
+// empties and fails alike:
+//
+// - loading: `skeletonRows` rows shaped like the list's, so the card
+//   keeps its height when the data arrives;
+// - empty: one quiet line the app supplies ("Nothing waiting");
+// - error: ErrorState's compact form with a retry, inside the card, so a
+//   failing widget never takes the page down;
+// - success: the app's own children, usually a WidgetList.
+//
+// The title is a real heading (`headingLevel`, h2 by default, under the
+// page's h1) and names the card's region, so each widget is in the page's
+// outline and its landmarks. Height follows content (`self-start` in a
+// grid), so a short widget doesn't stretch to its tallest neighbour.
+//
+// WidgetList and WidgetListItem are the common body: rows with dividers,
+// each a primary link (or plain text) truncated to one line, an optional
+// muted note ("2 h ago") and an optional trailing element (a badge, a
+// switch). A trailing control is labelled by the row's text: pass a
+// function and it gets the id to put in `aria-labelledby`.
+import { useId } from 'react';
+import { Link } from 'react-router';
+import { ExternalLinkIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { ErrorState } from './error-state.js';
+import { Card, CardContent, CardHeader } from '../ui/card.js';
+import { Skeleton } from '../ui/skeleton.js';
+const HEADER_LINK_CLASS = 'shrink-0 rounded-sm type-label text-foreground underline underline-offset-4 outline-none ' +
+    'hover:decoration-2 focus-visible:ring-3 focus-visible:ring-ring/50';
+export function WidgetCard({ title, icon: Icon, headingLevel = 2, link, isLoading, error, onRetry, isEmpty, emptyMessage, skeletonRows = 3, children, className, }) {
+    const headingId = useId();
+    const Heading = `h${headingLevel}`;
+    const state = error ? 'error' : isLoading ? 'loading' : isEmpty ? 'empty' : 'success';
+    return (_jsx("section", { "aria-labelledby": headingId, "data-slot": "widget-card", "data-state": state, className: cn('min-w-0 self-start', className), children: _jsxs(Card, { children: [_jsxs(CardHeader, { className: "flex items-center justify-between gap-3", children: [_jsxs(Heading, { id: headingId, className: "flex min-w-0 items-center gap-2 type-section-title text-foreground", children: [Icon && _jsx(Icon, { "aria-hidden": "true", className: "size-4 shrink-0 text-muted-foreground" }), _jsx("span", { className: "truncate", children: title })] }), link && (_jsx(Link, { to: link.to, "aria-describedby": headingId, className: HEADER_LINK_CLASS, children: link.label }))] }), _jsx(CardContent, { "aria-busy": state === 'loading' || undefined, children: error ? (_jsx(ErrorState, { error: error, onRetry: onRetry, size: "compact" })) : state === 'loading' ? (_jsx(WidgetListSkeleton, { rows: skeletonRows })) : state === 'empty' ? (_jsx("p", { "data-state": "empty", className: "py-2 type-body text-muted-foreground", children: emptyMessage })) : (children) })] }) }));
+}
+// One row's height, shared by the skeleton and the list so the card doesn't
+// jump: py-2 around one line of type-body (or a small control).
+const ROW_CLASS = 'flex min-h-9 items-center gap-3 py-2';
+// Varied widths, so the skeleton reads as a list of titles, not a grid.
+const SKELETON_WIDTHS = ['w-3/5', 'w-2/5', 'w-1/2', 'w-2/3', 'w-1/3', 'w-3/5'];
+function WidgetListSkeleton({ rows }) {
+    return (_jsxs("div", { "data-state": "loading", className: "flex flex-col divide-y divide-border", children: [_jsx("span", { className: "sr-only", children: "Loading" }), Array.from({ length: rows }, (_, row) => (_jsxs("div", { className: ROW_CLASS, children: [_jsx(Skeleton, { className: cn('h-4', SKELETON_WIDTHS[row % SKELETON_WIDTHS.length]) }), _jsx(Skeleton, { className: "ml-auto h-4 w-12" })] }, row)))] }));
+}
+/** The rows of a WidgetCard: a list with a divider between rows. */
+export function WidgetList({ children, className }) {
+    return (_jsx("ul", { "data-slot": "widget-list", className: cn('flex flex-col divide-y divide-border', className), children: children }));
+}
+const ROW_LINK_CLASS = 'min-w-0 truncate rounded-sm font-medium text-foreground underline-offset-4 outline-none ' +
+    'hover:underline focus-visible:underline focus-visible:ring-3 focus-visible:ring-ring/50';
+export function WidgetListItem({ children, to, href, note, trailing, className }) {
+    const textId = useId();
+    const text = to !== undefined ? (_jsx(Link, { id: textId, to: to, title: children, className: ROW_LINK_CLASS, children: children })) : href !== undefined ? (_jsxs("a", { id: textId, href: href, target: "_blank", rel: "noreferrer", title: children, className: cn(ROW_LINK_CLASS, 'flex items-center gap-1'), children: [_jsx("span", { className: "truncate", children: children }), _jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "size-3 shrink-0 text-muted-foreground" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] })) : (_jsx("span", { id: textId, title: children, className: "min-w-0 truncate text-foreground", children: children }));
+    return (_jsxs("li", { "data-slot": "widget-list-item", className: cn(ROW_CLASS, 'type-body', className), children: [text, (note !== undefined || trailing !== undefined) && (_jsxs("span", { className: "ml-auto flex shrink-0 items-center gap-3", children: [note !== undefined && _jsx("span", { className: "type-caption tabular-nums text-muted-foreground", children: note }), typeof trailing === 'function' ? trailing(textId) : trailing] }))] }));
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { AppShell, type AppShellProps, type NavItem } from './components/app/app-shell.js';
+export { AppShell, type AppShellProps, type NavEntry, type NavItem, type NavSection } from './components/app/app-shell.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableProps, type DataTableWidth, type SortingState } from './components/app/data-table.js';
 export { EntityForm, type EntityFormProps } from './components/app/entity-form.js';
@@ -19,6 +19,7 @@ export { RichTextEditor, type RichTextEditorProps } from './components/app/rich-
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { SecondaryFilters, type ActiveFilter, type SecondaryFiltersProps } from './components/app/secondary-filters.js';
 export { StageCircle, type StageCircleProps, type StageCircleStage, type StageCircleTone, } from './components/app/stage-circle.js';
+export { WidgetCard, WidgetList, WidgetListItem, type WidgetCardProps, type WidgetListItemProps, } from './components/app/widget-card.js';
 export { ThemeProvider } from './components/theme-provider.js';
 export { LoginRoute, type LoginRouteProps } from './routes/login.js';
 export { RegisterRoute } from './routes/register.js';

package/dist/index.js

@@ -24,6 +24,7 @@ export { RichTextEditor } from './components/app/rich-text-editor.js';
 export { RouteErrorBoundary } from './components/app/route-error-boundary.js';
 export { SecondaryFilters } from './components/app/secondary-filters.js';
 export { StageCircle, } from './components/app/stage-circle.js';
+export { WidgetCard, WidgetList, WidgetListItem, } from './components/app/widget-card.js';
 export { ThemeProvider } from './components/theme-provider.js';
 // Screens outside the app shell
 export { LoginRoute } from './routes/login.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "3.28.1",
+  "version": "3.30.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {