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

package/src/primitives/useRovingTabIndex.ts

@@ -1,20 +1,27 @@
 import { type KeyboardEvent, useCallback, useEffect, useRef } from 'react';
 
-/** Where a key takes focus within `count` items, or null if it does not move it. */
-export function nextIndex(current: number, key: string, count: number): number | null {
+/** Which axis a toolbar's arrow keys walk. Matches `aria-orientation`. */
+export type RovingOrientation = 'horizontal' | 'vertical';
+
+/** Where a key takes focus within `count` items, or null if it does not move it.
+ *
+ *  Only the arrows on the toolbar's own axis move focus — APG leaves the
+ *  cross-axis arrows to the page, so a vertical strip does not swallow
+ *  ArrowLeft. `Home` / `End` work on both. */
+export function nextIndex(
+  current: number,
+  key: string,
+  count: number,
+  orientation: RovingOrientation = 'horizontal',
+): number | null {
   if (count === 0) return null;
-  switch (key) {
-    case 'ArrowRight':
-      return (current + 1) % count;
-    case 'ArrowLeft':
-      return (current - 1 + count) % count;
-    case 'Home':
-      return 0;
-    case 'End':
-      return count - 1;
-    default:
-      return null;
-  }
+  const forward = orientation === 'vertical' ? 'ArrowDown' : 'ArrowRight';
+  const back = orientation === 'vertical' ? 'ArrowUp' : 'ArrowLeft';
+  if (key === forward) return (current + 1) % count;
+  if (key === back) return (current - 1 + count) % count;
+  if (key === 'Home') return 0;
+  if (key === 'End') return count - 1;
+  return null;
 }
 
 /**
@@ -23,7 +30,9 @@ export function nextIndex(current: number, key: string, count: number): number |
  * threaded through props, because the items are arbitrary children — the
  * container never sees them as a list it could index.
  */
-export function useRovingTabIndex<T extends HTMLElement>() {
+export function useRovingTabIndex<T extends HTMLElement>(
+  orientation: RovingOrientation = 'horizontal',
+) {
   const ref = useRef<T | null>(null);
   const stop = useRef(0);
 
@@ -66,13 +75,13 @@ export function useRovingTabIndex<T extends HTMLElement>() {
     (e: KeyboardEvent<T>) => {
       const found = items();
       const current = found.indexOf(document.activeElement as HTMLElement);
-      const next = nextIndex(current === -1 ? 0 : current, e.key, found.length);
+      const next = nextIndex(current === -1 ? 0 : current, e.key, found.length, orientation);
       if (next === null) return;
       e.preventDefault();
       found[next]?.focus();
       setTabStop(next);
     },
-    [items, setTabStop],
+    [items, setTabStop, orientation],
   );
 
   return { ref, onKeyDown };

package/src/state/document.test.ts

@@ -8,6 +8,7 @@ import {
   MIGRATIONS,
   migrateV0toV1,
   migrateV1toV2,
+  migrateV2toV3,
   normalizeDocument,
   quarantineDocument,
   quarantineKey,
@@ -324,6 +325,7 @@ describe('normalizeDocument', () => {
       trials: [],
       saves: [],
       layout: {},
+      undockedPanels: {},
       mode: 'auto',
     });
   });
@@ -367,3 +369,24 @@ describe('normalizeDocument', () => {
     expect(out.layout).toEqual({});
   });
 });
+
+describe('version 2 to version 3', () => {
+  it('gives a document with no undocked panels an empty set', () => {
+    const out = migrateV2toV3({ version: 2, trials: [], saves: [], layout: {}, mode: 'auto' });
+    expect(out.version).toBe(3);
+    expect(out.undockedPanels).toEqual({});
+  });
+
+  it('leaves the rest of the document alone', () => {
+    const out = migrateV2toV3({
+      version: 2,
+      trials: [{ id: 'a' }],
+      saves: [],
+      layout: { a: 1 },
+      mode: 'dark',
+    });
+    expect(out.trials).toEqual([{ id: 'a' }]);
+    expect(out.layout).toEqual({ a: 1 });
+    expect(out.mode).toBe('dark');
+  });
+});

