@tristan2828/ui-foundation 3.2.0 → 3.3.0

package/conventions/docs/cell-patterns.md

@@ -5,10 +5,14 @@ first attempt gets wrong — **not components**: the lookup maps are always
 per-entity, and only the shape is reusable. Copy the markup into your
 `<entity>-columns.tsx`.
 
-Every pattern below was chosen for a real column, from a page of
+Patterns 1–10 were each chosen for a real column, from a page of
 alternatives ([`column-options.md`](column-options.md)), not designed in the abstract.
-A pattern that proves generic is worth raising for the foundation, so it
-ships here for every app.
+Patterns from 11 on are marked **Unproven**: written ahead of a real
+column, so no app has tested them on real data yet. Prefer a proven
+pattern when one fits. When you use an unproven one, say so in the
+entity's plan, and raise what you learned for the foundation, so the
+entry can lose its label. A pattern that proves generic is worth raising
+too, so it ships here for every app.
 
 ## The rules that apply to every cell
 
@@ -223,3 +227,102 @@ A one-to-many value (`★ 4.7 (3)` opening a per-person breakdown).
 - **Cost:** the detail can't be scanned down the column, and an average
   can't be sorted server-side without a backend change
   (`enableSorting: false`).
+
+## 11. Number or currency — *Unproven*
+
+A count, a quantity, a price.
+
+```tsx
+// Module scope: one formatter per column, not one per cell render.
+const priceFormatter = new Intl.NumberFormat(undefined, { style: 'currency', currency: 'USD' })
+
+cell: ({ getValue }) => {
+  const value = getValue<string | null>()
+  return value == null ? emptyCell : <span className="tabular-nums">{priceFormatter.format(Number(value))}</span>
+}
+```
+
+- `tabular-nums` gives every digit the same width, so values line up down
+  the column even when left-aligned.
+- **Zero is a value, not an empty cell.** Test `value == null`, never
+  falsiness, or `0` renders as an em dash.
+- An API `format: decimal` arrives as a **string**. `Number()` is exact
+  enough to display (about 15 significant digits). Never add up money in
+  floats on the client: totals come from the backend.
+- **Right-aligning isn't available yet.** `DataTable`'s `meta.align` only
+  supports `'center'`, and a right-aligned cell under a left-aligned header
+  looks broken. Stay left-aligned until a real column needs
+  `align: 'right'`, then raise it for the foundation.
+- The currency code comes from the data or the plan, never a guess. The
+  template's `USD` is the demo's.
+- **Cost:** none to speak of. It's the plain-text pattern with formatting.
+
+## 12. Boolean — *Unproven*
+
+A yes/no field.
+
+```tsx
+cell: ({ getValue }) => {
+  const value = getValue<boolean | null>()
+  if (value == null) return emptyCell
+  return value ? (
+    <span className="inline-flex items-center gap-1">
+      <CheckIcon aria-hidden="true" className="size-4 text-success-text" />
+      Yes
+    </span>
+  ) : (
+    <span className="text-muted-foreground">No</span>
+  )
+}
+```
+
+- **The word carries the value.** The check only reinforces it, so the
+  cell survives greyscale and a screen reader hears "Yes".
+- **Never a checkbox** in a read-only cell. It looks editable, and people
+  will try to click it.
+- "No" is muted, not red. False is rarely bad. If it is, the field is
+  really an enum with a verdict, and pattern 5 fits better.
+- **Nullable means three states.** `null` is the em dash, distinct from
+  "No". Check the schema before collapsing them.
+- **Cost:** a column that is mostly "Yes" is noise. If almost every row
+  shares the value, consider showing only the exception.
+
+## 13. Progress bar — *Unproven*
+
+A percentage, or a count out of a total (`7 of 12 done`).
+
+- The package doesn't ship `progress`. Install shadcn's into
+  `src/components/ui/` (`npx shadcn@<tools.shadcn> add progress`, after
+  checking its dependencies against `deps-allowlist.json`).
+- **Always print the number** beside the bar (`72%`, `7 / 12`). The bar
+  shows roughly how far; the number says exactly.
+- Fix the bar's width (`w-24`) so bars compare down the column. A bar that
+  stretches with the column compares nothing.
+- The default colour is `bg-primary`. Tone it (`bg-success`) only when the
+  value means something, like "complete", and say that in the plan.
+- Clamp to the schema's range. A value of 105% from bad data shouldn't
+  draw past the track.
+- Give each bar a row-specific `aria-label` (`${row.original.name}
+  progress`).
+- **Cost:** a bar takes far more width than the number it replaces. On a
+  wide table, the plain number from pattern 11 usually wins.
+
+## 14. Avatar and name — *Unproven*
+
+A person: an assignee or an owner.
+
+- The package doesn't ship `avatar`. Install shadcn's the same way as
+  pattern 13.
+- **Always render the fallback** (initials). Images fail, load slowly, or
+  aren't set, and the cell must still look intentional.
+- The image is decorative (`alt=""`) because the name is right beside
+  it. Otherwise a screen reader reads the name twice.
+- `size-6` keeps the row height unchanged at `compact` density
+  ([`design-language.md`](design-language.md) "Density").
+- Initials on `bg-muted text-muted-foreground`. Categorical colours
+  would make every person look like a category.
+- Avatar URLs load from wherever the API points. Use `loading="lazy"` so a
+  25-row page doesn't fetch every image up front.
+- **Cost:** a column of faces draws the eye more than any other cell. Use
+  it when *who* matters most in the row, not as decoration.
+

