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

package/src/stories/Pierre/CodeView.stories.tsx

@@ -0,0 +1,196 @@
+/**
+ * Demo: Pierre CodeView with snippets from different files.
+ *
+ * Throughlines want many short windows across files in one scroll —
+ * CodeView is the Pierre primitive for that (virtualized list of file items).
+ */
+import React, { useMemo, useRef } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  CodeView,
+  type CodeViewHandle,
+  type CodeViewItem,
+} from '@pierre/diffs/react';
+import { ThemeProvider, defaultEditorTheme, useTheme } from '@principal-ade/industry-theme';
+import { sliceSnippetWindow } from '../../pierre/sliceSnippet';
+import { resolvePierreSyntaxThemeName } from '../../pierre/pierreSyntaxTheme';
+import componentDeclarationSource from '../../subsystem/ComponentDeclaration.tsx?raw';
+import resolveSource from '../../graphify/resolve.ts?raw';
+import modelSource from '../../subsystem/model.ts?raw';
+
+type SnippetSpec = {
+  id: string;
+  path: string;
+  contents: string;
+  startLine: number;
+  endLine: number;
+  focusLine?: number;
+  label: string;
+};
+
+const SNIPPETS: SnippetSpec[] = [
+  {
+    id: 'step-1',
+    path: 'packages/react/src/subsystem/ComponentDeclaration.tsx',
+    contents: componentDeclarationSource,
+    startLine: 252,
+    endLine: 270,
+    focusLine: 252,
+    label: '1 · ComponentDeclaration export',
+  },
+  {
+    id: 'step-2',
+    path: 'packages/react/src/graphify/resolve.ts',
+    contents: resolveSource,
+    startLine: 1,
+    endLine: 40,
+    focusLine: 1,
+    label: '2 · graphify resolve',
+  },
+  {
+    id: 'step-3',
+    path: 'packages/react/src/subsystem/model.ts',
+    contents: modelSource,
+    startLine: 216,
+    endLine: 250,
+    focusLine: 216,
+    label: '3 · Throughline types',
+  },
+];
+
+const meta = {
+  title: 'Pierre/CodeView',
+  parameters: {
+    layout: 'fullscreen',
+  },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+function MultiFileSnippetsDemo() {
+  const { theme, mode } = useTheme();
+  const viewRef = useRef<CodeViewHandle>(null);
+
+  const items = useMemo((): CodeViewItem[] => {
+    return SNIPPETS.map((spec) => {
+      const slice = sliceSnippetWindow(
+        spec.contents,
+        spec.startLine,
+        spec.endLine,
+        2,
+        spec.focusLine ?? spec.startLine,
+      );
+      return {
+        id: spec.id,
+        type: 'file' as const,
+        file: {
+          name: spec.path,
+          contents: slice.contents,
+          cacheKey: `${spec.id}:${slice.sliceStart}-${slice.sliceEnd}`,
+        },
+        annotations:
+          slice.focusOffset != null
+            ? [{ lineNumber: slice.focusOffset }]
+            : undefined,
+      };
+    });
+  }, []);
+
+  const options = useMemo(
+    () => ({
+      theme: {
+        dark: resolvePierreSyntaxThemeName('dark'),
+        light: resolvePierreSyntaxThemeName('light'),
+      } as const,
+      stickyHeaders: true,
+      layout: { paddingTop: 12, paddingBottom: 24, gap: 16 },
+      ...(mode === 'light' || mode === 'dark' ? { themeType: mode as 'light' | 'dark' } : {}),
+    }),
+    [mode],
+  );
+
+  return (
+    <div
+      style={{
+        display: 'flex',
+        height: '100vh',
+        background: theme.colors.background,
+        color: theme.colors.text,
+        fontFamily: theme.fonts.sans,
+      }}
+    >
+      <aside
+        style={{
+          width: 260,
+          flexShrink: 0,
+          borderRight: `1px solid ${theme.colors.border ?? '#333'}`,
+          padding: 16,
+          display: 'flex',
+          flexDirection: 'column',
+          gap: 8,
+        }}
+      >
+        <div style={{ fontSize: 13, fontWeight: 600, marginBottom: 4 }}>
+          Throughline steps
+        </div>
+        <div style={{ fontSize: 12, color: theme.colors.textSecondary, marginBottom: 8 }}>
+          Pierre <code>CodeView</code> — one scroll, snippets from different files.
+        </div>
+        {SNIPPETS.map((spec) => (
+          <button
+            key={spec.id}
+            type="button"
+            onClick={() => viewRef.current?.scrollTo({ type: 'item', id: spec.id })}
+            style={{
+              textAlign: 'left',
+              padding: '8px 10px',
+              borderRadius: 6,
+              border: `1px solid ${theme.colors.border ?? '#333'}`,
+              background: theme.colors.surface ?? 'transparent',
+              color: theme.colors.text,
+              cursor: 'pointer',
+              fontSize: 12,
+            }}
+          >
+            {spec.label}
+            <div
+              style={{
+                marginTop: 4,
+                fontFamily: theme.fonts.monospace,
+                fontSize: 10,
+                color: theme.colors.textSecondary,
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+              }}
+            >
+              {spec.path.split('/').pop()}:{spec.startLine}
+            </div>
+          </button>
+        ))}
+      </aside>
+      <div style={{ flex: 1, minWidth: 0, minHeight: 0 }}>
+        <CodeView
+          ref={viewRef}
+          items={items}
+          options={options}
+          style={{ height: '100%', overflow: 'auto' }}
+        />
+      </div>
+    </div>
+  );
+}
+
+export const MultiFileSnippets: Story = {
+  name: 'Multi-file snippets',
+  render: () => <MultiFileSnippetsDemo />,
+};

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/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: 'createSubsystemGraph',
+    construct: 'function',
+    file: 'packages/trail-viewer/src/bun/subsystem-graph-store.ts',
+    purl,
+    symbol: 'createSubsystemGraph',
+    purpose: 'language-only helper — no framework / stereotype',
+    process: 'trail-viewer/host',
+    layer: 1,
+  },
+  {
+    id: 'http-entry',
+    name: 'handleSubsystemGraphRequest',
+    construct: 'function',
+    file: 'packages/trail-viewer/src/bun/http-server.ts',
+    purl,
+    symbol: 'handleSubsystemGraphRequest',
+    purpose: 'HTTP bridge entry — topology role, still no React stereotype',
+    role: 'entry',
+    process: 'trail-viewer/host',
+    layer: 1,
+  },
+  {
+    id: 'sessions-view',
+    name: 'AgentSessionsOverviewView',
+    construct: 'function',
+    file: 'packages/trail-viewer/src/mainview/views/AgentSessions.tsx',
+    purl,
+    symbol: 'AgentSessionsOverviewView',
+    purpose: 'React view — construct stays function; stereotype labels it',
+    framework: 'react',
+    stereotype: 'component',
+    process: 'trail-viewer/renderer',
+    layer: 2,
+  },
+  {
+    id: 'analysis-view',
+    name: 'AnalysisView',
+    construct: 'function',
+    file: 'packages/trail-viewer/src/mainview/views/AnalysisView.tsx',
+    purl,
+    symbol: 'AnalysisView',
+    purpose: 'another React component alongside a hook',
+    framework: 'react',
+    stereotype: 'component',
+    process: 'trail-viewer/renderer',
+    layer: 2,
+  },
+  {
+    id: 'drawings-host',
+    name: 'useDrawingsHost',
+    construct: 'function',
+    file: 'packages/trail-viewer/src/mainview/hooks/useDrawingsHost.ts',
+    purl,
+    symbol: 'useDrawingsHost',
+    purpose: 'React hook — same construct, different stereotype',
+    framework: 'react',
+    stereotype: 'hook',
+    process: 'trail-viewer/renderer',
+    layer: 2,
+  },
+  {
+    id: 'graph-doc-type',
+    name: 'SubsystemGraphDocument',
+    construct: 'type_alias',
+    file: 'packages/core/src/types/subsystem-graph.ts',
+    purl,
+    symbol: 'SubsystemGraphDocument',
+    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: 'SubsystemGraphsController',
+    construct: 'class',
+    file: 'src/graphs/graphs.controller.ts',
+    purl: 'pkg:github/acme/api',
+    symbol: 'SubsystemGraphsController',
+    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/Spotlights.stories.tsx

@@ -38,8 +38,8 @@ type Story = StoryObj<typeof meta>;
 // Targeted side-by-side spotlights: each construct's DATA next to its
 // RENDERING — no full graph shell. Three spotlights: nodes, mechanisms
 // (edges), and anatomy (declaration panels). The mapping these make visible:
-// construct:→ node anatomy + color, role → topology glyph, detail → drill-down,
-// mechanism → edge color/style.
+// construct:→ node anatomy + color, framework+stereotype → badge label,
+// role → topology glyph, detail → drill-down, mechanism → edge color/style.
 // ---------------------------------------------------------------------------
 
 /** Data snippet card — the raw object on the left of every row. */
@@ -209,6 +209,35 @@ const nodeSpotlights: Array<{ label: string; component: SubsystemComponent; note
       symbol: 'createSubsystemGraph',
     },
   },
