docs: update navigation redesign spec to reflect final implementation

2026-03-28 15:51:37 +01:00
parent b4c9be9334
commit 175e62f514
1 changed files with 141 additions and 0 deletions
--- a/docs/superpowers/specs/2026-03-28-navigation-redesign-design.md
+++ b/docs/superpowers/specs/2026-03-28-navigation-redesign-design.md
@@ -0,0 +1,141 @@
+# Navigation Redesign: Persona-Driven Layout
+
+## Status: Implemented (2026-03-28)
+
+## Context
+
+The Cameleer3 UI was redesigned from page-based routing to a scope-based model with three content tabs. The Process Diagram is the major USP for the Apache Camel community.
+
+## Core Model
+
+**Sidebar scopes WHERE** (app -> route hierarchy), **content tabs switch WHAT** (Exchanges | Dashboard | Runtime).
+
+## Layout Shell
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ TopBar: [All > order-svc > route-a]  [Cmd+K]  [filters]  [user]           │
+├───────────┬──────────────────────────────────────────────────────────────────┤
+│ Sidebar   │ [ Exchanges | Dashboard | Runtime ]   TOTAL 443↑ ERR% 0.0%↓  │
+│           ├──────────────────────────────────────────────────────────────────┤
+│ Apps      │                                                                │
+│ ● app-1   │ Content area (layout varies by tab + selection)               │
+│ ◐ app-2   │                                                                │
+│ ▾ app-3   │                                                                │
+│   route-a │                                                                │
+│   route-b │                                                                │
+│           │                                                                │
+│ ⚙ Admin   │                                                                │
+└───────────┴──────────────────────────────────────────────────────────────────┘
+```
+
+## Sidebar
+
+Simplified to **app -> route** hierarchy only. No agents (accessible via Runtime tab). Sidebar clicks act as scope filters via event interception (`display: contents` wrapper intercepts Link clicks and re-routes through current tab).
+
+## Scope Trail
+
+Integrated into the TopBar breadcrumb (not a separate component). Shows: `All Applications > appId > routeId`.
+
+## Tab Bar with Inline KPIs
+
+Content tabs (Exchanges | Dashboard | Runtime) rendered using design system `Tabs` component. Right-aligned compact KPI metrics show: Total, Err%, Avg, P99 — each with trend arrow (green=good, red=bad) computed from `useExecutionStats`. KPIs are scope-aware.
+
+## Tab: Exchanges (Primary USP)
+
+### Full-width mode (no exchange selected)
+
+Exchange table (DataTable from design system) with search, sort, filter. No KPI strip (metrics are in the tab bar). Clicking a row selects the exchange via local state (not URL navigation — preserves search scope).
+
+### Split mode (exchange selected)
+
+Draggable 50:50 split (20%-80% range, amber highlight on drag):
+
+```
+┌──────────────────────┬───────────────────────────────────────┐
+│ Exchange Table       │ Exchange Header                       │
+│ (same DataTable,     │  status | attrs | app route | agent   │
+│  search preserved)   │ Correlated Exchanges (chain)          │
+│                      ├───────────────────────────────────────┤
+│                      │ Process Diagram (execution overlay)   │
+│                      │  + minimap (bottom-right, above zoom) │
+│                      ├───────────────────────────────────────┤
+│                      │ Detail Panel (tabs)                   │
+│                      │  Info|Headers|Input|Output|Error|     │
+│                      │  Config|Timeline|Log                  │
+└──────────────────────┴───────────────────────────────────────┘
+```
+
+**Exchange Header** features:
+- Status dot + badge + tap-collected attribute badges (consistent color via value hash)
+- Clickable app name (resets to app scope), route name + GitBranch icon (resets to route scope)
+- Clickable agent name + ID + Server icon (colored by agent state: green/yellow/red) -> agent pages
+- Correlation chain with StatusDot per node, route name + duration, arrow connectors, total duration (far right)
+- Clicking a correlated exchange switches the diagram via local state
+- Clicking app/route clears the selection (returns to full-width table)
+
+**Browser history integration:**
+- Each exchange selection pushes a history entry with the selection in `location.state`
+- Back/Forward restores the exact selection state (split view reappears)
+- Navigating to agent details and pressing Back returns to the diagram
+
+**Detail Panel tabs:** Info, Headers (sorted alphabetically), Input, Output, Error, Config, Timeline, **Log** (new — shows exchange logs filtered by processor when selected).
+
+## Tab: Dashboard
+
+Wraps existing pages: RoutesMetrics (no route scope) or RouteDetail (route scoped).
+
+## Tab: Runtime
+
+Wraps existing pages: AgentHealth (no agent scope) or AgentInstance (agent selected).
+
+## Admin
+
+Gear icon in sidebar footer. Unchanged tab-based layout (RBAC, Audit, OIDC, AppConfig, DB, OpenSearch).
+
+## URL Structure
+
+```
+/exchanges                    -> Exchanges tab, no scope
+/exchanges/:appId             -> Exchanges tab, app-scoped
+/exchanges/:appId/:routeId    -> Exchanges tab, route-scoped
+/dashboard                    -> Dashboard tab
+/dashboard/:appId             -> Dashboard tab, app-scoped
+/dashboard/:appId/:routeId    -> Dashboard tab, route-scoped
+/runtime                      -> Runtime tab
+/runtime/:appId               -> Runtime tab, app-scoped
+/runtime/:appId/:instanceId   -> Runtime tab, agent detail
+/admin/*                      -> Admin (unchanged)
+/apps/*, /agents/*            -> Legacy redirects to new paths
+```
+
+Default `/` redirects to `/exchanges`.
+
+## Key Implementation Files
+
+| File | Purpose |
+|------|---------|
+| `ui/src/hooks/useScope.ts` | URL scope parsing + navigation helpers |
+| `ui/src/components/ContentTabs.tsx` | Tab bar with inline KPIs |
+| `ui/src/components/TabKpis.tsx` | Compact KPI metrics (Total, Err%, Avg, P99) |
+| `ui/src/components/LayoutShell.tsx` | Shell with sidebar interception, scope trail, tabs |
+| `ui/src/pages/Exchanges/ExchangesPage.tsx` | Full-width / split orchestrator with history state |
+| `ui/src/pages/Exchanges/ExchangeHeader.tsx` | Exchange info bar + correlation chain |
+| `ui/src/pages/Dashboard/Dashboard.tsx` | Exchange table (accepts `onExchangeSelect` callback) |
+| `ui/src/pages/RuntimeTab/RuntimePage.tsx` | AgentHealth / AgentInstance wrapper |
+| `ui/src/pages/DashboardTab/DashboardPage.tsx` | RoutesMetrics / RouteDetail wrapper |
+| `ui/src/utils/attribute-color.ts` | Deterministic badge color from value hash |
+| `ui/src/components/ExecutionDiagram/tabs/LogTab.tsx` | Log tab for detail panel |
+| `ui/src/router.tsx` | Tab-based routes + legacy redirects |
+
+## What Differentiates from njams
+
+1. **Three-tab model** — njams interleaves everything; Cameleer3 separates concerns
+2. **Inline KPI metrics** — compact stats in the tab bar with trend indicators
+3. **State-based selection** — exchange selection via local state, not URL navigation (preserves search)
+4. **Browser history integration** — Back/Forward restores exchange selection
+5. **Scope-based sidebar** — filters rather than navigates
+6. **Runtime tab** — dedicated agent monitoring
+7. **Draggable split** — resizable divider between table and diagram
+8. **Correlation chain** — arrow-connected nodes with route names, durations, total duration
+9. **Attribute badges** — consistent colors across all views via value hash