@principal-ai/subsystems-react 0.17.0

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

@@ -0,0 +1,239 @@
+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';
+import { SubsystemComponentGraph } from '../../../subsystem/SubsystemComponentGraph';
+import type {
+  SubsystemComponent,
+  SubsystemComponentEdge,
+  SubsystemThroughline,
+} from '../../../subsystem/model';
+import { PierreThroughlineCodeView } from '../../../pierre';
+import type { ThroughlineViewerContext } from '../../../subsystem/SubsystemComponentGraph';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Flows',
+  component: SubsystemComponentGraph,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof SubsystemComponentGraph>;
+
+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);
+  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',
+    name: 'DrawingsLeftPanel',
+    construct: 'class',
+    file: 'src/panels/DrawingsLeftPanel.tsx',
+    purl: 'pkg:github/principal-ai/desktop-app',
+    purpose: 'lists drawings; emits open/delete intents',
+    symbol: 'DrawingsLeftPanel',
+    process: 'draw-list',
+  },
+  {
+    id: 'host',
+    name: 'useDrawingsHost',
+    construct: 'function',
+    file: 'src/hooks/useDrawingsHost.ts',
+    purl: 'pkg:github/principal-ai/desktop-app',
+    purpose: 'hosts drawing CRUD; dispatches to storage and shell',
+    symbol: 'useDrawingsHost',
+    process: 'draw-list',
+  },
+  {
+    id: 'storage',
+    name: 'DrawingsStorage',
+    construct: 'class',
+    file: 'src/storage/drawingsStorage.ts',
+    purl: 'pkg:github/principal-ai/desktop-app',
+    purpose: 'persists drawings as files',
+    symbol: 'DrawingsStorage',
+    process: 'draw-host',
+  },
+  {
+    id: 'fs',
+    name: 'FileSystemService',
+    construct: 'external',
+    file: 'src/services/fileSystem.ts',
+    purl: 'pkg:github/principal-ai/desktop-app',
+    purpose: 'sandboxed host fd/fs access',
+    symbol: 'FileSystemService',
+    role: 'service',
+  },
+  {
+    id: 'shell',
+    name: 'WorkspaceShell',
+    construct: 'class',
+    file: 'src/workspace/WorkspaceShell.tsx',
+    purl: 'pkg:github/principal-ai/desktop-app',
+    purpose: 'mounts tabs for opened drawings',
+    symbol: 'WorkspaceShell',
+    process: 'draw-host',
+  },
+  {
+    id: 'tab',
+    name: 'DrawingTabContent',
+    construct: 'class',
+    file: 'src/components/DrawingTabContent.tsx',
+    purl: 'pkg:github/principal-ai/desktop-app',
+    purpose: 'loads/saves an open drawing',
+    symbol: 'DrawingTabContent',
+    process: 'draw-host',
+  },
+];
+
+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[] = [
+  {
+    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' },
+    ],
+  },
+  {
+    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' },
+    ],
+  },
+  {
+    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' },
+    ],
+  },
+];
+
+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
+        components={drawingComponents}
+        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**; clicking a step focuses that edge and scrolls the bottom CodeView to that snippet."
+        renderThroughlineViewer={renderThroughlineViewer}
+        renderFileViewer={(file, opts) => (
+          <div
+            style={{
+              padding: 12,
+              fontFamily: 'monospace',
+              fontSize: 12,
+              color: '#bbb',
+              whiteSpace: 'pre',
+            }}
+          >
+            {`// ${file}`}
+            {opts?.startLine != null ? `\n  // → focus line ${opts.startLine}` : ''}
+            {'\n  …'}
+          </div>
+        )}
+      />
+    </div>
+  );
+}
+
+export const ThreeFlows: Story = {
+  render: () => <FlowsDemo />,
+};

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

