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

package/src/stories/Subsystem/ComponentGraph/Flows.stories.tsx

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useCallback } from 'react';
 import '@xyflow/react/dist/style.css';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
@@ -8,6 +8,8 @@ import type {
   SubsystemComponentEdge,
   SubsystemThroughline,
 } from '../../../subsystem/model';
+import { PierreThroughlineCodeView } from '../../../pierre';
+import type { ThroughlineViewerContext } from '../../../subsystem/SubsystemComponentGraph';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Flows',
@@ -32,10 +34,53 @@ type Story = StoryObj<typeof meta>;
 // Mirror of the retrofitted electron-app drawing graph: the sidebar's Files
 // panel swaps to a Flows panel listing three throughlines (open / save /
 // delete). Clicking a flow row toggles its steps; clicking a step focuses
-// that step's edge and frames it on the canvas. Other opened flows stay
-// dimmed; the rest of the graph is hidden.
+// that step's edge, frames it on the canvas, and scrolls the bottom CodeView
+// to that step's snippet. Other opened flows stay dimmed; the rest of the
+// graph is hidden.
 // ---------------------------------------------------------------------------
 
+/** Build enough placeholder lines so step `line` values land inside the file. */
+function fakeSource(path: string, markedLines: number[]): string {
+  const maxLine = Math.max(80, ...markedLines);
+  const marks = new Set(markedLines);
+  const lines: string[] = [`// ${path}`, ''];
+  for (let i = 3; i <= maxLine; i++) {
+    if (marks.has(i)) {
+      lines.push(`export function stepAtLine${i}() {`);
+      lines.push(`  return ${i};`);
+      lines.push(`}`);
+      lines.push('');
+    } else {
+      lines.push(`// context line ${i}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+const storyFiles: Record<string, string> = {
+  'src/panels/DrawingsLeftPanel.tsx': fakeSource('src/panels/DrawingsLeftPanel.tsx', [
+    56, 85,
+  ]),
+  'src/hooks/useDrawingsHost.ts': fakeSource('src/hooks/useDrawingsHost.ts', [
+    45, 64, 66,
+  ]),
+  'src/workspace/WorkspaceShell.tsx': fakeSource('src/workspace/WorkspaceShell.tsx', [
+    369, 372,
+  ]),
+  'src/storage/drawingsStorage.ts': fakeSource('src/storage/drawingsStorage.ts', [90]),
+  'src/components/DrawingTabContent.tsx': fakeSource('src/components/DrawingTabContent.tsx', [
+    83, 112, 121,
+  ]),
+};
+
+function readStoryFile(path: string): Promise<string> {
+  const content = storyFiles[path];
+  if (content == null) {
+    return Promise.reject(new Error(`No story fixture for ${path}`));
+  }
+  return Promise.resolve(content);
+}
+
 const drawingComponents: SubsystemComponent[] = [
   {
     id: 'panel',
@@ -148,6 +193,18 @@ const drawingThroughlines: SubsystemThroughline[] = [
 ];
 
 function FlowsDemo() {
+  const renderThroughlineViewer = useCallback(
+    ({ throughline, stepIndex }: ThroughlineViewerContext) => (
+      <PierreThroughlineCodeView
+        throughline={throughline}
+        stepIndex={stepIndex}
+        readFile={readStoryFile}
+        contextLines={4}
+      />
+    ),
+    [],
+  );
+
   return (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
@@ -155,7 +212,8 @@ function FlowsDemo() {
         edges={drawingEdges}
         throughlines={drawingThroughlines}
         title="drawing-files flow"
-        description="Three throughlines over one graph — opening, saving, and deleting a drawing. The sidebar's **Flows** panel lists each step by **symbol** (the frame at that hop); clicking a step focuses that edge on the canvas."
+        description="Three throughlines over one graph — opening, saving, and deleting a drawing. The sidebar's **Flows** panel lists each step by **symbol**; clicking a step focuses that edge and scrolls the bottom CodeView to that snippet."
+        renderThroughlineViewer={renderThroughlineViewer}
         renderFileViewer={(file, opts) => (
           <div
             style={{

package/src/subsystem/FileDrawer.tsx

@@ -1,7 +1,8 @@
 /**
  * FileDrawer — bottom panel that slides up from the bottom of the graph area
- * to show a file's contents. Opened by sidebar file-tree clicks (and any host
- * wiring); content is injected as children by the graph component.
+ * to show file / throughline code. Opened by sidebar file-tree clicks,
+ * declaration links, and throughline step focus; content is injected as
+ * children by the graph component.
  */
 
 import { useEffect } from 'react';
@@ -9,22 +10,22 @@ import type { ReactNode } from 'react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { X } from 'lucide-react';
 
-/** Bottom panel that slides up from the bottom of the graph area to show a
- *  file's contents — opened by node clicks and sidebar file-tree clicks
- *  alike. Sits in normal flow (canvas shrinks while open, nothing covered)
+/** Bottom panel that slides up from the bottom of the graph area.
+ *  Sits in normal flow (canvas shrinks while open, nothing covered)
  *  and animates via height; stays mounted so open/close animates. */
 export function FileDrawer({
-  file,
+  title,
   onClose,
   children,
 }: {
-  file: string | null;
+  /** Drawer chrome title; `null` closes the drawer. */
+  title: string | null;
   onClose: () => void;
   children?: ReactNode;
 }) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
-  const open = file !== null;
+  const open = title !== null;
 
   useEffect(() => {
     if (!open) return;
@@ -64,7 +65,7 @@ export function FileDrawer({
         }}
       >
         <span
-          title={file ?? undefined}
+          title={title ?? undefined}
           style={{
             flex: 1,
             minWidth: 0,
@@ -76,7 +77,7 @@ export function FileDrawer({
             color: muted,
           }}
         >
-          {file}
+          {title}
         </span>
         <button
           type="button"

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} />