@ultimat3/ui 6.0.0 → 8.0.0

package/CLAUDE.md

@@ -1,6 +1,6 @@
 # @ultimat3/ui — agent notes
 
-Tier 5. Imports `@ultimat3/core`, `schema`, `i18n`, `money`, `time`. Never `http`, `action`, `render`, `admin`.
+Tier 4 (moved 5 → 4 on 2026-08-19, when the `admin → ui` exception was deleted). Imports `@ultimat3/core`, `schema`, `i18n`, `money`, `time`. Never `http`, `action`, `render`, `admin` — `render` is tier 4 too, which is what keeps the static bundle graph out of the design system.
 
 ## Boundary
 
@@ -29,7 +29,7 @@ Tier 5. Imports `@ultimat3/core`, `schema`, `i18n`, `money`, `time`. Never `http
 - **`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.
+- **The rule being pure is not enough — the WIRING has to be tested too.** `createRovingTabindex` was correct and `Menu` handed it `[role="menuitem"]`, so a disabled item made every item after it unreachable and every assertion in the package still passed. `src/jsx-probe.ts` reads the props an element actually carries (a `tabindex`, an `aria-live`, an `onKeyDown`, a `ref`) and `src/fake-dom.ts` gives it a DOM where a disabled control REFUSES focus, exactly as the real one does. Both are test-only and neither is in `index.ts`. `jsx-probe`'s `probe`/`unprobe` are the one exception, reachable at the subpath `@ultimat3/ui/jsx-probe` and still absent from the barrel: `globalThis.React` is ONE property, so its install/restore counter has to be ONE counter — `@ultimat3/admin` (tier 5) kept a second pair, and interleaved installs restored the two harnesses in the wrong order, leaving the global holding a harness the run had already torn down. `components/interaction.test.ts` is where a keyboard or form-participation claim gets proven; asserting the pure helper alone is how these shipped.
 - **A roving group excludes disabled items from both answers** — the set arrows walk and the one item holding the tab stop (`src/roving.ts`). `focus()` on a disabled control is a no-op, so a disabled item left in the list pins the reducer on its index forever. And a control that answers arrows itself (`handlesOwnArrowKeys`) keeps them: a `Toolbar` exists to hold a search field.
 - **A single-winner state attribute is decided by POSITION, never by a missing prop.** `Breadcrumb` gives `aria-current="page"` to the last item and to nothing else; an href-less ancestor renders as plain text with no `aria-current` at all. Reading "no href" as "is the current page" put two of them in one `<nav>`. `Tabs.tsx` is the same rule for `tabindex`, and `Breadcrumb.test.ts` proves it through `jsx-probe` rather than through the pure helper.
 - **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.
@@ -55,7 +55,7 @@ Tier 5. Imports `@ultimat3/core`, `schema`, `i18n`, `money`, `time`. Never `http
 | `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/jsx-probe.ts` | TEST-ONLY: a component's node tree, so a test can assert the props and call the handlers an element carries. `probe`/`unprobe` are the framework's ONE owner of `globalThis.React`, reached from `@ultimat3/admin` at `@ultimat3/ui/jsx-probe`; the walkers stay internal |
 | `src/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

package/README.md

@@ -186,7 +186,7 @@ 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'))` |
+| The runtime | `INERT_SOLID_RUNTIME`, handed out automatically: signals hold, memos recompute on read, effects never run | the real one, registered once: `setSolidRuntime(solidRuntime)`, from `import * as solidRuntime from '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 |
 
@@ -220,19 +220,74 @@ import '../../shared/global'; // `shared/global.scss` is the app's one `@use '@u
 ```
 
 ```tsx
-// A client entry — an island, or a hydrated app shell. Both lines, in this order, once.
+// A client entry — an island's `mount()`, or a hydrated app shell. In this order, once.
+import { createTranslator } from '@ultimat3/i18n';
 import { setSolidRuntime, UiProvider } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import * as solidRuntime from 'solid-js';
