Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

refactor(explorer): split focused view from layout modes (#1599)

csy2063cd6989cfdc
diff --git a/explorer/package.json b/explorer/package.json
index 48c94e73..2a133602 100644
--- a/explorer/package.json
+++ b/explorer/package.json
@@ -9,7 +9,7 @@
"lint": "eslint .",
"preview": "vite preview",
"test:graph-store": "node --test tests/graphStore.multi-edge.test.mjs",
- "test:graph-workspace": "node --import tsx --test tests/markdownContentViewer.test.ts tests/markdownEditorInteraction.test.tsx tests/markdownEditorState.test.ts tests/nodeMarkdownSync.test.ts tests/graphSceneState.display.test.ts tests/temporalLifecycle.test.ts tests/temporalScrubberBounds.test.ts tests/deterministicExplorerRendering.test.ts tests/explorerCapabilities.test.tsx tests/smallGraphLayout.test.ts tests/realtimeGraphAttributes.test.ts tests/ontologyEditorModel.test.ts tests/graphColorLegend.test.ts tests/ontologyUrlState.test.ts",
+ "test:graph-workspace": "node --import tsx --test tests/markdownContentViewer.test.ts tests/markdownEditorInteraction.test.tsx tests/markdownEditorState.test.ts tests/nodeMarkdownSync.test.ts tests/graphSceneState.display.test.ts tests/graphViewCopy.test.ts tests/localGraphTransition.test.ts tests/temporalLifecycle.test.ts tests/temporalScrubberBounds.test.ts tests/deterministicExplorerRendering.test.ts tests/explorerCapabilities.test.tsx tests/smallGraphLayout.test.ts tests/realtimeGraphAttributes.test.ts tests/ontologyEditorModel.test.ts tests/graphColorLegend.test.ts tests/ontologyUrlState.test.ts",
"test:deterministic-e2e": "node --import tsx --test tests/deterministicExplorerRendering.e2e.ts",
"test:graph-legend-e2e": "node --import tsx --test tests/graphColorLegend.e2e.ts",
"test:plugin-registry": "node --import tsx --test tests/pluginRegistry.temporal.test.mjs"
diff --git a/explorer/src/workspaces/GraphWorkspace/GraphInspectorPanel.tsx b/explorer/src/workspaces/GraphWorkspace/GraphInspectorPanel.tsx
index 0a8113a2..23ebfce5 100644
--- a/explorer/src/workspaces/GraphWorkspace/GraphInspectorPanel.tsx
+++ b/explorer/src/workspaces/GraphWorkspace/GraphInspectorPanel.tsx
@@ -2,7 +2,8 @@ import type { CSSProperties } from "react";
import { Loader2 } from "lucide-react";
import { graph } from "../../store/graphStore";
import { GRAPH_THEME, withAlpha } from "./graphTheme";
-import type { GraphSelectedNodeKind } from "./types";
+import type { FocusedUnavailableReason, GraphSelectedNodeKind } from "./types";
+import { focusedUnavailableReasonText } from "./graphViewCopy";
import { MarkdownContentViewer } from "./MarkdownContentViewer";
import type { MarkdownApplyResult } from "./markdownResourceClient";
@@ -33,7 +34,7 @@ export interface GraphInspectorPanelProps {
inspectableNodeId?: string | null;
selectedNodeKind?: GraphSelectedNodeKind;
canActivateFocused?: boolean;
- focusedUnavailableReason?: string | null;
+ focusedUnavailableReason?: FocusedUnavailableReason | null;
predictions: LinkPrediction[];
predictionType: string;
onPredictionTypeChange: (value: string) => void;
@@ -347,7 +348,7 @@ export function GraphInspectorPanel({
<div style={{ color: GRAPH_THEME.ui.text.body, fontSize: 13, lineHeight: 1.6 }}>
{canActivateFocused
? "Use Focus to resolve this grouped selection to its canonical node."
- : (focusedUnavailableReason ?? "Focused mode is unavailable for the current selection.")}
+ : focusedUnavailableReasonText(focusedUnavailableReason)}
</div>
</div>
</aside>
@@ -398,7 +399,7 @@ export function GraphInspectorPanel({
<div style={{ color: GRAPH_THEME.ui.text.body, fontSize: 13, lineHeight: 1.6 }}>
{canActivateFocused
? `Canonical node available: ${effectiveNodeId}`
- : (focusedUnavailableReason ?? "Focused mode is unavailable for the current selection.")}
+ : focusedUnavailableReasonText(focusedUnavailableReason)}
</div>
</div>
) : null}
diff --git a/explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx b/explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx
index b8a0517a..ea5fc713 100644
--- a/explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx
+++ b/explorer/src/workspaces/GraphWorkspace/GraphWorkspace.tsx
@@ -29,6 +29,8 @@ import { GraphLoadingOverlay } from "./GraphLoadingOverlay";
import { createGraphLoadProgress, getGraphLoadTitle } from "./graphLoading";
import { GRAPH_THEME, withAlpha } from "./graphTheme";
import { buildGraphColorLegend, type GraphColorLegendItem } from "./graphColorLegend";
+import { focusedUnavailableReasonText, groupedViewReasonText } from "./graphViewCopy";
+import { localGraphRequiresDraftConfirm } from "./localGraphTransition";
import { buildHeatmapRenderSnapshot, buildStructuralDistanceSnapshot, checkGroupedViewAvailability, getDistanceBandColor, resolveDisplayGraph, resolveDisplayStateSnapshot, resolveGroupedDisplayNodeId, resolveGroupedDisplayStateSnapshot, summarizeDistanceBuckets } from "./graphSceneState";
import {
type GraphPlugin,
@@ -52,6 +54,7 @@ import {
} from "./nodeMarkdownSync";
import type { GraphSceneHandle, GraphSceneRuntime } from "./scene";
import type {
+ FocusedUnavailableReason,
GraphAnalyticsSnapshot,
GraphDistanceVisualMode,
GraphDistanceVisualState,
@@ -60,6 +63,7 @@ import type {
GraphEffectToggle,
GraphEffectsState,
GraphInteractionState,
+ GraphLayoutViewMode,
GraphLoadProgress,
GraphLoadSummary,
GraphRuntimeDiagnosticsSnapshot,
@@ -221,10 +225,12 @@ function ToolbarButton({
item,
compact = false,
className = "",
+ toggle = false,
}: {
item: GraphToolbarItem;
compact?: boolean;
className?: string;
+ toggle?: boolean;
}) {
const isCompact = compact || item.compact;
return (
@@ -233,6 +239,7 @@ function ToolbarButton({
className={`explore-tool-button ${item.tone === "primary" ? "explore-tool-button-primary" : ""} ${className}`}
data-active={item.active ? "true" : "false"}
data-compact={isCompact ? "true" : "false"}
+ aria-pressed={toggle ? item.active === true : undefined}
onClick={item.onClick}
title={item.title}
aria-label={item.ariaLabel ?? item.label}
@@ -280,7 +287,7 @@ function SegmentedModeControl({ items }: { items: GraphToolbarItem[] }) {
return (
<div className="explore-mode-control" role="group" aria-label="Graph view mode">
{items.map((item) => (
- <ToolbarButton key={item.id} item={item} className="explore-mode-segment" />
+ <ToolbarButton key={item.id} item={item} className="explore-mode-segment" toggle />
))}
</div>
);
@@ -1097,7 +1104,7 @@ function buildSelectedNodeState(
type FocusResolution = {
kind: GraphSelectedNodeKind;
resolvedNodeId: string | null;
- reason: string | null;
+ reason: FocusedUnavailableReason | null;
};
function buildSelectedEdgeState(
@@ -1567,7 +1574,7 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken, onDirt
return {
kind: "none",
resolvedNodeId: null,
- reason: "Select a node to inspect in Focused mode.",
+ reason: { code: "no-selection" },
};
}
@@ -1601,14 +1608,14 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken, onDirt
return {
kind: "grouped",
resolvedNodeId: null,
- reason: "Focused mode is unavailable for this grouped selection.",
+ reason: { code: "grouped-unresolvable" },
};
}
return {
kind: "unavailable",
resolvedNodeId: null,
- reason: "Selected item is not available in the current graph.",
+ reason: { code: "not-in-graph" },
};
}, []);
@@ -1640,21 +1647,33 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken, onDirt
}, [markdownDraftDirty]);
- const requestViewMode = useCallback((nextViewMode: GraphViewMode) => {
- if (nextViewMode !== viewMode && !confirmDiscardMarkdownDraft()) return;
- if (nextViewMode === "focused") {
- const resolution = resolveNodeIdForFocusedMode(selectedNodeId, pluginRuntimeRef.current?.displayGraph);
- if (!resolution.resolvedNodeId) {
- return;
- }
+ const enterLocalGraph = useCallback((nodeId: string) => {
+ const resolution = resolveNodeIdForFocusedMode(nodeId, pluginRuntimeRef.current?.displayGraph);
+ if (!resolution.resolvedNodeId) {
+ return;
+ }
- setFocusedNodeId(resolution.resolvedNodeId);
- setSelectedNodeId(resolution.resolvedNodeId);
- setViewMode("focused");
- setIsLayoutRunning(false);
+ const nextNodeId = resolution.resolvedNodeId;
+ const requiresDraftConfirm = localGraphRequiresDraftConfirm(viewMode, selectedNodeId, nextNodeId);
+ if (requiresDraftConfirm && !confirmDiscardMarkdownDraft()) {
return;
}
+ setFocusedNodeId(nextNodeId);
+ setSelectedNodeId(nextNodeId);
+ if (requiresDraftConfirm) {
+ setSelectedEdgeId("");
+ setPathResult(null);
+ setSearchResults([]);
+ setSearchError("");
+ }
+ setViewMode("focused");
+ setIsLayoutRunning(false);
+ }, [confirmDiscardMarkdownDraft, resolveNodeIdForFocusedMode, selectedNodeId, viewMode]);
+
+ const setLayoutViewMode = useCallback((nextViewMode: GraphLayoutViewMode) => {
+ if (nextViewMode !== viewMode && !confirmDiscardMarkdownDraft()) return;
+
if (nextViewMode === "grouped") {
if (!groupedViewAvailable) {
debugGraphWorkspace("grouped-view-unavailable", {
@@ -1703,7 +1722,6 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken, onDirt
groupedViewAvailable,
groupedViewReason,
lastGroupedSelectedNodeId,
- resolveNodeIdForFocusedMode,
selectedNodeId,
viewMode,
]);
@@ -2359,7 +2377,7 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken, onDirt
if (viewMode === "grouped") {
return displayState.groupedViewAvailable
? "Communities compressed into grouped structure view"
- : (displayState.groupedViewReason ?? "Grouped view is unavailable for the current graph");
+ : (groupedViewReasonText(displayState.groupedViewReason) ?? groupedViewReasonText({ code: "communities-undetected" }));
}
return null;
}
@@ -2493,7 +2511,10 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken, onDirt
focusNode(action.nodeId);
return;
case "setViewMode":
- requestViewMode(action.viewMode);
+ setLayoutViewMode(action.viewMode);
+ return;
+ case "enterLocalGraph":
+ enterLocalGraph(action.nodeId);
return;
case "collapseNeighborhood":
if (!selectedNodeId) {
@@ -2545,7 +2566,7 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken, onDirt
setActiveDockPanelId((previous) => (previous === action.panelId ? null : previous));
return;
}
- }, [focusNode, requestViewMode, selectedNodeId, setEffectToggle]);
+ }, [enterLocalGraph, focusNode, selectedNodeId, setEffectToggle, setLayoutViewMode]);
const diagnosticsSnapshot = useMemo<GraphDiagnosticsSnapshot | null>(() => {
if (!GRAPH_THEME.effects.diagnostics.enabledInDev || !graphDiagnosticsState) {
@@ -2776,38 +2797,47 @@ export function GraphWorkspace({ externalFocusNodeId, externalFocusToken, onDirt
title: "Return to the full graph context",
icon: Layers3,
active: viewMode === "full",
- onClick: () => requestViewMode("full"),
+ onClick: () => setLayoutViewMode("full"),
},
{
id: "view-grouped",
label: "Grouped View",
title: displayState.groupedViewAvailable
? "Compress dense structure into detected communities"
- : (displayState.groupedViewReason ?? "Grouped view is unavailable until communities can be detected"),
+ : (groupedViewReasonText(displayState.groupedViewReason)
+ ?? groupedViewReasonText({ code: "communities-undetected" })
+ ?? undefined),
icon: GitBranch,
active: viewMode === "grouped",
disabled: !displayState.groupedViewAvailable,
- onClick: () => requestViewMode("grouped"),
+ onClick: () => setLayoutViewMode("grouped"),
},
{
id: "view-focused",
label: "Focus",
title: canActivateFocusedMode
? "Inspect the selected node in a focused local graph"
- : (focusedSelectionResolution.reason ?? "Focused mode is unavailable for the current selection"),
+ : (focusedUnavailableReasonText(focusedSelectionResolution.reason) ?? undefined),
icon: Focus,
active: viewMode === "focused",
disabled: viewMode !== "focused" && !canActivateFocusedMode,
- onClick: () => requestViewMode("focused"),
+ onClick: () => {
+ const nodeId = focusedSelectionResolution.resolvedNodeId;
+ if (nodeId) {
+ enterLocalGraph(nodeId);
+ }
+ },
},
];
}, [
canActivateFocusedMode,
displayState.groupedViewAvailable,
displayState.groupedViewReason,
+ enterLocalGraph,
focusedSelectionResolution.reason,
+ focusedSelectionResolution.resolvedNodeId,
hasGraphContent,
- requestViewMode,
+ setLayoutViewMode,
viewMode,
]);
diff --git a/explorer/src/workspaces/GraphWorkspace/graphSceneState.ts b/explorer/src/workspaces/GraphWorkspace/graphSceneState.ts
index 485a11c5..e4d2bc1c 100644
--- a/explorer/src/workspaces/GraphWorkspace/graphSceneState.ts
+++ b/explorer/src/workspaces/GraphWorkspace/graphSceneState.ts
@@ -23,6 +23,7 @@ import { getSemanticNodeColor } from "./graphColorLegend";
import { classifyEntityShape } from "./graphEntityShape";
import { computeGraphAnalyticsBase } from "./graphAnalytics";
import type {
+ FocusedUnavailableReason,
GraphDistanceBucketCounts,
GraphDisplayMeta,
GraphDisplayStateSnapshot,
@@ -32,6 +33,7 @@ import type {
GraphInteractionState,
GraphSelectedNodeKind,
GraphViewMode,
+ GroupedViewUnavailableReason,
} from "./types";
const MAX_FOCUS_NEIGHBORS = GRAPH_THEME.focus.maxNeighbors;
@@ -576,7 +578,7 @@ function createEmptyDisplayState(
selectedNodeKind: selectedNodeId ? "unavailable" : "none",
canActivateFocused: false,
resolvedFocusedNodeId: null,
- focusedUnavailableReason: selectedNodeId ? "Selected item is not available in the current graph." : null,
+ focusedUnavailableReason: selectedNodeId ? { code: "not-in-graph" } : null,
};
}
@@ -622,7 +624,10 @@ export function resolveGroupedDisplayNodeId(
return resolvedNodeId;
}
-export function checkGroupedViewAvailability(): { available: boolean; reason: string | null } {
+export function checkGroupedViewAvailability(): {
+ available: boolean;
+ reason: GroupedViewUnavailableReason | null;
+} {
const base = computeGraphAnalyticsBase(graph, {
computeCommunities: true,
computeCentrality: false,
@@ -630,7 +635,7 @@ export function checkGroupedViewAvailability(): { available: boolean; reason: st
const available = base.communitiesByNode.size > 0;
return {
available,
- reason: available ? null : "Grouped view is unavailable until communities can be detected.",
+ reason: available ? null : { code: "communities-undetected" },
};
}
@@ -682,10 +687,10 @@ export function resolveGroupedDisplayStateSnapshot(
selectedNodeId: string,
options?: {
groupedViewAvailable?: boolean;
- groupedViewReason?: string | null;
+ groupedViewReason?: GroupedViewUnavailableReason | null;
selectedNodeKind?: GraphSelectedNodeKind;
resolvedFocusedNodeId?: string | null;
- focusedUnavailableReason?: string | null;
+ focusedUnavailableReason?: FocusedUnavailableReason | null;
},
): GraphDisplayStateSnapshot {
const displayState = createEmptyDisplayState(selectedNodeId, true);
@@ -714,12 +719,14 @@ export function resolveGroupedDisplayStateSnapshot(
return displayState;
}
-function validateGroupedDisplayGraph(grouped: Graph<NodeAttributes, EdgeAttributes>): string | null {
+function validateGroupedDisplayGraph(
+ grouped: Graph<NodeAttributes, EdgeAttributes>,
+): GroupedViewUnavailableReason | null {
if (grouped.order === 0) {
- return "Grouped view is unavailable because no community nodes could be created.";
+ return { code: "community-nodes-missing" };
}
- let invalidReason: string | null = null;
+ let invalidReason: GroupedViewUnavailableReason | null = null;
grouped.forEachNode((nodeId, attrs) => {
if (invalidReason) {
return;
@@ -727,7 +734,7 @@ function validateGroupedDisplayGraph(grouped: Graph<NodeAttributes, EdgeAttribut
const nodeAttrs = attrs as NodeAttributes;
if (!Number.isFinite(Number(nodeAttrs.x)) || !Number.isFinite(Number(nodeAttrs.y))) {
- invalidReason = `Grouped node ${nodeId} has invalid coordinates.`;
+ invalidReason = { code: "invalid-community-layout", nodeId };
}
});
@@ -741,7 +748,7 @@ function validateGroupedDisplayGraph(grouped: Graph<NodeAttributes, EdgeAttribut
}
if (!grouped.hasNode(sourceId) || !grouped.hasNode(targetId)) {
- invalidReason = `Grouped edge ${edgeId} references a missing grouped node.`;
+ invalidReason = { code: "missing-grouped-node", edgeId };
}
});
@@ -2207,7 +2214,7 @@ function buildCommunityGroupedGraph(): GraphDisplayResult {
const state = createEmptyDisplayState("", true);
state.groupedViewAvailable = base.communitiesByNode.size > 0;
if (base.communitiesByNode.size === 0) {
- state.groupedViewReason = "Grouped view is unavailable until communities can be detected.";
+ state.groupedViewReason = { code: "communities-undetected" };
return { graph: aggregateDisplayGraph(graph), state, meta: MIRRORED_DISPLAY_META };
}
@@ -2484,10 +2491,10 @@ export function resolveDisplayStateSnapshot(
aggregationEnabled?: boolean;
collapsedNeighborhoodNodeIds?: Iterable<string>;
groupedViewAvailable?: boolean;
- groupedViewReason?: string | null;
+ groupedViewReason?: GroupedViewUnavailableReason | null;
selectedNodeKind?: GraphSelectedNodeKind;
resolvedFocusedNodeId?: string | null;
- focusedUnavailableReason?: string | null;
+ focusedUnavailableReason?: FocusedUnavailableReason | null;
},
): GraphDisplayStateSnapshot {
const aggregationEnabled = options?.aggregationEnabled ?? true;
@@ -2506,7 +2513,7 @@ export function resolveDisplayStateSnapshot(
computeCentrality: false,
}).communitiesByNode.size > 0;
displayState.groupedViewReason = options?.groupedViewReason
- ?? (displayState.groupedViewAvailable ? null : "Grouped view is unavailable until communities can be detected.");
+ ?? (displayState.groupedViewAvailable ? null : { code: "communities-undetected" });
if (!selectedNodeId || !graph.hasNode(selectedNodeId)) {
return displayState;
diff --git a/explorer/src/workspaces/GraphWorkspace/graphViewCopy.ts b/explorer/src/workspaces/GraphWorkspace/graphViewCopy.ts
new file mode 100644
index 00000000..95199c56
--- /dev/null
+++ b/explorer/src/workspaces/GraphWorkspace/graphViewCopy.ts
@@ -0,0 +1,41 @@
+import type { FocusedUnavailableReason, GroupedViewUnavailableReason } from "./types";
+
+const GROUPED_VIEW_COPY = {
+ "communities-undetected": "Grouped view is unavailable until communities can be detected.",
+ "community-nodes-missing": "Grouped view is unavailable because no community nodes could be created.",
+} as const;
+
+const FOCUSED_MODE_COPY = {
+ "no-selection": "Select a node to inspect in Focused mode.",
+ "grouped-unresolvable": "Focused mode is unavailable for this grouped selection.",
+ "not-in-graph": "Selected item is not available in the current graph.",
+} as const;
+
+export function groupedViewReasonText(
+ reason: GroupedViewUnavailableReason | null | undefined,
+): string | null {
+ if (!reason) {
+ return null;
+ }
+
+ switch (reason.code) {
+ case "communities-undetected":
+ return GROUPED_VIEW_COPY["communities-undetected"];
+ case "community-nodes-missing":
+ return GROUPED_VIEW_COPY["community-nodes-missing"];
+ case "invalid-community-layout":
+ return `Grouped node ${reason.nodeId} has invalid coordinates.`;
+ case "missing-grouped-node":
+ return `Grouped edge ${reason.edgeId} references a missing grouped node.`;
+ }
+}
+
+export function focusedUnavailableReasonText(
+ reason: FocusedUnavailableReason | null | undefined,
+): string | null {
+ if (!reason) {
+ return null;
+ }
+
+ return FOCUSED_MODE_COPY[reason.code];
+}
diff --git a/explorer/src/workspaces/GraphWorkspace/localGraphTransition.ts b/explorer/src/workspaces/GraphWorkspace/localGraphTransition.ts
new file mode 100644
index 00000000..e00c2e83
--- /dev/null
+++ b/explorer/src/workspaces/GraphWorkspace/localGraphTransition.ts
@@ -0,0 +1,9 @@
+import type { GraphViewMode } from "./types";
+
+export function localGraphRequiresDraftConfirm(
+ viewMode: GraphViewMode,
+ selectedNodeId: string,
+ resolvedNodeId: string,
+): boolean {
+ return viewMode !== "focused" || resolvedNodeId !== selectedNodeId;
+}
diff --git a/explorer/src/workspaces/GraphWorkspace/plugins/types.ts b/explorer/src/workspaces/GraphWorkspace/plugins/types.ts
index 1292ee69..500fcfb2 100644
--- a/explorer/src/workspaces/GraphWorkspace/plugins/types.ts
+++ b/explorer/src/workspaces/GraphWorkspace/plugins/types.ts
@@ -14,7 +14,7 @@ import type {
GraphLoadSummary,
GraphSelectedNodeState,
GraphTemporalState,
- GraphViewMode,
+ GraphLayoutViewMode,
} from "../types";
export type { GraphTemporalState } from "../types";
@@ -31,7 +31,8 @@ export type GraphPluginActionRequest =
| { type: "fitView" }
| { type: "focusNode"; nodeId: string }
| { type: "selectNode"; nodeId: string }
- | { type: "setViewMode"; viewMode: GraphViewMode }
+ | { type: "setViewMode"; viewMode: GraphLayoutViewMode }
+ | { type: "enterLocalGraph"; nodeId: string }
| { type: "collapseNeighborhood" }
| { type: "expandNeighborhood" }
| { type: "toggleEffect"; effect: GraphEffectToggle }
diff --git a/explorer/src/workspaces/GraphWorkspace/types.ts b/explorer/src/workspaces/GraphWorkspace/types.ts
index 85087698..28371302 100644
--- a/explorer/src/workspaces/GraphWorkspace/types.ts
+++ b/explorer/src/workspaces/GraphWorkspace/types.ts
@@ -1,4 +1,17 @@
-export type GraphViewMode = "focused" | "full" | "grouped";
+export type GraphLayoutViewMode = "full" | "grouped";
+export type GraphViewMode = GraphLayoutViewMode | "focused";
+
+export type GroupedViewUnavailableReason =
+ | { code: "communities-undetected" }
+ | { code: "community-nodes-missing" }
+ | { code: "invalid-community-layout"; nodeId: string }
+ | { code: "missing-grouped-node"; edgeId: string };
+
+export type FocusedUnavailableReason =
+ | { code: "no-selection" }
+ | { code: "grouped-unresolvable" }
+ | { code: "not-in-graph" };
+
export type GraphLayoutSource = "provided" | "carried" | "runtime";
export type GraphLayoutState = "idle" | "bootstrapping" | "running" | "stabilized" | "interactive" | "failed";
export type GraphLoadPhase =
@@ -73,14 +86,14 @@ export interface GraphInteractionState {
export interface GraphDisplayStateSnapshot {
aggregationEnabled: boolean;
groupedViewAvailable: boolean;
- groupedViewReason: string | null;
+ groupedViewReason: GroupedViewUnavailableReason | null;
selectedRootNodeId: string | null;
selectedVisibleNeighborIds: string[];
selectedCollapsedNeighborIds: string[];
selectedNodeKind: GraphSelectedNodeKind;
canActivateFocused: boolean;
resolvedFocusedNodeId: string | null;
- focusedUnavailableReason: string | null;
+ focusedUnavailableReason: FocusedUnavailableReason | null;
}
export type GraphDisplayLayoutMode = "base" | "mirrored" | "owned";
diff --git a/explorer/tests/graphSceneState.display.test.ts b/explorer/tests/graphSceneState.display.test.ts
index 17049d38..06cdd01c 100644
--- a/explorer/tests/graphSceneState.display.test.ts
+++ b/explorer/tests/graphSceneState.display.test.ts
@@ -1060,7 +1060,7 @@ test("resolveGroupedDisplayStateSnapshot maps selected base node to community in
test("checkGroupedViewAvailability returns unavailable on empty graph", () => {
const result = checkGroupedViewAvailability();
assert.equal(result.available, false);
- assert.ok(typeof result.reason === "string" && result.reason.length > 0);
+ assert.equal(result.reason?.code, "communities-undetected");
});
test("checkGroupedViewAvailability returns available when communities exist", () => {
diff --git a/explorer/tests/graphViewCopy.test.ts b/explorer/tests/graphViewCopy.test.ts
new file mode 100644
index 00000000..0a62d5c5
--- /dev/null
+++ b/explorer/tests/graphViewCopy.test.ts
@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ focusedUnavailableReasonText,
+ groupedViewReasonText,
+} from "../src/workspaces/GraphWorkspace/graphViewCopy.ts";
+
+test("groupedViewReasonText owns grouped-view copy for every reason code", () => {
+ assert.equal(
+ groupedViewReasonText({ code: "communities-undetected" }),
+ "Grouped view is unavailable until communities can be detected.",
+ );
+ assert.equal(
+ groupedViewReasonText({ code: "community-nodes-missing" }),
+ "Grouped view is unavailable because no community nodes could be created.",
+ );
+ assert.equal(
+ groupedViewReasonText({ code: "invalid-community-layout", nodeId: "community-a" }),
+ "Grouped node community-a has invalid coordinates.",
+ );
+ assert.equal(
+ groupedViewReasonText({ code: "missing-grouped-node", edgeId: "edge-1" }),
+ "Grouped edge edge-1 references a missing grouped node.",
+ );
+ assert.equal(groupedViewReasonText(null), null);
+});
+
+test("focusedUnavailableReasonText owns focused-mode copy for every reason code", () => {
+ assert.equal(
+ focusedUnavailableReasonText({ code: "no-selection" }),
+ "Select a node to inspect in Focused mode.",
+ );
+ assert.equal(
+ focusedUnavailableReasonText({ code: "grouped-unresolvable" }),
+ "Focused mode is unavailable for this grouped selection.",
+ );
+ assert.equal(
+ focusedUnavailableReasonText({ code: "not-in-graph" }),
+ "Selected item is not available in the current graph.",
+ );
+ assert.equal(focusedUnavailableReasonText(null), null);
+});
diff --git a/explorer/tests/localGraphTransition.test.ts b/explorer/tests/localGraphTransition.test.ts
new file mode 100644
index 00000000..2b76ef89
--- /dev/null
+++ b/explorer/tests/localGraphTransition.test.ts
@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { localGraphRequiresDraftConfirm } from "../src/workspaces/GraphWorkspace/localGraphTransition.ts";
+import type { GraphViewMode } from "../src/workspaces/GraphWorkspace/types.ts";
+
+test("localGraphRequiresDraftConfirm prompts when enterLocalGraph would change mode or Markdown resource", () => {
+ const cases: Array<{
+ viewMode: GraphViewMode;
+ selectedNodeId: string;
+ resolvedNodeId: string;
+ expected: boolean;
+ }> = [
+ { viewMode: "focused", selectedNodeId: "n1", resolvedNodeId: "n1", expected: false },
+ { viewMode: "focused", selectedNodeId: "n1", resolvedNodeId: "n2", expected: true },
+ { viewMode: "focused", selectedNodeId: "", resolvedNodeId: "n1", expected: true },
+ { viewMode: "full", selectedNodeId: "n1", resolvedNodeId: "n1", expected: true },
+ { viewMode: "full", selectedNodeId: "n1", resolvedNodeId: "n2", expected: true },
+ { viewMode: "grouped", selectedNodeId: "community-1", resolvedNodeId: "n1", expected: true },
+ { viewMode: "grouped", selectedNodeId: "n1", resolvedNodeId: "n1", expected: true },
+ ];
+
+ for (const row of cases) {
+ assert.equal(
+ localGraphRequiresDraftConfirm(row.viewMode, row.selectedNodeId, row.resolvedNodeId),
+ row.expected,
+ JSON.stringify(row),
+ );
+ }
+});