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

package/src/config/types.ts

@@ -0,0 +1,108 @@
+import type { PrefGroup, PrefLeaf, PrefRenderer } from '@weasel-js/ui';
+
+/**
+ * Renders the control cell for one config leaf. Identical to weasel-ui's
+ * `PrefRenderer` on purpose — aliased rather than redeclared so the two
+ * cannot drift.
+ */
+export type ControlRenderer = PrefRenderer;
+
+/** One labeled choice in an `enum` leaf. */
+export interface ConfigOption {
+  value: string;
+  label: string;
+}
+
+/** Everything a leaf can carry beyond its kind and default. A flat union of
+ *  every `Pref*` leaf's extras, plus labkit's own `debounceMs`. */
+export interface Annotations {
+  name?: string;
+  description?: string;
+  hidden?: boolean;
+  block?: boolean;
+  pair?: string;
+  min?: number;
+  max?: number;
+  step?: number;
+  control?: string;
+  options?: readonly ConfigOption[];
+  placeholder?: string;
+  maxLength?: number;
+  /** Milliseconds to debounce a string leaf's live writes. Default 150. */
+  debounceMs?: number;
+}
+
+/** What a rule contributes. `kind` is honored only while it is still unset,
+ *  which is what makes `f.value` claimable and a kinded factory final. */
+export type LeafPatch = Annotations & { kind?: string };
+
+/** What a rule is given for the leaf it is deciding about. */
+export interface ConfigRuleContext {
+  /** The config key this leaf writes. */
+  key: string;
+  /** Dotted path within the schema. Equal to `key` while schemas are flat. */
+  path: string;
+  /** The leaf's default value. A rule may read it but never change it. */
+  default: unknown;
+  /** What earlier rules and the author's own annotations have settled. */
+  leaf: Readonly<LeafPatch>;
+}
+
+/**
+ * Decides part of how a leaf is presented. Returns a patch, or null to
+ * abstain. Merging is gap-filling: a property already settled is never
+ * overwritten, so the author's annotations beat every rule and a consumer's
+ * rules beat labkit's built-ins.
+ */
+export type ConfigRule = (ctx: ConfigRuleContext) => LeafPatch | null;
+
+/** A presentational bucket of leaves, rendered under one heading. */
+export interface SectionSpec {
+  label: string;
+  paths: readonly string[];
+}
+
+/** A schema resolved against a set of rules: the vocabulary weasel-ui renders,
+ *  plus the three things labkit keeps on the side because `PrefLeaf` has no
+ *  field for them. */
+export interface ResolvedConfig {
+  /** Flat: every leaf is a direct child, so a leaf's path is its config key. */
+  group: PrefGroup;
+  sections: readonly SectionSpec[];
+  showIf: ReadonlyMap<string, (config: Record<string, unknown>) => boolean>;
+  /** Node-level `.render` overrides, keyed by path. */
+  renderers: Readonly<Record<string, ControlRenderer>>;
+}
+
+/** Per-node extras that do not belong on a `PrefLeaf`. */
+export interface NodeOptions {
+  section?: string;
+  showIf?: (config: Record<string, unknown>) => boolean;
+  render?: ControlRenderer;
+  validate?: (leaf: PrefLeaf) => string[];
+}
+
+/** The builder's leaf: a kind (or null, to be decided by rules), a default,
+ *  an annotation bag, and the extras above. */
+export interface ConfigNode<T = unknown> {
+  readonly kind: string | null;
+  readonly default: T;
+  readonly annotations: Readonly<Annotations>;
+  readonly options: Readonly<NodeOptions>;
+}
+
+/** The value type a node produces. */
+export type NodeValue<N> = N extends ConfigNode<infer T> ? T : never;
+
+/** The config type a builder shape produces. */
+export type InferConfig<S> = { [K in keyof S]: NodeValue<S[K]> };
+
+/** An instrument's config, declared once. */
+export interface ConfigSchema<TC> {
+  readonly nodes: Readonly<Record<string, ConfigNode>>;
+  /** The starting config — what `defaultConfig()` would have returned. */
+  defaults(): TC;
+}
+
+/** The config type behind a schema: `ConfigOf<typeof sceneConfig>`. */
+export type ConfigOf<S> = S extends ConfigSchema<infer TC> ? TC : never;

package/src/config/useConfigSchema.ts

