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

package/src/config/builder.ts

@@ -0,0 +1,224 @@
+import type { PrefLeaf } from '@weasel-js/ui';
+import type {
+  Annotations,
+  ConfigNode,
+  ConfigOption,
+  ConfigSchema,
+  ControlRenderer,
+  InferConfig,
+  NodeOptions,
+} from './types';
+
+/** Shared chaining surface. Every method clones, so a node can be reused as a
+ *  base for several leaves without one bleeding into the next. */
+abstract class BaseNode<T> implements ConfigNode<T> {
+  abstract readonly kind: string | null;
+
+  // `default` is a reserved word in a parameter position, so the field is
+  // declared rather than taken as a parameter property.
+  readonly default: T;
+
+  constructor(
+    defaultValue: T,
+    readonly annotations: Readonly<Annotations> = {},
+    readonly options: Readonly<NodeOptions> = {},
+  ) {
+    this.default = defaultValue;
+  }
+
+  /** Clone into the same subclass. Subclasses with extra constructor
+   *  arguments override this. */
+  protected with(annotations: Annotations, options: NodeOptions): this {
+    const Ctor = this.constructor as new (
+      d: T,
+      a: Annotations,
+      o: NodeOptions,
+    ) => this;
+    return new Ctor(this.default, annotations, options);
+  }
+
+  protected ann(patch: Annotations): this {
+    return this.with({ ...this.annotations, ...patch }, this.options);
+  }
+
+  protected opt(patch: NodeOptions): this {
+    return this.with(this.annotations, { ...this.options, ...patch });
+  }
+
+  /** Human-readable label. Defaults to the key, title-cased. */
+  label(name: string): this {
+    return this.ann({ name });
+  }
+
+  /** Longer help text, surfaced as a tooltip on the row label. */
+  describe(description: string): this {
+    return this.ann({ description });
+  }
+
+  /** Omit from the panel unless it is asked to show hidden leaves. */
+  hidden(): this {
+    return this.ann({ hidden: true });
+  }
+
+  /** Pair with a sibling sharing this id, side-by-side on one row. */
+  pair(pair: string): this {
+    return this.ann({ pair });
+  }
+
+  /** Render under a named section heading. */
+  section(section: string): this {
+    return this.opt({ section });
+  }
+
+  /** Show this row only while the predicate holds. Presentational — the value
+   *  stays in config and the instrument still reads it. */
+  showIf(predicate: (config: Record<string, unknown>) => boolean): this {
+    return this.opt({ showIf: predicate });
+  }
+
+  /** Draw this one row yourself, keeping the kind, default and validation. */
+  render(renderer: ControlRenderer): this {
+    return this.opt({ render: renderer });
+  }
+}
+
+class NumberNode extends BaseNode<number> {
+  readonly kind = 'number';
+
+  /** Bound the value. A number with both bounds renders as a slider. */
+  range(min: number, max: number): this {
+    return this.ann({ min, max });
+  }
+
+  step(step: number): this {
+    return this.ann({ step });
+  }
+
+  /** Force a slider even without both bounds. */
+  slider(): this {
+    return this.ann({ control: 'slider' });
+  }
+
+  /** Force a typed input even when both bounds are set. */
+  input(): this {
+    return this.ann({ control: 'input' });
+  }
+}
+
+class BooleanNode extends BaseNode<boolean> {
+  readonly kind = 'boolean';
+
+  /** Ask for a switch. `ControlPanel` still draws a checkbox; weasel-ui's
+   *  `PrefsForm` honors the distinction. */
+  toggle(): this {
+    return this.ann({ control: 'switch' });
+  }
+}
+
+class StringNode extends BaseNode<string> {
+  readonly kind = 'string';
+
+  placeholder(placeholder: string): this {
+    return this.ann({ placeholder });
+  }
+
+  maxLength(maxLength: number): this {
+    return this.ann({ maxLength });
+  }
+
+  /** Milliseconds to debounce live writes. 0 commits every keystroke. */
+  debounce(debounceMs: number): this {
+    return this.ann({ debounceMs });
+  }
+}
+
+class ColorNode extends BaseNode<string> {
+  readonly kind = 'color';
+}
+
+class EnumNode<T extends string> extends BaseNode<T> {
+  readonly kind = 'enum';
+
+  /** Render as a segmented control rather than a select. */
+  radio(): this {
+    return this.ann({ control: 'radio' });
+  }
+
+  /** Relabel the choices. Named `labels` rather than `options` because
+   *  `options` is the node's own extras bag. */
+  labels(options: readonly ConfigOption[]): this {
+    return this.ann({ options });
+  }
+}
+
+/** A leaf whose kind the rule chain decides. */
+class ValueNode<T> extends BaseNode<T> {
+  readonly kind = null;
+}
+
+/** A leaf of a kind labkit does not ship a row for. */
+class CustomNode<T> extends BaseNode<T> {
+  constructor(
+    readonly kind: string,
+    defaultValue: T,
+    annotations: Readonly<Annotations> = {},
+    options: Readonly<NodeOptions> = {},
+  ) {
+    super(defaultValue, annotations, options);
+  }
+
+  protected override with(annotations: Annotations, options: NodeOptions): this {
+    return new CustomNode(this.kind, this.default, annotations, options) as this;
+  }
+}
+
+const expand = <T extends string>(
+  options: readonly T[] | readonly ConfigOption[],
+): readonly ConfigOption[] =>
+  options.map((o) => (typeof o === 'string' ? { value: o, label: o } : o));
+
+/**
+ * Builds an instrument's config: the values, their types, and how each is
+ * edited, in one declaration.
+ *
+ * ```ts
+ * const config = f.schema({
+ *   showGrid: f.boolean(true),
+ *   cellSize: f.number(20).range(5, 80).step(5).label('Grid spacing'),
+ * })
+ * ```
+ */
+export const f = {
+  number: (def: number): NumberNode => new NumberNode(def),
+  boolean: (def: boolean): BooleanNode => new BooleanNode(def),
+  string: (def: string): StringNode => new StringNode(def),
+  color: (def: string): ColorNode => new ColorNode(def),
+
+  /** A fixed set of choices. The default's literal type flows into the config
+   *  type, so `f.enum('fast', ['fast', 'accurate'])` gives
+   *  `'fast' | 'accurate'` with no `as const`. */
+  enum: <const T extends string>(
+    def: T,
+    options: readonly T[] | readonly ConfigOption[],
+  ): EnumNode<T> => new EnumNode<T>(def, { options: expand(options) }),
+
+  /** A leaf with no declared kind: the rule chain decides, which is how a lab
+   *  states a convention like "every `*Color` key is a color picker". */
+  value: <T>(def: T): ValueNode<T> => new ValueNode(def),
+
+  /** 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 } : {}),
+
+  /** Collect leaves into an instrument's config. */
+  schema<S extends Record<string, ConfigNode>>(nodes: S): ConfigSchema<InferConfig<S>> {
+    return {
+      nodes,
+      defaults: () => {
+        const out: Record<string, unknown> = {};
+        for (const [key, node] of Object.entries(nodes)) out[key] = node.default;
+        return out as InferConfig<S>;
+      },
+    };
+  },
+};

