@principal-ai/subsystems-react 0.53.6 → 0.54.0

package/src/subsystem/TrailStepsNav.test.tsx

@@ -0,0 +1,179 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { createElement } from 'react';
+import { Window } from 'happy-dom';
+import { cleanup, fireEvent, render } from '@testing-library/react/pure';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { TrailStepsNav } from './TrailStepsNav';
+import type { SubsystemTrail } from './model';
+
+// Bun's happy-dom test environment isn't registered (no @happy-dom/global-
+// registrator), so wire the DOM primitives React DOM needs before rendering.
+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.getComputedStyle = dom.getComputedStyle.bind(dom);
+globals.requestAnimationFrame = dom.requestAnimationFrame.bind(dom);
+globals.cancelAnimationFrame = dom.cancelAnimationFrame.bind(dom);
+globals.localStorage = dom.localStorage;
+globals.matchMedia = dom.matchMedia.bind(dom);
+
+afterEach(cleanup);
+
+const step = (from: string, to: string, symbol: string, annotation?: string) => ({
+  from,
+  to,
+  mechanism: 'calls' as const,
+  file: `${from}.ts`,
+  line: 1,
+  purl: `pkg:github/x#${from}.ts`,
+  symbol,
+  ...(annotation ? { annotation } : {}),
+});
+
+const TRAILS: SubsystemTrail[] = [
+  {
+    id: 't1',
+    title: 'First flow',
+    steps: [step('a', 'b', 'A.go', 'Read the source seam.'), step('b', 'c', 'B.go')],
+  },
+  { id: 't2', title: 'Second flow', steps: [step('c', 'd', 'C.go')] },
+];
+
+function renderNav(props: Record<string, unknown>) {
+  return render(
+    createElement(
+      ThemeProvider,
+      { theme: defaultEditorTheme },
+      createElement(TrailStepsNav as never, props as never),
+    ),
+  );
+}
+
+describe('TrailStepsNav', () => {
+  test('lists trails with step counts and focuses on click', () => {
+    let focused: string | null = null;
+    const { getByText, getByRole } = renderNav({
+      trails: TRAILS,
+      focusedTrailId: null,
+      focusedStepIndex: null,
+      hoveredTrailStep: null,
+      onFocusFlow: (t: SubsystemTrail) => {
+        focused = t.id;
+      },
+      onClearFocus: () => {},
+      onFocusStep: () => {},
+      onHoverStep: () => {},
+      onHoverFlow: () => {},
+      onLeaveStep: () => {},
+    });
+    expect(getByText('First flow')).toBeTruthy();
+    expect(getByText('Second flow')).toBeTruthy();
+    fireEvent.click(getByRole('button', { name: /First flow/ }));
+    expect(focused).toBe('t1');
+  });
+
+  test('a hovered trail row previews the flow', () => {
+    const hovered: string[] = [];
+    const { getByRole } = renderNav({
+      trails: TRAILS,
+      focusedTrailId: null,
+      focusedStepIndex: null,
+      hoveredTrailStep: null,
+      onFocusFlow: () => {},
+      onClearFocus: () => {},
+      onFocusStep: () => {},
+      onHoverStep: () => {},
+      onHoverFlow: (t: SubsystemTrail) => hovered.push(t.id),
+      onLeaveStep: () => {},
+    });
+    fireEvent.mouseEnter(getByRole('button', { name: /Second flow/ }));
+    expect(hovered).toContain('t2');
+  });
+
+  test('back slides the step pane out before its steps unmount', async () => {
+    const base = {
+      trails: TRAILS,
+      focusedStepIndex: null,
+      hoveredTrailStep: null,
+      onFocusFlow: () => {},
+      onClearFocus: () => {},
+      onFocusStep: () => {},
+      onHoverStep: () => {},
+      onHoverFlow: () => {},
+      onLeaveStep: () => {},
+      transitionMs: 30,
+    };
+    const { getByText, queryByText, rerender } = renderNav({ ...base, focusedTrailId: 't1' });
+    expect(getByText('A.go')).toBeTruthy();
+    // Back clears the focus, but the pane keeps its content while it slides out.
+    rerender(
+      createElement(
+        ThemeProvider,
+        { theme: defaultEditorTheme },
+        createElement(TrailStepsNav as never, { ...base, focusedTrailId: null } as never),
+      ),
+    );
+    expect(queryByText('A.go')).toBeTruthy();
+    // Once the transition has run, the step content is dropped.
+    await new Promise((r) => setTimeout(r, 30 + 40));
+    expect(queryByText('A.go')).toBeNull();
+  });
+
+  test('a focused trail shows its steps; back clears the focus', () => {
+    let cleared = false;
+    let focusedStep: number | null = null;
+    const { getByText, getByLabelText, getByRole } = renderNav({
+      trails: TRAILS,
+      focusedTrailId: 't1',
+      focusedStepIndex: null,
+      hoveredTrailStep: null,
+      onFocusFlow: () => {},
+      onClearFocus: () => {
+        cleared = true;
+      },
+      onFocusStep: (_t: SubsystemTrail, i: number) => {
+        focusedStep = i;
+      },
+      onHoverStep: () => {},
+      onHoverFlow: () => {},
+      onLeaveStep: () => {},
+    });
+    // The step pane is translated in; both steps render by symbol, and an
+    // annotated step shows its note as the row's description.
+    expect(getByText('A.go')).toBeTruthy();
+    expect(getByText('B.go')).toBeTruthy();
+    expect(getByText('Read the source seam.')).toBeTruthy();
+    fireEvent.click(getByRole('button', { name: /B\.go/ }));
+    expect(focusedStep).toBe(1);
+    fireEvent.click(getByLabelText('Back to trails'));
+    expect(cleared).toBe(true);
+  });
+
+  test('clicking the step-pane header title also goes back', () => {
+    let cleared = false;
+    const { getByRole } = renderNav({
+      trails: TRAILS,
+      focusedTrailId: 't1',
+      focusedStepIndex: null,
+      hoveredTrailStep: null,
+      onFocusFlow: () => {},
+      onClearFocus: () => {
+        cleared = true;
+      },
+      onFocusStep: () => {},
+      onHoverStep: () => {},
+      onHoverFlow: () => {},
+      onLeaveStep: () => {},
+    });
+    // The header title is its own button (the list row's accessible name
+    // includes the step count, so the exact title matches the header).
+    fireEvent.click(getByRole('button', { name: 'First flow' }));
+    expect(cleared).toBe(true);
+  });
+});

