@principal-ai/subsystems-react 0.51.2 → 0.51.3

package/src/subsystem/C4Graph.tsx

@@ -1,7 +1,7 @@
 /**
  * C4Graph — a C4 projection of a (composed) subsystem model on React Flow.
  *
- * Feed it a `C4Model` from `buildC4Model()` and it draws the
+ * Feed it an authored `C4Model` 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.
@@ -22,9 +22,11 @@ import {
   ReactFlow,
   ReactFlowProvider,
   useReactFlow,
+  useViewport,
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { computeElkLayout } from '../utils/elkLayout';
+import { EDGE_LABEL_FONT_SIZE, EDGE_LABEL_HEIGHT, EDGE_LABEL_WIDTH } from '../utils/edgeLabel';
 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';
@@ -34,6 +36,17 @@ export interface C4GraphProps {
   model: C4Model;
   title?: string;
   onSelectNode?: (id: string | null) => void;
+  /**
+   * Extra width / height reserved around each card when laying out, in flow px.
+   * The visible gap between boxes is `2 × gutter` (ELK's `nodeNode` spacing,
+   * plus the frame padding where a frame adds one).
+   *
+   * Above the default 28 the `needs …` gap row was removed, so cards are
+   * shorter and packing them tighter than the spacing they were tuned at makes
+   * them collide. Raise it for a more airy graph.
+   * @default 28
+   */
+  gutter?: number;
 }
 
 function edgeColor(mechanism: string | undefined, fallback: string): string {
@@ -57,6 +70,98 @@ function C4NodeView(props: NodeProps<Node<{ node: C4Node; selected: boolean }>>)
   );
 }
 
