@principal-ai/subsystems-react 0.53.4 → 0.53.6

package/src/subsystem/C4NodeCard.tsx

@@ -75,16 +75,127 @@ export function nodeSize(node: C4Element): { width: number; height: number } {
  */
 const LABEL_SLOT_H = 40;
 
+/**
+ * The technology row's height, pinned for the same reason as the label slot: the
+ * row is a line of text plus an optional 16px brand mark, so its natural height
+ * depends on which of those are present. Pinning it makes the card's chrome a
+ * known quantity, which is what lets `descriptionLineBudget` below say how many
+ * description lines fit — and lets the footer pad and the header pad agree about
+ * where the card's content actually ends.
+ */
+const TECH_SLOT_H = 18;
+
+/** The card's own vertical padding (`padding: '10px 12px'`). */
+const CARD_PAD_Y = 10;
+
+/** The card's flex `gap`, between each of its rows. */
+const CARD_GAP = 3;
+
+/** The description's line height, as a multiple of its font size. */
+const DESC_LINE_HEIGHT = 1.35;
+
+/**
+ * Breathing room between a grown container's own chrome and the components nested
+ * inside it.
+ *
+ * The description is hidden while grown, so the components land where the
+ * description would have been — immediately under the technology row. Without
+ * this the gap is the width of one row gap, which reads as the components being
+ * crowded against the header while the sides and footer sit `OPEN_SIDE_PAD` away.
+ * This is not chrome: nothing is drawn in it.
+ */
+const OPEN_HEADER_AIR = 16;
+
 /**
  * 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
+ * padding, its label slot, its technology row, the gaps between them, and a little
  * air. The description is hidden while grown, so it is not part of this.
  *
+ * Derived from the same constants the card is built from, rather than written as
+ * a literal, so it cannot drift from `descriptionLineBudget` — which subtracts
+ * exactly this chrome (and no air) to decide how much description a closed card
+ * can show. Those two disagreeing is how a card ends up taller than the box ELK
+ * laid out for it.
+ *
  * 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;
+export const OPEN_HEADER_PAD =
+  CARD_PAD_Y * 2 + LABEL_SLOT_H + CARD_GAP + TECH_SLOT_H + CARD_GAP + OPEN_HEADER_AIR;
+
+/**
+ * How many description lines fit in a card of this height before the drawn box
+ * would grow past the box the layout reserved for it.
+ *
+ * A card's height is a contract with the layout: ELK sized the node, the system
+ * frame and every edge against it. The description is the one part of a card whose
+ * length the layout cannot know, so it is clamped to what fits rather than allowed
+ * to push the border out past the frame drawn around it. Height is a *minimum* on
+ * the card, so without this a long description silently grows the drawn box while
+ * ELK — and therefore the boundary and the edge endpoints — keeps the old size.
+ *
+ * `hasTechRow` matters because an empty technology row is zero-height: a person
+ * card has one more line of room than a container. The row is pinned to
+ * `TECH_SLOT_H` when it has content, so this is exact rather than approximate.
+ */
+export function descriptionLineBudget(opts: {
+  reservedHeight: number;
+  lineHeight: number;
+  /** The card's border, which sits above the content and varies by kind. */
+  borderWidth: number;
+  hasTechRow: boolean;
+  /** Whether a collapse affordance is drawn at the bottom-right. */
+  reservesFooter: boolean;
+}): number {
+  const { reservedHeight, lineHeight, borderWidth, hasTechRow, reservesFooter } = opts;
+  if (lineHeight <= 0) return 0;
+  const topChrome =
+    borderWidth + CARD_PAD_Y + LABEL_SLOT_H + CARD_GAP + (hasTechRow ? TECH_SLOT_H : 0) + CARD_GAP;
+  // Reserving the footer is not the same as the card's own bottom padding. The
+  // toggle is `position: absolute` inset from the *padding* box, so it reaches
+  // `inset + size` up from the content box's bottom edge — and a description that
+  // only cleared the padding would still have its last line drawn through the
+  // button. Measured: the last line lands in the bottom ~26px band, and the toggle
+  // occupies the bottom 28 of it.
+  const bottomChrome = reservesFooter
+    ? Math.max(CARD_PAD_Y, TOGGLE_INSET + TOGGLE_SIZE)
+    : CARD_PAD_Y;
+  return Math.max(0, Math.floor((reservedHeight - topChrome - bottomChrome) / lineHeight));
+}
+
+/**
+ * The drill-down affordance, in the card's own box. Extracted from the button's
+ * style so the reserved footer below cannot drift from the thing it is reserving
+ * for — the two numbers are the same number.
+ */
+const TOGGLE_SIZE = 22;
+const TOGGLE_INSET = 6;
+
+/**
+ * Space a *grown* container reserves below its nested components, so the last row
+ * does not sit under the collapse affordance.
+ *
+ * The toggle is absolutely positioned, so it takes no space in the card's flow and
+ * ELK knows nothing about it: without this the parent is fitted to its children
+ * alone and the final row is drawn straight through the button. Reserving the
+ * toggle's own reach plus a little air keeps that an ELK fit too, rather than
+ * something we nudge afterwards.
+ */
+export const OPEN_FOOTER_PAD = TOGGLE_INSET + TOGGLE_SIZE + 8;
+
+/**
+ * Space a *grown* container reserves to the left and right of its nested
+ * components.
+ *
+ * Deliberately the footer's number rather than its own: the nested cards should
+ * sit in one uniform inset, not a wider one at the bottom than at the sides. Both
+ * are wider than the card's own 12px text inset — the label and technology row are
+ * the container's chrome and sit flush with its padding, while the nested cards
+ * are separate boxes it contains, and at the same inset they read as part of that
+ * chrome rather than held inside it.
+ */
+export const OPEN_SIDE_PAD = OPEN_FOOTER_PAD;
 
 type Theme = ReturnType<typeof useTheme>['theme'];
 
@@ -318,6 +429,22 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
   const subtitle = nodeSubtitle(node);
 
   const size = nodeSize(node);
+  // The height the layout reserved for this card — what the system frame and the
+  // edge endpoints were placed against. Everything below sizes to this, not to
+  // whatever the content would like.
+  const reservedHeight = height ?? size.height;
+  // A container always has a technology row (at minimum the member count); a
+  // person never does.
+  const hasTechRow = !!topLabel || node.kind === 'container';
+  const descLineHeightPx = theme.fontSizes[0] * DESC_LINE_HEIGHT;
+  const descLines = descriptionLineBudget({
+    reservedHeight,
+    lineHeight: descLineHeightPx,
+    borderWidth: style.width,
+    hasTechRow,
+    // The affordance is drawn exactly when the card can be expanded or collapsed.
+    reservesFooter: !!onExpand,
+  });
   const centered = shape.align === 'center';
   // The pill's inset is a separate concern from alignment, and a centred
   // component must not inherit it: 30px of each side would leave a 160-wide box
@@ -331,8 +458,15 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
       style={{
         position: 'relative',
         width: width ?? size.width,
-        minHeight: height ?? size.height,
-        transition: 'width 420ms ease-out, min-height 420ms ease-out',
+        // A hard height, not a minimum. The card *is* the box the layout reserved
+        // — the system frame is fitted around it and every edge endpoint is placed
+        // against it — so it must not be able to grow itself. `overflow: hidden`
+        // makes that structural: if the content ever exceeds the box, it is clipped
+        // rather than drawn outside the boundary. The description is clamped above
+        // so that clipping is never what you actually see.
+        height: reservedHeight,
+        transition: 'width 420ms ease-out, height 420ms ease-out',
+        overflow: 'hidden',
         boxSizing: 'border-box',
         display: 'flex',
         flexDirection: 'column',
@@ -340,7 +474,7 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
         // marker is conditional), and centring pushes the tag to a different
         // height on every card. In a graph grid that makes the row unscannable.
         justifyContent: 'flex-start',
-        gap: 3,
+        gap: CARD_GAP,
         padding: pillInset ? '10px 30px' : '10px 12px',
         borderRadius: shape.radius,
         background: theme.colors.backgroundSecondary ?? theme.colors.background,
@@ -362,6 +496,10 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
           justifyContent: centered ? 'center' : 'space-between',
           gap: 6,
           height: LABEL_SLOT_H,
+          // Without this the slot shrinks when the content exceeds the card's fixed
+          // height, and `descriptionLineBudget`'s chrome stops being the chrome —
+          // measured at 39.11px instead of 40 the moment the description ran long.
+          flexShrink: 0,
           minWidth: 0,
         }}
       >
@@ -414,6 +552,10 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
           letterSpacing: 0.5,
           textTransform: 'uppercase',
           minWidth: 0,
+          // Pinned, like the label slot above it: an empty row would otherwise be
+          // zero-height and the description budget would have to guess which cards
+          // have a technology row. Empty stays zero — a person has no technology.
+          ...(hasTechRow ? { height: TECH_SLOT_H, flexShrink: 0 } : {}),
         }}
       >
         {topLabel && (
@@ -447,16 +589,25 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
           </span>
         )}
       </span>
