@weasel-js/labkit 1.5.0 → 1.5.2

package/src/loupe/TrialLoupe.tsx

@@ -1,3 +1,4 @@
+import { WeaselProvider } from '@weasel-js/core';
 import { type RefObject, useContext, useMemo } from 'react';
 import { CanvasStackContext } from '../canvas/CanvasStackContext';
 import type { WorldSpec } from '../canvas/worldSpec';
@@ -6,6 +7,7 @@ import { CanvasLoupe } from './CanvasLoupe';
 import { sampleStack } from './canvasLens';
 import { DomLoupe } from './DomLoupe';
 import { LoupeBubble } from './LoupeBubble';
+import { LoupeGestures } from './LoupeGestures';
 import type { ResolvedLoupe } from './types';
 import { useHostSize } from './useHostSize';
 import { useLoupe } from './useLoupe';
@@ -59,35 +61,48 @@ export function TrialLoupe({
   const measured = useHostSize(host);
   const size = surface?.size ?? measured;
 
-  if (!loupe.visible) return null;
+  // The gestures mount outside the visibility gate: hold-to-peek is what
+  // raises a lens that is down, so its binding has to be live while it is.
+  // One isolated scope per loupe, for the reason `<AnnotationOverlay>` gives
+  // — an actions registry holds one dispatcher.
+  const gestures = (
+    <WeaselProvider isolate>
+      <LoupeGestures hostRef={host} input={loupe.input} peekKey={capability.peekKey ?? null} />
+    </WeaselProvider>
+  );
+
+  if (!loupe.visible) return gestures;
 
   return (
-    <LoupeBubble aim={loupe.aim} diameter={capability.diameter}>
-      {capability.render ? (
-        <DomLoupe
-          aim={loupe.aim}
-          factor={loupe.factor}
-          mode={loupe.mode}
-          diameter={capability.diameter}
-          size={size}
-          view={view}
-          frame={stack?.frame}
-          state={state}
-          config={config}
-          render={capability.render}
-        />
-      ) : surface && stack ? (
-        <CanvasLoupe
-          aim={loupe.aim}
-          factor={loupe.factor}
-          mode={loupe.mode}
-          diameter={capability.diameter}
-          surface={surface}
-          view={stack.view}
-          frame={stack.frame}
-          worldSpec={worldSpec}
-        />
-      ) : null}
-    </LoupeBubble>
+    <>
+      {gestures}
+      <LoupeBubble aim={loupe.aim} diameter={capability.diameter}>
+        {capability.render ? (
+          <DomLoupe
+            aim={loupe.aim}
+            factor={loupe.factor}
+            mode={loupe.mode}
+            diameter={capability.diameter}
+            size={size}
+            view={view}
+            frame={stack?.frame}
+            state={state}
+            config={config}
+            render={capability.render}
+          />
+        ) : surface && stack ? (
+          <CanvasLoupe
+            aim={loupe.aim}
+            factor={loupe.factor}
+            mode={loupe.mode}
+            diameter={capability.diameter}
+            surface={surface}
+            view={stack.view}
+            frame={stack.frame}
+            worldSpec={worldSpec}
+          />
+        ) : null}
+      </LoupeBubble>
+    </>
   );
 }

package/src/loupe/index.ts

@@ -6,6 +6,10 @@ export type { DomLoupeProps } from './DomLoupe';
 export { DomLoupe } from './DomLoupe';
 export type { LoupeBubbleProps } from './LoupeBubble';
 export { LoupeBubble } from './LoupeBubble';
+export type { LoupeGesturesProps } from './LoupeGestures';
+export { LoupeGestures } from './LoupeGestures';
+export type { LoupeInputApi } from './loupeActions';
+export { createLoupeActions, LOUPE_MAGNIFY_ID, LOUPE_PEEK_ID } from './loupeActions';
 export type { TrialLoupeProps } from './TrialLoupe';
 export { TrialLoupe } from './TrialLoupe';
 export type {

package/src/loupe/loupeActions.ts

@@ -0,0 +1,98 @@
+/**
+ * The loupe's two bindable interactions, as `Action` descriptors the gesture
+ * dispatcher routes: hold a key to peek, and walk the magnification with the
+ * wheel.
+ *
+ * Free of React so the routing can be tested without a DOM.
+ */
+import type { Action } from '@weasel-js/core';
+
+/** Canonical id of the hold-to-peek action. */
+export const LOUPE_PEEK_ID = 'loupe.peek';
+/** Canonical id of the wheel-magnify action. */
+export const LOUPE_MAGNIFY_ID = 'loupe.magnify';
+
+/** How fast the wheel walks the magnification. Gentler than the pan-zoom
+ *  wheel: the lens' whole range is one order of magnitude. */
+export const WHEEL_RATE = 0.002;
+
+/** What the actions do to a live loupe. Every member is read through the
+ *  object on each invocation, so one stable instance serves the life of the
+ *  registration. */
+export interface LoupeInputApi {
+  /** Whether the lens is up. The wheel belongs to the loupe only while it is;
+   *  otherwise `loupe.magnify` declines and the dispatcher leaves the event
+   *  unhandled, which is what hands it back to the lab's own pan/zoom. */
+  shown: () => boolean;
+  /** Raise or drop the hold-to-peek flag. */
+  setPeeking: (on: boolean) => void;
+  /** Multiply the magnification by one wheel notch of `deltaY`. */
+  magnifyBy: (deltaY: number) => void;
+}
+
+/**
+ * Build the loupe's actions. `peekKey` is a `KeyboardEvent.key`; passing
+ * `null` omits `loupe.peek` entirely rather than registering a binding no key
+ * can match.
+ */
+export function createLoupeActions(
+  input: LoupeInputApi,
+  peekKey: string | null,
+): readonly Action[] {
+  const magnify: Action = {
+    id: LOUPE_MAGNIFY_ID,
+    label: 'Magnify (loupe)',
+    group: 'loupe',
+    // Every modifier optional: the lens claims the wheel whenever it is up,
+    // which is what the hand-rolled capture-phase listener did. A bare spec
+    // would forbid modifiers and hand Cmd+wheel back to the lab mid-peek.
+    defaultBinding: [
+      {
+        spec: {
+          kind: 'wheel',
+          mods: { alt: 'optional', ctrl: 'optional', meta: 'optional', shift: 'optional' },
+        },
+        opts: {},
+      },
+    ],
+    enabled: () => (input.shown() ? true : 'not-applicable'),
+    invoker: {
+      timing: 'immediate',
+      run(_deps, params) {
+        input.magnifyBy((params?.deltaY as number | undefined) ?? 0);
+      },
+    },
+  };
+
+  if (peekKey === null) return [magnify];
+
+  const peek: Action = {
+    id: LOUPE_PEEK_ID,
+    label: 'Peek (loupe)',
+    group: 'loupe',
+    // Hotkey scope: peeking must beat whatever the lab's active tool binds to
+    // the same key, the way every other held-key trigger does.
+    scope: 'hotkey',
+    // Every modifier optional because the peek key may BE one: the keydown
+    // that carries `Alt` — the default — also reports `altKey: true`, and the
+    // matcher forbids any modifier a spec does not name.
+    defaultBinding: [
+      {
+        spec: {
+          kind: 'key-held',
+          key: peekKey,
+          mods: { alt: 'optional', ctrl: 'optional', meta: 'optional', shift: 'optional' },
+        },
+        opts: {},
+      },
+    ],
+    invoker: {
+      timing: 'ongoing',
+      start() {
+        input.setPeeking(true);
+        return { onEnd: () => input.setPeeking(false) };
+      },
+    },
+  };
+  return [peek, magnify];
+}

package/src/loupe/useLoupe.test.tsx

@@ -1,6 +1,8 @@
 import { act, fireEvent, render, screen } from '@testing-library/react';
+import { WeaselProvider } from '@weasel-js/core';
 import { type RefObject, StrictMode, useRef } from 'react';
 import { describe, expect, it, vi } from 'vitest';
+import { LoupeGestures } from './LoupeGestures';
 import { resolveLoupe } from './types';
 import { type LoupeState, useLoupe } from './useLoupe';
 
@@ -15,18 +17,29 @@ interface HarnessProps {
 }
 
 /** Reports the loupe's state as text, which is every assertion jsdom can make
- *  about a magnifier — that the lens shows the right region is a screenshot. */
+ *  about a magnifier — that the lens shows the right region is a screenshot.
+ *
+ *  Mounts `<LoupeGestures>` the way `<TrialLoupe>` does, so the key and wheel
+ *  cases below exercise the real dispatcher route rather than a stand-in. */
 function Harness({ enabled = true, seen, sample, ...rest }: HarnessProps) {
   const hostRef = useRef<HTMLDivElement | null>(null);
+  const capability = resolveLoupe(rest);
   const loupe = useLoupe({
     hostRef: hostRef as RefObject<HTMLElement | null>,
     enabled,
     sample,
-    capability: resolveLoupe(rest),
+    capability,
   });
   seen?.(loupe);
   return (
     <div ref={hostRef} data-testid="host">
+      <WeaselProvider isolate>
+        <LoupeGestures
+          hostRef={hostRef as RefObject<HTMLElement | null>}
+          input={loupe.input}
+          peekKey={capability.peekKey ?? null}
+        />
+      </WeaselProvider>
       <span data-testid="visible">{String(loupe.visible)}</span>
       <span data-testid="aim">{`${loupe.aim.x},${loupe.aim.y}`}</span>
       <span data-testid="factor">{loupe.factor}</span>
@@ -94,6 +107,7 @@ describe('useLoupe', () => {
     act(() => {
       fireEvent.keyDown(window, { key: 'Alt' });
     });
+    expect(read('visible')).toBe('true');
     act(() => {
       fireEvent.blur(window);
     });
@@ -148,6 +162,49 @@ describe('useLoupe', () => {
     expect(wheel.defaultPrevented).toBe(true);
   });
 
+  it('stops a claimed wheel reaching the pan-zoom handler above it', () => {
+    // The real handler is React's, delegated to the root container, so what
+    // decides whether pan-zoom runs is whether the event bubbles past the
+    // host — `defaultPrevented` says nothing about that. A listener on an
+    // ancestor is the proxy for React's root one.
+    const above = vi.fn();
+    const { container } = render(<Harness />);
+    container.addEventListener('wheel', above);
+
+    const host = screen.getByTestId('host');
+    move(40, 25);
+    act(() => {
+      host.dispatchEvent(
+        new WheelEvent('wheel', { deltaY: -100, bubbles: true, cancelable: true }),
+      );
+    });
+    expect(above).not.toHaveBeenCalled();
+
+    fireEvent.pointerLeave(host);
+    act(() => {
+      host.dispatchEvent(
+        new WheelEvent('wheel', { deltaY: -100, bubbles: true, cancelable: true }),
+      );
+    });
+    expect(above).toHaveBeenCalledTimes(1);
+  });
+
+  it('leaves the native context menu and file drops to the lab', () => {
+    // The dispatcher suppresses `contextmenu` unconditionally and makes its
+    // element a drop target; the loupe mounts with both channels off, so a
+    // lab that turns a magnifier on keeps its right-click and its drops.
+    render(<Harness />);
+    const host = screen.getByTestId('host');
+    move(40, 25);
+
+    const menu = new MouseEvent('contextmenu', { bubbles: true, cancelable: true });
+    act(() => {
+      host.dispatchEvent(menu);
+    });
+    expect(menu.defaultPrevented).toBe(false);
+    expect(host.classList.contains('weasel-dropover')).toBe(false);
+  });
+
   it('reports the color under the aim', () => {
     const onColorChange = vi.fn();
     render(

package/src/loupe/useLoupe.ts

@@ -5,6 +5,8 @@ import {
   type LoupePoint,
 } from '@weasel-js/loupe';
 import { type RefObject, useCallback, useEffect, useReducer, useRef } from 'react';
+import type { LoupeInputApi } from './loupeActions';
+import { WHEEL_RATE } from './loupeActions';
 import type { ResolvedLoupe } from './types';
 
 /** Options for {@link useLoupe}. */
@@ -32,21 +34,21 @@ export interface LoupeState {
   setFactor: (factor: number) => void;
   /** Sample what the lens shows at a point inside it. */
   pick: (p?: LoupePoint) => string | null;
+  /** What `<LoupeGestures>` drives the lens through. Stable for the life of
+   *  the hook, so registering the actions on it does not churn. */
+  input: LoupeInputApi;
 }
 
-/** How fast the wheel walks the magnification. Gentler than the pan-zoom
- *  wheel: the lens' whole range is one order of magnitude. */
-const WHEEL_RATE = 0.002;
-
 /**
- * Binds `@weasel-js/loupe`'s model to a host element and drives it from the
- * pointer, the peek key and the wheel.
+ * Binds `@weasel-js/loupe`'s model to a host element and tracks the pointer
+ * across it.
  *
- * These are plain listeners rather than gesture bindings because labkit trials
- * do not route input through the dispatcher — see the loupe entry under
- * "Selection, actions & UI panels" in `docs/TODO.md`. They are all in this one
- * hook so that when trial input does go through it, this is the only file to
- * rewrite.
+ * The peek key and the wheel are not here: they are `loupe.peek` and
+ * `loupe.magnify`, routed through the gesture dispatcher that
+ * `<LoupeGestures>` mounts on the same host. Aiming stays a plain listener
+ * because a hover is not a gesture the grammar names — `GESTURE_DESCRIPTORS`
+ * has no continuous-motion entry, and inventing one to carry the lens' aim
+ * would be an input taxonomy change, not a loupe change.
  */
 export function useLoupe({ capability, hostRef, enabled, sample }: UseLoupeOptions): LoupeState {
   const [, bump] = useReducer((n: number) => n + 1, 0);
@@ -128,53 +130,30 @@ export function useLoupe({ capability, hostRef, enabled, sample }: UseLoupeOptio
       overRef.current = false;
       bump();
     };
-    const onWheel = (e: WheelEvent): void => {
-      if (!shown()) return;
-      // Ahead of the stack's own pan-zoom, which is a React handler on this same
-      // element: capture runs first, and stopping propagation keeps the event
-      // from reaching React's root listener at all.
-      e.preventDefault();
-      e.stopPropagation();
-      model.setFactor(model.factor * Math.exp(-e.deltaY * WHEEL_RATE));
-    };
 
     host.addEventListener('pointermove', onPointerMove);
     host.addEventListener('pointerleave', onPointerLeave);
-    host.addEventListener('wheel', onWheel, { capture: true, passive: false });
     return () => {
       host.removeEventListener('pointermove', onPointerMove);
       host.removeEventListener('pointerleave', onPointerLeave);
-      host.removeEventListener('wheel', onWheel, { capture: true });
     };
   }, [hostRef, model, shown]);
 
-  const peekKey = capability.peekKey;
-  useEffect(() => {
-    if (peekKey == null) return;
-    const setPeeking = (next: boolean): void => {
-      if (peekingRef.current === next) return;
-      peekingRef.current = next;
-      bump();
-    };
-    const onKeyDown = (e: KeyboardEvent): void => {
-      if (e.key === peekKey) setPeeking(true);
-    };
-    const onKeyUp = (e: KeyboardEvent): void => {
-      if (e.key === peekKey) setPeeking(false);
-    };
-    // A key held while the window loses focus never sends its keyup, so the
-    // peek would stay on until the key was pressed and released again.
-    const onBlur = (): void => setPeeking(false);
-
-    window.addEventListener('keydown', onKeyDown);
-    window.addEventListener('keyup', onKeyUp);
-    window.addEventListener('blur', onBlur);
-    return () => {
-      window.removeEventListener('keydown', onKeyDown);
-      window.removeEventListener('keyup', onKeyUp);
-      window.removeEventListener('blur', onBlur);
+  const inputRef = useRef<LoupeInputApi | null>(null);
+  if (inputRef.current === null) {
+    inputRef.current = {
+      shown,
+      setPeeking: (on) => {
+        if (peekingRef.current === on) return;
+        peekingRef.current = on;
+        bump();
+      },
+      magnifyBy: (deltaY) => {
+        const m = modelRef.current;
+        if (m) m.setFactor(m.factor * Math.exp(-deltaY * WHEEL_RATE));
+      },
     };
-  }, [peekKey]);
+  }
 
   return {
     visible: shown(),
@@ -185,5 +164,6 @@ export function useLoupe({ capability, hostRef, enabled, sample }: UseLoupeOptio
     setMode: model.setMode,
     setFactor: model.setFactor,
     pick: model.pick,
+    input: inputRef.current,
   };
 }

package/src/passthrough/weasel-ui.ts

@@ -15,6 +15,8 @@ export {
   type ActionsBarVariant,
   type AddPointMode,
   type AnchorRenderProps,
+  type AsyncOption,
+  type AsyncOptionsResult,
   type AxesSettings,
   Badge,
   type BadgeProps,
@@ -191,12 +193,10 @@ export {
   ToolPalette,
   type ToolPaletteProps,
   type TrackCtx,
+  type UseAsyncOptionsProps,
   type UseReorderDragListOptions,
   type UseRovingTabIndexOptions,
   useAsyncOptions,
-  type AsyncOption,
-  type AsyncOptionsResult,
-  type UseAsyncOptionsProps,
   useReorderDragList,
   useRovingTabIndex,
   visiblePrefSubtree,

package/src/primitives/FloatingPanel.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { localStorageAdapter } from '../state/adapters';
 import { Persistence } from '../state/Persistence';
 import { FloatingPanel } from './FloatingPanel';

package/src/primitives/FpsMeter.less

@@ -1,6 +1,7 @@
 .lk-fps-meter {
   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);
@@ -9,6 +10,10 @@
 
 .lk-fps-meter-value {
   color: var(--wzl-fg);
-  min-width: 2.5ch;
+  /* Sized for the widest rate it can hold rather than the one it holds now:
+     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/FpsMeter.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { FpsMeter } from './FpsMeter';
 
 const meta: Meta<typeof FpsMeter> = {

package/src/primitives/FpsMeter.test.tsx

@@ -9,9 +9,17 @@ describe('FpsMeter', () => {
 
   test('renders an FPS label', () => {
     render(<FpsMeter />);
-    expect(screen.getByText(/fps/i)).toBeInTheDocument();
+    expect(screen.getByText('FPS')).toBeInTheDocument();
   });
 
+  /* The label and the rate are separate elements so the rate can hold a fixed
+     width; a text query spanning both would go back to matching one box. */
+  const rate = (): HTMLElement => {
+    const el = document.querySelector('.lk-fps-meter-value');
+    if (!el) throw new Error('no rate readout');
+    return el as HTMLElement;
+  };
+
   test('uses lk-fps-meter class', () => {
     const { container } = render(<FpsMeter />);
     expect((container.firstChild as HTMLElement).className).toBe('lk-fps-meter');
@@ -31,7 +39,7 @@ describe('FpsMeter', () => {
       raf?.(16.67);
       raf?.(33.34);
     });
-    expect(screen.getByText(/FPS\s+\d+/)).toBeInTheDocument();
+    expect(rate().textContent).toMatch(/^\d+$/);
 
     vi.unstubAllGlobals();
   });
@@ -59,7 +67,7 @@ describe('FpsMeter', () => {
       run(16.67);
       run(33.34);
     });
-    const before = screen.getByText(/FPS\s+\d+/).textContent;
+    const before = rate().textContent;
 
     // An hour hidden. The frame that lands on resume is not a 60-minute frame,
     // and must not enter the rolling average as one.
@@ -74,7 +82,7 @@ describe('FpsMeter', () => {
       run(3_600_016.67);
     });
 
-    expect(screen.getByText(/FPS\s+\d+/).textContent).toBe(before);
+    expect(rate().textContent).toBe(before);
 
     setHidden(false);
     vi.unstubAllGlobals();

package/src/primitives/FpsMeter.tsx

@@ -42,7 +42,12 @@ export function FpsMeter() {
 
   return (
     <div className="lk-fps-meter" ref={rootRef}>
-      <span className="lk-fps-meter-value">FPS {fps}</span>
+      <span className="lk-fps-meter-label">FPS</span>
+      {/* The number is its own cell because it is the only part that changes:
+          in one box with the label, every digit it gains or loses resizes the
+          readout, and the status bar it sits in wraps to a second line and
+          back — which in a small trial resizes the window. */}
+      <span className="lk-fps-meter-value">{fps}</span>
     </div>
   );
 }

package/src/primitives/JobProgress.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import type { JobHandle } from '../job/types';
 import { JobProgress } from './JobProgress';
 
@@ -13,7 +13,7 @@ const base: JobHandle = {
 };
 
 const meta: Meta<typeof JobProgress> = {
-  title: 'labkit/primitives/JobProgress',
+  title: 'labkit/Primitives/JobProgress',
   component: JobProgress,
 };
 export default meta;

package/src/primitives/Legend.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { Legend } from './Legend';
 
 const meta: Meta<typeof Legend> = {

package/src/primitives/ScaleIndicator.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { ScaleIndicator } from './ScaleIndicator';
 
 const meta: Meta<typeof ScaleIndicator> = {

package/src/primitives/Sidebar.less

@@ -60,6 +60,13 @@
 
 .lk-sidebar-section {
   border-bottom: var(--wzl-border-w) solid var(--wzl-line-subtle);
+
+  // The last section runs to the bottom of its pane. Stopped at its content,
+  // its rule and the bare pane under it read as a second, empty zone.
+  &:last-child {
+    flex-grow: 1;
+    border-bottom: 0;
+  }
 }
 
 .lk-sidebar-section__bar {

package/src/primitives/Sidebar.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { useState } from 'react';
 import { Sidebar } from './Sidebar';
 

package/src/primitives/Split.test.tsx

@@ -83,6 +83,31 @@ describe('Split', () => {
     expect(container.querySelector('.lk-x__main')?.textContent).toBe('main');
   });
 
+  it('puts the sidebar after the content on the end side, where dragging the seam left widens it', () => {
+    const onWidthChange = vi.fn();
+    const { container } = render(
+      <Split
+        viewport={VIEWPORT}
+        side="end"
+        width={320}
+        sidebarClassName="lk-x__side"
+        contentClassName="lk-x__main"
+        sidebar={<p>side</p>}
+        onWidthChange={onWidthChange}
+      >
+        <p>main</p>
+      </Split>,
+    );
+    const side = container.querySelector('.lk-x__side') as HTMLElement;
+    const main = container.querySelector('.lk-x__main') as HTMLElement;
+    expect(main.compareDocumentPosition(side) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+    const seam = screen.getByRole('separator');
+    fireEvent.pointerDown(seam, { clientX: 480, clientY: 100 });
+    fireEvent.pointerMove(seam, { clientX: 420, clientY: 100 });
+    fireEvent.pointerUp(seam, { clientX: 420, clientY: 100 });
+    expect(onWidthChange).toHaveBeenLastCalledWith(380);
+  });
+
   it('names its seam after the sidebar label', () => {
     render(
       <Split viewport={VIEWPORT} label="Stories" sidebar={<p>side</p>}>