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

package/src/subsystem/ComponentDetail.tsx

@@ -0,0 +1,386 @@
+/**
+ * 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 { Fragment, type ReactNode } from 'react';
+import { useTheme } from '@principal-ade/industry-theme';
+import {
+  KIND_COLOR,
+  deriveNameFromSymbol,
+  formatPurl,
+  type SubsystemComponent,
+} from './model';
+
+/** 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 (
+    <span
+      onClick={(e) => {
+        e.stopPropagation();
+        onClick();
+      }}
+      style={{
+        cursor: 'pointer',
+        textDecorationLine: 'underline',
+        textDecorationStyle: 'dotted',
+        textUnderlineOffset: 2,
+      }}
+    >
+      {children}
+    </span>
+  );
+}
+
+/** 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);
+
+  // 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 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>
+    ));
+
+  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',
+        ),
+      );
+      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',
+        ),
+      );
+      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',
+        ),
+      );
+      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',
+        ),
+      );
+      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/EdgeLegendModal.tsx

@@ -0,0 +1,146 @@
+/**
+ * EdgeLegendModal — modal over the graph area showing the edge-mechanism
+ * legend (moved out of the sidebar), plus the canonical mechanism
+ * descriptions table shared with the canvas's edge-label overlay.
+ */
+
+import { useEffect } from 'react';
+import { useTheme } from '@principal-ade/industry-theme';
+import { X } from 'lucide-react';
+import { MECHANISM_COLOR, type SubsystemEdgeMechanism } from './model';
+
+/** Mechanism → [description, verifiable-with-graphify]. Drives the legend
+ *  modal and the "not directly verifiable" styling of edge labels. */
+export const MECHANISM_DESCRIPTIONS: [SubsystemEdgeMechanism, string, boolean][] = [
+  ['imports', 'import statement (code-level dependency)', true],
+  ['imports_from', 'imported by (reverse dependency)', true],
+  ['re_exports', 're-exports symbols from', true],
+  ['defines', 'defines / declares symbol', true],
+  ['calls', 'function/method call (call graph edge)', true],
+  ['extends', 'class inheritance', true],
+  ['inherits', 'class inheritance', true],
+  ['implements', 'implements interface / protocol', true],
+  ['mixes_in', 'applies mixin', true],
+  ['uses', 'general dependency (import, call, or reference)', false],
+  ['method', 'structural: has method / member', true],
+  ['references', 'type / symbol reference (not a call)', true],
+  ['contains', 'structural: contains / encapsulates', true],
+  ['feeds', 'data flow: output feeds into input', false],
+  ['produces', 'data flow: produces / outputs', false],
+  ['registers-into', 'registration pattern', false],
+];
+
+/** Modal over the graph area showing the edge-mechanism legend (moved out of
+ *  the sidebar). Closes on backdrop click or Escape; renders nothing when
+ *  closed. */
+export function EdgeLegendModal({
+  open,
+  mechanisms,
+  onClose,
+}: {
+  open: boolean;
+  mechanisms: Set<string>;
+  onClose: () => void;
+}) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  return (
+    <div
+      onClick={onClose}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        zIndex: 20,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        background: 'rgba(0,0,0,0.5)',
+      }}
+    >
+      <div
+        onClick={(e) => e.stopPropagation()}
+        style={{
+          background: theme.colors.background,
+          border: `1px solid ${theme.colors.border}`,
+          borderRadius: 8,
+          boxShadow: '0 8px 32px rgba(0,0,0,0.4)',
+          padding: '16px',
+          width: 420,
+          maxWidth: '90%',
+          maxHeight: '80%',
+          overflowY: 'auto',
+          fontFamily: theme.fonts.body,
+        }}
+      >
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
+            marginBottom: 12,
+          }}
+        >
+          <span
+            style={{
+              fontSize: theme.fontSizes[1],
+              fontWeight: 600,
+              color: theme.colors.text,
+            }}
+          >
+            Edge Legend
+          </span>
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label="Close legend"
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              width: 22,
+              height: 22,
+              padding: 0,
+              border: 'none',
+              borderRadius: 4,
+              background: 'transparent',
+              color: theme.colors.text,
+              cursor: 'pointer',
+            }}
+          >
+            <X size={14} />
+          </button>
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+          {MECHANISM_DESCRIPTIONS.filter(([m]) => mechanisms.has(m)).map(([mechanism, desc, verifiable]) => (
+            <div key={mechanism} style={{ display: 'flex', alignItems: 'center', gap: 8, fontSize: theme.fontSizes[0] }}>
+              <span
+                style={{
+                  width: 10,
+                  height: 10,
+                  borderRadius: verifiable ? '50%' : '30% 70% 70% 30% / 30% 30% 70% 70%',
+                  background: MECHANISM_COLOR[mechanism],
+                  border: verifiable ? 'none' : `1px dashed ${MECHANISM_COLOR[mechanism]}`,
+                  flexShrink: 0,
+                }}
+              />
+              <span style={{ fontFamily: theme.fonts.monospace, color: MECHANISM_COLOR[mechanism], fontWeight: 500 }}>{mechanism}</span>
+              <span style={{ color: muted }}>{desc}</span>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/subsystem/FileDrawer.tsx

@@ -0,0 +1,105 @@
+/**
+ * FileDrawer — bottom panel that slides up from the bottom of the graph area
+ * to show a file's contents. Opened by sidebar file-tree clicks (and any host
+ * wiring); content is injected as children by the graph component.
+ */
+
+import { useEffect } from 'react';
+import type { ReactNode } from 'react';
+import { useTheme } from '@principal-ade/industry-theme';
+import { X } from 'lucide-react';
+
+/** Bottom panel that slides up from the bottom of the graph area to show a
+ *  file's contents — opened by node clicks and sidebar file-tree clicks
+ *  alike. Sits in normal flow (canvas shrinks while open, nothing covered)
+ *  and animates via height; stays mounted so open/close animates. */
+export function FileDrawer({
+  file,
+  onClose,
+  children,
+}: {
+  file: string | null;
+  onClose: () => void;
+  children?: ReactNode;
+}) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const open = file !== null;
+
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [open, onClose]);
+
+  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,
+        height: open ? '45%' : 0,
+        minHeight: 0,
+        overflow: 'hidden',
+        display: 'flex',
+        flexDirection: 'column',
+        background: theme.colors.background,
+        borderTop: open ? `1px solid ${theme.colors.border}` : 'none',
+        transition: 'height 200ms ease',
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 8,
+          padding: '6px 10px',
+          borderBottom: `1px solid ${theme.colors.border}`,
+          flexShrink: 0,
+        }}
+      >
+        <span
+          title={file ?? undefined}
+          style={{
+            flex: 1,
+            minWidth: 0,
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+            fontFamily: theme.fonts.monospace,
+            fontSize: theme.fontSizes[0],
+            color: muted,
+          }}
+        >
+          {file}
+        </span>
+        <button
+          type="button"
+          onClick={onClose}
+          aria-label="Close file"
+          style={{
+            display: 'inline-flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            width: 22,
+            height: 22,
+            padding: 0,
+            border: 'none',
+            borderRadius: 4,
+            background: 'transparent',
+            color: theme.colors.text,
+            cursor: 'pointer',
+          }}
+        >
+          <X size={14} />
+        </button>
+      </div>
+      <div style={{ flex: 1, minHeight: 0, overflow: 'auto' }}>{children}</div>
+    </div>
+  );
+}