@ultimat3/ui 22.2.2 → 22.3.0

package/CATALOG.md

@@ -478,17 +478,19 @@ A button whose only content is an icon, so `label` is mandatory: it becomes the
 
 ### Image
 
-Zero-CLS image primitive: a plain <img>, no JS, no fetch, no client state.  The build-time half of the pipeline in `docs/idea/07-rendering-seo.md` — reading real dimensions, encoding AVIF/WebP renditions, the data-URI blur placeholder — is NOT here. This component emits exactly what it is handed and fabricates nothing: no variants it was not given, no dimensions it did not measure.
+Zero-CLS image primitive: a plain <img>, or a <picture> around one when AVIF/WebP renditions are handed in. No JS, no fetch, no client state.  The encoding half of the pipeline — AVIF/WebP renditions, measured dimensions — is the app's build step; the URLs come from `asset('assets/…')` in the page. This component emits exactly what it is handed and fabricates nothing, except the one thing it insists on: a reserved box.
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
-| `src` | `string` | yes |  |
+| `src` | `string` | yes | The fallback every browser can decode — usually the JPEG/PNG rendition. |
 | `alt` | `string` | yes | Required, with no default: an <Image> whose meaning is undescribed is a type error at the call site. Pass `alt=""` for a decorative image, deliberately. |
-| `variants` | `readonly ImageVariant[]` | — | Renditions to offer; the descriptors and their order are derived, not written. |
-| `sizes` | `string` | — | Layout width of the box, e.g. `(max-width: 700px) 100vw, 620px`. |
-| `priority` | `boolean` | — | The LCP image, at most one per route: eager, high fetch priority. |
-| `width` | `number` | — | Intrinsic dimensions, from the build step that measured them. Both or neither. |
+| `variants` | `readonly ImageVariant[]` | — | Renditions of `src`'s own encoding; the descriptors and their order are derived. |
+| `sources` | `ImageSources` | — | AVIF and WebP renditions, each a width list: `{ avif: [{ src: asset('…'), width: 640 }] }`. |
+| `sizes` | `string` | — | Layout width of the box, e.g. `(max-width: 700px) 100vw, 620px`. Applies to every set. |
+| `priority` | `boolean` | — | The LCP image, at most one per route: eager, `fetchpriority="high"`, never lazy. |
+| `width` | `number` | — | Intrinsic size in CSS pixels, from the step that encoded it. Both, or `aspectRatio`. |
 | `height` | `number` | — |  |
+| `aspectRatio` | `ImageAspectRatio` | — | `'16 / 9'` — the reservation when the intrinsic size is not known. Never beside width/height. |
 | `class` | `string` | — |  |
 
 ### InfiniteScroll
@@ -565,10 +567,12 @@ Locale picker. Option labels come from `Intl.DisplayNames` in each locale's own
 
 | Prop | Type | Required | Notes |
 |---|---|---|---|
-| `locales` | `readonly Locale[]` | yes |  |
+| `locales` | `readonly Locale[]` | yes | Every locale to offer, the DEFAULT first — `routedLocales()` from `@ultimat3/i18n`. |
 | `value` | `Locale` | — | Defaults to the context locale. |
 | `onLocaleChange` | `((locale: Locale) => void)` | — |  |
-| `hrefFor` | `((locale: Locale) => string)` | — | Render as links instead of a select, for a 0kb-JS `site/` route. |
+| `hrefFor` | `((locale: Locale) => string)` | — | Render as links instead of a select, for a 0kb-JS `site/` route. Defaults, when `path` is given, to that page in each locale — `localizedPath`: unprefixed for the default, `/en/…` otherwise — so a site's switcher needs no href of its own. |
+| `path` | `string` | — | The page's own path, prefixed or not — `new URL(props.url).pathname`. Turns on links mode. |
+| `defaultLocale` | `Locale` | — | The unprefixed locale. Defaults to `locales[0]`, which is where `routedLocales()` puts it. |
 | `class` | `string` | — |  |
 
 ### Menu
