@weasel-js/labkit 1.2.0 → 1.3.0

package/src/controls/ControlPanel.stories.tsx

@@ -1,5 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import { PropertyRow } from '@weasel-js/ui';
 import { useState } from 'react';
+import { f } from '../config/builder';
+import { resolveConfigSchema } from '../config/resolve';
+import type { ConfigRule, ControlRenderer } from '../config/types';
 import { ControlPanel } from './ControlPanel';
 import type { ConfigField } from './types';
 
@@ -75,3 +79,124 @@ 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 described = f.schema({
+  frequency: f
+    .number(2)
+    .range(0.1, 10)
+    .step(0.1)
+    .describe('Cycles per second the oscillator runs at.'),
+  amplitude: f.number(0.5).range(0, 1).step(0.05),
+  showGrid: f.boolean(true).describe('Draw the alignment grid behind the plot.'),
+  wave: f
+    .enum('sine', [
+      { value: 'sine', label: 'Sine' },
+      { value: 'square', label: 'Square' },
+    ])
+    .describe('Waveform the generator emits.'),
+  title: f.string('My experiment'),
+  tint: f.color('#3a86ff').describe('Plot line color.'),
+});
+
+/** A leaf with a `describe(...)` gets an \u24d8 beside its label whose tooltip
+ *  carries the text; leaves without one stay bare. */
+export const Described: Story = {
+  render: () => {
+    const schema = resolveConfigSchema(described, []);
+    const [config, setConfig] = useState<Record<string, unknown>>(described.defaults());
+    return (
+      <ControlPanel
+        schema={schema}
+        config={config}
+        setConfig={(key, value) => setConfig((prev) => ({ ...prev, [key as string]: value }))}
+      />
+    );
+  },
+};
+
+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 { TOOL_PREF_KINDS, type ToolPrefKind } from '@weasel-js/core';
+import type { PrefLeaf } from '@weasel-js/ui';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { f } from '../config/builder';
+import { resolveConfigSchema } from '../config/resolve';
+import type { ResolvedConfig } from '../config/types';
 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,242 @@ 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');
+  });
+
+  it('hangs a described leaf\u2019s description off a help affordance, and leaves an undescribed leaf bare', () => {
+    const schema = resolveConfigSchema(
+      f.schema({
+        showGrid: f.boolean(true).describe('Draw the alignment grid.'),
+        snap: f.boolean(true),
+      }),
+      [],
+    );
+    render(
+      <ControlPanel schema={schema} config={{ showGrid: true, snap: true }} setConfig={vi.fn()} />,
+    );
+    expect(screen.getByRole('button', { name: 'About Show grid' })).toBeInTheDocument();
+    expect(screen.getAllByRole('button', { name: /^About / })).toHaveLength(1);
+  });
+});
+
+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') }), []);
+    render(
+      <ControlPanel
+        schema={schema}
+        config={{ tint: '#ffffff' }}
+        setConfig={vi.fn()}
+        renderers={{ color: () => null }}
+      />,
+    );
+    expect(screen.queryByText('Tint')).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') }),
+      [],
+    );
+    render(
+      <ControlPanel schema={schema} config={{ showGrid: true, seed: 0 }} setConfig={vi.fn()} />,
+    );
+    expect(screen.getByText('Advanced')).toBeInTheDocument();
+    const group = screen.getByRole('heading', { name: 'Advanced' }).parentElement;
+    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/);
   });
 });