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

package/src/surface/deviceRect.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { toDeviceRect } from './deviceRect';
+
+const onGrid = (v: number, dpr: number) => Math.abs(v * dpr - Math.round(v * dpr)) < 1e-9;
+
+describe('toDeviceRect', () => {
+  it('measures y from the bottom of the surface', () => {
+    const r = toDeviceRect({ x: 0, y: 0, w: 40, h: 10 }, 100, 1);
+    expect(r.y).toBe(90);
+    expect(r.h).toBe(10);
+  });
+
+  it('leaves x and width alone', () => {
+    const r = toDeviceRect({ x: 5, y: 0, w: 40, h: 10 }, 100, 1);
+    expect(r.x).toBe(5);
+    expect(r.w).toBe(40);
+  });
+
+  it('puts every edge on the device grid', () => {
+    const r = toDeviceRect({ x: 33.3, y: 7.7, w: 33.3, h: 21.4 }, 100, 2);
+    expect(onGrid(r.x, 2)).toBe(true);
+    expect(onGrid(r.x + r.w, 2)).toBe(true);
+    expect(onGrid(r.y, 2)).toBe(true);
+    expect(onGrid(r.y + r.h, 2)).toBe(true);
+  });
+
+  it('does not strand a column between neighbours', () => {
+    const a = toDeviceRect({ x: 0, y: 0, w: 33.3333, h: 10 }, 100, 2);
+    const b = toDeviceRect({ x: 33.3333, y: 0, w: 33.3333, h: 10 }, 100, 2);
+    const c = toDeviceRect({ x: 66.6666, y: 0, w: 33.3334, h: 10 }, 100, 2);
+    expect(a.x + a.w).toBe(b.x);
+    expect(b.x + b.w).toBe(c.x);
+  });
+
+  it('snaps a stacked pair without overlapping them', () => {
+    const top = toDeviceRect({ x: 0, y: 0, w: 10, h: 33.3333 }, 100, 3);
+    const bottom = toDeviceRect({ x: 0, y: 33.3333, w: 10, h: 33.3333 }, 100, 3);
+    expect(bottom.y + bottom.h).toBe(top.y);
+  });
+});

package/src/surface/deviceRect.ts

@@ -0,0 +1,19 @@
+import type { Rect } from './rect';
+
+/**
+ * A DOM rect as a GL viewport rect: origin at the bottom-left, every edge snapped
+ * to the device-pixel grid. Still CSS pixels, because three.js applies its own
+ * pixel ratio — snapping here is what stops a tile and its neighbour rounding
+ * apart and leaving a hairline column between them.
+ */
+export function toDeviceRect(rect: Rect, surfaceHeight: number, dpr: number): Rect {
+  const snap = (v: number) => Math.round(v * dpr) / dpr;
+  const x = snap(rect.x);
+  const y = snap(surfaceHeight - rect.y - rect.h);
+  return {
+    x,
+    y,
+    w: snap(rect.x + rect.w) - x,
+    h: snap(surfaceHeight - rect.y) - y,
+  };
+}

package/src/surface/index.ts

@@ -0,0 +1,7 @@
+export { composeRects, rectsEqual } from './composeRects';
+export { toDeviceRect } from './deviceRect';
+export type { Box, Rect } from './rect';
+export { SurfaceContext } from './SurfaceContext';
+export { useSurface, useSurfaceOptional, useSurfaceTile } from './useSurfaceTile';
+export type { SurfaceFrame, SurfaceHandle, UseTiledSurfaceOptions } from './useTiledSurface';
+export { useTiledSurface } from './useTiledSurface';

package/src/surface/rect.ts

@@ -0,0 +1,16 @@
+/** A box in CSS pixels, measured from the surface's own top-left corner. */
+export interface Rect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** The subset of `DOMRect` this package reads. Accepting the subset rather than
+ *  `DOMRect` is what lets the pure functions be tested without a DOM. */
+export interface Box {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}

package/src/surface/useSurfaceTile.test.tsx

