@weasel-js/labkit 1.5.0 → 1.5.1

package/src/config/autoConfig.ts

@@ -0,0 +1,153 @@
+import { isPrefLeaf, type PrefGroup, type PrefLeaf } from '@weasel-js/ui';
+import { isAuto } from './auto';
+import { isRecord, withValueAtPath } from './path';
+import type { ResolvedConfig } from './types';
+
+type Resolver = (config: Record<string, unknown>) => unknown;
+
+/** Reads a labkit-only extra off a resolved leaf. `PrefLeaf` has no field for
+ *  these; they ride as extra keys and survive the resolve walk. */
+function extra<T>(leaf: PrefLeaf, key: string): T | undefined {
+  return (leaf as unknown as Record<string, T | undefined>)[key];
+}
+
+/** Every leaf in a resolved schema, in schema order, with its dotted path. */
+function* leaves(group: PrefGroup, at = ''): Generator<[string, PrefLeaf]> {
+  for (const [key, child] of Object.entries(group.children)) {
+    const path = at === '' ? key : `${at}.${key}`;
+    if (isPrefLeaf(child)) yield [path, child];
+    else yield* leaves(child, path);
+  }
+}
+
+/** The dotted paths a schema declares as starting auto — every leaf that said
+ *  `.initial(auto)`. This is what seeds a new trial's unpinned set. */
+export function autoPathsOf(resolved: ResolvedConfig): string[] {
+  const out: string[] = [];
+  for (const [path, leaf] of leaves(resolved.group)) {
+    if (extra<boolean>(leaf, 'unpinned')) out.push(path);
+  }
+  return out;
+}
+
+/**
+ * The config an instrument reads: the stored one, with every unpinned path
+ * either computed by its resolver or removed.
+ *
+ * Resolution is demand-driven — a resolver reading another unpinned path
+ * forces that one first, whatever order the schema declared them in — so a
+ * cycle is a real cycle and not an ordering accident.
+ */
+export function resolveAutoConfig<TC>(
+  resolved: ResolvedConfig,
+  config: TC,
+  autoPaths: ReadonlySet<string>,
+): TC {
+  if (autoPaths.size === 0) return config;
+
+  const resolvers = new Map<string, Resolver | undefined>();
+  for (const [path, leaf] of leaves(resolved.group)) {
+    if (autoPaths.has(path)) resolvers.set(path, extra<Resolver>(leaf, 'autoResolve'));
+  }
+  if (resolvers.size === 0) return config;
+
+  // Drop first, so a resolver reading a still-unresolved auto path sees
+  // `undefined` rather than a stale pinned value it would silently believe.
+  let out = config as unknown as Record<string, unknown>;
+  for (const path of resolvers.keys()) out = dropAtPath(out, path);
+
+  const inFlight = new Set<string>();
+  const done = new Set<string>();
+
+  const need = (path: string): void => {
+    if (done.has(path)) return;
+    if (inFlight.has(path)) {
+      throw new Error(`[labkit] auto resolver cycle at "${path}"`);
+    }
+    const resolve = resolvers.get(path);
+    if (!resolve) {
+      done.add(path);
+      return;
+    }
+    inFlight.add(path);
+    try {
+      // Read `out` only after the resolver has run: it forces its own
+      // dependencies, and each of those replaced `out`.
+      const value = resolve(demand(() => out, resolvers, need));
+      out = withValueAtPath(out, path, value);
+    } finally {
+      inFlight.delete(path);
+    }
+    done.add(path);
+  };
+
+  for (const path of resolvers.keys()) need(path);
+  return out as unknown as TC;
+}
+
+/**
+ * The config a resolver reads. A top-level key that is itself unpinned is
+ * forced before it is handed back, which is what makes declaration order
+ * irrelevant and turns a genuine loop into a named error.
+ *
+ * Only top-level keys are trapped: a resolver reaching `c.grid.size` gets the
+ * already-dropped branch, and a nested auto path it depends on resolves by
+ * schema order alone.
+ */
+function demand(
+  read: () => Record<string, unknown>,
+  resolvers: ReadonlyMap<string, Resolver | undefined>,
+  need: (path: string) => void,
+): Record<string, unknown> {
+  return new Proxy(read(), {
+    get(_target, key) {
+      if (typeof key === 'string' && resolvers.has(key)) need(key);
+      return Reflect.get(read(), key);
+    },
+    has(_target, key) {
+      return Reflect.has(read(), key);
+    },
+    ownKeys() {
+      return Reflect.ownKeys(read());
+    },
+    getOwnPropertyDescriptor(_target, key) {
+      return Reflect.getOwnPropertyDescriptor(read(), key);
+    },
+  });
+}
+
+/** A copy of `config` with the dotted path removed, copying every record on
+ *  the way down. A path that is not there comes back unchanged. */
+function dropAtPath(config: Record<string, unknown>, path: string): Record<string, unknown> {
+  const [head, ...rest] = path.split('.');
+  if (head === undefined || !(head in config)) return config;
+  if (rest.length === 0) {
+    const { [head]: _dropped, ...kept } = config;
+    return kept;
+  }
+  const child = config[head];
+  if (!isRecord(child)) return config;
+  return { ...config, [head]: dropAtPath(child, rest.join('.')) };
+}
+
+/**
+ * What writing `value` at `path` makes of a trial's raw config and its set of
+ * unpinned paths. `auto` pins nothing and joins the set; any other value is
+ * written and leaves it. Both the store and the chrome go through this, so
+ * they cannot disagree about what a write meant.
+ */
+export function applyConfigWrite<TC>(
+  config: TC,
+  autoPaths: readonly string[],
+  path: string,
+  value: unknown,
+): { config: TC; autoPaths: readonly string[] } {
+  if (isAuto(value)) {
+    if (autoPaths.includes(path)) return { config, autoPaths };
+    return { config, autoPaths: [...autoPaths, path] };
+  }
+  return {
+    config: withValueAtPath(config, path, value),
+    autoPaths: autoPaths.includes(path) ? autoPaths.filter((p) => p !== path) : autoPaths,
+  };
+}

