@weasel-js/labkit 1.3.0-pre.0 → 1.4.0-pre.0

package/src/lab/Lab.surface.test.tsx

@@ -0,0 +1,162 @@
+/**
+ * `useTiledSurface` was built, exported and tested, but nothing mounted a
+ * `SurfaceContext` in production — so `useSurfaceOptional()` always answered
+ * null and a tile registered from inside a trial reached nothing.
+ *
+ * The surface is anchored to `.lk-lab__body` rather than wrapped around the
+ * workspace: `.lk-lab__body > .lk-workspace { min-width: 0 }` is a direct-child
+ * selector, so an extra element between them silently drops that rule.
+ */
+import { act, render } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { SurfaceContext } from '../surface/SurfaceContext';
+import { useSurfaceOptional, useSurfaceTile } from '../surface/useSurfaceTile';
+import type { SurfaceFrame, SurfaceHandle } from '../surface/useTiledSurface';
+import { useTiledSurface } from '../surface/useTiledSurface';
+import { Lab } from './Lab';
+
+/** jsdom measures everything as zero, so each element is given a box by hand. */
+function stubBox(el: HTMLElement, left: number, top: number, width: number, height: number): void {
+  vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+    left,
+    top,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect);
+}
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+let seen: SurfaceHandle | null | 'not-rendered' = 'not-rendered';
+
+function Probe() {
+  seen = useSurfaceOptional();
+  const tile = useSurfaceTile('pane');
+  return <div data-testid="pane" ref={tile} />;
+}
+
+const probeInstrument = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'Probe',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <Probe />,
+});
+
+describe('<Lab> surface provider', () => {
+  it('puts a surface handle in reach of an instrument', () => {
+    seen = 'not-rendered';
+    render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
+    expect(seen).not.toBe('not-rendered');
+    expect(seen).not.toBeNull();
+    expect(typeof (seen as unknown as SurfaceHandle).registerTile).toBe('function');
+  });
+
+  it('mounts one inert buffer inside the lab body', () => {
+    const { container } = render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
+    const canvases = container.querySelectorAll('.lk-lab__body > canvas.lk-lab__surface');
+    expect(canvases).toHaveLength(1);
+  });
+
+  it('mounts no buffer of its own when a host already owns the surface', () => {
+    function Host({ children }: { children: ReactNode }) {
+      const surface = useTiledSurface({ onFrame: () => {} });
+      return (
+        <SurfaceContext.Provider value={surface}>
+          <div ref={surface.containerRef}>{children}</div>
+        </SurfaceContext.Provider>
+      );
+    }
+    const { container } = render(
+      <Host>
+        <Lab instruments={[probeInstrument]} defaultInstrument="Probe" />
+      </Host>,
+    );
+    expect(container.querySelectorAll('canvas.lk-lab__surface')).toHaveLength(0);
+  });
+
+  it('keeps the workspace a direct child of the lab body', () => {
+    // The min-width:0 rule that keeps the flex row from overflowing is
+    // `.lk-lab__body > .lk-workspace`. An element inserted between them drops
+    // it, and jsdom cannot see the overflow that follows.
+    const { container } = render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
+    const body = container.querySelector('.lk-lab__body');
+    expect(body).not.toBeNull();
+    expect(body?.querySelector(':scope > .lk-workspace')).not.toBeNull();
+  });
+});
+
+describe('<Lab> tile round trip', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) =>
+      setTimeout(() => cb(0), 16),
+    );
+    vi.stubGlobal('cancelAnimationFrame', (id: number) => clearTimeout(id));
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('publishes a rect for a tile an instrument registered', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+
+    function Host({ children }: { children: ReactNode }) {
+      const surface = useTiledSurface({ onFrame: (f) => frames.push(f) });
+      handle = surface;
+      return (
+        <SurfaceContext.Provider value={surface}>
+          <div
+            ref={(el) => {
+              if (!el) return;
+              stubBox(el, 0, 0, 800, 600);
+              surface.containerRef(el);
+            }}
+          >
+            {children}
+          </div>
+        </SurfaceContext.Provider>
+      );
+    }
+
+    render(
+      <Host>
+        <Lab instruments={[probeInstrument]} defaultInstrument="Probe" />
+      </Host>,
+    );
+
+    // The instrument's own div is the tile. Give it a box the container did
+    // not have, so a rect composed against the wrong origin is visible.
+    const pane = document.querySelector('[data-testid="pane"]') as HTMLElement;
+    expect(pane).not.toBeNull();
+    stubBox(pane, 240, 100, 320, 200);
+
+    act(() => {
+      handle?.invalidateRects();
+      handle?.invalidate('pane');
+    });
+    act(() => {
+      vi.advanceTimersByTime(64);
+    });
+
+    // Assert the frame fired at all before asserting its contents — a test
+    // that passes because nothing ran is the failure mode this arc keeps
+    // hitting.
+    expect(frames.length).toBeGreaterThan(0);
+    const rect = frames[frames.length - 1]?.rects.get('pane');
+    expect(rect).toEqual({ x: 240, y: 100, w: 320, h: 200 });
+  });
+});