@@ -0,0 +1,216 @@
+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 } from '../../../subsystem/model';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/FrameworkStereotype',
+  component: SubsystemComponentGraph,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof SubsystemComponentGraph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const purl = 'pkg:github/principal-ai/principal-view-core-library';
+
+/**
+ * Same language construct (`function`) with and without framework stereotypes.
+ * Badge text prefers `framework · stereotype` so UI units read as components /
+ * hooks instead of plain functions; construct color stays function-indigo.
+ */
+const reactUiComponents: SubsystemComponent[] = [
+  {
+    id: 'create-graph',
+    name: 'createSubsystemModel',
+    construct: 'function',
+    file: 'packages/subsystems-studio/src/bun/subsystem-model-store.ts',
+    purl,
+    symbol: 'createSubsystemModel',
+    purpose: 'language-only helper — no framework / stereotype',
+    process: 'principal-studio/host',
+    layer: 1,
+  },
+  {
+    id: 'http-entry',
+    name: 'handleSubsystemModelRequest',
+    construct: 'function',
+    file: 'packages/subsystems-studio/src/bun/http-server.ts',
+    purl,
+    symbol: 'handleSubsystemModelRequest',
+    purpose: 'HTTP bridge entry — topology role, still no React stereotype',
+    role: 'entry',
+    process: 'principal-studio/host',
+    layer: 1,
+  },
+  {
+    id: 'sessions-view',
+    name: 'AgentSessionsOverviewView',
+    construct: 'function',
+    file: 'packages/subsystems-studio/src/mainview/views/AgentSessions.tsx',
+    purl,
+    symbol: 'AgentSessionsOverviewView',
+    purpose: 'React view — construct stays function; stereotype labels it',
+    framework: 'react',
+    stereotype: 'component',
+    process: 'principal-studio/renderer',
+    layer: 2,
+  },
+  {
+    id: 'analysis-view',
+    name: 'AnalysisView',
+    construct: 'function',
+    file: 'packages/subsystems-studio/src/mainview/views/AnalysisView.tsx',
+    purl,
+    symbol: 'AnalysisView',
+    purpose: 'another React component alongside a hook',
+    framework: 'react',
+    stereotype: 'component',
+    process: 'principal-studio/renderer',
+    layer: 2,
+  },
+  {
+    id: 'drawings-host',
+    name: 'useDrawingsHost',
+    construct: 'function',
+    file: 'packages/subsystems-studio/src/mainview/hooks/useDrawingsHost.ts',
+    purl,
+    symbol: 'useDrawingsHost',
+    purpose: 'React hook — same construct, different stereotype',
+    framework: 'react',
+    stereotype: 'hook',
+    process: 'principal-studio/renderer',
+    layer: 2,
+  },
+  {
+    id: 'graph-doc-type',
+    name: 'SubsystemModelDocument',
+    construct: 'type_alias',
+    file: 'packages/subsystems-core/src/types/subsystem-model.ts',
+    purl,
+    symbol: 'SubsystemModelDocument',
+    purpose: 'type-only — framework / stereotype stay empty',
+    layer: 3,
+  },
+];
+
+const reactUiEdges: SubsystemComponentEdge[] = [
+  {
+    id: 'http-to-create',
+    from: 'http-entry',
+    to: 'create-graph',
+    mechanism: 'calls',
+  },
+  {
+    id: 'sessions-uses-hook',
+    from: 'sessions-view',
+    to: 'drawings-host',
+    mechanism: 'uses',
+  },
+  {
+    id: 'analysis-uses-type',
+    from: 'analysis-view',
+    to: 'graph-doc-type',
+    mechanism: 'references',
+  },
+  {
+    id: 'sessions-to-analysis',
+    from: 'sessions-view',
+    to: 'analysis-view',
+    mechanism: 'feeds',
+  },
+];
+
+export const ReactComponentsAndHooks: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        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}
+      />
+    </div>
+  ),
+};
+
+/** Nest-style stereotypes on the same ontology — controller / middleware / guard. */
+const nestComponents: SubsystemComponent[] = [
+  {
+    id: 'graphs-controller',
+    name: 'SubsystemModelsController',
+    construct: 'class',
+    file: 'src/graphs/graphs.controller.ts',
+    purl: 'pkg:github/acme/api',
+    symbol: 'SubsystemModelsController',
+    purpose: 'Nest HTTP controller',
+    framework: 'nestjs',
+    stereotype: 'controller',
+    role: 'entry',
+    layer: 1,
+  },
+  {
+    id: 'auth-guard',
+    name: 'AuthGuard',
+    construct: 'class',
+    file: 'src/auth/auth.guard.ts',
+    purl: 'pkg:github/acme/api',
+    symbol: 'AuthGuard',
+    purpose: 'request guard',
+    framework: 'nestjs',
+    stereotype: 'guard',
+    layer: 1,
+  },
+  {
+    id: 'logging-mw',
+    name: 'LoggingMiddleware',
+    construct: 'function',
+    file: 'src/logging/logging.middleware.ts',
+    purl: 'pkg:github/acme/api',
+    symbol: 'LoggingMiddleware',
+    purpose: 'Express-style middleware function under Nest',
+    framework: 'nestjs',
+    stereotype: 'middleware',
+    layer: 1,
+  },
+  {
+    id: 'graphs-service',
+    name: 'GraphsService',
+    construct: 'class',
+    file: 'src/graphs/graphs.service.ts',
+    purl: 'pkg:github/acme/api',
+    symbol: 'GraphsService',
+    purpose: 'injectable service — stereotype without UI',
+    framework: 'nestjs',
+    stereotype: 'injectable',
+    layer: 2,
+  },
+];
+
+const nestEdges: SubsystemComponentEdge[] = [
+  { id: 'mw-to-guard', from: 'logging-mw', to: 'auth-guard', mechanism: 'uses' },
+  { id: 'guard-to-ctrl', from: 'auth-guard', to: 'graphs-controller', mechanism: 'uses' },
+  { id: 'ctrl-to-svc', from: 'graphs-controller', to: 'graphs-service', mechanism: 'calls' },
+];
+
+export const NestControllerStack: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        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}
+      />
+    </div>
+  ),
+};

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

