@principal-ai/subsystems-react 0.17.0

package/src/stories/OTEL/ValidationEventsCanvas.stories.tsx

@@ -0,0 +1,209 @@
+import React, { useState, useEffect } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import '@xyflow/react/dist/style.css';
+import { GraphRenderer } from '../../components/GraphRenderer';
+import type { ExtendedCanvas } from '@principal-ai/subsystems-core';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+
+// Import the CLI events canvas
+import validationEventsCanvasUrl from '../../../../../.principal-views/principal-view-cli.events.canvas?url';
+
+// Helper to load canvas from URL
+async function loadCanvas(url: string): Promise<ExtendedCanvas> {
+  const response = await fetch(url);
+  return await response.json();
+}
+
+// Wrapper component that loads canvas data
+function CanvasLoader({ url, children }: { url: string; children: (canvas: ExtendedCanvas) => React.ReactNode }) {
+  const [canvas, setCanvas] = useState<ExtendedCanvas | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    loadCanvas(url)
+      .then(setCanvas)
+      .catch((err) => setError(err.message));
+  }, [url]);
+
+  if (error) {
+    return <div style={{ padding: 20, color: 'red' }}>Error loading canvas: {error}</div>;
+  }
+
+  if (!canvas) {
+    return <div style={{ padding: 20 }}>Loading canvas...</div>;
+  }
+
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      {children(canvas)}
+    </div>
+  );
+}
+
+const meta = {
+  title: 'OTEL/ValidationEventsCanvas',
+  component: GraphRenderer,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <div style={{ width: '100vw', height: '100vh' }}>
+          <Story />
+        </div>
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof GraphRenderer>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Validation Event Namespace Canvas
+ *
+ * File: .principal-views/validation/validation.events.canvas
+ * Type: event-namespace nodes
+ * Purpose: Shows the vocabulary of events emitted during validation workflows
+ */
+export const EventNamespaceVocabulary: Story = {
+  render: () => (
+    <CanvasLoader url={validationEventsCanvasUrl}>
+      {(canvas) => <GraphRenderer canvas={canvas} showBackground={false} editable={true} />}
+    </CanvasLoader>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Renders the **validation.events.canvas** file - an event namespace vocabulary canvas.
+
+## Event Namespace Canvas Concept
+
+Unlike span canvases (which show user workflows) or OTEL event canvases (which show individual events),
+this canvas shows the **vocabulary of event namespaces** and their adjacency relationships.
+
+### Structure
+
+**Nodes = Event Namespaces**
+- \`analysis\` - Analysis pipeline lifecycle events
+- \`validation\` - Validation lifecycle events (started, complete, error)
+- \`file\` - File parsing events
+- \`type\` - Type detection events
+- etc.
+
+Each namespace node documents all events within that namespace with their attributes.
+
+**Edges = Adjacency**
+- Edges represent when events from one namespace appear adjacent to events from another namespace in workflow scenarios
+- Example: \`analysis → filetree\` because \`analysis.started → filetree.built\` in scenarios
+- Example: \`file → validation\` because \`file.parsed → validation.error\` in scenarios
+
+### Purpose
+
+This canvas serves as:
+1. **Event vocabulary documentation** - What events can be emitted
+2. **Flow visualization** - How events from different namespaces connect
+3. **Implementation guide** - What attributes each event requires
+4. **Validation source** - Canvas edges must match actual workflow scenario adjacencies
+
+### Conventions
+
+As defined in \`.principal-views/architecture.events.md\`:
+- Events follow \`{namespace}.{action}.{detail}\` naming
+- Edges represent direct adjacency only (not transitive)
+- Canvas is validated against workflow scenario files
+- Namespaces group code-level implementation events (vs user-level workflow spans)
+
+**Use this to:**
+- Preview event namespace canvas rendering
+- Understand event flow architecture
+- Document which events your code emits
+- Validate event relationships match actual code
+        `,
+      },
+    },
+  },
+};
+
+/**
+ * Event Namespace Canvas with Annotations
+ *
+ * Shows the canvas with additional context about what each namespace contains
+ */
+export const WithNamespaceDetails: Story = {
+  render: () => (
+    <CanvasLoader url={validationEventsCanvasUrl}>
+      {(canvas) => (
+        <div style={{ display: 'flex', height: '100vh' }}>
+          <div style={{ flex: 1 }}>
+            <GraphRenderer canvas={canvas} showBackground={false} editable={true} />
+          </div>
+          <div style={{
+            width: '350px',
+            padding: '20px',
+            backgroundColor: '#f5f5f5',
+            overflowY: 'auto',
+            fontFamily: 'system-ui, -apple-system, sans-serif'
+          }}>
+            <h2 style={{ marginTop: 0, fontSize: '18px' }}>Event Namespaces</h2>
+            <p style={{ fontSize: '14px', color: '#666' }}>
+              Each node represents a namespace grouping related events.
+            </p>
+
+            <div style={{ marginTop: '20px' }}>
+              <h3 style={{ fontSize: '14px', marginBottom: '8px' }}>Discovery Phase</h3>
+              <ul style={{ fontSize: '13px', lineHeight: '1.6', paddingLeft: '20px' }}>
+                <li><strong>analysis</strong> - Pipeline start</li>
+                <li><strong>filetree</strong> - Repository scanning</li>
+                <li><strong>packages</strong> - Package discovery</li>
+                <li><strong>canvases</strong> - Canvas file discovery</li>
+                <li><strong>executions</strong> - Execution file discovery</li>
+                <li><strong>library</strong> - Component library loading</li>
+                <li><strong>discovery</strong> - Phase completion</li>
+              </ul>
+            </div>
+
+            <div style={{ marginTop: '20px' }}>
+              <h3 style={{ fontSize: '14px', marginBottom: '8px' }}>Validation Phase</h3>
+              <ul style={{ fontSize: '13px', lineHeight: '1.6', paddingLeft: '20px' }}>
+                <li><strong>validation</strong> - Lifecycle (started, complete, error)</li>
+                <li><strong>file</strong> - Parsing operations</li>
+                <li><strong>type</strong> - Type detection</li>
+                <li><strong>canvas</strong> - Canvas validation</li>
+                <li><strong>workflow</strong> - Workflow validation</li>
+                <li><strong>execution</strong> - Execution validation</li>
+                <li><strong>rules</strong> - Lint rule execution</li>
+                <li><strong>results</strong> - Result aggregation</li>
+              </ul>
+            </div>
+
+            <div style={{ marginTop: '20px', padding: '12px', backgroundColor: '#fff3cd', borderRadius: '4px' }}>
+              <h4 style={{ fontSize: '13px', marginTop: 0 }}>Adjacency Edges</h4>
+              <p style={{ fontSize: '12px', margin: 0, color: '#856404' }}>
+                Edges show when events from one namespace appear next to events from another namespace
+                in workflow scenarios. These are validated against actual execution traces.
+              </p>
+            </div>
+          </div>
+        </div>
+      )}
+    </CanvasLoader>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Same canvas with a side panel showing namespace details and explanations.
+
+This view helps:
+- Understand what each namespace contains
+- See the phase groupings (discovery vs validation)
+- Learn the event namespace canvas concept
+        `,
+      },
+    },
+  },
+};

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

@@ -0,0 +1,219 @@
+/**
+ * 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/subsystems-react/src/subsystem/ComponentDeclaration.tsx',
+    contents: componentDeclarationSource,
+    startLine: 252,
+    endLine: 270,
+    focusLine: 252,
+    label: '1 · ComponentDeclaration export',
+  },
+  {
+    id: 'step-2',
+    path: 'packages/subsystems-react/src/graphify/resolve.ts',
+    contents: resolveSource,
+    startLine: 1,
+    endLine: 40,
+    focusLine: 1,
+    label: '2 · graphify resolve',
+  },
+  {
+    id: 'step-3',
+    path: 'packages/subsystems-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 [activeId, setActiveId] = React.useState<string | null>(SNIPPETS[0]?.id ?? null);
+
+  const sliced = useMemo(() => {
+    return SNIPPETS.map((spec) => {
+      const slice = sliceSnippetWindow(
+        spec.contents,
+        spec.startLine,
+        spec.endLine,
+        2,
+        spec.focusLine ?? spec.startLine,
+      );
+      return { spec, slice };
+    });
+  }, []);
+
+  const items = useMemo((): CodeViewItem[] => {
+    return sliced.map(({ spec, slice }) => ({
+      id: spec.id,
+      type: 'file' as const,
+      file: {
+        name: spec.path,
+        contents: slice.contents,
+        cacheKey: `${spec.id}:${slice.sliceStart}-${slice.sliceEnd}`,
+      },
+    }));
+  }, [sliced]);
+
+  const selectedLines = useMemo(() => {
+    if (activeId == null) return null;
+    const hit = sliced.find((s) => s.spec.id === activeId);
+    if (hit?.slice.focusOffset == null) return null;
+    return {
+      id: activeId,
+      range: { start: hit.slice.focusOffset, end: hit.slice.focusOffset },
+    };
+  }, [activeId, sliced]);
+
+  const focusStep = (id: string) => {
+    setActiveId(id);
+    const hit = sliced.find((s) => s.spec.id === id);
+    const line = hit?.slice.focusOffset;
+    if (line == null) return;
+    viewRef.current?.scrollTo({ type: 'line', id, lineNumber: line, align: 'center' });
+  };
+
+  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 }}>
+          Click a step to scroll + highlight its site line.
+        </div>
+        {SNIPPETS.map((spec) => (
+          <button
+            key={spec.id}
+            type="button"
+            onClick={() => focusStep(spec.id)}
+            style={{
+              textAlign: 'left',
+              padding: '8px 10px',
+              borderRadius: 6,
+              border: `1px solid ${theme.colors.border ?? '#333'}`,
+              background:
+                activeId === spec.id
+                  ? (theme.colors.surfaceHover ?? theme.colors.surface ?? 'transparent')
+                  : (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}
+          selectedLines={selectedLines}
+          style={{ height: '100%', overflow: 'auto' }}
+        />
+      </div>
+    </div>
+  );
+}
+
+export const MultiFileSnippets: Story = {
+  name: 'Multi-file snippets',
+  render: () => <MultiFileSnippetsDemo />,
+};