@principal-ai/subsystems-react 0.20.6 → 0.21.0

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

@@ -3,13 +3,9 @@ import '@xyflow/react/dist/style.css';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
-import type {
-  SubsystemComponent,
-  SubsystemComponentEdge,
-  SubsystemThroughline,
-} from '../../../subsystem/model';
-import { PierreThroughlineCodeView } from '../../../pierre';
-import type { ThroughlineViewerContext } from '../../../subsystem/SubsystemComponentGraph';
+import type { SubsystemComponent, SubsystemWalkthrough } from '../../../subsystem/model';
+import { PierreWalkthroughCodeView } from '../../../pierre';
+import type { WalkthroughViewerContext } from '../../../subsystem/SubsystemComponentGraph';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Flows',
@@ -30,16 +26,6 @@ const meta = {
 export default meta;
 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, 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);
@@ -58,19 +44,11 @@ function fakeSource(path: string, markedLines: number[]): string {
 }
 
 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/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,
-  ]),
+  'src/components/DrawingTabContent.tsx': fakeSource('src/components/DrawingTabContent.tsx', [83, 112, 121]),
 };
 
 function readStoryFile(path: string): Promise<string> {
@@ -144,59 +122,46 @@ const drawingComponents: SubsystemComponent[] = [
   },
 ];
 
