@principal-ai/subsystems-react 0.24.23 → 0.24.25

package/src/subsystem/ConstructsCatalog.tsx

@@ -11,7 +11,7 @@ import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { ReactNode } from 'react';
 import { useTheme } from '@principal-ade/industry-theme';
 import { IndustryMarkdownSlide } from 'themed-markdown';
-import { ChevronDown, ChevronUp } from 'lucide-react';
+import { ChevronDown, ChevronRight, ChevronUp, FileText, Folder } from 'lucide-react';
 import {
   constructBadgeColor,
   constructBadgeLabel,
@@ -55,6 +55,55 @@ const FileDrawerContent = memo(function FileDrawerContent({
   return <>{render(file, startLine != null ? { startLine } : undefined)}</>;
 });
 
+interface FileTreeNode {
+  name: string;
+  /** Full path for files; path prefix for folders. */
+  path: string;
+  isFile: boolean;
+  children: FileTreeNode[];
+  /** Components declared in this file (file nodes only). */
+  components: SubsystemComponent[];
+}
+
+/** Build a folder/file tree from component `file` paths. */
+function buildFileTree(components: SubsystemComponent[]): FileTreeNode {
+  const root: FileTreeNode = {
+    name: '',
+    path: '',
+    isFile: false,
+    children: [],
+    components: [],
+  };
+  for (const c of components) {
+    if (!c.file) continue;
+    const parts = c.file.split('/').filter(Boolean);
+    let node = root;
+    let prefix = '';
+    parts.forEach((name, i) => {
+      const isFile = i === parts.length - 1;
+      prefix = prefix ? `${prefix}/${name}` : name;
+      let child = node.children.find(
+        (x) => x.name === name && x.isFile === isFile,
+      );
+      if (!child) {
+        child = { name, path: prefix, isFile, children: [], components: [] };
+        node.children.push(child);
+      }
+      node = child;
+    });
+    node.components.push(c);
+  }
+  const sortNode = (n: FileTreeNode) => {
+    n.children.sort((a, b) => {
+      if (a.isFile !== b.isFile) return a.isFile ? 1 : -1;
+      return a.name.localeCompare(b.name);
+    });
+    n.children.forEach(sortNode);
+  };
+  sortNode(root);
+  return root;
+}
+
 function resolveRelated(
   components: SubsystemComponent[],
   ref: string,
@@ -69,9 +118,7 @@ function resolveRelated(
   );
 }
 
-const GH_PURL = /^pkg:github\/([^/]+)\/([^/#?]+)/;
-
-/** Repo/app label for a purl group header. */
+const GH_PURL = /^pkg:github\/([^/]+)\/([^/#?]+)/;/** Repo/app label for a purl group header. */
 function repoLabel(c: SubsystemComponent): string {
   const m = GH_PURL.exec(c.purl ?? '');
   if (m) return m[2]!;
@@ -131,6 +178,11 @@ export function ConstructsCatalog({
   );
   const [descriptionVisible, setDescriptionVisible] = useState(false);
   const [descToggleHover, setDescToggleHover] = useState(false);
+  const [hoveredRow, setHoveredRow] = useState<string | null>(null);
+  const [sidebarTab, setSidebarTab] = useState<'constructs' | 'files'>('constructs');
+  const [collapsedFolders, setCollapsedFolders] = useState<Set<string>>(
+    new Set(),
+  );
   const [drawer, setDrawer] = useState<{ file: string; startLine?: number } | null>(
     null,
   );
@@ -143,6 +195,12 @@ export function ConstructsCatalog({
     [orderedComponents, visibleSet],
   );
 
+  const fileTree = useMemo(() => buildFileTree(orderedComponents), [orderedComponents]);
+  const hasFiles = useMemo(
+    () => orderedComponents.some((c) => !!c.file),
+    [orderedComponents],
+  );
+
   // Group visible declarations by purl so the repo/app identity (logo + name)
   // renders once per group instead of on every card.
   const repoGroups = useMemo(() => {
@@ -235,6 +293,169 @@ export function ConstructsCatalog({
     [],
   );
 
+  const toggleFolder = useCallback((path: string) => {
+    setCollapsedFolders((prev) => {
+      const next = new Set(prev);
+      if (next.has(path)) next.delete(path);
+      else next.add(path);
+      return next;
+    });
+  }, []);
+
+  /** File-tree click: show every construct declared in the file, or hide them
+   *  all when they're already shown — mirroring a construct row toggle. */
+  const toggleFile = useCallback(
+    (comps: SubsystemComponent[]) => {
+      const ids = comps.map((c) => c.id);
+      setVisibleIds((prev) => {
+        const set = new Set(prev);
+        const allVisible = ids.every((id) => set.has(id));
+        ids.forEach((id) => (allVisible ? set.delete(id) : set.add(id)));
+        return orderedComponents.filter((c) => set.has(c.id)).map((c) => c.id);
+      });
+      const first = comps[0];
+      if (first) {
+        setFocusedId(first.id);
+        onSelect?.(first.id);
+      }
+    },
+    [orderedComponents, onSelect],
+  );
+
+  const renderTree = useCallback(
+    (node: FileTreeNode, depth: number): ReactNode => {
+      return node.children.map((child) => {
+        if (!child.isFile) {
+          const collapsed = collapsedFolders.has(child.path);
+          const hovered = hoveredRow === child.path;
+          return (
+            <li key={child.path} role="presentation">
+              <button
+                type="button"
+                onClick={() => toggleFolder(child.path)}
+                onMouseEnter={() => setHoveredRow(child.path)}
+                onMouseLeave={() =>
+                  setHoveredRow((h) => (h === child.path ? null : h))
+                }
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 4,
+                  width: '100%',
+                  padding: '4px 8px',
+                  paddingLeft: 8 + depth * 12,
+                  border: 'none',
+                  borderRadius: 6,
+                  background: hovered ? theme.colors.border : 'transparent',
+                  color:
+                    hovered
+                      ? theme.colors.text
+                      : theme.colors.textSecondary ?? muted,
+                  fontFamily: theme.fonts.monospace,
+                  fontSize: theme.fontSizes[0],
+                  textAlign: 'left',
+                  cursor: 'pointer',
+                  transition: 'background 100ms ease',
+                }}
+              >
+                {collapsed ? <ChevronRight size={12} /> : <ChevronDown size={12} />}
+                <Folder size={12} />
+                <span
+                  style={{
+                    minWidth: 0,
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    whiteSpace: 'nowrap',
+                  }}
+                >
+                  {child.name}
+                </span>
+              </button>
+              {!collapsed && (
+                <ul style={{ listStyle: 'none', margin: 0, padding: 0 }}>
+                  {renderTree(child, depth + 1)}
+                </ul>
+              )}
+            </li>
+          );
+        }
+        const ids = child.components.map((c) => c.id);
+        const allVisible = ids.length > 0 && ids.every((id) => visibleSet.has(id));
+        const hovered = hoveredRow === child.path;
+        const color = componentColor(child.components[0]!, pierreTheme);
+        return (
+          <li key={child.path} role="presentation">
+            <button
+              type="button"
+              data-testid={`file-row-${child.path}`}
+              aria-pressed={allVisible}
+              onClick={() => toggleFile(child.components)}
+              onMouseEnter={() => setHoveredRow(child.path)}
+              onMouseLeave={() =>
+                setHoveredRow((h) => (h === child.path ? null : h))
+              }
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: 6,
+                width: '100%',
+                padding: '4px 8px',
+                paddingLeft: 8 + depth * 12 + 16,
+                border: 'none',
+                borderRadius: 6,
+                background: hovered ? theme.colors.border : 'transparent',
+                color:
+                  allVisible
+                    ? color
+                    : hovered
+                      ? theme.colors.text
+                      : theme.colors.textSecondary ?? muted,
+                fontFamily: theme.fonts.monospace,
+                fontSize: theme.fontSizes[0],
+                textAlign: 'left',
+                cursor: 'pointer',
+                transition: 'background 100ms ease',
+              }}
+            >
+              <FileText size={12} style={{ flexShrink: 0 }} />
+              <span
+                style={{
+                  flex: 1,
+                  minWidth: 0,
+                  overflow: 'hidden',
+                  textOverflow: 'ellipsis',
+                  whiteSpace: 'nowrap',
+                  fontWeight: allVisible ? 600 : 400,
+                }}
+              >
+                {child.name}
+              </span>
+              <span
+                style={{
+                  flexShrink: 0,
+                  fontSize: theme.fontSizes[0] * 0.85,
+                  color: allVisible ? color : muted,
+                }}
+              >
+                {ids.length}
+              </span>
+            </button>
+          </li>
+        );
+      });
+    },
+    [
+      collapsedFolders,
+      hoveredRow,
+      visibleSet,
+      toggleFolder,
+      toggleFile,
+      theme,
+      muted,
+      pierreTheme,
+    ],
+  );
+
   const onOpenFile = useCallback(
     (file: string, opts?: SubsystemOpenFileOptions) => {
       const startLine = opts?.startLine;
@@ -458,18 +679,45 @@ export function ConstructsCatalog({
           </div>
         )}
         <div
+          role="tablist"
+          aria-label="Sidebar view"
           style={{
-            padding: '10px 16px 6px',
-            fontSize: theme.fontSizes[0],
-            fontFamily: theme.fonts.monospace,
-            letterSpacing: 0.4,
-            textTransform: 'uppercase',
-            color: muted,
+            display: 'flex',
+            gap: 4,
+            padding: '8px 12px 6px',
             flexShrink: 0,
+            borderBottom: `1px solid ${theme.colors.border}`,
           }}
         >
-          Constructs
+          {(['constructs', 'files'] as const).map((tab) => {
+            if (tab === 'files' && !hasFiles) return null;
+            const active = sidebarTab === tab;
+            return (
+              <button
+                key={tab}
+                type="button"
+                role="tab"
+                aria-selected={active}
+                onClick={() => setSidebarTab(tab)}
+                style={{
+                  padding: '3px 10px',
+                  border: 'none',
+                  borderRadius: 6,
+                  background: active ? theme.colors.border : 'transparent',
+                  color: active ? theme.colors.text : muted,
+                  fontSize: theme.fontSizes[0],
+                  fontFamily: theme.fonts.monospace,
+                  letterSpacing: 0.4,
+                  textTransform: 'uppercase',
+                  cursor: 'pointer',
+                }}
+              >
+                {tab === 'constructs' ? 'Constructs' : 'Files'}
+              </button>
+            );
+          })}
         </div>
+        {sidebarTab === 'constructs' ? (
         <ul
           role="listbox"
           aria-label="Constructs"
@@ -503,6 +751,7 @@ export function ConstructsCatalog({
               !!c.file &&
               c.file === drawer.file &&
               c.declarationRef?.startLine === drawer.startLine;
+            const hovered = hoveredRow === c.id;
             return (
               <li key={c.id} role="presentation">
                 <button
@@ -512,6 +761,10 @@ export function ConstructsCatalog({
                   aria-selected={visible}
                   data-testid={`construct-row-${c.id}`}
                   onClick={() => toggle(c.id)}
+                  onMouseEnter={() => setHoveredRow(c.id)}
+                  onMouseLeave={() =>
+                    setHoveredRow((h) => (h === c.id ? null : h))
+                  }
                   style={{
                     display: 'flex',
                     flexDirection: 'column',
@@ -523,10 +776,13 @@ export function ConstructsCatalog({
                     textAlign: 'left',
                     border: 'none',
                     borderRadius: 6,
-                    background: visible
-                      ? theme.colors.background
-                      : 'transparent',
+                    background: hovered
+                      ? theme.colors.border
+                      : visible
+                        ? theme.colors.background
+                        : 'transparent',
                     cursor: 'pointer',
+                    transition: 'background 100ms ease, opacity 100ms ease',
                     boxShadow: [
                       visible ? `inset 0 0 0 1px ${theme.colors.border}` : null,
                       rowOpen ? `inset 2px 0 0 ${accentColor}` : null,
@@ -535,7 +791,7 @@ export function ConstructsCatalog({
                       .join(', ') || undefined,
                     outline: focused && !visible ? `1px dotted ${muted}` : undefined,
                     outlineOffset: -1,
-                    opacity: visible ? 1 : 0.72,
+                    opacity: visible ? 1 : hovered ? 1 : 0.72,
                   }}
                 >
                   <span
@@ -593,6 +849,22 @@ export function ConstructsCatalog({
             );
           })}
         </ul>
+        ) : (
+          <ul
+            role="tree"
+            aria-label="Files"
+            style={{
+              listStyle: 'none',
+              margin: 0,
+              padding: '6px 8px 12px',
+              overflowY: 'auto',
+              flex: 1,
+              minHeight: 0,
+            }}
+          >
+            {renderTree(fileTree, 0)}
+          </ul>
+        )}
       </aside>
       <div
         style={{

package/src/subsystem/model.test.ts

@@ -8,6 +8,8 @@ import {
   getSubsystemPackageRegions,
   processGroupNodeId,
   moduleGroupNodeId,
+  moduleBadgeLabel,
+  moduleMinWidthForBadge,
   packageGroupNodeId,
   buildBoundaryLayoutGroups,
   buildSubsystemGraph,

package/src/subsystem/model.ts

@@ -502,6 +502,27 @@ export function moduleGroupNodeId(moduleKey: string): string {
   return `module:${moduleKey}`;
 }
 
+export const MODULE_BADGE_INSET = 12;
+const MODULE_BADGE_CHAR_WIDTH = 12.5;
+const MODULE_BADGE_CHROME = 16;
+const MODULE_FRAME_BORDER = 4;
+
+export function moduleBadgeLabel(path: string, availableWidth = 0): string {
+  if (path.length * MODULE_BADGE_CHAR_WIDTH + MODULE_BADGE_CHROME <= availableWidth) {
+    return path;
+  }
+  const parts = path.split(/[\\/]/).filter((part) => part !== '' && part !== '.');
+  if (parts.length <= 2) return path;
+  return `${parts[0]}/…/${parts[parts.length - 1]}`;
+}
+
+export function moduleMinWidthForBadge(path: string): number {
+  return Math.ceil(
+    moduleBadgeLabel(path).length * MODULE_BADGE_CHAR_WIDTH +
+      MODULE_BADGE_CHROME + MODULE_BADGE_INSET * 2 + MODULE_FRAME_BORDER,
+  );
+}
+
 /** React Flow id for a package (repo) boundary group node. */
 export function packageGroupNodeId(packageKey: string): string {
   return `package:${packageKey}`;
@@ -1363,6 +1384,7 @@ export async function buildSubsystemGraph(
           id: g.id,
           memberIds: g.memberIds,
           parentId: g.parentId,
+          minWidth: g.region.kind === 'module' ? moduleMinWidthForBadge(g.region.label) : undefined,
         })),
       });
       const builtGroupIds = new Set(result.groupBounds.keys());

package/src/subsystem/nodes.test.ts

@@ -1,5 +1,9 @@
-import { describe, expect, test } from 'bun:test';
-import { EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility, hexWithAlpha } from './nodes';
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
+import { createElement, type ComponentProps } from 'react';
+import { cleanup, fireEvent, render } from '@testing-library/react/pure';
+import { ThemeProvider } from '@principal-ade/industry-theme';
+import { Window } from 'happy-dom';
+import { EDGE_DIM_ALPHA, fileMatchForNode, flowElementVisibility, hexWithAlpha, SubsystemGroupNode } from './nodes';
 
 describe('hexWithAlpha', () => {
   test('appends a two-digit alpha to #rrggbb', () => {

package/src/subsystem/nodes.tsx

@@ -29,6 +29,8 @@ import {
   deriveNameFromSymbol,
   BADGE_EDGE_INSET,
   nodeMinWidthForBadges,
+  MODULE_BADGE_INSET,
+  moduleBadgeLabel,
   packageColor,
   type SubsystemGraphNodeData,
   type SubsystemGroupNodeData,
@@ -352,6 +354,12 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
   // Kind is carried by frame chrome (square = process; rounded = module/package)
   // — don't prefix `module ·` / `package ·` or the path reads twice.
   const label = region?.label ?? '';
+  const [expandedLabel, setExpandedLabel] = useState<string | null>(null);
+  const isModule = region?.kind === 'module';
+  const expanded = isModule && expandedLabel === label;
+  const availableBadgeWidth = Math.max(0, (width ?? 400) - MODULE_BADGE_INSET * 2 - 4);
+  const collapsedLabel = isModule ? moduleBadgeLabel(label, availableBadgeWidth) : label;
+  const canExpand = isModule && collapsedLabel !== label;
   // Process frames match external nodes — square corners (outside the soft
   // component language). Module / package frames keep the rounded look.
   const isProcess = region?.kind === 'process';
@@ -382,6 +390,26 @@ export function SubsystemGroupNode(props: NodeProps<Node<SubsystemGroupNodeData,
       }}
     >
       <div
+        className={isModule ? 'nodrag nopan' : undefined}
+        role={canExpand ? 'button' : undefined}
+        tabIndex={canExpand && !hidden ? 0 : undefined}
+        aria-expanded={canExpand ? expanded : undefined}
+        aria-label={canExpand ? `${expanded ? 'Collapse' : 'Expand'} module path: ${label}` : undefined}
+        title={isModule ? label : undefined}
+        onClick={canExpand ? (event) => {
+          event.stopPropagation();
+          setExpandedLabel(expanded ? null : label);
+        } : undefined}
+        onKeyDown={canExpand ? (event) => {
+          if (event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            event.stopPropagation();
+            setExpandedLabel(expanded ? null : label);
+          } else if (event.key === 'Escape' && expanded) {
+            event.stopPropagation();
+            setExpandedLabel(null);
+          }
+        } : undefined}
         style={{
           position: 'absolute',
           // Process: badge fill starts with the process fill (inside the

package/src/utils/elkLayout.ts

@@ -79,7 +79,7 @@ export interface ElkLayoutOptions {
    * nests this group under another group; omit for a root-level frame.
    * Members reference their immediate parent via React Flow `parentId`.
    */
-  groups?: Array<{ id: string; memberIds: string[]; parentId?: string }>;
+  groups?: Array<{ id: string; memberIds: string[]; parentId?: string; minWidth?: number }>;
 }
 
 /** Result of ELK layout computation */
@@ -587,7 +587,11 @@ export async function computeElkLayout(
       builtGroups.set(g.id, {
         id: g.id,
         children: childNodes,
-        layoutOptions: compoundLayoutOptions,
+        layoutOptions: g.minWidth == null ? compoundLayoutOptions : {
+          ...compoundLayoutOptions,
+          'elk.nodeSize.constraints': 'MINIMUM_SIZE',
+          'elk.nodeSize.minimum': `(${g.minWidth},0)`,
+        },
       });
     }
     if (!progress) {