@ultimat3/ui 24.0.0 → 25.0.0

package/CATALOG.md

@@ -4,7 +4,7 @@
 
 Every component and every token, projected from source. Import all of it from `@ultimat3/ui`.
 
-62 components: `Accordion` · `Alert` · `AppShell` · `AsyncRegion` · `Avatar` · `Badge` · `BarChart` · `Breadcrumb` · `Button` · `Card` · `Checkbox` · `Combobox` · `CommandPalette` · `Container` · `CopyButton` · `DataTable` · `DateTime` · `Dialog` · `Divider` · `Drawer` · `Dropzone` · `EmptyState` · `ErrorState` · `Field` · `FileInput` · `Form` · `Grid` · `Icon` · `IconButton` · `Image` · `InfiniteScroll` · `Input` · `Kbd` · `Link` · `LocaleSwitcher` · `Menu` · `Meter` · `Money` · `PageHeader` · `Pagination` · `Popover` · `QrCode` · `Radio` · `RelativeTime` · `Section` · `Select` · `Skeleton` · `Sparkline` · `Spinner` · `Stack` · `StatTile` · `Switch` · `Table` · `Tabs` · `Text` · `Textarea` · `ThemeToggle` · `ToastRegion` · `Toast` · `Toaster` · `Toolbar` · `Tooltip`
+68 components: `Accordion` · `Alert` · `AppShell` · `AsyncRegion` · `Avatar` · `Badge` · `BarChart` · `Breadcrumb` · `Button` · `Card` · `ChartFrame` · `Checkbox` · `Combobox` · `CommandPalette` · `Container` · `CopyButton` · `DataTable` · `DateTime` · `Dialog` · `Divider` · `DonutChart` · `Drawer` · `Dropzone` · `EmptyState` · `ErrorState` · `Field` · `FileInput` · `Form` · `Gauge` · `Grid` · `Icon` · `IconButton` · `Image` · `InfiniteScroll` · `InlineBar` · `Input` · `Kbd` · `LineChart` · `AreaChart` · `Link` · `LocaleSwitcher` · `Menu` · `Meter` · `Money` · `PageHeader` · `Pagination` · `Popover` · `QrCode` · `Radio` · `RelativeTime` · `Section` · `Select` · `Skeleton` · `Sparkline` · `Spinner` · `Stack` · `StatTile` · `Switch` · `Table` · `Tabs` · `Text` · `Textarea` · `ThemeToggle` · `ToastRegion` · `Toast` · `Toaster` · `Toolbar` · `Tooltip`
 
 ## Vocabulary
 
