@weasel-js/labkit 1.6.0 → 1.7.0

package/src/overview/OverviewMarks.test.tsx

@@ -0,0 +1,100 @@
+/**
+ * The overview draws every target's marks where that target sits on the stage,
+ * and redraws when one is added. jsdom lays nothing out, so the target's rect
+ * and the stage's are mocked; the stage's camera is the identity there.
+ */
+import { act, render } from '@testing-library/react';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { useAnnotations } from '../annotations/AnnotationsContext';
+import type { AnnotationsApi } from '../annotations/types';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { Lab } from '../lab/Lab';
+import { TrialOverview } from './TrialOverview';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+});
+
+const rect = (left: number, top: number, width: number, height: number) =>
+  ({
+    left,
+    top,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    x: left,
+    y: top,
+  }) as DOMRect;
+
+let restore: (() => void) | null = null;
+afterEach(() => restore?.());
+
+/** Stage 400×300, the pane at stage (50, 20) and 200×100. */
+function mount() {
+  const pane = { current: null as HTMLDivElement | null };
+  let api: AnnotationsApi | null = null;
+  function Body() {
+    api = useAnnotations();
+    return (
+      <div
+        ref={(el) => {
+          pane.current = el;
+        }}
+        data-testid="pane"
+      />
+    );
+  }
+  const marked = defineInstrument<Record<string, never>, Record<string, never>>({
+    name: 'Marked',
+    defaultConfig: () => ({}),
+    initialState: () => ({}),
+    render: () => <Body />,
+    stage: {
+      size: { width: 400, height: 300 },
+      overlay: () => <TrialOverview width={200} height={150} render={() => <div />} />,
+    },
+    annotations: {
+      targets: () => [{ id: 'pane', ref: pane, content: { w: 200, h: 100 } }],
+    },
+  });
+  const original = HTMLElement.prototype.getBoundingClientRect;
+  HTMLElement.prototype.getBoundingClientRect = function (this: HTMLElement) {
+    if (this === pane.current) return rect(50, 20, 200, 100);
+    return rect(0, 0, 0, 0);
+  };
+  restore = () => {
+    HTMLElement.prototype.getBoundingClientRect = original;
+  };
+  const r = render(<Lab instruments={[marked]} defaultInstrument="Marked" />);
+  return { ...r, api: () => api as AnnotationsApi };
+}
+
+const px = (el: HTMLElement, name: string) => Number.parseFloat(el.style.getPropertyValue(name));
+
+describe('marks on the overview', () => {
+  it('draws nothing for a target with no marks', () => {
+    const h = mount();
+    expect(h.container.querySelector('.lk-overview__marks')).toBeNull();
+  });
+
+  it("places a target's marks at the target's rect, through the fit", () => {
+    const h = mount();
+    act(() => {
+      h.api().add({ target: 'pane', kind: 'rect', frac: { x: 0.1, y: 0.1, w: 0.2, h: 0.2 } });
+    });
+    const marks = h.container.querySelector<HTMLElement>('.lk-overview__marks[data-target="pane"]');
+    expect(marks).not.toBeNull();
+    if (!marks) return;
+    // Content 400×300 into 200×150, 6px in: scale 0.46, camera at
+    // (200 - 100 / 0.46, 150 - 75 / 0.46).
+    const s = 0.46;
+    expect(px(marks, '--lk-overview-mx')).toBeCloseTo((50 - (200 - 100 / s)) * s);
+    expect(px(marks, '--lk-overview-my')).toBeCloseTo((20 - (150 - 75 / s)) * s);
+    expect(px(marks, '--lk-overview-mw')).toBeCloseTo(200 * s);
+    expect(px(marks, '--lk-overview-mh')).toBeCloseTo(100 * s);
+    expect(marks.querySelector('svg path')).not.toBeNull();
+  });
+});

package/src/overview/OverviewMarks.tsx

