@weasel-js/labkit 1.2.0 → 1.3.0

package/src/controls/ControlPanel.tsx

@@ -1,251 +1,284 @@
-import { useEffect, useRef, useState } from 'react';
-import type {
-  CheckboxField,
-  ColorField,
-  ConfigField,
-  NumberField,
-  SelectField,
-  SliderField,
-  TextField,
-} from './types';
+import { isBuiltinToolPref } from '@weasel-js/core';
+import {
+  CheckboxRow,
+  ColorRow,
+  NumberRow,
+  type PrefLeaf,
+  PropertyGroup,
+  PropertyList,
+  PropertyRow,
+  SelectRow,
+  SliderRow,
+  TextRow,
+  ToggleRow,
+} from '@weasel-js/ui';
+import { type ReactNode, useEffect, useMemo, useRef, useState } from 'react';
+import { fromConfigFields } from '../config/fromConfigField';
+import type { ControlRenderer, ResolvedConfig } from '../config/types';
+import { isLeafVisible } from '../config/visible';
+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 description = leaf.description;
+  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} description={description} />;
+
+  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}
+            description={description}
+          />
+        );
+      }
+      // 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)))}
+          description={description}
+        />
+      );
+    }
+    case 'boolean':
+      return (
+        <CheckboxRow
+          label={label}
+          value={read<boolean>()}
+          onChange={write}
+          description={description}
+        />
+      );
+    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}
+          description={description}
+        />
+      );
+    }
+    case 'string':
+      return (
+        <DebouncedTextRow
+          leaf={leaf}
+          label={label}
+          value={read<string>()}
+          write={write}
+          description={description}
+        />
+      );
+    case 'color':
+      return (
+        <ColorRow label={label} value={read<string>()} onChange={write} description={description} />
+      );
+    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} description={description} />;
+    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,
+  description,
+}: {
+  label: string;
+  kind: string;
+  description?: 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} description={description}>
+      <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,
+  description,
+}: {
+  leaf: PrefLeaf;
+  label: string;
+  value: string;
+  write: (value: unknown) => void;
+  description?: string;
+}) {
+  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}
+      description={description}
+      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/dragdrop/index.ts

@@ -1 +1,12 @@
 export type { DragDropCapability, DragFeedback, PaletteItem } from '../instrument/types';
+export type {
+  DragOverlayProps,
+  DragState,
+  UseDragDropArgs,
+  UseDragDropResult,
+} from './DragDropRuntime';
+export { DragOverlay, useDragDrop } from './DragDropRuntime';
+export type { DragGhostProps } from './DragGhost';
+export { DragGhost } from './DragGhost';
+export type { PaletteProps } from './Palette';
+export { Palette } from './Palette';