@kennycorrea/ui 0.11.4 → 1.6.1

package/CHANGELOG.md

@@ -1,5 +1,187 @@
 # Changelog
 
+## 1.6.1 — 2026-10-23
+
+Fixes found by running the example app in a real browser at phone and desktop widths, in light and dark. Each has a test in `test/browser-fixes.test.tsx`; the cascade problems are pinned by computing the selectors' specificity.
+
+- **`Card` padding never applied** (since 0.11.4). Card rewrites a caller's `p-4` into `!p-4` so it beats Themes' own padding, but Tailwind only generates classes it finds in source, and `!p-4` is never written anywhere. `tokens.css` now lists the important padding utilities with `@source inline(...)`: every side, the common steps from 0 to 12, unprefixed and at `sm`–`xl`. **Needs Tailwind 4.1 or later.**
+- **Invalid fields had no red edge until focused.** Themes' `color="red"` only reaches the focus ring. `Input`, `Textarea`, the `Select` trigger and `DateInput` now show a red edge whenever `aria-invalid="true"`, alongside the message that carries the meaning.
+- **`DataTable`: the sticky first column ignored the row tint.** A selected or hovered row was tinted everywhere except the sticky cell, which stayed the solid panel colour. The tint is now a `--row-tint` variable, painted over the panel colour in the sticky cell. The selected tint is `--accent-a3` (was `a2`, too faint to see).
+- **`DataTable` stacked cards ran label and value together** ("CustomerCasey Diaz"). The `display: flex` for stacked cells lost to the `display: block` reset above it on specificity, so the label sat inline against the value. The same cause meant **`priority` columns never hid in the stacked layout**; both rules are now specific enough to win.
+- **`Sidebar collapsedHeader`** — new optional prop: what the header shows in the 64px rail (a logo mark), instead of the full header wrapping onto several lines. Defaults to `header`.
+- **Checked in the browser and working:** sign-in (errors, focus), the off-canvas panel (scrim, focus on its close button, closes on navigation), stacked cards, the bulk bar, the order detail page with its side column below on phones, sticky form actions with buttons sharing the width, the error summary, dark mode throughout, and the rail.
+- **Known, not changed:** the stacked layout hides the table header, so phones have per-row checkboxes but no select-all.
+
+## 1.6.0 — 2026-10-23
+
+Auth and polish (phase 6, the last, of [docs/admin-template-plan.md](docs/admin-template-plan.md)). Additive only.
+
+- **`AuthLayout`** — sign-in pages outside the shell: the page is `main`, the title its `h1`.
+  - A centred card on the canvas, with an optional `aside` panel beside it from 1024px.
+  - Below 520px the card fills the screen without a border.
+  - `toolbar` slot for a ThemeToggle or language switch.
+- **`LoginForm`**, **`SignupForm`**, **`ForgotPasswordForm`**, **`ResetPasswordForm`**:
+  - **Copy:** every visible word is a prop, since this is page copy rather than library strings.
+  - **Autocomplete:** each field has the right token (`username`, `current-password`, `new-password`, `email`, `name`), and the forms are `noValidate`.
+  - **Errors:** `errors` per field moves focus to the first one after a submit, and never in answer to errors that arrive while typing. `formError` is an alert.
+  - **Submitting:** `pending` blocks submits and shows the spinner.
+  - **Forgot password:** `sent` shows a status message that should not reveal whether an address has an account.
+  - Submit buttons are 44px.
+- **`PasswordInput`** — a show/hide toggle (`aria-pressed`, one name). `autoComplete` is required. Spellcheck and autocapitalisation are off. `FormField` gives it the red invalid state like `Input`.
+- **README** — "Admin kit: from sign-in to a form", a walkthrough of providers → sign-in → shell → list → record → form, with router wiring through `render`.
+- **Example** — [examples/admin/App.tsx](examples/admin/App.tsx) puts it all together, and `test/auth.test.tsx` drives it end to end: sign in, open a list, open a record, go back by breadcrumb, open the account form, sign out. The orders example gained an `onOpen` prop and exports its data for reuse.
+- **Strings** — `showPassword`.
+- **Not done** — the optional Playwright visual-regression job. It needs browsers in CI, which is a separate decision. Until then, real-layout behaviour (container queries, sticky bars, the off-canvas slide) is covered only by CSS-rule tests.
+
+## 1.5.0 — 2026-10-23
+
+Dates and charts (phase 5 of [docs/admin-template-plan.md](docs/admin-template-plan.md)). Additive only; no new dependencies.
+
+- **Date utilities** (`utils/dates`) — calendar dates as ISO `YYYY-MM-DD` strings, with arithmetic in UTC so nothing shifts across time zones or DST.
+  - **Functions:** `parseIsoDate`, `isIsoDate`, `toIsoDate`, `daysInMonth`, `addDays`, `addMonths` (clamps the day), `weekdayOf`, `startOfMonth` / `endOfMonth`, `startOfWeek` / `endOfWeek`, `isSameMonth`, `clampDate`, `isInRange`, `monthGrid` (always 6×7), `todayIso` (local), `firstDayOfWeek` (CLDR via `Intl.Locale`, ISO Monday fallback), `formatIsoDate`, `formatDateRange`, `weekdayNames`.
+  - **Types:** `IsoDate`, `DateRange`, `Weekday`.
+- **`Calendar`** — the WAI-ARIA date picker grid.
+  - **Keyboard:** one Tab stop; arrows, Home/End, PageUp/PageDown, Shift for a year; focus follows into the next month.
+  - **Labels:** days are named with the full date, and today is `aria-current="date"`; the month heading is a polite live region.
+  - **Selection:** `mode="range"` takes two clicks in either order.
+  - **Limits:** `min`, `max` and `isDateDisabled` (those dates stay focusable and are never chosen); `weekStartsOn`; `numberOfMonths`.
+- **`DateInput`** — a button showing the date, opening a Calendar in a popover, or a Sheet below `sheetBelow`.
+  - The chosen date is the button's description, so a `FormField` label stays its name.
+  - `native` uses `<input type="date">`.
+- **`DateRangePicker`** — two months with presets, or one month with preset chips in a sheet. It commits on the second date or a preset, and Escape leaves the value alone.
+- **Charts** — `BarChart` (grouped/stacked), `LineChart` (gaps break the line), `DonutChart` (legend with value and share) and `Sparkline`, in plain SVG sized to the container (`useElementWidth`).
+  - Each is a single `role="img"` named by a required `label` sentence.
+  - Series are distinguished by pattern or marker shape as well as colour, repeated in `ChartLegend`.
+  - Also exported: `niceTicks`, `chartTable`, `donutTable`.
+- **`ChartFrame`** — a Card section named by its heading, with a "View as table" toggle (`aria-pressed`) showing the same data as a captioned table. Works around any chart.
+- **Tokens** — `--chart-1`…`--chart-8` (blue, orange, jade, violet, crimson, cyan, gold, pink), each ≥ 3:1 against the panel in light and dark (WCAG 1.4.11), checked in `test/charts.test.tsx`. Amber, yellow, lime, mint and sky are excluded for failing it.
+- **`DashboardPage`** and **`DashboardWidget`** — a container-query grid: 1 column, 2 from 640px, `columns` (3 or 4) from 1024px; widgets can span 2 or the full row.
+- **Hooks** — `useElementWidth`.
+- **Strings** — `previousMonth`, `nextMonth`, `chooseDate`, `chooseDates`, `datePresets`, `viewAsTable`, `viewAsChart`.
+- **Differences from the plan:**
+  - `Calendar` is a molecule, not an organism, so that `DateInput` (a molecule) can use it without breaking the layer rule.
+  - `CommandMenu`, marked optional, is not built.
+  - In a `StatTile`, a `Sparkline` stays decorative, as the tile already hid its slot.
+- **Example** — [examples/admin/Dashboard.tsx](examples/admin/Dashboard.tsx).
+- **Tests** — `test/dates.test.tsx` covers date math (leap years, DST weeks, month clamping, six locales' week starts and formatting), calendar keyboard and range behaviour, and both picker layouts. `test/charts.test.tsx` covers ticks, rendering, tables, palette contrast in both appearances, and axe on the frame and the example.
+
+## 1.4.0 — 2026-10-23
+
+Forms and filters (phase 4 of [docs/admin-template-plan.md](docs/admin-template-plan.md)).
+
+- **`FormField`** — label, hint, error, `required` and invalid state wired into one control (`id`, `aria-describedby`, `required`).
+  - `Input`, `Textarea` and `Select` get `invalid`, which gives them their red state.
+  - Any other control gets `aria-invalid`, or the ids through a render function.
+  - `layout="inline"` for checkboxes and switches.
+  - Errors are text with an icon, never colour alone.
+- **`FormFieldset`** — a `fieldset` and legend, with hint and error describing the group.
+- **`ErrorSummary`** — after a failed submit it takes focus (whenever `submitCount` changes and there are errors).
+  - It is a region named by its heading ("There are 4 problems with this form").
+  - Each link moves focus into its field.
+- **`FormSection`** (fields beside the title from 720px of its own width), **`FormActions`** (sticky at the bottom below 768px, buttons sharing the width), **`FormPage`** (a `form` with `noValidate`, default prevented).
+- **`SearchField`** — magnifier, clear button, Escape to clear, `debounceMs`, and a page-wide `shortcut` key.
+  - The shortcut is ignored while typing elsewhere and its hint is hidden on touch.
+  - `aria-keyshortcuts` is set.
+- **`FilterPopover`** — a "Filters" button with an active count (read as "2 active"). It opens a popover, or a bottom Sheet below `sheetBelow`.
+  - With `onApply` the controls are a draft; `onReset` adds a Reset button.
+- **`FilterChips`** — `ChipGroup` with a clear-all while anything is selected.
+- **`FilterBar`** — search, filters and actions in one row; the search takes its own row below 640px. Active filters show as a named list of removable `Pill`s, with clear-all.
+- **`SettingsPage`** — one named `nav`: a sticky section list from 768px of page width, a select below it.
+- **`AppShell`** sets `data-tabbar` while its TabBar shows, and `tokens.css` turns that into `--bottom-bar-offset`.
+  - **Behaviour change in `BulkActionBar`:** it used to lift itself by the TabBar height on every screen under 1024px. Now it uses `--bottom-bar-offset`, so it lifts only when the TabBar is actually showing. `FormActions` uses the same offset.
+- **Strings** — `search`, `clearSearch`, `filters`, `apply`, `reset`, `clearFilters`, `activeFilters`, `activeCount`, `fixErrors`.
+- **Example** — [examples/admin/AccountForm.tsx](examples/admin/AccountForm.tsx): a validated form with an error summary.
+- **Tests** — `test/forms.test.tsx` covers wiring, focus management, debouncing, the shortcut key, popover against sheet, the CSS rules, and axe on the example form with errors showing and on `SettingsPage`.
+
+## 1.3.0 — 2026-10-23
+
+Data display (phase 3 of [docs/admin-template-plan.md](docs/admin-template-plan.md)). Additive only.
+
+- **`DataTable`** — controlled sort, selection, row actions, row click, `loading` / `empty` / `error` states and pagination.
+  - **Columns:** `id`, `header`, `cell`, `sortValue`, `sortable`, `align`, `width`, `priority`, `isRowHeader`, `mobileLabel`.
+  - **Responsive** to its own width (container queries): `priority: 'low'` hides below 640px, `'medium'` below 480px, and below `stackBelow` (`sm` 480 / `md` 640 default / `lg` 800 / `false`) rows become labelled cards.
+  - **Explicit table roles** on every part, so the stacked layout's `display: block` cannot strip the table semantics.
+  - **Keyboard:** a scrollable, named region that is a tab stop; `aria-sort` on sorted headers; sort cycles ascending → descending → off.
+  - **Selection:** select-all on the current page with an indeterminate state, and row checkboxes named after the row.
+  - **Row actions:** each row's actions menu is named after the row.
+  - **Row click:** with `onRowClick`, the row-header cell becomes a button for keyboard users, and clicks on the row's own controls are ignored.
+  - **Options:** `stickyFirstColumn`, `maxHeight` (sticky header), `density`.
+- **`useClientTable`** and **`sortRows`** — in-browser sorting (`Intl.Collator`, numeric, in the provider's locale; empty values last both ways; stable) and paging, with the page clamped.
+- **`Pagination`** and **`paginationRange`** — controlled; `total`/`pageSize` or `pageCount`.
+  - Shows a "1–25 of 500" range and an optional labelled rows-per-page select.
+  - Numbered pages, or "Page 2 of 10" below 520px of its own width.
+  - Short runs show every page.
+- **`BulkActionBar`** — a Radix Toolbar shown while anything is selected, sticky above the TabBar on small screens; the count is in a polite live region.
+- **States** — `EmptyState`, `ErrorState` (`role="alert"`, retry, details) and `LoadingState` (`spinner` / `rows` / `cards`, announced once).
+- **`StatGroup`**, **`KeyValueList`**, **`StatusIndicator`**, **`Pill`**.
+- **Templates** — `ListPage`, `DetailPage` (aside beside the main content from 960px of page width, always after it in the DOM, a named `complementary` landmark), `StatusPage`.
+- **Strings** — `remove`, `noResults`, `somethingWentWrong`, `retry`, `showDetails`, `pagination`, `previousPage`, `nextPage`, `rowsPerPage`, `goToPage`, `pageOf`, `rangeOf`, `selectAll`, `selectRow`, `actionsFor`, `bulkActions`, `selectedCount`, `clearSelection`. Those that carry a value are functions.
+- **Differences from the plan:**
+  - Column `header` is a string, because it is also the sort button's name and the stacked label.
+  - `density` is one value, not per-breakpoint.
+- **Example** — [examples/admin/Orders.tsx](examples/admin/Orders.tsx): 500 rows that sort, page, select and stack.
+- **Tests** — `test/data.test.tsx` covers pagination ranges, sorting edge cases, table behaviour, axe in four table states, the CSS thresholds, and the 500-row example end to end.
+
+## 1.2.0 — 2026-10-23
+
+The admin shell and navigation (phase 2 of [docs/admin-template-plan.md](docs/admin-template-plan.md)). Additive only.
+
+- **Templates** — `AdminLayout`: an `AppShell` with the page header and content in one column capped at `--content-max-width` (`width="full"` removes the cap).
+- **Organisms**
+  - `AppShell`: sidebar + topbar + `<main>`, with a skip link.
+    - From `breakpoint` (default `md`, 1024px) it is a two-column grid with a sticky sidebar.
+    - Below that it is one column, with the sidebar off-canvas and an optional bottom `TabBar` (`mobileNav`).
+    - Widening the window with the panel open closes the panel.
+  - `Sidebar`: sections of `NavItem`s.
+    - On wide screens it is a persistent column that collapses to an icon rail (`collapsed` / `defaultCollapsed` / `onCollapsedChange`).
+    - On narrow screens it is a Radix Dialog panel from the start edge, with a scrim, focus trap and Escape. It closes when an item is chosen.
+    - It also works outside an `AppShell` (`breakpoint`, `open`, `onOpenChange`).
+  - `Topbar`: a sticky `header`.
+    - Inside a shell, a menu button opens the off-canvas sidebar.
+    - The search moves to its own row below 768px.
+  - `PageHeader`: breadcrumbs, the `h1`, a description, `meta`, a primary action and secondary actions.
+    - The secondary actions are ghost buttons when the header is 640px or wider, and a "more" menu below that (a container query).
+  - `PageTabs`: sub-page navigation as a `nav` of links with `aria-current`, scrolling sideways when crowded.
+- **Molecules**
+  - `NavItem`: a link, button or one-level group. It carries a badge, with `badgeLabel` for screen readers.
+  - `Breadcrumbs`: folds the middle into a menu past `maxItems`, and shows only the parent as a back link below 768px.
+  - `UserMenu`: avatar + name opening an `ActionMenu`. The name stays in the accessible name on mobile.
+  - `ThemeToggle` and `AccentPicker`: read and store through a `createTheming` instance; the app applies the choice.
+- **Atoms**
+  - `ActionMenu`: a dropdown menu that becomes an `ActionSheet` below `sheetBelow` (default `sm`; `false` keeps the menu).
+  - `TextLink`: the theme's link style, router-agnostic, with `external`.
+  - Both are named to avoid shadowing the `DropdownMenu` and `Link` primitives.
+- **Routing** — every navigating component takes `href` + `render(props)`, with one shared `LinkRenderProps` / `RenderLink` type.
+- **Strings** — `skipToContent`, `mainNavigation`, `openNavigation`, `closeNavigation`, `collapseSidebar`, `expandSidebar`, `breadcrumbs`, `showMoreBreadcrumbs`, `opensInNewTab`, `userMenu`, `appearance`, `light`, `dark`, `system`, `accent`. English defaults; type dictionaries as `Partial<UiStrings>`.
+- **CSS** — `.ui-shell`, `.ui-sidebar*`, `.ui-nav-item*`, `.ui-topbar*`, `.ui-breadcrumbs*`, `.ui-page-header*`, `.ui-page-tabs*`, `.ui-user-menu*`, `.ui-accent-picker*`, `.ui-admin-content` and a `.ui-sr-only` utility in `tokens.css`.
+  - The shell uses `100dvh`.
+  - Touch targets are 44px on coarse pointers.
+  - Motion is off under `prefers-reduced-motion`.
+  - The off-canvas panel slides from the correct side in RTL.
+- **Example** — [examples/admin/Shell.tsx](examples/admin/Shell.tsx).
+- **Tests** — `test/shell.test.tsx` covers behaviour, wide and narrow viewports, server rendering, axe on the shell (both widths), Breadcrumbs and AccentPicker, and the CSS rules above. Shared viewport mock in `test/viewport.ts`.
+
+## 1.1.0 — 2026-10-23
+
+Foundations for the admin kit (phase 1 of [docs/admin-template-plan.md](docs/admin-template-plan.md)). Nothing removed, renamed or changed in default behaviour.
+
+- **Hooks** — `useMediaQuery(query, serverValue = true)`, `useBreakpoint(serverValue = 'lg')`, `useControllableState({ value, defaultValue, onChange })`. `useMediaQuery` also works without `matchMedia`: it returns `serverValue` instead of throwing.
+- **`BREAKPOINTS`** and **`minWidth(bp)`** — Radix Themes' scale (xs 520, sm 768, md 1024, lg 1280, xl 1640) as one constant for JavaScript.
+- **`ResponsiveDialog`, `ActionSheet`** — new optional `breakpoint` prop (default `sm`, the same 768px as before). Both now use `useMediaQuery` instead of their own copies.
+- **`UiStringsProvider locale`** — optional BCP 47 tag for `Intl` formatting, read with the new `useUiLocale()`. It inherits from an outer provider.
+- **Layers** — empty `molecules`, `organisms` and `templates` entry points, re-exported from the root.
+- **`Icon`** — neutral names `home`, `list`, `calendar`, `users`, `card`, `document`. The old names still work as aliases.
+- **Tokens** — `--sidebar-width`, `--sidebar-width-collapsed`, `--topbar-height`, `--content-max-width`, `--table-row-height-comfortable`, `--table-row-height-compact`. Not read by anything yet.
+- **`package.json`** — `"sideEffects": ["*.css"]`, so bundlers can drop unused exports from the root entry.
+- **Deprecated** — the free `readTheme`, `storeTheme`, `readAccent` and `storeAccent`. Use `createTheming({ storagePrefix })`. Removal is planned for 2.0.
+- **Comments, examples and test data** — reworded to be app-neutral.
+- **New tests** — `test/hooks.test.tsx`, plus `test/foundations.test.tsx`, which checks layer import boundaries, that every component folder is exported, that no export shadows a re-exported Radix primitive, and app-neutral wording. Each check was confirmed to fail when its rule is broken.
+
+## 1.0.0 — 2026-10-23
+
+- **Stable baseline.** The public API of 0.11.4 is now 1.0.0. There are no code changes, and nothing is removed or renamed.
+- **Admin template kit plan** — [docs/admin-template-plan.md](docs/admin-template-plan.md). It covers an audit of every atom on desktop and mobile, the layered breakdown (molecules, organisms, templates), ADRs, the testing strategy and a phased 1.x roadmap.
+
 ## 0.11.4 — 2026-10-20
 
 - **`Card`** — Themes' unlayered `.rt-Card` padding (16px at size 2) beat the layered `p-0`, so every card was padded on top of `CardHeader`/`CardBody` (double padding; header dividers short of the edges). The zero is now `!p-0` plus an unlayered `.ui-card.rt-Card { padding: 0 }` in `tokens.css`. Padding utilities a caller passes (`p-*`, `px-*`, `md:py-*`…) are promoted to `!` so they still win.

package/README.md

@@ -64,6 +64,9 @@ export const theming = createTheming({
 theming.readAccent(); // 'teal' | 'crimson'
 ```
 
+The free `readTheme`, `storeTheme`, `readAccent` and `storeAccent` functions are deprecated:
+they are bound to a fixed legacy storage prefix. Use an instance from `createTheming` instead.
+
 Every accent you offer needs its Radix colour scale imported.
 
 ### Dark mode and portals
@@ -88,6 +91,253 @@ Components never contain literal text. The handful they need — a spinner's lab
 placeholder, close/expand/collapse names, the `ScrollStrip` region name (`scrollableRegion`) — come from `UiStringsProvider`, which takes a partial
 `UiStrings` object. Defaults are English. Most components also accept the label as a prop.
 
+Type your dictionary as `Partial<UiStrings>`: new keys are added in minor releases, with
+English defaults, and a complete `UiStrings` object would stop type-checking when they arrive.
+
+`UiStringsProvider` also takes an optional `locale` (a BCP 47 tag such as `pt-PT`). Components
+that format dates, numbers or money pass it to `Intl`; `useUiLocale()` reads it. Left out, it
+inherits from an outer provider, and with none `Intl` uses the runtime's default.
+
+## Admin kit: from sign-in to a form
+
+The kit is layered: **atoms → molecules → organisms → templates**. Templates are slot layouts:
+they place what you give them and fetch nothing, so routing, data and auth stay in your app.
+Here is a whole app, in the order a person meets it. The runnable version is
+[examples/admin/App.tsx](examples/admin/App.tsx); `test/auth.test.tsx` drives it from sign-in
+to sign-out.
+
+**1. Providers, once, at the root.** Theme from Radix; your words and locale for the kit.
+
+```tsx
+const theming = createTheming({ accents: ['indigo'], defaultAccent: 'indigo', storagePrefix: 'myapp' });
+
+<Theme accentColor={theming.readAccent()}>
+  <UiStringsProvider strings={myDictionary.ui} locale="en-GB">
+    <App />
+  </UiStringsProvider>
+</Theme>
+```
+
+**2. Sign in.** `AuthLayout` is the page; the form is one of `LoginForm`, `SignupForm`,
+`ForgotPasswordForm`, `ResetPasswordForm`. Every label is a prop, because it is page copy.
+Validation and the request are yours: pass back `errors` (focus moves to the first one after
+a submit), `formError` and `pending`.
+
+```tsx
+<AuthLayout title="Sign in" footer={<TextLink href="/signup">Create an account</TextLink>}>
+  <LoginForm
+    labels={{ form: 'Sign in', identifier: 'Email', password: 'Password', submit: 'Sign in' }}
+    forgotPassword={<TextLink href="/forgot">Forgot password?</TextLink>}
+    errors={errors} formError={formError} pending={pending}
+    onSubmit={(values) => signIn(values)}
+  />
+</AuthLayout>
+```
+
+**3. The shell.** One `AdminLayout` around every signed-in page. Give NavItems an `href` and a
+`render` for your router's link, and mark the current one `active`.
+
+```tsx
+const link: RenderLink = (p) => <RouterLink to={p.href} {...p} />;
+
+<AdminLayout
+  sidebar={<Sidebar sections={[{ items: [
+    { label: 'Orders', icon: <CubeIcon />, href: '/orders', render: link, active: path.startsWith('/orders') },
+  ] }]} />}
+  topbar={<Topbar actions={<UserMenu name={user.name} items={menu} onSelect={onMenu} />} />}
+>
+  <Outlet />
+</AdminLayout>
+```
+
+**4. A list.** `ListPage` with a `PageHeader`, a `FilterBar` and a `DataTable`. With all the
+data in the browser, `useClientTable` sorts and pages; otherwise pass your server's page.
+
+```tsx
+<ListPage
+  header={<PageHeader title="Orders" primaryAction={<Button>New order</Button>} />}
+  toolbar={<FilterBar search={<SearchField onValueChange={setQuery} debounceMs={250} />} />}
+>
+  <DataTable caption="Orders" columns={columns} rows={page.rows} getRowId={(o) => o.id}
+    sort={sort} onSortChange={setSort} onRowClick={(o) => navigate(`/orders/${o.id}`)}
+    pagination={{ page, onPageChange: setPage, total: page.total, pageSize: 25 }} />
+</ListPage>
+```
+
+**5. A record.** `DetailPage`: header with breadcrumbs and tabs, main content, a side column.
+
+```tsx
+<DetailPage
+  header={<PageHeader title={`Order #${o.number}`} breadcrumbs={[{ label: 'Orders', href: '/orders', render: link }, { label: `#${o.number}` }]} />}
+  aside={<Card><KeyValueList items={[{ label: 'Customer', value: o.customer }]} /></Card>}
+  asideLabel="Order summary"
+>
+  …
+</DetailPage>
+```
+
+**6. A form.** `FormPage` with `FormSection`s of `FormField`s, an `ErrorSummary` and
+`FormActions`, as in [Forms and filters](#forms-and-filters).
+
+**Also there for the pages in between:** `DashboardPage` with `ChartFrame`s, `SettingsPage`,
+and `StatusPage` for 404 and 500.
+
+## Admin shell
+
+```tsx
+import { AdminLayout, PageHeader, Sidebar, Topbar, UserMenu } from '@kennycorrea/ui';
+
+<AdminLayout
+  sidebar={<Sidebar header={<Logo />} sections={[{ items: [
+    { label: 'Dashboard', icon: <HomeIcon />, href: '/', active: true },
+    { label: 'Orders', icon: <CubeIcon />, href: '/orders', badge: 3, badgeLabel: '3 new' },
+  ] }]} />}
+  topbar={<Topbar search={<Input type="search" aria-label="Search" />}
+    actions={<UserMenu name="Alex Morgan" items={menu} onSelect={onMenu} />} />}
+  header={<PageHeader title="Dashboard" primaryAction={<Button>New</Button>} />}
+>
+  …
+</AdminLayout>
+```
+
+- **`AppShell`** / **`AdminLayout`**: from `md` (1024px, the `breakpoint` prop) the sidebar is a
+  sticky column that collapses to an icon rail. Below that it is an off-canvas panel opened by
+  the Topbar's menu button, with an optional bottom `TabBar` (`mobileNav`). Includes a skip link
+  to `<main>`.
+- **`Sidebar`** sections of **`NavItem`**s: links, buttons, or one level of grouped links. In
+  the rail, labels become tooltips and groups open as a menu, and the header shows
+  `collapsedHeader` (a logo mark) if you give one.
+- **`Topbar`**, **`PageHeader`** (the page's `h1`, breadcrumbs, a primary action, and secondary
+  actions that fold into a menu below 640px of header width), **`PageTabs`** (a `nav` of
+  links), **`Breadcrumbs`** (folds long trails; only the parent shows below 768px).
+- **`UserMenu`**, **`ThemeToggle`**, **`AccentPicker`**: the last two take a `createTheming`
+  instance to read and store the choice. The app applies it to `<Theme>`.
+- **`ActionMenu`**: a dropdown menu that becomes an `ActionSheet` below `sm`. **`TextLink`**:
+  an inline link, with `external` for new-tab links.
+- **Routing**: everything that navigates takes `href` plus an optional `render` that receives
+  the props to spread onto your router's link:
+  `render={(p) => <RouterLink to={p.href} {...p} />}`.
+
+Full example: [examples/admin/Shell.tsx](examples/admin/Shell.tsx).
+
+## Data display
+
+```tsx
+const columns: DataTableColumn<Order>[] = [
+  { id: 'number', header: 'Order', isRowHeader: true, cell: (o) => `#${o.number}`, sortValue: (o) => o.number },
+  { id: 'total', header: 'Total', align: 'end', cell: (o) => money.format(o.total), sortValue: (o) => o.total },
+  { id: 'placed', header: 'Placed', priority: 'low', cell: (o) => day.format(o.placed), sortValue: (o) => o.placed },
+];
+const table = useClientTable(orders, columns, { sort, page, pageSize }); // or your server's page
+
+<DataTable caption="Orders" columns={columns} rows={table.rows} getRowId={(o) => o.id}
+  sort={sort} onSortChange={setSort} selection={selected} onSelectionChange={setSelected}
+  rowActions={() => [{ id: 'refund', label: 'Refund', destructive: true }]} onRowAction={act}
+  pagination={{ page, onPageChange: setPage, total: table.total, pageSize }} />
+```
+
+- **`DataTable`** is fully controlled: it never sorts, pages or selects by itself. It responds to
+  its own width. `low`-priority columns hide below 640px of table width and `medium` ones below
+  480px. Below `stackBelow` (`sm` 480 / `md` 640, the default / `lg` 800 / `false`) each row
+  becomes a labelled card. `state` covers `loading`, `empty` and `error` inside the table.
+- **`useClientTable`** / **`sortRows`**: sorting with `Intl.Collator` (numeric, in the provider's
+  `locale`, empty values last) and paging, for data already in the browser.
+- **`Pagination`**: numbered pages, or "Page 2 of 10" when narrow; range text and rows-per-page.
+  `paginationRange` is exported for custom pagers.
+- **`BulkActionBar`**: a sticky toolbar while rows are selected, with the count in a live region.
+- **`EmptyState`**, **`ErrorState`** (`role="alert"`, retry, details) and **`LoadingState`**
+  (`spinner`, `rows`, `cards`).
+- **`StatGroup`** (StatTiles in a ScrollStrip), **`KeyValueList`** (Radix `DataList`),
+  **`StatusIndicator`** (a dot and a word) and **`Pill`** (a removable token).
+- **Templates:** `ListPage`, `DetailPage` (the aside sits beside the main content from 960px and
+  comes after it in the DOM) and `StatusPage` (404/500, outside the shell).
+
+UI strings with a value in them are functions, e.g.
+`selectedCount: (n) => \`${n} seleccionados\``.
+Full example with 500 rows: [examples/admin/Orders.tsx](examples/admin/Orders.tsx).
+
+## Forms and filters
+
+```tsx
+<FormPage onSubmit={submit}
+  errorSummary={<ErrorSummary errors={summary} submitCount={submitCount} />}
+  actions={<FormActions><Button type="submit">Save</Button></FormActions>}>
+  <FormSection title="Profile" description="Shown on your profile.">
+    <FormField id="email" label="Email" hint="We never share it." error={errors.email} required>
+      <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
+    </FormField>
+  </FormSection>
+</FormPage>
+```
+
+- **`FormField`** wires the label, hint, error, `required` and invalid state into one control.
+  `Input`, `Textarea` and `Select` get their red state, and anything else gets `aria-invalid`.
+  Pass a function as the child to place the ids yourself. Use `layout="inline"` for a Checkbox
+  or Switch. **`FormFieldset`** groups controls under a legend.
+- **`ErrorSummary`**: after a failed submit it takes focus, says how many problems there are,
+  and links each one to its field. Increment `submitCount` on each submit so it refocuses.
+- **`FormSection`** (title beside the fields from 720px of its own width), **`FormActions`**
+  (sticky at the bottom below 768px, above an AppShell's TabBar), **`FormPage`**
+  (`noValidate`, so only your messages show).
+- **`SearchField`**: magnifier, clear button, Escape, optional `debounceMs` and a page-wide
+  `shortcut` key.
+- **`FilterPopover`**: a "Filters (n)" button opening a popover, or a bottom sheet below `sm`.
+  With `onApply` the controls are a draft. **`FilterChips`** is a ChipGroup plus clear-all.
+  **`FilterBar`** lays out search, filters and actions, with active filters as removable pills.
+- **`SettingsPage`**: section list beside the content from 768px; a select above it when
+  narrower.
+
+Full example: [examples/admin/AccountForm.tsx](examples/admin/AccountForm.tsx).
+
+## Dates and charts
+
+Dates are **calendar dates as ISO strings** (`'2026-09-21'`), not `Date` objects. A due date is
+the same day everywhere, so nothing shifts by a day across time zones or clock changes. The
+helpers in `utils/dates` (`addDays`, `addMonths`, `monthGrid`, `firstDayOfWeek`,
+`formatIsoDate`, `formatDateRange`…) do the arithmetic in UTC and format through `Intl` with
+the `UiStringsProvider` locale.
+
+- **`Calendar`** follows the WAI-ARIA date picker grid. Arrows, Home/End, PageUp/PageDown (with
+  Shift for a year) and Enter work; days are named by their full date, and today is
+  `aria-current="date"`. `mode="range"`, `min`/`max`/`isDateDisabled`, and the week starting on
+  the locale's own first day.
+- **`DateInput`**: a field showing the date that opens a Calendar, in a popover or (below
+  `sm`) a sheet. `native` uses `<input type="date">` instead. Works inside `FormField`.
+- **`DateRangePicker`**: two months beside presets, or one month and preset chips in a
+  sheet. The second date or a preset commits.
+- **Charts**: `BarChart` (grouped or stacked), `LineChart`, `DonutChart` and `Sparkline`, as
+  plain SVG with no dependency. Each is one image named by your `label` sentence. Series are
+  told apart by pattern (bars, donut) or marker shape (lines) as well as colour, and the
+  legend repeats them. The width follows the container.
+- **`ChartFrame`**: the card around any chart, yours or another library's, with a heading and
+  a "View as table" switch fed by `chartTable` / `donutTable`.
+- **`--chart-1` … `--chart-8`**: a palette where every colour reaches 3:1 against the panel in
+  light and dark, held there by a test.
+- **`DashboardPage`** + **`DashboardWidget span`**: one, two, then `columns` columns by the
+  page's own width.
+
+Full example: [examples/admin/Dashboard.tsx](examples/admin/Dashboard.tsx).
+
+## Hooks and breakpoints
+
+- `BREAKPOINTS` — Radix Themes' scale in pixels (`xs` 520, `sm` 768, `md` 1024, `lg` 1280,
+  `xl` 1640), the same scale `Responsive<T>` props and `tokens.css` use. `minWidth(bp)` turns
+  a name into a media query.
+- `useMediaQuery(query, serverValue = true)` — for switching *structure*; visual changes belong
+  in CSS. Returns `serverValue` on the server and without `matchMedia`.
+- `useBreakpoint(serverValue = 'lg')` — the largest breakpoint reached, or `'initial'`.
+- `useControllableState({ value, defaultValue, onChange })` — the controlled/uncontrolled pair.
+
+`ResponsiveDialog` and `ActionSheet` take a `breakpoint` (default `sm`, 768px, unchanged).
+
+## Library structure
+
+`src/` is layered: `atoms` → `molecules` → `organisms` → `templates`, with `hooks`, `utils`,
+`strings`, `primitives` and `icons` underneath. A layer imports only from layers below it, and
+`test/foundations.test.tsx` fails the build when one does not. Everything ships from the root
+entry. The plan for the upper layers is in
+[docs/admin-template-plan.md](docs/admin-template-plan.md).
+
 ## Mobile presentation layer
 
 An opt-in "grouped" surface style — rows in rounded cards on a tinted canvas, as in native
@@ -239,7 +489,7 @@ content, capped at 90%). Pass `detents` to let the user move between several; dr
 the lowest dismisses.
 
 ```tsx
-<Sheet open={open} onOpenChange={setOpen} title="New booking" detents={['medium', 'large']}
+<Sheet open={open} onOpenChange={setOpen} title="New item" detents={['medium', 'large']}
   defaultDetent="medium" scaleBackground footer={<Button>Save</Button>}>
   <form>…</form>
 </Sheet>

package/dist/atoms/ActionMenu/ActionMenu.d.ts

@@ -0,0 +1,37 @@
+import { type ReactElement, type ReactNode } from 'react';
+import { type Breakpoint } from '../../hooks/breakpoints.js';
+export interface ActionMenuItem {
+    /** Stable across renders; also what `onSelect` is given back. */
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    /** Red and separated from the rest, for the one that undoes something. */
+    destructive?: boolean;
+    /** Shown greyed in the menu. Left out of the sheet, which has no disabled state. */
+    disabled?: boolean;
+}
+export interface ActionMenuProps {
+    /** The button that opens it. Must accept a ref and `onClick` (any button does). */
+    trigger: ReactElement;
+    items: ActionMenuItem[];
+    onSelect: (id: string) => void;
+    /** Alignment of the menu against the trigger. Default `end`. */
+    align?: 'start' | 'center' | 'end';
+    side?: 'top' | 'right' | 'bottom' | 'left';
+    /**
+     * Below this breakpoint the menu is an `ActionSheet` instead, which is easier to hit with a
+     * thumb. Default `sm` (768px), the same switch `ActionSheet` makes. `false` keeps the menu
+     * everywhere.
+     */
+    sheetBelow?: Breakpoint | false;
+    /** The sheet's heading. */
+    title?: ReactNode;
+}
+/**
+ * A button that opens a short list of actions: a dropdown menu on wide screens, an action
+ * sheet on narrow ones. Items are data, in the same shape as `ContextMenu`'s.
+ *
+ * Named `ActionMenu` because `DropdownMenu` is Radix Themes' own component, re-exported from
+ * this package as a primitive for anything this does not cover.
+ */
+export declare function ActionMenu({ trigger, items, onSelect, align, side, sheetBelow, title, }: ActionMenuProps): import("react").JSX.Element;

package/dist/atoms/ActionMenu/ActionMenu.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Slot, DropdownMenu as ThemedDropdownMenu } from '@radix-ui/themes';
+import { Fragment, useState } from 'react';
+import { minWidth } from '../../hooks/breakpoints.js';
+import { useMediaQuery } from '../../hooks/useMediaQuery.js';
+import { ActionSheet } from '../ActionSheet/ActionSheet.js';
+/**
+ * A button that opens a short list of actions: a dropdown menu on wide screens, an action
+ * sheet on narrow ones. Items are data, in the same shape as `ContextMenu`'s.
+ *
+ * Named `ActionMenu` because `DropdownMenu` is Radix Themes' own component, re-exported from
+ * this package as a primitive for anything this does not cover.
+ */
+export function ActionMenu({ trigger, items, onSelect, align = 'end', side, sheetBelow = 'sm', title, }) {
+    const wide = useMediaQuery(minWidth(sheetBelow || 'xs'));
+    const [sheetOpen, setSheetOpen] = useState(false);
+    if (sheetBelow !== false && !wide) {
+        return (_jsxs(_Fragment, { children: [_jsx(Slot, { "aria-haspopup": "dialog", onClick: () => setSheetOpen(true), children: trigger }), _jsx(ActionSheet, { open: sheetOpen, onOpenChange: setSheetOpen, title: title, breakpoint: sheetBelow, actions: items
+                        .filter((item) => !item.disabled)
+                        .map((item) => ({
+                        label: item.label,
+                        icon: item.icon,
+                        tone: item.destructive ? 'danger' : 'neutral',
+                        onSelect: () => onSelect(item.id),
+                    })) })] }));
+    }
+    return (_jsxs(ThemedDropdownMenu.Root, { children: [_jsx(ThemedDropdownMenu.Trigger, { children: trigger }), _jsx(ThemedDropdownMenu.Content, { size: "2", align: align, side: side, children: items.map((item, index) => (_jsxs(Fragment, { children: [item.destructive && index > 0 && !items[index - 1].destructive ? (_jsx(ThemedDropdownMenu.Separator, {})) : null, _jsxs(ThemedDropdownMenu.Item, { color: item.destructive ? 'red' : undefined, disabled: item.disabled, onSelect: () => onSelect(item.id), children: [item.icon ? (_jsx("span", { "aria-hidden": "true", className: "inline-flex", children: item.icon })) : null, item.label] })] }, item.id))) })] }));
+}

package/dist/atoms/ActionMenu/index.d.ts

@@ -0,0 +1 @@
+export * from './ActionMenu.js';

package/dist/atoms/ActionMenu/index.js

@@ -0,0 +1 @@
+export * from './ActionMenu.js';

package/dist/atoms/ActionSheet/ActionSheet.d.ts

@@ -1,4 +1,5 @@
-import { type ReactNode } from 'react';
+import type { ReactNode } from 'react';
+import { type Breakpoint } from '../../hooks/breakpoints.js';
 export type ActionSheetTone = 'neutral' | 'brand' | 'danger';
 export interface ActionSheetAction {
     label: string;
@@ -18,13 +19,18 @@ export interface ActionSheetProps {
     cancelLabel?: string;
     /** Where the portal mounts. Default: the nearest `<Theme>`, else rendered in place. */
     container?: HTMLElement | null;
+    /**
+     * From this breakpoint up, the sheet is a small centred dialog. Default `sm` (768px), which
+     * is what Tailwind calls `md`.
+     */
+    breakpoint?: Breakpoint;
 }
 /**
- * A short list of actions to choose between, on Radix `AlertDialog`: below `md` anchored to the
- * bottom as a grouped list with a separated Cancel; at `md` and up a small centred dialog.
+ * A short list of actions to choose between, on Radix `AlertDialog`: below `breakpoint` anchored
+ * to the bottom as a grouped list with a separated Cancel; from it up a small centred dialog.
  *
  * AlertDialog rather than Dialog because the user is being asked to decide — it cannot be
  * dismissed by clicking outside, and focus lands on Cancel, so Enter never fires a destructive
  * action by accident. Escape and Cancel both close it without running anything.
  */
-export declare function ActionSheet({ open, onOpenChange, actions, title, message, cancelLabel, container, }: ActionSheetProps): import("react").JSX.Element;
+export declare function ActionSheet({ open, onOpenChange, actions, title, message, cancelLabel, container, breakpoint, }: ActionSheetProps): import("react").JSX.Element;

package/dist/atoms/ActionSheet/ActionSheet.js

@@ -1,36 +1,27 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import * as AlertDialog from '@radix-ui/react-alert-dialog';
 import { Theme } from '@radix-ui/themes';
-import { useSyncExternalStore } from 'react';
+import { minWidth } from '../../hooks/breakpoints.js';
+import { useMediaQuery } from '../../hooks/useMediaQuery.js';
 import { useUiStrings } from '../../strings.js';
 import { cn } from '../../utils/cn.js';
 import { useThemePortalTarget } from '../../utils/themePortal.js';
-/** Tailwind's `md`. At and above it the sheet becomes a small centred dialog. */
-const MD = '(min-width: 768px)';
-function subscribe(onChange) {
-    const query = window.matchMedia(MD);
-    query.addEventListener('change', onChange);
-    return () => query.removeEventListener('change', onChange);
-}
-function useIsMdUp() {
-    return useSyncExternalStore(subscribe, () => window.matchMedia(MD).matches, () => true);
-}
 const TONE = {
     neutral: 'text-ink',
     brand: 'text-brand-700',
     danger: 'text-[var(--red-11)]',
 };
 /**
- * A short list of actions to choose between, on Radix `AlertDialog`: below `md` anchored to the
- * bottom as a grouped list with a separated Cancel; at `md` and up a small centred dialog.
+ * A short list of actions to choose between, on Radix `AlertDialog`: below `breakpoint` anchored
+ * to the bottom as a grouped list with a separated Cancel; from it up a small centred dialog.
  *
  * AlertDialog rather than Dialog because the user is being asked to decide — it cannot be
  * dismissed by clicking outside, and focus lands on Cancel, so Enter never fires a destructive
  * action by accident. Escape and Cancel both close it without running anything.
  */
-export function ActionSheet({ open, onOpenChange, actions, title, message, cancelLabel, container, }) {
+export function ActionSheet({ open, onOpenChange, actions, title, message, cancelLabel, container, breakpoint = 'sm', }) {
     const strings = useUiStrings();
-    const mdUp = useIsMdUp();
+    const mdUp = useMediaQuery(minWidth(breakpoint));
     const { anchorRef, target, resolved } = useThemePortalTarget(container);
     const cancel = cancelLabel ?? strings.cancel;
     const hasHeader = title != null || message != null;

package/dist/atoms/ActionSheet/confirm.d.ts

@@ -14,7 +14,7 @@ export interface ConfirmOptions {
  * Asks and resolves `true` on accept, `false` on Cancel, Escape or any other dismissal.
  * Never rejects.
  *
- *     if (await confirm({ title: 'Delete booking?', confirmLabel: 'Delete', tone: 'danger' })) …
+ *     if (await confirm({ title: 'Delete item?', confirmLabel: 'Delete', tone: 'danger' })) …
  */
 export declare function confirm(options: ConfirmOptions): Promise<boolean>;
 /** Renders the pending confirmation. Mount once, inside `<Theme>`, next to `<Toaster>`. */

package/dist/atoms/ActionSheet/confirm.js

@@ -25,7 +25,7 @@ function subscribe(l) {
  * Asks and resolves `true` on accept, `false` on Cancel, Escape or any other dismissal.
  * Never rejects.
  *
- *     if (await confirm({ title: 'Delete booking?', confirmLabel: 'Delete', tone: 'danger' })) …
+ *     if (await confirm({ title: 'Delete item?', confirmLabel: 'Delete', tone: 'danger' })) …
  */
 export function confirm(options) {
     return new Promise((resolve) => emit([...queue, { ...options, resolve }]));