@ultimat3/ui 19.4.0 → 20.0.0

package/CATALOG.md

@@ -4,7 +4,7 @@
 
 Every component and every token, projected from source. Import all of it from `@ultimat3/ui`.
 
-52 components: `Accordion` · `Alert` · `AppShell` · `Avatar` · `Badge` · `Breadcrumb` · `Button` · `Card` · `Checkbox` · `Combobox` · `Container` · `DataTable` · `DateTime` · `Dialog` · `Divider` · `Drawer` · `Dropzone` · `EmptyState` · `ErrorState` · `Field` · `FileInput` · `Form` · `Grid` · `Icon` · `IconButton` · `Image` · `InfiniteScroll` · `Input` · `Link` · `LocaleSwitcher` · `Menu` · `Money` · `PageHeader` · `Pagination` · `Popover` · `Radio` · `RelativeTime` · `Section` · `Select` · `Skeleton` · `Spinner` · `Stack` · `Switch` · `Table` · `Tabs` · `Text` · `Textarea` · `ThemeToggle` · `ToastRegion` · `Toast` · `Toolbar` · `Tooltip`
+54 components: `Accordion` · `Alert` · `AppShell` · `AsyncRegion` · `Avatar` · `Badge` · `Breadcrumb` · `Button` · `Card` · `Checkbox` · `Combobox` · `Container` · `DataTable` · `DateTime` · `Dialog` · `Divider` · `Drawer` · `Dropzone` · `EmptyState` · `ErrorState` · `Field` · `FileInput` · `Form` · `Grid` · `Icon` · `IconButton` · `Image` · `InfiniteScroll` · `Input` · `Link` · `LocaleSwitcher` · `Menu` · `Money` · `PageHeader` · `Pagination` · `Popover` · `Radio` · `RelativeTime` · `Section` · `Select` · `Skeleton` · `Spinner` · `Stack` · `Switch` · `Table` · `Tabs` · `Text` · `Textarea` · `ThemeToggle` · `ToastRegion` · `Toast` · `Toaster` · `Toolbar` · `Tooltip`
 
 ## Vocabulary
 
@@ -61,6 +61,20 @@ The page frame every app screen sits in: skip link, banner, navigation, main, co
 | `stickyHeader` | `boolean` | — | Keeps the header pinned while the main region scrolls. |
 | `class` | `string` | — |  |
 
+### AsyncRegion
+
+The one way to render a region whose content has to arrive. Four branches, decided by `asyncBranch` and never by the caller: a skeleton while it loads, the error report when it fails, the empty state when a completed result held nothing, and the content.  `empty` and `ready` are REQUIRED props, so a region that forgot what "nothing here" looks like is a type error rather than a review comment. `pending` and `failed` are not props at all — the placeholder is derived from `reserve` so it cannot mismatch the loaded box, and the failure renders through `ErrorState`, which is the one thing allowed to phrase an error.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `state` | `AsyncState<T>` | yes | A live-query accessor, a resource, or a plain signal — narrowed to one of four shapes. |
+| `reserve` | `ReserveBox` | yes | The box the placeholder holds, and the box the loaded content lands in. Same value, once. |
+| `ready` | `(data: T) => JSX.Element` | yes | The content. Called only with data a completed result actually carried. |
+| `empty` | `() => JSX.Element` | yes | Required with no default: "nothing here yet" is a screen, not an oversight, and `EmptyState` is one line of it — `empty={() => <EmptyState title={t('posts.none')} />}`. |
+| `isEmpty` | `((data: T) => boolean)` | — | Emptiness for a shape that is not a list. Defaults to `isEmptyData`. |
+| `onRetry` | `(() => void)` | — | Passed straight to `ErrorState` on the failed branch. |
+| `class` | `string` | — |  |
+
 ### Avatar
 
 Identity chip. An avatar image always carries intrinsic dimensions and an empty alt (the name is rendered as text or the accessible label), so it can never shift layout or duplicate the name to a screen reader.
@@ -99,7 +113,7 @@ Ancestor trail. The last item is the current page: rendered as text, never a lin
 
 ### Button
 
