@eifi1/ui-kit 0.34.0 → 0.36.0

package/src/settings/device-reset-setting.tsx

@@ -0,0 +1,119 @@
+import type { ReactNode } from "react";
+
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { resetDeviceSettings } from "../lib/device-settings";
+import { Button } from "../components/button";
+import { useConfirm } from "../components/confirm-dialog";
+import { toast } from "../components/toast";
+import { SettingsSection, type SettingsSectionProps } from "./settings-section";
+import { DEFAULT_DEVICE_RESET_LABELS } from "./device-reset-setting-labels";
+
+/* ── Labels ──────────────────────────────────────────────────────────────── */
+
+/** Every string {@link DeviceResetSetting} renders — the `deviceReset` namespace of
+ *  `<UiKitProvider labels>`, overridable per instance through `labels`
+ *  (docs/settings-harmonization.md §11.3). The confirm's Cancel is `confirmDialog.cancel`. */
+export interface DeviceResetLabels {
+  /** The card's title, and the app's catalogue entry's. */
+  title: string;
+  /** The line under it: what goes back, and that the account is not touched. */
+  description: string;
+  /** The button that asks first. */
+  action: string;
+  /** The question it asks. */
+  confirmTitle: string;
+  /** What goes, what follows the account again, and what stays. */
+  confirmBody: string;
+  /** The button that answers it. */
+  confirmAction: string;
+  /** The toast once it is done. */
+  done: string;
+  /** For the app's catalogue entry (`keywords`); the card never reads it. */
+  keywords: string;
+}
+
+// Defined in ./device-reset-setting-labels, which holds no component code.
+export { DEFAULT_DEVICE_RESET_LABELS };
+
+/* ── The card ────────────────────────────────────────────────────────────── */
+
+/** The card's DOM id: its catalogue entry's `anchor`, the `?focus=` target. */
+export const DEVICE_RESET_ANCHOR = "settings-device-reset";
+
+// `onReset` is the card's own: the DOM's form-reset handler never fires on a div.
+export interface DeviceResetSettingProps
+  extends Omit<SettingsSectionProps, "anchor" | "title" | "description" | "children" | "onReset"> {
+  /** The app's sentence after the kit's description: what of its own goes back, and what
+   *  stays (keksdose: the date format, the feature set and the gestures go; presentation
+   *  mode and the home position stay). */
+  description?: ReactNode;
+  labels?: LabelOverride<DeviceResetLabels>;
+  /** Runs after the reset and before the toast, with the keys reset or removed. */
+  onReset?: (keys: string[]) => void;
+}
+
+/**
+ * "Reset this device's settings" (docs/settings-harmonization.md §11): the LAST card of
+ * the appearance group. It puts this device's appearance — theme, palette, language, text
+ * size, contrast and the app's own appearance choices — and its views — table views, the
+ * sidebar, folded groups, saved filters — back to what a new device gets, through
+ * {@link resetDeviceSettings}. The account, the sign-in, the session and anything waiting
+ * to be sent are never touched: they never join the registry.
+ *
+ * - **A confirm, not an undo** (§11.2 decision 9): `useConfirm` in the neutral tone,
+ *   then a toast. An app mounts a `ConfirmProvider` and a `Toaster` already.
+ * - **Not a commit**: nothing is written to the account, so a demo or a lapsed plan's
+ *   write lock does not disable it (decision 3).
+ * - **Live, no reload** (decision 10): each registered store resets through its own
+ *   setter; the card stays where it is.
+ *
+ * The app adds the catalogue entry, `{ id: "device_reset", group: "appearance", anchor:
+ * DEVICE_RESET_ANCHOR, title, keywords }` (`title` and `keywords` from these labels), last
+ * in its appearance group: inside a `SettingsLayout`, `SettingsSection` throws in
+ * development without it.
+ */
+export function DeviceResetSetting({
+  description,
+  labels: labelsProp,
+  onReset,
+  ...rest
+}: DeviceResetSettingProps) {
+  const labels = useKitLabels("deviceReset", DEFAULT_DEVICE_RESET_LABELS, labelsProp);
+  const confirm = useConfirm();
+
+  const reset = async () => {
+    const ok = await confirm({
+      title: labels.confirmTitle,
+      body: labels.confirmBody,
+      confirmLabel: labels.confirmAction,
+      tone: "neutral",
+    });
+    if (!ok) return;
+    const keys = resetDeviceSettings();
+    onReset?.(keys);
+    toast.success(labels.done);
+  };
+
+  return (
+    <SettingsSection
+      {...rest}
+      anchor={DEVICE_RESET_ANCHOR}
+      title={labels.title}
+      description={
+        description != null ? (
+          <>
+            {labels.description} {description}
+          </>
+        ) : (
+          labels.description
+        )
+      }
+    >
+      <div>
+        <Button variant="secondary" onClick={() => void reset()}>
+          {labels.action}
+        </Button>
+      </div>
+    </SettingsSection>
+  );
+}

package/src/shell/app-shell.tsx

@@ -8,6 +8,7 @@ import { cn } from "../lib/cn";
 import { scrollIntoStrip, useStripFade } from "../lib/strip-fade";
 import { dirOf, type Direction } from "../lib/direction";
 import { readStored, writeStored } from "../lib/safe-storage";
+import { registerDeviceSetting } from "../lib/device-settings";
 import { Tooltip } from "../components/tooltip";
 import { pickLinkRenderer } from "../components/text-link";
 import { DialogFrame } from "../components/dialog-frame";
@@ -394,6 +395,13 @@ export function AppShell({
   useEffect(() => {
     if (collapseStorageKey !== null) writeStored(collapseStorageKey, collapsed ? "1" : "0");
   }, [collapsed, collapseStorageKey]);
+  // Reset this device's settings (docs/settings-harmonization.md §11.4): the sidebar
+  // unfolds, live, and the effect above writes "0". An embedded shell without a key of
+  // its own stores nothing and joins nothing.
+  useEffect(() => {
+    if (collapseStorageKey === null) return;
+    return registerDeviceSetting({ key: collapseStorageKey, kind: "view", reset: () => setCollapsed(false) });
+  }, [collapseStorageKey]);
   // §4: at Large and Extra large the sidebar never collapses to icons only — a glyph
   // with its name in a tooltip is the very thing a reader who asked for bigger type
   // cannot use. The persisted preference is left alone, so Normal gets it back, and the

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));
+  }
 }
 
 /**