@weasel-js/labkit 1.3.0 → 1.4.0-pre.0

package/src/loupe/useLoupe.test.tsx

@@ -0,0 +1,197 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { type RefObject, StrictMode, useRef } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { resolveLoupe } from './types';
+import { type LoupeState, useLoupe } from './useLoupe';
+
+interface HarnessProps {
+  enabled?: boolean;
+  peekKey?: string | null;
+  sample?: (p: { x: number; y: number }) => string | null;
+  minFactor?: number;
+  maxFactor?: number;
+  onColorChange?: (hex: string) => void;
+  seen?: (loupe: LoupeState) => void;
+}
+
+/** 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. */
+function Harness({ enabled = true, seen, sample, ...rest }: HarnessProps) {
+  const hostRef = useRef<HTMLDivElement | null>(null);
+  const loupe = useLoupe({
+    hostRef: hostRef as RefObject<HTMLElement | null>,
+    enabled,
+    sample,
+    capability: resolveLoupe(rest),
+  });
+  seen?.(loupe);
+  return (
+    <div ref={hostRef} data-testid="host">
+      <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>
+      <span data-testid="mode">{loupe.mode}</span>
+      <span data-testid="color">{String(loupe.color)}</span>
+    </div>
+  );
+}
+
+const read = (id: string): string => screen.getByTestId(id).textContent ?? '';
+
+/** jsdom lays nothing out, so every rect is 0×0 at the origin and a client
+ *  coordinate is already host-relative. */
+function move(x: number, y: number): void {
+  fireEvent.pointerMove(screen.getByTestId('host'), { clientX: x, clientY: y });
+}
+
+describe('useLoupe', () => {
+  it('stays hidden until the pointer is over the host', () => {
+    render(<Harness />);
+    expect(read('visible')).toBe('false');
+    move(40, 25);
+    expect(read('visible')).toBe('true');
+    expect(read('aim')).toBe('40,25');
+  });
+
+  it('hides again when the pointer leaves', () => {
+    render(<Harness />);
+    move(40, 25);
+    fireEvent.pointerLeave(screen.getByTestId('host'));
+    expect(read('visible')).toBe('false');
+  });
+
+  it('ignores the pointer while it is turned off', () => {
+    render(<Harness enabled={false} />);
+    move(40, 25);
+    expect(read('visible')).toBe('false');
+  });
+
+  it('peeks while the peek key is held, and stops on release', () => {
+    render(<Harness enabled={false} />);
+    move(40, 25);
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Alt' });
+    });
+    expect(read('visible')).toBe('true');
+    act(() => {
+      fireEvent.keyUp(window, { key: 'Alt' });
+    });
+    expect(read('visible')).toBe('false');
+  });
+
+  it('does not peek when the capability turned the key off', () => {
+    render(<Harness enabled={false} peekKey={null} />);
+    move(40, 25);
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Alt' });
+    });
+    expect(read('visible')).toBe('false');
+  });
+
+  it('drops the peek when the window loses focus, so a held key cannot stick', () => {
+    render(<Harness enabled={false} />);
+    move(40, 25);
+    act(() => {
+      fireEvent.keyDown(window, { key: 'Alt' });
+    });
+    act(() => {
+      fireEvent.blur(window);
+    });
+    expect(read('visible')).toBe('false');
+  });
+
+  it('opens at the declared factor and zooms on the wheel', () => {
+    render(<Harness />);
+    move(40, 25);
+    expect(read('factor')).toBe('6');
+    act(() => {
+      fireEvent.wheel(screen.getByTestId('host'), { deltaY: -100 });
+    });
+    expect(Number(read('factor'))).toBeGreaterThan(6);
+  });
+
+  it('clamps the wheel to the declared bounds', () => {
+    render(<Harness minFactor={4} maxFactor={8} />);
+    move(40, 25);
+    for (let i = 0; i < 40; i++) {
+      act(() => {
+        fireEvent.wheel(screen.getByTestId('host'), { deltaY: -100 });
+      });
+    }
+    expect(Number(read('factor'))).toBe(8);
+    for (let i = 0; i < 80; i++) {
+      act(() => {
+        fireEvent.wheel(screen.getByTestId('host'), { deltaY: 100 });
+      });
+    }
+    expect(Number(read('factor'))).toBe(4);
+  });
+
+  it('leaves the wheel to pan-zoom while the lens is not shown', () => {
+    render(<Harness enabled={false} />);
+    const host = screen.getByTestId('host');
+    const wheel = new WheelEvent('wheel', { deltaY: -100, bubbles: true, cancelable: true });
+    act(() => {
+      host.dispatchEvent(wheel);
+    });
+    expect(wheel.defaultPrevented).toBe(false);
+  });
+
+  it('takes the wheel from pan-zoom while the lens is shown', () => {
+    render(<Harness />);
+    move(40, 25);
+    const host = screen.getByTestId('host');
+    const wheel = new WheelEvent('wheel', { deltaY: -100, bubbles: true, cancelable: true });
+    act(() => {
+      host.dispatchEvent(wheel);
+    });
+    expect(wheel.defaultPrevented).toBe(true);
+  });
+
+  it('reports the colour under the aim', () => {
+    const onColorChange = vi.fn();
+    render(
+      <Harness sample={(p) => (p.x > 10 ? '#ff0000' : '#00ff00')} onColorChange={onColorChange} />,
+    );
+    move(40, 25);
+    expect(read('color')).toBe('#ff0000');
+    expect(onColorChange).toHaveBeenCalledWith('#ff0000');
+    move(4, 25);
+    expect(read('color')).toBe('#00ff00');
+  });
+
+  it('picks what the lens shows at a point inside it', () => {
+    const seen: LoupeState[] = [];
+    render(<Harness sample={(p) => `#${Math.round(p.x)}`} seen={(l) => seen.push(l)} />);
+    move(100, 100);
+    const loupe = seen[seen.length - 1];
+    // Half the default 200px lens right of centre, at 6x, is 100/6 world px
+    // right of the aim.
+    const hex = loupe.pick({ x: 100 + 100, y: 100 });
+    expect(hex).toBe(`#${Math.round(100 + 100 / 6)}`);
+  });
+
+  it('still aims after a mount / unmount / remount', () => {
+    // What StrictMode does to every effect. The model is created once and
+    // `dispose` is one-way, so tearing it down on the first unmount left a
+    // magnifier that drew but never moved.
+    render(
+      <StrictMode>
+        <Harness />
+      </StrictMode>,
+    );
+    move(40, 25);
+    expect(read('visible')).toBe('true');
+    expect(read('aim')).toBe('40,25');
+  });
+
+  it('switches mode', () => {
+    const seen: LoupeState[] = [];
+    render(<Harness seen={(l) => seen.push(l)} />);
+    move(40, 25);
+    act(() => {
+      seen[seen.length - 1].setMode('pixel');
+    });
+    expect(read('mode')).toBe('pixel');
+  });
+});