package/src/config/builder.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+import { auto } from './auto';
 import { f } from './builder';
 import type { ConfigOf, ConfigPath, ValueAtPath } from './types';
 
@@ -154,3 +155,40 @@ describe('builder / nested types', () => {
     expect([size, path, value]).toEqual([20, 'grid.size', 40]);
   });
 });
+
+describe('auto on a node', () => {
+  it('attaches a resolver without changing the default', () => {
+    const n = f.number(12).auto((c) => (c.width as number) / 24);
+    expect(n.default).toBe(12);
+    expect(n.options.autoResolve?.({ width: 432 })).toBe(18);
+  });
+
+  it('.initial(auto) marks the node as starting unpinned', () => {
+    expect(f.number(3).initial(auto).options.unpinned).toBe(true);
+    expect(f.number(3).options.unpinned).toBeUndefined();
+  });
+
+  it('.manual() opts the node out of ever being auto', () => {
+    expect(f.number(1).manual().options.manual).toBe(true);
+  });
+
+  it('clones rather than mutating, like every other chaining method', () => {
+    const base = f.number(3);
+    const unpinned = base.initial(auto);
+    expect(base.options.unpinned).toBeUndefined();
+    expect(unpinned).not.toBe(base);
+  });
+
+  it('keeps the subclass, so kind-specific methods still chain after', () => {
+    const n = f.number(3).initial(auto).range(0, 10).suffix('px');
+    expect(n.annotations.min).toBe(0);
+    expect(n.annotations.suffix).toBe('px');
+    expect(n.options.unpinned).toBe(true);
+  });
+
+  it('rejects anything but the sentinel, for a caller TypeScript is not checking', () => {
+    const n = f.number(3) as unknown as { initial: (value: unknown) => unknown };
+    expect(() => n.initial(5)).toThrow(/takes `auto`/);
+    expect(() => n.initial(Symbol('auto'))).toThrow(/takes `auto`/);
+  });
+});

package/src/config/builder.ts

