fix(a11y): names that carry what they show; the unused-key check stops covering whole files

- The palette launcher's name replaced its visible "Jump to…" (and the key cap's its "Ctrl K"): a voice-control "click Jump to" matched nothing (WCAG 2.5.3). Each name contains its text now. - SegmentedToggle's `title` was only a tooltip on a non-focusable box — the live search's "how many per batch" hint reached no keyboard or screen-reader user. It is the group's accessible description, standalone and captioned alike. - The unused-key contract let a template like `card.${status}` cover its whole namespace, which hid five dead keys (deleted). Dynamic keys are matched by shape (`editor.*.hint`); a bare namespace shape covers nothing, and the audit/quota namespaces are now held both ways by backendIds. - CLAUDE.md's "FE control" row matches the lint rule it cites; each no-restricted-syntax entry has its reason directly above it.
2026-09-19 19:19:43 +02:00
parent fa4f823fc8
commit cf0c55ba80
13 changed files with 128 additions and 39 deletions
@@ -92,7 +92,7 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory
 | FE keyboard shortcut    | a row in `lib/keymap.ts` + `dispatch()`                      | a private `keydown` listener with its own key literals |
 | FE list/grid keys       | `NavGrid`/`keyboardNav` + `navItemAttrs` + `data-nav-open`   | a private arrow-key / roving-tabindex handler          |
 | FE view push (history)  | `rememberNavPosition()` right before `history.pushState`     | a push that forgets: Back strands focus on `<body>`    |
-| FE control              | the chip/segmented primitives (`Select` only for >6 options) | a native `<select>`                                    |
+| FE control              | `SegmentedToggle`; a long or user's list: `FilterSelect`     | a native `<select>` (lint-enforced)                    |
 | FE loading/empty/error  | `QueryState` / `StateMessage`                                | ad-hoc conditionals                                    |
 | FE failed write         | `meta.failTitle`, else `notifyActionError(err, title)`       | a bare `catch {}` or `notify()` with no error attached |
 | FE network call         | `req`/`uploadReq`/`beacon`, or `lib/http.ts` `send` (public pages) | a bare `fetch`/`XMLHttpRequest`/`WebSocket` (lint-enforced) |
@@ -212,15 +212,10 @@ export default tseslint.config(
        "error",
        { allowShortCircuit: true, allowTernary: true },
      ],