package/src/loupe/useLoupe.ts

@@ -0,0 +1,189 @@
+import {
+  createLoupeModel,
+  type LoupeMode,
+  type LoupeModel,
+  type LoupePoint,
+} from '@weasel-js/loupe';
+import { type RefObject, useCallback, useEffect, useReducer, useRef } from 'react';
+import type { ResolvedLoupe } from './types';
+
+/** Options for {@link useLoupe}. */
+export interface UseLoupeOptions {
+  capability: ResolvedLoupe;
+  /** The element the lens tracks the pointer across. */
+  hostRef: RefObject<HTMLElement | null>;
+  /** Whether the loupe is turned on. Hold-to-peek shows it regardless. */
+  enabled: boolean;
+  /** Hex colour at a host point. Omitted, the loupe reports no colour — which
+   *  is the honest answer for a surface with no pixels to read. */
+  sample?: (p: LoupePoint) => string | null;
+}
+
+/** A loupe as a React view reads it. */
+export interface LoupeState {
+  /** Whether the lens should be drawn. */
+  visible: boolean;
+  /** Where it is aimed, in the host's own pixels. */
+  aim: LoupePoint;
+  factor: number;
+  mode: LoupeMode;
+  color: string | null;
+  setMode: (mode: LoupeMode) => void;
+  setFactor: (factor: number) => void;
+  /** Sample what the lens shows at a point inside it. */
+  pick: (p?: LoupePoint) => string | null;
+}
+
+/** 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.
+ *
+ * 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.
+ */
+export function useLoupe({ capability, hostRef, enabled, sample }: UseLoupeOptions): LoupeState {
+  const [, bump] = useReducer((n: number) => n + 1, 0);
+
+  const overRef = useRef(false);
+  const peekingRef = useRef(false);
+  const enabledRef = useRef(enabled);
+  enabledRef.current = enabled;
+  const sampleRef = useRef(sample);
+  sampleRef.current = sample;
+  const onColorChangeRef = useRef(capability.onColorChange);
+  onColorChangeRef.current = capability.onColorChange;
+
+  // Reads nothing but refs, so it is stable and an effect may depend on it.
+  const shown = useCallback(
+    (): boolean => overRef.current && (enabledRef.current || peekingRef.current),
+    [],
+  );
+
+  const modelRef = useRef<LoupeModel | null>(null);
+  if (modelRef.current === null) {
+    modelRef.current = createLoupeModel({
+      mode: capability.mode,
+      factor: capability.factor,
+      minFactor: capability.minFactor,
+      maxFactor: capability.maxFactor,
+      onColorChange: (hex) => onColorChangeRef.current?.(hex),
+      surface: {
+        lens: () => {
+          const d = diameterRef.current;
+          const { x, y } = modelRef.current?.aim ?? { x: 0, y: 0 };
+          return { x: x - d / 2, y: y - d / 2, w: d, h: d };
+        },
+        // The lens follows the pointer and is painted over the host rather than
+        // into it, so it is never part of the picture being magnified.
+        covers: () => false,
+        sample: (p) => sampleRef.current?.(p) ?? null,
+        hidden: () => !shown(),
+        gone: () => goneRef.current,
+        changed: bump,
+      },
+    });
+  }
+  const model = modelRef.current;
+
+  const diameterRef = useRef(capability.diameter);
+  diameterRef.current = capability.diameter;
+  const goneRef = useRef(false);
+
+  // The model holds no resources, and `dispose` is one-way — so unmounting only
+  // reports the lens gone. Disposing here instead leaves React's mount / unmount
+  // / remount in StrictMode with a permanently dead model that silently ignores
+  // every aim.
+  useEffect(() => {
+    goneRef.current = false;
+    return () => {
+      goneRef.current = true;
+    };
+  }, []);
+
+  // Turning the loupe off with the pointer still inside must put the lens away,
+  // and the model only reconsiders on an aim.
+  useEffect(() => {
+    if (!enabled && !peekingRef.current) bump();
+  }, [enabled]);
+
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+
+    const onPointerMove = (e: PointerEvent): void => {
+      overRef.current = true;
+      const rect = host.getBoundingClientRect();
+      model.aimAt({ x: e.clientX - rect.left, y: e.clientY - rect.top });
+      if (!shown()) return;
+      bump();
+    };
+    const onPointerLeave = (): void => {
+      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);
+    };
+  }, [peekKey]);
+
+  return {
+    visible: shown(),
+    aim: model.aim,
+    factor: model.factor,
+    mode: model.mode,
+    color: model.color,
+    setMode: model.setMode,
+    setFactor: model.setFactor,
+    pick: model.pick,
+  };
+}