-The one button. Variants and tones are token-driven, so dark mode and RTL need no extra rules; `loading` keeps the label mounted to avoid a layout jump.
+The one button. Variants and tones are token-driven, so dark mode and RTL need no extra rules; `loading` keeps the label mounted to avoid a layout jump.  `loading` does NOT set the native `disabled` attribute, and that WILL read as a mistake — it set one until 2026-09. Four things go wrong when a control disables itself mid-flow: the browser moves focus off it to `<body>`, so a keyboard user's next Tab restarts at the top of the document; a disabled control is exempt from WCAG's contrast minimum, so the state the user most needs to read is the one allowed to be unreadable; it explains nothing, because `disabled` has no announced reason; and it does not actually prevent the double submit, which is a race on the server. `aria-disabled` says unavailable and keeps the control focusable, the click is refused here, and the form refuses it again — `Form busy` — because the button is not the only way in.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -191,7 +205,7 @@ Centred measure with a gutter. `margin-inline: auto` and `min()` mean one declar
 
 ### DataTable
 
-Data-driven table: sortable headers, cursor pagination, and the four states a real list always has (loading, error, empty, data). The error state renders an UltimateError with the same code/cause/fix strings the terminal prints.
+Data-driven table: sortable headers, cursor pagination, and the four states a real list always has (loading, error, empty, data). The error state renders an UltimateError with the same code/cause/fix strings the terminal prints.  The four-way decision itself is NOT here — it is `asyncBranch`, shared with `AsyncRegion`, so a table and a card list cannot disagree about what "loading with stale rows" looks like. Only the PLACEHOLDER is local, because a table's is table-shaped: rows of cells, not lines of text.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -355,7 +369,7 @@ A file picker that keeps the platform control and dresses it. The native button
 
 ### Form
 
-Form shell. Owns the one thing every form needs and always forgets: a top-of-form error summary that is announced (the Alert inside it is a live region) and that TAKES focus when an error arrives — the focus move is what makes the summary reachable at all, since its id is internal.
+Form shell. Owns the one thing every form needs and always forgets: a top-of-form error summary that is announced (the Alert inside it is a live region) and that TAKES focus when an error arrives — the focus move is what makes the summary reachable at all, since its id is internal.  Focus goes to the first INVALID CONTROL when there is one, and to the summary only when there is not. GOV.UK's tested pattern is a summary whose entries LINK to their fields; that shape is not available here, because `Field` mints its control ids internally (`Field.tsx`) and inverting that ownership is the drift `Field` exists to prevent — a summary cannot write an `href` to an id it cannot see. Focusing the control directly reaches the same place in one step. The summary still announces, and is still where a form-level rejection (a policy refusal, an unmatched issue) puts the reader, because that one names no control to send them to.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -363,6 +377,8 @@ Form shell. Owns the one thing every form needs and always forgets: a top-of-for
 | `error` | `string` | — | Already-translated summary shown above the fields when submit fails. |
 | `errorTitle` | `string` | — | Already-translated heading for the error summary region. |
 | `actions` | `JSX.Element` | — |  |
+| `invalidField` | `string` | — | The `name` of the control a failed submit should send the reader to — `form.firstInvalidField()`. Focused in preference to the summary: the summary describes the problem, the control is where it is fixed, and leaving the user on the summary strands them one Tab away from nothing. |
+| `busy` | `boolean` | — | A submit is in flight — `form.pending()`. Suppresses the submit outright, so a double submit is refused HERE and not only on whatever control happened to be clicked: Enter in a text field submits a form with no button involved at all. |
 | `gap` | `SpaceStep` | — |  |
 | `method` | `'get' \| 'post'` | — |  |
 | `action` | `string` | — |  |
@@ -777,7 +793,9 @@ Transient notification. ToastRegion is the single live region for the app; indiv
 | `children` | `JSX.Element` | yes |  |
 | `label` | `string` | yes | Already-translated landmark name, e.g. "Notifications". |
 | `politeness` | `Politeness` | — | How the region announces. `polite` waits for a pause and is right for everything an app routinely confirms; `assertive` interrupts whatever the user is being read, so it belongs only to a region that carries errors alone. One region, one politeness — mixing tones inside one list cannot work, because the live semantics belong to the list, not to the message. |