package/src/config/fromConfigField.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+import type { ConfigField } from '../controls/types';
+import { fromConfigFields } from './fromConfigField';
+import { isLeafVisible } from './visible';
+
+const leaf = (fields: ConfigField[], k: string) =>
+  fromConfigFields(fields).group.children[k] as unknown as Record<string, unknown>;
+
+describe('fromConfigFields', () => {
+  it('maps every ConfigField type to its PrefLeaf kind', () => {
+    expect(
+      leaf([{ type: 'slider', key: 'a', label: 'A', default: 1, min: 0, max: 2 }], 'a'),
+    ).toMatchObject({
+      kind: 'number',
+      control: 'slider',
+      min: 0,
+      max: 2,
+      default: 1,
+      name: 'A',
+    });
+    expect(leaf([{ type: 'number', key: 'b', label: 'B', default: 1 }], 'b')).toMatchObject({
+      kind: 'number',
+      control: 'input',
+    });
+    expect(leaf([{ type: 'checkbox', key: 'c', label: 'C', default: true }], 'c')).toMatchObject({
+      kind: 'boolean',
+      control: 'checkbox',
+    });
+    expect(
+      leaf(
+        [
+          {
+            type: 'select',
+            key: 'd',
+            label: 'D',
+            default: 'x',
+            options: [{ value: 'x', label: 'X' }],
+          },
+        ],
+        'd',
+      ),
+    ).toMatchObject({ kind: 'enum', options: [{ value: 'x', label: 'X' }] });
+    expect(leaf([{ type: 'text', key: 'e', label: 'E', default: '' }], 'e')).toMatchObject({
+      kind: 'string',
+    });
+    expect(leaf([{ type: 'color', key: 'g', label: 'G', default: '#fff' }], 'g')).toMatchObject({
+      kind: 'color',
+    });
+  });
+
+  it('gives every leaf the description PrefBase requires', () => {
+    expect(leaf([{ type: 'checkbox', key: 'c', label: 'C', default: true }], 'c').description).toBe(
+      '',
+    );
+  });
+
+  it('carries the text debounce through as a labkit extra', () => {
+    expect(
+      leaf([{ type: 'text', key: 'e', label: 'E', default: '', debounceMs: 0 }], 'e').debounceMs,
+    ).toBe(0);
+  });
+
+  it('drops absent optional annotations rather than settling them undefined', () => {
+    expect('min' in leaf([{ type: 'number', key: 'b', label: 'B', default: 1 }], 'b')).toBe(false);
+  });
+
+  it('carries an unrecognized type through as its kind', () => {
+    const odd = { type: 'vector2', key: 'v', label: 'V', default: 0 } as unknown as ConfigField;
+    expect(leaf([odd], 'v').kind).toBe('vector2');
+  });
+
+  it('preserves declaration order', () => {
+    const r = fromConfigFields([
+      { type: 'checkbox', key: 'z', label: 'Z', default: true },
+      { type: 'checkbox', key: 'a', label: 'A', default: true },
+    ]);
+    expect(Object.keys(r.group.children)).toEqual(['z', 'a']);
+  });
+});
+
+describe('isLeafVisible', () => {
+  it('is true for a leaf with no predicate', () => {
+    const r = fromConfigFields([{ type: 'checkbox', key: 'a', label: 'A', default: true }]);
+    expect(isLeafVisible(r, 'a', {})).toBe(true);
+  });
+
+  it('honors a hidden leaf unless asked to show hidden', () => {
+    const r = fromConfigFields([{ type: 'checkbox', key: 'a', label: 'A', default: true }]);
+    (r.group.children.a as unknown as Record<string, unknown>).hidden = true;
+    expect(isLeafVisible(r, 'a', {})).toBe(false);
+    expect(isLeafVisible(r, 'a', {}, true)).toBe(true);
+  });
+});