@@ -47,17 +47,18 @@ Inline message bound to the page, not the viewport. `danger`/`warning` use `role
 
 ### AppShell
 
-The page frame every app screen sits in: skip link, banner, navigation, main, contentinfo. Stateless on purpose — below `md` the sidebar becomes a band above the content instead of growing an open/closed flag, because an off-canvas menu is already `Drawer` and axiom 1 allows exactly one of those.
+The page frame every app screen sits in: skip link, banner, navigation, main, contentinfo. Stateless, and scriptless: below `md` the sidebar `<nav>` is a native `popover` panel at the inline-start edge, opened by a `popovertarget` menu button — the browser holds the open state, Esc and light dismiss, so the frame on every page costs no island. Not `Drawer`: that is a modal `<dialog>` opened from an effect, so it needs a hydrated island, and a `<dialog>` cannot also be the in-flow `navigation` landmark at `md` and up. An engine with no popovers keeps the old band.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
 | `children` | `JSX.Element` | yes | The page. Rendered inside the one `<main>`, which is the skip link's target. |
 | `header` | `JSX.Element` | — |  |
-| `sidebar` | `JSX.Element` | — | Rendered inside a `<nav>` landmark at the inline start. |
+| `sidebar` | `JSX.Element` | — | Rendered inside a `<nav>` landmark: the inline-start column at `md` and up, a panel below. |
 | `footer` | `JSX.Element` | — |  |
 | `sidebarLabel` | `string` | — | Accessible name for the sidebar landmark. Defaults to the translated `ui.navigation`. |
 | `skipLabel` | `string` | — | Skip-link text. Defaults to the translated `ui.skip`. |
-| `sidebarWidth` | `string` | — | Sidebar track width at `md` and up. Any CSS length. |
+| `menuLabel` | `string` | — | The menu button's text below `md`. Defaults to the translated `ui.menu`. |
+| `sidebarWidth` | `string` | — | Sidebar track width at `md` and up, and the panel's width below. Any CSS length. |
 | `stickyHeader` | `boolean` | — | Keeps the header pinned while the main region scrolls. |
 | `class` | `string` | — |  |
 
@@ -103,15 +104,19 @@ 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 — 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`.
+A bar chart of one series — clicks per day, signups per week — or two stacked (done, and failed on top): SVG bars, HTML axis labels. 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. The labels sit outside the svg because text inside a viewBox scales with it — a speck at phone width. It stands in a `ChartFrame`: a legend for two series, and a hidden table of the same numbers.
 
 | 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` | — |  |
+| `seriesLabels` | `{ readonly primary: string; readonly secondary: string }` | — | Names of the two series, already translated, read by each rect's `<title>`, the legend and the data table. Give them when a point carries `secondary`: a stacked bar with no name for its top is two numbers and no key. |
+| `keyLabel` | `string` | — | The key column's head in the data table, already translated — "Day". |
+| `format` | `((value: number) => string)` | — | Formats every value. Default: `Intl.NumberFormat` in the page's locale. |
+| `focusable` | `boolean` | — | Give every bar a tab stop and a hover/focus readout. Default off: no tab stops. |
+| `showCaption` | `boolean` | — | Show the caption above the plot. Default off — it names the figure either way. |
+| `class` | `string` | — | Lands on the root `<figure>`, which holds the svg and its HTML axis labels. |
 
 ### Breadcrumb
 
@@ -161,6 +166,19 @@ Surface container. Elevation is a token rung, and because the shadow tokens are
 | `as` | `'div' \| 'article' \| 'section' \| 'li'` | — |  |
 | `class` | `string` | — |  |
 
+### ChartFrame
+
+The frame every chart stands in: a `<figure>` named by its `<figcaption>`, the plot, a legend that wraps under the plot on a narrow container and stands beside it on a wide one, and a visually-hidden `<table>` of the same numbers — what a screen reader and a reader who cannot tell the colours apart get instead of the picture. Server-rendered HTML: no island, no JS.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `label` | `string` | yes | The chart's name, already translated: the `<figcaption>`, and the data table's caption. |
+| `children` | `JSX.Element` | yes | The plot — the chart's own svg and HTML axis labels. |
+| `showCaption` | `boolean` | — | Show the caption above the plot. Off by default: a chart usually sits under a Card's own heading, and the caption names the figure for assistive tech either way. |
+| `legend` | `readonly ChartLegendItem[]` | — | One entry per series. Omitted or empty renders no legend. |
+| `table` | `ChartTable` | — | The same data as rows, rendered visually hidden (`chartTable`). |
+| `class` | `string` | — | Lands on the root `<figure>`. |
+
 ### Checkbox
 
 Native checkbox with a token-drawn indicator. The label element wraps the input, so the whole row is a hit target without a manual `for`/`id` pairing.
@@ -251,7 +269,7 @@ Copies one string to the clipboard and says so — the control beside a short UR
 
 ### 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.  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.
+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.  A narrow table is the SAME table restyled as labelled cards (`DataTable.module.scss`), never a second copy: a duplicate is read twice or, hidden, is links the reader is told are not there.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -268,6 +286,8 @@ Data-driven table: sortable headers, cursor pagination, and the four states a re
 | `nextCursor` | `string` | — | Opaque cursors from the query result; absent means no further page. |
 | `prevCursor` | `string` | — |  |
 | `stickyHeader` | `boolean` | — |  |
+| `stickyFirstColumn` | `boolean` | — | Pins the first column while the table scrolls sideways. |
+| `narrow` | `DataTableNarrow` | — | What a table narrower than `sm` becomes. Default `cards`. |
 | `density` | `'comfortable' \| 'compact'` | — |  |
 | `skeletonRows` | `number` | — | Placeholder row count while loading. Match the usual page size. |
 | `class` | `string` | — |  |
@@ -315,6 +335,23 @@ A rule. Always an explicit `role="separator"` with an orientation; pass `label`
 | `label` | `string` | — | Visible, already-translated caption rendered inside the rule. |
 | `class` | `string` | — |  |
 
+### DonutChart
+
+Parts of one whole — traffic by device, runs by outcome — as a ring of segments with the total (or the caller's figure) in its centre, a legend giving each part's value and share, and a hidden data table. Each segment carries its series' marker shape and a gap from its neighbours, so the ring reads in greyscale. SVG geometry from `donut-chart-view.ts`; text is HTML.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `label` | `string` | yes | The chart's name, already translated: the figure's caption and the svg's accessible name. |
+| `segments` | `readonly DonutSegment[]` | yes | Clockwise from twelve o'clock, in the order the legend lists them. |
+| `centreValue` | `string` | — | The figure in the ring's centre, already formatted. Default: the formatted total. |
+| `centreLabel` | `string` | — | A short line under the centre figure, already translated — "Total", "Sessions". |
+| `keyLabel` | `string` | — | The segment column's head in the data table, already translated — "Device". |
+| `valueLabel` | `string` | — | The value column's head in the data table, already translated. Default: `label`. |
+| `format` | `((value: number) => string)` | — | Formats every value. Default: `Intl.NumberFormat` in the page's locale. |
+| `focusable` | `boolean` | — | Give every drawn segment a tab stop and a hover/focus readout. Default off. |
+| `showCaption` | `boolean` | — | Show the caption above the chart. Default off — it names the figure either way. |
+| `class` | `string` | — | Lands on the root `<figure>`. |
+
 ### Drawer
 
 Edge-anchored panel, also a native <dialog> so it inherits the top layer and inert background. `side` is logical (`inline-start`/`inline-end`), so a drawer pinned to the start edge lands on the right in an RTL locale automatically.
@@ -341,11 +378,11 @@ A drop surface that is a real `<label>` around a real, visually-hidden `<input t
 | `id` | `string` | — |  |
 | `name` | `string` | — |  |
 | `accept` | `string` | — | The `accept` attribute, and the same list a dropped file is partitioned against. |
