npm - @ultimat3/ui - Versions diffs - 6.0.0 → 7.0.0 - Mend

@ultimat3/ui 6.0.0 → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md +64 -9
package/package.json +9 -5
package/src/errors.ts +11 -7
package/src/theme/solid-adapter.ts +18 -2

package/README.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,9 +1,13 @@
 {
   "name": "@ultimat3/ui",
-  "version": "6.0.0",
+  "version": "7.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",
@@ -39,10 +43,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": "7.0.0",
+    "@ultimat3/i18n": "7.0.0",
+    "@ultimat3/money": "7.0.0",
+    "@ultimat3/time": "7.0.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"

package/src/errors.ts CHANGED Viewed

@@ -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/theme/solid-adapter.ts CHANGED Viewed

@@ -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;