@ultimat3/ui 1.2.0 → 3.0.0

package/CATALOG.md

@@ -4,7 +4,7 @@
 
 Every component and every token, projected from source. Import all of it from `@ultimat3/ui`.
 
-46 components: `Alert` · `AppShell` · `Avatar` · `Badge` · `Breadcrumb` · `Button` · `Card` · `Checkbox` · `Container` · `DataTable` · `DateTime` · `Dialog` · `Divider` · `Drawer` · `EmptyState` · `ErrorState` · `Field` · `Form` · `Grid` · `IconButton` · `Image` · `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`
+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`
 
 ## Vocabulary
 
@@ -19,6 +19,18 @@ One size scale, one tone scale, one variant scale — shared by every component
 
 ## Components
 
+### Accordion
+
+Expandable sections built on `<details>`/`<summary>`: open/close, keyboard, focus and `aria-expanded` are the browser's, so the component works with JavaScript disabled and there is no open-state to hydrate. `exclusive` is the native `name` group, not a listener.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `items` | `readonly AccordionItem[]` | yes |  |
+| `exclusive` | `boolean` | — | One section open at a time, through the native `<details name>` group. |
+| `level` | `HeadingLevel` | — | Wraps each title in a heading of this level, putting the sections in the page outline. Left out, a title is plain text inside the disclosure button — which is what a screen reader announces either way. |
+| `onToggle` | `((id: string, open: boolean) => void)` | — | Fires on every open and close, once the browser has already applied it. |
+| `class` | `string` | — |  |
+
 ### Alert
 
 Inline message bound to the page, not the viewport. `danger`/`warning` use `role="alert"` (assertive); the rest use `role="status"`, so an informational banner never interrupts what a screen-reader user is doing.
@@ -134,7 +146,7 @@ Native checkbox with a token-drawn indicator. The label element wraps the input,
 | `name` | `string` | — |  |
 | `value` | `string` | — |  |
 | `checked` | `boolean` | — |  |
-| `indeterminate` | `boolean` | — | Tri-state for "some children selected". Mirrored to `aria-checked`. |
+| `indeterminate` | `boolean` | — | Tri-state for "some children selected". The ONLY thing mirrored to `aria-checked`. |
 | `disabled` | `boolean` | — |  |
 | `required` | `boolean` | — |  |
 | `description` | `string` | — |  |
@@ -143,6 +155,28 @@ Native checkbox with a token-drawn indicator. The label element wraps the input,
 | `aria-invalid` | `boolean` | — |  |
 | `onChange` | `JSX.EventHandlerUnion<HTMLInputElement, Event>` | — |  |
 
+### Combobox
+
+A searchable text field with suggestions: one `<input list>` plus a `<datalist>`, which is a real combobox in every engine — typing, filtering, keyboard and mobile are the platform's, and the field still works with scripting off. `onFilter` is the debounced enhancement on top.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `options` | `readonly ComboboxOption[]` | yes |  |
+| `value` | `string` | — | The current query. Suggestions are filtered to it before they are rendered. |
+| `onFilter` | `((query: string) => void)` | — | Fires `debounceMs` after typing stops, and immediately when a suggestion is picked. Left out, the field is a plain filtered datalist — still correct, just not live. |
+| `debounceMs` | `number` | — | Debounce window in ms. Read once, when the field mounts. |
+| `limit` | `number` | — | Cap on rendered suggestions. |
+| `id` | `string` | — |  |
+| `name` | `string` | — |  |
+| `placeholder` | `string` | — | Already-translated placeholder. |
+| `size` | `Size` | — |  |
+| `required` | `boolean` | — |  |
+| `disabled` | `boolean` | — |  |
+| `class` | `string` | — |  |
+| `aria-label` | `string` | — |  |
+| `aria-describedby` | `string` | — |  |
+| `aria-invalid` | `boolean` | — |  |
+
 ### Container
 
 Centred measure with a gutter. `margin-inline: auto` and `min()` mean one declaration covers every viewport and both writing directions.
@@ -196,7 +230,7 @@ Renders <time datetime="<ISO instant>"> with text formatted in the context time
 
 ### Dialog
 
-Modal built on native <dialog>: the platform gives us the top layer, the backdrop, inert background content, and Escape-to-close for free. We add the labelled heading, the close affordance, and body scroll locking.
+Modal built on native <dialog>: the platform gives us the top layer, the backdrop, inert background content, and Escape-to-close for free. We add the labelled heading and the close affordance. Body scroll locking is one CSS rule in `tokens/reset.scss` (`html:has(dialog:modal)`) rather than anything here, so it covers Drawer too and cannot leak when a close path throws.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -234,6 +268,29 @@ Edge-anchored panel, also a native <dialog> so it inherits the top layer and ine
 | `footer` | `JSX.Element` | — |  |
 | `class` | `string` | — |  |
 
+### Dropzone
+
+A drop surface that is a real `<label>` around a real, visually-hidden `<input type="file">`. That shape is what makes it usable without a mouse: click, Enter and Space already open the picker, focus already lands somewhere, and the accessible name is the instruction the label renders. A `<div onClick>` with `tabindex` would reimplement all four and get one of them wrong. Dragging is the enhancement on top, never the only way in.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `label` | `string` | yes | Already-translated instruction. Required — it is the control's accessible name. |
+| `hint` | `string` | — | Already-translated secondary line: the accepted types, the size ceiling. |
+| `id` | `string` | — |  |
+| `name` | `string` | — |  |
+| `accept` | `string` | — | The `accept` attribute, and the same list a dropped file is partitioned against. |
+| `multiple` | `boolean` | — |  |
+| `required` | `boolean` | — |  |
+| `disabled` | `boolean` | — |  |
+| `maxBytes` | `number` | — | Client-side ceiling. The server enforces its own; this only spares a doomed transfer. |
+| `maxFiles` | `number` | — |  |
+| `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` | — |  |
+| `aria-describedby` | `string` | — |  |
+| `aria-invalid` | `boolean` | — |  |
+| `onSelect` | `(selection: FileSelection<File>) => void` | yes | Every file offered, partitioned into accepted and refused-with-a-reason. |
+
 ### EmptyState
 
 The "nothing here yet" surface. Title and description arrive as already translated strings; the action slot takes a Button so there is one CTA shape.
@@ -272,9 +329,33 @@ Label + hint + error, wired for a11y. Field owns the ids and hands them to the c
 | `markOptional` | `boolean` | — | Appends a translated "(optional)" marker instead of marking required. |
 | `class` | `string` | — |  |
 
+### FileInput
+
+A file picker that keeps the platform control and dresses it. The native button and the browser's own "no file chosen" summary are already localised, focusable and keyboard-driven, so replacing them with a div buys nothing and costs an accessible name. What the platform has no opinion about is added here: a determinate progress bar, and a partition of what it refused.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `id` | `string` | — |  |
+| `name` | `string` | — |  |
+| `accept` | `string` | — | The `accept` attribute, and the same list the refusal partition is computed against. |
+| `multiple` | `boolean` | — |  |
+| `size` | `Size` | — |  |
+| `required` | `boolean` | — |  |
+| `disabled` | `boolean` | — |  |
+| `maxBytes` | `number` | — | Client-side ceiling. The server enforces its own; this only spares a doomed transfer. |
+| `maxFiles` | `number` | — |  |
+| `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` | — |  |
+| `aria-label` | `string` | — |  |
+| `aria-describedby` | `string` | — |  |
+| `aria-invalid` | `boolean` | — |  |
+| `onSelect` | `((selection: FileSelection<File>) => void)` | — | Every chosen file, partitioned into accepted and refused-with-a-reason. |
+| `onBlur` | `JSX.EventHandlerUnion<HTMLInputElement, FocusEvent>` | — |  |
+
 ### Form
 
-Form shell. Owns the one thing every form needs and always forgets: a top-of-form error summary that is focusable and announced on submit.
+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.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -304,6 +385,17 @@ Grid layout primitive. The default is an intrinsic responsive grid (`auto-fit` +
 | `as` | `'div' \| 'ul' \| 'ol' \| 'section'` | — |  |
 | `class` | `string` | — |  |
 
+### Icon
+
+Inline SVG from one Lucide glyph. Decorative by default (`aria-hidden`); a `label` promotes it to `role="img"` with a name. Paint is `currentColor` and the box is one `em`, so an icon takes the tone and the type step of whatever it sits inside.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `glyph` | `IconGlyph` | yes | One glyph module: `import { iconSearch } from '@ultimat3/ui/icons/search'`. |
+| `label` | `string` | — | Already-translated accessible name. Omitted means decorative, and a decorative icon is hidden from assistive tech rather than read as a nameless image. |
+| `size` | `Size` | — |  |
+| `class` | `string` | — |  |
+
 ### IconButton
 
 A button whose only content is an icon, so `label` is mandatory: it becomes the accessible name and the tooltip. There is no unlabelled icon button.
@@ -339,6 +431,20 @@ Zero-CLS image primitive: a plain <img>, no JS, no fetch, no client state.  The
 | `height` | `number` | — |  |
 | `class` | `string` | — |  |
 
+### InfiniteScroll
+
+An endless list that degrades to pagination: the foot is always a real `rel="next"` link, so the next page is one navigation away with scripting off. With script, a sentinel below the list asks for that page before the reader reaches it, and the link's click is intercepted.
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `JSX.Element` | yes | The items rendered so far. This component owns the foot, never the list. |
+| `hasMore` | `boolean` | yes | Another page exists. |
+| `nextHref` | `string` | — | The next page's URL. Required whenever `hasMore` — it is the no-JS path. |
+| `loading` | `boolean` | — | A page is in flight; the control stops inviting a second request. |
+| `onLoadMore` | `(() => void)` | — | The enhancement: called when the sentinel appears, and in place of following the link. |
+| `rootMargin` | `string` | — | How far below the fold loading starts. A CSS length, as IntersectionObserver takes it. |
+| `class` | `string` | — |  |
+
 ### Input
 
 Single-line text control. No `type="number"` convenience wrapper: numeric input uses `inputmode` + a text type so locale decimal separators survive.
@@ -574,7 +680,7 @@ Flex layout primitive. Gap comes from the space scale as a custom property, so t
 
 ### Switch
 
-Boolean toggle with immediate effect (as opposed to Checkbox, which is part of a form submit). `role="switch"` on a native checkbox keeps keyboard behaviour.
+Boolean toggle with immediate effect (as opposed to Checkbox, which is part of a form submit). `role="switch"` on a native checkbox keeps keyboard behaviour — and its checked state, which is why nothing here writes `aria-checked`: `role="switch"` maps the host `checked` state on its own, and an attribute mirroring it never updates on the no-JS path, where ARIA would then outrank the truth and announce the switch stuck in whichever position it was rendered in.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -664,18 +770,19 @@ Theme control. `toggle` flips light/dark; `select` also offers "system", which c
 
 ### ToastRegion
 
-Transient notification. ToastRegion is the single live region for the app; individual Toasts are its children, so announcements are not duplicated and the region exists before the first message (screen readers require that).
+Transient notification. ToastRegion is the single live region for the app; individual Toasts are its children, so announcements are not duplicated and the region exists before the first message. That ordering is the whole point: a live region created with its content already in it is not announced by most screen readers, which is why `aria-live` sits on the persistent <ol> here and NOT on the <li> each Toast renders.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
 | `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'` | — |  |
 | `class` | `string` | — |  |
 
 ### Toast
 
