@weasel-js/labkit 0.1.0

package/src/canvas/useLayerScheduler.ts

@@ -0,0 +1,72 @@
+import { type RefObject, useEffect, useRef } from 'react';
+import type { ViewTransform } from '../instrument/types';
+
+export interface CanvasLayerDescriptor {
+  id: string;
+  visible: boolean;
+  render: (ctx: CanvasRenderingContext2D, view: ViewTransform) => void;
+}
+
+interface SchedulerOptions {
+  layers: CanvasLayerDescriptor[];
+  view: ViewTransform;
+  canvasRefs: RefObject<Map<string, HTMLCanvasElement>>;
+  size: { width: number; height: number; dpr: number };
+}
+
+export function useLayerScheduler({ layers, view, canvasRefs, size }: SchedulerOptions): void {
+  const dirty = useRef<Set<string>>(new Set());
+  const rafId = useRef<number | null>(null);
+  const lastRenderRef = useRef<Map<string, CanvasLayerDescriptor['render']>>(new Map());
+
+  useEffect(() => {
+    for (const layer of layers) {
+      const prev = lastRenderRef.current.get(layer.id);
+      if (prev !== layer.render) dirty.current.add(layer.id);
+      lastRenderRef.current.set(layer.id, layer.render);
+    }
+    for (const id of [...lastRenderRef.current.keys()]) {
+      if (!layers.find((l) => l.id === id)) lastRenderRef.current.delete(id);
+    }
+  }, [layers]);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: re-mark dirty when view or size changes
+  useEffect(() => {
+    for (const layer of layers) dirty.current.add(layer.id);
+  }, [view, size, layers]);
+
+  useEffect(() => {
+    const tick = () => {
+      rafId.current = null;
+      if (dirty.current.size === 0) return;
+      const map = canvasRefs.current;
+      if (!map) {
+        dirty.current.clear();
+        return;
+      }
+      for (const layer of layers) {
+        if (!dirty.current.has(layer.id)) continue;
+        if (!layer.visible) continue;
+        const canvas = map.get(layer.id);
+        if (!canvas) continue;
+        const ctx = canvas.getContext('2d');
+        if (!ctx) continue;
+        ctx.save();
+        ctx.setTransform(size.dpr, 0, 0, size.dpr, 0, 0);
+        ctx.clearRect(0, 0, size.width, size.height);
+        layer.render(ctx, view);
+        ctx.restore();
+      }
+      dirty.current.clear();
+    };
+    if (dirty.current.size > 0 && rafId.current === null) {
+      rafId.current = requestAnimationFrame(tick);
+    }
+    return () => {
+      if (rafId.current !== null) {
+        cancelAnimationFrame(rafId.current);
+        rafId.current = null;
+      }
+    };
+  });
+}

package/src/canvas/usePanZoom.ts

