@eifi1/ui-kit 0.33.1 → 0.35.0

package/src/shell/topbar-action-menu.tsx

@@ -2,7 +2,7 @@ import { useId, useLayoutEffect, useRef } from "react";
 import type { KeyboardEvent as ReactKeyboardEvent, ReactNode } from "react";
 import { Link } from "react-router";
 import { cn } from "../lib/cn";
-import { HoverMenu } from "../components/hover-menu";
+import { HoverMenu, type HoverMenuProps } from "../components/hover-menu";
 import { MenuItem } from "../components/menu-item";
 import type { MenuItemTone } from "../components/menu-item";
 import { StatusDot } from "../components/status-dot";
@@ -68,7 +68,7 @@ export type TopBarMenuEntry =
        *
        * The menu-wide `heading` prop is the panel's title, drawn once above everything;
        * with group headings it is usually redundant (two stacked caps lines read as one),
-       * and the trigger's `ariaLabel` already names the menu.
+       * and the trigger's `aria-label` already names the menu.
        */
       kind: "heading";
       key: string;
@@ -202,7 +202,7 @@ export function TopBarActionMenu({
   trigger,
   triggerClassName,
   href,
-  ariaLabel,
+  "aria-label": ariaLabel,
   heading,
   header,
   entries,
@@ -226,11 +226,11 @@ export function TopBarActionMenu({
    * INSIDE the kit's button, which keeps the wiring: `aria-haspopup`, `aria-expanded`,
    * the toggle, the keyboard. `open` is there for a chevron that turns.
    *
-   * The button is named by `ariaLabel` followed by any readable text in the face — a
+   * The button is named by `aria-label` followed by any readable text in the face — a
    * `UserAvatar` `badge` label reaches a screen reader that way ("Account menu 3
    * unread"), where an `aria-label` on the button would have hidden it. A
    * `UserAvatar`'s initials are `aria-hidden`, so the person's name is only in the
-   * name if `ariaLabel` carries it ("Marcel Eifert, account menu").
+   * name if `aria-label` carries it ("Marcel Eifert, account menu").
    */
   trigger?: (state: { open: boolean }) => ReactNode;
   /** Extra classes for the trigger button — `rounded-full` round an avatar. */
@@ -243,12 +243,13 @@ export function TopBarActionMenu({
    * row, so the rows stay reachable by keyboard. A tap on a touch screen follows the
    * link — so use it where the destination offers everything the menu does. Rendered as
    * an `<a>` (the router's `Link`) with `aria-haspopup="menu"` and `aria-expanded`,
-   * named by `ariaLabel`: a link inside the kit's button would be interactive content
+   * named by `aria-label`: a link inside the kit's button would be interactive content
    * inside interactive content.
    */
   href?: string;
-  /** Names the trigger and the menu. */
-  ariaLabel: string;
+  /** Names the trigger and the menu. Required: the trigger is an icon (refactor audit
+   *  2026-10, API-1 — the `ariaLabel` spelling went in 0.35). */
+  "aria-label": string;
   heading?: string;
   /** A non-interactive identity block above the rows. */
   header?: TopBarMenuHeader;
@@ -267,8 +268,9 @@ export function TopBarActionMenu({
   footer?: ReactNode | ((close: () => void) => ReactNode);
   /** Wraps the footer in a `<nav>` with this name ("Legal"). Without it, a plain block. */
   footerLabel?: string;
-  /** Which edge of the trigger the panel lines up with (see `HoverMenu`). Default `end`. */
-  align?: "start" | "end" | "left" | "right";
+  /** Which edge of the trigger the panel lines up with, `start` or `end` in the reading
+   *  direction (see `HoverMenu`, whose type this is). Default `end`. */
+  align?: HoverMenuProps["align"];
   panelClassName?: string;
 }) {
   // Names the groups' headings for `aria-labelledby`. Positional rather than from the
@@ -277,7 +279,7 @@ export function TopBarActionMenu({
   const uid = useId();
   return (
     <HoverMenu
-      ariaLabel={ariaLabel}
+      aria-label={ariaLabel}
       align={align}
       trigger={({ open, toggle, close }) => {
         // One element for both kinds: the router's link when `href` is set, else the
@@ -326,7 +328,7 @@ export function TopBarActionMenu({
         const footerBody = typeof footer === "function" ? footer(close) : footer;
         const headerExtra = typeof header?.extra === "function" ? header.extra(close) : header?.extra;
         const footerClass =
-          "flex flex-wrap gap-x-3 gap-y-1 text-xs text-[var(--text-muted)] [&_a:hover]:text-[var(--text-primary)] [&_a]:rounded-sm [&_a:focus-visible]:outline-none [&_a:focus-visible]:ring-[length:var(--focus-ring-width)] [&_a:focus-visible]:ring-[var(--brand)]";
+          "flex flex-wrap gap-x-3 gap-y-1 text-xs text-muted [&_a:hover]:text-primary [&_a]:rounded-sm [&_a:focus-visible]:outline-none [&_a:focus-visible]:ring-focus [&_a:focus-visible]:ring-brand";
         /** One action or link row — loose, or inside a heading's group. */
         const row = (entry: RowEntry) => (
           <li key={entry.key}>
@@ -365,16 +367,16 @@ export function TopBarActionMenu({
           // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- a Tab bubbling up from a row or footer link, see keepTabInsidePanel
           <ul className={cn("py-1", panelClassName)} onKeyDown={keepTabInsidePanel}>
             {header && (
-              <MenuSection className="mb-1 border-b border-[var(--border)] px-3 py-2">
-                <div className="truncate text-sm font-medium text-[var(--text-primary)]">{header.title}</div>
+              <MenuSection className="mb-1 border-b border-subtle px-3 py-2">
+                <div className="truncate text-sm font-medium text-primary">{header.title}</div>
                 {header.subtitle != null && (
-                  <div className="truncate text-xs text-[var(--text-muted)]">{header.subtitle}</div>
+                  <div className="truncate text-xs text-muted">{header.subtitle}</div>
                 )}
                 {headerExtra != null && headerExtra !== false && <div className="mt-1">{headerExtra}</div>}
               </MenuSection>
             )}
             {heading && (
-              <li className="px-3 py-1 text-micro font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
+              <li className="px-3 py-1 text-micro font-semibold uppercase tracking-wide text-placeholder">
                 {heading}
               </li>
             )}
@@ -382,7 +384,7 @@ export function TopBarActionMenu({
               if (block.kind === "loose") {
                 const entry = block.entry;
                 if (entry.kind === "divider") {
-                  return <li key={entry.key} className="my-1 border-t border-[var(--border)]" />;
+                  return <li key={entry.key} className="my-1 border-t border-subtle" />;
                 }
                 return row(entry);
               }
@@ -397,7 +399,7 @@ export function TopBarActionMenu({
                     id={headingId}
                     role="presentation"
                     className={cn(
-                      "px-3 pb-0.5 text-caption font-semibold uppercase tracking-wide text-[var(--text-muted)] [overflow-wrap:anywhere]",
+                      "px-3 pb-0.5 text-caption font-semibold uppercase tracking-wide text-muted [overflow-wrap:anywhere]",
                       tight ? "pt-1" : "pt-2.5",
                     )}
                   >
@@ -411,7 +413,7 @@ export function TopBarActionMenu({
             })}
             {children?.(close)}
             {footerBody != null && footerBody !== false && (
-              <MenuSection className="mt-1 border-t border-[var(--border)] px-3 py-2">
+              <MenuSection className="mt-1 border-t border-subtle px-3 py-2">
                 {footerLabel ? (
                   <nav aria-label={footerLabel} className={footerClass}>
                     {footerBody}

package/src/shell/topbar-controls.tsx

@@ -9,17 +9,17 @@ import { DEFAULT_TOP_BAR_LABELS, useKitLabels } from "../i18n/kit-labels";
 /** Shared square icon-button styling for top-bar triggers, so app-owned controls
  *  (account/feedback menus) line up with the shared ones. */
 export const TOPBAR_TRIGGER_CLASS =
-  "size-9 rounded-md flex items-center justify-center text-[var(--text-secondary)] hover:text-[var(--text-primary)] hover:bg-[var(--bg-hover)]";
+  "size-9 rounded-md flex items-center justify-center text-secondary hover:text-primary hover:bg-hover";
 
 /** Shared row styling for the top-bar hover-menu items. `text-start`, so a label that
  *  wraps aligns to the reading edge in RTL too. */
 export const TOPBAR_MENU_ITEM_CLASS =
-  "flex w-full items-center justify-between gap-3 px-3 py-2 text-sm text-start text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]";
+  "flex w-full items-center justify-between gap-3 px-3 py-2 text-sm text-start text-secondary hover:bg-hover";
 
 /** The small uppercase heading row the top-bar menus share (`heading`). */
 function MenuHeading({ children }: { children: string }) {
   return (
-    <li className="px-3 py-1 text-micro font-semibold uppercase tracking-wide text-[var(--text-placeholder)]">
+    <li className="px-3 py-1 text-micro font-semibold uppercase tracking-wide text-placeholder">
       {children}
     </li>
   );
@@ -29,18 +29,18 @@ function MenuHeading({ children }: { children: string }) {
 export function ThemeToggle({
   mode,
   onToggle,
-  ariaLabel,
+  "aria-label": ariaLabel,
   title,
   className,
 }: {
   mode: ThemeMode;
   onToggle: () => void;
   /** Default: `topBar.theme` from the {@link UiKitProvider}, else English. */
-  ariaLabel?: string;
+  "aria-label"?: string;
   title?: string;
   className?: string;
 }) {
-  // This had no default at all, so a toggle rendered without `ariaLabel` was an
+  // This had no default at all, so a toggle rendered without `aria-label` was an
   // icon button with no name — a reader heard "button" and nothing else.
   const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { theme: ariaLabel });
   const Icon = mode === "dark" ? Moon : Sun;
@@ -65,7 +65,7 @@ export function PaletteMenu({
   activeId,
   mode,
   onSelect,
-  ariaLabel,
+  "aria-label": ariaLabel,
   heading,
 }: {
   palettes: PalettePreset[];
@@ -73,7 +73,7 @@ export function PaletteMenu({
   mode: ThemeMode;
   onSelect: (id: string) => void;
   /** Default: `topBar.palette` from the {@link UiKitProvider}, else English. */
-  ariaLabel?: string;
+  "aria-label"?: string;
   /** Optional small heading row above the list. */
   heading?: string;
 }) {
@@ -81,7 +81,7 @@ export function PaletteMenu({
   const activeName = palettes.find((p) => p.id === activeId)?.name ?? activeId;
   return (
     <HoverMenu
-      ariaLabel={labels.palette}
+      aria-label={labels.palette}
       trigger={({ toggle }) => (
         <Tooltip label={activeName} portal>
           <button
@@ -131,13 +131,13 @@ export function PaletteMenu({
                     </span>
                     <span className="flex min-w-0 flex-col text-start">
                       <span className="truncate">{p.name}</span>
-                      <span className="truncate text-caption text-[var(--text-placeholder)]">
+                      <span className="truncate text-caption text-placeholder">
                         {p.blurb}
                       </span>
                     </span>
                   </span>
                   {activeId === p.id && (
-                    <Check className="size-4 shrink-0 text-[var(--text-secondary)]" />
+                    <Check className="size-4 shrink-0 text-secondary" />
                   )}
                 </button>
               </li>
@@ -169,14 +169,14 @@ export function LanguageMenu({
   options,
   current,
   onChange,
-  ariaLabel,
+  "aria-label": ariaLabel,
   heading,
 }: {
   options: LanguageOption[];
   current: string | undefined;
   onChange: (code: string) => void;
   /** Default: `topBar.language` from the {@link UiKitProvider}, else English. */
-  ariaLabel?: string;
+  "aria-label"?: string;
   /** Optional small heading row above the list — as on `TopBarActionMenu`,
    *  `OptionSwitcherMenu` and `PaletteMenu`. */
   heading?: string;
@@ -185,7 +185,7 @@ export function LanguageMenu({
   const active = options.find((o) => o.code === current);
   return (
     <HoverMenu
-      ariaLabel={labels.language}
+      aria-label={labels.language}
       trigger={({ toggle }) => (
         <Tooltip label={active?.label ?? labels.language} portal>
           <button
@@ -228,7 +228,7 @@ export function LanguageMenu({
                     />
                     {lang.label}
                   </span>
-                  {isActive && <Check className="size-4 text-[var(--text-secondary)]" />}
+                  {isActive && <Check className="size-4 text-secondary" />}
                 </button>
               </li>
             );

package/src/shell.ts

@@ -12,7 +12,7 @@ export * from "./shell/top-bar-brand";
 export * from "./shell/auth-layout";
 // 0.31.0: the settings and admin pages' shell (docs/settings-harmonization.md §3, §5).
 export { SettingsLayout, SETTINGS_SEARCH_THRESHOLD } from "./settings/settings-layout";
-export type { SettingsLayoutProps, SettingsLayoutWidth } from "./settings/settings-layout";
+export type { SettingsLayoutProps, SettingsLayoutWidth, SettingsDocumentTitleParts } from "./settings/settings-layout";
 export {
   useSettingsRoute,
   resolveSettingsLocation,

package/src/testing/index.ts

@@ -11,3 +11,16 @@ export {
   undeclaredCssVariables,
   type UndeclaredCssVariablesOptions,
 } from "./css-variables";
+// 0.34 (refactor audit 2026-10, TST-10): the environment jsdom lacks — a `matchMedia`
+// that answers from a viewport width (right at every text size) and a `ResizeObserver`
+// the test drives. Framework-free: each returns its own undo. 0.35: `setViewportWidth`,
+// a live resize of the stub in force — its lists flip and fire `change` (keksdose).
+export {
+  setViewportWidth,
+  stubResizeObserver,
+  stubViewportWidth,
+  viewportMatchMedia,
+  type ResizeObserverStub,
+  type StubbedBoxSize,
+  type ViewportOptions,
+} from "./viewport";

package/src/testing/viewport.ts

@@ -0,0 +1,357 @@
+/**
+ * Environment stubs for an app's own tests (0.34, refactor audit 2026-10, TST-10): the
+ * two browser APIs jsdom does not have and the kit's layout reads — `matchMedia` and
+ * `ResizeObserver`.
+ *
+ * Every suite rebuilt them by hand: the kit stubbed `matchMedia` in 25 files and defined
+ * the same `stubPhone()` eight times, keksdose stubs it in 41, and most copies answer
+ * one literal string. That breaks quietly at Large text, where `md` is 960 px and the
+ * phone query the kit writes is `(width < 960px)`, not `(width < 768px)`. These answer
+ * every width query from a WIDTH, as a browser does, so they stay right at every text
+ * size (docs/text-size-harmonization.md §3.3). The reference is keksdose's
+ * `frontend/src/test/viewport.ts`, which this generalises.
+ *
+ * Framework-free, like the rest of `@eifi1/ui-kit/testing`: nothing here imports vitest
+ * or jest. Each stub returns its own undo, so it works under either runner, and a suite
+ * that prefers `vi.stubGlobal` passes it {@link viewportMatchMedia} instead.
+ */
+
+/** The media features a test may want besides the width. Each is off by default. */
+export interface ViewportOptions {
+  /** The primary pointer is a finger: `(pointer: coarse)`, `(any-pointer: coarse)` and
+   *  `(hover: none)` match; `(pointer: fine)` and `(hover: hover)` do not. */
+  coarse?: boolean;
+  /** The person asked for less motion: `(prefers-reduced-motion: reduce)` matches, and
+   *  the kit's overlays skip their exit animations. */
+  reducedMotion?: boolean;
+  /** `(prefers-color-scheme: dark)` matches (`light` does not). */
+  dark?: boolean;
+  /** `(prefers-contrast: more)` matches. */
+  moreContrast?: boolean;
+}
+
+/** One length in CSS px. A media query's `rem`/`em` is the browser's default font size,
+ *  16 px, never `<html>`'s — the kit's own `breakpointQuery` writes px. */
+function lengthPx(value: string, unit: string): number {
+  return unit === "px" ? Number(value) : Number(value) * 16;
+}
+
+const RANGE = /^\(\s*width\s*(<=|>=|<|>)\s*([\d.]+)(px|r?em)\s*\)$/;
+const MIN_MAX = /^\(\s*(min|max)-width\s*:\s*([\d.]+)(px|r?em)\s*\)$/;
+const FEATURE = /^\(\s*([a-z-]+)\s*:\s*([a-z-]+)\s*\)$/;
+
+/** One `(…)` condition, or a media type. */
+function condition(part: string, width: number, options: ViewportOptions): boolean {
+  const q = part.trim();
+  if (q === "all" || q === "screen") return true;
+  const range = RANGE.exec(q);
+  if (range) {
+    const px = lengthPx(range[2], range[3]);
+    switch (range[1]) {
+      case "<":
+        return width < px;
+      case "<=":
+        return width <= px;
+      case ">":
+        return width > px;
+      default:
+        return width >= px;
+    }
+  }
+  const minMax = MIN_MAX.exec(q);
+  if (minMax) {
+    const px = lengthPx(minMax[2], minMax[3]);
+    return minMax[1] === "min" ? width >= px : width <= px;
+  }
+  const feature = FEATURE.exec(q);
+  if (!feature) return false;
+  const [, name, value] = feature;
+  const coarse = Boolean(options.coarse);
+  switch (name) {
+    case "pointer":
+    case "any-pointer":
+      return value === (coarse ? "coarse" : "fine");
+    case "hover":
+    case "any-hover":
+      return value === (coarse ? "none" : "hover");
+    case "prefers-reduced-motion":
+      return value === (options.reducedMotion ? "reduce" : "no-preference");
+    case "prefers-color-scheme":
+      return value === (options.dark ? "dark" : "light");
+    case "prefers-contrast":
+      return value === (options.moreContrast ? "more" : "no-preference");
+    default:
+      return false;
+  }
+}
+
+/** A whole query: comma lists are alternatives, `and` joins conditions, as in CSS. */
+function answer(query: string, width: number, options: ViewportOptions): boolean {
+  return query
+    .split(",")
+    .some((alternative) =>
+      alternative.split(/\s+and\s+/).every((part) => condition(part, width, options)),
+    );
+}
+
+/** A list {@link viewportMatchMedia} handed out: what {@link setViewportWidth} flips. */
+interface StubMediaQueryList {
+  matches: boolean;
+  readonly media: string;
+  onchange: ((this: MediaQueryList, event: MediaQueryListEvent) => unknown) | null;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject | null): void;
+  removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null): void;
+  addListener(listener: EventListenerOrEventListenerObject | null): void;
+  removeListener(listener: EventListenerOrEventListenerObject | null): void;
+  dispatchEvent(event: Event): boolean;
+}
+
+/** One stub's viewport: its width now, and every list it has handed out. */
+interface StubViewport {
+  width: number;
+  readonly options: ViewportOptions;
+  readonly lists: Set<StubMediaQueryList>;
+}
+
+/** Each `matchMedia` {@link viewportMatchMedia} made → its viewport. Keyed by the function,
+ *  so {@link setViewportWidth} finds whichever stub is in force however it was put in. */
+const VIEWPORTS = new WeakMap<object, StubViewport>();
+
+function mediaQueryList(query: string, viewport: StubViewport): StubMediaQueryList {
+  // One set for both APIs: in a browser `addListener(fn)` IS `addEventListener("change",
+  // fn)`, so adding the same function through both registers it once.
+  const listeners = new Set<EventListenerOrEventListenerObject>();
+  const list: StubMediaQueryList = {
+    matches: answer(query, viewport.width, viewport.options),
+    media: query,
+    onchange: null,
+    addEventListener(type, listener) {
+      if (type === "change" && listener) listeners.add(listener);
+    },
+    removeEventListener(type, listener) {
+      if (type === "change" && listener) listeners.delete(listener);
+    },
+    addListener(listener) {
+      if (listener) listeners.add(listener);
+    },
+    removeListener(listener) {
+      if (listener) listeners.delete(listener);
+    },
+    dispatchEvent(event) {
+      if (event.type !== "change") return true;
+      const self = list as unknown as MediaQueryList;
+      list.onchange?.call(self, event as MediaQueryListEvent);
+      for (const listener of [...listeners]) {
+        if (typeof listener === "function") listener.call(self, event);
+        else listener.handleEvent(event);
+      }
+      return !event.defaultPrevented;
+    },
+  };
+  return list;
+}
+
+/** The `change` a browser fires at a list whose answer flipped: a `MediaQueryListEvent`'s
+ *  `matches` and `media`, on an `Event` (jsdom has no `MediaQueryListEvent`). */
+function changeEvent(list: StubMediaQueryList): Event {
+  const event = new Event("change");
+  for (const [key, value] of Object.entries({ matches: list.matches, media: list.media, target: list, currentTarget: list })) {
+    Object.defineProperty(event, key, { value, enumerable: true });
+  }
+  return event;
+}
+
+/**
+ * A `window.matchMedia` for a viewport `width` CSS px wide.
+ *
+ * Width queries answer from `width`: the range syntax the kit writes for `max-*`
+ * (`(width < 768px)`) and every other comparison, `(min-width: …)` and `(max-width: …)`,
+ * in px or rem; `and` and comma lists combine as in CSS. The features in `options` answer
+ * as set there; every other query is false. The lists keep their listeners, and
+ * {@link setViewportWidth} resizes the viewport under them the way a browser window
+ * does: each list whose answer flips fires `change`.
+ *
+ * Hand it to the runner's own global stub where the suite undoes stubs that way —
+ * `vi.stubGlobal("matchMedia", viewportMatchMedia(375))` — or use
+ * {@link stubViewportWidth}.
+ */
+export function viewportMatchMedia(
+  width: number,
+  options: ViewportOptions = {},
+): (query: string) => MediaQueryList {
+  const viewport: StubViewport = { width, options, lists: new Set() };
+  const matchMedia = (query: string) => {
+    const list = mediaQueryList(query, viewport);
+    viewport.lists.add(list);
+    return list as unknown as MediaQueryList;
+  };
+  VIEWPORTS.set(matchMedia, viewport);
+  return matchMedia;
+}
+
+/**
+ * Resize the stubbed viewport to `width` CSS px, live — the window being dragged narrower,
+ * a phone turned (0.35, keksdose's 0.34 report). Every list the stub in force has handed
+ * out answers from the new width, and each one whose answer flipped fires `change` to its
+ * `addEventListener` listeners, its legacy `addListener` ones and its `onchange`, as in a
+ * browser; a list whose answer stayed the same tells nobody. So a mounted component that
+ * listens to a breakpoint (`usePhoneLayout()`, `useBreakpoint()`) switches without being
+ * rendered again.
+ *
+ * The stub in force is whatever `window.matchMedia` is now — one {@link stubViewportWidth}
+ * or `vi.stubGlobal("matchMedia", viewportMatchMedia(…))` put in; its features
+ * (`options`) stay as they were. Throws when `matchMedia` is not one of these stubs, rather
+ * than resize nothing. Synchronous: wrap it in `act()` when a listener sets state.
+ *
+ * ```ts
+ * undo = stubViewportWidth(1280);
+ * render(<Page />);
+ * act(() => setViewportWidth(375));
+ * expect(screen.getByRole("list")).toBeInTheDocument(); // the cards
+ * ```
+ */
+export function setViewportWidth(width: number): void {
+  const viewport = typeof window === "undefined" ? undefined : VIEWPORTS.get(window.matchMedia);
+  if (!viewport) {
+    throw new Error(
+      "setViewportWidth: no viewport stub is in force — put one in first with " +
+        "stubViewportWidth(width), or vi.stubGlobal(\"matchMedia\", viewportMatchMedia(width)).",
+    );
+  }
+  viewport.width = width;
+  for (const list of [...viewport.lists]) {
+    const matches = answer(list.media, width, viewport.options);
+    if (matches === list.matches) continue;
+    list.matches = matches;
+    list.dispatchEvent(changeEvent(list));
+  }
+}
+
+/**
+ * Make `window.matchMedia` answer as a viewport `width` CSS px wide (see
+ * {@link viewportMatchMedia}), and return the undo: it puts back what was there, which
+ * in jsdom is nothing — no `matchMedia` at all, the desktop fallback of every kit hook.
+ *
+ * ```ts
+ * let undo = () => {};
+ * afterEach(() => undo());
+ * it("shows cards on a phone", () => {
+ *   undo = stubViewportWidth(375);
+ *   …
+ * });
+ * ```
+ *
+ * Right at every text size: at Large the kit's phone query is `(width < 960px)`, which a
+ * 375 px viewport matches and a 1280 px one does not, as in a browser.
+ */
+export function stubViewportWidth(width: number, options: ViewportOptions = {}): () => void {
+  const before = Object.getOwnPropertyDescriptor(window, "matchMedia");
+  Object.defineProperty(window, "matchMedia", {
+    configurable: true,
+    writable: true,
+    value: viewportMatchMedia(width, options),
+  });
+  return () => {
+    if (before) Object.defineProperty(window, "matchMedia", before);
+    else Reflect.deleteProperty(window, "matchMedia");
+  };
+}
+
+/** A box size for {@link ResizeObserverStub.resize}, in CSS px. */
+export interface StubbedBoxSize {
+  width: number;
+  height: number;
+}
+
+/** What {@link stubResizeObserver} returns: the test drives the observers. */
+export interface ResizeObserverStub {
+  /**
+   * Report `target` at `size` to every live observer watching it, as a browser does once
+   * layout settles: one entry, with `contentRect` and the three box sizes all `size`.
+   * Synchronous; wrap it in `act()` when the callback sets state.
+   */
+  resize(target: Element, size: StubbedBoxSize): void;
+  /** The elements some live observer watches now, each once. */
+  observed(): Element[];
+  /** Put back the `ResizeObserver` that was there before — in jsdom, none. */
+  restore(): void;
+}
+
+/**
+ * Install a `ResizeObserver` the test drives. jsdom has none, and lays nothing out, so a
+ * component that measures itself (a windowed list, a fitted chart, a measured grid)
+ * either crashes on the missing global or never learns a size. Observers here record
+ * what they watch and are called only by {@link ResizeObserverStub.resize}.
+ *
+ * ```ts
+ * const ro = stubResizeObserver();
+ * afterEach(() => ro.restore());
+ * act(() => ro.resize(screen.getByRole("list"), { width: 400, height: 320 }));
+ * ```
+ */
+export function stubResizeObserver(): ResizeObserverStub {
+  const live = new Set<StubResizeObserver>();
+
+  class StubResizeObserver {
+    readonly targets = new Set<Element>();
+    constructor(readonly callback: ResizeObserverCallback) {
+      live.add(this);
+    }
+    observe(target: Element) {
+      this.targets.add(target);
+    }
+    unobserve(target: Element) {
+      this.targets.delete(target);
+    }
+    disconnect() {
+      this.targets.clear();
+      live.delete(this);
+    }
+  }
+
+  const before = Object.getOwnPropertyDescriptor(globalThis, "ResizeObserver");
+  Object.defineProperty(globalThis, "ResizeObserver", {
+    configurable: true,
+    writable: true,
+    value: StubResizeObserver,
+  });
+
+  return {
+    resize(target, { width, height }) {
+      const box = [{ inlineSize: width, blockSize: height }];
+      const contentRect = {
+        x: 0,
+        y: 0,
+        top: 0,
+        left: 0,
+        width,
+        height,
+        right: width,
+        bottom: height,
+        toJSON: () => ({ x: 0, y: 0, width, height }),
+      };
+      const entry = {
+        target,
+        contentRect,
+        borderBoxSize: box,
+        contentBoxSize: box,
+        devicePixelContentBoxSize: box,
+      } as unknown as ResizeObserverEntry;
+      for (const observer of [...live]) {
+        if (observer.targets.has(target)) {
+          observer.callback([entry], observer as unknown as ResizeObserver);
+        }
+      }
+    },
+    observed() {
+      const all: Element[] = [];
+      for (const observer of live) for (const target of observer.targets) if (!all.includes(target)) all.push(target);
+      return all;
+    },
+    restore() {
+      live.clear();
+      if (before) Object.defineProperty(globalThis, "ResizeObserver", before);
+      else Reflect.deleteProperty(globalThis, "ResizeObserver");
+    },
+  };
+}

package/src/theme/color.ts

@@ -195,10 +195,16 @@ export function solveLightness(
   const bgL = rgbToOklch(against).l;
   let lo = direction === "darker" ? 0 : bgL;
   let hi = direction === "darker" ? bgL : 1;
+  // Measured on the HEX both colours are painted as, never on the float (round 0.34
+  // BUG-8): a solve that stopped on the float colour rounded to a hex just under the
+  // target — brand #000000's light income figure solved to 4.5000 and shipped at 4.49:1.
+  // Rounding keeps contrast monotonic in each half, so the bisection still holds, and
+  // the side it returns is the side whose hex clears the target.
+  const bg = toHex(against);
 
   for (let i = 0; i < 24; i++) {
     const mid = (lo + hi) / 2;
-    const got = contrast(oklchToRgb({ l: mid, c, h }), against);
+    const got = contrast(toHex(oklchToRgb({ l: mid, c, h })), bg);
     // Moving AWAY from the background raises contrast; which way that is depends on
     // whether we are going lighter or darker.
     if (got < target) {