@weasel-js/labkit 1.6.1 → 1.7.1

package/src/state/useOpenOnce.ts

@@ -10,6 +10,13 @@ interface Entry<T> {
   mounts: number;
 }
 
+function openEntry<T>(open: () => T | Promise<T>): Entry<T> {
+  const result = open();
+  return result instanceof Promise
+    ? { value: null, pending: result, mounts: 0 }
+    : { value: result, pending: null, mounts: 0 };
+}
+
 /**
  * Open something once for a component's lifetime: at once when `open` returns
  * a value, after it settles when it returns a promise. Closed on unmount — but
@@ -18,13 +25,7 @@ interface Entry<T> {
  */
 export function useOpenOnce<T extends Closable>(open: () => T | Promise<T>): T | null {
   const entry = useRef<Entry<T> | null>(null);
-  if (entry.current === null) {
-    const result = open();
-    entry.current =
-      result instanceof Promise
-        ? { value: null, pending: result, mounts: 0 }
-        : { value: result, pending: null, mounts: 0 };
-  }
+  if (entry.current === null) entry.current = openEntry(open);
   const [value, setValue] = useState<T | null>(entry.current.value);
 
   useEffect(() => {
@@ -56,13 +57,16 @@ export function useOpenOnce<T extends Closable>(open: () => T | Promise<T>): T |
 export function useWarnIgnoredChange(component: string, props: Record<string, unknown>): void {
   const first = useRef(props);
   const warned = useRef(false);
-  if (process.env.NODE_ENV === 'production' || warned.current) return;
-  for (const key of Object.keys(props)) {
-    if (Object.is(first.current[key], props[key])) continue;
-    warned.current = true;
-    console.warn(
-      `[labkit] ${component} reads \`${key}\` once, at mount; a later change is ignored`,
-    );
-    return;
-  }
+  // In an effect, so only props that committed are compared.
+  useEffect(() => {
+    if (process.env.NODE_ENV === 'production' || warned.current) return;
+    for (const key of Object.keys(props)) {
+      if (Object.is(first.current[key], props[key])) continue;
+      warned.current = true;
+      console.warn(
+        `[labkit] ${component} reads \`${key}\` once, at mount; a later change is ignored`,
+      );
+      return;
+    }
+  });
 }

package/src/state/usePersistedState.test.tsx

@@ -109,7 +109,7 @@ describe('usePersistedState', () => {
     );
     await screen.findByLabelText('a');
     act(() => screen.getByText('set a').click());
-    expect(shown('b')).toBe('color');
+    await waitFor(() => expect(shown('b')).toBe('color'));
   });
 
   it("re-renders with another tab's write", async () => {

package/src/state/view.ts

@@ -5,6 +5,7 @@ import type { ViewTransform } from '../instrument/types';
  *  other. Re-exported under its own name so a consumer can say which it means. */
 export type ViewTransform2D = ViewTransform;
 
+/** Zoom 1, no pan. */
 export const DEFAULT_VIEW: ViewTransform2D = { zoom: 1, pan: { x: 0, y: 0 } };
 
 /** A trial's view is opaque to labkit, so anything that needs the 2D shape — the

package/src/styles.less

@@ -14,6 +14,7 @@
 @import './primitives/FpsMeter.less';
 @import './primitives/ScaleIndicator.less';
 @import './primitives/Legend.less';
+@import './primitives/Readout.less';
 @import './primitives/FloatingPanel.less';
 @import './lab/Lab.less';
 @import './trial/Trial.less';

package/src/surface/index.ts

@@ -1,4 +1,4 @@
-export { composeRects, rectsEqual } from './composeRects';
+export { composeRects } from './composeRects';
 export { toDeviceRect } from './deviceRect';
 export type { Box, Rect } from './rect';
 export type { SurfaceCanvases, SurfaceLayer } from './SurfaceContext';

package/src/surface/useTiledSurface.test.tsx

@@ -1,4 +1,5 @@
 import { act, render, renderHook } from '@testing-library/react';
+import { renderThenAbandon } from '@weasel-js/react/testing/abandonRender';
 import { useEffect } from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { SurfaceFrame, SurfaceHandle } from './useTiledSurface';
@@ -505,6 +506,19 @@ describe('useTiledSurface', () => {
       expect(clear).toHaveBeenCalledTimes(1);
     });
   });
+  it("hands a frame to the committed owner, never an abandoned render's", () => {
+    const committed: SurfaceFrame[] = [];
+    const abandoned: SurfaceFrame[] = [];
+    const onHandle = (): void => {};
+    renderThenAbandon<HarnessProps>(
+      { frames: committed, onHandle },
+      { frames: abandoned, onHandle },
+      (p) => <Harness {...p} />,
+    );
+    flushFrames();
+    expect(abandoned).toHaveLength(0);
+    expect(committed.length).toBeGreaterThan(0);
+  });
 });
 
 describe('useTiledSurface handle identity', () => {

package/src/surface/useTiledSurface.ts

@@ -1,4 +1,4 @@
-import { useVisibleRaf } from '@weasel-js/core';
+import { useLatest, useVisibleRaf } from '@weasel-js/core';
 import { useCallback, useEffect, useMemo, useRef } from 'react';
 import { composeRects, rectsEqual } from './composeRects';
 import type { Box, Rect } from './rect';
@@ -55,10 +55,19 @@ export type TilePainter = (rect: Rect, frame: SurfaceFrame) => void;
  *  viewport takes. */
 export type SurfaceClear = (size: { width: number; height: number }, dpr: number) => void;
 
+/** Inputs to `useTiledSurface`. `onFrame` runs once per frame that has dirty
+ *  tiles, before any tile paints — the place to size the shared buffer. */
 export interface UseTiledSurfaceOptions {
   onFrame: (frame: SurfaceFrame) => void;
 }
 
+/**
+ * Share one drawing buffer among tiles laid out by the DOM. Tiles register
+ * their elements; the hook measures them against the container, re-measures on
+ * resize, and batches invalidations into one visible-only frame that calls
+ * `onFrame`, then (on a retiled frame) the registered clears, then each dirty
+ * tile's painter.
+ */
 export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHandle {
   const container = useRef<HTMLElement | null>(null);
   const tiles = useRef(new Map<string, HTMLElement>());
@@ -72,8 +81,7 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
 
   // 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 onFrameRef = useLatest(onFrame);
 
   const measure = useCallback((): boolean => {
     const el = container.current;

package/src/theme/Interstellar.stories.tsx

@@ -3,9 +3,11 @@ import type { TokenName } from '@weasel-js/theme';
 import { useTheme } from '@weasel-js/theme/react';
 import { PropertyField, PropertyList, PropertyPanel } from '@weasel-js/ui';
 import './Interstellar.stories.less';
+import { decimal } from '@weasel-js/quantity';
 
 const meta: Meta = {
   title: 'labkit/Themes/Interstellar',
+  tags: ['gallery'],
   parameters: {
     docs: {
       description: {
@@ -150,7 +152,7 @@ function LivePanelPreview() {
             max={1}
             step={0.01}
             onChange={() => {}}
-            format={(v) => v.toFixed(2)}
+            display={decimal({ places: 2 })}
           />
           <PropertyField kind="color" label="Fill" value="#b08adb" onChange={() => {}} />
           <PropertyField kind="color" label="Stroke" value="#1a1428" onChange={() => {}} />

package/src/theme/base.less

@@ -1,6 +1,10 @@
 // The Oswald and Inter faces come from @weasel-js/theme/faces.css, imported at
 // the top of styles.less.
 
+// weasel-ui's native range skin, read for `:extend` below and emitted only
+// through it.
+@import (reference, less) '../../../ui/src/components/range.module.css';
+
 // Resets and global element defaults.
 .lk-root {
   font-family: var(--wzl-font-ui);
@@ -21,7 +25,10 @@
 // Deliberate overrides of a weasel-ui component go the other way — see the
 // `.lk-root` prefix convention below.
 :where(.lk-root) {
-  :where(button) {
+  // Only a button with no class or a labkit one. Specificity cannot keep this
+  // off a weasel-ui button: whatever its module leaves unset — a height, a
+  // backdrop blur — the default fills in.
+  :where(button:not([class]), button[class^='lk-'], button[class*=' lk-']) {
     font: inherit;
     color: inherit;
     background: var(--wzl-surface-raised);
@@ -33,63 +40,32 @@
     backdrop-filter: blur(var(--wzl-glass-blur));
     -webkit-backdrop-filter: blur(var(--wzl-glass-blur));
 
-    &:hover {
+    &:where(:hover) {
       border-color: var(--wzl-accent);
       color: var(--wzl-accent-fg);
     }
 
-    &:focus-visible {
+    &:where(:focus-visible) {
       outline: 2px solid var(--wzl-focus-ring);
       outline-offset: 1px;
     }
 
-    &:disabled {
+    &:where(:disabled) {
       color: var(--wzl-fg-subtle);
       cursor: not-allowed;
     }
   }
 
-  // Mirrors packages/ui/src/components/range.module.css so a consumer's bare
-  // range matches the kit's. A weasel-ui component's own module class outranks
-  // this, which is what keeps InlineRange's gradient track intact.
-  :where(input[type="range"]) {
-    appearance: none;
-    -webkit-appearance: none;
-    height: 12px;
-    background: transparent;
-    cursor: pointer;
-
-    &::-webkit-slider-runnable-track {
-      height: var(--wzl-slider-track-h);
-      border-radius: var(--wzl-radius-sm);
-      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-track-mix), transparent);
-    }
-
-    &::-moz-range-track {
-      height: var(--wzl-slider-track-h);
-      border-radius: var(--wzl-radius-sm);
-      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-track-mix), transparent);
-    }
-
-    &::-webkit-slider-thumb {
-      appearance: none;
-      -webkit-appearance: none;
-      width: var(--wzl-slider-thumb-size);
-      height: var(--wzl-slider-thumb-size);
-      border: none;
-      border-radius: 50%;
-      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-thumb-mix), transparent);
-      margin-top: calc((var(--wzl-slider-track-h) - var(--wzl-slider-thumb-size)) / 2);
-    }
-
-    &::-moz-range-thumb {
-      width: var(--wzl-slider-thumb-size);
-      height: var(--wzl-slider-thumb-size);
-      border: none;
-      border-radius: 50%;
-      background: color-mix(in srgb, var(--wzl-accent) var(--wzl-slider-thumb-mix), transparent);
-    }
+  // The browser sets these in its own `monospace`, which no font token reaches.
+  :where(code, kbd, samp, pre) {
+    font-family: var(--wzl-font-mono);
   }
+
+  // A consumer's bare range wears weasel-ui's range skin, extended from its one
+  // definition rather than copied. The skin keeps its pseudo-classes inside
+  // :where(), so nothing this emits outranks a single class and a weasel-ui
+  // component's own module class still wins.
+  :where(input[type="range"]):extend(.range all) {}
 }
 
 // The `.lk-root` prefix convention: a labkit class handed to a weasel-ui
@@ -151,9 +127,7 @@
 }
 
 // Headline / display text uses Oswald light at tighter line-height.
-.lk-lab h1,
-.lk-lab h2,
-.lk-lab h3 {
+:where(.lk-lab) :where(h1, h2, h3) {
   font-family: var(--wzl-font-display);
   font-weight: var(--wzl-font-weight-light);
   letter-spacing: 0.01em;

package/src/theme/interstellar.test.ts

@@ -18,7 +18,7 @@ describe('interstellarTheme', () => {
 
     // Values carried over verbatim from the retired Less.
     expect(dark['--wzl-surface']).toBe('#0a0a14');
-    expect(dark['--wzl-accent']).toBe('#b08adb');
+    expect(dark['--wzl-accent']).toBe('#4f46e5');
     // Light mode is weasel's own: interstellar restyles the dark only.
     const weasel = resolveTheme(weaselTheme, { mode: 'light' });
     expect(light['--wzl-surface']).toBe(weasel['--wzl-surface']);

package/src/theme/interstellar.theme.json

@@ -81,21 +81,28 @@
     "accent": {
       "by": "mode",
       "dark": {
-        "value": "#b08adb",
+        "value": "#4f46e5",
         "type": "color"
       }
     },
     "accent-hover": {
       "by": "mode",
       "dark": {
-        "value": "#c6a3ee",
+        "value": "#6d5dfc",
+        "type": "color"
+      }
+    },
+    "accent-strong": {
+      "by": "mode",
+      "dark": {
+        "value": "#7474fe",
         "type": "color"
       }
     },
     "focus-ring": {
       "by": "mode",
       "dark": {
-        "value": "rgba(176, 138, 219, 0.45)",
+        "value": "rgba(116, 116, 254, 0.5)",
         "type": "color"
       }
     },

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

@@ -180,6 +180,79 @@ describe('the trial undo chrome over marks', () => {
   });
 });
 
+function GrowingPane({ n, grow }: { n: number; grow: () => void }) {
+  const api = useAnnotations();
+  return (
+    <button type="button" data-testid="growing" data-targets={api.targets().length} onClick={grow}>
+      {n}
+    </button>
+  );
+}
+
+describe('targets that follow the trial state', () => {
+  it('reach a reader of the store once the change commits', () => {
+    // The store reads the committed state, so a reader rendering in the same
+    // pass as the change sees the one before; the trial tells it to read again.
+    const growing = defineInstrument<{ n: number }, Record<string, never>>({
+      name: 'Growing',
+      defaultConfig: () => ({}),
+      initialState: () => ({ n: 1 }),
+      render: (ctx) => (
+        <GrowingPane n={ctx.state.n} grow={() => ctx.setState((s) => ({ n: s.n + 1 }))} />
+      ),
+      annotations: {
+        targets: (state) =>
+          Array.from({ length: state.n }, (_, i) => ({
+            id: `t${i}`,
+            ref: { current: null },
+            content: { w: 10, h: 10 },
+          })),
+      },
+    });
+    render(<Lab instruments={[growing]} defaultInstrument="Growing" />);
+    expect(screen.getByTestId('growing').dataset.targets).toBe('1');
+    act(() => {
+      fireEvent.click(screen.getByTestId('growing'));
+    });
+    expect(screen.getByTestId('growing').textContent).toBe('2');
+    expect(screen.getByTestId('growing').dataset.targets).toBe('2');
+  });
+});
+
+describe("the capability's selection mode", () => {
+  const twoTargets = (selection?: 'per-target') =>
+    defineInstrument<Record<string, never>, Record<string, never>>({
+      ...annotating,
+      name: 'Two',
+      annotations: {
+        targets: () => [
+          { id: 'a', ref: { current: null }, content: { w: 200, h: 100 } },
+          { id: 'b', ref: { current: null }, content: { w: 200, h: 100 } },
+        ],
+        ...(selection ? { selection } : {}),
+      },
+    });
+  const selectBoth = (): readonly string[] => {
+    const onA = marks().add({ target: 'a', kind: 'rect', frac: { x: 0, y: 0, w: 0.1, h: 0.1 } });
+    const onB = marks().add({ target: 'b', kind: 'rect', frac: { x: 0, y: 0, w: 0.1, h: 0.1 } });
+    act(() => marks().setSelection([onA, onB]));
+    return [onA, onB];
+  };
+
+  it('keeps the selection to one target by default', () => {
+    render(<Lab instruments={[twoTargets()]} defaultInstrument="Two" />);
+    const [onA] = selectBoth();
+    expect(marks().selection()).toEqual([onA]);
+  });
+
+  it("reaches the trial's store when the instrument asks for per-target", () => {
+    render(<Lab instruments={[twoTargets('per-target')]} defaultInstrument="Two" />);
+    expect(marks().selection()).toEqual([]);
+    const both = selectBoth();
+    expect(marks().selection()).toEqual(both);
+  });
+});
+
 describe('an instrument that declares none', () => {
   it('gets no store and no palette', () => {
     render(<Lab instruments={[plain]} defaultInstrument="Plain" />);

package/src/trial/Trial.less

@@ -76,22 +76,6 @@
     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;
   }
@@ -109,19 +93,6 @@
   }
 }
 
-.lk-toolbar__zoom-label {
-  font-size: var(--wzl-font-size-sm);
-  color: var(--wzl-fg-muted);
-  padding: 0 var(--wzl-space-sm);
-}
-
-.lk-sidebar__placeholder {
-  padding: var(--wzl-space-sm);
-  color: var(--wzl-fg-muted);
-  font-size: var(--wzl-font-size-sm);
-}
-
-
 .lk-trial__titlebar {
   display: flex;
   align-items: center;

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

@@ -3,6 +3,7 @@ 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';
+import { TrialLoupe } from '../loupe';
 
 beforeAll(() => {
   HTMLCanvasElement.prototype.getContext = vi.fn(() => ({
@@ -21,17 +22,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,7 +52,7 @@ function pointAt(host: Element, x: number, y: number): void {
   fireEvent.pointerMove(host, { clientX: x, clientY: y });
 }
 
-describe('the loupe capability', () => {
+describe('a lens the instrument mounts', () => {
   it('gives a trial a toolbar toggle, and no lens until it is on', () => {
     const { container } = render(
       <Lab instruments={[canvasInstrument]} defaultInstrument="Drawn" />,
@@ -58,7 +61,7 @@ describe('the loupe capability', () => {
     expect(lens(container)).toBeNull();
   });
 
-  it('offers nothing to an instrument that declares none', () => {
+  it('offers nothing to an instrument that mounts none', () => {
     render(<Lab instruments={[noLoupe]} defaultInstrument="Plain" />);
     expect(screen.queryByRole('button', { name: 'Loupe' })).toBeNull();
   });
@@ -95,7 +98,7 @@ describe('the loupe capability', () => {
     const { container } = render(<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,9 +108,24 @@ describe('the loupe capability', () => {
     expect(screen.getByTestId('body')).toBeInTheDocument();
   });
 
-  it('wraps a DOM instrument only when it declares a loupe', () => {
+  it('wraps nothing for an instrument that mounts no lens', () => {
     const { container } = render(<Lab instruments={[noLoupe]} defaultInstrument="Plain" />);
-    expect(container.querySelector('.lk-trial__loupe-host')).toBeNull();
+    expect(container.querySelector('.lk-loupe-host')).toBeNull();
+  });
+
+  it('raises a lens told `enabled` without the trial toggle', () => {
+    const always = defineInstrument<Record<string, never>, Record<string, never>>({
+      name: 'Always',
+      defaultConfig: () => ({}),
+      initialState: () => ({}),
+      render: () => <TrialLoupe enabled />,
+      canvas: { layers: [{ id: 'main', draw: () => undefined }] },
+    });
+    const { container } = render(<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 () => {
@@ -136,7 +154,7 @@ describe('the loupe and the trial camera share one dispatcher', () => {
       name: 'Zoomed',
       defaultConfig: () => ({}),
       initialState: () => ({}),
-      render: () => null,
+      render: () => <TrialLoupe />,
       canvas: {
         layers: [
           {
@@ -147,7 +165,6 @@ describe('the loupe and the trial camera share one dispatcher', () => {
           },
         ],
       },
-      loupe: true,
     });
     const r = render(<Lab instruments={[drawn]} defaultInstrument="Zoomed" />);
     const stack = r.container.querySelector('.lk-canvas-stack');