@@ -0,0 +1,67 @@
+import { render } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { SurfaceContext } from './SurfaceContext';
+import { useSurface, useSurfaceOptional, useSurfaceTile } from './useSurfaceTile';
+import type { SurfaceHandle } from './useTiledSurface';
+
+function fakeHandle(): SurfaceHandle {
+  return {
+    invalidate: vi.fn(),
+    invalidateAll: vi.fn(),
+    invalidateRects: vi.fn(),
+    registerTile: vi.fn(),
+    containerRef: vi.fn(),
+  };
+}
+
+function Tile({ id }: { id: string }) {
+  const ref = useSurfaceTile(id);
+  return <div ref={ref} data-testid={id} />;
+}
+
+describe('useSurfaceTile', () => {
+  it('registers its element with the surface on mount', () => {
+    const handle = fakeHandle();
+    const { getByTestId } = render(
+      <SurfaceContext.Provider value={handle}>
+        <Tile id="a" />
+      </SurfaceContext.Provider>,
+    );
+    expect(handle.registerTile).toHaveBeenCalledWith('a', getByTestId('a'));
+  });
+
+  it('unregisters on unmount', () => {
+    const handle = fakeHandle();
+    const { unmount } = render(
+      <SurfaceContext.Provider value={handle}>
+        <Tile id="a" />
+      </SurfaceContext.Provider>,
+    );
+    unmount();
+    expect(handle.registerTile).toHaveBeenCalledWith('a', null);
+  });
+
+  it('is inert with no surface above it, so a 2D lab is unaffected', () => {
+    expect(() => render(<Tile id="a" />)).not.toThrow();
+  });
+});
+
+describe('useSurface', () => {
+  it('throws outside a provider, because a caller asking for it needs one', () => {
+    function Consumer() {
+      useSurface();
+      return null;
+    }
+    expect(() => render(<Consumer />)).toThrow(/requires a surface/i);
+  });
+
+  it('returns null from the optional form outside a provider', () => {
+    let seen: SurfaceHandle | null | undefined;
+    function Consumer() {
+      seen = useSurfaceOptional();
+      return null;
+    }
+    render(<Consumer />);
+    expect(seen).toBeNull();
+  });
+});

package/src/surface/useSurfaceTile.ts

@@ -0,0 +1,32 @@
+import { useCallback, useContext } from 'react';
+import { SurfaceContext } from './SurfaceContext';
+import type { SurfaceHandle } from './useTiledSurface';
+
+/** The surface above, or null. Use this where a surface is genuinely optional. */
+export function useSurfaceOptional(): SurfaceHandle | null {
+  return useContext(SurfaceContext);
+}
+
+/** The surface above. Throws where a caller cannot work without one. */
+export function useSurface(): SurfaceHandle {
+  const surface = useContext(SurfaceContext);
+  if (!surface) throw new Error('[labkit] useSurface requires a surface owner above it');
+  return surface;
+}
+
+/**
+ * A ref callback that publishes this element's rect to the surface under `id`.
+ *
+ * Attach it to whichever element the surface should draw into — that is not
+ * necessarily the trial's own element, since a trial may hold a drawn pane beside
+ * an undrawn one, or none at all.
+ */
+export function useSurfaceTile(id: string): (el: HTMLElement | null) => void {
+  const surface = useSurfaceOptional();
+  return useCallback(
+    (el: HTMLElement | null) => {
+      surface?.registerTile(id, el);
+    },
+    [surface, id],
+  );
+}

package/src/surface/useTiledSurface.test.tsx