package/conventions/docs/design-language.md

@@ -126,3 +126,57 @@ Four things about them:
 
 If you find yourself wanting a ninth, that is usually a sign the column
 should be showing a shape or a label rather than more colours.
+
+## Typography
+
+Five 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 |
+|---|---|---|
+| `type-page-title` | the screen's one `<h1>` (a table's title, a form's title) | 18px / 600 |
+| `type-section-title` | a heading inside a screen (a form section, a card group) | 16px / 600 |
+| `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 |
+
+- **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`.
+- **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
+  unknown `text-*` class as a colour, so
+  `cn('text-page-title', 'text-foreground')` would silently drop the title.
+- A shadcn primitive keeps its own sizes (`CardTitle`, `Button`). Don't put
+  a role on one: its built-in size classes would then compete with the role.
+
+## Density
+
+Tables have three densities, set with `data-density` on **any ancestor**
+(a wrapper `<div>`, a route's layout, or `<html>` for the whole app). It is
+a token set, not a `DataTable` prop:
+
+```tsx
+<div data-density="compact">
+  <DataTable … />
+</div>
+```
+
+| `data-density` | Cell padding (vertical) | Header height | For |
+|---|---|---|---|
+| `compact` | 4px | 32px | wide tables people scan, many rows per screen |
+| *(unset)* | 8px | 40px | the default |
+| `comfortable` | 12px | 48px | short tables, or rows people read rather than scan |
+
+- Density changes padding only. Text keeps `type-body`, so compact never
+  drops below a readable size.
+- Pick **one density per screen**. Two tables at different densities side
+  by side look like a mistake.
+- Under the hood, the table primitive's cells read `--table-cell-px`,
+  `--table-cell-py` and `--table-head-height`, and the `data-density`
+  selectors in `styles/theme.css` set them. The package's Storybook check
+  measures that each step really changes the row height.
+

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

@@ -69,7 +69,7 @@ export function AppShell({ title, nav, sidebarExtra, defaultSidebarOpen = true }
                                                                 ? 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 text-xs text-sidebar-foreground/70 group-data-[collapsible=icon]:hidden", children: user.name }), _jsx(Button, { variant: "ghost", size: "icon-sm", "aria-label": "Log out", onClick: () => {
+                                                        }) }) })] }), 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);
                                                     logout().catch(() => setIsLoggingOut(false));
                                                 }, children: _jsx(LogOutIcon, {}) })] }) })] }) }), _jsxs(SidebarInset, { className: "min-w-0", children: [_jsxs("header", { className: "flex h-14 shrink-0 items-center gap-2 border-b border-border px-4", children: [_jsx(SidebarTrigger, {}), _jsx("div", { className: "flex-1" }), _jsx(ThemeToggle, {})] }), _jsx("div", { className: "flex-1 p-6", children: _jsx(Outlet, {}) })] })] }), _jsx(Toaster, { position: "top-center" })] }));

