merge: ui/keyboard-acks-remits — j/k row nav + ? cheatsheet on Acks and Remittances

src/hooks/useRowKeyboard.test.ts

@@ -0,0 +1,226 @@
+// @vitest-environment happy-dom
+// Mirror the IS_REACT_ACT_ENVIRONMENT setup from `useDrawerKeyboard.test.ts`
+// so React doesn't log act() warnings about the createRoot render/unmount.
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { useRowKeyboard } from "./useRowKeyboard";
+
+/**
+ * Minimal renderHook shim — same shape as the project's other hook tests.
+ * `useRowKeyboard` returns `void` (its side effect is the window listener),
+ * so the shim doesn't surface a `result`; we only need `unmount` for
+ * cleanup verification.
+ */
+function renderHook(setup: () => void): { unmount: () => void } {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+
+  function Probe() {
+    setup();
+    return null;
+  }
+
+  const root: Root = createRoot(container);
+  act(() => {
+    root.render(React.createElement(Probe));
+  });
+
+  return {
+    unmount: () => {
+      act(() => root.unmount());
+      container.remove();
+    },
+  };
+}
+
+/**
+ * Dispatch a synthetic keydown. By default the target is `window`
+ * (which is what a real keypress bubbles to). Pass an explicit target
+ * for the "input has focus" test. `bubbles: true` + `cancelable: true`
+ * so the event behaves like a real keydown — the handler calls
+ * `preventDefault` on matched keys.
+ */
+function pressKey(
+  key: string,
+  target: EventTarget = window,
+  init: KeyboardEventInit = {}
+): void {
+  const event = new KeyboardEvent("keydown", {
+    key,
+    bubbles: true,
+    cancelable: true,
+    ...init,
+  });
+  target.dispatchEvent(event);
+}
+
+describe("useRowKeyboard", () => {
+  // vi.fn() with no args in vitest 4 is typed `Mock<Procedure |
+  // Constructable>`, which carries a constructor signature and won't
+  // assign to `() => void`. Constraining the generic to `vi.fn<() => void>()`
+  // gives a plain function-typed mock that flows directly into the hook's
+  // callback params.
+  let onNext: () => void;
+  let onPrev: () => void;
+  let onClose: () => void;
+  let onToggleHelp: () => void;
+
+  beforeEach(() => {
+    onNext = vi.fn<() => void>();
+    onPrev = vi.fn<() => void>();
+    onClose = vi.fn<() => void>();
+    onToggleHelp = vi.fn<() => void>();
+  });
+
+  it("fires onNext for j and ArrowDown", () => {
+    const { unmount } = renderHook(() =>
+      useRowKeyboard({ enabled: true, onNext, onPrev, onClose, onToggleHelp })
+    );
+
+    pressKey("j");
+    expect(onNext).toHaveBeenCalledTimes(1);
+    expect(onPrev).not.toHaveBeenCalled();
+
+    pressKey("ArrowDown");
+    expect(onNext).toHaveBeenCalledTimes(2);
+    expect(onPrev).not.toHaveBeenCalled();
+
+    unmount();
+  });
+
+  it("fires onPrev for k and ArrowUp", () => {
+    const { unmount } = renderHook(() =>
+      useRowKeyboard({ enabled: true, onNext, onPrev, onClose, onToggleHelp })
+    );
+
+    pressKey("k");
+    expect(onPrev).toHaveBeenCalledTimes(1);
+    expect(onNext).not.toHaveBeenCalled();
+
+    pressKey("ArrowUp");
+    expect(onPrev).toHaveBeenCalledTimes(2);
+    expect(onNext).not.toHaveBeenCalled();
+
+    unmount();
+  });
+
+  it("fires onClose when Escape is pressed", () => {
+    const { unmount } = renderHook(() =>
+      useRowKeyboard({ enabled: true, onNext, onPrev, onClose, onToggleHelp })
+    );
+
+    pressKey("Escape");
+    expect(onClose).toHaveBeenCalledTimes(1);
+    expect(onNext).not.toHaveBeenCalled();
+    expect(onPrev).not.toHaveBeenCalled();
+    expect(onToggleHelp).not.toHaveBeenCalled();
+
+    unmount();
+  });
+
+  it('fires onToggleHelp when "?" is pressed', () => {
+    const { unmount } = renderHook(() =>
+      useRowKeyboard({ enabled: true, onNext, onPrev, onClose, onToggleHelp })
+    );
+
+    pressKey("?");
+    expect(onToggleHelp).toHaveBeenCalledTimes(1);
+    expect(onNext).not.toHaveBeenCalled();
+    expect(onPrev).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+
+    unmount();
+  });
+
+  it("ignores keys when an input has focus", () => {
+    const { unmount } = renderHook(() =>
+      useRowKeyboard({ enabled: true, onNext, onPrev, onClose, onToggleHelp })
+    );
+
+    // Mount a real input and focus it. A real keystroke while the input
+    // is focused would have `event.target === input` and bubble to
+    // window — we simulate that by dispatching the keydown on the input
+    // itself with `bubbles: true`.
+    const input = document.createElement("input");
+    document.body.appendChild(input);
+    input.focus();
+    expect(document.activeElement).toBe(input);
+
+    pressKey("j", input);
+    pressKey("Escape", input);
+    pressKey("?", input);
+
+    expect(onNext).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+    expect(onToggleHelp).not.toHaveBeenCalled();
+
+    input.remove();
+    unmount();
+  });
+
+  it("ignores keys when a textarea has focus", () => {
+    // Same protection as <input>: rich text fields must not be hijacked.
+    // Mirrors the contenteditable note in the hook's JSDoc.
+    const { unmount } = renderHook(() =>
+      useRowKeyboard({ enabled: true, onNext, onPrev, onClose, onToggleHelp })
+    );
+
+    const textarea = document.createElement("textarea");
+    document.body.appendChild(textarea);
+    textarea.focus();
+    expect(document.activeElement).toBe(textarea);
+
+    pressKey("j", textarea);
+    pressKey("k", textarea);
+    expect(onNext).not.toHaveBeenCalled();
+    expect(onPrev).not.toHaveBeenCalled();
+
+    textarea.remove();
+    unmount();
+  });
+
+  it("does nothing when enabled is false", () => {
+    // The `enabled` flag is the recommended way to yield to an open
+    // overlay (e.g. the cheatsheet). When false, the listener must not
+    // attach at all — no keydown should reach our handlers.
+    const { unmount } = renderHook(() =>
+      useRowKeyboard({ enabled: false, onNext, onPrev, onClose, onToggleHelp })
+    );
+
+    pressKey("j");
+    pressKey("Escape");
+    pressKey("?");
+
+    expect(onNext).not.toHaveBeenCalled();
+    expect(onPrev).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+    expect(onToggleHelp).not.toHaveBeenCalled();
+
+    unmount();
+  });
+
+  it("cleans up the keydown listener on unmount", () => {
+    const { unmount } = renderHook(() =>
+      useRowKeyboard({ enabled: true, onNext, onPrev, onClose, onToggleHelp })
+    );
+
+    pressKey("j");
+    expect(onNext).toHaveBeenCalledTimes(1);
+
+    unmount();
+
+    // After unmount the effect's cleanup has removed the listener, so a
+    // follow-up keydown should be a no-op. We dispatch a few different
+    // keys to be thorough.
+    pressKey("j");
+    pressKey("Escape");
+    pressKey("?");
+
+    expect(onNext).toHaveBeenCalledTimes(1);
+    expect(onClose).not.toHaveBeenCalled();
+    expect(onToggleHelp).not.toHaveBeenCalled();
+  });
+});