-      // R10 S2: keep the rem system from rotting. A px-frozen `text-[Npx]` font size does NOT scale
-      // with the Settings --font-scale slider while its rem neighbours do; use `text-2xs`/`text-3xs`
-      // or a `text-[Nrem]` arbitrary instead. Matches both plain strings and template-literal chunks;
-      // rem arbitraries (text-[0.75rem]) don't match (no "px").
+      // Source-shape rules, each with its reason right above it (contract-tested in
+      // lib/*.contract.test.ts).
      "no-restricted-syntax": [
        "error",
-        // The canonical "FE control" row (CLAUDE.md): a short fixed set is a SegmentedToggle, a
-        // longer one or a user's own list a FilterSelect. Six native selects had drifted in; the
-        // 2026-09 debt burn replaced them, and this keeps the next one out.
        // `enabled:` sees only the native attribute; a FocusSafeButton that holds the focus is
        // disabled by aria-disabled, so a bare `enabled:hover:` lit it up on hover as if it worked.
        {
@@ -233,11 +228,18 @@ export default tseslint.config(
          message:
            "`enabled:hover:` misses a focused FocusSafeButton (aria-disabled): use `enabled:not-aria-disabled:hover:`.",
        },
+        // The canonical "FE control" row (CLAUDE.md): a short fixed set is a SegmentedToggle, a
+        // longer one or a user's own list a FilterSelect. Six native selects had drifted in; the
+        // 2026-09 debt burn replaced them, and this keeps the next one out.
        {
          selector: "JSXOpeningElement[name.name='select']",
          message:
            "No native <select>: use ui/SegmentedToggle for a short fixed set, ui/FilterSelect for a longer one or a user's own list.",
        },
+        // R10 S2: keep the rem system from rotting. A px-frozen `text-[Npx]` font size does NOT
+        // scale with the Settings --font-scale slider while its rem neighbours do; use
+        // `text-2xs`/`text-3xs` or a `text-[Nrem]` arbitrary instead. Matches both plain strings and
+        // template-literal chunks; rem arbitraries (text-[0.75rem]) don't match (no "px").
        {
          selector: "Literal[value=/text-\\[[\\d.]+px\\]/]",
          message:
@@ -446,14 +446,12 @@ export default function Feed({
              {zeroQuota ? t("feed.yt.freeNote") : t("feed.yt.quotaNote")}
            </span>
            {/* Four fixed counts: the house's segmented control, not a native <select> (owner's
-                pick, 2026-09-19). The caption is the group's name; the hint rides on the row. */}
-            <div
-              className="ml-auto flex items-center gap-1.5 text-xs text-muted shrink-0"
-              title={t("feed.yt.showHint")}
-            >
+                pick, 2026-09-19). The caption is the group's name, the hint its description. */}
+            <div className="ml-auto flex items-center gap-1.5 text-xs text-muted shrink-0">
              <span aria-hidden="true">{t("feed.yt.show")}</span>
              <SegmentedToggle
                ariaLabel={t("feed.yt.show")}
+                title={t("feed.yt.showHint")}
                value={String(ytCount)}
                onChange={(v) => setYtCount(Number(v))}
                options={YT_COUNTS.map((n) => ({ value: String(n), label: String(n) }))}
@@ -54,8 +54,9 @@ describe("the command palette's visible entry", () => {
  it("is a key cap inside the search field, naming the chord the palette row binds", () => {
    page = "feed";
    const isOpen = mount();
-    const cap = screen.getByRole("button", { name: "palette.open" });
-    expect(cap.textContent).toMatch(/^(Ctrl|⌘) K$/);
+    const cap = screen.getByRole("button", { name: /^palette\.open \((Ctrl|⌘) K\)$/ });
+    // Label in Name: the name carries what the cap shows, so "click Ctrl K" finds it.
+    expect(cap.getAttribute("aria-label")).toContain(cap.textContent);
    expect(screen.getByRole("textbox")).toBeTruthy();
    fireEvent.click(cap);
    expect(isOpen()).toBe(true);
@@ -65,8 +66,9 @@ describe("the command palette's visible entry", () => {
    page = "home";
    const isOpen = mount();
    expect(screen.queryByRole("textbox")).toBeNull();
-    const pill = screen.getByRole("button", { name: "palette.open" });
-    expect(pill.textContent).toContain("palette.title");
+    // Named by what it shows ("Jump to…"), not by a label that replaced it.
+    const pill = screen.getByRole("button", { name: "palette.title" });
+    expect(pill.getAttribute("title")).toBe("palette.open");
    fireEvent.click(pill);
    expect(isOpen()).toBe(true);
  });
@@ -20,6 +20,10 @@ function useCap(): string {
  });
 }

+// Each accessible name CONTAINS what the control shows (WCAG 2.5.3, Label in Name): a voice-control
+// user says what they see — "click Jump to", "click Ctrl K" — and a name that replaced the visible
+// words matched nothing.
+
 /** The key cap at the end of a search field. A button, so the pointer and a screen reader reach it
 *  too; left out of a phone's narrow header, where there is no keyboard to press it on. */
 export function PaletteKeycap() {
@@ -29,7 +33,7 @@ export function PaletteKeycap() {
    <button
      type="button"
      onClick={openPalette}
-      aria-label={t("palette.open")}
+      aria-label={`${t("palette.open")} (${cap})`}
      title={t("palette.open")}
      className="shrink-0 rounded-md border border-border px-1.5 py-0.5 font-mono text-3xs text-muted transition hover:border-accent/50 hover:text-fg @max-[640px]/appmain:hidden"
    >
@@ -46,7 +50,7 @@ export function PaletteLauncher() {
    <button
      type="button"
      onClick={openPalette}
-      aria-label={t("palette.open")}
+      title={t("palette.open")}
      className="pointer-events-auto glass-menu flex h-11 items-center gap-2 rounded-2xl px-3 text-sm text-muted transition hover:text-fg"
    >
      <Command className="h-4 w-4 shrink-0" aria-hidden="true" />
@@ -69,4 +69,39 @@ describe("SegmentedToggle", () => {
    expect(screen.getByTestId("ic-my")).toBeTruthy();
    expect(screen.getByRole("button", { name: "Mine" }).getAttribute("title")).toBe("Your subs");
  });
+
+  // The hint was a `title` on a non-focusable box: the pointer's tooltip, and nothing at all for a
+  // keyboard or screen-reader user (deep review, debt burn). It is the group's description now.
+  it("describes the group by its title, standalone and captioned alike", () => {
+    render(
+      <>
+        <SegmentedToggle
+          options={OPTS}
+          value="or"
+          onChange={vi.fn()}
+          ariaLabel="Show"
+          title="Results per batch"
+        />
+        <SegmentedToggle
+          options={OPTS}
+          value="or"
+          onChange={vi.fn()}
+          ariaLabel="Match"
+          label="Match"
+          title="Any or all"
+        />
+      </>,
+    );
+    expect(
+      screen.getByRole("group", { name: "Show", description: "Results per batch" }),
+    ).toBeTruthy();
+    expect(screen.getByRole("group", { name: "Match", description: "Any or all" })).toBeTruthy();
+  });
+
+  it("adds no description without a title", () => {
+    render(<SegmentedToggle options={OPTS} value="or" onChange={vi.fn()} ariaLabel="Match" />);
+    expect(screen.getByRole("group", { name: "Match" }).hasAttribute("aria-describedby")).toBe(
+      false,
+    );
+  });
 });
@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import { useId, type ReactNode } from "react";

 // Shared MATCH / segmented primitive — a rounded-full pill track where exactly ONE option is active
 // (radio-like). Backs the feed any/all + or/and "Match" toggles and the feed Mine/Library scope bar,
@@ -31,13 +31,17 @@ export default function SegmentedToggle<T extends string>({
  // Optional left-hand caption; when set the control renders as a justify-between row (the feed/Plex
  // "Match" toggles). Omit for a standalone bar (the Mine/Library scope switch).
  label?: ReactNode;
-  title?: string; // tooltip on the whole row (caption mode only)
+  // What the choice means, beyond its name: the row's tooltip for the pointer, and the group's
+  // accessible description for the keyboard and a screen reader — a `title` on a non-focusable box
+  // alone reaches neither (it had only ever been the pointer's).
+  title?: string;
  // Full-width track with flex-1 buttons (the scope bar); default is intrinsic width.
  fullWidth?: boolean;
  // sm = text-3xs, compact padding (the captioned match toggles); md = text-xs (the scope bar).
  size?: "sm" | "md";
  className?: string;
 }) {
+  const hintId = useId();
  const track = (
    <div
      className={`inline-flex items-center rounded-full border border-border bg-card p-0.5 ${
@@ -45,7 +49,14 @@ export default function SegmentedToggle<T extends string>({
      }${fullWidth ? " w-full" : ""}`}
      role="group"
      aria-label={ariaLabel}
+      aria-describedby={title ? hintId : undefined}
+      title={label == null ? title : undefined}
    >
+      {title && (
+        <span id={hintId} hidden>
+          {title}
+        </span>
+      )}
      {options.map((o) => (
        <button
          key={o.value}
@@ -201,6 +201,14 @@ describe("backend ids have their names in both languages", () => {
    it(`${lang}: every audit and quota action`, () => {
      expect(auditActions.filter((a) => !idsUnder(keys, "auditActions").has(a))).toEqual([]);
      expect(quotaActions.filter((a) => !idsUnder(keys, "quotaActions").has(a))).toEqual([]);
+      // …and no name for an action the backend no longer has (the unused-key contract leaves
+      // these two namespaces to this check).
+      expect([...idsUnder(keys, "auditActions")].filter((a) => !auditActions.includes(a))).toEqual(
+        [],
+      );
+      expect([...idsUnder(keys, "quotaActions")].filter((a) => !quotaActions.includes(a))).toEqual(
+        [],
+      );
    });

    it(`${lang}: every download failure-catalog entry`, () => {
@@ -8,7 +8,6 @@
  "saveForLater": "Save for later",
  "unhide": "Unhide",
  "hide": "Hide",
-  "onlyThisChannel": "Only this channel",
  "resetState": "Reset — clear watch progress/status",
  "thisChannel": "This channel",
  "continueTitle": "Continue where you left off",
@@ -1,15 +1,11 @@
 {
  "title": "Edit “{{name}}”",
  "playPause": "Play / pause",
-  "setIn": "Set start",
-  "setOut": "Set end",
  "in": "Start",
  "out": "End",
-  "selected": "Selection",
  "cropOff": "Add crop",
  "cropOn": "Cropping",
  "cropReencode": "Cropping always re-encodes (frame-accurate).",
-  "split": "Split into",
  "accurate": {
    "label": "Precise cut",
    "hint": "Frame-accurate. Re-encodes the clip."
@@ -8,7 +8,6 @@
  "saveForLater": "Mentés későbbre",
  "unhide": "Megjelenítés",
  "hide": "Elrejtés",
-  "onlyThisChannel": "Csak ez a csatorna",
  "resetState": "Alaphelyzet — nézési előzmény/státusz törlése",
  "thisChannel": "Ez a csatorna",
  "continueTitle": "Folytatás ott, ahol abbahagytad",
@@ -1,15 +1,11 @@
 {
  "title": "Szerkesztés: „{{name}}”",
  "playPause": "Lejátszás / szünet",
-  "setIn": "Kezdet itt",
-  "setOut": "Vég itt",
  "in": "Kezdet",
  "out": "Vég",
-  "selected": "Kijelölés",
  "cropOff": "Vágókeret",
  "cropOn": "Vágókeret bekapcsolva",
  "cropReencode": "A vágókeret mindig újrakódol (frame-pontos).",
-  "split": "Feldarabolás",
  "accurate": {
    "label": "Pontos vágás",
    "hint": "Frame-pontos. Újrakódolja a klipet."
@@ -9,11 +9,21 @@ import { describe, expect, it } from "vitest";
 // for nobody, and each one making "is this key live?" a grep instead of a fact.
 //
 // A key counts as used when the source (tests excluded — a test naming a key does not show it to
-// anyone) holds it as a whole string literal, or holds a string that ends in `.` right before an
-// interpolation or a concatenation — a DYNAMIC prefix like `plex.sort.${k}` — which then covers every
-// key under it. Plural forms count through their base key. A key read in a way this cannot see goes
-// in ALLOWED with the reason, rather than the check being loosened for everyone.
-const ALLOWED: Record<string, string> = {};
+// anyone) holds it as a whole string literal, or matches the shape of a DYNAMIC key — a template
+// or concatenation that opens with a key head, each interpolation any segment: `plex.sort.${k}`
+// covers `plex.sort.*`, `editor.${m}.hint` only `editor.*.hint`. A shape that is nothing but the
+// namespace and one interpolation (`card.${status}`) would cover the whole file — it hid five dead
+// keys — so it covers nothing; a key it reads that nothing else names is listed below. Plural forms
+// count through their base key. A key read in a way this cannot see goes in ALLOWED with the reason,
+// rather than the check being loosened for everyone.
+const LOG_FAILURE = "AdminLogs reads `adminLogs.${failure}`, a word its query hook returns";
+const ALLOWED: Record<string, string> = {
+  "adminLogs.olderFailed": LOG_FAILURE,
+  "adminLogs.stale": LOG_FAILURE,
+  "adminLogs.countsFailed": LOG_FAILURE,
+};
+// Namespaces that are one backend enum each, and held key-for-value to it by backendIds.contract.
+const BACKEND_ENUMS = ["auditActions.", "quotaActions."];

 const SRC = fileURLToPath(new URL("../", import.meta.url));

@@ -42,16 +52,45 @@ const keys = readdirSync(locales).flatMap((f) =>
 );
 const code = sources(SRC).join("\n");
 const literals = new Set([...code.matchAll(/["'`]([\w.-]+)["'`]/g)].map((m) => m[1]!));
-const prefixes = [...code.matchAll(/["'`]([\w.]+\.)(?:\$\{|["'`]\s*\+)/g)].map((m) => m[1]!);
+// Each dynamic key as a SHAPE, every interpolation a `*`: `plex.sort.*`, `editor.*.hint`,
+// `config.choices.*.*` — from a template literal that opens with a key head, or a head concatenated.
+const shapes = [
+  ...[...code.matchAll(/`([\w.]+\.(?:\$\{[^}`]*\}|[\w.-])*)`/g)].map((m) => m[1]!),
+  ...[...code.matchAll(/["'`]([\w.]+\.)["'`]\s*\+/g)].map((m) => `${m[1]!}\${}`),
+]
+  .filter((s) => s.includes("${"))
+  .map((s) => s.replace(/\$\{[^}]*\}/g, "*"));
+// A shape that is one namespace and one `*` covers nothing (see above).
+const namespaceWide = (shape: string) => /^[\w-]+\.\*$/.test(shape);
+const patterns = shapes
+  .filter((s) => !namespaceWide(s))
+  .map(
+    (s) =>
+      new RegExp(
+        `^${s
+          .split("*")
+          .map((part) => part.replace(/[.$]/g, "\\$&"))
+          .join("[\\w.-]+")}$`,
+      ),
+  );
 const base = (k: string) => k.replace(/_(zero|one|two|few|many|other)$/, "");
 const used = (k: string) =>
-  literals.has(k) || literals.has(base(k)) || prefixes.some((p) => k.startsWith(p));
+  literals.has(k) ||
+  literals.has(base(k)) ||
+  patterns.some((p) => p.test(k) || p.test(base(k))) ||
+  BACKEND_ENUMS.some((ns) => k.startsWith(ns));

 describe("i18n keys", () => {
  it("finds keys and code to check them against", () => {
    expect(keys.length).toBeGreaterThan(1000);
    expect(literals.has("home.hero.reroll")).toBe(true);
-    expect(prefixes).toContain("plex.sort.");
+    expect(used("plex.sort.newest")).toBe(true); // `plex.sort.${k}`
+    expect(shapes).toContain("editor.*.hint"); // `editor.${m}.hint`
+    expect(used("editor.accurate.hint")).toBe(true);
+    expect(used("editor.accurate.nope")).toBe(false);
+    // A bare namespace head covers nothing — the hole that hid five dead keys.
+    expect(shapes).toContain("card.*");
+    expect(used("card.anythingAtAll")).toBe(false);
  });

  it("are all read somewhere in the app", () => {