From 2426863c674ab4b95821e9da0c30550268f703ec Mon Sep 17 00:00:00 2001
From: Ib Green <7025232+ibgreen@users.noreply.github.com>
Date: Tue, 4 Nov 2025 12:54:31 -0500
Subject: [PATCH 1/2] Add synced mini-map and collapsed chain breadcrumbs

---
 examples/graph-layers/graph-viewer/app.tsx    | 155 ++++++++-
 .../graph-layers/graph-viewer/mini-map.tsx    | 313 ++++++++++++++++++
 2 files changed, 467 insertions(+), 1 deletion(-)
 create mode 100644 examples/graph-layers/graph-viewer/mini-map.tsx

diff --git a/examples/graph-layers/graph-viewer/app.tsx b/examples/graph-layers/graph-viewer/app.tsx
index 60bfebab..0cf453f8 100644
--- a/examples/graph-layers/graph-viewer/app.tsx
+++ b/examples/graph-layers/graph-viewer/app.tsx
@@ -28,6 +28,7 @@ import {extent} from 'd3-array';
 
 import {ControlPanel, ExampleDefinition, LayoutType} from './control-panel';
 import {DEFAULT_EXAMPLE, EXAMPLES} from './examples';
+import {MiniMap} from './mini-map';
 
 const INITIAL_VIEW_STATE = {
   /** the target origin of the view */
@@ -39,6 +40,9 @@ const INITIAL_VIEW_STATE = {
 // the default cursor in the view
 const DEFAULT_CURSOR = 'default';
 const DEFAULT_LAYOUT = DEFAULT_EXAMPLE?.layouts[0] ?? 'd3-force-layout';
+const MINI_MAP_VIEWPORT_WIDTH = 200;
+const MINI_MAP_VIEWPORT_HEIGHT = 160;
+const MINI_MAP_PADDING = 12;
 
 type LayoutFactory = (options?: Record<string, unknown>) => GraphLayout;
 
@@ -122,6 +126,7 @@ export function App(props) {
   const engine = useMemo(() => (graph && layout ? new GraphEngine({graph, layout}) : null), [graph, layout]);
   const isFirstMount = useRef(true);
   const dagLayout = layout instanceof D3DagLayout ? (layout as D3DagLayout) : null;
+  const [engineRevision, bumpEngineRevision] = useReducer((count: number) => count + 1, 0);
 
   useLayoutEffect(() => {
     if (!engine) {
@@ -185,6 +190,23 @@ export function App(props) {
     }
   }, [isDagLayout, selectedExample]);
 
+  useEffect(() => {
+    if (!engine) {
+      return () => undefined;
+    }
+
+    const handleEngineUpdate = () => bumpEngineRevision();
+    engine.addEventListener('onLayoutStart', handleEngineUpdate);
+    engine.addEventListener('onLayoutChange', handleEngineUpdate);
+    engine.addEventListener('onLayoutDone', handleEngineUpdate);
+
+    return () => {
+      engine.removeEventListener('onLayoutStart', handleEngineUpdate);
+      engine.removeEventListener('onLayoutChange', handleEngineUpdate);
+      engine.removeEventListener('onLayoutDone', handleEngineUpdate);
+    };
+  }, [engine, bumpEngineRevision]);
+
   useEffect(() => {
     if (!dagLayout) {
       return;
@@ -243,6 +265,57 @@ export function App(props) {
     };
   }, [engine, dagLayout, isDagLayout]);
 
+  const nodes = engine ? engine.getNodes() : [];
+  const hoveredNode = nodes.find((node) => node.getState() === 'hover') ?? null;
+
+  const hoveredChainInfo = useMemo(() => {
+    if (!engine || !hoveredNode) {
+      return null;
+    }
+
+    const chainId = hoveredNode.getPropertyValue('collapsedChainId');
+    const collapsedNodeIds = hoveredNode.getPropertyValue('collapsedNodeIds');
+    const representativeId = hoveredNode.getPropertyValue('collapsedChainRepresentativeId');
+
+    if (
+      chainId === null ||
+      chainId === undefined ||
+      !Array.isArray(collapsedNodeIds) ||
+      collapsedNodeIds.length <= 1 ||
+      representativeId !== hoveredNode.getId()
+    ) {
+      return null;
+    }
+
+    const collapsedNodeIdSet = new Set<string | number>(collapsedNodeIds as (string | number)[]);
+    const graph = engine.props.graph;
+    const parents = new Set<string | number>();
+
+    for (const edge of graph.getEdges()) {
+      if (!edge.isDirected()) {
+        continue;
+      }
+      const targetId = edge.getTargetNodeId();
+      if (!collapsedNodeIdSet.has(targetId)) {
+        continue;
+      }
+      const sourceId = edge.getSourceNodeId();
+      if (collapsedNodeIdSet.has(sourceId)) {
+        continue;
+      }
+      parents.add(sourceId);
+    }
+
+    const parentList = Array.from(parents).map((id) => String(id));
+    parentList.sort((a, b) => a.localeCompare(b, undefined, {numeric: true, sensitivity: 'base'}));
+
+    return {
+      chainId: String(chainId),
+      breadcrumb: parentList.length ? parentList.join(' › ') : 'No parent nodes',
+      collapsedLength: collapsedNodeIdSet.size
+    };
+  }, [engine, hoveredNode, engineRevision]);
+
   const handleToggleCollapseEnabled = useCallback(() => {
     setCollapseEnabled((value) => !value);
   }, []);
@@ -336,6 +409,30 @@ export function App(props) {
     setSelectedLayout(layoutType);
   }, []);
 
+  const handleNodeInteraction = useCallback(() => {
+    bumpEngineRevision();
+  }, [bumpEngineRevision]);
+
+  const graphLayerNodeEvents = useMemo(
+    () => ({
+      onHover: handleNodeInteraction,
+      onMouseLeave: handleNodeInteraction,
+      onClick: handleNodeInteraction,
+      onDrag: handleNodeInteraction
+    }),
+    [handleNodeInteraction]
+  );
+
+  const handleMiniMapRecenter = useCallback(
+    (target: [number, number]) => {
+      setViewState((prev) => ({
+        ...prev,
+        target: [target[0], target[1]]
+      }));
+    },
+    [setViewState]
+  );
+
   return (
     <div
       style={{
@@ -398,7 +495,8 @@ export function App(props) {
                   new GraphLayer({
                     engine,
                     stylesheet: selectedStyles,
-                    resumeLayoutAfterDragging
+                    resumeLayoutAfterDragging,
+                    nodeEvents: graphLayerNodeEvents
                   })
                 ]
               : []
@@ -406,6 +504,61 @@ export function App(props) {
           widgets={widgets}
           getTooltip={(info) => getToolTip(info.object)}
         />
+        {engine ? (
+          <div
+            style={{
+              position: 'absolute',
+              right: '1.5rem',
+              bottom: '1.5rem',
+              width: `${MINI_MAP_VIEWPORT_WIDTH + MINI_MAP_PADDING * 2}px`,
+              padding: `${MINI_MAP_PADDING}px`,
+              borderRadius: '0.75rem',
+              background: 'rgba(15, 23, 42, 0.85)',
+              boxShadow: '0 12px 28px rgba(15, 23, 42, 0.45)',
+              border: '1px solid rgba(148, 163, 184, 0.25)',
+              color: '#e2e8f0',
+              fontSize: '0.75rem',
+              lineHeight: 1.4,
+              pointerEvents: 'auto',
+              backdropFilter: 'blur(6px)'
+            }}
+          >
+            <div
+              style={{
+                width: `${MINI_MAP_VIEWPORT_WIDTH}px`,
+                height: `${MINI_MAP_VIEWPORT_HEIGHT}px`,
+                borderRadius: '0.5rem',
+                overflow: 'hidden',
+                background: 'rgba(15, 23, 42, 0.6)',
+                marginBottom: '0.75rem'
+              }}
+            >
+              <MiniMap
+                engine={engine}
+                revision={engineRevision}
+                mainViewState={viewState}
+                width={MINI_MAP_VIEWPORT_WIDTH}
+                height={MINI_MAP_VIEWPORT_HEIGHT}
+                onRecenter={handleMiniMapRecenter}
+              />
+            </div>
+            {hoveredChainInfo ? (
+              <div style={{display: 'flex', flexDirection: 'column', gap: '0.25rem'}}>
+                <div style={{fontWeight: 600, color: '#f8fafc'}}>
+                  Chain {hoveredChainInfo.chainId}
+                  <span style={{marginLeft: '0.35rem', fontWeight: 400, color: '#cbd5f5'}}>
+                    • {hoveredChainInfo.collapsedLength} nodes
+                  </span>
+                </div>
+                <div style={{color: '#cbd5f5'}}>Parents: {hoveredChainInfo.breadcrumb}</div>
+              </div>
+            ) : (
+              <div style={{color: '#94a3b8'}}>
+                Hover a collapsed chain to see parent breadcrumbs.
+              </div>
+            )}
+          </div>
+        ) : null}
       </div>
       <aside
         style={{
diff --git a/examples/graph-layers/graph-viewer/mini-map.tsx b/examples/graph-layers/graph-viewer/mini-map.tsx
new file mode 100644
index 00000000..be7c6d51
--- /dev/null
+++ b/examples/graph-layers/graph-viewer/mini-map.tsx
@@ -0,0 +1,313 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import React, {useCallback, useMemo} from 'react';
+
+import DeckGL from '@deck.gl/react';
+import {OrthographicView} from '@deck.gl/core';
+import {PolygonLayer, ScatterplotLayer} from '@deck.gl/layers';
+
+import type {GraphEngine, Node} from '@deck.gl-community/graph-layers';
+
+type GraphViewState = {
+  target?: [number, number] | [number, number, number];
+  zoom?: number;
+  width?: number;
+  height?: number;
+};
+
+type MiniMapPoint = {
+  node: Node;
+  position: [number, number];
+  isChainRepresentative: boolean;
+  isCollapsedChain: boolean;
+};
+
+type MiniMapProps = {
+  engine: GraphEngine | null;
+  revision: number;
+  mainViewState: GraphViewState;
+  width: number;
+  height: number;
+  onRecenter: (target: [number, number]) => void;
+};
+
+const DEFAULT_VIEW_STATE = {
+  target: [0, 0, 0] as [number, number, number],
+  zoom: 0,
+  width: 1,
+  height: 1
+};
+
+const COLOR_DEFAULT = [148, 163, 184, 180];
+const COLOR_COLLAPSED = [248, 113, 113, 255];
+const COLOR_EXPANDED_CHAIN = [251, 191, 36, 230];
+const COLOR_SELECTED = [37, 99, 235, 255];
+const COLOR_HOVERED = [16, 185, 129, 255];
+const COLOR_DRAGGING = [59, 130, 246, 255];
+const COLOR_DEFAULT_OUTLINE = [71, 85, 105, 200];
+const COLOR_COLLAPSED_OUTLINE = [220, 38, 38, 255];
+const COLOR_EXPANDED_CHAIN_OUTLINE = [217, 119, 6, 255];
+
+const VIEWPORT_FILL_COLOR = [59, 130, 246, 45];
+const VIEWPORT_STROKE_COLOR = [59, 130, 246, 180];
+
+const MINI_MAP_VIEW_ID = 'graph-mini-map-view';
+
+export function MiniMap({engine, revision, mainViewState, width, height, onRecenter}: MiniMapProps) {
+  const data = useMemo<MiniMapPoint[]>(() => {
+    if (!engine) {
+      return [];
+    }
+
+    const nodes = engine.getNodes();
+    return nodes
+      .map((node) => {
+        const position = engine.getNodePosition(node);
+        if (!position) {
+          return null;
+        }
+        const chainId = node.getPropertyValue('collapsedChainId');
+        const collapsedNodeIds = node.getPropertyValue('collapsedNodeIds');
+        const representativeId = node.getPropertyValue('collapsedChainRepresentativeId');
+        const isCollapsedChain = Boolean(node.getPropertyValue('isCollapsedChain'));
+        const isChainRepresentative =
+          chainId !== null &&
+          chainId !== undefined &&
+          Array.isArray(collapsedNodeIds) &&
+          collapsedNodeIds.length > 1 &&
+          representativeId === node.getId();
+
+        return {
+          node,
+          position: position as [number, number],
+          isChainRepresentative,
+          isCollapsedChain
+        };
+      })
+      .filter(Boolean) as MiniMapPoint[];
+  }, [engine, revision]);
+
+  const bounds = useMemo(() => {
+    if (!data.length) {
+      return null;
+    }
+
+    let minX = Infinity;
+    let maxX = -Infinity;
+    let minY = Infinity;
+    let maxY = -Infinity;
+
+    for (const point of data) {
+      const [x, y] = point.position;
+      minX = Math.min(minX, x);
+      minY = Math.min(minY, y);
+      maxX = Math.max(maxX, x);
+      maxY = Math.max(maxY, y);
+    }
+
+    if (!Number.isFinite(minX) || !Number.isFinite(maxX) || !Number.isFinite(minY) || !Number.isFinite(maxY)) {
+      return null;
+    }
+
+    return {minX, minY, maxX, maxY};
+  }, [data]);
+
+  const miniMapViewState = useMemo(() => {
+    if (!bounds) {
+      return {...DEFAULT_VIEW_STATE, width, height};
+    }
+
+    const padding = 24;
+    const effectiveWidth = Math.max(width - padding, 1);
+    const effectiveHeight = Math.max(height - padding, 1);
+
+    const spanX = Math.max(bounds.maxX - bounds.minX, 1);
+    const spanY = Math.max(bounds.maxY - bounds.minY, 1);
+
+    const scaleX = effectiveWidth / spanX;
+    const scaleY = effectiveHeight / spanY;
+    const scale = Math.max(Math.min(scaleX, scaleY), 1e-3);
+    const zoom = Math.log(scale);
+
+    return {
+      target: [
+        (bounds.minX + bounds.maxX) / 2,
+        (bounds.minY + bounds.maxY) / 2,
+        0
+      ] as [number, number, number],
+      zoom,
+      width,
+      height
+    };
+  }, [bounds, width, height]);
+
+  const viewportPolygon = useMemo(() => {
+    const zoom = mainViewState.zoom;
+    const viewWidth = mainViewState.width;
+    const viewHeight = mainViewState.height;
+
+    if (
+      !Number.isFinite(zoom) ||
+      !Number.isFinite(viewWidth) ||
+      !Number.isFinite(viewHeight) ||
+      viewWidth === undefined ||
+      viewHeight === undefined
+    ) {
+      return null;
+    }
+
+    const scale = Math.exp(zoom as number);
+    if (!Number.isFinite(scale) || scale <= 0) {
+      return null;
+    }
+
+    const target = Array.isArray(mainViewState.target) ? mainViewState.target : [0, 0, 0];
+    const targetX = target[0] ?? 0;
+    const targetY = target[1] ?? 0;
+
+    const halfWidth = (viewWidth as number) / (2 * scale);
+    const halfHeight = (viewHeight as number) / (2 * scale);
+
+    return [
+      [targetX - halfWidth, targetY - halfHeight],
+      [targetX + halfWidth, targetY - halfHeight],
+      [targetX + halfWidth, targetY + halfHeight],
+      [targetX - halfWidth, targetY + halfHeight]
+    ];
+  }, [mainViewState]);
+
+  const scatterplotLayer = useMemo(() => {
+    if (!data.length) {
+      return null;
+    }
+
+    return new ScatterplotLayer<MiniMapPoint>({
+      id: 'mini-map-nodes',
+      data,
+      pickable: false,
+      radiusUnits: 'pixels',
+      stroked: true,
+      lineWidthUnits: 'pixels',
+      lineWidthMinPixels: 1,
+      parameters: {depthTest: false},
+      getPosition: (d) => d.position,
+      getRadius: (d) => {
+        const base = d.isChainRepresentative ? 7 : 5;
+        const state = d.node.getState();
+        if (state === 'selected') {
+          return base + 4;
+        }
+        if (state === 'hover') {
+          return base + 2;
+        }
+        if (state === 'dragging') {
+          return base + 3;
+        }
+        return base;
+      },
+      getFillColor: (d) => {
+        const state = d.node.getState();
+        if (state === 'selected') {
+          return COLOR_SELECTED;
+        }
+        if (state === 'hover') {
+          return COLOR_HOVERED;
+        }
+        if (state === 'dragging') {
+          return COLOR_DRAGGING;
+        }
+        if (d.isChainRepresentative) {
+          return d.isCollapsedChain ? COLOR_COLLAPSED : COLOR_EXPANDED_CHAIN;
+        }
+        return COLOR_DEFAULT;
+      },
+      getLineColor: (d) => {
+        const state = d.node.getState();
+        if (state === 'selected') {
+          return COLOR_SELECTED;
+        }
+        if (state === 'hover') {
+          return COLOR_HOVERED;
+        }
+        if (state === 'dragging') {
+          return COLOR_DRAGGING;
+        }
+        if (d.isChainRepresentative) {
+          return d.isCollapsedChain ? COLOR_COLLAPSED_OUTLINE : COLOR_EXPANDED_CHAIN_OUTLINE;
+        }
+        return COLOR_DEFAULT_OUTLINE;
+      },
+      updateTriggers: {
+        getRadius: revision,
+        getFillColor: revision,
+        getLineColor: revision
+      }
+    });
+  }, [data, revision]);
+
+  const viewBoundsLayer = useMemo(() => {
+    if (!viewportPolygon) {
+      return null;
+    }
+
+    return new PolygonLayer({
+      id: 'mini-map-viewport',
+      data: [{polygon: viewportPolygon}],
+      getPolygon: (d) => d.polygon,
+      stroked: true,
+      filled: true,
+      parameters: {depthTest: false},
+      getFillColor: VIEWPORT_FILL_COLOR,
+      getLineColor: VIEWPORT_STROKE_COLOR,
+      lineWidthUnits: 'pixels',
+      lineWidthMinPixels: 1.5
+    });
+  }, [viewportPolygon]);
+
+  const handleClick = useCallback(
+    (info: any) => {
+      if (!onRecenter) {
+        return;
+      }
+      const viewport = info?.viewport;
+      let coordinate = info?.coordinate as [number, number] | undefined;
+      if (!coordinate && viewport && typeof info?.x === 'number' && typeof info?.y === 'number') {
+        coordinate = viewport.unproject([info.x, info.y]);
+      }
+      if (!coordinate) {
+        return;
+      }
+      const [x, y] = coordinate;
+      if (!Number.isFinite(x) || !Number.isFinite(y)) {
+        return;
+      }
+      onRecenter([x, y]);
+    },
+    [onRecenter]
+  );
+
+  const layers = useMemo(() => {
+    const result = [] as any[];
+    if (scatterplotLayer) {
+      result.push(scatterplotLayer);
+    }
+    if (viewBoundsLayer) {
+      result.push(viewBoundsLayer);
+    }
+    return result;
+  }, [scatterplotLayer, viewBoundsLayer]);
+
+  return (
+    <DeckGL
+      style={{width: '100%', height: '100%'}}
+      controller={false}
+      views={[new OrthographicView({id: MINI_MAP_VIEW_ID, controller: false})]}
+      viewState={{...miniMapViewState, id: MINI_MAP_VIEW_ID}}
+      layers={layers}
+      getCursor={() => 'pointer'}
+      onClick={handleClick}
+    />
+  );
+}

From 59117dc70221cbedcfda88315cd9fbf63068f967 Mon Sep 17 00:00:00 2001
From: Ib Green <7025232+ibgreen@users.noreply.github.com>
Date: Tue, 4 Nov 2025 13:11:07 -0500
Subject: [PATCH 2/2] Adjust graph viewer layout for minimap

---
 examples/graph-layers/graph-viewer/app.tsx | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/examples/graph-layers/graph-viewer/app.tsx b/examples/graph-layers/graph-viewer/app.tsx
index 0cf453f8..660f5593 100644
--- a/examples/graph-layers/graph-viewer/app.tsx
+++ b/examples/graph-layers/graph-viewer/app.tsx
@@ -437,7 +437,8 @@ export function App(props) {
     <div
       style={{
         display: 'flex',
-        height: '100%',
+        height: '100vh',
+        maxHeight: '100vh',
         width: '100%',
         boxSizing: 'border-box',
         fontFamily: 'Inter, "Helvetica Neue", Arial, sans-serif'
@@ -447,7 +448,8 @@ export function App(props) {
         style={{
           flex: '1 1 auto',
           minWidth: 0,
-          position: 'relative'
+          position: 'relative',
+          height: '100%'
         }}
       >
         {isLoading ? (
@@ -570,6 +572,8 @@ export function App(props) {
           borderLeft: '1px solid #e2e8f0',
           background: '#f1f5f9',
           overflowY: 'auto',
+          height: '100%',
+          maxHeight: '100vh',
           fontFamily: 'inherit'
         }}
       >
@@ -677,6 +681,9 @@ export function renderToDOM() {
     document.body.style.margin = '0';
     document.body.style.fontFamily = 'Inter, "Helvetica Neue", Arial, sans-serif';
     const container = document.createElement('div');
+    container.style.width = '100vw';
+    container.style.height = '100vh';
+    container.style.overflow = 'hidden';
     document.body.appendChild(container);
     const root = createRoot(container);
     root.render(<App />);