From 5cc03462841663f1cead07d3a0801ea1ddb32795 Mon Sep 17 00:00:00 2001
From: ololadedavidvictor-bit <ololadedavidvictor@gmail.com>
Date: Tue, 28 Jul 2026 17:13:06 +0000
Subject: [PATCH] feat: add LatencyChart page with HelpPopover for P95 metric
 explanation

- Create src/pages/LatencyChart.tsx with responsive bar chart and stat cards
- Integrate HelpPopover next to chart title explaining P95 latency for first-time users
- Add className prop to HelpPopover for layout alignment flexibility
- Include LatencyChart.test.tsx with focused accessibility and rendering tests
- Update HelpPopover.test.tsx to cover className forwarding
- Add page-specific CSS and focus-visible styles in index.css and focus.css
- Register /latency-chart route in main.tsx
---
 src/components/HelpPopover.test.tsx |  10 ++
 src/components/HelpPopover.tsx      |   8 +-
 src/index.css                       | 141 +++++++++++++++++++++++++
 src/main.tsx                        |   6 ++
 src/pages/LatencyChart.test.tsx     |  94 +++++++++++++++++
 src/pages/LatencyChart.tsx          | 158 ++++++++++++++++++++++++++++
 src/styles/focus.css                |   9 ++
 7 files changed, 425 insertions(+), 1 deletion(-)
 create mode 100644 src/pages/LatencyChart.test.tsx
 create mode 100644 src/pages/LatencyChart.tsx

diff --git a/src/components/HelpPopover.test.tsx b/src/components/HelpPopover.test.tsx
index 5d34028..e08c063 100644
--- a/src/components/HelpPopover.test.tsx
+++ b/src/components/HelpPopover.test.tsx
@@ -109,4 +109,14 @@ describe("HelpPopover", () => {
     const btn = screen.getByRole("button", { name: "Help" });
     expect(btn.className).toContain("help-popover-trigger");
   });
+
+  it("forwards an additional className to the trigger button", () => {
+    render(
+      <HelpPopover content="Class test" className="custom-class" />
+    );
+
+    const btn = screen.getByRole("button", { name: "Help" });
+    expect(btn.className).toContain("help-popover-trigger");
+    expect(btn.className).toContain("custom-class");
+  });
 });
