@principal-ai/principal-view-react 0.16.59 → 0.16.61

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -79,8 +79,22 @@ export interface SubsystemComponentGraphProps {
   maxNodeWidth?: number;
   /** Show edge labels (mechanism names) on the graph. @default true */
   showEdgeLabels?: boolean;
+  /** Show the mechanism-legend button overlay on the canvas. @default true */
+  showLegend?: boolean;
   /** Subsystem title displayed in the sidebar. */
   title?: string;
+  /**
+   * Suppresses the sidebar entirely (title, description, file tree,
+   * throughlines) for graph-only embeds. Pair with `graphTitle` to keep the
+   * subsystem name visible as an overlay on the canvas.
+   */
+  hideSidebar?: boolean;
+  /**
+   * Subsystem title rendered as a non-interactive overlay chip on the graph
+   * canvas (top-center). Does not trigger the sidebar — for graph-only
+   * embeds that still need to name what they show.
+   */
+  graphTitle?: string;
   /** Markdown description rendered in the sidebar. */
   description?: string;
   /** Rendered over the graph canvas only (not the title/legend sidebar). */
@@ -143,7 +157,7 @@ interface InnerProps extends SubsystemComponentGraphProps {
   measured: { w: number; h: number } | null;
 }
 
-function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, title, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
+function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measured: _measured, maxNodeWidth, showEdgeLabels, showLegend, title, hideSidebar, graphTitle, description, canvasOverlay, sidebarExtra, sidebarAfterDescription, renderFileView, renderFileViewer, onFileSelect, onVerifyComponent, componentVerification }: InnerProps) {
   const { theme } = useTheme();
   const { fitView } = useReactFlow();
   const viewport = useViewport();
@@ -770,7 +784,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
   return (
     <div style={{ width: '100%', height: '100%', display: 'flex', flexDirection: 'row' }}>
       {/* Sidebar: scrollable title/description on top, files or flows pinned to the bottom half */}
-      {(title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasThroughlines) && (
+      {!hideSidebar && (title || description || sidebarExtra || sidebarAfterDescription || treeFilePaths.length > 0 || hasThroughlines) && (
         <div
           style={{
             width: 340,
@@ -1052,7 +1066,7 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
         <Controls showZoom showFitView showInteractive />
       </ReactFlow>
       {/* Legend button — top-left overlay on the canvas; opens the modal. */}
-      {usedMechanisms.size > 0 && (
+      {showLegend !== false && usedMechanisms.size > 0 && (
         <button
           type="button"
           onClick={() => setLegendOpen(true)}
@@ -1078,6 +1092,36 @@ function Inner({ components, edges, throughlines, onSelect, onEdgeSelect, measur
           <MapIcon size={13} />
           Legend
         </button>
+      )}
+      {/* Graph title — non-interactive chip centered at the top of the canvas
+          (clear of the top-left legend button and top-right declaration
+          card). Lets graph-only embeds name the subsystem they show. */}
+      {graphTitle && (
+        <div
+          style={{
+            position: 'absolute',
+            top: 10,
+            left: '50%',
+            transform: 'translateX(-50%)',
+            zIndex: 6,
+            maxWidth: '60%',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+            padding: '6px 18px',
+            fontSize: theme.fontSizes[3],
+            fontWeight: 600,
+            fontFamily: theme.fonts.heading,
+            color: theme.colors.text,
+            background: theme.colors.backgroundSecondary ?? theme.colors.background,
+            border: `1px solid ${theme.colors.border}`,
+            borderRadius: 6,
+            boxShadow: '0 1px 4px rgba(0,0,0,0.25)',
+            pointerEvents: 'none',
+          }}
+        >
+          {graphTitle}
+        </div>
       )}
         {/* Selected-component declaration — floating card over the canvas
             (top-right, clear of the top-left legend button). The graph never

package/src/subsystem/model.test.ts

@@ -7,6 +7,8 @@ import {
   processGroupNodeId,
   buildSubsystemGraph,
   deriveNameFromSymbol,
+  constructBadgeLabel,
+  nodeMinWidthForBadges,
   formatPurl,
   packageColor,
   subsystemGraphLayoutKey,
@@ -105,6 +107,48 @@ describe('subsystem graph model', () => {
     expect(deriveNameFromSymbol('Foo {}', 'class')).toBe('Foo {}');
   });
 
+  test('deriveNameFromSymbol uses JSX decoration for component stereotype', () => {
+    expect(deriveNameFromSymbol('AnalysisView', 'function', undefined, undefined, 'component')).toBe(
+      '<AnalysisView>',
+    );
+    expect(deriveNameFromSymbol('useDrawingsHost', 'function', undefined, undefined, 'hook')).toBe(
+      'useDrawingsHost()',
+    );
+  });
+
+  test('constructBadgeLabel prefers framework · stereotype over construct', () => {
+    expect(
+      constructBadgeLabel({
+        construct: 'function',
+        framework: 'react',
+        stereotype: 'component',
+      }),
+    ).toBe('react · component');
+    expect(constructBadgeLabel({ construct: 'function', stereotype: 'hook' })).toBe('hook');
+    expect(constructBadgeLabel({ construct: 'function' })).toBe('function');
+    expect(constructBadgeLabel({ construct: 'type_alias' })).toBe('type alias');
+  });
+
+  test('nodeMinWidthForBadges widens for long construct badges and role pairs', () => {
+    const plain = nodeMinWidthForBadges({ construct: 'function' });
+    expect(plain).toBe(150);
+
+    const stereotype = nodeMinWidthForBadges({
+      construct: 'function',
+      framework: 'react',
+      stereotype: 'component',
+    });
+    expect(stereotype).toBeGreaterThan(150);
+
+    const withRole = nodeMinWidthForBadges({
+      construct: 'function',
+      framework: 'react',
+      stereotype: 'component',
+      role: 'entry',
+    });
+    expect(withRole).toBeGreaterThan(stereotype);
+  });
+
   test('deriveNameFromSymbol falls back to file basename for modules', () => {
     expect(deriveNameFromSymbol(undefined, 'module', undefined, 'transcript.ts')).toBe('transcript');
     expect(deriveNameFromSymbol(undefined, 'module', undefined, 'src/event-processors/index.ts')).toBe('index');

package/src/subsystem/model.ts

@@ -45,6 +45,22 @@ export type SubsystemComponentConstruct =
  */
 export type SubsystemComponentRole = 'entry' | 'service';
 
+/**
+ * Framework that owns a stereotype vocabulary (open string).
+ * Examples: `react`, `vue`, `nestjs`, `django`, `spring`.
+ * Empty when the node is language-only / framework-agnostic.
+ */
+export type SubsystemFramework = string;
+
+/**
+ * Framework-level pattern stamped on a language construct (open string).
+ * Examples: `component`, `hook`, `middleware`, `controller`, `guard`.
+ * Empty when no framework pattern applies. Pair with `framework` when set —
+ * a React component stays `construct: 'function'` with
+ * `framework: 'react'` + `stereotype: 'component'`.
+ */
+export type SubsystemStereotype = string;
+
 // ---------------------------------------------------------------------------
 // Declaration tokens — structured source representation
 // ---------------------------------------------------------------------------
@@ -97,7 +113,10 @@ export interface SubsystemComponent {
    * anchors to a definition; runtime occurrences (variables, activations,
    * instances) are NOT constructs — they belong to a future execution-mode
    * graph whose occurrence nodes reference these definitions. Ontology:
-   * construct = what it is, role = where it sits, process = where it runs.
+   * construct = what it is, framework + stereotype = which framework pattern
+   * it plays, role = where it sits, process = where it runs. Prefer
+   * `framework` + `stereotype` over inventing framework-specific constructs
+   * (a React component is still `construct: 'function'`).
    */
   construct: SubsystemComponentConstruct;
   /** Source location the component lives in (repo-root-relative path). */
@@ -115,6 +134,17 @@ export interface SubsystemComponent {
    * inbound, `produces` outbound).
    */
   role?: SubsystemComponentRole;
+  /**
+   * Framework that owns the stereotype vocabulary (e.g. `react`, `nestjs`).
+   * Orthogonal to `construct` — leave empty for language-only units.
+   */
+  framework?: SubsystemFramework;
+  /**
+   * Framework pattern this declaration plays (e.g. `component`, `hook`).
+   * When set, the node badge prefers this label over the construct name so
+   * a React UI unit reads as "component" rather than "function".
+   */
+  stereotype?: SubsystemStereotype;
   /**
    * Runtime process membership — which deployment unit this node is a
    * member of (e.g. `trail-viewer/host`, `trail-viewer/renderer`). Nodes
@@ -225,6 +255,7 @@ export function deriveNameFromSymbol(
   construct: SubsystemComponentConstruct,
   existingName?: string,
   file?: string,
+  stereotype?: string,
 ): string {
   let name: string | undefined;
   if (symbol && symbol.trim()) {
@@ -236,10 +267,13 @@ export function deriveNameFromSymbol(
   }
   if (!name) name = existingName ?? 'untitled';
 
-  // Decoration = what the drill-down shows. Executable constructs wear `()`
-  // (a signature you can call); brace-bodied constructs wear ` {}` (a member
-  // body — fields for types/interfaces/enums, fields+methods for classes).
-  // Everything else (store, variable, module, external) renders bare.
+  // Decorations = what the drill-down shows. Framework stereotypes can override
+  // the language decoration (a React component wears `<>` instead of `()`).
+  // Executable constructs wear `()`; brace-bodied constructs wear ` {}`.
+  // Everything else (store, module, external) renders bare.
+  if (stereotype === 'component' && !name.startsWith('<')) {
+    return `<${name}>`;
+  }
   if ((construct === 'function' || construct === 'method') && !name.endsWith('()')) {
     name = `${name}()`;
   }
@@ -443,6 +477,64 @@ export const ROLE_LABEL: Record<SubsystemComponentRole, string> = {
   service: 'service',
 };
 
+/**
+ * Primary badge text for a node: prefer framework stereotype over the
+ * language construct so a React UI unit reads as "component" / "hook"
+ * rather than "function". When both framework and stereotype are set,
+ * show `framework · stereotype` (e.g. `react · component`).
+ */
+export function constructBadgeLabel(component: {
+  construct: SubsystemComponentConstruct;
+  framework?: string;
+  stereotype?: string;
+}): string {
+  const constructLabel =
+    component.construct === 'type_alias' ? 'type alias' : component.construct;
+  if (component.stereotype && component.framework) {
+    return `${component.framework} · ${component.stereotype}`;
+  }
+  if (component.stereotype) return component.stereotype;
+  return constructLabel ?? '';
+}
+
+/** Default CSS floor for component nodes (padding aside). */
+export const NODE_CSS_MIN_WIDTH = 150;
+/** Inset of each top badge from the node edge (`left` / `right` style). */
+export const BADGE_EDGE_INSET = 5;
+/** Minimum gap between left construct badge and right role badge. */
+const BADGE_PAIR_GAP = 8;
+/** Badge box chrome: padding 5+5 + border 1+1. */
+const BADGE_BOX_CHROME = 12;
+/** Approx monospace uppercase width incl. letter-spacing (~0.5px). */
+const BADGE_CHAR_WIDTH = 8;
+
+/** Estimated rendered width of a top tab badge label. */
+export function estimateBadgeLabelWidth(label: string): number {
+  return (label?.length ?? 0) * BADGE_CHAR_WIDTH + BADGE_BOX_CHROME;
+}
+
+/**
+ * Minimum node width so top badges stay on one line and (when both are
+ * present) don't overlap — badges are absolutely positioned, so they don't
+ * contribute to layout unless we widen the node explicitly.
+ */
+export function nodeMinWidthForBadges(component: {
+  construct: SubsystemComponentConstruct;
+  framework?: string;
+  stereotype?: string;
+  role?: SubsystemComponentRole;
+}): number {
+  const left = estimateBadgeLabelWidth(constructBadgeLabel(component));
+  if (component.role == null) {
+    return Math.max(NODE_CSS_MIN_WIDTH, BADGE_EDGE_INSET + left + BADGE_EDGE_INSET);
+  }
+  const right = estimateBadgeLabelWidth(ROLE_LABEL[component.role]);
+  return Math.max(
+    NODE_CSS_MIN_WIDTH,
+    BADGE_EDGE_INSET + left + BADGE_PAIR_GAP + right + BADGE_EDGE_INSET,
+  );
+}
+
 /**
  * Convert a subsystem graph document into React Flow nodes. Components that
  * carry a `process` get a `parentId` pointing at their boundary group node
@@ -489,9 +581,9 @@ export function convertSubsystemToNodes(
         .sort((a, b) => b.length - a.length)[0];
       const cap = maxNodeWidth ?? 300;
       const textWidth = Math.min(cap, Math.max(60, (text?.length ?? 10) * 8));
-      // Account for CSS minWidth and padding/border so ELK's port positions match
-      // the actual rendered node boundaries.
-      const cssMinWidth = 150;
+      // Account for CSS minWidth (incl. top badges) and padding/border so ELK's
+      // port positions match the actual rendered node boundaries.
+      const cssMinWidth = nodeMinWidthForBadges(c);
       const cssPadding = 20; // horizontal padding (left + right)
       const cssBorder = 4; // 2px border each side
       const rawWidth = Math.max(cssMinWidth, textWidth + cssPadding + cssBorder);

package/src/subsystem/nodes.tsx

@@ -21,7 +21,10 @@ import {
   MECHANISM_STYLE,
   ROLE_COLOR,
   ROLE_LABEL,
+  constructBadgeLabel,
   deriveNameFromSymbol,
+  BADGE_EDGE_INSET,
+  nodeMinWidthForBadges,
   packageColor,
   type SubsystemGraphNodeData,
   type SubsystemGroupNodeData,
@@ -86,7 +89,10 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
   const configuredMax = SUBSYSTEM_CALLBACKS.maxNodeWidth;
   const maxWidth = configuredMax ?? 300;
   // `symbol` is the source of truth; `name` is derived from it consistently.
-  const displayName = deriveNameFromSymbol(c.symbol, c.construct, c.name, c.file);
+  const displayName = deriveNameFromSymbol(c.symbol, c.construct, c.name, c.file, c.stereotype);
+  // Top badges are absolutely positioned — widen the node so they nowrap
+  // instead of wrapping, including when construct + role badges share the top.
+  const badgeMinWidth = nodeMinWidthForBadges(c);
   // Set while a file is open in the drawer: true → spotlight, false → dim,
   // absent (no file open) → neutral.
   const fileMatch = data.fileMatch as boolean | undefined;
@@ -117,7 +123,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
         boxSizing: 'border-box',
         width: nodeWidth,
         height: nodeHeight,
-        minWidth: 150,
+        minWidth: badgeMinWidth,
         maxWidth,
         padding: '6px 10px',
         borderRadius: 8,
@@ -135,20 +141,21 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
         fontFamily: theme.fonts.body,
       }}
     >
-      {/* Construct badge — a small tab riding the top-right border, in the
-          construct color. Persistent (no hover needed); pointer-events none so
-          clicks pass through to the node. */}
+      {/* Construct / stereotype badge — prefers framework stereotype so a
+          React UI unit reads as "react · component" instead of "function".
+          Persistent; pointer-events none so clicks pass through to the node. */}
       <div
         style={{
           position: 'absolute',
           top: -9,
-          left: 10,
+          left: BADGE_EDGE_INSET,
           zIndex: 1,
           fontFamily: theme.fonts.monospace,
           fontSize: theme.fontSizes[0] * 1.1,
           letterSpacing: 0.5,
           textTransform: 'uppercase',
           lineHeight: '17px',
+          whiteSpace: 'nowrap',
           color,
           background: theme.colors.backgroundSecondary ?? theme.colors.background,
           border: `1px solid ${color}`,
@@ -156,7 +163,7 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
           padding: '0 5px',
         }}
       >
-        {CONSTRUCT_LABEL[c.construct] ?? c.construct}
+        {constructBadgeLabel(c)}
       </div>
 
       {/* Role badge — top-right, only when the node carries a topology role.
@@ -167,13 +174,14 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
           style={{
             position: 'absolute',
             top: -9,
-            right: 10,
+            right: BADGE_EDGE_INSET,
             zIndex: 1,
             fontFamily: theme.fonts.monospace,
             fontSize: theme.fontSizes[0] * 1.1,
             letterSpacing: 0.5,
             textTransform: 'uppercase',
             lineHeight: '17px',
+            whiteSpace: 'nowrap',
             color: ROLE_COLOR[c.role],
             background: theme.colors.backgroundSecondary ?? theme.colors.background,
             border: `1px solid ${ROLE_COLOR[c.role]}`,
@@ -242,10 +250,15 @@ export function SubsystemComponentNode(props: NodeProps<Node<SubsystemGraphNodeD
       </div>
 
       {/* Hide the identity line when the symbol is just the title without its
-          decoration (`()` or ` {}`) — only show it when it adds information
-          (e.g. the dotted host on methods, or a different code identity). */}
+          decoration (`()`, ` {}`, or `<>`) — only show it when it adds
+          information (e.g. the dotted host on methods, or a different code
+          identity). */}
       {c.symbol &&
-        c.symbol !== displayName.replace(/ ?\{\}$/, '').replace(/\(\)$/, '') && (
+        c.symbol !==
+          displayName
+            .replace(/^<(.+)>$/, '$1')
+            .replace(/ ?\{\}$/, '')
+            .replace(/\(\)$/, '') && (
         <div
           style={{
             fontSize: theme.fontSizes[0] * 0.82,