@principal-ai/subsystems-react 0.53.0 → 0.53.1

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

@@ -20,12 +20,14 @@ import {
   CircleDashed,
   CircleEllipsis,
   CircleHelp,
+  CircleSlash,
   CircleX,
   Component,
   FileX,
   FolderGit2,
   Footprints,
   History,
+  Link2Off,
   MapPin,
   Network,
   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.ts

@@ -150,9 +150,16 @@ export interface ElkLayoutOptions {
    * decoration drawn around wherever the members landed.
    *
    * Only for groups whose members need no parent-relative positioning (C4's
-   * system frame). @default false
+   * system frame).
+   *
+   * A set names specific groups to flatten, leaving the rest as real ELK
+   * parents — the drill-down needs this, because the opened container must be
+   * *sized by ELK to fit its nested components* while the system frame around
+   * it stays decorative. Descendants of a flattened group are flattened too.
+   *
+   * @default false
    */
-  flatGroups?: boolean;
+  flatGroups?: boolean | ReadonlySet<string>;
 
   /**
    * ELK partition per node id. Nodes are banded by `partition` — ELK places all
@@ -520,6 +527,21 @@ export interface CompoundGroupDef {
   id: string;
   memberIds: string[];
   minWidth?: number;
+  /**
+   * ELK partition for this group. Partitioning is activated on the root and
+   * inherited, so a compound parent must be told its band explicitly —
+   * otherwise it falls to partition 0 and lays out away from the siblings it is
+   * supposed to sit among (which, for a flat frame around those siblings, drags
+   * the frame across an unrelated band).
+   */
+  partition?: number;
+  /**
+   * Space reserved above the first child, in px. Set it when the parent draws
+   * its own chrome at the top (C4's grown container draws a label slot and a
+   * technology row) so ELK still owns the fit — it pads the parent by this and
+   * the children land below the chrome rather than under it.
+   */
+  padTop?: number;
 }
 
 /** Which groups ELK builds, and which it drops. */
@@ -528,7 +550,7 @@ export interface CompoundGroupPlan {
    * Built groups in build order — a group's children always appear before it,
    * so callers can map ids to shells in one forward pass.
    */
-  built: Array<{ id: string; childIds: string[]; minWidth?: number }>;
+  built: Array<{ id: string; childIds: string[]; minWidth?: number; padTop?: number; partition?: number }>;
   /**
    * Dropped groups. Their members are promoted into the nearest built
    * ancestor, so callers must clear those members' `parentId`.
@@ -864,11 +886,27 @@ export async function computeElkLayout(
   // and the frame is synthesized from the members' bounds after layout. This
   // keeps every edge on one spacing instead of inheriting a nested frame's.
   const flatGroupIds = new Set<string>();
-  if (flatGroups) {
+  if (flatGroups === true) {
     for (const g of plan.built) flatGroupIds.add(g.id);
+  } else if (flatGroups) {
+    for (const g of plan.built) if (flatGroups.has(g.id)) flatGroupIds.add(g.id);
+    // A group inside a flat frame can't be an ELK parent either — its members
+    // lay out at the root alongside the frame's other members.
+    let grew = true;
+    while (grew) {
+      grew = false;
+      for (const g of plan.built) {
+        if (flatGroupIds.has(g.id)) continue;
+        const parentId = groupById.get(g.id)?.parentId;
+        if (parentId && flatGroupIds.has(parentId)) {
+          flatGroupIds.add(g.id);
+          grew = true;
+        }
+      }
+    }
   }
   for (const g of plan.built) {
-    if (flatGroups) break;
+    if (flatGroupIds.has(g.id)) continue;
     const children: ElkNode[] = [];
     for (const cid of g.childIds) {
       const leaf = elkById.get(cid);
@@ -878,14 +916,26 @@ export async function computeElkLayout(
         if (nested) children.push(nested);
       }
     }
+    const sizeOptions: Record<string, string> = {};
+    if (g.minWidth != null) {
+      // MINIMUM_SIZE, not a forced size: ELK grows the parent past it when the
+      // children need more, but never shrinks it below it.
+      sizeOptions['elk.nodeSize.constraints'] = 'MINIMUM_SIZE';
+      sizeOptions['elk.nodeSize.minimum'] = `(${g.minWidth},0)`;
+    }
+    if (g.padTop != null) {
+      // Reserving the parent's own chrome. Children then start below it, and
+      // the parent's height still comes from ELK's fit.
+      sizeOptions['elk.padding'] = `[top=${g.padTop},left=12,bottom=12,right=12]`;
+    }
+    if (g.partition != null) sizeOptions['partition'] = String(g.partition);
     builtGroups.set(g.id, {
       id: g.id,
       children,
-      layoutOptions: g.minWidth == null ? compoundLayoutOptions : {
-        ...compoundLayoutOptions,
-        'elk.nodeSize.constraints': 'MINIMUM_SIZE',
-        'elk.nodeSize.minimum': `(${g.minWidth},0)`,
-      },
+      layoutOptions:
+        Object.keys(sizeOptions).length > 0
+          ? { ...compoundLayoutOptions, ...sizeOptions }
+          : compoundLayoutOptions,
     });
   }