@principal-ai/subsystems-react 0.56.1 → 0.56.2

package/src/subsystem/FileDrawer.test.tsx

@@ -0,0 +1,130 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import type { ComponentProps } 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 { FileDrawer } from './FileDrawer';
+
+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.KeyboardEvent = dom.KeyboardEvent;
+globals.localStorage = dom.localStorage;
+globals.sessionStorage = dom.sessionStorage;
+globals.matchMedia = dom.matchMedia.bind(dom);
+globals.requestAnimationFrame = dom.requestAnimationFrame.bind(dom);
+globals.cancelAnimationFrame = dom.cancelAnimationFrame.bind(dom);
+
+afterEach(cleanup);
+
+function drawer(props: Partial<ComponentProps<typeof FileDrawer>> = {}) {
+  return (
+    <ThemeProvider theme={defaultEditorTheme}>
+      <FileDrawer title="Trail code" onClose={() => {}} {...props}>
+        <input aria-label="Code state" defaultValue="selected step" />
+      </FileDrawer>
+    </ThemeProvider>
+  );
+}
+
+function parts(container: HTMLElement) {
+  return {
+    spacer: container.children[0] as HTMLElement,
+    panel: container.children[1] as HTMLElement,
+  };
+}
+
+describe('FileDrawer docking', () => {
+  test('keeps the default bottom drawer and reserves height', () => {
+    const { container } = render(drawer());
+    const { spacer, panel } = parts(container);
+    expect(spacer.style.height).toBe('45%');
+    expect(spacer.style.width).toBe('');
+    expect(panel.style.height).toBe('45%');
+    expect(panel.style.left).toBe('0px');
+    expect(panel.style.right).toBe('0px');
+    expect(panel.style.top).toBe('');
+    expect(panel.style.borderTopStyle).toBe('solid');
+  });
+
+  test('docks on the left and reserves width before the canvas', () => {
+    const { container } = render(drawer({ placement: 'left' }));
+    const { spacer, panel } = parts(container);
+    expect(spacer.style.width).toBe('45%');
+    expect(spacer.style.height).toBe('');
+    expect(spacer.style.order).toBe('-1');
+    expect(panel.style.width).toBe('45%');
+    expect(panel.style.height).toBe('100%');
+    expect(panel.style.left).toBe('0px');
+    expect(panel.style.right).toBe('');
+    expect(panel.style.top).toBe('0px');
+    expect(panel.style.borderRightStyle).toBe('solid');
+    expect(panel.style.borderTopStyle).toBe('none');
+  });
+
+  test('preserves mounted content when switching dock axes', () => {
+    const { container, getByLabelText, rerender } = render(drawer());
+    const input = getByLabelText('Code state') as HTMLInputElement;
+    fireEvent.change(input, { target: { value: 'step 3' } });
+    rerender(drawer({ placement: 'left' }));
+    expect(getByLabelText('Code state')).toBe(input);
+    expect(input.value).toBe('step 3');
+    expect(parts(container).spacer.style.height).toBe('');
+    rerender(drawer());
+    expect(getByLabelText('Code state')).toBe(input);
+    expect(parts(container).spacer.style.width).toBe('');
+    expect(parts(container).panel.style.width).toBe('');
+  });
+
+  test('maximizes and restores along the left dock axis', () => {
+    const { container, getByLabelText } = render(drawer({ placement: 'left' }));
+    fireEvent.click(getByLabelText('Maximize code view'));
+    expect(parts(container).panel.style.width).toBe('100%');
+    expect(parts(container).spacer.style.width).toBe('0px');
+    fireEvent.click(getByLabelText('Minimize code view'));
+    expect(parts(container).panel.style.width).toBe('45%');
+    expect(parts(container).spacer.style.width).toBe('45%');
+  });
+
+  test('fills the graph area for full-file reading', () => {
+    const { container } = render(drawer({ placement: 'left', fillHeight: true }));
+    expect(parts(container).panel.style.width).toBe('100%');
+    expect(parts(container).spacer.style.width).toBe('0px');
+  });
+
+  test('closed and hidden left drawers reserve no width', () => {
+    const { container, rerender } = render(drawer({ placement: 'left', title: null }));
+    expect(parts(container).panel.style.width).toBe('0px');
+    expect(parts(container).spacer.style.width).toBe('0px');
+    rerender(drawer({ placement: 'left', hidden: true }));
+    expect(parts(container).panel.style.width).toBe('0px');
+    expect(parts(container).spacer.style.width).toBe('0px');
+  });
+
+  test('closing resets maximize state before reopening', () => {
+    const { container, getByLabelText, rerender } = render(drawer({ placement: 'left' }));
+    fireEvent.click(getByLabelText('Maximize code view'));
+    rerender(drawer({ placement: 'left', title: null }));
+    rerender(drawer({ placement: 'left' }));
+    expect(parts(container).panel.style.width).toBe('45%');
+    expect(getByLabelText('Maximize code view')).not.toBeNull();
+  });
+
+  test('Escape closes a left drawer unless a full-file overlay handles it', () => {
+    let closes = 0;
+    const onClose = () => { closes++; };
+    const { rerender } = render(drawer({ placement: 'left', onClose }));
+    fireEvent.keyDown(window, { key: 'Escape' });
+    expect(closes).toBe(1);
+    rerender(drawer({ placement: 'left', onClose, suppressEscape: true }));
+    fireEvent.keyDown(window, { key: 'Escape' });
+    expect(closes).toBe(1);
+  });
+});

