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

package/dist/surface/index.d.ts

@@ -50,8 +50,18 @@ interface SurfaceHandle {
      *  moved something a ResizeObserver cannot see. */
     invalidateRects: () => void;
     registerTile: (id: string, el: HTMLElement | null) => void;
+    /** Subscribe a tile to the frames it is dirty on. A tile paints on its own
+     *  loop, so this is how the surface wakes one: a resize of the shared buffer
+     *  clears every tile, not only the one that moved. */
+    registerPainter: (id: string, paint: TilePainter) => () => void;
     containerRef: (el: HTMLElement | null) => void;
+    /** The element tile rects are measured against, and so the one a tile's own
+     *  chrome positions itself inside. Null before the owner attaches it. */
+    getContainer: () => HTMLElement | null;
 }
+/** What a tile's painter is handed: where it sits on the surface now, and the
+ *  frame that dirtied it. */
+type TilePainter = (rect: Rect, frame: SurfaceFrame) => void;
 interface UseTiledSurfaceOptions {
     onFrame: (frame: SurfaceFrame) => void;
 }
@@ -59,7 +69,13 @@ declare function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHa
 
 /** Null when no surface owner is above — a lab with no shared surface at all. */
 declare const SurfaceContext: react.Context<SurfaceHandle | null>;
+/** The buffer the surface's tiles paint into. Null until the owner's canvas is
+ *  mounted, and for an owner that keeps its surface unpainted. */
+declare const SurfaceCanvasContext: react.Context<HTMLCanvasElement | null>;
 
+/** The surface's shared buffer, or null where nothing paints one. What a tile
+ *  hands to `paintInto`. */
+declare function useSurfaceCanvas(): HTMLCanvasElement | null;
 /** The surface above, or null. Use this where a surface is genuinely optional. */
 declare function useSurfaceOptional(): SurfaceHandle | null;
 /** The surface above. Throws where a caller cannot work without one. */
@@ -73,5 +89,5 @@ declare function useSurface(): SurfaceHandle;
  */
 declare function useSurfaceTile(id: string): (el: HTMLElement | null) => void;
 
-export { SurfaceContext, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceOptional, useSurfaceTile, useTiledSurface };
-export type { Box, Rect, SurfaceFrame, SurfaceHandle, UseTiledSurfaceOptions };
+export { SurfaceCanvasContext, SurfaceContext, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTiledSurface };
+export type { Box, Rect, SurfaceFrame, SurfaceHandle, TilePainter, UseTiledSurfaceOptions };

package/dist/surface/index.js

@@ -1,4 +1,4 @@
-export { SurfaceContext, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceOptional, useSurfaceTile, useTiledSurface } from '../chunk-LGKRIUSW.js';
-import '../chunk-QCICIHEO.js';
+export { SurfaceCanvasContext, SurfaceContext, composeRects, rectsEqual, toDeviceRect, useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile, useTiledSurface } from '../chunk-4EY67BKJ.js';
+import '../chunk-ROQDRXKW.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/ui/layers/index.js

@@ -1,4 +1,4 @@
-export { c3 as LayerStack } from '../../chunk-RGT4EJIB.js';
-import '../../chunk-QCICIHEO.js';
+export { c3 as LayerStack } from '../../chunk-HEORBLVT.js';
+import '../../chunk-ROQDRXKW.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/undo/index.d.ts

@@ -1,9 +1,10 @@
-export { U as UndoCapability } from '../_dts/types-BttTIent.js';
+export { a0 as UndoCapability } from '../_dts/frac-Cp3NivlC.js';
 import 'react';
-import '../_dts/types-DCGEcMO_.js';
-import '../_dts/PrefsForm-BYa6cWnO.js';
-import '../_dts/types-1Sdxy_Pv.js';
+import '../_dts/types-D6s4b7if.js';
+import '../_dts/PrefsForm-BkUJZx0A.js';
+import '../_dts/types-DYMaEvM5.js';
 import '../_dts/types-DJ79Tg5J.js';
