@principal-ai/subsystems-react 0.24.0 → 0.24.1

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

@@ -0,0 +1,138 @@
+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 {
+  SubsystemDiagnosticToggle,
+  type SubsystemDiagnosticStatus,
+} from '../../../subsystem/DiagnosticToggle';
+import { components, graphSpecFromEdges } from './fixtures';
+
+const meta = {
+  title: 'Subsystem/ComponentGraph/Diagnostics',
+  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 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],
+  ['caller', 'Web client', 'external', '', 'external', undefined, undefined],
+]);
+
+const graphEdges = graphSpecFromEdges([
+  ['caller', 'entry', 'calls'],
+  ['entry', 'store', 'writes'],
+  ['entry', 'stripe', 'calls'],
+]);
+
+const GRAPH_DESCRIPTION =
+  'A small e-commerce checkout subsystem: an HTTP entry point that writes to retained cart state and calls out to Stripe.';
+
+/** Every chip state side by side, for quick visual review. */
+export const States: Story = {
+  render: () => {
+    const rows: Array<{ label: string; status: SubsystemDiagnosticStatus; issueCount?: number; stale?: boolean; busy?: boolean }> = [
+      { label: 'ok', status: 'ok' },
+      { label: 'ok (stale)', status: 'ok', stale: true },
+      { label: 'issues · 3', status: 'issues', issueCount: 3 },
+      { label: 'gaps · 2', status: 'gaps', issueCount: 2 },
+      { label: 'unknown (never checked)', status: 'unknown' },
+      { label: 'issues (busy)', status: 'issues', issueCount: 3, busy: true },
+    ];
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 18, padding: 32 }}>
+        {rows.map((row) => (
+          <div key={row.label} style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+            <span style={{ width: 200, fontFamily: 'monospace', fontSize: 12, opacity: 0.7 }}>
+              {row.label}
+            </span>
+            <SubsystemDiagnosticToggle
+              status={row.status}
+              issueCount={row.issueCount}
+              stale={row.stale}
+              busy={row.busy}
+              onOpen={() => {}}
+            />
+          </div>
+        ))}
+      </div>
+    );
+  },
+};
+
+/** The chip in its real home: the sidebar title row, beside the description toggle. */
+export const GraphClean: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={graphComponents}
+        relations={graphEdges.relations}
+        walkthroughs={graphEdges.walkthroughs}
+        title="Checkout"
+        description={GRAPH_DESCRIPTION}
+        diagnostic={{ status: 'ok', onOpen: () => {} }}
+      />
+    </div>
+  ),
+};
+
+export const GraphWithIssues: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={graphComponents}
+        relations={graphEdges.relations}
+        walkthroughs={graphEdges.walkthroughs}
+        title="Checkout"
+        description={GRAPH_DESCRIPTION}
+        diagnostic={{ status: 'issues', issueCount: 3, onOpen: () => {} }}
+      />
+    </div>
+  ),
+};
+
+/** Stale report: the color stays, a hollow ring marks that inputs changed. */
+export const GraphStale: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={graphComponents}
+        relations={graphEdges.relations}
+        walkthroughs={graphEdges.walkthroughs}
+        title="Checkout"
+        description={GRAPH_DESCRIPTION}
+        diagnostic={{ status: 'issues', issueCount: 3, stale: true, onOpen: () => {} }}
+      />
+    </div>
+  ),
+};
+
+/** No title/description — the chip still anchors the title row at the right. */
+export const GraphChipOnly: Story = {
+  render: () => (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <SubsystemComponentGraph
+        components={graphComponents}
+        relations={graphEdges.relations}
+        walkthroughs={graphEdges.walkthroughs}
+        title="Checkout"
+        diagnostic={{ status: 'gaps', issueCount: 2, onOpen: () => {} }}
+      />
+    </div>
+  ),
+};

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);