@tristan2828/ui-foundation 4.30.1 → 4.32.0

package/conventions/AGENTS.md

@@ -84,7 +84,8 @@ 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.
+its own data, its error inside the card; a hub's place (a module, with
+one live number) is a `ModuleCard` in a `ModuleStrip`, the same way.
 Every screen has one Playwright test per state, forced via MSW overrides
 (`@tristan2828/ui-foundation/testing`).
 

package/conventions/docs/add-an-entity.md

@@ -390,8 +390,11 @@ is a filled-in example while the Widgets demo is still here).
    - **A source credit** (`footer`), only when the record's data comes
      from an outside service whose terms ask for one (many free APIs
      do: a film database, a games catalogue): `<SourceCredit sources={[{
-     name, href, note }]} />`, with `note` the sentence the terms ask for,
-     word for word. Logos and their rules are the app's own.
+     name, href, note, icon }]} />`, with `note` the sentence the terms ask
+     for, word for word, and `icon` the service's mark when the app has
+     one (the same component it shows for that service elsewhere; drawn
+     before the name, which stays the link's text). Logos and their rules
+     are the app's own.
    - **Every value renders the way its table cell does**: badges, names
      of linked records, a done-count, from the shared lookups in
      `<entity>-format.ts`. Never re-derive one for the view.

package/conventions/docs/design-language.md

@@ -104,7 +104,8 @@ lower; say so in a comment.
 ## Logos and brand marks
 
 An app's own logo (`AppShell`'s `logo`) and the marks of the services it
-links to (a video site's mark on "Open on …", on a `WidgetCard` about it)
+links to (a video site's mark on "Open on …", on a `WidgetCard` about it,
+beside its name in a `SourceCredit`)
 are **icon components** (`IconComponent`): sized by a `size-*` class,
 `aria-hidden` passed through to the `<svg>`, with the same props as a
 Lucide icon, so they go wherever an icon goes. Lucide has no brand logos,
@@ -143,7 +144,8 @@ Colour them in one of two ways:
   one-colour mark there.
 
 The package's own stories show the slots with made-up marks in
-`currentColor` (`app/AppShell` With logo, `app/WidgetCard` Brand mark).
+`currentColor` (`app/AppShell` With logo, `app/WidgetCard` Brand mark,
+`app/EntityView` Notice and footer).
 
 ## Categorical colour
 
@@ -219,7 +221,7 @@ room that stays readable.
 
 ## Typography
 
-Five roles cover every screen. Each is one class that sets size, line
+Six roles cover every screen. Each is one class that sets size, line
 height and weight together, from tokens in the package's `styles/theme.css`:
 
 | Class | For | Size / weight |
@@ -229,12 +231,17 @@ height and weight together, from tokens in the package's `styles/theme.css`:
 | `type-body` | running text, table cells, form text, the pagination summary | 14px / 400 |
 | `type-label` | column headers, field labels, a small heading over a group | 14px / 500 |
 | `type-caption` | counts, metadata, helper text under a field | 12px / 400 |
+| `type-numeric` | the one live number on a card (`ModuleCard`'s count), in tabular figures | 22px / 500 |
 
 - **Use a role instead of size and weight classes,** not as well as them.
   `type-page-title` replaces `text-lg font-semibold`. Combining a role with
   `text-sm`, `font-medium` or `leading-*` makes two classes set the same
   property, and which one wins depends on the order of rules in the
   stylesheet, not on the order in `className`.
+- **`type-numeric` sets tabular figures** (`font-variant-numeric:
+  tabular-nums`), so counts line up from card to card and don't change
+  width as they tick. A number in running text or a table cell keeps its
+  row's role; add `tabular-nums` there if a column of them should align.
 - **Colour stays separate:** `type-caption text-muted-foreground`. A role
   never sets a colour, so any text token pairs with it.
 - **Why `type-*` and not `text-*`:** `cn` (tailwind-merge) treats an
@@ -292,13 +299,18 @@ set, not a `DataTable` prop:
 
 | `data-density` | Changes | Table cell padding (vertical) | Header height | For |
 |---|---|---|---|---|
-| `compact` | table rows only | 4px | 32px | wide tables people scan, many rows per screen |
+| `compact` | table rows, and a hub's cards (`WidgetCard`, `WidgetList` rows, `ModuleCard`) | 4px | 32px | wide tables people scan, many rows per screen; a dense hub |
 | *(unset)* | — | 8px | 40px | the default |
 | `comfortable` | table rows only | 12px | 48px | short tables, or rows people read rather than scan |
 | `large` | **everything**: type, spacing, control heights, icons, the sidebar, table rows | 12px | 56px | a screen read from a distance: a TV used as the desktop monitor, with a mouse and keyboard |
 
 - `compact` and `comfortable` change padding only. Text keeps
   `type-body`, so compact never drops below a readable size.
+- On a hub, `compact` takes a `WidgetCard`'s padding from 16px to 12px,
+  a `WidgetList` row from 36px to 32px (6px around its line) and a
+  `ModuleCard`'s band and body by 4px each. On a phone a compact row is
+  44px instead, its link filling that height, so it stays a finger's
+  target.
 - `large` grows the whole UI by about a quarter: body text 14 → 18px,
   controls 32 → 40px tall, icons 16 → 20px, the sidebar 256 → 320px.
   Breakpoints and `max-w-*` containers stay where they are, which is
@@ -306,7 +318,8 @@ set, not a `DataTable` prop:
   a wide screen can fall into the phone layout).
 - For `large`, set it on **`<html>`**. Menus, selects, dialogs and
   tooltips are portaled to `<body>`, so a wrapper `<div>` doesn't reach
-  them. `compact` and `comfortable` only touch tables, so a wrapper is fine.
+  them. `compact` and `comfortable` only touch tables and hub cards, so a
+  wrapper is fine.
 - Pick **one density per screen**. Two tables at different densities side
   by side look like a mistake.
 - Size things the way the package does and `large` reaches them for free:
@@ -319,9 +332,13 @@ set, not a `DataTable` prop:
   Tailwind's own scale (`--spacing`, `--text-*`, `--radius`), the `--type-*`
   roles and `--control-text-sm` (the small Button and Toggle). Each
   default is the value it always had, so a screen without `data-density`
-  doesn't change. The selectors are in `styles/theme.css`. Storybook's
+  doesn't change. The selectors are in `styles/theme.css`. A composite
+  reaches `compact` with the `density-compact:` variant (`styles/index.css`:
+  any ancestor with `data-density="compact"`), the way `WidgetCard` and
+  `ModuleCard` do; an app's own card can use it too. Storybook's
   Density toolbar shows any story at a density, and `patterns/Density`
-  shows the primitives, `DataTable` and the sidebar at each. Its checks
+  shows the primitives, `DataTable`, the sidebar and the hub cards at
+  each. Its checks
   measure that every step changes what it should, and that the default
   keeps today's sizes.
 
@@ -396,6 +413,66 @@ const { data, isLoading, error, refetch } = useReadyTasksQuery() // one page of
   one in each state; its checks run axe and the token and glyph checks in
   both themes and at `large`.
 
+## Module cards (a hub's places)
+
+Above its widgets, a hub shows the app's places: its modules, and the
+sites outside it that it links to. Each is a `ModuleCard` in a
+`ModuleStrip`: a small card that names the place, shows one live number,
+and offers one action.
+
+```tsx
+const { data, isLoading, error, refetch } = useProjectsSummaryQuery()
+
+<ModuleStrip aria-label="Places">
+  <ModuleCard
+    title="Projects"
+    icon={ListTodoIcon}
+    category={1}
+    to="/projects"
+    value={data?.openCount}
+    note="open"
+    action={{ to: '/projects?view=today', label: 'Today' }}
+    isLoading={isLoading}
+    error={error}
+    onRetry={() => refetch()}
+  />
+  <ModuleCard title="Recipes" icon={RecipesMark} category={6} href="https://recipes.example.com" note="Opens its own app" />
+</ModuleStrip>
+```
+
+- **The band names the place and links to it.** The icon takes the
+  place's categorical slot (`category`, 1–12), and the band behind the
+  icon and the name is a 10% wash of the same slot over the card, with
+  `foreground` text on it (axe measures every slot's wash in both themes).
+  Give each place the slot it has elsewhere in the app (its sidebar entry,
+  its badges), so a place is one colour everywhere. Without a `category`
+  the icon is muted and the band plain.
+- **One number, with a short note.** `value` is the one count that says
+  what's live there ("5" open, "2" due today), in `type-numeric`; `note`
+  is a few words under it. A card with no `value` shows no number, and
+  that is not an empty state: a place outside the app usually has none,
+  and its note says what it is ("Opens its own app").
+- **One action** at the foot: the thing most often done next ("Today",
+  "Start", "Add one"). It's described by the place's name, so several
+  "Open" links on one page stay distinct.
+- **A place outside the app** takes `href` instead of `to` (an action
+  can too): it opens in a new tab with the external-link mark. Its icon
+  can be the service's own mark ("Logos and brand marks" above).
+- **States are the number's.** While loading, a skeleton the number's
+  size (the note stays, it doesn't load); on an error, "Couldn't load"
+  and Retry inside the card, so one failing place never hides the
+  others. The band and the action work in every state.
+- **The strip** is a navigation landmark (`aria-label` names it) of
+  equal columns, 170px or wider, that wrap: six to eight across a
+  desktop. On a phone it's three columns of smaller tiles with no action,
+  each tile one link to its place (at least 44px tall); Retry stays its
+  own button above it. Six places make the phone's 3 × 2 grid; past
+  that, put the rest behind one tile ("More") rather than a third row.
+- Storybook's `app/ModuleCard` shows a hub with a strip and a widget,
+  every state, and both at `compact`; its checks run axe and the token and
+  glyph checks in both themes and at `large`, and measure the strip at a
+  desktop and a phone width.
+
 ## Notices
 
 A `Notice` says, across the page, a state that decides what you do with

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

@@ -0,0 +1,53 @@
+import { type ReactNode } from 'react';
+import { type To } from 'react-router';
+import type { AppError } from '../../api/contracts.js';
+import type { IconComponent } from './icon-component.js';
+/** One of the twelve categorical slots (design-language.md "Categorical colour"). */
+export type CategorySlot = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+/** Where a module card's band goes: a route in the app, or another site. */
+export type ModuleCardPlace = {
+    to: To;
+    href?: never;
+} | {
+    href: string;
+    to?: never;
+};
+/** A link on a module card: a route in the app (`to`), or another site (`href`, opens in a new tab). */
+export type ModuleCardLink = {
+    label: string;
+} & ModuleCardPlace;
+export type ModuleCardProps = ModuleCardPlace & {
+    /** The place's name, on the band. */
+    title: string;
+    /**
+     * The place's icon: a Lucide icon, or a brand mark for another site.
+     * Decorative: the title names the place.
+     */
+    icon: IconComponent;
+    /** The slot the icon and the band's wash take. Without one, the icon is muted and the band plain. */
+    category?: CategorySlot;
+    /** The live number: `5`, or a short string (`'1–10 m'`). Omitted: no number. */
+    value?: number | string;
+    /** A few words under the number: "open", "due today", "Opens its own app". */
+    note?: string;
+    /** One link at the foot of the card (hidden on a phone, where the tile is the link). */
+    action?: ModuleCardLink;
+    /** True while the number loads. */
+    isLoading?: boolean;
+    error?: AppError | null;
+    onRetry?: () => void;
+    className?: string;
+};
+export declare function ModuleCard({ title, icon: Icon, category, to, href, value, note, action, isLoading, error, onRetry, className, }: ModuleCardProps): import("react").JSX.Element;
+export interface ModuleStripProps {
+    /** Names the strip's navigation landmark: "Places". */
+    'aria-label': string;
+    /** ModuleCards, one per place. */
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * A hub's places, a ModuleCard each: equal columns of 170px or more that
+ * wrap, and three columns of tiles on a phone.
+ */
+export declare function ModuleStrip({ 'aria-label': label, children, className }: ModuleStripProps): import("react").JSX.Element;

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

@@ -0,0 +1,95 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// A place on a hub page (issue #224): one of the app's modules, or a site
+// outside it, as a small card in a strip across the top of the page.
+//
+// - The band: the place's icon, tinted with its categorical slot, and its
+//   name, on a 10% wash of the same slot over the card. The band is the
+//   link to the place (`to`, or `href` for another site, which opens in a
+//   new tab with the external-link mark).
+// - The body: one live number (`value`, in type-numeric's tabular figures)
+//   and a short `note` under it ("open", "due today"). No `value` means no
+//   number, not an empty state: a place outside the app has none.
+// - The foot: one `action` link ("Today", "Start").
+//
+// States work like WidgetCard's, for the number only: a skeleton the
+// number's size while loading, and on an error a short line and Retry
+// inside the card, so one failing place never hides the others. The band
+// and the action stay usable in every state.
+//
+// ModuleStrip lays the cards out: equal columns of 170px or more that
+// wrap (six to eight across a desktop), and on a phone three columns of
+// smaller tiles with no action, each tile a whole link (the band link's
+// target stretched over the card) at least 44px tall. Retry sits above
+// that target. data-density="compact" tightens the band and the body.
+import { Children, useId } from 'react';
+import { Link } from 'react-router';
+import { AlertCircleIcon, ExternalLinkIcon } from 'lucide-react';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Card } from '../ui/card.js';
+import { Skeleton } from '../ui/skeleton.js';
+// Whole class names per slot, so Tailwind generates them.
+const ICON_CLASS = {
+    1: 'text-category-1',
+    2: 'text-category-2',
+    3: 'text-category-3',
+    4: 'text-category-4',
+    5: 'text-category-5',
+    6: 'text-category-6',
+    7: 'text-category-7',
+    8: 'text-category-8',
+    9: 'text-category-9',
+    10: 'text-category-10',
+    11: 'text-category-11',
+    12: 'text-category-12',
+};
+// The band's wash: the slot at 10% over the card, so foreground text on
+// it keeps its contrast (axe measures it in both themes).
+const BAND_CLASS = {
+    1: 'bg-category-1/10',
+    2: 'bg-category-2/10',
+    3: 'bg-category-3/10',
+    4: 'bg-category-4/10',
+    5: 'bg-category-5/10',
+    6: 'bg-category-6/10',
+    7: 'bg-category-7/10',
+    8: 'bg-category-8/10',
+    9: 'bg-category-9/10',
+    10: 'bg-category-10/10',
+    11: 'bg-category-11/10',
+    12: 'bg-category-12/10',
+};
+// The band link. On a phone its ::after covers the whole card, so the tile
+// is one target; the focus ring moves to that ::after with it.
+const BAND_LINK_CLASS = 'group/band flex min-h-9 items-center gap-2 px-3 py-1.5 type-label text-foreground outline-none ' +
+    'focus-visible:ring-3 focus-visible:ring-inset focus-visible:ring-ring/50 ' +
+    'density-compact:min-h-8 density-compact:py-1 ' +
+    'max-sm:gap-1.5 max-sm:px-2 max-sm:after:absolute max-sm:after:inset-0 max-sm:after:rounded-xl ' +
+    'max-sm:focus-visible:ring-0 max-sm:focus-visible:after:ring-3 max-sm:focus-visible:after:ring-inset ' +
+    'max-sm:focus-visible:after:ring-ring/50';
+const ACTION_CLASS = 'flex items-center gap-1 border-t border-border px-3 py-2 type-label text-foreground underline ' +
+    'underline-offset-4 outline-none hover:decoration-2 focus-visible:ring-3 focus-visible:ring-inset ' +
+    'focus-visible:ring-ring/50 density-compact:py-1.5 max-sm:hidden';
+function NewTabMark() {
+    return (_jsxs(_Fragment, { children: [_jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "size-3.5 shrink-0 text-muted-foreground" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] }));
+}
+export function ModuleCard({ title, icon: Icon, category, to, href, value, note, action, isLoading = false, error, onRetry, className, }) {
+    const titleId = useId();
+    const bodyId = useId();
+    const state = error ? 'error' : isLoading ? 'loading' : 'success';
+    const band = (_jsxs(_Fragment, { children: [_jsx(Icon, { "aria-hidden": "true", className: cn('size-4 shrink-0', category ? ICON_CLASS[category] : 'text-muted-foreground') }), _jsx("span", { id: titleId, className: "min-w-0 flex-1 truncate underline-offset-4 group-hover/band:underline", children: title })] }));
+    const bandProps = {
+        'aria-describedby': bodyId,
+        'data-slot': 'module-card-band',
+        className: cn(BAND_LINK_CLASS, category && BAND_CLASS[category]),
+    };
+    return (_jsxs(Card, { "data-slot": "module-card", "data-state": state, className: cn('relative h-full min-w-0 gap-0 py-0', className), children: [href !== undefined ? (_jsxs("a", { href: href, target: "_blank", rel: "noreferrer", ...bandProps, children: [band, _jsx(NewTabMark, {})] })) : (_jsx(Link, { to: to, ...bandProps, children: band })), _jsxs("div", { id: bodyId, "data-slot": "module-card-body", "aria-busy": state === 'loading' || undefined, className: "flex flex-1 flex-col gap-0.5 px-3 py-2 density-compact:py-1.5 max-sm:px-2", children: [state === 'error' ? (_jsxs(_Fragment, { children: [_jsxs("p", { className: "flex items-center gap-1.5 type-body text-foreground", children: [_jsx(AlertCircleIcon, { "aria-hidden": "true", className: "size-4 shrink-0 text-destructive-text" }), _jsxs("span", { className: "min-w-0", children: ["Couldn't load", error?.message && _jsxs("span", { className: "sr-only", children: [": ", error.message] })] })] }), onRetry && (_jsx(Button, { size: "sm", variant: "outline", onClick: onRetry, "aria-describedby": titleId, className: "relative z-10 mt-1 self-start", children: "Retry" }))] })) : state === 'loading' ? (_jsxs(_Fragment, { children: [_jsx("span", { className: "sr-only", children: "Loading" }), _jsx(Skeleton, { "data-state": "loading", className: "my-0.5 h-6 w-12" })] })) : (value !== undefined && (_jsx("span", { "data-slot": "module-card-value", className: "type-numeric text-foreground", children: value }))), note && state !== 'error' && (_jsx("span", { className: "truncate type-body text-muted-foreground", title: note, children: note }))] }), action &&
+                (action.href !== undefined ? (_jsxs("a", { href: action.href, target: "_blank", rel: "noreferrer", "aria-describedby": titleId, className: ACTION_CLASS, children: [_jsx("span", { className: "truncate", children: action.label }), _jsx(NewTabMark, {})] })) : (_jsx(Link, { to: action.to, "aria-describedby": titleId, className: ACTION_CLASS, children: _jsx("span", { className: "truncate", children: action.label }) })))] }));
+}
+/**
+ * A hub's places, a ModuleCard each: equal columns of 170px or more that
+ * wrap, and three columns of tiles on a phone.
+ */
+export function ModuleStrip({ 'aria-label': label, children, className }) {
+    return (_jsx("nav", { "aria-label": label, "data-slot": "module-strip", className: className, children: _jsx("ul", { className: "grid grid-cols-3 gap-2 sm:grid-cols-[repeat(auto-fill,minmax(--spacing(42.5),1fr))]", children: Children.map(children, (child) => child && _jsx("li", { className: "min-w-0", children: child })) }) }));
+}

package/dist/components/app/source-credit.d.ts

@@ -1,3 +1,4 @@
+import type { IconComponent } from './icon-component.js';
 export type Source = {
     /** The service's name, the link's text: "TMDB". */
     name: string;
@@ -5,6 +6,12 @@ export type Source = {
     href: string;
     /** A sentence the service's terms ask for, shown after the list as written. */
     note?: string;
+    /**
+     * The service's mark, drawn before its name inside the link and hidden
+     * from screen readers: the name stays the link's text. The app's own
+     * component, the one it shows for this service elsewhere.
+     */
+    icon?: IconComponent;
 };
 export type SourceCreditProps = {
     sources: Source[];

package/dist/components/app/source-credit.js

@@ -2,8 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Credits the outside services a record's data comes from, as many free
 // APIs require on every screen showing their data ("This product uses the
 // TMDB API but is not endorsed or certified by TMDB"). EntityView's
-// `footer` is its usual home. Text and links only: a service's logo and
-// its usage rules are the app's.
+// `footer` is its usual home. A source's mark is the app's own icon
+// component (`icon`), drawn before its name; its usage rules are the app's.
 import { Fragment } from 'react';
 import { ExternalLinkIcon } from 'lucide-react';
 function joined(index, count) {
@@ -17,5 +17,5 @@ export function SourceCredit({ sources, lead = 'Data from' }) {
     if (sources.length === 0)
         return null;
     const notes = sources.flatMap((source) => (source.note ? [source.note] : []));
-    return (_jsxs("p", { "data-slot": "source-credit", className: "type-caption text-muted-foreground", children: [lead, ' ', sources.map((source, index) => (_jsxs(Fragment, { children: [joined(index, sources.length), _jsxs("a", { href: source.href, target: "_blank", rel: "noreferrer", className: "rounded-sm underline underline-offset-2 outline-none hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50", children: [source.name, _jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "ml-0.5 inline size-3 align-baseline" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] })] }, source.name))), ".", notes.map((note) => ` ${note}`).join('')] }));
+    return (_jsxs("p", { "data-slot": "source-credit", className: "type-caption text-muted-foreground", children: [lead, ' ', sources.map(({ icon: Icon, ...source }, index) => (_jsxs(Fragment, { children: [joined(index, sources.length), _jsxs("a", { href: source.href, target: "_blank", rel: "noreferrer", className: "rounded-sm underline underline-offset-2 outline-none hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50", children: [Icon && _jsx(Icon, { "aria-hidden": "true", className: "mr-1 inline size-3.5 align-text-bottom" }), source.name, _jsx(ExternalLinkIcon, { "aria-hidden": "true", className: "ml-0.5 inline size-3 align-baseline" }), _jsx("span", { className: "sr-only", children: " (opens in a new tab)" })] })] }, source.name))), ".", notes.map((note) => ` ${note}`).join('')] }));
 }

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

@@ -21,6 +21,11 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // 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`.
+//
+// Under data-density="compact" (#224) the card's padding drops to 12px and
+// a row's to 4px, for a dense hub; text stays at type-body. On a phone a
+// compact row is 44px tall and its link fills that height, so it stays a
+// finger's target.
 import { useId } from 'react';
 import { Link } from 'react-router';
 import { ExternalLinkIcon } from 'lucide-react';
