@weasel-js/labkit 1.5.0 → 1.5.1

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

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

package/src/primitives/Split.tsx

@@ -11,6 +11,8 @@ const STRATEGIES = { strip: stripStrategy as never };
 export interface SplitProps {
   /** The sidebar pane's contents. */
   sidebar: ReactNode;
+  /** The edge the sidebar sits on. Read once, when the strip mounts. Default `'start'`. */
+  side?: 'start' | 'end';
   /** The content pane's contents. */
   children: ReactNode;
   /** Names the sidebar pane, and through it the seam. Default `'Sidebar'`. */
@@ -51,6 +53,7 @@ export interface SplitProps {
 export function Split({
   sidebar,
   children,
+  side = 'start',
   label = 'Sidebar',
   className,
   sidebarClassName,
@@ -72,28 +75,37 @@ export function Split({
       createNode({
         kind: 'zone',
         id: ZONE_ID,
-        container: { strategyId: 'strip', config: { axis: 'x', resizable: true } },
-      }),
-    );
-    store.registerNode(
-      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 } },
-      }),
-    );
-    store.registerNode(
-      createNode({
-        kind: 'content',
-        id: CONTENT_ID,
-        parentId: ZONE_ID,
-        meta: { title: 'Content' },
-        hints: { minSize: { w: contentMinWidth, h: 0 } },
+        // 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 } },
+    });
+    // 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;
@@ -127,6 +139,10 @@ export function Split({
   useEffect(
     () =>
       store.events.on('node.placementChanged', () => {
+        // A neighbor drag pins the content's width too; unpinned, it goes on filling the strip.
+        if ((store.getPlacement(CONTENT_ID)?.size as { w?: number } | undefined)?.w !== undefined) {
+          store.patchPlacement(CONTENT_ID, { size: {} });
+        }
         const next = (store.getPlacement(SIDEBAR_ID)?.size as { w?: number } | undefined)?.w;
         if (typeof next !== 'number' || next === widthRef.current) return;
         widthRef.current = next;

package/src/primitives/StatusBar.stories.tsx

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

package/src/primitives/Toolbar.stories.tsx

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

package/src/specimen/Specimen.less

@@ -0,0 +1,95 @@
+.lk-specimen {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wzl-space-lg);
+  padding: var(--wzl-space-lg);
+  background: var(--wzl-surface);
+  color: var(--wzl-fg);
+  font-family: var(--wzl-font-ui);
+  font-size: var(--wzl-font-size);
+}
+
+.lk-specimen__section {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wzl-space-sm);
+}
+
+.lk-specimen__heading {
+  margin: 0;
+  padding-block-end: var(--wzl-space-xs);
+  border-bottom: var(--wzl-border-w) solid var(--wzl-line-subtle);
+  color: var(--wzl-fg-muted);
+  font-family: var(--wzl-font-display);
+  font-size: var(--wzl-font-size-sm);
+  font-weight: var(--wzl-font-weight-normal);
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.lk-specimen__grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+  gap: var(--wzl-space-md);
+  align-items: start;
+}
+
+.lk-specimen__cell {
+  display: flex;
+  flex-direction: column;
+  gap: var(--wzl-space-xs);
+  min-width: 0;
+}
+
+.lk-specimen__label {
+  color: var(--wzl-fg-subtle);
+  font-family: var(--wzl-font-mono);
+  font-size: var(--wzl-font-size-xs);
+}
+
+.lk-specimen__row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--wzl-space-sm);
+}
+
+.lk-specimen__cell--wide {
+  grid-column: 1 / -1;
+}
+
+.lk-specimen__box {
+  position: relative;
+  display: flex;
+  height: 160px;
+  overflow: hidden;
+  border: var(--wzl-border-w) solid var(--wzl-line-subtle);
+  border-radius: var(--wzl-radius-sm);
+}
+
+.lk-specimen__box-main {
+  flex: 1;
+  min-width: 0;
+  padding: var(--wzl-space-sm);
+}
+
+.lk-specimen__pad {
+  padding: var(--wzl-space-xs) var(--wzl-space-sm);
+}
+
+.lk-specimen__pane {
+  flex: none;
+  width: var(--lk-specimen-pane-w);
+  padding: var(--wzl-space-sm);
+}
+
+.lk-specimen__timeline {
+  height: 180px;
+}
+
+.lk-specimen__floating-host {
+  position: relative;
+  height: 160px;
+  border: var(--wzl-border-w) solid var(--wzl-line-subtle);
+  border-radius: var(--wzl-radius-sm);
+}

package/src/specimen/Specimen.stories.tsx

@@ -0,0 +1,13 @@
+import type { Meta, StoryObj } from '@weasel-js/forge';
+import { Specimen } from './Specimen';
+
+const meta: Meta<typeof Specimen> = {
+  title: 'labkit/Specimen',
+  component: Specimen,
+  parameters: { layout: 'fullscreen' },
+};
+export default meta;
+
+type Story = StoryObj<typeof Specimen>;
+
+export const Everything: Story = {};

package/src/specimen/Specimen.test.tsx

@@ -0,0 +1,13 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { SPECIMEN_SECTIONS, Specimen } from './Specimen';
+
+describe('<Specimen>', () => {
+  it('renders every section as a named region', () => {
+    render(<Specimen />);
+    expect(SPECIMEN_SECTIONS.length).toBeGreaterThan(0);
+    for (const title of SPECIMEN_SECTIONS) {
+      expect(screen.getByRole('region', { name: title })).toBeInTheDocument();
+    }
+  });
+});