@@ -0,0 +1,231 @@
+import { act, render } from '@testing-library/react';
+import { useEffect } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { SurfaceFrame, SurfaceHandle } from './useTiledSurface';
+import { useTiledSurface } from './useTiledSurface';
+
+/** jsdom measures everything as zero, so each element is given a box by hand. */
+function stubBox(el: HTMLElement, left: number, top: number, width: number, height: number): void {
+  vi.spyOn(el, 'getBoundingClientRect').mockReturnValue({
+    left,
+    top,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as DOMRect);
+}
+
+interface HarnessProps {
+  frames: SurfaceFrame[];
+  onHandle: (h: SurfaceHandle) => void;
+}
+
+function Harness({ frames, onHandle }: HarnessProps) {
+  const surface = useTiledSurface({
+    onFrame: (f) => {
+      frames.push(f);
+    },
+  });
+  useEffect(() => {
+    onHandle(surface);
+  }, [surface, onHandle]);
+  return (
+    <div
+      data-testid="stage"
+      ref={(el) => {
+        if (!el) return;
+        stubBox(el, 0, 0, 800, 600);
+        surface.containerRef(el);
+      }}
+    >
+      <div
+        data-testid="a"
+        ref={(el) => {
+          if (!el) return;
+          stubBox(el, 0, 0, 400, 600);
+          surface.registerTile('a', el);
+        }}
+      />
+      <div
+        data-testid="b"
+        ref={(el) => {
+          if (!el) return;
+          stubBox(el, 400, 0, 400, 600);
+          surface.registerTile('b', el);
+        }}
+      />
+    </div>
+  );
+}
+
+/** Runs every pending rAF callback. */
+function flushFrames(): void {
+  act(() => {
+    vi.advanceTimersByTime(64);
+  });
+}
+
+describe('useTiledSurface', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) =>
+      setTimeout(() => cb(0), 16),
+    );
+    vi.stubGlobal('cancelAnimationFrame', (id: number) => clearTimeout(id));
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it('coalesces three invalidations in one tick into a single frame', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    act(() => {
+      handle?.invalidate('a');
+      handle?.invalidate('b');
+      handle?.invalidate('a');
+    });
+    flushFrames();
+
+    expect(frames).toHaveLength(1);
+    expect([...(frames[0]?.dirty ?? [])].sort()).toEqual(['a', 'b']);
+  });
+
+  it('fires nothing on a clean tick', () => {
+    const frames: SurfaceFrame[] = [];
+    render(<Harness frames={frames} onHandle={() => {}} />);
+    flushFrames();
+    frames.length = 0;
+    flushFrames();
+    expect(frames).toHaveLength(0);
+  });
+
+  it('carries every tile rect, not only the dirty ones', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    act(() => handle?.invalidate('a'));
+    flushFrames();
+
+    expect([...(frames[0]?.dirty ?? [])]).toEqual(['a']);
+    expect(frames[0]?.rects.get('b')).toEqual({ x: 400, y: 0, w: 400, h: 600 });
+  });
+
+  it('reports the surface size and dpr', () => {
+    vi.stubGlobal('devicePixelRatio', 3);
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    act(() => handle?.invalidateAll());
+    flushFrames();
+
+    expect(frames[0]?.dpr).toBe(3);
+    expect(frames[0]?.size).toEqual({ width: 800, height: 600 });
+  });
+
+  it('marks every tile dirty when the dpr changes', () => {
+    vi.stubGlobal('devicePixelRatio', 1);
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    vi.stubGlobal('devicePixelRatio', 2);
+    act(() => handle?.invalidateRects());
+    flushFrames();
+
+    expect([...(frames[0]?.dirty ?? [])].sort()).toEqual(['a', 'b']);
+    expect(frames[0]?.dpr).toBe(2);
+  });
+
+  it('re-measures on invalidateRects, which is how a moved tile is caught', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    const { getByTestId } = render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    // A sibling reflow slides tile b left. ResizeObserver sees no size change.
+    stubBox(getByTestId('b'), 320, 0, 400, 600);
+
+    act(() => handle?.invalidateRects());
+    flushFrames();
+
+    expect(frames[0]?.rects.get('b')).toEqual({ x: 320, y: 0, w: 400, h: 600 });
+  });
+
+  it('drops a tile that unregisters', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+    frames.length = 0;
+
+    act(() => {
+      handle?.registerTile('b', null);
+      handle?.invalidate('a');
+    });
+    flushFrames();
+
+    expect(frames[0]?.rects.has('b')).toBe(false);
+  });
+});

package/src/surface/useTiledSurface.ts

