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

package/src/chrome/regions/PaletteRegion.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 import type { TrialChromeContext, TrialContribution } from '../types';
 import { PaletteRegion } from './PaletteRegion';
@@ -33,4 +33,25 @@ describe('PaletteRegion', () => {
     screen.getByRole('button', { name: 'brush' }).click();
     expect(setActiveTool).toHaveBeenCalledWith('brush');
   });
+
+  it('puts exactly one tool in the tab order', () => {
+    render(<PaletteRegion contributions={[tool('brush'), tool('eraser')]} ctx={ctxWith(null)} />);
+    expect(screen.getByRole('button', { name: 'brush' })).toHaveAttribute('tabindex', '0');
+    expect(screen.getByRole('button', { name: 'eraser' })).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('walks the vertical strip with ArrowDown, and leaves ArrowRight to the page', () => {
+    render(<PaletteRegion contributions={[tool('brush'), tool('eraser')]} ctx={ctxWith(null)} />);
+    const strip = screen.getByRole('toolbar', { name: 'Tools' });
+    const brush = screen.getByRole('button', { name: 'brush' });
+    const eraser = screen.getByRole('button', { name: 'eraser' });
+
+    brush.focus();
+    fireEvent.keyDown(strip, { key: 'ArrowDown' });
+    expect(document.activeElement).toBe(eraser);
+    expect(eraser).toHaveAttribute('tabindex', '0');
+
+    fireEvent.keyDown(strip, { key: 'ArrowRight' });
+    expect(document.activeElement).toBe(eraser);
+  });
 });

package/src/chrome/regions/PaletteRegion.tsx

@@ -1,4 +1,5 @@
 import { ToolButton, ToolGroup } from '../../passthrough/weasel-ui';
+import { useRovingTabIndex } from '../../primitives/useRovingTabIndex';
 import type { TrialChromeContext, TrialContribution } from '../types';
 
 /** Props for `<PaletteRegion>`. */