package/dist/components/app/data-table.js

@@ -163,5 +163,5 @@ export function DataTable({ columns, data, total, page, pageSize, onPageChange,
                                                         : 'none', children: header.isPlaceholder ? null : canSort ? (_jsxs("button", { type: "button", className: cn('flex items-center gap-1 text-foreground', header.column.columnDef.meta?.align === 'center' && 'w-full justify-center'), onClick: header.column.getToggleSortingHandler(), children: [flexRender(header.column.columnDef.header, header.getContext()), sortDirection === 'asc' ? (_jsx(ArrowUpIcon, { className: "size-3.5 text-muted-foreground" })) : sortDirection === 'desc' ? (_jsx(ArrowDownIcon, { className: "size-3.5 text-muted-foreground" })) : (_jsx(ArrowUpDownIcon, { className: "size-3.5 text-muted-foreground/50" }))] })) : (flexRender(header.column.columnDef.header, header.getContext())) }, header.id));
                                     }) }, headerGroup.id))) }), _jsx(TableBody, { children: table.getRowModel().rows.map((row) => (_jsx(TableRow, { className: cn((pinFirstColumn || pinLastColumn) && ROW_GROUP_CLASS), children: row.getVisibleCells().map((cell, index) => (_jsx(TableCell, { className: cn(pinFirstColumn && index === 0 && PINNED_COLUMN_CLASS, pinLastColumn &&
                                             index === row.getVisibleCells().length - 1 &&
-                                            PINNED_LAST_COLUMN_CLASS, cell.column.columnDef.meta?.align === 'center' && 'text-center'), children: flexRender(cell.column.columnDef.cell, cell.getContext()) }, cell.id))) }, row.id))) })] }), pinFirstColumn && isOverflowing && (_jsx("div", { ref: barRef, "aria-hidden": "true", tabIndex: -1, "data-slot": "bottom-scrollbar", className: "sticky bottom-0 z-20 h-4 overflow-x-auto border-t border-border bg-background", children: _jsx("div", { style: { width: scrollWidth, height: 1 } }) })), _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("p", { className: "text-sm text-muted-foreground", children: [total === 0 ? 0 : (page - 1) * pageSize + 1, '–', Math.min(page * pageSize, total), " of ", total] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Previous page", disabled: page <= 1, onClick: () => onPageChange(page - 1), children: _jsx(ChevronLeftIcon, {}) }), _jsxs("span", { className: "text-sm text-muted-foreground", children: ["Page ", page, " of ", pageCount] }), _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Next page", disabled: page >= pageCount, onClick: () => onPageChange(page + 1), children: _jsx(ChevronRightIcon, {}) })] })] })] }))] }));
+                                            PINNED_LAST_COLUMN_CLASS, cell.column.columnDef.meta?.align === 'center' && 'text-center'), children: flexRender(cell.column.columnDef.cell, cell.getContext()) }, cell.id))) }, row.id))) })] }), pinFirstColumn && isOverflowing && (_jsx("div", { ref: barRef, "aria-hidden": "true", tabIndex: -1, "data-slot": "bottom-scrollbar", className: "sticky bottom-0 z-20 h-4 overflow-x-auto border-t border-border bg-background", children: _jsx("div", { style: { width: scrollWidth, height: 1 } }) })), _jsxs("div", { className: "flex items-center justify-between", children: [_jsxs("p", { className: "type-body text-muted-foreground", children: [total === 0 ? 0 : (page - 1) * pageSize + 1, '–', Math.min(page * pageSize, total), " of ", total] }), _jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Previous page", disabled: page <= 1, onClick: () => onPageChange(page - 1), children: _jsx(ChevronLeftIcon, {}) }), _jsxs("span", { className: "type-body text-muted-foreground", children: ["Page ", page, " of ", pageCount] }), _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": "Next page", disabled: page >= pageCount, onClick: () => onPageChange(page + 1), children: _jsx(ChevronRightIcon, {}) })] })] })] }))] }));
 }