-| `placement` | `'block-end-inline-end' \| 'block-start-inline-end' \| 'block-end-center'` | — |  |
+| `placement` | `ToastPlacement` | — |  |
+| `onHold` | `((reason: ToastHold) => void)` | — | Stop the dwell while the reader is engaged with the stack, and start it again when they leave. WCAG 2.2 2.2.1 wants a timing the user can extend, and a message that expires under the pointer reaching for its undo is the failure that rule is about.  Two reasons, reported separately: a pointer leaving a toast a keyboard user is still inside must not restart the countdown, which one boolean cannot express. |
+| `onRelease` | `((reason: ToastHold) => void)` | — |  |
 | `class` | `string` | — |  |
 
 ### Toast
@@ -794,6 +812,19 @@ Transient notification. ToastRegion is the single live region for the app; indiv
 | `dismissLabel` | `string` | — |  |
 | `class` | `string` | — |  |
 
+### Toaster
+
+The one way to render a toast queue: the store's VISIBLE slice, inside the region that owns the live semantics. The half that was missing — `Toast` and `ToastRegion` shipped with no store, so every app wrote its own queue, its own dwell and its own pause rules.  Toasts over the cap are not drawn and not counted on screen: they are still queued, and their dwell has not started. A "+3 more" badge would be a message about messages, in a corner the reader is already being asked to look away to.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `store` | `ToastStore` | yes | The queue. One per app — `createToastStore()` in the island that mounts this. |
+| `label` | `string` | yes | Already-translated landmark name, e.g. "Notifications". |
+| `politeness` | `Politeness` | — |  |
+| `placement` | `ToastPlacement` | — |  |
+| `dismissLabel` | `string` | — | Already-translated; falls back to the `ui.dismiss` catalog key. |
+| `class` | `string` | — |  |
+
 ### Toolbar
 
 The control strip above a table or a list: filters and search at the inline start, actions at the inline end. `role="toolbar"` with the same roving-tabindex helper Tabs uses, so arrow keys move between the strip's buttons. It is NOT one tab stop: the strip holds arbitrary children it cannot reach into to set an initial `tabindex`, and a search field at the inline start keeps its own arrow keys, so making the strip a single stop would strand every control past it.

package/CLAUDE.md