@@ -10,13 +11,16 @@ export interface PaletteRegionProps {
 /** A trial's tool strip. Selection lives in the trial's or the lab's tool
  *  slot; this region only reflects it. */
 export function PaletteRegion({ contributions, ctx }: PaletteRegionProps) {
+  const { ref, onKeyDown } = useRovingTabIndex<HTMLDivElement>('vertical');
   if (contributions.length === 0) return null;
   return (
     <div
+      ref={ref}
       className="lk-palette-region"
       role="toolbar"
       aria-label="Tools"
       aria-orientation="vertical"
+      onKeyDown={onKeyDown}
     >
       <ToolGroup orientation="vertical">
         {contributions.map((c) => {

package/src/chrome/regions/SidebarRegion.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 import { useState } from 'react';
-import type { TrialChromeContext, TrialContribution } from '../types';
+import type { SidebarSection, TrialChromeContext, TrialContribution } from '../types';
 
 /** Props for `<SidebarRegion>`. */
 export interface SidebarRegionProps {
@@ -11,29 +11,46 @@ export interface SidebarRegionProps {
 function Section({
   title,
   defaultCollapsed,
+  onUndock,
   children,
 }: {
   title: string;
   defaultCollapsed: boolean;
+  onUndock?: () => void;
   children: ReactNode;
 }) {
   const [collapsed, setCollapsed] = useState(defaultCollapsed);
   return (
     <section className="lk-sidebar-section">
-      <button
-        type="button"
-        className="lk-sidebar-section__head"
-        aria-expanded={!collapsed}
-        onClick={() => setCollapsed((c) => !c)}
-      >
-        {title}
-      </button>
+      <div className="lk-sidebar-section__bar">
+        <button
+          type="button"
+          className="lk-sidebar-section__head"
+          aria-expanded={!collapsed}
+          onClick={() => setCollapsed((c) => !c)}
+        >
+          {title}
+        </button>
+        {onUndock ? (
+          <button
+            type="button"
+            className="lk-sidebar-section__undock"
+            aria-label={`Undock ${title}`}
+            title={`Undock ${title}`}
+            onClick={onUndock}
+          >
+            ⧉
+          </button>
+        ) : null}
+      </div>
       {collapsed ? null : <div className="lk-sidebar-section__body">{children}</div>}
     </section>
   );
 }
 
-/** Lays a trial's `sidebar` contributions out as titled, collapsible sections. */
+/** Lays a trial's `sidebar` contributions out as titled, collapsible sections.
+ *  A section the trial has torn out is not rendered here — `Trial` portals its
+ *  body into the workspace instead. */
 export function SidebarRegion({ contributions, ctx }: SidebarRegionProps) {
   if (contributions.length === 0) return null;
   return (
@@ -41,13 +58,20 @@ export function SidebarRegion({ contributions, ctx }: SidebarRegionProps) {
       {contributions.map((c) => {
         if (c.render) return <div key={c.id}>{c.render(ctx)}</div>;
         if (c.region !== 'sidebar' || !c.item) return null;
+        if (ctx.undockedPanels.includes(c.id)) return null;
+        const item = c.item as SidebarSection;
         return (
           <Section
             key={c.id}
-            title={c.item.title}
-            defaultCollapsed={c.item.defaultCollapsed ?? false}
+            title={item.title}
+            defaultCollapsed={item.defaultCollapsed ?? false}
+            onUndock={
+              item.undockable === false
+                ? undefined
+                : () => ctx.undockPanel(c.id, item.undockAs ?? 'tile')
+            }
           >
-            {c.item.body}
+            {item.body}
           </Section>
         );
       })}

package/src/chrome/regions/ToolbarRegion.tsx

@@ -38,13 +38,14 @@ function groupsOf(contributions: readonly TrialContribution[]): Group[] {
 function renderEntry(c: TrialContribution, ctx: TrialChromeContext): ReactNode {
   if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
   if (c.region !== 'toolbar' || !c.item) return null;
-  const { icon: Icon, label, shortcut, disabled, danger, showLabel } = c.item;
+  const { icon: Icon, label, shortcut, disabled, danger, showLabel, pressed } = c.item;
   return (
     <Toolbar.Button
       key={c.id}
       iconOnly={!showLabel}
       variant={danger ? 'danger' : 'default'}
       disabled={disabled}
+      pressed={pressed}
       aria-label={label}
       title={shortcut ? `${label} (${shortcut})` : label}
       onClick={c.item.onActivate}

package/src/chrome/regions/ViewportRegion.tsx

@@ -1,3 +1,4 @@
+import { useRovingTabIndex } from '../../primitives/useRovingTabIndex';
 import type { TrialChromeContext, TrialContribution } from '../types';
 
 /** Props for `<ViewportRegion>`. */
@@ -11,9 +12,16 @@ export interface ViewportRegionProps {
  * rather than in the toolbar, which acts on the trial itself.
  */
 export function ViewportRegion({ contributions, ctx }: ViewportRegionProps) {
+  const { ref, onKeyDown } = useRovingTabIndex<HTMLDivElement>();
   if (contributions.length === 0) return null;
   return (
-    <div className="lk-viewport-controls" role="toolbar" aria-label="View">
+    <div
+      ref={ref}
+      className="lk-viewport-controls"
+      role="toolbar"
+      aria-label="View"
+      onKeyDown={onKeyDown}
+    >
       {contributions.map((c) => {
         if (c.render) return <span key={c.id}>{c.render(ctx)}</span>;
         if (c.region !== 'viewport' || !c.item) return null;

package/src/chrome/regions/regions.test.tsx

@@ -6,7 +6,12 @@ import { StatusRegion } from './StatusRegion';
 import { ViewportRegion } from './ViewportRegion';
 
 const Glyph = () => <svg />;
-const ctx = { trialId: 't1' } as unknown as TrialChromeContext;
+const ctx = {
+  trialId: 't1',
+  undockedPanels: [],
+  undockPanel: () => {},
+  dockPanel: () => {},
+} as unknown as TrialChromeContext;
 
 describe('SidebarRegion', () => {
   it('renders nothing when empty', () => {

package/src/chrome/types.ts

@@ -19,6 +19,9 @@ export interface ToolbarItem {
   disabled?: boolean;
   /** Reddens on hover. For actions that discard work. */
   danger?: boolean;
+  /** A toggle rather than a command: renders `aria-pressed` and reads as held
+   *  down while true. */
+  pressed?: boolean;
   /** Render the label beside the glyph rather than only in the tooltip. */
   showLabel?: boolean;
   onActivate: () => void;
@@ -37,6 +40,11 @@ export interface SidebarSection {
   title: string;
   /** Starts collapsed. The open/closed state itself is the region's. */
   defaultCollapsed?: boolean;
+  /** Offer the tear-out control. On by default; a section that only makes
+   *  sense beside its trial sets this false. */
+  undockable?: boolean;
+  /** Where the tear-out control sends it. Default `'tile'`. */
+  undockAs?: 'tile' | 'floating';
   body: ReactNode;
 }
 
@@ -103,6 +111,11 @@ export interface TrialChromeContext {
   undo: () => void;
   redo: () => void;
 
+  /** Whether the trial's loupe is turned on. False for an instrument that
+   *  declares none, whose chrome offers no way to turn one on. */
+  loupeOn: boolean;
+  toggleLoupe: () => void;
+
   /** The instrument's controls, resolved against the lab's rules. Always
    *  populated: a legacy `configSchema()` is adapted into the same shape. */
   configSchema: ResolvedConfig;
@@ -112,6 +125,13 @@ export interface TrialChromeContext {
   config: unknown;
   setConfig: (key: string, value: unknown) => void;
 
+  /** Section ids this trial currently has torn out of its sidebar. */
+  undockedPanels: readonly string[];
+  /** Tear a sidebar section out into the workspace. */
+  undockPanel: (sectionId: string, as?: 'tile' | 'floating') => void;
+  /** Put a torn-out section back in the sidebar. */
+  dockPanel: (sectionId: string) => void;
+
   savedSnapshots: SavedSnapshot[];
   saveSnapshot: (name?: string) => void;
   loadSnapshot: (snapshotId: string) => void;

package/src/controls/ControlPanel.test.tsx

@@ -382,3 +382,41 @@ describe('<ControlPanel> built-in kind coverage', () => {
     ).toThrow(/spline/);
   });
 });
+
+describe('<ControlPanel> packing', () => {
+  const schema = resolveConfigSchema(
+    f.schema({ width: f.number(256), title: f.string('a'), tint: f.color('#ff0000') }),
+    [],
+  );
+  const config = { width: 256, title: 'a', tint: '#ff0000' };
+  // jsdom lays out no grid, so the class the grid rules key off is the proxy
+  // for "these rows pair" — a layout assertion is not available here.
+  const list = (container: HTMLElement) => container.querySelector('.lk-control-panel');
+  const rowOf = (name: string) => screen.getByLabelText(name).closest('label');
+
+  it('packs two rows to a line by default', () => {
+    const { container } = render(
+      <ControlPanel schema={schema} config={config} setConfig={vi.fn()} />,
+    );
+    expect(list(container)?.className).toMatch(/listPairs/);
+    expect(rowOf('Width')?.className).not.toMatch(/span/);
+  });
+
+  it('gives every row its own line under one-up', () => {
+    const { container } = render(
+      <ControlPanel schema={schema} config={config} setConfig={vi.fn()} pack="one-up" />,
+    );
+    expect(list(container)?.className).not.toMatch(/listPairs/);
+  });
+
+  it('spans the rows that need the width under auto, and pairs the rest', () => {
+    render(<ControlPanel schema={schema} config={config} setConfig={vi.fn()} pack="auto" />);
+    expect(rowOf('Title')?.className).toMatch(/span/);
+    expect(rowOf('Width')?.className).not.toMatch(/span/);
+  });
+
+  it('passes its layout down to the rows', () => {
+    render(<ControlPanel schema={schema} config={config} setConfig={vi.fn()} layout="inline" />);
+    expect(rowOf('Width')?.className).toMatch(/rowInline/);
+  });
+});

package/src/controls/ControlPanel.tsx

@@ -7,6 +7,7 @@ import {
   PropertyGroup,
   PropertyList,
   PropertyRow,
+  type PropertyRowLayout,
   SelectRow,
   SliderRow,
   TextRow,
@@ -18,6 +19,16 @@ import type { ControlRenderer, ResolvedConfig } from '../config/types';
 import { isLeafVisible } from '../config/visible';
 import type { ConfigField } from './types';
 
+/** How a panel packs its rows into the two-column property grid.
+ *   - `'auto'`: narrow controls (numbers, checkboxes, dropdowns, colours) sit
+ *     two per row; the ones that need the width — text, sliders, segmented
+ *     toggles — span it.
+ *   - `'pairs'`: every row pairs. A control that needs the full width says so
+ *     itself, with `<PropertyRow span>`.
+ *   - `'one-up'`: one control per row, colours excepted.
+ */
+export type ControlPack = 'auto' | 'pairs' | 'one-up';
+
 export interface ControlPanelProps<TC extends Record<string, unknown>> {
   /** The instrument's resolved config schema. */
   schema?: ResolvedConfig;
@@ -31,6 +42,11 @@ export interface ControlPanelProps<TC extends Record<string, unknown>> {
    * the row; entries override the built-in rows on collision.
    */
   renderers?: Record<string, ControlRenderer>;
+  /** How rows pack into the two-column grid. Defaults to `'pairs'`. */
+  pack?: ControlPack;
+  /** Where a row's label sits relative to its control. Defaults to `'block'`
+   *  — above it, which is what leaves a paired row room for its value. */
+  layout?: PropertyRowLayout;
   /** Draw leaves marked `hidden`. */
   showHidden?: boolean;
   className?: string;
@@ -45,6 +61,8 @@ export function ControlPanel<TC extends Record<string, unknown>>({
   config,
   setConfig,
   renderers,
+  pack = 'pairs',
+  layout = 'block',
   showHidden = false,
   className,
 }: ControlPanelProps<TC>) {
@@ -62,15 +80,21 @@ export function ControlPanel<TC extends Record<string, unknown>>({
       config={config}
       setConfig={setConfig}
       renderers={renderers}
+      pack={pack}
+      layout={layout}
       showHidden={showHidden}
     />
   );
 
+  const gridPack = pack === 'one-up' ? 'auto-color' : 'pairs';
   return (
-    <PropertyList className={className ? `lk-control-panel ${className}` : 'lk-control-panel'}>
+    <PropertyList
+      pack={gridPack}
+      className={className ? `lk-control-panel ${className}` : 'lk-control-panel'}
+    >
       {loose.map(row)}
       {resolved.sections.map((section) => (
-        <PropertyGroup key={section.label} title={section.label}>
+        <PropertyGroup key={section.label} title={section.label} pack={gridPack}>
           {section.paths.map(row)}
         </PropertyGroup>
       ))}
@@ -84,6 +108,8 @@ interface ControlRowProps<TC extends Record<string, unknown>> {
   config: TC;
   setConfig: (key: keyof TC, value: unknown) => void;
   renderers?: Record<string, ControlRenderer>;
+  pack: ControlPack;
+  layout: PropertyRowLayout;
   showHidden: boolean;
 }
 
@@ -99,6 +125,8 @@ function ControlRow<TC extends Record<string, unknown>>({
   config,
   setConfig,
   renderers,
+  pack,
+  layout,
   showHidden,
 }: ControlRowProps<TC>) {
   const leaf = resolved.group.children[path] as PrefLeaf | undefined;
@@ -112,11 +140,16 @@ function ControlRow<TC extends Record<string, unknown>>({
   // Most specific wins, and within a tier the lab's entry beats the
   // instrument's: controls[path] -> node .render -> controls[kind] -> built-in.
   const custom = renderers?.[path] ?? resolved.renderers[path] ?? renderers?.[leaf.kind];
+  // A custom row places itself like any other; one that needs the full width
+  // says so with `<PropertyRow span>`, which is the same opt-out a built-in has.
   if (custom) return custom({ path, pref: leaf, value, setValue: write });
 
   const label = leaf.name;
   const description = leaf.description;
   const read = <T,>(): T => value as T;
+  // `auto` gives the whole width to the controls that read badly at half of a
+  // sidebar's: free text, a slider track, a segmented toggle. `pairs` doesn't.
+  const wide = pack === 'auto';
 
   if (!isBuiltinToolPref(leaf))
     return <UnwiredRow label={label} kind={leaf.kind} description={description} />;
@@ -135,6 +168,8 @@ function ControlRow<TC extends Record<string, unknown>>({
             max={max}
             step={step}
             onChange={write}
+            layout={layout}
+            span={wide}
             description={description}
           />
         );
@@ -152,6 +187,7 @@ function ControlRow<TC extends Record<string, unknown>>({
           max={max}
           step={step}
           onChange={(n) => write(Math.min(hi, Math.max(lo, n)))}
+          layout={layout}
           description={description}
         />
       );
@@ -167,13 +203,16 @@ function ControlRow<TC extends Record<string, unknown>>({
       );
     case 'enum': {
       const options = extra<readonly { value: string; label: string }[]>(leaf, 'options') ?? [];
-      const Row = extra<string>(leaf, 'control') === 'radio' ? ToggleRow : SelectRow;
+      const segmented = extra<string>(leaf, 'control') === 'radio';
+      const Row = segmented ? ToggleRow : SelectRow;
       return (
         <Row
           label={label}
           value={read<string>()}
           options={options}
           onChange={write}
+          layout={layout}
+          span={segmented && wide}
           description={description}
         />
       );
@@ -185,6 +224,8 @@ function ControlRow<TC extends Record<string, unknown>>({
           label={label}
           value={read<string>()}
           write={write}
+          layout={layout}
+          span={wide}
           description={description}
         />
       );
@@ -235,12 +276,16 @@ function DebouncedTextRow({
   label,
   value,
   write,
+  layout,
+  span,
   description,
 }: {
   leaf: PrefLeaf;
   label: string;
   value: string;
   write: (value: unknown) => void;
+  layout?: PropertyRowLayout;
+  span?: boolean;
   description?: string;
 }) {
   const debounceMs = extra<number>(leaf, 'debounceMs') ?? 150;
@@ -265,6 +310,8 @@ function DebouncedTextRow({
   return (
     <TextRow
       label={label}
+      layout={layout}
+      span={span}
       description={description}
       value={local}
       placeholder={extra<string>(leaf, 'placeholder')}

package/src/dragdrop/DragDropRuntime.tsx

@@ -1,6 +1,7 @@
 import { useVisibleRaf } from '@weasel-js/core';
 import { type RefObject, useCallback, useEffect, useRef, useState } from 'react';
 import { screenToWorld } from '../canvas/canvasCoords';
+import { resolveFrame, type WorldSpec } from '../canvas/worldSpec';
 import type {
   DragDropCapability,
   DragFeedback,
@@ -20,6 +21,9 @@ export interface UseDragDropArgs<TS, TC> {
   capability: DragDropCapability<TS, TC>;
   canvasContainerRef: RefObject<HTMLElement | null>;
   view: ViewTransform;
+  /** The instrument's coordinate system, resolved against the container each
+   *  time a screen point is converted — the container is what knows its size. */
+  worldSpec?: WorldSpec;
   state: TS;
   config: TC;
   setState: (next: TS | ((prev: TS) => TS)) => void;
@@ -39,6 +43,7 @@ export function useDragDrop<TS, TC>({
   config,
   setState,
   emit,
+  worldSpec,
 }: UseDragDropArgs<TS, TC>): UseDragDropResult {
   const [drag, setDrag] = useState<DragState | null>(null);
   const dragRef = useRef<DragState | null>(null);
@@ -67,9 +72,10 @@ export function useDragDrop<TS, TC>({
       const el = canvasContainerRef.current;
       if (!el) return null;
       const r = el.getBoundingClientRect();
-      return screenToWorld({ x: screenPos.x - r.left, y: screenPos.y - r.top }, view);
+      const frame = resolveFrame(worldSpec, { width: r.width, height: r.height });
+      return screenToWorld({ x: screenPos.x - r.left, y: screenPos.y - r.top }, view, frame);
     },
-    [canvasContainerRef, view],
+    [canvasContainerRef, view, worldSpec],
   );
 
   const frameLoop = useVisibleRaf(() => {

package/src/dragdrop/dragDrop.test.tsx

@@ -41,9 +41,19 @@ function StateProbe({ onState }: { onState: (state: DropState) => void }) {
   return null;
 }
 
-function renderLab(probe?: (state: DropState) => void) {
+const centredInstrument = defineInstrument<DropState, Record<string, never>>({
+  ...testInstrument,
+  name: 'CentredDrop',
+  canvas: {
+    worldSpec: { origin: { x: 0.5, y: 0.5 }, yAxis: 'up' },
+    initialView: { zoom: 1, pan: { x: 0, y: 0 } },
+    layers: [{ id: 'main', draw: () => undefined }],
+  },
+});
+
+function renderLab(probe?: (state: DropState) => void, instrument = testInstrument) {
   return render(
-    <Lab instruments={[testInstrument]} defaultInstrument="TestDrop">
+    <Lab instruments={[instrument]} defaultInstrument={instrument.name}>
       {probe ? <StateProbe onState={probe} /> : null}
     </Lab>,
   );
@@ -139,4 +149,21 @@ describe('DragDrop integration', () => {
     windowPointerUp(250, 250);
     expect(document.querySelector('.lk-drag-ghost')).toBeNull();
   });
+
+  it('drops through the instrument world spec, not the canvas top-left', () => {
+    let latest: DropState = { items: [] };
+    renderLab((s) => {
+      latest = s;
+    }, centredInstrument);
+    const palette = screen.getByRole('button', { name: 'Item A' });
+
+    act(() => {
+      pointerDown(palette, 0, 0);
+    });
+    // The host spans (100,100)-(500,500), so its centre is at (300,300).
+    // Dropping 50px right of centre and 50px above it, at zoom 1, y up.
+    windowPointerUp(350, 250);
+
+    expect(latest.items[0]).toMatchObject({ x: 50, y: 50 });
+  });
 });

package/src/index.test.ts

@@ -60,11 +60,34 @@ describe('surface, job and orbit entry points', () => {
     expect(typeof kit.useSurfaceOptional).toBe('function');
     expect(typeof kit.toDeviceRect).toBe('function');
     expect(typeof kit.composeRects).toBe('function');
+    expect(typeof kit.createAnnotationStore).toBe('function');
+    expect(typeof kit.createAnnotationScene).toBe('function');
+    expect(typeof kit.annotationsFromJSON).toBe('function');
+    expect(typeof kit.seenFrom).toBe('function');
+    expect(typeof kit.fracToWorld).toBe('function');
     expect(typeof kit.useOrbit).toBe('function');
     expect(typeof kit.orbitAfterDrag).toBe('function');
+    expect(typeof kit.usePanZoom).toBe('function');
     expect(typeof kit.useJob).toBe('function');
     expect(typeof kit.as2DView).toBe('function');
     expect(kit.SurfaceContext).toBeDefined();
+    expect(kit.SurfaceCanvasContext).toBeDefined();
+    expect(typeof kit.useSurfaceCanvas).toBe('function');
+  });
+});
+
+describe('the annotations capability', () => {
+  it('reaches a host through the package root', async () => {
+    const kit = await import('./index');
+    expect(typeof kit.useAnnotations).toBe('function');
+    expect(typeof kit.useAnnotationsOptional).toBe('function');
+    expect(typeof kit.AnnotationTargets).toBe('function');
+    expect(typeof kit.AnnotationOverlay).toBe('function');
+    expect(typeof kit.markCommands).toBe('function');
+    expect(typeof kit.annotationToolInfo).toBe('function');
+    expect(typeof kit.fitView).toBe('function');
+    expect(kit.ANNOTATION_TOOLS.map((t) => t.id)).toContain('arrow');
+    expect(typeof kit.MarkList).toBe('function');
     expect(kit.DEFAULT_VIEW).toEqual({ zoom: 1, pan: { x: 0, y: 0 } });
   });
 });