-Transient notification. ToastRegion is the single live region for the app; individual Toasts are its children, so announcements are not duplicated and the region exists before the first message (screen readers require that).
+Transient notification. ToastRegion is the single live region for the app; individual Toasts are its children, so announcements are not duplicated and the region exists before the first message. That ordering is the whole point: a live region created with its content already in it is not announced by most screen readers, which is why `aria-live` sits on the persistent <ol> here and NOT on the <li> each Toast renders.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
@@ -689,7 +796,7 @@ Transient notification. ToastRegion is the single live region for the app; indiv
 
 ### 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 controls and the strip costs one Tab stop instead of a dozen.
+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.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|

package/CLAUDE.md

@@ -0,0 +1,77 @@
+# @ultimat3/ui — agent notes
+
+Tier 5. Imports `@ultimat3/core`, `schema`, `i18n`, `money`, `time`. Never `http`, `action`, `render`, `admin`.
+
+## Boundary
+
+| Owns | Does not own |
+|---|---|
+| design tokens, theme resolution, Solid primitives, a11y helpers, the Lucide icon wrapper | routing, data fetching, business logic, layout of a specific app, icon **artwork** |
+
+## Hard rules
+
+- **SCSS modules only.** `Foo.tsx` + `Foo.module.scss`, always paired. No Tailwind, no CSS-in-JS, no inline `style` except CSS custom properties.
+- **No raw colours.** Only `t.role('<role>')` / `var(--color-*)`. Canonical roles live in `src/tokens/_colors.scss`; `tokens.ts` mirrors them and `tokens.test.ts` fails on drift.
+- **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'`.
+- **`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()`. Those two read **core's own `Ctx.locale` / `Ctx.tz`**, which `@ultimat3/http`'s `locale` stage writes once per request; `@ultimat3/i18n` and `@ultimat3/time` publish no field of their own. Never add a second ambient store here or there — `time` kept a `ctx['timeZone']` nothing wrote until 2026-08, and the whole cost was invisible: every server-rendered date formatted in UTC under a doc comment saying it did not. `theme`/`currency` deliberately have no ambient source at all.
+- **`UiProvider` is client-only and throws on the server** (`providerNeedsRuntimeError`, the same `X_UI_RUNTIME_MISSING`). A Provider in an inert tree reaches no descendant — the tree is built before the renderer walks it, so consumers are walked outside every owner and read the context default even with a real Solid runtime registered. Rendering the children anyway would drop its locale, zone, currency and translator silently. Making it work needs the *renderer* to scope a context around the walk; until then it refuses.
+- **A component may call `solid()` freely.** Its effects must stay DOM-only work — they simply never run on the server.
+- **No `{...rest}` prop spreading.** Splitting props reactively needs solid's `splitProps` (a value import), so components declare explicit props and read `props.x` inside JSX.
+- **No hardcoded strings.** Label props, or `useUi().t(UI_KEYS.x)`. New built-in strings go in `src/i18n-keys.ts`.
+- **Page layout is four composites**: `AppShell` (frame + skip link + landmarks), `PageHeader`, `Section`, `Toolbar`. A screen that hand-rolls a header grid is the bug they exist to prevent. `AppShell` holds no state — off-canvas is `Drawer`.
+- **Restyling goes through `defineTheme()`**, never a forked stylesheet and never an SCSS `with ()` override. Its values are validated, not escaped: the output lands in a `<style>` element.
+- **`@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.
+- **One icon, one module.** The `Icon` component takes a `glyph`, not a name: a `name → glyph` map would be one module holding 1767 icons, and no bundler can split that. Per-icon imports are the whole point (1 icon = 104 B minified, 50 = 8.9 kB).
+- **No client runtime exists yet.** A new interactive component must be correct server-rendered and usable with scripting off — `<details>` for disclosure, `<input list>`+`<datalist>` for suggestions, a real `rel="next"` link for paging — with listeners and observers as additive extras. A component that renders nothing until JS runs does not ship.
+- **`inert-render.test.ts` must not assume which factory its `.tsx` compiled to.** `@ultimat3/render`'s `index.ts` installs a process-global `Bun.plugin` `onLoad` for `/\.tsx$/` at import, and `bun test` is one process — so any file in the run that imports render first makes every ui component after it compile to render's `h` instead of the file's own inert copy. The walker recognises both (`Symbol.for('ultimate.render.jsx')`, off the global registry, never an import), and the first test in the describe asserts a component returned a node it recognises. Without both halves the file silently rendered `"[object Object]"` and 26 assertions were decided by shard packing.
+- **Components are not unit-tested through a renderer.** `.tsx` compiles to `@ultimat3/render`'s `h`, which this package may not import, so every rule lives in a pure module beside the component (`icon-glyph.ts`, `accordion-view.ts`, `combobox-filter.ts`, `infinite-scroll-view.ts`) and *that* is what the tests assert.
+- Formatting logic lives in a pure `*-view.ts` next to the component (`money-view.ts`, `date-time-view.ts`) so it is testable with no renderer. Every other renderer-free core follows the same rule under its own name (`sort-state.ts`, `image-source.ts`) — the `.tsx` holds markup, never a rule.
+- **The rule being pure is not enough — the WIRING has to be tested too.** `createRovingTabindex` was correct and `Menu` handed it `[role="menuitem"]`, so a disabled item made every item after it unreachable and every assertion in the package still passed. `src/jsx-probe.ts` reads the props an element actually carries (a `tabindex`, an `aria-live`, an `onKeyDown`, a `ref`) and `src/fake-dom.ts` gives it a DOM where a disabled control REFUSES focus, exactly as the real one does. Both are test-only and neither is in `index.ts`. `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.
+- **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.
+- **Generated source is a CODE sink.** `build-icons.ts` writes modules every app EXECUTES at import, from data fetched over the network, so an attribute value goes through `JSON.stringify` and never `'${value}'` — and `SAFE_ATTR_VALUE` refuses anything that is not glyph geometry one layer earlier. `iconElements` guards tags and attribute NAMES; it has never guarded a value. Malformed upstream data is `X_UI_INVALID_VALUE`; only the generator's real environment faults (no network, no biome binary) are `X_UI_RUNTIME_MISSING`.
+
+## Files
+
+| Path | Responsibility |
+|---|---|
+| `src/tokens/*.scss` | canonical token maps + `_mixins.scss` authoring helpers |
+| `src/tokens/theme.scss` | the only stylesheet that emits global custom properties |
+| `src/theme/solid-adapter.ts` | the runtime slot and the one rule that decides which runtime a render gets |
+| `src/theme/inert-runtime.ts` | `INERT_SOLID_RUNTIME` — what a server render IS, not a stub of what it lacks |
+| `src/theme/theme.ts` | resolution: stored choice → OS; all side effects via injected `ThemeEnv` |
+| `src/theme/inline-script.ts` | anti-flash `<head>` snippet + its CSP sha256 |
+| `src/components/` | 50 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/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/fake-dom.ts` | TEST-ONLY: a DOM where a disabled control refuses focus. Never exported from `index.ts` |
+| `src/jsx-probe.ts` | TEST-ONLY: a component's node tree, so a test can assert the props and call the handlers an element carries |
+| `src/components/style-classes.test.ts` | the build error behind "every `styles['x']` a component names is declared in its own `.module.scss`" — under `bun test` a `.module.scss` import resolves to the file PATH, so no render can catch a dead class |
+
+## Assumed peer contracts
+
+`@ultimat3/money` → `formatMoney(money, { locale })`; `@ultimat3/time` → `formatDateTime(date, { locale, timeZone, dateStyle?, timeStyle? })`. Both are injectable via a `format` prop, so a signature change touches one line.
+
+## Commands
+
+```
+bun test                                  # from the repo root
+bun run --filter @ultimat3/ui typecheck
+bun run --filter @ultimat3/ui catalog     # after any prop change — CATALOG.md is gated
+bun run --filter @ultimat3/ui icons       # regenerate the glyph set (network; dev-only)
+```
+
+## Deep import
+
+`@ultimat3/ui/icons/*` resolves through the package's `exports` map. Inside this monorepo a
+`tsconfig` that maps `@ultimat3/*` to `packages/*/src` needs the more specific entry
+`"@ultimat3/ui/icons/*": ["./packages/ui/src/icons/glyphs/*"]` for TypeScript to follow it —
+runtime resolution is the `exports` map either way.

package/README.md

@@ -61,7 +61,7 @@ Four composites cover the frame of an app screen. Below them are `Container`,
 | `AppShell` | skip link + `header` / `nav` / `main` / `footer` landmarks on a CSS grid | the frame every screen sits in — one per document |
 | `PageHeader` | breadcrumbs, the page's one `h1`, description, actions | the top of a screen |
 | `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 | filters and actions above a table or list |
