@principal-ai/subsystems-react 0.51.0 → 0.51.2

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.
@@ -26,9 +26,9 @@ import {
 import { useTheme } from '@principal-ade/industry-theme';
 import { computeElkLayout } from '../utils/elkLayout';
 import { MECHANISM_COLOR } from './model';
-import { C4NodeCard, NODE_H, NODE_W, nodeStyle } from './C4NodeCard';
+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;
@@ -130,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 % 5) * (NODE_W + 44), y: Math.floor(i / 5) * (NODE_H + 44) },
-      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,
@@ -147,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,
@@ -159,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 },
@@ -241,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(
     () =>
@@ -254,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 }}>
@@ -369,22 +383,23 @@ function Inner({ model, title, onSelectNode }: C4GraphProps) {
               }}
             >
               <span style={{ color: nodeStyle(selected, theme).color }}>
-                {selected.decoration?.state ?? 'unconfirmed'} · {selected.decoration?.type ?? 'no type'}
+                {selected.state}
+                {selected.containerKind ? ` · ${selected.containerKind}` : ` · ${selected.kind}`}
               </span>
-              {selected.decoration?.technology ? (
-                <span>technology: {selected.decoration.technology}</span>
+              {selected.technology ? (
+                <span>technology: {selected.technology}</span>
               ) : (
                 <span style={{ color: theme.colors.warning ?? '#e8a33a' }}>technology: not stated</span>
               )}
-              {selected.decoration?.description ? (
-                <span style={{ whiteSpace: 'normal', lineHeight: 1.4 }}>{selected.decoration.description}</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.sourceKeys && selected.sourceKeys.length > 1 && (
+              {selected.derivedFrom && selected.derivedFrom.length > 1 && (
                 <span style={{ whiteSpace: 'normal', lineHeight: 1.4 }}>
-                  merged from: {selected.sourceKeys.join(', ')}
+                  consolidated from: {selected.derivedFrom.join(', ')}
                 </span>
               )}
             </div>

package/src/subsystem/C4NodeCard.test.ts

@@ -1,6 +1,18 @@
 import { describe, expect, test } from 'bun:test';
-import { nodeStyle, nodeSubtitle, nodeTag, nodeMissing, NODE_W, NODE_H } from './C4NodeCard';
-import type { C4Node, C4ElementType, C4AssociationState } from './toC4';
+import {
+  nodeStyle,
+  nodeSubtitle,
+  nodeTag,
+  nodeKindIcon,
+  nodeTypeLabel,
+  nodeShape,
+  nodeMissing,
+  NODE_W,
+  NODE_H,
+  nodeSize,
+  COMPONENT_SIZE,
+} from './C4NodeCard';
+import type { C4Node } from './c4';
 
 const theme = {
   colors: {
@@ -12,86 +24,172 @@ const theme = {
   },
 } 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: [], isStore: false, ...over };
+  return { id: 'n', kind: 'container', label: 'n', members: [], constructs: [], state: 'proposed', ...over };
 }
 
-function decorated(state: C4AssociationState, extra: Record<string, unknown> = {}): C4Node {
-  return node({ decoration: { id: 'container:x', state, ...extra } as C4Node['decoration'] });
-}
-
-describe('nodeStyle', () => {
+describe('nodeStyle — one axis per channel', () => {
   test('selected overrides everything', () => {
-    expect(nodeStyle(decorated('accepted'), theme, true).width).toBe(3);
-    expect(nodeStyle(node(), theme, true).color).toBe('#4ec9b0');
+    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(decorated('accepted'), theme);
+    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(decorated('proposed'), theme);
+    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(decorated('rejected'), theme);
+    const s = nodeStyle(node({ state: 'rejected' }), theme);
     expect(s.dash).toBe('dotted');
     expect(s.color).toBe('#555');
   });
 
-  test('no association is muted, so confirmed boxes read stronger', () => {
-    expect(nodeStyle(node(), theme).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('an external and an actor are distinguished without an association', () => {
-    expect(nodeStyle(node({ kind: 'external' }), theme).color).toBe('#e8a33a');
-    expect(nodeStyle(node({ kind: 'actor' }), theme).color).toBe('#e3b341');
+  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('confirmation state wins over kind', () => {
-    const s = nodeStyle(decorated('accepted'), theme);
-    expect(s.color).toBe('#4ec9b0');
+  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(decorated('accepted'), bare)).not.toThrow();
-    expect(nodeStyle(decorated('accepted'), bare).dash).toBe('solid');
+    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('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);
+  });
+
+  test('the icon does not depend on confirmation state', () => {
+    expect(nodeKindIcon(node({ state: 'proposed' }))).toBe(
+      nodeKindIcon(node({ state: 'accepted' })),
+    );
+  });
+});
+
+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');
+  });
+
+  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();
+    }
   });
 });
 
-describe('nodeTag', () => {
-  test('names the confirmation state ahead of the C4 kind', () => {
-    expect(nodeTag(decorated('accepted'))).toBe('confirmed');
-    expect(nodeTag(decorated('proposed'))).toBe('proposed');
-    expect(nodeTag(decorated('rejected'))).toBe('rejected');
+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('falls back to the kind when there is no association', () => {
-    expect(nodeTag(node())).toBe('container');
-    expect(nodeTag(node({ kind: 'external' }))).toBe('external');
-    expect(nodeTag(node({ kind: 'actor' }))).toBe('actor');
+  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 type and technology once confirmed', () => {
+  test('shows the technology, and does not repeat the container kind', () => {
     const s = nodeSubtitle(
-      decorated('accepted', { type: 'application', technology: 'Bun + Electrobun' }),
+      node({ containerKind: 'application', technology: 'Bun + Electrobun' }),
     );
-    expect(s).toBe('application · Bun + Electrobun');
+    expect(s).toBe('Bun + Electrobun');
+    expect(s).not.toContain('application');
   });
 
-  test('omits technology when it was never stated', () => {
-    expect(nodeSubtitle(decorated('accepted', { type: 'data-store' }))).toBe('data-store');
+  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 for a raw container', () => {
+  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');
@@ -119,38 +217,85 @@ describe('nodeSubtitle', () => {
     );
     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 bare container reports both notation gaps', () => {
-    expect(nodeMissing(node())).toEqual(['technology', 'description']);
+  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(decorated('accepted', { technology: 'React' }))).toEqual(['description']);
+    expect(nodeMissing(node({ technology: 'React', description: undefined }))).toEqual([
+      'description',
+    ]);
   });
 
   test('a fully stated container reports nothing', () => {
     expect(
-      nodeMissing(decorated('accepted', { technology: 'React', description: 'Renders graphs.' })),
+      nodeMissing(node({ technology: 'React', description: 'Renders graphs.', state: 'accepted' })),
     ).toEqual([]);
   });
 
   test('the requirement is on containers only', () => {
-    expect(nodeMissing(node({ kind: 'external' }))).toEqual([]);
-    expect(nodeMissing(node({ kind: 'actor' }))).toEqual([]);
-    expect(nodeMissing(node({ kind: 'component' }))).toEqual([]);
+    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).toBeGreaterThan(0);
-    expect(NODE_H).toBeGreaterThan(0);
+    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, type+technology, notation
+    // 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;
@@ -177,20 +322,17 @@ describe('card metrics', () => {
   });
 });
 
-/** Compile-time guard: every declared element type is reachable from a card. */
-const ALL_TYPES: C4ElementType[] = [
-  'application',
-  'data-store',
-  'queue',
-  'library',
-  'software-system',
-  'person',
-];
-
-describe('element types', () => {
-  test('each one renders as a subtitle without special-casing', () => {
-    for (const type of ALL_TYPES) {
-      expect(nodeSubtitle(decorated('accepted', { type }))).toBe(type);
+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('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']).not.toContain('library');
+  });
 });