@@ -0,0 +1,93 @@
+/**
+ * Every annotation target's marks, drawn read-only on the overview through the
+ * export's own vector path: `markSvgNodes`, then `serializeSvg`.
+ */
+import type { View } from '@weasel-js/core';
+import { serializeSvg } from '@weasel-js/svg';
+import { type CSSProperties, type RefObject, useEffect, useReducer } from 'react';
+import { useAnnotationsOptional } from '../annotations/AnnotationsContext';
+import { markSvgNodes } from '../annotations/svgNodes';
+import type { AnnotationsApi } from '../annotations/types';
+import type { CameraContextValue } from '../canvas/CameraInput';
+
+/** A target's box, in the camera's frame-local units. */
+interface LocalRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** Where `el` sits in the camera's frame-local units: its screen rect,
+ *  measured against the camera's element, through the camera. */
+function localRectOf(el: HTMLElement, camera: CameraContextValue): LocalRect | null {
+  const host = camera.element();
+  if (!host) return null;
+  const r = el.getBoundingClientRect();
+  const h = host.getBoundingClientRect();
+  const v = camera.view.get();
+  return {
+    x: (r.left - h.left) / v.scale.x + v.x,
+    y: (r.top - h.top) / v.scale.y + v.y,
+    w: r.width / v.scale.x,
+    h: r.height / v.scale.y,
+  };
+}
+
+/** The element a target's marks sit on. The capability's targets carry their
+ *  `ref`; the store's type names only the half it reads. */
+function elementOf(target: object): HTMLElement | null {
+  return (target as { ref?: RefObject<HTMLElement | null> }).ref?.current ?? null;
+}
+
+function markupOf(api: AnnotationsApi, target: string, content: { w: number; h: number }): string {
+  const painted = api.paintedMarks(target);
+  if (painted.length === 0) return '';
+  const nodes = painted.flatMap(({ mark, style }) => markSvgNodes(mark, content, style));
+  return serializeSvg(nodes, { viewBox: { x: 0, y: 0, width: content.w, height: content.h } });
+}
+
+/** Props for `<OverviewMarks>`. */
+export interface OverviewMarksProps {
+  fit: View;
+  camera: CameraContextValue;
+}
+
+/**
+ * The marks of every target in the annotations store in scope, placed where
+ * each target's element sits on the stage. Draws nothing outside an annotating
+ * trial, and takes no input.
+ */
+export function OverviewMarks({ fit, camera }: OverviewMarksProps) {
+  const api = useAnnotationsOptional();
+  const [, redraw] = useReducer((n: number) => n + 1, 0);
+  useEffect(() => api?.subscribe(redraw), [api]);
+  if (!api) return null;
+  const s = fit.scale.x;
+  return (
+    <>
+      {api.targets().map((t) => {
+        const el = elementOf(t);
+        const box = el ? localRectOf(el, camera) : null;
+        const markup = box ? markupOf(api, t.id, t.content) : '';
+        if (!box || !markup) return null;
+        const place = {
+          ['--lk-overview-mx' as string]: `${(box.x - fit.x) * s}px`,
+          ['--lk-overview-my' as string]: `${(box.y - fit.y) * s}px`,
+          ['--lk-overview-mw' as string]: `${box.w * s}px`,
+          ['--lk-overview-mh' as string]: `${box.h * s}px`,
+        } as CSSProperties;
+        return (
+          <div
+            key={t.id}
+            className="lk-overview__marks"
+            style={place}
+            data-target={t.id}
+            // biome-ignore lint/security/noDangerouslySetInnerHtml: the export's SVG serializer is the one vector path marks have; re-deriving React nodes would be a second.
+            dangerouslySetInnerHTML={{ __html: markup }}
+          />
+        );
+      })}
+    </>
+  );
+}

package/src/overview/TrialOverview.less