-const drawingEdges: SubsystemComponentEdge[] = [
-  { id: 'e-scan', from: 'panel', to: 'storage', mechanism: 'calls' },
-  { id: 'e-open-event', from: 'panel', to: 'host', mechanism: 'produces' },
-  { id: 'e-refresh', from: 'host', to: 'panel', mechanism: 'produces' },
-  { id: 'e-open', from: 'host', to: 'storage', mechanism: 'calls' },
-  { id: 'e-read', from: 'storage', to: 'fs', mechanism: 'calls' },
-  { id: 'e-delete', from: 'host', to: 'fs', mechanism: 'calls' },
-  { id: 'e-show', from: 'host', to: 'shell', mechanism: 'produces' },
-  { id: 'e-mount', from: 'shell', to: 'tab', mechanism: 'feeds' },
-  { id: 'e-tab-io', from: 'tab', to: 'fs', mechanism: 'calls' },
-  { id: 'e-saved-event', from: 'tab', to: 'host', mechanism: 'produces' },
-];
-
-const drawingThroughlines: SubsystemThroughline[] = [
+const drawingWalkthroughs: SubsystemWalkthrough[] = [
   {
     id: 'tl-open-drawing',
     title: 'Open drawing',
     steps: [
-      { edgeId: 'e-scan', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan', annotation: 'Lists the drawings directory; each row feeds an open intent.' },
-      { edgeId: 'e-open-event', file: 'src/panels/DrawingsLeftPanel.tsx', line: 85, symbol: 'DrawingsLeftPanel.openDrawing', annotation: 'Emits the open intent up to the host.' },
-      { edgeId: 'e-open', file: 'src/hooks/useDrawingsHost.ts', line: 45, symbol: 'useDrawingsHost.openDrawing', annotation: 'Host resolves the path and delegates to storage.' },
-      { edgeId: 'e-show', file: 'src/workspace/WorkspaceShell.tsx', line: 369, symbol: 'WorkspaceShell.openTab', annotation: 'Asks the shell to surface the drawing as a tab.' },
-      { edgeId: 'e-mount', file: 'src/workspace/WorkspaceShell.tsx', line: 372, symbol: 'WorkspaceShell.mountTab' },
-      { edgeId: 'e-read', file: 'src/storage/drawingsStorage.ts', line: 90, symbol: 'DrawingsStorage.read', annotation: 'Reads the file through the sandboxed fs service.' },
-      { edgeId: 'e-tab-io', file: 'src/components/DrawingTabContent.tsx', line: 83, symbol: 'DrawingTabContent.load' },
+      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan', annotation: 'Lists the drawings directory; each row feeds an open intent.' },
+      { from: 'panel', to: 'host', mechanism: 'produces', file: 'src/panels/DrawingsLeftPanel.tsx', line: 85, symbol: 'DrawingsLeftPanel.openDrawing', annotation: 'Emits the open intent up to the host.' },
+      { from: 'host', to: 'storage', mechanism: 'calls', file: 'src/hooks/useDrawingsHost.ts', line: 45, symbol: 'useDrawingsHost.openDrawing', annotation: 'Host resolves the path and delegates to storage.' },
+      { from: 'host', to: 'shell', mechanism: 'produces', file: 'src/workspace/WorkspaceShell.tsx', line: 369, symbol: 'WorkspaceShell.openTab', annotation: 'Asks the shell to surface the drawing as a tab.' },
+      { from: 'shell', to: 'tab', mechanism: 'feeds', file: 'src/workspace/WorkspaceShell.tsx', line: 372, symbol: 'WorkspaceShell.mountTab' },
+      { from: 'storage', to: 'fs', mechanism: 'calls', file: 'src/storage/drawingsStorage.ts', line: 90, symbol: 'DrawingsStorage.read', annotation: 'Reads the file through the sandboxed fs service.' },
+      { from: 'tab', to: 'fs', mechanism: 'calls', file: 'src/components/DrawingTabContent.tsx', line: 83, symbol: 'DrawingTabContent.load' },
     ],
   },
   {
     id: 'tl-save-drawing',
     title: 'Save drawing',
     steps: [
-      { edgeId: 'e-tab-io', file: 'src/components/DrawingTabContent.tsx', line: 112, symbol: 'DrawingTabContent.save' },
-      { edgeId: 'e-saved-event', file: 'src/components/DrawingTabContent.tsx', line: 121, symbol: 'DrawingTabContent.emitSaved' },
-      { edgeId: 'e-refresh', file: 'src/hooks/useDrawingsHost.ts', line: 64, symbol: 'useDrawingsHost.onSaved' },
-      { edgeId: 'e-scan', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan' },
+      { from: 'tab', to: 'fs', mechanism: 'calls', file: 'src/components/DrawingTabContent.tsx', line: 112, symbol: 'DrawingTabContent.save' },
+      { from: 'tab', to: 'host', mechanism: 'produces', file: 'src/components/DrawingTabContent.tsx', line: 121, symbol: 'DrawingTabContent.emitSaved' },
+      { from: 'host', to: 'panel', mechanism: 'produces', file: 'src/hooks/useDrawingsHost.ts', line: 64, symbol: 'useDrawingsHost.onSaved' },
+      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan' },
     ],
   },
   {
     id: 'tl-delete-drawing',
     title: 'Delete drawing',
     steps: [
-      { edgeId: 'e-delete', file: 'src/hooks/useDrawingsHost.ts', line: 64, symbol: 'useDrawingsHost.deleteDrawing' },
-      { edgeId: 'e-refresh', file: 'src/hooks/useDrawingsHost.ts', line: 66, symbol: 'useDrawingsHost.refreshList' },
-      { edgeId: 'e-scan', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan' },
+      { from: 'host', to: 'fs', mechanism: 'calls', file: 'src/hooks/useDrawingsHost.ts', line: 64, symbol: 'useDrawingsHost.deleteDrawing' },
+      { from: 'host', to: 'panel', mechanism: 'produces', file: 'src/hooks/useDrawingsHost.ts', line: 66, symbol: 'useDrawingsHost.refreshList' },
+      { from: 'panel', to: 'storage', mechanism: 'calls', file: 'src/panels/DrawingsLeftPanel.tsx', line: 56, symbol: 'DrawingsLeftPanel.scan' },
     ],
   },
 ];
 
 function FlowsDemo() {
-  const renderThroughlineViewer = useCallback(
-    ({ throughline, stepIndex }: ThroughlineViewerContext) => (
-      <PierreThroughlineCodeView
-        throughline={throughline}
+  const renderWalkthroughViewer = useCallback(
+    ({ walkthrough, stepIndex }: WalkthroughViewerContext) => (
+      <PierreWalkthroughCodeView
+        walkthrough={walkthrough}
         stepIndex={stepIndex}
         readFile={readStoryFile}
         contextLines={4}
@@ -209,11 +174,11 @@ function FlowsDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={drawingComponents}
-        edges={drawingEdges}
-        throughlines={drawingThroughlines}
+        relations={[]}
+        walkthroughs={drawingWalkthroughs}
         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**; clicking a step focuses that edge and scrolls the bottom CodeView to that snippet."
-        renderThroughlineViewer={renderThroughlineViewer}
+        description="Three walkthroughs over one graph — opening, saving, and deleting a drawing. The sidebar's **Walkthroughs** panel lists each step by **symbol**; clicking a step focuses that hop and scrolls the bottom CodeView to that snippet."
+        renderWalkthroughViewer={renderWalkthroughViewer}
         renderFileViewer={(file, opts) => (
           <div
             style={{
@@ -236,4 +201,4 @@ function FlowsDemo() {
 
 export const ThreeFlows: Story = {
   render: () => <FlowsDemo />,
-};
+};

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

@@ -137,7 +137,7 @@ export const ReactComponentsAndHooks: Story = {
         title="Framework + stereotype"
         description="construct stays language-shaped (function / type_alias). framework + stereotype label React units as component / hook without inventing a react_component construct. Empty fields mean language-only."
         components={reactUiComponents}
-        edges={reactUiEdges}
+        relations={reactUiEdges.relations} walkthroughs={reactUiEdges.walkthroughs}
       />
     </div>
   ),
@@ -209,7 +209,7 @@ export const NestControllerStack: Story = {
         title="Nest framework stereotypes"
         description="Same optional fields work outside React: class/function constructs plus nestjs controller / guard / middleware / injectable stereotypes."
         components={nestComponents}
-        edges={nestEdges}
+        relations={nestEdges.relations} walkthroughs={nestEdges.walkthroughs}
       />
     </div>
   ),

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

@@ -3,7 +3,7 @@ import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
-import { components, edges } from './fixtures';
+import { components, graphSpecFromEdges, relations } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/GraphTitle',
@@ -30,7 +30,7 @@ const graphOnlyComponents = components([
   ['caller', 'Web client', 'external', '', 'external', undefined, undefined],
 ]);
 
-const graphOnlyEdges = edges([
+const graphOnlyEdges = graphSpecFromEdges([
   ['caller', 'entry', 'calls'],
   ['entry', 'store', 'writes'],
   ['entry', 'stripe', 'calls'],
@@ -41,7 +41,7 @@ function GraphOnly() {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphOnlyComponents}
-        edges={graphOnlyEdges}
+        relations={graphOnlyEdges.relations} walkthroughs={graphOnlyEdges.walkthroughs}
         graphTitle="Checkout"
         hideSidebar
       />
@@ -60,7 +60,7 @@ export const WithSidebar: Story = {
     <div style={{ width: '100%', height: '100vh' }}>
       <SubsystemComponentGraph
         components={graphOnlyComponents}
-        edges={graphOnlyEdges}
+        relations={graphOnlyEdges.relations} walkthroughs={graphOnlyEdges.walkthroughs}
         title="Checkout"
         description="A small e-commerce checkout subsystem: an HTTP entry point that writes to retained cart state and calls out to Stripe."
         graphTitle="Checkout"

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

@@ -2,7 +2,7 @@ import '@xyflow/react/dist/style.css';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
-import { components, edges } from './fixtures';
+import { components, graphSpecFromEdges, relations } from './fixtures';
 
 const meta = {
   title: 'Subsystem/ComponentGraph/Processes',
@@ -47,7 +47,7 @@ const processComponents = [
       : c,
 );
 
-const processEdges = edges([
+const processEdges = graphSpecFromEdges([
   ['main', 'store', 'writes'],
   ['main', 'bridge', 'calls'],
   ['bridge', 'view', 'feeds'],
@@ -61,7 +61,7 @@ export const ProcessBoundaries: Story = {
         title="Process boundaries"
         description="Host and renderer each render in their own ELK-aware boundary frame. The telemetry service has no `process` and sits outside every boundary."
         components={processComponents}
-        edges={processEdges}
+        relations={processEdges.relations} walkthroughs={processEdges.walkthroughs}
       />
     </div>
   ),

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

@@ -237,7 +237,7 @@ function MigrationDemo() {
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <SubsystemComponentGraph
         components={migrationComponents}
-        edges={migrationEdges}
+        relations={migrationEdges.relations} walkthroughs={migrationEdges.walkthroughs}
         onSelect={(id) => setSelected(id)}
       />
       <div style={{ marginTop: 8, padding: '0 12px', fontFamily: 'monospace', fontSize: 12, color: '#aaa' }}>