Merge pull request #210 from helpfulengineering/frontend-dev

Frontend dev

Author: touchthesun

frontend/e2e/okh-catalog.spec.ts

@@ -0,0 +1,65 @@
+import { test, expect } from "./mock-api";
+import { okhListEmptyFixture } from "../src/test/fixtures";
+
+// Slice A1: faceted OKH design catalog. Mocked lane (default gate) covers the
+// facet behavior; the real-api lane only runs the lenient "loads" check.
+
+test("faceted catalog loads with a filter panel", async ({ page }) => {
+  await page.goto("/okh");
+  await expect(
+    page.getByRole("heading", { name: /open hardware designs/i }),
+  ).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Filters" })).toBeVisible();
+});
+
+test("shows fixture designs (mocked)", async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === "real-api", "asserts fixture data");
+  await page.goto("/okh");
+  await expect(page.getByRole("heading", { name: "Open Ventilator" })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Face Shield" })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Test Rig" })).toBeVisible();
+});
+
+test("selecting a facet narrows the results (mocked)", async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === "real-api", "asserts fixture data");
+  await page.goto("/okh");
+  // Only Face Shield is GPL-2.0.
+  await page.getByRole("checkbox", { name: /GPL-2\.0/ }).check();
+  await expect(page.getByRole("heading", { name: "Face Shield" })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Open Ventilator" })).toBeHidden();
+  // Facet selection is reflected in the URL (deep-linkable).
+  await expect(page).toHaveURL(/license=GPL-2\.0/);
+});
+
+test("category facet is the primary spine and narrows results (mocked)", async ({
+  page,
+}, testInfo) => {
+  test.skip(testInfo.project.name === "real-api", "asserts fixture data");
+  await page.goto("/okh");
+  // Category is present as a facet group. Test Rig ("Calibration test rig") is
+  // the only Test & Measurement device.
+  await expect(page.getByRole("heading", { name: "Category" })).toBeVisible();
+  await page.getByRole("checkbox", { name: /Test & Measurement/ }).check();
+  await expect(page.getByRole("heading", { name: "Test Rig" })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Open Ventilator" })).toBeHidden();
+  await expect(page).toHaveURL(/category=Test/);
+});
+
+test("shows the empty state (mocked)", async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === "real-api", "forces an empty response");
+  await page.route("**/v1/api/okh**", (route) =>
+    route.fulfill({ json: okhListEmptyFixture }),
+  );
+  await page.goto("/okh");
+  await expect(page.getByText(/no designs/i)).toBeVisible();
+});
+
+test("shows the error state with retry (mocked)", async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === "real-api", "forces an error response");
+  await page.route("**/v1/api/okh**", (route) =>
+    route.fulfill({ status: 503, json: { message: "boom" } }),
+  );
+  await page.goto("/okh");
+  await expect(page.getByRole("alert")).toBeVisible();
+  await expect(page.getByRole("button", { name: /retry/i })).toBeVisible();
+});

frontend/e2e/okh-detail.spec.ts

@@ -0,0 +1,20 @@
+import { test, expect } from "./mock-api";
+
+// Slice 2 (#187): OKH design detail + validate. Mocked lane (the fixture id
+// okh-0001 isn't guaranteed in the live corpus).
+
+test("shows OKH design detail (mocked)", async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === "real-api", "uses a fixture id");
+  await page.goto("/okh/okh-0001");
+  await expect(page.getByRole("heading", { name: "Open Ventilator" })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Design Info" })).toBeVisible();
+});
+
+test("validate surfaces a validation result (mocked)", async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === "real-api", "uses fixtures");
+  await page.goto("/okh/okh-0001");
+  await page.getByRole("button", { name: "Validate" }).click();
+  await expect(page.getByRole("heading", { name: "Validation" })).toBeVisible();
+  await expect(page.getByText(/Missing intended_use/)).toBeVisible();
+  await expect(page.getByText(/Add a bill of materials/)).toBeVisible();
+});

frontend/e2e/okw-catalog.spec.ts

