@principal-ai/subsystems-react 0.28.6 → 0.29.0

package/src/subsystem/FileDrawer.tsx

@@ -5,19 +5,20 @@
  * children by the graph component.
  */
 
-import { useEffect, useState } from 'react';
-import type { ReactNode } from 'react';
-import { useTheme } from '@principal-ade/industry-theme';
-import { X } from 'lucide-react';
+import { useEffect, useState } from "react";
+import type { ReactNode } from "react";
+import { useTheme } from "@principal-ade/industry-theme";
+import { Minimize2, Maximize2, X } from "lucide-react";
 
 /** Matches `transition: height …` below — callers that fitView after open
  *  should wait at least this long so the canvas has its reduced height. */
 export const FILE_DRAWER_HEIGHT_MS = 200;
 
 /** Bottom panel that slides up from the bottom of the graph area.
- *  Sits in normal flow (canvas shrinks while open, nothing covered)
- *  and animates via height; stays mounted so open/close animates.
- *  `fillHeight` expands to the full graph column (for whole-file reading). */
+ *  Bottom-anchored with an animated height; an in-flow spacer reserves its
+ *  footprint so the canvas shrinks while open (nothing covered). Stays mounted
+ *  so open/close/maximize animate. The header's maximize button (or a
+ *  double-click) grows it over the whole graph column for whole-file reading. */
 export function FileDrawer({
   title,
   onClose,
@@ -38,85 +39,144 @@ export function FileDrawer({
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const open = title !== null;
   const [closeHover, setCloseHover] = useState(false);
+  const [maxHover, setMaxHover] = useState(false);
+  // Full-height mode: the maximize button or double-clicking the header.
+  // The panel is always bottom-anchored with an animated height, and a spacer
+  // in normal flow reserves its footprint, so maximizing grows it upward over
+  // the still-mounted graph instead of snapping to full.
+  const [maximized, setMaximized] = useState(false);
+  // A closed drawer reopens at the default height, not maximized.
+  useEffect(() => {
+    if (!open) setMaximized(false);
+  }, [open]);
+  const fullHeight = open && (maximized || fillHeight);
+  // Space the panel takes out of the canvas's flow (0 when it overlays fully).
+  const reservedHeight = fullHeight ? 0 : open ? "45%" : 0;
 
   useEffect(() => {
     if (!open || suppressEscape) return;
     const onKey = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') onClose();
+      if (e.key === "Escape") onClose();
     };
-    window.addEventListener('keydown', onKey);
-    return () => window.removeEventListener('keydown', onKey);
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
   }, [open, onClose, suppressEscape]);
 
   return (
-    <div
-      style={{
-        position: 'relative',
-        // Above the absolute edge-label overlay (zIndex 5), which spans the
-        // whole graph-area container including this panel's slice.
-        zIndex: 6,
-        flexShrink: 0,
-        flex: open && fillHeight ? 1 : undefined,
-        height: open ? (fillHeight ? undefined : '45%') : 0,
-        minHeight: 0,
-        overflow: 'hidden',
-        display: 'flex',
-        flexDirection: 'column',
-        background: theme.colors.background,
-        borderTop: open ? `1px solid ${theme.colors.border}` : 'none',
-        transition: `height ${FILE_DRAWER_HEIGHT_MS}ms ease`,
-      }}
-    >
+    <>
+      {/* Reserves the drawer's footprint in the column so the canvas shrinks
+          while the drawer is open. Animates with the panel, so the boundary
+          between graph and code slides smoothly. */}
       <div
+        aria-hidden="true"
         style={{
-          display: 'flex',
-          alignItems: 'center',
-          gap: 8,
-          padding: '6px 10px',
-          borderBottom: `1px solid ${theme.colors.border}`,
           flexShrink: 0,
+          height: reservedHeight,
+          transition: `height ${FILE_DRAWER_HEIGHT_MS}ms ease`,
+        }}
+      />
+      {/* The panel — bottom-anchored and grown via `height`, so maximize/fill
+          reads as dragging up over the diagram. */}
+      <div
+        style={{
+          position: "absolute",
+          left: 0,
+          right: 0,
+          bottom: 0,
+          // Above the edge-label overlay (zIndex 5), React Flow, and overlays
+          // (zIndex 6–8); 30 lifts it over the whole graph area when maximized.
+          zIndex: maximized ? 30 : 6,
+          height: open ? (fullHeight ? "100%" : "45%") : 0,
+          minHeight: 0,
+          overflow: "hidden",
+          display: "flex",
+          flexDirection: "column",
+          background: theme.colors.background,
+          borderTop: open ? `1px solid ${theme.colors.border}` : "none",
+          transition: `height ${FILE_DRAWER_HEIGHT_MS}ms ease`,
         }}
       >
-        <span
-          title={title ?? undefined}
-          style={{
-            flex: 1,
-            minWidth: 0,
-            overflow: 'hidden',
-            textOverflow: 'ellipsis',
-            whiteSpace: 'nowrap',
-            fontFamily: theme.fonts.monospace,
-            fontSize: theme.fontSizes[0],
-            color: muted,
-          }}
-        >
-          {title}
-        </span>
-        <button
-          type="button"
-          onClick={onClose}
-          onMouseEnter={() => setCloseHover(true)}
-          onMouseLeave={() => setCloseHover(false)}
-          aria-label="Close file"
+        <div
+          onDoubleClick={() => setMaximized((v) => !v)}
           style={{
-            display: 'inline-flex',
-            alignItems: 'center',
-            justifyContent: 'center',
-            width: 22,
-            height: 22,
-            padding: 0,
-            border: 'none',
-            borderRadius: 4,
-            background: closeHover ? theme.colors.border : 'transparent',
-            color: closeHover ? theme.colors.text : muted,
-            cursor: 'pointer',
-            transition: 'background 120ms ease, color 120ms ease',
+            display: "flex",
+            alignItems: "center",
+            gap: 8,
+            padding: "6px 10px",
+            borderBottom: `1px solid ${theme.colors.border}`,
+            flexShrink: 0,
+            cursor: "default",
+            userSelect: "none",
           }}
         >
-          <X size={14} />
-        </button>
+          <span
+            title={title ?? undefined}
+            style={{
+              flex: 1,
+              minWidth: 0,
+              overflow: "hidden",
+              textOverflow: "ellipsis",
+              whiteSpace: "nowrap",
+              fontFamily: theme.fonts.monospace,
+              fontSize: theme.fontSizes[0],
+              color: muted,
+            }}
+          >
+            {title}
+          </span>
+          <button
+            type="button"
+            onClick={() => setMaximized((v) => !v)}
+            onMouseEnter={() => setMaxHover(true)}
+            onMouseLeave={() => setMaxHover(false)}
+            aria-label={maximized ? "Minimize code view" : "Maximize code view"}
+            aria-pressed={maximized}
+            title={maximized ? "Minimize code view" : "Maximize code view"}
+            style={{
+              display: "inline-flex",
+              alignItems: "center",
+              justifyContent: "center",
+              width: 22,
+              height: 22,
+              padding: 0,
+              border: "none",
+              borderRadius: 4,
+              background: maxHover ? theme.colors.border : "transparent",
+              color: maxHover ? theme.colors.text : muted,
+              cursor: "pointer",
+              transition: "background 120ms ease, color 120ms ease",
+            }}
+          >
+            {maximized ? <Minimize2 size={14} /> : <Maximize2 size={14} />}
+          </button>
+          <button
+            type="button"
+            onClick={onClose}
+            onMouseEnter={() => setCloseHover(true)}
+            onMouseLeave={() => setCloseHover(false)}
+            aria-label="Close file"
+            style={{
+              display: "inline-flex",
+              alignItems: "center",
+              justifyContent: "center",
+              width: 22,
+              height: 22,
+              padding: 0,
+              border: "none",
+              borderRadius: 4,
+              background: closeHover ? theme.colors.border : "transparent",
+              color: closeHover ? theme.colors.text : muted,
+              cursor: "pointer",
+              transition: "background 120ms ease, color 120ms ease",
+            }}
+          >
+            <X size={14} />
+          </button>
+        </div>
+        <div style={{ flex: 1, minHeight: 0, overflow: "auto" }}>
+          {children}
+        </div>
       </div>
-      <div style={{ flex: 1, minHeight: 0, overflow: 'auto' }}>{children}</div>
-    </div>
+    </>
   );
 }

package/src/subsystem/IssueList.tsx

@@ -11,7 +11,7 @@
  * (e.g. focus the node on the graph, or apply the fix in the report).
  */
 
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import type { LucideIcon } from 'lucide-react';
 import {
   ChevronDown,
@@ -499,6 +499,14 @@ export interface SubsystemIssueListProps {
   onSelectIssue?: (issue: SubsystemIssue) => void;
   onApplyFix?: (issue: SubsystemIssue) => void;
   onHoverIssue?: (issue: SubsystemIssue | null) => void;
+  /**
+   * Land the list focused on one verification layer: that category starts
+   * expanded and every other category starts collapsed. Used when the list is
+   * opened from a lane-specific entry point (e.g. the Maintainer tab's lane
+   * badges) so the caller's intent — "show me this layer's findings" — is
+   * honoured without an extra click.
+   */
+  focusCategory?: SubsystemIssueCategory;
 }
 
 export function SubsystemIssueList({
@@ -506,15 +514,32 @@ export function SubsystemIssueList({
   onSelectIssue,
   onApplyFix,
   onHoverIssue,
+  focusCategory,
 }: SubsystemIssueListProps) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
   const categories = groupIssuesByCategory(issues);
-  // Collapsed categories (by id). Everything starts expanded.
+  // Collapsed categories (by id). Everything starts expanded, unless the list
+  // was opened focused on a single layer — then every other layer starts
+  // collapsed so the focused category's findings are what you land on.
   const [collapsed, setCollapsed] = useState<Set<SubsystemIssueCategory>>(
-    () => new Set(),
+    () =>
+      focusCategory
+        ? new Set(
+            SUBSYSTEM_ISSUE_CATEGORIES.filter((c) => c !== focusCategory),
+          )
+        : new Set(),
   );
   const [hovered, setHovered] = useState<SubsystemIssueCategory | null>(null);
+  // Re-apply the focus when it changes on an already-mounted list (e.g. the
+  // host switches which lane the open model is focused on).
+  useEffect(() => {
+    setCollapsed(
+      focusCategory
+        ? new Set(SUBSYSTEM_ISSUE_CATEGORIES.filter((c) => c !== focusCategory))
+        : new Set(),
+    );
+  }, [focusCategory]);
   const toggleCollapsed = (category: SubsystemIssueCategory) => {
     setCollapsed((prev) => {
       const next = new Set(prev);

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -55,7 +55,11 @@ import { ConstructsCatalog } from './ConstructsCatalog';
 import type { SubsystemOpenFileOptions } from './declarationRef';
 import { SubsystemComponentNode, SubsystemGroupNode, SubsystemEdge, SUBSYSTEM_CALLBACKS, hexWithAlpha, EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility } from './nodes';
 import { SubsystemDiagnosticToggle, type SubsystemDiagnostic } from './DiagnosticToggle';
-import { SubsystemIssueList, type SubsystemIssue } from './IssueList';
+import {
+  SubsystemIssueList,
+  type SubsystemIssue,
+  type SubsystemIssueCategory,
+} from './IssueList';
 import { SubsystemFileTree } from './SubsystemFileTree';
 import { GraphLayoutCover } from './GraphLayoutCover';
 import { GRAPH_NAV_PROPS, GraphChrome } from './graphChrome';
@@ -172,7 +176,7 @@ export interface SubsystemComponentGraphProps {
    * Which edge vocabulary the canvas draws. The relation and walkthrough
    * vocabularies are disjoint, so a graph carrying both shows one or the
    * other — never both. Edges outside the view are hidden (labels go too).
-   * - `relations`: topology relation edges (`imports`, `extends`, …)
+   * - `relations`: topology relation edges (`extends`, `implements`, …)
    * - `walkthroughs`: walkthrough hop edges (`calls`, `feeds`, …), including
    *   step numbers when a flow is focused/hovered
    * Leave unset to let the sidebar's Files / Walkthroughs tab drive it: Files
@@ -246,6 +250,12 @@ export interface SubsystemComponentGraphProps {
    * diagnostics on iff `issues` is non-empty, and the title-row chip toggles it.
    */
   showIssues?: boolean;
+  /**
+   * When the issues list is active, land it focused on this verification
+   * layer: that category expands, the rest start collapsed. Optional — the
+   * plain issues view expands everything.
+   */
+  focusIssueCategory?: SubsystemIssueCategory;
   /** Click an issue — focus its target on the graph / open detail. */
   onSelectIssue?: (issue: SubsystemIssue) => void;
   /** Apply an issue's deterministic fix. */
@@ -375,7 +385,7 @@ interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, relations, walkthroughs, initialWalkthroughId, onReorderWalkthroughs, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, edgeView, title, hideSidebar, walkthroughStepMode = 'focus', autoPlayWalkthroughs = false, walkthroughAutoPlayIntervalMs = WALKTHROUGH_PLAY_PAUSE_MS, zoomOnWalkthroughFocus = true, graphTitle, showWalkthroughTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, onVerifyComponent, componentVerification, persistKey }: InnerProps) {
+function Inner({ components, relations, walkthroughs, initialWalkthroughId, onReorderWalkthroughs, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, edgeView, title, hideSidebar, walkthroughStepMode = 'focus', autoPlayWalkthroughs = false, walkthroughAutoPlayIntervalMs = WALKTHROUGH_PLAY_PAUSE_MS, zoomOnWalkthroughFocus = true, graphTitle, showWalkthroughTitle = false, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, diagnostic, issues, showIssues, focusIssueCategory, onSelectIssue, onApplyIssueFix, onHoverIssue, renderFileView, renderFileViewer, renderWalkthroughViewer, onFileSelect, onVerifyComponent, componentVerification, persistKey }: InnerProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const viewport = useViewport();
@@ -972,7 +982,7 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
     };
     // Edges outside the selected view are hidden entirely (labels included).
     const edgeInView = (e: Edge): boolean => {
-      const mechanism = (e.data as { mechanism?: string } | undefined)?.mechanism ?? 'imports';
+      const mechanism = (e.data as { mechanism?: string } | undefined)?.mechanism ?? 'uses';
       return resolvedEdgeView === 'relations'
         ? isRelationMechanism(mechanism)
         : isWalkthroughMechanism(mechanism);
@@ -1560,7 +1570,7 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
         } | undefined;
         return {
           id: e.id,
-          mechanism: d?.mechanism ?? 'imports',
+          mechanism: d?.mechanism ?? 'uses',
           dimmed: d?.dimmed === true,
           midX: d?.labelX ?? 0,
           midY: d?.labelY ?? 0,
@@ -1738,6 +1748,7 @@ function Inner({ components, relations, walkthroughs, initialWalkthroughId, onRe
               {issuesActive ? (
                 <SubsystemIssueList
                   issues={issues ?? []}
+                  focusCategory={focusIssueCategory}
                   onSelectIssue={onSelectIssue}
                   onApplyFix={onApplyIssueFix}
                   onHoverIssue={onHoverIssue}

package/src/subsystem/model.test.ts

@@ -40,9 +40,9 @@ const comps: SubsystemComponent[] = [
 ];
 
 const relations = [
-  { id: 'e1', from: 'transcript', to: 'reader', relationType: 'imports' as const },
+  { id: 'e1', from: 'transcript', to: 'reader', relationType: 'references' as const },
   // 'host' is NOT a component — this is the cross-package external case.
-  { id: 'e2', from: 'reader', to: 'host', relationType: 'imports' as const, refs: ['bun/index.ts'] },
+  { id: 'e2', from: 'reader', to: 'host', relationType: 'references' as const, refs: ['bun/index.ts'] },
 ];
 
 const doc = { components: comps, relations };

package/src/subsystem/model.ts

@@ -91,7 +91,6 @@ export interface SubsystemDeclToken {
  * Belongs on `relations[]`, not on walkthrough hops.
  */
 export type SubsystemRelationType =
-  | 'imports'
   | 'extends'
   | 'inherits'
   | 'implements'
@@ -120,7 +119,7 @@ export type SubsystemEdgeMechanism =
 /**
  * Which edge vocabulary the canvas draws. The two vocabularies are disjoint;
  * a view shows only edges (and their labels) from the selected source.
- * - `relations`: only topology relation edges (`imports`, `extends`, …)
+ * - `relations`: only topology relation edges (`extends`, `implements`, …)
  * - `walkthroughs`: only walkthrough hop edges (`calls`, `feeds`, …)
  */
 export type SubsystemEdgeView = 'relations' | 'walkthroughs';
@@ -945,7 +944,6 @@ export type SubsystemGraphEdge = Edge<SubsystemGraphEdgeData>;
  * source (the two unions are disjoint).
  */
 export const SUBSYSTEM_RELATION_TYPES = [
-  'imports',
   'extends',
   'inherits',
   'implements',
@@ -986,7 +984,6 @@ export function isWalkthroughMechanism(
 }
 
 export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
-  imports: '#0893d2', // blue
   calls: '#4ec9b0', // teal
   extends: '#b48ead', // purple
   inherits: '#9b6fd0', // purple
@@ -1004,7 +1001,6 @@ export const MECHANISM_COLOR: Record<SubsystemEdgeMechanism, string> = {
 };
 
 export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed' | 'dotted'> = {
-  imports: 'solid',
   calls: 'solid',
   extends: 'dashed',
   inherits: 'dashed',
@@ -1024,7 +1020,6 @@ export const MECHANISM_STYLE: Record<SubsystemEdgeMechanism, 'solid' | 'dashed'
 /** Mechanism → [description, verifiable-with-graphify]. Drives the "not
  *  directly verifiable" styling of edge labels. */
 export const MECHANISM_DESCRIPTIONS: [SubsystemEdgeMechanism, string, boolean][] = [
-  ['imports', 'import statement (code-level dependency)', true],
   ['calls', 'function/method call (call graph edge)', true],
   ['extends', 'class inheritance', true],
   ['inherits', 'class inheritance', true],

package/src/subsystem/nodes.tsx

@@ -539,7 +539,7 @@ export function SubsystemEdge({
   markerEnd,
 }: EdgeProps<SubsystemGraphEdge>) {
   const path = data?.elkPath ?? '';
-  const mechanism = data?.mechanism ?? 'imports';
+  const mechanism = data?.mechanism ?? 'uses';
   const color = MECHANISM_COLOR[mechanism] ?? '#888';
   // Dash style comes from the mechanism table (dashed = inverted-control or
   // observational relationships: hierarchy, registration, watches).