@@ -40,6 +40,51 @@ Tier 4 (moved 5 → 4 on 2026-08-19, when the `admin → ui` exception was delet
 - **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.
 - **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` 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.
 - **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.
@@ -68,6 +113,12 @@ Tier 4 (moved 5 → 4 on 2026-08-19, when the `admin → ui` exception was delet
 | `src/tokens/contrast.ts` | WCAG ratios over the channel tokens; `contrast.test.ts` gates AA in both themes |
 | `src/catalog/` | parses `components/*.tsx` into `CATALOG.md`; `bun run catalog` writes it, `catalog.test.ts` fails on drift |
 | `src/roving.ts` | the pure rules of a keyboard group: navigable set, tab stop, who keeps their own arrows |
+| `src/components/async-branch.ts` | the one `(pending, failed, empty, ready)` decision, plus the `reserve` box both the placeholder and the loaded content land in |
+| `src/toast/toast-state.ts` | the toast queue's pure rules: dedupe, the visible cap, and what a tick may spend |
+| `src/toast/toast-store.ts` | the same queue with a clock and the three pause holds; `ToastEnv` is the injected host |
+| `src/toast/use-toasts.ts` | the Solid shell: the store's queue in a signal, subscribed from an effect so a server render never does |
+| `src/form/form-touch.ts` | touched and dirty — progress through a form, never a second copy of its values |
+| `src/tokens/contrast-pairs.ts` | every pairing a component renders, with its AA floor; read by `defineTheme()` and by `contrast.test.ts` |
 | `src/form/field-path.ts` | the one path grammar, both directions — pure, and deliberately free of `../errors` so mapping an issue costs no chunk the error registry |
 | `src/form/form-issue.ts` | the two readers of an issue: a local parse result, and whatever the server rejected with |
 | `src/form/form-state.ts` | where an issue LANDS — the declared field, or the form |

package/README.md

@@ -51,6 +51,88 @@ roleContrast('dark', 'accent', 'bg') >= AA_TEXT;   // true
 contrastRatio('31 110 178', '253 246 240');        // 4.99 — check a brand before shipping it
 ```
 
+`As of 2026-09` **a brand override is measured too, and a failing one is refused.**
+`defineTheme()` resolves your channels over the shipped palette and checks every pairing in
+`CONTRAST_PAIRS` — the same table the framework's own palette is held to — throwing
+`X_UI_CONTRAST_INSUFFICIENT` with the measured ratio, the required one and the role to move.
+Only pairings your brand can have *changed* are measured: a new `accent` against the shipped
+white `accent-fg` is the commonest way a palette goes unreadable, and it is half a pair.
+WCAG 2.2 AA, never APCA — APCA is not a standard, and AA is the operative legal benchmark.
+
+```ts
+import { defineTheme } from '@ultimat3/ui';
+
+defineTheme({ colors: { light: { accent: '235 235 235' } } });
+// X_UI_CONTRAST_INSUFFICIENT: defineTheme() light palette renders the label on a primary Button:
+// "accent-fg" on "accent" measures 1.09:1, and WCAG 2.2 AA requires 4.5:1
+```
+
+## One async region
+
+Four states, one decision. `asyncBranch` is the only place `(pending, failed, empty, ready)` is
+decided — `<AsyncRegion>` renders it, `<DataTable>` calls it, and an app's own list can call it too.
+
+```tsx
+import { AsyncRegion, asyncStateOf, EmptyState } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+
+declare const posts: { loading: boolean; error: unknown; latest: readonly string[] | undefined };
+declare const t: (key: string) => string;
+declare const PostList: (props: { rows: readonly string[] }) => JSX.Element;
+declare const refetch: () => void;
+
+const region = (
+  <AsyncRegion
+    state={asyncStateOf({ loading: posts.loading, error: posts.error, data: posts.latest })}
+    reserve={{ lines: 5, height: '3rem' }}
+    empty={() => <EmptyState title={t('posts.none')} />}
+    ready={(rows) => <PostList rows={rows} />}
+    onRetry={() => refetch()}
+  />
+);
+```
+
+`empty` and `ready` are **required**, so forgetting the empty state is a type error rather than a
+review comment. Three properties are structural, not documented:
+
+- **`empty` is unreachable while pending.** A `pending` state carries no data, so nothing can be
+  found empty in it — "No results" before the first page arrives is unconstructible.
+- **A refetch keeps the previous data.** `refreshing` carries it: the current page stays rendered
+  and dimmed under `aria-busy`, and the empty branch is reachable only from a *completed* result
+  that returned zero. `<DataTable loading>` with rows behaves the same way.
+- **The placeholder shares the loaded box.** `reserve` feeds the `<Skeleton>` *and* the
+  `min-block-size` of every branch, so a skeleton that resizes on load — a slower layout shift —
+  cannot be written.
+
+## Toasts
+
+`Toast` and `ToastRegion` render; `createToastStore()` is the queue behind them, and `<Toaster>` is
+the one way to draw it.
+
+```tsx
+import { createToastStore, Toaster } from '@ultimat3/ui';
+
+declare const t: (key: string) => string;
+declare const restore: () => void;
+
+const toasts = createToastStore();
+toasts.show({ message: t('post.saved'), tone: 'success' });
+toasts.show({ message: t('post.deleted'), action: { label: t('undo'), onAction: restore } });
+
+const region = <Toaster store={toasts} label={t('notifications')} />;
+```
+
+Auto-dismiss on a **token** (`short` 4s, `long` 8s, `sticky` never), a three-deep visible cap with
+the rest queued — a queued toast has not started its dwell, because nobody has read it — identical
+messages deduped rather than stacked, and the countdown held for three independent reasons: pointer
+over the stack, focus inside it, **and `document.hidden`**. The last is the one everybody forgets
+and the only one that loses the message outright: a backgrounded tab spends the whole dwell and the
+corner is empty when the user comes back.
+
+A toast never takes focus, never carries the only copy of anything, and carries at most one
+undo-shaped action. The region renders server-side and empty, which is what makes it announce at
+all — a live region created with its content already inside it is not read.
+
 ## Page layout
 
 Four composites cover the frame of an app screen. Below them are `Container`,
@@ -432,6 +514,25 @@ expected number`) — `packages/action/src/errors.ts` puts nothing in `meta`, an
 field only when the head is a declared path, so a message holding `'; '` or `': '` degrades to a
 form-level error rather than to a wrong control.
 
+### The submit state, and why `disabled` is refused
+
+`form.pending()` is the one value that reaches both halves: `<Button loading>` and `<Form busy>`.
+Neither sets the native `disabled` attribute, and that is deliberate — a control that disables
+itself mid-flow drops focus to `<body>`, is exempt from the contrast minimum, announces no reason,
+and does not actually prevent the double write, which is a race on the server. `aria-disabled` says
+unavailable and keeps the control focusable; the click is refused in the component, and `<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** (`form.firstInvalidField()`, in declaration
+order — a server may report the last field first), and the announced summary keeps the focus only
+when the rejection names no control at all. `form.touch(path)` and `form.edit(path, value)` record
+touched and dirty against the binding's `initial`; an empty control and an absent baseline are the
+same thing, so deleting what you just typed leaves the form clean.
+
+Blur-time validation is deliberately **absent**: this binding is server-authoritative, the local
+parse's value is already discarded, and a client-side "is this field valid" would be a second source
+of truth for the one thing the server decides.
+
 ## Errors
 
 | Code | When |
@@ -440,6 +541,7 @@ form-level error rather than to a wrong control.
 | `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_INVALID_VALUE` | `<Money>` given a float, `<DateTime>` given an unparseable instant, `<Image>` given mixed `w`/`x` descriptors or one dimension without the other, 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) |
 
 ## Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ui",
-  "version": "19.4.0",
+  "version": "20.0.0",
   "description": "SolidJS design system: semantic design tokens, dark/RTL-ready SCSS modules, a11y primitives",
   "license": "MIT",
   "type": "module",
@@ -44,10 +44,10 @@
     "icons": "bun run src/icons/build-icons.ts"
   },
   "dependencies": {
-    "@ultimat3/core": "19.4.0",
-    "@ultimat3/i18n": "19.4.0",
-    "@ultimat3/money": "19.4.0",
-    "@ultimat3/time": "19.4.0"
+    "@ultimat3/core": "20.0.0",
+    "@ultimat3/i18n": "20.0.0",
+    "@ultimat3/money": "20.0.0",
+    "@ultimat3/time": "20.0.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"

package/src/a11y.ts

@@ -218,22 +218,61 @@ export type Politeness = 'polite' | 'assertive';
  */
 const LIVE_REGION_ID = 'ultimate-live-region';
 
+/** Both levels, in the order `AppShell` emits them. One region per politeness, never per message. */
+export const LIVE_REGION_LEVELS: readonly Politeness[] = ['polite', 'assertive'];
+
+/** The attributes ONE live region carries. */
+export interface LiveRegionAttrs {
+  readonly id: string;
+  readonly class: string;
+  readonly role: 'status' | 'alert';
+  readonly 'aria-live': Politeness;
+  readonly 'aria-atomic': 'true';
+}
+
 /**
- * Announce a message to assistive tech. Uses one persistent region per
- * politeness level, because creating a region and writing to it in the same
- * frame is not announced by most screen readers.
+ * One derivation, read by both halves — `AppShell`, which renders these regions into the SERVER
+ * response, and `announce()`, which writes into them. That ordering is the reason this exists at
+ * all: a live region created and filled in the same frame is not announced by most screen readers,
+ * so the region that carries the first message has to predate the message. `announce()`'s own
+ * fallback (below) can only ever be right from its second call onwards; a shell that already
+ * emitted the region makes the first one right too.
+ *
+ * `aria-atomic="true"` is correct HERE and wrong on `ToastRegion`'s `<ol>`: this element holds one
+ * message at a time and is re-read whole, where the toast list holds several and must announce
+ * only the arrival.
+ */
+export function liveRegionAttrs(politeness: Politeness): LiveRegionAttrs {
+  return {
+    id: `${LIVE_REGION_ID}-${politeness}`,
+    class: LIVE_REGION_ID,
+    role: politeness === 'assertive' ? 'alert' : 'status',
+    'aria-live': politeness,
+    'aria-atomic': 'true',
+  };
+}
+
+/**
+ * Announce a message to assistive tech — for a state change with no surface of its own: "12
+ * results", "sorted by name, descending", "page 3 of 9". NOT for a notification, which is a
+ * `Toast` in the `ToastRegion` that owns its own live semantics; two announcement paths for one
+ * message is how a screen reader ends up reading it twice.
+ *
+ * Writes into the region `AppShell` already rendered. The create-if-absent branch is the fallback
+ * for a tree with no shell, and it carries this module's known limit: the region it builds is
+ * appended and written in the same frame, so the FIRST message through it may be silent.
  */
 export function announce(message: string, politeness: Politeness = 'polite'): void {
   if (typeof document === 'undefined') return;
-  const id = `${LIVE_REGION_ID}-${politeness}`;
-  let region = document.getElementById(id);
+  const attrs = liveRegionAttrs(politeness);
+  let region = document.getElementById(attrs.id);
   if (region === null) {
     region = document.createElement('div');
-    region.id = id;
-    region.className = LIVE_REGION_ID;
-    region.setAttribute('role', politeness === 'assertive' ? 'alert' : 'status');
-    region.setAttribute('aria-live', politeness);
-    region.setAttribute('aria-atomic', 'true');
+    region.id = attrs.id;
+    region.className = attrs.class;
+    region.setAttribute('role', attrs.role);
+    region.setAttribute('aria-live', attrs['aria-live']);
+    region.setAttribute('aria-atomic', attrs['aria-atomic']);
     document.body.appendChild(region);
   }
   region.textContent = '';

package/src/components/AppShell.tsx

@@ -4,7 +4,7 @@
 // exactly one of those.
 
 import type { JSX } from 'solid-js';
-import { useId } from '../a11y';
+import { LIVE_REGION_LEVELS, liveRegionAttrs, useId } from '../a11y';
 import { cx } from '../cx';
 import { UI_KEYS } from '../i18n-keys';
 import { useUi } from '../theme/context';
@@ -56,6 +56,23 @@ export function AppShell(props: AppShellProps): JSX.Element {
         {props.children}
       </main>
       {props.footer === undefined ? null : <footer class={styles['footer']}>{props.footer}</footer>}
+      {/* The two live regions, in the SERVER response and empty. `announce()` had none until
+          2026-09 and built its own on first call — a region appended and written in the same frame,
+          which most screen readers do not announce, so the first message of a session was silent.
+          They are last in DOM order because they are never visible and never focusable: the class
+          is `visually-hidden`, not `display: none`, which would stop them being read at all. */}
+      {LIVE_REGION_LEVELS.map((politeness) => {
+        const attrs = liveRegionAttrs(politeness);
+        return (
+          <div
+            id={attrs.id}
+            class={attrs.class}
+            role={attrs.role}
+            aria-live={attrs['aria-live']}
+            aria-atomic={attrs['aria-atomic']}
+          />
+        );
+      })}
     </div>
   );
 }

package/src/components/AsyncRegion.module.scss

@@ -0,0 +1,15 @@
+@use '../tokens' as t;
+
+// The reserved box, held in every branch: the placeholder, the error, the empty state and the
+// content are all at least this tall, so the answer arriving moves nothing below the region.
+.region {
+  min-block-size: var(--async-reserve);
+}
+
+// A refetch over content already on screen. Dimmed rather than replaced — the previous page stays
+// readable, which is what makes a search-as-you-type list feel fast instead of flickering.
+// Behind the global `prefers-reduced-motion` guard in `reset.scss` like every other animated rule.
+.stale {
+  opacity: 0.6;
+  transition: opacity t.duration(fast) t.easing(out);
+}

package/src/components/AsyncRegion.tsx

@@ -0,0 +1,78 @@
+// The one way to render a region whose content has to arrive. Four branches, decided by
+// `asyncBranch` and never by the caller: a skeleton while it loads, the error report when it
+// fails, the empty state when a completed result held nothing, and the content.
+//
+// `empty` and `ready` are REQUIRED props, so a region that forgot what "nothing here" looks like
+// is a type error rather than a review comment. `pending` and `failed` are not props at all — the
+// placeholder is derived from `reserve` so it cannot mismatch the loaded box, and the failure
+// renders through `ErrorState`, which is the one thing allowed to phrase an error.
+
+import { finiteCount } from '@ultimat3/core';
+import type { JSX } from 'solid-js';
+import { ariaBool } from '../a11y';
+import { cx } from '../cx';
+import styles from './AsyncRegion.module.scss';
+import {
+  type AsyncBranch,
+  type AsyncState,
+  asyncBranch,
+  isBusyBranch,
+  type ReserveBox,
+  reserveBlockSize,
+} from './async-branch';
+import { ErrorState } from './ErrorState';
+import { Skeleton } from './Skeleton';
+
+export interface AsyncRegionProps<T> {
+  /** A live-query accessor, a resource, or a plain signal — narrowed to one of four shapes. */
+  state: AsyncState<T>;
+  /** The box the placeholder holds, and the box the loaded content lands in. Same value, once. */
+  reserve: ReserveBox;
+  /** The content. Called only with data a completed result actually carried. */
+  ready: (data: T) => JSX.Element;
+  /**
+   * Required with no default: "nothing here yet" is a screen, not an oversight, and `EmptyState`
+   * is one line of it — `empty={() => <EmptyState title={t('posts.none')} />}`.
+   */
+  empty: () => JSX.Element;
+  /** Emptiness for a shape that is not a list. Defaults to `isEmptyData`. */
+  isEmpty?: ((data: T) => boolean) | undefined;
+  /** Passed straight to `ErrorState` on the failed branch. */
+  onRetry?: (() => void) | undefined;
+  class?: string | undefined;
+}
+
+export function AsyncRegion<T>(props: AsyncRegionProps<T>): JSX.Element {
+  // `Array.from({ length: NaN })` is `[]` and `Infinity` asks for 2^53 - 1 elements, so an
+  // unscreened line count is either a collapsed box reported as a healthy loading state or a bare
+  // `RangeError` out of a render — the same screen `Skeleton` and `DataTable` already apply.
+  const lines = (): number => finiteCount('AsyncRegion', 'reserve.lines', props.reserve.lines, 0);
+
+  const branch = (): AsyncBranch<T> => asyncBranch(props.state, props.isEmpty);
+
+  const content = (): JSX.Element => {
+    const at = branch();
+    if (at.kind === 'failed') return <ErrorState error={at.error} onRetry={props.onRetry} />;
+    if (at.kind === 'pending') {
+      return <Skeleton lines={lines()} height={props.reserve.height} />;
+    }
+    return at.kind === 'empty' ? props.empty() : props.ready(at.data);
+  };
+
+  // Dimmed only where there is something to dim: a refetch over content the reader is looking at.
+  // A pending region is already a placeholder, and fading a placeholder says nothing.
+  const stale = (): boolean => branch().kind !== 'pending' && isBusyBranch(branch());
+
+  return (
+    <div
+      class={cx(styles['region'], stale() && styles['stale'], props.class)}
+      // The reserved box is emitted in EVERY branch, which is what makes the four the same size:
+      // a skeleton, an error, an empty state and the content all land in one box, so nothing under
+      // the region moves when the answer arrives.
+      style={{ '--async-reserve': reserveBlockSize({ ...props.reserve, lines: lines() }) }}
+      aria-busy={ariaBool(isBusyBranch(branch()))}
+    >
+      {content()}
+    </div>
+  );
+}

package/src/components/Button.module.scss

@@ -15,11 +15,20 @@
   white-space: nowrap;
   cursor: pointer;
 
-  &:active:not(:disabled) {
+  &:active:not(:disabled, [aria-disabled='true']) {
     transform: translateY(1px);
   }
 
   @include t.disabled;
+
+  // A BUSY control is one the reader is waiting on, so it has to stay readable: `t.disabled` dims
+  // to 0.55, and WCAG exempts a disabled control from the contrast minimum precisely because
+  // nobody is meant to read it. `loading` now carries `aria-disabled` too — this is what keeps the
+  // two states from sharing one appearance. Written after the mixin: same specificity, later wins.
+  &[aria-busy='true'] {
+    opacity: 1;
+    cursor: progress;
+  }
 }
 
 .full {

package/src/components/Button.tsx

@@ -1,5 +1,14 @@
 // The one button. Variants and tones are token-driven, so dark mode and RTL
 // need no extra rules; `loading` keeps the label mounted to avoid a layout jump.
+//
+// `loading` does NOT set the native `disabled` attribute, and that WILL read as a mistake — it set
+// one until 2026-09. Four things go wrong when a control disables itself mid-flow: the browser
+// moves focus off it to `<body>`, so a keyboard user's next Tab restarts at the top of the
+// document; a disabled control is exempt from WCAG's contrast minimum, so the state the user most
+// needs to read is the one allowed to be unreadable; it explains nothing, because `disabled` has
+// no announced reason; and it does not actually prevent the double submit, which is a race on the
+// server. `aria-disabled` says unavailable and keeps the control focusable, the click is refused
+// here, and the form refuses it again — `Form busy` — because the button is not the only way in.
 
 import type { JSX } from 'solid-js';
 import { ariaBool } from '../a11y';
@@ -29,8 +38,29 @@ export interface ButtonProps {
   onClick?: JSX.EventHandlerUnion<HTMLButtonElement, MouseEvent> | undefined;
 }
 
+type ButtonClick = Parameters<JSX.EventHandler<HTMLButtonElement, MouseEvent>>[0];
+
 export function Button(props: ButtonProps): JSX.Element {
-  const inert = (): boolean => props.disabled === true || props.loading === true;
+  const busy = (): boolean => props.loading === true;
+  const inert = (): boolean => props.disabled === true || busy();
+
+  /**
+   * `aria-disabled` is advisory — it changes what is announced and nothing else — so the refusal
+   * has to happen here. `preventDefault` is what stops a `type="submit"` reaching its form; not
+   * calling the caller's handler is what stops everything else.
+   */
+  const onClick = (event: ButtonClick): void => {
+    if (inert()) {
+      event.preventDefault();
+      return;
+    }
+    const handler = props.onClick;
+    if (handler === undefined) return;
+    // Solid's bound form is `[handler, data]`, and a component that only called the function form
+    // would silently drop every `onClick={[save, id]}` in the app.
+    if (typeof handler === 'function') handler(event);
+    else handler[0](handler[1], event);
+  };
 
   return (
     <button
@@ -44,15 +74,17 @@ export function Button(props: ButtonProps): JSX.Element {
         props.fullWidth === true && styles['full'],
         props.class,
       )}
-      disabled={inert()}
+      // Only the caller's explicit `disabled` reaches the attribute. `loading` is a state the user
+      // is meant to read and wait out, not a control taken away from under them.
+      disabled={props.disabled === true ? true : undefined}
       aria-disabled={ariaBool(inert())}
-      aria-busy={ariaBool(props.loading === true)}
+      aria-busy={ariaBool(busy())}
       aria-label={props['aria-label']}
       aria-controls={props['aria-controls']}
       aria-expanded={ariaBool(props['aria-expanded'])}
-      onClick={props.onClick}
+      onClick={onClick}
     >
-      {props.loading === true ? (
+      {busy() ? (
         <span class={styles['spinner']}>
           <Spinner size="sm" />
         </span>

package/src/components/DataTable.module.scss

@@ -31,3 +31,10 @@
   color: t.role('fg-muted');
   font-size: 0.75em;
 }
+
+// A refetch over rows already on screen: dimmed, never torn down. Same rule and same tokens as
+// `AsyncRegion`'s `.stale`, because it is the same state — the shared `asyncBranch` decides both.
+.stale {
+  opacity: 0.6;
+  transition: opacity t.duration(fast) t.easing(out);
+}