@@ -0,0 +1,48 @@
+import { test, expect } from "./mock-api";
+import { okwSearchEmptyFixture } from "../src/test/fixtures";
+
+// Slice #188: read-only OKW facility catalog. Mocked lane covers the behavior;
+// the real-api lane runs the lenient "loads" check against the live corpus.
+
+test("facility catalog loads", async ({ page }) => {
+  await page.goto("/facilities");
+  await expect(
+    page.getByRole("heading", { name: /manufacturing facilities/i }),
+  ).toBeVisible();
+});
+
+test("shows fixture facilities with humanized processes (mocked)", async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === "real-api", "asserts fixture data");
+  await page.goto("/facilities");
+  await expect(page.getByRole("heading", { name: "Laser Fab Lab" })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Community Makerspace" })).toBeVisible();
+  // Wikipedia URI is humanized for display.
+  await expect(page.getByText("Laser Cutter")).toBeVisible();
+});
+
+test("filtering by access type narrows results (mocked)", async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === "real-api", "asserts fixture data");
+  await page.goto("/facilities");
+  await page.getByRole("button", { name: "Public", pressed: false }).click();
+  await expect(page.getByRole("heading", { name: "Community Makerspace" })).toBeVisible();
+  await expect(page.getByRole("heading", { name: "Laser Fab Lab" })).toBeHidden();
+});
+
+test("shows the empty state (mocked)", async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === "real-api", "forces an empty response");
+  await page.route("**/v1/api/okw/search**", (route) =>
+    route.fulfill({ json: okwSearchEmptyFixture }),
+  );
+  await page.goto("/facilities");
+  await expect(page.getByText(/no facilities/i)).toBeVisible();
+});
+
+test("shows the error state with retry (mocked)", async ({ page }, testInfo) => {
+  test.skip(testInfo.project.name === "real-api", "forces an error response");
+  await page.route("**/v1/api/okw/search**", (route) =>
+    route.fulfill({ status: 500, json: { message: "boom" } }),
+  );
+  await page.goto("/facilities");
+  await expect(page.getByRole("alert")).toBeVisible();
+  await expect(page.getByRole("button", { name: /retry/i })).toBeVisible();
+});

frontend/harness.config.json

@@ -7,5 +7,5 @@
   "apiPathPrefix": "/v1/api",
   "openapiUrl": "http://localhost:8001/v1/openapi.json",
   "apiTypesOutput": "src/api/generated/schema.d.ts",
-  "routesToScreenshot": ["/", "/okh", "/match"]
+  "routesToScreenshot": ["/", "/okh", "/okh/okh-0001", "/facilities", "/match"]
 }

frontend/package-lock.json

@@ -29,6 +29,7 @@
     "echarts": "^6.1.0",
     "echarts-for-react": "^3.0.2",
     "lucide-react": "^1.23.0",
+    "openapi-fetch": "^0.17.0",
     "react": "^19.0.0",
     "react-cytoscapejs": "^2.0.0",
     "react-dom": "^19.0.0",

frontend/package.json

@@ -3,6 +3,7 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { Layout } from "./components/layout/Layout";
 import { HomePage } from "./pages/HomePage";
 import { OkhPage } from "./pages/OkhPage";
+import { OkwPage } from "./pages/OkwPage";
 import { MatchPage } from "./pages/MatchPage";
 import { VisualizationPage } from "./pages/VisualizationPage";
 import { RfqPage } from "./pages/RfqPage";
