Merge latest main into a11y/contrast-verify-and-correct-badge

Author: mikewheeleer

.github/workflows/ci.yml

@@ -51,7 +51,7 @@ jobs:
 
       - name: Scan PR diff for secrets
         env:
-          BASE_REF: ${{ github.event.pull_request.base.ref || 'origin/main' }}
+          BASE_REF: origin/${{ github.event.pull_request.base.ref || 'main' }}
         run: npm run scan:secrets:ci
 
   build-test:

CONTRIBUTING.md

@@ -65,6 +65,28 @@ Run coverage locally with:
 npm run test:coverage
 ```
 
+#### Testing components with global side effects
+
+Components that register `window`/`document`-level listeners (keyboard shortcuts,
+visibility changes, `matchMedia`) or trigger navigation need a few extra things
+covered beyond a normal render test. `src/components/__tests__/CommandPalette.test.tsx`
+is the reference example — it mocks `next/navigation`'s `useRouter` and drives the
+component entirely through `fireEvent.keyDown(window, ...)`, since the palette's
+open/close/navigate behaviour is wired to a global `keydown` listener rather than
+props. At minimum, cover:
+
+- The open/dismiss triggers themselves (e.g. `Cmd`/`Ctrl+K`, `Escape`) fired on
+  `window`, not just on an element inside the component.
+- Filtering or derived state is asserted against the actual source data
+  (e.g. `ROUTES` from `src/lib/routes.ts`), not a hard-coded expected list, so the
+  test still catches a real regression if that data changes shape.
+- Keyboard selection assertions target a *specific* highlighted item (not just
+  "the first one"), so a test can't pass by accident if the highlight logic is
+  broken but happens to default to index 0.
+- Listener cleanup on unmount (`jest.spyOn(window, 'removeEventListener')`), so a
+  leaked listener from a later regression fails the suite instead of silently
+  accumulating in production.
+
 ---
 
 ## Lighthouse CI — performance budgets

README.md

@@ -58,7 +58,7 @@ Reusable building blocks live under `src/components` and are imported by route p
 | [`KeyboardShortcutsHelp`](src/components/KeyboardShortcutsHelp.tsx) | `?` overlay listing keyboard shortcuts                                 |
 | [`CommandPalette`](src/components/CommandPalette.tsx)               | `Cmd/Ctrl+K` route jump palette                                        |
 | [`Tooltip`](src/components/Tooltip.tsx)                             | Status surface with loading/empty/error/success states (see [tooltips.md](docs/tooltips.md)) |
-| [`Slippage`](src/components/Slippage.tsx)                           | Slippage tolerance control with preset/custom options and state handling (see [slippage.md](docs/slippage.md)) |
+| [`QuoteHistory`](src/app/quote/QuoteHistory.tsx)                   | Recent quote history list with selection callback and memoization (see [history.md](docs/history.md)) |
 
 Data fetching helpers (`apiClient`, `useApi`, `useList`) live in `src/lib`.
 

docs/STYLEGUIDE.md

@@ -233,6 +233,8 @@ function SortHeader({ label, sortKey, activeSortKey, sortDir, onSort }) {
 - [`README.md`](../README.md) — overview, routes, scripts.
 - [`docs/theme-storage.md`](./theme-storage.md) — light/dark toggle and the
   `localStorage` contract that backs it.
+- [`docs/history.md`](./history.md) — quote history component contract, props,
+  and memoization.
 
 ## IconButton accessible-label contract
 

docs/architecture.md

@@ -124,7 +124,7 @@ incrementing `requestIdRef`.
 | 3    | Request                    | Calls `apiFetch<Quote>(path)` with query params `?source_asset=...&dest_asset=...&amount=...`. Aborts previous in-flight request via `AbortController`. |
 | 4    | `src/lib/apiClient.ts`     | Sends GET, parses `Quote` response.                                                                                                                     |
 | 5    | Display                    | Formats amount via `formatQuoteAmountDisplay` / `formatQuoteRateDisplay` (both from `src/lib/format.ts`).                                               |
-| 6    | History                    | Inputs persisted to `localStorage` via `useLocalStorage` (`src/lib/useLocalStorage.ts`).                                                                |
+| 6    | History                    | Inputs persisted to `localStorage` via `useLocalStorage` (`src/lib/useLocalStorage.ts`) and rendered via `QuoteHistory` (see [`docs/history.md`](history.md)). |
 
 ### Events
 

docs/history.md

@@ -0,0 +1,69 @@
+# Quote History (`QuoteHistory`)
+
+The `QuoteHistory` component renders a list of recently requested currency routing path quotes persisted in `localStorage`. Clicking a history item applies its saved inputs (`source`, `dest`, `amount`) back into the quote form.
+
+The component is memoized (`React.memo`) so stable prop references prevent unnecessary re-renders when parent form inputs, loading state, or error messages update.
+
+## Props
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `history` | `HistoryEntry[]` | Yes | List of recently saved quote input entries. |
+| `onSelect` | `(entry: HistoryEntry) => void` | Yes | Callback invoked when a user clicks a history button to select an entry. |
+
+## Types
+
+```typescript
+export type QuoteInputs = {
+  source: string;
+  dest: string;
+  amount: string;
+};
+
+export type HistoryEntry = QuoteInputs & {
+  savedAt: number; // Unix timestamp in milliseconds when saved
+};
+
+export interface QuoteHistoryProps {
+  history: HistoryEntry[];
+  onSelect: (entry: HistoryEntry) => void;
+}
+```
+
+## Behavior & Rendering Contract
+
+- **Empty State** — If `history` is empty (`history.length === 0`), `QuoteHistory` renders `null`.
+- **Item Display** — Each entry is rendered as a full-width button displaying `{entry.source} → {entry.dest} · {entry.amount}`.
+- **Memoization** — Wrapped with `React.memo`. Re-renders only when `history` array reference or `onSelect` function reference changes.
+- **Persistence** — Quotes are stored in `localStorage` under `stableroute.quote.history`, limited to a maximum of 5 entries. Duplicate entries are deduplicated on push.
+
+## Usage Example
+
+```tsx
+import { QuoteHistory, HistoryEntry } from './QuoteHistory';
+import { useCallback, useState } from 'react';
+
+function QuoteContainer() {
+  const [history, setHistory] = useState<HistoryEntry[]>([]);
+
+  const handleSelectHistory = useCallback((entry: HistoryEntry) => {
+    // Populate form fields with selected history item
+    setSourceAsset(entry.source);
+    setDestAsset(entry.dest);
+    setAmount(entry.amount);
+  }, []);
+
+  return (
+    <QuoteHistory
+      history={history}
+      onSelect={handleSelectHistory}
+    />
+  );
+}
+```
+
+## Accessibility
+
+- Wrapped in a `<section>` element linked to the section title via `aria-labelledby="recent-quotes-heading"`.
+- Uses semantic `<h2>` with ID `recent-quotes-heading`.
+- Interactive items are rendered as semantic `<button type="button">` elements with explicit type attributes to avoid accidental form submission.

src/app/api-keys/Client.tsx

@@ -1,19 +1,22 @@
 'use client';
 
-import { useCallback, useState } from 'react';
+import React, { memo, useCallback, useState, useRef } from 'react';
 import { IconButton } from '@/components/IconButton';
 import { ResourceList } from '@/components/ResourceList';
 import { TextField } from '@/components/TextField';
 import { TimeAgo } from '@/components/TimeAgo';
 import { Badge } from '@/components/Badge';
 import { apiDelete, apiGet, apiPost } from '@/lib/apiClient';
+import { useFormAnnouncement } from '@/lib/useFormAnnouncement';
 import { useList } from '@/lib/useList';
 import { writeToClipboard } from '@/lib/clipboard';
 import { useToast } from '@/components/ToastProvider';
 import type { ApiKey, CreateApiKeyResponse } from '@/lib/types';
 import { isApiKeyListResponse, isCreateApiKeyResponse } from '@/lib/validate';
 
-export default function ApiKeysClient() {
+function ApiKeysClient() {
+  const renderCount = useRef(0);
+  renderCount.current++;
   const loadItems = useCallback(
     () =>
       apiGet<{ items: ApiKey[] }>('/api/v1/api-keys', {
@@ -29,6 +32,7 @@ export default function ApiKeysClient() {
   const [recentPrefix, setRecentPrefix] = useState<string | null>(null);
   const [submitting, setSubmitting] = useState(false);
   const [copyFailed, setCopyFailed] = useState(false);
+  const { message: formStatus, announce } = useFormAnnouncement();
   const { push } = useToast();
   const items = itemsResult.status === 'success' ? itemsResult.data : null;
   const loading =
@@ -37,6 +41,7 @@ export default function ApiKeysClient() {
   const onCreate = async (event: React.FormEvent) => {
     event.preventDefault();
     setSubmitting(true);
+    announce('Creating API key…');
     try {
       const response = await apiPost<CreateApiKeyResponse>(
         '/api/v1/api-keys',
@@ -47,8 +52,10 @@ export default function ApiKeysClient() {
       setCopyFailed(false);
       setRecentPrefix(response.prefix ?? response.key.slice(0, 8));
       setLabel('');
+      announce('API key created. Copy it now.');
       await itemsResult.refetch();
     } catch (err) {
+      announce('');
       /* surfaced via useList error if refetch fails; keep form local */
     } finally {
       setSubmitting(false);
@@ -145,6 +152,7 @@ export default function ApiKeysClient() {
         loading={loading}
         emptyMessage="No API keys yet."
         getKey={(key) => key.prefix}
+        announcement={formStatus || undefined}
         rowClassName="flex items-center justify-between py-3"
         removeDialogTitle="Revoke API key?"
         removeDialogConfirmLabel="Revoke"
@@ -180,3 +188,4 @@ export default function ApiKeysClient() {
     </main>
   );
 }
+export default memo(ApiKeysClient);

src/app/api-keys/page.test.tsx

@@ -227,6 +227,93 @@ describe('ApiKeysPage', () => {
     expect(screen.getAllByText(/Key/i).length).toBeGreaterThanOrEqual(1);
   });
 
+  describe('form announcement', () => {
+    it('announces form submission status inside the polite live region', async () => {
+      let resolvePost: ((value: Response) => void) | undefined;
+      const pendingResponse = new Promise<Response>((resolve) => {
+        resolvePost = resolve;
+      });
+
+      global.fetch = jest
+        .fn()
+        .mockResolvedValueOnce({
+          ok: true,
+          text: async () => JSON.stringify({ items: [] }),
+        } as unknown as Response)
+        .mockImplementationOnce(
+          () => pendingResponse
+        ) as unknown as typeof global.fetch;
+
+      renderPage();
+      await waitFor(() => screen.getByText(/No API keys yet/i));
+
+      fireEvent.change(screen.getByLabelText('Label'), {
+        target: { value: 'My key' },
+      });
+      fireEvent.click(screen.getByRole('button', { name: 'Create' }));
+
+      const liveRegion = document.querySelector('[aria-live=polite]');
+      expect(liveRegion).toHaveTextContent('Creating API key…');
+
+      resolvePost?.({
+        ok: true,
+        text: async () =>
+          JSON.stringify({ key: 'sk_test123', prefix: 'sk_test' }),
+      } as unknown as Response);
+
+      // After success, the live region should contain the success announcement
+      await waitFor(() => {
+        expect(liveRegion).toHaveTextContent('API key created. Copy it now.');
+      });
+    });
+
+    it('clears the form announcement on creation failure', async () => {
+      global.fetch = jest
+        .fn()
+        .mockResolvedValueOnce({
+          ok: true,
+          text: async () => JSON.stringify({ items: [] }),
+        } as unknown as Response)
+        .mockRejectedValueOnce(
+          new Error('Network error')
+        ) as unknown as typeof global.fetch;
+
+      renderPage();
+      await waitFor(() => screen.getByText(/No API keys yet/i));
+
+      fireEvent.change(screen.getByLabelText('Label'), {
+        target: { value: 'My key' },
+      });
+      fireEvent.click(screen.getByRole('button', { name: 'Create' }));
+
+      // After the POST fails, the catch block clears the announcement.
+      // The button re-enables once submitting is false.
+      await waitFor(() => {
+        expect(
+          screen.getByRole('button', { name: 'Create' })
+        ).not.toBeDisabled();
+      });
+
+      const liveRegion = document.querySelector('[aria-live=polite]');
+      expect(liveRegion).not.toHaveTextContent('Creating API key…');
+      expect(liveRegion).not.toHaveTextContent('API key created.');
+    });
+
+    it('does not announce form status on initial render', async () => {
+      global.fetch = jest.fn().mockResolvedValueOnce({
+        ok: true,
+        text: async () => JSON.stringify({ items: [] }),
+      } as unknown as Response);
+
+      renderPage();
+      await waitFor(() => screen.getByText(/No API keys yet/i));
+
+      const liveRegion = document.querySelector('[aria-live=polite]');
+      expect(liveRegion).not.toHaveTextContent('Creating');
+      expect(liveRegion).not.toHaveTextContent('API key created');
+    });
+  });
+
   describe('clipboard guard', () => {
     function mockCreateFlow() {
       global.fetch = jest
@@ -255,32 +342,43 @@ describe('ApiKeysPage', () => {
         } as unknown as Response);
     }
 
-    it('copies the secret and hides it once the write succeeds', async () => {
-      mockCreateFlow();
-      const writeText = jest.fn().mockResolvedValue(undefined);
-      setClipboard({ writeText });
-
-      renderPage();
-      await waitFor(() => screen.getByText(/No API keys yet/i));
-      await createKey();
-
-      expect(
-        await screen.findByText('sk_live_supersecret')
-      ).toBeInTheDocument();
-
-      fireEvent.click(
-        screen.getByRole('button', { name: 'Copy API key secret' })
-      );
+    it('increments render count on each render', async () => {
+  // Initial fetch with empty list
+  global.fetch = jest.fn().mockResolvedValueOnce({
+    ok: true,
+    text: async () => JSON.stringify({ items: [] }),
+  } as unknown as Response);
+
+  renderPage();
+  await waitFor(() => screen.getByText(/No API keys yet/i));
+  const getRenderCount = () => Number(screen.getByTestId('render-count').textContent);
+  const initial = getRenderCount();
+  expect(initial).toBe(1);
+
+  // Mock fetches for creating a key and then listing keys
+  const now = Date.now();
+  global.fetch = jest
+    .fn()
+    .mockResolvedValueOnce({
+      ok: true,
+      text: async () => JSON.stringify({ items: [] }),
+    } as unknown as Response) // initial list
+    .mockResolvedValueOnce({
+      ok: true,
+      text: async () => JSON.stringify({ key: 'sk_test', prefix: 'sk_test' }),
+    } as unknown as Response) // create response
+    .mockResolvedValueOnce({
+      ok: true,
+      text: async () =>
+        JSON.stringify({
+          items: [{ prefix: 'sk_test', label: 'Test', createdAt: now }],
+        }),
+    } as unknown as Response); // list after creation
 
-      await waitFor(() => {
-        expect(writeText).toHaveBeenCalledWith('sk_live_supersecret');
-      });
-      await waitFor(() => {
-        expect(
-          screen.queryByText('sk_live_supersecret')
-        ).not.toBeInTheDocument();
-      });
-    });
+  await createKey();
+  const after = getRenderCount();
+  expect(after).toBeGreaterThan(initial);
+});
 
     it('shows a toast and a selectable fallback field when the write is rejected', async () => {
       mockCreateFlow();