+/**
+ * Edge-label overlay.
+ *
+ * Drawn as an HTML layer above the canvas rather than React Flow's built-in
+ * edge label, so a C4 line's label reads like the subsystem graph's: an opaque
+ * rounded chip in the mechanism colour, monospace text, scaling with zoom.
+ *
+ * Positions come from ELK's computed label anchors (`edgeLabelPositions`, flow
+ * coords); the current viewport converts them to screen space.
+ */
+function C4EdgeLabels({
+  positions,
+  edges,
+  muted,
+}: {
+  positions: Map<string, { x: number; y: number }>;
+  edges: C4Model['edges'];
+  muted: string;
+}) {
+  const { theme } = useTheme();
+  const viewport = useViewport();
+  const surface = theme.colors.backgroundSecondary ?? theme.colors.background;
+  const byId = useMemo(() => new Map(edges.map((e) => [e.id, e])), [edges]);
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        inset: 0,
+        overflow: 'hidden',
+        pointerEvents: 'none',
+        zIndex: 5,
+      }}
+    >
+      {[...positions].map(([id, p]) => {
+        const edge = byId.get(id);
+        if (!edge) return null;
+        const color = edgeColor(edge.mechanisms[0], muted);
+        // C4 asks the line to name the interaction's protocol; fall back to the
+        // label when a caller supplied none.
+        const text = edge.protocol ?? edge.label;
+        return (
+          <div
+            key={id}
+            style={{
+              position: 'absolute',
+              left: p.x * viewport.zoom + viewport.x,
+              top: p.y * viewport.zoom + viewport.y,
+              transform: `translate(-50%, -50%) scale(${viewport.zoom})`,
+              transformOrigin: 'center center',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: EDGE_LABEL_WIDTH,
+              height: EDGE_LABEL_HEIGHT,
+              boxSizing: 'border-box',
+              padding: '7px 8px',
+            }}
+          >
+            <span
+              aria-hidden
+              style={{
+                position: 'absolute',
+                inset: 0,
+                borderRadius: 4,
+                border: `0.5px solid ${color}`,
+                background: surface,
+              }}
+            />
+            <span
+              style={{
+                position: 'relative',
+                maxWidth: '100%',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+                fontSize: EDGE_LABEL_FONT_SIZE,
+                lineHeight: 1,
+                fontFamily: theme.fonts.monospace,
+                fontWeight: 500,
+                color,
+              }}
+            >
+              {text}
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
 function C4GroupView(props: NodeProps<Node<{ label: string; kind: 'system' | 'container'; color: string }>>) {
   const { theme } = useTheme();
   const color = props.data.color;
@@ -106,7 +211,7 @@ const nodeTypes = {
   'c4-group': C4GroupView,
 };
 
-function Inner({ model, title, onSelectNode }: C4GraphProps) {
+function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
@@ -114,6 +219,9 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
   const [rfEdges, setRfEdges] = useState<Edge[]>([]);
   const [ready, setReady] = useState(false);
   const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [labelPositions, setLabelPositions] = useState<Map<string, { x: number; y: number }>>(
+    () => new Map(),
+  );
 
   const layoutKey = useMemo(
     () =>
@@ -130,10 +238,11 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
     setReady(false);
     setSelectedId(null);
 
-    // 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.
+    // Per-kind size, so a square component is laid out as a square. Feeding the
+    // container dimensions for everything would make ELK reserve 250x150 of
+    // space around a 140x140 box and space the component view twice as far
+    // apart as it needs. `gutter` is added here, not passed as node spacing, so
+    // a frame's padding clears the card inside it by the same margin.
     const rfNodes: Node[] = model.nodes.map((n, i) => {
       const size = nodeSize(n);
       return {
@@ -142,8 +251,8 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
         // 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,
+        width: size.width + gutter,
+        height: size.height + gutter,
         ...(n.parentId ? { parentId: n.parentId } : {}),
         data: { node: n, selected: false },
       };
@@ -162,16 +271,17 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
         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 },
+        // The reserved label box and the chip must agree on size, so ELK is
+        // given the same text the chip draws (protocol first, then label). The
+        // chip itself is the C4EdgeLabels overlay, not this field.
+        label: e.protocol ?? e.label,
         style: {
           stroke: color,
           strokeWidth: 1 + Math.min(e.count, 6) * 0.4,
           strokeDasharray: '6 4',
         },
         markerEnd: { type: MarkerType.ArrowClosed, color, width: 18, height: 18 },
-        data: { edge: e },
+        data: { edge: e, color },
       };
     });
 
@@ -180,10 +290,12 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
       preserveNodePositions: false,
       groups,
       keepSingletonGroups: true,
+      edgeLabels: { enabled: true, placement: 'CENTER' },
     })
       .then((result) => {
         if (!alive) return;
         const positioned = new Map(result.nodes.map((n) => [n.id, n]));
+        setLabelPositions(result.edgeLabelPositions ?? new Map());
         const builtGroups = new Set(result.groupBounds.keys());
         const groupById = new Map(model.groups.map((g) => [g.id, g]));
 
@@ -293,6 +405,9 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
       >
         <GraphChrome />
       </ReactFlow>
+      {ready && labelPositions.size > 0 && (
+        <C4EdgeLabels positions={labelPositions} edges={model.edges} muted={muted} />
+      )}
       {!ready && (
         <div
           style={{

package/src/subsystem/C4NodeCard.test.ts

@@ -4,7 +4,7 @@ import {
   nodeSubtitle,
   nodeTag,
   nodeKindIcon,
-  nodeTypeLabel,
+  nodeTopLabel,
   nodeShape,
   nodeMissing,
   NODE_W,
@@ -113,14 +113,19 @@ describe('nodeTag — what the box IS', () => {
   });
 });
 
-describe('nodeKindIcon — the kind as a glyph, not a word', () => {
-  test('every kind has its own icon', () => {
-    const icons = (['container', 'component', 'external-system', 'person'] as const).map((kind) =>
-      nodeKindIcon(node({ kind })),
-    );
-    for (const icon of icons) expect(icon).toBeDefined();
-    // Different kinds must not share a glyph, or the icon says nothing.
-    expect(new Set(icons).size).toBe(4);
+describe('nodeKindIcon — a container’s sort, not its C4 kind', () => {
+  test('application and data-store get different icons', () => {
+    const app = nodeKindIcon(node({ containerKind: 'application' }));
+    const store = nodeKindIcon(node({ containerKind: 'data-store' }));
+    expect(app).toBeDefined();
+    expect(store).toBeDefined();
+    expect(app).not.toBe(store);
+  });
+
+  test('only containers get an icon — the shape carries the rest', () => {
+    for (const kind of ['component', 'external-system', 'person'] as const) {
+      expect(nodeKindIcon(node({ kind }))).toBeUndefined();
+    }
   });
 
   test('the icon does not depend on confirmation state', () => {
@@ -130,16 +135,22 @@ describe('nodeKindIcon — the kind as a glyph, not a word', () => {
   });
 });
 
-describe('nodeTypeLabel — the one word in the icon row', () => {
-  test('a container names its kind', () => {
-    expect(nodeTypeLabel(node({ containerKind: 'application' }))).toBe('application');
-    expect(nodeTypeLabel(node({ containerKind: 'data-store' }))).toBe('data-store');
+describe('nodeTopLabel — the technology, or the kind when none is stated', () => {
+  test('a stated technology is the label', () => {
+    expect(
+      nodeTopLabel(node({ containerKind: 'application', technology: 'Bun + Electrobun' })),
+    ).toBe('Bun + Electrobun');
+    expect(nodeTopLabel(node({ kind: 'component', technology: 'React + ELK' }))).toBe('React + ELK');
   });
 
-  test('the other three kinds have no subtype, so no word', () => {
-    for (const kind of ['component', 'external-system', 'person'] as const) {
-      expect(nodeTypeLabel(node({ kind }))).toBeUndefined();
-    }
+  test('a container with no technology falls back to its kind', () => {
+    expect(nodeTopLabel(node({ containerKind: 'data-store', technology: '' }))).toBe('data-store');
+  });
+
+  test('the other kinds fall back to their C4 kind', () => {
+    expect(nodeTopLabel(node({ kind: 'component' }))).toBe('component');
+    expect(nodeTopLabel(node({ kind: 'external-system' }))).toBe('external-system');
+    expect(nodeTopLabel(node({ kind: 'person' }))).toBe('person');
   });
 });
 
@@ -174,52 +185,28 @@ describe('nodeShape — kind without relying on colour or dash', () => {
 });
 
 describe('nodeSubtitle', () => {
-  test('shows the technology, and does not repeat the container kind', () => {
-    const s = nodeSubtitle(
-      node({ containerKind: 'application', technology: 'Bun + Electrobun' }),
-    );
-    expect(s).toBe('Bun + Electrobun');
-    expect(s).not.toContain('application');
-  });
-
-  test('a container with no technology falls back to its construct breakdown', () => {
-    const s = nodeSubtitle(
-      node({ containerKind: 'data-store', technology: '', constructs: ['store'], members: ['a'] }),
-    );
-    expect(s).toBe('1 store · 1 component');
-  });
-
-  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');
+  test('is the element description when it has one', () => {
+    expect(
+      nodeSubtitle(node({ technology: 'Bun', description: 'Runs the audit pipeline.' })),
+    ).toBe('Runs the audit pipeline.');
+  });
+
+  test('is empty when nothing is stated — there is no fallback', () => {
+    const withTech = node({ technology: 'Bun + Electrobun' });
+    const withMembers = node({ constructs: ['function', 'store'], members: ['a', 'b'] });
+    const component = node({
+      kind: 'component',
+      component: {
+        alias: 'a',
+        name: 'buildGroups',
+        construct: 'function',
+        file: 'src/subsystem/model.ts',
+        purl: 'pkg:x#src/subsystem/model.ts',
+      },
+    });
+    for (const n of [withTech, withMembers, component]) {
+      expect(nodeSubtitle(n)).toBe('');
+    }
   });
 });
 
@@ -285,8 +272,8 @@ describe('nodeSize — a component is a proper square', () => {
 
 describe('card metrics', () => {
   test('exposes the size the graph lays out against', () => {
-    expect(NODE_W).toBe(210);
-    expect(NODE_H).toBe(138);
+    expect(NODE_W).toBe(250);
+    expect(NODE_H).toBe(150);
   });
 
   test('COMPONENT_SIZE is a square, not just a smaller rectangle', () => {
@@ -295,23 +282,23 @@ describe('card metrics', () => {
   });
 
   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.
+    // The card carries three fields (technology row, label, description). A
+    // 3:1 strip wraps the last two hard; 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.
+  test('is tall enough for three lines of content', () => {
+    // technology row + 2-line label + description, plus padding.
     expect(NODE_H).toBeGreaterThanOrEqual(130);
   });
 
-  test('leaves breathing room around four lines of text', () => {
+  test('leaves breathing room around three 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
+    // balance: technology row + 2-line label slot + description + padding.
+    const contentBudget = 16 + 40 + 16 + 20; // lines + 10px padding ×2
     expect(NODE_H - contentBudget).toBeGreaterThanOrEqual(12);
   });
 
@@ -323,13 +310,20 @@ describe('card metrics', () => {
 });
 
 describe('container kinds', () => {
-  test('every container kind renders as the icon-row label without special-casing', () => {
-    const kinds = ['application', 'data-store'] as const;
-    for (const containerKind of kinds) {
-      expect(nodeTypeLabel(node({ containerKind }))).toBe(containerKind);
+  test('each container kind has an icon and a fallback label', () => {
+    for (const containerKind of ['application', 'data-store'] as const) {
+      expect(nodeKindIcon(node({ containerKind }))).toBeDefined();
+      // No technology stated, so the label falls back to the kind.
+      expect(nodeTopLabel(node({ containerKind, technology: '' }))).toBe(containerKind);
     }
   });
 
+  test('application and data-store do not share an icon', () => {
+    expect(nodeKindIcon(node({ containerKind: 'application' }))).not.toBe(
+      nodeKindIcon(node({ containerKind: 'data-store' })),
+    );
+  });
+
   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.