@principal-ai/subsystems-react 0.51.4 → 0.52.0

package/src/subsystem/C4Graph.tsx

@@ -27,39 +27,30 @@ import {
 } from '@xyflow/react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { computeElkLayout, pointAlongPath, pointsToSmoothPath } 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 { EDGE_LABEL_FONT_SIZE, EDGE_LABEL_HEIGHT, C4_LABEL_WIDTH, estimateEdgeLabelWidth } from '../utils/edgeLabel';
+import { protocolColor } from './c4';
+import { C4NodeCard, NODE_H, NODE_W, nodeSize } from './C4NodeCard';
 import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome, GraphLayerStyle } from './graphChrome';
-import type { C4Model, C4Node } from './c4';
+import type { C4Element, C4Model } from './c4';
 
 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.
+   * Breathing room around each card, in flow px, applied as ELK spacing (not by
+   * inflating the node box — that left the edge lines starting short of the
+   * card border). `nodeSpacing` is `2 × gutter`; `edgeNodeSpacing` is `gutter`.
    * @default 28
    */
   gutter?: number;
 }
 
-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 { node, selected } = props.data;
+function C4NodeView(props: NodeProps<Node<{ element: C4Element; selected: boolean }>>) {
+  const { element, selected } = props.data;
   return (
     <C4NodeCard
-      node={node}
+      node={element}
       selected={selected}
       handles={
         <>
@@ -82,11 +73,9 @@ function C4NodeView(props: NodeProps<Node<{ node: C4Node; selected: boolean }>>)
 function C4EdgeLabels({
   positions,
   edges,
-  muted,
 }: {
   positions: Map<string, { x: number; y: number }>;
   edges: C4Model['edges'];
-  muted: string;
 }) {
   const { theme } = useTheme();
   const viewport = useViewport();
@@ -106,7 +95,7 @@ function C4EdgeLabels({
       {[...positions].map(([id, p]) => {
         const edge = byId.get(id);
         if (!edge) return null;
-        const color = edgeColor(edge.mechanisms[0], muted);
+        const color = protocolColor(edge.protocol);
         const text = edge.protocol ?? edge.label;
         return (
           <div
@@ -120,7 +109,7 @@ function C4EdgeLabels({
               display: 'flex',
               alignItems: 'center',
               justifyContent: 'center',
-              width: EDGE_LABEL_WIDTH,
+              width: estimateEdgeLabelWidth(text),
               height: EDGE_LABEL_HEIGHT,
               boxSizing: 'border-box',
               padding: '7px 8px',
@@ -263,12 +252,17 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
     setReady(false);
     setSelectedId(null);
 
-    // 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) => {
+    // Draw only the elements for this view. A container diagram shows the
+    // runtime units (containers, externals, people); components belong to the
+    // component view. Components are still carried on the model (see the side
+    // panel), just not drawn here.
+    const inView = (n: C4Element): boolean =>
+      model.view === 'component' ? n.kind !== 'container' : n.kind !== 'component';
+
+    // Layout against the true card size, so ELK's ports sit on the card's
+    // border — an inflated box leaves the line starting short of the card edge.
+    // The `gutter` becomes ELK spacing instead (see `nodeSpacing` below).
+    const rfNodes: Node[] = model.nodes.filter(inView).map((n, i) => {
       const size = nodeSize(n);
       return {
         id: n.id,
@@ -276,10 +270,10 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: 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 + gutter,
-        height: size.height + gutter,
+        width: size.width,
+        height: size.height,
         ...(n.parentId ? { parentId: n.parentId } : {}),
-        data: { node: n, selected: false },
+        data: { element: n, selected: false },
       };
     });
 
@@ -289,9 +283,32 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
       ...(g.parentId ? { parentId: g.parentId } : {}),
     }));
 
+    // Band nodes so a flat layout still reads as C4 and frames can't interleave.
+    //
+    // Flat mode has no ELK parents, so without bands ELK mixes members of
+    // different frames across the whole graph — their synthesized bounding
+    // boxes then overlap. A partition per frame keeps each frame's members
+    // contiguous; people lead, externals trail.
+    //
+    // Order (ascending = earlier in the layout direction): people, then each
+    // frame in model order, then external systems.
+    const frameIds = model.groups.map((g) => g.id);
+    const frameIndex = new Map(frameIds.map((id, i) => [id, i]));
+    const partitionByNode = new Map<string, number>(
+      model.nodes.map((n) => {
+        if (n.kind === 'person') return [n.id, 0];
+        if (n.kind === 'external-system') return [n.id, frameIds.length + 1];
+        // A node inside a frame shares its frame's band; a frame-less node
+        // (a container at container view) gets its own by id order.
+        const band = n.parentId ? (frameIndex.get(n.parentId) ?? 0) : (frameIndex.get(n.id) ?? 0);
+        return [n.id, 1 + band];
+      }),
+    );
+
     const rfEdges: Edge[] = model.edges.map((e) => {
-      // Every edge here came from a trail step, so the mechanism colours apply.
-      const color = edgeColor(e.mechanisms[0], muted);
+      // Colour keys off the protocol, not the trail verb: on a container
+      // diagram the transport is what a reader distinguishes at a glance.
+      const color = protocolColor(e.protocol);
       return {
         id: e.id,
         type: 'c4-edge',
@@ -311,7 +328,22 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
       preserveNodePositions: false,
       groups,
       keepSingletonGroups: true,
-      edgeLabels: { enabled: true, placement: 'CENTER' },
+      edgeLabels: { enabled: true, placement: 'CENTER', width: C4_LABEL_WIDTH, measure: estimateEdgeLabelWidth },
+      // The gutter that used to inflate each node box is now real spacing, so
+      // the ports still sit on the card edge.
+      nodeSpacing: gutter * 2,
+      edgeNodeSpacing: gutter,
+      // Between-layer/between-partition gap. This is what keeps the external
+      // band clear of the system frame's padding — ELK gives partitions zero
+      // default separation. It stacks on top of ELK's reserved label layer, so
+      // it is kept modest.
+      interLayerSpacing: 40,
+      // Draw the system frame as a decoration around the boxes rather than an
+      // ELK parent. Nesting made in-frame edges inherit the frame's padding and
+      // spacing, so they ran longer than a root-level edge touching the same
+      // nodes; flattening gives every edge one spacing.
+      flatGroups: true,
+      partitionByNode,
     })
       .then((result) => {
         if (!alive) return;
@@ -341,15 +373,26 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
           return d;
         };
 
+        // Shell positions from flat synthesis are absolute. React Flow reads a
+        // child's `position` as relative to its parent, so a shell nested in
+        // another shell must be made relative to it.
+        const shellAbs = new Map(result.groupBounds);
+        const shellOrigin = (id: string | undefined): { x: number; y: number } => {
+          if (!id) return { x: 0, y: 0 };
+          const b = shellAbs.get(id);
+          return b ? { x: b.x, y: b.y } : { x: 0, y: 0 };
+        };
+
         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;
+            const origin = shellOrigin(parentId);
             return {
               id,
               type: 'c4-group',
-              position: { x: b.x, y: b.y },
+              position: { x: b.x - origin.x, y: b.y - origin.y },
               width: Math.max(200, b.width),
               height: Math.max(120, b.height),
               draggable: false,
@@ -365,13 +408,19 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
 
         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;
+          // Absolute flow position from the flat layout.
+          const abs = p ? p.position : n.position;
+          // Re-parent to the shell this node sits in, if any: a component's
+          // container, or a container's system frame. React Flow positions a
+          // child relative to its parent, so subtract the shell origin.
+          let parentId: string | undefined;
+          if (n.data && typeof n.data === 'object') {
+            const modelNode = (n.data as { element?: C4Element }).element;
+            if (modelNode?.parentId && builtGroups.has(modelNode.parentId)) parentId = modelNode.parentId;
           }
-          return node;
+          const origin = shellOrigin(parentId);
+          const node = { ...n, position: { x: abs.x - origin.x, y: abs.y - origin.y } };
+          return (parentId ? { ...node, parentId } : { ...node, parentId: undefined }) as Node;
         });
 
         setNodes([...shells, ...leaves]);
@@ -399,6 +448,24 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
     [model, selectedId],
   );
 
+  /**
+   * The components authored inside the selected element, if it is a container.
+   * These are `C4Component`s whose `container` names the selected id (or, once
+   * flattened, whose `parentId` does). Shown in the panel so a container can be
+   * inspected without zooming the diagram into its components.
+   */
+  const selectedComponents = useMemo(
+    () =>
+      selected
+        ? model.nodes.filter(
+            (n) =>
+              n.kind === 'component' &&
+              (n.container === selected.id || n.parentId === selected.id),
+          )
+        : [],
+    [model, selected],
+  );
+
   const displayNodes = useMemo(
     () =>
       nodes.map((n) =>
@@ -409,7 +476,11 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
     [nodes, selectedId],
   );
 
-  const runtime = model.nodes.filter((n) => n.kind === 'container' || n.kind === 'component').length;
+  // What the current view draws: runtime units at container level, components
+  // at component level. Mirrors the `inView` filter used for the nodes.
+  const runtime = model.nodes.filter((n) =>
+    model.view === 'component' ? n.kind === 'component' : n.kind === 'container',
+  ).length;
   const outside = model.nodes.filter(
     (n) => n.kind === 'external-system' || n.kind === 'person',
   ).length;
@@ -443,7 +514,7 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
         <GraphChrome />
       </ReactFlow>
       {ready && labelPositions.size > 0 && (
-        <C4EdgeLabels positions={labelPositions} edges={model.edges} muted={muted} />
+        <C4EdgeLabels positions={labelPositions} edges={model.edges} />
       )}
       {!ready && (
         <div
@@ -499,7 +570,7 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
           }}
         >
           <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' }}>
+            <span style={{ fontFamily: theme.fonts.monospace, fontWeight: 600, color: theme.colors.text, flex: 1, minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
               {selected.label}
             </span>
             <button
@@ -514,13 +585,30 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
               ×
             </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>
+          {/* The sub-line carries the technology — the fact worth reading at a
+              glance. Counts are omitted: the list below is already the count,
+              and kind/state are on the box itself. A person has no technology,
+              so its sub-line is blank. */}
+          {selected.kind !== 'person' &&
+            (() => {
+              const technology = (selected as { technology?: string }).technology;
+              return (
+                <div
+                  style={{
+                    fontFamily: theme.fonts.monospace,
+                    fontSize: theme.fontSizes[0],
+                    color: technology ? muted : (theme.colors.warning ?? '#e8a33a'),
+                    margin: '4px 0 8px',
+                  }}
+                >
+                  {technology ?? 'technology: not stated'}
+                </div>
+              );
+            })()}
 
-          {/* Confirmation state, with what is still missing. */}
-          {selected.kind === 'container' && (
+          {/* The container's own description already shows on the card, so the
+              panel only adds what the card omits: the claimed process. */}
+          {selected.kind === 'container' && selected.process && (
             <div
               style={{
                 fontFamily: theme.fonts.monospace,
@@ -529,52 +617,124 @@ function Inner({ model, title, onSelectNode, gutter = 28 }: C4GraphProps) {
                 borderTop: `1px solid ${theme.colors.border ?? '#333'}`,
                 paddingTop: 6,
                 marginBottom: 8,
+                whiteSpace: 'normal',
+                lineHeight: 1.4,
+              }}
+            >
+              verifies process: {selected.process}
+            </div>
+          )}
+
+          {/* Components authored inside this container, listed so the container
+              can be inspected without zooming the diagram into them. Inert for
+              now — the drill-down hung off them comes later. */}
+          {selected.kind === 'container' && selectedComponents.length > 0 && (
+            <div
+              style={{
                 display: 'flex',
                 flexDirection: 'column',
-                gap: 3,
+                gap: 6,
+                borderTop: `1px solid ${theme.colors.border ?? '#333'}`,
+                paddingTop: 8,
               }}
             >
-              <span style={{ color: nodeStyle(selected, theme).color }}>
-                {selected.state}
-                {selected.containerKind ? ` · ${selected.containerKind}` : ` · ${selected.kind}`}
+              <span
+                style={{
+                  fontFamily: theme.fonts.monospace,
+                  fontSize: theme.fontSizes[0],
+                  color: muted,
+                  textTransform: 'uppercase',
+                  letterSpacing: 0.5,
+                }}
+              >
+                Components
               </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>
-              )}
+              {selectedComponents.map((c) => (
+                <div key={c.id} style={{ display: 'flex', flexDirection: 'column', gap: 1 }}>
+                  <span
+                    title={c.description ?? c.label}
+                    style={{
+                      fontFamily: theme.fonts.body,
+                      color: theme.colors.text,
+                      overflow: 'hidden',
+                      textOverflow: 'ellipsis',
+                      whiteSpace: 'nowrap',
+                    }}
+                  >
+                    {c.label}
+                  </span>
+                  <span
+                    style={{
+                      fontFamily: theme.fonts.monospace,
+                      fontSize: theme.fontSizes[0],
+                      color: muted,
+                      overflow: 'hidden',
+                      textOverflow: 'ellipsis',
+                      whiteSpace: 'nowrap',
+                    }}
+                  >
+                    {'technology' in c && c.technology ? c.technology : c.kind}
+                    {(c.members ?? []).length > 0 ? ` · ${(c.members ?? []).length} member${(c.members ?? []).length === 1 ? '' : 's'}` : ''}
+                  </span>
+                </div>
+              ))}
             </div>
           )}
 
-          <div style={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
-            {selected.members.map((alias) => (
+          {/* No components authored: fall back to the raw member aliases, or
+              say so plainly when there is nothing inside at all. Same divider +
+              header as the authored list, so the panel sections consistently. */}
+          {selected.kind === 'container' && selectedComponents.length === 0 && (
+            <div
+              style={{
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 6,
+                borderTop: `1px solid ${theme.colors.border ?? '#333'}`,
+                paddingTop: 8,
+              }}
+            >
               <span
-                key={alias}
-                title={alias}
                 style={{
                   fontFamily: theme.fonts.monospace,
                   fontSize: theme.fontSizes[0],
-                  color: theme.colors.text,
-                  overflow: 'hidden',
-                  textOverflow: 'ellipsis',
-                  whiteSpace: 'nowrap',
+                  color: muted,
+                  textTransform: 'uppercase',
+                  letterSpacing: 0.5,
                 }}
               >
-                {alias}
+                Components
               </span>
-            ))}
-          </div>
+              {(selected.members ?? []).length > 0 ? (
+                (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>
+                ))
+              ) : (
+                <span
+                  style={{
+                    fontFamily: theme.fonts.monospace,
+                    fontSize: theme.fontSizes[0],
+                    color: muted,
+                  }}
+                >
+                  No components
+                </span>
+              )}
+            </div>
+          )}
         </div>
       )}
     </div>

package/src/subsystem/C4NodeCard.test.ts

@@ -12,7 +12,7 @@ import {
   nodeSize,
   COMPONENT_SIZE,
 } from './C4NodeCard';
-import type { C4Node } from './c4';
+import type { C4Element, C4Container } from './c4';
 
 const theme = {
   colors: {
@@ -25,12 +25,20 @@ 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.
+ * A container element with overridable fields. `state` is required — 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 };
+function node(over: Partial<C4Container> = {}): C4Element {
+  return {
+    id: 'n',
+    kind: 'container',
+    label: 'n',
+    containerKind: 'application',
+    technology: '',
+    state: 'proposed',
+    ...over,
+  };
 }
 
 describe('nodeStyle — one axis per channel', () => {
@@ -39,16 +47,12 @@ describe('nodeStyle — one axis per channel', () => {
     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('accepted is solid', () => {
+    expect(nodeStyle(node({ state: 'accepted' }), theme).dash).toBe('solid');
   });
 
-  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('proposed is dashed', () => {
+    expect(nodeStyle(node({ state: 'proposed' }), theme).dash).toBe('dashed');
   });
 
   test('rejected is dotted and muted', () => {
@@ -67,12 +71,18 @@ describe('nodeStyle — one axis per channel', () => {
     }
   });
 
-  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('colour follows the technology, not the state', () => {
+    // Same kind and state, different tech: different hue.
+    const react = nodeStyle(node({ technology: 'React 19', state: 'accepted' }), theme).color;
+    const bun = nodeStyle(node({ technology: 'Bun', state: 'accepted' }), theme).color;
+    expect(react).not.toBe(bun);
+    // State does not move the colour.
+    expect(nodeStyle(node({ technology: 'React 19', state: 'proposed' }), theme).color).toBe(react);
+  });
+
+  test('an unknown technology falls back to the muted border', () => {
+    expect(nodeStyle(node({ technology: '', state: 'accepted' }), theme).color).toBe('#555');
+    expect(nodeStyle(node({ technology: 'COBOL', state: 'accepted' }), theme).color).toBe('#555');
   });
 
   test('border weight carries the level, not the state', () => {
@@ -165,10 +175,10 @@ describe('nodeShape — kind without relying on colour or dash', () => {
     expect(nodeShape(node({ kind: 'component' })).kind).toBe('square');
   });
 
-  test('an external system is a rounded rectangle', () => {
+  test('an external system has no corner radius', () => {
     const s = nodeShape(node({ kind: 'external-system' }));
     expect(s.kind).toBe('rect');
-    expect(s.radius).toBeGreaterThan(nodeShape(node()).radius);
+    expect(s.radius).toBe(0);
   });
 
   test('a person is a pill', () => {