package/src/config/fromConfigField.ts

@@ -0,0 +1,74 @@
+import type { PrefLeaf } from '@weasel-js/ui';
+import type { ConfigField } from '../controls/types';
+import type { LeafPatch, ResolvedConfig } from './types';
+
+/** One `ConfigField` as the `Pref*` vocabulary spells it. The two describe the
+ *  same thing; `ConfigField` just keys on the control where `PrefLeaf`
+ *  separates the value's kind from how it is presented. */
+function toLeaf(field: ConfigField): LeafPatch {
+  const base = { name: field.label, description: '' };
+  switch (field.type) {
+    case 'slider':
+      return {
+        ...base,
+        kind: 'number',
+        control: 'slider',
+        min: field.min,
+        max: field.max,
+        step: field.step,
+      };
+    case 'number':
+      return {
+        ...base,
+        kind: 'number',
+        control: 'input',
+        min: field.min,
+        max: field.max,
+        step: field.step,
+      };
+    case 'checkbox':
+      return { ...base, kind: 'boolean', control: 'checkbox' };
+    case 'select':
+      return { ...base, kind: 'enum', options: field.options };
+    case 'text':
+      return {
+        ...base,
+        kind: 'string',
+        placeholder: field.placeholder,
+        maxLength: field.maxLength,
+        debounceMs: field.debounceMs,
+      };
+    case 'color':
+      return { ...base, kind: 'color' };
+    default:
+      // A schema can arrive from outside TypeScript. Carry the kind through
+      // so a lab-supplied renderer can still claim it.
+      return { ...base, kind: (field as ConfigField).type };
+  }
+}
+
+/**
+ * Adapt a legacy `configSchema(): ConfigField[]` into the resolved shape, so
+ * both instrument paths reach one renderer.
+ *
+ * Rules do not run here: a hand-written `ConfigField` already states its label
+ * and control, which is everything the rule chain would have inferred.
+ */
+export function fromConfigFields(fields: readonly ConfigField[]): ResolvedConfig {
+  const children: Record<string, PrefLeaf> = {};
+  for (const field of fields) {
+    const patch = toLeaf(field);
+    for (const key of Object.keys(patch)) {
+      if ((patch as Record<string, unknown>)[key] === undefined) {
+        delete (patch as Record<string, unknown>)[key];
+      }
+    }
+    children[field.key] = { ...patch, default: field.default } as PrefLeaf;
+  }
+  return {
+    group: { name: '', children },
+    sections: [],
+    showIf: new Map(),
+    renderers: {},
+  };
+}