@@ -0,0 +1,70 @@
+import '@xyflow/react/dist/style.css';
+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';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/GraphTitle',
+  component: SubsystemComponentGraph,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof SubsystemComponentGraph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const graphOnlyComponents = components([
+  ['entry', 'checkoutApi', 'function', 'src/checkout/api.ts', 'pkg:github/you/your-app', 'Handles cart requests.', 'checkoutApi'],
+  ['store', 'cartStore', 'store', 'src/checkout/cartStore.ts', 'pkg:github/you/your-app', 'Retained cart state.', 'cartStore'],
+  ['stripe', 'Stripe', 'external', '', 'external', undefined, undefined],
+  ['caller', 'Web client', 'external', '', 'external', undefined, undefined],
+]);
+
+const graphOnlyEdges = edges([
+  ['caller', 'entry', 'calls'],
+  ['entry', 'store', 'writes'],
+  ['entry', 'stripe', 'calls'],
+]);
+
+function GraphOnly() {
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={graphOnlyComponents}
+        edges={graphOnlyEdges}
+        graphTitle="Checkout"
+        hideSidebar
+      />
+    </div>
+  );
+}
+
+/** The hero configuration: no sidebar, subsystem name as a canvas chip. */
+export const GraphOnlyWithTitle: Story = {
+  render: () => <GraphOnly />,
+};
+
+/** graphTitle also works alongside the full sidebar (chip + sidebar title). */
+export const WithSidebar: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={graphOnlyComponents}
+        edges={graphOnlyEdges}
+        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"
+      />
+    </div>
+  ),
+};

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

@@ -0,0 +1,68 @@
+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';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Processes',
+  component: SubsystemComponentGraph,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof SubsystemComponentGraph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Two deployment units + one unframed outsider: host and renderer each get a
+// dashed process frame; the service sits outside every boundary.
+const processComponents = [
+  ...components([
+    ['main', 'main', 'function', 'src/host/main.ts', 'pkg:github/principal-ai/principal-studio', 'boots the host process', 'main'],
+    ['store', 'SessionStore', 'store', 'src/host/store.ts', 'pkg:github/principal-ai/principal-studio', 'retained host state', 'SessionStore'],
+    ['view', 'TrailView', 'function', 'src/renderer/view.tsx', 'pkg:github/principal-ai/principal-studio', 'renders the trail', 'TrailView'],
+    ['bridge', 'bridge', 'module', 'src/renderer/bridge.ts', 'pkg:github/principal-ai/principal-studio', 'IPC bridge to the host', 'bridge'],
+  ]),
+  {
+    id: 'svc',
+    name: 'telemetry',
+    construct: 'external' as const,
+    file: '',
+    purl: 'external',
+    purpose: 'external telemetry sink (no process, never framed)',
+    role: 'service' as const,
+  },
+].map((c, i) =>
+  i < 2
+    ? { ...c, process: 'principal-studio/host' }
+    : i < 4
+      ? { ...c, process: 'principal-studio/renderer' }
+      : c,
+);
+
+const processEdges = edges([
+  ['main', 'store', 'writes'],
+  ['main', 'bridge', 'calls'],
+  ['bridge', 'view', 'feeds'],
+  ['main', 'svc', 'uses'],
+]);
+
+export const ProcessBoundaries: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        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}
+      />
+    </div>
+  ),
+};