-| `multiple` | `boolean` | — |  |
+| `multiple` | `boolean` | — | Without it the zone takes ONE file, dropped or picked — the rest are refused by `count`. |
 | `required` | `boolean` | — |  |
 | `disabled` | `boolean` | — |  |
 | `maxBytes` | `number` | — | Client-side ceiling. The server enforces its own; this only spares a doomed transfer. |
-| `maxFiles` | `number` | — |  |
+| `maxFiles` | `number` | — | Read only with `multiple`: a single-file zone's ceiling is one. |
 | `progress` | `number` | — | 0..1 while an upload runs. Absent renders no bar at all — never one stuck at zero. |
 | `progressLabel` | `string` | — | Already-translated accessible name for the progress bar. |
 | `class` | `string` | — |  |
@@ -435,6 +472,19 @@ Form shell. Owns the one thing every form needs and always forgets: a top-of-for
 | `aria-label` | `string` | — |  |
 | `onSubmit` | `JSX.EventHandlerUnion<HTMLFormElement, SubmitEvent>` | — |  |
 
+### Gauge
+
+One value against its maximum as a 270° dial — CPU, a quota, a queue's fill — with the reading in its centre and its label under it. A `meter` role carries the value for assistive tech, the way `Meter` does; the readout is HTML over the svg so it keeps its size on a phone.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `label` | `string` | yes | What is measured, already translated: shown under the dial, and the meter's name. |
+| `value` | `number` | yes |  |
+| `max` | `number` | yes |  |
+| `tone` | `Tone` | — | The fill's colour role. Default `accent`; a caller picks `warning`/`danger` by threshold. |
+| `format` | `((value: number, max: number) => string)` | — | The readout, from the value and max. Default: the share as a percentage in the page's locale. |
+| `class` | `string` | — | Lands on the root `<figure>`. |
+
 ### Grid
 
 Grid layout primitive. The default is an intrinsic responsive grid (`auto-fit` + `minmax`) so most layouts need no breakpoint at all.
@@ -511,6 +561,18 @@ An endless list that degrades to pagination: the foot is always a real `rel="nex
 | `rootMargin` | `string` | — | How far below the fold loading starts. A CSS length, as IntersectionObserver takes it. |
 | `class` | `string` | — |  |
 
+### InlineBar
+
+A figure with a bar drawn to its share of a maximum — the in-cell bar a dashboard table uses to make a column of numbers scannable. The text is the fact and is what assistive tech reads; the bar is `Meter`'s decorative form, so the share rule and its clamping are written once. The figure arrives formatted, as `StatTile`'s does: this component never guesses a locale.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `value` | `number` | yes |  |
+| `max` | `number` | yes | The whole the bar is a share of — usually the largest value in the column. |
+| `text` | `string` | yes | The figure as the cell shows it, already formatted (`Intl.NumberFormat`, `formatMoney`). |
+| `tone` | `Tone` | — |  |
+| `class` | `string` | — |  |
+
 ### Input
 
 Single-line text control. No `type="number"` convenience wrapper: numeric input uses `inputmode` + a text type so locale decimal separators survive.
@@ -548,6 +610,38 @@ A keyboard key or chord as the user reads it — "⌘K", "Esc", "/". A native `<
 | `children` | `JSX.Element` | yes | The key or chord, already translated where a key name is a word. |
 | `class` | `string` | — |  |
 
+### LineChart
+
+A line chart of one or more series over the same keys — signups per day, p95 per hour — and `AreaChart`, the same chart with each series' area filled to the baseline. SVG lines on a nice 1-2-5 value axis, HTML axis labels (text inside a viewBox scales to a speck on a phone), a legend, and a hidden data table. Every series has its own dash and marker, never colour alone.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `label` | `string` | yes | The chart's name, already translated: the figure's caption and the svg's accessible name. |
+| `keys` | `readonly string[]` | yes | The x axis, oldest first, already formatted for display — "17 Sep", "14:00". |
+| `series` | `readonly ChartSeries[]` | yes | One entry per line. `values[i]` belongs to `keys[i]`; `null` is a gap, never a zero. |
+| `keyLabel` | `string` | — | The key column's head in the data table, already translated — "Day". |
+| `format` | `((value: number) => string)` | — | Formats every value and tick. Default: `Intl.NumberFormat` in the page's locale. |
+| `zero` | `boolean` | — | Start the value axis at zero. Default on; off fits the axis to the data. |
+| `focusable` | `boolean` | — | Give every point a tab stop and a hover/focus readout. Default off: no tab stops. |
+| `showCaption` | `boolean` | — | Show the caption above the plot. Default off — it names the figure either way. |
+| `class` | `string` | — | Lands on the root `<figure>`. |
+
+### AreaChart
+
+A line chart of one or more series over the same keys — signups per day, p95 per hour — and `AreaChart`, the same chart with each series' area filled to the baseline. SVG lines on a nice 1-2-5 value axis, HTML axis labels (text inside a viewBox scales to a speck on a phone), a legend, and a hidden data table. Every series has its own dash and marker, never colour alone.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `label` | `string` | yes | The chart's name, already translated: the figure's caption and the svg's accessible name. |
+| `keys` | `readonly string[]` | yes | The x axis, oldest first, already formatted for display — "17 Sep", "14:00". |
+| `series` | `readonly ChartSeries[]` | yes | One entry per line. `values[i]` belongs to `keys[i]`; `null` is a gap, never a zero. |
+| `keyLabel` | `string` | — | The key column's head in the data table, already translated — "Day". |
+| `format` | `((value: number) => string)` | — | Formats every value and tick. Default: `Intl.NumberFormat` in the page's locale. |
+| `zero` | `boolean` | — | Start the value axis at zero. Default on; off fits the axis to the data. |
+| `focusable` | `boolean` | — | Give every point a tab stop and a hover/focus readout. Default off: no tab stops. |
+| `showCaption` | `boolean` | — | Show the caption above the plot. Default off — it names the figure either way. |
+| `class` | `string` | — | Lands on the root `<figure>`. |
+
 ### Link
 
 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.
