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

package/src/trial/Trial.annotations.persist.test.tsx

@@ -0,0 +1,166 @@
+/**
+ * Marks survive a reload. The payload goes in a trial slot of labkit's own —
+ * not in `record.state`, which is the instrument's and typed as such — and it
+ * is written on a trailing debounce: a write per scene notification re-renders
+ * every trial on every frame of a drag.
+ */
+import { act, render } from '@testing-library/react';
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { useAnnotations } from '../annotations/AnnotationsContext';
+import type { AnnotationsApi, SerializedAnnotations } from '../annotations/types';
+import { defineInstrument } from '../instrument/defineInstrument';
+import type { InstrumentList } from '../instrument/types';
+import { Lab } from '../lab/Lab';
+import { createMemoryAdapter } from '../state/adapters';
+import type { StorageAdapter } from '../state/types';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+let api: AnnotationsApi | null = null;
+
+function Pane() {
+  api = useAnnotations();
+  return <div data-testid="pane" />;
+}
+
+/** Read through a call, so TypeScript does not narrow the module-level `api`
+ *  to `null` across the remounts these tests are about. */
+function marks(): AnnotationsApi {
+  if (!api) throw new Error('no annotations api — did the instrument render?');
+  return api;
+}
+
+const TARGET = { id: 'pane', ref: { current: null }, content: { w: 200, h: 100 } };
+
+const inspector = defineInstrument<Record<string, never>, { angle: number }>({
+  name: 'Inspector',
+  defaultConfig: () => ({ angle: 0 }),
+  initialState: () => ({}),
+  render: () => <Pane />,
+  annotations: { targets: () => [{ ...TARGET, positionDependsOn: ['angle'] }] },
+});
+
+/** The instrument keeps its own marks, so labkit must not keep them too. */
+let owned: SerializedAnnotations | null = null;
+const selfStoring = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'SelfStoring',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <Pane />,
+  annotations: {
+    targets: () => [TARGET],
+    storage: {
+      load: () => owned,
+      save: (doc) => {
+        owned = doc;
+      },
+    },
+  },
+});
+
+function mount(storage: StorageAdapter, which: InstrumentList[number] = inspector) {
+  return render(
+    <Lab
+      instruments={[which]}
+      defaultInstrument={which.name}
+      storage={storage}
+      storageKey="persist-test"
+    />,
+  );
+}
+
+const MARK = { target: 'pane', kind: 'rect' as const, frac: { x: 0.2, y: 0.3, w: 0.1, h: 0.1 } };
+
+describe('a trial that persists its marks', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    api = null;
+    owned = null;
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('brings them back on a remount from the same storage', () => {
+    const storage = createMemoryAdapter();
+    const first = mount(storage);
+    const id = marks().add(MARK, { angle: 12 });
+
+    // Past both debounces: labkit's write-back, then the document flush.
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    first.unmount();
+
+    api = null;
+    mount(storage);
+    const back = marks().get(id);
+    expect(back).toMatchObject({ id, target: 'pane', kind: 'rect', frac: MARK.frac });
+    // The staleness snapshot has to survive too, or every restored mark reads
+    // as fresh against whatever config it is opened under.
+    expect(back?.seen).toEqual({ angle: 12 });
+    if (!back) throw new Error('unreachable');
+    expect(marks().isStale(back, { angle: 45 })).toBe(true);
+  });
+
+  it('writes nothing before the debounce elapses', () => {
+    const storage = createMemoryAdapter();
+    const first = mount(storage);
+    marks().add(MARK);
+    act(() => {
+      vi.advanceTimersByTime(20);
+    });
+    first.unmount();
+
+    api = null;
+    mount(storage);
+    // Not a claim about the debounce interval — a claim that one exists, and
+    // that a store write is not synchronous with a scene notification.
+    //
+    // It is also the no-migration claim: the document this remount reads was
+    // written with trials and no `annotations` field, exactly as every
+    // document from before this arc is, and the trial opens on an empty store
+    // rather than failing to load.
+    expect(marks().query()).toHaveLength(0);
+  });
+
+  it('flushes on unmount, so the last mark before a close is not lost', () => {
+    const storage = createMemoryAdapter();
+    const first = mount(storage);
+    const id = marks().add(MARK);
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    marks().add({ ...MARK, frac: { x: 0.6, y: 0.6, w: 0.1, h: 0.1 } });
+    first.unmount();
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+
+    api = null;
+    mount(storage);
+    expect(marks().query()).toHaveLength(2);
+    expect(marks().get(id)).toBeDefined();
+  });
+
+  it('leaves the slot alone when the instrument owns the storage', () => {
+    const storage = createMemoryAdapter();
+    const first = mount(storage, selfStoring);
+    marks().add(MARK);
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    first.unmount();
+
+    expect(owned?.version).toBe(1);
+    expect(storage.read('lk:persist-test:doc')).not.toContain('"annotations"');
+
+    api = null;
+    mount(storage, selfStoring);
+    expect(marks().query()).toHaveLength(1);
+  });
+});

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