@@ -879,7 +883,7 @@ Theme control. `toggle` flips light/dark; `select` also offers "system", which c
 | Prop | Type | Required | Notes |
 |---|---|---|---|
 | `mode` | `'toggle' \| 'select'` | — |  |
-| `initial` | `Theme` | — | Server-render value; the effect corrects it on the client before paint. |
+| `initial` | `Theme` | — | The theme in force at server render — the toggle's glyph. Never the select's choice: nothing on the server knows whether the visitor chose it, so the select shows "system" until the effect reads storage. |
 | `env` | `ThemeEnv` | — | Injectable for tests and for non-DOM hosts. |
 | `class` | `string` | — |  |
 

package/README.md

@@ -401,21 +401,23 @@ transparent inside a heading or a caption.
 | `weight` | keys of `fontWeightTokens`: `normal` `medium` `semibold` `bold` |
 | `as` | `span` (default) `p` `div` `strong` `em` |
 
-`<Image>` is one `<img>` — no JS, no fetch, no client state. `alt` is a required
-prop, so a missing description is a type error rather than a review comment.
+`<Image>` is one `<img>`, or a `<picture>` around one when `sources` is given — no
+JS, no fetch, no client state. `alt` is a required prop, so a missing description
+is a type error rather than a review comment.
 
 | Prop | Emitted |
 |---|---|
 | `variants` | `srcset`, descriptors derived and ordered ascending (`srcsetFor`) |
-| `sizes` | `sizes`, verbatim |
+| `sources` | `{ avif?, webp? }` width lists → `<source type="image/avif">`, then `image/webp`, before the `<img>` (`sourceSetsFor`) |
+| `sizes` | `sizes`, verbatim, on the `<img>` and every `<source>` |
 | `priority` | `loading="eager"` + `fetchpriority="high"`; otherwise `lazy` + `auto`, always `decoding="async"` |
-| `width` + `height` | inlined attributes — both or neither, so the ratio is always reservable |
+| `width` + `height`, or `aspectRatio` | required — one of the two. Inlined attributes plus `--image-ratio` (`aspect-ratio`), so the box is always reserved (`reservedRatio`) |
 
-Shipped here: the element. Measuring intrinsic dimensions, encoding AVIF/WebP
-renditions and the data-URI blur placeholder are build-pipeline steps
-([`docs/idea/07-rendering-seo.md`](../../docs/idea/07-rendering-seo.md)), not part
-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.
+Shipped here: the element. Measuring intrinsic dimensions and encoding AVIF/WebP
+renditions are build-pipeline steps; the URLs come from `asset('assets/…')` in
+`@ultimat3/render` ([Static Assets](../../wiki/Static-Assets.md)). The component
+emits what it is handed and fabricates nothing — no variants it was not given, no
+dimensions it did not measure.
 
 ## Keyboard groups
 
@@ -543,7 +545,7 @@ of truth for the one thing the server decides.
 | `X_UI_FORM_PATH_INVALID` | a form field or control name the path grammar cannot read (`items.0.price`, `items[]`, `__proto__`), or two control names describing different shapes for one path (`user` beside `user.name`) |
 | `X_UI_CONTRAST_INSUFFICIENT` | a `defineTheme()` palette whose resolved channels put a pairing in `CONTRAST_PAIRS` below WCAG 2.2 AA — 4.5:1 for text, 3:1 for the focus ring. Only pairings the brand changed are measured; the cause names the measured ratio and the required one |
 | `X_UI_QR_CAPACITY` | a `<QrCode>` value over version 3's 42-byte ceiling (byte mode, error-correction level M). The encoder draws versions 1–3 only; the cause names the byte count and the ceiling |
