@principal-ai/principal-view-react 0.16.45 → 0.16.47

package/src/subsystem/ComponentDeclaration.tsx

@@ -6,15 +6,16 @@
  * comments. File content lives in the bottom FileDrawer, not here.
  */
 
-import { Fragment, useState, type ReactNode } from 'react';
+import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react';
 import { AlignLeft, FileText } from 'lucide-react';
 import { useTheme } from '@principal-ade/industry-theme';
 import {
   KIND_COLOR,
-  deriveNameFromSymbol,
   formatPurl,
   type SubsystemComponent,
+  type SubsystemDeclTokenKind,
 } from './model';
+import { tokenizeComponent } from './tokenizeComponent';
 
 /** Shared affordance for clickable text pieces. */
 const clickableStyle = {
@@ -54,10 +55,12 @@ export interface ComponentDeclarationProps {
   /** Related-name click (types, callers/callees, implementors, …) → select
    *  that component if one matches; unmatched refs no-op. */
   onRelatedSelect?: (ref: string) => void;
+  /** Max width of the declaration panel (CSS value). Defaults to none. */
+  maxWidth?: string | number;
 }
 
 /** Declaration panel for the selected component — its definition, code-style. */
-export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect }: ComponentDeclarationProps) {
+export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect: _onRelatedSelect, maxWidth }: ComponentDeclarationProps) {
   const { theme } = useTheme();
   const [fileHovered, setFileHovered] = useState(false);
   // Header visibility toggles — off by default so the panel opens as pure
@@ -66,26 +69,26 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect }:
   const [showPurpose, setShowPurpose] = useState(false);
   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>;
+  // Token-kind → theme-color map (used by the token iterator below).
+  const tokenColor: Record<SubsystemDeclTokenKind, string> = {
+    keyword: theme.colors.secondary,
+    name: color,
+    member: theme.colors.info,
+    type: theme.colors.accent,
+    punctuation: muted,
+    string: theme.colors.success,
+    newline: '', // not rendered — drives line breaks
+  };
 
-  const line = (children: ReactNode, key?: string, indent?: boolean) => (
-    <div key={key} style={indent ? { paddingLeft: 16 } : undefined}>
-      {children}
-    </div>
-  );
+  const line = (children: ReactNode, key?: string, indent?: boolean | number) => {
+    const paddingLeft = typeof indent === 'number' ? indent : indent ? 16 : 0;
+    return (
+      <div key={key} style={{ display: 'flex', alignItems: 'center', whiteSpace: 'pre', minHeight: 18, ...(paddingLeft ? { paddingLeft } : {}) }}>
+        {children}
+      </div>
+    );
+  };
   const commentStyle = { color: muted, fontStyle: 'italic' } as const;
   const commentLine = (text: string, key?: string, indent?: boolean, onClick?: () => void) =>
     line(
@@ -109,15 +112,6 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect }:
   // `// implemented by:`, …) are deliberately not rendered — the graph's
   // edges carry interactions, and duplicated name lists read as clutter. The
   // data stays on the Graphify detail types for other surfaces.
-  // 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[] = [];
   // Repo identity — owner avatar + name for GitHub-hosted purls; anything
   // else falls back to the formatted purl as a quiet comment. The avatar
@@ -207,246 +201,71 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect }:
       ),
     );
 