@@ -0,0 +1,121 @@
+/**
+ * Declaring `annotations` is what provides the drawing palette and the hook —
+ * the same "a capability provides the chrome" rule the other capabilities
+ * follow. The overlay's own geometry is covered in
+ * `annotations/Annotations.overlay.test.tsx`.
+ */
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { useAnnotations, useAnnotationsOptional } from '../annotations/AnnotationsContext';
+import type { AnnotationsApi } from '../annotations/types';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { Lab } from '../lab/Lab';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+let api: AnnotationsApi | null = null;
+
+function Pane() {
+  api = useAnnotations();
+  return <div data-testid="pane" data-marks={api.query().length} />;
+}
+
+function marks(): AnnotationsApi {
+  if (!api) throw new Error('no annotations api');
+  return api;
+}
+
+const annotating = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'Annotating',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <Pane />,
+  annotations: {
+    targets: () => [{ id: 'pane', ref: { current: null }, content: { w: 200, h: 100 } }],
+  },
+});
+
+function PlainPane() {
+  const api = useAnnotationsOptional();
+  return <div data-testid="plain" data-has-api={String(api !== null)} />;
+}
+
+const plain = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'Plain',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => <PlainPane />,
+});
+
+describe('an instrument that declares annotations', () => {
+  it('gets a drawing palette', () => {
+    render(<Lab instruments={[annotating]} defaultInstrument="Annotating" />);
+    for (const label of ['Select', 'Freehand', 'Line', 'Arrow', 'Rectangle', 'Ellipse', 'Text']) {
+      expect(screen.getByRole('button', { name: label })).toBeTruthy();
+    }
+  });
+
+  it('puts the store in reach of its own render', () => {
+    render(<Lab instruments={[annotating]} defaultInstrument="Annotating" />);
+    expect(screen.getByTestId('pane').dataset.marks).toBe('0');
+  });
+
+  it('starts in select, so a first click does not draw', () => {
+    render(<Lab instruments={[annotating]} defaultInstrument="Annotating" />);
+    expect(screen.getByRole('button', { name: 'Select' }).getAttribute('aria-current')).toBe(
+      'true',
+    );
+  });
+});
+
+describe('the trial undo chrome over marks', () => {
+  it('gets undo and redo without the instrument declaring `undo`', () => {
+    // Weasel history is the authority for marks, so the capability that
+    // creates them is what earns the buttons.
+    render(<Lab instruments={[annotating]} defaultInstrument="Annotating" />);
+    expect(screen.getByRole('button', { name: 'Undo' })).toBeTruthy();
+    expect(screen.getByRole('button', { name: 'Redo' })).toBeTruthy();
+  });
+
+  it('takes back a mark, and puts it back', () => {
+    render(<Lab instruments={[annotating]} defaultInstrument="Annotating" />);
+    const undo = screen.getByRole('button', { name: 'Undo' });
+    expect(undo.getAttribute('aria-disabled') ?? undo.getAttribute('disabled')).not.toBeNull();
+
+    act(() => {
+      marks().add({ target: 'pane', kind: 'rect', frac: { x: 0.1, y: 0.1, w: 0.2, h: 0.2 } });
+    });
+    expect(screen.getByTestId('pane').dataset.marks).toBe('1');
+
+    act(() => {
+      fireEvent.click(screen.getByRole('button', { name: 'Undo' }));
+    });
+    expect(screen.getByTestId('pane').dataset.marks).toBe('0');
+
+    act(() => {
+      fireEvent.click(screen.getByRole('button', { name: 'Redo' }));
+    });
+    expect(screen.getByTestId('pane').dataset.marks).toBe('1');
+  });
+
+  it('lists the marks in a sidebar panel', () => {
+    render(<Lab instruments={[annotating]} defaultInstrument="Annotating" />);
+    expect(screen.getByText('Marks')).toBeTruthy();
+    act(() => {
+      marks().add({ target: 'pane', kind: 'line', frac: { x: 0, y: 0, w: 0.5, h: 0 } });
+    });
+    expect(screen.getAllByRole('listitem')).toHaveLength(1);
+  });
+});
+
+describe('an instrument that declares none', () => {
+  it('gets no store and no palette', () => {
+    render(<Lab instruments={[plain]} defaultInstrument="Plain" />);
+    expect(screen.getByTestId('plain').dataset.hasApi).toBe('false');
+    expect(screen.queryByRole('button', { name: 'Rectangle' })).toBeNull();
+  });
+});

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

