@ultimat3/ui 1.2.0 → 2.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.
@@ -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.
@@ -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,6 +329,30 @@ 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.
@@ -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.

package/CLAUDE.md

@@ -0,0 +1,68 @@
+# @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.
+
+## 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 |
+
+## 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

@@ -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>
+```
+
+```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'));   // once, in the app entry
+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>
 ```
 
@@ -180,8 +279,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`, or a negative `debounce` window |
 
 ## Commands
 
@@ -189,4 +288,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": "2.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": "2.0.0",
+    "@ultimat3/i18n": "2.0.0",
+    "@ultimat3/money": "2.0.0",
+    "@ultimat3/time": "2.0.0"
   },
   "peerDependencies": {
-    "solid-js": "^2.0.0"
+    "solid-js": "^1.9.0"
   }
 }

package/src/a11y.ts

@@ -21,8 +21,16 @@ export const FOCUSABLE_SELECTOR = [
 let idCounter = 0;
 
 /**
- * Stable-per-render unique id for label/description wiring. Prefixed so a
- * hydration mismatch is obvious in the DOM rather than silent.
+ * Unique id for label/description wiring, from a PROCESS-wide counter. Prefixed so a mismatch is
+ * obvious in the DOM rather than silent.
+ *
+ * Correct for the only render path that exists: a server render walks a tree once, so every id in
+ * one document is distinct, which is all `for`/`aria-describedby` need. It is NOT stable across two
+ * renders of the same tree — a second process, or a client re-render, starts its own count — so it
+ * cannot survive hydration. That is latent rather than broken: this package has no client runtime
+ * (see CLAUDE.md), so nothing re-renders a server tree yet. Making it survive needs a
+ * RENDER-SCOPED counter, which means a seam in `@ultimat3/render` (or a `SolidRuntime` member);
+ * resetting this one per request would only move the collision. Do not paper over it here.
  */
 export function useId(prefix = 'u'): string {
   idCounter += 1;

package/src/components/Accordion.module.scss

@@ -0,0 +1,59 @@
+@use '../tokens' as t;
+
+.accordion {
+  @include t.column(0);
+  border: 1px solid t.role('line');
+  border-radius: t.radius(lg);
+  background: t.role('surface');
+  overflow: hidden;
+}
+
+.section + .section {
+  border-block-start: 1px solid t.role('line');
+}
+
+.summary {
+  @include t.row(t.space(2));
+  @include t.focus-ring;
+  @include t.transition(background);
+  padding-block: t.space(3);
+  padding-inline: t.space(4);
+  color: t.role('fg-strong');
+  font-weight: t.weight(medium);
+  cursor: pointer;
+
+  // The default triangle is replaced by the chevron, in both engines.
+  list-style: none;
+
+  &::-webkit-details-marker {
+    display: none;
+  }
+
+  &:hover {
+    background: t.role('bg-soft');
+  }
+}
+
+// A chevron on the block axis, not the inline one: down/up needs no RTL mirror, so there is
+// no `[dir='rtl']` rule to keep in sync with the glyph.
+.marker {
+  @include t.transition(rotate);
+  color: t.role('fg-muted');
+  rotate: 0deg;
+}
+
+[open] > .summary > .marker {
+  rotate: 180deg;
+}
+
+.title {
+  margin: 0;
+  font: inherit;
+  color: inherit;
+}
+
+.panel {
+  padding-block-end: t.space(4);
+  padding-inline: t.space(4);
+  color: t.role('fg');
+}

package/src/components/Accordion.tsx

@@ -0,0 +1,63 @@
+// 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.
+
+import type { JSX } from 'solid-js';
+import { useId } from '../a11y';
+import { cx } from '../cx';
+import { iconChevronDown } from '../icons/glyphs/chevron-down';
+import styles from './Accordion.module.scss';
+import type { AccordionSection } from './accordion-view';
+import { accordionOpenIds } from './accordion-view';
+import type { HeadingLevel } from './heading-level';
+import { headingTag } from './heading-level';
+import { Icon } from './Icon';
+
+export interface AccordionItem extends AccordionSection {
+  /** Already-translated section title. */
+  title: string;
+  panel: JSX.Element;
+  /** Expanded on first paint — a real `open` attribute, so no script has to run. */
+  defaultOpen?: boolean | undefined;
+}
+
+export interface AccordionProps {
+  items: readonly AccordionItem[];
+  /** One section open at a time, through the native `<details name>` group. */
+  exclusive?: boolean | undefined;
+  /**
+   * 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.
+   */
+  level?: HeadingLevel | undefined;
+  /** Fires on every open and close, once the browser has already applied it. */
+  onToggle?: ((id: string, open: boolean) => void) | undefined;
+  class?: string | undefined;
+}
+
+export function Accordion(props: AccordionProps): JSX.Element {
+  const base = useId('accordion');
+  const open = accordionOpenIds(props.items, props.exclusive === true);
+  const Title = props.level === undefined ? 'span' : headingTag(props.level);
+
+  return (
+    <div class={cx(styles['accordion'], props.class)}>
+      {props.items.map((item) => (
+        <details
+          id={`${base}-${item.id}`}
+          class={styles['section']}
+          name={props.exclusive === true ? base : undefined}
+          open={open.has(item.id)}
+          onToggle={(event) => props.onToggle?.(item.id, event.currentTarget.open)}
+        >
+          <summary class={styles['summary']}>
+            <Icon glyph={iconChevronDown} class={styles['marker']} size="sm" />
+            <Title class={styles['title']}>{item.title}</Title>
+          </summary>
+          <div class={styles['panel']}>{item.panel}</div>
+        </details>
+      ))}
+    </div>
+  );
+}

package/src/components/Avatar.tsx

@@ -2,6 +2,7 @@
 // empty alt (the name is rendered as text or the accessible label), so it can
 // never shift layout or duplicate the name to a screen reader.
 
+import { safeUrl } from '@ultimat3/core';
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
 import styles from './Avatar.module.scss';
@@ -48,7 +49,14 @@ export function Avatar(props: AvatarProps): JSX.Element {
           {initialsOf(props.name)}
         </span>
       ) : (
-        <img src={props.src} alt="" width={px()} height={px()} loading="lazy" decoding="async" />
+        <img
+          src={safeUrl(props.src, 'src') ?? undefined}
+          alt=""
+          width={px()}
+          height={px()}
+          loading="lazy"
+          decoding="async"
+        />
       )}
       <span class={styles['name']}>{props.name}</span>
     </span>

package/src/components/Breadcrumb.tsx

@@ -6,6 +6,7 @@ import { cx } from '../cx';
 import { UI_KEYS } from '../i18n-keys';
 import { useUi } from '../theme/context';
 import styles from './Breadcrumb.module.scss';
+import { linkTarget } from './link-target';
 
 export interface BreadcrumbItem {
   /** Already-translated label. */
@@ -36,7 +37,7 @@ export function Breadcrumb(props: BreadcrumbProps): JSX.Element {
                 {item.label}
               </span>
             ) : (
-              <a class={styles['link']} href={item.href}>
+              <a class={styles['link']} href={linkTarget(item.href).href}>
                 {item.label}
               </a>
             )}