package/dist/components/app/entity-form.js

@@ -4,5 +4,5 @@ import { Button } from '../ui/button.js';
 import { FieldGroup } from '../ui/field.js';
 import { Spinner } from '../ui/spinner.js';
 export function EntityForm({ title, onSubmit, isSubmitting, submitError, submitLabel, onCancel, danger, children, }) {
-    return (_jsxs("form", { onSubmit: onSubmit, noValidate: true, className: "flex max-w-xl flex-col gap-6", children: [_jsx("h1", { className: "text-lg font-semibold text-foreground", children: title }), _jsx(FieldGroup, { children: children }), submitError && (_jsx(ErrorState, { error: submitError, className: "border border-dashed border-destructive/30" })), _jsxs("div", { className: `flex items-center gap-2 ${danger ? 'justify-between' : 'justify-end'}`, children: [danger, _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: isSubmitting, children: "Cancel" }), _jsxs(Button, { type: "submit", disabled: isSubmitting, children: [isSubmitting && _jsx(Spinner, { className: "size-4" }), submitLabel] })] })] })] }));
+    return (_jsxs("form", { onSubmit: onSubmit, noValidate: true, className: "flex max-w-xl flex-col gap-6", children: [_jsx("h1", { className: "type-page-title text-foreground", children: title }), _jsx(FieldGroup, { children: children }), submitError && (_jsx(ErrorState, { error: submitError, className: "border border-dashed border-destructive/30" })), _jsxs("div", { className: `flex items-center gap-2 ${danger ? 'justify-between' : 'justify-end'}`, children: [danger, _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: isSubmitting, children: "Cancel" }), _jsxs(Button, { type: "submit", disabled: isSubmitting, children: [isSubmitting && _jsx(Spinner, { className: "size-4" }), submitLabel] })] })] })] }));
 }

package/dist/components/ui/table.js