+  {
+    label: 'framework: react · stereotype: component — still construct: function',
+    note: 'badge reads "react · component"; name wears <> ; color stays function',
+    component: {
+      id: 'analysis-view',
+      name: 'AnalysisView',
+      construct: 'function',
+      file: 'packages/trail-viewer/src/mainview/views/AnalysisView.tsx',
+      purl: corePurl,
+      symbol: 'AnalysisView',
+      framework: 'react',
+      stereotype: 'component',
+      purpose: 'renders a saved analysis as concept cards',
+    },
+  },
+  {
+    label: 'framework: react · stereotype: hook',
+    note: 'same construct, different stereotype — badge "react · hook", keeps ()',
+    component: {
+      id: 'drawings-host',
+      name: 'useDrawingsHost',
+      construct: 'function',
+      file: 'packages/trail-viewer/src/mainview/hooks/useDrawingsHost.ts',
+      purl: corePurl,
+      symbol: 'useDrawingsHost',
+      framework: 'react',
+      stereotype: 'hook',
+    },
+  },
   {
     label: 'role: entry on construct: function — boundary element',
     note: 'orange overrides construct:color; anatomy inherited from the function',
@@ -331,7 +360,13 @@ function NodeSpotlightsDemo() {
         {nodeSpotlights.map(({ component }) => {
           const on = activeIds.has(component.id);
           const color = constructColors[component.construct];
-          const chip = component.role != null ? `${component.construct} · ${component.role}` : component.construct;
+          const chip = component.stereotype
+            ? component.framework
+              ? `${component.framework} · ${component.stereotype}`
+              : component.stereotype
+            : component.role != null
+              ? `${component.construct} · ${component.role}`
+              : component.construct;
           return (
             <button
               key={component.id}

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"