feat(calm-hub-ui): adding detailed architecture navigation (finos#2799)

* feat(calm-hub-ui): adding detailed architecture navigation

* feat(calm-hub-ui): adding resource type to not found error message

* fix(calm-hub-ui): don't advertise node drill-down for unresolvable detailed-architecture refs

* fix(calm-hub-ui): guard success callbacks against stale loads after navigation

* fix(calm-hub-ui): widen the immediate-parent breadcrumb cap to 12rem

Author: lbulanti-ms

calm-hub-ui/src/hub/Hub.test.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { render, screen, fireEvent, act } from '@testing-library/react';
-import { MemoryRouter, useNavigate } from 'react-router-dom';
+import { MemoryRouter, useLocation, useNavigate } from 'react-router-dom';
 import Hub from './Hub.js';
 import { vi, describe, it, expect, afterEach, beforeEach } from 'vitest';
 import { authStore } from '../service/utils/auth-store.js';
@@ -131,10 +131,44 @@ vi.mock('../components/navbar/Navbar', () => ({
     Navbar: () => <nav data-testid="navbar">Navbar</nav>,
 }));
 
-vi.mock('./components/diagram-section/DiagramSection', () => ({
-    DiagramSection: ({ data, onItemSelect }: { data: { id?: string }; onItemSelect?: (item: { data: unknown }) => void }) => (
+vi.mock('./components/diagram-section/DiagramSection', async () => {
+    // Real context, not a mock: the stub consumes Hub's provider exactly like the
+    // production tree (CustomNode / NodeDetails) does.
+    const { useDiagramActions } = await import('../visualizer/context/DiagramActionsContext.js');
+    const DiagramSection = ({
+        data,
+        onItemSelect,
+        breadcrumbs,
+        onDisplayNameChange,
+    }: {
+        data: { id?: string };
+        onItemSelect?: (item: { data: unknown }) => void;
+        breadcrumbs?: unknown[];
+        onDisplayNameChange?: (name: string | undefined) => void;
+    }) => {
+        const { onNavigateToDetailedArch } = useDiagramActions();
+        return (
         <div data-testid="diagram-section">
             Diagram: {data?.id}
+            {/* Trail from history state, echoed for breadcrumb-accumulation tests. */}
+            <div data-testid="breadcrumbs">{JSON.stringify(breadcrumbs ?? [])}</div>
+            {/* Simulates the summaries fetch resolving the display name. */}
+            <button data-testid="set-display-name" onClick={() => onDisplayNameChange?.('Nice Name')}>
+                set display name
+            </button>
+            {/* Simulates a node's "Explore Architecture" action (context consumer). */}
+            <button
+                data-testid="navigate-detailed-arch"
+                onClick={() => onNavigateToDetailedArch?.('/calm/namespaces/finos/architectures/target-arch/versions/2.0.0')}
+            >
+                navigate detailed
+            </button>
+            <button
+                data-testid="navigate-detailed-arch-bad"
+                onClick={() => onNavigateToDetailedArch?.('/not/a/calm/path')}
+            >
+                navigate bad
+            </button>
             {/* Lets tests simulate a node/edge tap on the graph so Hub's node-detail
                 wiring (the mobile bottom-sheet + prev/next steppers) is exercised.
                 `select-node` (n1) is retained for existing tests; `select-n1/n2/n3`
@@ -197,8 +231,10 @@ vi.mock('./components/diagram-section/DiagramSection', () => ({
                 select edge
             </button>
         </div>
-    ),
-}));
+        );
+    };
+    return { DiagramSection };
+});
 
 // Helpers to drive the captured load callbacks.
 const loadData = () =>
@@ -278,6 +314,21 @@ const renderAt = (path: string) =>
         </MemoryRouter>
     );
 
+// Echoes the live pathname so tests can assert where a context-triggered
+// navigation landed. Accepts entry objects so a test can seed history state.
+function LocationProbe() {
+    const location = useLocation();
+    return <div data-testid="location-pathname">{location.pathname}</div>;
+}
+
+const renderWithLocation = (entries: React.ComponentProps<typeof MemoryRouter>['initialEntries']) =>
+    render(
+        <MemoryRouter initialEntries={entries}>
+            <Hub />
+            <LocationProbe />
+        </MemoryRouter>
+    );
+
 // A tiny in-router harness so tests can drive real react-router navigation
 // (changing location.key) against the same <Hub/> instance — `rerender` with a
 // fresh MemoryRouter would remount Hub and discard its state, defeating the test.
@@ -722,4 +773,69 @@ describe('Hub', () => {
             expect(screen.queryByTestId('adr-renderer')).not.toBeInTheDocument();
         });
     });
+    describe('detailed-architecture navigation (breadcrumb state)', () => {
+        const readCrumbs = () => JSON.parse(screen.getByTestId('breadcrumbs').textContent!);
+
+        it('pushes the current resource as a named crumb and navigates to the parsed target', () => {
+            renderWithLocation(['/test-namespace/architectures/arch/1.0']);
+            loadArchitectureWithNodes();
+            fireEvent.click(screen.getByTestId('set-display-name'));
+
+            fireEvent.click(screen.getByTestId('navigate-detailed-arch'));
+
+            expect(screen.getByTestId('location-pathname')).toHaveTextContent(
+                '/finos/architectures/target-arch/2.0.0'
+            );
+            // The new route's resource loads; the remounted diagram receives the trail.
+            loadArchitectureWithNodes();
+            expect(readCrumbs()).toEqual([
+                { namespace: 'test-namespace', type: 'architectures', id: 'arch', version: '1.0', name: 'Nice Name' },
+            ]);
+        });
+
+        it('accumulates one crumb per hop and omits the name when it never resolved', () => {
+            renderWithLocation(['/test-namespace/architectures/arch/1.0']);
+            loadArchitectureWithNodes();
+            fireEvent.click(screen.getByTestId('navigate-detailed-arch'));
+            loadArchitectureWithNodes();
+            expect(readCrumbs()).toHaveLength(1);
+
+            fireEvent.click(screen.getByTestId('navigate-detailed-arch'));
+            loadArchitectureWithNodes();
+
+            const crumbs = readCrumbs();
+            expect(crumbs).toHaveLength(2);
+            // No set-display-name click before either hop's navigation: the crumb
+            // carries no name and consumers fall back to the id.
+            expect(crumbs[0].name).toBeUndefined();
+            expect(crumbs[1]).toEqual({ namespace: 'test-namespace', type: 'architectures', id: 'arch', version: '1.0' });
+        });
+
+        it('ignores references that are not CALM Hub paths, keeping the current view intact', () => {
+            renderWithLocation(['/test-namespace/architectures/arch/1.0']);
+            loadArchitectureWithNodes();
+
+            fireEvent.click(screen.getByTestId('navigate-detailed-arch-bad'));
+
+            expect(screen.getByTestId('location-pathname')).toHaveTextContent(
+                '/test-namespace/architectures/arch/1.0'
+            );
+            // No navigation happened, so the loaded diagram was not cleared.
+            expect(screen.getByTestId('diagram-section')).toHaveTextContent('Diagram: arch');
+        });
+
+        it('filters malformed entries out of untrusted history state', () => {
+            const valid = { namespace: 'finos', type: 'architectures', id: 'parent', version: '1.0.0' };
+            renderWithLocation([
+                {
+                    pathname: '/test-namespace/architectures/arch/1.0',
+                    state: { breadcrumbs: [valid, { junk: true }, 'nonsense', null, { namespace: 'x', type: 'flows', id: 'y', version: '1' }] },
+                },
+            ]);
+            loadArchitectureWithNodes();
+
+            expect(readCrumbs()).toEqual([valid]);
+        });
+    });
+
 });

calm-hub-ui/src/hub/Hub.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useLayoutEffect, useMemo, useState } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { useLocation, useMatch, useNavigate } from 'react-router-dom';
 import { IoChevronForwardOutline, IoCompassOutline } from 'react-icons/io5';
 import { ExploreRail } from './components/explore-rail/ExploreRail.js';
@@ -8,7 +8,7 @@ import { DomainPage } from './components/domain-page/DomainPage.js';
 import { FirstRunLanding } from './components/first-run-landing/FirstRunLanding.js';
 import { useResourceFromRoute } from './hooks/useResourceFromRoute.js';
 import { useIsMobile } from '../hooks/useMediaQuery.js';
-import { Data, Adr } from '../model/calm.js';
+import { BreadcrumbItem, Data, Adr } from '../model/calm.js';
 import { ControlData } from '../model/control.js';
 import { InterfaceData } from '../model/interface.js';
 import { NamespaceCounts, DomainControlCount } from '../model/counts.js';
@@ -21,19 +21,46 @@ import { InterfaceDetailSection } from './components/interface-detail-section/In
 import { DiagramSection } from './components/diagram-section/DiagramSection.js';
 import { Sidebar } from '../visualizer/components/sidebar/Sidebar.js';
 import { NodeSheet } from '../visualizer/components/sidebar/NodeSheet.js';
+import { DiagramActionsContext } from '../visualizer/context/DiagramActionsContext.js';
+import { ResourceNotFound } from './components/resource-not-found/ResourceNotFound.js';
+import { parseCALMHubPath } from '../visualizer/components/reactflow/utils/calmHelpers.js';
 import type { SelectedItem } from '../visualizer/contracts/contracts.js';
 import type { CalmNodeSchema } from '@finos/calm-models/types';
 import { authStore } from '../service/utils/auth-store.js';
 import './Hub.css';
 
+// Breadcrumbs live in history state so Back restores the parent's trail for free,
+// at the documented cost that a hard refresh or shared deep link starts with an
+// empty trail. History state is untyped and can be stale (older sessions) or set
+// by other code, so validate the shape instead of trusting a cast.
+function readBreadcrumbs(state: unknown): BreadcrumbItem[] {
+    const crumbs = (state as { breadcrumbs?: unknown } | null)?.breadcrumbs;
+    if (!Array.isArray(crumbs)) return [];
+    return crumbs.filter(
+        (c): c is BreadcrumbItem =>
+            typeof c === 'object' &&
+            c !== null &&
+            typeof (c as BreadcrumbItem).namespace === 'string' &&
+            ((c as BreadcrumbItem).type === 'architectures' || (c as BreadcrumbItem).type === 'patterns') &&
+            typeof (c as BreadcrumbItem).id === 'string' &&
+            typeof (c as BreadcrumbItem).version === 'string'
+    );
+}
+
 export default function Hub() {
+    const navigate = useNavigate();
+    const location = useLocation();
+    const currentDisplayNameRef = useRef<string | undefined>(undefined);
     const [data, setData] = useState<Data | undefined>();
     const [adrData, setAdrData] = useState<Adr | undefined>();
     const [controlData, setControlData] = useState<ControlData | undefined>();
     const [interfaceData, setInterfaceData] = useState<InterfaceData | undefined>();
     const [isSidebarOpen, setIsSidebarOpen] = useState(true);
     const [isMobileNavOpen, setIsMobileNavOpen] = useState(true);
     const [selectedItem, setSelectedItem] = useState<SelectedItem>(null);
+    // A detail-route load rejected (missing resource, dangling reference). Cleared
+    // on every navigation; renders ResourceNotFound instead of an empty pane.
+    const [resourceLoadFailed, setResourceLoadFailed] = useState(false);
     const [namespaceCounts, setNamespaceCounts] = useState<NamespaceCounts[]>([]);
     const [namespaceCountsLoaded, setNamespaceCountsLoaded] = useState(false);
     // Distinct from "loaded": a failed counts fetch means counts are unknown, not
@@ -46,8 +73,6 @@ export default function Hub() {
     // Route-first content selection (redesign problem #4): the same <Hub/> element
     // is reused across `/`, `/namespace/:ns`, `/domain/:domain` and the detail
     // route, so the URL — not residual state — decides what renders.
-    const { key: locationKey } = useLocation();
-    const navigate = useNavigate();
     const namespaceMatch = useMatch('/namespace/:ns');
     const domainMatch = useMatch('/domain/:domain');
     const detailMatch = useMatch('/:namespace/:type/:id/:version');
@@ -107,7 +132,8 @@ export default function Hub() {
         setControlData(undefined);
         setInterfaceData(undefined);
         setSelectedItem(null);
-    }, [locationKey]);
+        setResourceLoadFailed(false);
+    }, [location.key]);
 
     const handleDataLoad = useCallback((loaded: Data) => {
         setData(loaded);
@@ -116,6 +142,7 @@ export default function Hub() {
         setInterfaceData(undefined);
         setSelectedItem(null);
         setIsMobileNavOpen(false);
+        currentDisplayNameRef.current = undefined;
     }, []);
 
     const handleAdrLoad = useCallback((adr: Adr) => {
@@ -145,12 +172,18 @@ export default function Hub() {
         setIsMobileNavOpen(false);
     }, []);
 
+    const handleResourceLoadError = useCallback((error: unknown) => {
+        console.error('%s', 'Failed to load routed resource:', error);
+        setResourceLoadFailed(true);
+    }, []);
+
     // Single owner of deep-link / external-navigation loading for the detail route.
     useResourceFromRoute({
         onDataLoad: handleDataLoad,
         onAdrLoad: handleAdrLoad,
         onControlLoad: handleControlLoad,
         onInterfaceLoad: handleInterfaceLoad,
+        onLoadError: handleResourceLoadError,
     });
 
     const handleItemSelect = useCallback((item: SelectedItem) => {
@@ -192,6 +225,41 @@ export default function Hub() {
         [isDetailRoute, navigate, handleControlLoad]
     );
 
+    // The resource's display name is fetched by DiagramSection (it owns the
+    // summaries fetch) and mirrored here so the crumb pushed on navigation can
+    // carry it. A ref, not state: it is only read imperatively at navigate time,
+    // so Hub need not re-render when it resolves. This handler MUST stay memoised
+    // (identity-stable) — DiagramSection lists it in a fetch effect's deps.
+    const handleDisplayNameChange = useCallback((name: string | undefined) => {
+        currentDisplayNameRef.current = name;
+    }, []);
+
+    const handleNavigateToDetailedArch = useCallback((ref: string) => {
+        const parsed = parseCALMHubPath(ref);
+        if (!parsed || !data) return;
+        const currentCrumb: BreadcrumbItem = {
+            namespace: data.name,
+            type: data.calmType === 'Architectures' ? 'architectures' : 'patterns',
+            id: data.id,
+            version: data.version,
+            name: currentDisplayNameRef.current,
+        };
+        navigate(`/${parsed.namespace}/${parsed.type}/${parsed.id}/${parsed.version}`, {
+            state: { breadcrumbs: [...readBreadcrumbs(location.state), currentCrumb] }
+        });
+    }, [navigate, data, location.state]);
+
+    const breadcrumbs = useMemo(() => readBreadcrumbs(location.state), [location.state]);
+
+    // Single, memoised provider value for every detailed-architecture navigation
+    // consumer: CustomNode (which ReactFlow instantiates internally, out of reach
+    // of props) and NodeDetails (rendered in both the Sidebar and the NodeSheet).
+    // Memoised so consumers don't re-render on unrelated Hub renders.
+    const diagramActions = useMemo(
+        () => ({ onNavigateToDetailedArch: handleNavigateToDetailedArch }),
+        [handleNavigateToDetailedArch]
+    );
+
     const isDiagramView = data?.calmType === 'Architectures' || data?.calmType === 'Patterns';
 
     // Mobile node bottom-sheet prev/next steppers (Frame G). The ordered node list
@@ -269,7 +337,13 @@ export default function Hub() {
     ) : adrData ? (
         <AdrRenderer adrDetails={adrData} />
     ) : isDiagramView ? (
-        <DiagramSection data={data} onItemSelect={handleItemSelect} hasDetailsPanel={!!selectedItem} />
+        <DiagramSection
+            data={data}
+            onItemSelect={handleItemSelect}
+            hasDetailsPanel={!!selectedItem}
+            breadcrumbs={breadcrumbs}
+            onDisplayNameChange={handleDisplayNameChange}
+        />
     ) : (
         <DocumentDetailSection data={data} />
     );
@@ -291,6 +365,16 @@ export default function Hub() {
             onControlLoad={handleControlActivate}
             selectedControlId={controlData.controlId}
         />
+    ) : isDetailRoute && resourceLoadFailed && !interfaceData && !adrData && !data ? (
+        // The routed resource failed to load: show a recoverable not-found state
+        // (never a blank pane). Loaded data wins if a late success ever lands.
+        <ResourceNotFound
+            namespace={detailMatch.params.namespace!}
+            id={detailMatch.params.id!}
+            version={detailMatch.params.version!}
+            type={detailMatch.params.type}
+            breadcrumbs={breadcrumbs}
+        />
     ) : isDetailRoute || interfaceData || adrData || data ? (
         detailContent
     ) : activeNamespace ? (
@@ -313,6 +397,7 @@ export default function Hub() {
     );
 
     return (
+        <DiagramActionsContext.Provider value={diagramActions}>
         <div className="flex flex-col h-screen overflow-hidden">
             <Navbar />
             {isMobile && !isMobileNavOpen && (
@@ -415,5 +500,6 @@ export default function Hub() {
                 )}
             </div>
         </div>
+        </DiagramActionsContext.Provider>
     );
 }