diff --git a/src/components/HelpPopover.tsx b/src/components/HelpPopover.tsx
index 601beed..e4f056e 100644
--- a/src/components/HelpPopover.tsx
+++ b/src/components/HelpPopover.tsx
@@ -54,12 +54,18 @@ type HelpPopoverProps = {
    * @default 300
    */
   hoverDelayMs?: number;
+  /**
+   * Additional CSS class forwarded to the trigger button.
+   * Useful for layout alignment in page headers (e.g. LatencyChart).
+   */
+  className?: string;
 };
 
 export default function HelpPopover({
   content,
   ariaLabel = "Help",
   hoverDelayMs = 300,
+  className,
 }: HelpPopoverProps): JSX.Element {
   const labelId = useId();
 
@@ -67,7 +73,7 @@ export default function HelpPopover({
     <Tooltip content={content} hoverDelayMs={hoverDelayMs}>
       <button
         type="button"
-        className="help-popover-trigger"
+        className={`help-popover-trigger${className ? ` ${className}` : ""}`}
         aria-label={ariaLabel}
         aria-describedby={labelId}
         style={{
diff --git a/src/index.css b/src/index.css
index 1b3ba58..5445ed9 100644
--- a/src/index.css
+++ b/src/index.css
@@ -6938,4 +6938,145 @@ code,
   }
 }
 
+/* ── LatencyChart page (GrantFox FWC26) ───────────────────────────────────────
+   Responsive latency dashboard with bar chart and HelpPopover. Uses design
+   tokens for light/dark mode consistency. */
+.latency-chart-page {
+  display: grid;
+  gap: 24px;
+  padding: 20px;
+  max-width: 1180px;
+  margin: 0 auto;
+}
+
+.latency-chart-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+
+.latency-chart-title-group {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.latency-chart-title-group h1 {
+  margin: 0;
+  font-size: clamp(1.75rem, 3vw, 2.35rem);
+  line-height: 1.1;
+}
+
+.latency-chart-subtitle {
+  color: var(--muted);
+  font-size: 0.875rem;
+}
+
+.latency-stats-grid {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 16px;
+}
+
+.latency-stat-card {
+  padding: 18px;
+  border-radius: var(--radius-lg);
+  border: 1px solid rgba(169, 184, 255, 0.12);
+  background: var(--surface-soft);
+}
+
+.latency-stat-label {
+  display: block;
+  margin-bottom: 10px;
+  color: var(--muted);
+  font-size: 0.9rem;
+}
+
+.latency-stat-value {
+  display: block;
+  font-size: 1.35rem;
+}
+
+.latency-chart-container {
+  margin-top: 24px;
+  padding: 20px;
+  border-radius: var(--radius-lg);
+  border: 1px solid var(--line);
+  background: var(--surface-soft);
+  min-height: 260px;
+}
+
+.latency-chart-bars {
+  display: flex;
+  align-items: flex-end;
+  gap: 8px;
+  height: 220px;
+}
+
+.latency-chart-bar-wrapper {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 0;
+}
+
+.latency-chart-bar {
+  width: 100%;
+  max-width: 48px;
+  border-radius: 6px 6px 0 0;
+  background: linear-gradient(180deg, var(--accent), color-mix(in srgb, var(--accent) 70%, var(--accent-strong)));
+  transition: opacity 180ms ease;
+  cursor: pointer;
+}
+
+.latency-chart-bar--peak {
+  background: linear-gradient(180deg, var(--danger), color-mix(in srgb, var(--danger) 70%, var(--warning)));
+}
+
+.latency-chart-bar-label {
+  font-size: 0.75rem;
+  color: var(--muted);
+  text-align: center;
+  white-space: nowrap;
+}
+
+.latency-chart-caption {
+  margin: 12px 0 0;
+  color: var(--muted);
+  font-size: 0.875rem;
+  line-height: 1.5;
+}
+
+@media (max-width: 768px) {
+  .latency-stats-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .latency-chart-bars {
+    gap: 4px;
+  }
+
+  .latency-chart-bar-label {
+    font-size: 0.65rem;
+  }
+}
+
+@media (max-width: 480px) {
+  .latency-chart-page {
+    padding: 14px;
+  }
+
+  .latency-stats-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .latency-chart-bars {
+    height: 160px;
+  }
+}
+
 
diff --git a/src/main.tsx b/src/main.tsx
index a41c1fa..f3144a9 100644
--- a/src/main.tsx
+++ b/src/main.tsx
@@ -14,6 +14,7 @@ import { ThemeProvider } from "./ThemeContext";
 import { CollectionsProvider } from "./state/collectionsStore";
 import MarketplacePageSkeleton from "./pages/MarketplacePage.skeleton";
 import ApiDetailPageSkeleton from "./pages/ApiDetailPage.skeleton";
+import LatencyChart from "./pages/LatencyChart";
 
 const root = ReactDOM.createRoot(document.getElementById("root")!);
 
@@ -74,6 +75,11 @@ async function renderRoute() {
     return;
   }
 
+  if (pathname.startsWith("/latency-chart")) {
+    root.render(wrap(<LatencyChart />));
+    return;
+  }
+
   // Default: render the existing App
   root.render(
     <React.StrictMode>
diff --git a/src/pages/LatencyChart.test.tsx b/src/pages/LatencyChart.test.tsx
new file mode 100644
index 0000000..6f962b0
--- /dev/null
+++ b/src/pages/LatencyChart.test.tsx
@@ -0,0 +1,94 @@
+// @vitest-environment jsdom
+
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { MemoryRouter } from "react-router-dom";
+import LatencyChart from "./LatencyChart";
+
+afterEach(cleanup);
+
+function renderChart() {
+  return render(
+    <MemoryRouter>
+      <LatencyChart />
+    </MemoryRouter>
+  );
+}
+
+describe("LatencyChart Page (#714)", () => {
+  it("renders the page title and breadcrumb", () => {
+    renderChart();
+
+    expect(screen.getByRole("heading", { name: "Latency" })).toBeTruthy();
+    expect(screen.getByText("Dashboard")).toBeTruthy();
+    expect(screen.getByText("Last 24 hours")).toBeTruthy();
+  });
+
+  it("renders the HelpPopover with an accessible label explaining P95 latency", async () => {
+    renderChart();
+
+    const helpBtn = screen.getByRole("button", { name: "Help: What is P95 latency?" });
+    expect(helpBtn).toBeTruthy();
+
+    fireEvent.focus(helpBtn);
+
+    await waitFor(() => {
+      const tooltip = screen.getByRole("tooltip");
+      expect(tooltip).toBeTruthy();
+      expect(tooltip).toHaveTextContent("P95 Latency");
+      expect(tooltip).toHaveTextContent("95th percentile response time");
+    });
+  });
+
+  it("renders stat cards for min, avg, P95, and max", () => {
+    renderChart();
+
+    expect(screen.getByText("Min")).toBeTruthy();
+    expect(screen.getByText("Avg")).toBeTruthy();
+    expect(screen.getByText("P95")).toBeTruthy();
+    expect(screen.getByText("Max")).toBeTruthy();
+  });
+
+  it("renders the correct latency values in stat cards", () => {
+    renderChart();
+
+    const minValue = screen.getByText("88 ms");
+    const maxValue = screen.getByText("210 ms");
+    const avgValue = screen.getByText("152 ms");
+    const p95Value = screen.getByText("200 ms");
+    expect(minValue).toBeTruthy();
+    expect(maxValue).toBeTruthy();
+    expect(avgValue).toBeTruthy();
+    expect(p95Value).toBeTruthy();
+  });
+
+  it("renders the latency chart bars with accessible labels", () => {
+    renderChart();
+
+    const bars = screen.getAllByRole("img", { name: /ms/ });
+    expect(bars.length).toBeGreaterThan(0);
+  });
+
+  it("renders the chart caption for screen reader context", () => {
+    renderChart();
+
+    expect(screen.getByText(/Bars represent sampled response times/)).toBeTruthy();
+  });
+
+  it("dismisses the HelpPopover tooltip on Escape", async () => {
+    renderChart();
+
+    const helpBtn = screen.getByRole("button", { name: "Help: What is P95 latency?" });
+    fireEvent.focus(helpBtn);
+
+    await waitFor(() => {
+      expect(screen.getByRole("tooltip")).toBeTruthy();
+    });
+
+    fireEvent.keyDown(document, { key: "Escape" });
+
+    await waitFor(() => {
+      expect(screen.queryByRole("tooltip")).toBeNull();
+    });
+  });
+});
diff --git a/src/pages/LatencyChart.tsx b/src/pages/LatencyChart.tsx
new file mode 100644
index 0000000..f04aa86
--- /dev/null
+++ b/src/pages/LatencyChart.tsx
@@ -0,0 +1,158 @@
+import { useMemo } from "react";
+import Breadcrumb from "../components/Breadcrumb";
+import HelpPopover from "../components/HelpPopover";
+
+type LatencyPoint = {
+  label: string;
+  value: number;
+  timestamp: Date;
+};
+
+const MOCK_DATA: LatencyPoint[] = [
+  { label: "00:00", value: 120, timestamp: new Date(Date.now() - 24 * 60 * 60 * 1000) },
+  { label: "01:00", value: 115, timestamp: new Date(Date.now() - 23 * 60 * 60 * 1000) },
+  { label: "02:00", value: 95, timestamp: new Date(Date.now() - 22 * 60 * 60 * 1000) },
+  { label: "03:00", value: 88, timestamp: new Date(Date.now() - 21 * 60 * 60 * 1000) },
+  { label: "04:00", value: 92, timestamp: new Date(Date.now() - 20 * 60 * 60 * 1000) },
+  { label: "05:00", value: 105, timestamp: new Date(Date.now() - 19 * 60 * 60 * 1000) },
+  { label: "06:00", value: 145, timestamp: new Date(Date.now() - 18 * 60 * 60 * 1000) },
+  { label: "07:00", value: 160, timestamp: new Date(Date.now() - 17 * 60 * 60 * 1000) },
+  { label: "08:00", value: 210, timestamp: new Date(Date.now() - 16 * 60 * 60 * 1000) },
+  { label: "09:00", value: 195, timestamp: new Date(Date.now() - 15 * 60 * 60 * 1000) },
+  { label: "10:00", value: 180, timestamp: new Date(Date.now() - 14 * 60 * 60 * 1000) },
+  { label: "11:00", value: 175, timestamp: new Date(Date.now() - 13 * 60 * 60 * 1000) },
+  { label: "12:00", value: 185, timestamp: new Date(Date.now() - 12 * 60 * 60 * 1000) },
+  { label: "13:00", value: 170, timestamp: new Date(Date.now() - 11 * 60 * 60 * 1000) },
+  { label: "14:00", value: 168, timestamp: new Date(Date.now() - 10 * 60 * 60 * 1000) },
+  { label: "15:00", value: 165, timestamp: new Date(Date.now() - 9 * 60 * 60 * 1000) },
+  { label: "16:00", value: 190, timestamp: new Date(Date.now() - 8 * 60 * 60 * 1000) },
+  { label: "17:00", value: 200, timestamp: new Date(Date.now() - 7 * 60 * 60 * 1000) },
+  { label: "18:00", value: 195, timestamp: new Date(Date.now() - 6 * 60 * 60 * 1000) },
+  { label: "19:00", value: 175, timestamp: new Date(Date.now() - 5 * 60 * 60 * 1000) },
+  { label: "20:00", value: 155, timestamp: new Date(Date.now() - 4 * 60 * 60 * 1000) },
+  { label: "21:00", value: 140, timestamp: new Date(Date.now() - 3 * 60 * 60 * 1000) },
+  { label: "22:00", value: 130, timestamp: new Date(Date.now() - 2 * 60 * 60 * 1000) },
+  { label: "23:00", value: 125, timestamp: new Date(Date.now() - 1 * 60 * 60 * 1000) },
+  { label: "Now", value: 120, timestamp: new Date() },
+];
+
+function computeStats(data: LatencyPoint[]) {
+  const values = data.map((d) => d.value);
+  const min = Math.min(...values);
+  const max = Math.max(...values);
+  const avg = Math.round(values.reduce((a, b) => a + b, 0) / values.length);
+  const sorted = [...values].sort((a, b) => a - b);
+  const p95Index = Math.ceil(sorted.length * 0.95) - 1;
+  const p95 = sorted[Math.max(0, p95Index)];
+  return { min, max, avg, p95 };
+}
+
+export default function LatencyChart() {
+  const stats = useMemo(() => computeStats(MOCK_DATA), []);
+  const maxValue = useMemo(() => Math.max(...MOCK_DATA.map((d) => d.value)), []);
+
+  return (
+    <div className="latency-chart-page">
+      <Breadcrumb
+        items={[
+          { label: "Dashboard", href: "/dashboard" },
+          {
+            label: "Latency",
+            href: "/latency-chart",
+            isCurrent: true,
+          },
+        ]}
+      />
+
+      <div className="surface latency-chart-surface">
+        <div className="latency-chart-header">
+          <div className="latency-chart-title-group">
+            <h1>Latency</h1>
+            <HelpPopover
+              content={
+                <span>
+                  <strong style={{ display: "block", marginBottom: "0.25rem" }}>
+                    P95 Latency
+                  </strong>
+                  <span style={{ display: "block" }}>
+                    The 95th percentile response time. 95% of requests complete
+                    faster than this value; the remaining 5% are slower.
+                  </span>
+                  <span
+                    style={{
+                      display: "block",
+                      marginTop: "0.25rem",
+                      opacity: 0.85,
+                    }}
+                  >
+                    Lower is better — aim for under 200 ms for a smooth
+                    experience.
+                  </span>
+                </span>
+              }
+              ariaLabel="Help: What is P95 latency?"
+            />
+          </div>
+          <span className="latency-chart-subtitle">Last 24 hours</span>
+        </div>
+
+        <div className="latency-stats-grid">
+          <div className="latency-stat-card">
+            <span className="latency-stat-label">Min</span>
+            <strong className="latency-stat-value tabular-nums">
+              {stats.min} ms
+            </strong>
+          </div>
+          <div className="latency-stat-card">
+            <span className="latency-stat-label">Avg</span>
+            <strong className="latency-stat-value tabular-nums">
+              {stats.avg} ms
+            </strong>
+          </div>
+          <div className="latency-stat-card">
+            <span className="latency-stat-label">P95</span>
+            <strong className="latency-stat-value tabular-nums">
+              {stats.p95} ms
+            </strong>
+          </div>
+          <div className="latency-stat-card">
+            <span className="latency-stat-label">Max</span>
+            <strong className="latency-stat-value tabular-nums">
+              {stats.max} ms
+            </strong>
+          </div>
+        </div>
+
+        <div className="latency-chart-container" role="img" aria-label="Latency bar chart showing response times over the last 24 hours">
+          <div className="latency-chart-bars">
+            {MOCK_DATA.map((point, idx) => {
+              const heightPct = (point.value / maxValue) * 100;
+              const isHighest = point.value === maxValue;
+              return (
+                <div
+                  key={idx}
+                  className={`latency-chart-bar-wrapper`}
+                  style={{ flex: 1 }}
+                >
+                  <div
+                    className={`latency-chart-bar${isHighest ? " latency-chart-bar--peak" : ""}`}
+                    style={{ height: `${heightPct}%` }}
+                    title={`${point.label}: ${point.value} ms`}
+                    role="img"
+                    aria-label={`${point.label}: ${point.value} ms`}
+                  />
+                  <span className="latency-chart-bar-label">{point.label}</span>
+                </div>
+              );
+            })}
+          </div>
+        </div>
+
+        <p className="latency-chart-caption">
+          Bars represent sampled response times. The tallest bar marks the
+          highest observed latency in the window.
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/src/styles/focus.css b/src/styles/focus.css
index a357c0b..f11039e 100644
--- a/src/styles/focus.css
+++ b/src/styles/focus.css
@@ -346,6 +346,15 @@
     outline: 2px solid var(--accent);
     outline-offset: 2px;
   }
+
+  /* ── LatencyChart focus-visible overrides ────────────────────────────
+     Chart bars are interactive elements that receive pointer + keyboard
+     events. They need a visible focus ring for WCAG 2.4.7. */
+  .latency-chart-page .latency-chart-bar:focus-visible {
+    outline: 2px solid var(--accent);
+    outline-offset: 2px;
+    background: var(--accent);
+  }
 }
 
 /* ── reduced-motion: suppress transition on focus for ApiUsage controls ── */