package/src/subsystem/TrailStepsNav.tsx

@@ -0,0 +1,372 @@
+import { useCallback, useEffect, useState } from 'react';
+import type { CSSProperties } from 'react';
+import { ChevronRight, Route, X } from 'lucide-react';
+import { useTheme } from '@principal-ade/industry-theme';
+import type { SubsystemTrail } from './model';
+
+/**
+ * TrailStepsNav — the trails side panel as a two-step slide: a list of trails,
+ * and a step pane that slides in from the right when a trail is picked (and
+ * back out when focus clears). The counterpart to `TrailsPanel`'s inline
+ * expand — same data and callbacks, a push instead of a dropdown.
+ *
+ * Pure presentation: the host owns the focus state and the canvas response.
+ * `onFocusFlow` opens the step pane (and, in the C4 drill, hides the elements
+ * the trail does not touch); `onClearFocus` closes it. Hovering a row previews
+ * that trail (`onHoverFlow`); hovering a step previews the hop
+ * (`onHoverStep`), which the host dims to.
+ *
+ * Back is a slide, not a swap: clearing the focus leaves the last trail's steps
+ * rendered until the pane has finished sliding out, so the detail view is what
+ * moves, not a blank pane.
+ *
+ * Each step row leads with its `annotation` (the free-text note anchored to its
+ * site line) as the row's description, with the `symbol` beneath it.
+ */
+
+export interface TrailStepsNavProps {
+  /** Ordered trails — the list pane. */
+  trails: SubsystemTrail[];
+  /** Focused trail id, or null for the list pane. */
+  focusedTrailId: string | null;
+  /** Focused step within the focused trail, or null for the whole flow. */
+  focusedStepIndex: number | null;
+  /** Hovered trail/step, for the preview highlight (`stepIndex: null` = whole). */
+  hoveredTrailStep: { trailId: string; stepIndex: number | null } | null;
+  /** Pick a trail: focus the whole flow — this opens the step pane. */
+  onFocusFlow: (trail: SubsystemTrail) => void;
+  /** Back: clear the focus — this closes the step pane. */
+  onClearFocus: () => void;
+  onFocusStep: (trail: SubsystemTrail, stepIndex: number) => void;
+  onHoverStep: (trail: SubsystemTrail, stepIndex: number) => void;
+  onHoverFlow: (trail: SubsystemTrail) => void;
+  onLeaveStep: () => void;
+  /** Aliases of components marked `proposed` — a row whose steps touch one tints. */
+  proposedAliases?: ReadonlySet<string>;
+  /** Slide duration in ms. @default 340 */
+  transitionMs?: number;
+}
+
+const PROPOSED_COLOR = 'darkgoldenrod';
+
+const PANE: CSSProperties = {
+  position: 'absolute',
+  inset: 0,
+  display: 'flex',
+  flexDirection: 'column',
+  minHeight: 0,
+  willChange: 'transform',
+};
+
+function touchesProposed(trail: SubsystemTrail, proposed?: ReadonlySet<string>): boolean {
+  if (!proposed) return false;
+  return trail.steps.some((s) => proposed.has(s.from) || proposed.has(s.to));
+}
+
+export function TrailStepsNav({
+  trails,
+  focusedTrailId,
+  focusedStepIndex,
+  hoveredTrailStep,
+  onFocusFlow,
+  onClearFocus,
+  onFocusStep,
+  onHoverStep,
+  onHoverFlow,
+  onLeaveStep,
+  proposedAliases,
+  transitionMs = 340,
+}: TrailStepsNavProps) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const hoverBg = theme.colors.backgroundHover ?? theme.colors.backgroundSecondary ?? '#232323';
+  const transition = `transform ${transitionMs}ms cubic-bezier(0.2, 0, 0, 1)`;
+
+  // Hovering a collapsed row previews the whole trail while nothing is focused;
+  // the list pane is the only place that happens.
+  const [hoveredRow, setHoveredRow] = useState<string | null>(null);
+  // Hovering the detail title (or the close) lights the close, so the title
+  // reads as the same back action.
+  const [headerHover, setHeaderHover] = useState(false);
+
+  const focused = trails.find((t) => t.id === focusedTrailId) ?? null;
+  const open = focused != null;
+
+  // The step pane is a translated layer, not a mounted/unmounted one: on back,
+  // `focused` goes null immediately, which would blank the pane's content the
+  // instant the slide-out starts. Hold the last focused trail through the
+  // transition, then drop it — slide first, unmount after. A fresh focus lands
+  // immediately (and cancels any pending drop).
+  const [displayedTrail, setDisplayedTrail] = useState<SubsystemTrail | null>(focused);
+  useEffect(() => {
+    if (focused) {
+      setDisplayedTrail(focused);
+      return;
+    }
+    const timer = setTimeout(() => setDisplayedTrail(null), transitionMs);
+    return () => clearTimeout(timer);
+  }, [focused, transitionMs]);
+
+  // A focused trail (from the graph side) always lands on the step pane.
+  const leaveList = useCallback(() => {
+    setHoveredRow(null);
+  }, []);
+
+  useEffect(() => {
+    if (open) setHoveredRow(null);
+    setHeaderHover(false);
+  }, [open]);
+
+  return (
+    <div style={{ flex: 1, minHeight: 0, position: 'relative', overflow: 'hidden' }}>
+      {/* List pane. */}
+      <div
+        aria-hidden={open}
+        style={{
+          ...PANE,
+          transform: open ? 'translateX(-100%)' : 'translateX(0)',
+          transition,
+        }}
+        onMouseLeave={leaveList}
+      >
+        <div style={{ flex: 1, minHeight: 0, overflowY: 'auto', padding: '0 0 12px' }}>
+          {trails.map((trail) => {
+            const proposed = touchesProposed(trail, proposedAliases);
+            const focusedRow = trail.id === focusedTrailId;
+            const hovered = hoveredRow === trail.id;
+            return (
+              <button
+                key={trail.id}
+                type="button"
+                onMouseEnter={() => {
+                  setHoveredRow(trail.id);
+                  onHoverFlow(trail);
+                }}
+                onMouseLeave={leaveList}
+                onClick={() => onFocusFlow(trail)}
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 8,
+                  width: '100%',
+                  minWidth: 0,
+                  padding: '10px 8px 10px 12px',
+                  border: 'none',
+                  borderRadius: 0,
+                  background: focusedRow || hovered ? hoverBg : 'transparent',
+                  cursor: 'pointer',
+                  textAlign: 'left',
+                  transition: 'background 120ms ease',
+                }}
+              >
+                <Route
+                  size={14}
+                  strokeWidth={2}
+                  aria-hidden
+                  style={{
+                    flexShrink: 0,
+                    color: focusedRow || hovered ? theme.colors.primary : muted,
+                    transition: 'color 120ms ease',
+                  }}
+                />
+                <span
+                  style={{
+                    flex: 1,
+                    minWidth: 0,
+                    overflowWrap: 'anywhere',
+                    fontSize: theme.fontSizes[1],
+                    fontFamily: theme.fonts.monospace,
+                    fontWeight: 600,
+                    color: proposed ? PROPOSED_COLOR : theme.colors.text,
+                  }}
+                >
+                  {trail.title}
+                </span>
+                <span
+                  style={{
+                    flexShrink: 0,
+                    fontSize: theme.fontSizes[0],
+                    fontFamily: theme.fonts.monospace,
+                    color: muted,
+                  }}
+                >
+                  {trail.steps.length}
+                </span>
+                <ChevronRight size={14} strokeWidth={2} style={{ flexShrink: 0, color: muted }} />
+              </button>
+            );
+          })}
+        </div>
+      </div>
+
+      {/* Step pane. */}
+      <div
+        aria-hidden={!open}
+        style={{
+          ...PANE,
+          transform: open ? 'translateX(0)' : 'translateX(100%)',
+          transition,
+        }}
+      >
+        {displayedTrail && (
+          <>
+            <div
+              style={{
+                flexShrink: 0,
+                display: 'flex',
+                alignItems: 'center',
+                gap: 8,
+                // Left inset + leading cell + gap match the step rows below, so
+                // the trail icon and the step numbers share one column.
+                padding: '6px 6px 6px 12px',
+                borderBottom: `1px solid ${theme.colors.border}`,
+              }}
+            >
+              <Route
+                size={14}
+                strokeWidth={2}
+                aria-hidden
+                // The focused trail: the icon stays primary, matching the row's
+                // hover colour in the list it came from.
+                style={{ flexShrink: 0, color: theme.colors.primary }}
+              />
+              {/* The title is the back affordance too: clicking it goes back to
+                  the list, like the trailing close. */}
+              <button
+                type="button"
+                onClick={onClearFocus}
+                onMouseEnter={() => setHeaderHover(true)}
+                onMouseLeave={() => setHeaderHover(false)}
+                style={{
+                  flex: 1,
+                  minWidth: 0,
+                  display: 'flex',
+                  alignItems: 'center',
+                  padding: 0,
+                  border: 'none',
+                  background: 'transparent',
+                  cursor: 'pointer',
+                  textAlign: 'left',
+                  overflowWrap: 'anywhere',
+                  fontSize: theme.fontSizes[1],
+                  fontFamily: theme.fonts.monospace,
+                  fontWeight: 600,
+                  color: touchesProposed(displayedTrail, proposedAliases) ? PROPOSED_COLOR : theme.colors.text,
+                }}
+              >
+                {displayedTrail.title}
+              </button>
+              <button
+                type="button"
+                aria-label="Back to trails"
+                title="All trails"
+                onClick={onClearFocus}
+                onMouseEnter={() => setHeaderHover(true)}
+                onMouseLeave={() => setHeaderHover(false)}
+                style={{
+                  display: 'inline-flex',
+                  alignItems: 'center',
+                  justifyContent: 'center',
+                  flexShrink: 0,
+                  width: 24,
+                  height: 24,
+                  padding: 0,
+                  border: 'none',
+                  borderRadius: 4,
+                  background: headerHover ? (theme.colors.border ?? hoverBg) : 'transparent',
+                  color: headerHover ? theme.colors.text : muted,
+                  cursor: 'pointer',
+                  transition: 'background 120ms ease, color 120ms ease',
+                }}
+              >
+                <X size={16} strokeWidth={2} />
+              </button>
+            </div>
+            <div
+              style={{ flex: 1, minHeight: 0, overflowY: 'auto', padding: '0 0 12px' }}
+              onMouseLeave={onLeaveStep}
+            >
+              {displayedTrail.steps.map((step, i) => {
+                const active = focusedStepIndex === i;
+                const hovered =
+                  hoveredTrailStep?.trailId === displayedTrail.id &&
+                  hoveredTrailStep.stepIndex === i;
+                return (
+                  <button
+                    key={`${step.from}->${step.to}-${i}`}
+                    type="button"
+                    onMouseEnter={() => onHoverStep(displayedTrail, i)}
+                    onClick={() => onFocusStep(displayedTrail, i)}
+                    style={{
+                      display: 'flex',
+                      alignItems: 'flex-start',
+                      gap: 8,
+                      width: '100%',
+                      minWidth: 0,
+                      padding: '8px 16px 8px 12px',
+                      border: 'none',
+                      borderRadius: 0,
+                      background: active || hovered ? hoverBg : 'transparent',
+                      cursor: 'pointer',
+                      textAlign: 'left',
+                      transition: 'background 120ms ease',
+                    }}
+                  >
+                    <span
+                      style={{
+                        flexShrink: 0,
+                        // Same 14px leading column as the header's trail icon,
+                        // so the digit sits under it.
+                        width: 14,
+                        textAlign: 'center',
+                        paddingTop: 1,
+                        fontSize: theme.fontSizes[0],
+                        fontFamily: theme.fonts.monospace,
+                        color: active ? theme.colors.text : muted,
+                      }}
+                    >
+                      {i + 1}
+                    </span>
+                    <span
+                      style={{
+                        flex: 1,
+                        minWidth: 0,
+                        display: 'flex',
+                        flexDirection: 'column',
+                        gap: 2,
+                      }}
+                    >
+                      {step.annotation && (
+                        <span
+                          style={{
+                            minWidth: 0,
+                            overflowWrap: 'anywhere',
+                            fontSize: theme.fontSizes[1],
+                            fontFamily: theme.fonts.monospace,
+                            color: theme.colors.text,
+                          }}
+                        >
+                          {step.annotation}
+                        </span>
+                      )}
+                      <span
+                        style={{
+                          fontSize: theme.fontSizes[0],
+                          fontFamily: theme.fonts.body,
+                          color: muted,
+                          lineHeight: 1.35,
+                        }}
+                      >
+                        {step.symbol ?? step.from}
+                      </span>
+                    </span>
+                  </button>
+                );
+              })}
+            </div>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/subsystem/TrailsPanel.tsx

@@ -223,7 +223,7 @@ function TrailFlow({
           display: 'flex',
           alignItems: 'center',
           gap: 4,
-          height: TRAIL_CONTROL_SIZE,
+          minHeight: TRAIL_CONTROL_SIZE,
           padding: '0 0 0 16px',
           background: wholeFlowActive || headerHover ? hoverBg : 'transparent',
           transition: 'background 120ms ease',
@@ -259,9 +259,8 @@ function TrailFlow({
         >
           <span
             style={{
-              overflow: 'hidden',
-              textOverflow: 'ellipsis',
-              whiteSpace: 'nowrap',
+              minWidth: 0,
+              overflowWrap: 'anywhere',
               fontSize: theme.fontSizes[1],
               fontFamily: theme.fonts.monospace,
               fontWeight: 600,