@principal-ai/principal-view-react 0.16.61 → 0.16.63

package/src/pierre/PierreThroughlineCodeView.tsx

@@ -0,0 +1,210 @@
+/**
+ * PierreThroughlineCodeView — multi-file step snippets via `@pierre/diffs` CodeView.
+ *
+ * Renders one sliced window per throughline step in a single virtualized
+ * scroll; when `stepIndex` changes, scrolls that step into view.
+ */
+
+import { useEffect, useMemo, useRef, useState, type ReactElement } from 'react';
+import {
+  CodeView,
+  type CodeViewHandle,
+  type CodeViewItem,
+  type CodeViewReactOptions,
+} from '@pierre/diffs/react';
+import { useTheme } from '@principal-ade/industry-theme';
+import type { SubsystemThroughline } from '../subsystem/model';
+import { buildPierreOptions, PIERRE_FILE_STYLE } from './pierreBackground';
+import { resolvePierreSyntaxThemeName } from './pierreSyntaxTheme';
+import { sliceSnippetWindow } from './sliceSnippet';
+
+export interface PierreThroughlineCodeViewProps {
+  throughline: SubsystemThroughline;
+  /** Focused step; `null` shows all snippets without scrolling to a step. */
+  stepIndex: number | null;
+  readFile: (path: string) => Promise<string>;
+  /** Context lines above/below each step site; defaults to 8. */
+  contextLines?: number;
+  /** Override Pierre's container background. */
+  background?: string;
+}
+
+type FileLoadState =
+  | { status: 'loading' }
+  | { status: 'error'; message: string }
+  | { status: 'ready'; byPath: Map<string, string> };
+
+function stepItemId(throughlineId: string, index: number): string {
+  return `${throughlineId}:${index}`;
+}
+
+export function PierreThroughlineCodeView({
+  throughline,
+  stepIndex,
+  readFile,
+  contextLines = 8,
+  background,
+}: PierreThroughlineCodeViewProps) {
+  const { theme, mode } = useTheme();
+  const viewRef = useRef<CodeViewHandle<undefined>>(null);
+  const [load, setLoad] = useState<FileLoadState>({ status: 'loading' });
+
+  const pathsKey = useMemo(() => {
+    const paths = [...new Set(throughline.steps.map((s) => s.file))];
+    paths.sort();
+    return paths.join('\0');
+  }, [throughline.steps]);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoad({ status: 'loading' });
+    const paths = [...new Set(throughline.steps.map((s) => s.file))];
+    void Promise.all(
+      paths.map(async (path) => {
+        const contents = await readFile(path);
+        return [path, contents] as const;
+      }),
+    )
+      .then((entries) => {
+        if (cancelled) return;
+        setLoad({ status: 'ready', byPath: new Map(entries) });
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setLoad({
+          status: 'error',
+          message: err instanceof Error ? err.message : 'Failed to read files',
+        });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [throughline.id, pathsKey, readFile]);
+
+  const items = useMemo((): CodeViewItem[] => {
+    if (load.status !== 'ready') return [];
+    return throughline.steps.map((step, index) => {
+      const contents = load.byPath.get(step.file) ?? '';
+      const slice = sliceSnippetWindow(
+        contents,
+        step.line,
+        step.line,
+        contextLines,
+        step.line,
+      );
+      return {
+        id: stepItemId(throughline.id, index),
+        type: 'file' as const,
+        version: 1,
+        file: {
+          // Real path → Shiki language detection from extension.
+          name: step.file,
+          contents: slice.contents,
+          cacheKey: `${throughline.id}:${index}:${step.file}:${step.line}:${slice.sliceStart}-${slice.sliceEnd}`,
+        },
+        annotations:
+          slice.focusOffset != null
+            ? [{ lineNumber: slice.focusOffset }]
+            : undefined,
+      };
+    });
+  }, [load, throughline.id, throughline.steps, contextLines]);
+
+  const renderHeaderPrefix = useMemo(() => {
+    return (item: CodeViewItem) => {
+      const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
+      const step = throughline.steps[index];
+      if (!step) return null;
+      const label =
+        step.symbol != null && step.symbol.length > 0
+          ? step.symbol
+          : `step ${index + 1}`;
+      return (
+        <span
+          style={{
+            fontFamily: theme.fonts.monospace,
+            fontSize: theme.fontSizes[0],
+            color: theme.colors.textSecondary,
+            marginRight: 8,
+          }}
+        >
+          {index + 1}. {label}
+        </span>
+      );
+    };
+  }, [throughline.steps, theme]);
+
+  const renderHeaderMetadata = useMemo(() => {
+    return (item: CodeViewItem) => {
+      const index = Number.parseInt(item.id.split(':').pop() ?? '', 10);
+      const step = throughline.steps[index];
+      if (!step) return null;
+      return (
+        <span
+          style={{
+            fontFamily: theme.fonts.monospace,
+            fontSize: theme.fontSizes[0],
+            color: theme.colors.textSecondary,
+            marginLeft: 8,
+          }}
+        >
+          L{step.line}
+        </span>
+      );
+    };
+  }, [throughline.steps, theme]);
+
+  const options = useMemo((): CodeViewReactOptions => {
+    return {
+      theme: {
+        dark: resolvePierreSyntaxThemeName('dark'),
+        light: resolvePierreSyntaxThemeName('light'),
+      },
+      stickyHeaders: true,
+      disableFileHeader: false,
+      layout: { paddingTop: 8, paddingBottom: 16, gap: 12 },
+      ...(background ? buildPierreOptions(background) : {}),
+      ...(mode === 'light' || mode === 'dark' ? { themeType: mode } : {}),
+    };
+  }, [background, mode]);
+
+  useEffect(() => {
+    if (load.status !== 'ready' || stepIndex == null) return;
+    if (stepIndex < 0 || stepIndex >= throughline.steps.length) return;
+    // Defer until CodeView has laid out items.
+    const id = stepItemId(throughline.id, stepIndex);
+    const t = window.setTimeout(() => {
+      viewRef.current?.scrollTo({ type: 'item', id, align: 'start' });
+    }, 50);
+    return () => window.clearTimeout(t);
+  }, [load.status, stepIndex, throughline.id, throughline.steps.length, items.length]);
+
+  if (load.status === 'error') {
+    return (
+      <div style={{ padding: 16, color: theme.colors.error ?? '#e5534b' }}>
+        {load.message}
+      </div>
+    );
+  }
+  if (load.status === 'loading' || items.length === 0) {
+    return (
+      <div style={{ padding: 16, color: theme.colors.textSecondary }}>
+        Loading…
+      </div>
+    );
+  }
+
+  // Pierre's CodeView prop / item unions blow past TS's complexity limit.
+  const CodeViewLoose = CodeView as unknown as (props: Record<string, unknown>) => ReactElement;
+
+  return (
+    <CodeViewLoose
+      ref={viewRef}
+      items={items}
+      options={options}
+      renderHeaderPrefix={renderHeaderPrefix}
+      renderHeaderMetadata={renderHeaderMetadata}
+      style={{ ...PIERRE_FILE_STYLE, height: '100%', overflow: 'auto' }}
+    />
+  );
+}

package/src/pierre/index.ts

@@ -2,6 +2,8 @@ export { PierreFileView } from './PierreFileView';
 export type { PierreFileViewProps } from './PierreFileView';
 export { PierreSnippetView } from './PierreSnippetView';
 export type { PierreSnippetViewProps } from './PierreSnippetView';
+export { PierreThroughlineCodeView } from './PierreThroughlineCodeView';
+export type { PierreThroughlineCodeViewProps } from './PierreThroughlineCodeView';
 export { sliceSnippetWindow } from './sliceSnippet';
 export type { SnippetSlice } from './sliceSnippet';
 export {

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/subsystem/EdgeLegendModal.tsx

@@ -27,6 +27,9 @@ export const MECHANISM_DESCRIPTIONS: [SubsystemEdgeMechanism, string, boolean][]
   ['contains', 'structural: contains / encapsulates', true],
   ['feeds', 'data flow: output feeds into input', false],
   ['produces', 'data flow: produces / outputs', false],
+  ['writes', 'state access: mutates retained state', true],
+  ['reads', 'state access: reads retained state', true],
+  ['watches', 'observes retained state without owning it', false],
   ['registers-into', 'registration pattern', false],
 ];
 

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"