Responsive mobile layout for CALM Hub UI

[rocketstack-matt]

Feature Proposal

Target Project:

CALM Hub UI (calm-hub-ui/)

Description of Feature:

CALM Hub UI is currently built for desktop viewports and does not render well on phones or tablet‑portrait screens. We should introduce a responsive layout so the Hub, the architecture/pattern diagram, the detail panels, and the version timeline/compare views are all usable on small screens, while leaving the desktop experience unchanged.

User Stories:

• As a mobile user, I want the navigation, content, and detail panels to adapt to my screen so that I can browse architectures without horizontal scrolling or overlapping panels.
• As a mobile user, I want the namespace/control tree to be reachable without it permanently consuming a quarter of my screen so that the content area gets the space it needs.
• As a mobile user, I want the architecture diagram to fill the viewport (without the minimap, search bar, and timeline crowding it out) so that I can actually read and interact with the nodes.
• As a mobile user, I want node/relationship details and the version timeline to open as focused, full‑width surfaces so that I can read them comfortably.
• As a desktop user, I want the existing layout to remain exactly as it is so that nothing regresses.

Current Limitations:

• Hub layout uses a rigid three‑column flex layout — tree navigation (w-1/4), main content (flex-1), and a details panel (w-96, 384px). On a phone the tree column collapses to an unusable ~90px and the three columns cannot physically fit together.
• Details panel (Sidebar) is a fixed 384px, wider than most phones.
• Global search input and dropdown can overflow the navbar/viewport on narrow screens.
• Section header breadcrumb + tabs use whitespace-nowrap and overflow horizontally.
• Architecture/pattern diagram: the minimap is oversized and overlaps the canvas, the node search/type‑filter bar floats across the top, and the version timeline occupies a permanent bottom strip — together leaving very little room for the actual graph on a short viewport.
• Compare view renders the two version graphs side‑by‑side, squeezing each into an unreadable ~190px column on mobile.

Proposed Implementation:

• Introduce a useMediaQuery / useIsMobile hook keyed to Tailwind's lg breakpoint (1024px); below it, switch to a mobile layout. Must be test‑safe (guard window.matchMedia).
• Hub: turn the tree navigation into an off‑canvas drawer (slide‑in with a dimmed backdrop, opened from an "Explore" button); make the details panel a full‑screen overlay. Keep the desktop three‑column layout for lg+.
• Diagram: hide the minimap on mobile (single and compare views), collapse the node search/type‑filter to a single expandable icon, and make the diagram tabs icon‑only.
• Timeline: tuck it behind a control (e.g. a floating button → bottom sheet) instead of permanently occupying the bottom of a short viewport.
• Compare view: stack the two version graphs vertically on mobile so each is legible.
• Header / search: allow the breadcrumb and tabs to wrap; make the global search input and dropdown viewport‑bounded.
• Ensure URL deep‑links and global‑search navigation still load data on mobile (the data‑loading lifecycle must not be coupled to a component that is only mounted on desktop).

Alternatives Considered:

• CSS‑only responsive tweaks (no JS breakpoint): insufficient — the drawer/overlay behaviour and conditional rendering of the minimap/timeline need component logic, not just utility classes.
• A separate mobile route/app: rejected as high‑maintenance duplication; a single responsive layout keeps one codebase and one set of routes.
• Leaving the diagram as‑is and only fixing the shell: rejected — testing shows the diagram itself (minimap/search/timeline clutter) is the biggest mobile pain point.

Testing Strategy:

• Unit tests (Vitest + React Testing Library) for the useMediaQuery/useIsMobile hook and for the Hub's mobile drawer open/close behaviour (with a mocked matchMedia).
• Keep the existing desktop‑oriented tests green (default matchMedia → desktop).
• Manual verification at representative widths (≈390px phone, tablet‑portrait, desktop) across: Hub browse, architecture diagram, node/relationship detail, JSON tab, version timeline, and the compare view.

Documentation Requirements:

• Update calm-hub-ui/AGENTS.md if new conventions (e.g. the media‑query hook) are introduced.

Implementation Checklist:

• Design reviewed and approved
• Implementation completed
• Tests written and passing
• Documentation updated
• Relevant workflows updated (if needed)
• Performance impact assessed

Additional Context:

Affects only calm-hub-ui/. Desktop behaviour should be unchanged; all changes gate on the mobile breakpoint.

[rocketstack-matt]

Closing — this proposal should be tracked in the upstream finos/architecture-as-code repository, not this fork. The full proposal content above can be reused when filing it upstream.

---

Generated by Claude Code