package/src/config/index.ts

@@ -0,0 +1,22 @@
+export { f } from './builder';
+export { fromConfigFields } from './fromConfigField';
+export { resolveConfigSchema } from './resolve';
+export { applyRules, builtinRules, titleCase } from './rules';
+export type {
+  Annotations,
+  ConfigNode,
+  ConfigOf,
+  ConfigOption,
+  ConfigRule,
+  ConfigRuleContext,
+  ConfigSchema,
+  ControlRenderer,
+  InferConfig,
+  LeafPatch,
+  NodeOptions,
+  NodeValue,
+  ResolvedConfig,
+  SectionSpec,
+} from './types';
+export { useConfigSchema } from './useConfigSchema';
+export { isLeafVisible } from './visible';

package/src/config/resolve.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from 'vitest';
+import { f } from './builder';
+import { resolveConfigSchema } from './resolve';
+import { titleCase } from './rules';
+import type { ConfigRule } from './types';
+
+const leafAt = (r: ReturnType<typeof resolveConfigSchema>, k: string) =>
+  r.group.children[k] as unknown as Record<string, unknown>;
+
+describe('titleCase', () => {
+  it('splits camelCase without shattering acronyms', () => {
+    expect(titleCase('cellSize')).toBe('Cell size');
+    expect(titleCase('showGrid')).toBe('Show grid');
+    expect(titleCase('useHDR')).toBe('Use hdr');
+    expect(titleCase('seed')).toBe('Seed');
+  });
+});
+
+describe('resolveConfigSchema', () => {
+  it('titleCases a missing label', () => {
+    const r = resolveConfigSchema(f.schema({ cellSize: f.number(20) }), []);
+    expect(leafAt(r, 'cellSize').name).toBe('Cell size');
+  });
+
+  it('an explicit label beats the built-in rule', () => {
+    const r = resolveConfigSchema(f.schema({ cellSize: f.number(20).label('Grid spacing') }), []);
+    expect(leafAt(r, 'cellSize').name).toBe('Grid spacing');
+  });
+
+  it('carries the default through', () => {
+    const r = resolveConfigSchema(f.schema({ cellSize: f.number(20) }), []);
+    expect(leafAt(r, 'cellSize').default).toBe(20);
+  });
+
+  it('picks a slider when a number has both bounds', () => {
+    const r = resolveConfigSchema(f.schema({ a: f.number(1).range(0, 10), b: f.number(1) }), []);
+    expect(leafAt(r, 'a').control).toBe('slider');
+    expect(leafAt(r, 'b').control).toBeUndefined();
+  });
+
+  it('an explicit .input() beats the slider rule', () => {
+    const r = resolveConfigSchema(f.schema({ a: f.number(1).range(0, 10).input() }), []);
+    expect(leafAt(r, 'a').control).toBe('input');
+  });
+
+  it('infers kind from typeof for an f.value leaf', () => {
+    const r = resolveConfigSchema(
+      f.schema({ on: f.value(true), n: f.value(2), s: f.value('x') }),
+      [],
+    );
+    expect(leafAt(r, 'on').kind).toBe('boolean');
+    expect(leafAt(r, 'n').kind).toBe('number');
+    expect(leafAt(r, 's').kind).toBe('string');
+  });
+
+  it('a consumer rule claims an f.value kind before the built-in', () => {
+    const colorByName: ConfigRule = (ctx) =>
+      ctx.key.endsWith('Color') ? { kind: 'color' } : null;
+    const r = resolveConfigSchema(f.schema({ tintColor: f.value('#fff') }), [colorByName]);
+    expect(leafAt(r, 'tintColor').kind).toBe('color');
+  });
+
+  it('a consumer rule cannot overwrite a kind the factory settled', () => {
+    const forceColor: ConfigRule = () => ({ kind: 'color' });
+    const r = resolveConfigSchema(f.schema({ a: f.string('#fff') }), [forceColor]);
+    expect(leafAt(r, 'a').kind).toBe('string');
+  });
+
+  it('a consumer rule cannot overwrite an explicit annotation', () => {
+    const forceLabel: ConfigRule = () => ({ name: 'Forced' });
+    const r = resolveConfigSchema(f.schema({ a: f.number(1).label('Mine') }), [forceLabel]);
+    expect(leafAt(r, 'a').name).toBe('Mine');
+  });
+
+  it('an earlier consumer rule beats a later one', () => {
+    const first: ConfigRule = () => ({ name: 'First' });
+    const second: ConfigRule = () => ({ name: 'Second' });
+    const r = resolveConfigSchema(f.schema({ a: f.number(1) }), [first, second]);
+    expect(leafAt(r, 'a').name).toBe('First');
+  });
+
+  it('collects sections in first-appearance order', () => {
+    const r = resolveConfigSchema(
+      f.schema({
+        b: f.number(1).section('Two'),
+        a: f.number(1).section('One'),
+        c: f.number(1).section('Two'),
+      }),
+      [],
+    );
+    expect(r.sections).toEqual([
+      { label: 'Two', paths: ['b', 'c'] },
+      { label: 'One', paths: ['a'] },
+    ]);
+  });
+
+  it('collects showIf and node renderers by path', () => {
+    const r = resolveConfigSchema(
+      f.schema({
+        showGrid: f.boolean(true),
+        seed: f.value(0).showIf((c) => c.showGrid === true),
+        custom: f.number(1).render(() => null),
+      }),
+      [],
+    );
+    expect(r.showIf.get('seed')?.({ showGrid: false })).toBe(false);
+    expect(r.renderers.custom).toBeTypeOf('function');
+    expect(r.renderers.seed).toBeUndefined();
+  });
+
+  it('every leaf gets a description, since PrefBase requires one', () => {
+    const r = resolveConfigSchema(f.schema({ a: f.number(1) }), []);
+    expect(leafAt(r, 'a').description).toBe('');
+  });
+
+  it('preserves declaration order', () => {
+    const r = resolveConfigSchema(f.schema({ z: f.number(1), a: f.number(1) }), []);
+    expect(Object.keys(r.group.children)).toEqual(['z', 'a']);
+  });
+});