package/src/state/document.ts

@@ -7,9 +7,10 @@ import type {
   SerializedTrial,
   StorageAdapter,
 } from './types';
+import type { UndockedPanels } from './undock';
 
 /** Bumped whenever the persisted shape changes; every bump needs a migration. */
-export const CURRENT_DOCUMENT_VERSION = 2;
+export const CURRENT_DOCUMENT_VERSION = 3;
 
 /** The one key a lab persists under. The `:doc` suffix keeps it out of the
  *  legacy bucket namespace, where a lab named `a:saves` would otherwise write
@@ -28,6 +29,7 @@ export function quarantineKey(storageKey: string): string {
 export function emptyDocument(mode: LabMode): LabDocument {
   return {
     version: CURRENT_DOCUMENT_VERSION,
+    undockedPanels: {},
     trials: [],
     saves: [],
     layout: {},
@@ -161,6 +163,10 @@ export function normalizeDocument(
     saves: Array.isArray(doc.saves) ? (doc.saves as SavedSnapshot[]) : [],
     layout:
       doc.layout && typeof doc.layout === 'object' ? (doc.layout as Record<string, unknown>) : {},
+    undockedPanels:
+      doc.undockedPanels && typeof doc.undockedPanels === 'object'
+        ? (doc.undockedPanels as UndockedPanels)
+        : {},
     mode,
   };
 }
@@ -190,5 +196,11 @@ export function migrateV1toV2(doc: Record<string, unknown>): Record<string, unkn
   return { ...rest, trials: Array.isArray(workspaces) ? workspaces : [], version: 2 };
 }
 
+/** Version 2 to version 3: undocked sidebar panels became persisted state.
+ *  Nothing existing moves; the field simply starts empty. */
+export function migrateV2toV3(doc: Record<string, unknown>): Record<string, unknown> {
+  return { ...doc, undockedPanels: {}, version: 3 };
+}
+
 /** Index `i` migrates a version-`i` document to version `i + 1`. */
-export const MIGRATIONS: Migration[] = [migrateV0toV1, migrateV1toV2];
+export const MIGRATIONS: Migration[] = [migrateV0toV1, migrateV1toV2, migrateV2toV3];

package/src/state/index.ts

@@ -45,4 +45,6 @@ export type {
   TrialStateHandle,
   UndoStack,
 } from './types';
+export type { UndockedPanel, UndockedPanels } from './undock';
+export { dockPanel, panelKey, undockPanel } from './undock';
 export { useTrialState } from './useTrialState';

package/src/state/store.test.ts

@@ -649,3 +649,27 @@ describe('createLabStore — folding without a mutation', () => {
     warn.mockRestore();
   });
 });
+
+describe('undocking a sidebar panel', () => {
+  it('starts with nothing undocked', () => {
+    expect(makeStore().getState().undockedPanels).toEqual({});
+  });
+
+  it('records an undock and docks it back', () => {
+    const s = makeStore();
+    s.getState().undockPanel('t1', 'settings', 'floating');
+    expect(Object.values(s.getState().undockedPanels)).toEqual([
+      { trialId: 't1', sectionId: 'settings', as: 'floating' },
+    ]);
+    s.getState().dockPanel('t1', 'settings');
+    expect(s.getState().undockedPanels).toEqual({});
+  });
+
+  it('closing a trial takes its undocked panels with it', () => {
+    const s = makeStore();
+    s.getState().addTrial({ id: 't1', instrumentName: 'i', config: {}, state: {}, view: null });
+    s.getState().undockPanel('t1', 'settings');
+    s.getState().removeTrial('t1');
+    expect(s.getState().undockedPanels).toEqual({});
+  });
+});

package/src/state/store.ts

@@ -20,6 +20,11 @@ import type {
   SavedSnapshot,
   TrialRecord,
 } from './types';
