@principal-ai/principal-view-react 0.16.61 → 0.16.63

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -59,6 +59,17 @@ const EDGE_LABEL_MAX_EDGE_FRACTION = 0.55;
 const EDGE_LABEL_CHAR_PX = 6.2;
 const EDGE_LABEL_PAD_PX = 18;
 
+/** Context passed to `renderThroughlineViewer` when a flow/step is focused. */
+export interface ThroughlineViewerContext {
+  throughline: SubsystemThroughline;
+  /** Focused step index; `null` means the whole flow (no specific step). */
+  stepIndex: number | null;
+}
+
+type DrawerTarget =
+  | { kind: 'file'; file: string; startLine?: number }
+  | { kind: 'throughline'; throughlineId: string; stepIndex: number | null };
+
 export interface SubsystemComponentGraphProps {
   components: SubsystemComponent[];
   edges: SubsystemComponentEdge[];
@@ -67,8 +78,9 @@ export interface SubsystemComponentGraphProps {
    * flow. When present the sidebar's bottom half offers a Files/Flows toggle:
    * the flows panel lists each throughline's steps (`symbol` or `file:line`);
    * clicking a flow row toggles its steps; clicking a step focuses that
-   * step's edge. Opened flows stay on the canvas (unselected ones dimmed);
-   * everything else is hidden.
+   * step's edge and (when `renderThroughlineViewer` is set) opens the bottom
+   * drawer on that flow's snippets. Opened flows stay on the canvas
+   * (unselected ones dimmed); everything else is hidden.
    */
   throughlines?: SubsystemThroughline[];
   onSelect?: (componentId: string) => void;
@@ -105,11 +117,16 @@ export interface SubsystemComponentGraphProps {
   sidebarAfterDescription?: ReactNode;
   /**
    * Host-injected reader/renderer for the bottom file drawer, keyed by
-   * repo-root-relative path. Opening happens on node click (component with a
-   * `file`) and sidebar file-tree click. Keeps this package free of fs and
-   * code-view dependencies.
+   * repo-root-relative path. Opening happens on declaration/file-tree clicks.
+   * Keeps this package free of fs and code-view dependencies.
    */
   renderFileViewer?: (file: string, opts?: SubsystemOpenFileOptions) => ReactNode;
+  /**
+   * Host-injected multi-snippet viewer for a focused throughline. When set,
+   * clicking a flow step (or the whole flow) opens the bottom drawer with
+   * this content and updates it as the focused step changes.
+   */
+  renderThroughlineViewer?: (ctx: ThroughlineViewerContext) => ReactNode;
   /**
    * Legacy component-keyed variant, kept for backward compatibility. When
    * `renderFileViewer` is absent, drawer content resolves via the first
@@ -136,28 +153,39 @@ const edgeTypes: EdgeTypes = {
   'subsystem-edge': SubsystemEdge,
 };
 
-// Memoized drawer body: only rebuilds children when the open file changes.
+// Memoized drawer body: only rebuilds children when the open target changes.
 // Inner re-renders on every viewport pan/zoom and hover; recreating host
 // elements then would churn their readFile closures and flash the file
 // viewer's loading state on each render.
-const DrawerContent = memo(function DrawerContent({
+const FileDrawerContent = memo(function FileDrawerContent({
   render,
   file,
   startLine,
 }: {
   render: (file: string, opts?: SubsystemOpenFileOptions) => ReactNode;
-  file: string | null;
+  file: string;
   startLine?: number;
 }) {
-  if (!file) return null;
   return <>{render(file, startLine != null ? { startLine } : undefined)}</>;
 });
 
+const ThroughlineDrawerContent = memo(function ThroughlineDrawerContent({
+  render,
+  throughline,
+  stepIndex,
+}: {
+  render: (ctx: ThroughlineViewerContext) => ReactNode;
+  throughline: SubsystemThroughline;
+  stepIndex: number | null;
+}) {
+  return <>{render({ throughline, stepIndex })}</>;
+});
+
 interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showLegend, title, hideSidebar, graphTitle, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
+function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showLegend, title, hideSidebar, graphTitle, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, renderThroughlineViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const viewport = useViewport();
@@ -167,13 +195,8 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   });
   const [layoutReady, setLayoutReady] = useState(false);
   const [selected, setSelected] = useState<SubsystemComponent | null>(null);
-  /** File shown in the bottom drawer + optional declaration scroll target. */
-  const [openFileTarget, setOpenFileTarget] = useState<{
-    file: string;
-    startLine?: number;
-  } | null>(null);
-  const openFile = openFileTarget?.file ?? null;
-  const openFileStartLine = openFileTarget?.startLine;
+  /** Bottom drawer: single file or throughline multi-snippet mode. */
+  const [drawerTarget, setDrawerTarget] = useState<DrawerTarget | null>(null);
   // Edge-legend modal visibility (opened from the canvas's top-left button).
   const [legendOpen, setLegendOpen] = useState(false);
   // Component the pointer is over (null on leave) → transient tree highlight.
@@ -194,9 +217,31 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   // closure over the effect deps) can toggle without a stale value.
   const selectedRef = useRef<SubsystemComponent | null>(null);
   selectedRef.current = selected;
-  // Ref mirror of `openFile` for the tree-click toggle.
+  // Ref mirror of the open file drawer target for tree-click toggle.
   const openFileRef = useRef<{ file: string; startLine?: number } | null>(null);
-  openFileRef.current = openFileTarget;
+  const openFile =
+    drawerTarget?.kind === 'file' ? drawerTarget.file : null;
+  openFileRef.current =
+    drawerTarget?.kind === 'file'
+      ? { file: drawerTarget.file, startLine: drawerTarget.startLine }
+      : null;
+
+  const focusedThroughline = useMemo(() => {
+    if (drawerTarget?.kind !== 'throughline' || !throughlines) return null;
+    return throughlines.find((t) => t.id === drawerTarget.throughlineId) ?? null;
+  }, [drawerTarget, throughlines]);
+
+  const drawerTitle = useMemo(() => {
+    if (!drawerTarget) return null;
+    if (drawerTarget.kind === 'file') return drawerTarget.file;
+    const tl = focusedThroughline;
+    if (!tl) return null;
+    if (drawerTarget.stepIndex == null) return tl.title;
+    const step = tl.steps[drawerTarget.stepIndex];
+    if (!step) return tl.title;
+    const site = `${step.file.split('/').pop() ?? step.file}:${step.line}`;
+    return `${tl.title} · ${site}`;
+  }, [drawerTarget, focusedThroughline]);
 
   // Refresh selected component when the components list updates (e.g. verify
   // writes back declarationRef).
@@ -594,10 +639,10 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   const onTreeSelectFile = useCallback(
     (file: string) => {
       if (openFileRef.current?.file === file && openFileRef.current.startLine == null) {
-        setOpenFileTarget(null);
+        setDrawerTarget(null);
         return;
       }
-      setOpenFileTarget({ file });
+      setDrawerTarget({ kind: 'file', file });
       onFileSelect?.(file);
     },
     [onFileSelect],
@@ -610,10 +655,10 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         openFileRef.current?.file === file &&
         openFileRef.current.startLine === startLine
       ) {
-        setOpenFileTarget(null);
+        setDrawerTarget(null);
         return;
       }
-      setOpenFileTarget({ file, startLine });
+      setDrawerTarget({ kind: 'file', file, startLine });
       onFileSelect?.(file);
     },
     [onFileSelect],
@@ -643,7 +688,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
 
   // Focus an entire flow: hide everything but the flow's nodes and edges, and
   // frame the flow on the canvas. Selection state is cleared — the graph now
-  // reads as the narrative.
+  // reads as the narrative. Opens the throughline drawer when a viewer is set.
   const focusThroughlineEdges = useCallback(
     (tl: SubsystemThroughline) => {
       setSelected(null);
@@ -651,17 +696,28 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
       setFocusedStepIndex(null);
       setFocusedThroughlineId(tl.id);
       fitFocusBounds(new Set(tl.steps.map((s) => s.edgeId)));
+      if (renderThroughlineViewer) {
+        setDrawerTarget({ kind: 'throughline', throughlineId: tl.id, stepIndex: null });
+      } else if (tl.steps[0]) {
+        // Fallback: single-file snippet of the first step.
+        setDrawerTarget({
+          kind: 'file',
+          file: tl.steps[0].file,
+          startLine: tl.steps[0].line,
+        });
+      }
     },
-    [fitFocusBounds],
+    [fitFocusBounds, renderThroughlineViewer],
   );
 
   const clearThroughlineFocus = useCallback(() => {
     setFocusedThroughlineId(null);
     setFocusedStepIndex(null);
+    setDrawerTarget((prev) => (prev?.kind === 'throughline' ? null : prev));
   }, []);
 
-  // Focus a single step's edge on the canvas. The step's file:line is listed
-  // in the row; we don't open the drawer from here.
+  // Focus a single step's edge on the canvas and open/scroll the throughline
+  // drawer to that step's snippet.
   const focusThroughlineStep = useCallback(
     (tl: SubsystemThroughline, stepIndex: number) => {
       const step = tl.steps[stepIndex];
@@ -671,8 +727,21 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
       setFocusedStepIndex(stepIndex);
       setFocusedThroughlineId(tl.id);
       fitFocusBounds(new Set([step.edgeId]));
+      if (renderThroughlineViewer) {
+        setDrawerTarget({
+          kind: 'throughline',
+          throughlineId: tl.id,
+          stepIndex,
+        });
+      } else {
+        setDrawerTarget({
+          kind: 'file',
+          file: step.file,
+          startLine: step.line,
+        });
+      }
     },
-    [fitFocusBounds],
+    [fitFocusBounds, renderThroughlineViewer],
   );
 
   const toggleThroughlineCollapsed = useCallback((tlId: string) => {
@@ -781,6 +850,14 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
     [],
   );
 
+  const throughlineViewerRef = useRef(renderThroughlineViewer);
+  throughlineViewerRef.current = renderThroughlineViewer;
+  const renderThroughlineDrawerContent = useCallback(
+    (ctx: ThroughlineViewerContext) =>
+      throughlineViewerRef.current?.(ctx) ?? null,
+    [],
+  );
+
   return (
     <div style={{ width: '100%', height: '100%', display: 'flex', flexDirection: 'row' }}>
       {/* Sidebar: scrollable title/description on top, files or flows pinned to the bottom half */}
@@ -1157,12 +1234,22 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
           mechanisms={usedMechanisms}
           onClose={() => setLegendOpen(false)}
         />
-      <FileDrawer file={openFile} onClose={() => setOpenFileTarget(null)}>
-        <DrawerContent
-          render={renderDrawerContent}
-          file={openFile}
-          startLine={openFileStartLine}
-        />
+      <FileDrawer title={drawerTitle} onClose={() => setDrawerTarget(null)}>
+        {drawerTarget?.kind === 'throughline' &&
+        focusedThroughline &&
+        renderThroughlineViewer ? (
+          <ThroughlineDrawerContent
+            render={renderThroughlineDrawerContent}
+            throughline={focusedThroughline}
+            stepIndex={drawerTarget.stepIndex}
+          />
+        ) : drawerTarget?.kind === 'file' ? (
+          <FileDrawerContent
+            render={renderDrawerContent}
+            file={drawerTarget.file}
+            startLine={drawerTarget.startLine}
+          />
+        ) : null}
       </FileDrawer>
       {/* Startup cover — hides measurement, layout swap, and camera settle. */}
       <GraphLayoutCover revealed={layoutReady} />

package/src/subsystem/nodes.tsx

@@ -322,10 +322,10 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
       <div
         style={{
           position: 'absolute',
-          top: -13,
+          top: -19,
           left: 12,
           fontFamily: theme.fonts.monospace,
-          fontSize: theme.fontSizes[0],
+          fontSize: theme.fontSizes[3],
           fontWeight: 700,
           letterSpacing: 0.6,
           color,
@@ -336,7 +336,7 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
           whiteSpace: 'nowrap',
         }}
       >
-        {`process: ${region.label}`}
+        {region.label}
       </div>
     </div>
   );