@weasel-js/labkit 1.7.0 → 1.7.1

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/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.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/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/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;
   }

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');