@@ -34,11 +39,14 @@ export function WidgetCard({ title, icon: Icon, headingLevel = 2, link, isLoadin
     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) })] }) }));
+    return (_jsx("section", { "aria-labelledby": headingId, "data-slot": "widget-card", "data-state": state, className: cn('min-w-0 self-start', className), children: _jsxs(Card, { className: "density-compact:[--card-spacing:--spacing(3)]", 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';
+// jump: py-2 around one line of type-body (or a small control). Compact
+// is 32px (6px around the line); on a phone it's 44px, the link's own
+// padding making up the height (ROW_LINK_CLASS).
+const ROW_CLASS = 'flex min-h-9 items-center gap-3 py-2 density-compact:min-h-8 density-compact:py-1 ' +
+    'max-sm:density-compact:min-h-11 max-sm:density-compact:py-0';
 // 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 }) {
@@ -49,7 +57,8 @@ 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';
+    'hover:underline focus-visible:underline focus-visible:ring-3 focus-visible:ring-ring/50 ' +
+    'max-sm:density-compact:py-3';
 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 }));

package/dist/index.d.ts

@@ -36,6 +36,7 @@ export { ImageField, type ImageFieldProps } from './components/app/image-field.j
 export { DEFAULT_IMAGE_TYPES, type ImageUpload, type ImageUploadResult } from './lib/image-file.js';
 export { formatPlainDate, type PlainDate } from './lib/plain-date.js';
 export { ChoiceCell, LinkCell, NameCell, type ChoiceCellProps, type LinkCellProps, type NameCellProps, } from './components/app/row-edit-cells.js';
+export { ModuleCard, ModuleStrip, type CategorySlot, type ModuleCardLink, type ModuleCardPlace, type ModuleCardProps, type ModuleStripProps, } from './components/app/module-card.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';

package/dist/index.js

@@ -40,6 +40,7 @@ export { ImageField } from './components/app/image-field.js';
 export { DEFAULT_IMAGE_TYPES } from './lib/image-file.js';
 export { formatPlainDate } from './lib/plain-date.js';
 export { ChoiceCell, LinkCell, NameCell, } from './components/app/row-edit-cells.js';
+export { ModuleCard, ModuleStrip, } from './components/app/module-card.js';
 export { WidgetCard, WidgetList, WidgetListItem, } from './components/app/widget-card.js';
 export { ThemeProvider } from './components/theme-provider.js';
 // Screens outside the app shell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.30.1",
+  "version": "4.32.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": {

package/styles/index.css

@@ -16,6 +16,12 @@
 
 @custom-variant dark (&:is(.dark *));
 
+/* Compact density beyond tables (design-language.md "Density"): a
+   composite's own rows and padding tighten under data-density="compact"
+   on any ancestor, the way the table's tokens do. `density-compact:py-1`.
+   Text never shrinks under it. */
+@custom-variant density-compact (&:where([data-density="compact"], [data-density="compact"] *));
+
 @theme inline {
     --font-heading: var(--font-sans);
     --font-sans: 'Geist Variable', sans-serif;
@@ -113,6 +119,14 @@
   line-height: var(--type-caption-leading);
   font-weight: var(--type-caption-weight);
 }
+/* Counts on a hub's cards: tabular figures, so numbers line up from card
+   to card and don't shift width as they change. */
+@utility type-numeric {
+  font-size: var(--type-numeric-size);
+  line-height: var(--type-numeric-leading);
+  font-weight: var(--type-numeric-weight);
+  font-variant-numeric: tabular-nums;
+}
 @utility type-heading-1 {
   font-size: var(--type-heading-1-size);
   line-height: var(--type-heading-1-leading);

package/styles/theme.css

@@ -138,6 +138,9 @@
   --type-caption-size: 0.75rem; /* counts, metadata, helper text */
   --type-caption-leading: 1rem;
   --type-caption-weight: 400;
+  --type-numeric-size: 1.375rem; /* a count on a hub's ModuleCard, in tabular figures */
+  --type-numeric-leading: 1.75rem;
+  --type-numeric-weight: 500;
   /*
    * Headings inside written text (a record's notes: <Markdown> and the
    * rich-text editor), not the screen's own outline. Three clear steps
@@ -309,6 +312,8 @@
   --type-label-leading: 1.625rem;
   --type-caption-size: 0.9375rem;
   --type-caption-leading: 1.25rem;
+  --type-numeric-size: 1.75rem;
+  --type-numeric-leading: 2.25rem;
   --type-heading-1-size: 2.1875rem;
   --type-heading-1-leading: 2.8125rem;
   --type-heading-2-size: 1.5625rem;