@@ -595,7 +689,7 @@ Action menu: a trigger plus a `role="menu"` list with roving tabindex. Distinct
 | `items` | `readonly MenuItem[]` | yes |  |
 | `open` | `boolean` | yes |  |
 | `onOpenChange` | `(open: boolean) => void` | yes |  |
-| `trigger` | `(control: { id: string; 'aria-haspopup': 'menu'; 'aria-expanded': boolean; 'aria-controls': string; }) => JSX.Element` | yes |  |
+| `trigger` | `(control: { id: string; 'aria-haspopup': 'menu'; 'aria-expanded': boolean; 'aria-controls': string \| undefined; }) => JSX.Element` | yes | The menu button. `aria-controls` is present only while the list is mounted: an IDREF to an element not in the document names nothing. |
 | `label` | `string` | yes | Already-translated accessible name for the menu. |
 | `align` | `'start' \| 'end'` | — |  |
 | `class` | `string` | — |  |
@@ -827,7 +921,7 @@ Boolean toggle with immediate effect (as opposed to Checkbox, which is part of a
 
 ### Table
 
-Presentational table. Owns two things every hand-rolled table gets wrong: a sticky header, and horizontal overflow contained inside the table's own scroll container so the page body never scrolls sideways.
+Presentational table. Owns what every hand-rolled table gets wrong: a sticky header, a first column that stays put while the rest scrolls, and horizontal overflow contained inside the table's own scroll container so the page body never scrolls sideways.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -835,6 +929,8 @@ Presentational table. Owns two things every hand-rolled table gets wrong: a stic
 | `children` | `JSX.Element` | yes |  |
 | `hideCaption` | `boolean` | — | Hide the caption visually while keeping it for assistive tech. |
 | `stickyHeader` | `boolean` | — |  |
+| `stickyFirstColumn` | `boolean` | — | Pins the first column at the inline start while the table scrolls sideways. Off by default. |
+| `explicitRoles` | `boolean` | — | Declares `role="table"` on the element itself. For a caller that restyles the table's `display` (DataTable's card view): WebKit drops a table's semantics once `display` changes, and the explicit role is what keeps it a table. The rows and cells are the caller's to mark. |
 | `density` | `'comfortable' \| 'compact'` | — |  |
 | `striped` | `boolean` | — | Zebra striping. Off by default — a border is usually enough. |
 | `class` | `string` | — |  |
@@ -933,7 +1029,7 @@ The one way to render a toast queue: the store's VISIBLE slice, inside the regio
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
-| `store` | `ToastStore` | yes | The queue. One per app — `createToastStore()` in the island that mounts this. |
+| `store` | `ToastStore` | yes | The queue. One per app — `toastStore()` in the island that mounts this. |
 | `label` | `string` | yes | Already-translated landmark name, e.g. "Notifications". |
 | `politeness` | `Politeness` | — |  |
 | `placement` | `ToastPlacement` | — |  |
@@ -997,6 +1093,14 @@ charts and email.
 | `info` | `--color-info` |
 | `info-soft` | `--color-info-soft` |
 | `info-fg` | `--color-info-fg` |
+| `chart-1` | `--color-chart-1` |
+| `chart-2` | `--color-chart-2` |
+| `chart-3` | `--color-chart-3` |
+| `chart-4` | `--color-chart-4` |
+| `chart-5` | `--color-chart-5` |
+| `chart-6` | `--color-chart-6` |
+| `chart-7` | `--color-chart-7` |
+| `chart-8` | `--color-chart-8` |
 
 ### Space — `--space-*`
 

package/CLAUDE.md

@@ -16,7 +16,7 @@ Tier 4. Imports `@ultimat3/core`, `i18n`, `money`, `time` — **not `schema`**,
 - **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.
+- **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, issue #273) rather than allowing bytes for it. Its sibling #276 — a pure re-export entry shaken to its export clause — was fixed in Bun 1.4.1 (oven-sh/bun#40578), and barrels have been built as their own entry since.
 - **`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.
@@ -26,7 +26,7 @@ Tier 4. Imports `@ultimat3/core`, `i18n`, `money`, `time` — **not `schema`**,
 - **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`.
+- **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; its mobile nav is a no-JS `popover`, and `Drawer` stays the modal off-canvas.
 - **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.
 - **`@include t.tone-classes`** emits the `.tone-*` custom-property blocks. Never hand-write a seventh copy; `$tones` in `_colors.scss` mirrors `TONES` and `variants.test.ts` gates it.
 - **Icons are generated, never authored.** `src/icons/glyphs/*.ts` is one module per Lucide icon, written by `bun run icons` from `lucide-static@LUCIDE_VERSION`. Never hand-edit a glyph, never add a hand-drawn one, never introduce a second icon source. An upstream fix is a version bump plus a re-run. `lucide` itself is NOT a dependency — the data is committed, so the package still installs, typechecks and renders offline with zero runtime deps.
