@weasel-js/labkit 1.4.1 → 1.4.3

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

@@ -145,25 +145,40 @@ export {
   zoomAt,
 } from './canvas';
 export * from './chrome';
-export { f } from './config/builder';
+export { f, isConfigBranch } from './config/builder';
 export { fromConfigFields } from './config/fromConfigField';
+export {
+  fillConfigDefaults,
+  hasConfigPath,
+  schemaNodeAtPath,
+  valueAtPath,
+  withValueAtPath,
+} from './config/path';
 export { resolveConfigSchema } from './config/resolve';
 export { applyRules, builtinRules, titleCase } from './config/rules';
 export type {
   Annotations,
+  BranchAnnotations,
+  BranchOptions,
+  ConfigBranch,
+  ConfigEntry,
   ConfigNode,
   ConfigOf,
   ConfigOption,
+  ConfigPath,
   ConfigRule,
   ConfigRuleContext,
   ConfigSchema,
+  ConfigShape,
   ControlRenderer,
+  EntryValue,
   InferConfig,
   LeafPatch,
   NodeOptions,
   NodeValue,
   ResolvedConfig,
   SectionSpec,
+  ValueAtPath,
 } from './config/types';
 export { useConfigSchema } from './config/useConfigSchema';
 export { isLeafVisible } from './config/visible';
