@principal-ai/subsystems-react 0.56.3 → 0.56.5

package/src/subsystem/DecorationPanel.test.tsx

@@ -0,0 +1,128 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { cleanup, fireEvent, render } from '@testing-library/react/pure';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { DecorationPanel, type DecorationPanelProps } from './DecorationPanel';
+import { decorationTrailKey, type SubsystemDecoration } from './decoration';
+
+// Same DOM shim as TrailsPanel.test: happy-dom lacks ResizeObserver, which
+// themed-markdown uses to measure its slide container.
+const dom = new Window();
+const globals = globalThis as unknown as Record<string, unknown>;
+globals.window = dom;
+globals.document = dom.document;
+globals.navigator = dom.navigator;
+globals.HTMLElement = dom.HTMLElement;
+globals.Node = dom.Node;
+globals.Element = dom.Element;
+globals.Event = dom.Event;
+globals.MouseEvent = dom.MouseEvent;
+globals.FocusEvent = dom.FocusEvent;
+globals.KeyboardEvent = dom.KeyboardEvent;
+globals.getComputedStyle = dom.getComputedStyle.bind(dom);
+globals.requestAnimationFrame = dom.requestAnimationFrame.bind(dom);
+globals.cancelAnimationFrame = dom.cancelAnimationFrame.bind(dom);
+globals.localStorage = dom.localStorage;
+globals.sessionStorage = dom.sessionStorage;
+globals.matchMedia = dom.matchMedia.bind(dom);
+globals.ResizeObserver = class {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+};
+
+afterEach(cleanup);
+
+const decoration: SubsystemDecoration = {
+  version: 1,
+  id: 'dec-sync',
+  title: 'Local-first sync',
+  description: 'A **reading path** for the save flow.',
+  trails: [
+    { kind: 'base', modelId: 'sg-desktop', trailId: 'tl-save' },
+    { kind: 'base', modelId: 'sg-server', trailId: 'tl-persist' },
+    {
+      kind: 'draft',
+      modelId: 'sg-desktop',
+      trail: { id: 'tl-planned', title: 'Planned sync', steps: [] },
+    },
+  ],
+  draft: {
+    components: [
+      { alias: 'sync-agent', name: 'SyncAgent', construct: 'class' },
+    ],
+    edges: [{ from: 'tab', to: 'sync-agent', mechanism: 'produces' }],
+  },
+  provenance: { source: 'author', at: '2026-10-20T00:00:00.000Z' },
+};
+
+const resolveTrail: NonNullable<DecorationPanelProps['resolveTrail']> = (ref) => {
+  if (ref.kind === 'draft') return undefined;
+  const key = decorationTrailKey(ref);
+  if (key === 'sg-desktop:tl-save') return { title: 'Save drawing', stepCount: 4 };
+  if (key === 'sg-server:tl-persist') return { title: 'Persist file', stepCount: 5 };
+  return undefined;
+};
+
+function renderPanel(overrides: Partial<DecorationPanelProps> = {}) {
+  const props: DecorationPanelProps = {
+    decoration,
+    active: true,
+    onToggleActive: () => {},
+    resolveTrail,
+    modelLabels: new Map([
+      ['sg-desktop', 'desktop-app'],
+      ['sg-server', 'sync-service'],
+    ]),
+    ...overrides,
+  };
+  return render(
+    <ThemeProvider theme={defaultEditorTheme}>
+      <DecorationPanel {...props} />
+    </ThemeProvider>,
+  );
+}
+
+describe('DecorationPanel', () => {
+  test('renders the description, grouped trails, and draft structure', () => {
+    const { getByText, container } = renderPanel();
+    expect(container.textContent).toContain('reading path');
+    expect(getByText('desktop-app')).not.toBeNull();
+    expect(getByText('sync-service')).not.toBeNull();
+    expect(getByText('Save drawing')).not.toBeNull();
+    expect(getByText('Persist file')).not.toBeNull();
+    expect(getByText('Planned sync')).not.toBeNull();
+    expect(getByText('draft')).not.toBeNull();
+    expect(getByText('SyncAgent')).not.toBeNull();
+    expect(getByText('+ 1 draft edge')).not.toBeNull();
+  });
+
+  test('the toggle reports the next active state', () => {
+    const onToggleActive = mock(() => {});
+    const { getByLabelText } = renderPanel({ onToggleActive });
+    fireEvent.click(getByLabelText('Turn decoration off'));
+    expect(onToggleActive).toHaveBeenCalledWith(false);
+  });
+
+  test('selecting a trail hands the ref back to the host', () => {
+    const onSelectTrail = mock(() => {});
+    const { getByText } = renderPanel({ onSelectTrail });
+    fireEvent.click(getByText('Save drawing'));
+    expect(onSelectTrail).toHaveBeenCalledWith({
+      kind: 'base',
+      modelId: 'sg-desktop',
+      trailId: 'tl-save',
+    });
+  });
+
+  test('selecting a draft component hands the component back', () => {
+    const onSelectDraftComponent = mock(() => {});
+    const { getByText } = renderPanel({ onSelectDraftComponent });
+    fireEvent.click(getByText('SyncAgent'));
+    expect(onSelectDraftComponent).toHaveBeenCalledWith({
+      alias: 'sync-agent',
+      name: 'SyncAgent',
+      construct: 'class',
+    });
+  });
+});

