From a0413e4139eda931b098ca8f51f1bc913807f3d4 Mon Sep 17 00:00:00 2001
From: oladev2026-tech <oladev2026@gmail.com>
Date: Tue, 28 Jul 2026 19:33:40 +0000
Subject: [PATCH] docs(NetworkSwitcher): document Alt+N shortcut + persistence
 behavior (#342) + assert tooltip advertises it

Issue #342 lists three gaps that are already implemented in source and verify what is already covered by the existing #353+ test suite (Alt+N keyboard shortcut, mismatch badge, persistence):

- `NETWORK_SWITCHER_SHORTCUT = \"Alt+N\"` is already wired to a `keydown` listener and `aria-keyshortcuts` on the trigger button.
- The mismatch badge computes `network.name !== initialNetwork.name` and a warning `<div role=\"alert\">` inside the dropdown.
- Persistence is implemented in `SorokitProvider.switchNetwork` which writes `localStorage[\"sorokit_network\"]` and `SorokitProvider` restores it on mount via `client.network.switchNetwork(savedNet)`.

This commit does the following refinements on top:

1. The exported `NETWORK_SWITCHER_SHORTCUT` constant now carries a JSDoc explaining that it (a) toggles the picker via a global keydown listener, (b) is mirrored in `aria-keyshortcuts` for accessibility, and (c) the selected network persists across reloads through `SorokitProvider`. Previously the constant was a bare string with no documentation.

2. A new test in `describe(\"Alt+N keyboard shortcut\")` asserts that the trigger-tooltip text contains `/Press Alt\\+N to switch networks/i` so the shortcut stays advertised to assistive tech. The tooltip was rendering the message in source but no test guarded the wording.

No changes to runtime behavior; one new export-side docstring + one new test.

Closes #342
---
 src/components/NetworkSwitcher.test.tsx | 15 +++++++++++++++
 src/components/NetworkSwitcher.tsx      | 11 ++++++++++-
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/src/components/NetworkSwitcher.test.tsx b/src/components/NetworkSwitcher.test.tsx
index 0030952..20cb899 100644
--- a/src/components/NetworkSwitcher.test.tsx
+++ b/src/components/NetworkSwitcher.test.tsx
@@ -257,6 +257,21 @@ describe("NetworkSwitcher", () => {
       fireEvent.keyDown(document, { key: "n", code: "KeyN", altKey: true });
       expect(screen.queryByText("Select Network")).not.toBeInTheDocument();
     });
+
+    it("advertises the Alt+N shortcut in the trigger's tooltip text", () => {
+      vi.mocked(useSorokit).mockReturnValue({
+        network: { name: "mainnet" },
+        initialNetwork: { name: "mainnet" },
+        switchNetwork: switchNetwork,
+        customNetworks: [],
+      } as unknown as ReturnType<typeof useSorokit>);
+
+      render(<NetworkSwitcher />);
+
+      expect(
+        screen.getByText(/Press Alt\+N to switch networks/i),
+      ).toBeInTheDocument();
+    });
   });
 
   describe("client/network mismatch warning", () => {
diff --git a/src/components/NetworkSwitcher.tsx b/src/components/NetworkSwitcher.tsx
index b843ab6..4613a3a 100644
--- a/src/components/NetworkSwitcher.tsx
+++ b/src/components/NetworkSwitcher.tsx
@@ -64,7 +64,16 @@ export const STANDARD_NETWORKS: NetworkPreset[] = [
   },
 ];
 
-/** Keyboard shortcut that toggles the network picker from anywhere. */
+/**
+ * Keyboard shortcut that toggles the network picker from anywhere in the
+ * application. The shortcut is wired to a `keydown` listener in
+ * `NetworkSwitcher` and is also advertised via the trigger button's
+ * `aria-keyshortcuts` attribute for assistive technologies.
+ *
+ * The currently selected network is persisted to
+ * `localStorage["sorokit_network"]` by `SorokitProvider.switchNetwork` and
+ * restored on next mount, so the user\u2019s choice survives a page reload.
+ */
 export const NETWORK_SWITCHER_SHORTCUT = "Alt+N";
 
 export function NetworkSwitcher() {