+import '../_dts/types-C-gh9Ap-.js';
 
 /** A subscriber to a named event. */
 type EventListener = () => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/labkit",
-  "version": "1.3.0",
+  "version": "1.4.0-pre.0",
   "description": "React widgets for building self-contained interactive lab pages",
   "license": "MIT",
   "author": "orochi235",
@@ -82,7 +82,11 @@
       "types": "./dist/ui/layers/index.d.ts",
       "import": "./dist/ui/layers/index.js"
     },
-    "./styles.css": "./dist/styles.css"
+    "./styles.css": "./dist/styles.css",
+    "./loupe": {
+      "types": "./dist/loupe/index.d.ts",
+      "import": "./dist/loupe/index.js"
+    }
   },
   "scripts": {
     "dev": "vite",
@@ -102,16 +106,19 @@
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
-    "dev:schema": "LABKIT_EXAMPLE=schema-lab vite"
+    "dev:schema": "LABKIT_EXAMPLE=schema-lab vite",
+    "dev:annotate": "LABKIT_EXAMPLE=annotate-lab vite"
   },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "dependencies": {
-    "@weasel-js/core": "1.3.0",
-    "@weasel-js/theme": "1.3.0",
-    "@weasel-js/ui": "1.3.0",
+    "@weasel-js/core": "1.4.0-pre.0",
+    "@weasel-js/loupe": "1.4.0-pre.0",
+    "@weasel-js/svg": "1.4.0-pre.0",
+    "@weasel-js/theme": "1.4.0-pre.0",
+    "@weasel-js/ui": "1.4.0-pre.0",
     "earcut": "2.2.4",
     "polygon-clipping": "^0.15.7",
     "react-aria-components": "^1.5.0",
@@ -122,7 +129,7 @@
     "@biomejs/biome": "^2.4.12",
     "@rollup/plugin-alias": "^6.0.0",
     "@testing-library/jest-dom": "^6.6.0",
-    "@weasel-js/modes": "1.3.0",
+    "@weasel-js/modes": "1.4.0-pre.0",
     "less": "^4.2.0",
     "rollup-plugin-dts": "^6.4.1",
     "tsx": "^4.19.0",

package/src/annotations/AnnotationOverlay.tsx

@@ -0,0 +1,205 @@
+import {
+  type InsertNodeFactory,
+  SceneCanvas,
+  type SceneCanvasApi,
+  useActiveToolContext,
+  type View,
+  WeaselProvider,
+} from '@weasel-js/core';
+import { type CSSProperties, useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import type { Rect } from '../surface/rect';
+import { useSurfaceCanvas, useSurfaceOptional } from '../surface/useSurfaceTile';
+import { createMarkDrawOne } from './drawOne';
+import type { WorldRect } from './frac';
+import { seenFrom } from './staleness';
+import type { MarkScene } from './store';
+import { ANNOTATION_WEASEL_TOOLS, annotationToolInfo } from './toolMap';
+import type {
+  AnnotationData,
+  AnnotationKind,
+  AnnotationMeaning,
+  AnnotationTarget,
+  FracPoint,
+} from './types';
+import { fitView, toWeaselView } from './view';
+
+/** Props for `<AnnotationOverlay>`. */
+export interface AnnotationOverlayProps {
+  target: AnnotationTarget;
+  /** The trial's mark scene — shared by every target; a mark's own `target`
+   *  field is what separates them. */
+  scene: MarkScene;
+  /** Snapshotted onto each new mark, so staleness can be answered later. */
+  config: unknown;
+  /** The trial's resolved tool slot. */
+  activeToolId: string | null;
+  /** The instrument's vocabulary, for a status's colour. */
+  meaning?: AnnotationMeaning;
+}
+
+const sameRect = (a: Rect | null, b: Rect): boolean =>
+  a !== null && a.x === b.x && a.y === b.y && a.w === b.w && a.h === b.h;
+
+/** Pushes the trial's tool into the weasel scope this pane owns. Its own
+ *  component because the context only exists below `<WeaselProvider>`. */
+function ToolBridge({ toolId }: { toolId: string }) {
+  const tools = useActiveToolContext();
+  const setActive = tools.setActive;
+  useEffect(() => {
+    setActive(toolId);
+  }, [toolId, setActive]);
+  return null;
+}
+
+/** Every vertex the insert carried, in fractions of the content box. */
+function pointsOf(
+  extras: Record<string, unknown>,
+  content: { w: number; h: number },
+): readonly FracPoint[] | undefined {
+  const toFrac = (p: { x: number; y: number }): FracPoint => ({
+    x: content.w === 0 ? 0 : p.x / content.w,
+    y: content.h === 0 ? 0 : p.y / content.h,
+  });
+  if (extras.kind === 'line') {
+    return [toFrac(extras.a as FracPoint), toFrac(extras.b as FracPoint)];
+  }
+  if (extras.kind === 'pencil') {
+    return (extras.samples as { x: number; y: number }[]).map(toFrac);
+  }
+  return undefined;
+}
+
+/**
+ * One target's drawing surface: a transparent box over the target's element
+ * taking the input, and a `<SceneCanvas>` painting into the lab's shared
+ * buffer at that box's rect.
+ *
+ * The box is portalled into the surface container because that is what tile
+ * rects are measured against; positioning it among the instrument's own DOM
+ * would put it in whatever positioning context happened to be there.
+ */
+export function AnnotationOverlay({
+  target,
+  scene,
+  config,
+  activeToolId,
+  meaning,
+}: AnnotationOverlayProps) {
+  const surface = useSurfaceOptional();
+  const canvas = useSurfaceCanvas();
+  const [rect, setRect] = useState<Rect | null>(null);
+  const [input, setInput] = useState<HTMLDivElement | null>(null);
+  const sceneCanvas = useRef<SceneCanvasApi | null>(null);
+
+  // Read in the insert factory, which is built once and must see the tool the
+  // pane is holding now — `arrow` and `stroke` are indistinguishable from
+  // `line` and `pencil` at the weasel end.
+  const toolRef = useRef(activeToolId);
+  toolRef.current = activeToolId;
+  const configRef = useRef(config);
+  configRef.current = config;
+
+  const id = target.id;
+  const lastTile = useRef<HTMLElement | null>(null);
+  useEffect(() => {
+    const el = target.ref.current ?? null;
+    if (el === lastTile.current) return;
+    lastTile.current = el;
+    surface?.registerTile(id, el);
+  });
+  useEffect(
+    () => () => {
+      // Clearing this is what lets the effect above re-register on the next
+      // commit. StrictMode's mount / unmount / mount would otherwise take the
+      // tile out and never put it back, and the surface would measure nothing.
+      lastTile.current = null;
+      surface?.registerTile(id, null);
+    },
+    [surface, id],
+  );
+
+  useEffect(
+    () =>
+      surface?.registerPainter(id, (next) => {
+        setRect((prev) => (sameRect(prev, next) ? prev : next));
+        // The shared buffer was cleared if it resized this frame; this pane's
+        // own loop has no way to know that.
+        sceneCanvas.current?.requestRedraw();
+      }),
+    [surface, id],
+  );
+
+  const container = surface?.getContainer() ?? null;
+  if (!container || !rect) return null;
+
+  const view: View = toWeaselView(target.view ?? fitView(target.content, { w: rect.w, h: rect.h }));
+
+  const drawOne = createMarkDrawOne({
+    content: target.content,
+    positionDependsOn: target.positionDependsOn,
+    config,
+    meaning,
+  });
+
+  const factories: Record<string, InsertNodeFactory> = {};
+  for (const weaselTool of ANNOTATION_WEASEL_TOOLS) {
+    factories[weaselTool] = (_bounds, extras) => {
+      const info = annotationToolInfo(toolRef.current);
+      const kind: AnnotationKind | undefined = info?.kind;
+      if (!kind) return null;
+      const points = pointsOf(extras as unknown as Record<string, unknown>, target.content);
+      const data: AnnotationData = {
+        target: id,
+        kind,
+        ...(points ? { points } : {}),
+        seen: seenFrom(configRef.current, target.positionDependsOn ?? []),
+      };
+      return { data };
+    };
+  }
+
+  // A measured rect has nowhere to live but the element's own style. Set as
+  // custom properties, which the stylesheet reads — the sanctioned use.
+  const box = {
+    ['--lk-anno-x' as string]: `${rect.x}px`,
+    ['--lk-anno-y' as string]: `${rect.y}px`,
+    ['--lk-anno-w' as string]: `${rect.w}px`,
+    ['--lk-anno-h' as string]: `${rect.h}px`,
+  } as CSSProperties;
+
+  return createPortal(
+    <>
+      <div
+        ref={setInput}
+        className="lk-annotate__input"
+        data-annotation-target={id}
+        role="application"
+        aria-label={`Annotations on ${id}`}
+        // biome-ignore lint/a11y/noNoninteractiveTabindex: role="application" IS the interactive case — a region with its own keymap. The rule's allowed-role list stops at the native widget roles and does not include it, and the gesture dispatcher listens on this element, so without focus no tool's keyboard binding ever fires.
+        tabIndex={0}
+        style={box}
+      />
+      {canvas && input ? (
+        // One scope per pane: a shared <ActionsProvider> lets only the newest
+        // canvas under it respond to input, and the rest go silently dead.
+        <WeaselProvider isolate>
+          <ToolBridge toolId={annotationToolInfo(activeToolId)?.weaselTool ?? 'select'} />
+          <SceneCanvas<AnnotationData, 'marks', WorldRect>
+            ref={sceneCanvas}
+            scene={scene}
+            width={rect.w}
+            height={rect.h}
+            view={view}
+            paintInto={{ canvas, x: rect.x, y: rect.y }}
+            inputElement={input}
+            defaultTools={ANNOTATION_WEASEL_TOOLS}
+            insertNodeFactories={factories}
+            layers={{ scene: { drawOne } }}
+          />
+        </WeaselProvider>
+      ) : null}
+    </>,
+    container,
+  );
+}

package/src/annotations/AnnotationTargets.tsx

@@ -0,0 +1,37 @@
+import { AnnotationOverlay } from './AnnotationOverlay';
+import type { AnnotationsApi, AnnotationsCapability } from './types';
+
+/** Props for `<AnnotationTargets>`. */
+export interface AnnotationTargetsProps {
+  capability: AnnotationsCapability;
+  state: unknown;
+  config: unknown;
+  annotations: AnnotationsApi;
+  activeToolId: string | null;
+}
+
+/** One overlay per region the instrument said accepts marks. */
+export function AnnotationTargets({
+  capability,
+  state,
+  config,
+  annotations,
+  activeToolId,
+}: AnnotationTargetsProps) {
+  const targets = capability.targets(state, config);
+
+  return (
+    <>
+      {targets.map((t) => (
+        <AnnotationOverlay
+          key={t.id}
+          target={t}
+          scene={annotations.sceneFor(t.id)}
+          meaning={capability.meaning}
+          config={config}
+          activeToolId={activeToolId}
+        />
+      ))}
+    </>
+  );
+}

package/src/annotations/Annotations.less

@@ -0,0 +1,129 @@
+// The box a target takes its marks' input from: transparent, over the target's
+// element, positioned in the surface container the tile rects are measured
+// against. Above the shared buffer, because the buffer takes no input at all.
+.lk-annotate__input {
+  position: absolute;
+  left: var(--lk-anno-x);
+  top: var(--lk-anno-y);
+  width: var(--lk-anno-w);
+  height: var(--lk-anno-h);
+  z-index: 2;
+}
+
+// The sidebar list of marks. One row per mark: what it is, where it is, what
+// it says, and whether it still describes the picture under it.
+.lk-mark-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: var(--wzl-space-xs);
+}
+
+.lk-mark-list__empty {
+  color: var(--wzl-fg-muted);
+  font-size: var(--wzl-font-size-sm);
+}
+
+.lk-mark-list__row {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wzl-space-xs);
+  padding: var(--wzl-space-xs);
+  border: 1px solid var(--wzl-border);
+  border-radius: var(--wzl-radius-sm);
+  background: var(--wzl-surface-raised);
+}
+
+.lk-mark-list__head {
+  display: flex;
+  align-items: center;
+  gap: var(--wzl-space-xs);
+  font-size: var(--wzl-font-size-sm);
+}
+
+.lk-mark-list__target {
+  color: var(--wzl-fg-muted);
+}
+
+.lk-mark-list__stale {
+  color: var(--wzl-warning);
+  font-size: var(--wzl-font-size-xs);
+  text-transform: uppercase;
+}
+
+.lk-mark-list__drop {
+  margin-left: auto;
+  background: none;
+  border: 0;
+  color: var(--wzl-fg-muted);
+  cursor: pointer;
+}
+
+// The export panel: a target to export, how, and at what resolution. Held in
+// a popover because a mark belongs to a target — with more than one pane,
+// "export" on its own does not say what.
+.lk-export__panel {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  align-items: center;
+  gap: var(--wzl-space-xs) var(--wzl-space-sm);
+  min-width: 220px;
+  font-size: var(--wzl-font-size-sm);
+}
+
+.lk-export__title {
+  grid-column: 1 / -1;
+  font-weight: var(--wzl-font-weight-medium);
+}
+
+// A row spans both columns and re-declares the same tracks, so every row's
+// label lines up whether it is a <label> or a <fieldset>: subgrid is what
+// keeps one column definition rather than three copies.
+.lk-export__row {
+  display: grid;
+  grid-column: 1 / -1;
+  grid-template-columns: subgrid;
+  align-items: center;
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  > span:first-child {
+    grid-column: 1;
+    grid-row: 1;
+    color: var(--wzl-fg-muted);
+  }
+
+  > select {
+    grid-column: 2;
+  }
+}
+
+.lk-export__choices {
+  grid-column: 2;
+  grid-row: 1;
+  display: flex;
+  gap: var(--wzl-space-sm);
+
+  label {
+    display: inline-flex;
+    align-items: center;
+    gap: 3px;
+  }
+}
+
+.lk-export__actions {
+  grid-column: 1 / -1;
+  display: flex;
+  gap: var(--wzl-space-xs);
+  margin-top: var(--wzl-space-xs);
+}
+
+.lk-export__error {
+  grid-column: 1 / -1;
+  margin: 0;
+  color: var(--wzl-danger);
+  font-size: var(--wzl-font-size-xs);
+}

