feat(frontend): Phase 3 Information Architecture + Search — close UX-H1 + FE-H2 + UX-M5 + UX-H6 + FE-L4; FE-M6 deferred

Phase 3 of the frontend-design audit: information architecture + search.
Layout.tsx rewritten once for BOTH grouped-sidebar (UX-H1) AND lucide-
react icon migration (FE-H2). Breadcrumbs primitive added + wired into
PageHeader. cmd+k command palette mounted globally via cmdk. FE-M6
(drop unsafe-inline from CSP style-src) deferred — the audit's framing
was incomplete.

New / changed
=============

  web/src/components/Layout.tsx (rewrite — UX-H1 + FE-H2 + FE-L4)
    Pre: flat 31-item nav array with literal SVG path-string icons.
    Post: 7 semantic groups (Inventory / Trust / Delivery / People /
    Notify / Access / Audit) of 31 NavLinks total; lucide-react
    icon components replace every path string (27 named imports);
    collapsible per-group state persisted to localStorage
    (`certctl:nav:collapsed-groups`); aria-expanded / aria-controls
    on each group header; the existing Setup-guide button and Sign-
    out button kept verbatim. Logout icon swapped from inline SVG to
    lucide `LogOut`.

  web/src/components/Breadcrumbs.tsx (new — UX-M5)
    Walks the current pathname via useLocation() + a static
    pathSegmentLabels map. Renders <nav aria-label="Breadcrumb"> + an
    ol of links + a terminal aria-current="page" span. Renders
    nothing on the dashboard root. 8 sibling tests in
    Breadcrumbs.test.tsx pin: root → no nav; top-level → Home + Page;
    detail → Home + List + Detail; 3-deep /issuers/:id/hierarchy →
    Home + Issuers + Detail + Hierarchy; /auth/* uses
    authSubsegmentLabels; terminal crumb is aria-current=page; nav
    has aria-label=Breadcrumb.

  web/src/components/PageHeader.tsx (1-line wire-in)
    Renders <Breadcrumbs /> above the page title. Backward-
    compatible — pages without a breadcrumbed pathname see no extra
    chrome.

  web/src/components/CommandPalette.tsx (new — UX-H6)
    cmdk-driven palette with three sections:
      1. Navigation — flattened view of Layout's 31 nav items, kept
         in sync by hand at NAV_COMMANDS.
      2. Actions — quick-fire ops not bound to a route (Issue new
         certificate / Create issuer / Trigger discovery scan).
      3. Server-search — debounced (250ms) fetch against
         getCertificates({ q }) + getIssuers({ q }) for typeahead
         across cert common-names + issuer names. Hidden when query
         < 2 chars; silently degrades to no-results on fetch error.

  web/src/components/CommandPaletteHost.tsx (new — FE-L4)
    Thin host owning open/close state + the global keydown listener
    (meta+k on macOS, ctrl+k everywhere else). Lazy-loads the
    palette via React.lazy so cmdk's bundle (~25 KB) only lands
    when the operator first hits cmd+k. Mounted inside BrowserRouter
    so useNavigate() resolves.

Audit-accuracy callouts
=======================

  1. UX-H1 wording was FACTUALLY WRONG. The audit's "/auth/* completely
     absent from primary nav" claim is incorrect — verified against
     web/src/components/Layout.tsx top-to-bottom that all 8 /auth/*
     entries AND /audit were already in the array. The actual issue
     was UNGROUPED, not absent. Phase 3's value-add is the
     hierarchical regrouping, not surfacing new routes. Restated in
     the file header comment.

  2. FE-M6 deferred — audit framing was too narrow. The CSP comment
     in internal/api/middleware/securityheaders.go::35 says
     `unsafe-inline` exists for "Tailwind (via Vite) injects per-
     component <style> blocks at build time", NOT for the 31 inline
     SVG attributes the audit cited. Even after FE-H2 removes the
     Layout.tsx SVGs, there are 17 production tsx files with React
     `style={...}` attributes that still emit inline styles in the
     rendered HTML (Tooltip, AgentFleetPage, UsersPage, etc.).
     Tightening the CSP needs every one of those migrated to
     utility classes or CSS custom properties — significantly
     larger scope than this phase. Tracked as Phase 4+ follow-up.

  3. UX-M5 implementation pivot. The audit prompt suggested
     useMatches() + per-route handle.crumb. That API only works
     under React Router v6's data-router (createBrowserRouter); the
     certctl app currently uses the JSX <BrowserRouter> form, and
     migrating the router is a phase-sized effort on its own.
     Pivoted to useLocation() + a static pathSegmentLabels map.
     Works under BrowserRouter; same visual + a11y output;
     limitation noted in Breadcrumbs.tsx header so a future
     router migration can upgrade in place.

Verification
============

  $ npx tsc --noEmit
    (exit 0)

  $ npx vitest run src/components/Layout.test.tsx src/components/Breadcrumbs.test.tsx
    Test Files  2 passed (2)
         Tests  15 passed (15)
    (Layout's 7 existing tests pass without modification — Setup
    guide / Users testid / Sessions-precedes-Users DOM order all
    preserved. Breadcrumbs ships with 8 new assertions.)

  $ npx vite build
    ✓ built in 3.58s
    (bundle grows ~25 KB from lucide-react + cmdk; cmdk lazy-loaded
    so it doesn't land on initial page load)

  $ grep -nE "navGroups|label: 'Access'|from 'lucide-react'|cmdk" \
       web/src --type tsx --type ts -r | grep -v test
    (15+ hits across Layout / Breadcrumbs / CommandPalette / Host)

  $ grep -cE "icon: '" web/src/components/Layout.tsx
    0    (was 31 path strings; now all replaced with lucide imports)

  $ ls web/src/components/{Breadcrumbs,CommandPalette,CommandPaletteHost}.tsx
    (all three new files exist)

Residual risks
==============

  * The 14-ish inline SVGs in other pages (DashboardPage, ErrorState,
    DataTable, JobsPage, CertificateDetailPage, OnboardingWizard)
    still ship as raw <svg> markup. They're decorative — not
    blocking — but the icon-library migration is incomplete. Next
    per-page touches should replace them with lucide imports.
  * CommandPalette's server-search hits `getCertificates({ q })` +
    `getIssuers({ q })` — whether the Go handlers honour the `q`
    parameter is not verified in this commit. If they ignore it,
    the palette returns the first page unfiltered (acceptable for
    now; the navigation + actions sections work regardless).
  * The Layout's NAV_COMMANDS table in CommandPalette.tsx duplicates
    the navGroups array in Layout.tsx by hand. A future small
    refactor could move both behind a shared `web/src/config/nav.ts`.
  * useMatches()-driven breadcrumb data (the audit's preferred
    pattern) stays a future task — triggers on router migration.
This commit is contained in:
shankar0123
2026-05-14 15:27:23 +00:00
parent 1daae5d709
commit e761ae40a4
9 changed files with 1446 additions and 74 deletions
+2
View File
@@ -19,6 +19,8 @@
"@fontsource/jetbrains-mono": "^5.2.8",
"@headlessui/react": "^2.2.10",
"@tanstack/react-query": "^5.90.21",
"cmdk": "^1.1.1",
"lucide-react": "^1.16.0",
"react": "^18.3.1",
"react-dom": "^18.3.1",
"react-router-dom": "^6.30.3",