@@ -42,8 +42,11 @@ Tier 4. Imports `@ultimat3/core`, `i18n`, `money`, `time` — **not `schema`**,
 - **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.
+- **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. Once per failure: only a CHANGED `(invalidField, error)` moves focus (`Form.test.ts`, real Solid).
 - **`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.
+- **A preset is a BASE, never a mode.** `defineTheme({ preset })` merges `THEME_PRESETS[name]` under the app's overrides key by key (an `undefined` override is no override), then runs every existing check on the merged result. A preset states ALL colour roles in both themes, so `presets.test.ts` measures it alone against `CONTRAST_PAIRS`, the chart CVD floor and the scrim rule. A new preset is a row in `presets.ts` plus its file; no preset forces a theme or ships CSS.
+- **Chart series are measured twice**: 3:1 on all four surfaces (`CONTRAST_PAIRS`), and `CHART_DISTINCT_MIN` ΔE apart under protan/deutan/tritan simulation (`colour-vision.ts`, `colour-vision.test.ts`). Moving one channel of one series can break the second check without touching the first.
+- **A `defineTheme()` shadow is a GRAMMAR match** (`theme/shadow-value.ts`), not a pattern of allowed characters: layers of lengths plus `rgb(R G B / a)` or `rgb(var(--color-<known role>) / a)`. The glow and tinted rungs read `--color-accent`, so a brand's accent recolours them for free — `tokens.test.ts` refuses a channel literal there.
 - **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,10 +71,16 @@ Tier 4. Imports `@ultimat3/core`, `i18n`, `money`, `time` — **not `schema`**,
 | `src/theme/ambient-slot.ts` | the module-scope slot holding the reader `useUi()` falls back to on the server — imports nothing, so a browser chunk pays nothing for it |
 | `src/theme/ambient.ts` | the server's reader (`ambientUiContext`: request locale, zone, direction, translator), registered at import; `index.ts` imports it bare, and the `browser` field maps it to `ambient.browser.ts`, which answers the defaults and registers nothing |
 | `src/error-registry.ts` | the `registerErrorCodes()` call, alone, so `errors.ts` is pure and the barrel's re-export of it costs a chunk nothing |
-| `src/components/` | 62 components, `PascalCase.tsx` (component convention overrides the repo's kebab-case) |
+| `src/components/` | 67 components, `PascalCase.tsx` (component convention overrides the repo's kebab-case) |
 | `src/icons/glyphs/` | GENERATED: 1767 per-icon modules, `@ultimat3/ui/icons/<name>` → `icon<Name>` |
 | `src/icons/build-icons.ts` | the generator + the pinned `LUCIDE_VERSION`; `LICENSE.lucide` is upstream's ISC text |
-| `src/theme/brand.ts` | `defineTheme()` — the ONE brand-override seam; there is no SCSS `@use ... with ()` path |
+| `src/theme/brand.ts` | `defineTheme()` — the ONE brand-override seam; there is no SCSS `@use ... with ()` path. Merges a preset under the overrides, measures, emits at every level `theme.scss` does |
+| `src/theme/brand-declarations.ts` | each slot's validation + its custom-property lines, in canonical order (colours, shadows, radius, font) |
+| `src/theme/shadow-value.ts` | the shadow-value grammar a brand override must match |
+| `src/theme/presets.ts` · `preset-shape.ts` · `preset-scifi.ts` | `THEME_PRESETS` (`scifi`), the `ThemePreset` shape + `FONT_SLOTS`, and the scifi data |
+| `src/tokens/color-tokens.ts` | `COLOR_ROLES`, `CHART_ROLES`, the channel mirror — split from `tokens.ts` by size, re-exported by it |
+| `src/tokens/colour-vision.ts` | Machado 2009 dichromacy simulation + CIE76 ΔE; `closestChartPair()` answers the pair to move |
+| `src/tokens/_touch.scss` · `_effects.scss` | `--touch-target` + `touch-target` mixin; `glow-edge` and `grid-texture` (CSS only, static, withdrawn under `prefers-contrast: more` / `forced-colors`) |
 | `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 |

package/README.md