-      {showDescription && subtitle && (
+      {showDescription && subtitle && descLines > 0 && (
         <span
           style={{
             fontFamily: theme.fonts.monospace,
             fontSize: theme.fontSizes[0],
             color: muted,
-            lineHeight: 1.35,
+            lineHeight: DESC_LINE_HEIGHT,
             whiteSpace: 'normal',
             overflowWrap: 'anywhere',
             textAlign: centered ? 'center' : 'left',
+            // Clamped to the room the layout left for it. The card's height is a
+            // contract with ELK — the boundary and every edge endpoint are placed
+            // against it — so the description cannot be allowed to grow the box.
+            // Same mechanism the label uses above; the count is derived from the
+            // reserved height rather than tuned by hand.
+            display: '-webkit-box',
+            WebkitLineClamp: descLines,
+            WebkitBoxOrient: 'vertical',
+            overflow: 'hidden',
           }}
         >
           {subtitle}
@@ -475,13 +626,13 @@ export function C4NodeCard({ node, selected = false, handles, onClick, component
           aria-label="Show components"
           style={{
             position: 'absolute',
-            right: 6,
-            bottom: 6,
+            right: TOGGLE_INSET,
+            bottom: TOGGLE_INSET,
             display: 'inline-flex',
             alignItems: 'center',
             justifyContent: 'center',
-            width: 22,
-            height: 22,
+            width: TOGGLE_SIZE,
+            height: TOGGLE_SIZE,
             padding: 0,
             borderRadius: 4,
             border: `1px solid ${style.color}`,

package/src/subsystem/c4.ts

@@ -170,23 +170,23 @@ export interface C4Group {
  * 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.
+ * component view, or when it is one of the opened containers. 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'>,
+  model: Pick<C4Model, 'view' | 'system' | 'nodes'> & OpenState,
 ): 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;
+  const opened = new Set(openContainerSet(model));
   // 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;
+    model.view === 'component' || opened.has(containerId);
 
   const framedContainers: string[] = [];
   for (const c of containers) {
@@ -294,7 +294,7 @@ export function protocolColor(protocol: string | undefined): string {
  * 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.
+ * or opened via `openContainerIds`), never a separately-authored thing.
  */
 export interface C4Model {
   view: C4View;
@@ -302,13 +302,52 @@ export interface C4Model {
   nodes: C4Element[];
   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.
+   * Drill-down scope: the containers whose components are shown nested inside
+   * them as a grown card. Absent/empty → every container is drawn as a plain box
+   * and all components are hidden. The renderer derives the frames either way.
+   *
+   * Several may be open at once: each is an independent ELK parent, and opening
+   * one never closes another. Order is not significant — {@link openContainerSet}
+   * normalizes it, so two permutations of the same set are one layout.
+   */
+  openContainerIds?: readonly string[];
+  /**
+   * Single-container shorthand for {@link C4Model.openContainerIds}, folded into
+   * it by {@link openContainerSet}. Kept because `C4Model` is a published type
+   * and removing the field would break every caller at once; prefer the plural,
+   * which is what the drill-down actually means now.
+   *
+   * @deprecated Use {@link C4Model.openContainerIds}.
    */
   openContainerId?: string | null;
 }
 
+/** Anything that can say which containers are open, however it says it. */
+type OpenState = Pick<C4Model, 'openContainerId' | 'openContainerIds'>;
+
+/**
+ * The open containers as a deduplicated, **sorted** list.
+ *
+ * Sorted on purpose: this doubles as the layout cache key, and two callers that
+ * open the same containers in a different order are in the same state — one
+ * layout, not two. A plain `Set` iteration order would follow insertion, so
+ * `[a, b]` and `[b, a]` would each compute their own ELK run for a diagram that
+ * did not change.
+ */
+export function openContainerSet(state: OpenState): string[] {
+  const ids = new Set<string>(state.openContainerIds ?? []);
+  if (state.openContainerId) ids.add(state.openContainerId);
+  return [...ids].sort();
+}
+
+/**
+ * Cache key for one open state. `''` is the closed diagram, which is why it is a
+ * join and not a count.
+ */
+export function openStateKey(openIds: readonly string[]): string {
+  return openIds.join(',');
+}
+
 /**
  * `owner/name` from a purl, trimmed of scheme and fragment. Used to label the
  * system frame when a repo key is known.

package/src/utils/elkLayout.test.ts

@@ -171,6 +171,29 @@ describe('planCompoundGroups', () => {
     expect(plan.skipped).toEqual(['proc']);
   });
 
+  test('carries the parent chrome padding through, all three pads', () => {
+    // `computeElkLayout` turns these into ELK's `elk.padding` on the parent. If
+    // they stop here the parent is fitted to its children alone, and chrome drawn
+    // around the content — the grown container's label slot, its collapse
+    // affordance, the inset that separates nested cards from its edges — is lost.
+    const plan = planCompoundGroups(
+      [{ id: 'host', memberIds: ['a', 'b'], padTop: 84, padBottom: 36, padX: 36 }],
+      ['a', 'b'],
+    );
+    expect(plan.built[0]!.padTop).toBe(84);
+    expect(plan.built[0]!.padBottom).toBe(36);
+    expect(plan.built[0]!.padX).toBe(36);
+  });
+
+  test('leaves the padding unset when the group asks for none', () => {
+    // Unset, not zero: `computeElkLayout` falls back to the default 12px, so a
+    // group that never asked for chrome keeps the padding it always had.
+    const plan = planCompoundGroups([{ id: 'proc', memberIds: ['a', 'b'] }], ['a', 'b']);
+    expect(plan.built[0]!.padTop).toBeUndefined();
+    expect(plan.built[0]!.padBottom).toBeUndefined();
+    expect(plan.built[0]!.padX).toBeUndefined();
+  });
+
   test('counts leaves through nested groups', () => {
     // process → module(one leaf) is still a single leaf, so both drop by
     // default even though the process lists one member id.

package/src/utils/elkLayout.ts

@@ -593,6 +593,23 @@ export interface CompoundGroupDef {
    * partition set on the parent itself is ignored.
    */
   padTop?: number;
+  /**
+   * Space reserved below the last child, in px — the `padTop` of the other end.
+   * Set it when the parent draws chrome at the bottom that its children must clear,
+   * e.g. the drill-down's absolutely-positioned collapse affordance, which takes
+   * no space in flow and so is invisible to ELK unless it is reserved here.
+   *
+   * Falls back to the same default padding as the other three sides.
+   */
+  padBottom?: number;
+  /**
+   * Space reserved to the left *and* right of the children, in px. One number for
+   * both sides because a parent that insets its contents does so symmetrically —
+   * there is no chrome that lives on one side only.
+   *
+   * Falls back to the default padding.
+   */
+  padX?: number;
 }
 
 /** Which groups ELK builds, and which it drops. */
@@ -601,7 +618,14 @@ 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; padTop?: number }>;
+  built: Array<{
+    id: string;
+    childIds: string[];
+    minWidth?: number;
+    padTop?: number;
+    padBottom?: number;
+    padX?: number;
+  }>;
   /**
    * Dropped groups. Their members are promoted into the nearest built
    * ancestor, so callers must clear those members' `parentId`.
@@ -703,6 +727,8 @@ export function planCompoundGroups(
         // Carried through, not just validated here: the caller turns each of
         // these into ELK layout options on the parent node.
         padTop: g.padTop,
+        padBottom: g.padBottom,
+        padX: g.padX,
       });
     }
     if (!progress) {
@@ -933,16 +959,18 @@ export async function computeElkLayout(
     // edge by ~13px) plus a gap before the first child.
     'elk.padding': '[top=64,left=24,bottom=24,right=24]',
     'elk.spacing.nodeNode': '40',
-    // Edges inside a frame host labels too, so the frame's own layout has to
-    // reserve the same room the root does — otherwise a nested graph (C4 puts
-    // every box in the system frame) lays its edges out with the label space
-    // ignored, and a 140px chip overflows a ~72px gap. `EDGE_LABEL_EDGE_GAP` is
-    // the full reserved width (label box + clearance at each end); labels off
+    // Edges inside a frame host labels too, so the frame reserves the same
+    // between-layer clearance the root does — the caller's `interLayerSpacing`.
+    //
+    // The reserved label box already carries the chip width plus
+    // `EDGE_LABEL_SIDE_PADDING` at each end (see `elkEdge.labels` below), and
+    // CENTER_LAYER applies this spacing on *both* sides of that label layer.
+    // Setting the full `width + 2 * padding` here therefore stacked a second
+    // box on top of the first: the same two nodes measured a 612px gap inside a
+    // process frame vs 268px at the root. Per-side clearance only; labels off
     // falls back to a plain between-layer gap.
     'elk.layered.spacing.nodeNodeBetweenLayers': String(
-      edgeLabels?.enabled === false
-        ? 40
-        : (edgeLabels?.width ?? EDGE_LABEL_WIDTH) + EDGE_LABEL_SIDE_PADDING * 2,
+      edgeLabels?.enabled === false ? 40 : (options.interLayerSpacing ?? 0),
     ),
   };
   // Match the root's inline-label reservation, so ELK inside the frame leaves a
@@ -1008,10 +1036,13 @@ export async function computeElkLayout(
       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.padTop != null || g.padBottom != null || g.padX != null) {
+      // Reserving the parent's own chrome. Children then sit inside it, and the
+      // parent's size still comes from ELK's fit. Each side falls back to the
+      // default padding, so setting only one side keeps the others as they were
+      // rather than collapsing them to zero.
+      sizeOptions['elk.padding'] =
+        `[top=${g.padTop ?? 12},left=${g.padX ?? 12},bottom=${g.padBottom ?? 12},right=${g.padX ?? 12}]`;
     }
     builtGroups.set(g.id, {
       id: g.id,