Initial Commit

apps/testbed/src/client/components/layout/sidebar.md

@@ -0,0 +1,43 @@
+# sidebar
+
+## Purpose
+
+`Sidebar` renders the primary navigation for the testbed as a vertically scrollable nav panel.
+Routes are grouped by their `category` field from `routes.ts` and rendered as React Router
+`NavLink` elements. Active links receive distinct styling.
+
+Every `data-testid="nav-<path>"` attribute maps directly to a route in the manifest, making
+it trivial to enumerate and test all routes programmatically in E2E navigation specs.
+
+## Features
+
+- Groups routes by category, preserving insertion order from `routes.ts`
+- Uses React Router `NavLink` with `isActive` callback for active-state styling
+- Each nav item has `data-testid="nav-<route-path-without-slash>"` for Playwright
+- Scrollable: overflow-y-auto handles large numbers of routes
+
+## Usage: Basic Example
+
+```tsx
+import { Sidebar } from "./sidebar.js"; // requires BrowserRouter in tree
+```
+
+## Usage: Advanced Example
+
+```tsx
+// E2E -- click nav link and assert page title
+await page.click('[data-testid="nav-crypto"]');
+await page.waitForSelector('[data-testid="page-title"]');
+```
+
+## API Reference
+
+### `Sidebar(): JSX.Element`
+
+No props. Reads `routes` from `routes.ts`. Requires `BrowserRouter` or `MemoryRouter` in tree.
+
+## Implementation Notes
+
+Categories are derived via `[...new Set(routes.map(r => r.category))]`. ES2015+ Set preserves
+insertion order, so routes appear in the same order as the manifest. Adding routes to
+`routes.ts` automatically updates the sidebar.