+import {
+  dockPanel as dockPanelIn,
+  type UndockedPanel,
+  undockPanel as undockPanelIn,
+} from './undock';
 
 /** Every mutation a lab store supports: managing trials, saving and
  *  restoring snapshots, and setting the color mode. */
@@ -29,6 +34,7 @@ export interface LabStoreActions {
   updateTrialState: <TS>(id: string, next: TS | ((prev: TS) => TS)) => void;
   updateTrialConfig: <TC>(id: string, key: keyof TC, value: TC[keyof TC]) => void;
   updateTrialView: (id: string, view: unknown) => void;
+  updateTrialAnnotations: (id: string, doc: unknown) => void;
   updateTrialUndoStack: (
     id: string,
     next: TrialRecord['undoStack'] | ((prev: TrialRecord['undoStack']) => TrialRecord['undoStack']),
@@ -42,6 +48,10 @@ export interface LabStoreActions {
   setLabTool: (id: string | null) => void;
   setTrialTool: (trialId: string, id: string | null) => void;
   setLayout: (layout: Record<string, unknown>) => void;
+  /** Tear a sidebar section out of its trial. Default target is a workspace tile. */
+  undockPanel: (trialId: string, sectionId: string, as?: UndockedPanel['as']) => void;
+  /** Put one section back, or — with no `sectionId` — every panel the trial owns. */
+  dockPanel: (trialId: string, sectionId?: string) => void;
 }
 
 /** A lab's store: its state and actions, plus the hook instruments use to
@@ -72,6 +82,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
     savedSnapshots: hydratedSnapshots,
     mode: hydratedMode,
     layout: hydratedLayout,
+    undockedPanels: hydrated.undockedPanels,
     activeToolId: null,
 
     addTrial: (record) => {
@@ -82,7 +93,10 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
     },
 
     removeTrial: (id) => {
-      set((s) => ({ trials: s.trials.filter((w) => w.id !== id) }));
+      set((s) => ({
+        trials: s.trials.filter((w) => w.id !== id),
+        undockedPanels: dockPanelIn(s.undockedPanels, id),
+      }));
       scheduleFlush();
     },
 
@@ -122,6 +136,15 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
       scheduleFlush();
     },
 
+    updateTrialAnnotations: (id, doc) => {
+      set((s) => ({
+        trials: s.trials.map((w) =>
+          w.id === id && !Object.is(doc, w.annotations) ? { ...w, annotations: doc } : w,
+        ),
+      }));
+      scheduleFlush();
+    },
+
     updateTrialUndoStack: (id, next) => {
       set((s) => ({
         trials: s.trials.map((w) => {
@@ -211,6 +234,16 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
         trials: s.trials.map((t) => (t.id === trialId ? { ...t, activeToolId: id } : t)),
       })),
 
+    undockPanel: (trialId, sectionId, as) => {
+      set((s) => ({ undockedPanels: undockPanelIn(s.undockedPanels, trialId, sectionId, as) }));
+      scheduleFlush();
+    },
+
+    dockPanel: (trialId, sectionId) => {
+      set((s) => ({ undockedPanels: dockPanelIn(s.undockedPanels, trialId, sectionId) }));
+      scheduleFlush();
+    },
+
     setLayout: (layout) => {
       set({ layout });
       scheduleFlush();
@@ -227,6 +260,7 @@ export function createLabStore(options: CreateLabStoreOptions): LabStore {
         trials: serializeTrials(s.trials, serializers),
         saves: s.savedSnapshots,
         layout: s.layout,
+        undockedPanels: s.undockedPanels,
         mode: s.mode,
       };
       const serialized = JSON.stringify(document);

package/src/state/types.ts

@@ -1,3 +1,4 @@
+import type { UndockedPanels } from './undock';
 /** A trial's undo history, as snapshots of its state either side of the
  *  present. */
 export interface UndoStack {
@@ -17,6 +18,11 @@ export interface TrialRecord<TS = unknown, TC = unknown, TV = unknown> {
   view: TV;
   /** This trial's own tool slot. Undefined means it reads the lab's. */
   activeToolId?: string | null;
+  /** The marks on this trial's annotation targets, as `AnnotationsApi.toJSON`
+   *  wrote them. Opaque here, and absent for a trial whose instrument declares
+   *  no `annotations` — or declares its own `storage`. Not in `state`, which
+   *  belongs to the instrument and is typed as such. */
+  annotations?: unknown;
   undoStack: UndoStack;
 }
 
@@ -46,6 +52,9 @@ export interface LabStoreState {
   /** Per-trial tile extents, keyed by trial id. Opaque here — the
    *  shape belongs to whatever lays the trials out. */
   layout: Record<string, unknown>;
+  /** Sidebar sections torn out of their trial. A panel here is not rendered in
+   *  its trial's sidebar; the workspace renders it instead. */
+  undockedPanels: UndockedPanels;
 }
 
 /** Where a lab persists itself. Implementations are keyed string storage and
@@ -91,6 +100,8 @@ export interface LabDocument {
   trials: SerializedTrial[];
   saves: SavedSnapshot[];
   layout: Record<string, unknown>;
+  /** Sidebar sections torn out of their trial, keyed by trial and section. */
+  undockedPanels: UndockedPanels;
   mode: LabMode;
 }
 

package/src/state/undock.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { dockPanel, panelKey, undockPanel } from './undock';
+
+describe('undocked panel bookkeeping', () => {
+  it('keys a panel by its trial and section, so two trials can undock the same section', () => {
+    expect(panelKey('t1', 'settings')).not.toBe(panelKey('t2', 'settings'));
+  });
+
+  it('records an undock as a tile by default', () => {
+    const next = undockPanel({}, 't1', 'settings');
+    expect(next[panelKey('t1', 'settings')]).toEqual({
+      trialId: 't1',
+      sectionId: 'settings',
+      as: 'tile',
+    });
+  });
+
+  it('records the requested target', () => {
+    const next = undockPanel({}, 't1', 'settings', 'floating');
+    expect(next[panelKey('t1', 'settings')]?.as).toBe('floating');
+  });
+
+  it('re-undocking to a different target moves it rather than adding a second', () => {
+    const once = undockPanel({}, 't1', 'settings', 'tile');
+    const twice = undockPanel(once, 't1', 'settings', 'floating');
+    expect(Object.keys(twice)).toHaveLength(1);
+    expect(twice[panelKey('t1', 'settings')]?.as).toBe('floating');
+  });
+
+  it('docking removes it and leaves other panels alone', () => {
+    const both = undockPanel(undockPanel({}, 't1', 'a'), 't1', 'b');
+    const next = dockPanel(both, 't1', 'a');
+    expect(Object.keys(next)).toEqual([panelKey('t1', 'b')]);
+  });
+
+  it('closing a trial takes its undocked panels with it', () => {
+    const panels = undockPanel(undockPanel({}, 't1', 'a'), 't2', 'a');
+    expect(Object.keys(dockPanel(panels, 't1'))).toEqual([panelKey('t2', 'a')]);
+  });
+});

package/src/state/undock.ts

@@ -0,0 +1,39 @@
+/** A sidebar section torn out of its trial, and where it went. */
+export interface UndockedPanel {
+  trialId: string;
+  sectionId: string;
+  as: 'tile' | 'floating';
+}
+
+/** Undocked panels, keyed by {@link panelKey}. */
+export type UndockedPanels = Record<string, UndockedPanel>;
+
+export function panelKey(trialId: string, sectionId: string): string {
+  return `${trialId}::${sectionId}`;
+}
+
+export function undockPanel(
+  panels: UndockedPanels,
+  trialId: string,
+  sectionId: string,
+  as: UndockedPanel['as'] = 'tile',
+): UndockedPanels {
+  return { ...panels, [panelKey(trialId, sectionId)]: { trialId, sectionId, as } };
+}
+
+/** Dock one section back, or — with no `sectionId` — every panel the trial
+ *  owns, which is what closing a trial wants. */
+export function dockPanel(
+  panels: UndockedPanels,
+  trialId: string,
+  sectionId?: string,
+): UndockedPanels {
+  const out: UndockedPanels = {};
+  for (const [key, panel] of Object.entries(panels)) {
+    if (panel.trialId === trialId && (sectionId === undefined || panel.sectionId === sectionId)) {
+      continue;
+    }
+    out[key] = panel;
+  }
+  return out;
+}

package/src/styles.less

@@ -17,6 +17,8 @@
 @import './chrome/regions/PaletteRegion.less';
 @import './controls/ControlPanel.less';
 @import './canvas/CanvasStack.less';
+@import './loupe/Loupe.less';
 @import './layers/LayerList.less';
+@import './annotations/Annotations.less';
 @import './dragdrop/Palette.less';
 @import './dragdrop/DragGhost.less';

package/src/surface/SurfaceContext.ts

@@ -3,3 +3,7 @@ import type { SurfaceHandle } from './useTiledSurface';
 
 /** Null when no surface owner is above — a lab with no shared surface at all. */
 export const SurfaceContext = createContext<SurfaceHandle | null>(null);
+
+/** The buffer the surface's tiles paint into. Null until the owner's canvas is
+ *  mounted, and for an owner that keeps its surface unpainted. */
+export const SurfaceCanvasContext = createContext<HTMLCanvasElement | null>(null);

package/src/surface/index.ts

@@ -1,7 +1,12 @@
 export { composeRects, rectsEqual } from './composeRects';
 export { toDeviceRect } from './deviceRect';
 export type { Box, Rect } from './rect';
-export { SurfaceContext } from './SurfaceContext';
-export { useSurface, useSurfaceOptional, useSurfaceTile } from './useSurfaceTile';
-export type { SurfaceFrame, SurfaceHandle, UseTiledSurfaceOptions } from './useTiledSurface';
+export { SurfaceCanvasContext, SurfaceContext } from './SurfaceContext';
+export { useSurface, useSurfaceCanvas, useSurfaceOptional, useSurfaceTile } from './useSurfaceTile';
+export type {
+  SurfaceFrame,
+  SurfaceHandle,
+  TilePainter,
+  UseTiledSurfaceOptions,
+} from './useTiledSurface';
 export { useTiledSurface } from './useTiledSurface';

package/src/surface/useSurfaceTile.test.tsx

@@ -10,7 +10,9 @@ function fakeHandle(): SurfaceHandle {
     invalidateAll: vi.fn(),
     invalidateRects: vi.fn(),
     registerTile: vi.fn(),
+    registerPainter: vi.fn(() => () => {}),
     containerRef: vi.fn(),
+    getContainer: vi.fn(() => null),
   };
 }
 

package/src/surface/useSurfaceTile.ts

@@ -1,7 +1,13 @@
 import { useCallback, useContext } from 'react';
-import { SurfaceContext } from './SurfaceContext';
+import { SurfaceCanvasContext, SurfaceContext } from './SurfaceContext';
 import type { SurfaceHandle } from './useTiledSurface';
 
+/** The surface's shared buffer, or null where nothing paints one. What a tile
+ *  hands to `paintInto`. */
+export function useSurfaceCanvas(): HTMLCanvasElement | null {
+  return useContext(SurfaceCanvasContext);
+}
+
 /** The surface above, or null. Use this where a surface is genuinely optional. */
 export function useSurfaceOptional(): SurfaceHandle | null {
   return useContext(SurfaceContext);

package/src/surface/useTiledSurface.test.tsx

@@ -228,4 +228,62 @@ describe('useTiledSurface', () => {
 
     expect(frames[0]?.rects.has('b')).toBe(false);
   });
+
+  it("calls a dirty tile's painter with that tile's rect", () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+
+    const paintA = vi.fn();
+    const paintB = vi.fn();
+    act(() => {
+      handle?.registerPainter('a', paintA);
+      handle?.registerPainter('b', paintB);
+      handle?.invalidate('a');
+    });
+    flushFrames();
+
+    // The rect, not just the call: a painter handed the wrong origin paints
+    // the right picture in the wrong place.
+    expect(paintA).toHaveBeenCalledWith({ x: 0, y: 0, w: 400, h: 600 }, expect.anything());
+    expect(paintB).not.toHaveBeenCalled();
+  });
+
+  it('stops calling a painter that unregisters', () => {
+    const frames: SurfaceFrame[] = [];
+    let handle: SurfaceHandle | null = null;
+    render(
+      <Harness
+        frames={frames}
+        onHandle={(h) => {
+          handle = h;
+        }}
+      />,
+    );
+    flushFrames();
+
+    const paint = vi.fn();
+    let off: (() => void) | undefined;
+    act(() => {
+      off = handle?.registerPainter('a', paint);
+      handle?.invalidate('a');
+    });
+    flushFrames();
+    expect(paint).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      off?.();
+      handle?.invalidate('a');
+    });
+    flushFrames();
+    expect(paint).toHaveBeenCalledTimes(1);
+  });
 });

