@weasel-js/labkit 1.7.0 → 1.7.2

package/src/trial/Trial.loupe.test.tsx

@@ -1,8 +1,10 @@
-import { act, fireEvent, render, screen } from '@testing-library/react';
+import { act, fireEvent, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { beforeAll, describe, expect, it, vi } from 'vitest';
 import { defineInstrument } from '../instrument/defineInstrument';
 import { Lab } from '../lab/Lab';
+import { TrialLoupe } from '../loupe';
 
 beforeAll(() => {
   HTMLCanvasElement.prototype.getContext = vi.fn(() => ({
@@ -21,17 +23,19 @@ const canvasInstrument = defineInstrument<Record<string, never>, Record<string,
   name: 'Drawn',
   defaultConfig: () => ({}),
   initialState: () => ({}),
-  render: () => null,
+  render: () => <TrialLoupe />,
   canvas: { layers: [{ id: 'main', draw: () => undefined }] },
-  loupe: true,
 });
 
 const domInstrument = defineInstrument<Record<string, never>, Record<string, never>>({
   name: 'Written',
   defaultConfig: () => ({}),
   initialState: () => ({}),
-  render: () => <p data-testid="body">the content</p>,
-  loupe: { render: ({ view }) => <p data-testid="lens-body">zoom {view.zoom}</p> },
+  render: () => (
+    <TrialLoupe render={({ view }) => <p data-testid="lens-body">zoom {view.zoom}</p>}>
+      <p data-testid="body">the content</p>
+    </TrialLoupe>
+  ),
 });
 
 const noLoupe = defineInstrument<Record<string, never>, Record<string, never>>({
@@ -49,28 +53,30 @@ function pointAt(host: Element, x: number, y: number): void {
   fireEvent.pointerMove(host, { clientX: x, clientY: y });
 }
 
-describe('the loupe capability', () => {
-  it('gives a trial a toolbar toggle, and no lens until it is on', () => {
-    const { container } = render(
+describe('a lens the instrument mounts', () => {
+  it('gives a trial a toolbar toggle, and no lens until it is on', async () => {
+    const { container } = await renderSettled(
       <Lab instruments={[canvasInstrument]} defaultInstrument="Drawn" />,
     );
     expect(screen.getByRole('button', { name: 'Loupe' })).toHaveAttribute('aria-pressed', 'false');
     expect(lens(container)).toBeNull();
   });
 
-  it('offers nothing to an instrument that declares none', () => {
-    render(<Lab instruments={[noLoupe]} defaultInstrument="Plain" />);
+  it('offers nothing to an instrument that mounts none', async () => {
+    await renderSettled(<Lab instruments={[noLoupe]} defaultInstrument="Plain" />);
     expect(screen.queryByRole('button', { name: 'Loupe' })).toBeNull();
   });
 
-  it('drops out of a trial that suppresses it', () => {
-    render(<Lab instruments={[canvasInstrument]} defaultInstrument="Drawn" suppress={['loupe']} />);
+  it('drops out of a trial that suppresses it', async () => {
+    await renderSettled(
+      <Lab instruments={[canvasInstrument]} defaultInstrument="Drawn" suppress={['loupe']} />,
+    );
     expect(screen.queryByRole('button', { name: 'Loupe' })).toBeNull();
   });
 
   it('raises the lens over a canvas stack once it is on and aimed', async () => {
     const user = userEvent.setup();
-    const { container } = render(
+    const { container } = await renderSettled(
       <Lab instruments={[canvasInstrument]} defaultInstrument="Drawn" />,
     );
     await user.click(screen.getByRole('button', { name: 'Loupe' }));
@@ -92,10 +98,12 @@ describe('the loupe capability', () => {
 
   it('asks a DOM instrument to draw itself again at the magnified camera', async () => {
     const user = userEvent.setup();
-    const { container } = render(<Lab instruments={[domInstrument]} defaultInstrument="Written" />);
+    const { container } = await renderSettled(
+      <Lab instruments={[domInstrument]} defaultInstrument="Written" />,
+    );
     await user.click(screen.getByRole('button', { name: 'Loupe' }));
 
-    const host = container.querySelector('.lk-trial__loupe-host');
+    const host = container.querySelector('.lk-loupe-host');
     if (!host) throw new Error('no loupe host');
     pointAt(host, 60, 40);
 
@@ -105,14 +113,33 @@ describe('the loupe capability', () => {
     expect(screen.getByTestId('body')).toBeInTheDocument();
   });
 
-  it('wraps a DOM instrument only when it declares a loupe', () => {
-    const { container } = render(<Lab instruments={[noLoupe]} defaultInstrument="Plain" />);
-    expect(container.querySelector('.lk-trial__loupe-host')).toBeNull();
+  it('wraps nothing for an instrument that mounts no lens', async () => {
+    const { container } = await renderSettled(
+      <Lab instruments={[noLoupe]} defaultInstrument="Plain" />,
+    );
+    expect(container.querySelector('.lk-loupe-host')).toBeNull();
+  });
+
+  it('raises a lens told `enabled` without the trial toggle', async () => {
+    const always = defineInstrument<Record<string, never>, Record<string, never>>({
+      name: 'Always',
+      defaultConfig: () => ({}),
+      initialState: () => ({}),
+      render: () => <TrialLoupe enabled />,
+      canvas: { layers: [{ id: 'main', draw: () => undefined }] },
+    });
+    const { container } = await renderSettled(
+      <Lab instruments={[always]} defaultInstrument="Always" />,
+    );
+    const stack = container.querySelector('.lk-canvas-stack');
+    if (!stack) throw new Error('no canvas stack');
+    pointAt(stack, 60, 40);
+    expect(lens(container)).not.toBeNull();
   });
 
   it('puts the lens away again when the toggle goes off', async () => {
     const user = userEvent.setup();
-    const { container } = render(
+    const { container } = await renderSettled(
       <Lab instruments={[canvasInstrument]} defaultInstrument="Drawn" />,
     );
     const toggle = screen.getByRole('button', { name: 'Loupe' });
@@ -130,13 +157,13 @@ describe('the loupe capability', () => {
 describe('the loupe and the trial camera share one dispatcher', () => {
   const frame = () => new Promise<void>((r) => requestAnimationFrame(() => r()));
 
-  function mountDrawn() {
+  async function mountDrawn() {
     const zooms: number[] = [];
     const drawn = defineInstrument<Record<string, never>, Record<string, never>>({
       name: 'Zoomed',
       defaultConfig: () => ({}),
       initialState: () => ({}),
-      render: () => null,
+      render: () => <TrialLoupe />,
       canvas: {
         layers: [
           {
@@ -147,9 +174,8 @@ describe('the loupe and the trial camera share one dispatcher', () => {
           },
         ],
       },
-      loupe: true,
     });
-    const r = render(<Lab instruments={[drawn]} defaultInstrument="Zoomed" />);
+    const r = await renderSettled(<Lab instruments={[drawn]} defaultInstrument="Zoomed" />);
     const stack = r.container.querySelector('.lk-canvas-stack');
     if (!stack) throw new Error('no canvas stack');
     return { ...r, stack, zooms };
@@ -168,7 +194,7 @@ describe('the loupe and the trial camera share one dispatcher', () => {
   };
 
   it('zooms the camera while the lens is down', async () => {
-    const h = mountDrawn();
+    const h = await mountDrawn();
     await act(async () => {
       await frame();
     });
@@ -181,7 +207,7 @@ describe('the loupe and the trial camera share one dispatcher', () => {
 
   it('gives the wheel to the lens while it is up, and leaves the camera alone', async () => {
     const user = userEvent.setup();
-    const h = mountDrawn();
+    const h = await mountDrawn();
     await user.click(screen.getByRole('button', { name: 'Loupe' }));
     pointAt(h.stack, 60, 40);
     expect(lens(h.container)).not.toBeNull();

package/src/trial/Trial.targets.test.tsx

@@ -4,7 +4,8 @@
  * trial open, a `targets` that ignored the trial it was asked about would look
  * identical.
  */
-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 { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { AnnotationTarget } from '../annotations/types';
 import { defineInstrument } from '../instrument/defineInstrument';
@@ -63,13 +64,13 @@ function CaptureLab() {
   );
 }
 
-function mountTwoTrials(): [string, string] {
-  render(
+async function mountTwoTrials(): Promise<[string, string]> {
+  await renderSettled(
     <Lab instruments={[subject]} defaultInstrument="Subject">
       <CaptureLab />
     </Lab>,
   );
-  act(() => labRef?.addTrial('Subject'));
+  await act(async () => labRef?.addTrial('Subject'));
   const ids = labRef?.trials.map((t) => t.id) ?? [];
   const [a, b] = ids;
   if (!a || !b) throw new Error('expected two trials');
@@ -82,13 +83,13 @@ describe('annotations.targets', () => {
     labRef = null;
   });
 
-  it('is told which trial is asking', () => {
-    const [a, b] = mountTwoTrials();
+  it('is told which trial is asking', async () => {
+    const [a, b] = await mountTwoTrials();
     expect(new Set(asked.map((t) => t.id))).toEqual(new Set([a, b]));
   });
 
-  it("is told that trial's own view, not the other's", () => {
-    const [a, b] = mountTwoTrials();
+  it("is told that trial's own view, not the other's", async () => {
+    const [a, b] = await mountTwoTrials();
     fireEvent.click(screen.getByTestId(`zoom-${a}`));
     expect(lastAsk(a).view).toEqual({ zoom: 3, pan: { x: 0, y: 0 } });
     expect(lastAsk(b).view).toEqual({ zoom: 1, pan: { x: 0, y: 0 } });

package/src/trial/Trial.test.tsx

@@ -1,4 +1,5 @@
-import { fireEvent, render, screen, within } from '@testing-library/react';
+import { fireEvent, screen, within } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { type ReactNode, useState } from 'react';
 import { describe, expect, it, vi } from 'vitest';
 import { useStore } from 'zustand/react';
@@ -102,19 +103,19 @@ function ChromeFromStore({
 }
 
 describe('<TrialChrome>', () => {
-  it('renders children in the content area', () => {
-    render(<ChromeHarness />);
+  it('renders children in the content area', async () => {
+    await renderSettled(<ChromeHarness />);
     expect(screen.getByTestId('content')).toBeInTheDocument();
   });
 
-  it('renders the built-in trial actions', () => {
-    render(<ChromeHarness />);
+  it('renders the built-in trial actions', async () => {
+    await renderSettled(<ChromeHarness />);
     expect(screen.getByRole('button', { name: 'Close trial' })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: 'Clone trial' })).toBeInTheDocument();
   });
 
-  it('puts clone, reset and snapshot at the end of the title bar, beside close', () => {
-    const { container } = render(<ChromeHarness />);
+  it('puts clone, reset and snapshot at the end of the title bar, beside close', async () => {
+    const { container } = await renderSettled(<ChromeHarness />);
     const titlebar = container.querySelector('.lk-trial__titlebar');
     if (!titlebar) throw new Error('no title bar');
     expect(titlebar).toContainElement(screen.getByRole('button', { name: 'Clone trial' }));
@@ -125,15 +126,15 @@ describe('<TrialChrome>', () => {
     expect(labels).toEqual(['Clone trial', 'Reset trial', 'Save snapshot', 'Close trial']);
   });
 
-  it('disables close on the last trial', () => {
-    render(<ChromeHarness isLastTrial />);
+  it('disables close on the last trial', async () => {
+    await renderSettled(<ChromeHarness isLastTrial />);
     expect(screen.getByRole('button', { name: /close/i })).toBeDisabled();
   });
 
-  it('omits undo and redo unless the instrument declares undo', () => {
-    render(<ChromeHarness />);
+  it('omits undo and redo unless the instrument declares undo', async () => {
+    await renderSettled(<ChromeHarness />);
     expect(screen.queryByRole('button', { name: 'Undo' })).toBeNull();
-    render(
+    await renderSettled(
       <ChromeHarness
         instrument={{ ...stubInstrument, undo: {} }}
         undoBindings={{ canUndo: true, canRedo: false, undo: vi.fn(), redo: vi.fn() }}
@@ -143,7 +144,7 @@ describe('<TrialChrome>', () => {
     expect(screen.getByRole('button', { name: 'Redo' })).toBeDisabled();
   });
 
-  it('offers the snapshot loader once a snapshot exists', () => {
+  it('offers the snapshot loader once a snapshot exists', async () => {
     const snapshot: SavedSnapshot = {
       id: 's1',
       name: 'First',
@@ -153,17 +154,19 @@ describe('<TrialChrome>', () => {
       state: {},
       savedAt: 1,
     };
-    render(<ChromeHarness labOverrides={{ savedSnapshots: [snapshot] }} />);
+    await renderSettled(<ChromeHarness labOverrides={{ savedSnapshots: [snapshot] }} />);
     expect(screen.getByRole('button', { name: /load snapshot/i })).toBeInTheDocument();
   });
 
-  it('renders a consumer contribution alongside the built-ins', () => {
-    render(<ChromeHarness chrome={[{ id: 'mine', region: 'status', item: { text: 'ready' } }]} />);
+  it('renders a consumer contribution alongside the built-ins', async () => {
+    await renderSettled(
+      <ChromeHarness chrome={[{ id: 'mine', region: 'status', item: { text: 'ready' } }]} />,
+    );
     expect(screen.getByText('ready')).toBeInTheDocument();
   });
 
-  it('leads the title bar with a contribution that does not set `end`', () => {
-    const { container } = render(
+  it('leads the title bar with a contribution that does not set `end`', async () => {
+    const { container } = await renderSettled(
       <ChromeHarness
         chrome={[
           {
@@ -183,8 +186,8 @@ describe('<TrialChrome>', () => {
     expect(lead.compareDocumentPosition(heading) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
   });
 
-  it('reads the instrument name until a contribution calls setTitle', () => {
-    render(
+  it('reads the instrument name until a contribution calls setTitle', async () => {
+    await renderSettled(
       <ChromeHarness
         chrome={[
           {
@@ -205,9 +208,9 @@ describe('<TrialChrome>', () => {
     expect(screen.getByRole('region', { name: 'Trial Sprocket 7' })).toBeInTheDocument();
   });
 
-  it("reads the instrument's title over its name, and returns to it on setTitle(null)", () => {
+  it("reads the instrument's title over its name, and returns to it on setTitle(null)", async () => {
     const titled: Instrument = { ...stubInstrument, title: 'Stub / Default' };
-    render(
+    await renderSettled(
       <ChromeHarness
         instrument={titled}
         chrome={[
@@ -232,9 +235,9 @@ describe('<TrialChrome>', () => {
     expect(screen.getByRole('region', { name: 'Trial Stub / Default' })).toBeInTheDocument();
   });
 
-  it('Cmd+S triggers saveSnapshot', () => {
+  it('Cmd+S triggers saveSnapshot', async () => {
     const saveSnapshot = vi.fn();
-    render(<ChromeHarness labOverrides={{ saveSnapshot }} />);
+    await renderSettled(<ChromeHarness labOverrides={{ saveSnapshot }} />);
     const region = screen.getByRole('region', { name: /trial/i });
     fireEvent.keyDown(region, { key: 's', metaKey: true });
     expect(saveSnapshot).toHaveBeenCalledWith('ws-1', undefined);
@@ -242,30 +245,32 @@ describe('<TrialChrome>', () => {
 });
 
 describe('chrome regions in a mounted lab', () => {
-  function renderLabWith(instrument: Instrument) {
-    return render(<Lab title="T" instruments={[instrument]} defaultInstrument={instrument.name} />);
+  async function renderLabWith(instrument: Instrument) {
+    return renderSettled(
+      <Lab title="T" instruments={[instrument]} defaultInstrument={instrument.name} />,
+    );
   }
 
-  it('puts zoom in the viewport region and not in the toolbar', () => {
-    renderLabWith({ ...stubInstrument, canvas: { layers: [] }, undo: {} });
+  it('puts zoom in the viewport region and not in the toolbar', async () => {
+    await renderLabWith({ ...stubInstrument, canvas: { layers: [] }, undo: {} });
     const toolbar = document.querySelector('.lk-trial__toolbar') as HTMLElement;
     const viewport = document.querySelector('.lk-viewport-controls') as HTMLElement;
     expect(within(viewport).getByRole('button', { name: 'Zoom in' })).toBeInTheDocument();
     expect(within(toolbar).queryByRole('button', { name: 'Zoom in' })).toBeNull();
   });
 
-  it('renders no undo group for an instrument that does not declare undo', () => {
-    renderLabWith({ ...stubInstrument, canvas: { layers: [] } });
+  it('renders no undo group for an instrument that does not declare undo', async () => {
+    await renderLabWith({ ...stubInstrument, canvas: { layers: [] } });
     expect(screen.queryByRole('button', { name: 'Undo' })).toBeNull();
   });
 
-  it('renders no viewport region for an instrument with no canvas', () => {
-    renderLabWith(stubInstrument);
+  it('renders no viewport region for an instrument with no canvas', async () => {
+    await renderLabWith(stubInstrument);
     expect(document.querySelector('.lk-viewport-controls')).toBeNull();
   });
 
-  it('Lab provides context for nested TrialChrome', () => {
-    renderLabWith(stubInstrument);
+  it('Lab provides context for nested TrialChrome', async () => {
+    await renderLabWith(stubInstrument);
     expect(document.querySelector('.lk-lab')).toBeTruthy();
   });
 });
@@ -291,46 +296,46 @@ describe('<TrialChrome> — state that outlives a mount', () => {
     },
   ];
 
-  it('keeps a title across a remount', () => {
+  it('keeps a title across a remount', async () => {
     const store = makeChromeStore();
-    const first = render(<ChromeHarness store={store} chrome={renameChrome} />);
+    const first = await renderSettled(<ChromeHarness store={store} chrome={renameChrome} />);
     fireEvent.click(screen.getByRole('button', { name: 'Rename' }));
     first.unmount();
 
-    render(<ChromeHarness store={store} chrome={renameChrome} />);
+    await renderSettled(<ChromeHarness store={store} chrome={renameChrome} />);
     expect(screen.getByRole('region', { name: 'Trial Sprocket 7' })).toBeInTheDocument();
   });
 
-  it('keeps a folded sidebar section across a remount', () => {
+  it('keeps a folded sidebar section across a remount', async () => {
     const store = makeChromeStore();
-    const first = render(<ChromeHarness store={store} chrome={sectionChrome} />);
+    const first = await renderSettled(<ChromeHarness store={store} chrome={sectionChrome} />);
     expect(screen.getByTestId('notes-body')).toBeInTheDocument();
     fireEvent.click(screen.getByRole('button', { name: 'Notes' }));
     expect(screen.queryByTestId('notes-body')).toBeNull();
     first.unmount();
 
-    render(<ChromeHarness store={store} chrome={sectionChrome} />);
+    await renderSettled(<ChromeHarness store={store} chrome={sectionChrome} />);
     expect(screen.getByRole('button', { name: 'Notes' })).toHaveAttribute('aria-expanded', 'false');
     expect(screen.queryByTestId('notes-body')).toBeNull();
   });
 
-  it('keeps a folded settings group across a remount', () => {
+  it('keeps a folded settings group across a remount', async () => {
     const sectioned: Instrument = {
       ...stubInstrument,
       config: f.schema({ size: f.number(1).section('Shape') }),
     };
     const store = makeChromeStore();
-    const first = render(<ChromeHarness store={store} instrument={sectioned} />);
+    const first = await renderSettled(<ChromeHarness store={store} instrument={sectioned} />);
     const twisty = screen.getByRole('button', { name: 'Shape' });
     expect(twisty).toHaveAttribute('aria-expanded', 'true');
     fireEvent.click(twisty);
     first.unmount();
 
-    render(<ChromeHarness store={store} instrument={sectioned} />);
+    await renderSettled(<ChromeHarness store={store} instrument={sectioned} />);
     expect(screen.getByRole('button', { name: 'Shape' })).toHaveAttribute('aria-expanded', 'false');
   });
 
-  it('reopens a section that starts collapsed, and keeps it open across a remount', () => {
+  it('reopens a section that starts collapsed, and keeps it open across a remount', async () => {
     const collapsedChrome: ChromeProps['chrome'] = [
       {
         id: 'notes',
@@ -343,12 +348,12 @@ describe('<TrialChrome> — state that outlives a mount', () => {
       },
     ];
     const store = makeChromeStore();
-    const first = render(<ChromeHarness store={store} chrome={collapsedChrome} />);
+    const first = await renderSettled(<ChromeHarness store={store} chrome={collapsedChrome} />);
     expect(screen.queryByTestId('notes-body')).toBeNull();
     fireEvent.click(screen.getByRole('button', { name: 'Notes' }));
     first.unmount();
 
-    render(<ChromeHarness store={store} chrome={collapsedChrome} />);
+    await renderSettled(<ChromeHarness store={store} chrome={collapsedChrome} />);
     expect(screen.getByTestId('notes-body')).toBeInTheDocument();
   });
 });

package/src/trial/Trial.trialId.test.tsx

@@ -4,7 +4,8 @@
  * `SingletonExperiment` — so `useTrialState()` threw everywhere else, which
  * made the documented hook pattern unreachable from an instrument's `render`.
  */
-import { act, render, screen } from '@testing-library/react';
+import { act, screen } from '@testing-library/react';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { beforeAll, describe, expect, it, vi } from 'vitest';
 import { defineInstrument } from '../instrument/defineInstrument';
 import { Lab } from '../lab/Lab';
@@ -30,16 +31,16 @@ const reader = defineInstrument<{ hits: number }, Record<string, never>>({
 });
 
 describe('<Trial> trial-scoped hooks', () => {
-  it('lets an instrument read its own trial state through useTrialState', () => {
-    render(<Lab instruments={[reader]} defaultInstrument="Reader" />);
+  it('lets an instrument read its own trial state through useTrialState', async () => {
+    await renderSettled(<Lab instruments={[reader]} defaultInstrument="Reader" />);
     expect(screen.getByTestId('probe')).toHaveTextContent('hits:7');
   });
 });
 
 describe('<Trial> root element', () => {
-  it('carries its trial id, so a lab can find a trial from outside', () => {
+  it('carries its trial id, so a lab can find a trial from outside', async () => {
     let labRef: LabContextValue | null = null;
-    const { container } = render(
+    const { container } = await renderSettled(
       <Lab instruments={[reader]} defaultInstrument="Reader">
         <LabContext.Consumer>
           {(value) => {
@@ -49,7 +50,7 @@ describe('<Trial> root element', () => {
         </LabContext.Consumer>
       </Lab>,
     );
-    act(() => (labRef as LabContextValue | null)?.addTrial('Reader'));
+    await act(async () => (labRef as LabContextValue | null)?.addTrial('Reader'));
     const ids = (labRef as LabContextValue | null)?.trials.map((t) => t.id) ?? [];
     expect(ids).toHaveLength(2);
     const roots = container.querySelectorAll<HTMLElement>('.lk-trial[data-trial-id]');