+import { render } from 'solid-js/web';
+
+interface Props {
+  readonly locale: string;
+  readonly timeZone: string;
+  readonly currency: string;
+  /** The `ui.*` keys this tree renders, resolved on the server. A catalog crosses the seam as
+   *  JSON; a `Translator` is a function and cannot. */
+  readonly strings: Readonly<Record<string, string>>;
+  readonly tree: JSX.Element;
+}
+
+export function mount(el: HTMLElement, props: Props): void {
+  // NOT `await import('solid-js')`: the chunk already carries Solid statically, so the await buys
+  // no bytes and makes `mount` async — and the hydration runtime calls it synchronously.
+  setSolidRuntime(solidRuntime);
+  el.textContent = ''; // Solid's `render` APPENDS; the server's shell would stay above this one.
+  render(
+    () => (
+      <UiProvider
+        locale={props.locale}
+        timeZone={props.timeZone}
+        currency={props.currency}
+        t={createTranslator(props.strings, props.locale)}
+      >
+        {props.tree}
+      </UiProvider>
+    ),
+    el,
+  );
+}
+```
 
-setSolidRuntime(await import('solid-js'));
+**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**
+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
+`translatorFor(locale)` on the client is the same empty answer wearing a better name. Send the
+subset the island renders and build the translator from it. `t` itself — `@ultimat3/i18n`'s bare
+exported function — is not a `Translator` and is `TS2739` in this position.
 
-<UiProvider locale="ar-EG" timeZone="Africa/Cairo" currency="EGP" t={t}>
-  {tree}
-</UiProvider>
-```
+An island's own copy is a different thing and stays a plain prop: it arrives already translated,
+as text, because `t()`'s catalog does not cross the seam and neither does a callback.
 
 `Field` owns the ids, so `aria-describedby` / `aria-invalid` can never drift from
-what is rendered. `UiProvider` sets `lang` + `dir` on `<html>`; nothing else is
-needed to make that form correct in Arabic.
+what is rendered. `UiProvider` sets `lang` + `dir` on `<html>` from `locale`, so
+`ar-EG` needs no second stylesheet and no second component.
+
+**An island pays for the barrel, not for the component it named.** Measured through
+`buildIslands` — minified, production Solid, `As of 2026-08-21`:
+
+| An island that imports | Chunk |
+|---|---|
+| nothing | 52 B |
+| `setSolidRuntime` alone | 5.7 kB |
+| `<UiProvider>` + one `<Button>` | 49.0 kB, of which Solid's own runtime is 12.2 kB |
+| `<UiProvider>` + `<Form>` + `<Input>` + `<Button>` | 54.8 kB |
+
+There are no component subpath exports, so `import { Button }` reaches the whole index —
+issue **#275**. `@ultimat3/ui/icons/*` is the one part of the package already shaped the
+other way, and is what the components want. Budget an island against these numbers, not
+against the component's own source.
 
 ## `<Text>` and `<Image>`
 

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@ultimat3/ui",
-  "version": "6.0.0",
+  "version": "8.0.0",
   "description": "SolidJS design system: semantic design tokens, dark/RTL-ready SCSS modules, a11y primitives",
   "license": "MIT",
   "type": "module",