src/hooks/useRowKeyboard.ts

@@ -0,0 +1,101 @@
+import { useEffect } from "react";
+
+/** Tag names whose descendants can receive free-form text input. */
+const INPUT_TAGS = new Set(["INPUT", "TEXTAREA", "SELECT"]);
+
+/**
+ * Returns true when the keyboard event originated inside a free-form
+ * text field, in which case we should NOT consume j/k/escape/`?` —
+ * the user is typing, not navigating the table.
+ *
+ * - `INPUT` / `TEXTAREA` / `SELECT` are the obvious cases.
+ * - `contenteditable` elements (e.g. rich text editors) are the
+ *   non-obvious one: `target.isContentEditable` is the standard check.
+ *
+ * Lifted from `useDrawerKeyboard` so both hooks agree on the
+ * "is the user typing?" predicate. Keeping it in lock-step matters:
+ * if the predicates drift, a future search box might accidentally
+ * become a navigation surface in one component but not another.
+ */
+function isEditableTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (INPUT_TAGS.has(target.tagName)) return true;
+  return target.isContentEditable;
+}
+
+/**
+ * Wires keyboard shortcuts for a paginated/filterable table whose rows
+ * are keyboard-navigable (j/k to move, ? for help, Esc to close the
+ * help overlay). When `enabled` is true, listens for `keydown` on
+ * `window` and dispatches:
+ *
+ *   j / ArrowDown  →  onNext
+ *   k / ArrowUp    →  onPrev
+ *   Escape         →  onClose
+ *   ?              →  onToggleHelp
+ *
+ * Semantically a sibling of `useDrawerKeyboard`, but tuned for
+ * list-row navigation rather than a modal drawer:
+ *
+ *  - `onNext` / `onPrev` advance/decrement a row index in the
+ *    *list* (the caller decides whether to wrap or clamp; this hook
+ *    doesn't enforce either policy — it just signals "the user wants
+ *    to move").
+ *  - `onClose` closes whatever overlay is currently open on the
+ *    page — typically just the keyboard-cheatsheet. The hook itself
+ *    doesn't own the overlay; it just forwards the key.
+ *  - `onToggleHelp` flips the cheatsheet open/closed. The hook does
+ *    NOT preempt this on `?` — see KeyboardCheatsheet.tsx for the
+ *    matching "skip `?` in the dismiss listener" rule.
+ *
+ * Keys are ignored when an `<input>`, `<textarea>`, `<select>`, or
+ * `contenteditable` element has focus — typing "j" into a search box
+ * must not jump rows. `preventDefault` is called for each matched
+ * key to suppress the browser's default (arrow keys scrolling the
+ * page, Escape closing modals/pausing video, etc.).
+ *
+ * Recommended pairing: pass `enabled: !helpOpen` so j/k nav yields
+ * to the cheatsheet while it's open (the cheatsheet's own dismiss
+ * listener still fires for any keypress, including j/k).
+ */
+export function useRowKeyboard(opts: {
+  enabled: boolean;
+  onNext: () => void;
+  onPrev: () => void;
+  onClose: () => void;
+  onToggleHelp: () => void;
+}): void {
+  const { enabled, onNext, onPrev, onClose, onToggleHelp } = opts;
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handler = (e: KeyboardEvent) => {
+      if (isEditableTarget(e.target)) return;
+
+      switch (e.key) {
+        case "j":
+        case "ArrowDown":
+          e.preventDefault();
+          onNext();
+          break;
+        case "k":
+        case "ArrowUp":
+          e.preventDefault();
+          onPrev();
+          break;
+        case "Escape":
+          e.preventDefault();
+          onClose();
+          break;
+        case "?":
+          e.preventDefault();
+          onToggleHelp();
+          break;
+      }
+    };
+
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, [enabled, onNext, onPrev, onClose, onToggleHelp]);
+}