@@ -20,10 +20,32 @@ channels** so `rgb(var(--color-accent) / 0.12)` gives a tint with no extra token
 | `scrim` | modal backdrops |
 | `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 |
+| `chart-1` … `chart-8` | categorical chart series, in assignment order (`CHART_ROLES`) |
+
+The chart series are Okabe–Ito-derived and **measured, not picked** (`As of 2026-10`): each clears
+3:1 against all four surfaces in both themes (WCAG 1.4.11, in `CONTRAST_PAIRS`), and every pair
+stays at least `CHART_DISTINCT_MIN` (ΔE 10) apart under protanopia, deuteranopia and tritanopia
+simulation (`colour-vision.test.ts`). A ninth series reuses `chart-1` with a second encoding — a
+dash, a pattern, a label — never a ninth hue.
 
 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).
+`--easing-*`, `--z-*` (named ladder, no magic numbers), `--touch-target` (44px, as `2.75rem`).
+
+| Shadow rung (`t.shadow('…')`) | What it is |
+|---|---|
+| `xs` `sm` `md` `lg` `xl` | elevation: a drop shadow, deeper and darker in dark |
+| `glow-sm` `glow-md` `glow-lg` | a halo drawn from the **accent** role, no offset — a live tile, a focused panel, a selected series |
+| `tinted-sm` `tinted-md` `tinted-lg` | coloured elevation: a drop shadow in the accent hue |
+
+Glow and tinted rungs read `--color-accent`, so a brand's accent recolours them with no second
+override. `SHADOW_NAMES` / `ShadowName` is the list.
+
+| Font slot | Default stack | Read by |
+|---|---|---|
+| `--font-sans` | `system-ui` … | body copy |
+| `--font-mono` | `ui-monospace` … | `code` and `pre`, error frames |
+| `--font-data` | `ui-monospace`, `'Cascadia Mono'`, `'JetBrains Mono'` … | `@include t.data-text` — figures in tables, axes and stat tiles, ids, `Kbd` |
 
 Authoring helpers, from the same `@use '@ultimat3/ui/tokens' as t` — an app writes no mixin of its own for any of them:
 
@@ -34,6 +56,11 @@ Authoring helpers, from the same `@use '@ultimat3/ui/tokens' as t` — an app wr
 | `@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 |
+| `@include t.data-text` | `font-family: var(--font-data); font-variant-numeric: tabular-nums` — columns of figures that do not wobble |
+| `@include t.touch-target` | `min-block-size` + `min-inline-size` of `var(--touch-target)` — the box itself is hittable |
+| `@include t.touch-target($extend: true)` | the box keeps its size; a centred `::after` grows the HIT AREA to the target — a chart point, a dense icon row |
+| `@include t.glow-edge` | `box-shadow: inset 0 0 0 var(--stroke-hairline) <accent / 0.55>, var(--shadow-glow-sm)` — `t.glow-edge('glow-lg', 0.8)` picks rung and ring alpha |
+| `@include t.grid-texture` | a faint accent grid on a `t.space(6)` pitch with scanlines over it, as `background-image` only; `t.grid-texture(t.space(4), 0.1, false)` drops the scanlines. Withdrawn under `prefers-contrast: more` and `forced-colors: active`; animates nothing |
 
 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.
 
