@principal-ai/subsystems-react 0.56.12 → 0.56.13

package/src/stories/Canvases/C4/C4Draft.stories.tsx

@@ -0,0 +1,238 @@
+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 { C4ConstructGraph } from '../../../subsystem/C4Graph';
+import type { C4Edge, C4Element, C4Model } from '../../../subsystem/c4';
+import {
+  DRILLDOWN_COMPONENTS,
+  DRILLDOWN_PURL,
+  DRILLDOWN_TRAILS,
+} from '../../../subsystem/__fixtures__/c4Drilldown';
+
+const meta = {
+  title: 'Canvases/C4/C4Draft',
+  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>;
+
+// ---------------------------------------------------------------------------
+// The minimal C4: no accepted containers, no authored components.
+//
+// Every box is derived from the model itself:
+//
+//   - one *draft* container per runtime `process` key (members resolve by
+//     exact process match, the rule accepted containers use);
+//   - a file-less / external process becomes an external system, so lines
+//     leaving the boundary have somewhere to land;
+//   - lines are the fold of cross-boundary trail steps, labelled by
+//     mechanism;
+//   - each opened container hosts its member constructs directly, because no
+//     C4 component layer exists to group them.
+//
+// Nothing here claims verification. This is what the API's `source=draft`
+// projection looks like: a reading of the model, not a stored decision.
+// ---------------------------------------------------------------------------
+
+const SYSTEM = {
+  id: 'system:draft',
+  label: 'Gist share from Studio',
+  repoKey: DRILLDOWN_PURL,
+};
+
+const byAlias = new Map(DRILLDOWN_COMPONENTS.map((c) => [c.alias, c]));
+
+/** `local/disk` → `local-disk`; keeps ids readable in the story. */
+function slug(value: string): string {
+  return value.replace(/[^a-zA-Z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+interface DraftElement {
+  element: C4Element;
+  members: string[];
+}
+
+const elements: C4Element[] = [];
+const membersByElement = new Map<string, string[]>();
+const elementOfAlias = new Map<string, string>();
+
+const byProcess = new Map<string, string[]>();
+for (const component of DRILLDOWN_COMPONENTS) {
+  const process = component.process?.trim();
+  if (!process) continue;
+  const list = byProcess.get(process) ?? [];
+  list.push(component.alias);
+  byProcess.set(process, list);
+}
+
+const drafts: DraftElement[] = [];
+for (const [process, members] of byProcess) {
+  // A process with no grounded code behind it is not a deployable unit: it is
+  // the model's way of naming something outside the boundary.
+  const fileless = members.every((alias) => !byAlias.get(alias)?.file);
+  const external =
+    fileless || process.startsWith('external/') || process.startsWith('local/');
+
+  if (external) {
+    const element: C4Element = {
+      kind: 'external-system',
+      id: `external:${slug(process)}`,
+      label: process,
+      members,
+      technology: byAlias.get(members[0] ?? '')?.framework ?? 'external',
+      state: 'accepted',
+      description: `${members.length} member${members.length === 1 ? '' : 's'} outside the boundary.`,
+    };
+    elements.push(element);
+    drafts.push({ element, members });
+    membersByElement.set(element.id, members);
+  } else {
+    const element: C4Element = {
+      kind: 'container',
+      id: `container:${slug(process)}`,
+      label: process,
+      containerKind: members.some((alias) => byAlias.get(alias)?.construct === 'store')
+        ? 'data-store'
+        : 'application',
+      technology: byAlias.get(members[0] ?? '')?.framework ?? '',
+      process,
+      parentId: SYSTEM.id,
+      state: 'accepted',
+      description: `${members.length} component${members.length === 1 ? '' : 's'} derived from process ${process}.`,
+    };
+    elements.push(element);
+    drafts.push({ element, members });
+    membersByElement.set(element.id, members);
+  }
+  for (const alias of members) elementOfAlias.set(alias, elements[elements.length - 1]!.id);
+}
+
+const containers = drafts.filter((d) => d.element.kind === 'container');
+const externals = drafts.filter((d) => d.element.kind === 'external-system');
+
+// Fold cross-boundary trail steps into lines. Same rule the accepted-store
+// projection uses; only the membership source differs.
+const edges: C4Edge[] = (() => {
+  const byKey = new Map<
+    string,
+    { source: string; target: string; mechanism: string; refs: Map<string, number[]> }
+  >();
+  for (const trail of DRILLDOWN_TRAILS) {
+    trail.steps.forEach((step, index) => {
+      const source = elementOfAlias.get(step.from);
+      const target = elementOfAlias.get(step.to);
+      if (!source || !target || source === target) return;
+      const key = [source, target, step.mechanism].join('\0');
+      let acc = byKey.get(key);
+      if (!acc) {
+        acc = { source, target, mechanism: step.mechanism, refs: new Map() };
+        byKey.set(key, acc);
+      }
+      const steps = acc.refs.get(trail.id) ?? [];
+      steps.push(index);
+      acc.refs.set(trail.id, steps);
+    });
+  }
+  return [...byKey.values()].map((acc) => ({
+    id: `e:${slug(acc.source)}-${slug(acc.target)}-${acc.mechanism}`,
+    source: acc.source,
+    target: acc.target,
+    label: acc.mechanism,
+    protocol: acc.mechanism,
+    mechanisms: [acc.mechanism],
+    count: [...acc.refs.values()].reduce((n, steps) => n + steps.length, 0),
+    trailRefs: [...acc.refs.entries()].map(([trailId, stepIndices]) => ({
+      trailId,
+      stepIndices,
+    })),
+  }));
+})();
+
+// No `componentOf`: the constructs nest directly under their container.
+const constructGraphByContainer = new Map<string, C4ConstructGraph>();
+for (const draft of containers) {
+  const members = membersByElement.get(draft.element.id) ?? [];
+  constructGraphByContainer.set(draft.element.id, {
+    components: members
+      .map((alias) => byAlias.get(alias))
+      .filter((c): c is NonNullable<typeof c> => Boolean(c)),
+    trails: DRILLDOWN_TRAILS,
+  });
+}
+
+const allContainerIds = containers.map((d) => d.element.id);
+
+function Demo() {
+  const [openIds, setOpenIds] = useState<string[]>(allContainerIds);
+
+  const model = useMemo<C4Model>(
+    () => ({
+      view: 'container',
+      system: SYSTEM,
+      nodes: elements,
+      edges,
+      openContainerIds: openIds,
+    }),
+    [openIds],
+  );
+
+  const toggle = (id: string) =>
+    setOpenIds((prev) =>
+      prev.includes(id) ? prev.filter((x) => x !== id) : [...prev, id].sort(),
+    );
+
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 16,
+          padding: '7px 12px',
+          borderBottom: '1px solid #333',
+          background: '#1b1b1b',
+          color: '#aaa',
+          fontFamily: 'ui-monospace, monospace',
+          fontSize: 12,
+        }}
+      >
+        <strong style={{ color: '#e3b341' }}>DRAFT</strong>
+        <span>
+          no accepted containers — {containers.length} derived from process keys,{' '}
+          {externals.length} externals, {edges.length} lines
+        </span>
+        <span style={{ marginLeft: 'auto', display: 'flex', gap: 6 }}>
+          <button type="button" onClick={() => setOpenIds(allContainerIds)}>
+            Open all
+          </button>
+          <button type="button" onClick={() => setOpenIds([])}>
+            Collapse all
+          </button>
+        </span>
+      </div>
+      <div style={{ flex: 1, minHeight: 0, position: 'relative' }}>
+        <C4Graph
+          model={model}
+          onToggleContainer={toggle}
+          constructGraphByContainer={constructGraphByContainer}
+        />
+      </div>
+    </div>
+  );
+}
+
+export const DraftFromProcessKeys: Story = {
+  render: () => <Demo />,
+};

package/src/subsystem/C4Graph.tsx

@@ -1383,10 +1383,16 @@ function Inner({ model, onSelectNode, onSelectEdge, onTrailClick, onToggleContai
           element: n,
           selected: false,
           componentCount: childComponentCount.get(n.id) ?? 0,
-          // A container with components opens; the same affordance closes it
-          // again, so the toggle lives in one place.
-          ...(n.kind === 'container' && (childComponentCount.get(n.id) ?? 0) > 0 && canToggle
-            ? { onExpand: () => toggle(n.id), open: opened.has(n.id) }
+          // A container with components — or with constructs hosted from the
+          // model, when no C4 component layer exists — opens; the same
+          // affordance closes it again, so the toggle lives in one place.
+          ...(n.kind === 'container' &&
+          ((childComponentCount.get(n.id) ?? 0) > 0 ||
+            (constructGraphByContainer?.get(n.id)?.components.length ?? 0) > 0)
+            ? {
+                ...(canToggle ? { onExpand: () => toggle(n.id) } : {}),
+                open: opened.has(n.id),
+              }
             : {}),
           // A component grown to hold its constructs is a drawn-as-card group:
           // no description, absolute box, sized by ELK.

package/src/subsystem/DescriptionOverlay.test.tsx

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { createElement } from 'react';
+import { Window } from 'happy-dom';
+import { cleanup, fireEvent, render } from '@testing-library/react/pure';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { SubsystemComponentGraph } from './SubsystemComponentGraph';
+
+const dom = new Window();
+const globals = globalThis as unknown as Record<string, unknown>;
+globals.window = dom;
+globals.document = dom.document;
+globals.navigator = dom.navigator;
+globals.HTMLElement = dom.HTMLElement;
+globals.SVGElement = dom.SVGElement;
+globals.Node = dom.Node;
+globals.Element = dom.Element;
+globals.Event = dom.Event;
+globals.localStorage = dom.localStorage;
+globals.ResizeObserver = dom.ResizeObserver;
+globals.getComputedStyle = dom.getComputedStyle.bind(dom);
+globals.requestAnimationFrame = dom.requestAnimationFrame.bind(dom);
+globals.cancelAnimationFrame = dom.cancelAnimationFrame.bind(dom);
+globals.matchMedia = dom.matchMedia.bind(dom);
+
+afterEach(cleanup);
+
+function renderGraph(description: string | undefined) {
+  return render(createElement(
+    ThemeProvider,
+    { theme: defaultEditorTheme },
+    createElement(SubsystemComponentGraph, {
+      components: [
+        { alias: 'entry', name: 'Entry', construct: 'function', file: 'entry.ts' },
+        { alias: 'store', name: 'Store', construct: 'function', file: 'store.ts' },
+      ],
+      trails: [{
+        id: 'request',
+        title: 'Request flow',
+        steps: [{ from: 'entry', to: 'store', mechanism: 'calls' }],
+      }],
+      description,
+    }),
+  ));
+}
+
+describe('subsystem description overlay', () => {
+  for (const closeWithEscape of [false, true]) {
+    test(`More opens the full markdown over the graph and closes with ${closeWithEscape ? 'Escape' : 'the close button'}`, () => {
+      const description = `${'A long description. '.repeat(50)}\n\n**Final detail**`;
+      const view = renderGraph(description);
+      const more = view.getByRole('button', { name: 'Read full description' });
+      more.focus();
+      fireEvent.click(more);
+      const overlay = view.getByRole('dialog', { name: 'Subsystem description' });
+      expect(overlay.textContent).toContain('A long description. '.repeat(50).trim());
+      expect(overlay.querySelector('strong')?.textContent).toBe('Final detail');
+      expect(overlay.style.position).toBe('absolute');
+      expect(overlay.parentElement?.contains(view.getByLabelText('Resize sidebar'))).toBe(false);
+      expect(more.getAttribute('aria-expanded')).toBe('true');
+      const close = view.getByRole('button', { name: 'Close description' });
+      expect(document.activeElement).toBe(close);
+      if (closeWithEscape) fireEvent.keyDown(close, { key: 'Escape' });
+      else fireEvent.click(close);
+      expect(view.queryByRole('dialog')).toBeNull();
+      expect(more.getAttribute('aria-expanded')).toBe('false');
+      expect(document.activeElement).toBe(more);
+      expect(view.getByText('Request flow')).toBeTruthy();
+    });
+  }
+
+  test('does not offer More when there is no description', () => {
+    const view = renderGraph(undefined);
+    expect(view.queryByRole('button', { name: 'Read full description' })).toBeNull();
+    expect(view.queryByRole('dialog')).toBeNull();
+  });
+});

package/src/subsystem/DescriptionOverlay.tsx

@@ -0,0 +1,101 @@
+import { useEffect, useRef } from 'react';
+import { useTheme } from '@principal-ade/industry-theme';
+import { X } from 'lucide-react';
+import { IndustryMarkdownSlide } from 'themed-markdown';
+
+export function DescriptionOverlay({ description, onClose }: {
+  description: string;
+  onClose: () => void;
+}) {
+  const { theme } = useTheme();
+  const closeRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    const previousFocus = document.activeElement;
+    closeRef.current?.focus();
+    return () => {
+      if (previousFocus instanceof HTMLElement && previousFocus.isConnected) previousFocus.focus();
+    };
+  }, []);
+
+  return (
+    <div
+      role="dialog"
+      aria-label="Subsystem description"
+      onKeyDown={(event) => {
+        if (event.key === 'Escape') {
+          event.stopPropagation();
+          onClose();
+        }
+      }}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        zIndex: 10,
+        display: 'flex',
+        flexDirection: 'column',
+        background: theme.colors.background,
+        color: theme.colors.text,
+      }}
+    >
+      <div style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 8,
+        flexShrink: 0,
+        padding: '12px 16px',
+        borderBottom: `1px solid ${theme.colors.border}`,
+      }}>
+        <h3 style={{
+          flex: 1,
+          margin: 0,
+          fontSize: theme.fontSizes[1],
+          fontFamily: theme.fonts.monospace,
+          textTransform: 'uppercase',
+          color: theme.colors.textSecondary,
+        }}>
+          Overview
+        </h3>
+        <button
+          ref={closeRef}
+          type="button"
+          aria-label="Close description"
+          onClick={onClose}
+          style={{
+            display: 'inline-flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            width: 24,
+            height: 24,
+            padding: 0,
+            border: 'none',
+            borderRadius: 4,
+            background: 'transparent',
+            color: theme.colors.textSecondary,
+            cursor: 'pointer',
+          }}
+        >
+          <X size={14} />
+        </button>
+      </div>
+      <div style={{ flex: 1, minHeight: 0, overflow: 'auto', padding: '20px 0 32px' }}>
+        <div style={{ lineHeight: 1.7 }}>
+          <IndustryMarkdownSlide
+            content={description}
+            slideIdPrefix="subsystem-desc-overlay"
+            slideIndex={0}
+            isVisible
+            theme={theme}
+            disableScroll
+            disableBasePadding
+            transparentBackground
+            additionalPadding={{ left: '24px', right: '24px' }}
+            fontSizeScale={1.05}
+            enableKeyboardScrolling={false}
+            autoFocusOnVisible={false}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/subsystem/SubsystemComponentGraph.sidebar.test.tsx