package/src/passthrough/weasel-ui.ts

@@ -29,6 +29,9 @@ export {
   type ButtonProps,
   type ButtonSize,
   type ButtonVariant,
+  Callout,
+  type CalloutProps,
+  CalloutTrigger,
   Checkbox,
   type CheckboxProps,
   type ChromaCurve,

package/src/primitives/FloatingPanel.test.tsx

@@ -117,14 +117,25 @@ describe('FloatingPanel', () => {
 });
 
 describe('FloatingPanel dragging', () => {
-  it('marks itself dragging between pointerdown and pointerup', () => {
+  it('marks itself dragging once the pointer moves, not on the press', () => {
     const { panel } = renderPanel(<FloatingPanel>x</FloatingPanel>);
     fireEvent.pointerDown(panel, { clientX: 100, clientY: 100 });
+    expect(panel.dataset.dragging).toBeUndefined();
+    fireEvent.pointerMove(panel, { clientX: 140, clientY: 100 });
     expect(panel.dataset.dragging).toBe('true');
     fireEvent.pointerUp(panel);
     expect(panel.dataset.dragging).toBeUndefined();
   });
 
+  it('a press that never moves is not a drag', () => {
+    const { panel } = renderPanel(<FloatingPanel anchor="top-left">x</FloatingPanel>);
+    const before = panel.style.left;
+    fireEvent.pointerDown(panel, { clientX: 100, clientY: 100 });
+    fireEvent.pointerUp(panel, { clientX: 100, clientY: 100 });
+    expect(panel.dataset.dragging).toBeUndefined();
+    expect(panel.style.left).toBe(before);
+  });
+
   it('moves with the pointer, accumulating across moves', () => {
     const { panel } = renderPanel(<FloatingPanel anchor="top-left">x</FloatingPanel>);
     expect(panel.style.left).toBe('12px');
@@ -238,3 +249,67 @@ describe('FloatingPanel persistence', () => {
     expect(() => renderPanel(<FloatingPanel storageKey="k">x</FloatingPanel>)).not.toThrow();
   });
 });
+
+describe('a child that is not a native control', () => {
+  // The real symptom — capture retargets mouseup, so the browser synthesizes no
+  // `click` on the child — cannot be reproduced in jsdom, which fires the click
+  // either way. Capture-on-press is the observable proxy for it.
+  it('does not capture the pointer until the pointer has actually moved', () => {
+    const captured: number[] = [];
+    Element.prototype.setPointerCapture = (id: number) => {
+      captured.push(id);
+    };
+    render(
+      <FloatingPanel>
+        {/* biome-ignore lint/a11y/useSemanticElements: a non-native control is the subject */}
+        <span data-testid="row" role="button" tabIndex={0}>
+          row
+        </span>
+      </FloatingPanel>,
+    );
+    const row = screen.getByTestId('row');
+    fireEvent.pointerDown(row, { pointerId: 1, button: 0, clientX: 40, clientY: 40 });
+    expect(captured).toEqual([]);
+  });
+});
+
+describe('a clickable row nested in a list, the shape a floating panel usually holds', () => {
+  it('does not capture the pointer on a press two ancestors below the panel', () => {
+    const captured: number[] = [];
+    Element.prototype.setPointerCapture = (id: number) => {
+      captured.push(id);
+    };
+    render(
+      <FloatingPanel>
+        <ul>
+          <li>
+            {/* biome-ignore lint/a11y/useSemanticElements: a non-native control is the subject */}
+            <span data-testid="row" role="button" tabIndex={0}>
+              row
+            </span>
+          </li>
+        </ul>
+      </FloatingPanel>,
+    );
+    fireEvent.pointerDown(screen.getByTestId('row'), {
+      pointerId: 1,
+      button: 0,
+      clientX: 40,
+      clientY: 40,
+    });
+    expect(captured).toEqual([]);
+  });
+
+  it('still drags when the press that started in the list actually moves', () => {
+    const { panel } = renderPanel(
+      <FloatingPanel anchor="top-left">
+        <ul>
+          <li>row</li>
+        </ul>
+      </FloatingPanel>,
+    );
+    fireEvent.pointerDown(screen.getByText('row'), { pointerId: 1, clientX: 100, clientY: 100 });
+    fireEvent.pointerMove(panel, { pointerId: 1, clientX: 200, clientY: 100 });
+    expect(panel.dataset.dragging).toBe('true');
+  });
+});

package/src/primitives/FloatingPanel.tsx

@@ -37,6 +37,9 @@ function borderBoxOf(entry: ResizeObserverEntry): { w: number; h: number } {
   return { w: entry.contentRect.width, h: entry.contentRect.height };
 }
 
+/** How far the pointer must travel before a press becomes a drag. */
+const DRAG_THRESHOLD = 3;
+
 /** A pointerdown on one of these is the child's, not a drag. */
 function isInteractive(target: EventTarget | null): boolean {
   if (!(target instanceof Element)) return false;
@@ -127,18 +130,30 @@ export function FloatingPanel({
     .placements.get(ITEM_ID);
 
   const dragging = useRef<{ x: number; y: number } | null>(null);
+  /** Pressed but not yet moved far enough to be a drag. */
+  const pending = useRef<{ x: number; y: number; pointerId: number } | null>(null);
   const [isDragging, setDragging] = useState(false);
 
   const onPointerDown = (e: React.PointerEvent<HTMLDivElement>) => {
     if (isInteractive(e.target)) return;
     // The canvas stack underneath owns pan/zoom on the same pointer events.
     e.stopPropagation();
-    dragging.current = { x: e.clientX, y: e.clientY };
-    setDragging(true);
-    e.currentTarget.setPointerCapture?.(e.pointerId);
+    // Armed, not capturing. Capture retargets mouseup to this element, and the
+    // browser then synthesizes no `click` on the child under the cursor — so
+    // capturing on press makes every non-native control in the panel dead to a
+    // real mouse, silently. `isInteractive` only exempts the names it lists; a
+    // `role="button"` span, a react-aria control or a canvas is not among them.
+    pending.current = { x: e.clientX, y: e.clientY, pointerId: e.pointerId };
   };
 
   const onPointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
+    const armed = pending.current;
+    if (armed && armed.pointerId === e.pointerId && !dragging.current) {
+      if (Math.hypot(e.clientX - armed.x, e.clientY - armed.y) < DRAG_THRESHOLD) return;
+      dragging.current = { x: armed.x, y: armed.y };
+      setDragging(true);
+      e.currentTarget.setPointerCapture?.(e.pointerId);
+    }
     const from = dragging.current;
     if (!from) return;
     const dx = e.clientX - from.x;
@@ -160,6 +175,7 @@ export function FloatingPanel({
   };
 
   const endDrag = (e: React.PointerEvent<HTMLDivElement>) => {
+    pending.current = null;
     if (!dragging.current) return;
     dragging.current = null;
     setDragging(false);

package/src/primitives/ScaleIndicator.test.tsx

@@ -1,6 +1,7 @@
 import { render, screen } from '@testing-library/react';
 import { describe, expect, test } from 'vitest';
 import { CanvasStackContext } from '../canvas/CanvasStackContext';
+import { DEFAULT_FRAME } from '../canvas/worldSpec';
 import { ScaleIndicator } from './ScaleIndicator';
 
 describe('ScaleIndicator', () => {
@@ -27,7 +28,9 @@ describe('ScaleIndicator', () => {
 
   test('reads zoom from CanvasStackContext when prop omitted', () => {
     render(
-      <CanvasStackContext.Provider value={{ view: { zoom: 2.5, pan: { x: 0, y: 0 } } }}>
+      <CanvasStackContext.Provider
+        value={{ view: { zoom: 2.5, pan: { x: 0, y: 0 } }, frame: DEFAULT_FRAME }}
+      >
         <ScaleIndicator pixelsPerUnit={50} unit="ft" />
       </CanvasStackContext.Provider>,
     );
@@ -37,7 +40,9 @@ describe('ScaleIndicator', () => {
 
   test('explicit zoom prop overrides context', () => {
     render(
-      <CanvasStackContext.Provider value={{ view: { zoom: 100, pan: { x: 0, y: 0 } } }}>
+      <CanvasStackContext.Provider
+        value={{ view: { zoom: 100, pan: { x: 0, y: 0 } }, frame: DEFAULT_FRAME }}
+      >
         <ScaleIndicator zoom={1} pixelsPerUnit={50} unit="ft" />
       </CanvasStackContext.Provider>,
     );

package/src/primitives/Sidebar.less

@@ -62,7 +62,25 @@
   border-bottom: var(--wzl-border-w) solid var(--wzl-line-subtle);
 }
 
+.lk-sidebar-section__bar {
+  display: flex;
+  align-items: center;
+}
+
+.lk-sidebar-section__undock {
+  padding: 0 var(--wzl-space-xs);
+  border: 0;
+  background: transparent;
+  color: var(--wzl-fg-subtle);
+  cursor: pointer;
+
+  &:hover {
+    color: var(--wzl-fg);
+  }
+}
+
 .lk-sidebar-section__head {
+  flex: 1;
   width: 100%;
   padding: var(--wzl-space-xs);
   border: 0;

package/src/primitives/Toolbar.less

@@ -73,6 +73,14 @@
     border-color: var(--wzl-border);
   }
 
+  // A toggle that is on stays on when the pointer leaves, so it reads as held
+  // rather than hovered — the hover rule alone would be indistinguishable.
+  &--pressed {
+    background: var(--wzl-accent-soft);
+    border-color: var(--wzl-accent);
+    color: var(--wzl-fg);
+  }
+
   &--danger:hover:not(:disabled) {
     color: var(--wzl-danger);
     border-color: var(--wzl-danger);

package/src/primitives/Toolbar.tsx

@@ -70,6 +70,8 @@ export interface ToolbarButtonProps {
   variant?: 'default' | 'danger';
   /** Square, for a button whose whole content is one glyph. */
   iconOnly?: boolean;
+  /** Makes this a toggle: `aria-pressed`, and held down while true. */
+  pressed?: boolean;
 }
 
 function Button({
@@ -80,11 +82,13 @@ function Button({
   'aria-label': ariaLabel,
   variant = 'default',
   iconOnly,
+  pressed,
 }: ToolbarButtonProps) {
   const cls = [
     'lk-toolbar-button',
     variant === 'danger' && 'lk-toolbar-button--danger',
     iconOnly && 'lk-toolbar-button--icon',
+    pressed && 'lk-toolbar-button--pressed',
   ]
     .filter(Boolean)
     .join(' ');
@@ -96,6 +100,7 @@ function Button({
       disabled={disabled}
       title={title}
       aria-label={ariaLabel ?? title}
+      aria-pressed={pressed}
     >
       {children}
     </button>

package/src/primitives/useRovingTabIndex.test.ts

@@ -25,3 +25,24 @@ describe('nextIndex', () => {
     expect(nextIndex(0, 'ArrowRight', 0)).toBeNull();
   });
 });
+
+describe('nextIndex — vertical', () => {
+  it('walks the down/up arrows', () => {
+    expect(nextIndex(0, 'ArrowDown', 3, 'vertical')).toBe(1);
+    expect(nextIndex(2, 'ArrowDown', 3, 'vertical')).toBe(0);
+    expect(nextIndex(1, 'ArrowUp', 3, 'vertical')).toBe(0);
+    expect(nextIndex(0, 'ArrowUp', 3, 'vertical')).toBe(2);
+  });
+
+  it('leaves the cross-axis arrows to the page', () => {
+    expect(nextIndex(0, 'ArrowRight', 3, 'vertical')).toBeNull();
+    expect(nextIndex(0, 'ArrowLeft', 3, 'vertical')).toBeNull();
+    expect(nextIndex(0, 'ArrowDown', 3)).toBeNull();
+    expect(nextIndex(0, 'ArrowUp', 3)).toBeNull();
+  });
+
+  it('still jumps to the ends', () => {
+    expect(nextIndex(1, 'Home', 3, 'vertical')).toBe(0);
+    expect(nextIndex(1, 'End', 3, 'vertical')).toBe(2);
+  });
+});