-  const detail = component.detail;
-  // Detail facets may be hand-authored (see `detailProvenance`) and the wire
-  // carries no guarantee that every typed array is present — treat all of
-  // them as optional so a partial detail degrades to fewer lines, never a
-  // render crash.
-  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'));
-      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',
-        ),
-      );
-      // Caller/callee relationship comments (`// called by:` / `// calls:`)
-      // are deliberately not rendered here — the graph's edges carry
-      // interactions, and duplicated call lists read as clutter. The data
-      // stays on `GraphifyFunctionDetail` for other surfaces.
-      break;
-    }
-    case 'type': {
-      const tpe = detail?.kind === 'type' ? detail : undefined;
-      const hasBody = ((tpe?.properties ?? []).length) > 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'));
-      break;
+  // --- Container width measurement --------------------------------------
+  // Approximate character count from the container's clientWidth so Prettier
+  // wraps at the same column the code block will actually use.
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [printWidth, setPrintWidth] = useState(80);
+
+  const measure = useCallback(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const ch = el.querySelector('[data-declaration-line]');
+    if (ch) {
+      // Use the width of a single `ch` unit from the monospace container.
+      const charWidth = ch.getBoundingClientRect().width || 8.4;
+      setPrintWidth(Math.max(40, Math.floor(el.clientWidth / charWidth)));
+    } else {
+      // Fallback: assume ~8.4 px per char at 14px monospace.
+      setPrintWidth(Math.max(40, Math.floor(el.clientWidth / 8.4)));
     }
-    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;
+  }, []);
+
+  useEffect(() => {
+    measure();
+    const el = containerRef.current;
+    if (!el) return;
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, [measure]);
+
+  // --- Declaration tokens ------------------------------------------------
+  // Tokenize asynchronously via Prettier + highlight.js. Pre-tokenized
+  // tokens from the wire skip the pipeline entirely.
+  const [tokens, setTokens] = useState(component.tokens ?? []);
+  useEffect(() => {
+    if (component.tokens) {
+      setTokens(component.tokens);
+      return;
     }
-    case 'external': {
-      lines.push(
-        line(
-          <>
-            {kw('external')}
-            {' '}
-            {detail?.kind === 'external' ? (
-              <>
-                {pn("'")}
-                {str(detail.label)}
-                {pn("'")}
-              </>
-            ) : (
-              nm(displayName)
-            )}
-          </>,
-          'decl',
-        ),
-      );
-      break;
+    let cancelled = false;
+    tokenizeComponent(component, printWidth).then((t) => {
+      if (!cancelled) setTokens(t);
+    });
+    return () => { cancelled = true; };
+  }, [component, printWidth]);
+  const declLines: ReactNode[][] = [[]];
+  let di = 0;
+  for (const tok of tokens) {
+    if (tok.kind === 'newline') {
+      declLines.push([]);
+      di++;
+      continue;
     }
+    declLines[di].push(
+      <span key={`${di}-${declLines[di].length}`} style={{ color: tokenColor[tok.kind] }}>
+        {tok.text}
+      </span>,
+    );
+  }
+  for (let li = 0; li < declLines.length; li++) {
+    if (declLines[li].length === 0) continue;
+    lines.push(
+      <div key={`decl-${li}`} data-declaration-line style={{ display: 'flex', alignItems: 'center', whiteSpace: 'pre', minHeight: 18 }}>
+        {declLines[li]}
+      </div>,
+    );
   }
 
   // Purpose prose follows the declaration — identity and syntax first, the
@@ -468,13 +287,16 @@ export function ComponentDeclaration({ component, onOpenFile, onRelatedSelect }:
 
   return (
     <div
+      ref={containerRef}
       style={{
         background: theme.colors.backgroundSecondary,
         padding: '10px 12px',
         fontFamily: theme.fonts.monospace,
         fontSize: theme.fontSizes[1],
         lineHeight: 1.7,
-        wordBreak: 'break-word',
+        ...(maxWidth != null
+          ? { maxWidth, wordBreak: 'break-word' }
+          : { overflowX: 'auto' }),
       }}
     >
       {lines}

package/src/subsystem/formatDeclaration.ts

@@ -0,0 +1,116 @@
+/**
+ * Generate a TypeScript declaration string from a SubsystemComponent's detail.
+ *
+ * This is the "source code" that Prettier will format. The output is valid
+ * TypeScript (except for `external`, which is handled separately). The string
+ * is intentionally simple — no indentation, no line breaks — because Prettier
+ * handles all formatting.
+ */
+
+import type { SubsystemComponent } from './model';
+import type { GraphifyComponentDetail } from '../graphify';
+
+export function generateDeclarationString(component: SubsystemComponent): string {
+  const detail = component.detail;
+  const kind = detail?.kind ?? component.kind;
+  const name = component.symbol || component.name || 'untitled';
+
+  switch (kind) {
+    case 'class':
+      return generateClass(name, detail);
+    case 'function':
+      return generateFunction(name, detail);
+    case 'type':
+      return generateType(name, detail);
+    case 'module':
+      return generateModule(detail);
+    case 'external':
+      // Not valid TypeScript — caller should handle formatting.
+      return `external '${detail?.kind === 'external' ? detail.label : name}'`;
+    default:
+      return `${kind} ${name}`;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Format parameters, synthesising names for unnamed positionals. */
+function formatParams(params: { name?: string; type: string }[]): string {
+  return params
+    .map((p, i) => (p.name ? `${p.name}: ${p.type}` : `arg${i}: ${p.type}`))
+    .join(', ');
+}
+
+// ---------------------------------------------------------------------------
+// Per-kind generators
+// ---------------------------------------------------------------------------
+
+function generateClass(name: string, detail?: GraphifyComponentDetail): string {
+  const cls = detail?.kind === 'class' ? detail : undefined;
+  const parts: string[] = [`class ${name}`];
+
+  if (cls?.extends && cls.extends.length > 0) {
+    parts.push(`extends ${cls.extends.join(', ')}`);
+  }
+  if (cls?.implements && cls.implements.length > 0) {
+    parts.push(`implements ${cls.implements.join(', ')}`);
+  }
+
+  const members: string[] = [];
+
+  for (const m of cls?.methods ?? []) {
+    const ret = m.returnType ? `: ${m.returnType}` : '';
+    members.push(`  ${m.name}(${formatParams(m.parameters ?? [])})${ret};`);
+  }
+
+  for (const prop of cls?.properties ?? []) {
+    const t = prop.type ? `: ${prop.type}` : '';
+    members.push(`  ${prop.name}${t};`);
+  }
+
+  if (members.length > 0) {
+    parts.push(`{\n${members.join('\n')}\n}`);
+  } else {
+    parts.push('{}');
+  }
+
+  return parts.join(' ');
+}
+
+function generateFunction(name: string, detail?: GraphifyComponentDetail): string {
+  const fn = detail?.kind === 'function' ? detail : undefined;
+  const params = formatParams(fn?.parameters ?? []);
+  const ret = fn?.returnType ? `: ${fn.returnType}` : '';
+  return `function ${name}(${params})${ret};`;
+}
+
+function generateType(name: string, detail?: GraphifyComponentDetail): string {
+  const tpe = detail?.kind === 'type' ? detail : undefined;
+  const props = (tpe?.properties ?? [])
+    .map((p) => `  ${p.name}${p.type ? `: ${p.type}` : ''};`)
+    .join('\n');
+
+  if (props) {
+    return `interface ${name} {\n${props}\n}`;
+  }
+  return `interface ${name} {}`;
+}
+
+function generateModule(detail?: GraphifyComponentDetail): string {
+  const mod = detail?.kind === 'module' ? detail : undefined;
+  if (!mod) return 'module {}';
+
+  const parts: string[] = [];
+
+  for (const imp of mod.imports ?? []) {
+    parts.push(`import '${imp.name}';`);
+  }
+
+  if ((mod.exports ?? []).length > 0) {
+    parts.push(`export { ${mod.exports!.join(', ')} };`);
+  }
+
+  return parts.join('\n') || `module {}`;
+}

package/src/subsystem/model.ts

@@ -27,6 +27,24 @@ export type SubsystemComponentKind =
   | 'module'
   | 'external';
 
+// ---------------------------------------------------------------------------
+// Declaration tokens — structured source representation
+// ---------------------------------------------------------------------------
+
+export type SubsystemDeclTokenKind =
+  | 'keyword'
+  | 'name'
+  | 'member'
+  | 'type'
+  | 'punctuation'
+  | 'string'
+  | 'newline';
+
+export interface SubsystemDeclToken {
+  text: string;
+  kind: SubsystemDeclTokenKind;
+}
+
 export type SubsystemEdgeMechanism =
   | 'imports'
   | 'imports_from'
@@ -87,6 +105,12 @@ export interface SubsystemComponent {
    * may claim `verified`.
    */
   detailProvenance?: 'verified' | 'authored';
+  /**
+   * Pre-tokenized declaration for the detail panel. When present, the
+   * renderer skips client-side tokenization. Tokens are language-agnostic;
+   * a different language just needs a different tokenizer and text joiner.
+   */
+  tokens?: SubsystemDeclToken[];
 }
 
 /** A cross-component edge in the subsystem graph. */

package/src/subsystem/tokenizeComponent.ts

@@ -0,0 +1,70 @@
+/**
+ * Tokenize a SubsystemComponent into a flat token stream for the detail panel.
+ *
+ * Pipeline: generate declaration string → format with Prettier → tokenize
+ * with highlight.js. The `component.tokens` field, when present, overrides
+ * the entire pipeline (for pre-tokenized data from graphify).
+ *
+ * This function is async because Prettier's format() is async.
+ */
+
+import type { SubsystemComponent, SubsystemDeclToken } from './model';
+import { generateDeclarationString } from './formatDeclaration';
+import { tokenizeFormatted } from './tokenizeFormatted';
+
+// Lazy-loaded Prettier to avoid startup cost.
+let prettierPromise: Promise<typeof import('prettier/standalone')> | null = null;
+let prettierPluginsPromise: Promise<{
+  typescript: typeof import('prettier/plugins/typescript');
+  estree: typeof import('prettier/plugins/estree');
+}> | null = null;
+
+async function getPrettier() {
+  if (!prettierPromise) {
+    prettierPromise = import('prettier/standalone');
+  }
+  if (!prettierPluginsPromise) {
+    prettierPluginsPromise = Promise.all([
+      import('prettier/plugins/typescript'),
+      import('prettier/plugins/estree'),
+    ]).then(([typescript, estree]) => ({ typescript, estree }));
+  }
+  const [prettier, plugins] = await Promise.all([prettierPromise, prettierPluginsPromise]);
+  return { prettier, plugins };
+}
+
+/**
+ * Tokenize a SubsystemComponent into SubsystemDeclToken[].
+ *
+ * When `component.tokens` is present (pre-tokenized data from the wire),
+ * it's returned as-is. Otherwise the pipeline generates a TypeScript
+ * declaration string, formats it with Prettier, and tokenizes the output.
+ */
+export async function tokenizeComponent(component: SubsystemComponent, printWidth = 80): Promise<SubsystemDeclToken[]> {
+  // Pre-tokenized tokens from the wire take precedence.
+  if (component.tokens) return component.tokens;
+
+  // External kind — not valid TypeScript, bypass Prettier.
+  const kind = component.detail?.kind ?? component.kind;
+  if (kind === 'external') {
+    const label = component.detail?.kind === 'external' ? component.detail.label : component.name;
+    return [
+      { text: 'external', kind: 'keyword' },
+      { text: ' ', kind: 'punctuation' },
+      { text: "'", kind: 'punctuation' },
+      { text: label, kind: 'string' },
+      { text: "'", kind: 'punctuation' },
+    ];
+  }
+
+  // Generate → format → tokenize
+  const raw = generateDeclarationString(component);
+  const { prettier, plugins } = await getPrettier();
+  const formatted = await prettier.format(raw, {
+    parser: 'typescript',
+    plugins: [plugins.typescript, plugins.estree],
+    printWidth,
+  });
+
+  return tokenizeFormatted(formatted);
+}