Initial Commit

apps/testbed/src/client/pages/home/home-page.md

@@ -0,0 +1,63 @@
+# HomePage
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->## Purpose
+
+The `HomePage` is the landing page of the Suaveplan Testbed application. It renders a responsive grid of cards, one for each registered library route, giving developers an at-a-glance overview of all interactive demonstrations available in the testbed. Each card links directly to its corresponding library demo page.
+
+## Features
+
+- Responsive grid layout (1 column on mobile, 2 on tablet, 3 on desktop)
+- One card per route entry, derived from the shared `routes` array (excluding the home route itself)
+- Category label displayed in small uppercase above each card title
+- Amber "Requires services" badge on routes that need external services running
+- All required `data-testid` attributes for Playwright E2E testing
+- Dark-mode aware styling with Tailwind utility classes throughout
+
+## Usage: Basic Example
+
+```tsx
+import React from "react";
+import { MemoryRouter } from "react-router-dom";
+import { HomePage } from "./home-page.js";
+
+export function App() {
+  return (
+    <MemoryRouter>
+      <HomePage />
+    </MemoryRouter>
+  );
+}
+```
+
+## Usage: Advanced Example
+
+The home page automatically reflects any changes to the `routes` array. Add a new route entry in `routes.ts` and it will appear on the home page without further changes:
+
+```ts
+// routes.ts
+export const routes: RouteEntry[] = [
+  // existing routes...
+  { path: "/new-library", label: "@suaveplan/new-library", category: "utilities" },
+];
+```
+
+The `requiresServices` flag causes an amber badge to render, signalling to developers that the demo needs external dependencies (databases, object storage, etc.) to function.
+
+## API Reference
+
+### `HomePage(): React.JSX.Element`
+
+No props. Renders the full landing page including the library card grid, a hidden `demo-card` placeholder, and a console panel footer.
+
+**data-testid attributes:**
+
+- `page-title` — the `<h1>` heading
+- `library-card` — each `<Link>` card (one per non-home route)
+- `demo-card` — hidden placeholder div (for test compatibility)
+- `console-panel` — bottom console section
+
+## Implementation Notes
+
+The home route (`"/"`) is explicitly excluded from the grid using a `.filter()` call to avoid a self-referential link. The `routes` array is imported from the shared `routes.ts` module, ensuring the home page always reflects the authoritative list of pages. The layout uses CSS Grid with Tailwind breakpoints for a fluid responsive experience. The hidden `demo-card` element preserves the standard page contract so baseline E2E sweeps that check for `[data-testid="demo-card"]` pass on the home route.