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

package/src/controls/ControlPanel.tsx

@@ -1,251 +1,250 @@
-import { useEffect, useRef, useState } from 'react';
-import type {
-  CheckboxField,
-  ColorField,
-  ConfigField,
-  NumberField,
-  SelectField,
-  SliderField,
-  TextField,
-} from './types';
+import { isBuiltinToolPref } from '@weasel-js/core';
+import type { PrefLeaf } from '@weasel-js/ui';
+import { useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { fromConfigFields } from '../config/fromConfigField';
+import type { ControlRenderer, ResolvedConfig } from '../config/types';
+import { isLeafVisible } from '../config/visible';
+import { PropertyGroup } from '../ui/properties/PropertyGroup';
+import {
+  CheckboxRow,
+  ColorRow,
+  NumberRow,
+  PropertyList,
+  PropertyRow,
+  SelectRow,
+  TextRow,
+  ToggleRow,
+  SliderRow,
+} from '../ui/properties/PropertyPanel';
+import type { ConfigField } from './types';
 
 export interface ControlPanelProps<TC extends Record<string, unknown>> {
-  fields: ConfigField[];
+  /** The instrument's resolved config schema. */
+  schema?: ResolvedConfig;
+  /** @deprecated Pass `schema`. A field list is adapted into one internally. */
+  fields?: ConfigField[];
   config: TC;
   setConfig: (key: keyof TC, value: unknown) => void;
+  /**
+   * Control overrides and app-defined kinds, PrefsForm-style. Keys are config
+   * paths (checked first) or leaf kinds. A renderer returning `null` collapses
+   * the row; entries override the built-in rows on collision.
+   */
+  renderers?: Record<string, ControlRenderer>;
+  /** Draw leaves marked `hidden`. */
+  showHidden?: boolean;
   className?: string;
 }
 
 /** Render an instrument's config schema as a stack of controls, each writing
- *  back through `setConfig`. */
+ *  back through `setConfig`. Built on the property rows, so a lab's controls
+ *  are the same aligned, themed rows the rest of the kit uses. */
 export function ControlPanel<TC extends Record<string, unknown>>({
+  schema,
   fields,
   config,
   setConfig,
+  renderers,
+  showHidden = false,
   className,
 }: ControlPanelProps<TC>) {
+  const resolved = useMemo(
+    () => schema ?? fromConfigFields(fields ?? []),
+    [schema, fields],
+  );
+
+  const paths = Object.keys(resolved.group.children);
+  const sectioned = new Set(resolved.sections.flatMap((s) => s.paths));
+  const loose = paths.filter((p) => !sectioned.has(p));
+
+  const row = (path: string): ReactNode => (
+    <ControlRow
+      key={path}
+      path={path}
+      resolved={resolved}
+      config={config}
+      setConfig={setConfig}
+      renderers={renderers}
+      showHidden={showHidden}
+    />
+  );
+
   return (
-    <div className={className ? `lk-control-panel ${className}` : 'lk-control-panel'}>
-      {fields.map((field) => (
-        <ControlRow key={field.key} field={field} config={config} setConfig={setConfig} />
+    <PropertyList className={className ? `lk-control-panel ${className}` : 'lk-control-panel'}>
+      {loose.map(row)}
+      {resolved.sections.map((section) => (
+        <PropertyGroup key={section.label} title={section.label}>
+          {section.paths.map(row)}
+        </PropertyGroup>
       ))}
-    </div>
+    </PropertyList>
   );
 }
 
 interface ControlRowProps<TC extends Record<string, unknown>> {
-  field: ConfigField;
+  path: string;
+  resolved: ResolvedConfig;
   config: TC;
   setConfig: (key: keyof TC, value: unknown) => void;
+  renderers?: Record<string, ControlRenderer>;
+  showHidden: boolean;
+}
+
+/** Reads a labkit-only extra off a leaf. `PrefLeaf` has no field for these,
+ *  and extra keys survive the resolve pass at runtime. */
+function extra<T>(leaf: PrefLeaf, key: string): T | undefined {
+  return (leaf as unknown as Record<string, T | undefined>)[key];
 }
 
 function ControlRow<TC extends Record<string, unknown>>({
-  field,
+  path,
+  resolved,
   config,
   setConfig,
+  renderers,
+  showHidden,
 }: ControlRowProps<TC>) {
-  switch (field.type) {
-    case 'slider':
-      return <SliderRow field={field} config={config} setConfig={setConfig} />;
-    case 'checkbox':
-      return <CheckboxRow field={field} config={config} setConfig={setConfig} />;
-    case 'select':
-      return <SelectRow field={field} config={config} setConfig={setConfig} />;
-    case 'number':
-      return <NumberRow field={field} config={config} setConfig={setConfig} />;
-    case 'text':
-      return <TextRow field={field} config={config} setConfig={setConfig} />;
-    case 'color':
-      return <ColorRow field={field} config={config} setConfig={setConfig} />;
-    default:
-      return null;
-  }
-}
+  const leaf = resolved.group.children[path] as PrefLeaf | undefined;
+  if (!leaf || !('kind' in leaf)) return null;
+  if (!isLeafVisible(resolved, path, config as Record<string, unknown>, showHidden)) return null;
 
-type RowProps<F extends ConfigField, TC extends Record<string, unknown>> = {
-  field: F;
-  config: TC;
-  setConfig: (key: keyof TC, value: unknown) => void;
-};
+  const write = (value: unknown): void => setConfig(path as keyof TC, value);
+  const fallback = extra<unknown>(leaf, 'default');
+  const value = config[path] ?? fallback;
 
-function SliderRow<TC extends Record<string, unknown>>({
-  field,
-  config,
-  setConfig,
-}: RowProps<SliderField, TC>) {
-  const value = (config[field.key] as number | undefined) ?? field.default;
-  return (
-    <div className="lk-control-row">
-      <label className="lk-control-label" htmlFor={`lk-ctrl-${field.key}`}>
-        {field.label}
-      </label>
-      <div className="lk-control-slider-row">
-        <input
-          id={`lk-ctrl-${field.key}`}
-          className="lk-control-input lk-control-input--range"
-          type="range"
-          min={field.min}
-          max={field.max}
-          step={field.step ?? 1}
-          value={value}
-          onChange={(e) => setConfig(field.key as keyof TC, Number(e.target.value))}
-        />
-        <span className="lk-control-slider-value">{value}</span>
-      </div>
-    </div>
-  );
-}
+  // 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];
+  if (custom) return custom({ path, pref: leaf, value, setValue: write });
 
-function CheckboxRow<TC extends Record<string, unknown>>({
-  field,
-  config,
-  setConfig,
-}: RowProps<CheckboxField, TC>) {
-  const value = (config[field.key] as boolean | undefined) ?? field.default;
-  return (
-    <div className="lk-control-row lk-control-row--inline">
-      <input
-        id={`lk-ctrl-${field.key}`}
-        className="lk-control-input lk-control-input--checkbox"
-        type="checkbox"
-        checked={value}
-        onChange={(e) => setConfig(field.key as keyof TC, e.target.checked)}
-      />
-      <label className="lk-control-label" htmlFor={`lk-ctrl-${field.key}`}>
-        {field.label}
-      </label>
-    </div>
-  );
-}
+  const label = leaf.name;
+  const read = <T,>(): T => value as T;
 
-function SelectRow<TC extends Record<string, unknown>>({
-  field,
-  config,
-  setConfig,
-}: RowProps<SelectField, TC>) {
-  const value = (config[field.key] as string | undefined) ?? field.default;
-  return (
-    <div className="lk-control-row">
-      <label className="lk-control-label" htmlFor={`lk-ctrl-${field.key}`}>
-        {field.label}
-      </label>
-      <select
-        id={`lk-ctrl-${field.key}`}
-        className="lk-control-input"
-        value={value}
-        onChange={(e) => setConfig(field.key as keyof TC, e.target.value)}
-      >
-        {field.options.map((opt) => (
-          <option key={opt.value} value={opt.value}>
-            {opt.label}
-          </option>
-        ))}
-      </select>
-    </div>
-  );
+  if (!isBuiltinToolPref(leaf)) return <UnwiredRow label={label} kind={leaf.kind} />;
+
+  switch (leaf.kind) {
+    case 'number': {
+      const min = extra<number>(leaf, 'min');
+      const max = extra<number>(leaf, 'max');
+      const step = extra<number>(leaf, 'step');
+      if (extra<string>(leaf, 'control') === 'slider' && min !== undefined && max !== undefined) {
+        return (
+          <SliderRow
+            label={label}
+            value={read<number>()}
+            min={min}
+            max={max}
+            step={step}
+            onChange={write}
+          />
+        );
+      }
+      // NumberRow commits every keystroke and does not clamp, so the bounds a
+      // schema declares are enforced here — an instrument should never be
+      // handed a config value outside the range it asked for.
+      const lo = min ?? Number.NEGATIVE_INFINITY;
+      const hi = max ?? Number.POSITIVE_INFINITY;
+      return (
+        <NumberRow
+          label={label}
+          value={read<number>()}
+          min={min}
+          max={max}
+          step={step}
+          onChange={(n) => write(Math.min(hi, Math.max(lo, n)))}
+        />
+      );
+    }
+    case 'boolean':
+      return <CheckboxRow label={label} value={read<boolean>()} onChange={write} />;
+    case 'enum': {
+      const options = extra<readonly { value: string; label: string }[]>(leaf, 'options') ?? [];
+      const Row = extra<string>(leaf, 'control') === 'radio' ? ToggleRow : SelectRow;
+      return (
+        <Row label={label} value={read<string>()} options={options} onChange={write} />
+      );
+    }
+    case 'string':
+      return <DebouncedTextRow leaf={leaf} label={label} value={read<string>()} write={write} />;
+    case 'color':
+      return <ColorRow label={label} value={read<string>()} onChange={write} />;
+    case 'paint':
+    case 'object':
+      // Declined: a hex swatch would write a solid over a gradient, and a flat
+      // row would write one field into a half-built object. Override with
+      // `render` to edit either.
+      return <UnwiredRow label={label} kind={leaf.kind} />;
+    default: {
+      // Not reachable while every built-in kind has an arm — and a new kind
+      // that lacks one is a compile error here, never a blank row.
+      const _exhaustive: never = leaf;
+      throw new Error(
+        `ControlPanel: no control for built-in pref kind "${(_exhaustive as { kind: string }).kind}"`,
+      );
+    }
+  }
 }
 
-function NumberRow<TC extends Record<string, unknown>>({
-  field,
-  config,
-  setConfig,
-}: RowProps<NumberField, TC>) {
-  const value = (config[field.key] as number | undefined) ?? field.default;
+/** A leaf this panel has no control for is named rather than dropped: a silent
+ *  gap reads as "this control does not exist". */
+function UnwiredRow({ label, kind }: { label: string; kind: string }) {
   return (
-    <div className="lk-control-row">
-      <label className="lk-control-label" htmlFor={`lk-ctrl-${field.key}`}>
-        {field.label}
-      </label>
-      <input
-        id={`lk-ctrl-${field.key}`}
-        className="lk-control-input"
-        type="number"
-        value={value}
-        min={field.min}
-        max={field.max}
-        step={field.step}
-        onChange={(e) => setConfig(field.key as keyof TC, Number(e.target.value))}
-        onBlur={(e) => {
-          const n = Number(e.target.value);
-          if (!Number.isFinite(n)) return;
-          let clamped = n;
-          if (field.min !== undefined && clamped < field.min) clamped = field.min;
-          if (field.max !== undefined && clamped > field.max) clamped = field.max;
-          if (clamped !== n) setConfig(field.key as keyof TC, clamped);
-        }}
-      />
-    </div>
+    <PropertyRow label={label}>
+      <span className="lk-control-panel__unknown">no control for “{kind}”</span>
+    </PropertyRow>
   );
 }
 
-function TextRow<TC extends Record<string, unknown>>({
-  field,
-  config,
-  setConfig,
-}: RowProps<TextField, TC>) {
-  const debounceMs = field.debounceMs ?? 150;
-  const initial = (config[field.key] as string | undefined) ?? field.default;
-  const [local, setLocal] = useState(initial);
+/** Text writes are debounced so typing does not re-run the instrument on every
+ *  keystroke, which means the row is locally controlled between commits and has
+ *  to notice when the config changes underneath it. */
+function DebouncedTextRow({
+  leaf,
+  label,
+  value,
+  write,
+}: {
+  leaf: PrefLeaf;
+  label: string;
+  value: string;
+  write: (value: unknown) => void;
+}) {
+  const debounceMs = extra<number>(leaf, 'debounceMs') ?? 150;
+  const [local, setLocal] = useState(value);
   const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const lastExternal = useRef(initial);
+  const lastExternal = useRef(value);
 
   useEffect(() => {
-    const ext = (config[field.key] as string | undefined) ?? field.default;
-    if (ext !== lastExternal.current) {
-      lastExternal.current = ext;
-      setLocal(ext);
+    if (value !== lastExternal.current) {
+      lastExternal.current = value;
+      setLocal(value);
     }
-  }, [config, field.key, field.default]);
+  }, [value]);
 
-  return (
-    <div className="lk-control-row">
-      <label className="lk-control-label" htmlFor={`lk-ctrl-${field.key}`}>
-        {field.label}
-      </label>
-      <input
-        id={`lk-ctrl-${field.key}`}
-        className="lk-control-input"
-        type="text"
-        value={local}
-        placeholder={field.placeholder}
-        maxLength={field.maxLength}
-        onChange={(e) => {
-          const next = e.target.value;
-          setLocal(next);
-          if (timer.current) clearTimeout(timer.current);
-          if (debounceMs === 0) {
-            lastExternal.current = next;
-            setConfig(field.key as keyof TC, next);
-          } else {
-            timer.current = setTimeout(() => {
-              lastExternal.current = next;
-              setConfig(field.key as keyof TC, next);
-            }, debounceMs);
-          }
-        }}
-      />
-    </div>
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
   );
-}
 
-function ColorRow<TC extends Record<string, unknown>>({
-  field,
-  config,
-  setConfig,
-}: RowProps<ColorField, TC>) {
-  const value = (config[field.key] as string | undefined) ?? field.default;
   return (
-    <div className="lk-control-row lk-control-row--inline">
-      <label className="lk-control-label" htmlFor={`lk-ctrl-${field.key}`}>
-        {field.label}
-      </label>
-      <input
-        id={`lk-ctrl-${field.key}`}
-        className="lk-control-input lk-control-input--color"
-        type="color"
-        value={value}
-        onChange={(e) => setConfig(field.key as keyof TC, e.target.value)}
-      />
-    </div>
+    <TextRow
+      label={label}
+      value={local}
+      placeholder={extra<string>(leaf, 'placeholder')}
+      maxLength={extra<number>(leaf, 'maxLength')}
+      onChange={(next) => {
+        setLocal(next);
+        if (timer.current) clearTimeout(timer.current);
+        const commit = () => {
+          lastExternal.current = next;
+          write(next);
+        };
+        if (debounceMs === 0) commit();
+        else timer.current = setTimeout(commit, debounceMs);
+      }}
+    />
   );
 }

package/src/dragdrop/DragDropRuntime.tsx

@@ -1,3 +1,4 @@
+import { useVisibleRaf } from '@weasel-js/core';
 import { type RefObject, useCallback, useEffect, useRef, useState } from 'react';
 import { screenToWorld } from '../canvas/canvasCoords';
 import type {
@@ -42,7 +43,9 @@ export function useDragDrop<TS, TC>({
   const [drag, setDrag] = useState<DragState | null>(null);
   const dragRef = useRef<DragState | null>(null);
   dragRef.current = drag;
-  const rafThrottle = useRef<number | null>(null);
+  /** The move the next frame will resolve. Doubles as the throttle's flag:
+   *  non-null means a frame is already queued. */
+  const pendingPos = useRef<Point | null>(null);
 
   const isOverCanvas = useCallback(
     (screenPos: Point): boolean => {
@@ -69,37 +72,42 @@ export function useDragDrop<TS, TC>({
     [canvasContainerRef, view],
   );
 
+  const frameLoop = useVisibleRaf(() => {
+    const screenPos = pendingPos.current;
+    pendingPos.current = null;
+    const active = dragRef.current;
+    if (!active || !screenPos) return;
+    let feedback: DragFeedback | null = null;
+    if (capability.onDragOver && isOverCanvas(screenPos)) {
+      const world = screenToWorldFromContainer(screenPos);
+      if (world) feedback = capability.onDragOver(world, active.item, state, config);
+    }
+    setDrag({ ...active, screenPos, feedback });
+  });
+
   useEffect(() => {
     if (!drag) return;
     const handleMove = (e: PointerEvent) => {
       const screenPos = { x: e.clientX, y: e.clientY };
       const current = dragRef.current;
       if (!current) return;
-      if (rafThrottle.current !== null) {
+      if (pendingPos.current !== null) {
+        // A frame is already queued: keep the ghost under the cursor and let
+        // that frame probe the drop target from the newest position.
+        pendingPos.current = screenPos;
         dragRef.current = { ...current, screenPos };
         setDrag(dragRef.current);
         return;
       }
-      rafThrottle.current = requestAnimationFrame(() => {
-        rafThrottle.current = null;
-        const active = dragRef.current;
-        if (!active) return;
-        let feedback: DragFeedback | null = null;
-        if (capability.onDragOver && isOverCanvas(screenPos)) {
-          const world = screenToWorldFromContainer(screenPos);
-          if (world) feedback = capability.onDragOver(world, active.item, state, config);
-        }
-        setDrag({ ...active, screenPos, feedback });
-      });
+      pendingPos.current = screenPos;
+      frameLoop.request();
     };
     const handleUp = (e: PointerEvent) => {
       const screenPos = { x: e.clientX, y: e.clientY };
       const active = dragRef.current;
       if (!active) return;
-      if (rafThrottle.current !== null) {
-        cancelAnimationFrame(rafThrottle.current);
-        rafThrottle.current = null;
-      }
+      pendingPos.current = null;
+      frameLoop.cancel();
       if (isOverCanvas(screenPos)) {
         const world = screenToWorldFromContainer(screenPos);
         if (world) {
@@ -116,7 +124,17 @@ export function useDragDrop<TS, TC>({
       window.removeEventListener('pointermove', handleMove);
       window.removeEventListener('pointerup', handleUp);
     };
-  }, [drag, capability, state, config, setState, emit, isOverCanvas, screenToWorldFromContainer]);
+  }, [
+    drag,
+    capability,
+    state,
+    config,
+    setState,
+    emit,
+    frameLoop,
+    isOverCanvas,
+    screenToWorldFromContainer,
+  ]);
 
   const startDrag = useCallback((item: PaletteItem, originScreenPos: Point) => {
     setDrag({ item, screenPos: originScreenPos, feedback: null });

package/src/dragdrop/DragGhost.less

@@ -5,7 +5,7 @@
   padding: 4px 8px;
   background: var(--wzl-surface-raised);
   border: 1px solid var(--wzl-border);
-  border-radius: 4px;
+  border-radius: var(--wzl-radius-sm);
   box-shadow: 0 4px 12px rgba(0, 0, 0, 0.18);
   font: inherit;
   color: inherit;

package/src/dragdrop/Palette.less

@@ -13,7 +13,7 @@
   padding: var(--wzl-space-sm);
   background: var(--wzl-surface-raised);
   border: 1px solid var(--wzl-border);
-  border-radius: 4px;
+  border-radius: var(--wzl-radius-sm);
   cursor: grab;
   font: inherit;
   color: inherit;

package/src/index.ts

@@ -9,6 +9,29 @@ export {
   useOrbit,
   wrapYaw,
 } from './canvas/useOrbit';
+export * from './chrome';
+export { f } from './config/builder';
+export { fromConfigFields } from './config/fromConfigField';
+export { resolveConfigSchema } from './config/resolve';
+export { applyRules, builtinRules, titleCase } from './config/rules';
+export type {
+  Annotations,
+  ConfigNode,
+  ConfigOf,
+  ConfigOption,
+  ConfigRule,
+  ConfigRuleContext,
+  ConfigSchema,
+  ControlRenderer,
+  InferConfig,
+  LeafPatch,
+  NodeOptions,
+  NodeValue,
+  ResolvedConfig,
+  SectionSpec,
+} from './config/types';
+export { useConfigSchema } from './config/useConfigSchema';
+export { isLeafVisible } from './config/visible';
 export { ControlPanel } from './controls/ControlPanel';
 export type {
   CheckboxField,
@@ -22,9 +45,7 @@ export type {
   SliderField,
   TextField,
 } from './controls/types';
-export type { CapabilityFlags } from './instrument/capabilityDetector';
-export { detectCapabilities } from './instrument/capabilityDetector';
-export { defineInstrument } from './instrument/defineInstrument';
+export { defineInstrument, type InstrumentSpec } from './instrument/defineInstrument';
 export type {
   CanvasCapability,
   CanvasLayer,
@@ -82,6 +103,7 @@ export type { ViewTransform2D } from './state/view';
 export { as2DView, DEFAULT_VIEW } from './state/view';
 export * from './surface';
 export { interstellarTheme } from './theme/interstellar';
+export type { ToolCapability, TrialTool } from './tools/types';
 export * from './trial';
 export * from './ui/layers';
 export * from './ui/properties';

package/src/instrument/SineWave.smoke.test.tsx

@@ -86,7 +86,14 @@ describe('SineWave instrument smoke test', () => {
       config: SineWaveInstrument.defaultConfig(),
       setState: vi.fn(),
       setConfig: vi.fn(),
-      trial: { id: 'w', view: DEFAULT_VIEW, setView: vi.fn(), zoom: 1, setZoom: vi.fn() },
+      trial: {
+        id: 'w',
+        view: DEFAULT_VIEW,
+        setView: vi.fn(),
+        zoom: 1,
+        setZoom: vi.fn(),
+        activeToolId: null,
+      },
       emit: vi.fn(),
     };
     const { container } = render(SineWaveInstrument.render(ctx) as ReactElement);