@principal-ai/subsystems-react 0.23.4 → 0.24.1

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

@@ -0,0 +1,159 @@
+import React, { useState } 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 { SubsystemEdgeView } from '../../../subsystem/model';
+import { components, relations, walkthroughFromHops } from './fixtures';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/EdgeViews',
+  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>;
+
+// ---------------------------------------------------------------------------
+// A graph that carries BOTH vocabularies between overlapping node pairs:
+//   svc --imports--> reader   (topology)
+//   svc --calls--> reader     (runtime hop)
+//   store --imports--> db     (topology)
+//   store --calls--> db       (runtime hop)
+// so switching the label view visibly changes which labels appear.
+// ---------------------------------------------------------------------------
+const labelViewComponents = components([
+  ['api', 'ApiHandler', 'function', 'src/api/handler.ts', 'pkg:github/principal-ai/agent-monitoring', 'HTTP entry point', 'handleRequest'],
+  ['svc', 'SessionService', 'class', 'src/session/SessionService.ts', 'pkg:github/principal-ai/agent-monitoring', 'owns session persistence', 'SessionService'],
+  ['reader', 'SessionReader', 'class', 'src/session/SessionReader.ts', 'pkg:github/principal-ai/agent-monitoring', 'normalizes raw records', 'SessionReader'],
+  ['store', 'SessionStore', 'class', 'src/session/SessionStore.ts', 'pkg:github/principal-ai/agent-monitoring', 'retained session state', 'SessionStore'],
+  ['event', 'SessionEvent', 'interface', 'src/types/SessionEvent.ts', 'pkg:github/principal-ai/agent-monitoring', 'output event shape', 'SessionEvent'],
+  ['db', 'PostgresStore', 'external', 'src/db/PostgresStore.ts', 'pkg:github/principal-ai/agent-monitoring', 'external persistence driver', 'PostgresStore'],
+]);
+
+const labelViewRelations = relations([
+  ['svc', 'reader', 'imports'],
+  ['svc', 'event', 'references'],
+  ['store', 'db', 'imports'],
+  ['reader', 'event', 'references'],
+]);
+
+const labelViewWalkthroughs = [
+  walkthroughFromHops('tl-capture', 'Capture session', [
+    ['api', 'svc', 'calls', 'src/api/handler.ts', 42],
+    ['svc', 'store', 'writes', 'src/session/SessionService.ts', 88],
+    ['store', 'db', 'calls', 'src/session/SessionStore.ts', 120],
+    ['svc', 'event', 'produces', 'src/session/SessionService.ts', 95],
+  ]),
+  walkthroughFromHops('tl-normalize', 'Normalize records', [
+    ['svc', 'reader', 'calls', 'src/session/SessionService.ts', 61],
+    ['reader', 'event', 'produces', 'src/session/SessionReader.ts', 77],
+  ]),
+];
+
+const VIEWS: { value: SubsystemEdgeView; label: string }[] = [
+  { value: 'relations', label: 'Relations' },
+  { value: 'walkthroughs', label: 'Walkthroughs' },
+];
+
+function EdgeViewDemo() {
+  const [view, setView] = useState<SubsystemEdgeView>('relations');
+  const [showEdgeLabels, setShowEdgeLabels] = useState(true);
+
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 12,
+          padding: '8px 12px',
+          borderBottom: '1px solid #333',
+          fontFamily: 'monospace',
+          fontSize: 12,
+          color: '#ddd',
+        }}
+      >
+        <span style={{ color: '#888' }}>edge view</span>
+        <div style={{ display: 'flex', gap: 4 }}>
+          {VIEWS.map((v) => (
+            <button
+              key={v.value}
+              type="button"
+              onClick={() => setView(v.value)}
+              style={{
+                padding: '3px 10px',
+                borderRadius: 4,
+                border: '1px solid #444',
+                background: view === v.value ? '#0893d2' : 'transparent',
+                color: view === v.value ? '#fff' : '#bbb',
+                cursor: 'pointer',
+                font: 'inherit',
+              }}
+            >
+              {v.label}
+            </button>
+          ))}
+        </div>
+        <label style={{ display: 'flex', alignItems: 'center', gap: 6, marginLeft: 'auto' }}>
+          <input
+            type="checkbox"
+            checked={showEdgeLabels}
+            onChange={(e) => setShowEdgeLabels(e.target.checked)}
+          />
+          showEdgeLabels
+        </label>
+      </div>
+      <div style={{ flex: 1, minHeight: 0 }}>
+        <SubsystemComponentGraph
+          components={labelViewComponents}
+          relations={labelViewRelations}
+          walkthroughs={labelViewWalkthroughs}
+          title="edge views"
+          description="The relation and walkthrough vocabularies are disjoint and never shown together. Toggle the view: **Relations** draws `svc --imports--> reader`; **Walkthroughs** draws `svc --calls--> reader`. The model is the same either way."
+          showEdgeLabels={showEdgeLabels}
+          edgeView={view}
+        />
+      </div>
+    </div>
+  );
+}
+
+/** Interactive toggle between the `relations` and `walkthroughs` edge views. */
+export const ToggleEdgeView: Story = {
+  render: () => <EdgeViewDemo />,
+};
+
+/** Storybook-controls variant of the same toggle. */
+export const ViewControl: Story = {
+  render: (args) => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={labelViewComponents}
+        relations={labelViewRelations}
+        walkthroughs={labelViewWalkthroughs}
+        showEdgeLabels={args.showEdgeLabels}
+        edgeView={args.edgeView}
+      />
+    </div>
+  ),
+  args: {
+    showEdgeLabels: true,
+    edgeView: 'relations',
+  },
+  argTypes: {
+    showEdgeLabels: { control: 'boolean' },
+    edgeView: { control: 'inline-radio', options: ['relations', 'walkthroughs'] },
+  },
+};

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