package/src/config/resolve.ts

@@ -0,0 +1,67 @@
+import type { PrefGroup, PrefLeaf } from '@weasel-js/ui';
+import { applyRules, builtinRules } from './rules';
+import type {
+  ConfigRule,
+  ConfigSchema,
+  ControlRenderer,
+  LeafPatch,
+  ResolvedConfig,
+  SectionSpec,
+} from './types';
+
+/** Drop keys whose value is undefined, so an unset annotation stays a gap the
+ *  rule chain can fill rather than a settled `undefined`. */
+function defined(annotations: Record<string, unknown>): LeafPatch {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(annotations)) if (v !== undefined) out[k] = v;
+  return out as LeafPatch;
+}
+
+/**
+ * Resolve a schema into the vocabulary weasel-ui renders, running each leaf
+ * through the consumer's rules and then labkit's own.
+ *
+ * The group is flat — every leaf is a direct child — so a leaf's path is its
+ * config key and both `ControlPanel` and `PrefsForm` address it identically.
+ */
+export function resolveConfigSchema<TC>(
+  schema: ConfigSchema<TC>,
+  rules: readonly ConfigRule[] = [],
+): ResolvedConfig {
+  const children: Record<string, PrefLeaf> = {};
+  const sectionOrder: string[] = [];
+  const sectionPaths = new Map<string, string[]>();
+  const showIf = new Map<string, (config: Record<string, unknown>) => boolean>();
+  const renderers: Record<string, ControlRenderer> = {};
+
+  const chain = [...rules, ...builtinRules];
+
+  for (const [key, node] of Object.entries(schema.nodes)) {
+    const seed: LeafPatch = defined({
+      ...node.annotations,
+      ...(node.kind === null ? {} : { kind: node.kind }),
+    });
+
+    const patch = applyRules(seed, { key, path: key, default: node.default }, chain);
+    children[key] = { ...patch, default: node.default } as PrefLeaf;
+
+    const { section, showIf: predicate, render } = node.options;
+    if (section !== undefined) {
+      if (!sectionPaths.has(section)) {
+        sectionOrder.push(section);
+        sectionPaths.set(section, []);
+      }
+      sectionPaths.get(section)?.push(key);
+    }
+    if (predicate) showIf.set(key, predicate);
+    if (render) renderers[key] = render;
+  }
+
+  const group: PrefGroup = { name: '', children };
+  const sections: SectionSpec[] = sectionOrder.map((label) => ({
+    label,
+    paths: sectionPaths.get(label) ?? [],
+  }));
+
+  return { group, sections, showIf, renderers };
+}