@@ -0,0 +1,53 @@
+.lk-overview__title {
+  padding: 2px 6px 4px;
+  font-size: var(--wzl-font-size-sm);
+  color: var(--wzl-fg-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  cursor: grab;
+}
+
+.lk-overview__box {
+  position: relative;
+  width: var(--lk-overview-w);
+  height: var(--lk-overview-h);
+  overflow: hidden;
+  background: var(--wzl-surface-sunken);
+  touch-action: none;
+  cursor: crosshair;
+}
+
+.lk-overview__content {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--lk-overview-cw);
+  height: var(--lk-overview-ch);
+  transform-origin: 0 0;
+  transform: translate(var(--lk-overview-x), var(--lk-overview-y)) scale(var(--lk-overview-zoom));
+  pointer-events: none;
+}
+
+.lk-overview__canvas {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+}
+
+.lk-overview__marks {
+  position: absolute;
+  left: var(--lk-overview-mx);
+  top: var(--lk-overview-my);
+  width: var(--lk-overview-mw);
+  height: var(--lk-overview-mh);
+  pointer-events: none;
+}
+
+.lk-overview__marks > svg {
+  display: block;
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+}

package/src/overview/TrialOverview.stories.tsx

@@ -0,0 +1,50 @@
+import type { Meta, StoryObj } from '@weasel-js/forge';
+import { useState } from 'react';
+import { Stage } from '../canvas/Stage';
+import type { ViewTransform } from '../instrument/types';
+import { TrialOverview } from './TrialOverview';
+
+const meta: Meta<typeof TrialOverview> = {
+  title: 'labkit/Overview/TrialOverview',
+  component: TrialOverview,
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof TrialOverview>;
+
+const SIZE = { width: 640, height: 420 };
+const DOTS = [40, 120, 200, 280, 360, 440, 520, 600];
+
+/** A picture bigger than the stage at 2×, so there is somewhere to go. */
+function Picture() {
+  return (
+    <svg viewBox="0 0 640 420" width={SIZE.width} height={SIZE.height} role="img" aria-label="Grid">
+      <title>Grid</title>
+      <rect width="640" height="420" fill="#f4f1ea" />
+      {DOTS.map((x, i) => (
+        <circle key={x} cx={x} cy={40 + i * 48} r="24" fill="#8b98a8" />
+      ))}
+    </svg>
+  );
+}
+
+function Harness() {
+  const [view, setView] = useState<ViewTransform>({ zoom: 2, pan: { x: -200, y: -120 } });
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <Stage
+        size={SIZE}
+        view={view}
+        onViewChange={setView}
+        overlay={<TrialOverview width={200} height={140} render={() => <Picture />} />}
+      >
+        <Picture />
+      </Stage>
+    </div>
+  );
+}
+
+export const Default: Story = {
+  render: () => <Harness />,
+};

package/src/overview/TrialOverview.test.tsx