@@ -0,0 +1,130 @@
+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 { SubsystemIssueList, type SubsystemIssue } from '../../../subsystem/IssueList';
+import { components, graphSpecFromEdges } from './fixtures';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Issues',
+  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 ISSUES: SubsystemIssue[] = [
+  {
+    id: 'i1',
+    severity: 'error',
+    kind: 'missing_file',
+    message: 'File src/checkout/cartStore.ts is not present on disk (repo pkg:github/you/your-app).',
+    target: { kind: 'component', id: 'store', label: 'cartStore' },
+    fix: { label: 'Use graphify file' },
+  },
+  {
+    id: 'i2',
+    severity: 'error',
+    kind: 'construct_mismatch',
+    message: 'Claimed function but graphify infers class.',
+    target: { kind: 'component', id: 'entry', label: 'checkoutApi' },
+  },
+  {
+    id: 'i3',
+    severity: 'info',
+    kind: 'signature_unconfirmed',
+    message: 'Named parameter types are not present in the graphify cache.',
+    target: { kind: 'component', id: 'entry', label: 'checkoutApi' },
+  },
+  {
+    id: 'i4',
+    severity: 'error',
+    kind: 'topology_broken_endpoint',
+    message: 'Relation endpoint "store" does not resolve to a component.',
+    target: { kind: 'relation', id: 'r1', label: 'checkoutApi → cartStore', detail: 'writes' },
+  },
+  {
+    id: 'i5',
+    severity: 'warn',
+    kind: 'boundary_module_file_mismatch',
+    message: 'Module "src/checkout" contains a file outside its declared root.',
+    target: { kind: 'module', id: 'src/checkout', label: 'src/checkout' },
+  },
+  {
+    id: 'i6',
+    severity: 'info',
+    kind: 'walkthrough',
+    message: 'Step 2 references a line that moved (was :42).',
+    target: { kind: 'walkthrough', id: 'flow-1', label: 'Checkout', detail: 'step 2' },
+  },
+  {
+    id: 'i7',
+    severity: 'warn',
+    kind: 'boundary_process_nest_disagree',
+    message: 'Component is nested in process "api" but Graphify places it outside.',
+    target: { kind: 'module', id: 'api', label: 'api' },
+  },
+];
+
+const graphComponents = 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],
+]);
+
+const graphEdges = graphSpecFromEdges([
+  ['entry', 'store', 'writes'],
+  ['entry', 'stripe', 'calls'],
+]);
+
+/** The catalogue, grouped by verification layer. */
+export const List: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', width: 380, height: '100vh', borderRight: '1px solid #333' }}>
+      <SubsystemIssueList
+        issues={ISSUES}
+        onSelectIssue={() => {}}
+        onApplyFix={() => {}}
+      />
+    </div>
+  ),
+};
+
+/** All four layers clean — the happy state. */
+export const AllGood: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', width: 380, height: '100vh', borderRight: '1px solid #333' }}>
+      <SubsystemIssueList issues={[]} />
+    </div>
+  ),
+};
+
+/** In place: diagnostics active, so the sidebar bottom panel is the issue list. */
+export const GraphWithIssues: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={graphComponents}
+        relations={graphEdges.relations}
+        walkthroughs={graphEdges.walkthroughs}
+        title="Checkout"
+        description="A small e-commerce checkout subsystem."
+        diagnostic={{ status: 'issues', issueCount: 5, onOpen: () => {} }}
+        issues={ISSUES}
+        onSelectIssue={() => {}}
+        onApplyIssueFix={() => {}}
+      />
+    </div>
+  ),
+};

package/src/subsystem/ComponentDeclaration.tsx

@@ -118,6 +118,8 @@ export interface ComponentDeclarationProps {
   onVerify?: (componentId: string) => void;
   /** Live verification status for the selected component. */
   verification?: ComponentVerificationState | null;
+  /** Start with the file path row visible (catalog / source-first views). */
+  defaultShowFile?: boolean;
 }
 
 function verificationSummary(
@@ -256,11 +258,12 @@ export function ComponentDeclaration({
   maxWidth,
   onVerify,
   verification,
+  defaultShowFile = false,
 }: ComponentDeclarationProps) {
   const { theme, mode } = useTheme();
   const pierreSyntaxTheme = resolvePierreSyntaxThemeName(mode);
   const [fileHovered, setFileHovered] = useState(false);
-  const [showFile, setShowFile] = useState(false);
+  const [showFile, setShowFile] = useState(defaultShowFile);
   const [showPurpose, setShowPurpose] = useState(false);
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const color = componentColor(component, pierreSyntaxTheme);