-| `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) |
+| `X_UI_INVALID_VALUE` | `<Money>` given a float, `<DateTime>` given an unparseable instant, `<Image>` given mixed `w`/`x` descriptors, one dimension without the other, or no reserved box at all, 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) |
 
 ### Error classes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/ui",
-  "version": "22.2.2",
+  "version": "22.3.0",
   "description": "SolidJS design system: semantic design tokens, dark/RTL-ready SCSS modules, a11y primitives",
   "license": "MIT",
   "type": "module",
@@ -48,10 +48,10 @@
     "icons": "bun run src/icons/build-icons.ts"
   },
   "dependencies": {
-    "@ultimat3/core": "22.2.2",
-    "@ultimat3/i18n": "22.2.2",
-    "@ultimat3/money": "22.2.2",
-    "@ultimat3/time": "22.2.2"
+    "@ultimat3/core": "22.3.0",
+    "@ultimat3/i18n": "22.3.0",
+    "@ultimat3/money": "22.3.0",
+    "@ultimat3/time": "22.3.0"
   },
   "peerDependencies": {
     "solid-js": "^1.9.0"

package/src/components/Image.module.scss

@@ -17,3 +17,9 @@
   color: t.role('fg-muted');
   font-size: t.text(sm);
 }
+
+// A <picture> only chooses a source; it must not become a box of its own, or the <img>'s
+// reservation above would sit inside an inline wrapper with a line box of its own.
+.picture {
+  display: contents;
+}

package/src/components/Image.tsx

@@ -1,9 +1,9 @@
-// Zero-CLS image primitive: a plain <img>, no JS, no fetch, no client state.
+// Zero-CLS image primitive: a plain <img>, or a <picture> around one when AVIF/WebP renditions
+// are handed in. No JS, no fetch, no client state.
 //
-// The build-time half of the pipeline in `docs/idea/07-rendering-seo.md` — reading
-// real dimensions, encoding AVIF/WebP renditions, the data-URI blur placeholder —
-// is NOT here. This component emits exactly what it is handed and fabricates
-// nothing: no variants it was not given, no dimensions it did not measure.
+// The encoding half of the pipeline — AVIF/WebP renditions, measured dimensions — is the app's
+// build step; the URLs come from `asset('assets/…')` in the page. This component emits exactly
+// what it is handed and fabricates nothing, except the one thing it insists on: a reserved box.
 
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
@@ -11,44 +11,70 @@ import styles from './Image.module.scss';
 import {
   assertNonEmptySrc,
   boxFor,
+  type ImageAspectRatio,
   type ImageBox,
   type ImageLoadingHints,
+  type ImageSourceSet,
+  type ImageSources,
   type ImageVariant,
   loadingHints,
-  ratioFor,
+  reservedRatio,
+  sourceSetsFor,
   srcsetFor,
 } from './image-source';
 
-export interface ImageProps {
+/**
+ * The box is ALWAYS reserved: the intrinsic size, or an explicit ratio when the size is not known
+ * (a CSS-sized hero). Neither is a type error here and `X_UI_INVALID_VALUE` at render.
+ */
+export type ImageDimensions =
+  | { width: number; height: number; aspectRatio?: undefined }
+  | { aspectRatio: ImageAspectRatio; width?: undefined; height?: undefined };
+
+export interface ImageBaseProps {
+  /** The fallback every browser can decode — usually the JPEG/PNG rendition. */
   src: string;
   /**
    * Required, with no default: an <Image> whose meaning is undescribed is a type
    * error at the call site. Pass `alt=""` for a decorative image, deliberately.
    */
   alt: string;
-  /** Renditions to offer; the descriptors and their order are derived, not written. */
+  /** Renditions of `src`'s own encoding; the descriptors and their order are derived. */
   variants?: readonly ImageVariant[] | undefined;
-  /** Layout width of the box, e.g. `(max-width: 700px) 100vw, 620px`. */
+  /** AVIF and WebP renditions, each a width list: `{ avif: [{ src: asset('…'), width: 640 }] }`. */
+  sources?: ImageSources | undefined;
+  /** Layout width of the box, e.g. `(max-width: 700px) 100vw, 620px`. Applies to every set. */
   sizes?: string | undefined;
-  /** The LCP image, at most one per route: eager, high fetch priority. */
+  /** The LCP image, at most one per route: eager, `fetchpriority="high"`, never lazy. */
   priority?: boolean | undefined;
-  /** Intrinsic dimensions, from the build step that measured them. Both or neither. */
+  /** Intrinsic size in CSS pixels, from the step that encoded it. Both, or `aspectRatio`. */
   width?: number | undefined;
   height?: number | undefined;
+  /** `'16 / 9'` — the reservation when the intrinsic size is not known. Never beside width/height. */
+  aspectRatio?: ImageAspectRatio | undefined;
   class?: string | undefined;
 }
 
-export function Image(props: ImageProps): JSX.Element {
+/** What a call site passes: the base props, with exactly one of the two box forms required. */
+export type ImageProps = ImageBaseProps & ImageDimensions;
+
+export function Image(props: ImageBaseProps & ImageDimensions): JSX.Element {
   const src = (): string => assertNonEmptySrc('Image', props.src, props.src);
   const hints = (): ImageLoadingHints => loadingHints(props.priority);
+  // Validated first: `reservedRatio` refuses a missing box before anything is emitted.
+  const ratio = (): string => reservedRatio(props.width, props.height, props.aspectRatio);
   const box = (): ImageBox | undefined => boxFor(props.width, props.height);
+  const sets = (): readonly ImageSourceSet[] => sourceSetsFor(props.sources);
+  // Once, eagerly: a compiled `style` binding may be read inside an effect, and a refusal thrown
+  // there reaches no caller. Here it fails the render that wrote the bad props.
+  ratio();
 
-  return (
+  const img = (): JSX.Element => (
     <img
       class={cx(styles['image'], props.class)}
-      // A custom property, because that is the one thing an inline `style` may carry here. Absent
-      // when the dimensions are unknown, and the stylesheet's fallback is then `auto`.
-      style={box() === undefined ? undefined : { '--image-ratio': ratioFor(box()) }}
+      // A custom property, because that is the one thing an inline `style` may carry here. The
+      // stylesheet turns it into `aspect-ratio`, the half of the reservation that survives styling.
+      style={{ '--image-ratio': ratio() }}
       src={src()}
       alt={props.alt}
       srcset={srcsetFor(props.variants)}
@@ -60,4 +86,14 @@ export function Image(props: ImageProps): JSX.Element {
       decoding={hints().decoding}
     />
   );
+
+  if (sets().length === 0) return img();
+  return (
+    <picture class={styles['picture']}>
+      {sets().map((set) => (
+        <source type={set.type} srcset={set.srcset} sizes={props.sizes} />
+      ))}
+      {img()}
+    </picture>
+  );
 }

package/src/components/LocaleSwitcher.tsx

@@ -1,6 +1,9 @@
 // Locale picker. Option labels come from `Intl.DisplayNames` in each locale's own
 // language (endonyms), so the list needs no translation catalog of its own.
 
+// Core's, never the i18n barrel's: that barrel installs the framework catalog at import, and this
+// component ships in browser chunks (issue #490). `localizePath` is what i18n's `localizedPath` is.
+import { localizePath } from '@ultimat3/core';
 import type { Locale } from '@ultimat3/i18n';
 import type { JSX } from 'solid-js';
 import { cx } from '../cx';
@@ -10,12 +13,21 @@ import styles from './LocaleSwitcher.module.scss';
 import { Select, type SelectOption } from './Select';
 
 export interface LocaleSwitcherProps {
+  /** Every locale to offer, the DEFAULT first — `routedLocales()` from `@ultimat3/i18n`. */
   locales: readonly Locale[];
   /** Defaults to the context locale. */
   value?: Locale | undefined;
   onLocaleChange?: ((locale: Locale) => void) | undefined;
-  /** Render as links instead of a select, for a 0kb-JS `site/` route. */
+  /**
+   * Render as links instead of a select, for a 0kb-JS `site/` route. Defaults, when `path` is
+   * given, to that page in each locale — `localizedPath`: unprefixed for the default, `/en/…`
+   * otherwise — so a site's switcher needs no href of its own.
+   */
   hrefFor?: ((locale: Locale) => string) | undefined;
+  /** The page's own path, prefixed or not — `new URL(props.url).pathname`. Turns on links mode. */
+  path?: string | undefined;
+  /** The unprefixed locale. Defaults to `locales[0]`, which is where `routedLocales()` puts it. */
+  defaultLocale?: Locale | undefined;
   class?: string | undefined;
 }
 
@@ -31,13 +43,22 @@ export function LocaleSwitcher(props: LocaleSwitcherProps): JSX.Element {
   const options = (): SelectOption[] =>
     props.locales.map((tag) => ({ value: tag, label: localeLabel(tag) }));
 
-  if (props.hrefFor !== undefined) {
+  const hrefFor = (): ((locale: Locale) => string) | undefined => {
+    if (props.hrefFor !== undefined) return props.hrefFor;
+    const path = props.path;
+    if (path === undefined) return undefined;
+    const fallback = props.defaultLocale ?? props.locales[0] ?? current();
+    return (locale) => localizePath(path, locale, props.locales, fallback);
+  };
+
+  const linkFor = hrefFor();
+  if (linkFor !== undefined) {
     return (
       <nav class={cx(styles['links'], props.class)} aria-label={ui.t(UI_KEYS.language)}>
         {props.locales.map((tag) => (
           <a
             class={styles['link']}
-            href={props.hrefFor?.(tag)}
+            href={linkFor(tag)}
             hreflang={tag}
             lang={tag}
             aria-current={tag === current() ? 'true' : undefined}

package/src/components/ThemeToggle.tsx

@@ -26,7 +26,11 @@ export type ThemeChoice = Theme | 'system';
 
 export interface ThemeToggleProps {
   mode?: 'toggle' | 'select' | undefined;
-  /** Server-render value; the effect corrects it on the client before paint. */
+  /**
+   * The theme in force at server render — the toggle's glyph. Never the select's choice: nothing
+   * on the server knows whether the visitor chose it, so the select shows "system" until the
+   * effect reads storage.
+   */
   initial?: Theme | undefined;
   /** Injectable for tests and for non-DOM hosts. */
   env?: ThemeEnv | undefined;
@@ -36,7 +40,10 @@ export interface ThemeToggleProps {
 export function ThemeToggle(props: ThemeToggleProps): JSX.Element {
   const ui = useUi();
   const rt = solid();
-  const [choice, setChoice] = rt.createSignal<ThemeChoice>(props.initial ?? 'system');
+  // "system" until the effect reads storage, whatever `initial` says: `initial` is the RESOLVED
+  // theme the boot stamped on <html>, and seeding the choice with it made the select claim the
+  // visitor had picked it — so picking "system" looked like a no-op on every first paint.
+  const [choice, setChoice] = rt.createSignal<ThemeChoice>('system');
   const [resolved, setResolved] = rt.createSignal<Theme>(props.initial ?? 'light');
 
   const env = (): ThemeEnv => props.env ?? browserThemeEnv();

package/src/components/image-source.ts

@@ -180,3 +180,68 @@ function assertPixels(value: number): void {
     throw invalidValueError('Image', value, 'a positive whole number of CSS pixels');
   }
 }
+
+/** `16 / 9`, as CSS writes it — the reservation when the intrinsic size is not known. */
+export type ImageAspectRatio = `${number} / ${number}`;
+
+const RATIO = /^\s*(\d+(?:\.\d+)?)\s*\/\s*(\d+(?:\.\d+)?)\s*$/;
+
+/**
+ * The box an image reserves, which it ALWAYS reserves: both intrinsic dimensions, or an explicit
+ * `aspectRatio` — never neither, which is a layout shift waiting for the decode, and never both,
+ * which is two answers to one question. The returned ratio is what `--image-ratio` carries.
+ */
+export function reservedRatio(
+  width: number | undefined,
+  height: number | undefined,
+  aspectRatio: string | undefined,
+): string {
+  if (aspectRatio !== undefined) {
+    if (width !== undefined || height !== undefined) {
+      throw invalidValueError(
+        'Image',
+        { width, height, aspectRatio },
+        'width and height, or aspectRatio — not both, which would be two ratios for one box',
+      );
+    }
+    const match = RATIO.exec(aspectRatio);
+    if (match === null || Number(match[1]) <= 0 || Number(match[2]) <= 0) {
+      throw invalidValueError('Image', aspectRatio, 'an aspectRatio such as "16 / 9"');
+    }
+    return `${match[1]} / ${match[2]}`;
+  }
+  const box = boxFor(width, height);
+  if (box === undefined) {
+    throw invalidValueError(
+      'Image',
+      { width, height },
+      'width and height (the intrinsic size) or an aspectRatio — an image with neither reserves no box and shifts the layout when it decodes',
+    );
+  }
+  return ratioFor(box) as string;
+}
+
+/** Modern encodings, offered in this order ahead of the `<img>`'s own `src`. */
+export interface ImageSources {
+  readonly avif?: readonly ImageVariant[] | undefined;
+  readonly webp?: readonly ImageVariant[] | undefined;
+}
+
+export interface ImageSourceSet {
+  readonly type: 'image/avif' | 'image/webp';
+  readonly srcset: string;
+}
+
+/**
+ * One `<source>` per encoding handed in, AVIF first: the browser takes the FIRST type it can
+ * decode, so the smaller encoding has to be asked about before the larger one.
+ */
+export function sourceSetsFor(sources: ImageSources | undefined): readonly ImageSourceSet[] {
+  if (sources === undefined) return [];
+  const sets: ImageSourceSet[] = [];
+  const avif = srcsetFor(sources.avif);
+  if (avif !== undefined) sets.push({ type: 'image/avif', srcset: avif });
+  const webp = srcsetFor(sources.webp);
+  if (webp !== undefined) sets.push({ type: 'image/webp', srcset: webp });
+  return sets;
+}

package/src/index.ts

@@ -140,7 +140,7 @@ export type { IconProps } from './components/Icon';
 export { Icon } from './components/Icon';
 export type { IconButtonProps } from './components/IconButton';
 export { IconButton } from './components/IconButton';
-export type { ImageProps } from './components/Image';
+export type { ImageBaseProps, ImageDimensions, ImageProps } from './components/Image';
 export { Image } from './components/Image';
 export type { InfiniteScrollProps } from './components/InfiniteScroll';
 export { InfiniteScroll } from './components/InfiniteScroll';
@@ -148,8 +148,15 @@ export type { InputProps, InputType } from './components/Input';
 export { Input } from './components/Input';
 export type { IconElement, IconGlyph, IconTag } from './components/icon-glyph';
 export { ICON_TAGS, iconElements } from './components/icon-glyph';
-export type { ImageBox, ImageLoadingHints, ImageVariant } from './components/image-source';
-export { boxFor, srcsetFor } from './components/image-source';
+export type {
+  ImageAspectRatio,
+  ImageBox,
+  ImageLoadingHints,
+  ImageSourceSet,
+  ImageSources,
+  ImageVariant,
+} from './components/image-source';
+export { boxFor, reservedRatio, sourceSetsFor, srcsetFor } from './components/image-source';
 export type { LoadMoreInput, LoadMoreState } from './components/infinite-scroll-view';
 export type { KbdProps } from './components/Kbd';
 export { Kbd } from './components/Kbd';