package/src/subsystem/DecorationPanel.tsx

@@ -0,0 +1,334 @@
+/**
+ * DecorationPanel — the reading surface for one `SubsystemDecoration`.
+ *
+ * A decoration is an additive, unverified layer over one or more subsystem
+ * models: markdown prose, an ordered list of trails (each naming its own
+ * model), and optional draft structure. This panel is the container's own
+ * surface — it deliberately does not render the graph. Selecting a trail (or
+ * a draft component) is handed back to the host, which decides whether to
+ * focus a model, open a tab, or overlay the draft.
+ *
+ * Nothing here writes: the first prototype is read-only plus an on/off toggle.
+ */
+
+import type { CSSProperties } from 'react';
+import { useTheme } from '@principal-ade/industry-theme';
+import { Box, Eye, EyeOff, Network, Route, Sparkles } from 'lucide-react';
+import { IndustryMarkdownSlide } from 'themed-markdown';
+import {
+  decorationTrailId,
+  groupDecorationTrailsByModel,
+  type DecorationDraftComponent,
+  type DecorationTrailRef,
+  type SubsystemDecoration,
+} from './decoration';
+
+export interface DecorationPanelTrailMeta {
+  title: string;
+  stepCount?: number;
+}
+
+export interface DecorationPanelProps {
+  decoration: SubsystemDecoration;
+  /** Whether the decoration overlay is currently on. */
+  active: boolean;
+  onToggleActive: (active: boolean) => void;
+  /** Click a trail row. The host focuses the owning model/trail. */
+  onSelectTrail?: (ref: DecorationTrailRef) => void;
+  /** Click a draft component. Omit to render the draft list read-only. */
+  onSelectDraftComponent?: (component: DecorationDraftComponent) => void;
+  /**
+   * Resolve a base trail's display title/step count from its owning model.
+   * Draft trails carry their content inline and need no resolver.
+   */
+  resolveTrail?: (ref: DecorationTrailRef) => DecorationPanelTrailMeta | undefined;
+  /** Friendly model names, keyed by `modelId`. Falls back to the id. */
+  modelLabels?: ReadonlyMap<string, string>;
+}
+
+export function DecorationPanel({
+  decoration,
+  active,
+  onToggleActive,
+  onSelectTrail,
+  onSelectDraftComponent,
+  resolveTrail,
+  modelLabels,
+}: DecorationPanelProps) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const secondary = theme.colors.textSecondary ?? muted;
+  const warning = theme.colors.warning ?? secondary;
+  const accent = theme.colors.accent ?? theme.colors.primary ?? theme.colors.text;
+  const groups = groupDecorationTrailsByModel(decoration.trails);
+  const draftComponents = decoration.draft?.components ?? [];
+  const draftEdges = decoration.draft?.edges ?? [];
+  const sectionLabel: CSSProperties = {
+    fontFamily: theme.fonts.monospace,
+    fontSize: theme.fontSizes[0],
+    fontWeight: theme.fontWeights.semibold,
+    letterSpacing: '0.06em',
+    textTransform: 'uppercase',
+  };
+
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        width: '100%',
+        height: '100%',
+        minHeight: 0,
+        background: theme.colors.background,
+        color: theme.colors.text,
+      }}
+    >
+      <header
+        style={{
+          flexShrink: 0,
+          padding: '14px 16px 10px',
+          borderBottom: `1px solid ${theme.colors.border}`,
+        }}
+      >
+        <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+          <Sparkles size={15} strokeWidth={2} color={accent} aria-hidden />
+          <h2
+            style={{
+              flex: 1,
+              minWidth: 0,
+              margin: 0,
+              overflowWrap: 'anywhere',
+              fontFamily: theme.fonts.monospace,
+              fontSize: theme.fontSizes[2],
+              fontWeight: theme.fontWeights.semibold,
+            }}
+          >
+            {decoration.title}
+          </h2>
+          <button
+            type="button"
+            aria-pressed={active}
+            aria-label={active ? 'Turn decoration off' : 'Turn decoration on'}
+            title={active ? 'Turn decoration off' : 'Turn decoration on'}
+            onClick={() => onToggleActive(!active)}
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              gap: 4,
+              flexShrink: 0,
+              padding: '3px 8px',
+              borderRadius: 4,
+              border: `1px solid ${active ? accent : theme.colors.border}`,
+              background: active ? `${accent}18` : 'transparent',
+              color: active ? accent : muted,
+              fontFamily: theme.fonts.monospace,
+              fontSize: theme.fontSizes[0],
+              cursor: 'pointer',
+            }}
+          >
+            {active ? <Eye size={12} strokeWidth={2} /> : <EyeOff size={12} strokeWidth={2} />}
+            {active ? 'On' : 'Off'}
+          </button>
+        </div>
+      </header>
+
+      <div style={{ flex: 1, minHeight: 0, overflowY: 'auto', padding: '12px 16px 18px' }}>
+        {decoration.description && (
+          <div style={{ fontSize: theme.fontSizes[1], lineHeight: theme.lineHeights.body }}>
+            <IndustryMarkdownSlide
+              content={decoration.description}
+              slideIdPrefix={`decoration-${decoration.id}`}
+              slideIndex={0}
+              isVisible={true}
+              theme={theme}
+              disableScroll={true}
+              disableBasePadding
+              enableKeyboardScrolling={false}
+              autoFocusOnVisible={false}
+            />
+          </div>
+        )}
+
+        <section
+          style={{
+            marginTop: 16,
+            paddingTop: 14,
+            borderTop: `1px solid ${theme.colors.border}`,
+          }}
+        >
+          <div style={{ ...sectionLabel, color: secondary }}>
+            Trails · {decoration.trails.length}
+          </div>
+          {groups.map((group) => (
+            <div key={group.modelId}>
+              <div
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 6,
+                  margin: '12px 0 3px',
+                }}
+              >
+                <Network size={14} strokeWidth={2} color={secondary} aria-hidden />
+                <span
+                  style={{
+                    minWidth: 0,
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    whiteSpace: 'nowrap',
+                    fontFamily: theme.fonts.monospace,
+                    fontSize: theme.fontSizes[1],
+                    fontWeight: theme.fontWeights.semibold,
+                    color: theme.colors.text,
+                  }}
+                >
+                  {modelLabels?.get(group.modelId) ?? group.modelId}
+                </span>
+              </div>
+              {group.trails.map((ref) => {
+                const meta = resolveTrail?.(ref);
+                const title =
+                  meta?.title ??
+                  (ref.kind === 'draft' ? ref.trail.title : ref.trailId);
+                const stepCount =
+                  meta?.stepCount ??
+                  (ref.kind === 'draft' ? ref.trail.steps.length : undefined);
+                return (
+                  <button
+                    key={decorationTrailId(ref)}
+                    type="button"
+                    onClick={() => onSelectTrail?.(ref)}
+                    style={{
+                      display: 'flex',
+                      alignItems: 'center',
+                      gap: 8,
+                      width: '100%',
+                      minWidth: 0,
+                      padding: '6px 6px 6px 0',
+                      border: 'none',
+                      borderRadius: 4,
+                      background: 'transparent',
+                      color: theme.colors.text,
+                      textAlign: 'left',
+                      cursor: onSelectTrail ? 'pointer' : 'default',
+                    }}
+                  >
+                    <Route size={13} strokeWidth={2} color={muted} aria-hidden />
+                    <span
+                      style={{
+                        flex: 1,
+                        minWidth: 0,
+                        overflow: 'hidden',
+                        textOverflow: 'ellipsis',
+                        whiteSpace: 'nowrap',
+                        fontFamily: theme.fonts.monospace,
+                        fontSize: theme.fontSizes[1],
+                      }}
+                    >
+                      {title}
+                    </span>
+                    {ref.kind === 'draft' && (
+                      <span
+                        style={{
+                          flexShrink: 0,
+                          padding: '1px 5px',
+                          borderRadius: 3,
+                          border: `1px solid ${warning}`,
+                          color: warning,
+                          fontFamily: theme.fonts.monospace,
+                          fontSize: theme.fontSizes[0],
+                        }}
+                      >
+                        draft
+                      </span>
+                    )}
+                    {stepCount != null && (
+                      <span
+                        style={{
+                          flexShrink: 0,
+                          fontFamily: theme.fonts.monospace,
+                          fontSize: theme.fontSizes[0],
+                          color: secondary,
+                        }}
+                      >
+                        {stepCount}
+                      </span>
+                    )}
+                  </button>
+                );
+              })}
+            </div>
+          ))}
+        </section>
+
+        {(draftComponents.length > 0 || draftEdges.length > 0) && (
+          <section style={{ marginTop: 18 }}>
+            <div style={{ ...sectionLabel, color: secondary }}>
+              Draft structure · not verified
+            </div>
+            {draftComponents.map((component) => (
+              <button
+                key={component.alias}
+                type="button"
+                onClick={() => onSelectDraftComponent?.(component)}
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 8,
+                  width: '100%',
+                  minWidth: 0,
+                  padding: '6px 6px 6px 0',
+                  border: 'none',
+                  borderRadius: 4,
+                  background: 'transparent',
+                  color: theme.colors.text,
+                  textAlign: 'left',
+                  cursor: onSelectDraftComponent ? 'pointer' : 'default',
+                }}
+              >
+                <Box size={13} strokeWidth={2} color={muted} aria-hidden />
+                <span
+                  style={{
+                    flex: 1,
+                    minWidth: 0,
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    whiteSpace: 'nowrap',
+                    fontFamily: theme.fonts.monospace,
+                    fontSize: theme.fontSizes[1],
+                  }}
+                >
+                  {component.name}
+                </span>
+                {component.construct && (
+                  <span
+                    style={{
+                      flexShrink: 0,
+                      fontFamily: theme.fonts.monospace,
+                      fontSize: theme.fontSizes[0],
+                      color: secondary,
+                    }}
+                  >
+                    {component.construct}
+                  </span>
+                )}
+              </button>
+            ))}
+            {draftEdges.length > 0 && (
+              <div
+                style={{
+                  marginTop: 4,
+                  fontFamily: theme.fonts.monospace,
+                  fontSize: theme.fontSizes[0],
+                  color: secondary,
+                }}
+              >
+                + {draftEdges.length} draft edge{draftEdges.length === 1 ? '' : 's'}
+              </div>
+            )}
+          </section>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/subsystem/DiagnosticToggle.tsx

