@principal-ai/subsystems-react 0.24.0 → 0.24.1

package/src/subsystem/ConstructsCatalog.tsx

@@ -0,0 +1,644 @@
+/**
+ * ConstructsCatalog — master/detail for a constructs-only subsystem
+ * (components, no topology or walkthrough edges).
+ *
+ * Left: the model's constructs as a toggle list. Right: signatures for
+ * every construct currently on (`ComponentDeclaration`, stacked). 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 { ChevronDown, ChevronUp } from 'lucide-react';
+import {
+  constructBadgeColor,
+  constructBadgeLabel,
+  deriveNameFromSymbol,
+  rightBadgeColor,
+  rightBadgeLabel,
+  type SubsystemComponent,
+} from './model';
+import type { SubsystemOpenFileOptions } from './declarationRef';
+import { ComponentDeclaration } from './ComponentDeclaration';
+import type { ComponentVerificationState } from './ComponentDeclaration';
+import { SubsystemDiagnosticToggle, type SubsystemDiagnostic } from './DiagnosticToggle';
+import { FileDrawer } from './FileDrawer';
+import { componentColor } from '../pierre/constructColors';
+import { resolvePierreSyntaxThemeName } from '../pierre/pierreSyntaxTheme';
+
+export interface ConstructsCatalogProps {
+  components: SubsystemComponent[];
+  onSelect?: (componentId: string) => void;
+  title?: string;
+  hideSidebar?: boolean;
+  description?: string;
+  diagnostic?: SubsystemDiagnostic;
+  sidebarExtra?: ReactNode;
+  sidebarAfterDescription?: ReactNode;
+  renderFileViewer?: (file: string, opts?: SubsystemOpenFileOptions) => ReactNode;
+  renderFileView?: (component: SubsystemComponent) => ReactNode;
+  onFileSelect?: (file: string) => void;
+  onVerifyComponent?: (componentId: string) => void;
+  componentVerification?: ComponentVerificationState | null;
+}
+
+const FileDrawerContent = memo(function FileDrawerContent({
+  render,
+  file,
+  startLine,
+}: {
+  render: (file: string, opts?: SubsystemOpenFileOptions) => ReactNode;
+  file: string;
+  startLine?: number;
+}) {
+  return <>{render(file, startLine != null ? { startLine } : undefined)}</>;
+});
+
+function resolveRelated(
+  components: SubsystemComponent[],
+  ref: string,
+): SubsystemComponent | undefined {
+  const clean = ref.replace(/\(\)$/, '');
+  return components.find(
+    (c) =>
+      c.id === clean ||
+      c.name === clean ||
+      c.symbol === clean ||
+      c.symbol?.replace(/\(\)$/, '') === clean,
+  );
+}
+
+export function ConstructsCatalog({
+  components,
+  onSelect,
+  title,
+  hideSidebar,
+  description,
+  diagnostic,
+  sidebarExtra,
+  sidebarAfterDescription,
+  renderFileViewer,
+  renderFileView,
+  onFileSelect,
+  onVerifyComponent,
+  componentVerification,
+}: ConstructsCatalogProps) {
+  const { theme, mode } = useTheme();
+  const pierreTheme = resolvePierreSyntaxThemeName(mode);
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const [visibleIds, setVisibleIds] = useState<string[]>(() =>
+    components[0] ? [components[0].id] : [],
+  );
+  const [focusedId, setFocusedId] = useState<string | null>(
+    () => components[0]?.id ?? null,
+  );
+  const [descriptionVisible, setDescriptionVisible] = useState(false);
+  const [descToggleHover, setDescToggleHover] = useState(false);
+  const [drawer, setDrawer] = useState<{ file: string; startLine?: number } | null>(
+    null,
+  );
+  const focusedRef = useRef<string | null>(focusedId);
+  focusedRef.current = focusedId;
+
+  const visibleSet = useMemo(() => new Set(visibleIds), [visibleIds]);
+  const visibleComponents = useMemo(
+    () => components.filter((c) => visibleSet.has(c.id)),
+    [components, visibleSet],
+  );
+
+  useEffect(() => {
+    if (!focusedId) return;
+    document.getElementById(`construct-${focusedId}`)?.scrollIntoView({ block: 'nearest' });
+  }, [focusedId]);
+
+  useEffect(() => {
+    const last = visibleIds[visibleIds.length - 1];
+    if (!last) return;
+    document
+      .getElementById(`construct-signature-${last}`)
+      ?.scrollIntoView({ block: 'nearest' });
+  }, [visibleIds]);
+
+  // Drop ids that left the model; if nothing remains, show the first construct.
+  useEffect(() => {
+    const ids = new Set(components.map((c) => c.id));
+    setVisibleIds((prev) => {
+      const next = prev.filter((id) => ids.has(id));
+      if (next.length > 0 || components.length === 0) return next;
+      return [components[0]!.id];
+    });
+    setFocusedId((prev) => {
+      if (prev && ids.has(prev)) return prev;
+      return components[0]?.id ?? null;
+    });
+  }, [components]);
+
+  const toggle = useCallback(
+    (id: string) => {
+      setFocusedId(id);
+      setVisibleIds((prev) =>
+        prev.includes(id) ? prev.filter((x) => x !== id) : [...prev, id],
+      );
+      onSelect?.(id);
+    },
+    [onSelect],
+  );
+
+  const show = useCallback(
+    (id: string) => {
+      setFocusedId(id);
+      setVisibleIds((prev) => (prev.includes(id) ? prev : [...prev, id]));
+      onSelect?.(id);
+    },
+    [onSelect],
+  );
+
+  const focusAt = useCallback(
+    (id: string) => {
+      setFocusedId(id);
+    },
+    [],
+  );
+
+  const onOpenFile = useCallback(
+    (file: string, opts?: SubsystemOpenFileOptions) => {
+      const startLine = opts?.startLine;
+      setDrawer((prev) => {
+        if (prev?.file === file && prev.startLine === startLine) return null;
+        return { file, startLine };
+      });
+      onFileSelect?.(file);
+    },
+    [onFileSelect],
+  );
+
+  const openComponentSource = useCallback(
+    (c: SubsystemComponent) => {
+      if (!c.file) return;
+      const startLine = c.declarationRef?.startLine;
+      onOpenFile(
+        c.file,
+        startLine != null ? { startLine } : undefined,
+      );
+    },
+    [onOpenFile],
+  );
+
+  const onRelatedSelect = useCallback(
+    (ref: string) => {
+      const comp = resolveRelated(components, ref);
+      if (!comp) return;
+      show(comp.id);
+    },
+    [components, show],
+  );
+
+  const fileViewer = useMemo(() => {
+    if (renderFileViewer) return renderFileViewer;
+    if (renderFileView) {
+      const byFile = new Map(
+        components.filter((c) => c.file).map((c) => [c.file, c] as const),
+      );
+      return (file: string, _opts?: SubsystemOpenFileOptions) => {
+        const comp = byFile.get(file);
+        return comp ? renderFileView(comp) : null;
+      };
+    }
+    return undefined;
+  }, [renderFileViewer, renderFileView, components]);
+
+  const fileViewerRef = useRef(fileViewer);
+  fileViewerRef.current = fileViewer;
+  const renderDrawerContent = useCallback(
+    (file: string, opts?: SubsystemOpenFileOptions) =>
+      fileViewerRef.current?.(file, opts) ?? null,
+    [],
+  );
+
+  const moveFocus = useCallback(
+    (delta: number) => {
+      if (components.length === 0) return;
+      const idx = Math.max(
+        0,
+        components.findIndex((c) => c.id === focusedRef.current),
+      );
+      const next = components[(idx + delta + components.length) % components.length]!;
+      focusAt(next.id);
+    },
+    [components, focusAt],
+  );
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      const el = e.target as HTMLElement | null;
+      if (
+        el &&
+        (el.tagName === 'INPUT' ||
+          el.tagName === 'TEXTAREA' ||
+          el.tagName === 'SELECT' ||
+          el.isContentEditable)
+      ) {
+        return;
+      }
+      if (e.metaKey || e.ctrlKey || e.altKey) return;
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        moveFocus(1);
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        moveFocus(-1);
+      } else if (e.key === 'Home') {
+        e.preventDefault();
+        if (components[0]) focusAt(components[0].id);
+      } else if (e.key === 'End') {
+        e.preventDefault();
+        const last = components[components.length - 1];
+        if (last) focusAt(last.id);
+      } else if (e.key === ' ' || e.key === 'Enter') {
+        if (focusedRef.current) {
+          e.preventDefault();
+          toggle(focusedRef.current);
+        }
+      } else if (e.key === 'Escape' && drawer) {
+        setDrawer(null);
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [components, drawer, moveFocus, focusAt, toggle]);
+
+  const showChrome =
+    !hideSidebar &&
+    !!(title || description || diagnostic || sidebarExtra || sidebarAfterDescription);
+  const showDesc = !!description && descriptionVisible;
+
+  return (
+    <div
+      data-testid="constructs-catalog"
+      style={{
+        width: '100%',
+        height: '100%',
+        minHeight: 0,
+        display: 'flex',
+        flexDirection: 'row',
+        background: theme.colors.background,
+      }}
+    >
+      <aside
+        style={{
+          width: 280,
+          minWidth: 200,
+          maxWidth: 360,
+          flexShrink: 0,
+          borderRight: `1px solid ${theme.colors.border}`,
+          background: theme.colors.backgroundSecondary ?? theme.colors.background,
+          display: 'flex',
+          flexDirection: 'column',
+          overflow: 'hidden',
+        }}
+      >
+        {showChrome && (
+          <div
+            style={{
+              flex: showDesc ? '0 0 auto' : undefined,
+              padding: '16px 16px 8px',
+              display: 'flex',
+              flexDirection: 'column',
+              gap: 12,
+            }}
+          >
+            {sidebarExtra}
+            {(title || description || diagnostic) && (
+              <div style={{ display: 'flex', alignItems: 'flex-start', gap: 8 }}>
+                {title && (
+                  <h2
+                    style={{
+                      margin: 0,
+                      flex: 1,
+                      minWidth: 0,
+                      fontSize: theme.fontSizes[2],
+                      fontWeight: 600,
+                      color: theme.colors.text,
+                      fontFamily: theme.fonts.monospace,
+                    }}
+                  >
+                    {title}
+                  </h2>
+                )}
+                <div
+                  style={{
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 4,
+                    flexShrink: 0,
+                    marginLeft: title ? undefined : 'auto',
+                  }}
+                >
+                  {diagnostic && <SubsystemDiagnosticToggle {...diagnostic} />}
+                  {description && (
+                    <button
+                      type="button"
+                      aria-expanded={descriptionVisible}
+                      aria-label={
+                        descriptionVisible ? 'Hide description' : 'Show description'
+                      }
+                      title={
+                        descriptionVisible ? 'Hide description' : 'Show description'
+                      }
+                      onMouseEnter={() => setDescToggleHover(true)}
+                      onMouseLeave={() => setDescToggleHover(false)}
+                      onClick={() => setDescriptionVisible((v) => !v)}
+                      style={{
+                        display: 'inline-flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        flexShrink: 0,
+                        width: 22,
+                        height: 22,
+                        padding: 0,
+                        border: 'none',
+                        borderRadius: 4,
+                        background: descToggleHover ? theme.colors.border : 'transparent',
+                        color: descToggleHover ? theme.colors.text : muted,
+                        cursor: 'pointer',
+                      }}
+                    >
+                      {descriptionVisible ? (
+                        <ChevronUp size={14} />
+                      ) : (
+                        <ChevronDown size={14} />
+                      )}
+                    </button>
+                  )}
+                </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
+                  fontSizeScale={0.9}
+                  enableKeyboardScrolling={false}
+                  autoFocusOnVisible={false}
+                />
+              </div>
+            )}
+            {sidebarAfterDescription}
+          </div>
+        )}
+        <div
+          style={{
+            padding: '10px 16px 6px',
+            fontSize: theme.fontSizes[0],
+            fontFamily: theme.fonts.monospace,
+            letterSpacing: 0.4,
+            textTransform: 'uppercase',
+            color: muted,
+            flexShrink: 0,
+          }}
+        >
+          Constructs
+        </div>
+        <ul
+          role="listbox"
+          aria-label="Constructs"
+          aria-multiselectable="true"
+          aria-activedescendant={focusedId ? `construct-${focusedId}` : undefined}
+          style={{
+            listStyle: 'none',
+            margin: 0,
+            padding: '0 8px 12px',
+            overflowY: 'auto',
+            flex: 1,
+            minHeight: 0,
+          }}
+        >
+          {components.map((c) => {
+            const visible = visibleSet.has(c.id);
+            const focused = c.id === focusedId;
+            const color = componentColor(c, pierreTheme);
+            const badgeColor = constructBadgeColor(c) ?? color;
+            const displayName = deriveNameFromSymbol(
+              c.symbol,
+              c.construct,
+              c.name,
+              c.file,
+              c.stereotype,
+            );
+            const role = rightBadgeLabel(c);
+            const roleColor = rightBadgeColor(c);
+            return (
+              <li key={c.id} role="presentation">
+                <button
+                  type="button"
+                  id={`construct-${c.id}`}
+                  role="option"
+                  aria-selected={visible}
+                  data-testid={`construct-row-${c.id}`}
+                  onClick={() => toggle(c.id)}
+                  style={{
+                    display: 'flex',
+                    flexDirection: 'column',
+                    alignItems: 'stretch',
+                    gap: 2,
+                    width: '100%',
+                    margin: '2px 0',
+                    padding: '8px 10px 8px 12px',
+                    textAlign: 'left',
+                    border: 'none',
+                    borderRadius: 6,
+                    background: visible
+                      ? theme.colors.background
+                      : 'transparent',
+                    cursor: 'pointer',
+                    boxShadow: visible
+                      ? `inset 0 0 0 1px ${theme.colors.border}`
+                      : undefined,
+                    outline: focused && !visible ? `1px dotted ${muted}` : undefined,
+                    outlineOffset: -1,
+                    opacity: visible ? 1 : 0.72,
+                  }}
+                >
+                  <span
+                    style={{
+                      display: 'flex',
+                      alignItems: 'baseline',
+                      gap: 8,
+                      minWidth: 0,
+                    }}
+                  >
+                    <span
+                      style={{
+                        flex: 1,
+                        minWidth: 0,
+                        overflow: 'hidden',
+                        textOverflow: 'ellipsis',
+                        whiteSpace: 'nowrap',
+                        fontFamily: theme.fonts.monospace,
+                        fontSize: theme.fontSizes[1],
+                        color,
+                        fontWeight: visible ? 600 : 500,
+                      }}
+                    >
+                      {displayName}
+                    </span>
+                    <span
+                      style={{
+                        flexShrink: 0,
+                        fontFamily: theme.fonts.monospace,
+                        fontSize: theme.fontSizes[0] * 0.95,
+                        letterSpacing: 0.4,
+                        textTransform: 'uppercase',
+                        color: badgeColor,
+                      }}
+                    >
+                      {constructBadgeLabel(c)}
+                    </span>
+                  </span>
+                  {(c.file || role) && (
+                    <span
+                      style={{
+                        display: 'flex',
+                        alignItems: 'center',
+                        gap: 8,
+                        minWidth: 0,
+                      }}
+                    >
+                      {c.file ? (
+                        <span
+                          title={fileViewer ? `Open ${c.file}` : c.file}
+                          onClick={
+                            fileViewer
+                              ? (e) => {
+                                  e.stopPropagation();
+                                  openComponentSource(c);
+                                }
+                              : undefined
+                          }
+                          style={{
+                            flex: 1,
+                            minWidth: 0,
+                            overflow: 'hidden',
+                            textOverflow: 'ellipsis',
+                            whiteSpace: 'nowrap',
+                            fontFamily: theme.fonts.body,
+                            fontSize: theme.fontSizes[0],
+                            color: muted,
+                            cursor: fileViewer ? 'pointer' : undefined,
+                            textDecoration: fileViewer ? 'underline' : undefined,
+                            textDecorationStyle: fileViewer ? 'dotted' : undefined,
+                            textUnderlineOffset: 2,
+                          }}
+                        >
+                          {c.file}
+                        </span>
+                      ) : (
+                        <span style={{ flex: 1 }} />
+                      )}
+                      {role && roleColor && (
+                        <span
+                          style={{
+                            flexShrink: 0,
+                            fontFamily: theme.fonts.monospace,
+                            fontSize: theme.fontSizes[0] * 0.9,
+                            letterSpacing: 0.4,
+                            textTransform: 'uppercase',
+                            color: roleColor,
+                          }}
+                        >
+                          {role}
+                        </span>
+                      )}
+                    </span>
+                  )}
+                </button>
+              </li>
+            );
+          })}
+        </ul>
+      </aside>
+      <div
+        style={{
+          flex: 1,
+          minWidth: 0,
+          minHeight: 0,
+          display: 'flex',
+          flexDirection: 'column',
+        }}
+      >
+        <div
+          data-testid="construct-signature"
+          style={{
+            flex: 1,
+            minHeight: 0,
+            overflow: 'auto',
+            padding: 16,
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 12,
+          }}
+        >
+          {visibleComponents.length > 0 ? (
+            visibleComponents.map((c) => (
+              <div
+                key={c.id}
+                id={`construct-signature-${c.id}`}
+                style={{
+                  border: `1px solid ${theme.colors.border}`,
+                  borderRadius: 8,
+                  overflow: 'hidden',
+                  flexShrink: 0,
+                }}
+              >
+                <ComponentDeclaration
+                  component={c}
+                  onOpenFile={fileViewer ? onOpenFile : undefined}
+                  defaultShowFile={!!fileViewer}
+                  onRelatedSelect={onRelatedSelect}
+                  onVerify={onVerifyComponent}
+                  verification={
+                    componentVerification && focusedId === c.id
+                      ? componentVerification
+                      : undefined
+                  }
+                />
+              </div>
+            ))
+          ) : (
+            <p
+              style={{
+                margin: 0,
+                color: muted,
+                fontFamily: theme.fonts.body,
+                fontSize: theme.fontSizes[1],
+              }}
+            >
+              Toggle constructs on the left to show their signatures.
+            </p>
+          )}
+        </div>
+        <FileDrawer
+          title={drawer?.file ?? null}
+          onClose={() => setDrawer(null)}
+          fillHeight={drawer != null && drawer.startLine == null}
+        >
+          {drawer ? (
+            <FileDrawerContent
+              render={renderDrawerContent}
+              file={drawer.file}
+              startLine={drawer.startLine}
+            />
+          ) : null}
+        </FileDrawer>
+      </div>
+    </div>
+  );
+}