@weasel-js/labkit 1.4.0 → 1.4.2

package/src/dragdrop/DragDropRuntime.tsx

@@ -1,5 +1,12 @@
-import { useVisibleRaf } from '@weasel-js/core';
-import { type RefObject, useCallback, useEffect, useRef, useState } from 'react';
+import { openPointerSession, type PointerSession, useVisibleRaf } from '@weasel-js/core';
+import {
+  type PointerEvent as ReactPointerEvent,
+  type RefObject,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
 import { screenToWorld } from '../canvas/canvasCoords';
 import { resolveFrame, type WorldSpec } from '../canvas/worldSpec';
 import type {
@@ -32,7 +39,7 @@ export interface UseDragDropArgs<TS, TC> {
 
 export interface UseDragDropResult {
   drag: DragState | null;
-  startDrag: (item: PaletteItem, originScreenPos: Point) => void;
+  startDrag: (item: PaletteItem, e: ReactPointerEvent) => void;
 }
 
 export function useDragDrop<TS, TC>({
@@ -51,6 +58,12 @@ export function useDragDrop<TS, TC>({
   /** The move the next frame will resolve. Doubles as the throttle's flag:
    *  non-null means a frame is already queued. */
   const pendingPos = useRef<Point | null>(null);
+  const sessionRef = useRef<PointerSession | null>(null);
+
+  /** A session keeps the closure it was opened with, so everything the drop
+   *  reads has to come from here rather than from that closure. */
+  const liveRef = useRef({ capability, state, config, setState, emit, view, worldSpec });
+  liveRef.current = { capability, state, config, setState, emit, view, worldSpec };
 
   const isOverCanvas = useCallback(
     (screenPos: Point): boolean => {
@@ -72,10 +85,14 @@ export function useDragDrop<TS, TC>({
       const el = canvasContainerRef.current;
       if (!el) return null;
       const r = el.getBoundingClientRect();
-      const frame = resolveFrame(worldSpec, { width: r.width, height: r.height });
-      return screenToWorld({ x: screenPos.x - r.left, y: screenPos.y - r.top }, view, frame);
+      const frame = resolveFrame(liveRef.current.worldSpec, { width: r.width, height: r.height });
+      return screenToWorld(
+        { x: screenPos.x - r.left, y: screenPos.y - r.top },
+        liveRef.current.view,
+        frame,
+      );
     },
-    [canvasContainerRef, view, worldSpec],
+    [canvasContainerRef],
   );
 
   const frameLoop = useVisibleRaf(() => {
@@ -83,68 +100,64 @@ export function useDragDrop<TS, TC>({
     pendingPos.current = null;
     const active = dragRef.current;
     if (!active || !screenPos) return;
+    const live = liveRef.current;
     let feedback: DragFeedback | null = null;
-    if (capability.onDragOver && isOverCanvas(screenPos)) {
+    if (live.capability.onDragOver && isOverCanvas(screenPos)) {
       const world = screenToWorldFromContainer(screenPos);
-      if (world) feedback = capability.onDragOver(world, active.item, state, config);
+      if (world) feedback = live.capability.onDragOver(world, active.item, live.state, live.config);
     }
     setDrag({ ...active, screenPos, feedback });
   });
 
-  useEffect(() => {
-    if (!drag) return;
-    const handleMove = (e: PointerEvent) => {
-      const screenPos = { x: e.clientX, y: e.clientY };
-      const current = dragRef.current;
-      if (!current) return;
-      if (pendingPos.current !== null) {
-        // A frame is already queued: keep the ghost under the cursor and let
-        // that frame probe the drop target from the newest position.
-        pendingPos.current = screenPos;
-        dragRef.current = { ...current, screenPos };
-        setDrag(dragRef.current);
-        return;
-      }
-      pendingPos.current = screenPos;
-      frameLoop.request();
-    };
-    const handleUp = (e: PointerEvent) => {
-      const screenPos = { x: e.clientX, y: e.clientY };
-      const active = dragRef.current;
-      if (!active) return;
-      pendingPos.current = null;
-      frameLoop.cancel();
-      if (isOverCanvas(screenPos)) {
-        const world = screenToWorldFromContainer(screenPos);
-        if (world) {
-          const nextState = capability.onDrop(world, active.item, state, config);
-          setState(nextState);
-          emit('canvas.itemAdded');
-        }
-      }
-      setDrag(null);
-    };
-    window.addEventListener('pointermove', handleMove);
-    window.addEventListener('pointerup', handleUp);
-    return () => {
-      window.removeEventListener('pointermove', handleMove);
-      window.removeEventListener('pointerup', handleUp);
-    };
-  }, [
-    drag,
-    capability,
-    state,
-    config,
-    setState,
-    emit,
-    frameLoop,
-    isOverCanvas,
-    screenToWorldFromContainer,
-  ]);
+  const clearDrag = useCallback(() => {
+    pendingPos.current = null;
+    frameLoop.cancel();
+    sessionRef.current = null;
+    dragRef.current = null;
+    setDrag(null);
+  }, [frameLoop]);
+
+  const startDrag = useCallback(
+    (item: PaletteItem, e: ReactPointerEvent) => {
+      if (sessionRef.current) return;
+      const next: DragState = { item, screenPos: { x: e.clientX, y: e.clientY }, feedback: null };
+      dragRef.current = next;
+      setDrag(next);
+      sessionRef.current = openPointerSession(e.currentTarget, e, {
+        onMove: (ev) => {
+          const screenPos = { x: ev.clientX, y: ev.clientY };
+          const current = dragRef.current;
+          if (!current) return;
+          if (pendingPos.current !== null) {
+            // A frame is already queued: keep the ghost under the cursor and
+            // let that frame probe the drop target from the newest position.
+            pendingPos.current = screenPos;
+            dragRef.current = { ...current, screenPos };
+            setDrag(dragRef.current);
+            return;
+          }
+          pendingPos.current = screenPos;
+          frameLoop.request();
+        },
+        onEnd: (ev) => {
+          const screenPos = { x: ev.clientX, y: ev.clientY };
+          const active = dragRef.current;
+          clearDrag();
+          if (!active || !isOverCanvas(screenPos)) return;
+          const world = screenToWorldFromContainer(screenPos);
+          if (!world) return;
+          const live = liveRef.current;
+          live.setState(live.capability.onDrop(world, active.item, live.state, live.config));
+          live.emit('canvas.itemAdded');
+        },
+        // An interrupted gesture never named a destination, so it drops nothing.
+        onCancel: clearDrag,
+      });
+    },
+    [clearDrag, frameLoop, isOverCanvas, screenToWorldFromContainer],
+  );
 
-  const startDrag = useCallback((item: PaletteItem, originScreenPos: Point) => {
-    setDrag({ item, screenPos: originScreenPos, feedback: null });
-  }, []);
+  useEffect(() => () => sessionRef.current?.cancel(), []);
 
   return { drag, startDrag };
 }

package/src/dragdrop/Palette.tsx

@@ -1,8 +1,9 @@
-import type { PaletteItem, Point } from '../instrument/types';
+import type { PointerEvent as ReactPointerEvent } from 'react';
+import type { PaletteItem } from '../instrument/types';
 
 export interface PaletteProps {
   items: PaletteItem[];
-  onDragStart: (item: PaletteItem, originScreenPos: Point) => void;
+  onDragStart: (item: PaletteItem, e: ReactPointerEvent) => void;
   className?: string;
 }
 
@@ -16,7 +17,7 @@ export function Palette({ items, onDragStart, className }: PaletteProps) {
           className="lk-palette__item"
           onPointerDown={(e) => {
             e.preventDefault();
-            onDragStart(item, { x: e.clientX, y: e.clientY });
+            onDragStart(item, e);
           }}
         >
           <span className="lk-palette__label">{item.label}</span>

package/src/dragdrop/dragDrop.test.tsx

@@ -83,19 +83,23 @@ afterEach(() => {
 });
 
 function pointerDown(el: Element, x: number, y: number) {
-  fireEvent.pointerDown(el, { clientX: x, clientY: y });
+  fireEvent.pointerDown(el, { pointerId: 1, buttons: 1, clientX: x, clientY: y });
 }
 
-function windowPointerMove(x: number, y: number) {
+/** The session listens on the document, so that is where the rest of the
+ *  gesture has to arrive — a dispatch on `window` reaches nothing. */
+function dispatchOnDocument(type: string, init: PointerEventInit) {
   act(() => {
-    window.dispatchEvent(new MouseEvent('pointermove', { clientX: x, clientY: y, bubbles: true }));
+    document.dispatchEvent(new PointerEvent(type, { pointerId: 1, bubbles: true, ...init }));
   });
 }
 
-function windowPointerUp(x: number, y: number) {
-  act(() => {
-    window.dispatchEvent(new MouseEvent('pointerup', { clientX: x, clientY: y, bubbles: true }));
-  });
+function pointerMove(x: number, y: number) {
+  dispatchOnDocument('pointermove', { buttons: 1, clientX: x, clientY: y });
+}
+
+function pointerUp(x: number, y: number) {
+  dispatchOnDocument('pointerup', { clientX: x, clientY: y });
 }
 
 describe('DragDrop integration', () => {
@@ -114,7 +118,7 @@ describe('DragDrop integration', () => {
     act(() => {
       pointerDown(palette, 0, 0);
     });
-    windowPointerUp(250, 250);
+    pointerUp(250, 250);
 
     expect(latest.items).toHaveLength(1);
     expect(latest.items[0]?.id).toBe('a');
@@ -130,8 +134,8 @@ describe('DragDrop integration', () => {
     act(() => {
       pointerDown(palette, 0, 0);
     });
-    windowPointerMove(10, 10);
-    windowPointerUp(10, 10);
+    pointerMove(10, 10);
+    pointerUp(10, 10);
 
     expect(latest.items).toHaveLength(0);
     expect(document.querySelector('.lk-drag-ghost')).toBeNull();
@@ -146,7 +150,26 @@ describe('DragDrop integration', () => {
     });
     expect(document.querySelector('.lk-drag-ghost')).not.toBeNull();
 
-    windowPointerUp(250, 250);
+    pointerUp(250, 250);
+    expect(document.querySelector('.lk-drag-ghost')).toBeNull();
+  });
+
+  it('a cancelled gesture drops nothing and clears the ghost', () => {
+    let latest: DropState = { items: [] };
+    renderLab((s) => {
+      latest = s;
+    });
+    const palette = screen.getByRole('button', { name: 'Item A' });
+
+    act(() => {
+      pointerDown(palette, 0, 0);
+    });
+    pointerMove(250, 250);
+    expect(document.querySelector('.lk-drag-ghost')).not.toBeNull();
+
+    dispatchOnDocument('pointercancel', {});
+
+    expect(latest.items).toHaveLength(0);
     expect(document.querySelector('.lk-drag-ghost')).toBeNull();
   });
 
@@ -162,7 +185,7 @@ describe('DragDrop integration', () => {
     });
     // The host spans (100,100)-(500,500), so its centre is at (300,300).
     // Dropping 50px right of centre and 50px above it, at zoom 1, y up.
-    windowPointerUp(350, 250);
+    pointerUp(350, 250);
 
     expect(latest.items[0]).toMatchObject({ x: 50, y: 50 });
   });

package/src/index.ts

@@ -202,7 +202,7 @@ export type { ValidationResult } from './instrument/validateConfigSchema';
 export { validateConfigSchema } from './instrument/validateConfigSchema';
 export * from './job';
 export * from './lab';
-export type { LayerListProps } from './layers';
+export type { LayerListProps, LayerTreeNode } from './layers';
 export { LayerList } from './layers';
 export * from './loupe';
 export * from './primitives';
@@ -230,6 +230,7 @@ export type {
   SavedSnapshot,
   SerializedTrial,
   StorageAdapter,
+  TrialInfo,
   TrialRecord,
   TrialStateHandle,
   UndoStack,

package/src/instrument/types.ts

@@ -6,6 +6,7 @@ import type { ConfigSchema } from '../config/types';
 import type { ConfigField } from '../controls/types';
 import type { JobCapability, JobHandle } from '../job/types';
 import type { LoupeDeclaration } from '../loupe/types';
+import type { TrialInfo } from '../state/types';
 import type { ToolCapability } from '../tools/types';
 
 /** What an instrument's `render` is handed: its state and config, the setters
@@ -15,11 +16,9 @@ export interface RenderContext<TS = unknown, TC = unknown> {
   config: TC;
   setState: (next: TS | ((prev: TS) => TS)) => void;
   setConfig: (key: keyof TC, value: unknown) => void;
-  trial: {
-    id: string;
-    /** The trial's view, in whatever shape this instrument chose. labkit persists
-     *  it and restores it on Reset without ever reading into it. */
-    view: unknown;
+  /** labkit persists `view` and restores it on Reset without ever reading
+   *  into it. */
+  trial: TrialInfo & {
     setView: (next: unknown) => void;
     /** 2D convenience over `view`. Reads 1 and writes nothing when the trial holds
      *  a view that is not the 2D one. */

package/src/job/useJob.ts

@@ -111,7 +111,7 @@ export function useJob<TS, TC, TItem>({
     lastKey.current = key;
     started.current = true;
     start();
-  }, [auto, key, start]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [auto, key, start]);
 
   useEffect(
     () => () => {

package/src/lab/Lab.test.tsx

@@ -52,6 +52,13 @@ describe('<Lab>', () => {
     expect(screen.getAllByRole('region', { name: /trial/i })).toHaveLength(2);
   });
 
+  it('addTrial opens each trial on the config it was given', () => {
+    mountLab();
+    act(() => labRef?.addTrial('Stub', { config: { count: 7 } }));
+    expect(labRef?.trials.map((t) => (t.config as { count: number }).count)).toEqual([0, 7]);
+    expect(labRef?.trials.map((t) => (t.state as { value: number }).value)).toEqual([0, 7]);
+  });
+
   it('closeTrial removes one when more than one exists', () => {
     mountLab();
     act(() => labRef?.addTrial('Stub'));

package/src/lab/Lab.tsx

@@ -220,8 +220,8 @@ export function Lab({
     return {
       instruments,
       trials,
-      addTrial: (instrumentName) => {
-        const next = addTrialOp(store.getState().trials, instruments, instrumentName);
+      addTrial: (instrumentName, options) => {
+        const next = addTrialOp(store.getState().trials, instruments, instrumentName, options);
         replaceTrials(next);
       },
       cloneTrial: (id) => {

package/src/lab/LabContext.ts

@@ -2,6 +2,7 @@ import { createContext, useContext } from 'react';
 import type { ConfigRule, ControlRenderer } from '../config/types';
 import type { InstrumentList } from '../instrument/types';
 import type { LabMode, SavedSnapshot, TrialRecord } from '../state/types';
+import type { AddTrialOptions } from '../trial/trialOps';
 
 /** Lab-wide state and commands: the available instruments, the open
  *  trials and the operations over them, saved snapshots, and the color
@@ -9,7 +10,10 @@ import type { LabMode, SavedSnapshot, TrialRecord } from '../state/types';
 export interface LabContextValue {
   instruments: InstrumentList;
   trials: TrialRecord[];
-  addTrial: (instrumentName: string) => void;
+  /** Open a trial running `instrumentName`. `options.config` is written over
+   *  that instrument's defaults, which is where a trial opened on a subject
+   *  says which subject. */
+  addTrial: (instrumentName: string, options?: AddTrialOptions) => void;
   cloneTrial: (id: string) => void;
   closeTrial: (id: string) => void;
   resetTrial: (id: string) => void;

package/src/lab/LabShell.less

@@ -14,7 +14,10 @@
 
 .lk-shell-header {
   display: flex;
-  align-items: center;
+  // Baseline, not center: the title is `--wzl-font-size-xl` and the controls
+  // beside it are not, so centering them leaves every label sitting off the
+  // title's baseline by half the difference in leading.
+  align-items: baseline;
   gap: var(--wzl-space-md);
   padding: var(--wzl-space-sm) var(--wzl-space-md);
   background: var(--wzl-surface-raised);
@@ -32,6 +35,9 @@
 .lk-shell-header-actions {
   margin-left: auto;
   display: flex;
+  // A flex container reports its first item's baseline, so this is what
+  // carries the row's baseline up to the header.
+  align-items: baseline;
   gap: var(--wzl-space-sm);
 }
 
@@ -73,12 +79,21 @@
   font-size: var(--wzl-font-size-sm);
 }
 
+// A flex container reports its *first* item's baseline, and the leading icon
+// is an <svg> with none — so a centered button hands the header a baseline
+// synthesized from the icon's bottom edge, and the label lands 2px off the
+// title. Baseline here makes the label the button's baseline; the icon keeps
+// its own centering through `align-self`.
 .lk-lab-header__add {
   display: inline-flex;
-  align-items: center;
+  align-items: baseline;
   gap: var(--wzl-space-xs);
 }
 
+.lk-lab-header__add > svg {
+  align-self: center;
+}
+
 // `Select` is a form field and defaults to `width: 100%`. Left to resolve that
 // against a shrink-to-fit header row it swallows the slack, which pushed the
 // consumer's own header content down to min-content and wrapped the row to

package/src/lab/Workspace.tsx

@@ -210,7 +210,7 @@ export function Workspace({
     if (!surface) return;
     surface.invalidateRects();
     return store.events.on('node.placementChanged', () => surface.invalidateRects());
-  }, [store, surface, nodeIds]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [store, surface, nodeIds]);
 
   useEffect(() => {
     if (!onLayoutChange) return;

package/src/layers/AGENTS.md

@@ -6,22 +6,26 @@ The `src/layers/` directory implements the `<LayerList>` UI used by the `layers`
 
 | File | Role |
 |---|---|
-| `LayerList.tsx` | Layer toggle/reorder list (sidebar widget) |
-| `LayerList.less` | Row styling, drag handle, pinned-row variant |
+| `LayerList.tsx` | Layer toggle/reorder list, flat or nested (sidebar widget) |
+| `LayerList.less` | Row styling, drag handle, pinned-row variant, subtree indent |
+| `LayerList.stories.tsx` | Flat and nested renderings |
 
 ## Props
 
 ```ts
 interface LayerListProps {
-  layers: LayerDescriptor[];                    // { id, label, alwaysOn? }
+  layers: LayerTreeNode[];                      // LayerDescriptor + { children?, defaultCollapsed? }
   visibility: Record<string, boolean>;          // missing key → visible
-  onReorder: (newOrder: LayerDescriptor[]) => void;
+  onReorder: (newOrder: LayerTreeNode[]) => void;
   onToggle: (id: string, visible: boolean) => void;
+  collapsedIds?: readonly string[];             // supplying it makes collapse controlled
+  onCollapsedChange?: (ids: string[]) => void;
   className?: string;
 }
 ```
 
-`LayerDescriptor` lives in `src/instrument/types.ts`.
+`LayerDescriptor` lives in `src/instrument/types.ts`; `LayerTreeNode` extends it
+in `LayerList.tsx`, so a plain `LayerDescriptor[]` is still a valid `layers`.
 
 ## How it integrates
 
@@ -44,6 +48,24 @@ Setting `alwaysOn: true` on a `LayerDescriptor` does two things:
 
 This is intended for legend/HUD layers that should never be toggled off. Visibility for pinned rows is **not** read from the `visibility` prop; they always render.
 
+## Nesting
+
+A node with `children` renders an expandable subtree. The expand control is
+`<Disclosure>` from `@weasel-js/ui` — the same twisty every other collapsible
+surface uses.
+
+Reordering is scoped to siblings: a drag moves a row within its own parent's
+child list and never reparents it. `onReorder` still receives the whole tree,
+with only that sibling group's order changed.
+
+The twisty column appears only when some node in the tree has children — a flat
+list renders exactly the rows it always did. Within a tree, childless rows get
+`.lk-layer-list__twisty-gap` so labels stay aligned down a level.
+
+Collapse is uncontrolled by default, seeded once from each node's
+`defaultCollapsed`. Pass `collapsedIds` to own it; `onCollapsedChange` fires
+either way.
+
 ## Drag handle customization
 
 The drag handle is a button with class `lk-layer-list__handle` holding `<DragHandleGlyph>` (from `@weasel-js/ui`), the same grip `LayerStack` uses. Its padding is transparent and cancelled by an equal negative margin, so the grab target is larger than the drawn dots without widening the row. Row pitch — height plus row gap — is measured from the DOM when a drag starts, so restyling the row does not skew drag distance. It used to be a hardcoded `28`, which had already drifted from the rendered height by the time it was found.
@@ -59,7 +81,7 @@ If `layers.length === 0`, renders `.lk-layer-list__empty` with the text "No laye
 Fork this component if you need:
 - Multi-select reorder (current implementation is single-row)
 - Right-click context menu
-- Layer groups or nesting
+- Reparenting by drag (nesting renders, but a drag stays within one parent)
 - Solo/mute UI common in DAW-style apps
 
-The implementation is small (~100 lines) and self-contained — only depends on `LayerDescriptor` from instrument types.
+It is self-contained: `LayerDescriptor` from instrument types and `Disclosure`/`DragHandleGlyph` from `@weasel-js/ui`.

package/src/layers/LayerList.less

@@ -75,3 +75,19 @@
 .lk-layer-list input[type='checkbox'] {
   accent-color: var(--wzl-accent);
 }
+
+.lk-layer-list__children {
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+  // Indents by the twisty column, so a child's own twisty starts where its
+  // parent's label does.
+  padding-left: var(--wzl-space-md);
+}
+
+// Holds the twisty column open on rows that have nothing to expand, so labels
+// line up down the level.
+.lk-layer-list__twisty-gap {
+  flex: 0 0 auto;
+  width: var(--wzl-disclosure-target, 20px);
+}

package/src/layers/LayerList.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { LayerList, type LayerTreeNode } from './LayerList';
+
+const meta: Meta<typeof LayerList> = {
+  title: 'labkit/layers/LayerList',
+  component: LayerList,
+};
+export default meta;
+type Story = StoryObj<typeof LayerList>;
+
+const FLAT: LayerTreeNode[] = [
+  { id: 'plants', label: 'Plants' },
+  { id: 'grid', label: 'Grid' },
+  { id: 'legend', label: 'Legend', alwaysOn: true },
+];
+
+const NESTED: LayerTreeNode[] = [
+  {
+    id: 'ingest',
+    label: 'Ingest',
+    children: [
+      { id: 'ingest.fetch', label: 'Fetch' },
+      { id: 'ingest.parse', label: 'Parse' },
+    ],
+  },
+  {
+    id: 'solve',
+    label: 'Solve',
+    defaultCollapsed: true,
+    children: [
+      { id: 'solve.seed', label: 'Seed' },
+      {
+        id: 'solve.relax',
+        label: 'Relax',
+        children: [
+          { id: 'solve.relax.sweep', label: 'Sweep' },
+          { id: 'solve.relax.check', label: 'Check' },
+        ],
+      },
+    ],
+  },
+  { id: 'report', label: 'Report', alwaysOn: true },
+];
+
+function Demo({ seed }: { seed: LayerTreeNode[] }) {
+  const [layers, setLayers] = useState(seed);
+  const [visibility, setVisibility] = useState<Record<string, boolean>>({});
+  return (
+    <div style={{ width: 220 }}>
+      <LayerList
+        layers={layers}
+        visibility={visibility}
+        onReorder={setLayers}
+        onToggle={(id, visible) => setVisibility((v) => ({ ...v, [id]: visible }))}
+      />
+    </div>
+  );
+}
+
+/** No node has children, so no row spends width on a twisty column. */
+export const Flat: Story = { render: () => <Demo seed={FLAT} /> };
+
+/** Dragging a row reorders it among its own siblings — a drag never moves a
+ *  layer to a different parent. */
+export const Tree: Story = { render: () => <Demo seed={NESTED} /> };