@@ -33,11 +33,15 @@ function TableFooter({ className, ...props }) {
 function TableRow({ className, ...props }) {
     return (_jsx("tr", { "data-slot": "table-row", className: cn("border-b transition-colors hover:bg-muted/50 has-aria-expanded:bg-muted/50 data-[state=selected]:bg-muted", className), ...props }));
 }
+// Patched (ui-foundation): padding and header height come from the
+// --table-* density tokens in styles/theme.css instead of upstream's fixed
+// h-10 / p-2, so data-density on an ancestor retunes every table. The
+// defaults equal upstream's values.
 function TableHead({ className, ...props }) {
-    return (_jsx("th", { "data-slot": "table-head", className: cn("h-10 px-2 text-left align-middle font-medium whitespace-nowrap text-foreground [&:has([role=checkbox])]:pr-0", className), ...props }));
+    return (_jsx("th", { "data-slot": "table-head", className: cn("h-(--table-head-height) px-(--table-cell-px) text-left align-middle font-medium whitespace-nowrap text-foreground [&:has([role=checkbox])]:pr-0", className), ...props }));
 }
 function TableCell({ className, ...props }) {
-    return (_jsx("td", { "data-slot": "table-cell", className: cn("p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0", className), ...props }));
+    return (_jsx("td", { "data-slot": "table-cell", className: cn("px-(--table-cell-px) py-(--table-cell-py) align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0", className), ...props }));
 }
 function TableCaption({ className, ...props }) {
     return (_jsx("caption", { "data-slot": "table-caption", className: cn("mt-4 text-sm text-muted-foreground", className), ...props }));

package/package.json

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

@@ -78,6 +78,34 @@
     --radius-4xl: calc(var(--radius) * 2.6);
 }
 
+/* Typography roles: one class sets size, line height and weight together,
+   from the --type-* tokens in theme.css. */
+@utility type-page-title {
+  font-size: var(--type-page-title-size);
+  line-height: var(--type-page-title-leading);
+  font-weight: var(--type-page-title-weight);
+}
+@utility type-section-title {
+  font-size: var(--type-section-title-size);
+  line-height: var(--type-section-title-leading);
+  font-weight: var(--type-section-title-weight);
+}
+@utility type-body {
+  font-size: var(--type-body-size);
+  line-height: var(--type-body-leading);
+  font-weight: var(--type-body-weight);
+}
+@utility type-label {
+  font-size: var(--type-label-size);
+  line-height: var(--type-label-leading);
+  font-weight: var(--type-label-weight);
+}
+@utility type-caption {
+  font-size: var(--type-caption-size);
+  line-height: var(--type-caption-leading);
+  font-weight: var(--type-caption-weight);
+}
+
 @layer base {
   * {
     @apply border-border outline-ring/50;

package/styles/theme.css

@@ -99,6 +99,41 @@
 
   --radius-base: 0.625rem;
 
+  /*
+   * Typography roles (conventions/docs/design-language.md "Typography").
+   * Each role is a size, a line height and a weight, consumed only through
+   * the type-* utilities in index.css. Named type-*, not text-*: the class
+   * merger (cn, tailwind-merge) reads an unknown text-* class as a colour,
+   * so `cn('text-page-title', 'text-foreground')` would drop the title.
+   * The values are what the package and template already used, so moving
+   * onto a role changes nothing visible.
+   */
+  --type-page-title-size: 1.125rem; /* was text-lg font-semibold */
+  --type-page-title-leading: 1.75rem;
+  --type-page-title-weight: 600;
+  --type-section-title-size: 1rem;
+  --type-section-title-leading: 1.5rem;
+  --type-section-title-weight: 600;
+  --type-body-size: 0.875rem; /* text-sm: tables, forms, most UI text */
+  --type-body-leading: 1.25rem;
+  --type-body-weight: 400;
+  --type-label-size: 0.875rem; /* column headers, field labels */
+  --type-label-leading: 1.25rem;
+  --type-label-weight: 500;
+  --type-caption-size: 0.75rem; /* counts, metadata, helper text */
+  --type-caption-leading: 1rem;
+  --type-caption-weight: 400;
+
+  /*
+   * Table density (design-language.md "Density"). The table primitive's
+   * cells read these, so density is a CSS choice, not a DataTable prop: an
+   * app sets data-density on any ancestor (a wrapper, a route, <html>).
+   * The default is what the table always had.
+   */
+  --table-cell-px: 0.5rem;
+  --table-cell-py: 0.5rem;
+  --table-head-height: 2.5rem;
+
   /* Layer 2 — semantic (light) */
   --background: var(--white);
   --foreground: var(--black);
@@ -160,6 +195,16 @@
   --sidebar-ring: var(--gray-400);
 }
 
+[data-density="compact"] {
+  --table-cell-py: 0.25rem;
+  --table-head-height: 2rem;
+}
+
+[data-density="comfortable"] {
+  --table-cell-py: 0.75rem;
+  --table-head-height: 3rem;
+}
+
 .dark {
   /* Layer 2 — semantic (dark). Only this block is remapped; Layer 1 is not. */
   --background: var(--black);