@principal-ai/principal-view-react 0.16.35 → 0.16.36

package/src/subsystem/ComponentDetail.tsx

@@ -1,187 +1,386 @@
 /**
- * ComponentDetail — selection detail panel for a subsystem component: the
- * verifiable identity (symbol/file/purpose/purl) plus graphify drill-down
- * sections. File content lives in the bottom FileDrawer, not here.
+ * ComponentDetail — selection detail panel for a subsystem component, rendered
+ * as it would appear in code: a file-path comment + doc comment, then the kind's
+ * declaration (`class X extends Y { ... }`, `function f(): T`, ...) with its
+ * members as signatures. Graphify relationship drill-downs appear as trailing
+ * comments. File content lives in the bottom FileDrawer, not here.
  */
 
-import type { ReactNode } from 'react';
+import { Fragment, type ReactNode } from 'react';
 import { useTheme } from '@principal-ade/industry-theme';
 import {
   KIND_COLOR,
   deriveNameFromSymbol,
+  formatPurl,
   type SubsystemComponent,
 } from './model';
-import type { GraphifyComponentDetail } from '../graphify';
 
-/** Detail panel for the selected component — the verifiable identity + sources
- *  moved off the canvas so nodes stay minimal. */
-export function ComponentDetail({ component }: { component: SubsystemComponent }) {
-  const { theme } = useTheme();
-  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
-  const color = KIND_COLOR[component.kind] ?? '#888';
-  const displayName = deriveNameFromSymbol(component.symbol, component.kind, component.name, component.file);
-  const rows: Array<[string, string]> = [];
-  if (component.symbol) rows.push(['Symbol', component.symbol]);
-  if (component.file) rows.push(['File', component.file]);
-  if (component.purpose) rows.push(['Purpose', component.purpose]);
-  rows.push(['PURL', component.purl]);
+/** Shared affordance for clickable text pieces. */
+const clickableStyle = {
+  cursor: 'pointer',
+  textDecorationLine: 'underline',
+  textDecorationStyle: 'dotted',
+  textUnderlineOffset: 2,
+} as const;
 
+/** Clickable detail-panel piece — dotted underline signals interactivity. */
+function DetailLink({ children, onClick }: { children: ReactNode; onClick?: () => void }) {
+  if (!onClick) return <>{children}</>;
   return (
-    <div
+    <span
+      onClick={(e) => {
+        e.stopPropagation();
+        onClick();
+      }}
       style={{
-        borderTop: `1px solid ${theme.colors.border}`,
-        background: theme.colors.background,
-        padding: '10px 12px',
-        fontFamily: theme.fonts.body,
+        cursor: 'pointer',
+        textDecorationLine: 'underline',
+        textDecorationStyle: 'dotted',
+        textUnderlineOffset: 2,
       }}
     >
-      <div
-        style={{
-          display: 'flex',
-          alignItems: 'center',
-          gap: 8,
-          fontSize: theme.fontSizes[1],
-          fontWeight: 600,
-          marginBottom: 6,
-        }}
-      >
-        <span style={{ color }}>{displayName}</span>
-        <span
-          style={{
-            fontSize: theme.fontSizes[0] * 0.8,
-            fontFamily: theme.fonts.monospace,
-            textTransform: 'uppercase',
-            color,
-          }}
-        >
-          {component.kind}
-        </span>
-      </div>
-      {rows.map(([k, v]) => (
-        <div
-          key={k}
-          style={{ display: 'flex', gap: 8, fontSize: theme.fontSizes[0], lineHeight: 1.5 }}
-        >
-          <span
-            style={{
-              width: 64,
-              flexShrink: 0,
-              color: muted,
-              fontFamily: theme.fonts.monospace,
-              textTransform: 'uppercase',
-              fontSize: theme.fontSizes[0] * 0.8,
-            }}
-          >
-            {k}
-          </span>
-          <span style={{ color: theme.colors.text, fontFamily: theme.fonts.monospace }}>
-            {v}
-          </span>
-        </div>
-      ))}
-      {component.detail && <GraphifyDetailSections detail={component.detail} />}
-    </div>
+      {children}
+    </span>
   );
 }
 
-/** Renders the graphify drill-down payload for a component. */
-function GraphifyDetailSections({ detail }: { detail: GraphifyComponentDetail }) {
+/** Panel props. The two callbacks are wired by the graph; standalone usage
+ *  without them renders the same panel with nothing clickable. */
+export interface ComponentDetailProps {
+  component: SubsystemComponent;
+  /** File-path click → open that file in the bottom drawer. */
+  onOpenFile?: (file: string) => void;
+  /** Related-name click (types, callers/callees, implementors, …) → select
+   *  that component if one matches; unmatched refs no-op. */
+  onRelatedSelect?: (ref: string) => void;
+}
+
+/** Detail panel for the selected component — its declaration, code-style. */
+export function ComponentDetail({ component, onOpenFile, onRelatedSelect }: ComponentDetailProps) {
   const { theme } = useTheme();
   const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const color = KIND_COLOR[component.kind] ?? '#888';
+  const displayName = deriveNameFromSymbol(component.symbol, component.kind, component.name, component.file);
 
-  const label = (k: string) => (
-    <span
-      style={{
-        width: 64,
-        flexShrink: 0,
-        color: muted,
-        fontFamily: theme.fonts.monospace,
-        textTransform: 'uppercase',
-        fontSize: theme.fontSizes[0] * 0.8,
-      }}
-    >
-      {k}
-    </span>
+  // Token styles — keyword / name / member / type / string / punctuation.
+  const kw = (text: string) => <span style={{ color: theme.colors.secondary }}>{text}</span>;
+  const nm = (text: string) => <span style={{ color }}>{text}</span>;
+  const mb = (text: string) => <span style={{ color: theme.colors.info }}>{text}</span>;
+  // Type tokens are links into the graph (other components often own them).
+  const ty = (text: string) => (
+    <DetailLink onClick={onRelatedSelect ? () => onRelatedSelect(text) : undefined}>
+      <span style={{ color: theme.colors.accent }}>{text}</span>
+    </DetailLink>
   );
-  const chip = (name: string, meta?: string, key?: string | number) => (
-    <span
-      key={key}
-      style={{
-        fontFamily: theme.fonts.monospace,
-        fontSize: theme.fontSizes[0],
-        color: theme.colors.text,
-        border: `1px solid ${theme.colors.border}`,
-        borderRadius: 4,
-        padding: '1px 6px',
-        marginRight: 6,
-        marginBottom: 4,
-        display: 'inline-block',
-      }}
-    >
-      {name}
-      {meta ? <span style={{ color: muted }}> {meta}</span> : ''}
-    </span>
-  );
-  const row = (k: string, children: ReactNode) => (
-    <div
-      style={{ display: 'flex', gap: 8, fontSize: theme.fontSizes[0], lineHeight: 1.5, marginBottom: 4 }}
-    >
-      {label(k)}
-      <div style={{ minWidth: 0 }}>{children}</div>
+  const str = (text: string) => <span style={{ color: theme.colors.success }}>{text}</span>;
+  const pn = (text: string) => <span style={{ color: muted }}>{text}</span>;
+
+  const line = (children: ReactNode, key?: string, indent?: boolean) => (
+    <div key={key} style={indent ? { paddingLeft: 16 } : undefined}>
+      {children}
     </div>
   );
+  const commentStyle = { color: muted, fontStyle: 'italic' } as const;
+  const commentLine = (text: string, key?: string, indent?: boolean, onClick?: () => void) =>
+    line(
+      <DetailLink onClick={onClick}>
+        <span style={{ ...commentStyle, ...(onClick ? clickableStyle : undefined) }}>{text}</span>
+      </DetailLink>,
+      key,
+      indent,
+    );
+  // Trailing relationship comments whose names are individually clickable.
+  const commentListLine = (prefix: string, names: string[], key?: string) =>
+    line(
+      <>
+        <span style={commentStyle}>{prefix}</span>
+        {list(
+          names.map((n, i) => (
+            <Fragment key={i}>
+              <DetailLink onClick={onRelatedSelect ? () => onRelatedSelect(n) : undefined}>
+                <span style={{ ...commentStyle, ...(onRelatedSelect ? clickableStyle : undefined) }}>{n}</span>
+              </DetailLink>
+            </Fragment>
+          )),
+        )}
+      </>,
+      key,
+    );
+  // Comma-join rendered tokens without raw-array key churn.
+  const list = (items: ReactNode[]) =>
+    items.map((item, i) => (
+      <Fragment key={i}>
+        {i > 0 ? ', ' : null}
+        {item}
+      </Fragment>
+    ));
 
-  switch (detail.kind) {
-    case 'class':
-      return (
-        <>
-          {detail.methods.length > 0 &&
-            row('methods', detail.methods.map((m, i) => chip(m.name, m.returnType, i)))}
-          {detail.properties.length > 0 &&
-            row('props', detail.properties.map((p, i) => chip(p.name, p.type, i)))}
-          {detail.extends.length > 0 && row('extends', detail.extends.map((e, i) => chip(e, undefined, i)))}
-          {detail.implements.length > 0 && row('impl', detail.implements.map((e, i) => chip(e, undefined, i)))}
-          {detail.instantiations.length > 0 &&
-            row('insts', detail.instantiations.map((i, idx) => chip(i.name, undefined, idx)))}
-          {detail.references.length > 0 &&
-            row('refs', detail.references.map((r, idx) => chip(r.name, undefined, idx)))}
-        </>
+  const lines: ReactNode[] = [];
+  if (component.purl)
+    lines.push(commentLine(`// ${formatPurl(component.purl)}`, 'purl'));
+  if (component.file)
+    lines.push(commentLine(`// ${component.file}`, 'file', false, onOpenFile ? () => onOpenFile(component.file) : undefined));
+  if (component.purpose) lines.push(commentLine(`/** ${component.purpose} */`, 'purpose'));
+
+  const detail = component.detail;
+  switch (detail?.kind ?? component.kind) {
+    case 'class': {
+      const members: ReactNode[] = [];
+      if (detail?.kind === 'class') {
+        detail.methods.forEach((m, i) =>
+          members.push(
+            line(
+              <>
+                {mb(m.name)}
+                {pn('(')}
+                {(m.parameters ?? []).length > 0 &&
+                  list(
+                    (m.parameters ?? []).map((p, j) => (
+                      <Fragment key={j}>
+                        {p.name ? (
+                          <>
+                            {mb(p.name)}
+                            {pn(': ')}
+                          </>
+                        ) : null}
+                        {ty(p.type)}
+                      </Fragment>
+                    )),
+                  )}
+                {pn(')')}
+                {m.returnType ? (
+                  <>
+                    {pn(': ')}
+                    {ty(m.returnType)}
+                  </>
+                ) : null}
+              </>,
+              `m${i}`,
+              true,
+            ),
+          ),
+        );
+        detail.properties.forEach((prop, i) =>
+          members.push(
+            line(
+              <>
+                {mb(prop.name)}
+                {prop.type ? (
+                  <>
+                    {pn(': ')}
+                    {ty(prop.type)}
+                  </>
+                ) : null}
+              </>,
+              `p${i}`,
+              true,
+            ),
+          ),
+        );
+      }
+      const cls = detail?.kind === 'class' ? detail : undefined;
+      const hasBody = members.length > 0;
+      lines.push(
+        line(
+          <>
+            {kw('class')}
+            {' '}
+            {nm(displayName)}
+            {cls && cls.extends.length > 0 && (
+              <>
+                {' '}
+                {kw('extends')}
+                {' '}
+                {list(cls.extends.map((e, i) => <Fragment key={i}>{ty(e)}</Fragment>))}
+              </>
+            )}
+            {cls && cls.implements.length > 0 && (
+              <>
+                {' '}
+                {kw('implements')}
+                {' '}
+                {list(cls.implements.map((e, i) => <Fragment key={i}>{ty(e)}</Fragment>))}
+              </>
+            )}
+            {hasBody ? pn(' {') : null}
+          </>,
+          'decl',
+        ),
       );
-    case 'function':
-      return (
-        <>
-          {detail.parameters.length > 0 &&
-            row('params', detail.parameters.map((p, i) => chip(p.type, undefined, i)))}
-          {detail.returnType && row('return', <span>{detail.returnType}</span>)}
-          {detail.callers.length > 0 &&
-            row('callers', detail.callers.map((c, i) => chip(c.name, undefined, i)))}
-          {detail.callees.length > 0 &&
-            row('callees', detail.callees.map((c, i) => chip(c.name, undefined, i)))}
-        </>
+      lines.push(...members);
+      if (hasBody) lines.push(line(pn('}'), 'end'));
+      if (cls && cls.instantiations.length > 0)
+        lines.push(commentListLine('// constructed by: ', cls.instantiations.map((c) => c.name), 'insts'));
+      if (cls && cls.references.length > 0)
+        lines.push(commentListLine('// referenced by: ', cls.references.map((r) => r.name), 'refs'));
+      break;
+    }
+    case 'function': {
+      const fn = detail?.kind === 'function' ? detail : undefined;
+      const params = fn?.parameters ?? [];
+      lines.push(
+        line(
+          <>
+            {kw('function')}
+            {' '}
+            {nm(displayName)}
+            {pn('(')}
+            {params.length > 0 &&
+              list(
+                params.map((param, i) => (
+                  <Fragment key={i}>
+                    {param.name ? (
+                      <>
+                        {mb(param.name)}
+                        {pn(': ')}
+                      </>
+                    ) : null}
+                    {ty(param.type)}
+                  </Fragment>
+                )),
+              )}
+            {pn(')')}
+            {fn?.returnType ? (
+              <>
+                {pn(': ')}
+                {ty(fn.returnType)}
+              </>
+            ) : null}
+            {pn(';')}
+          </>,
+          'decl',
+        ),
       );
-    case 'type':
-      return (
-        <>
-          {detail.properties.length > 0 &&
-            row('props', detail.properties.map((p, i) => chip(p.name, p.type, i)))}
-          {detail.usedBy.length > 0 &&
-            row('used by', detail.usedBy.map((u, i) => chip(u.name, undefined, i)))}
-          {detail.implementors.length > 0 &&
-            row('impl', detail.implementors.map((e, i) => chip(e, undefined, i)))}
-        </>
+      if (fn && fn.callers.length > 0)
+        lines.push(commentListLine('// called by: ', fn.callers.map((c) => c.name), 'callers'));
+      if (fn && fn.callees.length > 0)
+        lines.push(commentListLine('// calls: ', fn.callees.map((c) => c.name), 'callees'));
+      break;
+    }
+    case 'type': {
+      const tpe = detail?.kind === 'type' ? detail : undefined;
+      const hasBody = (tpe?.properties.length ?? 0) > 0;
+      lines.push(
+        line(
+          <>
+            {kw('interface')}
+            {' '}
+            {nm(displayName)}
+            {hasBody ? pn(' {') : null}
+          </>,
+          'decl',
+        ),
       );
-    case 'module':
-      return (
-        <>
-          {detail.exports.length > 0 &&
-            row('exports', detail.exports.map((e, i) => chip(e, undefined, i)))}
-          {detail.imports.length > 0 &&
-            row('imports', detail.imports.map((i, idx) => chip(i.name, undefined, idx)))}
-          {detail.symbols.length > 0 &&
-            row('symbols', detail.symbols.map((s, i) => chip(s, undefined, i)))}
-        </>
+      if (tpe) {
+        tpe.properties.forEach((prop, i) =>
+          lines.push(
+            line(
+              <>
+                {mb(prop.name)}
+                {prop.type ? (
+                  <>
+                    {pn(': ')}
+                    {ty(prop.type)}
+                  </>
+                ) : null}
+                {pn(';')}
+              </>,
+              `p${i}`,
+              true,
+            ),
+          ),
+        );
+      }
+      if (hasBody) lines.push(line(pn('}'), 'end'));
+      if (tpe && tpe.implementors.length > 0)
+        lines.push(commentListLine('// implemented by: ', tpe.implementors, 'impl'));
+      if (tpe && tpe.usedBy.length > 0)
+        lines.push(commentListLine('// used by: ', tpe.usedBy.map((u) => u.name), 'usedBy'));
+      break;
+    }
+    case 'module': {
+      const mod = detail?.kind === 'module' ? detail : undefined;
+      if (mod) {
+        mod.imports.forEach((imp, i) =>
+          lines.push(
+            line(
+              <>
+                {kw('import')}
+                {' '}
+                {pn("'")}
+                {str(imp.name)}
+                {pn("';")}
+              </>,
+              `imp${i}`,
+            ),
+          ),
+        );
+        if (mod.exports.length > 0)
+          lines.push(
+            line(
+              <>
+                {kw('export')}
+                {' '}
+                {pn('{ ')}
+                {list(mod.exports.map((e, i) => <Fragment key={i}>{mb(e)}</Fragment>))}
+                {pn(' }')}
+                {pn(';')}
+              </>,
+              'exports',
+            ),
+          );
+        if (mod.symbols.length > 0)
+          lines.push(commentLine(`// defines: ${mod.symbols.join(', ')}`, 'symbols'));
+      } else {
+        lines.push(
+          line(
+            <>
+              {kw('module')}
+              {' '}
+              {nm(displayName)}
+            </>,
+            'decl',
+          ),
+        );
+      }
+      break;
+    }
+    case 'external': {
+      lines.push(
+        line(
+          <>
+            {kw('external')}
+            {' '}
+            {detail?.kind === 'external' ? (
+              <>
+                {pn("'")}
+                {str(detail.label)}
+                {pn("'")}
+              </>
+            ) : (
+              nm(displayName)
+            )}
+          </>,
+          'decl',
+        ),
       );
-    case 'external':
-      return row('source', <span>{detail.label}</span>);
+      break;
+    }
   }
+
+  return (
+    <div
+      style={{
+        borderTop: `1px solid ${theme.colors.border}`,
+        background: theme.colors.backgroundSecondary,
+        padding: '10px 12px',
+        fontFamily: theme.fonts.monospace,
+        fontSize: theme.fontSizes[0],
+        lineHeight: 1.7,
+        wordBreak: 'break-word',
+      }}
+    >
+      {lines}
+    </div>
+  );
 }

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -12,7 +12,7 @@
  * injection, onNodeClick) adapted to the subsystem model — read-only.
  */
 
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { MouseEvent as ReactMouseEvent, ReactNode } from 'react';
 import {
   ReactFlow,
@@ -97,6 +97,21 @@ const edgeTypes: EdgeTypes = {
   'subsystem-edge': SubsystemEdge,
 };
 
+// Memoized drawer body: only rebuilds children when the open file changes.
+// Inner re-renders on every viewport pan/zoom and hover; recreating host
+// elements then would churn their readFile closures and flash the file
+// viewer's loading state on each render.
+const DrawerContent = memo(function DrawerContent({
+  render,
+  file,
+}: {
+  render: (file: string) => ReactNode;
+  file: string | null;
+}) {
+  if (!file) return null;
+  return <>{render(file)}</>;
+});
+
 interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
@@ -360,6 +375,26 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     [onFileSelect],
   );
 
+  // Detail-panel links: related-name clicks select the matching component —
+  // resolved by id, name, or symbol (call labels may carry a trailing `()`).
+  const resolveRelatedComponent = useCallback(
+    (ref: string) => {
+      const clean = ref.replace(/\(\)$/, '');
+      const comp = components.find(
+        (c) =>
+          c.id === clean ||
+          c.name === clean ||
+          c.symbol === clean ||
+          c.symbol?.replace(/\(\)$/, '') === clean,
+      );
+      if (!comp || comp.id === selectedRef.current?.id) return;
+      setSelected(comp);
+      setSelectedEdgeId(null);
+      onSelect?.(comp.id);
+    },
+    [components, onSelect],
+  );
+
   // Edge label data for the overlay (rendered OUTSIDE ReactFlow so the pane
   // doesn't intercept pointer events). Uses ELK-computed label midpoints from
   // the actual edge path (not node-center approximations).
@@ -408,6 +443,15 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
     return undefined;
   }, [renderFileViewer, renderFileView, components]);
 
+  // Latest-viewer ref + stable callback so DrawerContent's memo holds across
+  // unrelated Inner renders (see comment there).
+  const fileViewerRef = useRef(fileViewer);
+  fileViewerRef.current = fileViewer;
+  const renderDrawerContent = useCallback(
+    (file: string) => fileViewerRef.current?.(file) ?? null,
+    [],
+  );
+
   return (
     <div style={{ width: '100%', height: '100%', display: 'flex', flexDirection: 'row' }}>
       {/* Sidebar: scrollable title/description on top, file tree pinned to the bottom half */}
@@ -596,9 +640,15 @@ function Inner({ components, edges, onSelect, onEdgeSelect, measured: _measured,
         mechanisms={usedMechanisms}
         onClose={() => setLegendOpen(false)}
       />
-      {selected && <ComponentDetail component={selected} />}
+      {selected && (
+        <ComponentDetail
+          component={selected}
+          onOpenFile={onTreeSelectFile}
+          onRelatedSelect={resolveRelatedComponent}
+        />
+      )}
       <FileDrawer file={openFile} onClose={() => setOpenFile(null)}>
-        {fileViewer && openFile ? fileViewer(openFile) : null}
+        <DrawerContent render={renderDrawerContent} file={openFile} />
       </FileDrawer>
       {/* Startup cover — hides measurement, layout swap, and camera settle. */}
       <GraphLayoutCover revealed={layoutReady} />

package/src/subsystem/model.test.ts

@@ -4,6 +4,7 @@ import {
   convertSubsystemToEdges,
   buildSubsystemGraph,
   deriveNameFromSymbol,
+  formatPurl,
   packageColor,
 } from './model';
 import type { SubsystemComponent, SubsystemComponentEdge } from './model';
@@ -76,4 +77,14 @@ describe('subsystem graph model', () => {
     // File basename wins over a supplied name for modules (derivation precedence).
     expect(deriveNameFromSymbol(undefined, 'module', 'MyModule', 'x.ts')).toBe('x');
   });
+
+  test('formatPurl renders the human identity', () => {
+    expect(formatPurl('pkg:npm/@principal-ai/core')).toBe('@principal-ai/core');
+    expect(formatPurl('pkg:github/principal-ai/agent-monitoring')).toBe('principal-ai/agent-monitoring');
+    expect(formatPurl('pkg:npm/left-pad@1.3.0')).toBe('left-pad');
+    expect(formatPurl('pkg:gitlab/group/proj?arch=amd64')).toBe('group/proj');
+    expect(formatPurl('pkg:generic/local--Users-me-my-app')).toBe('Users-me-my-app (local)');
+    // Malformed purls pass through untouched.
+    expect(formatPurl('not-a-purl')).toBe('not-a-purl');
+  });
 });