package/src/config/rules.ts

@@ -0,0 +1,68 @@
+import type { ConfigRule, ConfigRuleContext, LeafPatch } from './types';
+
+/** `cellSize` -> `Cell size`. Splits camelCase without shattering acronyms. */
+export function titleCase(key: string): string {
+  const words = key
+    .replace(/[_-]+/g, ' ')
+    .split(/(?<=[a-z0-9])(?=[A-Z])/)
+    .join(' ')
+    .trim()
+    .toLowerCase();
+  return words.length === 0 ? words : words[0].toUpperCase() + words.slice(1);
+}
+
+/** An `f.value` leaf takes its kind from the shape of its default. */
+const kindFromValue: ConfigRule = (ctx) => {
+  const t = typeof ctx.default;
+  if (t === 'boolean' || t === 'number' || t === 'string') return { kind: t };
+  return null;
+};
+
+const labelFromKey: ConfigRule = (ctx) => ({ name: titleCase(ctx.key) });
+
+/** A number bounded on both sides is a slider; one bound or none is an input. */
+const sliderWhenBounded: ConfigRule = (ctx) => {
+  if (ctx.leaf.kind !== 'number') return null;
+  const bounded = ctx.leaf.min !== undefined && ctx.leaf.max !== undefined;
+  return bounded ? { control: 'slider' } : null;
+};
+
+/** `PrefBase.description` is required, so every leaf must end up with one. */
+const descriptionDefault: ConfigRule = () => ({ description: '' });
+
+/**
+ * labkit's own inference, expressed in the same vocabulary a consumer
+ * extends. Runs after the consumer's rules, so a lab always wins.
+ *
+ * If one of these ever needs something a `ConfigRule` cannot express, the
+ * seam is too weak — that is the point of writing them this way.
+ */
+export const builtinRules: readonly ConfigRule[] = [
+  kindFromValue,
+  labelFromKey,
+  sliderWhenBounded,
+  descriptionDefault,
+];
+
+/**
+ * Fold a rule chain into one leaf patch. Gap-filling: a property already
+ * settled is never overwritten, so the accumulator seeded with the author's
+ * annotations beats every rule, and earlier rules beat later ones.
+ */
+export function applyRules(
+  seed: LeafPatch,
+  ctx: Omit<ConfigRuleContext, 'leaf'>,
+  rules: readonly ConfigRule[],
+): LeafPatch {
+  const acc: LeafPatch = { ...seed };
+  for (const rule of rules) {
+    const patch = rule({ ...ctx, leaf: acc });
+    if (patch === null) continue;
+    for (const [k, v] of Object.entries(patch)) {
+      if (v !== undefined && acc[k as keyof LeafPatch] === undefined) {
+        (acc as Record<string, unknown>)[k] = v;
+      }
+    }
+  }
+  return acc;
+}