@principal-ai/subsystems-react 0.56.12 → 0.56.14

package/src/subsystem/C4SketchView.tsx

@@ -0,0 +1,241 @@
+/**
+ * C4SketchView — a standalone authored C4 hypothesis.
+ *
+ * Pure presentation: the host loads the sketch and passes it in. There is no
+ * model comparison, grounding, or promotion here; a sketch is a diagram in its
+ * own right.
+ */
+
+import { useCallback, useMemo, useState } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
+import { useTheme } from '@principal-ade/industry-theme';
+import { PencilRuler } from 'lucide-react';
+import { IndustryMarkdownSlide } from 'themed-markdown';
+import { C4Graph } from './C4Graph';
+import { GraphWithSidebar } from './GraphWithSidebar';
+import type { C4Sketch } from './c4Sketch';
+
+export interface C4SketchViewProps {
+  sketch: C4Sketch;
+  /** Controlled open-container ids. Omit to let the view own them. */
+  openContainerIds?: readonly string[];
+  onOpenContainerIdsChange?: (ids: string[]) => void;
+  /** Extra controls in the header. */
+  headerActions?: ReactNode;
+  /** Sidebar width persistence key. */
+  persistKey?: string;
+  /** Outer style for the flex fill. */
+  style?: CSSProperties;
+}
+
+export function C4SketchView({
+  sketch,
+  openContainerIds,
+  onOpenContainerIdsChange,
+  headerActions,
+  persistKey,
+  style,
+}: C4SketchViewProps) {
+  const { theme } = useTheme();
+  const [internalOpenIds, setInternalOpenIds] = useState<string[]>(() =>
+    [...(openContainerIds ?? sketch.model.openContainerIds ?? [])].sort(),
+  );
+  const resolvedOpenIds = openContainerIds
+    ? [...openContainerIds]
+    : internalOpenIds;
+  const setOpenIds = useCallback(
+    (next: string[]) => {
+      if (!openContainerIds) setInternalOpenIds(next);
+      onOpenContainerIdsChange?.(next);
+    },
+    [onOpenContainerIdsChange, openContainerIds],
+  );
+
+  const model = useMemo(
+    () => ({ ...sketch.model, openContainerIds: resolvedOpenIds }),
+    [resolvedOpenIds, sketch.model],
+  );
+
+  const toggleContainer = useCallback(
+    (id: string) => {
+      setOpenIds(
+        resolvedOpenIds.includes(id)
+          ? resolvedOpenIds.filter((openId) => openId !== id)
+          : [...resolvedOpenIds, id].sort(),
+      );
+    },
+    [resolvedOpenIds, setOpenIds],
+  );
+
+  const openAll = useCallback(() => {
+    setOpenIds(
+      sketch.model.nodes
+        .filter((node) => node.kind === 'container')
+        .map((node) => node.id)
+        .sort(),
+    );
+  }, [setOpenIds, sketch.model.nodes]);
+
+  const collapseAll = useCallback(() => setOpenIds([]), [setOpenIds]);
+
+  const notes = sketch.notes?.trim();
+  const notesPanel = notes ? (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+      <div
+        style={{
+          fontSize: 10,
+          fontFamily: theme.fonts.monospace,
+          letterSpacing: 0.4,
+          color: theme.colors.textSecondary,
+        }}
+      >
+        ABOUT
+      </div>
+      <IndustryMarkdownSlide
+        content={notes}
+        slideIdPrefix={`c4-sketch-notes-${sketch.id}`}
+        slideIndex={0}
+        isVisible={true}
+        theme={theme}
+        disableScroll={true}
+        disableBasePadding
+        enableKeyboardScrolling={false}
+        autoFocusOnVisible={false}
+      />
+    </div>
+  ) : null;
+
+  return (
+    <div
+      style={{
+        width: '100%',
+        height: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        background: theme.colors.background,
+        ...style,
+      }}
+    >
+      <header
+        style={{
+          flexShrink: 0,
+          display: 'flex',
+          alignItems: 'center',
+          gap: 12,
+          flexWrap: 'wrap',
+          padding: '12px 16px',
+          background: theme.colors.background,
+          borderBottom: `1px solid ${theme.colors.border}`,
+        }}
+      >
+        <div
+          style={{
+            minWidth: 240,
+            flex: 1,
+            display: 'flex',
+            alignItems: 'center',
+            gap: 8,
+            flexWrap: 'wrap',
+          }}
+        >
+          <h2
+            style={{
+              margin: 0,
+              minWidth: 0,
+              fontSize: theme.fontSizes[2],
+              fontWeight: 600,
+              color: theme.colors.text,
+              fontFamily: theme.fonts.monospace,
+              overflowWrap: 'anywhere',
+            }}
+          >
+            {sketch.title}
+          </h2>
+          <span
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              gap: 4,
+              padding: '1px 7px',
+              borderRadius: 4,
+              border: '1px solid #e3b341',
+              color: '#e3b341',
+              fontFamily: theme.fonts.monospace,
+              fontSize: 10,
+              letterSpacing: 0.4,
+              flexShrink: 0,
+            }}
+          >
+            <PencilRuler size={10} aria-hidden="true" />
+            SKETCH
+          </span>
+        </div>
+        <div
+          style={{
+            marginLeft: 'auto',
+            flexShrink: 0,
+            display: 'flex',
+            alignItems: 'center',
+            gap: 6,
+            flexWrap: 'wrap',
+          }}
+        >
+          {headerActions}
+          <button
+            type="button"
+            onClick={openAll}
+            style={smallButton(theme, { width: 132 })}
+          >
+            Open all
+          </button>
+          <button
+            type="button"
+            onClick={collapseAll}
+            style={smallButton(theme, { width: 132 })}
+          >
+            Collapse all
+          </button>
+        </div>
+      </header>
+
+      <div style={{ flex: 1, minHeight: 0 }}>
+        <GraphWithSidebar
+          hidden={!notes}
+          stretchHeader
+          defaultWidth={320}
+          minWidth={240}
+          maxWidth={480}
+          persistKey={persistKey ?? `c4-sketch-notes-${sketch.id}`}
+          header={notesPanel}
+        >
+          <C4Graph model={model} onToggleContainer={toggleContainer} />
+        </GraphWithSidebar>
+      </div>
+    </div>
+  );
+}
+
+function smallButton(
+  theme: ReturnType<typeof useTheme>['theme'],
+  opts: { width?: number } = {},
+) {
+  return {
+    flexShrink: 0,
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 5,
+    ...(opts.width ? { width: opts.width } : {}),
+    height: 34,
+    padding: '0 10px',
+    boxSizing: 'border-box',
+    whiteSpace: 'nowrap',
+    borderRadius: 6,
+    border: `1px solid ${theme.colors.border}`,
+    background: 'transparent',
+    color: theme.colors.textSecondary,
+    fontFamily: theme.fonts.body,
+    fontSize: theme.fontSizes[1],
+    cursor: 'pointer',
+  } as const;
+}

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

