@principal-ai/subsystems-react 0.56.13 → 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/__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

package/src/subsystem/__fixtures__/c4Sketch.ts

@@ -0,0 +1,94 @@
+/**
+ * Storybook fixture for an authored C4 sketch.
+ *
+ * A standalone hypothesis: containers, a component, an external, a person,
+ * and two authored lines. No model or grounding is involved.
+ */
+
+import type { C4Sketch } from '../c4Sketch';
+
+const PURL = 'pkg:github/acme/widget';
+
+export const SKETCH_FIXTURE: C4Sketch = {
+  id: 'c4s-story',
+  title: 'Acme widget architecture',
+  repoKeys: [PURL],
+  author: 'storybook',
+  notes:
+    '## About this sketch\n\nThis is an **authored hypothesis** for the Acme widget. It describes the host and worker containers, the store inside the host, and the GitHub integration.\n\n- The worker calls the host over RPC.\n- The host calls GitHub over HTTPS.\n- Nothing here is verified or promoted.',
+  createdAt: '2026-10-25T00:00:00.000Z',
+  updatedAt: '2026-10-25T00:00:00.000Z',
+  model: {
+    view: 'container',
+    system: { id: 'system:acme', label: 'Acme' },
+    nodes: [
+      {
+        kind: 'container',
+        id: 'container:host',
+        label: 'Host',
+        containerKind: 'application',
+        technology: 'Bun',
+        process: 'acme/host',
+        state: 'proposed',
+        description: 'The long-lived host process.',
+      },
+      {
+        kind: 'container',
+        id: 'container:worker',
+        label: 'Worker',
+        containerKind: 'application',
+        technology: 'Bun',
+        process: 'acme/worker',
+        state: 'proposed',
+        description: 'The background worker.',
+      },
+      {
+        kind: 'component',
+        id: 'component:store',
+        label: 'Store',
+        container: 'container:host',
+        technology: 'Postgres',
+        members: ['store', 'ghost'],
+        state: 'proposed',
+        description: 'Persistence inside the host.',
+      },
+      {
+        kind: 'external-system',
+        id: 'external:github',
+        label: 'GitHub',
+        technology: 'REST',
+        members: ['github'],
+        state: 'proposed',
+        description: 'External source control.',
+      },
+      {
+        kind: 'person',
+        id: 'person:dev',
+        label: 'Developer',
+        state: 'proposed',
+        description: 'Uses the system.',
+      },
+    ],
+    edges: [
+      {
+        id: 'e:host-github',
+        source: 'container:host',
+        target: 'external:github',
+        label: 'HTTPS',
+        protocol: 'HTTPS',
+        mechanisms: ['calls'],
+        count: 1,
+      },
+      {
+        id: 'e:worker-host',
+        source: 'container:worker',
+        target: 'container:host',
+        label: 'RPC',
+        protocol: 'RPC',
+        mechanisms: ['calls'],
+        count: 1,
+      },
+    ],
+  },
+};
+

package/src/subsystem/c4Sketch.ts

@@ -0,0 +1,78 @@
+/**
+ * Authored C4 sketches — the types shared by the sketch view and the host
+ * stores.
+ *
+ * These live in `subsystems-react` so the pure view and its Storybook fixtures
+ * can use them without importing Studio's cross-process contract.
+ */
+
+import type { C4Model } from './c4';
+
+/**
+ * A C4 sketch — an authored, unverified architecture hypothesis.
+ *
+ * Unlike the accepted element store (approved containers only) and a model
+ * projection (derived from `process` keys), a sketch carries containers,
+ * components, externals, persons, AND edges. It can exist before any subsystem
+ * model does. Element state is forced to `proposed` by the host store: a sketch
+ * never claims acceptance.
+ */
+export interface C4Sketch {
+  id: string;
+  title: string;
+  /** Repos the sketch claims to describe; can be empty for greenfield. */
+  repoKeys: string[];
+  /** Authored nodes + edges. */
+  model: C4Model;
+  author?: string;
+  notes?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Lightweight row for listing sketches without their nodes/edges. */
+export interface C4SketchSummary {
+  id: string;
+  title: string;
+  repoKeys: string[];
+  author?: string;
+  createdAt: string;
+  updatedAt: string;
+  counts: {
+    containers: number;
+    components: number;
+    externals: number;
+    persons: number;
+    edges: number;
+  };
+}
+
+/** Which C4 source a model projection or tab reads. */
+export type SubsystemC4Source = 'auto' | 'accepted' | 'draft';
+
+/**
+ * A drawable C4 projection for one subsystem model.
+ *
+ * `accepted` uses the repo's approved containers; `draft` derives provisional
+ * containers from the model's `process` keys. `memberships` is element id →
+ * component aliases, so a view can build construct graphs without re-deriving
+ * the join.
+ */
+export interface SubsystemC4Projection {
+  model: C4Model;
+  source: 'accepted' | 'draft';
+  memberships: Record<string, string[]>;
+  counts: {
+    containers: number;
+    externals: number;
+    edges: number;
+    components: number;
+    unassignedComponents: number;
+    unbackedProcesses: number;
+  };
+  repos: string[];
+  /** Aliases of components that state no `process`. */
+  unassignedComponents: string[];
+  /** Container-shaped process keys no accepted container claims (accepted source only). */
+  unbackedProcesses: string[];
+}

package/src/subsystem/c4TrailFocus.ts

@@ -0,0 +1,62 @@
+/**
+ * C4 trail focus — the pure read-side helpers shared by the C4 projection view
+ * and its stories.
+ *
+ * These do not own state: a host decides which trail/step is focused and asks
+ * which elements and lines that focus touches.
+ */
+
+import type { C4Edge } from './c4';
+import type { SubsystemTrailStep } from './model';
+
+/**
+ * The C4 elements a trail touches — every element that owns a step endpoint.
+ *
+ * Because a container's process-claim membership AND the authored components
+ * nested inside it can both claim an alias, 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.
+ */
+export function deriveTrailPlayerElements(
+  steps: readonly SubsystemTrailStep[],
+  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 a focus — a whole trail, or one specific step.
+ *
+ * An edge is lit iff its authored `trailRefs` cover the source. A step entirely
+ * internal to a container folds into no C4 line, so its focus lights nothing —
+ * which is honest: no drawn edge represents that hop.
+ */
+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;
+}