+| `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.
@@ -82,6 +82,62 @@ never skips a level.
 </AppShell>
 ```
 
+## Icons
+
+The set is [Lucide](https://lucide.dev) (ISC), wrapped — not redrawn. Every one of its
+**1767 icons** is a module of its own, generated from upstream `lucide-static` node data
+by `bun run icons`, so an import is one glyph and a bundler drops the rest.
+
+```tsx
+import { Icon } from '@ultimat3/ui';
+import { iconSearch } from '@ultimat3/ui/icons/search';       // one module, one icon
+import { iconCircleAlert } from '@ultimat3/ui/icons/circle-alert';
+
+<Icon glyph={iconSearch} />                                    // decorative → aria-hidden
+<Icon glyph={iconCircleAlert} label={t('form.invalid')} />     // meaningful → role="img"
+```
+
+| Rule | How |
+|---|---|
+| Module per icon | `@ultimat3/ui/icons/<kebab-name>`, exporting `icon<PascalName>` — `iconDelete`, not `delete`, so reserved words stay legal |
+| Pay for what you use | one icon **104 B** minified, fifty **8.9 kB**, all 1767 **365 kB** — measured with `bun build --minify` |
+| Colour | `currentColor` only; a glyph carrying a literal colour is refused with `X_UI_INVALID_VALUE` |
+| Size | `sm` / `md` / `lg` map to `--text-*` and the box is `1em` — no icon carries a pixel literal |
+| Accessible name | omitted `label` means `aria-hidden="true"`; a `label` promotes it to `role="img"` with that name |
+| Attributes | only the tags and attributes in `ICON_TAGS` reach the DOM — glyph data never becomes an arbitrary attribute |
+
+Upstream bump: raise `LUCIDE_VERSION` in `src/icons/build-icons.ts`, run `bun run icons`,
+commit the diff. There is no hand-edited icon in the package.
+
+## Works without JavaScript
+
+Three components are interactive without a client runtime, because the platform already
+has the behaviour. Each is correct server-rendered, and the script layer only adds.
+
+| Component | Platform base | The enhancement |
+|---|---|---|
+| `Accordion` | `<details>` / `<summary>`; `exclusive` is the native `name` group | `onToggle` notification, after the browser has applied it |
+| `Combobox` | `<input list>` + `<datalist>` — typing, filtering, keyboard, mobile | `onFilter`, debounced, for a live/server-side query |
+| `InfiniteScroll` | a real `rel="next"` link to the next page | an `IntersectionObserver` sentinel that calls `onLoadMore` and intercepts the click |
+
+```tsx
+<Accordion level={3} exclusive items={[{ id: 'ship', title: t('faq.ship'), panel: <p>…</p> }]} />
+
+<Combobox name="city" value={query()} options={cities} onFilter={setQuery} debounceMs={250} />
+
+<InfiniteScroll hasMore={page.hasNext} nextHref={`?page=${page.next}`} onLoadMore={loadNext}>
+  {rows}
+</InfiniteScroll>
+```
+
+`InfiniteScroll` refuses `hasMore` without a `nextHref` (`X_UI_INVALID_VALUE`): with
+scripting off the control is a link, and a link needs somewhere to go. `Combobox` filters
+what it is given by `value` (`filterOptions` — case- and accent-insensitive, prefix first),
+so the list is right on the first paint and after a form round-trip, not only once JS runs.
+
+`debounce(fn, ms)` is exported on its own: trailing edge, `cancel()`, `flush()`, `pending()`.
+Components cancel theirs on cleanup, so a filter never fires into a tree that is gone.
+
 ## Branding
 
 `defineTheme()` is the **only** seam for restyling. No SCSS `@use ... with ()`
@@ -89,7 +145,7 @@ override, no forked package, no second entry point — one call, validated, rend
 as the custom properties that beat `theme.scss` at every specificity level it emits.
 
 ```ts
-import { brandStyleTag, defineTheme } from '@ultimat3/ui';
+import { brandStyleCspSource, brandStyleTag, defineTheme } from '@ultimat3/ui';
 
 export const brand = defineTheme({
   colors: {
@@ -102,6 +158,11 @@ export const brand = defineTheme({
 
 // 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)}`;
 ```
 
 | Slot | Accepts | Refused with |
@@ -115,19 +176,57 @@ anything carrying `;`, `}` or `</style>` is a refusal at the app's entry point r
 than a CSS injection. Every component in the system follows the override — they only
 ever read the roles, never a colour.
 
+## The two render paths
+
+Every component renders on the server. Half of them read the ambient presentation context —
+locale, time zone, currency, direction, translator — and where that context comes from is the
+only thing that differs between a server render and a hydrated one. **An app registers nothing
+to render on the server.**
+
+| | Server render | Client render |
+|---|---|---|
+| The renderer | `@ultimat3/render`'s inert JSX factory — a component is a plain function, called once | Solid, with a reactive graph |
+| The runtime | `INERT_SOLID_RUNTIME`, handed out automatically: signals hold, memos recompute on read, effects never run | the real one, registered once: `setSolidRuntime(await import('solid-js'))` |
+| Where `useUi()` reads | the request — `currentLocale()`, `currentTimeZone()`, `useI18n()` | `<UiProvider>`, through Solid's context |
+| `<UiProvider>` | **throws** `X_UI_RUNTIME_MISSING` | the one injection point |
+
+`<UiProvider>` is client-only on purpose. A Provider in an inert tree reaches no descendant —
+the tree is already built when the renderer walks it, so every consumer is walked outside every
+owner and sees the context default, with a real Solid runtime registered too. Rendering the
+children anyway would drop the locale, zone, currency and translator it was handed while looking
+like it worked, so it refuses instead and names the fix.
+
+The mirror image is just as loud: a **DOM** with no registered runtime is the "my theme toggle
+does nothing" bug, and `solid()` still throws there. No DOM, no reactivity to lose.
+
+Server-side, the locale and zone are `ctx.locale` and `ctx.tz` — **core's own fields**, written
+once per request by `@ultimat3/http`'s `locale` stage and read back by `currentLocale()` /
+`currentTimeZone()`. `withChildContext({ locale, tz })` scopes a subtree. There is no second
+ambient store, here or anywhere: `@ultimat3/time` used to keep its own `ctx['timeZone']` that
+nothing ever wrote, so every server-rendered date was UTC however the request arrived.
+
 ## Example
 
 ```tsx
