@principal-ai/subsystems-react 0.37.1 → 0.37.3

package/src/subsystem/ConstructsCatalog.tsx

@@ -6,15 +6,26 @@
  * constructs. Right: signatures grouped by repo, and within a repo stacked
  * per file under one combined file header carrying the path and a
  * description toggle; a declaration with a known line labels just that
- * construct's line in a file-like gutter. File opens still use the bottom
- * FileDrawer when the host injects a viewer.
+ * construct's line in a file-like gutter, and `external` constructs get a
+ * header naming their kind with the body naming the construct. The model
+ * description's toggle sits in the left chrome and opens the markdown as an
+ * overlay over the construct area. File opens still use the bottom FileDrawer
+ * when the host injects a viewer.
  */
 
 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 { AlignLeft, ChevronDown, ChevronRight, FileText, Folder } from 'lucide-react';
+import {
+  AlignLeft,
+  Box,
+  ChevronDown,
+  ChevronRight,
+  FileText,
+  Folder,
+  X,
+} from 'lucide-react';
 import {
   formatPurl,
   type SubsystemComponent,
@@ -33,7 +44,18 @@ export interface ConstructsCatalogProps {
   onSelect?: (componentAlias: string) => void;
   title?: string;
   hideSidebar?: boolean;
+  /**
+   * Model description. Its toggle lives in the left chrome; opening it shows
+   * the markdown as an overlay over the construct area.
+   */
   description?: string;
+  /**
+   * Controlled open state for the description overlay. When provided the host
+   * owns it (e.g. a button in its own header) and the built-in toggle just
+   * reports changes; otherwise the built-in toggle drives the state.
+   */
+  descriptionOpen?: boolean;
+  onDescriptionOpenChange?: (open: boolean) => void;
   diagnostic?: SubsystemDiagnostic;
   sidebarExtra?: ReactNode;
   sidebarAfterDescription?: ReactNode;
@@ -164,6 +186,8 @@ export function ConstructsCatalog({
   title,
   hideSidebar,
   description,
+  descriptionOpen: descriptionOpenProp,
+  onDescriptionOpenChange,
   diagnostic,
   sidebarExtra,
   sidebarAfterDescription,
@@ -199,13 +223,21 @@ export function ConstructsCatalog({
   const [focusedAlias, setFocusedAlias] = useState<string | null>(null);
   const [searchQuery, setSearchQuery] = useState('');
   const [descriptionVisible, setDescriptionVisible] = useState(false);
+  const descriptionOpen = descriptionOpenProp ?? descriptionVisible;
+  const setDescriptionOpen = (open: boolean) => {
+    setDescriptionVisible(open);
+    onDescriptionOpenChange?.(open);
+  };
   const [descToggleHover, setDescToggleHover] = useState(false);
   const [hoveredRow, setHoveredRow] = useState<string | null>(null);
   const [collapsedFolders, setCollapsedFolders] = useState<Set<string>>(
     new Set(),
   );
-  // Files whose shared-header description toggle is expanded (keyed by file run).
-  const [openPurposes, setOpenPurposes] = useState<Set<string>>(new Set());
+  // Explicit description toggles per file run. Unset falls back to the kind's
+  // default (externals open, files closed).
+  const [purposeOverrides, setPurposeOverrides] = useState<
+    Record<string, boolean>
+  >({});
   const [drawer, setDrawer] = useState<{ file: string; startLine?: number } | null>(
     null,
   );
@@ -317,13 +349,8 @@ export function ConstructsCatalog({
     });
   }, []);
 
-  const togglePurpose = useCallback((key: string) => {
-    setOpenPurposes((prev) => {
-      const next = new Set(prev);
-      if (next.has(key)) next.delete(key);
-      else next.add(key);
-      return next;
-    });
+  const setPurposeOpen = useCallback((key: string, open: boolean) => {
+    setPurposeOverrides((prev) => ({ ...prev, [key]: open }));
   }, []);
 
   /** File-tree click: show every construct declared in the file, or hide them
@@ -542,8 +569,13 @@ export function ConstructsCatalog({
 
   const showChrome =
     !hideSidebar &&
-    !!(title || description || diagnostic || sidebarExtra || sidebarAfterDescription);
-  const showDesc = !!description && descriptionVisible;
+    !!(
+      title ||
+      description ||
+      diagnostic ||
+      sidebarExtra ||
+      sidebarAfterDescription
+    );
 
   return (
     <div
@@ -573,7 +605,6 @@ export function ConstructsCatalog({
         {showChrome && (
           <div
             style={{
-              flex: showDesc ? '0 0 auto' : undefined,
               padding: '16px 16px 8px',
               display: 'flex',
               flexDirection: 'column',
@@ -611,16 +642,16 @@ export function ConstructsCatalog({
                   {description && (
                     <button
                       type="button"
-                      aria-expanded={descriptionVisible}
+                      aria-expanded={descriptionOpen}
                       aria-label={
-                        descriptionVisible ? 'Hide description' : 'Show description'
+                        descriptionOpen ? 'Hide description' : 'Show description'
                       }
                       title={
-                        descriptionVisible ? 'Hide description' : 'Show description'
+                        descriptionOpen ? 'Hide description' : 'Show description'
                       }
                       onMouseEnter={() => setDescToggleHover(true)}
                       onMouseLeave={() => setDescToggleHover(false)}
-                      onClick={() => setDescriptionVisible((v) => !v)}
+                      onClick={() => setDescriptionOpen(!descriptionOpen)}
                       style={{
                         display: 'inline-flex',
                         alignItems: 'center',
@@ -631,8 +662,8 @@ export function ConstructsCatalog({
                         padding: 0,
                         border: 'none',
                         borderRadius: 4,
-                        background: descriptionVisible || descToggleHover ? theme.colors.border : 'transparent',
-                        color: descriptionVisible || descToggleHover ? theme.colors.text : muted,
+                        background: descriptionOpen || descToggleHover ? theme.colors.border : 'transparent',
+                        color: descriptionOpen || descToggleHover ? theme.colors.text : muted,
                         cursor: 'pointer',
                       }}
                     >
@@ -642,21 +673,6 @@ export function ConstructsCatalog({
                 </div>
               </div>
             )}
-            {showDesc && (
-              <div style={{ fontSize: theme.fontSizes[0], lineHeight: 1.5 }}>
-                <IndustryMarkdownSlide
-                  content={description!}
-                  slideIdPrefix="constructs-desc"
-                  slideIndex={0}
-                  isVisible={true}
-                  theme={theme}
-                  disableScroll={true}
-                  disableBasePadding
-                  enableKeyboardScrolling={false}
-                  autoFocusOnVisible={false}
-                />
-              </div>
-            )}
             {sidebarAfterDescription}
           </div>
         )}
@@ -699,6 +715,97 @@ export function ConstructsCatalog({
           flexDirection: 'column',
         }}
       >
+        {description && descriptionOpen && (
+          <>
+            <div
+              onClick={() => setDescriptionOpen(false)}
+              style={{
+                position: 'absolute',
+                inset: 0,
+                zIndex: 2,
+                background: 'rgba(0,0,0,0.45)',
+              }}
+            />
+            <div
+              style={{
+                position: 'absolute',
+                top: '50%',
+                left: '50%',
+                transform: 'translate(-50%, -50%)',
+                zIndex: 3,
+                width: 360,
+                maxWidth: 'calc(100% - 16px)',
+                maxHeight: '70%',
+                overflow: 'auto',
+                padding: 16,
+                border: `1px solid ${theme.colors.border}`,
+                borderRadius: 8,
+                background: theme.colors.background,
+                boxShadow: '0 8px 24px rgba(0,0,0,0.28)',
+                fontSize: theme.fontSizes[0],
+                lineHeight: 1.5,
+              }}
+            >
+              <div
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 8,
+                  marginBottom: 12,
+                }}
+              >
+                <h3
+                  style={{
+                    margin: 0,
+                    flex: 1,
+                    minWidth: 0,
+                    fontSize: theme.fontSizes[1],
+                    fontWeight: 600,
+                    fontFamily: theme.fonts.monospace,
+                    letterSpacing: 0.4,
+                    textTransform: 'uppercase',
+                    color: theme.colors.textSecondary ?? muted,
+                  }}
+                >
+                  Overview
+                </h3>
+                <button
+                  type="button"
+                  aria-label="Close description"
+                  title="Close"
+                  onClick={() => setDescriptionOpen(false)}
+                  style={{
+                    display: 'inline-flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    flexShrink: 0,
+                    width: 22,
+                    height: 22,
+                    padding: 0,
+                    border: 'none',
+                    borderRadius: 4,
+                    background: 'transparent',
+                    color: muted,
+                    cursor: 'pointer',
+                  }}
+                >
+                  <X size={14} />
+                </button>
+              </div>
+              <IndustryMarkdownSlide
+                content={description}
+                slideIdPrefix="constructs-desc-overlay"
+                slideIndex={0}
+                isVisible
+                theme={theme}
+                disableScroll
+                disableBasePadding
+                enableKeyboardScrolling={false}
+                autoFocusOnVisible={false}
+              />
+            </div>
+          </>
+        )}
         {searchActive && (
           <div style={{ flexShrink: 0, padding: '12px 16px 0' }}>
             <input
@@ -772,12 +879,14 @@ export function ConstructsCatalog({
                 {splitByFileRun(group.items).map((run) => {
                   const lead = run[0]!;
                   const hasFile = !!lead.file;
-                  // Every file-backed run gets the combined header, one
-                  // declaration or many, so the style stays consistent.
-                  const showHeader = hasFile;
+                  const isExternal = lead.construct === 'external';
+                  // File-backed runs and externals both get a header; externals
+                  // name their kind instead of a path, so the body doesn't have
+                  // to spell it out.
+                  const showHeader = hasFile || isExternal;
                   const runKey = `${group.key}:${lead.file || lead.alias}`;
                   const runHasPurpose = run.some((c) => !!c.purpose?.trim());
-                  const purposeOpen = openPurposes.has(runKey);
+                  const purposeOpen = purposeOverrides[runKey] ?? isExternal;
                   const runFileOpen =
                     drawer != null && hasFile && lead.file === drawer.file;
                   return (
@@ -815,41 +924,64 @@ export function ConstructsCatalog({
                             fontSize: theme.fontSizes[0],
                           }}
                         >
-                          <button
-                            type="button"
-                            title={fileViewer ? `Open ${lead.file}` : lead.file}
-                            onClick={
-                              fileViewer
-                                ? () => onOpenFile(lead.file)
-                                : undefined
-                            }
-                            style={{
-                              display: 'flex',
-                              alignItems: 'center',
-                              gap: 6,
-                              flex: 1,
-                              minWidth: 0,
-                              padding: 0,
-                              border: 'none',
-                              background: 'transparent',
-                              color: 'inherit',
-                              fontFamily: 'inherit',
-                              fontSize: 'inherit',
-                              textAlign: 'left',
-                              cursor: fileViewer ? 'pointer' : 'default',
-                            }}
-                          >
-                            <FileText size={12} style={{ flexShrink: 0 }} />
+                          {isExternal ? (
                             <span
                               style={{
-                                overflow: 'hidden',
-                                textOverflow: 'ellipsis',
-                                whiteSpace: 'nowrap',
+                                display: 'flex',
+                                alignItems: 'center',
+                                gap: 6,
+                                flex: 1,
+                                minWidth: 0,
                               }}
                             >
-                              {lead.file}
+                              <Box size={12} style={{ flexShrink: 0 }} />
+                              <span
+                                style={{
+                                  overflow: 'hidden',
+                                  textOverflow: 'ellipsis',
+                                  whiteSpace: 'nowrap',
+                                }}
+                              >
+                                external
+                              </span>
                             </span>
-                          </button>
+                          ) : (
+                            <button
+                              type="button"
+                              title={fileViewer ? `Open ${lead.file}` : lead.file}
+                              onClick={
+                                fileViewer
+                                  ? () => onOpenFile(lead.file)
+                                  : undefined
+                              }
+                              style={{
+                                display: 'flex',
+                                alignItems: 'center',
+                                gap: 6,
+                                flex: 1,
+                                minWidth: 0,
+                                padding: 0,
+                                border: 'none',
+                                background: 'transparent',
+                                color: 'inherit',
+                                fontFamily: 'inherit',
+                                fontSize: 'inherit',
+                                textAlign: 'left',
+                                cursor: fileViewer ? 'pointer' : 'default',
+                              }}
+                            >
+                              <FileText size={12} style={{ flexShrink: 0 }} />
+                              <span
+                                style={{
+                                  overflow: 'hidden',
+                                  textOverflow: 'ellipsis',
+                                  whiteSpace: 'nowrap',
+                                }}
+                              >
+                                {lead.file}
+                              </span>
+                            </button>
+                          )}
                           {runHasPurpose && (
                             <button
                               type="button"
@@ -860,7 +992,7 @@ export function ConstructsCatalog({
                                 purposeOpen ? 'Hide description' : 'Show description'
                               }
                               aria-expanded={purposeOpen}
-                              onClick={() => togglePurpose(runKey)}
+                              onClick={() => setPurposeOpen(runKey, !purposeOpen)}
                               style={{
                                 display: 'inline-flex',
                                 alignItems: 'center',
@@ -898,6 +1030,9 @@ export function ConstructsCatalog({
                         // render unnumbered. Without a header, keep the badge.
                         const numbered =
                           hasFile && c.declarationRef?.startLine != null;
+                        // The header names the external kind, so the body just
+                        // names the construct.
+                        const isExt = c.construct === 'external';
                         return (
                           <div
                             key={c.alias}
@@ -933,6 +1068,7 @@ export function ConstructsCatalog({
                               showRepoIdentity={false}
                               fileBadgeChrome={showHeader ? false : !!fileViewer}
                               hideActions={showHeader}
+                              externalName={isExt}
                               showPurpose={showHeader ? purposeOpen : undefined}
                               lineNumbers={numbered}
                               verification={

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -259,6 +259,12 @@ export interface SubsystemComponentGraphProps {
   showWalkthroughTitle?: boolean;
   /** Markdown description rendered in the sidebar. */
   description?: string;
+  /**
+   * Controlled open state for the constructs catalog's description overlay.
+   * When provided, the host owns it (e.g. a button in its own header).
+   */
+  descriptionOpen?: boolean;
+  onDescriptionOpenChange?: (open: boolean) => void;
   /** Rendered over the graph canvas only (not the title/legend sidebar). */
   canvasOverlay?: ReactNode;
   /** Extra controls at the top of the title/legend sidebar. */
@@ -2543,6 +2549,8 @@ export function SubsystemComponentGraph(props: SubsystemComponentGraphProps) {
             title={props.title}
             hideSidebar={props.hideSidebar}
             description={props.description}
+            descriptionOpen={props.descriptionOpen}
+            onDescriptionOpenChange={props.onDescriptionOpenChange}
             diagnostic={props.diagnostic}
             sidebarExtra={props.sidebarExtra}
             sidebarAfterDescription={props.sidebarAfterDescription}