@@ -1,4 +1,5 @@
-import type { PrefLeaf, PrefNumberFormat } from '@weasel-js/ui';
+import type { PrefLeaf, PrefNumberFormat, PrefNumberUnit } from '@weasel-js/ui';
+import { type Auto, isAuto } from './auto';
 import type {
   Annotations,
   BranchAnnotations,
@@ -12,6 +13,7 @@ import type {
   ControlRenderer,
   InferConfig,
   NodeOptions,
+  SectionOption,
 } from './types';
 
 /** Whether a schema entry is a branch rather than a leaf. */
@@ -72,8 +74,9 @@ export abstract class BaseNode<T> implements ConfigNode<T> {
   }
 
   /** Render under a named section heading. `collapsed` opens the section
-   *  folded — say it on any one of the section's leaves. */
-  section(label: string, opts: { collapsed?: boolean } = {}): this {
+   *  folded, and `layout` and `pack` lay out its rows — say each on any one of
+   *  the section's leaves. */
+  section(label: string, opts: Omit<SectionOption, 'label'> = {}): this {
     return this.opt({ section: { label, ...opts } });
   }
 
@@ -87,6 +90,30 @@ export abstract class BaseNode<T> implements ConfigNode<T> {
   render(renderer: ControlRenderer): this {
     return this.opt({ render: renderer });
   }
+
+  /**
+   * Compute this leaf's value while it is auto, instead of leaving it
+   * `undefined`. The resolver is given the config with every other auto path
+   * already resolved.
+   */
+  auto(resolve: (config: Record<string, unknown>) => T): this {
+    return this.opt({ autoResolve: resolve as (c: Record<string, unknown>) => unknown });
+  }
+
+  /**
+   * Start this leaf auto rather than pinned at its default. Takes `auto` and
+   * nothing else — the constructor argument already declares the value, and a
+   * second way to say it would fight with the first.
+   */
+  initial(value: Auto): this {
+    if (!isAuto(value)) throw new Error('[labkit] .initial() takes `auto` and nothing else');
+    return this.opt({ unpinned: true });
+  }
+
+  /** Never auto. The row takes no pin dot and ignores the gesture. */
+  manual(): this {
+    return this.opt({ manual: true });
+  }
 }
 
 export class NumberNode extends BaseNode<number> {
@@ -113,6 +140,16 @@ export class NumberNode extends BaseNode<number> {
     return this.ann({ format });
   }
 
+  /**
+   * Store the value in one unit and edit it in another — radians stored,
+   * degrees typed. `min`, `max` and `step` are declared in the stored unit
+   * alongside the value, and convert with it. `prefUnit` builds one from a
+   * `UnitSystem`.
+   */
+  unit(unit: PrefNumberUnit): this {
+    return this.ann({ unit });
+  }
+
   /** Force a slider even without both bounds. */
   slider(): this {
     return this.ann({ control: 'slider' });
@@ -127,8 +164,7 @@ export class NumberNode extends BaseNode<number> {
 export class BooleanNode extends BaseNode<boolean> {
   readonly kind = 'boolean';
 
-  /** Ask for a switch. `ControlPanel` still draws a checkbox; weasel-ui's
-   *  `PrefsForm` honors the distinction. */
+  /** Ask for a switch rather than a checkbox. */
   toggle(): this {
     return this.ann({ control: 'switch' });
   }
@@ -153,6 +189,12 @@ export class StringNode extends BaseNode<string> {
 
 export class ColorNode extends BaseNode<string> {
   readonly kind = 'color';
+
+  /** The value carries alpha as `#rrggbbaa`, and the row gets an opacity
+   *  track beside the swatch. */
+  alpha(): this {
+    return this.ann({ alpha: true });
+  }
 }
 
 export class EnumNode<T extends string> extends BaseNode<T> {
@@ -220,7 +262,7 @@ export class GroupNode<S extends ConfigShape> implements ConfigBranch<S> {
   }
 
   /** Render this whole group under a named section heading. */
-  section(label: string, opts: { collapsed?: boolean } = {}): GroupNode<S> {
+  section(label: string, opts: Omit<SectionOption, 'label'> = {}): GroupNode<S> {
     return this.with(this.annotations, { ...this.options, section: { label, ...opts } });
   }
 
@@ -282,8 +324,11 @@ export const f = {
   group: <const S extends ConfigShape>(children: S): GroupNode<S> => new GroupNode(children),
 
   /** A leaf of a kind a lab supplies the control for, through `controls`. */
-  custom: <T>(kind: string, def: T, validate?: (leaf: PrefLeaf) => string[]): CustomNode<T> =>
-    new CustomNode(kind, def, {}, validate ? { validate } : {}),
+  custom: <T>(
+    kind: string,
+    def: T,
+    validate?: (leaf: PrefLeaf, config: Record<string, unknown>) => string[],
+  ): CustomNode<T> => new CustomNode(kind, def, {}, validate ? { validate } : {}),
 
   /** Collect leaves and groups into an instrument's config. */
   schema<S extends ConfigShape>(nodes: S): ConfigSchema<InferConfig<S>> {

package/src/config/index.ts

@@ -1,3 +1,5 @@
+export { type Auto, auto, isAuto } from './auto';
+export { autoPathsOf, resolveAutoConfig } from './autoConfig';
 export {
   BaseNode,
   BooleanNode,
@@ -46,4 +48,5 @@ export type {
   ValueAtPath,
 } from './types';
 export { useConfigSchema } from './useConfigSchema';
+export { useResolvedConfig } from './useResolvedConfig';
 export { isLeafVisible } from './visible';

package/src/config/path.ts

@@ -6,8 +6,13 @@ import type { PrefGroup, PrefLeaf } from '@weasel-js/ui';
  * reached by exactly the same call.
  */
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A plain object a config tree can be walked into. An array, a `Date`, a
+ *  `Map` or a class instance is a leaf value: a walk that descended into one
+ *  would rebuild it as a bare `{}`. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
 }
 
 /** The value at a dotted path. `undefined` when a segment is missing or the

package/src/config/resolve.test.ts

@@ -1,5 +1,6 @@
 import type { PrefGroup } from '@weasel-js/ui';
 import { describe, expect, it } from 'vitest';
+import { auto } from './auto';
 import { f } from './builder';
 import { resolveConfigSchema } from './resolve';
 import { titleCase } from './rules';
@@ -207,4 +208,28 @@ describe('resolveConfigSchema / nested groups', () => {
     );
     expect(r.sections).toEqual([{ at: '', label: 'Advanced', paths: ['grid'] }]);
   });
+
+  it('rejects a leaf that is both manual and starts auto', () => {
+    const schema = f.schema({ seed: f.number(1).manual().initial(auto) });
+    expect(() => resolveConfigSchema(schema, [])).toThrow(/seed/);
+    expect(() => resolveConfigSchema(schema, [])).toThrow(/manual/);
+  });
+
+  it('carries autoResolve, unpinned and manual onto the resolved leaf', () => {
+    const r = resolveConfigSchema(
+      f.schema({
+        gap: f.number(12).auto(() => 18),
+        cols: f.number(3).initial(auto),
+        seed: f.number(1).manual(),
+        plain: f.number(0),
+      }),
+      [],
+    );
+    expect(typeof leafAt(r, 'gap').autoResolve).toBe('function');
+    expect(leafAt(r, 'cols').unpinned).toBe(true);
+    expect(leafAt(r, 'seed').manual).toBe(true);
+    expect(leafAt(r, 'plain').autoResolve).toBeUndefined();
+    expect(leafAt(r, 'plain').unpinned).toBeUndefined();
+    expect(leafAt(r, 'plain').manual).toBeUndefined();
+  });
 });

package/src/config/resolve.ts

@@ -76,6 +76,8 @@ function resolveShape(shape: ConfigShape, at: string, name: string, sink: Sink):
       if (section.collapsed !== undefined) {
         spec.collapsed = (spec.collapsed ?? false) || section.collapsed;
       }
+      if (section.layout !== undefined && spec.layout === undefined) spec.layout = section.layout;
+      if (section.pack !== undefined && spec.pack === undefined) spec.pack = section.pack;
     }
     if (predicate) sink.showIf.set(path, predicate);
     if (!isConfigBranch(entry) && entry.options.render) sink.renderers[path] = entry.options.render;
@@ -101,10 +103,24 @@ function resolveEntry(
       ? group
       : { ...group, description: entry.annotations.description };
   }
+  if (entry.options.manual && entry.options.unpinned) {
+    throw new Error(
+      `[labkit] "${path}" is both .manual() and .initial(auto) — a field that can never be auto cannot start auto`,
+    );
+  }
   const seed: LeafPatch = defined({
     ...entry.annotations,
     ...(entry.kind === null ? {} : { kind: entry.kind }),
   });
   const patch = applyRules(seed, { key, path, default: entry.default }, sink.chain);
-  return { ...patch, default: entry.default } as PrefLeaf;
+  const { autoResolve, unpinned, manual } = entry.options;
+  return {
+    ...patch,
+    default: entry.default,
+    // Extra keys survive onto the leaf at runtime; `ControlPanel` reads them
+    // back with its `extra<T>` helper, the same as `min`, `step` and the rest.
+    ...(autoResolve === undefined ? {} : { autoResolve }),
+    ...(unpinned === undefined ? {} : { unpinned }),
+    ...(manual === undefined ? {} : { manual }),
+  } as PrefLeaf;
 }

package/src/config/types.ts

@@ -1,4 +1,10 @@
-import type { PrefGroup, PrefLeaf, PrefNumberFormat, PrefRenderer } from '@weasel-js/ui';
+import type {
+  PrefGroup,
+  PrefLeaf,
+  PrefNumberFormat,
+  PrefNumberUnit,
+  PrefRenderer,
+} from '@weasel-js/ui';
 
 /**
  * Renders the control cell for one config leaf. Identical to weasel-ui's
@@ -27,6 +33,11 @@ export interface Annotations {
   suffix?: string;
   /** How a number's value is shown. `compact` abbreviates from a thousand up. */
   format?: PrefNumberFormat;
+  /** Display-unit conversion for a number stored in a canonical unit — the
+   *  value, its bounds and its step all convert at the control's edge. */
+  unit?: PrefNumberUnit;
+  /** A color leaf's value carries alpha (`#rrggbbaa`) and its row edits it. */
+  alpha?: boolean;
   control?: string;
   options?: readonly ConfigOption[];
   placeholder?: string;
@@ -76,6 +87,10 @@ export interface SectionSpec {
    *  whether or not it was given a panel-wide `collapse`; a fold the reader
    *  has since toggled outranks it. */
   collapsed?: boolean;
+  /** Where the section's rows put their labels, over the panel's `layout`. */
+  layout?: 'block' | 'inline';
+  /** How the section packs its rows, over the panel's `pack`. */
+  pack?: 'auto' | 'pairs' | 'one-up';
 }
 
 /** A schema resolved against a set of rules: the vocabulary weasel-ui renders,
@@ -97,12 +112,27 @@ export interface ResolvedConfig {
 export interface SectionOption {
   label: string;
   collapsed?: boolean;
+  /** Where the section's rows put their labels, over the panel's `layout`. */
+  layout?: 'block' | 'inline';
+  /** How the section packs its rows, over the panel's `pack`. */
+  pack?: 'auto' | 'pairs' | 'one-up';
 }
 
 /** Per-node extras that do not belong on a `PrefLeaf`. */
 export interface NodeOptions extends BranchOptions {
   render?: ControlRenderer;
-  validate?: (leaf: PrefLeaf) => string[];
+  /** Errors for this leaf under `config`, the instrument's whole config. */
+  validate?: (leaf: PrefLeaf, config: Record<string, unknown>) => string[];
+  /** Computes this leaf's value while it is auto. Attaching one is what lets
+   *  the ghosted control draw a real value and keeps the instrument off
+   *  `?? compute()`. */
+  autoResolve?: (config: Record<string, unknown>) => unknown;
+  /** The leaf starts auto rather than pinned at its default. Set by
+   *  `.initial(auto)`. */
+  unpinned?: boolean;
+  /** The leaf can never be auto: the row takes no pin dot and ignores the
+   *  gesture. For a value the instrument cannot receive as `undefined`. */
+  manual?: boolean;
 }
 
 /** What a branch can say about itself, beyond its children. */

package/src/config/useResolvedConfig.ts

@@ -0,0 +1,26 @@
+import { useMemo } from 'react';
+import { resolveAutoConfig } from './autoConfig';
+import type { ResolvedConfig } from './types';
+
+const NONE: ReadonlySet<string> = new Set();
+
+/**
+ * The config an instrument reads: the stored one with every unpinned path
+ * resolved. The single place resolution happens, so `Trial` and
+ * `useTrialState` cannot disagree about what an instrument is looking at.
+ */
+export function useResolvedConfig<TC>(
+  schema: ResolvedConfig | undefined,
+  config: TC,
+  autoPaths: readonly string[] | undefined,
+): { config: TC; auto: ReadonlySet<string> } {
+  const auto = useMemo(
+    () => (autoPaths && autoPaths.length > 0 ? new Set(autoPaths) : NONE),
+    [autoPaths],
+  );
+  const resolvedConfig = useMemo(
+    () => (schema ? resolveAutoConfig(schema, config, auto) : config),
+    [schema, config, auto],
+  );
+  return { config: resolvedConfig, auto };
+}

package/src/controls/AutoControls.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from '@weasel-js/forge';
+import { useState } from 'react';
+import { applyConfigWrite } from '../config/autoConfig';
+import { f } from '../config/builder';
+import { resolveConfigSchema } from '../config/resolve';
+import { ControlPanel } from './ControlPanel';
+
+/**
+ * The ghosting and the muted accent are CSS, and jsdom resolves neither
+ * `var()` nor `color-mix()`. This story is the only place they can be checked.
+ */
+const meta: Meta<typeof ControlPanel> = {
+  title: 'labkit/Controls/AutoControls',
+  component: ControlPanel,
+  parameters: { layout: 'padded' },
+};
+export default meta;
+
+type Story = StoryObj<typeof ControlPanel>;
+
+const schema = f.schema({
+  width: f.number(432).range(64, 1024).label('Width'),
+  gap: f
+    .number(12)
+    .range(0, 48)
+    .suffix('px')
+    .auto((c) => Math.round((c.width as number) / 24))
+    .label('Gap'),
+  cols: f.number(3).range(1, 12).label('Columns'),
+  wave: f.enum('sine', ['sine', 'square', 'triangle']).label('Wave'),
+  mode: f.enum('fit', ['fit', 'fill']).radio().label('Mode'),
+  showGrid: f.boolean(true).label('Show grid'),
+  title: f.string('My experiment').placeholder('Title…').label('Title'),
+  tint: f.color('#3a86ff').label('Tint'),
+  seed: f.number(1).range(0, 99).manual().label('Seed'),
+});
+
+const resolved = resolveConfigSchema(schema, []);
+
+/** Every path the panel will draw ghosted, except the `.manual()` one. */
+const EVERY_AUTO = ['gap', 'cols', 'wave', 'mode', 'showGrid', 'title', 'tint'];
+
+function Panel({ start }: { start: readonly string[] }) {
+  const [state, setState] = useState(() => ({
+    config: schema.defaults() as Record<string, unknown>,
+    autoPaths: start,
+  }));
+  return (
+    <ControlPanel
+      schema={resolved}
+      config={state.config}
+      auto={new Set(state.autoPaths)}
+      setConfig={(path, value) =>
+        setState((prev) => applyConfigWrite(prev.config, prev.autoPaths, path, value))
+      }
+    />
+  );
+}
+
+function Pair() {
+  return (
+    <div style={{ display: 'flex', gap: 32, alignItems: 'flex-start' }}>
+      <div style={{ flex: '1 1 0', minWidth: 0 }}>
+        <h3>Pinned</h3>
+        <Panel start={[]} />
+      </div>
+      <div style={{ flex: '1 1 0', minWidth: 0 }}>
+        <h3>Auto</h3>
+        <Panel start={EVERY_AUTO} />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Both states of every row kind, side by side. What to look at: an auto row's
+ * control keeps no accent color, its readout reads `auto · 18 px` rather than a
+ * number, and the pin dot appears only under the pointer — except on an auto
+ * row, where it stays. `Seed` is `.manual()` and takes no dot at all.
+ */
+export const BothStates: Story = {
+  render: () => <Pair />,
+};
+
+/** One panel to shift-click around in: the handle must not move as it toggles. */
+export const Interactive: Story = {
+  render: () => <Panel start={['gap']} />,
+};

package/src/controls/ControlPanel.stories.tsx

@@ -1,4 +1,5 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ANGLE_RADIANS, prefUnit } from '@weasel-js/core';
+import type { Meta, StoryObj } from '@weasel-js/forge';
 import { PropertyRow } from '@weasel-js/ui';
 import { useState } from 'react';
 import { f } from '../config/builder';
@@ -234,3 +235,43 @@ export const Nested: Story = {
     );
   },
 };
+
+const degrees = prefUnit(ANGLE_RADIANS, 'deg', { precision: 1 });
+
+const presentation = f.schema({
+  x: f.number(120).label('X').pair('Offset'),
+  y: f.number(-40).label('Y').pair('Offset'),
+  spin: f
+    .number(Math.PI / 4)
+    .range(0, Math.PI * 2)
+    .unit(degrees)
+    .label('Rotation'),
+  nudge: f
+    .number(Math.PI / 180)
+    .input()
+    .unit(degrees)
+    .label('Nudge'),
+  tint: f.color('#3a86ffcc').alpha().label('Tint'),
+  opaque: f.color('#3a86ff').label('Grid'),
+});
+
+/** The three presentation fields a leaf can declare: `pair` puts `X` and `Y`
+ *  on one row the pair names, `unit` stores radians and edits degrees, and
+ *  `alpha` gives the swatch an opacity track and stores `#rrggbbaa`. The dump
+ *  shows what each control actually wrote. */
+export const Presentation: Story = {
+  render: () => {
+    const schema = resolveConfigSchema(presentation, []);
+    const [config, setConfig] = useState<Record<string, unknown>>(presentation.defaults());
+    return (
+      <>
+        <ControlPanel
+          schema={schema}
+          config={config}
+          setConfig={(path, value) => setConfig((prev) => withValueAtPath(prev, path, value))}
+        />
+        <pre>{JSON.stringify(config, null, 2)}</pre>
+      </>
+    );
+  },
+};