@@ -0,0 +1,30 @@
+import { useContext, useMemo } from 'react';
+import type { Instrument } from '../instrument/types';
+import { LabContext } from '../lab/LabContext';
+import { fromConfigFields } from './fromConfigField';
+import { resolveConfigSchema } from './resolve';
+import type { ResolvedConfig } from './types';
+
+const NO_RULES: readonly [] = [];
+
+/**
+ * An instrument's controls, resolved against the surrounding lab's rules.
+ *
+ * Resolution cannot happen in `defineInstrument` — rules are lab-scoped and
+ * that runs at module load — so it happens here, at render. Both instrument
+ * paths land in the same shape, so callers never branch on which was used.
+ */
+export function useConfigSchema(
+  // biome-ignore lint/suspicious/noExplicitAny: instruments are stored contravariantly; see InstrumentList
+  instrument: Instrument<any, any, any>, // eslint-disable-line @typescript-eslint/no-explicit-any
+): ResolvedConfig {
+  const lab = useContext(LabContext);
+  const rules = lab?.configRules ?? NO_RULES;
+  return useMemo(
+    () =>
+      instrument.config
+        ? resolveConfigSchema(instrument.config, rules)
+        : fromConfigFields(instrument.configSchema?.() ?? []),
+    [instrument, rules],
+  );
+}

package/src/config/visible.ts

@@ -0,0 +1,20 @@
+import type { ResolvedConfig } from './types';
+
+/**
+ * Whether a leaf's row should be drawn right now.
+ *
+ * `hidden` is the leaf's own static flag; `showIf` is the schema's predicate
+ * over the live config. Both are presentational — a hidden leaf keeps its
+ * value and the instrument still reads it.
+ */
+export function isLeafVisible(
+  resolved: ResolvedConfig,
+  path: string,
+  config: Record<string, unknown>,
+  showHidden = false,
+): boolean {
+  const leaf = resolved.group.children[path];
+  if (leaf && 'hidden' in leaf && leaf.hidden === true && !showHidden) return false;
+  const predicate = resolved.showIf.get(path);
+  return predicate ? predicate(config) : true;
+}

package/src/controls/ControlPanel.less

@@ -1,61 +1,7 @@
+// The panel is a `<PropertyList>` now, so the rows carry their own styling
+// from PropertyPanel.less. This class remains as the consumer-facing hook.
+// It carries no padding: whatever mounts the panel insets it, and a second
+// inset here doubled the gutter inside an already narrow sidebar.
 .lk-control-panel {
-  display: flex;
-  flex-direction: column;
-  gap: var(--wzl-space-sm);
-  padding: var(--wzl-space-sm);
-}
-
-.lk-control-row {
-  display: flex;
-  flex-direction: column;
-  gap: var(--wzl-space-xs);
-}
-
-.lk-control-row--inline {
-  flex-direction: row;
-  align-items: center;
-  gap: var(--wzl-space-sm);
-}
-
-.lk-control-label {
-  font-size: var(--wzl-font-size-sm);
-  color: var(--wzl-fg);
-}
-
-.lk-control-input {
-  width: 100%;
-  background: var(--wzl-surface-raised);
-  color: var(--wzl-fg);
-  border: 1px solid var(--wzl-border);
-  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(--wzl-font-size-sm);
-  font-variant-numeric: tabular-nums;
-  color: var(--wzl-fg-muted);
-  min-width: 3ch;
-  text-align: right;
-}
-
-.lk-control-slider-row {
-  display: flex;
-  align-items: center;
-  gap: var(--wzl-space-sm);
 }

package/src/controls/ControlPanel.stories.tsx

@@ -1,5 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';
+import { f } from '../config/builder';
+import { resolveConfigSchema } from '../config/resolve';
+import type { ConfigRule, ControlRenderer } from '../config/types';
+import { PropertyRow } from '../ui/properties/PropertyPanel';
 import { ControlPanel } from './ControlPanel';
 import type { ConfigField } from './types';
 
@@ -75,3 +79,85 @@ export const Minimal: Story = {
     />
   ),
 };
