@weasel-js/labkit 1.7.0 → 1.7.2

package/src/overview/TrialOverview.test.tsx

@@ -7,8 +7,9 @@
  * centering puts the pressed world point at the stage's origin instead.
  */
 
-import { act, render } from '@testing-library/react';
+import { act } from '@testing-library/react';
 import type { PointerContextValue } from '@weasel-js/core';
+import { renderSettled } from '@weasel-js/react/testing/renderSettled';
 import { beforeAll, describe, expect, it, vi } from 'vitest';
 import { defineInstrument } from '../instrument/defineInstrument';
 import { Lab } from '../lab/Lab';
@@ -40,7 +41,7 @@ function pointer(el: Element, type: string, x: number, y: number, buttons = 1) {
 
 /** Content 400×300 in a 200×150 box, 6px in: scale 0.46, so box (100, 75)
  *  is content (200, 150). */
-function mount() {
+async function mount() {
   let store: PointerContextValue | null = null;
   const pictured = defineInstrument<Record<string, never>, Record<string, never>>({
     name: 'Pictured',
@@ -57,7 +58,7 @@ function mount() {
       ),
     },
   });
-  const r = render(<Lab instruments={[pictured]} defaultInstrument="Pictured" />);
+  const r = await renderSettled(<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');
@@ -67,15 +68,15 @@ function mount() {
 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();
+  it('draws the instrument-supplied content, not the instrument itself', async () => {
+    const h = await 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(() => {
+  it('moves the stage camera to the pressed point', async () => {
+    const h = await mount();
+    await act(async () => {
       pointer(h.box, 'pointerdown', 100, 75);
       pointer(h.box, 'pointerup', 100, 75, 0);
     });
@@ -83,9 +84,9 @@ describe('<TrialOverview>', () => {
     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(() => {
+  it('follows a drag with the camera, and never pans the stage by it', async () => {
+    const h = await mount();
+    await act(async () => {
       pointer(h.box, 'pointerdown', 100, 75);
       pointer(h.box, 'pointermove', 110, 75);
       pointer(h.box, 'pointermove', 123, 75);
@@ -96,9 +97,9 @@ describe('<TrialOverview>', () => {
     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));
+  it("publishes the pointer over it as the overview's, and the stage draws it", async () => {
+    const h = await mount();
+    await act(async () => pointer(h.box, 'pointermove', 100, 75, 0));
     const p = h.store()?.get();
     expect(p?.viewId).toBe('overview');
     expect(p?.worldX).toBeCloseTo(200);
@@ -106,10 +107,10 @@ describe('<TrialOverview>', () => {
     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();
+  it("publishes the stage's pointer as the stage's, so the stage draws none", async () => {
+    const h = await mount();
     const host = h.container.querySelector('.lk-stage') as HTMLElement;
-    act(() => pointer(host, 'pointermove', 10, 10, 0));
+    await act(async () => pointer(host, 'pointermove', 10, 10, 0));
     expect(h.store()?.get()?.viewId).toBe('stage');
     expect(h.container.querySelector('.lk-stage .lk-linked-cursor')).toBeNull();
   });

package/src/overview/TrialOverview.tsx

@@ -20,6 +20,7 @@ import {
   useActionsRegistry,
   useDepSource,
   useGestureDispatcher,
+  useLatest,
   usePointerPosition,
   type View,
   type ViewApi,
@@ -314,8 +315,7 @@ function OverviewDispatch({
   camera: CameraContextValue;
 }) {
   const registry = useActionsRegistry();
-  const fitRef = useRef(fit);
-  fitRef.current = fit;
+  const fitRef = useLatest(fit);
   const root = camera.view;
   useDepSource('rootView', () => root as ViewApi);
 
@@ -336,7 +336,7 @@ function OverviewDispatch({
         y: (cy - (r?.top ?? 0)) / f.scale.y + f.y,
       };
     },
-    [boxRef],
+    [boxRef, fitRef],
   );
 
   useGestureDispatcher({

package/src/passthrough/weasel-ui.test.ts

@@ -20,11 +20,11 @@ import {
   paintGradientTrack,
   RadioGroup,
   RangeSlider,
-  sampleByInterpolation,
   Select,
   Sidebar,
   Slider,
   Switch,
+  sampleByInterpolation,
   Tabs,
   ToolPalette,
   useReorderDragList,

package/src/passthrough/weasel-ui.ts

@@ -182,7 +182,7 @@ export {
   type ReorderDragHandlers,
   type ReorderDragState,
   type ReorderGhost,
-  type RovingItem,
+  type RovingOrientation,
   type RovingTabIndex,
   type SegmentTooltipFields,
   Select,

package/src/primitives/FloatingPanel.tsx

@@ -1,4 +1,9 @@
-import { openPointerSession, type PointerSession, pastDragThreshold } from '@weasel-js/core';
+import {
+  openPointerSession,
+  type PointerSession,
+  pastDragThreshold,
+  useLatest,
+} from '@weasel-js/core';
 import type React from 'react';
 import { type CSSProperties, type ReactNode, useEffect, useMemo, useRef, useState } from 'react';
 import {
@@ -119,8 +124,7 @@ export function FloatingPanel({
   // A drag outlives the render that started it, so the reducer's inputs are
   // read here and not from that render's closure — a container resized
   // mid-drag would otherwise place the panel against its old box.
-  const layout = useRef({ container, options, item });
-  layout.current = { container, options, item };
+  const layout = useLatest({ container, options, item });
 
   useEffect(() => () => session.current?.cancel(), []);
 

package/src/primitives/FpsMeter.less

@@ -1,9 +1,9 @@
 .lk-fps-meter {
+  .numeric();
   display: inline-flex;
   align-items: center;
   white-space: nowrap;
   gap: var(--wzl-space-xs);
-  font-family: var(--wzl-font-mono);
   font-size: var(--wzl-font-size-sm);
   color: var(--wzl-fg-muted);
 }
@@ -14,6 +14,5 @@
      a 240Hz display reads three digits, and a readout that grows into them
      pushes whatever shares its row. */
   min-width: 3ch;
-  font-variant-numeric: tabular-nums;
   text-align: right;
 }

package/src/primitives/JobProgress.less

@@ -30,7 +30,7 @@
   }
 
   &__count {
-    font-variant-numeric: tabular-nums;
+    .numeric();
     white-space: nowrap;
   }
 

package/src/primitives/Readout.test.tsx

@@ -81,8 +81,8 @@ describe('Readout', () => {
   });
 
   it('merges a consumer className on its root', () => {
-    const { container } = render(<Readout className="mine" rows={[]} />);
-    expect(must(container.firstElementChild).className).toMatch(/\blk-readout\b.*\bmine\b/);
+    const { container } = render(<Readout className="is-mine" rows={[]} />);
+    expect(must(container.firstElementChild).className).toMatch(/\blk-readout\b.*\bis-mine\b/);
   });
 
   it('is exported from the labkit barrel, with the list it is built on', () => {

package/src/primitives/ScaleIndicator.less

@@ -1,8 +1,8 @@
 .lk-scale-indicator {
+  .numeric();
   display: inline-flex;
   align-items: center;
   gap: var(--wzl-space-xs);
-  font-family: var(--wzl-font-mono);
   font-size: var(--wzl-font-size-sm);
   color: var(--wzl-fg-muted);
 }

package/src/primitives/Split.tsx

@@ -1,3 +1,4 @@
+import { useLatest } from '@weasel-js/core';
 import { type ReactNode, useEffect, useMemo, useRef } from 'react';
 import { asNodeId, createNode, Store, stripStrategy } from 'windease';
 import { type ChromeMap, Container, Provider, StrategyRegistryProvider } from 'windease/react';
@@ -42,6 +43,65 @@ export interface SplitProps {
   viewport?: { w: number; h: number };
 }
 
+interface SplitInit {
+  side: 'start' | 'end';
+  label: string;
+  sidebarWidth: number;
+  minWidth: number;
+  maxWidth: number;
+  contentMinWidth: number;
+}
+
+/** A strip holding the sidebar and the content pane, sized as the first render asks. */
+function createSplitStore({
+  side,
+  label,
+  sidebarWidth,
+  minWidth,
+  maxWidth,
+  contentMinWidth,
+}: SplitInit): Store {
+  const store = new Store();
+  store.registerNode(
+    createNode({
+      kind: 'zone',
+      id: ZONE_ID,
+      // A strip's seam resizes the pane before it, which on the end side is the
+      // content; 'neighbor' has the seam size the sidebar after it too.
+      container: {
+        strategyId: 'strip',
+        config: {
+          axis: 'x',
+          resizable: true,
+          ...(side === 'end' ? { resizeMode: 'neighbor' } : {}),
+        },
+      },
+    }),
+  );
+  const sidebarNode = createNode({
+    kind: 'sidebar',
+    id: SIDEBAR_ID,
+    parentId: ZONE_ID,
+    meta: { title: label },
+    placement: { size: { w: sidebarWidth } },
+    hints: { minSize: { w: minWidth, h: 0 }, maxSize: { w: maxWidth, h: 0 } },
+  });
+  const contentNode = createNode({
+    kind: 'content',
+    id: CONTENT_ID,
+    parentId: ZONE_ID,
+    meta: { title: 'Content' },
+    hints: { minSize: { w: contentMinWidth, h: 0 } },
+  });
+  // A strip lays its children out in registration order.
+  for (const node of side === 'end' ? [contentNode, sidebarNode] : [sidebarNode, contentNode]) {
+    store.registerNode(node);
+  }
+  store.showNode(SIDEBAR_ID);
+  store.showNode(CONTENT_ID);
+  return store;
+}
+
 /**
  * A sidebar and a content pane as a two-pane strip with a draggable seam.
  *
@@ -70,45 +130,14 @@ export function Split({
   // stretches its panes to the container's height and never reads `h`.
   const storeRef = useRef<Store | null>(null);
   if (storeRef.current === null) {
-    const store = new Store();
-    store.registerNode(
-      createNode({
-        kind: 'zone',
-        id: ZONE_ID,
-        // A strip's seam resizes the pane before it, which on the end side is the
-        // content; 'neighbor' has the seam size the sidebar after it too.
-        container: {
-          strategyId: 'strip',
-          config: {
-            axis: 'x',
-            resizable: true,
-            ...(side === 'end' ? { resizeMode: 'neighbor' } : {}),
-          },
-        },
-      }),
-    );
-    const sidebarNode = createNode({
-      kind: 'sidebar',
-      id: SIDEBAR_ID,
-      parentId: ZONE_ID,
-      meta: { title: label },
-      placement: { size: { w: width ?? defaultWidth } },
-      hints: { minSize: { w: minWidth, h: 0 }, maxSize: { w: maxWidth, h: 0 } },
-    });
-    const contentNode = createNode({
-      kind: 'content',
-      id: CONTENT_ID,
-      parentId: ZONE_ID,
-      meta: { title: 'Content' },
-      hints: { minSize: { w: contentMinWidth, h: 0 } },
+    storeRef.current = createSplitStore({
+      side,
+      label,
+      sidebarWidth: width ?? defaultWidth,
+      minWidth,
+      maxWidth,
+      contentMinWidth,
     });
-    // A strip lays its children out in registration order.
-    for (const node of side === 'end' ? [contentNode, sidebarNode] : [sidebarNode, contentNode]) {
-      store.registerNode(node);
-    }
-    store.showNode(SIDEBAR_ID);
-    store.showNode(CONTENT_ID);
-    storeRef.current = store;
   }
   const store = storeRef.current;
 
@@ -134,8 +163,7 @@ export function Split({
     store.patchPlacement(SIDEBAR_ID, { size: { w: width } });
   }, [store, width]);
 
-  const onWidthChangeRef = useRef(onWidthChange);
-  onWidthChangeRef.current = onWidthChange;
+  const onWidthChangeRef = useLatest(onWidthChange);
   useEffect(
     () =>
       store.events.on('node.placementChanged', () => {
@@ -148,7 +176,7 @@ export function Split({
         widthRef.current = next;
         onWidthChangeRef.current?.(next);
       }),
-    [store],
+    [onWidthChangeRef, store],
   );
 
   const chrome = useMemo<ChromeMap>(

package/src/primitives/StatusBar.less

@@ -1,4 +1,5 @@
 .lk-status-bar {
+  .numeric();
   display: flex;
   align-items: center;
   /* One line, always. A bar that grows a second line takes it from the canvas
@@ -11,7 +12,6 @@
   border-top: 1px solid var(--wzl-border);
   font-size: var(--wzl-font-size-sm);
   color: var(--wzl-fg-muted);
-  font-family: var(--wzl-font-mono);
 }
 
 .lk-status-bar-section {

package/src/primitives/Toolbar.tsx

@@ -1,5 +1,5 @@
 import type { MouseEventHandler, ReactNode } from 'react';
-import { useRovingTabIndex } from './useRovingTabIndex';
+import { useRovingTabIndex } from '../passthrough/weasel-ui';
 
 /** Props for `<Toolbar>`. */
 export interface ToolbarProps {
@@ -12,10 +12,10 @@ export interface ToolbarProps {
 /** A horizontal bar of controls. Fill it with `<Toolbar.Title>`,
  *  `<Toolbar.Group>`, `<Toolbar.Button>` and `<Toolbar.Spacer>`. */
 export function Toolbar({ children, 'aria-label': ariaLabel }: ToolbarProps) {
-  const { ref, onKeyDown } = useRovingTabIndex<HTMLDivElement>();
+  const { rootRef, onKeyDown } = useRovingTabIndex<HTMLDivElement>({ orientation: 'horizontal' });
   return (
     <div
-      ref={ref}
+      ref={rootRef}
       className="lk-toolbar"
       role="toolbar"
       aria-label={ariaLabel}

package/src/primitives/ZoomControl.less

@@ -13,8 +13,7 @@
   }
 }
 
-// The slider is a weasel-ui component whose module class sets `width`.
-// See the `.lk-root` prefix convention in theme/base.less.
+// Under `.lk-root` to outrank theme/base.less's element defaults; see its prefix convention.
 .lk-root {
   .lk-zoom {
     // Narrow enough to sit in a trial toolbar, wide enough for the octave

package/src/specimen/Specimen.less

@@ -78,6 +78,7 @@
 }
 
 .lk-specimen__pane {
+  .numeric();
   flex: none;
   width: var(--lk-specimen-pane-w);
   padding: var(--wzl-space-sm);

package/src/specimen/Specimen.tsx

@@ -666,7 +666,6 @@ function ToolChrome() {
               label={id}
               shortcut={id.slice(0, 1).toUpperCase()}
               active={tool === id}
-              tabbable={tool === id}
               onClick={() => setTool(id)}
             />
           ))}

package/src/state/undock.ts

@@ -8,10 +8,13 @@ export interface UndockedPanel {
 /** Undocked panels, keyed by {@link panelKey}. */
 export type UndockedPanels = Record<string, UndockedPanel>;
 
+/** The `UndockedPanels` key for one trial's section. */
 export function panelKey(trialId: string, sectionId: string): string {
   return `${trialId}::${sectionId}`;
 }
 
+/** `panels` with the section marked undocked `as` a tile or a floating panel,
+ *  replacing any earlier entry for it. Returns a new record. */
 export function undockPanel(
   panels: UndockedPanels,
   trialId: string,

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/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

@@ -2,6 +2,8 @@
 // Left as a CSS @import for the consumer's bundler to resolve; build-css.mjs
 // swaps it for the faces themselves, pointed at dist/fonts/.
 @import (css) '@weasel-js/theme/faces.css';
+// The numeric face's one definition, taken as a mixin: `.numeric();`.
+@import (reference, less) '@weasel-js/theme/numeric.module.css';
 @import './theme/base.less';
 @import './lab/Workspace.less';
 @import './lab/LabShell.less';
@@ -22,6 +24,7 @@
 @import './chrome/regions/PaletteRegion.less';
 @import './chrome/regions/SidebarRegion.less';
 @import './controls/ControlPanel.less';
+@import './controls/ControlMatrix.less';
 @import './canvas/CanvasStack.less';
 @import './canvas/Stage.less';
 @import './canvas/LinkedCursor.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;