@@ -0,0 +1,98 @@
+import { type PointerEvent, useCallback, useRef, type WheelEvent } from 'react';
+import type { ViewTransform } from '../instrument/types';
+
+export interface UsePanZoomOptions {
+  view: ViewTransform;
+  onViewChange: (v: ViewTransform) => void;
+  minZoom?: number;
+  maxZoom?: number;
+}
+
+export interface PanZoomHandlers {
+  onWheel: (e: WheelEvent<HTMLElement>) => void;
+  onPointerDown: (e: PointerEvent<HTMLElement>) => void;
+  onPointerMove: (e: PointerEvent<HTMLElement>) => void;
+  onPointerUp: (e: PointerEvent<HTMLElement>) => void;
+  isDragging: () => boolean;
+}
+
+interface DragState {
+  pointerId: number;
+  startScreenX: number;
+  startScreenY: number;
+  startPan: { x: number; y: number };
+  moved: boolean;
+}
+
+const DRAG_THRESHOLD = 3;
+
+export function usePanZoom({
+  view,
+  onViewChange,
+  minZoom = 0.1,
+  maxZoom = 32,
+}: UsePanZoomOptions): PanZoomHandlers {
+  const dragRef = useRef<DragState | null>(null);
+  const viewRef = useRef(view);
+  viewRef.current = view;
+
+  const onWheel = useCallback(
+    (e: WheelEvent<HTMLElement>) => {
+      e.preventDefault();
+      const rect = e.currentTarget.getBoundingClientRect();
+      const cursorX = e.clientX - rect.left;
+      const cursorY = e.clientY - rect.top;
+      const v = viewRef.current;
+      const factor = Math.exp(-e.deltaY * 0.001);
+      const nextZoom = Math.min(maxZoom, Math.max(minZoom, v.zoom * factor));
+      const ratio = nextZoom / v.zoom;
+      const nextPan = {
+        x: cursorX - (cursorX - v.pan.x) * ratio,
+        y: cursorY - (cursorY - v.pan.y) * ratio,
+      };
+      onViewChange({ zoom: nextZoom, pan: nextPan });
+    },
+    [onViewChange, minZoom, maxZoom],
+  );
+
+  const onPointerDown = useCallback((e: PointerEvent<HTMLElement>) => {
+    if (e.button !== 0) return;
+    e.currentTarget.setPointerCapture(e.pointerId);
+    dragRef.current = {
+      pointerId: e.pointerId,
+      startScreenX: e.clientX,
+      startScreenY: e.clientY,
+      startPan: { ...viewRef.current.pan },
+      moved: false,
+    };
+  }, []);
+
+  const onPointerMove = useCallback(
+    (e: PointerEvent<HTMLElement>) => {
+      const drag = dragRef.current;
+      if (!drag || drag.pointerId !== e.pointerId) return;
+      const dx = e.clientX - drag.startScreenX;
+      const dy = e.clientY - drag.startScreenY;
+      if (!drag.moved && Math.hypot(dx, dy) < DRAG_THRESHOLD) return;
+      drag.moved = true;
+      onViewChange({
+        zoom: viewRef.current.zoom,
+        pan: { x: drag.startPan.x + dx, y: drag.startPan.y + dy },
+      });
+    },
+    [onViewChange],
+  );
+
+  const onPointerUp = useCallback((e: PointerEvent<HTMLElement>) => {
+    const drag = dragRef.current;
+    if (!drag || drag.pointerId !== e.pointerId) return;
+    if (e.currentTarget.hasPointerCapture(e.pointerId)) {
+      e.currentTarget.releasePointerCapture(e.pointerId);
+    }
+    dragRef.current = null;
+  }, []);
+
+  const isDragging = useCallback(() => dragRef.current?.moved === true, []);
+
+  return { onWheel, onPointerDown, onPointerMove, onPointerUp, isDragging };
+}

package/src/controls/ControlPanel.less

