@ultimat3/ui 22.15.0 → 23.0.0

package/CATALOG.md

@@ -103,13 +103,14 @@ Small status label. Tone maps straight onto the status colour roles so the same
 
 ### BarChart
 
-A bar chart of one series — clicks per day, signups per week — as static SVG. No charting library: the framework's own docs use a sparkline pulling one in as the cautionary example, and a route's JS budget counts raw minified bytes. `<rect>` bars cost nothing to hydrate, so the server-rendered shell IS the chart. Geometry lives in `bar-chart-view.ts`.
+A bar chart of one series — clicks per day, signups per week — or two stacked (done, and failed on top), as static SVG. No charting library: the framework's own docs use a sparkline pulling one in as the cautionary example, and a route's JS budget counts raw minified bytes. `<rect>` bars cost nothing to hydrate, so the server-rendered shell IS the chart. Geometry lives in `bar-chart-view.ts`.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
 | `label` | `string` | yes | The accessible name for the whole chart, already translated. |
 | `points` | `readonly ChartPoint[]` | yes | Oldest first. Every bar comes from exactly this array — the caller zero-fills gaps. |
 | `highlightLast` | `boolean` | — | Draw the last bar at full strength — the eye lands where the live number is. Default on. |
+| `seriesLabels` | `{ readonly primary: string; readonly secondary: string }` | — | Names of the two series, already translated, read by each rect's `<title>`. Give them when a point carries `secondary`: a stacked bar with no name for its top is two numbers and no key. |
 | `class` | `string` | — |  |
 
 ### Breadcrumb
@@ -170,6 +171,7 @@ Native checkbox with a token-drawn indicator. The label element wraps the input,
 | `id` | `string` | — |  |
 | `name` | `string` | — |  |
 | `value` | `string` | — |  |
+| `form` | `string` | — | The id of the `<form>` this box submits with, when it cannot sit inside it — a row checkbox in a table whose page already holds another form. The platform's own association, no script. |
 | `checked` | `boolean` | — |  |
 | `indeterminate` | `boolean` | — | Tri-state for "some children selected". The ONLY thing mirrored to `aria-checked`. |
 | `disabled` | `boolean` | — |  |
@@ -258,7 +260,6 @@ Data-driven table: sortable headers, cursor pagination, and the four states a re
 | `rows` | `readonly Row[]` | yes |  |
 | `rowKey` | `(row: Row) => string` | yes |  |
 | `sort` | `SortState` | — |  |
-| `onSortChange` | `(sort: SortState \| undefined) => void` | — |  |
 | `loading` | `boolean` | — |  |
 | `error` | `unknown` | — | An UltimateError (or anything shaped like one) from the query. |
 | `onRetry` | `(() => void)` | — |  |
@@ -266,11 +267,14 @@ Data-driven table: sortable headers, cursor pagination, and the four states a re
 | `emptyDescription` | `string` | — |  |
 | `nextCursor` | `string` | — | Opaque cursors from the query result; absent means no further page. |
 | `prevCursor` | `string` | — |  |
-| `onCursor` | `((cursor: string, direction: 'next' \| 'prev') => void)` | — |  |
 | `stickyHeader` | `boolean` | — |  |
 | `density` | `'comfortable' \| 'compact'` | — |  |
 | `skeletonRows` | `number` | — | Placeholder row count while loading. Match the usual page size. |
 | `class` | `string` | — |  |
+| `onCursor` | `((cursor: string, direction: 'next' \| 'prev') => void)` | — | Callback paging. Never beside `hrefFor` — the type refuses the pair. |
+| `onSortChange` | `((sort: SortState \| undefined) => void)` | — | Callback sorting. Never beside `sortHrefFor` — the type refuses the pair. |
+| `hrefFor` | `(cursor: string, direction: 'next' \| 'prev') => string` | — | Link paging: the URL of the page a cursor names, handed to `<Pagination hrefFor>`. |
+| `sortHrefFor` | `((sort: SortState \| undefined) => string)` | — | Link sorting: the URL of the list under the NEXT sort state of a header's cycle (`undefined` is "unsorted"). Absent, a sortable header is plain text — never a button with no handler. |
 
 ### DateTime
 