@@ -50,12 +50,19 @@ describe('subsystem graph sidebar', () => {
     expect(content?.textContent).not.toContain('Request subsystem');
   });
 
-  test('caps the scrollable description at 30% above the trails', () => {
+  test('truncates the description without scrolling and offers the full description', () => {
     const body = renderGraph();
-    const description = body.querySelector('[style*="max-height:30%"]') as HTMLElement;
+    const description = body.querySelector('[style*="-webkit-line-clamp:6"]') as HTMLElement;
     expect(description).not.toBeNull();
     expect(description.textContent).toContain('Always visible description.');
-    expect(description.style.overflowY).toBe('auto');
+    expect(description.style.overflow).toBe('hidden');
+    expect(description.style.maxHeight).toBe('9em');
+    const more = body.querySelector('button[aria-label="Read full description"]');
+    expect(more?.textContent).toBe('More');
+    expect(more?.getAttribute('aria-haspopup')).toBe('dialog');
+    expect(more?.getAttribute('aria-expanded')).toBe('false');
+    expect(body.querySelector('[role="dialog"]')).toBeNull();
+    expect(body.querySelector('[style*="max-height:30%"]')).toBeNull();
   });
 
   test('keeps the Files button in the header when no name is provided', () => {

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -89,6 +89,7 @@ import type { ComponentVerificationState } from './ComponentDeclaration';
 import type { DeclarationSymbolRef, SymbolInspection } from './symbolRefs';
 import { FileDrawer, FILE_DRAWER_HEIGHT_MS } from './FileDrawer';
 import { GraphWithSidebar } from './GraphWithSidebar';
+import { DescriptionOverlay } from './DescriptionOverlay';
 import type { GraphSidebarTab } from './GraphSidebar';
 import { TrailsPanel, TRAIL_PLAY_PAUSE_MS } from './TrailsPanel';
 import type { StepEmphasisMap } from './stepEmphasis';
@@ -618,6 +619,7 @@ interface InnerProps extends SubsystemComponentGraphProps {
 function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirection: layoutDirectionProp, defaultLayoutDirection = 'horizontal', onLayoutDirectionChange, hideLayoutToggle = false, refocusOnLayoutFlip = true, initialTrailId, onTrailSelect, onTrailStepHover, onReorderTrails, stepEmphasis, onRemoveStepEmphasis, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showSingletonFrames = true, moduleNesting, edgeView, hideSidebar, trailStepMode = 'focus', autoPlayTrails = false, trailAutoPlayIntervalMs = TRAIL_PLAY_PAUSE_MS, zoomOnTrailFocus = true, trailFocusDurationMs = 300, graphTitle, showTrailTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, issues, showIssues, filesActive, sidebarScope, onSidebarTrailChange, focusIssueCategory, laneStatus, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileViewer, renderTrailViewer, onFileSelect, componentVerification, onInspectSymbol, boundaryColors, codeProcessKeys, hideDrawer = false, persistKey, liveEvents, agentsPanel }: InnerProps) {
   const { theme } = useTheme();
   const { fitView, fitBounds } = useReactFlow();
+  const [descriptionOpen, setDescriptionOpen] = useState(false);
   const viewport = useViewport();
   // Restored once per mount from `localStorage` (see `readViewState`). Each
   // graph is its own tab/mount, so `persistKey` is stable for a mount.
@@ -2730,17 +2732,45 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       {sidebarExtra}
       {description && (
         <div style={{ fontSize: theme.fontSizes[0], lineHeight: 1.5 }}>
-          <IndustryMarkdownSlide
-            content={description}
-            slideIdPrefix="subsystem-desc"
-            slideIndex={0}
-            isVisible={true}
-            theme={theme}
-            disableScroll={true}
-            disableBasePadding
-            enableKeyboardScrolling={false}
-            autoFocusOnVisible={false}
-          />
+          <div style={{
+            display: '-webkit-box',
+            WebkitBoxOrient: 'vertical',
+            WebkitLineClamp: 6,
+            maxHeight: '9em',
+            overflow: 'hidden',
+          }}>
+            <IndustryMarkdownSlide
+              content={description}
+              slideIdPrefix="subsystem-desc"
+              slideIndex={0}
+              isVisible={true}
+              theme={theme}
+              disableScroll={true}
+              disableBasePadding
+              enableKeyboardScrolling={false}
+              autoFocusOnVisible={false}
+            />
+          </div>
+          <button
+            type="button"
+            aria-label="Read full description"
+            aria-haspopup="dialog"
+            aria-expanded={descriptionOpen}
+            onClick={() => setDescriptionOpen(true)}
+            style={{
+              marginTop: 6,
+              padding: 0,
+              border: 'none',
+              background: 'transparent',
+              color: theme.colors.textSecondary,
+              fontFamily: theme.fonts.body,
+              fontSize: theme.fontSizes[0],
+              textDecoration: 'underline',
+              cursor: 'pointer',
+            }}
+          >
+            More
+          </button>
         </div>
       )}
       {sidebarAfterDescription}
@@ -2864,7 +2894,6 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
     <GraphWithSidebar
       hidden={!sidebarVisible}
       bodyHidden={!sidebarBodyVisible}
-      headerMaxHeight={sidebarBodyVisible ? '30%' : '100%'}
       header={sidebarHeader}
       tabs={sidebarTabs}
       activeTab={diagnosticsTab}
@@ -2877,6 +2906,9 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       persistKey={persistKey}
       onResizeEnd={() => requestAnimationFrame(() => fitView())}
     >
+      {!hideSidebar && description && descriptionOpen && (
+        <DescriptionOverlay description={description} onClose={() => setDescriptionOpen(false)} />
+      )}
       {/* Graph area */}
       <div style={{ flex: 1, position: 'relative', display: 'flex', flexDirection: committedDirection === 'vertical' ? 'row' : 'column', minHeight: 0, minWidth: 0 }}>
         {/* Canvas box — the edge-label overlay and legend anchor here, so