package/src/annotations/Annotations.meaning.test.tsx

@@ -0,0 +1,111 @@
+/**
+ * The meaning tier: what a mark says, as opposed to where it is. The store
+ * already carries `title` / `status` / `tags`; this is the chrome over them,
+ * plus the two things a reader needs at a glance — which target a mark is on,
+ * and whether it still describes the picture under it.
+ */
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { AnnotationsContext } from './AnnotationsContext';
+import { MarkList } from './MarkList';
+import { createAnnotationStore } from './store';
+import type { AnnotationMeaning, AnnotationsApi, AnnotationTargetInfo } from './types';
+
+const TARGETS: AnnotationTargetInfo[] = [
+  { id: 'flat', content: { w: 200, h: 100 }, positionDependsOn: ['angle'] },
+  { id: 'shaded', content: { w: 200, h: 100 } },
+];
+
+const MEANING: AnnotationMeaning = {
+  statuses: [
+    { id: 'open', label: 'Open', color: '#e5484d' },
+    { id: 'fixed', label: 'Fixed', color: '#30a46c' },
+  ],
+};
+
+function mount(store: AnnotationsApi, meaning?: AnnotationMeaning, config: unknown = { angle: 0 }) {
+  return render(
+    <AnnotationsContext.Provider value={store}>
+      <MarkList meaning={meaning} config={config} />
+    </AnnotationsContext.Provider>,
+  );
+}
+
+function seeded() {
+  const store = createAnnotationStore({ targets: () => TARGETS });
+  store.add(
+    {
+      target: 'flat',
+      kind: 'rect',
+      frac: { x: 0.1, y: 0.1, w: 0.2, h: 0.2 },
+      title: 'spurious ring',
+      status: 'open',
+    },
+    { angle: 0 },
+  );
+  store.add({ target: 'shaded', kind: 'line', frac: { x: 0.4, y: 0.4, w: 0.2, h: 0 } }, {});
+  return store;
+}
+
+describe('<MarkList>', () => {
+  it('lists every mark, with the target it is on', () => {
+    mount(seeded(), MEANING);
+    const rows = screen.getAllByRole('listitem');
+    expect(rows).toHaveLength(2);
+    expect(rows[0]?.textContent).toContain('flat');
+    expect(rows[1]?.textContent).toContain('shaded');
+  });
+
+  it('writes a status through the store, and re-renders from it', () => {
+    const store = seeded();
+    mount(store, MEANING);
+    const picker = screen.getAllByRole('combobox')[0];
+    if (!picker) throw new Error('no status picker');
+    fireEvent.change(picker, { target: { value: 'fixed' } });
+
+    expect(store.query({ status: 'fixed' })).toHaveLength(1);
+    // The list is not holding its own copy: the value it shows came back out
+    // of the store, which is what makes a mark drawn on the canvas appear here.
+    expect((screen.getAllByRole('combobox')[0] as HTMLSelectElement).value).toBe('fixed');
+  });
+
+  it('renames a mark through the store', () => {
+    const store = seeded();
+    mount(store, MEANING);
+    const field = screen.getAllByRole('textbox')[0];
+    if (!field) throw new Error('no title field');
+    fireEvent.change(field, { target: { value: 'missing edge' } });
+    expect(store.query({ where: (a) => a.title === 'missing edge' })).toHaveLength(1);
+  });
+
+  it("marks a row stale when its target's declared config moved", () => {
+    const store = seeded();
+    // `flat` snapshotted angle 0 and declares it; `shaded` declares nothing
+    // and can never go stale.
+    mount(store, MEANING, { angle: 30 });
+    const rows = screen.getAllByRole('listitem');
+    expect(rows[0]?.textContent).toContain('stale');
+    expect(rows[1]?.textContent).not.toContain('stale');
+  });
+
+  it('drops a mark on request', () => {
+    const store = seeded();
+    mount(store, MEANING);
+    fireEvent.click(screen.getAllByRole('button', { name: /remove/i })[0] as HTMLElement);
+    expect(store.query()).toHaveLength(1);
+    expect(screen.getAllByRole('listitem')).toHaveLength(1);
+  });
+
+  it('still lists marks for an instrument that declared no vocabulary', () => {
+    // No `meaning` is "this host owns what a mark means", not "hide the list".
+    mount(seeded());
+    expect(screen.getAllByRole('listitem')).toHaveLength(2);
+    expect(screen.queryAllByRole('combobox')).toHaveLength(0);
+  });
+
+  it('says so when there are none', () => {
+    mount(createAnnotationStore({ targets: () => TARGETS }), MEANING);
+    expect(screen.queryAllByRole('listitem')).toHaveLength(0);
+    expect(screen.getByText(/no marks/i)).toBeTruthy();
+  });
+});