@@ -202,7 +217,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 +245,7 @@ export type {
   SavedSnapshot,
   SerializedTrial,
   StorageAdapter,
+  TrialInfo,
   TrialRecord,
   TrialStateHandle,
   UndoStack,

package/src/instrument/serializers.ts

@@ -0,0 +1,36 @@
+import type { InstrumentSerializers } from '../state/types';
+import type { InstrumentList } from './types';
+
+/**
+ * Each instrument's default config, keyed by name — what `createLabStore`
+ * fills a stored config's gaps from, so one saved before its schema grew a
+ * branch still loads.
+ */
+export function configDefaultsOf(instruments: InstrumentList): Record<string, () => unknown> {
+  const out: Record<string, () => unknown> = {};
+  for (const instrument of instruments) out[instrument.name] = () => instrument.defaultConfig();
+  return out;
+}
+
+/**
+ * The `serialize` / `deserialize` an instrument list declares, keyed by
+ * instrument name — what `createLabStore` needs to rebuild a trial's state
+ * from storage.
+ *
+ * An instrument declaring neither gets no entry, which is what leaves a
+ * JSON-safe state to pass through untouched.
+ */
+export function serializersOf(instruments: InstrumentList): InstrumentSerializers {
+  const out: InstrumentSerializers = {};
+  for (const instrument of instruments) {
+    const { name, serialize, deserialize } = instrument;
+    if (!serialize && !deserialize) continue;
+    out[name] = {
+      ...(serialize ? { serialize: (state: unknown) => serialize(state) } : {}),
+      ...(deserialize
+        ? { deserialize: (data: unknown, config: unknown) => deserialize(data, config) }
+        : {}),
+    };
+  }
+  return out;
+}

package/src/instrument/types.ts

@@ -2,10 +2,11 @@ import type { ReactNode } from 'react';
 import type { AnnotationsCapability } from '../annotations/types';
 import type { ViewportSize, WorldSpec } from '../canvas/worldSpec';
 import type { TrialContribution } from '../chrome/types';
-import type { ConfigSchema } from '../config/types';
+import type { ConfigPath, 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
@@ -14,12 +15,12 @@ export interface RenderContext<TS = unknown, TC = unknown> {
   state: TS;
   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;
+  /** Write one config value, by dotted path — `'grid.size'` for a leaf under
+   *  an `f.group`, `'cellSize'` for one at the root. */
+  setConfig: (path: ConfigPath<TC>, value: unknown) => void;
+  /** 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/lab/Lab.test.tsx

@@ -1,7 +1,9 @@
 import { act, render, screen } from '@testing-library/react';
 import type { ReactNode } from 'react';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import type { Instrument } from '../instrument/types';
+import { createMemoryAdapter } from '../state/adapters';
+import { labDocumentKey } from '../state/document';
 import { Lab } from './Lab';
 import { LabContext, type LabContextValue } from './LabContext';
 
@@ -52,6 +54,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'));
@@ -128,4 +137,30 @@ describe('<Lab>', () => {
       /Unknown instrument/,
     );
   });
+
+  // The store reads its serializers while it is being built, so `<Lab>` is
+  // the only thing positioned to collect them off the instruments. They went
+  // uncollected for months, and an instrument holding anything JSON drops
+  // lost it with no error.
+  it('gives the store the serializers its instruments declare', () => {
+    vi.useFakeTimers();
+    const storage = createMemoryAdapter();
+    const mapped: Instrument = {
+      ...stub,
+      name: 'Mapped',
+      initialState: () => ({ seen: new Set(['a']) }),
+      serialize: (state) => ({ seen: [...(state as { seen: Set<string> }).seen] }),
+      deserialize: (data) => ({ seen: new Set((data as { seen: string[] }).seen) }),
+    };
+
+    render(
+      <Lab instruments={[mapped]} defaultInstrument="Mapped" storage={storage} storageKey="s" />,
+    );
+    act(() => vi.advanceTimersByTime(500));
+    expect(storage.read(labDocumentKey('s')) ?? '').toContain('"seen":["a"]');
+    vi.useRealTimers();
+
+    mountLab({ instruments: [mapped], defaultInstrument: 'Mapped', storage, storageKey: 's' });
+    expect((labRef?.trials[0]?.state as { seen: Set<string> }).seen).toEqual(new Set(['a']));
+  });
 });

package/src/lab/Lab.tsx

@@ -11,6 +11,7 @@ import {
 import { useStore } from 'zustand/react';
 import type { TrialContribution } from '../chrome/types';
 import type { ConfigRule, ControlRenderer } from '../config/types';
+import { configDefaultsOf, serializersOf } from '../instrument/serializers';
 import type { InstrumentList } from '../instrument/types';
 import { noneAdapter } from '../state/adapters';
 import { LabStoreContext } from '../state/context';
@@ -78,7 +79,15 @@ function buildStore(
   storageKey: string,
   initialMode: LabMode,
 ): LabStore {
-  const store = createLabStore({ storageKey, storage, initialMode });
+  // Hydration reads the serializers, so they go in with the store rather than
+  // being registered onto it afterwards.
+  const store = createLabStore({
+    storageKey,
+    storage,
+    initialMode,
+    serializers: serializersOf(instruments),
+    configDefaults: configDefaultsOf(instruments),
+  });
   if (store.getState().trials.length === 0) {
     const seeded = addTrialOp([], instruments, defaultInstrument);
     const record = seeded[0];
@@ -220,8 +229,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/LabShell.test.tsx

@@ -39,6 +39,14 @@ describe('LabShell', () => {
     expect(root.getAttribute('data-wzl-mode')).toMatch(/^(light|dark)$/);
   });
 
+  // The overlays weasel-ui ships default to the nearest portal host, and
+  // `.lk-root` is where labkit's element defaults live — not the themed
+  // wrapper above it.
+  test('marks lk-root as the portal host for overlays', () => {
+    const { container } = render(<LabShell title="t">x</LabShell>);
+    expect(container.querySelector('.lk-root')?.hasAttribute('data-wzl-portal-host')).toBe(true);
+  });
+
   test('always applies lk-root class', () => {
     const { container } = render(<LabShell title="t">x</LabShell>);
     expect(container.querySelector('.lk-root')).not.toBeNull();

package/src/lab/LabShell.tsx

@@ -24,7 +24,9 @@ export function LabShell({ title, children, header, footer, mode = 'auto' }: Lab
   const outer = useThemeOptional();
 
   const shell = (
-    <div className="lk-root lk-shell">
+    // Overlays portal here rather than to the themed wrapper above: `.lk-root`
+    // carries the element defaults a lab's bare markup is styled by.
+    <div className="lk-root lk-shell" data-wzl-portal-host="">
       <header className="lk-shell-header">
         <h1 className="lk-shell-title">{title}</h1>
         {header && <div className="lk-shell-header-actions">{header}</div>}