@principal-ai/subsystems-react 0.50.0 → 0.51.1

package/src/subsystem/C4Graph.tsx

@@ -1,7 +1,7 @@
 /**
  * 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
+ * Feed it a `C4Model` from `buildC4Model()` and it draws the
  * system as a compound frame, its containers (or components) as boxes, and
  * externals/actors outside the system. `trail` steps render as flow
  * edges. Click a box to list the source components it rolled up.
@@ -25,9 +25,10 @@ import {
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { computeElkLayout } from '../utils/elkLayout';
-import { describeConstructBreakdown, MECHANISM_COLOR } from './model';
+import { MECHANISM_COLOR } from './model';
+import { C4NodeCard, NODE_H, NODE_W, nodeSize, nodeStyle } from './C4NodeCard';
 import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
-import type { C4Model, C4Node } from './toC4';
+import type { C4Model, C4Node } from './c4';
 
 export interface C4GraphProps {
   model: C4Model;
@@ -35,104 +36,24 @@ export interface C4GraphProps {
   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>
+    <C4NodeCard
+      node={node}
+      selected={selected}
+      handles={
+        <>
+          <Handle type="target" position={Position.Left} style={{ opacity: 0 }} />
+          <Handle type="source" position={Position.Right} style={{ opacity: 0 }} />
+        </>
+      }
+    />
   );
 }
 
@@ -209,15 +130,24 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
     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 },
-    }));
+    // Per-node size, so a square component is laid out as a square. Feeding the
+    // container dimensions for everything would make ELK reserve 210x138 of
+    // space around a 132x132 box and space the component view twice as far
+    // apart as it needs.
+    const rfNodes: Node[] = model.nodes.map((n, i) => {
+      const size = nodeSize(n);
+      return {
+        id: n.id,
+        type: 'c4-node',
+        // Fallback grid pitch uses the container box — the largest, so the
+        // pre-layout positions never overlap. ELK replaces them on success.
+        position: { x: (i % 5) * (NODE_W + 44), y: Math.floor(i / 5) * (NODE_H + 44) },
+        width: size.width,
+        height: size.height,
+        ...(n.parentId ? { parentId: n.parentId } : {}),
+        data: { node: n, selected: false },
+      };
+    });
 
     const groups = model.groups.map((g) => ({
       id: g.id,
@@ -226,8 +156,8 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
     }));
 
     const rfEdges: Edge[] = model.edges.map((e) => {
-      const flow = e.kind === 'flow';
-      const color = flow ? edgeColor(e.mechanisms[0], muted) : (theme.colors.border ?? '#666');
+      // Every edge here came from a trail step, so the mechanism colours apply.
+      const color = edgeColor(e.mechanisms[0], muted);
       return {
         id: e.id,
         source: e.source,
@@ -238,7 +168,7 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
         style: {
           stroke: color,
           strokeWidth: 1 + Math.min(e.count, 6) * 0.4,
-          ...(flow ? { strokeDasharray: '6 4' } : {}),
+          strokeDasharray: '6 4',
         },
         markerEnd: { type: MarkerType.ArrowClosed, color, width: 18, height: 18 },
         data: { edge: e },
@@ -320,7 +250,10 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [layoutKey]);
 
-  const selected = useMemo(() => model.nodes.find((n) => n.id === selectedId) ?? null, [model, selectedId]);
+  const selected = useMemo(
+    () => model.nodes.find((n) => n.id === selectedId) ?? null,
+    [model, selectedId],
+  );
 
   const displayNodes = useMemo(
     () =>
@@ -333,7 +266,9 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
   );
 
   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;
+  const outside = model.nodes.filter(
+    (n) => n.kind === 'external-system' || n.kind === 'person',
+  ).length;
 
   return (
     <div style={{ position: 'relative', width: '100%', height: '100%', background: theme.colors.background }}>
@@ -431,6 +366,45 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
             {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>
+
+          {/* Confirmation state, with what is still missing. */}
+          {selected.kind === 'container' && (
+            <div
+              style={{
+                fontFamily: theme.fonts.monospace,
+                fontSize: theme.fontSizes[0],
+                color: muted,
+                borderTop: `1px solid ${theme.colors.border ?? '#333'}`,
+                paddingTop: 6,
+                marginBottom: 8,
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 3,
+              }}
+            >
+              <span style={{ color: nodeStyle(selected, theme).color }}>
+                {selected.state}
+                {selected.containerKind ? ` · ${selected.containerKind}` : ` · ${selected.kind}`}
+              </span>
+              {selected.technology ? (
+                <span>technology: {selected.technology}</span>
+              ) : (
+                <span style={{ color: theme.colors.warning ?? '#e8a33a' }}>technology: not stated</span>
+              )}
+              {selected.description ? (
+                <span style={{ whiteSpace: 'normal', lineHeight: 1.4 }}>{selected.description}</span>
+              ) : (
+                <span style={{ color: theme.colors.warning ?? '#e8a33a' }}>description: not stated</span>
+              )}
+              {/* A merge hides its inputs, so always show what it absorbed. */}
+              {selected.derivedFrom && selected.derivedFrom.length > 1 && (
+                <span style={{ whiteSpace: 'normal', lineHeight: 1.4 }}>
+                  consolidated from: {selected.derivedFrom.join(', ')}
+                </span>
+              )}
+            </div>
+          )}
+
           <div style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
             {selected.members.map((alias) => (
               <span

package/src/subsystem/C4NodeCard.test.ts

@@ -0,0 +1,301 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  nodeStyle,
+  nodeSubtitle,
+  nodeTag,
+  nodeShape,
+  nodeMissing,
+  NODE_W,
+  NODE_H,
+  nodeSize,
+  COMPONENT_SIZE,
+} from './C4NodeCard';
+import type { C4Node } from './c4';
+
+const theme = {
+  colors: {
+    border: '#555',
+    primary: '#4ec9b0',
+    warning: '#e8a33a',
+    accent: '#e3b341',
+    info: '#0ea5e9',
+  },
+} as Parameters<typeof nodeStyle>[1];
+
+/**
+ * A drawn node, flat. `state` is required on a real `C4Node` — every authored
+ * element carries a decision — so the card never has to cope with a box nobody
+ * proposed, and no test pretends otherwise.
+ */
+function node(over: Partial<C4Node> = {}): C4Node {
+  return { id: 'n', kind: 'container', label: 'n', members: [], constructs: [], state: 'proposed', ...over };
+}
+
+describe('nodeStyle — one axis per channel', () => {
+  test('selected overrides everything', () => {
+    expect(nodeStyle(node({ state: 'accepted' }), theme, true).width).toBe(3);
+    expect(nodeStyle(node({ state: 'accepted' }), theme, true).dash).toBe('solid');
+  });
+
+  test('accepted is solid and uses the primary colour', () => {
+    const s = nodeStyle(node({ state: 'accepted' }), theme);
+    expect(s.dash).toBe('solid');
+    expect(s.color).toBe('#4ec9b0');
+  });
+
+  test('proposed is dashed and uses the warning colour', () => {
+    const s = nodeStyle(node({ state: 'proposed' }), theme);
+    expect(s.dash).toBe('dashed');
+    expect(s.color).toBe('#e8a33a');
+  });
+
+  test('rejected is dotted and muted', () => {
+    const s = nodeStyle(node({ state: 'rejected' }), theme);
+    expect(s.dash).toBe('dotted');
+    expect(s.color).toBe('#555');
+  });
+
+  test('the dash belongs to state, never to kind', () => {
+    // This is the bug that made proposed boxes draw solid: the card rendered
+    // `shape.dash`, and shape answered to kind. Every kind at the same state
+    // must now draw the same dash.
+    for (const kind of ['container', 'component', 'external-system', 'person'] as const) {
+      expect(nodeStyle(node({ kind, state: 'proposed' }), theme).dash).toBe('dashed');
+      expect(nodeStyle(node({ kind, state: 'accepted' }), theme).dash).toBe('solid');
+    }
+  });
+
+  test('confirmation state wins over kind for colour', () => {
+    // Same state, four kinds: one colour. Kind is shape's job.
+    const colors = (['container', 'component', 'external-system', 'person'] as const).map(
+      (kind) => nodeStyle(node({ kind, state: 'accepted' }), theme).color,
+    );
+    expect(new Set(colors).size).toBe(1);
+  });
+
+  test('border weight carries the level, not the state', () => {
+    // Otherwise a component and a container differ only by hue, which is
+    // invisible in grayscale and to a colourblind reader.
+    expect(nodeStyle(node({ kind: 'component' }), theme).width).toBe(1);
+    expect(nodeStyle(node(), theme).width).toBe(2);
+  });
+
+  test('a component stays thinner once confirmed', () => {
+    expect(nodeStyle(node({ kind: 'component', state: 'accepted' }), theme).width).toBe(1);
+  });
+
+  test('falls back safely when the theme has no colour', () => {
+    const bare = { colors: {} } as Parameters<typeof nodeStyle>[1];
+    expect(() => nodeStyle(node({ state: 'accepted' }), bare)).not.toThrow();
+    expect(nodeStyle(node({ state: 'accepted' }), bare).dash).toBe('solid');
+  });
+});
+
+describe('nodeTag — what the box IS', () => {
+  test('names the C4 kind, never the confirmation state', () => {
+    expect(nodeTag(node({ state: 'accepted' }))).toBe('container');
+    expect(nodeTag(node({ state: 'proposed' }))).toBe('container');
+    expect(nodeTag(node({ state: 'rejected' }))).toBe('container');
+  });
+
+  test('keeps all four kinds distinct', () => {
+    expect(nodeTag(node({ kind: 'component' }))).toBe('component');
+    expect(nodeTag(node({ kind: 'external-system' }))).toBe('external-system');
+    expect(nodeTag(node({ kind: 'person' }))).toBe('person');
+  });
+
+  test('a confirmed container is still a container', () => {
+    // This is the regression that made the two levels unreadable: state used
+    // to overwrite the kind, so an accepted container stopped being one.
+    expect(nodeTag(node({ state: 'accepted' }))).not.toBe('confirmed');
+  });
+});
+
+describe('nodeShape — kind without relying on colour or dash', () => {
+  test('a container is a sharp rectangle', () => {
+    const s = nodeShape(node());
+    expect(s.kind).toBe('rect');
+    expect(s.radius).toBeLessThanOrEqual(4);
+  });
+
+  test('a component is a square', () => {
+    expect(nodeShape(node({ kind: 'component' })).kind).toBe('square');
+  });
+
+  test('an external system is a rounded rectangle', () => {
+    const s = nodeShape(node({ kind: 'external-system' }));
+    expect(s.kind).toBe('rect');
+    expect(s.radius).toBeGreaterThan(nodeShape(node()).radius);
+  });
+
+  test('a person is a pill', () => {
+    const s = nodeShape(node({ kind: 'person' }));
+    expect(s.kind).toBe('pill');
+    expect(s.radius).toBeGreaterThanOrEqual(NODE_H / 2);
+  });
+
+  test('shape does not depend on confirmation state', () => {
+    expect(nodeShape(node({ state: 'proposed' })).kind).toBe(
+      nodeShape(node({ state: 'accepted' })).kind,
+    );
+  });
+});
+
+describe('nodeSubtitle', () => {
+  test('shows the container kind and technology', () => {
+    expect(
+      nodeSubtitle(node({ containerKind: 'application', technology: 'Bun + Electrobun' })),
+    ).toBe('application · Bun + Electrobun');
+  });
+
+  test('shows a data store with no technology as just the kind', () => {
+    expect(nodeSubtitle(node({ containerKind: 'data-store', technology: '' }))).toBe('data-store');
+  });
+
+  test('falls back to the construct breakdown when neither is stated', () => {
+    const s = nodeSubtitle(node({ constructs: ['function', 'store'], members: ['a', 'b'] }));
+    expect(s).toContain('function');
+    expect(s).toContain('store');
+    expect(s).toContain('2 components');
+  });
+
+  test('singularises a single member', () => {
+    const s = nodeSubtitle(node({ constructs: ['function'], members: ['a'] }));
+    expect(s).toContain('1 component');
+    expect(s).not.toContain('1 components');
+  });
+
+  test('a component shows its construct and file basename', () => {
+    const s = nodeSubtitle(
+      node({
+        kind: 'component',
+        component: {
+          alias: 'a',
+          name: 'buildGroups',
+          construct: 'function',
+          file: 'src/subsystem/model.ts',
+          purl: 'pkg:x#src/subsystem/model.ts',
+        },
+      }),
+    );
+    expect(s).toBe('function · model.ts');
+  });
+
+  test('a component shows its technology when it has one', () => {
+    expect(nodeSubtitle(node({ kind: 'component', technology: 'React + ELK' }))).toBe('React + ELK');
+  });
+});
+
+describe('nodeMissing', () => {
+  test('a container with neither reports both notation gaps', () => {
+    expect(nodeMissing(node({ technology: '', description: undefined }))).toEqual([
+      'technology',
+      'description',
+    ]);
+  });
+
+  test('one supplied gap drops only that one', () => {
+    expect(nodeMissing(node({ technology: 'React', description: undefined }))).toEqual([
+      'description',
+    ]);
+  });
+
+  test('a fully stated container reports nothing', () => {
+    expect(
+      nodeMissing(node({ technology: 'React', description: 'Renders graphs.', state: 'accepted' })),
+    ).toEqual([]);
+  });
+
+  test('the requirement is on containers only', () => {
+    for (const kind of ['external-system', 'person', 'component'] as const) {
+      expect(nodeMissing(node({ kind, technology: '', description: undefined }))).toEqual([]);
+    }
+  });
+});
+
+describe('nodeSize — a component is a proper square', () => {
+  test('a component has equal width and height', () => {
+    const s = nodeSize(node({ kind: 'component' }));
+    expect(s.width).toBe(s.height);
+  });
+
+  test('a container is wider than it is tall', () => {
+    const s = nodeSize(node());
+    expect(s.width).toBeGreaterThan(s.height);
+  });
+
+  test('a component is smaller than its container', () => {
+    const c = nodeSize(node({ kind: 'component' }));
+    const k = nodeSize(node());
+    expect(c.width).toBeLessThan(k.width);
+    expect(c.height).toBeLessThan(k.height);
+  });
+
+  test('the square still fits its three lines of text', () => {
+    // tag + 2-line label slot + subtitle + 10px padding x2. Without this the
+    // square clips its own subtitle.
+    const s = nodeSize(node({ kind: 'component' }));
+    const content = 16 + 40 + 16 + 20;
+    expect(s.height).toBeGreaterThanOrEqual(content);
+  });
+
+  test('every kind but a component shares the container box', () => {
+    const c = nodeSize(node());
+    expect(nodeSize(node({ kind: 'external-system' }))).toEqual(c);
+    expect(nodeSize(node({ kind: 'person' }))).toEqual(c);
+  });
+});
+
+describe('card metrics', () => {
+  test('exposes the size the graph lays out against', () => {
+    expect(NODE_W).toBe(210);
+    expect(NODE_H).toBe(138);
+  });
+
+  test('COMPONENT_SIZE is a square, not just a smaller rectangle', () => {
+    expect(COMPONENT_SIZE).toBe(nodeSize(node({ kind: 'component' })).width);
+    expect(COMPONENT_SIZE).toBe(nodeSize(node({ kind: 'component' })).height);
+  });
+
+  test('is near-square, not a wide strip', () => {
+    // The card carries four fields (tag, label, kind+technology, notation
+    // gap). A 3:1 strip truncates the last two; this is the aspect ratio that
+    // lets each sit on its own line.
+    const ratio = NODE_W / NODE_H;
+    expect(ratio).toBeGreaterThan(1);
+    expect(ratio).toBeLessThan(1.8);
+  });
+
+  test('is tall enough for four lines of content', () => {
+    // tag + 2-line label + subtitle + gap marker, plus 8px padding top/bottom.
+    expect(NODE_H).toBeGreaterThanOrEqual(130);
+  });
+
+  test('leaves breathing room around four lines of text', () => {
+    // Top-aligned now, not centred, so this is about slack rather than
+    // balance: tag + 2-line label slot + subtitle + gap slot + padding.
+    const contentBudget = 16 + 40 + 16 + 18 + 20; // lines + 10px padding ×2
+    expect(NODE_H - contentBudget).toBeGreaterThanOrEqual(12);
+  });
+
+  test('fits the longest real container label on two lines', () => {
+    // "subsystems-studio/renderer" is the longest label the 40 stored models
+    // produce. It must be allowed to wrap rather than ellipsize.
+    expect(NODE_W).toBeGreaterThanOrEqual(200);
+  });
+});
+
+describe('container kinds', () => {
+  test('every container kind renders as a subtitle without special-casing', () => {
+    const kinds = ['application', 'data-store', 'queue'] as const;
+    for (const containerKind of kinds) {
+      expect(nodeSubtitle(node({ containerKind, technology: '' }))).toBe(containerKind);
+    }
+  });
+
+  test('a library is not one of them', () => {
+    // C4 says a module "typically" is not an element at all, so there is no
+    // kind to render. A library-shaped group is a review comment.
+    expect(['application', 'data-store', 'queue']).not.toContain('library');
+  });
+});