+  "sideEffects": [
+    "./src/errors.ts",
+    "**/*.scss"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/developerz-ai/ultimate.git",
@@ -16,6 +20,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./icons/*": "./src/icons/glyphs/*.ts",
+    "./jsx-probe": "./src/jsx-probe.ts",
     "./tokens": "./src/tokens/_index.scss",
     "./theme.scss": "./src/tokens/theme.scss",
     "./reset.scss": "./src/tokens/reset.scss",
@@ -39,10 +44,10 @@
     "icons": "bun run src/icons/build-icons.ts"
   },
   "dependencies": {
-    "@ultimat3/core": "6.0.0",
-    "@ultimat3/i18n": "6.0.0",
-    "@ultimat3/money": "6.0.0",
-    "@ultimat3/time": "6.0.0"
+    "@ultimat3/core": "8.0.0",
+    "@ultimat3/i18n": "8.0.0",
+    "@ultimat3/money": "8.0.0",
+    "@ultimat3/time": "8.0.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"

package/src/errors.ts

@@ -91,18 +91,22 @@ export function runtimeMissingError(api: string, fix: string): UiError {
 }
 
 /**
- * `<UiProvider>` on a server render. No new code: a reactive runtime is absent, which is exactly
- * what X_UI_RUNTIME_MISSING already names — and a code is stable forever once shipped. The throw
- * is the point. A Provider in an inert tree reaches no descendant (they are walked outside every
- * owner), so rendering the children anyway would drop the locale, zone, currency and translator it
- * was handed while looking like it worked.
+ * `<UiProvider>` with no runtime registered. No new code: a reactive runtime is absent, which is
+ * exactly what X_UI_RUNTIME_MISSING already names — and a code is stable forever once shipped. The
+ * throw is the point. A Provider in an inert tree reaches no descendant (they are walked outside
+ * every owner), so rendering the children anyway would drop the locale, zone, currency and
+ * translator it was handed while looking like it worked.
+ *
+ * TWO callers reach here, not one, and the cause used to name only the first: a server render,
+ * which has no runtime by design, and an island whose `mount` never called `setSolidRuntime` —
+ * which is a real bug in a real browser, and was being told it was a server render.
  */
 export function providerNeedsRuntimeError(): UiError {
   return new UiError({
     code: UI_ERROR_CODES.runtimeMissing,
     cause:
-      '<UiProvider> needs a registered Solid runtime; a server render has none, and its values would reach no component',
-    fix: 'delete <UiProvider> from the server tree — useUi() already reads the request locale and time zone; keep the provider inside your *.island.tsx, under the mount() that called setSolidRuntime()',
+      '<UiProvider> was rendered with no Solid runtime registered, so its locale, time zone, currency and translator would reach no component',
+    fix: "in an island, paste `import * as solidRuntime from 'solid-js';` at the top of the *.island.tsx and `setSolidRuntime(solidRuntime);` as the first line of its mount(), above the render() that builds <UiProvider>; on the server, delete <UiProvider> — useUi() already reads the request locale and time zone",
   });
 }
 

package/src/jsx-probe.ts

@@ -35,6 +35,14 @@ function h(
  * DELETED the property on the way out destroyed a binding it did not create, and a nested or
  * repeated probe tore the factory out from under the suite still using it — the counter is what
  * makes the last unprobe the only one that restores.
+ *
+ * There may be exactly ONE such counter in the framework, and it is this one — `globalThis.React`
+ * is a single property, so a second module counting its own depth over it restores in the wrong
+ * order. `@ultimat3/admin`'s `inert-jsx.ts` kept a second pair and the two interleaved: admin
+ * installs (saving the real binding), ui installs (saving ADMIN's factory), admin restores (both
+ * counters at 1 → the real binding is back), ui restores (its counter hits 0 → admin's factory is
+ * reinstalled over it). The global ended up holding a harness the run had already torn down.
+ * `admin` is tier 5 and `ui` is tier 4, so admin imports these rather than declaring them.
  */
 let depth = 0;
 let saved: PropertyDescriptor | undefined;

package/src/theme/solid-adapter.ts

@@ -9,10 +9,19 @@ import { INERT_SOLID_RUNTIME } from './inert-runtime';
 export type Accessor<T> = () => T;
 export type Setter<T> = (next: T) => void;
 
+/**
+ * `children` is REQUIRED, and that one keyword is what makes `setSolidRuntime(solidRuntime)`
+ * compile at all. Solid's own `ContextProviderComponent` takes `FlowProps`, whose `children` is
+ * required, and a function taking `children?` is not assignable to one taking `children` — so
+ * `typeof import('solid-js')` did not satisfy `SolidRuntime` and the registration this package
+ * documents was a type error nobody had ever compiled: it had zero non-test callers (issue #246),
+ * and every test passed a hand-written fake that matched the declaration instead of the runtime.
+ * `JSX.Element` already includes `undefined`, so a provider with no children still type-checks.
+ */
 export interface SolidContext<T> {
   readonly id: symbol;
   readonly defaultValue: T;
-  readonly Provider: (props: { value: T; children?: JSX.Element }) => JSX.Element;
+  readonly Provider: (props: { value: T; children: JSX.Element }) => JSX.Element;
 }
 
 /** The exact slice of solid-js the design system touches. */
@@ -56,9 +65,16 @@ function hasDom(): boolean {
 export function solid(): SolidRuntime {
   if (runtime !== null) return runtime;
   if (hasDom()) {
+    // Two lines to paste, and both are real: `x g resource` writes exactly them into the slice's
+    // `*-form.island.tsx`. The line this used to hand out was `setSolidRuntime(await
+    // import('solid-js'))`, which makes `mount` ASYNC for nothing — an island chunk already
+    // carries Solid statically, because the same file imports `render` from `solid-js/web`.
     throw runtimeMissingError(
       'a registered Solid runtime',
-      "add setSolidRuntime(await import('solid-js')) at the top of your *.island.tsx's mount() — a server render needs none",
+      // ONE literal, never a concatenation: `fix-scan.ts` reads a single literal in this position
+      // and counts anything else `unreadable`, so a fix split across `+` is a fix the gate stops
+      // checking.
+      "paste `import * as solidRuntime from 'solid-js';` at the top of your *.island.tsx and `setSolidRuntime(solidRuntime);` as the first line of its mount(), above render() — a server render needs none",
     );
   }
   return INERT_SOLID_RUNTIME;