@weasel-js/labkit 1.7.0 → 1.7.2

package/src/dragdrop/DragGhost.tsx

@@ -2,11 +2,14 @@ import { type ReactPortal, useEffect, useState } from 'react';
 import { createPortal } from 'react-dom';
 import type { PaletteItem, Point } from '../instrument/types';
 
+/** Props for `DragGhost`. `screenPos` is in client pixels. */
 export interface DragGhostProps {
   item: PaletteItem;
   screenPos: Point;
 }
 
+/** The dragged item's label, portaled to `document.body` just below-right of
+ *  `screenPos`. Renders nothing until mounted, so it is SSR-safe. */
 export function DragGhost({ item, screenPos }: DragGhostProps): ReactPortal | null {
   const [mounted, setMounted] = useState(false);
   useEffect(() => setMounted(true), []);

package/src/dragdrop/Palette.tsx

@@ -1,12 +1,14 @@
 import type { PointerEvent as ReactPointerEvent } from 'react';
 import type { PaletteItem } from '../instrument/types';
 
+/** Props for `Palette`. `onDragStart` is usually `useDragDrop`'s `startDrag`. */
 export interface PaletteProps {
   items: PaletteItem[];
   onDragStart: (item: PaletteItem, e: ReactPointerEvent) => void;
   className?: string;
 }
 
+/** One button per item, each starting a drag on pointerdown. */
 export function Palette({ items, onDragStart, className }: PaletteProps) {
   return (
     <div className={className ? `lk-palette ${className}` : 'lk-palette'}>

package/src/dragdrop/dragDrop.test.tsx

@@ -1,4 +1,5 @@
-import { act, fireEvent, render, screen } from '@testing-library/react';
+import { act, fireEvent, screen } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { useContext } from 'react';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { useStore } from 'zustand/react';
@@ -51,8 +52,8 @@ const centredInstrument = defineInstrument<DropState, Record<string, never>>({
   },
 });
 
-function renderLab(probe?: (state: DropState) => void, instrument = testInstrument) {
-  return render(
+async function renderLab(probe?: (state: DropState) => void, instrument = testInstrument) {
+  return renderSettled(
     <Lab instruments={[instrument]} defaultInstrument={instrument.name}>
       {probe ? <StateProbe onState={probe} /> : null}
     </Lab>,
@@ -88,104 +89,104 @@ function pointerDown(el: Element, 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(() => {
+async function dispatchOnDocument(type: string, init: PointerEventInit) {
+  await act(async () => {
     document.dispatchEvent(new PointerEvent(type, { pointerId: 1, bubbles: true, ...init }));
   });
 }
 
-function pointerMove(x: number, y: number) {
-  dispatchOnDocument('pointermove', { buttons: 1, clientX: x, clientY: y });
+async function pointerMove(x: number, y: number) {
+  await dispatchOnDocument('pointermove', { buttons: 1, clientX: x, clientY: y });
 }
 
-function pointerUp(x: number, y: number) {
-  dispatchOnDocument('pointerup', { clientX: x, clientY: y });
+async function pointerUp(x: number, y: number) {
+  await dispatchOnDocument('pointerup', { clientX: x, clientY: y });
 }
 
 describe('DragDrop integration', () => {
-  it('renders palette item in the sidebar', () => {
-    renderLab();
+  it('renders palette item in the sidebar', async () => {
+    await renderLab();
     expect(screen.getByRole('button', { name: 'Item A' })).toBeInTheDocument();
   });
 
-  it('drops an item onto the canvas and appends it to state', () => {
+  it('drops an item onto the canvas and appends it to state', async () => {
     let latest: DropState = { items: [] };
-    renderLab((s) => {
+    await renderLab((s) => {
       latest = s;
     });
     const palette = screen.getByRole('button', { name: 'Item A' });
 
-    act(() => {
+    await act(async () => {
       pointerDown(palette, 0, 0);
     });
-    pointerUp(250, 250);
+    await pointerUp(250, 250);
 
     expect(latest.items).toHaveLength(1);
     expect(latest.items[0]?.id).toBe('a');
   });
 
-  it('drop outside the canvas leaves state unchanged', () => {
+  it('drop outside the canvas leaves state unchanged', async () => {
     let latest: DropState = { items: [] };
-    renderLab((s) => {
+    await renderLab((s) => {
       latest = s;
     });
     const palette = screen.getByRole('button', { name: 'Item A' });
 
-    act(() => {
+    await act(async () => {
       pointerDown(palette, 0, 0);
     });
-    pointerMove(10, 10);
-    pointerUp(10, 10);
+    await pointerMove(10, 10);
+    await pointerUp(10, 10);
 
     expect(latest.items).toHaveLength(0);
     expect(document.querySelector('.lk-drag-ghost')).toBeNull();
   });
 
-  it('shows drag ghost during drag and clears on drop', () => {
-    renderLab();
+  it('shows drag ghost during drag and clears on drop', async () => {
+    await renderLab();
     const palette = screen.getByRole('button', { name: 'Item A' });
 
-    act(() => {
+    await act(async () => {
       pointerDown(palette, 5, 5);
     });
     expect(document.querySelector('.lk-drag-ghost')).not.toBeNull();
 
-    pointerUp(250, 250);
+    await pointerUp(250, 250);
     expect(document.querySelector('.lk-drag-ghost')).toBeNull();
   });
 
-  it('a cancelled gesture drops nothing and clears the ghost', () => {
+  it('a cancelled gesture drops nothing and clears the ghost', async () => {
     let latest: DropState = { items: [] };
-    renderLab((s) => {
+    await renderLab((s) => {
       latest = s;
     });
     const palette = screen.getByRole('button', { name: 'Item A' });
 
-    act(() => {
+    await act(async () => {
       pointerDown(palette, 0, 0);
     });
-    pointerMove(250, 250);
+    await pointerMove(250, 250);
     expect(document.querySelector('.lk-drag-ghost')).not.toBeNull();
 
-    dispatchOnDocument('pointercancel', {});
+    await dispatchOnDocument('pointercancel', {});
 
     expect(latest.items).toHaveLength(0);
     expect(document.querySelector('.lk-drag-ghost')).toBeNull();
   });
 
-  it('drops through the instrument world spec, not the canvas top-left', () => {
+  it('drops through the instrument world spec, not the canvas top-left', async () => {
     let latest: DropState = { items: [] };
-    renderLab((s) => {
+    await renderLab((s) => {
       latest = s;
     }, centredInstrument);
     const palette = screen.getByRole('button', { name: 'Item A' });
 
-    act(() => {
+    await act(async () => {
       pointerDown(palette, 0, 0);
     });
     // 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.
-    pointerUp(350, 250);
+    await pointerUp(350, 250);
 
     expect(latest.items[0]).toMatchObject({ x: 50, y: 50 });
   });

package/src/index.test.ts

@@ -49,6 +49,11 @@ describe('public export surface', () => {
     expect(labkit).toHaveProperty('useTrialState');
     expect(labkit).toHaveProperty('useTrialId');
   });
+
+  it('leaves the loupe to its own entry, so a lab without one does not load it', () => {
+    expect(labkit).not.toHaveProperty('TrialLoupe');
+    expect(labkit).not.toHaveProperty('useLoupe');
+  });
 });
 
 describe('ui re-exports', () => {

package/src/index.ts

@@ -80,6 +80,7 @@ export type {
   AnnotationMeaning,
   AnnotationPatch,
   AnnotationQuery,
+  AnnotationSelectionMode,
   AnnotationStatus,
   AnnotationStoreOptions,
   AnnotationsApi,
@@ -228,6 +229,12 @@ export type {
 export { useConfigSchema } from './config/useConfigSchema';
 export { useResolvedConfig } from './config/useResolvedConfig';
 export { isLeafVisible } from './config/visible';
+export {
+  ControlMatrix,
+  type ControlMatrixColumn,
+  type ControlMatrixProps,
+  type ControlMatrixRow,
+} from './controls/ControlMatrix';
 export { ControlPanel } from './controls/ControlPanel';
 export { type InDialogOptions, inDialog, summarizeValue } from './controls/inDialog';
 export type {
@@ -267,7 +274,6 @@ export * from './job';
 export * from './lab';
 export type { LayerListItem, LayerListProps, LayerMove } from './layers';
 export { LayerList, moveLayers } from './layers';
-export * from './loupe';
 export * from './primitives';
 export { SPECIMEN_SECTIONS, Specimen } from './specimen/Specimen';
 export {

package/src/instrument/types.ts

@@ -6,7 +6,6 @@ import type { TrialContribution } from '../chrome/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';
 
@@ -182,11 +181,6 @@ export interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
    *  is allowed to mean. Declaring it is what makes the trial provide the
    *  annotation overlay and its chrome. */
   annotations?: AnnotationsCapability<TS, TC>;
-  /** Magnification. `true` takes every default and re-draws the instrument's
-   *  canvas layers through a zoomed camera; an instrument whose content is DOM
-   *  gives a `render` that draws it again at a camera it is handed. A function
-   *  is re-read as the config changes, so a setting can drive the lens. */
-  loupe?: LoupeDeclaration<TS, TC> | ((config: TC) => LoupeDeclaration<TS, TC>);
   /** Chrome this instrument contributes beyond what its capabilities imply. */
   chrome?: TrialContribution[];
   /** Work too slow to do during a render. The runtime starts it, aborts it on

package/src/job/useJob.ts

@@ -1,6 +1,9 @@
+import { useLatest } from '@weasel-js/core';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import type { JobCapability, JobFailure, JobHandle, JobStatus } from './types';
 
+/** Inputs to `useJob`. `setState` receives each item folded in by the
+ *  capability's `onItem`. */
 export interface UseJobOptions<TS, TC, TItem> {
   capability: JobCapability<TS, TC, TItem>;
   config: TC;
@@ -23,6 +26,12 @@ function sameKey(a: readonly unknown[] | null, b: readonly unknown[] | null): bo
   return a.length === b.length && a.every((v, i) => Object.is(v, b[i]));
 }
 
+/**
+ * Drive a `JobCapability` and report its progress. `start` cancels any run in
+ * flight and begins again; results from a superseded or canceled run are
+ * dropped. With `auto`, it starts on mount and again whenever `key` changes
+ * element-wise. Unmounting aborts the run.
+ */
 export function useJob<TS, TC, TItem>({
   capability,
   config,
@@ -38,14 +47,10 @@ export function useJob<TS, TC, TItem>({
 
   // Read through refs: `run` is called once per run and must see the values as of
   // that moment rather than re-subscribing on every render.
-  const capRef = useRef(capability);
-  capRef.current = capability;
-  const configRef = useRef(config);
-  configRef.current = config;
-  const stateRef = useRef(state);
-  stateRef.current = state;
-  const setStateRef = useRef(setState);
-  setStateRef.current = setState;
+  const capRef = useLatest(capability);
+  const configRef = useLatest(config);
+  const stateRef = useLatest(state);
+  const setStateRef = useLatest(setState);
 
   const cancel = useCallback(() => {
     token.current += 1;
@@ -96,7 +101,7 @@ export function useJob<TS, TC, TItem>({
         }));
       }
     })();
-  }, []);
+  }, [capRef, configRef, setStateRef, stateRef]);
 
   // Re-run when the declared key changes. `auto` covers the first mount too.
   const lastKey = useRef<readonly unknown[] | null>(null);

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

@@ -1,4 +1,5 @@
 import { render, screen } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { describe, expect, it, vi } from 'vitest';
 import type { TrialContribution } from '../chrome/types';
 import type { Instrument } from '../instrument/types';
@@ -19,23 +20,27 @@ function silenceRenderError(): void {
 }
 
 describe('<Lab> chrome', () => {
-  it('renders a consumer contribution', () => {
+  it('renders a consumer contribution', async () => {
     const extra: TrialContribution = {
       id: 'export',
       region: 'toolbar',
       item: { icon: Glyph, label: 'Export', onActivate: () => {} },
     };
-    render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" chrome={[extra]} />);
+    await renderSettled(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" chrome={[extra]} />,
+    );
     expect(screen.getByRole('button', { name: 'Export' })).toBeInTheDocument();
   });
 
-  it('suppresses a built-in by id', () => {
-    render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" suppress={['snapshot']} />);
+  it('suppresses a built-in by id', async () => {
+    await renderSettled(
+      <Lab title="T" instruments={[bare]} defaultInstrument="Bare" suppress={['snapshot']} />,
+    );
     expect(screen.queryByRole('button', { name: 'Save snapshot' })).toBeNull();
     expect(screen.getByRole('button', { name: 'Clone trial' })).toBeInTheDocument();
   });
 
-  it('throws when a consumer id collides with a built-in', () => {
+  it('throws when a consumer id collides with a built-in', async () => {
     silenceRenderError();
     const clash: TrialContribution = {
       id: 'clone',
@@ -47,24 +52,24 @@ describe('<Lab> chrome', () => {
     ).toThrow(/duplicate contribution id "clone"/);
   });
 
-  it('throws when suppressing an id that is not there', () => {
+  it('throws when suppressing an id that is not there', async () => {
     silenceRenderError();
     expect(() =>
       render(<Lab title="T" instruments={[bare]} defaultInstrument="Bare" suppress={['nope']} />),
     ).toThrow(/cannot suppress "nope"/);
   });
 
-  it('renders an instrument-declared contribution', () => {
+  it('renders an instrument-declared contribution', async () => {
     const withChrome: Instrument = {
       ...bare,
       chrome: [{ id: 'mine', region: 'status', item: { text: 'ready' } }],
     };
-    render(<Lab title="T" instruments={[withChrome]} defaultInstrument="Bare" />);
+    await renderSettled(<Lab title="T" instruments={[withChrome]} defaultInstrument="Bare" />);
     expect(screen.getByText('ready')).toBeInTheDocument();
   });
 
-  it('renders an aside contribution in its own pane, after the workspace', () => {
-    render(
+  it('renders an aside contribution in its own pane, after the workspace', async () => {
+    await renderSettled(
       <Lab
         title="T"
         instruments={[bare]}

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

@@ -1,4 +1,4 @@
-import { render } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { resolveTheme } from '@weasel-js/theme';
 import { describe, expect, it } from 'vitest';
 import type { Instrument } from '../instrument/types';
@@ -18,8 +18,8 @@ const backdrop = (container: HTMLElement) =>
     .find(Boolean) ?? '';
 
 describe('<Lab nebula>', () => {
-  it('draws one blob per literal color', () => {
-    const { container } = render(
+  it('draws one blob per literal color', async () => {
+    const { container } = await renderSettled(
       <Lab
         instruments={[bare]}
         defaultInstrument="Bare"
@@ -30,8 +30,8 @@ describe('<Lab nebula>', () => {
     expect(backdrop(container).match(/radial-gradient/g)).toHaveLength(3);
   });
 
-  it('resolves a theme ramp against the lab’s theme', () => {
-    const { container } = render(
+  it('resolves a theme ramp against the lab’s theme', async () => {
+    const { container } = await renderSettled(
       <Lab instruments={[bare]} defaultInstrument="Bare" mode="dark" nebula={{ ramp: 'swatch' }} />,
     );
     const sky = resolveTheme(interstellarTheme, { mode: 'dark' })['--wzl-swatch-sky'];

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

@@ -7,7 +7,8 @@
  * 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 { act } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import type { ReactNode } from 'react';
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { defineInstrument } from '../instrument/defineInstrument';
@@ -75,16 +76,18 @@ const probeInstrument = defineInstrument<Record<string, never>, Record<string, n
 });
 
 describe('<Lab> surface provider', () => {
-  it('puts a surface handle in reach of an instrument', () => {
+  it('puts a surface handle in reach of an instrument', async () => {
     seen = 'not-rendered';
-    render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
+    await renderSettled(<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('stacks an under and an over buffer inside the lab body', () => {
-    const { container } = render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
+  it('stacks an under and an over buffer inside the lab body', async () => {
+    const { container } = await renderSettled(
+      <Lab instruments={[probeInstrument]} defaultInstrument="Probe" />,
+    );
     const canvases = container.querySelectorAll('.lk-lab__body > canvas.lk-lab__surface');
     expect(canvases).toHaveLength(2);
     // Source order, because the z-index that separates them is in a stylesheet
@@ -96,24 +99,28 @@ describe('<Lab> surface provider', () => {
     ]);
   });
 
-  it('hands a tenant whichever of the two it asks for', () => {
-    const { container } = render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
+  it('hands a tenant whichever of the two it asks for', async () => {
+    const { container } = await renderSettled(
+      <Lab instruments={[probeInstrument]} defaultInstrument="Probe" />,
+    );
     const [underEl, overEl] = [...container.querySelectorAll('canvas.lk-lab__surface')];
     expect(seenCanvases.over).toBe(overEl);
     expect(seenCanvases.under).toBe(underEl);
     expect(overEl).not.toBe(underEl);
   });
 
-  it('defaults a tenant to the buffer over the trials', () => {
+  it('defaults a tenant to the buffer over the trials', async () => {
     // Every tenant predating the split wants the over one: the surface was
     // built for marks that annotate an instrument.
-    const { container } = render(<Lab instruments={[probeInstrument]} defaultInstrument="Probe" />);
+    const { container } = await renderSettled(
+      <Lab instruments={[probeInstrument]} defaultInstrument="Probe" />,
+    );
     const [underEl, overEl] = [...container.querySelectorAll('canvas.lk-lab__surface')];
     expect(seenCanvases.byDefault).toBe(overEl);
     expect(seenCanvases.byDefault).not.toBe(underEl);
   });
 
-  it('mounts no buffer of its own when a host already owns the surface', () => {
+  it('mounts no buffer of its own when a host already owns the surface', async () => {
     function Host({ children }: { children: ReactNode }) {
       const surface = useTiledSurface({ onFrame: () => {} });
       return (
@@ -122,7 +129,7 @@ describe('<Lab> surface provider', () => {
         </SurfaceContext.Provider>
       );
     }
-    const { container } = render(
+    const { container } = await renderSettled(
       <Host>
         <Lab instruments={[probeInstrument]} defaultInstrument="Probe" />
       </Host>,
@@ -130,11 +137,13 @@ describe('<Lab> surface provider', () => {
     expect(container.querySelectorAll('canvas.lk-lab__surface')).toHaveLength(0);
   });
 
-  it('keeps the workspace a direct child of the lab body', () => {
+  it('keeps the workspace a direct child of the lab body', async () => {
     // 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 { container } = await renderSettled(
+      <Lab instruments={[probeInstrument]} defaultInstrument="Probe" />,
+    );
     const body = container.querySelector('.lk-lab__body');
     expect(body).not.toBeNull();
     expect(body?.querySelector(':scope > .lk-workspace')).not.toBeNull();
@@ -155,7 +164,7 @@ describe('<Lab> tile round trip', () => {
     vi.restoreAllMocks();
   });
 
-  it('publishes a rect for a tile an instrument registered', () => {
+  it('publishes a rect for a tile an instrument registered', async () => {
     const frames: SurfaceFrame[] = [];
     let handle: SurfaceHandle | null = null;
 
@@ -177,7 +186,7 @@ describe('<Lab> tile round trip', () => {
       );
     }
 
-    render(
+    await renderSettled(
       <Host>
         <Lab instruments={[probeInstrument]} defaultInstrument="Probe" />
       </Host>,
@@ -189,11 +198,11 @@ describe('<Lab> tile round trip', () => {
     expect(pane).not.toBeNull();
     stubBox(pane, 240, 100, 320, 200);
 
-    act(() => {
+    await act(async () => {
       handle?.invalidateRects();
       handle?.invalidate(paneTileId);
     });
-    act(() => {
+    await act(async () => {
       vi.advanceTimersByTime(64);
     });
 
@@ -208,8 +217,8 @@ describe('<Lab> tile round trip', () => {
 });
 
 describe('<Lab> pages', () => {
-  it("gives the title a way back to the project's other labs", () => {
-    const { getByRole } = render(
+  it("gives the title a way back to the project's other labs", async () => {
+    const { getByRole } = await renderSettled(
       <Lab
         instruments={[probeInstrument]}
         defaultInstrument="Probe"
@@ -225,8 +234,8 @@ describe('<Lab> pages', () => {
     expect(getByRole('button', { name: /kliegsminister/ })).toBeTruthy();
   });
 
-  it('leaves the title a plain heading when there are no other labs', () => {
-    const { getByRole, queryByRole } = render(
+  it('leaves the title a plain heading when there are no other labs', async () => {
+    const { getByRole, queryByRole } = await renderSettled(
       <Lab instruments={[probeInstrument]} defaultInstrument="Probe" title="solo" />,
     );
     expect(getByRole('heading', { name: 'solo' })).toBeTruthy();