@@ -47,7 +74,7 @@ A rung is `sm md lg xl 2xl`, quoted or bare. Prefer a container query (`t.contai
 | No physical directions | `margin-inline`, `inset-inline-start`, `text-align: start` — RTL needs no second stylesheet. Centring is `inset-inline` + `margin-inline: auto`, never a 50% logical inset beside a physical −50% translate, and an edge shadow's physical x offset gets a `[dir='rtl']` mirror (`components/rtl-sheets.test.ts`) |
 | No hardcoded strings | labels are props, or `t()` through `UI_KEYS` |
 | One token source | `src/tokens/*.scss` is canonical; `tokens.ts` mirrors it and `x verify` fails on drift |
-| AA contrast, both themes | `contrast.test.ts` measures every pairing a component renders — text, status fills, soft tints, focus rings, borders |
+| AA contrast, both themes | `contrast.test.ts` measures every pairing a component renders — text, status fills, soft tints, focus rings, borders, chart series (3:1 on every surface) |
 
 ## Contrast
 
@@ -118,16 +145,16 @@ review comment. Three properties are structural, not documented:
 
 ## Toasts
 
-`Toast` and `ToastRegion` render; `createToastStore()` is the queue behind them, and `<Toaster>` is
+`Toast` and `ToastRegion` render; `toastStore()` is the queue behind them, and `<Toaster>` is
 the one way to draw it.
 
 ```tsx
-import { createToastStore, Toaster } from '@ultimat3/ui';
+import { toastStore, Toaster } from '@ultimat3/ui';
 
 declare const t: (key: string) => string;
 declare const restore: () => void;
 
-const toasts = createToastStore();
+const toasts = toastStore();
 toasts.show({ message: t('post.saved'), tone: 'success' });
 toasts.show({ message: t('post.deleted'), action: { label: t('undo'), onAction: restore } });
 
@@ -157,11 +184,32 @@ Four composites cover the frame of an app screen. Below them are `Container`,
 | `Section` | a labelled `section` with a real heading and `aria-labelledby` | second-level structure inside a page |
 | `Toolbar` | `role="toolbar"` strip, start + end slots, arrow-key roving between its buttons (`As of 2026-08`) | filters and actions above a table or list |
 
-`AppShell` holds no state: below `md` the sidebar becomes a band above the content,
-and an off-canvas menu is `Drawer` — the one component that already does that.
+`AppShell` holds no state: below `md` the sidebar is a native `popover` panel behind a menu
+button (`menuLabel`), opened, closed and dismissed by the browser with no script; where `popover`
+is unsupported it stays a band above the content. A modal off-canvas panel is still `Drawer`.
 Heading levels are props (`headingTag`, `nextHeadingLevel`), so a nested `Section`
 never skips a level.
 
+### Data display
+
+Server-rendered, no island and no JS: a chart costs a route nothing until it asks to be focusable.
+Every chart stands in a `ChartFrame` — a `figure`, its caption, a legend and a visually-hidden data
+table — and every series has a dash and a marker as well as a colour (`chart-1` … `chart-8`).
+
+| Component | Renders | Use for |
+|---|---|---|
+| `LineChart` / `AreaChart` | multi-series line on a 1-2-5 axis (filled for `AreaChart`); `null` is a gap | a trend over keys |
+| `BarChart` | bars, an optional stacked second series with a legend | a count per key |
+| `DonutChart` | ring segments, a centre figure, a legend with value and share | parts of a whole |
+| `Gauge` | a 270° `meter` dial with a tone and a visible label | one value against its max |
+| `ChartFrame` | the figure, caption, legend and data table every chart stands in | a custom chart |
+| `niceTicks` · `chartTable` · `seriesStyle` | axis ticks, the fallback table, a series' dash and marker | building a custom chart |
+| `DataTable` | sort, cursor paging, states; `narrow: 'cards'` (default) collapses rows to labelled cards below `sm`; `Column.priority` hides a column behind a per-row disclosure, never losing its value; `stickyFirstColumn` | any list of records |
+| `Table` | a captioned table with a sticky header; `stickyFirstColumn` | static tabular data |
+| `InlineBar` | a caller-formatted figure with a decorative proportional bar | a number in a table cell |
+| `StatTile` / `Meter` / `Sparkline` | a KPI with its delta; a bar against a max; an inline mini line | the KPI row |
+
+
 ```tsx
 <AppShell header={<Toolbar label={t('nav.main')}>{nav}</Toolbar>} sidebar={<SideNav />}>
   <PageHeader
@@ -281,8 +329,13 @@ Components cancel theirs on cleanup, so a filter never fires into a tree that is
 override, no forked package, no second entry point — one call, validated, rendered
 as the custom properties that beat `theme.scss` at every specificity level it emits.
 
+An app declares it once, as `export const brand` in `apps/web/shared/theme.ts`. `x dev`, the
+container, `x build`'s static export and `/admin` inline it after the surface stylesheet, with its
+`sha256` in `style-src`; with no such module nothing is emitted. There is nothing to paste.
+
 ```ts
-import { brandStyleCspSource, brandStyleTag, defineTheme } from '@ultimat3/ui';
+// apps/web/shared/theme.ts
+import { defineTheme } from '@ultimat3/ui';
 
 export const brand = defineTheme({
   colors: {
@@ -292,27 +345,56 @@ export const brand = defineTheme({
   radius: { md: '0.125rem', lg: '0.25rem' },
   font: { sans: "Inter, system-ui, sans-serif" },
 });
-
-// in <head>, AFTER global.scss
-`${brandStyleTag(brand)}`;
-
-// …and the one source that admits it under the framework's locked CSP. The baseline is
-// `style-src 'self' 'sha256-…'` with no 'unsafe-inline', so a tag whose hash the header does
-// not carry is a stylesheet the browser parses zero rules out of.
-`Content-Security-Policy: style-src 'self' ${brandStyleCspSource(brand)}`;
 ```
 
+`brandStyleTag(brand)` and `brandStyleCspSource(brand)` are what the framework emits — exported
+for a host that renders documents itself.
+
 | Slot | Accepts | Refused with |
 |---|---|---|
 | `colors.light` / `colors.dark` | any `ColorRole`, as `R G B` channels | `X_TOKEN_UNKNOWN` for the role, `X_UI_INVALID_VALUE` for the value |
 | `radius` | any `RadiusName`, as a bare CSS length | `X_TOKEN_UNKNOWN` / `X_UI_INVALID_VALUE` |
-| `font` | `sans`, `mono`, as a `font-family` list | `X_TOKEN_UNKNOWN` / `X_UI_INVALID_VALUE` |
+| `font` | `sans`, `mono`, `data`, as a `font-family` list | `X_TOKEN_UNKNOWN` / `X_UI_INVALID_VALUE` |
+| `shadows.light` / `shadows.dark` | any `ShadowName`, as a `box-shadow`: comma-separated layers of lengths plus `rgb(R G B / a)` or `rgb(var(--color-<role>) / a)`, or `none` | `X_TOKEN_UNKNOWN` for the rung, `X_UI_INVALID_VALUE` for the value |
+| `preset` | a `THEME_PRESETS` name — `'scifi'` | `X_UI_INVALID_VALUE` |
 
 Values are validated, never escaped: the output goes into a `<style>` element, so
 anything carrying `;`, `}` or `</style>` is a refusal at the app's entry point rather
 than a CSS injection. Every component in the system follows the override — they only
 ever read the roles, never a colour.
 
+### The sci-fi preset
+
+`defineTheme({ preset: 'scifi' })` swaps the whole palette for a dashboard look: near-black
+panels in dark (`bg` `5 7 13`), cool paper in light, a cyan `accent` whose `accent-strong` (hover)
+is magenta, its own eight chart series, sharper radii, and — dark only — every elevation rung
+redrawn as an accent hairline plus a halo, so each card and popover has a glowing edge with no
+stylesheet of yours. It is a **base**: every other slot layers onto it role by role, and the
+merged palette is what `CONTRAST_PAIRS` measures.
+
+```ts
+import { defineTheme } from '@ultimat3/ui';
+
+export const brand = defineTheme({
+  preset: 'scifi',
+  colors: { dark: { 'chart-1': '120 220 255' } },   // scifi, with your own first series
+});
+```
+
+The preset ships tokens only (axiom 8). The texture and the edge are yours to place:
+
+```scss
+@use '@ultimat3/ui/tokens' as t;
+
+.main { background-color: t.role('bg'); @include t.grid-texture; }
+.tile { @include t.surface; @include t.glow-edge; }
+.tile[aria-current='true'] { @include t.glow-edge('glow-lg', 0.8); }
+```
+
+A dashboard that should open dark whatever the OS says sets the app default theme
+(`data-theme-default`, [Theme resolution](#theme-resolution)) — the preset never forces a theme.
+Like every brand, export it from `apps/web/shared/theme.ts` and the framework ships it with its CSP hash.
+
 ## The two render paths
 
 Every component renders on the server. Half of them read the ambient presentation context —
@@ -358,7 +440,7 @@ import '../../shared/global'; // `shared/global.scss` is the app's one `@use '@u
 
 ```tsx
 // A client entry — an island's `mount()`, or a hydrated app shell. In this order, once.
-import { createTranslator } from '@ultimat3/i18n';
+import { catalogTranslator } from '@ultimat3/i18n';
 import { setSolidRuntime, UiProvider } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
 import {
@@ -395,7 +477,7 @@ export function mount(el: HTMLElement, props: Props): void {
         locale={props.locale}
         timeZone={props.timeZone}
         currency={props.currency}
-        t={createTranslator(props.strings, props.locale)}
+        t={catalogTranslator(props.strings, props.locale)}
       >
         {props.tree}
       </UiProvider>
@@ -406,7 +488,7 @@ export function mount(el: HTMLElement, props: Props): void {
 ```
 
 **The prop is `t`, it takes a `Translator`, and omitting it is not neutral.** `<UiProvider>` with
-no `t` falls back to `fallbackTranslator(locale)` — `createTranslator({}, locale)`, an **empty**
+no `t` falls back to `fallbackTranslator(locale)` — `catalogTranslator({}, locale)`, an **empty**
 catalog — so every built-in string in the tree renders its key: `<Dialog>`'s close button reads
 `⟦ui.close⟧`, `<Field>`'s marker `⟦ui.required⟧`. The keys are `UI_KEYS`, and they live in the
 framework catalog the SERVER has registered; a browser chunk has none, which is why
@@ -462,7 +544,7 @@ is a type error rather than a review comment.
 
 | Prop | Emitted |
 |---|---|
-| `variants` | `srcset`, descriptors derived and ordered ascending (`srcsetFor`) |
+| `variants` | `srcset`, descriptors derived and ordered ascending (`variantSrcset`) |
 | `sources` | `{ avif?, webp? }` width lists → `<source type="image/avif">`, then `image/webp`, before the `<img>` (`sourceSetsFor`) |
 | `sizes` | `sizes`, verbatim, on the `<img>` and every `<source>` |
 | `priority` | `loading="eager"` + `fetchpriority="high"`; otherwise `lazy` + `auto`, always `decoding="async"` |
@@ -583,9 +665,12 @@ 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.
+when the rejection names no control at all. Focus moves once per failure: a `touch()` or `edit()`
+afterwards re-renders the form but never pulls focus back, so the user can work down the list.
+`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. A successful submit clears dirty except for the fields edited while it
+was in flight — the server never saw those, so a navigation guard still has something to protect.
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ui",
-  "version": "24.0.0",
+  "version": "25.0.0",
   "description": "SolidJS design system: semantic design tokens, dark/RTL-ready SCSS modules, a11y primitives",
   "license": "MIT",
   "type": "module",
@@ -40,7 +40,7 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
@@ -49,10 +49,10 @@
     "icons": "bun run src/icons/build-icons.ts"
   },
   "dependencies": {
-    "@ultimat3/core": "24.0.0",
-    "@ultimat3/i18n": "24.0.0",
-    "@ultimat3/money": "24.0.0",
-    "@ultimat3/time": "24.0.0"
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/i18n": "25.0.0",
+    "@ultimat3/money": "25.0.0",
+    "@ultimat3/time": "25.0.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"

package/src/a11y.ts

@@ -52,7 +52,7 @@ export function useId(prefix = 'u'): string {
 }
 
 /** Test-only: make id assertions deterministic. */
-export function resetIdCounter(): void {
+export function resetUseIdCounter(): void {
   idCounter = 0;
   islandScope = undefined;
 }
@@ -90,7 +90,7 @@ export interface FocusTrap {
  * branch that pulls it back was unreachable by construction. Every branch still tests
  * `root.contains`, so the trap only acts while it is the active one.
  */
-export function createFocusTrap(root: HTMLElement): FocusTrap {
+export function focusTrap(root: HTMLElement): FocusTrap {
   let previous: HTMLElement | null = null;
 
   /**
@@ -181,7 +181,7 @@ export function nextRovingIndex(
 }
 
 /** Wire a roving group: one tabbable item, arrows move focus and selection. */
-export function createRovingTabindex(
+export function rovingTabindex(
   getItems: () => readonly HTMLElement[],
   options: RovingOptions = {},
 ): (event: KeyboardEvent) => void {