@@ -90,6 +90,12 @@ export function diagnosticTitle(diagnostic: SubsystemDiagnostic): string {
 export interface SubsystemDiagnosticToggleProps extends SubsystemDiagnostic {
   /** Icon size in px. @default 14 */
   size?: number;
+  /** Optional visible label beside the status icon. */
+  labelText?: string;
+  /** Outline the button in header toolbars. */
+  bordered?: boolean;
+  /** Match an option inside a shared segmented view switch. */
+  segmented?: boolean;
 }
 
 export function SubsystemDiagnosticToggle({
@@ -100,6 +106,9 @@ export function SubsystemDiagnosticToggle({
   busy = false,
   active = false,
   size = 14,
+  labelText,
+  bordered = false,
+  segmented = false,
   onToggle,
   ...rest
 }: SubsystemDiagnosticToggleProps) {
@@ -122,7 +131,7 @@ export function SubsystemDiagnosticToggle({
   const showFixable = fixableCount > 0 && !busy;
   const fixableColor = theme.colors.success ?? '#2da44e';
   const background = active
-    ? hexWithAlpha(color, hover ? 0.24 : 0.16)
+    ? segmented ? theme.colors.border : hexWithAlpha(color, hover ? 0.24 : 0.16)
     : hover
       ? theme.colors.border
       : 'transparent';
@@ -138,15 +147,16 @@ export function SubsystemDiagnosticToggle({
         onMouseEnter={() => setHover(true)}
         onMouseLeave={() => setHover(false)}
         title={label}
-        aria-label={label}
+        aria-label={labelText ? `${labelText}: ${label}` : label}
         aria-pressed={active}
         style={{
           display: 'inline-flex',
           alignItems: 'center',
+          justifyContent: bordered || segmented ? 'center' : undefined,
           gap: 4,
-          height: 22,
-          padding: showCount ? '0 7px 0 6px' : '0 5px',
-          border: 'none',
+          height: bordered || segmented ? 28 : 22,
+          padding: bordered || segmented ? '4px 7px' : showCount ? '0 7px 0 6px' : '0 5px',
+          border: bordered ? `1px solid ${theme.colors.border}` : 'none',
           borderRadius: 4,
           background,
           color,
@@ -206,6 +216,11 @@ export function SubsystemDiagnosticToggle({
             </span>
           )}
         </span>
+        {labelText && (
+          <span style={{ fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[0] }}>
+            {labelText}
+          </span>
+        )}
         {showCount && (
           <span
             style={{

package/src/subsystem/GraphSidebar.test.tsx

@@ -95,6 +95,24 @@ describe('GraphSidebar chrome', () => {
     expect(queryByText('body')).toBeNull();
   });
 
+  test('a capped header fits its content while the body fills the remaining space', () => {
+    const { container } = renderSidebar({
+      header: createElement('span', null, 'description'),
+      headerMaxHeight: '30%',
+      sidebarBody: createElement('span', null, 'trails'),
+    });
+    const column = sidebarColumn(container);
+    const header = column.firstElementChild as HTMLElement;
+    const body = column.lastElementChild as HTMLElement;
+    expect(header.style.flexGrow).toBe('0');
+    expect(header.style.flexBasis).toBe('auto');
+    expect(header.style.maxHeight).toBe('30%');
+    expect(header.style.boxSizing).toBe('border-box');
+    expect(header.style.overflowY).toBe('auto');
+    expect(body.style.flexGrow).toBe('1');
+    expect(body.style.height).toBe('');
+  });
+
   test('controlled width applies to the column and reports drag changes', () => {
     let reports = 0;
     const { container, getByLabelText } = renderSidebar({

package/src/subsystem/GraphSidebar.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
-import type { MouseEvent as ReactMouseEvent, ReactNode } from 'react';
+import type { CSSProperties, MouseEvent as ReactMouseEvent, ReactNode } from 'react';
 import { useTheme } from '@principal-ade/industry-theme';
 
 /**
@@ -55,6 +55,8 @@ export interface GraphSidebarProps {
   /** Give the header the flexible share of the column, pinning the lower
    *  panel at half height (e.g. a description that unpacks on demand). */
   stretchHeader?: boolean;
+  /** Cap the upper block while letting short content use only the height it needs. */
+  headerMaxHeight?: CSSProperties['maxHeight'];
   /** Controlled sidebar width (px). */
   width?: number;
   onWidthChange?: (width: number) => void;
@@ -100,6 +102,7 @@ export function GraphSidebar({
   hidden = false,
   bodyHidden = false,
   stretchHeader = false,
+  headerMaxHeight,
   width,
   onWidthChange,
   defaultWidth = DEFAULT_WIDTH,
@@ -207,6 +210,8 @@ export function GraphSidebar({
             style={{
               flex: stretchHeader ? 1 : '0 0 auto',
               minHeight: 0,
+              maxHeight: headerMaxHeight,
+              boxSizing: 'border-box',
               overflowY: 'auto',
               padding: 16,
               display: 'flex',