feat(#479): add global keyboard shortcut registry with help overlay (#536)

- Add ShortcutRegistryProvider context (src/context/ShortcutRegistry.tsx):
  - Central registry where any component can register/unregister shortcuts
  - Global keydown listener lives here — single source of truth
  - useRegisterShortcuts() hook: auto-registers on mount, cleans up on unmount
  - useShortcutRegistry() for reading the full list of registered shortcuts
  - Shortcuts support grouping via 'group' field for overlay sections

- Rewrite useKeyboardShortcuts to register all built-in shortcuts via registry:
  - ? -> open/close help overlay
  - Esc -> close overlay / cancel G-chord
  - N -> create new invoice (on /dashboard only)
  - G then D/S/L/N -> navigate to Dashboard/Search/Leaderboard/New Invoice
  - Uses refs for chord state so handlers stay stable

- Rewrite KeyboardShortcutsModal to pull from registry dynamically:
  - Groups shortcuts by 'group' field (General, Navigation, Invoices, etc.)
  - Shows total registered shortcut count in header
  - Renders multi-key chords with 'then' separator between keys
  - Scrollable with max-height so long lists don't overflow viewport
  - New entries appear automatically when components register shortcuts

- Mount ShortcutRegistryProvider in root layout wrapping all children

Author: Mirabliss

src/app/layout.tsx

@@ -23,6 +23,7 @@ import QueryProvider from "@/contexts/QueryProvider";
 import LanguageSwitcher from "@/components/LanguageSwitcher";
 import { UserPreferencesProvider } from "@/context/UserPreferencesContext";
 import { FiatRateProvider } from "@/hooks/useFiatRate";
+import { ShortcutRegistryProvider } from "@/context/ShortcutRegistry";
 
 const themeBootstrap = `
 (function () {
@@ -184,6 +185,7 @@ export default function RootLayout({
                   <ToastProvider>
                     <UserPreferencesProvider>
                       <FiatRateProvider>
+                        <ShortcutRegistryProvider>
                         <Navbar />
                         <SimulationBanner />
                         <UpgradeBanner />
@@ -201,6 +203,7 @@ export default function RootLayout({
                         <RecipientOnboarding />
                         <InstallBanner />
                         <ToastContainer />
+                        </ShortcutRegistryProvider>
                       </FiatRateProvider>
                     </UserPreferencesProvider>
                   </ToastProvider>

src/components/KeyboardShortcutsModal.tsx

@@ -1,35 +1,72 @@
 "use client";
 
+import { useMemo } from "react";
 import FocusTrap from "@/components/FocusTrap";
+import { useShortcutRegistry, type ShortcutDefinition } from "@/context/ShortcutRegistry";
 
-interface ShortcutEntry {
-  keys: string[];
-  description: string;
+interface Props {
+  onClose: () => void;
 }
 
-const SHORTCUTS: ShortcutEntry[] = [
-  { keys: ["?"], description: "Open keyboard shortcuts reference" },
-  { keys: ["⌘", "K"], description: "Open command palette" },
-  { keys: ["N"], description: "Create new invoice (on dashboard)" },
-  { keys: ["Esc"], description: "Close modal / dismiss overlay" },
-  { keys: ["G", "D"], description: "Navigate to Dashboard" },
-  { keys: ["G", "S"], description: "Navigate to Search" },
-  { keys: ["G", "L"], description: "Navigate to Leaderboard" },
-];
+// ── Helpers ───────────────────────────────────────────────────────────────────
 
-interface Props {
-  onClose: () => void;
+/**
+ * Group shortcuts by their `group` field.
+ * Groups are returned in the order they first appear in the registry,
+ * with "General" always first when present.
+ */
+function groupShortcuts(
+  shortcuts: ShortcutDefinition[],
+): Array<{ group: string; entries: ShortcutDefinition[] }> {
+  const map = new Map<string, ShortcutDefinition[]>();
+
+  // Always seed General first so it stays at the top
+  map.set("General", []);
+
+  for (const s of shortcuts) {
+    // Hide internal chord-activation entries from the overlay
+    if (s.id === "global:g-chord") continue;
+
+    const group = s.group ?? "General";
+    if (!map.has(group)) map.set(group, []);
+    map.get(group)!.push(s);
+  }
+
+  // Remove empty groups
+  return Array.from(map.entries())
+    .filter(([, entries]) => entries.length > 0)
+    .map(([group, entries]) => ({ group, entries }));
+}
+
+// ── Kbd chip ──────────────────────────────────────────────────────────────────
+
+function KbdKey({ label }: { label: string }) {
+  return (
+    <kbd className="inline-flex items-center justify-center px-1.5 py-0.5 min-w-[1.5rem] rounded-md text-xs font-mono font-semibold text-gray-200 bg-gray-700 border border-gray-600 shadow-sm shadow-black/30">
+      {label}
+    </kbd>
+  );
 }
 
+// ── Modal ─────────────────────────────────────────────────────────────────────
+
 /**
  * KeyboardShortcutsModal
  *
- * A full-screen overlay that lists all global keyboard shortcuts.
- * Triggered by pressing `?` outside text inputs, or clicking the `?`
- * icon in the header. Closed by pressing Escape (via FocusTrap) or
+ * A help overlay that lists **all shortcuts registered via ShortcutRegistry**.
+ * Shortcuts are grouped by their `group` field (defaults to "General").
+ *
+ * Triggered by pressing `?` outside text inputs, or clicking the `?` icon in
+ * the header. Closed by pressing Escape (handled in useKeyboardShortcuts) or
  * clicking the backdrop / close button.
+ *
+ * Components register shortcuts with `useRegisterShortcuts` — the overlay
+ * automatically reflects additions and removals without any manual wiring.
  */
 export default function KeyboardShortcutsModal({ onClose }: Props) {
+  const { shortcuts } = useShortcutRegistry();
+  const grouped = useMemo(() => groupShortcuts(shortcuts), [shortcuts]);
+
   return (
     <div
       className="fixed inset-0 z-50 flex items-center justify-center bg-black/70 backdrop-blur-sm px-4"
@@ -40,17 +77,17 @@ export default function KeyboardShortcutsModal({ onClose }: Props) {
     >
       <FocusTrap onClose={onClose}>
         <div
-          className="relative w-full max-w-lg rounded-2xl border border-gray-700/60 bg-gray-900/95 shadow-2xl shadow-black/60 p-0 overflow-hidden"
+          className="relative w-full max-w-lg rounded-2xl border border-gray-700/60 bg-gray-900/95 shadow-2xl shadow-black/60 overflow-hidden max-h-[85vh] flex flex-col"
           onClick={(e) => e.stopPropagation()}
         >
           {/* Gradient accent strip */}
-          <div className="h-1 w-full bg-gradient-to-r from-indigo-500 via-purple-500 to-pink-500" />
+          <div className="h-1 w-full bg-gradient-to-r from-indigo-500 via-purple-500 to-pink-500 shrink-0" />
 
-          <div className="px-6 py-5">
+          <div className="px-6 pt-5 pb-4 overflow-y-auto">
             {/* Header */}
             <div className="flex items-center justify-between mb-5">
               <div className="flex items-center gap-2.5">
-                <span className="inline-flex items-center justify-center w-8 h-8 rounded-lg bg-indigo-500/20 border border-indigo-500/30">
+                <span className="inline-flex items-center justify-center w-8 h-8 rounded-lg bg-indigo-500/20 border border-indigo-500/30 shrink-0">
                   <svg
                     xmlns="http://www.w3.org/2000/svg"
                     className="h-4 w-4 text-indigo-400"
@@ -60,26 +97,28 @@ export default function KeyboardShortcutsModal({ onClose }: Props) {
                     strokeWidth={2}
                     aria-hidden="true"
                   >
-                    <path
-                      strokeLinecap="round"
-                      strokeLinejoin="round"
-                      d="M11 4a1 1 0 011-1h.01a1 1 0 110 2H12a1 1 0 01-1-1zm0 4a1 1 0 011-1h.01a1 1 0 110 2H12a1 1 0 01-1-1zM5 8a1 1 0 011-1h12a1 1 0 110 2H6a1 1 0 01-1-1zM5 12a1 1 0 011-1h12a1 1 0 110 2H6a1 1 0 01-1-1zm0 4a1 1 0 011-1h12a1 1 0 110 2H6a1 1 0 01-1-1z"
-                    />
+                    <rect x="2" y="4" width="20" height="16" rx="2" />
+                    <path d="M6 8h.01M10 8h.01M14 8h.01M18 8h.01M6 12h.01M10 12h.01M14 12h4M6 16h12" />
                   </svg>
                 </span>
-                <h2
-                  id="kbd-shortcuts-title"
-                  className="text-base font-semibold text-gray-100 tracking-tight"
-                >
-                  Keyboard Shortcuts
-                </h2>
+                <div>
+                  <h2
+                    id="kbd-shortcuts-title"
+                    className="text-base font-semibold text-gray-100 tracking-tight"
+                  >
+                    Keyboard Shortcuts
+                  </h2>
+                  <p className="text-xs text-gray-500 mt-0.5">
+                    {shortcuts.length} shortcut{shortcuts.length !== 1 ? "s" : ""} registered
+                  </p>
+                </div>
               </div>
 
               <button
                 id="kbd-shortcuts-close-btn"
                 onClick={onClose}
                 aria-label="Close keyboard shortcuts"
-                className="p-1.5 rounded-lg text-gray-400 hover:text-gray-100 hover:bg-gray-700/60 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500"
+                className="p-1.5 rounded-lg text-gray-400 hover:text-gray-100 hover:bg-gray-700/60 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-indigo-500 shrink-0"
               >
                 <svg
                   xmlns="http://www.w3.org/2000/svg"
@@ -90,60 +129,66 @@ export default function KeyboardShortcutsModal({ onClose }: Props) {
                   strokeWidth={2}
                   aria-hidden="true"
                 >
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    d="M6 18L18 6M6 6l12 12"
-                  />
+                  <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
                 </svg>
               </button>
             </div>
 
-            {/* Shortcut table */}
-            <table
-              className="w-full text-sm border-separate"
-              style={{ borderSpacing: "0 4px" }}
-              aria-label="Keyboard shortcuts list"
-            >
-              <thead>
-                <tr>
-                  <th className="text-left text-xs font-medium text-gray-500 uppercase tracking-wider pb-2 pl-3">
-                    Shortcut
-                  </th>
-                  <th className="text-left text-xs font-medium text-gray-500 uppercase tracking-wider pb-2">
-                    Action
-                  </th>
-                </tr>
-              </thead>
-              <tbody>
-                {SHORTCUTS.map((entry) => (
-                  <tr
-                    key={entry.description}
-                    className="group"
-                  >
-                    <td className="pl-3 pr-4 py-2.5 rounded-l-lg bg-gray-800/50 group-hover:bg-gray-800 transition-colors w-36">
-                      <span className="flex items-center gap-1">
-                        {entry.keys.map((k) => (
-                          <kbd
-                            key={k}
-                            className="inline-flex items-center justify-center px-1.5 py-0.5 min-w-[1.5rem] rounded-md text-xs font-mono font-semibold text-gray-200 bg-gray-700 border border-gray-600 shadow-sm shadow-black/30"
-                          >
-                            {k}
-                          </kbd>
+            {/* Grouped shortcut sections */}
+            {grouped.length === 0 ? (
+              <p className="text-sm text-gray-500 text-center py-4">
+                No shortcuts registered.
+              </p>
+            ) : (
+              <div className="flex flex-col gap-5">
+                {grouped.map(({ group, entries }) => (
+                  <section key={group} aria-labelledby={`kbd-group-${group}`}>
+                    <h3
+                      id={`kbd-group-${group}`}
+                      className="text-xs font-semibold text-gray-500 uppercase tracking-wider mb-2 px-1"
+                    >
+                      {group}
+                    </h3>
+
+                    <table
+                      className="w-full text-sm border-separate"
+                      style={{ borderSpacing: "0 3px" }}
+                      aria-label={`${group} keyboard shortcuts`}
+                    >
+                      <tbody>
+                        {entries.map((entry) => (
+                          <tr key={entry.id} className="group">
+                            <td className="pl-3 pr-4 py-2 rounded-l-lg bg-gray-800/50 group-hover:bg-gray-800 transition-colors w-40">
+                              <span className="flex items-center gap-1 flex-wrap">
+                                {entry.keys.map((k, i) => (
+                                  <span key={`${k}-${i}`} className="flex items-center gap-1">
+                                    {i > 0 && (
+                                      <span className="text-[10px] text-gray-600 mx-0.5">then</span>
+                                    )}
+                                    <KbdKey label={k} />
+                                  </span>
+                                ))}
+                              </span>
+                            </td>
+                            <td className="pr-3 py-2 rounded-r-lg bg-gray-800/50 group-hover:bg-gray-800 transition-colors text-gray-300 text-sm">
+                              {entry.description}
+                            </td>
+                          </tr>
                         ))}
-                      </span>
-                    </td>
-                    <td className="pr-3 py-2.5 rounded-r-lg bg-gray-800/50 group-hover:bg-gray-800 transition-colors text-gray-300">
-                      {entry.description}
-                    </td>
-                  </tr>
+                      </tbody>
+                    </table>
+                  </section>
                 ))}
-              </tbody>
-            </table>
+              </div>
+            )}
 
             {/* Footer hint */}
             <p className="mt-5 text-xs text-gray-500 text-center">
-              Shortcuts are disabled while typing in text fields.
+              Shortcuts are disabled while typing in text fields.{" "}
+              <kbd className="rounded bg-gray-700 border border-gray-600 px-1 py-0.5 text-[10px] font-mono text-gray-300">
+                Esc
+              </kbd>{" "}
+              to close.
             </p>
           </div>
         </div>