src/pages/Acks.test.tsx

@@ -51,6 +51,57 @@ async function waitForText(text: string, timeoutMs = 2000): Promise<void> {
   }
 }
 
+/**
+ * Poll a predicate until it holds or we time out. react-query's fetch
+ * resolves asynchronously, and Radix portals content into
+ * `document.body`, so the DOM doesn't reflect new state synchronously
+ * after a keypress — we have to await a tick before asserting.
+ */
+async function settle(
+  predicate: () => boolean,
+  timeoutMs = 2000
+): Promise<void> {
+  const start = Date.now();
+  while (!predicate()) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error("settle: predicate did not hold within timeout");
+    }
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 0));
+    });
+  }
+}
+
+/**
+ * Dispatch a synthetic keydown on `window`. Matches the dispatching
+ * pattern from `useDrawerKeyboard.test.ts` and `Claims.test.tsx` —
+ * `bubbles: true` so the event propagates like a real keypress, and
+ * `cancelable: true` so the hook's `preventDefault` has something to
+ * act on.
+ */
+function pressKey(key: string): void {
+  act(() => {
+    window.dispatchEvent(
+      new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true })
+    );
+  });
+}
+
+/** The row at `idx` (per `data-row-index={idx}` on the row). */
+function rowAt(idx: number): HTMLTableRowElement | null {
+  return document.querySelector(
+    `tbody tr[data-row-index="${idx}"]`
+  ) as HTMLTableRowElement | null;
+}
+
+/** True iff exactly one row carries `data-state="selected"`. */
+function hasExactlyOneSelectedRow(): boolean {
+  const selected = document.querySelectorAll(
+    'tbody tr[data-state="selected"]'
+  );
+  return selected.length === 1;
+}
+
 describe("Acks", () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -87,4 +138,314 @@ describe("Acks", () => {
     expect(document.body.textContent).toContain("b-uuid-1");
     unmount();
   });
+
+  it("test_initial_render_shows_no_selection_highlight", async () => {
+    // Three rows in the fixture so there's plenty to select; the test
+    // asserts the *initial* state has no row marked selected.
+    (api.listAcks as unknown as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [
+        {
+          id: 1,
+          sourceBatchId: "b-1",
+          acceptedCount: 1,
+          rejectedCount: 0,
+          receivedCount: 1,
+          ackCode: "A",
+          parsedAt: "2026-06-20T12:00:00Z",
+        },
+        {
+          id: 2,
+          sourceBatchId: "b-2",
+          acceptedCount: 2,
+          rejectedCount: 0,
+          receivedCount: 2,
+          ackCode: "A",
+          parsedAt: "2026-06-20T12:01:00Z",
+        },
+        {
+          id: 3,
+          sourceBatchId: "b-3",
+          acceptedCount: 3,
+          rejectedCount: 0,
+          receivedCount: 3,
+          ackCode: "A",
+          parsedAt: "2026-06-20T12:02:00Z",
+        },
+      ],
+      total: 3,
+      returned: 3,
+      has_more: false,
+    });
+
+    const { unmount } = renderIntoContainer(React.createElement(Acks));
+    await waitForText("b-3");
+
+    // None of the three rows should be marked selected — the spec
+    // requires the initial render shows no selection highlight.
+    expect(
+      document.querySelectorAll('tbody tr[data-state="selected"]').length
+    ).toBe(0);
+
+    unmount();
+  });
+
+  it("test_pressing_j_increments_selection", async () => {
+    (api.listAcks as unknown as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [
+        {
+          id: 1,
+          sourceBatchId: "b-1",
+          acceptedCount: 1,
+          rejectedCount: 0,
+          receivedCount: 1,
+          ackCode: "A",
+          parsedAt: "2026-06-20T12:00:00Z",
+        },
+        {
+          id: 2,
+          sourceBatchId: "b-2",
+          acceptedCount: 2,
+          rejectedCount: 0,
+          receivedCount: 2,
+          ackCode: "A",
+          parsedAt: "2026-06-20T12:01:00Z",
+        },
+        {
+          id: 3,
+          sourceBatchId: "b-3",
+          acceptedCount: 3,
+          rejectedCount: 0,
+          receivedCount: 3,
+          ackCode: "A",
+          parsedAt: "2026-06-20T12:02:00Z",
+        },
+      ],
+      total: 3,
+      returned: 3,
+      has_more: false,
+    });
+
+    const { unmount } = renderIntoContainer(React.createElement(Acks));
+    await waitForText("b-3");
+
+    // From null, j lands on row 0.
+    pressKey("j");
+    await settle(() => rowAt(0)?.getAttribute("data-state") === "selected");
+    expect(rowAt(0)?.getAttribute("data-state")).toBe("selected");
+    expect(rowAt(1)?.getAttribute("data-state")).not.toBe("selected");
+    expect(rowAt(2)?.getAttribute("data-state")).not.toBe("selected");
+
+    // j again → row 1.
+    pressKey("j");
+    await settle(() => rowAt(1)?.getAttribute("data-state") === "selected");
+    expect(rowAt(1)?.getAttribute("data-state")).toBe("selected");
+    expect(rowAt(0)?.getAttribute("data-state")).not.toBe("selected");
+
+    // j again → row 2.
+    pressKey("j");
+    await settle(() => rowAt(2)?.getAttribute("data-state") === "selected");
+    expect(rowAt(2)?.getAttribute("data-state")).toBe("selected");
+
+    // j from last row wraps to row 0 (per the wrap-or-clamp policy
+    // documented in Acks.tsx).
+    pressKey("j");
+    await settle(() => rowAt(0)?.getAttribute("data-state") === "selected");
+    expect(rowAt(0)?.getAttribute("data-state")).toBe("selected");
+
+    unmount();
+  });
+
+  it("test_pressing_k_decrements_selection_with_wrap", async () => {
+    (api.listAcks as unknown as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [
+        {
+          id: 1,
+          sourceBatchId: "b-1",
+          acceptedCount: 1,
+          rejectedCount: 0,
+          receivedCount: 1,
+          ackCode: "A",
+          parsedAt: "2026-06-20T12:00:00Z",
+        },
+        {
+          id: 2,
+          sourceBatchId: "b-2",
+          acceptedCount: 2,
+          rejectedCount: 0,
+          receivedCount: 2,
+          ackCode: "A",
+          parsedAt: "2026-06-20T12:01:00Z",
+        },
+        {
+          id: 3,
+          sourceBatchId: "b-3",
+          acceptedCount: 3,
+          rejectedCount: 0,
+          receivedCount: 3,
+          ackCode: "A",
+          parsedAt: "2026-06-20T12:02:00Z",
+        },
+      ],
+      total: 3,
+      returned: 3,
+      has_more: false,
+    });
+
+    const { unmount } = renderIntoContainer(React.createElement(Acks));
+    await waitForText("b-3");
+
+    // From null, k jumps to the last row — a one-keystroke "bottom
+    // of list" gesture.
+    pressKey("k");
+    await settle(() => rowAt(2)?.getAttribute("data-state") === "selected");
+    expect(rowAt(2)?.getAttribute("data-state")).toBe("selected");
+
+    // k again → row 1.
+    pressKey("k");
+    await settle(() => rowAt(1)?.getAttribute("data-state") === "selected");
+    expect(rowAt(1)?.getAttribute("data-state")).toBe("selected");
+    expect(rowAt(2)?.getAttribute("data-state")).not.toBe("selected");
+
+    // k twice more lands on row 0.
+    pressKey("k");
+    await settle(() => rowAt(0)?.getAttribute("data-state") === "selected");
+    expect(rowAt(0)?.getAttribute("data-state")).toBe("selected");
+
+    // k from row 0 wraps to row 2 (last).
+    pressKey("k");
+    await settle(() => rowAt(2)?.getAttribute("data-state") === "selected");
+    expect(rowAt(2)?.getAttribute("data-state")).toBe("selected");
+
+    unmount();
+  });
+
+  it("test_question_mark_toggles_cheatsheet_and_escape_closes", async () => {
+    (api.listAcks as unknown as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [
+        {
+          id: 1,
+          sourceBatchId: "b-1",
+          acceptedCount: 1,
+          rejectedCount: 0,
+          receivedCount: 1,
+          ackCode: "A",
+          parsedAt: "2026-06-20T12:00:00Z",
+        },
+      ],
+      total: 1,
+      returned: 1,
+      has_more: false,
+    });
+
+    const { unmount } = renderIntoContainer(React.createElement(Acks));
+    await waitForText("b-1");
+
+    // No cheatsheet initially.
+    expect(
+      document.body.querySelector('[data-testid="keyboard-cheatsheet"]')
+    ).toBeNull();
+
+    // `?` opens it (Radix portals into document.body — query there).
+    pressKey("?");
+    await settle(
+      () =>
+        document.body.querySelector('[data-testid="keyboard-cheatsheet"]') !==
+        null
+    );
+    expect(
+      document.body.querySelector('[data-testid="keyboard-cheatsheet"]')
+    ).not.toBeNull();
+
+    // Escape closes it. The page wires onClose via useRowKeyboard
+    // (Escape → onClose → setHelpOpen(false)).
+    pressKey("Escape");
+    await settle(
+      () =>
+        document.body.querySelector('[data-testid="keyboard-cheatsheet"]') ===
+        null
+    );
+    expect(
+      document.body.querySelector('[data-testid="keyboard-cheatsheet"]')
+    ).toBeNull();
+
+    // `?` again re-opens (proving the toggle works in both directions).
+    pressKey("?");
+    await settle(
+      () =>
+        document.body.querySelector('[data-testid="keyboard-cheatsheet"]') !==
+        null
+    );
+    expect(
+      document.body.querySelector('[data-testid="keyboard-cheatsheet"]')
+    ).not.toBeNull();
+
+    unmount();
+  });
+
+  it("test_j_does_not_navigate_while_cheatsheet_is_open", async () => {
+    // `enabled: !helpOpen` is the recommended pairing with
+    // useRowKeyboard: j/k nav yields to the cheatsheet while it's
+    // open. The cheatsheet's own dismiss listener still closes it on
+    // any non-`?` keypress (per KeyboardCheatsheet.tsx), so pressing
+    // j will close the cheatsheet but the row should NOT have moved.
+    (api.listAcks as unknown as ReturnType<typeof vi.fn>).mockResolvedValue({
+      items: [
+        {
+          id: 1,
+          sourceBatchId: "b-1",
+          acceptedCount: 1,
+          rejectedCount: 0,
+          receivedCount: 1,
+          ackCode: "A",
+          parsedAt: "2026-06-20T12:00:00Z",
+        },
+        {
+          id: 2,
+          sourceBatchId: "b-2",
+          acceptedCount: 2,
+          rejectedCount: 0,
+          receivedCount: 2,
+          ackCode: "A",
+          parsedAt: "2026-06-20T12:01:00Z",
+        },
+      ],
+      total: 2,
+      returned: 2,
+      has_more: false,
+    });
+
+    const { unmount } = renderIntoContainer(React.createElement(Acks));
+    await waitForText("b-2");
+
+    // Move selection to row 0 first (so we can later verify it didn't
+    // jump to row 1 while the cheatsheet is open).
+    pressKey("j");
+    await settle(() => rowAt(0)?.getAttribute("data-state") === "selected");
+
+    // Open cheatsheet.
+    pressKey("?");
+    await settle(
+      () =>
+        document.body.querySelector('[data-testid="keyboard-cheatsheet"]') !==
+        null
+    );
+
+    // Press j while cheatsheet is open. Cheatsheet closes (its own
+    // listener handles any non-? key), but selection should NOT have
+    // moved — row 0 is still selected.
+    pressKey("j");
+    await settle(
+      () =>
+        document.body.querySelector('[data-testid="keyboard-cheatsheet"]') ===
+        null
+    );
+    expect(
+      document.body.querySelector('[data-testid="keyboard-cheatsheet"]')
+    ).toBeNull();
+    // Row 0 is still the selected row.
+    expect(hasExactlyOneSelectedRow()).toBe(true);
+    expect(rowAt(0)?.getAttribute("data-state")).toBe("selected");
+
+    unmount();
+  });
 });

