@ultimat3/ui 19.4.0 → 20.1.0

package/src/components/DataTable.tsx

@@ -1,6 +1,10 @@
 // Data-driven table: sortable headers, cursor pagination, and the four states a
 // real list always has (loading, error, empty, data). The error state renders an
 // UltimateError with the same code/cause/fix strings the terminal prints.
+//
+// The four-way decision itself is NOT here — it is `asyncBranch`, shared with `AsyncRegion`, so a
+// table and a card list cannot disagree about what "loading with stale rows" looks like. Only the
+// PLACEHOLDER is local, because a table's is table-shaped: rows of cells, not lines of text.
 
 import { finiteCount } from '@ultimat3/core';
 import type { JSX } from 'solid-js';
@@ -8,6 +12,7 @@ import { ariaBool } from '../a11y';
 import { cx } from '../cx';
 import { UI_KEYS } from '../i18n-keys';
 import { useUi } from '../theme/context';
+import { type AsyncBranch, type AsyncState, asyncBranch, isBusyBranch } from './async-branch';
 import styles from './DataTable.module.scss';
 import { EmptyState } from './EmptyState';
 import { ErrorState } from './ErrorState';
@@ -60,8 +65,28 @@ export function DataTable<Row>(props: DataTableProps<Row>): JSX.Element {
       ? ui.t(UI_KEYS.sortDescending)
       : ui.t(UI_KEYS.sortAscending);
 
-  const body = (): JSX.Element => {
+  /**
+   * `rows` is one prop carrying two meanings, and this is where they are separated. An EMPTY array
+   * under `loading` is a first page in flight — there is nothing to keep, so the placeholder shows.
+   * A NON-EMPTY one is the previous page, which stays on screen dimmed rather than collapsing to a
+   * skeleton: re-sorting a table used to blank every row it was about to render again.
+   */
+  const state = (): AsyncState<readonly Row[]> => {
+    if (props.error !== undefined && props.error !== null) {
+      return { status: 'failed', error: props.error };
+    }
     if (props.loading === true) {
+      return props.rows.length === 0
+        ? { status: 'pending' }
+        : { status: 'refreshing', data: props.rows };
+    }
+    return { status: 'ready', data: props.rows };
+  };
+
+  const branch = (): AsyncBranch<readonly Row[]> => asyncBranch(state());
+
+  const body = (): JSX.Element => {
+    if (branch().kind === 'pending') {
       // `Array.from({ length: NaN })` is `[]`, so a busy tbody with no placeholders in it is the
       // collapsed layout this state exists to prevent, reported as healthy; `Infinity` asks for
       // 2^53 - 1 elements and dies with a bare, uncoded `RangeError` out of a render. `??` reaches
@@ -89,11 +114,14 @@ export function DataTable<Row>(props: DataTableProps<Row>): JSX.Element {
     ));
   };
 
-  if (props.error !== undefined && props.error !== null) {
-    return <ErrorState error={props.error} onRetry={props.onRetry} class={props.class} />;
+  const decided = branch();
+  if (decided.kind === 'failed') {
+    return <ErrorState error={decided.error} onRetry={props.onRetry} class={props.class} />;
   }
 
-  if (props.loading !== true && props.rows.length === 0) {
+  // Unreachable while pending, by the shape of `AsyncBranch` rather than by the order of two ifs:
+  // "No results" under a first page in flight is the bug that ordering used to be all that stopped.
+  if (decided.kind === 'empty') {
     return (
       <EmptyState
         title={props.emptyTitle}
@@ -142,7 +170,12 @@ export function DataTable<Row>(props: DataTableProps<Row>): JSX.Element {
             ))}
           </tr>
         </thead>
-        <tbody aria-busy={ariaBool(props.loading === true)}>{body()}</tbody>
+        <tbody
+          class={decided.kind === 'ready' && decided.busy ? styles['stale'] : undefined}
+          aria-busy={ariaBool(isBusyBranch(decided))}
+        >
+          {body()}
+        </tbody>
       </Table>
       {props.nextCursor === undefined && props.prevCursor === undefined ? null : (
         <Pagination

package/src/components/Dropzone.module.scss

@@ -59,8 +59,19 @@
   border-radius: t.radius(pill);
   background: t.role('bg-soft');
   overflow: hidden;
+  // Bounds the layout pass the `.bar` transition below costs to this subtree. See the note there.
+  contain: layout;
 }
 
+// The upload bar. `inline-size` is a LAYOUT-triggering property and a transition on one is not
+// compositor-only, which is a real cost and a deliberate trade — the compositor-safe form is
+// `transform: scaleX()`, and `transform-origin` has no logical keyword, so the bar would grow from
+// the physical left edge and fill away from the reading edge under `dir="rtl"`. A progress bar that
+// runs backwards in Arabic is a worse defect than a layout pass. `contain: layout` on the track is
+// what bounds the cost instead: the invalidation stops at the track, so nothing outside it is
+// re-laid-out per frame. `layout` alone and NOT `layout size` — `size` makes a box ignore its
+// contents in both axes, and FileInput's track takes its inline size from its containing block.
+//
 // Inline-start, not `left`: the bar has to fill from the reading edge under `dir="rtl"` too.
 .bar {
   display: block;

package/src/components/FileInput.module.scss

@@ -63,8 +63,19 @@
   border-radius: t.radius(pill);
   background: t.role('bg-soft');
   overflow: hidden;
+  // Bounds the layout pass the `.bar` transition below costs to this subtree. See the note there.
+  contain: layout;
 }
 
+// The upload bar. `inline-size` is a LAYOUT-triggering property and a transition on one is not
+// compositor-only, which is a real cost and a deliberate trade — the compositor-safe form is
+// `transform: scaleX()`, and `transform-origin` has no logical keyword, so the bar would grow from
+// the physical left edge and fill away from the reading edge under `dir="rtl"`. A progress bar that
+// runs backwards in Arabic is a worse defect than a layout pass. `contain: layout` on the track is
+// what bounds the cost instead: the invalidation stops at the track, so nothing outside it is
+// re-laid-out per frame. `layout` alone and NOT `layout size` — `size` makes a box ignore its
+// contents in both axes, and FileInput's track takes its inline size from its containing block.
+//
 // Inline-start, not `left`: the bar has to fill from the reading edge under `dir="rtl"` too.
 .bar {
   display: block;

package/src/components/Form.tsx

@@ -1,10 +1,19 @@
 // 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.
+//
+// Focus goes to the first INVALID CONTROL when there is one, and to the summary only when there is
+// not. GOV.UK's tested pattern is a summary whose entries LINK to their fields; that shape is not
+// available here, because `Field` mints its control ids internally (`Field.tsx`) and inverting that
+// ownership is the drift `Field` exists to prevent — a summary cannot write an `href` to an id it
+// cannot see. Focusing the control directly reaches the same place in one step. The summary still
+// announces, and is still where a form-level rejection (a policy refusal, an unmatched issue) puts
+// the reader, because that one names no control to send them to.
 
 import type { JSX } from 'solid-js';
-import { useId } from '../a11y';
+import { ariaBool, useId } from '../a11y';
 import { cx } from '../cx';
+import { fieldSelector } from '../form/field-path';
 import { solid } from '../theme/solid-adapter';
 import { Alert } from './Alert';
 import styles from './Form.module.scss';
@@ -17,6 +26,18 @@ export interface FormProps {
   /** Already-translated heading for the error summary region. */
   errorTitle?: string | undefined;
   actions?: JSX.Element | undefined;
+  /**
+   * The `name` of the control a failed submit should send the reader to — `form.firstInvalidField()`.
+   * Focused in preference to the summary: the summary describes the problem, the control is where
+   * it is fixed, and leaving the user on the summary strands them one Tab away from nothing.
+   */
+  invalidField?: string | undefined;
+  /**
+   * A submit is in flight — `form.pending()`. Suppresses the submit outright, so a double submit is
+   * refused HERE and not only on whatever control happened to be clicked: Enter in a text field
+   * submits a form with no button involved at all.
+   */
+  busy?: boolean | undefined;
   gap?: SpaceStep | undefined;
   method?: 'get' | 'post' | undefined;
   action?: string | undefined;
@@ -30,16 +51,54 @@ export function Form(props: FormProps): JSX.Element {
   const rt = solid();
   const summaryId = useId('form-error');
   let summary: HTMLDivElement | undefined;
+  let element: HTMLFormElement | undefined;
+
+  /**
+   * The control the rejection named, inside THIS form. `fieldSelector` answers `null` for a name
+   * the path grammar does not accept, which is the allowlist that keeps a caller's string out of a
+   * selector — no accepted name can carry a quote or close the attribute.
+   */
+  const invalidControl = (): HTMLElement | null => {
+    const name = props.invalidField;
+    if (name === undefined || element === undefined) return null;
+    const selector = fieldSelector(name);
+    return selector === null ? null : element.querySelector<HTMLElement>(selector);
+  };
 
   // `tabindex="-1"` alone was a focus target nothing ever aimed at: `summaryId` is internal, so no
   // caller could move focus here, and the component never did either. A failed submit that leaves
   // focus on the button leaves a keyboard user to hunt for what went wrong.
   rt.createEffect(() => {
+    const control = invalidControl();
+    if (control !== null) {
+      control.focus();
+      return;
+    }
     if (props.error !== undefined) summary?.focus();
   });
 
+  /**
+   * A form already submitting cannot submit again. `aria-disabled` on the button is advisory and
+   * Enter in a text field never touches the button at all, so this is the refusal that holds — and
+   * it is a guard, not the guarantee: the binding joins an in-flight submit, and the server is the
+   * only place a duplicate write is finally refused.
+   */
+  const onSubmit = (event: SubmitEvent): void => {
+    if (props.busy === true) {
+      event.preventDefault();
+      return;
+    }
+    const handler = props.onSubmit;
+    if (handler === undefined) return;
+    if (typeof handler === 'function') handler(event as Parameters<typeof handler>[0]);
+    else handler[0](handler[1], event as Parameters<(typeof handler)[0]>[1]);
+  };
+
   return (
     <form
+      ref={(el: HTMLFormElement) => {
+        element = el;
+      }}
       class={cx(styles['form'], props.class)}
       style={{ '--form-gap': `var(--space-${props.gap ?? 5})` }}
       method={props.method ?? 'post'}
@@ -47,7 +106,8 @@ export function Form(props: FormProps): JSX.Element {
       novalidate={props.novalidate === true}
       aria-label={props['aria-label']}
       aria-describedby={props.error === undefined ? undefined : summaryId}
-      onSubmit={props.onSubmit}
+      aria-busy={ariaBool(props.busy)}
+      onSubmit={onSubmit}
     >
       {props.error === undefined ? null : (
         <div

package/src/components/Image.module.scss

@@ -7,6 +7,11 @@
   max-inline-size: 100%;
   block-size: auto;
 
+  // The second half of the reservation, and the half that survives styling: the width/height
+  // attributes reserve the box only until a stylesheet sets a size of its own. `auto` when the
+  // dimensions are unknown, which is what a replaced element does without this rule at all.
+  aspect-ratio: var(--image-ratio, auto);
+
   // Painted only when the image fails to load: the browser renders the alt text
   // inside this box, and it inherits the img's own colour and font-size.
   color: t.role('fg-muted');

package/src/components/Image.tsx

@@ -15,6 +15,7 @@ import {
   type ImageLoadingHints,
   type ImageVariant,
   loadingHints,
+  ratioFor,
   srcsetFor,
 } from './image-source';
 
@@ -45,6 +46,9 @@ export function Image(props: ImageProps): JSX.Element {
   return (
     <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()) }}
       src={src()}
       alt={props.alt}
       srcset={srcsetFor(props.variants)}

package/src/components/Toast.module.scss

@@ -1,12 +1,5 @@
 @use '../tokens' as t;
 
-@keyframes ultimate-toast-in {
-  from {
-    opacity: 0;
-    translate: 0 12px;
-  }
-}
-
 .region {
   position: fixed;
   z-index: t.z(toast);
@@ -47,8 +40,24 @@
   padding: t.space(4);
   border-inline-start: 3px solid var(--toast-accent);
   color: t.role('fg');
-  animation: ultimate-toast-in t.duration(base) t.easing(out);
   pointer-events: auto;
+
+  // A TRANSITION, not a keyframe animation, and `@starting-style` is what makes an entry
+  // transition possible with no JS at all. The difference is interruption: a transition retargets
+  // from wherever the property currently is when the state changes mid-flight, and a keyframe
+  // animation restarts from its own `from`. A toast stack is the surface where that shows — a
+  // second message arriving 200ms into the first one's entry restarted the whole stack's motion.
+  // `opacity` and `translate` are the two the compositor can run without laying the page out again.
+  opacity: 1;
+  translate: 0 0;
+  transition:
+    opacity t.duration(base) t.easing(out),
+    translate t.duration(base) t.easing(out);
+
+  @starting-style {
+    opacity: 0;
+    translate: 0 12px;
+  }
 }
 
 .content {

package/src/components/Toast.tsx

@@ -9,10 +9,14 @@ import type { Politeness } from '../a11y';
 import { cx } from '../cx';
 import { UI_KEYS } from '../i18n-keys';
 import { useUi } from '../theme/context';
+import type { ToastHold } from '../toast/toast-state';
 import { IconButton } from './IconButton';
 import styles from './Toast.module.scss';
 import type { Tone } from './variants';
 
+/** Where the stack sits. Logical corners, so it follows the writing direction. */
+export type ToastPlacement = 'block-end-inline-end' | 'block-start-inline-end' | 'block-end-center';
+
 export interface ToastRegionProps {
   children: JSX.Element;
   /** Already-translated landmark name, e.g. "Notifications". */
@@ -24,13 +28,28 @@ export interface ToastRegionProps {
    * list cannot work, because the live semantics belong to the list, not to the message.
    */
   politeness?: Politeness | undefined;
-  placement?: 'block-end-inline-end' | 'block-start-inline-end' | 'block-end-center' | undefined;
+  placement?: ToastPlacement | undefined;
+  /**
+   * Stop the dwell while the reader is engaged with the stack, and start it again when they leave.
+   * WCAG 2.2 2.2.1 wants a timing the user can extend, and a message that expires under the
+   * pointer reaching for its undo is the failure that rule is about.
+   *
+   * Two reasons, reported separately: a pointer leaving a toast a keyboard user is still inside
+   * must not restart the countdown, which one boolean cannot express.
+   */
+  onHold?: ((reason: ToastHold) => void) | undefined;
+  onRelease?: ((reason: ToastHold) => void) | undefined;
   class?: string | undefined;
 }
 
 export function ToastRegion(props: ToastRegionProps): JSX.Element {
   // `aria-atomic="false"` on the list: only the toast that was just added is read, never the whole
   // list again on every arrival.
+  //
+  // The four handlers sit on the <ol> and all four BUBBLE. `mouseenter`/`mouseleave` do not, and
+  // this list is `pointer-events: none` so it is not a hit target of its own — only the toasts
+  // inside it are. `mouseover`/`mouseout` reach here from them; `mouseenter` would fire on a box
+  // the pointer can never be over.
   return (
     <section
       class={cx(
@@ -40,7 +59,20 @@ export function ToastRegion(props: ToastRegionProps): JSX.Element {
       )}
       aria-label={props.label}
     >
-      <ol class={styles['list']} aria-live={props.politeness ?? 'polite'} aria-atomic="false">
+      {/* biome-ignore lint/a11y/useKeyWithMouseEvents: the rule wants `onFocus` beside
+          `onMouseOver`, and `onFocus` is the WRONG half of the pair here — `focus` does not
+          bubble, so a handler on this list would never hear a toast's dismiss button being
+          reached, which is the exact case the pause exists for. `onFocusIn`/`onFocusOut` are the
+          bubbling forms and are both present, so the keyboard path this rule protects is covered. */}
+      <ol
+        class={styles['list']}
+        aria-live={props.politeness ?? 'polite'}
+        aria-atomic="false"
+        onMouseOver={() => props.onHold?.('pointer')}
+        onMouseOut={() => props.onRelease?.('pointer')}
+        onFocusIn={() => props.onHold?.('focus')}
+        onFocusOut={() => props.onRelease?.('focus')}
+      >
         {props.children}
       </ol>
     </section>

package/src/components/Toaster.tsx

@@ -0,0 +1,77 @@
+// The one way to render a toast queue: the store's VISIBLE slice, inside the region that owns the
+// live semantics. The half that was missing — `Toast` and `ToastRegion` shipped with no store, so
+// every app wrote its own queue, its own dwell and its own pause rules.
+//
+// Toasts over the cap are not drawn and not counted on screen: they are still queued, and their
+// dwell has not started. A "+3 more" badge would be a message about messages, in a corner the
+// reader is already being asked to look away to.
+
+import type { JSX } from 'solid-js';
+import type { Politeness } from '../a11y';
+import { type ToastItem, visibleToasts } from '../toast/toast-state';
+import type { ToastStore } from '../toast/toast-store';
+import { useToasts } from '../toast/use-toasts';
+import { Button } from './Button';
+import { Toast, type ToastPlacement, ToastRegion } from './Toast';
+
+export interface ToasterProps {
+  /** The queue. One per app — `createToastStore()` in the island that mounts this. */
+  store: ToastStore;
+  /** Already-translated landmark name, e.g. "Notifications". */
+  label: string;
+  politeness?: Politeness | undefined;
+  placement?: ToastPlacement | undefined;
+  /** Already-translated; falls back to the `ui.dismiss` catalog key. */
+  dismissLabel?: string | undefined;
+  class?: string | undefined;
+}
+
+export function Toaster(props: ToasterProps): JSX.Element {
+  const queue = useToasts(props.store);
+
+  /**
+   * One undo-shaped control, or nothing. A toast never carries the only affordance for an action:
+   * it disappears on a timer, and a keyboard user who was typing when it arrived never reached it.
+   * Taking the undo also dismisses — the offer has been answered.
+   */
+  const actionSlot = (item: ToastItem): JSX.Element => {
+    const action = item.action;
+    if (action === undefined) return null;
+    return (
+      <Button
+        size="sm"
+        variant="ghost"
+        tone={item.tone}
+        onClick={() => {
+          action.onAction();
+          props.store.dismiss(item.id);
+        }}
+      >
+        {action.label}
+      </Button>
+    );
+  };
+
+  return (
+    <ToastRegion
+      label={props.label}
+      politeness={props.politeness}
+      placement={props.placement}
+      class={props.class}
+      onHold={(reason) => props.store.hold(reason)}
+      onRelease={(reason) => props.store.release(reason)}
+    >
+      {visibleToasts(queue()).map((item) => (
+        <Toast
+          title={item.title}
+          tone={item.tone}
+          dismissLabel={props.dismissLabel}
+          action={actionSlot(item)}
+          onDismiss={() => props.store.dismiss(item.id)}
+        >
+          {item.message}
+        </Toast>
+      ))}
+    </ToastRegion>
+  );
+}

package/src/components/async-branch.ts

@@ -0,0 +1,113 @@
+// The ONE four-way decision every async region makes — pending, failed, empty, ready — written as
+// a pure rule so "what does this look like while it loads" stops being a judgement an agent makes
+// once per screen. Two properties are structural here rather than documented: `empty` is
+// unreachable until a result has arrived, and a refetch keeps the previous data on screen.
+
+/**
+ * What a caller hands an async region. A STATE, never a query: `@ultimat3/ui` is tier 4 and may
+ * not import `query`, `action` or `realtime`, so a live-query accessor, a `createResource` and a
+ * plain signal all arrive here as the same four shapes.
+ *
+ * `refreshing` is the one that makes search feel fast — it CARRIES the previous data, so a refetch
+ * re-renders what is already on screen instead of tearing it down to a skeleton.
+ */
+export type AsyncState<T> =
+  | { readonly status: 'pending' }
+  | { readonly status: 'refreshing'; readonly data: T }
+  | { readonly status: 'ready'; readonly data: T }
+  | { readonly status: 'failed'; readonly error: unknown };
+
+/**
+ * The branch a region renders. `empty` and `ready` carry `busy`; `pending` and `failed` do not,
+ * because `pending` IS busy and a failure is not in flight.
+ *
+ * There is no `{ kind: 'empty' }` reachable from `{ status: 'pending' }` — that is the whole
+ * point of this module. "No results" rendered for one frame before the first page arrives is the
+ * most common agent-authored UX bug in a list screen, and the union above makes it unconstructible
+ * rather than merely discouraged: `pending` holds no data, so nothing can be found empty in it.
+ */
+export type AsyncBranch<T> =
+  | { readonly kind: 'pending' }
+  | { readonly kind: 'failed'; readonly error: unknown }
+  | { readonly kind: 'empty'; readonly busy: boolean }
+  | { readonly kind: 'ready'; readonly data: T; readonly busy: boolean };
+
+const PENDING: AsyncBranch<never> = Object.freeze({ kind: 'pending' });
+
+/**
+ * The default emptiness test: a list with no items, a map or set with no entries, or nothing at
+ * all. Anything else is data — a `{ total: 0, items: [] }` envelope is a shape only its author
+ * knows, so it passes its own `isEmpty` rather than being guessed at here.
+ */
+export function isEmptyData(data: unknown): boolean {
+  if (data === null || data === undefined) return true;
+  if (Array.isArray(data)) return data.length === 0;
+  if (data instanceof Map || data instanceof Set) return data.size === 0;
+  if (typeof data === 'string') return data === '';
+  return false;
+}
+
+/**
+ * State → branch. The only place the four-way decision is made, so `DataTable`, `AsyncRegion` and
+ * an app's own region cannot disagree about what "loading with stale rows" looks like.
+ */
+export function asyncBranch<T>(
+  state: AsyncState<T>,
+  isEmpty: (data: T) => boolean = isEmptyData,
+): AsyncBranch<T> {
+  // Failure first: a query that failed while holding stale data must report the failure, never
+  // render the stale rows as if they were the answer to the request that just errored.
+  if (state.status === 'failed') return { kind: 'failed', error: state.error };
+  if (state.status === 'pending') return PENDING;
+  // `ready | refreshing`, and this annotation is the build error: a fifth status added to
+  // `AsyncState` fails to assign here instead of falling through to a region that renders nothing.
+  const settled: { readonly status: 'ready' | 'refreshing'; readonly data: T } = state;
+  const busy = settled.status === 'refreshing';
+  return isEmpty(settled.data)
+    ? { kind: 'empty', busy }
+    : { kind: 'ready', data: settled.data, busy };
+}
+
+/** Whether the region is waiting on the network — `aria-busy`, in one derivation. */
+export function isBusyBranch<T>(branch: AsyncBranch<T>): boolean {
+  return branch.kind === 'pending' || (branch.kind !== 'failed' && branch.busy);
+}
+
+/**
+ * The flag-shaped source a `createResource` (and most hand-rolled fetches) already are.
+ * `data: undefined` means NOTHING HAS ARRIVED; an empty array is data, and it is what makes the
+ * empty branch reachable. Solid's `latest` is exactly this: it holds the previous value across a
+ * refetch, which is why `loading` beside a defined `data` is `refreshing` and not `pending`.
+ */
+export interface AsyncFlags<T> {
+  readonly loading?: boolean | undefined;
+  readonly error?: unknown;
+  readonly data?: T | undefined;
+}
+
+export function asyncStateOf<T>(flags: AsyncFlags<T>): AsyncState<T> {
+  if (flags.error !== undefined && flags.error !== null)
+    return { status: 'failed', error: flags.error };
+  if (flags.data === undefined) return { status: 'pending' };
+  return flags.loading === true
+    ? { status: 'refreshing', data: flags.data }
+    : { status: 'ready', data: flags.data };
+}
+
+/** How much box the pending branch holds, so the skeleton and the loaded content share one size. */
+export interface ReserveBox {
+  /** Placeholder lines. Match what the loaded content renders, or the load is a layout shift. */
+  readonly lines: number;
+  /** CSS length of ONE line. Defaults to `1em`, the same default `Skeleton` uses. */
+  readonly height?: string | undefined;
+}
+
+/**
+ * The reserved block size, as one `calc()`. Emitted as a custom property on the region in EVERY
+ * branch — that is the mechanism behind `Skeleton`'s own rule (a placeholder that changes size on
+ * load is just a slower layout shift): one value feeds the placeholder and the box the real
+ * content lands in, so the two cannot be written to disagree.
+ */
+export function reserveBlockSize(reserve: ReserveBox): string {
+  return `calc(${String(reserve.lines)} * ${reserve.height ?? '1em'})`;
+}

package/src/components/image-source.ts

@@ -103,6 +103,21 @@ export function boxFor(
   return { width, height };
 }
 
+/**
+ * The `aspect-ratio` for a known box, as CSS writes it. `undefined` when the dimensions are
+ * unknown — there is no ratio to state, and `aspect-ratio: auto` is what a replaced element does
+ * anyway.
+ *
+ * Not a duplicate of the `width`/`height` attributes, which is what it looks like: those reserve
+ * the box only while the element's own layout is UNSTYLED, and a stylesheet that sets
+ * `inline-size: 100%` (this one sets `max-inline-size`, and an app's grid routinely sets the rest)
+ * drops the reserved height on the floor. `aspect-ratio` survives that, which is the class of
+ * layout shift left over after the attributes have done their part.
+ */
+export function ratioFor(box: ImageBox | undefined): string | undefined {
+  return box === undefined ? undefined : `${String(box.width)} / ${String(box.height)}`;
+}
+
 /**
  * A `src` with real content once whitespace is trimmed. Shared by the primary `src` prop and
  * every variant `src`: an empty or blank one emits a broken `<img>` or a srcset entry the

package/src/errors.ts

@@ -9,6 +9,7 @@ export const UI_ERROR_CODES = {
   runtimeMissing: 'X_UI_RUNTIME_MISSING',
   invalidValue: 'X_UI_INVALID_VALUE',
   formPathInvalid: 'X_UI_FORM_PATH_INVALID',
+  contrastInsufficient: 'X_UI_CONTRAST_INSUFFICIENT',
 } as const;
 
 export type UiErrorCode = (typeof UI_ERROR_CODES)[keyof typeof UI_ERROR_CODES];
@@ -22,6 +23,7 @@ registerErrorCodes({
   X_UI_RUNTIME_MISSING: { title: 'a host capability @ultimat3/ui needs is absent' },
   X_UI_INVALID_VALUE: { title: 'a formatting component received an unrenderable value' },
   X_UI_FORM_PATH_INVALID: { title: 'a form control name is not a usable field path' },
+  X_UI_CONTRAST_INSUFFICIENT: { title: 'a brand palette pairing does not meet WCAG 2.2 AA' },
 });
 
 export class UiError extends UltimateError {
@@ -167,6 +169,30 @@ export function invalidFieldPathError(subject: string, name: string): UiError {
   });
 }
 
+/**
+ * A `defineTheme()` palette that renders text nobody can read. Refused rather than warned about:
+ * a warning in a build log is the "enforced, not documented" failure this repo names as axiom 3,
+ * and an inaccessible theme is a legal exposure (EN 301 549, ADA Title II, the EAA) that the app
+ * author will not discover until an audit. WCAG 2.2 AA, never APCA — APCA is not a standard.
+ *
+ * The cause names the measured ratio and the required one, so the fix is arithmetic rather than
+ * guesswork; the fix names the role to move, because a pairing is repaired from one side.
+ */
+export function insufficientContrastError(
+  theme: string,
+  what: string,
+  fg: string,
+  bg: string,
+  ratio: number,
+  minimum: number,
+): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.contrastInsufficient,
+    cause: `defineTheme() ${theme} palette renders ${what}: "${fg}" on "${bg}" measures ${ratio.toFixed(2)}:1, and WCAG 2.2 AA requires ${String(minimum)}:1`,
+    fix: `darken or lighten the "${fg}" channels in defineTheme({ colors: { ${theme}: { '${fg}': '<R G B>' } } }) until contrastRatio() answers ${String(minimum)} or more against "${bg}" — @ultimat3/ui exports contrastRatio and roleContrast to measure a candidate before you ship it`,
+  });
+}
+
 /**
  * Two controls whose names describe different shapes for one path (`user` beside `user.name`).
  * Refused rather than resolved: either answer silently drops one control's value, and the value

package/src/fake-dom.ts

@@ -119,6 +119,11 @@ export class FakeElement extends Listeners {
     return this.children.flatMap((child) => [child, ...child.descendants()]);
   }
 
+  /** First match or `null`, exactly as the real one answers — `[0]` on an empty list is not it. */
+  querySelector(selector: string): FakeElement | null {
+    return this.querySelectorAll(selector)[0] ?? null;
+  }
+
   querySelectorAll(selector: string): FakeElement[] {
     const groups = selector.split(',').map((one) => one.trim());
     return this.descendants().filter((el) => groups.some((one) => compoundMatches(el, one)));

package/src/form/field-path.ts

@@ -89,3 +89,15 @@ export function parseFieldPath(name: string): readonly FieldPathSegment[] | null
   // `expectKey` still set means the name ended on a `.` or was empty — both are half a path.
   return expectKey ? null : segments;
 }
+
+/**
+ * The attribute selector that finds a control by its field path, or `null` for a name that is not
+ * one. The grammar above is the ALLOWLIST and the only thing between a caller's string and a
+ * selector: `parseFieldPath` accepts `[A-Za-z_$][A-Za-z0-9_$]*`, `.` and `[0]` and nothing else, so
+ * no name it returns a path for can carry a quote, a bracket it did not open, or a second selector.
+ * Refused rather than escaped, for the same reason the parser is total — a name no issue can name
+ * is a field whose errors land nowhere, and building a selector for it would hide that.
+ */
+export function fieldSelector(name: string): string | null {
+  return parseFieldPath(name) === null ? null : `[name="${name}"]`;
+}