@eifi1/ui-kit 0.34.0 → 0.35.0

package/src/rhf/fields.tsx

@@ -27,7 +27,7 @@
  *  - **The red border.** Every field gets `invalid` from the field state, so an errored
  *    field PAINTS as well as announces. kastlan's number, money, date and entity fields
  *    passed only `aria-invalid` through `FormControl`, or nothing, and `Input`, `Select`
- *    and `Textarea` paint only from the prop (see the note in ./form).
+ *    and `Textarea` paint only from the prop (see the note in ./form-core).
  *  - **Focus on error.** `field.ref` reaches the focusable element itself — the input,
  *    a picker's trigger, a toggle group whose `focus()` lands on its option (since 0.34
  *    every kit field takes a ref; the number field and the pickers were reached by an id
@@ -37,7 +37,7 @@
  *    through react-hook-form's context. Pass it for the field's value types
  *    (`control={form.control}` checks `name` against the form's values).
  *
- * The common props: `name`, `control`, `label` (a {@link FormLabel} above the field;
+ * The common props: `name`, `control`, `label` (the label above the field;
  * omitted, none — then give the field an `aria-label`), `hint` (standing advice under
  * the field, attached to it with `aria-describedby`), `required` (the label's mark,
  * and `aria-required` where the control takes it — validation is `rules`' or the
@@ -110,7 +110,7 @@ export interface RhfFieldBaseProps<
   control?: ControllerProps<TFieldValues, TName, TTransformed>["control"];
   /** react-hook-form's `rules` (`required`, `min`, `validate` …). */
   rules?: ControllerProps<TFieldValues, TName, TTransformed>["rules"];
-  /** A {@link FormLabel} above the field. Omitted: no label — name the control with
+  /** The label above the field. Omitted: no label — name the control with
    *  an `aria-label` instead. */
   label?: ReactNode;
   /** Standing advice under the field ("As printed on the card"), attached to the
@@ -146,8 +146,8 @@ export interface RhfFieldRenderContext<
   invalid: boolean;
   /** The error's message, if any. */
   error: string | undefined;
-  /** The control's id, which the label points at. `FormControl` sets it on the
-   *  rendered element already; this is for a control that routes it elsewhere. */
+  /** The control's id, which the label points at. The rendered element has it already
+   *  (unless `asControl` is false); this is for a control that routes it elsewhere. */
   id: string;
   /** The label's id, for a control that is named with `aria-labelledby`. */
   labelId: string;
@@ -160,16 +160,16 @@ export interface RhfFieldProps<
   TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
   TTransformed = TFieldValues,
 > extends RhfFieldBaseProps<TFieldValues, TName, TTransformed> {
-  /** The control. Wrapped in {@link FormControl} (its `id`, `aria-describedby` and
-   *  `aria-invalid`) unless `asControl` is false. */
+  /** The control. Given the field's `id`, `aria-describedby` and `aria-invalid` unless
+   *  `asControl` is false. */
   render: (ctx: RhfFieldRenderContext<TFieldValues, TName>) => ReactElement;
   /** `false`: render the control as is, for one that wires its own ids from the
    *  context. Default `true`. */
   asControl?: boolean;
-  /** `false`: no {@link FormMessage}, for a control that renders its own error (its
+  /** `false`: no error message under the field, for a control that renders its own (its
    *  `error` prop). Default `true`. */
   message?: boolean;
-  /** `false`: no {@link FormLabel}, for a control that carries its label itself (a
+  /** `false`: no label above the field, for a control that carries its label itself (a
    *  checkbox). Default `true`. */
   showLabel?: boolean;
 }
@@ -1622,7 +1622,7 @@ export type RhfToggleGroupProps<
  * asked for it with {@link RhfTimeInput} and {@link RhfDateRangePicker}: the controls
  * its forms still had to wire by hand through {@link RhfField}'s render.
  *
- * The label is the form's {@link FormLabel} above the bare group, as on every other
+ * The label is the field's own label above the bare group, as on every other
  * bound field — the `labelPlacement="above"` shape, not the group's own field chrome —
  * and it names the group (`aria-labelledby`); the hint and the message describe it,
  * and an error paints the group's border. Focus on error goes to the option a

package/src/rhf/form-core.tsx

@@ -1,10 +1,11 @@
 /**
- * The react-hook-form adapter: the five parts every form is built from, and the hook
- * they share. `@eifi1/ui-kit/rhf`.
+ * The react-hook-form adapter: the five parts every bound field is built from, and the
+ * hook they share. Behind `@eifi1/ui-kit/rhf`, which exports `Form` alone of them.
  *
  * The kit's own module since 0.34 (refactor audit 2026-10, API-6f): the bound `Rhf*`
- * fields build on these parts, and import them from here. ./form is the public face —
- * `Form`, and until 0.35 the parts under their deprecated names, which no app imports.
+ * fields and `RhfField` build on these parts, and import them from here. ./form is the
+ * public face — `Form`; the parts left the public surface in 0.35 (deprecated in 0.34),
+ * when no app imported them any more.
  *
  * ```tsx
  * <Form {...form}>

package/src/rhf/form.tsx

@@ -1,48 +1,12 @@
 /**
- * `Form`, and until 0.35 the shadcn scaffold under its old public names — the public face
- * of ./form-core, where the scaffold lives (its header has the whole story: what differs
- * from shadcn's file, why /rhf is its own entry, how a picker clears).
+ * `Form` — the public face of ./form-core, where the shadcn scaffold the bound fields are
+ * built from lives (its header has the whole story: what differs from shadcn's file, why
+ * /rhf is its own entry, how a picker clears).
  *
- * 0.34 (refactor audit 2026-10, API-6f): no app builds a form from the scaffold any more.
+ * The scaffold itself (`FormField`, `useFormField`, `FormItem`, `FormLabel`, `FormControl`,
+ * `FormDescription`, `FormMessage` and five props types) was public until 0.35 (refactor
+ * audit 2026-10, API-6f; deprecated in 0.34): no app builds a form from it any more.
  * kastlan, the one /rhf consumer, uses `Form`, the bound `Rhf*` fields and `RhfField` for
- * a control of its own, so the seven names and their props types leave the public
- * surface in 0.35. The bound fields import the parts from the core, so the removal is
- * the block below.
+ * a control of its own — the same parts, folded into one element.
  */
-import * as core from "./form-core";
-
 export { Form } from "./form-core";
-
-/* ── Deprecated 0.34, removed in 0.35 ───────────────────────────────────────
- * Each is the core's own value under its public name. The replacement for all of them:
- * a bound field (`RhfTextField`, `RhfSelect`, …), or `RhfField` around a control of
- * your own — the same parts, folded into one element. */
-
-/** @deprecated 0.34 — the bound `Rhf*` fields, or `RhfField` for a control of your own;
- *  removed in 0.35 (API-6f). */
-export const FormField = core.FormField;
-/** @deprecated 0.34 — `RhfField`, which reads the field's ids itself; removed in 0.35
- *  (API-6f). */
-export const useFormField = core.useFormField;
-/** @deprecated 0.34 — the bound `Rhf*` fields, or `RhfField`; removed in 0.35 (API-6f). */
-export const FormItem = core.FormItem;
-/** @deprecated 0.34 — the bound fields' and `RhfField`'s `label`; removed in 0.35 (API-6f). */
-export const FormLabel = core.FormLabel;
-/** @deprecated 0.34 — `RhfField`, which wires its control the same way; removed in 0.35
- *  (API-6f). */
-export const FormControl = core.FormControl;
-/** @deprecated 0.34 — the bound fields' and `RhfField`'s `hint`; removed in 0.35 (API-6f). */
-export const FormDescription = core.FormDescription;
-/** @deprecated 0.34 — the bound fields and `RhfField`, which show the error themselves;
- *  removed in 0.35 (API-6f). */
-export const FormMessage = core.FormMessage;
-/** @deprecated 0.34 — goes with `FormItem`; removed in 0.35 (API-6f). */
-export type FormItemProps = core.FormItemProps;
-/** @deprecated 0.34 — goes with `FormLabel`; removed in 0.35 (API-6f). */
-export type FormLabelProps = core.FormLabelProps;
-/** @deprecated 0.34 — goes with `FormControl`; removed in 0.35 (API-6f). */
-export type FormControlProps = core.FormControlProps;
-/** @deprecated 0.34 — goes with `FormDescription`; removed in 0.35 (API-6f). */
-export type FormDescriptionProps = core.FormDescriptionProps;
-/** @deprecated 0.34 — goes with `FormMessage`; removed in 0.35 (API-6f). */
-export type FormMessageProps = core.FormMessageProps;

package/src/rhf/line-items.tsx

@@ -27,7 +27,7 @@
  * `summary`, `fieldLabels`, `narrowColumns`, `removePlacement` and `removeAlign` pass
  * through to {@link LineItems}. With
  * `fieldLabels="floating"` a cell's `fieldLabel` is the column's name; the bound
- * fields' own `label` is a `FormLabel` ABOVE the control, so for the floating
+ * fields' own `label` is a label ABOVE the control, so for the floating
  * one render the kit field through `RhfField`:
  * `render={({ field, invalid }) => <Input label={fieldLabel} aria-label={label} {...field} invalid={invalid} />}`.
  */

package/src/rhf/use-rhf-wizard-step.ts

@@ -12,10 +12,10 @@
  *
  * Inside a `<StepperNav>` the hook registers the step's validator with the wizard, so
  * Next (and Finish on a form-bearing last step) runs it: on success the values go to
- * `onValid` and the wizard advances; on failure react-hook-form shows its own inline
- * `<FormMessage>`s, focuses the first field in error, and the wizard stays put — and,
- * since the result carries no per-field errors, says its "fill in the required
- * fields" line so the button did not seem to do nothing. It also RETURNS the
+ * `onValid` and the wizard advances; on failure the bound fields show their inline
+ * messages, react-hook-form focuses the first field in error, and the wizard stays
+ * put — and, since the result carries no per-field errors, says its "fill in the
+ * required fields" line so the button did not seem to do nothing. It also RETURNS the
  * validator, for a nav of your own outside `<StepperNav>` (where there is no wizard
  * context to register with, so nothing is registered).
  *

package/src/rhf.ts

@@ -1,6 +1,7 @@
 // `@eifi1/ui-kit/rhf` — the react-hook-form adapter: Form and the bound Rhf* fields (and
-// RhfField as the escape hatch). The shadcn scaffold (FormField, FormItem, FormLabel,
-// FormControl, FormDescription, FormMessage, useFormField) is deprecated in 0.34.
+// RhfField as the escape hatch). The shadcn scaffold they are built from (FormField,
+// FormItem, FormLabel, FormControl, FormDescription, FormMessage, useFormField) left the
+// surface in 0.35 (refactor audit 2026-10, API-6f; deprecated in 0.34).
 //
 // The only entry point in the package that requires `react-hook-form`, and an optional
 // peer for that reason: an app without a form library installs nothing for it. NOT

package/src/shell/option-switcher-menu.tsx

@@ -9,23 +9,6 @@ export interface OptionSwitcherOption<T extends string> {
   label: ReactNode;
 }
 
-/**
- * Names the trigger and the menu: one of the two spellings is required (API-1, refactor
- * audit 2026-10). `aria-label` wins when both are given. TopBarActionMenu has the same
- * type; both become a plain required `aria-label` when `ariaLabel` goes in 0.35.
- */
-type RequiredMenuName =
-  | {
-      "aria-label": string;
-      /** @deprecated 0.34 — use `aria-label`; removed in 0.35. */
-      ariaLabel?: string;
-    }
-  | {
-      "aria-label"?: string;
-      /** @deprecated 0.34 — use `aria-label`; removed in 0.35. */
-      ariaLabel: string;
-    };
-
 /**
  * A top-bar hover menu that switches between a small set of options, with a
  * check on the active one and an optional heading. Generic glue over
@@ -34,8 +17,7 @@ type RequiredMenuName =
  */
 export function OptionSwitcherMenu<T extends string>({
   icon,
-  "aria-label": ariaLabelAttr,
-  ariaLabel: ariaLabelProp,
+  "aria-label": ariaLabel,
   title,
   heading,
   options,
@@ -43,14 +25,15 @@ export function OptionSwitcherMenu<T extends string>({
   onSelect,
 }: {
   icon: ReactNode;
+  /** 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;
   title?: string;
   heading?: string;
   options: OptionSwitcherOption<T>[];
   value: T;
   onSelect: (value: T) => void;
-} & RequiredMenuName) {
-  // The DOM spelling wins; `ariaLabel` is the fallback for call sites not moved yet.
-  const ariaLabel = ariaLabelAttr ?? ariaLabelProp;
+}) {
   return (
     <HoverMenu
       aria-label={ariaLabel}

package/src/shell/role-switcher.tsx

@@ -8,9 +8,6 @@ export interface RoleSwitcherProps<R extends string> {
   onChange: (role: R) => void;
   /** Default: `topBar.switchRole` from the {@link UiKitProvider}, else English. */
   "aria-label"?: string;
-  /** @deprecated 0.34 — use `aria-label`; removed in 0.35 (refactor audit 2026-10, API-1).
-   *  Names the switcher only when `aria-label` is absent. */
-  ariaLabel?: string;
   heading?: string;
   /** The trigger's tooltip. Default: `topBar.role(value)`. */
   title?: string;
@@ -30,12 +27,11 @@ export function RoleSwitcher<R extends string>({
   roles,
   value,
   onChange,
-  "aria-label": ariaLabelAttr,
-  ariaLabel,
+  "aria-label": ariaLabel,
   heading,
   title,
 }: RoleSwitcherProps<R>) {
-  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { switchRole: ariaLabelAttr ?? ariaLabel });
+  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { switchRole: ariaLabel });
   return (
     <OptionSwitcherMenu<R>
       aria-label={labels.switchRole}

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

@@ -179,23 +179,6 @@ function keepTabInsidePanel(e: ReactKeyboardEvent<HTMLUListElement>) {
   if (stops.some((el) => el !== from && from.compareDocumentPosition(el) & way)) e.stopPropagation();
 }
 
-/**
- * Names the trigger and the menu: one of the two spellings is required (API-1, refactor
- * audit 2026-10). `aria-label` wins when both are given. OptionSwitcherMenu has the same
- * type; both become a plain required `aria-label` when `ariaLabel` goes in 0.35.
- */
-type RequiredMenuName =
-  | {
-      "aria-label": string;
-      /** @deprecated 0.34 — use `aria-label`; removed in 0.35. */
-      ariaLabel?: string;
-    }
-  | {
-      "aria-label"?: string;
-      /** @deprecated 0.34 — use `aria-label`; removed in 0.35. */
-      ariaLabel: string;
-    };
-
 /**
  * A top-bar icon button that opens a {@link HoverMenu} of actions and/or links,
  * with an optional uppercase heading and divider rules. Generic glue over the
@@ -219,8 +202,7 @@ export function TopBarActionMenu({
   trigger,
   triggerClassName,
   href,
-  "aria-label": ariaLabelAttr,
-  ariaLabel: ariaLabelProp,
+  "aria-label": ariaLabel,
   heading,
   header,
   entries,
@@ -265,6 +247,9 @@ export function TopBarActionMenu({
    * inside interactive content.
    */
   href?: 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;
@@ -283,13 +268,11 @@ 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`, whose type this
-   *  is: `left`/`right` are deprecated 0.34). Default `end`. */
+  /** 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;
-} & RequiredMenuName) {
-  // The DOM spelling wins; `ariaLabel` is the fallback for call sites not moved yet.
-  const ariaLabel = ariaLabelAttr ?? ariaLabelProp;
+}) {
   // Names the groups' headings for `aria-labelledby`. Positional rather than from the
   // entry's `key`, which is the caller's text and may hold a space — and a space in
   // `aria-labelledby` is a list separator.

package/src/shell/topbar-controls.tsx

@@ -29,8 +29,7 @@ function MenuHeading({ children }: { children: string }) {
 export function ThemeToggle({
   mode,
   onToggle,
-  "aria-label": ariaLabelAttr,
-  ariaLabel,
+  "aria-label": ariaLabel,
   title,
   className,
 }: {
@@ -38,15 +37,12 @@ export function ThemeToggle({
   onToggle: () => void;
   /** Default: `topBar.theme` from the {@link UiKitProvider}, else English. */
   "aria-label"?: string;
-  /** @deprecated 0.34 — use `aria-label`; removed in 0.35 (refactor audit 2026-10, API-1).
-   *  Names the control only when `aria-label` is absent. */
-  ariaLabel?: string;
   title?: string;
   className?: string;
 }) {
   // 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: ariaLabelAttr ?? ariaLabel });
+  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { theme: ariaLabel });
   const Icon = mode === "dark" ? Moon : Sun;
   return (
     <Tooltip label={title} portal>
@@ -69,8 +65,7 @@ export function PaletteMenu({
   activeId,
   mode,
   onSelect,
-  "aria-label": ariaLabelAttr,
-  ariaLabel,
+  "aria-label": ariaLabel,
   heading,
 }: {
   palettes: PalettePreset[];
@@ -79,13 +74,10 @@ export function PaletteMenu({
   onSelect: (id: string) => void;
   /** Default: `topBar.palette` from the {@link UiKitProvider}, else English. */
   "aria-label"?: string;
-  /** @deprecated 0.34 — use `aria-label`; removed in 0.35 (refactor audit 2026-10, API-1).
-   *  Names the control only when `aria-label` is absent. */
-  ariaLabel?: string;
   /** Optional small heading row above the list. */
   heading?: string;
 }) {
-  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { palette: ariaLabelAttr ?? ariaLabel });
+  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { palette: ariaLabel });
   const activeName = palettes.find((p) => p.id === activeId)?.name ?? activeId;
   return (
     <HoverMenu
@@ -177,8 +169,7 @@ export function LanguageMenu({
   options,
   current,
   onChange,
-  "aria-label": ariaLabelAttr,
-  ariaLabel,
+  "aria-label": ariaLabel,
   heading,
 }: {
   options: LanguageOption[];
@@ -186,14 +177,11 @@ export function LanguageMenu({
   onChange: (code: string) => void;
   /** Default: `topBar.language` from the {@link UiKitProvider}, else English. */
   "aria-label"?: string;
-  /** @deprecated 0.34 — use `aria-label`; removed in 0.35 (refactor audit 2026-10, API-1).
-   *  Names the control only when `aria-label` is absent. */
-  ariaLabel?: string;
   /** Optional small heading row above the list — as on `TopBarActionMenu`,
    *  `OptionSwitcherMenu` and `PaletteMenu`. */
   heading?: string;
 }) {
-  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { language: ariaLabelAttr ?? ariaLabel });
+  const labels = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS, { language: ariaLabel });
   const active = options.find((o) => o.code === current);
   return (
     <HoverMenu

package/src/testing/index.ts

@@ -13,8 +13,10 @@ export {
 } 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.
+// 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,

package/src/testing/viewport.ts

@@ -85,14 +85,91 @@ function condition(part: string, width: number, options: ViewportOptions): boole
   }
 }
 
+/** 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 it returns never change, so
- * nothing fires `change`: a test that changes the width stubs again and renders again.
+ * 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
@@ -102,23 +179,52 @@ export function viewportMatchMedia(
   width: number,
   options: ViewportOptions = {},
 ): (query: string) => MediaQueryList {
-  const answer = (query: string) =>
-    query
-      .split(",")
-      .some((alternative) =>
-        alternative.split(/\s+and\s+/).every((part) => condition(part, width, options)),
-      );
-  return (query: string) =>
-    ({
-      matches: answer(query),
-      media: query,
-      onchange: null,
-      addEventListener: () => {},
-      removeEventListener: () => {},
-      addListener: () => {},
-      removeListener: () => {},
-      dispatchEvent: () => false,
-    }) as unknown as 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));
+  }
 }
 
 /**