package/src/surface/useTiledSurface.ts

@@ -23,9 +23,20 @@ export interface SurfaceHandle {
    *  moved something a ResizeObserver cannot see. */
   invalidateRects: () => void;
   registerTile: (id: string, el: HTMLElement | null) => void;
+  /** Subscribe a tile to the frames it is dirty on. A tile paints on its own
+   *  loop, so this is how the surface wakes one: a resize of the shared buffer
+   *  clears every tile, not only the one that moved. */
+  registerPainter: (id: string, paint: TilePainter) => () => void;
   containerRef: (el: HTMLElement | null) => void;
+  /** The element tile rects are measured against, and so the one a tile's own
+   *  chrome positions itself inside. Null before the owner attaches it. */
+  getContainer: () => HTMLElement | null;
 }
 
+/** What a tile's painter is handed: where it sits on the surface now, and the
+ *  frame that dirtied it. */
+export type TilePainter = (rect: Rect, frame: SurfaceFrame) => void;
+
 export interface UseTiledSurfaceOptions {
   onFrame: (frame: SurfaceFrame) => void;
 }
@@ -35,6 +46,7 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
   const tiles = useRef(new Map<string, HTMLElement>());
   const rects = useRef(new Map<string, Rect>());
   const dirty = useRef(new Set<string>());
