@principal-ai/subsystems-react 0.53.0 → 0.53.2

package/src/stories/Subsystem/C4Graph/C4CardGrow.stories.tsx

@@ -0,0 +1,125 @@
+import React, { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { C4NodeCard, NODE_W, NODE_H } from '../../../subsystem/C4NodeCard';
+import type { C4Container, C4Component } from '../../../subsystem/c4';
+
+const meta = {
+  title: 'Subsystem/C4Graph/C4CardGrow',
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Isolated grow/shrink of one container card — no graph, no frames, no
+// components. Toggling the expand affordance animates the card's own size
+// between the box dimensions and an expanded rectangle, so the FLIP motion can
+// be judged on its own.
+// ---------------------------------------------------------------------------
+
+const GROWN_W = 420;
+const GROWN_H = 300;
+
+const card: C4Container = {
+  kind: 'container',
+  id: 'container:studio-host',
+  label: 'Subsystem Studio — host',
+  containerKind: 'application',
+  technology: 'Bun + Electrobun',
+  description: 'Owns the model store on disk and serves the renderer over RPC.',
+  state: 'accepted',
+  parentId: 'system:acme',
+};
+
+const COMPONENTS: C4Component[] = [
+  {
+    kind: 'component',
+    id: 'component:audit-verification',
+    label: 'Audit & verification',
+    container: card.id,
+    technology: 'Bun',
+    description: 'Checks a subsystem model and reports what is wrong.',
+    state: 'accepted',
+  },
+  {
+    kind: 'component',
+    id: 'component:model-store',
+    label: 'Model store I/O',
+    container: card.id,
+    technology: 'Bun fs',
+    description: 'Reads and writes model JSON under ~/.principal.',
+    state: 'accepted',
+  },
+];
+
+function Demo() {
+  const [open, setOpen] = useState(false);
+  const [grown, setGrown] = useState(false);
+  // True when the card has finished shrinking back to its box — only then is the
+  // description shown again (it stays hidden through open *and* the shrink).
+  const [settled, setSettled] = useState(true);
+  return (
+    <div
+      style={{
+        width: '100%',
+        height: '100vh',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        background: '#12141a',
+      }}
+    >
+      <div
+        onTransitionEnd={(e) => {
+          // The card's own size transition bubbles here.
+          if (e.propertyName !== 'width') return;
+          if (open) setGrown(true);
+          else setSettled(true);
+        }}
+      >
+        <C4NodeCard
+          node={card}
+          width={open ? GROWN_W : NODE_W}
+          height={open ? GROWN_H : NODE_H}
+          showDescription={settled}
+          onExpand={() => {
+            // Leaving the resting state: hide the description immediately.
+            setSettled(false);
+            if (open) setGrown(false);
+            setOpen((v) => !v);
+          }}
+        >
+          {grown && (
+            <div
+              style={{
+                display: 'grid',
+                gridTemplateColumns: '1fr 1fr',
+                gap: 10,
+                marginTop: 8,
+                minHeight: 0,
+              }}
+            >
+              {COMPONENTS.map((c) => (
+                <C4NodeCard key={c.id} node={c} />
+              ))}
+            </div>
+          )}
+        </C4NodeCard>
+      </div>
+    </div>
+  );
+}
+
+export const Grow: Story = {
+  render: () => <Demo />,
+};

package/src/stories/Subsystem/C4Graph/C4Component.stories.tsx

@@ -3,7 +3,7 @@ import '@xyflow/react/dist/style.css';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { C4Graph } from '../../../subsystem/C4Graph';
-import type { C4Edge, C4Group, C4Model, C4Element, C4Component } from '../../../subsystem/c4';
+import type { C4Edge, C4Model, C4Element, C4Component, C4Container } from '../../../subsystem/c4';
 
 const meta = {
   title: 'Subsystem/C4Graph/C4Component',
@@ -53,7 +53,25 @@ function component(
   };
 }
 
+/** A container element. Its components make it frame in the renderer. */
+function container(over: Partial<C4Container> & Pick<C4Container, 'id' | 'label'>): C4Element {
+  return {
+    kind: 'container',
+    containerKind: 'application',
+    technology: '',
+    state: 'accepted',
+    members: [],
+    constructs: [],
+    parentId: SYSTEM.id,
+    ...over,
+  };
+}
+
 const NODES: C4Element[] = [
+  // --- the containers these components sit in ------------------------------
+  container({ id: HOST, label: 'Subsystem Studio — host', technology: 'Bun + Electrobun' }),
+  container({ id: RENDERER, label: 'Subsystem Studio — renderer', technology: 'React 19' }),
+
   // --- inside the host ------------------------------------------------------
   component({
     id: 'component:audit-verification',
@@ -131,13 +149,6 @@ const NODES: C4Element[] = [
   }),
 ];
 
-/** The two containers at this level, drawn as frames. */
-const GROUPS: C4Group[] = [
-  { id: HOST, kind: 'container', label: 'Subsystem Studio — host', parentId: SYSTEM.id, memberIds: NODES.filter((n) => n.parentId === HOST).map((n) => n.id) },
-  { id: RENDERER, kind: 'container', label: 'Subsystem Studio — renderer', parentId: SYSTEM.id, memberIds: NODES.filter((n) => n.parentId === RENDERER).map((n) => n.id) },
-  { id: SYSTEM.id, kind: 'system', label: SYSTEM.label, memberIds: [HOST, RENDERER] },
-];
-
 /** A line between components — protocol-labelled, like the container view. */
 function edge(id: string, source: string, target: string, protocol: string): C4Edge {
   return { id, source, target, label: protocol, protocol, mechanisms: [], count: 1 };
@@ -158,7 +169,6 @@ const componentModel: C4Model = {
   view: 'component',
   system: SYSTEM,
   nodes: NODES,
-  groups: GROUPS,
   edges: EDGES,
 };
 
@@ -170,7 +180,7 @@ function Demo() {
   return (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <div style={{ flex: 1, minHeight: 0, position: 'relative' }}>
-        <C4Graph model={model} title="Subsystem Modeling" onSelectNode={setSelected} />
+        <C4Graph model={model} onSelectNode={setSelected} />
       </div>
       <div
         style={{
@@ -184,7 +194,7 @@ function Demo() {
           borderTop: '1px solid #333',
         }}
       >
-        <span>{components} components in {model.groups.filter((g) => g.kind === 'container').length} containers</span>
+        <span>{components} components in {model.nodes.filter((n) => n.kind === 'container').length} containers</span>
         <span>{model.edges.length} lines</span>
         <span>selected: {selected ?? '(none)'}</span>
         <span style={{ color: '#777' }}>each component is a grouping stitched across many models</span>

package/src/stories/Subsystem/C4Graph/C4Container.stories.tsx

@@ -195,14 +195,6 @@ const containerModel: C4Model = {
   view: 'container',
   system: SYSTEM,
   nodes: NODES,
-  groups: [
-    {
-      id: SYSTEM.id,
-      kind: 'system',
-      label: SYSTEM.label,
-      memberIds: NODES.filter((n) => n.parentId === SYSTEM.id).map((n) => n.id),
-    },
-  ],
   edges: EDGES,
 };
 
@@ -218,7 +210,7 @@ function Demo() {
   return (
     <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
       <div style={{ flex: 1, minHeight: 0, position: 'relative' }}>
-        <C4Graph model={model} title="Subsystem Modeling" onSelectNode={setSelected} />
+        <C4Graph model={model} onSelectNode={setSelected} />
       </div>
       <div
         style={{

package/src/stories/Subsystem/C4Graph/C4Transition.stories.tsx

@@ -0,0 +1,132 @@
+import React, { useMemo, useState } from 'react';
+import '@xyflow/react/dist/style.css';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { C4Graph } from '../../../subsystem/C4Graph';
+import type { C4Edge, C4Model, C4Element, C4Component, C4Container } from '../../../subsystem/c4';
+
+const meta = {
+  title: 'Subsystem/C4Graph/C4Transition',
+  component: C4Graph,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof C4Graph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Drill-down: two layouts, one transition.
+//
+// Closed, the container is a box. Its expand affordance (bottom-right) opens it,
+// and the graph swaps to a *second, already-computed* layout in which the same
+// element is an ELK parent — so ELK sizes it to hold its own components, and they
+// arrive as nested cards. The same affordance closes it again.
+//
+// Nothing is a frame here: the container stays a card and grows (its own
+// width/height transition), and the system frame around it grows with it — also
+// by size, since it is a real ELK parent and ELK owns both its origin and its fit.
+// Components stay hidden until the grow settles, and the card's description
+// returns only after the shrink — hence the two settled states below.
+//
+// The story also carries component→component edges, which the nested layout
+// routes inside the parent.
+// ---------------------------------------------------------------------------
+
+const SYSTEM = { id: 'system:acme', label: 'Subsystem Modeling', repoKey: 'pkg:github/acme/subsystem-modeling' };
+const HOST = 'container:studio-host';
+
+function container(over: Partial<C4Container> & Pick<C4Container, 'id' | 'label'>): C4Element {
+  return {
+    kind: 'container',
+    containerKind: 'application',
+    technology: '',
+    state: 'accepted',
+    members: [],
+    constructs: [],
+    parentId: SYSTEM.id,
+    ...over,
+  };
+}
+
+function component(
+  over: Partial<C4Component> & Pick<C4Component, 'id' | 'label' | 'container'>,
+): C4Element {
+  return {
+    kind: 'component',
+    members: [],
+    constructs: [],
+    state: 'accepted',
+    parentId: over.container,
+    technology: 'Bun',
+    ...over,
+  };
+}
+
+const NODES: C4Element[] = [
+  container({ id: HOST, label: 'Subsystem Studio — host', technology: 'Bun + Electrobun', description: 'The Electron main process.' }),
+  component({ id: 'component:audit-verification', label: 'Audit & verification', container: HOST, description: 'Checks a model, reports problems.' }),
+  component({ id: 'component:maintain-proposals', label: 'Maintain & proposals', container: HOST, description: 'Runs the maintain agent, records proposals.' }),
+  component({ id: 'component:model-store', label: 'Model store I/O', container: HOST, technology: 'Bun fs', description: 'Reads and writes model JSON.' }),
+];
+
+function edge(id: string, source: string, target: string, protocol: string): C4Edge {
+  return { id, source, target, label: protocol, protocol, mechanisms: [], count: 1 };
+}
+
+const EDGES: C4Edge[] = [
+  edge('e:audit-store', 'component:audit-verification', 'component:model-store', 'fs · JSON'),
+  edge('e:proposals-store', 'component:maintain-proposals', 'component:model-store', 'fs · JSON'),
+];
+
+function Demo() {
+  const [openId, setOpenId] = useState<string | null>(null);
+  const [selected, setSelected] = useState<string | null>(null);
+
+  const model = useMemo<C4Model>(
+    () => ({ view: 'container', system: SYSTEM, nodes: NODES, edges: EDGES, openContainerId: openId }),
+    [openId],
+  );
+
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <div style={{ flex: 1, minHeight: 0, position: 'relative' }}>
+        <C4Graph
+          model={model}
+          onSelectNode={setSelected}
+          onOpenContainer={setOpenId}
+          onCloseContainer={() => setOpenId(null)}
+        />
+      </div>
+      <div
+        style={{
+          padding: '6px 12px',
+          display: 'flex',
+          alignItems: 'center',
+          gap: 18,
+          fontFamily: 'monospace',
+          fontSize: 12,
+          color: '#aaa',
+          borderTop: '1px solid #333',
+        }}
+      >
+        <span>{openId ? `opened: ${openId}` : 'closed'}</span>
+        <span>selected: {selected ?? '(none)'}</span>
+        <span style={{ color: '#777' }}>
+          the expand icon (bottom-right of the container) opens it, and closes it again
+        </span>
+      </div>
+    </div>
+  );
+}
+
+export const DrillDown: Story = {
+  render: () => <Demo />,
+};

package/src/subsystem/C4Graph.groups.test.ts

@@ -0,0 +1,217 @@
+/**
+ * The nesting the drill-down's stability rests on.
+ *
+ * The 206px "moves down" report was not a FLIP bug or a camera bug — it was the
+ * software-system boundary having no position of its own. Flattened, the frame was
+ * synthesized as a union of its members' bounds, so it inherited their top edge and
+ * slid whenever ELK re-placed one of them. Making it a real ELK parent fixed it,
+ * and only because the opened container nests *inside* it.
+ *
+ * None of this is visible in the rendered output: get the nesting wrong and the
+ * graph still draws, just wrong. So it is asserted here instead. `c4GroupDefs` is
+ * pure and needs no ELK — the layout half it feeds is covered by the node e2e.
+ */
+import { describe, expect, test } from 'bun:test';
+import { c4GroupDefs, rebaseGroupBoundsAbsolute, showDescriptionFor } from './C4Graph';
+import type { C4Element, C4Model } from './c4';
+
+const SYSTEM = 'system:studio';
+
+const container = (id: string): C4Element => ({
+  id,
+  kind: 'container',
+  label: id,
+  parentId: SYSTEM,
+});
+const component = (id: string, of: string): C4Element => ({
+  id,
+  kind: 'component',
+  label: id,
+  container: of,
+});
+
+/** A container view: two containers, one of them with components. */
+function model(nodes: C4Element[]): C4Model {
+  return {
+    view: 'container',
+    system: { id: SYSTEM, label: 'Studio' },
+    nodes,
+    edges: [],
+  };
+}
+
+const HOST = 'container:host';
+const NOTES = 'container:notes';
+const base = model([
+  container(HOST),
+  container(NOTES),
+  component('cmp:a', HOST),
+  component('cmp:b', HOST),
+]);
+
+const groupById = (defs: ReturnType<typeof c4GroupDefs>['groups']) =>
+  new Map(defs.map((g) => [g.id, g]));
+
+describe('c4GroupDefs — the system boundary', () => {
+  test('is a group of its own, even with nothing open', () => {
+    const { groups } = c4GroupDefs(base, null);
+    expect(groupById(groups).has(SYSTEM)).toBe(true);
+  });
+
+  test('holds the containers, and not the things outside the boundary', () => {
+    const withOutsiders = model([
+      ...base.nodes,
+      { id: 'external:github', kind: 'external-system', label: 'GitHub' },
+      { id: 'person:dev', kind: 'person', label: 'Dev' },
+    ]);
+    const system = groupById(c4GroupDefs(withOutsiders, null).groups).get(SYSTEM)!;
+    // People and external systems sit outside the boundary — that is what the
+    // boundary means — so they must not be laid out as its contents.
+    expect(system.memberIds).toEqual([HOST, NOTES]);
+  });
+
+  test('is not dropped when a container opens', () => {
+    // The frame must not shrink to the opened container: it is the *system*
+    // boundary, and the open state adds a container inside it, not replaces it.
+    const { groups } = c4GroupDefs(base, HOST);
+    const system = groupById(groups).get(SYSTEM)!;
+    expect(system.memberIds).toContain(HOST);
+    expect(system.memberIds).toContain(NOTES);
+  });
+});
+
+describe('c4GroupDefs — the opened container', () => {
+  test('nests inside the system frame, not beside it', () => {
+    // The load-bearing assertion. As a sibling it is laid out from the root, the
+    // frame is no longer the origin of its contents, and the boundary's corner
+    // stops being pinned across the two layouts.
+    const { groups } = c4GroupDefs(base, HOST);
+    const open = groupById(groups).get(HOST)!;
+    expect(open.parentId).toBe(SYSTEM);
+  });
+
+  test('is drawn as a card as well as laid out as a group', () => {
+    // It has a node (the card we click) *and* a group (the parent ELK sizes to
+    // hold its components). Without the flag, ELK takes the bare leaf box.
+    const open = groupById(c4GroupDefs(base, HOST).groups).get(HOST)!;
+    expect(open.drawnAsCard).toBe(true);
+  });
+
+  test('lists its components, and reserves room for its own chrome', () => {
+    const open = groupById(c4GroupDefs(base, HOST).groups).get(HOST)!;
+    expect(open.memberIds).toEqual(['cmp:a', 'cmp:b']);
+    // Its label slot and technology row, so children land below them.
+    expect(open.padTop).toBeGreaterThan(0);
+    // Never narrower than the closed card: opening only grows the box.
+    expect(open.minWidth).toBeGreaterThan(0);
+  });
+
+  test('is absent when nothing is open, so the closed card stays a leaf', () => {
+    // The closed container is a plain node — no group. The group's whole purpose is
+    // to hold components, and there are none in view.
+    expect(groupById(c4GroupDefs(base, null).groups).has(HOST)).toBe(false);
+  });
+
+  test('adds no group for a container with no components in view', () => {
+    const { groups } = c4GroupDefs(model([container(NOTES)]), NOTES);
+    expect(groupById(groups).has(NOTES)).toBe(false);
+  });
+});
+
+describe('c4GroupDefs — frames', () => {
+  test('the opened container is not also drawn as a frame', () => {
+    // It is drawn as a grown card. Leaving it in `frames` would draw a frame
+    // around the card.
+    const { frames } = c4GroupDefs(base, HOST);
+    expect(frames.map((g) => g.id)).not.toContain(HOST);
+  });
+
+  test('frames feed the bands, so they exclude the opened container too', () => {
+    // Bands come from frames only. Counting the opened container as a frame would
+    // give it its own layer, away from the containers it belongs beside.
+    const { frames } = c4GroupDefs(base, HOST);
+    expect(frames).toEqual([expect.objectContaining({ id: SYSTEM, kind: 'system' })]);
+  });
+
+  test('the component view keeps a frame per container with components', () => {
+    const componentView: C4Model = { ...base, view: 'component' };
+    const { frames } = c4GroupDefs(componentView, null);
+    expect(frames.map((g) => g.id)).toContain(HOST);
+    // Those frames nest inside the system boundary.
+    expect(frames.find((g) => g.id === HOST)?.parentId).toBe(SYSTEM);
+  });
+});
+
+describe('rebaseGroupBoundsAbsolute', () => {
+  // Real numbers from the drill-down: the system frame sits at (12,12), and the
+  // opened container nests inside it, so ELK reports it 24px/64px in — offset by
+  // the frame's own 12,12 plus its 12px padding.
+  const result = () => ({
+    groupBounds: new Map([
+      [SYSTEM, { x: 12, y: 12, width: 298, height: 874 }],
+      [HOST, { x: 24, y: 64, width: 250, height: 596 }],
+    ]),
+    absoluteRects: new Map([
+      [SYSTEM, { x: 12, y: 12, width: 298, height: 874 }],
+      [HOST, { x: 36, y: 76, width: 250, height: 596 }],
+    ]),
+  });
+
+  test('lifts a nested group out of its parent origin', () => {
+    const rebased = rebaseGroupBoundsAbsolute(result());
+    // Unrebased, `containerRect` would read (24,64) and the morph would glide the
+    // container to a place it was never drawn.
+    expect(rebased.get(HOST)).toEqual({ x: 36, y: 76, width: 250, height: 596 });
+  });
+
+  test('leaves a root-level group alone', () => {
+    const rebased = rebaseGroupBoundsAbsolute(result());
+    expect(rebased.get(SYSTEM)).toEqual({ x: 12, y: 12, width: 298, height: 874 });
+  });
+
+  test('keeps a flat frame, which has no node and is already absolute', () => {
+    // Flat frames are synthesized from absolute member bounds and have no entry in
+    // `absoluteRects` — they must survive rather than drop out.
+    const r = result();
+    r.groupBounds.set('flat', { x: 12, y: 402, width: 274, height: 150 });
+    const rebased = rebaseGroupBoundsAbsolute(r);
+    expect(rebased.get('flat')).toEqual({ x: 12, y: 402, width: 274, height: 150 });
+  });
+
+  test('does not mutate the layout result', () => {
+    // `computeElkLayout`'s own result is read elsewhere in its native mixed space.
+    const r = result();
+    rebaseGroupBoundsAbsolute(r);
+    expect(r.groupBounds.get(HOST)).toEqual({ x: 24, y: 64, width: 250, height: 596 });
+  });
+
+  test('keeps every entry — no group is lost in the translation', () => {
+    const rebased = rebaseGroupBoundsAbsolute(result());
+    expect([...rebased.keys()].sort()).toEqual([SYSTEM, HOST].sort());
+  });
+});
+
+describe('showDescriptionFor', () => {
+  test('a plain card shows its description', () => {
+    expect(showDescriptionFor(false, true)).toBe(true);
+  });
+
+  test('no description while a morph is in flight', () => {
+    // The card is resizing underneath it; the line would slide across a moving box.
+    expect(showDescriptionFor(false, false)).toBe(false);
+  });
+
+  test('an expanded container never shows it, however long it has settled', () => {
+    // The regression: keying only on `settled` brought the line back the moment the
+    // grow finished, into the space the components now occupy. ELK reserves header
+    // chrome only, so it landed on top of the first component rather than above it.
+    expect(showDescriptionFor(true, true)).toBe(false);
+    expect(showDescriptionFor(true, false)).toBe(false);
+  });
+
+  test('an unset open flag is not "open"', () => {
+    // `open` is undefined until the layout stamps it, so `undefined` must not be
+    // read as truthy — that would hide descriptions on every card, always.
+    expect(showDescriptionFor(undefined, true)).toBe(true);
+  });
+});