@@ -0,0 +1,116 @@
+/**
+ * A trial's overview: a press in it moves the stage's camera there, and the
+ * pointer over it is published as the overview's, which the stage then draws.
+ *
+ * jsdom lays nothing out, so every rect measures zero: a client point is
+ * already box-relative, and the stage's viewport has no size to center in —
+ * centering puts the pressed world point at the stage's origin instead.
+ */
+
+import { act, render } from '@testing-library/react';
+import type { PointerContextValue } from '@weasel-js/core';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { defineInstrument } from '../instrument/defineInstrument';
+import { Lab } from '../lab/Lab';
+import { TrialOverview } from './TrialOverview';
+
+beforeAll(() => {
+  HTMLCanvasElement.prototype.getContext = vi.fn(
+    () => null,
+  ) as unknown as HTMLCanvasElement['getContext'];
+  const proto = HTMLElement.prototype as unknown as Record<string, unknown>;
+  proto.setPointerCapture = vi.fn();
+  proto.releasePointerCapture = vi.fn();
+  proto.hasPointerCapture = vi.fn(() => true);
+});
+
+function pointer(el: Element, type: string, x: number, y: number, buttons = 1) {
+  el.dispatchEvent(
+    new PointerEvent(type, {
+      bubbles: true,
+      cancelable: true,
+      pointerId: 1,
+      clientX: x,
+      clientY: y,
+      button: 0,
+      buttons,
+    }),
+  );
+}
+
+/** Content 400×300 in a 200×150 box, 6px in: scale 0.46, so box (100, 75)
+ *  is content (200, 150). */
+function mount() {
+  let store: PointerContextValue | null = null;
+  const pictured = defineInstrument<Record<string, never>, Record<string, never>>({
+    name: 'Pictured',
+    defaultConfig: () => ({}),
+    initialState: () => ({}),
+    render: (ctx) => {
+      store = ctx.trial.pointer;
+      return <div data-testid="picture" />;
+    },
+    stage: {
+      size: { width: 400, height: 300 },
+      overlay: () => (
+        <TrialOverview width={200} height={150} render={() => <div data-testid="thumb" />} />
+      ),
+    },
+  });
+  const r = render(<Lab instruments={[pictured]} defaultInstrument="Pictured" />);
+  const box = r.container.querySelector('.lk-overview__box');
+  const content = r.container.querySelector('.lk-stage__content') as HTMLElement | null;
+  if (!box || !content) throw new Error('no overview or stage');
+  return { ...r, box, content, store: () => store as PointerContextValue | null };
+}
+
+const px = (el: HTMLElement, name: string) => Number.parseFloat(el.style.getPropertyValue(name));
+
+describe('<TrialOverview>', () => {
+  it('draws the instrument-supplied content, not the instrument itself', () => {
+    const h = mount();
+    expect(h.box.querySelector('[data-testid="thumb"]')).not.toBeNull();
+    expect(h.box.querySelector('[data-testid="picture"]')).toBeNull();
+  });
+
+  it('moves the stage camera to the pressed point', () => {
+    const h = mount();
+    act(() => {
+      pointer(h.box, 'pointerdown', 100, 75);
+      pointer(h.box, 'pointerup', 100, 75, 0);
+    });
+    expect(px(h.content, '--lk-stage-x')).toBeCloseTo(-200);
+    expect(px(h.content, '--lk-stage-y')).toBeCloseTo(-150);
+  });
+
+  it('follows a drag with the camera, and never pans the stage by it', () => {
+    const h = mount();
+    act(() => {
+      pointer(h.box, 'pointerdown', 100, 75);
+      pointer(h.box, 'pointermove', 110, 75);
+      pointer(h.box, 'pointermove', 123, 75);
+      pointer(h.box, 'pointerup', 123, 75, 0);
+    });
+    // Box x 123 is content x 250 — a stage pan by the 23px drag would land
+    // elsewhere.
+    expect(px(h.content, '--lk-stage-x')).toBeCloseTo(-250);
+  });
+
+  it("publishes the pointer over it as the overview's, and the stage draws it", () => {
+    const h = mount();
+    act(() => pointer(h.box, 'pointermove', 100, 75, 0));
+    const p = h.store()?.get();
+    expect(p?.viewId).toBe('overview');
+    expect(p?.worldX).toBeCloseTo(200);
+    expect(p?.worldY).toBeCloseTo(150);
+    expect(h.container.querySelector('.lk-stage .lk-linked-cursor')).not.toBeNull();
+  });
+
+  it("publishes the stage's pointer as the stage's, so the stage draws none", () => {
+    const h = mount();
+    const host = h.container.querySelector('.lk-stage') as HTMLElement;
+    act(() => pointer(host, 'pointermove', 10, 10, 0));
+    expect(h.store()?.get()?.viewId).toBe('stage');
+    expect(h.container.querySelector('.lk-stage .lk-linked-cursor')).toBeNull();
+  });
+});