@@ -1,4 +1,5 @@
 import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { beforeAll, describe, expect, it, vi } from 'vitest';
 import { defineInstrument } from '../instrument/defineInstrument';
 import { Lab } from '../lab/Lab';
@@ -22,7 +23,10 @@ beforeAll(() => {
   ) as unknown as HTMLCanvasElement['getContext'];
 });
 
-function makeInstrument(draw: (ctx: CanvasRenderingContext2D, args: unknown) => void) {
+function makeInstrument(
+  draw: (ctx: CanvasRenderingContext2D, args: unknown) => void,
+  canvasExtra: Record<string, unknown> = {},
+) {
   return defineInstrument<St, Record<string, never>>({
     name: 'Probe',
     defaultConfig: () => ({}),
@@ -31,6 +35,7 @@ function makeInstrument(draw: (ctx: CanvasRenderingContext2D, args: unknown) =>
     canvas: {
       initialView: { zoom: 2, pan: { x: 30, y: 40 } },
       layers: [{ id: 'main', draw }],
+      ...canvasExtra,
     },
   });
 }
@@ -77,4 +82,74 @@ describe('LabProps.instruments', () => {
     render(<Lab instruments={[typed]} defaultInstrument="Probe" />);
     expect(screen.getByTestId('readout')).toBeInTheDocument();
   });
+
+  it('draws through a declared world spec, not the top-left default', async () => {
+    vi.spyOn(Element.prototype, 'getBoundingClientRect').mockReturnValue({
+      left: 0,
+      top: 0,
+      width: 800,
+      height: 600,
+    } as unknown as DOMRect);
+    ctxSpies.translate.mockClear();
+    ctxSpies.scale.mockClear();
+
+    const instrument = makeInstrument(vi.fn(), {
+      worldSpec: { origin: { x: 0.5, y: 0.5 }, yAxis: 'up' },
+    });
+    render(<Lab instruments={[instrument]} defaultInstrument="Probe" />);
+    await new Promise((r) => requestAnimationFrame(() => r(null)));
+
+    // Origin (400,300) plus the instrument's pan (30,40); y runs up.
+    expect(ctxSpies.translate).toHaveBeenCalledWith(430, 340);
+    expect(ctxSpies.scale).toHaveBeenCalledWith(2, -2);
+    vi.restoreAllMocks();
+  });
+
+  it('places a size-aware initial view once the canvas has been measured', async () => {
+    vi.spyOn(Element.prototype, 'getBoundingClientRect').mockReturnValue({
+      left: 0,
+      top: 0,
+      width: 800,
+      height: 600,
+    } as unknown as DOMRect);
+    ctxSpies.translate.mockClear();
+
+    const instrument = makeInstrument(vi.fn(), {
+      initialView: ({ width, height }: { width: number; height: number }) => ({
+        zoom: 1,
+        pan: { x: width / 4, y: height / 4 },
+      }),
+    });
+    render(<Lab instruments={[instrument]} defaultInstrument="Probe" />);
+    await new Promise((r) => requestAnimationFrame(() => r(null)));
+    await new Promise((r) => requestAnimationFrame(() => r(null)));
+
+    expect(ctxSpies.translate).toHaveBeenCalledWith(200, 150);
+    vi.restoreAllMocks();
+  });
+
+  it('tells the instrument which layers are currently visible', async () => {
+    let seen: readonly string[] = [];
+    const instrument = defineInstrument<St, Record<string, never>>({
+      name: 'Probe',
+      defaultConfig: () => ({}),
+      initialState: () => ({ n: 1 }),
+      render: ({ trial }) => {
+        seen = trial.visibleLayers;
+        return null;
+      },
+      canvas: {
+        layers: [
+          { id: 'grid', draw: () => undefined },
+          { id: 'glyph', draw: () => undefined },
+        ],
+      },
+      layers: { ids: ['grid', 'glyph'] },
+    });
+    render(<Lab instruments={[instrument]} defaultInstrument="Probe" />);
+    expect([...seen]).toEqual(['grid', 'glyph']);
+
+    await userEvent.click(screen.getByRole('checkbox', { name: 'Toggle grid' }));
+    expect([...seen]).toEqual(['glyph']);
+  });
 });

