feat(frontend): KeyboardCheatsheet overlay

2026-06-20 12:18:08 -06:00
parent 67d5c13939
commit d44aa1de3f
3 changed files with 395 additions and 0 deletions
@@ -0,0 +1,122 @@
+import { useEffect } from "react";
+import { Keyboard } from "lucide-react";
+import { Dialog, DialogContent } from "@/components/ui/dialog";
+
+type KeyboardCheatsheetProps = {
+  open: boolean;
+  onClose: () => void;
+};
+
+/**
+ * Shortcut rows. Each row may have multiple key chips (e.g. "j" and
+ * "↓" both navigate to the next claim) so the `keys` array renders one
+ * `<kbd>` per entry. The order here is the order rendered top→bottom
+ * and is the project's canonical "drawer shortcuts" reference.
+ */
+const SHORTCUTS = [
+  { keys: ["j", "↓"], description: "Next claim" },
+  { keys: ["k", "↑"], description: "Previous claim" },
+  { keys: ["Esc"], description: "Close drawer" },
+  { keys: ["?"], description: "Toggle this help" },
+] as const;
+
+/**
+ * Keyboard help overlay (SP4).
+ *
+ * Centered modal-style overlay (per spec: "centered modal-style
+ * overlay") built on the project's `Dialog` primitive — the only
+ * modal primitive in the codebase. It reuses Radix's focus
+ * management, ESC-to-close, and overlay-click-to-dismiss for free;
+ * the dialog's `onOpenChange(false)` is wired straight to the
+ * consumer's `onClose`.
+ *
+ * Dismissal rules (per spec §3.7):
+ *
+ *  1. Overlay click       → Radix fires `onOpenChange(false)`.
+ *  2. Escape key          → Radix fires `onOpenChange(false)`.
+ *  3. Any other key       → The window-level `keydown` listener below
+ *                           fires `onClose` directly.
+ *
+ * The `?` key is intentionally NOT a dismiss trigger: it's the
+ * toggle key the *parent* owns. The parent flips `open` to false
+ * (and back to true, if it's a toggle) without the cheatsheet
+ * pre-empting it — otherwise the "press ? to toggle" gesture would
+ * silently no-op on the close half of the cycle.
+ *
+ * `aria-describedby={undefined}` suppresses the Radix warning about
+ * a missing description; the cheatsheet's content (key list + helper
+ * text) is its own description and there's no separate description
+ * element worth pointing at.
+ */
+export function KeyboardCheatsheet({ open, onClose }: KeyboardCheatsheetProps) {
+  // Dismiss on any key while open (except `?`, which the parent owns).
+  // The listener is only attached when `open` is true — a closed
+  // cheatsheet shouldn't be intercepting keystrokes for the rest of
+  // the app.
+  useEffect(() => {
+    if (!open) return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === "?") return;
+      onClose();
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, [open, onClose]);
+
+  return (
+    <Dialog
+      open={open}
+      onOpenChange={(o) => {
+        // Radix fires `false` on overlay click, Escape, and the
+        // dialog's own close button. Forward all three as a single
+        // `onClose` to the parent.
+        if (!o) onClose();
+      }}
+    >
+      <DialogContent
+        // Centered modal (DialogContent's default positioning is
+        // `left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2`).
+        // We narrow it to max-w-md and apply the modern palette so
+        // it sits on the same surface as the rest of SP4.
+        className="max-w-md bg-[color:var(--m-surface)] text-[color:var(--m-ink-primary)] border border-[color:var(--m-border-heavy)]/20"
+        aria-describedby={undefined}
+        data-testid="keyboard-cheatsheet"
+      >
+        <header className="flex items-center gap-2 mb-3">
+          <Keyboard
+            className="h-4 w-4 text-[color:var(--m-ink-secondary)]"
+            strokeWidth={1.75}
+            aria-hidden
+          />
+          <h2 className="text-[10.5px] font-semibold uppercase tracking-[0.18em] text-[color:var(--m-ink-tertiary)]">
+            Keyboard
+          </h2>
+        </header>
+
+        <ul className="flex flex-col gap-2.5">
+          {SHORTCUTS.map((s) => (
+            <li
+              key={s.description}
+              className="flex items-center justify-between gap-3 text-sm"
+            >
+              <div className="flex items-center gap-1.5">
+                {s.keys.map((k) => (
+                  <kbd key={k} className="kbd">
+                    {k}
+                  </kbd>
+                ))}
+              </div>
+              <span className="text-[color:var(--m-ink-secondary)]">
+                {s.description}
+              </span>
+            </li>
+          ))}
+        </ul>
+
+        <p className="mt-4 text-xs text-[color:var(--m-ink-tertiary)]">
+          Press any other key to dismiss.
+        </p>
+      </DialogContent>
+    </Dialog>
+  );
+}