Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(architecture): move map chrome off the canvas and give it a ground (#2102)

Raghav Chamadiyaad94390b0ea4
diff --git a/packages/ui/__tests__/graph/graph-flow.test.tsx b/packages/ui/__tests__/graph/graph-flow.test.tsx
index 00bdc0056..5755bff18 100644
--- a/packages/ui/__tests__/graph/graph-flow.test.tsx
+++ b/packages/ui/__tests__/graph/graph-flow.test.tsx
@@ -58,14 +58,14 @@ describe("GraphFlow shell", () => {
});
// Uses "language" as the controlled value because it is the one that is not
- // the default. This was "risk" until that lens was removed for painting
- // `pagerank * 3` through unreachable thresholds; the assertion is about
- // control flow, not about which lens, so it survives the swap unchanged.
+ // the default. Rendered in the file scope: the constellation colours hubs by
+ // family whatever colorMode says, so the control is not offered there.
it("reflects a controlled colorMode and reports changes without self-updating", () => {
const onColorModeChange = vi.fn();
render(
<GraphFlow
{...baseProps}
+ initialViewMode="full"
colorMode="language"
onColorModeChange={onColorModeChange}
/>,
@@ -88,7 +88,9 @@ describe("GraphFlow shell", () => {
});
it("tracks its own colorMode when uncontrolled (seeded by initialColorMode)", () => {
- render(<GraphFlow {...baseProps} initialColorMode="language" />);
+ render(
+ <GraphFlow {...baseProps} initialViewMode="full" initialColorMode="language" />,
+ );
expect(
screen.getByRole("button", { name: "Language" }).getAttribute("aria-pressed"),
diff --git a/packages/ui/src/graph/graph-canvas-shell.tsx b/packages/ui/src/graph/graph-canvas-shell.tsx
index 9e7d67eac..595a86763 100644
--- a/packages/ui/src/graph/graph-canvas-shell.tsx
+++ b/packages/ui/src/graph/graph-canvas-shell.tsx
@@ -5,26 +5,41 @@ import { cn } from "../lib/cn";
export interface GraphCanvasShellProps {
/** Optional one-line title rendered above the canvas (no second header band). */
- title?: string;
+ title?: string | undefined;
/** Optional one-line description under the title. */
- description?: string;
- /** Right-aligned slot in the title row (e.g. a hint or a single action). */
- titleActions?: React.ReactNode;
+ description?: string | undefined;
+ /** Right-aligned slot in the title row. Scope controls and the toolbar live
+ * here rather than floating over the diagram. */
+ titleActions?: React.ReactNode | undefined;
/** A full-width banner slot above the canvas (e.g. truncation notice). */
- banner?: React.ReactNode;
+ banner?: React.ReactNode | undefined;
/** The canvas itself (Sigma / ReactFlow host). Fills the remaining height. */
children: React.ReactNode;
- /** Overlays drawn on top of the canvas (panels, doc rails, modals). */
- overlay?: React.ReactNode;
- className?: string;
+ /**
+ * Inspector content. A grid peer of the canvas from `lg` up, so a panel can
+ * never land on the map; below `lg` it becomes a bottom sheet over the canvas
+ * rather than starving it of height. Render nothing when there is no
+ * selection to explain and the canvas takes the full width.
+ */
+ rail?: React.ReactNode | undefined;
+ /** Legend / key row, rendered as a caption under the canvas. */
+ footer?: React.ReactNode | undefined;
+ /**
+ * Drawn on top of the canvas. Reserved for pointer-bound things: context
+ * menus, hover cards, modals. Persistent chrome belongs in `titleActions`,
+ * `footer` or `rail`.
+ */
+ overlay?: React.ReactNode | undefined;
+ className?: string | undefined;
}
/**
- * The single airy canvas container for every graph surface (Communities,
- * Explore, the Knowledge Graph layers route, and Coupling). Replaces the
- * per-view `rounded-lg border` frame and the double-header pattern: it owns at
- * most ONE thin title row and lets the diagram breathe with no box outline or
- * background fill behind it.
+ * The single canvas container for every graph surface.
+ *
+ * Chrome goes around the map, not on it: controls in the title row, key
+ * underneath, inspector as a grid peer. This mirrors `SystemMap`, the Code
+ * Health triage view and the Knowledge Graph page, which all converged on the
+ * same arrangement.
*/
export function GraphCanvasShell({
title,
@@ -32,6 +47,8 @@ export function GraphCanvasShell({
titleActions,
banner,
children,
+ rail,
+ footer,
overlay,
className,
}: GraphCanvasShellProps) {
@@ -39,7 +56,7 @@ export function GraphCanvasShell({
<div className={cn("flex h-full flex-col", className)}>
{(title || description || titleActions) && (
<div className="flex shrink-0 flex-wrap items-start justify-between gap-2 px-4 pt-3 sm:px-6">
- <div className="min-w-0">
+ <div className="min-w-0 max-w-2xl">
{title && (
<h2 className="text-sm font-semibold text-[var(--color-text-primary)]">
{title}
@@ -52,15 +69,42 @@ export function GraphCanvasShell({
)}
</div>
{titleActions && (
- <div className="flex shrink-0 items-center gap-2">{titleActions}</div>
+ <div className="flex min-w-0 flex-wrap items-center justify-end gap-2">
+ {titleActions}
+ </div>
)}
</div>
)}
{banner && <div className="shrink-0 px-4 pt-3 sm:px-6">{banner}</div>}
- <div className="relative min-h-0 flex-1 overflow-hidden">
- {children}
- {overlay}
+
+ <div
+ className={cn(
+ "relative mt-3 grid min-h-0 flex-1",
+ rail ? "lg:grid-cols-[minmax(0,1fr)_340px]" : "grid-cols-1",
+ )}
+ >
+ {/* A floor, so a tall header or key row cannot squeeze the subject to
+ nothing; the page scrolls instead. */}
+ <div className="relative min-h-0 overflow-hidden max-lg:min-h-[22rem]">
+ {children}
+ {overlay}
+ </div>
+ {rail && (
+ <aside
+ className={cn(
+ // Bottom sheet under lg so the canvas keeps its height on a
+ // phone; a real grid column from lg up.
+ "absolute inset-x-0 bottom-0 z-20 flex max-h-[70%] flex-col overflow-hidden",
+ "rounded-t-xl border-t border-[var(--color-border-default)] bg-[var(--color-bg-surface)] shadow-xl shadow-black/20",
+ "lg:static lg:max-h-none lg:rounded-none lg:border-t-0 lg:border-l lg:shadow-none",
+ )}
+ >
+ {rail}
+ </aside>
+ )}
</div>
+
+ {footer && <div className="shrink-0 px-4 pb-3 pt-2 sm:px-6">{footer}</div>}
</div>
);
}
diff --git a/packages/ui/src/graph/graph-community-panel.tsx b/packages/ui/src/graph/graph-community-panel.tsx
index bb051c17c..db768934e 100644
--- a/packages/ui/src/graph/graph-community-panel.tsx
+++ b/packages/ui/src/graph/graph-community-panel.tsx
@@ -32,7 +32,7 @@ export function GraphCommunityPanel({
memberHref,
}: GraphCommunityPanelProps) {
return (
- <div className="absolute right-0 top-0 bottom-0 w-full sm:w-[360px] border-l border-[var(--color-border-default)] bg-[var(--color-bg-surface)] z-20 flex flex-col shadow-lg shadow-black/20">
+ <div className="flex h-full min-h-0 flex-col">
{/* Header */}
<div className="flex items-center justify-between px-4 py-3 border-b border-[var(--color-border-default)]">
<div className="min-w-0">
@@ -47,6 +47,7 @@ export function GraphCommunityPanel({
</div>
<button
onClick={onClose}
+ aria-label="Close community details"
className="p-1 rounded hover:bg-[var(--color-bg-elevated)] transition-colors"
>
<X className="h-4 w-4 text-[var(--color-text-tertiary)]" />
diff --git a/packages/ui/src/graph/graph-doc-panel.tsx b/packages/ui/src/graph/graph-doc-panel.tsx
index 1a541a11d..a4a582635 100644
--- a/packages/ui/src/graph/graph-doc-panel.tsx
+++ b/packages/ui/src/graph/graph-doc-panel.tsx
@@ -49,7 +49,7 @@ export function GraphDocPanel({
}, [nodeId]);
return (
- <div className="absolute top-0 right-0 z-20 h-full w-[min(400px,calc(100vw-1.5rem))] flex flex-col bg-[var(--color-bg-surface)] border-l border-[var(--color-border-default)] shadow-2xl shadow-black/30">
+ <div className="flex h-full min-h-0 flex-col">
{/* Header */}
<div className="flex items-center gap-2 px-4 py-3 border-b border-[var(--color-border-default)] shrink-0">
<FileText className="h-4 w-4 text-[var(--color-accent-primary)] shrink-0" />
@@ -75,6 +75,7 @@ export function GraphDocPanel({
size="sm"
variant="ghost"
onClick={onClose}
+ aria-label="Close documentation"
className="h-6 w-6 p-0"
>
<X className="h-3.5 w-3.5" />
diff --git a/packages/ui/src/graph/graph-flow.tsx b/packages/ui/src/graph/graph-flow.tsx
index 4749831ea..cf28f78be 100644
--- a/packages/ui/src/graph/graph-flow.tsx
+++ b/packages/ui/src/graph/graph-flow.tsx
@@ -32,6 +32,7 @@ import { useModuleFilter } from "./use-module-filter";
import { useGraphKeyboardShortcuts } from "./use-graph-keyboard-shortcuts";
import { GraphToolbar, type ColorMode, type ViewMode, type LayoutMode, type GraphTheme } from "./graph-toolbar";
import { GraphLegend } from "./graph-legend";
+import { GraphCanvasShell } from "./graph-canvas-shell";
import { GraphContextMenu } from "./graph-context-menu";
import { GraphInspectionPanel } from "./graph-inspection-panel";
import { GraphFlowPanel } from "./graph-flow-panel";
@@ -62,8 +63,12 @@ import { useEgoFilter } from "./sigma/use-ego-filter";
export interface GraphFlowProps {
fullGraph: GraphExport | undefined;
isLoadingFullGraph: boolean;
- architectureGraph: GraphExport | undefined;
- isLoadingArchitectureGraph: boolean;
+ /** @deprecated Unread. The "architecture" scope draws the constellation from
+ * {@link constellationGraph}, not a file-graph export. Kept optional so an
+ * out-of-tree host compiles while it drops them. */
+ architectureGraph?: GraphExport | undefined;
+ /** @deprecated Unread. See {@link architectureGraph}. */
+ isLoadingArchitectureGraph?: boolean | undefined;
/** Community super-graph for the constellation (radial Knowledge Graph) scope. */
constellationGraph?: ArchitectureGraph | undefined;
isLoadingConstellationGraph?: boolean;
@@ -81,6 +86,10 @@ export interface GraphFlowProps {
isLoadingHotFilesGraph: boolean;
communities?: CommunitySummaryItem[];
executionFlows?: ExecutionFlows;
+ /** Fired when the flows panel opens or closes, so a host can defer fetching
+ * {@link executionFlows} until someone asks. Optional; ignoring it keeps the
+ * eager behaviour. */
+ onFlowsVisibilityChange?: ((visible: boolean) => void) | undefined;
initialViewMode?: ViewMode;
/** Controlled scope. Scope is now steered from the page's section header
* (`GraphScopeSwitcher`) rather than from a pill cluster on the canvas, so
@@ -129,10 +138,21 @@ export interface GraphFlowProps {
/** Blossom this community's files on the canvas (expand affordance). */
onExpandOnCanvas: () => void;
}) => ReactNode;
- /** Fired when the community detail panel transitions to open. Lets the
- * hosting page dismiss any competing right-rail panel (doc panel etc.)
- * so the right side is a single sidebar. */
+ /** Fired when the community detail panel transitions to open. */
onCommunityPanelOpen?: (communityId: number) => void;
+ /** Fired when canvas selection changes. A host owning `rail` content tied to
+ * a node (a doc panel) uses this to drop it once a different node is
+ * selected, instead of masking the inspector indefinitely. */
+ onSelectedNodeChange?: ((nodeId: string | null) => void) | undefined;
+ /** One-line explanation of the current scope, shown in the header row. */
+ description?: string;
+ /** Host controls placed left of the toolbar (scope switcher, module filter). */
+ headerActions?: ReactNode;
+ /** Full-width notice above the canvas (e.g. the truncation banner). */
+ banner?: ReactNode;
+ /** Host-owned rail content, e.g. a documentation panel. Takes the rail over
+ * the community and inspection panels; see the precedence in the render. */
+ rail?: ReactNode;
}
export function GraphFlow(props: GraphFlowProps) {
@@ -150,6 +170,7 @@ export function GraphFlow(props: GraphFlowProps) {
isLoadingHotFilesGraph,
communities,
executionFlows,
+ onFlowsVisibilityChange,
initialViewMode,
viewMode: controlledViewMode,
activeModule: controlledActiveModule,
@@ -166,6 +187,11 @@ export function GraphFlow(props: GraphFlowProps) {
renderPathFinder,
renderCommunityPanel,
onCommunityPanelOpen,
+ onSelectedNodeChange,
+ description,
+ headerActions,
+ banner,
+ rail,
} = props;
const sigmaRef = useRef<SigmaCanvasHandle>(null);
@@ -263,6 +289,15 @@ export function GraphFlow(props: GraphFlowProps) {
setActiveFlowIdx(null);
}, []);
+ // Reported from one place, not from each of the six setters that close it.
+ useEffect(() => {
+ onFlowsVisibilityChange?.(showFlows);
+ }, [showFlows, onFlowsVisibilityChange]);
+
+ useEffect(() => {
+ onSelectedNodeChange?.(selectedNodeId);
+ }, [selectedNodeId, onSelectedNodeChange]);
+
// Community detail panel (the filter state itself lives in useCommunityFilter)
const [communityPanelId, setCommunityPanelId] = useState<number | null>(null);
@@ -749,6 +784,9 @@ export function GraphFlow(props: GraphFlowProps) {
}
}
setSelectedNodeId(nodeId);
+ // The community panel describes a hub; selecting a file replaces it in
+ // the rail rather than outranking the inspector forever.
+ setCommunityPanelId(null);
},
[selectedNodeId, sigmaGraph, openCommunityPanel],
);
@@ -959,23 +997,233 @@ export function GraphFlow(props: GraphFlowProps) {
if (isLoading || isAwaitingAsyncBuild || (isBuildingGraph && !sigmaGraph))
return <Skeleton className="h-full w-full rounded-lg" />;
- // What the top-left status panel has to say, if anything. It is one bordered
- // panel now, so it must not render when every row inside it is empty — an
- // empty box is worse than the four separate chips it replaced.
const showOverlayCounts =
!!sigmaGraph && sigmaGraph.order > 0 && (isDeadView || isHotView);
const hasCanvasStatus =
(isEgoActive && !!selectedNodeId) || (showOverlayCounts && !!overlayStats);
- // The canvas is what the reader came for, so it sits on the page plane
- // rather than below it (rule 8). Dark mode used to paint
- // `--color-bg-inset`, which the July ramp move took a full step darker than
- // the `--color-bg-root` page around it, so the graph read as a hole cut in
- // the app. Light mode never painted anything and has always looked right;
- // this makes dark do what light already did. Same call the knowledge-graph
- // canvas made in `zoom/theme.ts`.
+ const inspectedFile = selectedNodeId
+ ? effectiveNodeDataMap.get(selectedNodeId)
+ : undefined;
+ const inspectedNode = selectedNodeId
+ ? (inspectedFile ?? effectiveModuleDataMap.get(selectedNodeId))
+ : undefined;
+
+ // One rail, most-explicit intent first. Path finder and flows are opened by
+ // hand, docs are asked for by name, a community panel follows a hub click,
+ // and the inspector is merely a selection. Three panels used to stack on the
+ // same edge with a host callback arbitrating between them.
+ const railContent = showPathFinder && renderPathFinder
+ ? renderPathFinder({
+ initialFrom: pathFrom,
+ initialTo: pathTo,
+ onPathFound: handlePathFound,
+ onClear: handlePathClear,
+ onClose: () => setShowPathFinder(false),
+ })
+ : showFlows
+ ? executionFlows && executionFlows.flows.length > 0
+ ? (
+ <GraphFlowPanel
+ flows={executionFlows}
+ activeFlowIdx={activeFlowIdx}
+ onSelect={handleFlowSelect}
+ onClose={handleFlowsClose}
+ missingCount={activeFlowMissingCount}
+ />
+ )
+ : (
+ // The trace fetch is deferred until this panel opens, so the first
+ // open has nothing yet. Saying so beats an empty rail.
+ <div className="p-4 text-xs text-[var(--color-text-secondary)]">
+ {executionFlows ? "No execution flows for this scope." : "Loading execution flows…"}
+ </div>
+ )
+ : rail
+ ? rail
+ : communityPanelId !== null && renderCommunityPanel
+ ? renderCommunityPanel({
+ communityId: communityPanelId,
+ onClose: () => setCommunityPanelId(null),
+ onExpandOnCanvas: () => handleConstellationHubToggle(communityPanelId),
+ })
+ : selectedNodeId && inspectedNode
+ ? (
+ <GraphInspectionPanel
+ nodeId={selectedNodeId}
+ data={inspectedNode}
+ graph={sigmaGraph}
+ allNodes={effectiveNodeDataMap}
+ communityLabel={
+ inspectedFile
+ ? communityLabels?.get(inspectedFile.communityId)
+ : undefined
+ }
+ onClose={() => { setSelectedNodeId(null); }}
+ onNavigateToNode={handleInspectNavigate}
+ onViewDocs={() => { onNodeViewDocs?.(selectedNodeId); }}
+ onViewSymbols={
+ inspectedFile && onNodeViewSymbols
+ ? () => { onNodeViewSymbols(selectedNodeId); }
+ : undefined
+ }
+ filePageHref={inspectedFile ? fileHrefFor?.(selectedNodeId) : undefined}
+ onFindPath={handleInspectFindPath}
+ isModuleExpanded={false}
+ egoDepth={egoDepth}
+ onEgoDepthChange={setEgoDepth}
+ egoVisibleCount={egoVisibleCount}
+ />
+ )
+ : undefined;
+
return (
- <div className="relative w-full h-full" style={{ touchAction: "none", ...(graphTheme === "dark" ? { background: "var(--color-bg-root)" } : {}) }} aria-label="Dependency graph">
+ <GraphCanvasShell
+ description={description}
+ titleActions={
+ <div className="flex flex-wrap items-center justify-end gap-2">
+ {headerActions}
+ <GraphToolbar
+ viewMode={viewMode}
+ onViewChange={handleViewChange}
+ colorMode={colorMode}
+ onColorModeChange={setColorMode}
+ hideTests={hideTests}
+ onHideTestsChange={(v) => {
+ setActiveSignals(prev => {
+ const next = new Set(prev);
+ if (v) next.add("hideTests");
+ else next.delete("hideTests");
+ return next;
+ });
+ }}
+ onFitView={handleFitView}
+ showPathFinder={showPathFinder}
+ pathFinderAvailable={Boolean(renderPathFinder)}
+ onTogglePathFinder={() => {
+ setShowPathFinder((s) => !s);
+ setShowFlows(false);
+ setActiveFlowIdx(null);
+ }}
+ showFlows={showFlows}
+ onToggleFlows={() => {
+ setShowFlows((s) => !s);
+ setActiveFlowIdx(null);
+ setShowPathFinder(false);
+ }}
+ searchQuery={searchQuery}
+ onSearchChange={setSearchQuery}
+ searchMatchCount={searchResults.length}
+ searchTotalCount={sigmaGraph?.order ?? 0}
+ onSearchKeyDown={handleSearchKeyDown}
+ layoutMode={layoutMode}
+ onLayoutModeChange={handleLayoutModeChange}
+ onToggleHelp={handleToggleShortcutHelp}
+ hierarchicalDisabledReason={
+ sigmaGraph && sigmaGraph.order > ELK_MAX_NODES
+ ? elkSkipReason(sigmaGraph.order)
+ : undefined
+ }
+ />
+ </div>
+ }
+ banner={
+ banner || layoutNotice ? (
+ <div className="space-y-2">
+ {banner}
+ {layoutNotice && (
+ <div
+ role="status"
+ aria-live="polite"
+ className="flex items-center gap-2 rounded-lg border border-[var(--color-warning)]/40 bg-[var(--color-bg-elevated)] px-3 py-1.5"
+ >
+ <span className="text-[11px] text-[var(--color-text-primary)]">{layoutNotice}</span>
+ <button
+ onClick={() => setLayoutNotice(null)}
+ aria-label="Dismiss layout notice"
+ className="shrink-0 text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)]"
+ >
+ <X className="w-3 h-3" />
+ </button>
+ </div>
+ )}
+ </div>
+ ) : undefined
+ }
+ rail={railContent}
+ footer={
+ <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
+ <GraphLegend
+ nodeCount={sigmaGraph?.order ?? 0}
+ edgeCount={sigmaGraph?.size ?? 0}
+ colorMode={colorMode}
+ viewMode={viewMode}
+ {...(communityLabels ? { communityLabels } : {})}
+ onCommunityClick={openCommunityPanel}
+ activeCommunities={activeCommunities ?? undefined}
+ onCommunityToggle={handleCommunityToggle}
+ onToggleAllCommunities={handleToggleAllCommunities}
+ visibleEdgeTypes={isConstellation ? undefined : visibleEdgeTypes}
+ onEdgeTypeToggle={isConstellation ? undefined : handleEdgeTypeToggle}
+ graphTheme={graphTheme}
+ constellationEntries={isConstellation ? constellationLegend : undefined}
+ onConstellationHubClick={handleConstellationHubClick}
+ />
+ {hasCanvasStatus && (
+ <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
+ {isEgoActive && selectedNodeId ? (
+ <span className="flex items-center gap-2 text-[11px] text-[var(--color-accent-primary)]">
+ <span role="status" aria-live="polite">
+ Showing {egoVisibleCount} nodes within {egoDepth} hop{egoDepth === 1 ? "" : "s"} of{" "}
+ <span className="font-mono font-medium">{selectedNodeId.split("/").pop()}</span>
+ </span>
+ <button
+ onClick={() => setEgoDepth(0)}
+ className="rounded px-1 py-0.5 text-[var(--color-text-tertiary)] underline hover:text-[var(--color-text-primary)]"
+ >
+ Clear
+ </button>
+ </span>
+ ) : null}
+ {showOverlayCounts && overlayStats && (
+ <span role="status" aria-live="polite" className="flex flex-wrap items-center gap-x-3">
+ {isDeadView && (
+ <OverlayCountChip kind="dead" inView={overlayStats.deadInView} total={deadTotal} />
+ )}
+ {isHotView && (
+ <OverlayCountChip kind="hot" inView={overlayStats.hotInView} total={hotTotal} />
+ )}
+ </span>
+ )}
+ </div>
+ )}
+ </div>
+ }
+ overlay={
+ <>
+ {ctxMenu && (
+ <GraphContextMenu
+ x={ctxMenu.x}
+ y={ctxMenu.y}
+ nodeId={ctxMenu.nodeId}
+ isModule={ctxMenu.nodeType === "moduleGroup"}
+ onViewDocs={handleCtxViewDocs}
+ onExplore={handleCtxExplore}
+ onPathFrom={handleCtxPathFrom}
+ onPathTo={handleCtxPathTo}
+ />
+ )}
+ {showShortcutHelp && (
+ <GraphShortcutHelp onClose={() => setShowShortcutHelp(false)} />
+ )}
+ </>
+ }
+ >
+ <div
+ className="relative h-full w-full"
+ style={{ touchAction: "none", ...(graphTheme === "dark" ? { background: "var(--color-bg-root)" } : {}) }}
+ aria-label="Dependency graph"
+ >
{sigmaGraph && sigmaGraph.order > 0 ? (
<SigmaCanvas
ref={sigmaRef}
@@ -1013,247 +1261,13 @@ export function GraphFlow(props: GraphFlowProps) {
/>
</div>
) : null}
-
- {/* Canvas status, top-left. One panel with hairline rows, matching the
- toolbar, the legend and the zoom controls — this corner could
- otherwise stack four independently-bordered, independently-shadowed
- chips (breadcrumb, expanded-modules, loading, tip, overlay counts)
- over the diagram at once. Rendered only when it has something to
- say, so an idle canvas carries no chrome here at all (rule 10). */}
- {hasCanvasStatus && (
- <div className={`absolute top-3 left-3 z-10 flex flex-col items-stretch overflow-hidden ${canvasPanelClass}`}>
- {isEgoActive && selectedNodeId ? (
- <div>
- <div className={canvasRowClass}>
- <span className="text-[10px] text-[var(--color-accent-primary)]">
- Showing {egoVisibleCount} nodes within {egoDepth} hop{egoDepth === 1 ? "" : "s"} of{" "}
- <span className="font-mono font-medium">{selectedNodeId.split("/").pop()}</span>
- </span>
- <button
- onClick={() => setEgoDepth(0)}
- className="text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)] text-[10px]"
- >
- Clear
- </button>
- </div>
- </div>
- ) : null}
-
- {/* Overlay coverage: how many flagged files are actually in view. The
- totals come from the backend when it provides them; without totals
- we still report the in-view count so the overlay never reads as
- silently doing nothing. */}
- {showOverlayCounts && overlayStats && (
- <>
- {isDeadView && (
- <OverlayCountChip
- kind="dead"
- inView={overlayStats.deadInView}
- total={deadTotal}
- />
- )}
- {isHotView && (
- <OverlayCountChip
- kind="hot"
- inView={overlayStats.hotInView}
- total={hotTotal}
- />
- )}
- </>
- )}
- </div>
- )}
-
- {/* Layout-skipped notice: the hierarchical toggle must never look
- active while silently doing nothing. */}
- {layoutNotice && (
- <div
- role="status"
- aria-live="polite"
- className="absolute top-3 left-1/2 -translate-x-1/2 z-10 flex max-w-[min(28rem,calc(100vw-6rem))] items-center gap-2 rounded-lg border border-[var(--color-warning)]/40 bg-[var(--color-bg-elevated)]/95 backdrop-blur-sm px-3 py-1.5 shadow-sm"
- >
- <span className="text-[11px] text-[var(--color-text-primary)]">{layoutNotice}</span>
- <button
- onClick={() => setLayoutNotice(null)}
- aria-label="Dismiss layout notice"
- className="shrink-0 text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)]"
- >
- <X className="w-3 h-3" />
- </button>
- </div>
- )}
-
- {/* Toolbar */}
- <div className="absolute top-3 right-3 z-10">
- <GraphToolbar
- viewMode={viewMode}
- onViewChange={handleViewChange}
- colorMode={colorMode}
- onColorModeChange={setColorMode}
- hideTests={hideTests}
- onHideTestsChange={(v) => {
- setActiveSignals(prev => {
- const next = new Set(prev);
- v ? next.add("hideTests") : next.delete("hideTests");
- return next;
- });
- }}
- onFitView={handleFitView}
- showPathFinder={showPathFinder}
- pathFinderAvailable={Boolean(renderPathFinder)}
- onTogglePathFinder={() => {
- // Path finder and flows share the same overlay slot — opening
- // one always closes the other.
- setShowPathFinder((s) => !s);
- setShowFlows(false);
- setActiveFlowIdx(null);
- }}
- showFlows={showFlows}
- onToggleFlows={() => {
- setShowFlows((s) => !s);
- setActiveFlowIdx(null);
- setShowPathFinder(false);
- }}
- searchQuery={searchQuery}
- onSearchChange={setSearchQuery}
- searchMatchCount={searchResults.length}
- searchTotalCount={sigmaGraph?.order ?? 0}
- onSearchKeyDown={handleSearchKeyDown}
- layoutMode={layoutMode}
- onLayoutModeChange={handleLayoutModeChange}
- onToggleHelp={handleToggleShortcutHelp}
- hierarchicalDisabledReason={
- sigmaGraph && sigmaGraph.order > ELK_MAX_NODES
- ? elkSkipReason(sigmaGraph.order)
- : undefined
- }
- />
- </div>
-
- {/* Path Finder. Carries the same viewport clamp as the flows panel below;
- without it the panel runs off the side of a phone. */}
- {showPathFinder && renderPathFinder && (
- <div className="absolute top-14 right-3 z-10 w-[min(20rem,calc(100vw-1.5rem))]">
- {renderPathFinder({
- initialFrom: pathFrom,
- initialTo: pathTo,
- onPathFound: handlePathFound,
- onClear: handlePathClear,
- onClose: () => setShowPathFinder(false),
- })}
- </div>
- )}
-
- {/* Execution Flows Panel */}
- {showFlows && executionFlows && executionFlows.flows.length > 0 && (
- <div className="absolute top-14 right-3 z-10 w-[min(16rem,calc(100vw-1.5rem))]">
- <GraphFlowPanel
- flows={executionFlows}
- activeFlowIdx={activeFlowIdx}
- onSelect={handleFlowSelect}
- onClose={handleFlowsClose}
- missingCount={activeFlowMissingCount}
- />
- </div>
- )}
-
- {/* Legend — on phones the inspection bottom sheet covers this corner,
- so yield to it instead of stacking underneath. */}
- <div className={`absolute bottom-3 left-3 z-10 ${selectedNodeId ? "hidden sm:block" : ""}`}>
- <GraphLegend
- nodeCount={sigmaGraph?.order ?? 0}
- edgeCount={sigmaGraph?.size ?? 0}
- colorMode={colorMode}
- viewMode={viewMode}
- {...(communityLabels ? { communityLabels } : {})}
- onCommunityClick={openCommunityPanel}
- activeCommunities={activeCommunities ?? undefined}
- onCommunityToggle={handleCommunityToggle}
- onToggleAllCommunities={handleToggleAllCommunities}
- visibleEdgeTypes={isConstellation ? undefined : visibleEdgeTypes}
- onEdgeTypeToggle={isConstellation ? undefined : handleEdgeTypeToggle}
- graphTheme={graphTheme}
- constellationEntries={isConstellation ? constellationLegend : undefined}
- onConstellationHubClick={handleConstellationHubClick}
- />
</div>
-
- {/* Keyboard shortcut help (toggled with ?) */}
- {showShortcutHelp && (
- <GraphShortcutHelp onClose={() => setShowShortcutHelp(false)} />
- )}
-
- {/* Context menu */}
- {ctxMenu && (
- <GraphContextMenu
- x={ctxMenu.x}
- y={ctxMenu.y}
- nodeId={ctxMenu.nodeId}
- isModule={ctxMenu.nodeType === "moduleGroup"}
- onViewDocs={handleCtxViewDocs}
- onExplore={handleCtxExplore}
- onPathFrom={handleCtxPathFrom}
- onPathTo={handleCtxPathTo}
- />
- )}
-
- {/* Community detail panel */}
- {communityPanelId !== null && renderCommunityPanel &&
- renderCommunityPanel({
- communityId: communityPanelId,
- onClose: () => setCommunityPanelId(null),
- onExpandOnCanvas: () => handleConstellationHubToggle(communityPanelId),
- })}
-
- {/* Inspection panel — works for both file and module nodes */}
- {selectedNodeId && (() => {
- const fileNd = effectiveNodeDataMap.get(selectedNodeId);
- const modNd = effectiveModuleDataMap.get(selectedNodeId);
- const nd = fileNd ?? modNd;
- if (!nd) return null;
- return (
- <GraphInspectionPanel
- nodeId={selectedNodeId}
- data={nd}
- graph={sigmaGraph}
- allNodes={effectiveNodeDataMap}
- communityLabel={fileNd ? communityLabels?.get(fileNd.communityId) : undefined}
- onClose={() => { setSelectedNodeId(null); }}
- onNavigateToNode={handleInspectNavigate}
- onViewDocs={() => { onNodeViewDocs?.(selectedNodeId); }}
- onViewSymbols={
- fileNd && onNodeViewSymbols
- ? () => { onNodeViewSymbols(selectedNodeId); }
- : undefined
- }
- filePageHref={fileNd ? fileHrefFor?.(selectedNodeId) : undefined}
- onFindPath={handleInspectFindPath}
- isModuleExpanded={false}
- egoDepth={egoDepth}
- onEgoDepthChange={setEgoDepth}
- egoVisibleCount={egoVisibleCount}
- />
- );
- })()}
- </div>
+ </GraphCanvasShell>
);
}
-/**
- * Chrome for the top-left status panel. Shares the toolbar / legend / zoom
- * treatment so every corner of the canvas reads as one system: one border, one
- * shadow, one blur, and hairline dividers instead of gaps between boxes.
- */
-const canvasPanelClass =
- "rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)]/85 shadow-sm backdrop-blur-sm";
-
-/** One row inside that panel. `first:border-t-0` keeps the top edge clean. */
-const canvasRowClass =
- "flex items-center gap-2 border-t border-[var(--color-border-default)] px-2.5 py-1.5 first:border-t-0";
-
-/** Small status chip captioning a dead/hot view: "12 of 37 dead files in
- * view" when the backend supplies repo-wide totals, or just the in-view
- * count when it doesn't. */
+/** Caption for a dead/hot view: "12 of 37 dead files in view" when the backend
+ * supplies repo-wide totals, or just the in-view count when it does not. */
function OverlayCountChip({
kind,
inView,
@@ -1266,15 +1280,13 @@ function OverlayCountChip({
const noun = kind === "dead" ? "dead files" : "hot files";
let text: string;
if (total != null && inView < total) {
- text = `${inView} of ${total} ${noun} in view — the rest are outside the loaded node set`;
+ text = `${inView} of ${total} ${noun} in view; the rest are outside the loaded node set`;
} else if (total != null) {
text = `Showing all ${total} ${noun}`;
} else {
text = `${inView} ${noun} in view`;
}
- return (
- <div role="status" className={canvasRowClass}>
- <span className="text-[10px] text-[var(--color-text-secondary)]">{text}</span>
- </div>
- );
+ // No role here: the footer wrapper is already the live region, and nesting
+ // one inside another gets the text announced twice.
+ return <span className="text-[11px] text-[var(--color-text-secondary)]">{text}</span>;
}
diff --git a/packages/ui/src/graph/graph-inspection-panel.tsx b/packages/ui/src/graph/graph-inspection-panel.tsx
index 00af5a680..c831c1fcb 100644
--- a/packages/ui/src/graph/graph-inspection-panel.tsx
+++ b/packages/ui/src/graph/graph-inspection-panel.tsx
@@ -146,21 +146,24 @@ export const GraphInspectionPanel = memo(function GraphInspectionPanel({
return (
<div
- // Right panel on sm+; bottom sheet (drag handle + swipe-dismiss) below.
- className="absolute inset-x-0 bottom-0 top-auto max-h-[70%] rounded-t-xl border-t border-[var(--color-border-default)] bg-[var(--color-bg-surface)] z-20 flex flex-col shadow-xl shadow-black/20 animate-in slide-in-from-bottom sm:slide-in-from-bottom-0 sm:slide-in-from-right duration-200 sm:inset-x-auto sm:right-0 sm:top-0 sm:bottom-0 sm:left-auto sm:w-[300px] sm:max-h-none sm:rounded-none sm:border-t-0 sm:border-l"
+ // Fills the shell's rail slot, which owns placement (sheet under lg,
+ // grid column above). Keeps the swipe-to-dismiss gesture for the sheet.
+ className="flex h-full min-h-0 flex-col"
onTouchStart={(e) => {
touchStartY.current = e.touches[0]?.clientY ?? null;
}}
onTouchEnd={(e) => {
const start = touchStartY.current;
touchStartY.current = null;
- if (start == null || window.innerWidth >= 640) return;
+ // Matches the shell's rail breakpoint: above lg this is a grid column,
+ // not a sheet, so there is nothing to swipe away.
+ if (start == null || window.innerWidth >= 1024) return;
const end = e.changedTouches[0]?.clientY ?? start;
if (end - start > 80) onClose();
}}
>
{/* Drag handle (mobile sheet only) */}
- <div className="flex justify-center py-1.5 sm:hidden" aria-hidden>
+ <div className="flex justify-center py-1.5 lg:hidden" aria-hidden>
<span className="h-1 w-9 rounded-full bg-[var(--color-border-default)]" />
</div>
{/* Header */}
@@ -176,6 +179,7 @@ export const GraphInspectionPanel = memo(function GraphInspectionPanel({
</div>
<button
onClick={onClose}
+ aria-label="Close inspector"
className="p-1 rounded hover:bg-[var(--color-bg-elevated)] transition-colors shrink-0"
>
<X className="h-4 w-4 text-[var(--color-text-tertiary)]" />
diff --git a/packages/ui/src/graph/graph-legend.tsx b/packages/ui/src/graph/graph-legend.tsx
index a06a142e6..44bae78af 100644
--- a/packages/ui/src/graph/graph-legend.tsx
+++ b/packages/ui/src/graph/graph-legend.tsx
@@ -7,6 +7,9 @@ import { edgeColorsForTheme } from "./sigma/constants";
import { useCommunityFamilies } from "../shared/use-theme-tokens";
import type { ColorMode, ViewMode } from "./graph-toolbar";
+/** Community rows shown before the key folds into a "+N" line. */
+const COMMUNITY_ROWS = 8;
+
const LANGUAGE_LEGEND = [
{ lang: "python", color: LANGUAGE_COLORS.python, label: "Python" },
{ lang: "typescript", color: LANGUAGE_COLORS.typescript, label: "TypeScript" },
@@ -29,19 +32,19 @@ const LANGUAGE_LEGEND = [
* large fraction of its content, it wants merging".
*/
const shellClass =
- "overflow-hidden rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)]/85 text-xs shadow-sm backdrop-blur-sm";
+ "flex w-full flex-wrap items-center gap-x-4 gap-y-1.5 border-t border-[var(--color-border-default)] pt-2 text-xs";
const headerClass =
- "flex w-full items-center justify-between gap-2 px-2.5 py-1.5 text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-text-primary)]";
+ "inline-flex shrink-0 items-center gap-1 rounded py-1.5 text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-text-primary)] sm:py-0";
const countClass = "font-mono text-[10px] tabular-nums tracking-[0.04em]";
const rowClass =
- "flex w-full items-center gap-2 rounded px-1.5 py-1 text-left text-[11px] text-[var(--color-text-secondary)] transition-colors hover:bg-[var(--color-bg-wash-hover)] hover:text-[var(--color-text-primary)]";
+ "inline-flex items-center gap-1.5 rounded px-1.5 py-1.5 text-left text-[11px] text-[var(--color-text-secondary)] transition-colors hover:bg-[var(--color-bg-wash-hover)] hover:text-[var(--color-text-primary)] sm:py-0.5";
/** Section label inside the key. Mono micro-label, no rule above it. */
const groupClass =
- "px-1.5 pt-1.5 pb-0.5 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]";
+ "shrink-0 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]";
function Chevron({ expanded }: { expanded: boolean }) {
const Icon = expanded ? ChevronDown : ChevronUp;
@@ -124,10 +127,8 @@ export const GraphLegend = memo(function GraphLegend({
constellationEntries,
onConstellationHubClick,
}: GraphLegendProps) {
- // Open by default. Every node on the canvas is painted from this key, so
- // collapsing it ships a field of coloured circles with no way to read them
- // until the reader thinks to click a counter. The key is the cheapest thing
- // on screen and the only one that makes the rest mean anything.
+ // Open by default: every node is painted from this key, so a collapsed one
+ // ships a field of coloured circles with no way to read them.
const [expanded, setExpanded] = useState(true);
const communityFamily = useCommunityFamilies();
const edgeColors = edgeColorsForTheme(graphTheme);
@@ -147,9 +148,9 @@ export const GraphLegend = memo(function GraphLegend({
<Chevron expanded={expanded} />
</button>
{expanded && (
- <div className="space-y-px px-1.5 pb-1.5">
+ <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
{entries.length === 0 && (
- <p className="px-1.5 py-1 text-[11px] text-[var(--color-text-tertiary)]">
+ <p className="text-[11px] text-[var(--color-text-tertiary)]">
No communities detected
</p>
)}
@@ -162,7 +163,7 @@ export const GraphLegend = memo(function GraphLegend({
className={rowClass}
>
<Swatch color={color} />
- <span className="min-w-0 flex-1 truncate">{e.label}</span>
+ <span className="truncate max-w-[12rem]">{e.label}</span>
<span className="shrink-0 tabular-nums text-[10px] text-[var(--color-text-tertiary)]">
{e.memberCount}
</span>
@@ -170,13 +171,10 @@ export const GraphLegend = memo(function GraphLegend({
);
})}
{overflow > 0 && (
- <p className="px-1.5 pt-1 text-[10px] text-[var(--color-text-tertiary)]">
+ <p className="text-[10px] text-[var(--color-text-tertiary)]">
+{overflow} smaller not listed
</p>
)}
- <p className="px-1.5 pt-1.5 text-[10px] text-[var(--color-text-tertiary)]">
- Inner ring = entry surface
- </p>
</div>
)}
</div>
@@ -184,7 +182,7 @@ export const GraphLegend = memo(function GraphLegend({
}
return (
- <div className={`${shellClass} min-w-[148px] max-w-[190px]`}>
+ <div className={shellClass}>
<button onClick={() => setExpanded((s) => !s)} className={headerClass}>
<span className={countClass}>
{nodeCount} nodes &middot; {edgeCount} edges
@@ -193,7 +191,7 @@ export const GraphLegend = memo(function GraphLegend({
</button>
{expanded && (
- <div className="space-y-px px-1.5 pb-1.5">
+ <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
<p className={groupClass}>
{colorMode === "language" ? "Language" : "Community"}
</p>
@@ -202,7 +200,7 @@ export const GraphLegend = memo(function GraphLegend({
LANGUAGE_LEGEND.map((l) => (
<div
key={l.lang}
- className="flex items-center gap-2 px-1.5 py-0.5 text-[11px] text-[var(--color-text-secondary)]"
+ className="inline-flex items-center gap-1.5 text-[11px] text-[var(--color-text-secondary)]"
>
<Swatch color={l.color} />
<span className="truncate">{l.label}</span>
@@ -210,9 +208,11 @@ export const GraphLegend = memo(function GraphLegend({
))}
{colorMode === "community" && (() => {
- const entries = communityLabels && communityLabels.size > 0
- ? Array.from(communityLabels.entries()).slice(0, 8)
+ const all = communityLabels && communityLabels.size > 0
+ ? Array.from(communityLabels.entries())
: null;
+ const entries = all ? all.slice(0, COMMUNITY_ROWS) : null;
+ const overflow = all ? all.length - entries!.length : 0;
const allSelected = !activeCommunities || (entries
? entries.every(([cid]) => activeCommunities.has(cid))
: true);
@@ -221,7 +221,7 @@ export const GraphLegend = memo(function GraphLegend({
{onToggleAllCommunities && entries && (
<button
onClick={() => onToggleAllCommunities(!allSelected)}
- className="px-1.5 pb-0.5 text-[10px] font-medium text-[var(--color-accent-primary)] hover:underline"
+ className="shrink-0 text-[10px] font-medium text-[var(--color-accent-primary)] hover:underline"
>
{allSelected ? "Deselect all" : "Select all"}
</button>
@@ -242,24 +242,34 @@ export const GraphLegend = memo(function GraphLegend({
) : (
<Swatch color={color} />
)}
- <span
- className="min-w-0 flex-1 truncate"
- onClick={() => onCommunityClick?.(cid)}
- >
- {label}
- </span>
+ {onCommunityClick ? (
+ <button
+ type="button"
+ onClick={() => onCommunityClick(cid)}
+ className="max-w-[12rem] truncate rounded hover:text-[var(--color-text-primary)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent-primary)]"
+ >
+ {label}
+ </button>
+ ) : (
+ <span className="max-w-[12rem] truncate">{label}</span>
+ )}
</div>
);
})
: Array.from({ length: 6 }, (_, i) => (
<div
key={i}
- className="flex items-center gap-2 px-1.5 py-0.5 text-[11px] text-[var(--color-text-secondary)]"
+ className="inline-flex items-center gap-1.5 text-[11px] text-[var(--color-text-secondary)]"
>
<Swatch color={communityFamily(i).hub} />
<span className="truncate">Community {i + 1}</span>
</div>
))}
+ {overflow > 0 && (
+ <p className="text-[10px] text-[var(--color-text-tertiary)]">
+ +{overflow} smaller not listed
+ </p>
+ )}
</>
);
})()}
@@ -283,9 +293,7 @@ export const GraphLegend = memo(function GraphLegend({
label={`Toggle ${et.label} edges`}
onToggle={() => onEdgeTypeToggle(et.type)}
/>
- <span
- className={`min-w-0 flex-1 truncate ${checked ? "" : "opacity-45"}`}
- >
+ <span className={`truncate ${checked ? "" : "opacity-45"}`}>
{et.label}
</span>
</div>
@@ -295,10 +303,10 @@ export const GraphLegend = memo(function GraphLegend({
)}
{viewMode !== "full" && (
- <p className="px-1.5 pt-1.5 text-[10px] text-[var(--color-text-tertiary)]">
+ <p className="text-[10px] text-[var(--color-text-tertiary)]">
{viewMode === "dead" && "Showing unreachable files"}
{viewMode === "hotfiles" && "Most-committed files (30d)"}
- {viewMode === "unified" && "Unified: community + risk signals"}
+ {viewMode === "unified" && "Dead and high-churn files"}
</p>
)}
</div>
diff --git a/packages/ui/src/graph/graph-shortcut-help.tsx b/packages/ui/src/graph/graph-shortcut-help.tsx
index c8cf66f91..bb93cce03 100644
--- a/packages/ui/src/graph/graph-shortcut-help.tsx
+++ b/packages/ui/src/graph/graph-shortcut-help.tsx
@@ -8,7 +8,8 @@ const SHORTCUTS: { keys: string[]; action: string }[] = [
{ keys: ["⌘K"], action: "Focus search" },
{ keys: ["1"], action: "Color by language" },
{ keys: ["2"], action: "Color by community" },
- { keys: ["3"], action: "Color by risk" },
+ { keys: ["↑", "↓"], action: "Step through search results" },
+ { keys: ["Enter"], action: "Select the highlighted search result" },
{ keys: ["Esc"], action: "Dismiss top layer (panel, selection, blossom…)" },
{ keys: ["?"], action: "Toggle this help" },
];
@@ -22,7 +23,7 @@ const GESTURES: { gesture: string; action: string }[] = [
/** Keyboard + gesture cheatsheet, toggled with `?`. */
export function GraphShortcutHelp({ onClose }: { onClose: () => void }) {
return (
- <div className="absolute inset-0 z-20 flex items-center justify-center bg-black/40 p-4" onClick={onClose}>
+ <div className="absolute inset-0 z-30 flex items-center justify-center bg-black/40 p-4" onClick={onClose}>
<div
className="w-full max-w-sm rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] p-4 shadow-xl shadow-black/30"
onClick={(e) => e.stopPropagation()}
diff --git a/packages/ui/src/graph/graph-toolbar.tsx b/packages/ui/src/graph/graph-toolbar.tsx
index 1ad96fd93..a669832b0 100644
--- a/packages/ui/src/graph/graph-toolbar.tsx
+++ b/packages/ui/src/graph/graph-toolbar.tsx
@@ -6,7 +6,6 @@ import {
EyeOff,
Maximize,
Route,
- GitFork,
Skull,
Flame,
Workflow,
@@ -142,31 +141,17 @@ const LAYOUT_MODES: { id: LayoutMode; icon: typeof GitBranch; label: string }[]
{ id: "hierarchical", icon: GitBranch, label: "Hierarchical" },
];
-// The constellation (Knowledge Graph) scope is always radial — a single
-// disabled-looking indicator replaces the Force/Hierarchical toggle there.
-const RADIAL_LAYOUT: { id: LayoutMode; icon: typeof GitFork; label: string } = {
- id: "radial",
- icon: GitFork,
- label: "Radial",
-};
-
/**
- * One panel, not four.
- *
- * Scope, node filter, the layout/colour/action row and search each used to be
- * their own rounded box with its own border, its own `shadow-sm` and its own
- * `backdrop-blur-sm`, stacked down the same edge with 6px of canvas showing
- * between them. Four frames and four shadows for one control surface, over a
- * diagram the reader is trying to look past (rule 13). They are now one shell
- * with hairline dividers, sharing the legend's chrome so the two corners of
- * the canvas read as the same system.
+ * One control surface in the section header. Translucency, blur and a shadow
+ * are how chrome sits over a diagram; this lives on the page plane now, so it
+ * takes a plain hairline frame instead.
*/
const panelClass =
- "overflow-hidden rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)]/85 shadow-sm backdrop-blur-sm";
+ "overflow-hidden rounded-lg border border-[var(--color-border-default)]";
/** A divider row inside the panel. The first group omits the top hairline. */
const groupClass =
- "flex items-center gap-0.5 p-1 border-t border-[var(--color-border-default)] first:border-t-0";
+ "flex flex-wrap items-center gap-0.5 p-1 border-t border-[var(--color-border-default)] first:border-t-0";
const itemActiveClass =
"bg-[var(--color-accent-primary)]/15 text-[var(--color-accent-primary)]";
@@ -273,22 +258,9 @@ export const GraphToolbar = memo(function GraphToolbar({
{/* Layout · colour · actions. */}
<div className={`${clusterVisibility} ${groupClass}`}>
+ {!isConstellation && (
<div className="flex gap-0.5">
- {isConstellation ? (
- // Constellation is locked to the radial layout; show a single
- // active indicator instead of the Force/Hierarchical toggle.
- <button
- key={RADIAL_LAYOUT.id}
- disabled
- className={`${itemClass} ${itemActiveClass} cursor-default`}
- title={`${RADIAL_LAYOUT.label} (fixed for Communities)`}
- aria-label={RADIAL_LAYOUT.label}
- aria-pressed
- >
- <RADIAL_LAYOUT.icon className="w-3 h-3" />
- </button>
- ) : (
- LAYOUT_MODES.map((m) => {
+ {LAYOUT_MODES.map((m) => {
const Icon = m.icon;
const isActive = layoutMode === m.id;
const disabledReason =
@@ -309,18 +281,15 @@ export const GraphToolbar = memo(function GraphToolbar({
<Icon className="w-3 h-3" />
</button>
);
- })
- )}
+ })}
</div>
+ )}
- {/* Colour-by. This control decides what every circle on the canvas
- means, and it used to be three unlabelled icons — a palette, a
- network and a shield — so there was no way to know whether you were
- looking at languages, communities or risk without hovering each
- one. Worse, Risk paints green/amber/red and Community paints
- families that include green, amber and red: same marks, two
- vocabularies, switched by a mystery glyph. The active mode now
- always carries its word. */}
+ {/* Colour-by. The active mode always carries its word: unlabelled
+ glyphs gave no way to tell which vocabulary the circles were in.
+ Hidden in the constellation, where hubs are family-coloured
+ regardless of this setting. */}
+ {!isConstellation && (
<div className="flex items-center gap-0.5 border-l border-[var(--color-border-default)] pl-1">
<span className="hidden pl-1 pr-0.5 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)] lg:inline">
Colour
@@ -343,6 +312,7 @@ export const GraphToolbar = memo(function GraphToolbar({
);
})}
</div>
+ )}
{/* No theme control here. It set the *global* theme, so it did exactly
what the app's own toggle in the header does, a few hundred pixels
diff --git a/packages/ui/src/graph/sigma/canvas-ground.tsx b/packages/ui/src/graph/sigma/canvas-ground.tsx
new file mode 100644
index 000000000..241f3b83a
--- /dev/null
+++ b/packages/ui/src/graph/sigma/canvas-ground.tsx
@@ -0,0 +1,90 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import type Sigma from "sigma";
+
+/** Dot spacing in graph units before the octave clamp below. */
+const BASE_SPACING = 40;
+/** Screen-pixel band the spacing is kept inside by doubling / halving. */
+const MIN_PX = 22;
+const MAX_PX = 88;
+const DOT_RADIUS = 1.1;
+
+/** `useId` output is not safe inside `url(#...)`: React 19 emits non-ASCII
+ * delimiters, which percent-encode before the SVG fragment lookup and leave
+ * the fill unresolved. A counter keeps the id ASCII and unique. */
+let groundSeq = 0;
+
+/**
+ * Graph-paper ground under the canvas.
+ *
+ * Dark mode painted `--color-bg-root`, which is also the page body colour, so
+ * canvas and page were the same value and the map read as a void. The plane is
+ * right (the canvas is the subject); it just had nothing on it. Light mode gets
+ * its ground for free from the warm paper root.
+ *
+ * Spacing doubles or halves to stay inside a screen-pixel band, so density
+ * holds steady while the step itself gives the zoom feedback the canvas
+ * otherwise has none of. An SVG pattern moved by one `patternTransform` write
+ * per frame; the tile is only resized when the octave actually steps.
+ */
+export function CanvasGround({ sigma }: { sigma: Sigma | null }) {
+ const patternRef = useRef<SVGPatternElement>(null);
+ const circleRef = useRef<SVGCircleElement>(null);
+ const [patternId] = useState(() => `canvas-ground-${(groundSeq += 1)}`);
+
+ useEffect(() => {
+ if (!sigma) return;
+ const pattern = patternRef.current;
+ const circle = circleRef.current;
+ if (!pattern || !circle) return;
+
+ let lastSpacing = 0;
+ const draw = () => {
+ const origin = sigma.graphToViewport({ x: 0, y: 0 });
+ const unit = sigma.graphToViewport({ x: BASE_SPACING, y: 0 });
+ let spacing = Math.hypot(unit.x - origin.x, unit.y - origin.y);
+ if (!Number.isFinite(spacing) || spacing <= 0) return;
+ while (spacing < MIN_PX) spacing *= 2;
+ while (spacing > MAX_PX) spacing /= 2;
+
+ // Panning only moves the lattice. Resizing the tile invalidates it and
+ // re-rasterises the full-viewport fill, so only do that when the octave
+ // actually steps.
+ if (spacing !== lastSpacing) {
+ lastSpacing = spacing;
+ pattern.setAttribute("width", String(spacing));
+ pattern.setAttribute("height", String(spacing));
+ circle.setAttribute("cx", String(spacing / 2));
+ circle.setAttribute("cy", String(spacing / 2));
+ }
+ pattern.setAttribute(
+ "patternTransform",
+ `translate(${origin.x % spacing},${origin.y % spacing})`,
+ );
+ };
+
+ sigma.on("afterRender", draw);
+ draw();
+ return () => {
+ sigma.off("afterRender", draw);
+ };
+ }, [sigma]);
+
+ return (
+ <svg className="pointer-events-none absolute inset-0 z-0 h-full w-full" aria-hidden="true">
+ <defs>
+ <pattern ref={patternRef} id={patternId} patternUnits="userSpaceOnUse" width={40} height={40}>
+ <circle
+ ref={circleRef}
+ r={DOT_RADIUS}
+ cx={20}
+ cy={20}
+ fill="var(--color-canvas-grid, rgba(128,128,128,0.1))"
+ />
+ </pattern>
+ </defs>
+ <rect width="100%" height="100%" fill={`url(#${patternId})`} />
+ </svg>
+ );
+}
diff --git a/packages/ui/src/graph/sigma/depth-rings.tsx b/packages/ui/src/graph/sigma/depth-rings.tsx
index e4a090f9d..857835a9b 100644
--- a/packages/ui/src/graph/sigma/depth-rings.tsx
+++ b/packages/ui/src/graph/sigma/depth-rings.tsx
@@ -14,8 +14,9 @@ interface DepthRingsProps {
* Faint concentric "depth" rings drawn behind the constellation. An SVG
* underlay synced to the Sigma camera: we project the graph origin and a
* point one radius out into viewport pixels every frame, so the rings track
- * zoom/pan smoothly with transform-only updates (no re-layout). Captioned
- * only in the legend ("inner = entry surface"), never on-canvas.
+ * zoom/pan smoothly with transform-only updates (no re-layout). What they mean
+ * is stated in the host's scope description, not on the canvas, so a host that
+ * renders its own copy must say it there.
*/
export function DepthRings({ sigma, ringRadii }: DepthRingsProps) {
const svgRef = useRef<SVGSVGElement>(null);
@@ -27,7 +28,7 @@ export function DepthRings({ sigma, ringRadii }: DepthRingsProps) {
const svg = svgRef.current;
if (!svg) return;
- const stroke = resolveToken("--color-canvas-dot", "rgba(128,128,128,0.08)");
+ const stroke = resolveToken("--color-canvas-grid", "rgba(128,128,128,0.1)");
const draw = () => {
const center = sigma.graphToViewport({ x: 0, y: 0 });
diff --git a/packages/ui/src/graph/sigma/sigma-canvas.tsx b/packages/ui/src/graph/sigma/sigma-canvas.tsx
index d96143a5b..0291ec321 100644
--- a/packages/ui/src/graph/sigma/sigma-canvas.tsx
+++ b/packages/ui/src/graph/sigma/sigma-canvas.tsx
@@ -22,6 +22,7 @@ import { useFA2Layout } from "./use-fa2-layout";
import { useElkSigmaLayout } from "./use-elk-sigma-layout";
import { SigmaControls } from "./sigma-controls";
import { DepthRings } from "./depth-rings";
+import { CanvasGround } from "./canvas-ground";
export interface SigmaCanvasProps {
graph: Graph<SigmaNodeAttributes, SigmaEdgeAttributes> | null;
@@ -90,7 +91,7 @@ export const SigmaCanvas = forwardRef<SigmaCanvasHandle, SigmaCanvasProps>(
visibleEdgeTypes: props.visibleEdgeTypes,
});
- const { isRunning: isLayoutRunning, toggle: toggleLayout } = useFA2Layout({
+ const { isRunning: isLayoutRunning } = useFA2Layout({
graph: props.graph,
sigma,
enabled: props.layoutMode === "force",
@@ -186,6 +187,18 @@ export const SigmaCanvas = forwardRef<SigmaCanvasHandle, SigmaCanvasProps>(
};
}, [sigma, container]);
+ // Sigma 3 re-measures only inside its own render, and only listens on
+ // window resize. The canvas cell now changes size without the window
+ // doing so: the rail toggles the grid, the key row collapses, a banner
+ // appears. On a settled graph nothing would trigger a render, leaving
+ // stale dimensions behind the ground and the rings too.
+ useEffect(() => {
+ if (!sigma || !container || typeof ResizeObserver === "undefined") return;
+ const observer = new ResizeObserver(() => sigma.refresh());
+ observer.observe(container);
+ return () => observer.disconnect();
+ }, [sigma, container]);
+
useImperativeHandle(ref, () => ({
focusNode,
fitView,
@@ -198,31 +211,22 @@ export const SigmaCanvas = forwardRef<SigmaCanvasHandle, SigmaCanvasProps>(
<div
className="relative w-full h-full"
style={
- // For the constellation, paint the dark canvas on the wrapper and keep
- // the sigma container transparent so the depth-ring underlay shows.
- hasDepthRings && props.graphTheme === "dark"
- ? { background: "var(--color-bg-root)" }
- : undefined
+ // The plane is painted here, under the ground, so the underlays show
+ // through a transparent Sigma container. Rule 8: the canvas is the
+ // subject, so it takes the page plane rather than a well below it.
+ props.graphTheme === "dark" ? { background: "var(--color-bg-root)" } : undefined
}
>
+ {/* Every scope gets a ground. The rings were constellation-only, which
+ left the file graph drawing nodes on a flat plane. */}
+ <CanvasGround sigma={sigma} />
{hasDepthRings && props.depthRingRadii && (
<DepthRings sigma={sigma} ringRadii={props.depthRingRadii} />
)}
<div
ref={containerCallback}
className="w-full h-full relative z-[1]"
- style={{
- // `--color-bg-canvas` aliases `--color-bg-inset`, which the July
- // ramp move took to #0a0a0b — darker than the page. The canvas is
- // the subject, so it takes the page plane (rule 8), matching the
- // knowledge-graph canvas. Light mode is unchanged: it was already
- // transparent, which is why only dark looked wrong.
- background:
- !hasDepthRings && props.graphTheme === "dark"
- ? "var(--color-bg-root)"
- : "transparent",
- cursor: "grab",
- }}
+ style={{ background: "transparent", cursor: "grab" }}
/>
<SigmaControls
onZoomIn={zoomIn}
@@ -234,7 +238,6 @@ export const SigmaCanvas = forwardRef<SigmaCanvasHandle, SigmaCanvasProps>(
: undefined
}
isLayoutRunning={props.layoutMode === "force" ? isLayoutRunning : isElkComputing}
- onToggleLayout={props.layoutMode === "force" ? toggleLayout : undefined}
/>
</div>
);
diff --git a/packages/ui/src/graph/sigma/sigma-controls.tsx b/packages/ui/src/graph/sigma/sigma-controls.tsx
index 98e65dc4d..281e3afe1 100644
--- a/packages/ui/src/graph/sigma/sigma-controls.tsx
+++ b/packages/ui/src/graph/sigma/sigma-controls.tsx
@@ -1,6 +1,6 @@
"use client";
-import { ZoomIn, ZoomOut, Maximize, Focus, Play, Pause } from "lucide-react";
+import { ZoomIn, ZoomOut, Maximize, Focus } from "lucide-react";
import { ActivityDot } from "../../ui/activity-dot";
interface SigmaControlsProps {
@@ -8,8 +8,11 @@ interface SigmaControlsProps {
onZoomOut: () => void;
onFitView: () => void;
onFocusSelected?: (() => void) | undefined;
+ /** Drives the "Arranging…" activity chip only. There is no start/stop
+ * control: re-running FA2 measurably *worsens* this layout (cluster
+ * separation 23.2 seeded, 7.7 after 1200 iterations), and the golden-angle
+ * community seed is the layout. */
isLayoutRunning: boolean;
- onToggleLayout?: (() => void) | undefined;
}
export function SigmaControls({
@@ -18,20 +21,10 @@ export function SigmaControls({
onFitView,
onFocusSelected,
isLayoutRunning,
- onToggleLayout,
}: SigmaControlsProps) {
- // One panel with hairline dividers, matching the toolbar and the legend, so
- // all three corners of the canvas read as the same system. Each button used
- // to be its own bordered, `shadow-lg` pill; five of them stacked down the
- // right edge was five frames and five shadows for one control.
- //
- // Dark mode also painted a hardcoded `#1a1a2e` navy that belongs to no
- // palette in this app — the same class of drift as `--color-bg-glass`, and
- // it survived for the same reason: it only ever renders on top of a diagram,
- // where a plane one step off reads as deliberate.
- // Mobile-first sizing, matching graph-toolbar's buttons: 36px is a usable
- // touch target on a phone, and the compact 28px returns from `sm` up where a
- // pointer is doing the aiming.
+ // Direct manipulation of the camera, so this is one of the few things that
+ // stays on the drawing plane. Mobile-first sizing: 36px is a usable touch
+ // target, compact 28px from `sm` up where a pointer is aiming.
const btnClass =
"flex h-9 w-9 sm:h-7 sm:w-7 items-center justify-center rounded-md text-[var(--color-text-tertiary)] transition-colors hover:bg-[var(--color-bg-wash-hover)] hover:text-[var(--color-text-primary)]";
@@ -82,24 +75,6 @@ export function SigmaControls({
<Focus className="h-3.5 w-3.5" />
</button>
)}
- {onToggleLayout && (
- <button
- type="button"
- onClick={onToggleLayout}
- className={`${btnClass} mt-1 border-t border-[var(--color-border-default)] pt-1 ${
- isLayoutRunning ? "text-[var(--color-accent-primary)]" : ""
- }`}
- title={isLayoutRunning ? "Stop arranging" : "Re-arrange nodes"}
- aria-label={isLayoutRunning ? "Stop arranging" : "Re-arrange nodes"}
- aria-pressed={isLayoutRunning}
- >
- {isLayoutRunning ? (
- <Pause className="h-3.5 w-3.5" />
- ) : (
- <Play className="h-3.5 w-3.5" />
- )}
- </button>
- )}
</div>
</div>
);
diff --git a/packages/ui/src/shared/view-tabs.tsx b/packages/ui/src/shared/view-tabs.tsx
index 1544375d5..fabcde5d0 100644
--- a/packages/ui/src/shared/view-tabs.tsx
+++ b/packages/ui/src/shared/view-tabs.tsx
@@ -22,6 +22,12 @@ export interface ViewTabsProps {
onValueChange: (id: string) => void;
/** The active panel, rendered below the tab row. */
children?: React.ReactNode;
+ /** Id of a panel the host renders itself, for layouts where the panel cannot
+ * be a child (a full-height canvas that must be a flex sibling). The host
+ * puts `role="tabpanel"`, this id and `tabIndex={0}` on that container, and
+ * labels it `aria-labelledby={`${panelId}-tab-${activeTabId}`}` — tab ids are
+ * derived from this value so the host can name them without a callback. */
+ panelId?: string;
className?: string;
}
@@ -35,13 +41,20 @@ export function ViewTabs({
value,
onValueChange,
children,
+ panelId: externalPanelId,
className,
}: ViewTabsProps) {
// Stable id base so each tab can be aria-labelled to the shared panel and
// the panel can point back at the active tab.
const baseId = React.useId();
- const tabId = (id: string) => `${baseId}-tab-${id}`;
- const panelId = `${baseId}-panel`;
+ // Derived from the host's panelId when it owns the panel, so the two sides
+ // agree on ids without threading a callback.
+ const tabId = (id: string) => `${externalPanelId ?? baseId}-tab-${id}`;
+ // Only claim a panel we can actually point at: an internal one when children
+ // were given, otherwise the host's. With neither, `aria-controls` is dropped
+ // rather than left dangling on an element that does not exist.
+ const ownsPanel = children != null;
+ const panelId = ownsPanel ? `${baseId}-panel` : externalPanelId;
const tabRefs = React.useRef<Record<string, HTMLButtonElement | null>>({});
// Keep the active tab in view even though the scrollbar is hidden — it can
@@ -87,7 +100,7 @@ export function ViewTabs({
type="button"
role="tab"
aria-selected={active}
- aria-controls={panelId}
+ {...(panelId ? { "aria-controls": panelId } : {})}
tabIndex={active ? 0 : -1}
onClick={() => onValueChange(tab.id)}
className={cn(
@@ -115,9 +128,11 @@ export function ViewTabs({
);
})}
</div>
- <div id={panelId} role="tabpanel" aria-labelledby={tabId(value)} tabIndex={0}>
- {children}
- </div>
+ {ownsPanel && (
+ <div id={panelId} role="tabpanel" aria-labelledby={tabId(value)} tabIndex={0}>
+ {children}
+ </div>
+ )}
</div>
);
}
diff --git a/packages/ui/styles/globals.css b/packages/ui/styles/globals.css
index 69b943821..39d6eeacd 100644
--- a/packages/ui/styles/globals.css
+++ b/packages/ui/styles/globals.css
@@ -275,6 +275,9 @@
BOTH themes; aliasing them to theme-aware surfaces fixes light mode. */
--color-bg-canvas: var(--color-bg-inset);
--color-canvas-dot: rgba(36, 27, 44, 0.08);
+ /* Graph-paper ground under a node-link canvas. Stronger than canvas-dot,
+ which is a scatter mark: a 1px ring at that alpha is below threshold. */
+ --color-canvas-grid: rgba(36, 27, 44, 0.10);
--color-bg-glass: rgba(255, 255, 255, 0.72);
/* Neutral hover washes for canvas-adjacent chrome (rows, chips, stubs) —
plum-alpha on paper, lavender-alpha on dark (same idiom as canvas-dot). */
@@ -549,6 +552,7 @@
/* C4 / graph canvas surfaces — dark variants (the var()-derived aliases
flip on their own; only the explicit rgbas need a dark override). */
--color-canvas-dot: rgba(255, 255, 255, 0.05);
+ --color-canvas-grid: rgba(255, 255, 255, 0.10);
/* Tracks --color-bg-surface. It was rgba(35,35,37,.72) — the #232325 that
bg-surface used to be, left behind when the dark ramp moved in July 2026 —
so every glass chip on every canvas was painting a graphite that exists
diff --git a/packages/web/src/app/repos/[id]/architecture/page.tsx b/packages/web/src/app/repos/[id]/architecture/page.tsx
index 335ee1330..73bcb4f91 100644
--- a/packages/web/src/app/repos/[id]/architecture/page.tsx
+++ b/packages/web/src/app/repos/[id]/architecture/page.tsx
@@ -93,6 +93,8 @@ const TAB_FOR_VIEW: Record<CanonicalView, string> = {
symbols: "symbols",
};
+const TAB_PANEL_ID = "architecture-tab-panel";
+
const TABS: { id: string; label: string }[] = [
{ id: "map", label: "Map" },
{ id: "coupling", label: "Coupling" },
@@ -124,6 +126,7 @@ export default function ArchitecturePage({
const [, setSignal] = useQueryState("signal");
const [, setModule] = useQueryState("module");
const [, setFocus] = useQueryState("focus");
+ const [, setNode] = useQueryState("node");
// The curated layers view now lives at /knowledge-graph. `?view=layers`
// redirects there so shared links keep working.
@@ -155,13 +158,17 @@ export default function ArchitecturePage({
const handleTabChange = useCallback(
(id: string) => {
void setView(DEFAULT_VIEW_FOR_TAB[id] ?? "communities");
- if (id !== "coupling") void setFocus(null);
+ // `?focus=` means a file path in Coupling and the literal "relationships"
+ // in Third-party, so carrying it across pins one tab's value in the
+ // other's vocabulary. Cleared on every change, not just when leaving.
+ void setFocus(null);
if (id !== "map") {
void setSignal(null);
void setModule(null);
+ void setNode(null);
}
},
- [setView, setFocus, setSignal, setModule],
+ [setView, setFocus, setSignal, setModule, setNode],
);
const handleScopeChange = useCallback(
@@ -178,10 +185,23 @@ export default function ArchitecturePage({
return (
<div className="flex h-full flex-col">
<div className="shrink-0 px-4 pt-3 sm:px-6">
- <ViewTabs tabs={TABS} value={activeTab} onValueChange={handleTabChange} />
+ <ViewTabs
+ tabs={TABS}
+ value={activeTab}
+ onValueChange={handleTabChange}
+ panelId={TAB_PANEL_ID}
+ />
</div>
- <div className="min-h-0 flex-1 overflow-auto">
+ {/* The panel is a flex sibling, not a ViewTabs child: the Map is a
+ full-height canvas that sizes itself from this box. */}
+ <div
+ id={TAB_PANEL_ID}
+ role="tabpanel"
+ aria-labelledby={`${TAB_PANEL_ID}-tab-${activeTab}`}
+ tabIndex={0}
+ className="min-h-0 flex-1 overflow-auto"
+ >
{activeTab === "map" && (
<GraphView
repoId={repoId}
diff --git a/packages/web/src/app/repos/[id]/refactoring/page.tsx b/packages/web/src/app/repos/[id]/refactoring/page.tsx
index ea93028df..1f2f3d702 100644
--- a/packages/web/src/app/repos/[id]/refactoring/page.tsx
+++ b/packages/web/src/app/repos/[id]/refactoring/page.tsx
@@ -19,6 +19,8 @@ import { parseAsString, parseAsStringLiteral, useQueryState } from "nuqs";
import { Wrench, RotateCw } from "lucide-react";
import { PageShell } from "@repowise-dev/ui/shared/page-shell";
import { ViewTabs } from "@repowise-dev/ui/shared/view-tabs";
+
+const REFACTORING_PANEL_ID = "refactoring-tab-panel";
import { fileEntityPath } from "@repowise-dev/ui/shared/entity";
import { Skeleton, SkeletonRegion } from "@repowise-dev/ui/ui/skeleton";
import {
@@ -250,12 +252,19 @@ export default function RefactoringPage({ params }: { params: Promise<{ id: stri
<ViewTabs
tabs={tabs}
value={type}
+ panelId={REFACTORING_PANEL_ID}
onValueChange={(id) => {
setOffset(0);
void setType(id as TypeFilter);
}}
/>
+ <div
+ id={REFACTORING_PANEL_ID}
+ role="tabpanel"
+ aria-labelledby={`${REFACTORING_PANEL_ID}-tab-${type}`}
+ tabIndex={0}
+ >
{error ? (
<div className="rounded-2xl border border-[var(--color-error)]/30 bg-[var(--color-error)]/5 p-6 text-sm text-[var(--color-text-secondary)]">
Couldn&apos;t load refactoring opportunities. The repo may not be indexed yet, or the
@@ -308,6 +317,7 @@ export default function RefactoringPage({ params }: { params: Promise<{ id: stri
}
/>
)}
+ </div>
</div>
<OpportunityDrawer
diff --git a/packages/web/src/components/architecture/graph-view.tsx b/packages/web/src/components/architecture/graph-view.tsx
index 871726491..a31846dff 100644
--- a/packages/web/src/components/architecture/graph-view.tsx
+++ b/packages/web/src/components/architecture/graph-view.tsx
@@ -6,7 +6,6 @@ import { useQueryState } from "nuqs";
import { useSearchParams } from "next/navigation";
import { GraphFlow } from "@/components/graph/graph-flow";
import { GraphDocPanel } from "@/components/graph/graph-doc-panel";
-import { GraphCanvasShell } from "@repowise-dev/ui/graph/graph-canvas-shell";
import { GraphTruncationBanner } from "@repowise-dev/ui/graph/graph-truncation-banner";
import {
GraphScopeSwitcher,
@@ -97,8 +96,14 @@ export function GraphView({
[setSelectedNode],
);
- // When the community panel opens from the legend, dismiss the doc panel
- // so the two never stack on the right rail. Single-sidebar UX.
+ // The rail holds one panel, and the doc panel outranks the inspector, so a
+ // doc left open would mask every later selection. Drop it once the selection
+ // moves elsewhere.
+ const handleSelectedNodeChange = useCallback((nodeId: string | null) => {
+ setDocNodeId((prev) => (prev !== null && prev !== nodeId ? null : prev));
+ }, []);
+
+ // Opening a community also replaces the doc panel.
const handleCommunityPanelOpen = useCallback(() => {
setDocNodeId(null);
}, []);
@@ -155,22 +160,18 @@ export function GraphView({
);
return (
- <GraphCanvasShell
- // No title. The tab above already says "Map", and the scope switcher on
- // the right says which zoom you are at — a heading that repeats the
- // control you just clicked spends a band of chrome saying nothing. What
- // is left is the one line that adds something neither can: what to do
- // with the thing you are looking at.
+ <GraphFlow
+ repoId={repoId}
+ // No title. The tab above says "Map" and the scope switcher says which
+ // zoom you are at; the one line left is what to do with what you see.
description={
isCommunities
- ? "Each circle is a detected community, sized by how much code it holds. Double-click one to open it up."
+ ? "Files that depend on each other more than on the rest of the repo, detected automatically. Circle size is how much code a group holds, and the nearer the centre, the nearer an entry point. Double-click a group to see the files inside it and what they depend on."
: "Every file and how it depends on the others. Pick two files to trace a path between them."
}
- titleActions={headerControls}
+ headerActions={headerControls}
banner={
- // Shown only when the file scope actually got capped. This line is the
- // one place the node count is stated, and it only became true when the
- // export stopped counting symbol nodes as files.
+ // Only when the file scope actually got capped.
usesFullGraph && graphData?.truncated && graphData.total_node_count != null ? (
<GraphTruncationBanner
shown={graphData.nodes.length}
@@ -181,7 +182,7 @@ export function GraphView({
/>
) : undefined
}
- overlay={
+ rail={
docNodeId ? (
<GraphDocPanel
repoId={repoId}
@@ -190,25 +191,22 @@ export function GraphView({
/>
) : undefined
}
- >
- <GraphFlow
- repoId={repoId}
- // Scope is controlled: `?view=` is the single source of truth, so
- // back/forward and shared links restore it without a remount.
- viewMode={viewMode}
- activeModule={activeModule}
- // Same value the banner reports, so the caption and the canvas can
- // never disagree about how many files are drawn.
- graphLimit={graphLimit}
- onModuleGroupsChange={setModuleGroups}
- colorMode={initialColorMode ?? "community"}
- initialSelectedNode={initialNode}
- onNodeClick={handleNodeClick}
- onNodeViewDocs={handleNodeViewDocs}
- onCommunityPanelOpen={handleCommunityPanelOpen}
- onViewModeChange={handleViewModeChange}
- onColorModeChange={handleColorModeChange}
- />
- </GraphCanvasShell>
+ // Scope is controlled: `?view=` is the single source of truth, so
+ // back/forward and shared links restore it without a remount.
+ viewMode={viewMode}
+ activeModule={activeModule}
+ // Same value the banner reports, so the caption and the canvas can
+ // never disagree about how many files are drawn.
+ graphLimit={graphLimit}
+ onModuleGroupsChange={setModuleGroups}
+ colorMode={initialColorMode ?? "community"}
+ initialSelectedNode={initialNode}
+ onNodeClick={handleNodeClick}
+ onNodeViewDocs={handleNodeViewDocs}
+ onCommunityPanelOpen={handleCommunityPanelOpen}
+ onSelectedNodeChange={handleSelectedNodeChange}
+ onViewModeChange={handleViewModeChange}
+ onColorModeChange={handleColorModeChange}
+ />
);
}
diff --git a/packages/web/src/components/graph/graph-flow.tsx b/packages/web/src/components/graph/graph-flow.tsx
index 16b52c449..2e701d1af 100644
--- a/packages/web/src/components/graph/graph-flow.tsx
+++ b/packages/web/src/components/graph/graph-flow.tsx
@@ -1,6 +1,6 @@
"use client";
-import { useState } from "react";
+import { useCallback, useState } from "react";
import { useRouter } from "next/navigation";
import { fileEntityPath } from "@repowise-dev/ui/shared/entity";
import {
@@ -9,7 +9,6 @@ import {
} from "@repowise-dev/ui/graph/graph-flow";
import {
useGraph,
- useArchitectureGraph,
useArchitectureCommunityGraph,
useDeadCodeGraph,
useHotFilesGraph,
@@ -56,12 +55,18 @@ export interface GraphFlowProps {
* Page uses this to dismiss the doc panel so the right rail stays
* to a single surface. */
onCommunityPanelOpen?: (communityId: number) => void;
+ onSelectedNodeChange?: GraphFlowShellProps["onSelectedNodeChange"];
/** Fired whenever the live scope (viewMode) changes. The page uses this to
* track the current scope so it can conditionally fetch the capped full
* graph (and gate the truncation banner) only for scopes that render it. */
onViewModeChange?: (mode: ViewMode) => void;
/** Fired when the node color mode changes so the page can sync the URL. */
onColorModeChange?: GraphFlowShellProps["onColorModeChange"];
+ /** Header/rail slots, forwarded to the shared shell. */
+ description?: GraphFlowShellProps["description"];
+ headerActions?: GraphFlowShellProps["headerActions"];
+ banner?: GraphFlowShellProps["banner"];
+ rail?: GraphFlowShellProps["rail"];
}
export function GraphFlow({
@@ -78,8 +83,13 @@ export function GraphFlow({
onNodeClick,
onNodeViewDocs,
onCommunityPanelOpen,
+ onSelectedNodeChange,
onViewModeChange,
onColorModeChange,
+ description,
+ headerActions,
+ banner,
+ rail,
}: GraphFlowProps) {
const router = useRouter();
// Constellation (Knowledge Graph) is the default scope.
@@ -90,13 +100,18 @@ export function GraphFlow({
// Currently-expanded constellation hubs (community ids). Drives the slice
// fetch; the shell owns the actual expand/collapse interaction state.
const [expandedHubs, setExpandedHubs] = useState<number[]>([]);
+ // Latched on first open of the flows panel. It starts closed, so this keeps a
+ // trace fetch nobody asked for off every file-scope render.
+ const [flowsRequested, setFlowsRequested] = useState(false);
+ const handleFlowsVisibilityChange = useCallback((visible: boolean) => {
+ if (visible) setFlowsRequested(true);
+ }, []);
const needsFullGraph = viewMode === "full" || viewMode === "unified";
const { graph: fullGraph, isLoading: fullLoading } = useGraph(
needsFullGraph ? repoId : null,
graphLimit,
);
- const { graph: archGraph, isLoading: archLoading } = useArchitectureGraph(null);
// Constellation community super-graph — only fetched for the radial scope.
const { graph: constellationGraph, isLoading: constellationLoading } =
useArchitectureCommunityGraph(viewMode === "architecture" ? repoId : null);
@@ -115,10 +130,10 @@ export function GraphFlow({
const { repo } = useRepo(repoId);
const resolvedRepoName = repoName ?? repo?.name;
const { communities } = useCommunities(repoId);
- // Flow traces highlight file-level nodes; the constellation has none, so it
- // skips the fetch. Dead/hot render file graphs, so flows work there too.
+ // File-level only (the constellation has no file nodes), and only once the
+ // panel that reads them has been opened.
const { flows: executionFlowsData } = useExecutionFlows(
- viewMode !== "architecture" ? repoId : null,
+ flowsRequested && viewMode !== "architecture" ? repoId : null,
{
top_n: 10,
max_depth: 6,
@@ -127,10 +142,12 @@ export function GraphFlow({
return (
<GraphFlowShell
+ description={description}
+ headerActions={headerActions}
+ banner={banner}
+ rail={rail}
fullGraph={fullGraph as GraphExport | undefined}
isLoadingFullGraph={fullLoading}
- architectureGraph={archGraph as GraphExport | undefined}
- isLoadingArchitectureGraph={archLoading}
constellationGraph={constellationGraph as ArchitectureGraph | undefined}
isLoadingConstellationGraph={constellationLoading}
constellationSlices={constellationSlices as Map<number, CommunitySlice> | undefined}
@@ -142,6 +159,7 @@ export function GraphFlow({
isLoadingHotFilesGraph={hotLoading}
communities={communities as CommunitySummaryItem[] | undefined}
executionFlows={executionFlowsData as ExecutionFlows | undefined}
+ onFlowsVisibilityChange={handleFlowsVisibilityChange}
initialViewMode={initialViewMode}
viewMode={controlledViewMode}
activeModule={activeModule}
@@ -163,6 +181,7 @@ export function GraphFlow({
}
fileHrefFor={(nodeId) => fileEntityPath(`/repos/${repoId}`, nodeId)}
onCommunityPanelOpen={onCommunityPanelOpen}
+ onSelectedNodeChange={onSelectedNodeChange}
renderPathFinder={(props) => (
<PathFinderPanel
repoId={repoId}