+
+const sectioned = f.schema({
+  showGrid: f.boolean(true),
+  cellSize: f.number(20).range(5, 80).step(5).label('Grid spacing'),
+  seed: f.number(1).section('Advanced'),
+  jitter: f.number(0).range(0, 1).step(0.05).section('Advanced'),
+  label: f.string('untitled').section('Advanced').placeholder('name this run'),
+  offset: f.custom('vector2', { x: 0, y: 0 }).section('Advanced').label('Offset'),
+});
+
+function SchemaHarness({
+  rules = [],
+  renderers,
+}: {
+  rules?: readonly ConfigRule[];
+  renderers?: Record<string, ControlRenderer>;
+}) {
+  const schema = resolveConfigSchema(sectioned, rules);
+  const [config, setConfig] = useState<Record<string, unknown>>(sectioned.defaults());
+  return (
+    <ControlPanel
+      schema={schema}
+      config={config}
+      setConfig={(key, value) => setConfig((prev) => ({ ...prev, [key as string]: value }))}
+      renderers={renderers}
+    />
+  );
+}
+
+/** Sections, and a kind no control is registered for — the placeholder names
+ *  the gap rather than dropping the row. */
+export const Sections: Story = {
+  render: () => <SchemaHarness />,
+};
+
+/** The same schema with a control supplied for `vector2`. */
+export const CustomControl: Story = {
+  render: () => (
+    <SchemaHarness
+      renderers={{
+        vector2: ({ pref, value, setValue }) => {
+          const v = value as { x: number; y: number };
+          return (
+            <PropertyRow label={(pref as { name: string }).name}>
+              <input
+                type="number"
+                value={v.x}
+                onChange={(e) => setValue({ ...v, x: Number(e.target.value) })}
+              />
+              <input
+                type="number"
+                value={v.y}
+                onChange={(e) => setValue({ ...v, y: Number(e.target.value) })}
+              />
+            </PropertyRow>
+          );
+        },
+      }}
+    />
+  ),
+};
+
+const conditional = f.schema({
+  showGrid: f.boolean(true),
+  cellSize: f.number(20).range(5, 80).step(5).label('Grid spacing').showIf((c) => c.showGrid === true),
+});
+
+/** `showIf` hides the row while the value stays in config. Toggle the
+ *  checkbox to watch the slider come and go. */
+export const Conditional: Story = {
+  render: () => {
+    const schema = resolveConfigSchema(conditional, []);
+    const [config, setConfig] = useState<Record<string, unknown>>(conditional.defaults());
+    return (
+      <ControlPanel
+        schema={schema}
+        config={config}
+        setConfig={(key, value) => setConfig((prev) => ({ ...prev, [key as string]: value }))}
+      />
+    );
+  },
+};

package/src/controls/ControlPanel.test.tsx

@@ -1,5 +1,10 @@
 import { fireEvent, render, screen } from '@testing-library/react';
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { TOOL_PREF_KINDS, type ToolPrefKind } from '@weasel-js/core';
+import type { PrefLeaf } from '@weasel-js/ui';
+import type { ResolvedConfig } from '../config/types';
+import { f } from '../config/builder';
+import { resolveConfigSchema } from '../config/resolve';
 import { ControlPanel } from './ControlPanel';
 import type { ConfigField } from './types';
 