package/src/subsystem/__fixtures__/c4Drilldown.ts

@@ -753,65 +753,14 @@ export function rollupEdgeTrailRefs(opts: {
 }
 
 /**
- * The C4 elements a trail touches — every element that owns a step endpoint.
- *
- * This is the reverse of the memberships above: given a step's `from`/`to`
- * alias, which C4 box(es) hold it. Because a container's own process-claim
- * membership AND the authored components nested inside it both claim the
- * aliases, BOTH end up in the set: the container is the visible card at
- * container view, its components are the visible cards when it is open, so
- * either view stays honest.
- *
- * The complement of the result (all element ids minus these) is what a
- * trail-driven emphasis pass should dim. Pure, and the spec the story's
- * "players stay bright" is asserted against.
- */
-export function deriveTrailPlayerElements(
-  steps: SubsystemTrail['steps'],
-  members: Readonly<Record<string, readonly string[]>>,
-): Set<string> {
-  const byAlias = new Map<string, string[]>();
-  for (const [elementId, aliases] of Object.entries(members)) {
-    for (const alias of aliases) {
-      const list = byAlias.get(alias);
-      if (list) list.push(elementId);
-      else byAlias.set(alias, [elementId]);
-    }
-  }
-  const players = new Set<string>();
-  for (const step of steps) {
-    for (const id of byAlias.get(step.from) ?? []) players.add(id);
-    for (const id of byAlias.get(step.to) ?? []) players.add(id);
-  }
-  return players;
-}
-
-/**
- * The C4 edges that carry the current focus — the line-level half of the
- * emphasis pair above.
- *
- * An edge is lit iff its authored `trailRefs` cover the source: the whole
- * trail, or one specific step of it. A step that is entirely internal to a
- * container folds into no C4 line (the rollup only keeps cross-boundary
- * hops), so its source lights NOTHING — every line dims, which is honest:
- * no drawn edge represents that hop.
+ * Trail-focus helpers live in production code now (`c4TrailFocus.ts`); keep
+ * these re-exports so the fixture's tests and the drill story can import them
+ * from the same place they always did.
  */
-export function deriveLitC4Edges(
-  source: { trailId: string; stepIndex?: number },
-  edges: readonly C4Edge[],
-): Set<string> {
-  const lit = new Set<string>();
-  for (const edge of edges) {
-    for (const ref of edge.trailRefs ?? []) {
-      if (ref.trailId !== source.trailId) continue;
-      if (source.stepIndex == null || ref.stepIndices.includes(source.stepIndex)) {
-        lit.add(edge.id);
-        break;
-      }
-    }
-  }
-  return lit;
-}
+export {
+  deriveLitC4Edges,
+  deriveTrailPlayerElements,
+} from '../c4TrailFocus';
 
 /**
  * Process claims the accepted C4 element set backs NOT at all — the set the