package/src/subsystem/FileDrawer.tsx

@@ -1,6 +1,6 @@
 /**
- * FileDrawer — bottom panel that slides up from the bottom of the graph area
- * to show file / trail code. Opened by sidebar file-tree clicks,
+ * FileDrawer — bottom or left panel in the graph area
+ * showing file / trail code. Opened by sidebar file-tree clicks,
  * declaration links, and trail step focus; content is injected as
  * children by the graph component.
  */
@@ -10,18 +10,15 @@ import type { ReactNode } from "react";
 import { useTheme } from "@principal-ade/industry-theme";
 import { Minimize2, Maximize2, X } from "lucide-react";
 
-/** Matches `transition: height …` below — callers that fitView after open
- *  should wait at least this long so the canvas has its reduced height. */
+/** Matches the drawer's size transition; wait this long before fitting the canvas. */
 export const FILE_DRAWER_HEIGHT_MS = 200;
 
-/** Bottom panel that slides up from the bottom of the graph area.
- *  Bottom-anchored with an animated height; an in-flow spacer reserves its
- *  footprint so the canvas shrinks while open (nothing covered). Stays mounted
- *  so open/close/maximize animate. The header's maximize button (or a
- *  double-click) grows it over the whole graph column for whole-file reading. */
+/** An in-flow spacer reserves the panel's footprint so it never covers the
+ *  canvas. Stays mounted across open/close, maximize, and docking changes. */
 export function FileDrawer({
   title,
   onClose,
+  placement = "bottom",
   fillHeight = false,
   suppressEscape = false,
   hidden = false,
@@ -32,7 +29,9 @@ export function FileDrawer({
   /** Drawer chrome title; `null` closes the drawer. */
   title: string | null;
   onClose: () => void;
-  /** When true and open, fill the graph column instead of ~45% height. */
+  /** Left docking requires a row container; bottom docking requires a column. */
+  placement?: "bottom" | "left";
+  /** When true and open, fill the graph area instead of ~45% of its dock axis. */
   fillHeight?: boolean;
   /** Skip Escape handling (e.g. while a full-file overlay is on top). */
   suppressEscape?: boolean;
@@ -54,18 +53,17 @@ export function FileDrawer({
   const showProgress = progress != null && progress.total > 1;
   const [closeHover, setCloseHover] = useState(false);
   const [maxHover, setMaxHover] = useState(false);
-  // Full-height mode: the maximize button or double-clicking the header.
-  // The panel is always bottom-anchored with an animated height, and a spacer
-  // in normal flow reserves its footprint, so maximizing grows it upward over
-  // the still-mounted graph instead of snapping to full.
+  // Maximize grows over the still-mounted graph along the current dock axis.
   const [maximized, setMaximized] = useState(false);
-  // A closed drawer reopens at the default height, not maximized.
+  // A closed drawer reopens at the default size, not maximized.
   useEffect(() => {
     if (!open) setMaximized(false);
   }, [open]);
-  const fullHeight = open && (maximized || fillHeight);
+  const fullSize = open && (maximized || fillHeight);
+  const sideDocked = placement === "left";
+  const sizeAxis = sideDocked ? "width" : "height";
   // Space the panel takes out of the canvas's flow (0 when it overlays fully).
-  const reservedHeight = fullHeight ? 0 : open ? "45%" : 0;
+  const reservedSize = fullSize ? 0 : open ? "45%" : 0;
 
   useEffect(() => {
     if (!open || suppressEscape) return;
@@ -78,36 +76,37 @@ export function FileDrawer({
 
   return (
     <>
-      {/* Reserves the drawer's footprint in the column so the canvas shrinks
-          while the drawer is open. Animates with the panel, so the boundary
-          between graph and code slides smoothly. */}
+      {/* Reserve the same size along the parent's matching flex axis. */}
       <div
         aria-hidden="true"
         style={{
           flexShrink: 0,
-          height: reservedHeight,
-          transition: `height ${FILE_DRAWER_HEIGHT_MS}ms ease`,
+          order: sideDocked ? -1 : undefined,
+          [sizeAxis]: reservedSize,
+          transition: `${sizeAxis} ${FILE_DRAWER_HEIGHT_MS}ms ease`,
         }}
       />
-      {/* The panel — bottom-anchored and grown via `height`, so maximize/fill
-          reads as dragging up over the diagram. */}
       <div
         style={{
           position: "absolute",
           left: 0,
-          right: 0,
+          top: sideDocked ? 0 : undefined,
+          right: sideDocked ? undefined : 0,
           bottom: 0,
           // Above the edge-label overlay (zIndex 5), React Flow, and overlays
           // (zIndex 6–8); 30 lifts it over the whole graph area when maximized.
           zIndex: maximized ? 30 : 6,
-          height: open ? (fullHeight ? "100%" : "45%") : 0,
+          width: sideDocked ? (open ? (fullSize ? "100%" : "45%") : 0) : undefined,
+          height: sideDocked ? "100%" : open ? (fullSize ? "100%" : "45%") : 0,
+          minWidth: 0,
           minHeight: 0,
           overflow: "hidden",
           display: "flex",
           flexDirection: "column",
           background: theme.colors.background,
-          borderTop: open ? `1px solid ${theme.colors.border}` : "none",
-          transition: `height ${FILE_DRAWER_HEIGHT_MS}ms ease`,
+          borderTop: open && !sideDocked ? `1px solid ${theme.colors.border}` : "none",
+          borderRight: open && sideDocked ? `1px solid ${theme.colors.border}` : "none",
+          transition: `${sizeAxis} ${FILE_DRAWER_HEIGHT_MS}ms ease`,
         }}
       >
         <div

package/src/subsystem/GraphSidebar.test.tsx

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from 'bun:test';
-import { createElement } from 'react';
+import { createElement, useState } from 'react';
 import { Window } from 'happy-dom';
 import { cleanup, fireEvent, render } from '@testing-library/react/pure';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
@@ -125,6 +125,59 @@ describe('GraphSidebar chrome', () => {
     expect(sidebarColumn(container).style.width).toBe('400px');
   });
 
+  test('multiple moves track displacement from drag start without accumulating', () => {
+    const { container, getByLabelText } = renderSidebar({});
+    const handle = getByLabelText('Resize sidebar');
+    fireEvent.mouseDown(handle, { clientX: 100 });
+    fireEvent.mouseMove(document, { clientX: 120 });
+    expect(sidebarColumn(container).style.width).toBe('340px');
+    fireEvent.mouseMove(document, { clientX: 140 });
+    expect(sidebarColumn(container).style.width).toBe('360px');
+    fireEvent.mouseMove(document, { clientX: 110 });
+    expect(sidebarColumn(container).style.width).toBe('330px');
+    fireEvent.mouseUp(document);
+
+    // Each new gesture starts from the width the previous gesture left.
+    fireEvent.mouseDown(handle, { clientX: 110 });
+    fireEvent.mouseMove(document, { clientX: 130 });
+    fireEvent.mouseUp(document);
+    expect(sidebarColumn(container).style.width).toBe('350px');
+  });
+
+  test('clamps at both limits and follows the pointer back from them', () => {
+    const { container, getByLabelText } = renderSidebar({});
+    fireEvent.mouseDown(getByLabelText('Resize sidebar'), { clientX: 100 });
+    fireEvent.mouseMove(document, { clientX: 500 });
+    expect(sidebarColumn(container).style.width).toBe('600px');
+    fireEvent.mouseMove(document, { clientX: 150 });
+    expect(sidebarColumn(container).style.width).toBe('370px');
+    fireEvent.mouseMove(document, { clientX: -100 });
+    expect(sidebarColumn(container).style.width).toBe('240px');
+    fireEvent.mouseMove(document, { clientX: 100 });
+    expect(sidebarColumn(container).style.width).toBe('320px');
+    fireEvent.mouseUp(document);
+  });
+
+  test('controlled host updates do not change the drag baseline', () => {
+    function ControlledSidebar() {
+      const [width, setWidth] = useState(400);
+      return createElement(
+        ThemeProvider,
+        { theme: defaultEditorTheme },
+        createElement(GraphSidebar, { width, onWidthChange: setWidth }),
+      );
+    }
+    const { container, getByLabelText } = render(createElement(ControlledSidebar));
+    fireEvent.mouseDown(getByLabelText('Resize sidebar'), { clientX: 100 });
+    fireEvent.mouseMove(document, { clientX: 140 });
+    expect(sidebarColumn(container).style.width).toBe('440px');
+    fireEvent.mouseMove(document, { clientX: 160 });
+    expect(sidebarColumn(container).style.width).toBe('460px');
+    fireEvent.mouseMove(document, { clientX: 100 });
+    expect(sidebarColumn(container).style.width).toBe('400px');
+    fireEvent.mouseUp(document);
+  });
+
   test('a drag ends by persisting the width under persistKey', () => {
     const { getByLabelText } = renderSidebar({
       persistKey: 'gs-test',
@@ -132,6 +185,8 @@ describe('GraphSidebar chrome', () => {
     });
     const handle = getByLabelText('Resize sidebar');
     fireEvent.mouseDown(handle, { clientX: 100 });
+    fireEvent.mouseMove(document, { clientX: 140 });
+    fireEvent.mouseMove(document, { clientX: 180 });
     fireEvent.mouseMove(document, { clientX: 200 });
     fireEvent.mouseUp(document);
     expect(window.localStorage.getItem('principal.subsystems.sidebarWidth.gs-test')).toBe('420');

package/src/subsystem/GraphSidebar.tsx

@@ -130,6 +130,7 @@ export function GraphSidebar({
   // persisting only then — not on every mousemove.
   const [dragging, setDragging] = useState(false);
   const dragStartX = useRef(0);
+  const dragStartWidth = useRef(0);
   // Mirror of the current width for the mouseup handler (a closure over the
   // drag-start render would persist the stale start width).
   const currentWidthRef = useRef(effectiveWidth);
@@ -139,6 +140,7 @@ export function GraphSidebar({
     (e: ReactMouseEvent) => {
       e.preventDefault();
       dragStartX.current = e.clientX;
+      dragStartWidth.current = effectiveWidth;
       currentWidthRef.current = effectiveWidth;
       setDragging(true);
       onDraggingChange?.(true);
@@ -150,7 +152,7 @@ export function GraphSidebar({
     if (!dragging) return;
     const onMove = (e: MouseEvent) => {
       const next = Math.min(
-        Math.max(currentWidthRef.current + (e.clientX - dragStartX.current), minWidth),
+        Math.max(dragStartWidth.current + (e.clientX - dragStartX.current), minWidth),
         maxWidth,
       );
       if (controlled) {

package/src/subsystem/SubsystemComponentGraph.tsx

@@ -199,7 +199,7 @@ export interface SubsystemComponentGraphProps {
    * sidebar's bottom half offers a Files/Trails toggle:
    * the flows panel lists each trail's steps (`symbol` or `file:line`);
    * clicking a flow row toggles its steps; clicking a step focuses that
-   * step's edge and (when `renderTrailViewer` is set) opens the bottom
+   * step's edge and (when `renderTrailViewer` is set) opens the code
    * drawer on that flow's snippets. Opened flows stay on the canvas
    * (unselected ones dimmed); everything else is hidden.
    */
@@ -450,8 +450,9 @@ export interface SubsystemComponentGraphProps {
   renderFileViewer?: (file: string, opts?: SubsystemOpenFileOptions) => ReactNode;
   /**
    * Host-injected multi-snippet viewer for a focused trail. When set,
-   * clicking a flow step opens the bottom drawer with this content and
-   * updates it as the focused step changes.
+   * clicking a flow step opens the code drawer with this content and
+   * updates it as the focused step changes. Docks left for vertical layouts,
+   * below the canvas for horizontal layouts.
    */
   renderTrailViewer?: (ctx: TrailViewerContext) => ReactNode;
   /**
@@ -928,10 +929,10 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
   const showDesc = !!description && descriptionVisible;
   // Sidebar width lives in the shared GraphWithSidebar chrome — draggable and
   // persisted under `principal.subsystems.sidebarWidth.<persistKey>`. The graph
-  // only bounds how wide the panel may get so the canvas keeps room to breathe;
+  // caps it at half the view width so the canvas keeps room to breathe;
   // a width saved under the old view-state key still seeds the panel once.
   const sidebarMaxWidth = useMemo(
-    () => Math.max(Math.min((_measured?.w ?? 680) * 0.5, 600), 240),
+    () => Math.max((_measured?.w ?? 680) * 0.5, 240),
     [_measured?.w],
   );
   // Persist the trail working set per model. Each write merges into the
@@ -2080,7 +2081,8 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
   const drawerFillHeight =
     drawerTarget?.kind === 'file' && drawerTarget.startLine == null;
   const fileOverlayOpen = fileOverlay != null;
-  const collapseCanvas = drawerFillHeight || fileOverlayOpen;
+  const collapseCanvas =
+    drawerFillHeight || (fileOverlayOpen && committedDirection !== 'vertical');
 
   // Drop the full-file overlay when the underlying trail drawer changes
   // or closes — open-file keeps the same drawerTarget so the snippets stay mounted.
@@ -3041,6 +3043,57 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       })}
     </>
   ) : null;
+  const fileOverlayView = fileOverlay && (
+    <div
+      style={{
+        position: 'absolute',
+        inset: 0,
+        zIndex: 8,
+        display: 'flex',
+        flexDirection: 'column',
+        background: theme.colors.background,
+        borderLeft: `1px solid ${theme.colors.border}`,
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 8,
+          padding: '6px 10px',
+          borderBottom: `1px solid ${theme.colors.border}`,
+          flexShrink: 0,
+        }}
+      >
+        <span
+          title={fileOverlay.file}
+          style={{
+            flex: 1,
+            minWidth: 0,
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            whiteSpace: 'nowrap',
+            fontFamily: theme.fonts.monospace,
+            fontSize: theme.fontSizes[0],
+            color: theme.colors.textMuted ?? theme.colors.textSecondary,
+          }}
+        >
+          {fileOverlay.file}
+        </span>
+        <FileOverlayCloseButton onClose={closeFileOverlay} />
+      </div>
+      <div style={{ flex: 1, minHeight: 0, overflow: 'auto' }}>
+        <FileDrawerContent
+          render={renderDrawerContent}
+          file={fileOverlay.file}
+          startLine={fileOverlay.startLine}
+          endLine={fileOverlay.endLine}
+          fullFile
+        />
+      </div>
+    </div>
+  );
+
   return (
     <GraphWithSidebar
       hidden={!sidebarVisible}
@@ -3063,7 +3116,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
       onResizeEnd={() => requestAnimationFrame(() => fitView())}
     >
       {/* Graph area */}
-      <div style={{ flex: 1, position: 'relative', display: 'flex', flexDirection: 'column', minHeight: 0 }}>
+      <div style={{ flex: 1, position: 'relative', display: 'flex', flexDirection: committedDirection === 'vertical' ? 'row' : 'column', minHeight: 0, minWidth: 0 }}>
         {/* Canvas box — the edge-label overlay and legend anchor here, so
             overlays shift with the canvas, not the labels. Collapses when the
             file drawer fills the column (whole-file reading). */}
@@ -3073,6 +3126,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
             position: 'relative',
             flex: collapseCanvas ? 0 : 1,
             minHeight: 0,
+            minWidth: 0,
             height: collapseCanvas ? 0 : undefined,
             overflow: 'hidden',
             display: 'flex',
@@ -3537,10 +3591,13 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
             />
           </div>
         )}
+        {/* Vertical full-file reading replaces only the graph, not either left column. */}
+        {committedDirection === 'vertical' && fileOverlayView}
         </div>
       <FileDrawer
         title={drawerTitle}
         onClose={closeDrawer}
+        placement={committedDirection === 'vertical' ? 'left' : 'bottom'}
         fillHeight={drawerFillHeight}
         suppressEscape={fileOverlayOpen}
         hidden={hideDrawer}
@@ -3579,56 +3636,7 @@ function Inner({ components, trails, graphifyRelations, orderByLine, layoutDirec
           />
         ) : null}
       </FileDrawer>
-      {fileOverlay && (
-        <div
-          style={{
-            position: 'absolute',
-            inset: 0,
-            zIndex: 8,
-            display: 'flex',
-            flexDirection: 'column',
-            background: theme.colors.background,
-            borderLeft: `1px solid ${theme.colors.border}`,
-          }}
-        >
-          <div
-            style={{
-              display: 'flex',
-              alignItems: 'center',
-              gap: 8,
-              padding: '6px 10px',
-              borderBottom: `1px solid ${theme.colors.border}`,
-              flexShrink: 0,
-            }}
-          >
-            <span
-              title={fileOverlay.file}
-              style={{
-                flex: 1,
-                minWidth: 0,
-                overflow: 'hidden',
-                textOverflow: 'ellipsis',
-                whiteSpace: 'nowrap',
-                fontFamily: theme.fonts.monospace,
-                fontSize: theme.fontSizes[0],
-                color: theme.colors.textMuted ?? theme.colors.textSecondary,
-              }}
-            >
-              {fileOverlay.file}
-            </span>
-            <FileOverlayCloseButton onClose={closeFileOverlay} />
-          </div>
-          <div style={{ flex: 1, minHeight: 0, overflow: 'auto' }}>
-            <FileDrawerContent
-              render={renderDrawerContent}
-              file={fileOverlay.file}
-              startLine={fileOverlay.startLine}
-              endLine={fileOverlay.endLine}
-              fullFile
-            />
-          </div>
-        </div>
-      )}
+      {committedDirection !== 'vertical' && fileOverlayView}
       {/* Startup cover — hides measurement, layout swap, and camera settle.
           Kept away during a direction flip: the flip is meant to be watched,
           and the cover would swallow the node slide. */}