From 175e62f514f3f37bbd7994c9a38e729d5c2ff7c2 Mon Sep 17 00:00:00 2001 From: hsiegeln <37154749+hsiegeln@users.noreply.github.com> Date: Sat, 28 Mar 2026 15:51:37 +0100 Subject: [PATCH] docs: update navigation redesign spec to reflect final implementation --- .../2026-03-28-navigation-redesign-design.md | 141 ++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 docs/superpowers/specs/2026-03-28-navigation-redesign-design.md diff --git a/docs/superpowers/specs/2026-03-28-navigation-redesign-design.md b/docs/superpowers/specs/2026-03-28-navigation-redesign-design.md new file mode 100644 index 00000000..32480344 --- /dev/null +++ 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