src/pages/Acks.tsx

@@ -1,4 +1,4 @@
-import { useState } from "react";
+import { useCallback, useState } from "react";
 import { CheckCircle2, Download } from "lucide-react";
 import {
   Table,
@@ -11,7 +11,9 @@ import {
 import { Skeleton } from "@/components/ui/skeleton";
 import { EmptyState } from "@/components/ui/empty-state";
 import { ErrorState } from "@/components/ui/error-state";
+import { KeyboardCheatsheet } from "@/components/KeyboardCheatsheet";
 import { useAcks } from "@/hooks/useAcks";
+import { useRowKeyboard } from "@/hooks/useRowKeyboard";
 import { api } from "@/lib/api";
 import { fmt } from "@/lib/format";
 import { cn } from "@/lib/utils";
@@ -107,7 +109,52 @@ export function Acks() {
   const { data, isLoading, isError, error, refetch } = useAcks({ limit: 100 });
   const items = data?.items ?? [];
 
+  // Row navigation state (SP4-style j/k). `selectedIndex === null`
+  // means "no row focused yet" — the initial render shows no
+  // highlight, and the first j press lands on row 0 (and the first k
+  // press lands on the last row, so the user can quickly jump to
+  // either end of the list).
+  const [selectedIndex, setSelectedIndex] = useState<number | null>(null);
+  const [helpOpen, setHelpOpen] = useState(false);
+
+  const moveNext = useCallback(() => {
+    setSelectedIndex((i) => {
+      if (items.length === 0) return null;
+      if (i === null) return 0;
+      return (i + 1) % items.length;
+    });
+  }, [items.length]);
+
+  const movePrev = useCallback(() => {
+    setSelectedIndex((i) => {
+      if (items.length === 0) return null;
+      if (i === null) return items.length - 1;
+      // Add items.length before the modulo so the negative index
+      // (first row → wrap to last) wraps correctly.
+      return (i - 1 + items.length) % items.length;
+    });
+  }, [items.length]);
+
+  // `enabled: !helpOpen` so j/k navigation yields to the cheatsheet
+  // while it's open. The cheatsheet's own dismiss listener still fires
+  // for any non-`?` keypress (including j/k), so pressing j will close
+  // the cheatsheet but won't move the row — exactly the behavior the
+  // user expects: "the cheatsheet is in the way, get it out of my
+  // way; I'll start navigating on the next keypress".
+  useRowKeyboard({
+    enabled: !helpOpen && items.length > 0,
+    onNext: moveNext,
+    onPrev: movePrev,
+    onClose: () => setHelpOpen(false),
+    onToggleHelp: () => setHelpOpen((v) => !v),
+  });
+
   return (
+    <>
+      <KeyboardCheatsheet
+        open={helpOpen}
+        onClose={() => setHelpOpen(false)}
+      />
       <div className="space-y-8 animate-fade-in">
         <header>
           <div className="text-[10.5px] font-semibold uppercase tracking-[0.18em] text-muted-foreground mb-2 flex items-center gap-2">
@@ -159,8 +206,28 @@ export function Acks() {
                 </TableRow>
               </TableHeader>
               <TableBody>
-              {items.map((a) => (
+                {items.map((a, idx) => {
-                <TableRow key={a.id}>
+                  const isSelected = selectedIndex === idx;
+                  return (
+                    <TableRow
+                      key={a.id}
+                      data-row-index={idx}
+                      data-state={isSelected ? "selected" : undefined}
+                      aria-selected={isSelected}
+                      className={cn(
+                        isSelected && [
+                          // Accent-tinted bg + ring + left strip make the
+                          // selected row clearly stand out from the
+                          // default `hover:bg-muted/30` and the
+                          // `data-[state=selected]:bg-muted` that the
+                          // TableRow primitive applies. Tailwind's
+                          // `accent` token is the same accent used
+                          // elsewhere in the app (nav-active indicator,
+                          // row-flash keyframe, focus ring).
+                          "bg-accent/10 ring-1 ring-inset ring-accent/40 shadow-[inset_2px_0_0_0_hsl(var(--accent))]",
+                        ],
+                      )}
+                    >
                       <TableCell className="text-muted-foreground">
                         <CheckCircle2
                           className={cn(
@@ -194,11 +261,13 @@ export function Acks() {
                         <DownloadButton id={a.id} sourceBatchId={a.sourceBatchId} />
                       </TableCell>
                     </TableRow>
-              ))}
+                  );
+                })}
               </TableBody>
             </Table>
           )}
         </div>
       </div>
+    </>
   );
 }

src/pages/Remittances.test.tsx

@@ -75,16 +75,56 @@ async function waitForText(
   }
 }
 
-describe("Remittances", () => {
+/**
-  beforeEach(() => {
+ * Poll a predicate until it holds or we time out. react-query's fetch
-    vi.clearAllMocks();
+ * resolves asynchronously, and Radix portals content into
+ * `document.body`, so the DOM doesn't reflect new state synchronously
+ * after a keypress — we have to await a tick before asserting.
+ */
+async function settle(
+  predicate: () => boolean,
+  timeoutMs = 2000
+): Promise<void> {
+  const start = Date.now();
+  while (!predicate()) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error("settle: predicate did not hold within timeout");
+    }
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 0));
     });
+  }
+}
 