@@ -0,0 +1,61 @@
+.lk-control-panel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--lk-spacing-sm, 8px);
+  padding: var(--lk-spacing-sm, 8px);
+}
+
+.lk-control-row {
+  display: flex;
+  flex-direction: column;
+  gap: var(--lk-spacing-xs, 4px);
+}
+
+.lk-control-row--inline {
+  flex-direction: row;
+  align-items: center;
+  gap: var(--lk-spacing-sm, 8px);
+}
+
+.lk-control-label {
+  font-size: var(--lk-font-size-sm, 12px);
+  color: var(--lk-color-text, #222);
+}
+
+.lk-control-input {
+  width: 100%;
+  background: var(--lk-color-surface, #fff);
+  color: var(--lk-color-text, #222);
+  border: 1px solid var(--lk-color-border, #ccc);
+  border-radius: 4px;
+  padding: 2px 6px;
+}
+
+.lk-control-input--range {
+  padding: 0;
+  border: none;
+}
+
+.lk-control-input--checkbox {
+  width: auto;
+}
+
+.lk-control-input--color {
+  width: 40px;
+  height: 24px;
+  padding: 0;
+}
+
+.lk-control-slider-value {
+  font-size: var(--lk-font-size-sm, 12px);
+  font-variant-numeric: tabular-nums;
+  color: var(--lk-color-text-muted, #666);
+  min-width: 3ch;
+  text-align: right;
+}
+
+.lk-control-slider-row {
+  display: flex;
+  align-items: center;
+  gap: var(--lk-spacing-sm, 8px);
+}

package/src/controls/ControlPanel.stories.tsx

@@ -0,0 +1,77 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { ControlPanel } from './ControlPanel';
+import type { ConfigField } from './types';
+
+const meta: Meta<typeof ControlPanel> = {
+  title: 'labkit/Controls/ControlPanel',
+  component: ControlPanel,
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof ControlPanel>;
+
+const allFields: ConfigField[] = [
+  {
+    key: 'frequency',
+    label: 'Frequency',
+    type: 'slider',
+    min: 0.1,
+    max: 10,
+    step: 0.1,
+    default: 2,
+  },
+  {
+    key: 'amplitude',
+    label: 'Amplitude',
+    type: 'slider',
+    min: 0,
+    max: 1,
+    step: 0.05,
+    default: 0.5,
+  },
+  { key: 'showGrid', label: 'Show grid', type: 'checkbox', default: true },
+  {
+    key: 'wave',
+    label: 'Wave',
+    type: 'select',
+    default: 'sine',
+    options: [
+      { value: 'sine', label: 'Sine' },
+      { value: 'square', label: 'Square' },
+      { value: 'triangle', label: 'Triangle' },
+    ],
+  },
+  { key: 'samples', label: 'Samples', type: 'number', default: 256, min: 16, max: 4096, step: 16 },
+  { key: 'title', label: 'Title', type: 'text', default: 'My experiment', placeholder: 'Title…' },
+  { key: 'tint', label: 'Tint', type: 'color', default: '#3a86ff' },
+];
+
+function Harness({ fields }: { fields: ConfigField[] }) {
+  const initial: Record<string, unknown> = {};
+  for (const f of fields) initial[f.key] = f.default;
+  const [config, setConfig] = useState<Record<string, unknown>>(initial);
+  return (
+    <ControlPanel
+      fields={fields}
+      config={config}
+      setConfig={(key, value) => setConfig((prev) => ({ ...prev, [key as string]: value }))}
+    />
+  );
+}
+
+export const Default: Story = {
+  render: () => <Harness fields={allFields} />,
+};
+
+export const Minimal: Story = {
+  render: () => (
+    <Harness
+      fields={[
+        { key: 'speed', label: 'Speed', type: 'slider', min: 0, max: 10, default: 5 },
+        { key: 'enabled', label: 'Enabled', type: 'checkbox', default: true },
+      ]}
+    />
+  ),
+};

package/src/controls/ControlPanel.test.tsx

@@ -0,0 +1,149 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { ControlPanel } from './ControlPanel';
+import type { ConfigField } from './types';
+
+describe('<ControlPanel> slider', () => {
+  it('renders a range input with min/max/step and label', () => {
+    const fields: ConfigField[] = [
+      { key: 'freq', label: 'Frequency', type: 'slider', min: 0, max: 10, step: 0.5, default: 2 },
+    ];
+    render(<ControlPanel fields={fields} config={{ freq: 2 }} setConfig={vi.fn()} />);
+    const input = screen.getByLabelText('Frequency') as HTMLInputElement;
+    expect(input.type).toBe('range');
+    expect(input.min).toBe('0');
+    expect(input.max).toBe('10');
+    expect(input.step).toBe('0.5');
+    expect(screen.getByText('2')).toBeInTheDocument();
+  });
+
+  it('calls setConfig with numeric value on change', () => {
+    const setConfig = vi.fn();
+    const fields: ConfigField[] = [
+      { key: 'freq', label: 'Frequency', type: 'slider', min: 0, max: 10, default: 2 },
+    ];
+    render(<ControlPanel fields={fields} config={{ freq: 2 }} setConfig={setConfig} />);
+    fireEvent.change(screen.getByLabelText('Frequency'), { target: { value: '5' } });
+    expect(setConfig).toHaveBeenCalledWith('freq', 5);
+  });
+});
+
+describe('<ControlPanel> checkbox', () => {
+  it('renders checkbox with label and reflects config', () => {
+    const fields: ConfigField[] = [{ key: 'on', label: 'On', type: 'checkbox', default: false }];
+    render(<ControlPanel fields={fields} config={{ on: true }} setConfig={vi.fn()} />);
+    const cb = screen.getByLabelText('On') as HTMLInputElement;
+    expect(cb.type).toBe('checkbox');
+    expect(cb.checked).toBe(true);
+  });
+
+  it('calls setConfig with boolean on change', () => {
+    const setConfig = vi.fn();
+    const fields: ConfigField[] = [{ key: 'on', label: 'On', type: 'checkbox', default: false }];
+    render(<ControlPanel fields={fields} config={{ on: false }} setConfig={setConfig} />);
+    fireEvent.click(screen.getByLabelText('On'));
+    expect(setConfig).toHaveBeenCalledWith('on', true);
+  });
+});
+
+describe('<ControlPanel> select', () => {
+  it('renders options and dispatches selected value', () => {
+    const setConfig = vi.fn();
+    const fields: ConfigField[] = [
+      {
+        key: 'wave',
+        label: 'Wave',
+        type: 'select',
+        default: 'sine',
+        options: [
+          { value: 'sine', label: 'Sine' },
+          { value: 'square', label: 'Square' },
+        ],
+      },
+    ];
+    render(<ControlPanel fields={fields} config={{ wave: 'sine' }} setConfig={setConfig} />);
+    const sel = screen.getByLabelText('Wave') as HTMLSelectElement;
+    expect(sel.tagName).toBe('SELECT');
+    fireEvent.change(sel, { target: { value: 'square' } });
+    expect(setConfig).toHaveBeenCalledWith('wave', 'square');
+  });
+});
+
+describe('<ControlPanel> number', () => {
+  it('renders number input with initial value', () => {
+    const fields: ConfigField[] = [
+      { key: 'n', label: 'N', type: 'number', default: 0, min: 0, max: 100 },
+    ];
+    render(<ControlPanel fields={fields} config={{ n: 42 }} setConfig={vi.fn()} />);
+    const input = screen.getByLabelText('N') as HTMLInputElement;
+    expect(input.type).toBe('number');
+    expect(input.value).toBe('42');
+  });
+
+  it('clamps to [min, max] on blur', () => {
+    const setConfig = vi.fn();
+    const fields: ConfigField[] = [
+      { key: 'n', label: 'N', type: 'number', default: 0, min: 0, max: 100 },
+    ];
+    render(<ControlPanel fields={fields} config={{ n: 50 }} setConfig={setConfig} />);
+    const input = screen.getByLabelText('N');
+    fireEvent.blur(input, { target: { value: '999' } });
+    expect(setConfig).toHaveBeenCalledWith('n', 100);
+  });
+});
+
+describe('<ControlPanel> text', () => {
+  it('renders text input with placeholder and maxLength', () => {
+    const fields: ConfigField[] = [
+      {
+        key: 't',
+        label: 'T',
+        type: 'text',
+        default: '',
+        placeholder: 'type here',
+        maxLength: 10,
+      },
+    ];
+    render(<ControlPanel fields={fields} config={{ t: 'hi' }} setConfig={vi.fn()} />);
+    const input = screen.getByLabelText('T') as HTMLInputElement;
+    expect(input.type).toBe('text');
+    expect(input.placeholder).toBe('type here');
+    expect(input.maxLength).toBe(10);
+  });
+
+  it('calls setConfig live when debounceMs is 0', () => {
+    const setConfig = vi.fn();
+    const fields: ConfigField[] = [
+      { key: 't', label: 'T', type: 'text', default: '', debounceMs: 0 },
+    ];
+    render(<ControlPanel fields={fields} config={{ t: '' }} setConfig={setConfig} />);
+    fireEvent.change(screen.getByLabelText('T'), { target: { value: 'a' } });
+    expect(setConfig).toHaveBeenCalledWith('t', 'a');
+  });
+});
+
+describe('<ControlPanel> color', () => {
+  it('renders a color input reflecting config and dispatches value', () => {
+    const setConfig = vi.fn();
+    const fields: ConfigField[] = [{ key: 'c', label: 'Color', type: 'color', default: '#000000' }];
+    render(<ControlPanel fields={fields} config={{ c: '#ff0000' }} setConfig={setConfig} />);
+    const input = screen.getByLabelText('Color') as HTMLInputElement;
+    expect(input.type).toBe('color');
+    expect(input.value).toBe('#ff0000');
+    fireEvent.change(input, { target: { value: '#00ff00' } });
+    expect(setConfig).toHaveBeenCalledWith('c', '#00ff00');
+  });
+});
+
+describe('<ControlPanel> defensive', () => {
+  it('renders nothing for an unknown field type without crashing', () => {
+    const fields = [
+      { key: 'mystery', label: 'Mystery', type: 'mystery', default: 1 },
+    ] as unknown as ConfigField[];
+    const { container } = render(
+      <ControlPanel fields={fields} config={{ mystery: 1 }} setConfig={vi.fn()} />,
+    );
+    expect(container.querySelector('.lk-control-panel')).not.toBeNull();
+    expect(container.querySelector('.lk-control-row')).toBeNull();
+  });
+});