package/src/lab/Lab.tsx

@@ -1,5 +1,13 @@
 import { ThemeProvider } from '@weasel-js/theme/react';
-import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef } from 'react';
+import {
+  type CSSProperties,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import { useStore } from 'zustand/react';
 import type { TrialContribution } from '../chrome/types';
 import type { ConfigRule, ControlRenderer } from '../config/types';
@@ -8,6 +16,9 @@ import { noneAdapter } from '../state/adapters';
 import { LabStoreContext } from '../state/context';
 import { createLabStore, type LabStore } from '../state/store';
 import type { LabMode, StorageAdapter, TrialRecord } from '../state/types';
+import { SurfaceCanvasContext, SurfaceContext } from '../surface/SurfaceContext';
+import { useSurfaceCanvas, useSurfaceOptional } from '../surface/useSurfaceTile';
+import { useTiledSurface } from '../surface/useTiledSurface';
 import { interstellarTheme } from '../theme/interstellar';
 import type { TrialTool } from '../tools/types';
 import { Trial } from '../trial/Trial';
@@ -22,8 +33,9 @@ import { LabContext, type LabContextValue } from './LabContext';
 import { LabHeader } from './LabHeader';
 import { LabPalette } from './LabPalette';
 import { LabShell } from './LabShell';
+import { createPanelHostRegistry, PanelHostContext } from './panelHost';
 import { useResolvedMode } from './useSystemMode';
-import { type TrialLayout, Workspace } from './Workspace';
+import { type PanelDescriptor, type TrialLayout, Workspace } from './Workspace';
 
 /** Props for `<Lab>`. */
 export interface LabProps {
@@ -137,6 +149,57 @@ export function Lab({
   const savedSnapshots = useStore(store, (s) => s.savedSnapshots);
   const modeValue = useStore(store, (s) => s.mode);
   const layout = useStore(store, (s) => s.layout);
+  const undockedPanels = useStore(store, (s) => s.undockedPanels);
+
+  // One registry for the lab's lifetime: a panel host is a DOM node the
+  // workspace owns and the trial portals into, so it must outlive both ends of
+  // a dock/undock without being rebuilt.
+  const panelHostsRef = useRef<ReturnType<typeof createPanelHostRegistry> | null>(null);
+  if (panelHostsRef.current === null) panelHostsRef.current = createPanelHostRegistry();
+
+  // One shared drawing surface for the whole lab, anchored to the body — tile
+  // rects compose against it, and every tile paints into the one buffer.
+  // `Workspace` invalidates rects when the grid moves something a
+  // ResizeObserver cannot see. A host that already owns a surface keeps it: a
+  // lab embedded in a larger shared-surface app must not open a second GL
+  // tenancy, and mounts no buffer of its own.
+  const outerSurface = useSurfaceOptional();
+  const outerCanvas = useSurfaceCanvas();
+  const [ownCanvas, setOwnCanvas] = useState<HTMLCanvasElement | null>(null);
+  const ownCanvasRef = useRef<HTMLCanvasElement | null>(null);
+  const bufferRef = useRef({ w: 0, h: 0 });
+  const surfaceRef = useRef<ReturnType<typeof useTiledSurface> | null>(null);
+
+  // Sizing the buffer clears all of it, so every tile has to repaint — not
+  // only the one whose move triggered the measurement.
+  const onFrame = useCallback((frame: { size: { width: number; height: number }; dpr: number }) => {
+    const c = ownCanvasRef.current;
+    if (!c) return;
+    const w = Math.round(frame.size.width * frame.dpr);
+    const h = Math.round(frame.size.height * frame.dpr);
+    if (bufferRef.current.w === w && bufferRef.current.h === h) return;
+    bufferRef.current = { w, h };
+    c.width = w;
+    c.height = h;
+    c.style.width = `${frame.size.width}px`;
+    c.style.height = `${frame.size.height}px`;
+    surfaceRef.current?.invalidateAll();
+  }, []);
+
+  const ownSurface = useTiledSurface({ onFrame });
+  surfaceRef.current = ownSurface;
+  const surface = outerSurface ?? ownSurface;
+  const surfaceCanvas = outerSurface ? outerCanvas : ownCanvas;
+
+  const workspacePanels = useMemo<PanelDescriptor[]>(
+    () =>
+      Object.entries(undockedPanels).map(([key, panel]) => ({
+        key,
+        title: panel.sectionId,
+        as: panel.as,
+      })),
+    [undockedPanels],
+  );
   const resolvedMode = useResolvedMode(modeValue);
 
   useEffect(() => {
@@ -232,21 +295,43 @@ export function Lab({
               </>
             }
           >
-            <div className="lk-lab__body">
-              {tools ? <LabPalette tools={tools} /> : null}
-              <Workspace
-                ids={trials.map((w) => w.id)}
-                resizable
-                reorderable
-                onReorder={(ids) => contextValue.reorderTrials(ids)}
-                layout={layout as TrialLayout}
-                onLayoutChange={(next) => store.getState().setLayout(next)}
-              >
-                {trials.map((w) => (
-                  <Trial key={w.id} id={w.id} chrome={chrome} suppress={suppress} />
-                ))}
-              </Workspace>
-            </div>
+            <PanelHostContext.Provider value={panelHostsRef.current}>
+              <SurfaceContext.Provider value={surface}>
+                <SurfaceCanvasContext.Provider value={surfaceCanvas}>
+                  <div
+                    className="lk-lab__body"
+                    ref={outerSurface ? undefined : ownSurface.containerRef}
+                  >
+                    {outerSurface ? null : (
+                      // Above the trials and inert: the marks a tile paints have
+                      // to sit over the instrument's own DOM, and nothing on this
+                      // buffer takes input — each tile has its own input box.
+                      <canvas
+                        className="lk-lab__surface"
+                        ref={(el) => {
+                          ownCanvasRef.current = el;
+                          setOwnCanvas(el);
+                        }}
+                      />
+                    )}
+                    {tools ? <LabPalette tools={tools} /> : null}
+                    <Workspace
+                      panels={workspacePanels}
+                      ids={trials.map((w) => w.id)}
+                      resizable
+                      reorderable
+                      onReorder={(ids) => contextValue.reorderTrials(ids)}
+                      layout={layout as TrialLayout}
+                      onLayoutChange={(next) => store.getState().setLayout(next)}
+                    >
+                      {trials.map((w) => (
+                        <Trial key={w.id} id={w.id} chrome={chrome} suppress={suppress} />
+                      ))}
+                    </Workspace>
+                  </div>
+                </SurfaceCanvasContext.Provider>
+              </SurfaceContext.Provider>
+            </PanelHostContext.Provider>
           </LabShell>
         </ThemeProvider>
       </LabContext.Provider>

package/src/lab/Lab.undock.test.tsx

@@ -0,0 +1,85 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it } from 'vitest';
+import type { TrialContribution } from '../chrome/types';
+import type { Instrument } from '../instrument/types';
+import { Lab } from './Lab';
+
+const bare: Instrument = {
+  name: 'Bare',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => null,
+};
+
+const notes: TrialContribution = {
+  id: 'notes',
+  region: 'sidebar',
+  item: { title: 'Notes', body: <p data-testid="notes-body">jot</p> },
+};
+
+const floater: TrialContribution = {
+  id: 'floater',
+  region: 'sidebar',
+  item: {
+    title: 'Floater',
+    undockAs: 'floating',
+    body: <p data-testid="floater-body">hover</p>,
+  },
+};
+
+const pinned: TrialContribution = {
+  id: 'pinned',
+  region: 'sidebar',
+  item: { title: 'Pinned', undockable: false, body: <p>stay</p> },
+};
+
+function renderLab() {
+  return render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" chrome={[notes]} />);
+}
+
+describe('undocking a sidebar section', () => {
+  it('starts docked inside the trial sidebar', () => {
+    const { container } = renderLab();
+    const sidebar = container.querySelector('.lk-trial__sidebar');
+    expect(sidebar).toContainElement(screen.getByTestId('notes-body'));
+  });
+
+  it('moves the section out of the sidebar and into a workspace panel', async () => {
+    const { container } = renderLab();
+    await userEvent.click(screen.getByRole('button', { name: 'Undock Notes' }));
+
+    expect(container.querySelector('.lk-trial__sidebar')).not.toContainElement(
+      screen.queryByTestId('notes-body'),
+    );
+    const panel = container.querySelector('.lk-panel-tile');
+    expect(panel).toContainElement(screen.getByTestId('notes-body'));
+  });
+
+  it('docks it back', async () => {
+    const { container } = renderLab();
+    await userEvent.click(screen.getByRole('button', { name: 'Undock Notes' }));
+    await userEvent.click(screen.getByRole('button', { name: 'Dock Notes' }));
+
+    expect(container.querySelector('.lk-panel-tile')).toBeNull();
+    expect(container.querySelector('.lk-trial__sidebar')).toContainElement(
+      screen.getByTestId('notes-body'),
+    );
+  });
+
+  it('sends a section declaring undockAs floating to the floating layer', async () => {
+    const { container } = render(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" chrome={[floater]} />,
+    );
+    await userEvent.click(screen.getByRole('button', { name: 'Undock Floater' }));
+
+    const floating = container.querySelector('.lk-workspace__floating');
+    expect(floating).toContainElement(screen.getByTestId('floater-body'));
+    expect(container.querySelector('.lk-panel-tile--floating')).not.toBeNull();
+  });
+
+  it('offers no tear-out control on a section that opts out', () => {
+    render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" chrome={[pinned]} />);
+    expect(screen.queryByRole('button', { name: 'Undock Pinned' })).toBeNull();
+  });
+});

package/src/lab/LabFullChrome.stories.tsx

@@ -280,6 +280,26 @@ export const AllChrome: Story = {
   },
 };
 
+/** Undocking, in both targets. `Notes` declares `undockAs: 'floating'`, so its
+ *  tear-out control sends it to the layer above the grid; every other section
+ *  defaults to a tile and joins the tiling as a peer of the trials. */
+export const UndockablePanels: Story = {
+  args: {
+    ...AllChrome.args,
+    chrome: [
+      {
+        id: 'notes',
+        region: 'sidebar',
+        item: {
+          title: 'Notes',
+          undockAs: 'floating',
+          body: <p className="lk-run-tag">Undock me — I float.</p>,
+        },
+      },
+    ],
+  },
+};
+
 /** The chrome the other story cannot show at the same time: one instrument, so
  *  the header is an Add trial button; one trial, so Close is disabled; no
  *  config schema, canvas, undo or job, so the sidebar falls back to its

package/src/lab/LabShell.less

@@ -48,12 +48,23 @@
   display: flex;
   height: 100%;
   min-height: 0;
+  position: relative;
 
   > .lk-workspace {
     min-width: 0;
   }
 }
 
+// The lab's one shared drawing buffer. Over the trials, because a tile's marks
+// annotate the instrument's own DOM; under the viewport chrome, whose z-overlay
+// outranks it; and inert, because every tile takes input from its own box.
+.lk-lab__surface {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  pointer-events: none;
+}
+
 .lk-shell-footer {
   border-top: 1px solid var(--wzl-border);
   padding: var(--wzl-space-xs) var(--wzl-space-md);

package/src/lab/Workspace.less

@@ -9,3 +9,76 @@
   height: 100%;
   min-height: 0;
 }
+
+// An undocked sidebar section. A tile version is placed by the grid like any
+// trial; the floating version sits above the grid in its own layer.
+.lk-panel-tile {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  overflow: hidden;
+  border: var(--wzl-border-w) solid var(--wzl-line-subtle);
+  border-radius: var(--wzl-radius-sm);
+  background: var(--wzl-surface);
+}
+
+.lk-panel-tile__titlebar {
+  display: flex;
+  align-items: center;
+  gap: var(--wzl-space-sm);
+  flex-shrink: 0;
+  padding: 0 var(--wzl-space-sm);
+  border-bottom: var(--wzl-border-w) solid var(--wzl-line-subtle);
+}
+
+.lk-panel-tile__title {
+  flex: 1;
+  color: var(--wzl-fg-muted);
+  font-family: var(--wzl-font-display);
+  font-size: var(--wzl-font-size-sm);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.lk-panel-tile__dock {
+  border: 0;
+  background: transparent;
+  color: var(--wzl-fg-subtle);
+  cursor: pointer;
+
+  &:hover {
+    color: var(--wzl-fg);
+  }
+}
+
+.lk-panel-tile__body {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+
+.lk-workspace-host {
+  position: relative;
+  width: 100%;
+  height: 100%;
+}
+
+.lk-workspace__floating {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+
+  > * {
+    pointer-events: auto;
+  }
+}
+
+.lk-panel-tile--floating {
+  position: absolute;
+  top: var(--wzl-space-md);
+  right: var(--wzl-space-md);
+  width: 260px;
+  height: auto;
+  max-height: 60%;
+  box-shadow: var(--wzl-shadow-panel, 0 2px 8px rgb(0 0 0 / 0.3));
+}

package/src/lab/Workspace.surface.test.tsx

@@ -10,7 +10,9 @@ function fakeHandle(): SurfaceHandle {
     invalidateAll: vi.fn(),
     invalidateRects: vi.fn(),
     registerTile: vi.fn(),
+    registerPainter: vi.fn(() => () => {}),
     containerRef: vi.fn(),
+    getContainer: vi.fn(() => null),
   };
 }