@@ -31,6 +32,7 @@ export function App() {
               <Route index element={<HomePage />} />
               <Route path="okh" element={<OkhPage />} />
               <Route path="okh/:id" element={<OkhPage />} />
+              <Route path="facilities" element={<OkwPage />} />
               <Route path="match" element={<MatchPage />} />
               <Route path="visualization" element={<VisualizationPage />} />
               <Route path="visualization/:solutionId" element={<VisualizationPage />} />

frontend/src/App.tsx

@@ -0,0 +1,51 @@
+/**
+ * Typed OHM API client (module 1 of the frontend architecture).
+ *
+ * Built on `openapi-fetch` over the types generated from the backend OpenAPI
+ * spec (`src/api/generated/schema.d.ts`). Paths, query params, and response
+ * envelopes are type-checked against the real contract, so backend drift is a
+ * compile error. Per-domain wrappers (e.g. `okh.ts`) live alongside this and
+ * expose small, intention-revealing functions to the rest of the app.
+ *
+ * The generated `paths` are rooted at `/api/...`; the versioned app is mounted
+ * at `/v1` (proxied to the OHM API in dev), so the base URL is `/v1`.
+ */
+import createClient from "openapi-fetch";
+import type { paths } from "../generated/schema";
+
+// Absolute base so requests work identically in the browser (real origin +
+// dev-proxy) and in the node/jsdom test env, where undici's fetch rejects
+// relative URLs. In a browser this resolves to the current origin + /v1.
+const origin =
+  typeof window !== "undefined" && window.location?.origin
+    ? window.location.origin
+    : "http://localhost";
+
+export const apiClient = createClient<paths>({
+  baseUrl: `${origin}/v1`,
+  // Defer to the *current* global fetch on each call rather than the reference
+  // captured at module load, so test-time interceptors (MSW) that replace
+  // globalThis.fetch after import are honored. No-op difference in the browser.
+  fetch: (input) => globalThis.fetch(input),
+});
+
+/** Thrown by domain wrappers when a request fails; carries the HTTP status. */
+export class ApiError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+/** Best-effort human message from a JSON error body ({message} or {detail}). */
+export function errorMessage(body: unknown, fallback: string): string {
+  if (body && typeof body === "object") {
+    const b = body as { message?: unknown; detail?: unknown };
+    if (typeof b.message === "string") return b.message;
+    if (typeof b.detail === "string") return b.detail;
+  }
+  return fallback;
+}

frontend/src/api/ohm/client.ts

@@ -0,0 +1,52 @@
+import { http, HttpResponse } from "msw";
+import { describe, expect, it } from "vitest";
+import { server } from "../../test/msw/server";
+import { ApiError } from "./client";
+import { fetchOkhDetail, validateOkh } from "./okh";
+
+describe("fetchOkhDetail", () => {
+  it("returns the manifest for an id", async () => {
+    const okh = await fetchOkhDetail("okh-0001");
+    expect(okh.title).toBe("Open Ventilator");
+  });
+
+  it("throws ApiError on failure", async () => {
+    server.use(
+      http.get("*/v1/api/okh/:id", () =>
+        HttpResponse.json({ message: "not found" }, { status: 404 }),
+      ),
+    );
+    await expect(fetchOkhDetail("missing")).rejects.toMatchObject({
+      name: "ApiError",
+      status: 404,
+    });
+    await expect(fetchOkhDetail("missing")).rejects.toBeInstanceOf(ApiError);
+  });
+});
+
+describe("validateOkh", () => {
+  it("returns a validation result", async () => {
+    const res = await validateOkh({ title: "x" });
+    expect(res.is_valid).toBe(true);
+    expect(res.score).toBeCloseTo(0.92);
+  });
+
+  it("posts content in the body and quality/strict as query params", async () => {
+    let body: { content?: { title?: string } } | null = null;
+    let q: URLSearchParams | null = null;
+    server.use(
+      http.post("*/v1/api/okh/validate", async ({ request }) => {
+        body = (await request.json()) as { content?: { title?: string } };
+        q = new URL(request.url).searchParams;
+        return HttpResponse.json({ is_valid: true, score: 1 });
+      }),
+    );
+    await validateOkh(
+      { title: "Widget" },
+      { qualityLevel: "professional", strictMode: true },
+    );
+    expect(body!.content!.title).toBe("Widget");
+    expect(q!.get("quality_level")).toBe("professional");
+    expect(q!.get("strict_mode")).toBe("true");
+  });
+});

frontend/src/api/ohm/okh-detail.test.ts

@@ -0,0 +1,42 @@
+import { http, HttpResponse } from "msw";
+import { describe, expect, it } from "vitest";
+import { server } from "../../test/msw/server";
+import { ApiError } from "./client";
+import { fetchOkhList } from "./okh";
+
+describe("fetchOkhList", () => {
+  it("returns narrowed items and pagination from the paginated envelope", async () => {
+    const result = await fetchOkhList();
+    expect(result.items).toHaveLength(3);
+    expect(result.items.map((i) => i.title)).toContain("Open Ventilator");
+    expect(result.pagination.total_items).toBe(3);
+  });
+
+  it("passes paging/sort/filter as query params", async () => {
+    let captured: URLSearchParams | null = null;
+    server.use(
+      http.get("*/v1/api/okh", ({ request }) => {
+        captured = new URL(request.url).searchParams;
+        return HttpResponse.json({ items: [], pagination: { total_items: 0 } });
+      }),
+    );
+    await fetchOkhList({ page: 2, page_size: 10, sort_by: "title", sort_order: "asc", filter: "vent" });
+    expect(captured!.get("page")).toBe("2");
+    expect(captured!.get("page_size")).toBe("10");
+    expect(captured!.get("sort_by")).toBe("title");
+    expect(captured!.get("filter")).toBe("vent");
+  });
+
+  it("throws ApiError with the HTTP status on failure", async () => {
+    server.use(
+      http.get("*/v1/api/okh", () =>
+        HttpResponse.json({ message: "boom" }, { status: 503 }),
+      ),
+    );
+    await expect(fetchOkhList()).rejects.toMatchObject({
+      name: "ApiError",
+      status: 503,
+    });
+    await expect(fetchOkhList()).rejects.toBeInstanceOf(ApiError);
+  });
+});