-import { Button, Field, Input, setSolidRuntime, UiProvider } from '@ultimat3/ui';
-import '@ultimat3/ui/global.scss';
+import { Button, Field, Input } from '@ultimat3/ui';
+import '../../shared/global'; // `shared/global.scss` is the app's one `@use '@ultimat3/ui/global.scss'`
+
+// A server render. `useUi()` inside <Field> reads the request's locale, direction and zone —
+// nothing to register, nothing to wrap.
+<Field label={t('signup.email')} hint={t('signup.email.hint')} error={errors.email}>
+  {(control) => <Input {...control} type="email" autocomplete="email" />}
+</Field>
+<Button tone="accent">{t('signup.submit')}</Button>
+```
 
-setSolidRuntime(await import('solid-js'));   // once, in the app entry
+```tsx
+// A client entry — an island, or a hydrated app shell. Both lines, in this order, once.
+import { setSolidRuntime, UiProvider } from '@ultimat3/ui';
+
+setSolidRuntime(await import('solid-js'));
 
 <UiProvider locale="ar-EG" timeZone="Africa/Cairo" currency="EGP" t={t}>
-  <Field label={t('signup.email')} hint={t('signup.email.hint')} error={errors.email}>
-    {(control) => <Input {...control} type="email" autocomplete="email" />}
-  </Field>
-  <Button tone="accent" loading={pending()}>{t('signup.submit')}</Button>
+  {tree}
 </UiProvider>
 ```
 
@@ -163,6 +262,26 @@ renditions and the data-URI blur placeholder are build-pipeline steps
 of this package. The component emits what it is handed and fabricates nothing —
 no variants it was not given, no dimensions it did not measure.
 
+## Keyboard groups
+
+`As of 2026-08`: a roving group — `Menu`, `Tabs`, `Toolbar` — is one Tab stop into a set of
+controls, and arrows move within it. Three rules, all of them in `src/roving.ts` and all of them
+enforced by tests:
+
+| Rule | Why |
+|---|---|
+| a disabled item is in neither the navigable set nor the tab stop (`MENU_ITEM_SELECTOR`, `TAB_SELECTOR`, `tabStopIndex`) | `focus()` on a disabled control is a **no-op**, so a disabled item left in the list pins the reducer on its index and hides everything after it |
+| the tab stop is the selection, or the first **enabled** item (`tabStopIndex`) | a group whose only tab stop is disabled cannot be entered at all |
+| a control that answers arrows itself keeps them (`handlesOwnArrowKeys`) | `Toolbar` exists to hold a search field, and stealing ArrowRight from it eats the keystroke moving the caret |
+
+`Toolbar` is deliberately **not** a single Tab stop: it holds arbitrary children it cannot reach
+into to set an initial `tabindex`, and a search field at its inline start keeps its own arrows —
+one stop there would strand every control past it.
+
+`As of 2026-08`, `ToastRegion` owns the live region, not `Toast`: the `<ol>` carries `aria-live`
+and outlives every message, because a region created with its content already inside it is not announced. One region,
+one politeness — `politeness="assertive"` for a region that carries errors alone.
+
 ## Theme resolution
 
 `explicit choice in localStorage` → `OS preference`. `setTheme()` persists,
@@ -180,8 +299,8 @@ Content-Security-Policy: script-src 'self' 'sha256-…'   # themeInlineScriptCsp
 |---|---|
 | `X_TOKEN_UNKNOWN` | a token role the SCSS source does not define — including a `defineTheme()` override of a role, radius or font slot that is not in the scale |
 | `X_THEME_INVALID` | a theme other than `light` / `dark` |
-| `X_UI_RUNTIME_MISSING` | reactive context or DOM APIs used where they do not exist |
-| `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, or a `defineTheme()` value that is not a token value |
+| `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_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
 
@@ -189,4 +308,5 @@ Content-Security-Policy: script-src 'self' 'sha256-…'   # themeInlineScriptCsp
 bun test                 # token parity, contrast, theme resolution, brand, catalog drift, a11y
 bun run typecheck
 bun run catalog          # regenerate CATALOG.md after changing a component's props
+bun run icons            # regenerate src/icons/glyphs/* from lucide-static (network, dev-only)
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ui",
-  "version": "1.2.0",
+  "version": "3.0.0",
   "description": "SolidJS design system: semantic design tokens, dark/RTL-ready SCSS modules, a11y primitives",
   "license": "MIT",
   "type": "module",
@@ -15,6 +15,7 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./icons/*": "./src/icons/glyphs/*.ts",
     "./tokens": "./src/tokens/_index.scss",
     "./theme.scss": "./src/tokens/theme.scss",
     "./reset.scss": "./src/tokens/reset.scss",
@@ -24,6 +25,7 @@
     "src",
     "!src/**/*.test.ts",
     "CATALOG.md",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -33,15 +35,16 @@
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test",
-    "catalog": "bun run src/catalog/build-catalog.ts"
+    "catalog": "bun run src/catalog/build-catalog.ts",
+    "icons": "bun run src/icons/build-icons.ts"
   },
   "dependencies": {
-    "@ultimat3/core": "1.2.0",
-    "@ultimat3/i18n": "1.2.0",
-    "@ultimat3/money": "1.2.0",
-    "@ultimat3/time": "1.2.0"
+    "@ultimat3/core": "3.0.0",
+    "@ultimat3/i18n": "3.0.0",
+    "@ultimat3/money": "3.0.0",
+    "@ultimat3/time": "3.0.0"
   },
   "peerDependencies": {
-    "solid-js": "^2.0.0"
+    "solid-js": "^1.9.0"
   }
 }