@@ -546,7 +550,7 @@ A keyboard key or chord as the user reads it — "⌘K", "Esc", "/". A native `<
 
 ### Link
 
-Anchor primitive. External links get `rel` hardening and a translated "opens in a new tab" hint automatically — never a bare `target="_blank"`.
+Anchor primitive. External links get `rel` hardening and a translated "opens in a new tab" hint automatically — never a bare `target="_blank"`. `appearance="button"` is Button's look on the same anchor: a control that navigates is a link.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -554,12 +558,19 @@ Anchor primitive. External links get `rel` hardening and a translated "opens in
 | `children` | `JSX.Element` | yes |  |
 | `external` | `boolean` | — |  |
 | `externalHint` | `string` | — | Announced suffix for external links; supply via `t()` at the call site. |
-| `underline` | `'always' \| 'hover' \| 'none'` | — |  |
-| `tone` | `'accent' \| 'inherit'` | — |  |
+| `rel` | `'next' \| 'prev'` | — | A pager's direction. Joins the hardening an external link always carries, never replaces it. |
 | `id` | `string` | — |  |
 | `class` | `string` | — |  |
 | `aria-current` | `'page' \| 'step' \| 'true' \| false` | — |  |
 | `onClick` | `JSX.EventHandlerUnion<HTMLAnchorElement, MouseEvent>` | — |  |
+| `appearance` | `'link' \| 'button'` | — | `button` wears Button's classes on the same `<a>`; the two looks take different props. |
+| `underline` | `'always' \| 'hover' \| 'none'` | — |  |
+| `tone` | `'accent' \| 'inherit' \| Tone` | — | A text link: `accent` or `inherit`. A button-link: any `Tone`. |
+| `variant` | `ButtonVariant` | — | `appearance="button"` only. |
+| `size` | `Size` | — | `appearance="button"` only. |
+| `fullWidth` | `boolean` | — | `appearance="button"` only. |
+| `iconStart` | `JSX.Element` | — | `appearance="button"` only. |
+| `iconEnd` | `JSX.Element` | — | `appearance="button"` only. |
 
 ### LocaleSwitcher
 
@@ -631,19 +642,20 @@ The top of a screen: breadcrumbs, the page's one heading, a description, and the
 
 ### Pagination
 
-Cursor-first pagination — the only shape a Postgres-backed list should use. Numbered mode exists for prerendered archives where the total is known.
+Cursor-first pagination — the only shape a Postgres-backed list should use. Numbered mode exists for prerendered archives where the total is known. One mode per use: callbacks (`onCursor` / `onPage`) for an island, or `hrefFor` for a server-rendered list — anchors the browser follows, with no script on the page.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
 | `nextCursor` | `string` | — | Opaque cursor for the following page; absent disables "next". |
 | `prevCursor` | `string` | — |  |
-| `onCursor` | `((cursor: string, direction: 'next' \| 'prev') => void)` | — |  |
-| `page` | `number` | — | Numbered mode: 1-based page and total. Ignored when cursors are present. |
-| `totalPages` | `number` | — |  |
-| `onPage` | `((page: number) => void)` | — |  |
 | `labelPrevious` | `string` | — | Already-translated; falls back to the ui.* catalog keys. |
 | `labelNext` | `string` | — |  |
 | `class` | `string` | — |  |
+| `onCursor` | `((cursor: string, direction: 'next' \| 'prev') => void)` | — | Callback mode. Never beside `hrefFor` — the type refuses the pair. |
+| `page` | `number` | — | Numbered mode: 1-based page and total. Ignored when cursors are present. |
+| `totalPages` | `number` | — |  |
+| `onPage` | `((page: number) => void)` | — |  |
+| `hrefFor` | `(cursor: string, direction: 'next' \| 'prev') => string` | — | Link mode: the URL of the page a cursor names. Renders `<a rel="next\|prev">` and attaches no handler, so it needs no island. Cursor paging only — never beside `onCursor`, `onPage`, `page` or `totalPages`. |
 
 ### Popover
 
@@ -1014,6 +1026,14 @@ charts and email.
 | `pill` | `999px` |
 | `full` | `50%` |
 
+### Stroke — `--stroke-*`
+
+| Token | Value |
+|---|---|
+| `hairline` | `1px` |
+| `thick` | `2px` |
+| `heavy` | `3px` |
+
 ### Font size — `--text-*`
 
 | Token | Value |
@@ -1078,7 +1098,7 @@ charts and email.
 | `toast` | `700` |
 | `skip-nav` | `800` |
 
-### Breakpoints — `@include t.respond-to(<name>)`
+### Breakpoints — `respond-to` · `respond-down` · `respond-between`
 
 | Token | Value |
 |---|---|
@@ -1087,3 +1107,14 @@ charts and email.
 | `lg` | `1024px` |
 | `xl` | `1280px` |
 | `2xl` | `1536px` |
+
+`@include t.respond-to(md)` is `md` and wider, `t.respond-down(md)` is narrower than `md`, and
+`t.respond-between(md, lg)` is `md` up to `lg`. A max-width arm stops 0.02px under its rung, so
+no width matches two of them.
+
+### Computed lengths
+
+| Function | Answers |
+|---|---|
+| `t.rem(24px)` | `1.5rem` — px, rem or a unitless px count in, rem out |
+| `t.fluid(1rem, 2rem, 20rem, 80rem)` | one `clamp()`: the first size at a 20rem viewport, the second at 80rem, linear between |

package/CLAUDE.md

@@ -12,17 +12,19 @@ Tier 4. Imports `@ultimat3/core`, `i18n`, `money`, `time` — **not `schema`**,
 
 - **SCSS modules only.** `Foo.tsx` + `Foo.module.scss`, always paired. No Tailwind, no CSS-in-JS, no inline `style` except CSS custom properties.
 - **No raw colours.** Only `t.role('<role>')` / `var(--color-*)`. Canonical roles live in `src/tokens/_colors.scss`; `tokens.ts` mirrors them and `tokens.test.ts` fails on drift.
+- **No raw length, breakpoint, z-index, shadow or duration** in any sheet here: `t.space()` / `t.stroke()` / `t.rem()`, `respond-*`, `t.z()`, `t.shadow()`, `t.duration()`. Held by `packages/cli/src/templates/scaffold-guards-style.test.ts`, which runs the guards `x new` ships over this package.
 - **Logical properties only.** `margin-inline`, `inset-inline-start`, `text-align: start`. A `left`/`right` in a stylesheet is a bug.
 - **solid-js is a type-only import.** All reactive access goes through `src/theme/solid-adapter.ts`. Never `import { createSignal } from 'solid-js'`.
 - **The runtime SLOT is `src/theme/runtime-slot.ts`; the RULE is `solid-adapter.ts`, and the split is a byte measurement.** `solid-adapter.ts` reaches `../errors` and so core's error registry; the slot imports nothing, so an island that only calls `setSolidRuntime` pays 72 B, not 5,719. `barrel-bytes.test.ts` holds the ceiling at 1 kB.
 - **The barrel is the ONE import path; component subpath exports are refused on measurement** (issue #275). A barrel import and a deep path emit the same modules and bytes, so `@ultimat3/ui/button` would be a second idiom for zero bytes. The two subpaths that exist are not exceptions: `./icons/*` is 1,767 data modules no bundler can split, and `./jsx-probe` is test-only. `barrel-bytes.test.ts` compares the two paths and names `schema-error-codes.ts` (Bun 1.4.0's load-correlated shake, issues #273 #276) rather than allowing bytes for it.
-- **`useUi()`'s server branch is a SLOT, and the module that fills it is browser-mapped** (issue #490). `context.ts` imports no value from `@ultimat3/i18n` or `@ultimat3/time` (the i18n barrel installs the framework catalog at import: 16.1 kB per island). `src/theme/ambient.ts` registers `ambientUiContext` into `ambient-slot.ts` at import; `index.ts` imports it BARE above every re-export, and `package.json`'s `browser` field maps it to `ambient.browser.ts` (bundlers only — `bun test` and SSR get the server's). A test reaching components by module path must `import './ambient'` itself, as `inert-render.test.ts` does. `fallbackTranslator` is held member-for-member against `createTranslator({})` by `context.test.ts`. `errors.ts` is pure: `registerErrorCodes()` is `src/error-registry.ts`, imported bare. `barrel-bytes.test.ts` pins the theme island's retained-module list.
+- **`useUi()`'s server branch is a SLOT, and the module that fills it is browser-mapped** (issue #490). `context.ts` imports no value from `@ultimat3/i18n` or `@ultimat3/time`. `src/theme/ambient.ts` registers into `ambient-slot.ts` at import; `index.ts` imports it BARE above every re-export; `package.json`'s `browser` field maps it to `ambient.browser.ts`. A test reaching components by module path must `import './ambient'` itself. `errors.ts` is pure: `registerErrorCodes()` is `src/error-registry.ts`, imported bare.
 - **`solid()` always answers off-DOM.** No registered runtime and no DOM is a *server render*, and it gets `INERT_SOLID_RUNTIME` (`src/theme/inert-runtime.ts`) — signals hold, memos recompute on read, effects never run, `useContext` returns the default. No DOM means no reactivity to lose; a **DOM** with no runtime is still `X_UI_RUNTIME_MISSING`, because that one is the theme toggle that does nothing. Never widen this to "no runtime, never throw": that is the silent degradation the split exists to prevent.
 - **`useUi()` reads the request on the server**, via `ambientUiContext()` — `currentLocale()`, `currentTimeZone()`, `useI18n()`, which read **core's own `Ctx.locale` / `Ctx.tz`** (written once per request by `@ultimat3/http`'s `locale` stage). Never add a second ambient store here or in `i18n`/`time`. `theme`/`currency` have no ambient source at all.
 - **Every locale-sensitive call takes the locale as an ARGUMENT, `toLocaleUpperCase` included.** `initialsOf(name, locale)` reads `useUi().locale`; a bare `toLocaleUpperCase()` reads the runtime's default (Turkish dotted `i` → `İ`).
 - **`UiProvider` is client-only and throws on the server** (`providerNeedsRuntimeError`, the same `X_UI_RUNTIME_MISSING`). A Provider in an inert tree reaches no descendant — the tree is built before the renderer walks it, so consumers are walked outside every owner and read the context default even with a real Solid runtime registered. Rendering the children anyway would drop its locale, zone, currency and translator silently. Making it work needs the *renderer* to scope a context around the walk; until then it refuses.
 - **A component may call `solid()` freely.** Its effects must stay DOM-only work — they simply never run on the server.
 - **No `{...rest}` prop spreading.** Splitting props reactively needs solid's `splitProps` (a value import), so components declare explicit props and read `props.x` inside JSX.
+- **One mode per use is a UNION of interfaces** (`LinkProps`, `PaginationProps`, `DataTableProps` — where the mode covers the pager AND the sort headers: `hrefFor` + `sortHrefFor`, or `onCursor` + `onSortChange`; a linked table never renders a button with no handler): a mode forbids the other's props with `x?: undefined`, and `catalog/parse-component.ts` merges the modes.
 - **No hardcoded strings.** Label props, or `useUi().t(UI_KEYS.x)`. New built-in strings go in `src/i18n-keys.ts`.
 - **Page layout is four composites**: `AppShell` (frame + skip link + landmarks), `PageHeader`, `Section`, `Toolbar`. A screen that hand-rolls a header grid is the bug they exist to prevent. `AppShell` holds no state — off-canvas is `Drawer`.
 - **Restyling goes through `defineTheme()`**, never a forked stylesheet and never an SCSS `with ()` override. Its values are validated, not escaped: the output lands in a `<style>` element.
@@ -33,55 +35,15 @@ Tier 4. Imports `@ultimat3/core`, `i18n`, `money`, `time` — **not `schema`**,
 - **`inert-render.test.ts` must not assume which factory its `.tsx` compiled to.** `@ultimat3/render` installs a process-global `.tsx` `onLoad` plugin at import, so in one `bun test` process a component may compile to render's `h`. The walker recognises both (`Symbol.for('ultimate.render.jsx')`), and the first test asserts a recognised node — otherwise the file renders `"[object Object]"` and passes by shard packing.
 - **Components are not unit-tested through a renderer.** `.tsx` compiles to `@ultimat3/render`'s `h`, which this package may not import, so every rule lives in a pure module beside the component (`icon-glyph.ts`, `accordion-view.ts`, `combobox-filter.ts`, `infinite-scroll-view.ts`) and *that* is what the tests assert.
 - Formatting logic lives in a pure `*-view.ts` next to the component (`money-view.ts`, `date-time-view.ts`) so it is testable with no renderer. Every other renderer-free core follows the same rule under its own name (`sort-state.ts`, `image-source.ts`) — the `.tsx` holds markup, never a rule.
-- **The rule being pure is not enough — the WIRING has to be tested too.** `createRovingTabindex` was correct and `Menu` handed it `[role="menuitem"]`, so a disabled item made every item after it unreachable and every assertion in the package still passed. `src/jsx-probe.ts` reads the props an element actually carries (a `tabindex`, an `aria-live`, an `onKeyDown`, a `ref`) and `src/fake-dom.ts` gives it a DOM where a disabled control REFUSES focus, exactly as the real one does. Both are test-only and neither is in `index.ts`. `jsx-probe`'s `probe`/`unprobe` are the one exception, reachable at the subpath `@ultimat3/ui/jsx-probe` and still absent from the barrel: `globalThis.React` is ONE property, so its install/restore counter has to be ONE counter — `@ultimat3/admin` (tier 5) kept a second pair, and interleaved installs restored the two harnesses in the wrong order, leaving the global holding a harness the run had already torn down. `components/interaction.test.ts` is where a keyboard or form-participation claim gets proven; asserting the pure helper alone is how these shipped.
+- **The rule being pure is not enough — the WIRING is tested too.** `src/jsx-probe.ts` reads the props an element carries and `src/fake-dom.ts` is a DOM where a disabled control refuses focus; both TEST-ONLY, neither in `index.ts`. `probe`/`unprobe` are the framework's ONE owner of `globalThis.React`, reachable at `@ultimat3/ui/jsx-probe` (admin imports them). A keyboard or form-participation claim is proven in `components/interaction.test.ts`.
 - **A roving group excludes disabled items from both answers** — the set arrows walk and the one item holding the tab stop (`src/roving.ts`). `focus()` on a disabled control is a no-op, so a disabled item left in the list pins the reducer on its index forever. And a control that answers arrows itself (`handlesOwnArrowKeys`) keeps them: a `Toolbar` exists to hold a search field.
 - **A single-winner state attribute is decided by POSITION, never by a missing prop.** `Breadcrumb` gives `aria-current="page"` to the last item and to nothing else; an href-less ancestor renders as plain text with no `aria-current` at all. Reading "no href" as "is the current page" put two of them in one `<nav>`. `Tabs.tsx` is the same rule for `tabindex`, and `Breadcrumb.test.ts` proves it through `jsx-probe` rather than through the pure helper.
-- **One async region, four branches, and `empty` is unreachable while `pending`.** `asyncBranch`
-  (`src/components/async-branch.ts`) is the ONLY place the `(pending, failed, empty, data)` decision
-  is made — `AsyncRegion` renders it and `DataTable` calls it, so a table and a card list cannot
-  disagree about what "loading with stale rows" looks like. The property is structural: an
-  `AsyncState` (declared in `@ultimat3/core` since 21.0.0 — imported here, never re-exported, so
-  it has one import path) in `pending` carries no data, so nothing can be found empty in it, and "No results"
-  for one frame before the first page arrives is unconstructible rather than discouraged.
-  `<AsyncRegion>`'s `empty` and `ready` are REQUIRED props, so forgetting the empty state is a type
-  error. `refreshing` CARRIES the previous data — a refetch dims what is on screen (`aria-busy`) and
-  never tears it down, which is what makes a search box feel fast; the empty branch is reachable
-  only from a completed result that returned zero. `reserve` feeds the placeholder AND the
-  `min-block-size` of every branch, so the skeleton and the loaded content cannot be written into
-  different boxes.
-- **A toast dwell stops for THREE independent reasons, and one of them is `document.hidden`.**
-  Hover and focus-within are the two everybody implements; a backgrounded tab spends the whole dwell
-  and the corner is empty when the user comes back. `ToastHold` is a set, never a boolean: a pointer
-  leaving a toast a keyboard user is still inside must not restart the countdown, which one flag
-  cannot express. Duration is a TOKEN (`TOAST_DWELL_MS`), never a per-call number of milliseconds.
-  The queue's rules are pure (`src/toast/toast-state.ts`) and the clock is injected (`ToastEnv`), so
-  a server render gets `INERT_TOAST_ENV` — nothing scheduled — and `ToastRegion` still emits its
-  empty live region, which is what the document has to carry BEFORE the first message.
-- **`announce()` writes into a region `AppShell` already rendered.** A live region created and
-  filled in the same frame is not announced by most screen readers, so `announce()`'s own
-  create-if-absent branch could only ever be right from its second call. `liveRegionAttrs` is the
-  one derivation both halves read. It is for a state change with no surface of its own ("12
-  results", "sorted by name"); a notification is a `Toast`, and two announcement paths for one
-  message is how a screen reader reads it twice.
-- **`loading` never sets the native `disabled` attribute** (`Button`), and that WILL read as a
-  mistake. A control that disables itself mid-flow drops focus to `<body>`, is exempt from the
-  contrast minimum, announces no reason, and still does not prevent the double submit — that race is
-  on the server. `aria-disabled` + a refused click keeps it focusable and readable; `Button.module.scss`
-  restores full opacity under `[aria-busy='true']` because `t.disabled` dims to 0.55. `<Form busy>`
-  refuses the submit again, because Enter in a text field touches no button at all.
-- **A failed submit focuses the first invalid CONTROL, and the summary only when there is none.**
-  GOV.UK's summary-with-links shape is not available here: `Field` mints its control ids internally,
-  and inverting that ownership is the drift `Field` exists to prevent. `firstInvalidField` answers in
-  DECLARATION order, never issue order — a server may report the last field first. `fieldSelector`
-  is the allowlist between a caller's string and a selector; a name the grammar refuses reaches no
-  `querySelector`.
-- **`defineTheme()` refuses a palette that fails WCAG 2.2 AA** (`X_UI_CONTRAST_INSUFFICIENT`),
-  measured against `CONTRAST_PAIRS` — the same table `contrast.test.ts` holds the shipped palette to,
-  in SOURCE rather than in a test, so an app cannot ship a brand the design system would have failed
-  its own suite over. Only pairings the brand can have CHANGED are measured, on the resolved palette
-  (shipped channels + overrides): a new `accent` against the shipped `accent-fg` is the commonest way
-  a brand goes unreadable. AA, never APCA — APCA is not a standard, and AA is the operative legal
-  benchmark.
+- **One async region, four branches, and `empty` is unreachable while `pending`.** `asyncBranch` (`src/components/async-branch.ts`) is the ONLY place the decision is made — `AsyncRegion` renders it, `DataTable` calls it. `AsyncState` is core's (imported, never re-exported). `empty` and `ready` are REQUIRED props; `refreshing` carries the previous data and dims it (`aria-busy`), never tears it down; `reserve` feeds the placeholder AND every branch's `min-block-size`.
+- **A toast dwell stops for THREE independent reasons** — hover, focus-within, `document.hidden` — so `ToastHold` is a set, never a boolean. Duration is a TOKEN (`TOAST_DWELL_MS`). Rules are pure (`src/toast/toast-state.ts`), the clock injected (`ToastEnv`); a server render gets `INERT_TOAST_ENV` and `ToastRegion` still emits its empty live region.
+- **`announce()` writes into a region `AppShell` already rendered** (`liveRegionAttrs` is the one derivation). For a state change with no surface of its own; a notification is a `Toast` — never both for one message.
+- **`loading` never sets the native `disabled` attribute** (`Button`): `aria-disabled` + a refused click keeps it focusable and readable; `Button.module.scss` restores full opacity under `[aria-busy='true']`. `<Form busy>` refuses the submit again.
+- **A failed submit focuses the first invalid CONTROL, and the summary only when there is none.** `firstInvalidField` answers in DECLARATION order; `fieldSelector` is the allowlist between a caller's string and a selector.
+- **`defineTheme()` refuses a palette that fails WCAG 2.2 AA** (`X_UI_CONTRAST_INSUFFICIENT`), measured against `CONTRAST_PAIRS` on the RESOLVED palette, only for pairings the brand changed. AA, never APCA.
 - **Live semantics belong to the container that outlives the message.** `ToastRegion`'s `<ol>` carries `aria-live`; a `Toast` is a plain `<li>`. A region created with its content already inside it is not announced, and a `role="status"` on the `<li>` also strips its `listitem` semantics.
 - **`aria-checked` never mirrors a native `checked`.** ARIA outranks host state in the accessibility tree, and on the no-JS path this package supports there is nothing to rewrite the attribute after the user ticks the box. `Checkbox` writes only `'mixed'` (an IDL property with no attribute form, so ARIA is the only server-side lever); `Switch` writes none at all, over a `biome-ignore` that says why.
 - **A form binds to an action; it never decides for one.** `useForm` (`src/form/`) is a binding over an existing `action`, not a ninth primitive and not a component — `submit` is REQUIRED and is the only producer of a `succeeded` state, and the client-side parse's **value** is discarded so that only its issues are read. A binding that submitted the locally-parsed value would let a browser choose what the server was asked to store; `FormSchema` has no output type for that reason.
@@ -96,7 +58,7 @@ Tier 4. Imports `@ultimat3/core`, `i18n`, `money`, `time` — **not `schema`**,
 
 | Path | Responsibility |
 |---|---|
-| `src/tokens/*.scss` | canonical token maps + `_mixins.scss` authoring helpers |
+| `src/tokens/*.scss` | canonical token maps + `_mixins.scss` authoring helpers (`respond-to`/`-down`/`-between`) + `_units.scss` (`rem()`, `fluid()`). Every `@error` is `string.unquote('X_CODE: … fix: …')` with a REGISTERED code — `mixins.test.ts` |
 | `src/tokens/theme.scss` | the only stylesheet that emits global custom properties |
 | `src/tokens/reset.scss` | the reset, ZERO specificity: every rule a component may restyle sits in `:where(…)` whole, pseudo-class inside (`:where(a:hover)`, never `:where(a):hover`). `a:hover` (0,1,1) beat `.primary` and hid a button link's text until 22.3.2. `reset.test.ts` computes it |
 | `src/theme/runtime-slot.ts` | the module-scope slot holding the app's Solid runtime — and nothing else, so registering one costs an island 72 B |
@@ -127,6 +89,8 @@ Tier 4. Imports `@ultimat3/core`, `i18n`, `money`, `time` — **not `schema`**,
 | `src/form/use-form.ts` | the Solid shell: the same binding with its state in a signal |
 | `src/form/form-values.ts` | `FormData` → the nested object the action's input schema declares |
 | `src/form/field-binding.test.ts` | the WIRING, end to end: a rejection reaching `aria-invalid` and `aria-describedby` on the control it named |
+| `src/sass-probe.ts` | TEST-ONLY: what Sass EMITS. `sass` is resolved from `packages/render`'s directory — never an import of render, never a second copy |
+| `src/components/button-classes.ts` | the keys of a button's look, asked by `Button` AND `<Link appearance="button">` (`link-classes.ts`). `Button` gets no `href` |
 | `src/fake-dom.ts` | TEST-ONLY: a DOM where a disabled control refuses focus. Never exported from `index.ts` |
 | `src/jsx-probe.ts` | TEST-ONLY: a component's node tree, so a test can assert the props and call the handlers an element carries. `probe`/`unprobe` are the framework's ONE owner of `globalThis.React`, reached from `@ultimat3/admin` at `@ultimat3/ui/jsx-probe`; the walkers stay internal |
 | `src/barrel-bytes.test.ts` | the build error behind the three claims above: the setter's byte ceiling, barrel-vs-deep-path parity, and the theme-toggle island's retained-module list — the last two read off the `minify: false` banners, never a byte allowance |

package/README.md

@@ -21,10 +21,22 @@ channels** so `rgb(var(--color-accent) / 0.12)` gives a tint with no extra token
 | `accent` / `accent-strong` / `accent-fg` | primary action, its hover, text on it |
 | `success` / `warning` / `danger` / `info` | status solid, each with a `-soft` tint and a `-fg` text-on-solid |
 
-Scales: `--space-*` (4px base), `--text-*` (fluid `clamp()`), `--radius-*`,
+Scales: `--space-*` (4px base), `--stroke-*` (line weights: `hairline thick heavy`), `--text-*` (fluid `clamp()`), `--radius-*`,
 `--shadow-*` (themed — dark gets deeper, higher-alpha shadows), `--duration-*`,
 `--easing-*`, `--z-*` (named ladder, no magic numbers).
 
+Authoring helpers, from the same `@use '@ultimat3/ui/tokens' as t` — an app writes no mixin of its own for any of them:
+
+| Helper | Emits |
+|---|---|
+| `@include t.respond-to(md)` | `@media (min-width: 768px)` — the rung and wider |
+| `@include t.respond-down(md)` | `@media (max-width: 767.98px)` — narrower than the rung; 0.02px under it, so no width matches both arms |
+| `@include t.respond-between(md, lg)` | `@media (min-width: 768px) and (max-width: 1023.98px)` |
+| `t.rem(24px)` | `1.5rem` — px, rem or a unitless px count in; `t.rem(20px, 10px)` states another root |
+| `t.fluid(1rem, 2rem, 20rem, 80rem)` | `clamp(1rem, 0.6666666667rem + 1.6666666667vw, 2rem)` — the first size at a 20rem viewport, the second at 80rem (the default range), linear between. Takes px too; a size that shrinks is legal |
+
+A rung is `sm md lg xl 2xl`, quoted or bare. Prefer a container query (`t.container` + `t.container-query`) to all three breakpoint mixins.
+
 ## The law
 
 | Rule | Enforcement |
@@ -193,7 +205,7 @@ commit the diff. There is no hand-edited icon in the package.
 
 ## Works without JavaScript
 
-Three components are interactive without a client runtime, because the platform already
+These components are interactive without a client runtime, because the platform already
 has the behaviour. Each is correct server-rendered, and the script layer only adds.
 
 | Component | Platform base | The enhancement |
@@ -201,6 +213,8 @@ has the behaviour. Each is correct server-rendered, and the script layer only ad
 | `Accordion` | `<details>` / `<summary>`; `exclusive` is the native `name` group | `onToggle` notification, after the browser has applied it |
 | `Combobox` | `<input list>` + `<datalist>` — typing, filtering, keyboard, mobile | `onFilter`, debounced, for a live/server-side query |
 | `InfiniteScroll` | a real `rel="next"` link to the next page | an `IntersectionObserver` sentinel that calls `onLoadMore` and intercepts the click |
+| `Pagination` with `hrefFor` | `<a rel="next">` / `<a rel="prev">`, one per cursor | none — link mode attaches no handler |
+| `Link appearance="button"` | an `<a href>` wearing Button's classes | none |
 
 ```tsx
 <Accordion level={3} exclusive items={[{ id: 'ship', title: t('faq.ship'), panel: <p>…</p> }]} />
@@ -217,6 +231,47 @@ scripting off the control is a link, and a link needs somewhere to go. `Combobox
 what it is given by `value` (`filterOptions` — case- and accent-insensitive, prefix first),
 so the list is right on the first paint and after a form round-trip, not only once JS runs.
 
+### A pager and a button that navigate
+
+```tsx
+import { Link, Pagination } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+
+interface PostsFooterProps {
+  prevCursor?: string | undefined;
+  nextCursor?: string | undefined;
+  /** Already translated: `t('posts.new')` at the call site. */
+  newLabel: string;
+}
+
+export function PostsFooter(props: PostsFooterProps): JSX.Element {
+  return (
+    <footer>
+      <Link appearance="button" variant="secondary" size="sm" href="/posts/new">
+        {props.newLabel}
+      </Link>
+      <Pagination
+        prevCursor={props.prevCursor}
+        nextCursor={props.nextCursor}
+        hrefFor={(cursor, direction) =>
+          `/posts?${direction === 'next' ? 'after' : 'before'}=${cursor}`
+        }
+      />
+    </footer>
+  );
+}
+```
+
+| Rule | Held by |
+|---|---|
+| `Pagination` is one mode per use: `hrefFor`, or `onCursor` / `onPage` / `page` / `totalPages` — never both | the type: `PaginationProps` is `PaginationLinkProps \| PaginationCallbackProps`, and each forbids the other's props |
+| `DataTable` takes the same pair — `hrefFor` or `onCursor` — and hands it to its pager | the type: `DataTableProps<Row>` is `DataTableLinkProps<Row> \| DataTableCallbackProps<Row>` |
+| a `DataTable` sort header follows the table's mode: an anchor at `sortHrefFor(next)` in link mode, a button calling `onSortChange` in callback mode; a linked table with no `sortHrefFor` renders the header as text | the same union — `sortHrefFor` lives on `DataTableLinkProps`, `onSortChange` on `DataTableCallbackProps` — and `DataTable.test.ts` |
+| link mode pages by cursor only; a side with no cursor is a disabled button, never an anchor with nowhere to go | `Pagination.test.ts` |
+| a control that navigates is a `Link`; `Button` has no `href` | `ButtonProps` |
+| a button-link takes `variant` / `tone` / `size` / `fullWidth` / `iconStart` / `iconEnd`; a text link takes `underline` and `tone: 'accent' \| 'inherit'` | the type: `LinkProps` is `TextLinkProps \| ButtonLinkProps` |
+| both elements wear ONE set of classes | `buttonClassKeys` (`button-classes.ts`), asked by `Button` and `Link` |
+
 `debounce(fn, ms)` is exported on its own: trailing edge, `cancel()`, `flush()`, `pending()`.
 Components cancel theirs on cleanup, so a filter never fires into a tree that is gone.
 
@@ -539,13 +594,13 @@ of truth for the one thing the server decides.
 
 | Code | When |
 |---|---|
-| `X_TOKEN_UNKNOWN` | a token role the SCSS source does not define — including a `defineTheme()` override of a role, radius or font slot that is not in the scale |
+| `X_TOKEN_UNKNOWN` | a token role the SCSS source does not define — including a `defineTheme()` override of a role, radius or font slot that is not in the scale, and a breakpoint rung `respond-to` / `respond-down` / `respond-between` was handed that is not in `$breakpoints` (a Sass `@error`: the stylesheet does not compile) |
 | `X_THEME_INVALID` | a theme other than `light` / `dark` |
 | `X_UI_RUNTIME_MISSING` | a DOM render with no registered Solid runtime, `<UiProvider>` on the server, or `browserThemeEnv()` off-DOM. A server render with no runtime is **not** one of them — it gets `INERT_SOLID_RUNTIME` |
 | `X_UI_FORM_PATH_INVALID` | a form field or control name the path grammar cannot read (`items.0.price`, `items[]`, `__proto__`), or two control names describing different shapes for one path (`user` beside `user.name`) |
 | `X_UI_CONTRAST_INSUFFICIENT` | a `defineTheme()` palette whose resolved channels put a pairing in `CONTRAST_PAIRS` below WCAG 2.2 AA — 4.5:1 for text, 3:1 for the focus ring. Only pairings the brand changed are measured; the cause names the measured ratio and the required one |
 | `X_UI_QR_CAPACITY` | a `<QrCode>` value over version 3's 42-byte ceiling (byte mode, error-correction level M). The encoder draws versions 1–3 only; the cause names the byte count and the ceiling |
-| `X_UI_INVALID_VALUE` | `<Money>` given a float, `<DateTime>` given an unparseable instant, `<Image>` given mixed `w`/`x` descriptors, one dimension without the other, or no reserved box at all, a heading level off 1–6, a `defineTheme()` value that is not a token value, an `<Icon>` glyph with a tag/attribute/colour outside `ICON_TAGS`, two `Accordion` items sharing an id, `InfiniteScroll` with `hasMore` and no `nextHref`, a negative `debounce` window, or (`As of 2026-08`) upstream icon data `bun run icons` refuses (not an object, no renderable nodes, an attribute value that is not glyph geometry) |
+| `X_UI_INVALID_VALUE` | `<Money>` given a float, `<DateTime>` given an unparseable instant, `<Image>` given mixed `w`/`x` descriptors, one dimension without the other, or no reserved box at all, a heading level off 1–6, a `defineTheme()` value that is not a token value, an `<Icon>` glyph with a tag/attribute/colour outside `ICON_TAGS`, two `Accordion` items sharing an id, `InfiniteScroll` with `hasMore` and no `nextHref`, a negative `debounce` window, or (`As of 2026-08`) upstream icon data `bun run icons` refuses (not an object, no renderable nodes, an attribute value that is not glyph geometry), or — as a Sass `@error` — `t.rem()` / `t.fluid()` given a unit other than px or rem, `t.fluid()` given a viewport range that is empty or reversed, `respond-between` given `$from` at or above `$to` |
 
 ### Error classes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ui",
-  "version": "22.15.0",
+  "version": "23.0.0",
   "description": "SolidJS design system: semantic design tokens, dark/RTL-ready SCSS modules, a11y primitives",
   "license": "MIT",
   "type": "module",
@@ -33,6 +33,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CATALOG.md",
     "CLAUDE.md",
     "README.md",
@@ -48,10 +49,10 @@
     "icons": "bun run src/icons/build-icons.ts"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/i18n": "22.15.0",
-    "@ultimat3/money": "22.15.0",
-    "@ultimat3/time": "22.15.0"
+    "@ultimat3/core": "23.0.0",
+    "@ultimat3/i18n": "23.0.0",
+    "@ultimat3/money": "23.0.0",
+    "@ultimat3/time": "23.0.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"

package/src/catalog/parse-component.ts

@@ -46,12 +46,64 @@ export function headerComment(source: string): string {
   return lines.join(' ').trim();
 }
 
-/** The members of `export interface <name> { … }`, generics and all. */
-export function parseProps(source: string, interfaceName: string): PropDoc[] {
-  const body = interfaceBody(source, interfaceName);
-  if (body === undefined) return [];
+/**
+ * Every prop a caller may write for `<name>`: the members of `interface <name>`, its bases' first,
+ * or — where `<name>` is `type <name> = A | B`, one interface per mode — the modes merged.
+ */
+export function parseProps(source: string, typeName: string): PropDoc[] {
+  const modes = unionMembers(source, typeName);
+  if (modes === undefined) return interfaceProps(source, typeName);
+  return mergeModes(modes.map((mode) => interfaceProps(source, mode)));
+}
 
-  const props: PropDoc[] = [];
+/** `GridLinkProps<Row>` names the interface `GridLinkProps`. */
+const withoutTypeArguments = (name: string): string => name.replace(/<[^>]*>/, '').trim();
+
+/** `A`, `B` out of `export type <name> = A | B;`. `undefined` when `<name>` is not such an alias. */
+function unionMembers(source: string, typeName: string): string[] | undefined {
+  const alias = new RegExp(`export type ${typeName}(?:<[^>]*>)?\\s*=\\s*([\\w\\s|<>]+);`).exec(
+    source,
+  );
+  return alias?.[1]
+    ?.split('|')
+    .map((member) => withoutTypeArguments(member))
+    .filter((member) => member !== '');
+}
+
+/**
+ * One row per prop across modes. Required only when EVERY mode requires it — a prop one mode
+ * forbids is optional to a reader choosing between them — and typed as each mode types it.
+ */
+function mergeModes(modes: readonly (readonly PropDoc[])[]): PropDoc[] {
+  const merged = new Map<string, PropDoc>();
+  for (const props of modes) {
+    for (const prop of props) {
+      const seen = merged.get(prop.name);
+      if (seen === undefined) {
+        merged.set(prop.name, prop);
+        continue;
+      }
+      merged.set(prop.name, {
+        name: prop.name,
+        type: seen.type === prop.type ? seen.type : `${seen.type} | ${prop.type}`,
+        required: seen.required && prop.required,
+        doc: seen.doc === '' ? prop.doc : seen.doc,
+      });
+    }
+  }
+  return [...merged.values()].map((prop) => ({
+    ...prop,
+    required: prop.required && modes.every((props) => props.some((p) => p.name === prop.name)),
+  }));
+}
+
+/** The members of `interface <name> { … }`, generics and all, after those of every base. */
+function interfaceProps(source: string, interfaceName: string): PropDoc[] {
+  const declared = interfaceDeclaration(source, interfaceName);
+  if (declared === undefined) return [];
+  const { body, bases } = declared;
+
+  const own: PropDoc[] = [];
   let doc: string[] = [];
   let buffer = '';
   let depth = 0;
@@ -68,11 +120,16 @@ export function parseProps(source: string, interfaceName: string): PropDoc[] {
     // A member ends at a `;` that is not inside a function type or an inline object type.
     if (depth > 0 || !buffer.endsWith(';')) continue;
     const prop = toProp(buffer, doc.join(' ').trim());
-    if (prop !== undefined) props.push(prop);
+    if (prop !== undefined) own.push(prop);
     buffer = '';
     doc = [];
   }
-  return props;
+
+  const names = new Set(own.map((prop) => prop.name));
+  const inherited = bases
+    .flatMap((base) => interfaceProps(source, base))
+    .filter((prop) => !names.has(prop.name));
+  return [...inherited, ...own];
 }
 
 function isComment(line: string): boolean {
@@ -105,9 +162,13 @@ function toProp(declaration: string, doc: string): PropDoc | undefined {
   const match = /^(?:readonly\s+)?('[^']+'|"[^"]+"|\w+)(\?)?:\s*([\s\S]+);$/.exec(declaration);
   if (match === null) return undefined;
   const [, rawName = '', optional, rawType = ''] = match;
+  const type = normaliseType(rawType);
+  // `hrefFor?: undefined` is how one mode of a union forbids another mode's prop: a member that
+  // exists so the prop CANNOT be written is not a prop.
+  if (type === '' || type === 'never') return undefined;
   return {
     name: rawName.replace(/^['"]|['"]$/g, ''),
-    type: normaliseType(rawType),
+    type,
     required: optional === undefined,
     doc,
   };
@@ -126,17 +187,29 @@ function normaliseType(type: string): string {
   );
 }
 
-/** Brace-matched so a nested object type does not end the interface early. */
-function interfaceBody(source: string, interfaceName: string): string | undefined {
-  const header = new RegExp(`export interface ${interfaceName}(?:<[^>]*>)?\\s*\\{`).exec(source);
+/**
+ * Brace-matched so a nested object type does not end the interface early. `export` is optional:
+ * a base shared by two modes is a detail of the file, and its members are still the component's.
+ */
+function interfaceDeclaration(
+  source: string,
+  interfaceName: string,
+): { readonly body: string; readonly bases: readonly string[] } | undefined {
+  const header = new RegExp(
+    `(?:export )?interface ${interfaceName}(?:<[^>]*>)?(?:\\s+extends\\s+([\\w\\s,<>]+?))?\\s*\\{`,
+  ).exec(source);
   if (header === null) return undefined;
+  const bases = (header[1] ?? '')
+    .split(',')
+    .map((base) => withoutTypeArguments(base))
+    .filter((base) => base !== '');
   const start = header.index + header[0].length;
   let depth = 1;
   for (let i = start; i < source.length; i += 1) {
     const char = source[i];
     if (char === '{') depth += 1;
     if (char === '}') depth -= 1;
-    if (depth === 0) return source.slice(start, i);
+    if (depth === 0) return { body: source.slice(start, i), bases };
   }
   return undefined;
 }

package/src/catalog/render-catalog.ts

@@ -13,6 +13,7 @@ import {
   lineHeightTokens,
   radiusTokens,
   spaceTokens,
+  strokeTokens,
   zTokens,
 } from '../tokens/tokens';
 import type { ComponentDoc } from './parse-component';
@@ -99,6 +100,8 @@ ${scaleTable('Space — `--space-*`', spaceTokens)}
 
 ${scaleTable('Radius — `--radius-*`', radiusTokens)}
 
+${scaleTable('Stroke — `--stroke-*`', strokeTokens)}
+
 ${scaleTable('Font size — `--text-*`', fontSizeTokens)}
 
 ${scaleTable('Font weight — `--weight-*`', fontWeightTokens)}
@@ -111,6 +114,23 @@ ${scaleTable('Easing — `--easing-*`', easingTokens)}
 
 ${scaleTable('Z-index — `--z-*`', zTokens)}
 
-${scaleTable('Breakpoints — `@include t.respond-to(<name>)`', breakpointTokens)}
+${scaleTable('Breakpoints — `respond-to` · `respond-down` · `respond-between`', breakpointTokens)}
+
+\`@include t.respond-to(md)\` is \`md\` and wider, \`t.respond-down(md)\` is narrower than \`md\`, and
+\`t.respond-between(md, lg)\` is \`md\` up to \`lg\`. A max-width arm stops 0.02px under its rung, so
+no width matches two of them.
+
+### Computed lengths
+
+${table(
+  ['Function', 'Answers'],
+  [
+    ['`t.rem(24px)`', '`1.5rem` — px, rem or a unitless px count in, rem out'],
+    [
+      '`t.fluid(1rem, 2rem, 20rem, 80rem)`',
+      'one `clamp()`: the first size at a 20rem viewport, the second at 80rem, linear between',
+    ],
+  ],
+)}
 `;
 }

package/src/components/Avatar.module.scss

@@ -47,7 +47,7 @@
     inset-inline-end: 0;
     inline-size: 28%;
     block-size: 28%;
-    border: 2px solid t.role('surface');
+    border: t.stroke(thick) solid t.role('surface');
     border-radius: t.radius(full);
     content: '';
   }

package/src/components/BarChart.module.scss

@@ -26,6 +26,17 @@
   }
 }
 
+// The second series — what went wrong, stacked on what went right.
+.secondary {
+  fill: t.role('danger');
+  opacity: 0.6;
+  transition: opacity t.duration(fast) t.easing(out);
+
+  &:hover {
+    opacity: 1;
+  }
+}
+
 .last {
   opacity: 1;
 }
@@ -36,7 +47,7 @@
   // SVG text scales with the chart: below `sm` these shrink to unreadable specks, and an
   // unreadable label is noise. Every bar still carries its `<title>`.
   display: none;
-  font-size: 8px;
+  font-size: t.rem(8px);
   fill: t.role('fg-muted');
 
   @include t.respond-to(sm) {