+  const painters = useRef(new Map<string, TilePainter>());
   const needsMeasure = useRef(true);
   const observer = useRef<ResizeObserver | null>(null);
   const lastDpr = useRef(0);
@@ -76,12 +88,18 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
       }
       if (dirty.current.size === 0) return;
       const box = el.getBoundingClientRect();
-      onFrameRef.current({
+      const frame: SurfaceFrame = {
         dirty: new Set(dirty.current),
         rects: new Map(rects.current),
         dpr,
         size: { width: box.width, height: box.height },
-      });
+      };
+      onFrameRef.current(frame);
+      // After the owner, which is what resized the buffer this frame.
+      for (const id of frame.dirty) {
+        const rect = frame.rects.get(id);
+        if (rect) painters.current.get(id)?.(rect, frame);
+      }
       dirty.current.clear();
     },
     // The host attaches its container through `containerRef`, which may land
@@ -130,6 +148,15 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
     [schedule],
   );
 
+  const registerPainter = useCallback((id: string, paint: TilePainter) => {
+    painters.current.set(id, paint);
+    return () => {
+      if (painters.current.get(id) === paint) painters.current.delete(id);
+    };
+  }, []);
+
+  const getContainer = useCallback(() => container.current, []);
+
   const containerRef = useCallback(
     (el: HTMLElement | null) => {
       if (container.current === el) return;
@@ -157,5 +184,13 @@ export function useTiledSurface({ onFrame }: UseTiledSurfaceOptions): SurfaceHan
     };
   }, [schedule, frameLoop]);
 
-  return { invalidate, invalidateAll, invalidateRects, registerTile, containerRef };
+  return {
+    invalidate,
+    invalidateAll,
+    invalidateRects,
+    registerTile,
+    registerPainter,
+    containerRef,
+    getContainer,
+  };
 }