package/src/trial/Trial.less

@@ -22,6 +22,9 @@
 
   &__sidebar {
     flex-shrink: 0;
+    // Stated, not content-derived: an auto-width sidebar is as wide as its
+    // widest label, so one verbose config key sets the width of the lab.
+    width: var(--lk-trial-sidebar-w, 20rem);
     display: flex;
     flex-direction: column;
     min-height: 0;
@@ -62,6 +65,22 @@
     height: 100%;
   }
 
+  // A DOM instrument's own box, so the lens has something to be positioned
+  // against. Reproduces the content well's column so the instrument still
+  // stretches to it rather than collapsing to its intrinsic height.
+  &__loupe-host {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    height: 100%;
+
+    > * {
+      flex: 1 1 auto;
+      min-height: 0;
+    }
+  }
+
   &__toolbar {
     flex-shrink: 0;
   }

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

@@ -0,0 +1,128 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { Lab } from '../lab/Lab';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(() => ({
+    save: vi.fn(),
+    restore: vi.fn(),
+    setTransform: vi.fn(),
+    clearRect: vi.fn(),
+    translate: vi.fn(),
+    scale: vi.fn(),
+    drawImage: vi.fn(),
+    getImageData: () => ({ data: Uint8ClampedArray.from([0, 0, 0, 0]) }),
+  })) as unknown as HTMLCanvasElement['getContext'];
+});
+
+const canvasInstrument = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'Drawn',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => null,
+  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> },
+});
+
+const noLoupe = defineInstrument<Record<string, never>, Record<string, never>>({
+  name: 'Plain',
+  defaultConfig: () => ({}),
+  initialState: () => ({}),
+  render: () => null,
+  canvas: { layers: [{ id: 'main', draw: () => undefined }] },
+});
+
+const lens = (c: HTMLElement): Element | null => c.querySelector('.lk-loupe');
+
+/** jsdom lays nothing out, so a client coordinate is already host-relative. */
+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(
+      <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" />);
+    expect(screen.queryByRole('button', { name: 'Loupe' })).toBeNull();
+  });
+
+  it('drops out of a trial that suppresses it', () => {
+    render(<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(
+      <Lab instruments={[canvasInstrument]} defaultInstrument="Drawn" />,
+    );
+    await user.click(screen.getByRole('button', { name: 'Loupe' }));
+    expect(screen.getByRole('button', { name: 'Loupe' })).toHaveAttribute('aria-pressed', 'true');
+
+    const stack = container.querySelector('.lk-canvas-stack');
+    if (!stack) throw new Error('no canvas stack');
+    pointAt(stack, 60, 40);
+
+    const bubble = lens(container);
+    expect(bubble).not.toBeNull();
+    // The lens is drawn inside the stack's overlay, so it moves with the canvas
+    // rather than with the page.
+    expect(container.querySelector('.lk-canvas-stack__overlay')).toContainElement(
+      bubble as HTMLElement,
+    );
+    expect(bubble?.querySelector('canvas')).not.toBeNull();
+  });
+
+  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" />);
+    await user.click(screen.getByRole('button', { name: 'Loupe' }));
+
+    const host = container.querySelector('.lk-trial__loupe-host');
+    if (!host) throw new Error('no loupe host');
+    pointAt(host, 60, 40);
+
+    // The trial opens at zoom 1 and the loupe at factor 6.
+    expect(screen.getByTestId('lens-body')).toHaveTextContent('zoom 6');
+    // The instrument's own body is still there, undisturbed.
+    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('puts the lens away again when the toggle goes off', async () => {
+    const user = userEvent.setup();
+    const { container } = render(
+      <Lab instruments={[canvasInstrument]} defaultInstrument="Drawn" />,
+    );
+    const toggle = screen.getByRole('button', { name: 'Loupe' });
+    await user.click(toggle);
+    const stack = container.querySelector('.lk-canvas-stack');
+    if (!stack) throw new Error('no canvas stack');
+    pointAt(stack, 60, 40);
+    expect(lens(container)).not.toBeNull();
+
+    await user.click(toggle);
+    expect(lens(container)).toBeNull();
+  });
+});