@@ -9,12 +14,13 @@ describe('<ControlPanel> slider', () => {
       { 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');
+    // The row holds two controls -- the range and an editable readout -- inside
+    // one wrapping label, so query the slider by role rather than by label text.
+    const input = screen.getByRole('slider') as HTMLInputElement;
     expect(input.min).toBe('0');
     expect(input.max).toBe('10');
     expect(input.step).toBe('0.5');
-    expect(screen.getByText('2')).toBeInTheDocument();
+    expect(screen.getByDisplayValue('2')).toBeInTheDocument();
   });
 
   it('calls setConfig with numeric value on change', () => {
@@ -23,7 +29,7 @@ describe('<ControlPanel> slider', () => {
       { 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' } });
+    fireEvent.change(screen.getByRole('slider'), { target: { value: '5' } });
     expect(setConfig).toHaveBeenCalledWith('freq', 5);
   });
 });
@@ -86,8 +92,9 @@ describe('<ControlPanel> number', () => {
       { 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' } });
+    // The number row commits as you type, so the clamp applies on change
+    // rather than waiting for blur.
+    fireEvent.change(screen.getByRole('spinbutton'), { target: { value: '999' } });
     expect(setConfig).toHaveBeenCalledWith('n', 100);
   });
 });
@@ -136,14 +143,220 @@ describe('<ControlPanel> color', () => {
 });
 
 describe('<ControlPanel> defensive', () => {
-  it('renders nothing for an unknown field type without crashing', () => {
+  it('names an unknown field type rather than dropping its row', () => {
     const fields = [
       { key: 'mystery', label: 'Mystery', type: 'mystery', default: 1 },
+      { key: 'ok', label: 'Ok', type: 'checkbox', default: true },
     ] as unknown as ConfigField[];
     const { container } = render(
-      <ControlPanel fields={fields} config={{ mystery: 1 }} setConfig={vi.fn()} />,
+      <ControlPanel fields={fields} config={{ mystery: 1, ok: true }} setConfig={vi.fn()} />,
     );
     expect(container.querySelector('.lk-control-panel')).not.toBeNull();
-    expect(container.querySelector('.lk-control-row')).toBeNull();
+    // A kind a lab has not wired up must not blank the panel, and a silently
+    // dropped row reads as "this control does not exist".
+    expect(screen.getByText(/mystery/)).toBeInTheDocument();
+    expect(screen.getByLabelText('Ok')).toBeInTheDocument();
+  });
+});
+
+describe('<ControlPanel> schema', () => {
+  it('renders a schema through the built-in rows', () => {
+    const schema = resolveConfigSchema(f.schema({ showGrid: f.boolean(true) }), []);
+    render(<ControlPanel schema={schema} config={{ showGrid: true }} setConfig={vi.fn()} />);
+    expect(screen.getByLabelText('Show grid')).toBeInTheDocument();
+  });
+
+  it('writes back through setConfig keyed by path', () => {
+    const setConfig = vi.fn();
+    const schema = resolveConfigSchema(f.schema({ showGrid: f.boolean(true) }), []);
+    render(<ControlPanel schema={schema} config={{ showGrid: true }} setConfig={setConfig} />);
+    fireEvent.click(screen.getByLabelText('Show grid'));
+    expect(setConfig).toHaveBeenCalledWith('showGrid', false);
+  });
+
+  it('picks a slider for a bounded number and an input for an open one', () => {
+    const schema = resolveConfigSchema(
+      f.schema({ a: f.number(5).range(0, 10), b: f.number(5) }),
+      [],
+    );
+    render(<ControlPanel schema={schema} config={{ a: 5, b: 5 }} setConfig={vi.fn()} />);
+    expect(screen.getByLabelText('B')).toHaveAttribute('type', 'number');
+  });
+
+  it('falls back to the leaf default when config holds no value', () => {
+    const schema = resolveConfigSchema(f.schema({ tint: f.color('#123456') }), []);
+    render(<ControlPanel schema={schema} config={{}} setConfig={vi.fn()} />);
+    expect(screen.getByLabelText('Tint')).toHaveValue('#123456');
+  });
+});
+
+describe('<ControlPanel> renderers', () => {
+  it('renderers[path] beats renderers[kind]', () => {
+    const schema = resolveConfigSchema(f.schema({ tint: f.color('#ffffff') }), []);
+    render(
+      <ControlPanel
+        schema={schema}
+        config={{ tint: '#ffffff' }}
+        setConfig={vi.fn()}
+        renderers={{ color: () => <span>by-kind</span>, tint: () => <span>by-path</span> }}
+      />,
+    );
+    expect(screen.getByText('by-path')).toBeInTheDocument();
+    expect(screen.queryByText('by-kind')).not.toBeInTheDocument();
+  });
+
+  it('a lab renderer for the path beats the node\'s own .render', () => {
+    const schema = resolveConfigSchema(
+      f.schema({ tint: f.color('#ffffff').render(() => <span>by-node</span>) }),
+      [],
+    );
+    render(
+      <ControlPanel
+        schema={schema}
+        config={{ tint: '#ffffff' }}
+        setConfig={vi.fn()}
+        renderers={{ tint: () => <span>by-path</span> }}
+      />,
+    );
+    expect(screen.getByText('by-path')).toBeInTheDocument();
+  });
+
+  it("a node's .render beats a lab renderer for the kind", () => {
+    const schema = resolveConfigSchema(
+      f.schema({ tint: f.color('#ffffff').render(() => <span>by-node</span>) }),
+      [],
+    );
+    render(
+      <ControlPanel
+        schema={schema}
+        config={{ tint: '#ffffff' }}
+        setConfig={vi.fn()}
+        renderers={{ color: () => <span>by-kind</span> }}
+      />,
+    );
+    expect(screen.getByText('by-node')).toBeInTheDocument();
+  });
+
+  it('supplies a control for a kind labkit does not ship', () => {
+    const schema = resolveConfigSchema(f.schema({ offset: f.custom('vector2', { x: 1 }) }), []);
+    render(
+      <ControlPanel
+        schema={schema}
+        config={{ offset: { x: 1 } }}
+        setConfig={vi.fn()}
+        renderers={{ vector2: (ctx) => <span>vec:{String((ctx.value as { x: number }).x)}</span> }}
+      />,
+    );
+    expect(screen.getByText('vec:1')).toBeInTheDocument();
+  });
+
+  it('a renderer returning null collapses the row', () => {
+    const schema = resolveConfigSchema(f.schema({ tint: f.color('#ffffff') }), []);
+    const { container } = render(
+      <ControlPanel
+        schema={schema}
+        config={{ tint: '#ffffff' }}
+        setConfig={vi.fn()}
+        renderers={{ color: () => null }}
+      />,
+    );
+    expect(container.querySelector('.lk-property-row')).toBeNull();
+  });
+});
+
+describe('<ControlPanel> visibility and sections', () => {
+  it('hides a row whose showIf is false', () => {
+    const schema = resolveConfigSchema(
+      f.schema({
+        showGrid: f.boolean(true),
+        cellSize: f.number(20).showIf((c) => c.showGrid === true),
+      }),
+      [],
+    );
+    const { rerender } = render(
+      <ControlPanel schema={schema} config={{ showGrid: true, cellSize: 20 }} setConfig={vi.fn()} />,
+    );
+    expect(screen.getByLabelText('Cell size')).toBeInTheDocument();
+    rerender(
+      <ControlPanel
+        schema={schema}
+        config={{ showGrid: false, cellSize: 20 }}
+        setConfig={vi.fn()}
+      />,
+    );
+    expect(screen.queryByLabelText('Cell size')).not.toBeInTheDocument();
+  });
+
+  it('keeps a hidden leaf out unless asked for it', () => {
+    const schema = resolveConfigSchema(f.schema({ seed: f.number(0).hidden() }), []);
+    const { rerender } = render(
+      <ControlPanel schema={schema} config={{ seed: 0 }} setConfig={vi.fn()} />,
+    );
+    expect(screen.queryByLabelText('Seed')).not.toBeInTheDocument();
+    rerender(<ControlPanel schema={schema} config={{ seed: 0 }} setConfig={vi.fn()} showHidden />);
+    expect(screen.getByLabelText('Seed')).toBeInTheDocument();
+  });
+
+  it('groups sectioned leaves under a heading, ungrouped ones first', () => {
+    const schema = resolveConfigSchema(
+      f.schema({ showGrid: f.boolean(true), seed: f.number(0).section('Advanced') }),
+      [],
+    );
+    const { container } = render(
+      <ControlPanel schema={schema} config={{ showGrid: true, seed: 0 }} setConfig={vi.fn()} />,
+    );
+    expect(screen.getByText('Advanced')).toBeInTheDocument();
+    const group = container.querySelector('.lk-property-group');
+    expect(group).not.toBeNull();
+    expect(group?.textContent).toContain('Seed');
+    expect(group?.textContent).not.toContain('Show grid');
+  });
+});
+
+describe('<ControlPanel> built-in kind coverage', () => {
+  const KIND = 'spline' as ToolPrefKind;
+  afterEach(() => {
+    delete (TOOL_PREF_KINDS as Record<string, true>)[KIND];
+  });
+
+  const schemaWith = (...leaves: PrefLeaf[]): ResolvedConfig => ({
+    group: {
+      name: 'root',
+      children: Object.fromEntries(leaves.map((leaf, i) => [`k${i}`, leaf])),
+    },
+    sections: [],
+    showIf: new Map(),
+    renderers: {},
+  });
+
+  it('declines paint and object with a named row rather than a blank one', () => {
+    render(
+      <ControlPanel
+        schema={schemaWith(
+          { kind: 'paint', name: 'Fill', description: '', default: null },
+          {
+            kind: 'object', name: 'Stroke', description: '', default: {},
+            children: { width: { kind: 'number', name: 'Width', description: '', default: 1 } },
+          },
+        )}
+        config={{}}
+        setConfig={vi.fn()}
+      />,
+    );
+    expect(screen.getByText(/no control for .paint./)).toBeInTheDocument();
+    expect(screen.getByText(/no control for .object./)).toBeInTheDocument();
+  });
+
+  it('throws for a built-in kind with no case arm', () => {
+    (TOOL_PREF_KINDS as Record<string, true>)[KIND] = true;
+    expect(() =>
+      render(
+        <ControlPanel
+          schema={schemaWith({ kind: KIND, name: 'Curve', description: '', default: null })}
+          config={{}}
+          setConfig={vi.fn()}
+        />,
+      ),
+    ).toThrow(/spline/);
   });
 });