@@ -0,0 +1,161 @@
+import { useVisibleRaf } from '@weasel-js/core';
+import { useCallback, useEffect, useRef } from 'react';
+import { composeRects, rectsEqual } from './composeRects';
+import type { Box, Rect } from './rect';
+
+/** What a surface owner is handed once per animation frame. `rects` carries every
+ *  tile, not only the dirty ones: a scissored draw has to know where it is drawing
+ *  relative to a surface that may have resized under it. */
+export interface SurfaceFrame {
+  dirty: ReadonlySet<string>;
+  rects: ReadonlyMap<string, Rect>;
+  dpr: number;
+  size: { width: number; height: number };
+}
+
+/** The invalidators and the two ref callbacks that publish geometry. */
+export interface SurfaceHandle {
+  /** Mark one tile for redraw. */
+  invalidate: (id: string) => void;
+  /** Mark every tile — what a resize or a tile-set change means. */
+  invalidateAll: () => void;
+  /** Re-measure before the next frame. The escape hatch for a host that knows it
+   *  moved something a ResizeObserver cannot see. */
+  invalidateRects: () => void;
+  registerTile: (id: string, el: HTMLElement | null) => void;
+  containerRef: (el: HTMLElement | null) => void;
+}
+
+export interface UseTiledSurfaceOptions {
+  onFrame: (frame: SurfaceFrame) => void;
+}
+
+export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHandle {
+  const container = useRef<HTMLElement | null>(null);
+  const tiles = useRef(new Map<string, HTMLElement>());
+  const rects = useRef(new Map<string, Rect>());
+  const dirty = useRef(new Set<string>());
+  const needsMeasure = useRef(true);
+  const observer = useRef<ResizeObserver | null>(null);
+  const lastDpr = useRef(0);
+
+  // Held in a ref so a caller passing an inline closure does not re-create every
+  // callback below on each render.
+  const onFrameRef = useRef(onFrame);
+  onFrameRef.current = onFrame;
+
+  const measure = useCallback((): boolean => {
+    const el = container.current;
+    if (!el) return false;
+    const boxes = new Map<string, Box>();
+    for (const [id, tile] of tiles.current) boxes.set(id, tile.getBoundingClientRect());
+    const next = composeRects(el.getBoundingClientRect(), boxes);
+    let changed = next.size !== rects.current.size;
+    for (const [id, rect] of next) {
+      if (!rectsEqual(rects.current.get(id), rect)) changed = true;
+    }
+    rects.current = next;
+    return changed;
+  }, []);
+
+  const frameLoop = useVisibleRaf(
+    () => {
+      const el = container.current;
+      if (!el) {
+        dirty.current.clear();
+        return;
+      }
+      if (needsMeasure.current) {
+        needsMeasure.current = false;
+        if (measure()) for (const id of rects.current.keys()) dirty.current.add(id);
+      }
+      const dpr = globalThis.devicePixelRatio ?? 1;
+      if (dpr !== lastDpr.current) {
+        lastDpr.current = dpr;
+        for (const id of rects.current.keys()) dirty.current.add(id);
+      }
+      if (dirty.current.size === 0) return;
+      const box = el.getBoundingClientRect();
+      onFrameRef.current({
+        dirty: new Set(dirty.current),
+        rects: new Map(rects.current),
+        dpr,
+        size: { width: box.width, height: box.height },
+      });
+      dirty.current.clear();
+    },
+    // The host attaches its container through `containerRef`, which may land
+    // well after this hook's first effect; the gate re-resolves it per request.
+    { target: () => container.current },
+  );
+
+  const schedule = useCallback(() => {
+    frameLoop.request();
+  }, [frameLoop]);
+
+  const invalidate = useCallback(
+    (id: string) => {
+      dirty.current.add(id);
+      schedule();
+    },
+    [schedule],
+  );
+
+  const invalidateAll = useCallback(() => {
+    for (const id of tiles.current.keys()) dirty.current.add(id);
+    schedule();
+  }, [schedule]);
+
+  const invalidateRects = useCallback(() => {
+    needsMeasure.current = true;
+    schedule();
+  }, [schedule]);
+
+  const registerTile = useCallback(
+    (id: string, el: HTMLElement | null) => {
+      const known = tiles.current.get(id);
+      if (known === el) return;
+      if (known) observer.current?.unobserve(known);
+      if (el) {
+        tiles.current.set(id, el);
+        observer.current?.observe(el);
+      } else {
+        tiles.current.delete(id);
+        rects.current.delete(id);
+        dirty.current.delete(id);
+      }
+      needsMeasure.current = true;
+      schedule();
+    },
+    [schedule],
+  );
+
+  const containerRef = useCallback(
+    (el: HTMLElement | null) => {
+      if (container.current === el) return;
+      if (container.current) observer.current?.unobserve(container.current);
+      container.current = el;
+      if (el) observer.current?.observe(el);
+      needsMeasure.current = true;
+      schedule();
+    },
+    [schedule],
+  );
+
+  useEffect(() => {
+    const ro = new ResizeObserver(() => {
+      needsMeasure.current = true;
+      schedule();
+    });
+    observer.current = ro;
+    if (container.current) ro.observe(container.current);
+    for (const el of tiles.current.values()) ro.observe(el);
+    return () => {
+      ro.disconnect();
+      observer.current = null;
+      frameLoop.cancel();
+    };
+  }, [schedule, frameLoop]);
+
+  return { invalidate, invalidateAll, invalidateRects, registerTile, containerRef };
+}

package/src/test-setup.ts