package/src/trial/Trial.stories.tsx

@@ -60,6 +60,7 @@ function Harness() {
                 zoom: 1,
                 setZoom: () => {},
                 activeToolId: null,
+                visibleLayers: [],
               },
               emit: () => {},
             })}

package/src/trial/Trial.test.tsx

@@ -82,6 +82,18 @@ describe('<TrialChrome>', () => {
     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 />);
+    const titlebar = container.querySelector('.lk-trial__titlebar');
+    if (!titlebar) throw new Error('no title bar');
+    expect(titlebar).toContainElement(screen.getByRole('button', { name: 'Clone trial' }));
+    expect(titlebar).toContainElement(screen.getByRole('button', { name: 'Reset trial' }));
+    const labels = [...titlebar.querySelectorAll('button')].map((b) =>
+      b.getAttribute('aria-label'),
+    );
+    expect(labels).toEqual(['Clone trial', 'Reset trial', 'Save snapshot', 'Close trial']);
+  });
+
   it('disables close on the last trial', () => {
     render(<ChromeHarness isLastTrial />);
     expect(screen.getByRole('button', { name: /close/i })).toBeDisabled();

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

@@ -0,0 +1,36 @@
+/**
+ * An instrument hosted by a real <Lab> must be able to reach trial-scoped
+ * hooks. `<TrialIdProvider>` had exactly one production mount —
+ * `SingletonExperiment` — so `useTrialState()` threw everywhere else, which
+ * made the documented hook pattern unreachable from an instrument's `render`.
+ */
+import { render, screen } from '@testing-library/react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { Lab } from '../lab/Lab';
+import { useTrialState } from '../state/useTrialState';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+function Probe() {
+  const { state } = useTrialState<{ hits: number }, Record<string, never>>();
+  return <div data-testid="probe">hits:{state.hits}</div>;
+}
+
+const reader = defineInstrument<{ hits: number }, Record<string, never>>({
+  name: 'Reader',
+  defaultConfig: () => ({}),
+  initialState: () => ({ hits: 7 }),
+  render: () => <Probe />,
+});
+
+describe('<Trial> trial-scoped hooks', () => {
+  it('lets an instrument read its own trial state through useTrialState', () => {
+    render(<Lab instruments={[reader]} defaultInstrument="Reader" />);
+    expect(screen.getByTestId('probe')).toHaveTextContent('hits:7');
+  });
+});