@principal-ai/subsystems-react 0.37.5 → 0.37.6

package/src/subsystem/C4Graph.tsx

@@ -0,0 +1,465 @@
+/**
+ * C4Graph — a C4 projection of a (composed) subsystem model on React Flow.
+ *
+ * Prototype test case: feed it a `C4Model` from `toC4()` and it draws the
+ * system as a compound frame, its containers (or components) as boxes, and
+ * externals/actors outside the system. Static `relations` render as solid
+ * edges; `walkthrough` hops render as dashed flow edges. Click a box to list
+ * the source components it rolled up.
+ *
+ * Same interaction language as the other graphs: React Flow + ELK + the shared
+ * `GRAPH_NAV_PROPS` chrome. Deliberately small — no measurement passes, no
+ * drawers, no walkthrough playback.
+ */
+
+import { useEffect, useMemo, useState } from 'react';
+import {
+  Edge,
+  Handle,
+  MarkerType,
+  Node,
+  NodeProps,
+  Position,
+  ReactFlow,
+  ReactFlowProvider,
+  useReactFlow,
+} from '@xyflow/react';
+import { useTheme } from '@principal-ade/industry-theme';
+import { computeElkLayout } from '../utils/elkLayout';
+import { describeConstructBreakdown, MECHANISM_COLOR } from './model';
+import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
+import type { C4Model, C4Node } from './toC4';
+
+export interface C4GraphProps {
+  model: C4Model;
+  title?: string;
+  onSelectNode?: (id: string | null) => void;
+}
+
+const NODE_W = 230;
+const NODE_H = 80;
+
+function baseName(path: string): string {
+  const parts = path.split('/').filter(Boolean);
+  return parts[parts.length - 1] ?? path;
+}
+
+function edgeColor(mechanism: string | undefined, fallback: string): string {
+  if (!mechanism) return fallback;
+  return (MECHANISM_COLOR as Record<string, string>)[mechanism] ?? fallback;
+}
+
+function C4NodeView(props: NodeProps<Node<{ node: C4Node; selected: boolean }>>) {
+  const { theme } = useTheme();
+  const { node, selected } = props.data;
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+
+  const kindColor =
+    node.kind === 'external'
+      ? (theme.colors.warning ?? theme.colors.accent ?? theme.colors.info)
+      : node.kind === 'actor'
+        ? (theme.colors.accent ?? theme.colors.info)
+        : (theme.colors.border ?? '#333');
+
+  const tag = node.kind === 'container' ? 'container' : node.kind === 'external' ? 'external system' : node.kind === 'actor' ? 'actor' : 'component';
+
+  const subtitle =
+    node.kind === 'component'
+      ? `${node.component?.construct ?? 'code'}${node.component?.file ? ` · ${baseName(node.component.file)}` : ''}`
+      : `${describeConstructBreakdown(node.constructs)}${
+          node.members.length > 0 ? ` · ${node.members.length} component${node.members.length === 1 ? '' : 's'}` : ''
+        }`;
+
+  return (
+    <div
+      style={{
+        width: NODE_W,
+        height: NODE_H,
+        boxSizing: 'border-box',
+        display: 'flex',
+        flexDirection: 'column',
+        justifyContent: 'center',
+        gap: 2,
+        padding: '8px 12px',
+        borderRadius: node.kind === 'actor' ? 20 : 8,
+        background: theme.colors.backgroundSecondary ?? theme.colors.background,
+        border: `2px ${node.kind === 'component' ? 'solid' : node.kind === 'container' ? 'solid' : 'dashed'} ${
+          selected ? theme.colors.primary : kindColor
+        }`,
+        boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
+        cursor: 'pointer',
+        fontFamily: theme.fonts.body,
+      }}
+    >
+      <span
+        style={{
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[0],
+          letterSpacing: 0.5,
+          textTransform: 'uppercase',
+          color: kindColor,
+          whiteSpace: 'nowrap',
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+        }}
+      >
+        {tag}
+      </span>
+      <span
+        style={{
+          fontWeight: 600,
+          fontSize: theme.fontSizes[2],
+          color: theme.colors.text,
+          whiteSpace: 'nowrap',
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+        }}
+        title={node.label}
+      >
+        {node.label}
+      </span>
+      <span
+        style={{
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[0],
+          color: muted,
+          whiteSpace: 'nowrap',
+          overflow: 'hidden',
+          textOverflow: 'ellipsis',
+        }}
+        title={node.members.join(', ')}
+      >
+        {subtitle}
+      </span>
+      <Handle type="target" position={Position.Left} style={{ opacity: 0 }} />
+      <Handle type="source" position={Position.Right} style={{ opacity: 0 }} />
+    </div>
+  );
+}
+
+function C4GroupView(props: NodeProps<Node<{ label: string; kind: 'system' | 'container'; color: string }>>) {
+  const { theme } = useTheme();
+  const color = props.data.color;
+  return (
+    <div
+      style={{
+        width: '100%',
+        height: '100%',
+        boxSizing: 'border-box',
+        borderRadius: 12,
+        border: `2px dashed ${color}`,
+        background: 'transparent',
+        pointerEvents: 'none',
+      }}
+    >
+      <span
+        style={{
+          position: 'absolute',
+          top: 0,
+          transform: 'translateY(-50%)',
+          left: 12,
+          zIndex: 1,
+          fontFamily: theme.fonts.monospace,
+          fontSize: theme.fontSizes[2],
+          fontWeight: 600,
+          letterSpacing: 0.5,
+          textTransform: 'uppercase',
+          lineHeight: '18px',
+          color,
+          background: theme.colors.background,
+          boxShadow: `0 0 0 1.5px ${theme.colors.background}`,
+          border: `2px solid ${color}`,
+          borderRadius: 4,
+          padding: '4px 10px',
+          boxSizing: 'border-box',
+          whiteSpace: 'nowrap',
+        }}
+      >
+        {props.data.label}
+      </span>
+    </div>
+  );
+}
+
+const nodeTypes = {
+  'c4-node': C4NodeView,
+  'c4-group': C4GroupView,
+};
+
+function Inner({ model, title, onSelectNode }: C4GraphProps) {
+  const { theme } = useTheme();
+  const { fitView } = useReactFlow();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const [nodes, setNodes] = useState<Node[]>([]);
+  const [rfEdges, setRfEdges] = useState<Edge[]>([]);
+  const [ready, setReady] = useState(false);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+
+  const layoutKey = useMemo(
+    () =>
+      [
+        ...model.nodes.map((n) => `${n.id}\0${n.parentId ?? ''}\0${n.label}`).sort(),
+        ...model.groups.map((g) => `${g.id}\0${g.parentId ?? ''}\0${g.memberIds.length}`).sort(),
+        ...model.edges.map((e) => `${e.id}\0${e.count}`).sort(),
+      ].join('\n'),
+    [model],
+  );
+
+  useEffect(() => {
+    let alive = true;
+    setReady(false);
+    setSelectedId(null);
+
+    const rfNodes: Node[] = model.nodes.map((n, i) => ({
+      id: n.id,
+      type: 'c4-node',
+      position: { x: (i % 4) * (NODE_W + 60), y: Math.floor(i / 4) * (NODE_H + 40) },
+      width: NODE_W,
+      height: NODE_H,
+      ...(n.parentId ? { parentId: n.parentId } : {}),
+      data: { node: n, selected: false },
+    }));
+
+    const groups = model.groups.map((g) => ({
+      id: g.id,
+      memberIds: g.memberIds,
+      ...(g.parentId ? { parentId: g.parentId } : {}),
+    }));
+
+    const rfEdges: Edge[] = model.edges.map((e) => {
+      const flow = e.kind === 'flow';
+      const color = flow ? edgeColor(e.mechanisms[0], muted) : (theme.colors.border ?? '#666');
+      return {
+        id: e.id,
+        source: e.source,
+        target: e.target,
+        label: e.label,
+        labelShowBg: false,
+        labelStyle: { fill: muted, fontSize: theme.fontSizes[0], fontFamily: theme.fonts.monospace },
+        style: {
+          stroke: color,
+          strokeWidth: 1 + Math.min(e.count, 6) * 0.4,
+          ...(flow ? { strokeDasharray: '6 4' } : {}),
+        },
+        markerEnd: { type: MarkerType.ArrowClosed, color, width: 18, height: 18 },
+        data: { edge: e },
+      };
+    });
+
+    void computeElkLayout(rfNodes, rfEdges, {
+      direction: 'RIGHT',
+      preserveNodePositions: false,
+      groups,
+      keepSingletonGroups: true,
+    })
+      .then((result) => {
+        if (!alive) return;
+        const positioned = new Map(result.nodes.map((n) => [n.id, n]));
+        const builtGroups = new Set(result.groupBounds.keys());
+        const groupById = new Map(model.groups.map((g) => [g.id, g]));
+
+        const depthOf = (id: string): number => {
+          let d = 0;
+          let g = groupById.get(id);
+          while (g?.parentId) {
+            d += 1;
+            g = groupById.get(g.parentId);
+          }
+          return d;
+        };
+
+        const shells: Node[] = [...result.groupBounds.entries()]
+          .sort((a, b) => depthOf(a[0]) - depthOf(b[0]))
+          .map(([id, b]) => {
+            const def = groupById.get(id);
+            const parentId = def?.parentId && builtGroups.has(def.parentId) ? def.parentId : undefined;
+            return {
+              id,
+              type: 'c4-group',
+              position: { x: b.x, y: b.y },
+              width: Math.max(200, b.width),
+              height: Math.max(120, b.height),
+              draggable: false,
+              selectable: false,
+              ...(parentId ? { parentId } : {}),
+              data: {
+                label: def?.label ?? id,
+                kind: def?.kind ?? 'container',
+                color: def?.kind === 'system' ? (theme.colors.text ?? '#888') : (theme.colors.accent ?? theme.colors.info),
+              },
+            };
+          });
+
+        const leaves = rfNodes.map((n) => {
+          const p = positioned.get(n.id);
+          const node = p ? { ...n, position: { x: p.position.x, y: p.position.y } } : n;
+          const parentId = (node as { parentId?: string }).parentId;
+          if (parentId && !builtGroups.has(parentId)) {
+            const { parentId: _drop, ...rest } = node as { parentId?: string } & Node;
+            return rest as Node;
+          }
+          return node;
+        });
+
+        setNodes([...shells, ...leaves]);
+        setRfEdges(rfEdges);
+        setReady(true);
+        requestAnimationFrame(() => fitView({ padding: 0.15 }));
+      })
+      .catch((err) => {
+        if (!alive) return;
+        console.warn('[c4-graph] ELK layout failed, using grid:', err);
+        setNodes(rfNodes);
+        setRfEdges(rfEdges);
+        setReady(true);
+        requestAnimationFrame(() => fitView({ padding: 0.15 }));
+      });
+
+    return () => {
+      alive = false;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [layoutKey]);
+
+  const selected = useMemo(() => model.nodes.find((n) => n.id === selectedId) ?? null, [model, selectedId]);
+
+  const displayNodes = useMemo(
+    () =>
+      nodes.map((n) =>
+        n.type === 'c4-node'
+          ? { ...n, data: { ...n.data, selected: n.id === selectedId } }
+          : n,
+      ),
+    [nodes, selectedId],
+  );
+
+  const runtime = model.nodes.filter((n) => n.kind === 'container' || n.kind === 'component').length;
+  const outside = model.nodes.filter((n) => n.kind === 'external' || n.kind === 'actor').length;
+
+  return (
+    <div style={{ position: 'relative', width: '100%', height: '100%', background: theme.colors.background }}>
+      <GraphLayerStyle />
+      <ReactFlow
+        nodes={displayNodes}
+        edges={rfEdges}
+        nodeTypes={nodeTypes}
+        className={GRAPH_CANVAS_CLASS}
+        {...GRAPH_NAV_PROPS}
+        onNodeClick={(_e, node) => {
+          if (node.type !== 'c4-node') return;
+          const next = node.id === selectedId ? null : node.id;
+          setSelectedId(next);
+          onSelectNode?.(next);
+        }}
+        onPaneClick={() => {
+          setSelectedId(null);
+          onSelectNode?.(null);
+        }}
+        proOptions={{ hideAttribution: true }}
+      >
+        <GraphChrome />
+      </ReactFlow>
+      {!ready && (
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            background: theme.colors.background,
+            color: muted,
+            fontFamily: theme.fonts.monospace,
+            fontSize: theme.fontSizes[0],
+          }}
+        >
+          Laying out C4 view…
+        </div>
+      )}
+      {title && (
+        <div
+          style={{
+            position: 'absolute',
+            top: 12,
+            left: 12,
+            fontSize: theme.fontSizes[2],
+            fontWeight: 600,
+            color: theme.colors.text,
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            border: `1px solid ${theme.colors.border ?? '#333'}`,
+            borderRadius: 6,
+            padding: '4px 10px',
+          }}
+        >
+          {title}
+          <span style={{ fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[0], color: muted, marginLeft: 8 }}>
+            {model.view} view · {runtime} {model.view === 'container' ? 'containers' : 'components'} · {outside} outside
+          </span>
+        </div>
+      )}
+      {selected && (
+        <div
+          style={{
+            position: 'absolute',
+            top: 12,
+            right: 12,
+            width: 280,
+            maxHeight: 'calc(100% - 24px)',
+            overflowY: 'auto',
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            border: `1px solid ${theme.colors.border ?? '#333'}`,
+            borderRadius: 8,
+            padding: '10px 12px',
+          }}
+        >
+          <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+            <span style={{ fontWeight: 600, color: theme.colors.text, flex: 1, minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+              {selected.label}
+            </span>
+            <button
+              type="button"
+              onClick={() => {
+                setSelectedId(null);
+                onSelectNode?.(null);
+              }}
+              aria-label="Clear selection"
+              style={{ border: 'none', background: 'transparent', color: muted, cursor: 'pointer', fontSize: theme.fontSizes[2], lineHeight: 1 }}
+            >
+              ×
+            </button>
+          </div>
+          <div style={{ fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[0], color: muted, margin: '4px 0 8px' }}>
+            {selected.kind} · {selected.members.length} component{selected.members.length === 1 ? '' : 's'}
+            {selected.models && selected.models.length > 0 ? ` · ${selected.models.length} model${selected.models.length === 1 ? '' : 's'}` : ''}
+          </div>
+          <div style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+            {selected.members.map((alias) => (
+              <span
+                key={alias}
+                title={alias}
+                style={{
+                  fontFamily: theme.fonts.monospace,
+                  fontSize: theme.fontSizes[0],
+                  color: theme.colors.text,
+                  overflow: 'hidden',
+                  textOverflow: 'ellipsis',
+                  whiteSpace: 'nowrap',
+                }}
+              >
+                {alias}
+              </span>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function C4Graph(props: C4GraphProps) {
+  return (
+    <ReactFlowProvider>
+      <Inner {...props} />
+    </ReactFlowProvider>
+  );
+}

package/src/subsystem/WalkthroughsPanel.test.tsx

@@ -0,0 +1,146 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { cleanup, fireEvent, render, waitFor } from '@testing-library/react/pure';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import {
+  STEP_COPY_FEEDBACK_MS,
+  WalkthroughsPanel,
+  type WalkthroughsPanelProps,
+} from './WalkthroughsPanel';
+import type { SubsystemWalkthrough } from './model';
+import { buildStepBrief } from './walkthroughBrief';
+
+// Bun's happy-dom test environment needs `@happy-dom/global-registrator`, which
+// isn't installed here, so wire the DOM primitives React DOM + Testing Library
+// need before any test renders.
+const dom = new Window();
+const globals = globalThis as unknown as Record<string, unknown>;
+globals.window = dom;
+globals.document = dom.document;
+globals.navigator = dom.navigator;
+globals.HTMLElement = dom.HTMLElement;
+globals.Node = dom.Node;
+globals.Element = dom.Element;
+globals.Event = dom.Event;
+globals.MouseEvent = dom.MouseEvent;
+globals.FocusEvent = dom.FocusEvent;
+globals.KeyboardEvent = dom.KeyboardEvent;
+globals.getComputedStyle = dom.getComputedStyle.bind(dom);
+globals.requestAnimationFrame = dom.requestAnimationFrame.bind(dom);
+globals.cancelAnimationFrame = dom.cancelAnimationFrame.bind(dom);
+globals.localStorage = dom.localStorage;
+globals.sessionStorage = dom.sessionStorage;
+globals.matchMedia = dom.matchMedia.bind(dom);
+
+
+const walkthroughs: SubsystemWalkthrough[] = [
+  {
+    id: 'auth-flow',
+    title: 'Auth flow',
+    steps: [
+      {
+        from: 'ui',
+        to: 'api',
+        mechanism: 'calls',
+        file: 'src/ui/login.tsx',
+        line: 42,
+        purl: 'pkg:github/acme/app',
+        symbol: 'Login.submit',
+      },
+    ],
+  },
+];
+
+const writeText = mock(() => Promise.resolve());
+
+beforeEach(() => {
+  writeText.mockClear();
+  Object.defineProperty(navigator, 'clipboard', {
+    value: { writeText },
+    configurable: true,
+  });
+});
+
+afterEach(cleanup);
+
+function renderPanel(overrides: Partial<WalkthroughsPanelProps> = {}) {
+  const props: WalkthroughsPanelProps = {
+    walkthroughs,
+    expandedWalkthroughs: new Set(['auth-flow']),
+    focusedWalkthroughId: null,
+    focusedStepIndex: null,
+    hoveredWalkthroughStep: null,
+    onToggleCollapsed: () => {},
+    onFocusFlow: () => {},
+    onClearFocus: () => {},
+    onFocusStep: () => {},
+    onHoverStep: () => {},
+    onHoverFlow: () => {},
+    onLeaveStep: () => {},
+    ...overrides,
+  };
+  return render(
+    <ThemeProvider theme={defaultEditorTheme}>
+      <WalkthroughsPanel {...props} />
+    </ThemeProvider>,
+  );
+}
+
+const COPY_LABEL = 'Copy step 1 of Auth flow for an agent';
+
+describe('WalkthroughsPanel step copy', () => {
+  test('copy icon is hidden until the step row is hovered', () => {
+    const { getByText, queryByLabelText } = renderPanel();
+    expect(queryByLabelText(COPY_LABEL)).toBeNull();
+    const row = getByText('Login.submit').closest('button')!;
+    fireEvent.mouseEnter(row);
+    expect(queryByLabelText(COPY_LABEL)).not.toBeNull();
+  });
+
+  test('copy icon is revealed on keyboard focus', () => {
+    const { getByText, queryByLabelText } = renderPanel();
+    const row = getByText('Login.submit').closest('button')!;
+    fireEvent.focus(row);
+    expect(queryByLabelText(COPY_LABEL)).not.toBeNull();
+  });
+
+  test('clicking copies the step brief and flashes a copied state', async () => {
+    const { getByText, getByLabelText } = renderPanel();
+    fireEvent.mouseEnter(getByText('Login.submit').closest('button')!);
+    const copy = getByLabelText(COPY_LABEL);
+    fireEvent.mouseDown(copy);
+    fireEvent.click(copy);
+    await waitFor(() => expect(writeText).toHaveBeenCalledTimes(1));
+    expect(writeText).toHaveBeenCalledWith(buildStepBrief(walkthroughs[0]!, 0));
+    expect(copy.getAttribute('title')).toBe('Copied');
+  });
+
+  test('hovering the row still focuses the step on click', () => {
+    const onFocusStep = mock(() => {});
+    const { getByText } = renderPanel({ onFocusStep });
+    const row = getByText('Login.submit').closest('button')!;
+    fireEvent.mouseEnter(row);
+    fireEvent.click(row);
+    expect(onFocusStep).toHaveBeenCalledWith(walkthroughs[0]!, 0);
+  });
+
+  test('the copied checkmark clears after the feedback window', async () => {
+    const { getByText, getByLabelText } = renderPanel();
+    fireEvent.mouseEnter(getByText('Login.submit').closest('button')!);
+    const copy = getByLabelText(COPY_LABEL);
+    fireEvent.click(copy);
+    await waitFor(() => expect(copy.getAttribute('title')).toBe('Copied'));
+    await new Promise((r) => setTimeout(r, STEP_COPY_FEEDBACK_MS + 20));
+    await waitFor(() => expect(copy.getAttribute('title')).not.toBe('Copied'));
+  });
+
+  test('a failed copy shows no copied state', async () => {
+    writeText.mockImplementationOnce(() => Promise.reject(new Error('denied')));
+    const { getByText, getByLabelText } = renderPanel();
+    fireEvent.mouseEnter(getByText('Login.submit').closest('button')!);
+    const copy = getByLabelText(COPY_LABEL);
+    fireEvent.click(copy);
+    await new Promise((r) => setTimeout(r, 10));
+    expect(copy.getAttribute('title')).toBe('Copy this step for an agent');
+  });
+});