-  it("renders a CAS adjustment label inside the expanded detail row", async () => {
+/**
-    (
+ * Dispatch a synthetic keydown on `window`. Same pattern used in
-      api.listRemittances as unknown as ReturnType<typeof vi.fn>
+ * `Claims.test.tsx` and `useDrawerKeyboard.test.ts`.
-    ).mockResolvedValue({
+ */
-      items: [
+function pressKey(key: string): void {
+  act(() => {
+    window.dispatchEvent(
+      new KeyboardEvent("keydown", { key, bubbles: true, cancelable: true })
+    );
+  });
+}
+
+/** The data row at `idx` (per `data-row-index={idx}`). */
+function rowAt(idx: number): HTMLTableRowElement | null {
+  return document.querySelector(
+    `tbody tr[data-row-index="${idx}"]`
+  ) as HTMLTableRowElement | null;
+}
+
+/** True iff exactly one row carries `data-state="selected"`. */
+function hasExactlyOneSelectedRow(): boolean {
+  const selected = document.querySelectorAll(
+    'tbody tr[data-state="selected"]'
+  );
+  return selected.length === 1;
+}
+
+/** Fixture used by every test below so the page has rows to navigate. */
+const SAMPLE_REMITS = [
   {
     id: "PCN-1",
     claimId: "CLM-1",
@@ -111,12 +151,44 @@ describe("Remittances", () => {
       },
     ],
   },
-      ],
+  {
-      total: 1,
+    id: "PCN-2",
-      returned: 1,
+    claimId: "CLM-2",
+    payerName: "Aetna",
+    paidAmount: 200,
+    adjustmentAmount: 0,
+    receivedDate: "2026-06-18T12:00:00Z",
+    checkNumber: "",
+    status: "received",
+    adjustments: [],
+  },
+  {
+    id: "PCN-3",
+    claimId: "CLM-3",
+    payerName: "United",
+    paidAmount: 300,
+    adjustmentAmount: 0,
+    receivedDate: "2026-06-17T12:00:00Z",
+    checkNumber: "",
+    status: "received",
+    adjustments: [],
+  },
+] as const;
+
+describe("Remittances", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    (
+      api.listRemittances as unknown as ReturnType<typeof vi.fn>
+    ).mockResolvedValue({
+      items: SAMPLE_REMITS,
+      total: SAMPLE_REMITS.length,
+      returned: SAMPLE_REMITS.length,
       has_more: false,
     });
+  });
 
+  it("renders a CAS adjustment label inside the expanded detail row", async () => {
     const { unmount } = renderIntoContainer(React.createElement(Remittances));
     await waitForText("PCN-1");
 
@@ -146,4 +218,175 @@ describe("Remittances", () => {
     expect(document.body.textContent).toContain("PR-1");
     unmount();
   });
+
+  it("test_initial_render_shows_no_selection_highlight", async () => {
+    const { unmount } = renderIntoContainer(React.createElement(Remittances));
+    await waitForText("PCN-3");
+
+    // The spec requires the initial render shows no selection
+    // highlight — none of the three data rows should be marked
+    // selected.
+    expect(
+      document.querySelectorAll('tbody tr[data-state="selected"]').length
+    ).toBe(0);
+
+    unmount();
+  });
+
+  it("test_pressing_j_increments_selection_with_wrap", async () => {
+    const { unmount } = renderIntoContainer(React.createElement(Remittances));
+    await waitForText("PCN-3");
+
+    // From null, j lands on row 0.
+    pressKey("j");
+    await settle(() => rowAt(0)?.getAttribute("data-state") === "selected");
+    expect(rowAt(0)?.getAttribute("data-state")).toBe("selected");
+
+    // j again → row 1, then row 2.
+    pressKey("j");
+    await settle(() => rowAt(1)?.getAttribute("data-state") === "selected");
+    expect(rowAt(1)?.getAttribute("data-state")).toBe("selected");
+
+    pressKey("j");
+    await settle(() => rowAt(2)?.getAttribute("data-state") === "selected");
+    expect(rowAt(2)?.getAttribute("data-state")).toBe("selected");
+
+    // j from the last row wraps to row 0 (wrap policy documented in
+    // Remittances.tsx — matches Claims' drawer behavior).
+    pressKey("j");
+    await settle(() => rowAt(0)?.getAttribute("data-state") === "selected");
+    expect(rowAt(0)?.getAttribute("data-state")).toBe("selected");
+    expect(hasExactlyOneSelectedRow()).toBe(true);
+
+    unmount();
+  });
+
+  it("test_pressing_k_decrements_selection_with_wrap", async () => {
+    const { unmount } = renderIntoContainer(React.createElement(Remittances));
+    await waitForText("PCN-3");
+
+    // From null, k jumps to the last row (one-keystroke "bottom of
+    // list" gesture).
+    pressKey("k");
+    await settle(() => rowAt(2)?.getAttribute("data-state") === "selected");
+    expect(rowAt(2)?.getAttribute("data-state")).toBe("selected");
+
+    // k → row 1, then row 0.
+    pressKey("k");
+    await settle(() => rowAt(1)?.getAttribute("data-state") === "selected");
+    expect(rowAt(1)?.getAttribute("data-state")).toBe("selected");
+
+    pressKey("k");
+    await settle(() => rowAt(0)?.getAttribute("data-state") === "selected");
+    expect(rowAt(0)?.getAttribute("data-state")).toBe("selected");
+
+    // k from row 0 wraps to row 2 (last).
+    pressKey("k");
+    await settle(() => rowAt(2)?.getAttribute("data-state") === "selected");
+    expect(rowAt(2)?.getAttribute("data-state")).toBe("selected");
+
+    unmount();
+  });
+
+  it("test_j_does_not_trigger_expand_collapse", async () => {
+    // j/k selection is a focus indicator, NOT a substitute for the
+    // click-to-expand gesture. Pressing j through a row that has
+    // adjustments must NOT open the detail row.
+    const { unmount } = renderIntoContainer(React.createElement(Remittances));
+    await waitForText("PCN-3");
+
+    // Row 0 has adjustments — moving selection onto it should leave
+    // the row collapsed (the user can still click to expand).
+    pressKey("j");
+    await settle(() => rowAt(0)?.getAttribute("data-state") === "selected");
+    expect(document.body.textContent).not.toContain("Adjustments (2)");
+
+    pressKey("j");
+    await settle(() => rowAt(1)?.getAttribute("data-state") === "selected");
+    expect(document.body.textContent).not.toContain("Adjustments (2)");
+
+    unmount();
+  });
+
+  it("test_question_mark_toggles_cheatsheet_and_escape_closes", async () => {
+    const { unmount } = renderIntoContainer(React.createElement(Remittances));
+    await waitForText("PCN-3");
+
+    // No cheatsheet initially.
+    expect(
+      document.body.querySelector('[data-testid="keyboard-cheatsheet"]')
+    ).toBeNull();
+
+    // `?` opens it.
+    pressKey("?");
+    await settle(
+      () =>
+        document.body.querySelector('[data-testid="keyboard-cheatsheet"]') !==
+        null
+    );
+    expect(
+      document.body.querySelector('[data-testid="keyboard-cheatsheet"]')
+    ).not.toBeNull();
+
+    // Escape closes it.
+    pressKey("Escape");
+    await settle(
+      () =>
+        document.body.querySelector('[data-testid="keyboard-cheatsheet"]') ===
+        null
+    );
+    expect(
+      document.body.querySelector('[data-testid="keyboard-cheatsheet"]')
+    ).toBeNull();
+
+    // `?` again re-opens (toggle works in both directions).
+    pressKey("?");
+    await settle(
+      () =>
+        document.body.querySelector('[data-testid="keyboard-cheatsheet"]') !==
+        null
+    );
+    expect(
+      document.body.querySelector('[data-testid="keyboard-cheatsheet"]')
+    ).not.toBeNull();
+
+    unmount();
+  });
+
+  it("test_j_does_not_navigate_while_cheatsheet_is_open", async () => {
+    // `enabled: !helpOpen` is the recommended pairing with
+    // useRowKeyboard: j/k nav yields to the cheatsheet while it's
+    // open. Pressing j while the cheatsheet is open closes the
+    // cheatsheet (its own dismiss listener handles any non-`?`
+    // keypress) but the row should NOT have moved.
+    const { unmount } = renderIntoContainer(React.createElement(Remittances));
+    await waitForText("PCN-3");
+
+    // Move selection to row 0 first.
+    pressKey("j");
+    await settle(() => rowAt(0)?.getAttribute("data-state") === "selected");
+
+    // Open cheatsheet.
+    pressKey("?");
+    await settle(
+      () =>
+        document.body.querySelector('[data-testid="keyboard-cheatsheet"]') !==
+        null
+    );
+
+    // j while cheatsheet open: closes cheatsheet, row stays at 0.
+    pressKey("j");
+    await settle(
+      () =>
+        document.body.querySelector('[data-testid="keyboard-cheatsheet"]') ===
+        null
+    );
+    expect(
+      document.body.querySelector('[data-testid="keyboard-cheatsheet"]')
+    ).toBeNull();
+    expect(hasExactlyOneSelectedRow()).toBe(true);
+    expect(rowAt(0)?.getAttribute("data-state")).toBe("selected");
+
+    unmount();
+  });
 });

src/pages/Remittances.tsx

@@ -1,4 +1,4 @@
-import { Fragment, useState } from "react";
+import { Fragment, useCallback, useState } from "react";
 import { ChevronDown, ChevronRight, Receipt } from "lucide-react";
 import {
   Table,
@@ -14,7 +14,9 @@ import { EmptyState } from "@/components/ui/empty-state";
 import { ErrorState } from "@/components/ui/error-state";
 import { FilterChips, type FilterChipOption } from "@/components/ui/filter-chips";
 import { Pagination } from "@/components/ui/pagination";
+import { KeyboardCheatsheet } from "@/components/KeyboardCheatsheet";
 import { useRemittances } from "@/hooks/useRemittances";
+import { useRowKeyboard } from "@/hooks/useRowKeyboard";
 import { fmt } from "@/lib/format";
 import { cn } from "@/lib/utils";
 import type { CasAdjustment, RemittanceStatus } from "@/types";
@@ -57,6 +59,11 @@ export function Remittances() {
   const [page, setPage] = useState(1);
   const [status, setStatus] = useState<RemittanceStatus | null>(null);
   const [expanded, setExpanded] = useState<Set<string>>(() => new Set());
+  // Row navigation (j/k) lives in parallel with `expanded`; selection
+  // is purely a focus-state indicator and does NOT auto-expand the
+  // row (so j/k doesn't fight the existing click-to-expand gesture).
+  const [selectedIndex, setSelectedIndex] = useState<number | null>(null);
+  const [helpOpen, setHelpOpen] = useState(false);
 
   const { data, isLoading, isError, error, refetch, dataUpdatedAt } = useRemittances({
     sort: "receivedDate",
@@ -83,7 +90,41 @@ export function Remittances() {
     });
   };
 
+  const moveNext = useCallback(() => {
+    setSelectedIndex((i) => {
+      if (items.length === 0) return null;
+      if (i === null) return 0;
+      return (i + 1) % items.length;
+    });
+  }, [items.length]);
+
+  const movePrev = useCallback(() => {
+    setSelectedIndex((i) => {
+      if (items.length === 0) return null;
+      if (i === null) return items.length - 1;
+      // Add items.length before the modulo so the negative index
+      // (first row → wrap to last) wraps correctly.
+      return (i - 1 + items.length) % items.length;
+    });
+  }, [items.length]);
+
+  // `enabled: !helpOpen` so j/k yields to the cheatsheet while it's
+  // open (the cheatsheet's own dismiss listener still closes it on
+  // any non-`?` keypress). See Acks.tsx for the full rationale.
+  useRowKeyboard({
+    enabled: !helpOpen && items.length > 0,
+    onNext: moveNext,
+    onPrev: movePrev,
+    onClose: () => setHelpOpen(false),
+    onToggleHelp: () => setHelpOpen((v) => !v),
+  });
+
   return (
+    <>
+      <KeyboardCheatsheet
+        open={helpOpen}
+        onClose={() => setHelpOpen(false)}
+      />
       <div className="space-y-8 animate-fade-in">
         <header>
           <div className="text-[10.5px] font-semibold uppercase tracking-[0.18em] text-muted-foreground mb-2 flex items-center gap-2">
@@ -165,14 +206,29 @@ export function Remittances() {
                   </TableRow>
                 </TableHeader>
                 <TableBody>
-                {items.map((r) => {
+                  {items.map((r, idx) => {
                     const isOpen = expanded.has(r.id);
                     const hasAdjustments =
                       !!r.adjustments && r.adjustments.length > 0;
+                    const isSelected = selectedIndex === idx;
                     return (
                       <Fragment key={`${r.id}-${dataUpdatedAt}`}>
                         <TableRow
-                        className={cn("animate-row-flash")}
+                          data-row-index={idx}
+                          data-state={isSelected ? "selected" : undefined}
+                          aria-selected={isSelected}
+                          className={cn(
+                            "animate-row-flash",
+                            isSelected && [
+                              // Same accent-tinted highlight as Acks:
+                              // background tint + inset ring + left
+                              // accent strip, layered on top of the
+                              // TableRow primitive's
+                              // `data-[state=selected]:bg-muted` to
+                              // win visually.
+                              "bg-accent/10 ring-1 ring-inset ring-accent/40 shadow-[inset_2px_0_0_0_hsl(var(--accent))]",
+                            ],
+                          )}
                           onClick={() =>
                             hasAdjustments ? toggleExpand(r.id) : undefined
                           }
@@ -259,5 +315,6 @@ export function Remittances() {
           )}
         </div>
       </div>
+    </>
   );
 }