@principal-ai/subsystems-react 0.43.1 → 0.44.0

package/src/subsystem/SubsystemModelTransition.tsx

@@ -0,0 +1,389 @@
+/**
+ * SubsystemModelTransition — a sibling of `SubsystemComponentGraph` that
+ * presents ONE subsystem as a sequence of steps (e.g. constructs → static
+ * topology → dynamic topology → walkthrough) and animates between them.
+ *
+ * Same look as the component graph: it reuses the same node / frame / edge
+ * components and the edge-label chrome, so only the motion is new. Each step is
+ * laid out with `buildSubsystemGraph`; nodes and frames are flattened to
+ * absolute rects and position + size + opacity are interpolated on a rAF tween.
+ * The viewport refits to the incoming layout at the start of a transition, and
+ * the graph's real (ELK-routed, mechanism-colored) edges appear once it settles.
+ */
+
+import { useEffect, useMemo, useRef, useState, type ComponentType, type CSSProperties } from 'react';
+import {
+  Background,
+  EdgeLabelRenderer,
+  ReactFlow,
+  ReactFlowProvider,
+  useReactFlow,
+  type Edge,
+  type EdgeProps,
+  type EdgeTypes,
+  type Node,
+  type NodeTypes,
+} from '@xyflow/react';
+import '@xyflow/react/dist/style.css';
+import { useTheme } from '@principal-ade/industry-theme';
+import {
+  buildSubsystemGraph,
+  edgeColor,
+  MECHANISM_DESCRIPTIONS,
+  type SubsystemEdgeProvenance,
+  type SubsystemGraphNode,
+  type SubsystemModelDocument,
+} from './model';
+import {
+  hexWithAlpha,
+  SubsystemCallbacksProvider,
+  SubsystemComponentNode,
+  SubsystemEdge,
+  SubsystemGroupNode,
+} from './nodes';
+import { GRAPH_CANVAS_CLASS, GRAPH_NAV_PROPS, GraphChrome } from './graphChrome';
+import {
+  EDGE_LABEL_CLOUD_EXTRA_TOP,
+  EDGE_LABEL_CLOUD_PATH,
+  EDGE_LABEL_FONT_SIZE,
+  EDGE_LABEL_HEIGHT,
+  EDGE_LABEL_WIDTH,
+} from '../utils/edgeLabel';
+
+/** One step of the transition — a full model plus its view options. */
+export interface SubsystemTransitionStep {
+  model: SubsystemModelDocument;
+  /** `path` derives directory frames and nests modules under them. */
+  moduleNesting?: 'exact' | 'path';
+  /** Show mechanism labels on edges. @default true */
+  showEdgeLabels?: boolean;
+  /** Explicit boundary frame colors (region key → hex); host override. */
+  boundaryColors?: Record<string, string>;
+}
+
+export interface SubsystemModelTransitionProps {
+  steps: SubsystemTransitionStep[];
+  /** Which step is shown. Controlled by the host (its nav / timer). */
+  activeIndex: number;
+  /** Tween duration, ms. @default 750 */
+  durationMs?: number;
+  /** fitView padding for the viewport refit. @default 0.18 */
+  fitPadding?: number;
+  /** Called when a node is clicked. */
+  onSelect?: (componentAlias: string) => void;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/** Graph edge look (ELK orth path) + the mechanism label the graph overlays. */
+function TransitionEdge(props: EdgeProps) {
+  const { theme } = useTheme();
+  const data = props.data as
+    | { mechanism?: string; provenance?: SubsystemEdgeProvenance; labelX?: number; labelY?: number }
+    | undefined;
+  const mechanism = data?.mechanism ?? 'uses';
+  const color = edgeColor({ mechanism, provenance: data?.provenance });
+  const verifiable =
+    data?.provenance === 'graphify' ||
+    MECHANISM_DESCRIPTIONS.find(([m]) => m === mechanism)?.[2] !== false;
+  const labelBg = theme.colors.backgroundSecondary ?? theme.colors.background;
+  const showLabel = data?.labelX != null && data?.labelY != null;
+  return (
+    <>
+      <EdgeRenderer {...props} />
+      {showLabel && (
+        <EdgeLabelRenderer>
+          <div
+            style={{
+              position: 'absolute',
+              transform: `translate(-50%, -50%) translate(${data!.labelX}px, ${data!.labelY}px)`,
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: EDGE_LABEL_WIDTH,
+              height: EDGE_LABEL_HEIGHT,
+              boxSizing: 'border-box',
+              padding: '7px 8px',
+              pointerEvents: 'none',
+            }}
+          >
+            {verifiable ? (
+              <span
+                aria-hidden
+                style={{
+                  position: 'absolute',
+                  inset: 0,
+                  borderRadius: 4,
+                  border: `0.5px solid ${color}`,
+                  background: labelBg,
+                }}
+              />
+            ) : (
+              <svg
+                aria-hidden
+                width={EDGE_LABEL_WIDTH}
+                height={EDGE_LABEL_HEIGHT + EDGE_LABEL_CLOUD_EXTRA_TOP}
+                viewBox={`0 0 ${EDGE_LABEL_WIDTH} ${EDGE_LABEL_HEIGHT + EDGE_LABEL_CLOUD_EXTRA_TOP}`}
+                style={{ position: 'absolute', left: 0, top: -EDGE_LABEL_CLOUD_EXTRA_TOP }}
+              >
+                <path
+                  d={EDGE_LABEL_CLOUD_PATH}
+                  fill={labelBg}
+                  stroke={hexWithAlpha(color, 0.75)}
+                  strokeWidth={1.2}
+                  strokeLinejoin="round"
+                />
+              </svg>
+            )}
+            <span
+              style={{
+                position: 'relative',
+                display: 'block',
+                maxWidth: '100%',
+                overflow: 'hidden',
+                textOverflow: 'ellipsis',
+                whiteSpace: 'nowrap',
+                fontSize: EDGE_LABEL_FONT_SIZE,
+                lineHeight: 1,
+                fontFamily: theme.fonts.monospace,
+                fontWeight: 500,
+                color,
+              }}
+            >
+              {mechanism}
+            </span>
+          </div>
+        </EdgeLabelRenderer>
+      )}
+    </>
+  );
+}
+
+const nodeTypes: NodeTypes = {
+  'subsystem-component': SubsystemComponentNode,
+  'subsystem-group': SubsystemGroupNode,
+};
+const edgeTypes: EdgeTypes = { 'subsystem-edge': TransitionEdge };
+
+/** `SubsystemEdge` narrows its props; render it through a permissive alias. */
+const EdgeRenderer = SubsystemEdge as unknown as ComponentType<EdgeProps>;
+
+type Rect = { x: number; y: number; w: number; h: number };
+type Live = Rect & { o: number };
+type StepMeta = { type: 'subsystem-component' | 'subsystem-group'; data: Record<string, unknown> };
+type StepLayout = {
+  rects: Map<string, Rect>;
+  meta: Map<string, StepMeta>;
+  order: string[];
+  edges: Edge[];
+};
+
+const ease = (t: number) => t * t * (3 - 2 * t);
+const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
+
+function flatten(
+  result: Awaited<ReturnType<typeof buildSubsystemGraph>>,
+  boundaryColors?: Record<string, string>,
+): StepLayout {
+  const rects = new Map<string, Rect>();
+  const meta = new Map<string, StepMeta>();
+  const order: string[] = [];
+  const nodes: SubsystemGraphNode[] = [
+    ...result.nodes.filter((n) => n.type === 'subsystem-group'),
+    ...result.nodes.filter((n) => n.type !== 'subsystem-group'),
+  ];
+  for (const n of nodes) {
+    const r = result.absoluteRects.get(n.id);
+    if (!r) continue;
+    rects.set(n.id, { x: r.x, y: r.y, w: r.width, h: r.height });
+    const data = { ...((n.data ?? {}) as Record<string, unknown>) };
+    if (n.type === 'subsystem-group' && boundaryColors) {
+      const key = (data as { region?: { key?: string } }).region?.key;
+      if (key && boundaryColors[key] != null) data.color = boundaryColors[key];
+    }
+    meta.set(n.id, { type: n.type as StepMeta['type'], data });
+    order.push(n.id);
+  }
+  return { rects, meta, order, edges: result.edges as unknown as Edge[] };
+}
+
+function TransitionInner({
+  steps,
+  activeIndex,
+  durationMs = 750,
+  fitPadding = 0.18,
+  onSelect,
+  className,
+  style,
+}: SubsystemModelTransitionProps) {
+  const { theme } = useTheme();
+  const { fitBounds } = useReactFlow();
+  const [layouts, setLayouts] = useState<StepLayout[] | null>(null);
+  const [display, setDisplay] = useState<Map<string, Live>>(new Map());
+  const [settled, setSettled] = useState(false);
+  const displayRef = useRef(display);
+  displayRef.current = display;
+  const rafRef = useRef<number | null>(null);
+
+  // Lay out every step whenever the steps prop changes (identity-keyed).
+  useEffect(() => {
+    let alive = true;
+    void (async () => {
+      const next: StepLayout[] = [];
+      for (const s of steps) {
+        const result = await buildSubsystemGraph(s.model, {
+          showSingletonFrames: true,
+          moduleNesting: s.moduleNesting,
+          showEdgeLabels: s.showEdgeLabels ?? true,
+        });
+        next.push(flatten(result, s.boundaryColors));
+      }
+      if (alive) setLayouts(next);
+    })();
+    return () => {
+      alive = false;
+    };
+  }, [steps]);
+
+  // Tween to the active step; refit; hide edges until settled.
+  useEffect(() => {
+    if (!layouts) return;
+    const step = layouts[activeIndex];
+    if (!step) return;
+    setSettled(false);
+
+    const rects = [...step.rects.values()];
+    if (rects.length > 0) {
+      const minX = Math.min(...rects.map((r) => r.x));
+      const minY = Math.min(...rects.map((r) => r.y));
+      const maxX = Math.max(...rects.map((r) => r.x + r.w));
+      const maxY = Math.max(...rects.map((r) => r.y + r.h));
+      fitBounds(
+        { x: minX, y: minY, width: maxX - minX, height: maxY - minY },
+        { padding: fitPadding, duration: durationMs },
+      );
+    }
+
+    const start = new Map(displayRef.current);
+    const ids = new Set<string>([...start.keys(), ...step.rects.keys()]);
+    const t0 = performance.now();
+    const tick = (now: number) => {
+      const t = Math.min(1, (now - t0) / durationMs);
+      const e = ease(t);
+      const next = new Map<string, Live>();
+      for (const id of ids) {
+        const cur = start.get(id);
+        const tgt = step.rects.get(id);
+        if (tgt) {
+          const from = cur ?? { ...tgt, o: 0 };
+          next.set(id, {
+            x: lerp(from.x, tgt.x, e),
+            y: lerp(from.y, tgt.y, e),
+            w: lerp(from.w, tgt.w, e),
+            h: lerp(from.h, tgt.h, e),
+            o: lerp(from.o ?? 0, 1, e),
+          });
+        } else if (cur) {
+          next.set(id, { ...cur, o: lerp(cur.o, 0, e) });
+        }
+      }
+      setDisplay(next);
+      if (t < 1) {
+        rafRef.current = requestAnimationFrame(tick);
+      } else {
+        setSettled(true);
+      }
+    };
+    rafRef.current = requestAnimationFrame(tick);
+    return () => {
+      if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
+    };
+  }, [layouts, activeIndex, durationMs, fitPadding, fitBounds]);
+
+  const unionMeta = useMemo(() => {
+    const m = new Map<string, StepMeta>();
+    for (const s of layouts ?? []) for (const [id, meta] of s.meta) if (!m.has(id)) m.set(id, meta);
+    return m;
+  }, [layouts]);
+
+  const activeLayout = layouts?.[activeIndex];
+
+  const nodes: Node[] = useMemo(() => {
+    const activeOrder = new Set(activeLayout?.order ?? []);
+    const ids = [...display.entries()]
+      .filter(([id, r]) => r.o > 0.01 || activeOrder.has(id))
+      .map(([id]) => id);
+    ids.sort((a, b) => {
+      const ga = unionMeta.get(a)?.type === 'subsystem-group' ? 0 : 1;
+      const gb = unionMeta.get(b)?.type === 'subsystem-group' ? 0 : 1;
+      return ga - gb;
+    });
+    const out: Node[] = [];
+    for (const id of ids) {
+      const meta = unionMeta.get(id);
+      const rect = display.get(id);
+      if (!meta || !rect) continue;
+      out.push({
+        id,
+        type: meta.type,
+        position: { x: rect.x, y: rect.y },
+        width: rect.w,
+        height: rect.h,
+        data: meta.data,
+        draggable: false,
+        selectable: false,
+        style: { opacity: rect.o },
+      } as Node);
+    }
+    return out;
+  }, [display, activeLayout, unionMeta]);
+
+  const edges: Edge[] = useMemo(
+    () => (settled ? activeLayout?.edges ?? [] : []),
+    [settled, activeLayout],
+  );
+
+  const callbacks = useMemo(() => (onSelect ? { onSelect } : {}), [onSelect]);
+
+  return (
+    <div
+      className={className}
+      style={{
+        position: 'relative',
+        width: '100%',
+        height: '100%',
+        minHeight: 0,
+        background: theme.colors.background,
+        ...style,
+      }}
+    >
+      {!layouts ? null : (
+        <SubsystemCallbacksProvider value={callbacks}>
+          <ReactFlow
+            nodes={nodes}
+            edges={edges}
+            nodeTypes={nodeTypes}
+            edgeTypes={edgeTypes}
+            className={GRAPH_CANVAS_CLASS}
+            {...GRAPH_NAV_PROPS}
+            proOptions={{ hideAttribution: true }}
+            nodesDraggable={false}
+            nodesConnectable={false}
+            style={{ width: '100%', height: '100%', background: theme.colors.background }}
+          >
+            <Background />
+            <GraphChrome />
+          </ReactFlow>
+        </SubsystemCallbacksProvider>
+      )}
+    </div>
+  );
+}
+
+export function SubsystemModelTransition(props: SubsystemModelTransitionProps) {
+  return (
+    <ReactFlowProvider>
+      <TransitionInner {...props} />
+    </ReactFlowProvider>
+  );
+}

package/src/subsystem/model.test.ts

@@ -954,6 +954,36 @@ describe('buildBoundaryLayoutGroupsByPath', () => {
     expect(ids.has(directoryGroupNodeId('lib'))).toBe(true);
   });
 
+  test('module directories are scoped to their process (process stays primary)', () => {
+    const comps: SubsystemComponent[] = [
+      { alias: 'page', name: 'page', construct: 'function', file: 'app/book/page.tsx', module: 'app/book/page.tsx', process: 'web/client', purl: 'pkg:github/p/app' },
+      { alias: 'a1', name: 'a1', construct: 'function', file: 'app/book/actions.ts', module: 'app/book/actions.ts', process: 'web/server', purl: 'pkg:github/p/app' },
+      { alias: 'a2', name: 'a2', construct: 'function', file: 'app/book/actions.ts', module: 'app/book/actions.ts', process: 'web/server', purl: 'pkg:github/p/app' },
+    ];
+    const groups = buildBoundaryLayoutGroupsByPath(
+      { components: comps },
+      { showSingletonFrames: true },
+    );
+    const client = groups.find((g) => g.id === processGroupNodeId('web/client'))!;
+    const server = groups.find((g) => g.id === processGroupNodeId('web/server'))!;
+    expect(client).toBeDefined();
+    expect(server).toBeDefined();
+
+    const clientDirs = groups.filter(
+      (g) => g.region.kind === 'directory' && g.parentId === processGroupNodeId('web/client'),
+    );
+    const serverDirs = groups.filter(
+      (g) => g.region.kind === 'directory' && g.parentId === processGroupNodeId('web/server'),
+    );
+    // Same folder path is split per process — separate, scoped frames.
+    expect(clientDirs.map((g) => g.region.key)).toEqual(['app/book']);
+    expect(serverDirs.map((g) => g.region.key)).toEqual(['app/book']);
+    expect(clientDirs[0]!.id).not.toBe(serverDirs[0]!.id);
+    // Process frames own those directories as children (not dropped/empty).
+    expect(client.memberAliases).toContain(clientDirs[0]!.id);
+    expect(server.memberAliases).toContain(serverDirs[0]!.id);
+  });
+
   test('exact mode adds no directory frames', () => {
     const groups = buildBoundaryLayoutGroups(
       { components: pathComps },