@principal-ai/subsystems-react 0.53.0 → 0.53.2

package/src/subsystem/C4NodeCard.test.ts

@@ -150,18 +150,21 @@ describe('nodeTopLabel — the technology, or the kind when none is stated', ()
     expect(
       nodeTopLabel(node({ containerKind: 'application', technology: 'Bun + Electrobun' })),
     ).toBe('Bun + Electrobun');
-    expect(nodeTopLabel(node({ kind: 'component', technology: 'React + ELK' }))).toBe('React + ELK');
   });
 
   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');
+  test('an external system / person falls back to its C4 kind', () => {
     expect(nodeTopLabel(node({ kind: 'external-system' }))).toBe('external-system');
     expect(nodeTopLabel(node({ kind: 'person' }))).toBe('person');
   });
+
+  test('a component has no top label — its technology is the container’s', () => {
+    expect(nodeTopLabel(node({ kind: 'component', technology: 'React + ELK' }))).toBe('');
+    expect(nodeTopLabel(node({ kind: 'component' }))).toBe('');
+  });
 });
 
 describe('nodeShape — kind without relying on colour or dash', () => {

package/src/subsystem/C4NodeCard.tsx

@@ -13,7 +13,7 @@
  */
 
 import { useTheme } from '@principal-ade/industry-theme';
-import { AppWindow, Component, Database } from 'lucide-react';
+import { AppWindow, Component, Database, Maximize2 } from 'lucide-react';
 import type { LucideIcon } from 'lucide-react';
 import { TechMark, technologyBrand } from './techIcons';
 import type { C4Element } from './c4';
@@ -50,6 +50,17 @@ export function nodeSize(node: C4Element): { width: number; height: number } {
  */
 const LABEL_SLOT_H = 40;
 
+/**
+ * Space a *grown* container reserves above its nested components: the card's own
+ * top padding + the label slot + the row gap + the technology row, plus a little
+ * air. The description is hidden while grown, so it is not part of this.
+ *
+ * The graph hands this to ELK as the compound parent's top padding rather than
+ * nudging the children down itself — so the parent's size and the children's
+ * placement are still one ELK fit, not our arithmetic layered on top of it.
+ */
+export const OPEN_HEADER_PAD = 84;
+
 type Theme = ReturnType<typeof useTheme>['theme'];
 
 export interface NodeStyle {
@@ -151,14 +162,17 @@ export function nodeKindIcon(node: C4Element): LucideIcon | undefined {
  * The text on the top row: the technology the box is built with (Bun, React,
  * Postgres…). Falls back to the container kind / C4 kind when no technology is
  * stated, so the row is never blank.
+ *
+ * A component returns `''`: its technology is almost always the container's, so
+ * restating it is noise. The container frame already carries it.
  */
 export function nodeTopLabel(node: C4Element): string {
+  if (node.kind === 'component') return '';
   const technology = nodeTechnology(node);
   if (technology) return technology;
   switch (node.kind) {
     case 'container':
       return node.containerKind;
-    case 'component':
     case 'external-system':
     case 'person':
       return node.kind;
@@ -231,9 +245,31 @@ export interface C4NodeCardProps {
    * row for containers. Omitted/0 → no count.
    */
   componentCount?: number;
+  /**
+   * When set, the card draws an expand affordance (bottom-right) that calls
+   * this — the drill-down trigger. Only containers with components pass it.
+   */
+  onExpand?: () => void;
+  /**
+   * Explicit box size, overriding the kind's default. Lets a host animate the
+   * card (the drill-down grow) without the card owning that state.
+   */
+  width?: number;
+  height?: number;
+  /**
+   * Show the description line under the label. Off when the card is grown to
+   * host components — the internals occupy that space.
+   * @default true
+   */
+  showDescription?: boolean;
+  /**
+   * Content drawn below the header (label / technology / description). Used by
+   * the grown card to host its component cards.
+   */
+  children?: React.ReactNode;
 }
 
-export function C4NodeCard({ node, selected = false, handles, onClick, componentCount = 0 }: C4NodeCardProps) {
+export function C4NodeCard({ node, selected = false, handles, onClick, componentCount = 0, onExpand, width, height, showDescription = true, children }: C4NodeCardProps) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const style = nodeStyle(node, theme, selected);
@@ -252,8 +288,10 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
     <div
       onClick={onClick}
       style={{
-        width: size.width,
-        minHeight: size.height,
+        position: 'relative',
+        width: width ?? size.width,
+        minHeight: height ?? size.height,
+        transition: 'width 420ms ease-out, min-height 420ms ease-out',
         boxSizing: 'border-box',
         display: 'flex',
         flexDirection: 'column',
@@ -280,7 +318,7 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
         style={{
           display: 'flex',
           alignItems: 'flex-start',
-          justifyContent: centered ? 'center' : 'flex-start',
+          justifyContent: centered ? 'center' : 'space-between',
           gap: 6,
           height: LABEL_SLOT_H,
           minWidth: 0,
@@ -337,20 +375,22 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
           minWidth: 0,
         }}
       >
-        <span style={{ display: 'flex', alignItems: 'center', gap: 6, minWidth: 0 }}>
-          {brand && <TechMark brand={brand} />}
-          <span
-            style={{
-              fontWeight: 600,
-              whiteSpace: 'nowrap',
-              overflow: 'hidden',
-              textOverflow: 'ellipsis',
-              minWidth: 0,
-            }}
-          >
-            {topLabel}
+        {topLabel && (
+          <span style={{ display: 'flex', alignItems: 'center', gap: 6, minWidth: 0 }}>
+            {brand && <TechMark brand={brand} />}
+            <span
+              style={{
+                fontWeight: 600,
+                whiteSpace: 'nowrap',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                minWidth: 0,
+              }}
+            >
+              {topLabel}
+            </span>
           </span>
-        </span>
+        )}
         {node.kind === 'container' && (
           <span
             style={{
@@ -366,7 +406,7 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
           </span>
         )}
       </span>
-      {subtitle && (
+      {showDescription && subtitle && (
         <span
           style={{
             fontFamily: theme.fonts.monospace,
@@ -381,6 +421,38 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
           {subtitle}
         </span>
       )}
+      {children}
+      {/* Drill-down affordance: bottom-right, its own hit target so the card's
+          own click (select) is unaffected. */}
+      {onExpand && (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation();
+            onExpand();
+          }}
+          aria-label="Show components"
+          style={{
+            position: 'absolute',
+            right: 6,
+            bottom: 6,
+            display: 'inline-flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            width: 22,
+            height: 22,
+            padding: 0,
+            borderRadius: 4,
+            border: `1px solid ${style.color}`,
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            color: style.color,
+            cursor: 'pointer',
+            lineHeight: 1,
+          }}
+        >
+          <Maximize2 size={13} strokeWidth={2.25} />
+        </button>
+      )}
       {handles}
     </div>
   );

package/src/subsystem/IssueList.category.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test';
+import { issueCategory, issueKindLabel } from './IssueList';
+
+/**
+ * Every C4 process-verification kind must land in the dynamic-topology
+ * category. These kinds are emitted by new audit passes over time, and an
+ * unmapped kind silently falls through to `construct` — the list then files a
+ * process finding under Constructs while the maintenance lane tally counts it
+ * as dynamic-topology, so the construct lane reads verified (green) beside a
+ * process issue. The regressions are real: `boundary_process_missing` shipped
+ * unmapped long before the container-first kinds joined it.
+ */
+describe('issueCategory — C4 process kinds', () => {
+  const processKinds = [
+    'boundary_process_missing',
+    'boundary_process_nest_disagree',
+    'boundary_process_unassigned',
+    'boundary_process_proposed',
+    'boundary_process_rejected',
+    'boundary_process_unbacked',
+  ];
+
+  for (const kind of processKinds) {
+    test(`${kind} categorizes as dynamic-topology`, () => {
+      expect(issueCategory({ id: 'x', severity: 'info', kind, message: '' })).toBe(
+        'dynamic-topology',
+      );
+    });
+  }
+
+  test('mapped kinds get human labels, not the humanized fallback', () => {
+    expect(issueKindLabel({ id: 'x', severity: 'info', kind: 'boundary_process_missing', message: '' })).toBe(
+      'Process claim missing',
+    );
+    expect(issueKindLabel({ id: 'x', severity: 'info', kind: 'boundary_process_unbacked', message: '' })).toBe(
+      'Process claim unbacked',
+    );
+  });
+});

package/src/subsystem/IssueList.tsx

@@ -14,23 +14,25 @@
 import { useEffect, useRef, useState } from 'react';
 import type { LucideIcon } from 'lucide-react';
 import {
+  AppWindow,
   ChevronDown,
   ChevronRight,
   CircleCheck,
   CircleDashed,
   CircleEllipsis,
   CircleHelp,
+  CircleSlash,
   CircleX,
   Component,
   FileX,
   FolderGit2,
   Footprints,
   History,
+  Link2Off,
   MapPin,
   Network,
   Route,
   Search,
-  Server,
   Shapes,
   Sigma,
   Split,
@@ -80,7 +82,7 @@ export const SUBSYSTEM_ISSUE_CATEGORY_ICON: Record<
   repo: FolderGit2,
   construct: Component,
   'static-topology': Network,
-  'dynamic-topology': Server,
+  'dynamic-topology': AppWindow,
   trail: Route,
 };
 
@@ -112,9 +114,11 @@ const KIND_CATEGORY: Record<string, SubsystemIssueCategory> = {
   // C4 process verification (verifyProcessBoundaries): a boundary whose
   // container claim is not an accepted one. `verified` reports nothing —
   // the audit reports absence only.
+  boundary_process_missing: 'dynamic-topology',
   boundary_process_unassigned: 'dynamic-topology',
   boundary_process_proposed: 'dynamic-topology',
   boundary_process_rejected: 'dynamic-topology',
+  boundary_process_unbacked: 'dynamic-topology',
   trail: 'trail',
   step_unconfirmed: 'trail',
   step_stale: 'trail',
@@ -180,9 +184,12 @@ export const ISSUE_KIND_ICON: Record<string, LucideIcon> = {
   boundary_process_nest_disagree: Split,
   // C4 process verification: unclaimed = no container at all, proposed = an
   // agent scaffold awaits a decision, rejected = a container was declined.
+  boundary_process_missing: CircleSlash,
   boundary_process_unassigned: CircleEllipsis,
   boundary_process_proposed: CircleDashed,
   boundary_process_rejected: CircleX,
+  // Container-first gate: a claim cites a key no accepted container owns.
+  boundary_process_unbacked: Link2Off,
   // Trail step verification: unconfirmed = no augmentation yet, stale = code changed
   step_unconfirmed: CircleHelp,
   step_stale: History,
@@ -267,9 +274,11 @@ const KIND_LABEL: Record<string, string> = {
   boundary_process_nest_disagree: 'Module spans multiple process contexts',
   // C4 process verification (labels read as boundary states, since the layer
   // scopes them to process frames).
+  boundary_process_missing: 'Process claim missing',
   boundary_process_unassigned: 'Process boundary unclaimed',
   boundary_process_proposed: 'Container awaiting decision',
   boundary_process_rejected: 'Container rejected',
+  boundary_process_unbacked: 'Process claim unbacked',
   trail: 'Step issue',
   step_unconfirmed: 'Call site not verified',
   step_stale: 'Call site changed',
@@ -304,9 +313,11 @@ const KIND_ORDER: Record<string, number> = {
   boundary_module_file_mismatch: 23,
   // Runtime topology — process containment
   boundary_process_nest_disagree: 30,
-  boundary_process_unassigned: 31,
-  boundary_process_proposed: 32,
-  boundary_process_rejected: 33,
+  boundary_process_missing: 31,
+  boundary_process_unassigned: 32,
+  boundary_process_unbacked: 33,
+  boundary_process_proposed: 34,
+  boundary_process_rejected: 35,
   // Trail — mechanical issues first, then step verification
   trail: 40,
   step_unconfirmed: 41,

package/src/subsystem/c4.ts

@@ -153,7 +153,11 @@ export interface C4ElementSet {
 /** Which level to draw. Determines which frames are drawn. */
 export type C4View = 'container' | 'component';
 
-/** A compound frame: the system, or a container holding its components. */
+/**
+ * A compound frame the renderer draws: the system, or a container holding its
+ * components. Never authored — `deriveC4Groups` produces these from the element
+ * `parentId` chains and the current scope.
+ */
 export interface C4Group {
   id: string;
   kind: 'system' | 'container';
@@ -162,6 +166,63 @@ export interface C4Group {
   memberIds: string[];
 }
 
+/**
+ * Derive the frames to draw from the elements and the current scope.
+ *
+ * A container becomes a frame whenever its components are on screen — in the
+ * component view, or when it is the opened container. The system frame wraps
+ * whichever containers are drawn. No frame is authored; this is the view of the
+ * element set, so a container's identity (id, label, technology, colour) lives
+ * only on the element.
+ */
+export function deriveC4Groups(
+  model: Pick<C4Model, 'view' | 'system' | 'nodes' | 'openContainerId'>,
+): C4Group[] {
+  const groups: C4Group[] = [];
+  const containers = model.nodes.filter((n): n is C4Container => n.kind === 'container');
+  const components = model.nodes.filter((n): n is C4Component => n.kind === 'component');
+
+  const opened = model.openContainerId ?? null;
+  // Component view shows every container's components; container view shows a
+  // container's components only when it is opened.
+  const framing = (containerId: string): boolean =>
+    model.view === 'component' || opened === containerId;
+
+  const framedContainers: string[] = [];
+  for (const c of containers) {
+    const members = components
+      .filter((comp) => (comp.container ?? comp.parentId) === c.id)
+      .map((comp) => comp.id);
+    if (members.length > 0 && framing(c.id)) {
+      groups.push({
+        id: c.id,
+        kind: 'container',
+        label: c.label,
+        parentId: model.system.id,
+        memberIds: members,
+      });
+      framedContainers.push(c.id);
+    }
+  }
+
+  // The system frame wraps the framed containers (component view) or the whole
+  // set of containers (container view) — the boundary is the system, so it must
+  // NOT shrink to the opened container. Opening one adds a nested container
+  // frame inside it; the system frame still spans everything.
+  const systemMembers =
+    model.view === 'component' ? framedContainers : containers.map((c) => c.id);
+  if (systemMembers.length > 0) {
+    groups.push({
+      id: model.system.id,
+      kind: 'system',
+      label: model.system.label,
+      memberIds: systemMembers,
+    });
+  }
+
+  return groups;
+}
+
 /**
  * A line between two elements. Authored, like the boxes.
  *
@@ -229,13 +290,23 @@ export function protocolColor(protocol: string | undefined): string {
   return best ? PROTOCOL_COLOR[best]! : PROTOCOL_COLOR_FALLBACK;
 }
 
-/** A drawable C4 projection. Authored, not derived. */
+/**
+ * A drawable C4 projection. Authored: the boxes and lines, nothing drawn for
+ * you. Frames are derived by the renderer from the elements' `parentId` chains
+ * — a container is a frame when its components are being shown (component view,
+ * or opened via `openContainerId`), never a separately-authored thing.
+ */
 export interface C4Model {
   view: C4View;
   system: { id: string; label: string; repoKey?: string };
   nodes: C4Element[];
-  groups: C4Group[];
   edges: C4Edge[];
+  /**
+   * Drill-down scope: the id of a container whose components should be shown
+   * inside it as a frame. Absent/null → the container is drawn as a box and its
+   * components are hidden. The renderer derives the frames either way.
+   */
+  openContainerId?: string | null;
 }
 
 /**

package/src/utils/elkLayout.test.ts

@@ -16,10 +16,126 @@ import {
   fractionAlongPath,
   planCompoundGroups,
   getElkOptions,
+  absoluteBoundsOf,
+  flowPositionOf,
   type Point,
 } from './elkLayout';
 import { EDGE_LABEL_WIDTH, EDGE_LABEL_SIDE_PADDING } from './edgeLabel';
 
+/**
+ * A synthetic laid-out result standing in for the drill-down's open layout: a
+ * compound parent at (12,12) with two children, a sibling container, and a
+ * flattened frame that never enters the ELK tree.
+ */
+function syntheticResult() {
+  const rect = (x: number, y: number, width: number, height: number) => ({
+    x, y, width, height,
+  });
+  return {
+    absoluteRects: new Map([
+      ['container:host', rect(12, 12, 508, 416)],
+      ['cmp:a', rect(24, 96, 140, 140)],
+      ['cmp:b', rect(24, 276, 140, 140)],
+      ['container:api', rect(576, 218, 250, 150)],
+    ]),
+    // A nested group's entry is parent-relative — the trap `flowPositionOf` avoids.
+    groupBounds: new Map([
+      ['container:host', rect(12, 12, 508, 416)],
+      ['container:api', rect(576, 218, 250, 150)],
+      ['system:acme', rect(-12, -52, 1152, 504)],
+    ]),
+  };
+}
+
+describe('absolute coordinate space', () => {
+  test('a root node keeps its absolute position', () => {
+    const r = syntheticResult();
+    expect(flowPositionOf(r, 'container:host')).toEqual({ x: 12, y: 12 });
+    expect(flowPositionOf(r, 'container:api')).toEqual({ x: 576, y: 218 });
+  });
+
+  // The bug this guards: a child's own position is already parent-relative, so
+  // subtracting the parent's absolute origin again pushed it out of its card.
+  test('a child is relative to its parent, offset exactly once', () => {
+    const r = syntheticResult();
+    expect(flowPositionOf(r, 'cmp:a', 'container:host')).toEqual({ x: 12, y: 84 });
+    expect(flowPositionOf(r, 'cmp:b', 'container:host')).toEqual({ x: 12, y: 264 });
+  });
+
+  test('children land inside the parent box they are nested in', () => {
+    const r = syntheticResult();
+    const box = absoluteBoundsOf(r, 'container:host')!;
+    for (const id of ['cmp:a', 'cmp:b']) {
+      const p = flowPositionOf(r, id, 'container:host')!;
+      const own = r.absoluteRects.get(id)!;
+      expect(p.x).toBeGreaterThanOrEqual(0);
+      expect(p.y).toBeGreaterThanOrEqual(0);
+      expect(p.x + own.width).toBeLessThanOrEqual(box.width);
+      expect(p.y + own.height).toBeLessThanOrEqual(box.height);
+    }
+  });
+
+  // A compound parent has no `result.nodes` entry at all, so anything reading
+  // positions from there leaves it on its authored slot.
+  test('a compound parent gets a real position, not a fallback', () => {
+    const r = syntheticResult();
+    expect(flowPositionOf(r, 'container:host')).not.toBeUndefined();
+    expect(flowPositionOf(r, 'container:host')).toEqual(
+      r.absoluteRects.get('container:host') && { x: 12, y: 12 },
+    );
+  });
+
+  test('a flattened frame resolves from the synthesized bounds', () => {
+    // Not in absoluteRects — it never entered the ELK tree.
+    expect(syntheticResult().absoluteRects.has('system:acme')).toBe(false);
+    expect(absoluteBoundsOf(syntheticResult(), 'system:acme')).toEqual({
+      x: -12, y: -52, width: 1152, height: 504,
+    });
+  });
+
+  test('an unknown id has no position rather than a silent zero', () => {
+    expect(flowPositionOf(syntheticResult(), 'nope')).toBeUndefined();
+    expect(absoluteBoundsOf(syntheticResult(), 'nope')).toBeUndefined();
+  });
+
+  test('an unknown parent falls back to absolute, not to a wrong origin', () => {
+    expect(flowPositionOf(syntheticResult(), 'cmp:a', 'nope')).toEqual({ x: 24, y: 96 });
+  });
+});
+
+/**
+ * A card's FLIP offset is the difference between where it was and where the new
+ * layout puts it. If this is computed in the wrong space the card slides to a
+ * plausible-looking wrong place, which is what "the anchors shift" looks like.
+ */
+describe('morph offsets', () => {
+  interface Rect { x: number; y: number; width: number; height: number }
+  const offsetTo = (from: Rect, to: Rect) => ({
+    x: from.x - to.x,
+    y: from.y - to.y,
+  });
+
+  test('a card that moves is offset by exactly the move', () => {
+    // Closed: (330,182) 250x150. Open: the compound parent ELK fitted at (12,12).
+    const closed = { x: 330, y: 182, width: 250, height: 150 };
+    const open = { x: 12, y: 12, width: 508, height: 416 };
+    expect(offsetTo(closed, open)).toEqual({ x: 318, y: 170 });
+  });
+
+  test('a card that does not move gets no offset', () => {
+    const same = { x: 576, y: 218, width: 250, height: 150 };
+    expect(offsetTo(same, same)).toEqual({ x: 0, y: 0 });
+  });
+
+  test('an offset ignores size, because the card transitions its own size', () => {
+    // Growing in place must not shift the anchor: the card's width/height
+    // transition handles the size, a translate must stay 0.
+    const before = { x: 12, y: 12, width: 250, height: 150 };
+    const after = { x: 12, y: 12, width: 508, height: 416 };
+    expect(offsetTo(before, after)).toEqual({ x: 0, y: 0 });
+  });
+});
+
 describe('planCompoundGroups', () => {
   test('drops a single-leaf group by default and promotes its member', () => {
     const plan = planCompoundGroups(
@@ -130,6 +246,21 @@ describe('planCompoundGroups', () => {
     );
     expect(plan.built[0]!.minWidth).toBe(220);
   });
+
+  // `padTop` only reaches ELK if the plan carries it; when it was dropped here
+  // the parent's own header was silently overlaid by its first child.
+  test('carries padTop through to the plan', () => {
+    const plan = planCompoundGroups(
+      [{ id: 'mod', memberIds: ['a', 'b'], padTop: 84 }],
+      ['a', 'b'],
+    );
+    expect(plan.built[0]!.padTop).toBe(84);
+  });
+
+  test('leaves padTop unset when the group does not reserve chrome', () => {
+    const plan = planCompoundGroups([{ id: 'mod', memberIds: ['a', 'b'] }], ['a', 'b']);
+    expect(plan.built[0]!.padTop).toBeUndefined();
+  });
 });
 
 describe('elkLayout helper functions', () => {