@@ -31,6 +31,32 @@ if (typeof globalThis.ResizeObserver === 'undefined') {
   } as unknown as typeof ResizeObserver;
 }
 
+// jsdom ships no PointerEvent, so `fireEvent.pointerDown` builds a bare Event
+// and drops clientX/clientY — a drag handler then reads `undefined` and computes
+// NaN deltas, which the DOM rejects as invalid CSS rather than reporting.
+// MouseEvent already carries the coordinate fields.
+if (typeof globalThis.PointerEvent === 'undefined') {
+  class PointerEventPolyfill extends MouseEvent {
+    readonly pointerId: number;
+    readonly pointerType: string;
+    readonly isPrimary: boolean;
+    constructor(type: string, init: PointerEventInit = {}) {
+      super(type, init);
+      this.pointerId = init.pointerId ?? 1;
+      this.pointerType = init.pointerType ?? 'mouse';
+      this.isPrimary = init.isPrimary ?? true;
+    }
+  }
+  globalThis.PointerEvent = PointerEventPolyfill as unknown as typeof PointerEvent;
+}
+
+// jsdom implements neither side of pointer capture.
+if (typeof Element.prototype.setPointerCapture === 'undefined') {
+  Element.prototype.setPointerCapture = () => {};
+  Element.prototype.releasePointerCapture = () => {};
+  Element.prototype.hasPointerCapture = () => false;
+}
+
 afterEach(() => {
   cleanup();
 });

package/src/theme/base.less

@@ -16,6 +16,10 @@
 
 // Resets and global element defaults.
 .lk-root {
+  // labkit's own vocabulary over the theme's raw scale — named for the thing
+  // rather than the step, so "the workspace is too tight" has one place to go.
+  --lk-workspace-pad: var(--wzl-space-sm);
+
   font-family: var(--wzl-font-ui);
   font-size: var(--wzl-font-size);
   font-weight: var(--wzl-font-weight-light);
@@ -26,8 +30,15 @@
   *, *::before, *::after {
     box-sizing: border-box;
   }
+}
 
-  button {
+// Defaults for labkit's own bare markup. `.lk-root` is inside :where() too, so
+// the whole selector scores (0,0,0): a weasel-ui module class beats it on
+// specificity instead of on which stylesheet happened to be injected last.
+// Deliberate overrides of a weasel-ui component go the other way — see the
+// `.lk-root` prefix convention below.
+:where(.lk-root) {
+  :where(button) {
     font: inherit;
     color: inherit;
     background: var(--wzl-surface-raised);
@@ -55,11 +66,17 @@
     }
   }
 
-  input[type="range"] {
+  :where(input[type="range"]) {
     accent-color: var(--wzl-accent);
   }
 }
 
+// The `.lk-root` prefix convention: a labkit class handed to a weasel-ui
+// component through `className` lands beside that component's own CSS-module
+// class at equal specificity, so injection order — not intent — decides the
+// winner. Prefixing with `.lk-root` scores (0,2,0) and settles it. Use it only
+// where labkit means to override the component; plain `.lk-*` elsewhere.
+
 // Cosmic background applied to the Lab root. The starscape sits as a fixed
 // pseudo-element so panning the trial doesn't shift the field of stars.
 .lk-lab {

package/src/theme/interstellar.tokens.json

@@ -28,7 +28,9 @@
         "fg-subtle": { "$value": "#5a5a78" },
         "accent": { "$value": "#b08adb" },
         "accent-hover": { "$value": "#c6a3ee" },
-        "focus-ring": { "$value": "rgba(176, 138, 219, 0.45)" }
+        "focus-ring": { "$value": "rgba(176, 138, 219, 0.45)" },
+        "shadow": { "$value": "rgba(0, 0, 0, 0.7)" },
+        "border-raised": { "$value": "rgba(255, 255, 255, 0.36)" }
       },
       "gradient": {
         "$type": "gradient",
@@ -50,7 +52,9 @@
         "fg-subtle": { "$value": "#a89b85" },
         "accent": { "$value": "#a86f3c" },
         "accent-hover": { "$value": "#c2854f" },
-        "focus-ring": { "$value": "rgba(168, 111, 60, 0.35)" }
+        "focus-ring": { "$value": "rgba(168, 111, 60, 0.35)" },
+        "shadow": { "$value": "rgba(80, 60, 40, 0.18)" },
+        "border-raised": { "$value": "#9e8b71" }
       }
     }
   }