@weasel-js/labkit 1.4.2 → 1.4.4

package/src/config/resolve.test.ts

@@ -1,3 +1,4 @@
+import type { PrefGroup } from '@weasel-js/ui';
 import { describe, expect, it } from 'vitest';
 import { f } from './builder';
 import { resolveConfigSchema } from './resolve';
@@ -88,8 +89,23 @@ describe('resolveConfigSchema', () => {
       [],
     );
     expect(r.sections).toEqual([
-      { label: 'Two', paths: ['b', 'c'] },
-      { label: 'One', paths: ['a'] },
+      { at: '', label: 'Two', paths: ['b', 'c'] },
+      { at: '', label: 'One', paths: ['a'] },
+    ]);
+  });
+
+  it('takes `collapsed` from any one leaf under the heading', () => {
+    const r = resolveConfigSchema(
+      f.schema({
+        a: f.number(1).section('Advanced'),
+        b: f.number(1).section('Advanced', { collapsed: true }),
+        c: f.number(1).section('Plain'),
+      }),
+      [],
+    );
+    expect(r.sections).toEqual([
+      { at: '', label: 'Advanced', paths: ['a', 'b'], collapsed: true },
+      { at: '', label: 'Plain', paths: ['c'] },
     ]);
   });
 
@@ -117,3 +133,78 @@ describe('resolveConfigSchema', () => {
     expect(Object.keys(r.group.children)).toEqual(['z', 'a']);
   });
 });
+
+describe('resolveConfigSchema / nested groups', () => {
+  const nested = () =>
+    resolveConfigSchema(
+      f.schema({
+        showGrid: f.boolean(true),
+        grid: f
+          .group({
+            size: f.number(20).range(5, 80),
+            color: f.color('#ffffff').showIf((c) => c.showGrid === true),
+          })
+          .label('Grid'),
+      }),
+      [],
+    );
+
+  it('emits a nested PrefGroup, not a flattened child', () => {
+    const r = nested();
+    const grid = r.group.children.grid as PrefGroup;
+    expect('children' in grid).toBe(true);
+    expect(Object.keys(grid.children)).toEqual(['size', 'color']);
+    expect(grid.name).toBe('Grid');
+  });
+
+  it('titleCases a group with no label', () => {
+    const r = resolveConfigSchema(f.schema({ gridStyle: f.group({ a: f.number(1) }) }), []);
+    expect((r.group.children.gridStyle as PrefGroup).name).toBe('Grid style');
+  });
+
+  it('runs the rule chain on a nested leaf, keyed by its own segment', () => {
+    const r = nested();
+    const grid = r.group.children.grid as PrefGroup;
+    const size = grid.children.size as unknown as Record<string, unknown>;
+    expect(size.name).toBe('Size');
+    expect(size.control).toBe('slider');
+  });
+
+  it('gives a rule the full dotted path alongside the key', () => {
+    const seen: { key: string; path: string }[] = [];
+    const spy: ConfigRule = (ctx) => {
+      seen.push({ key: ctx.key, path: ctx.path });
+      return null;
+    };
+    resolveConfigSchema(f.schema({ grid: f.group({ size: f.number(1) }) }), [spy]);
+    expect(seen).toContainEqual({ key: 'size', path: 'grid.size' });
+  });
+
+  it('keys showIf and renderers by the full dotted path', () => {
+    const r = nested();
+    expect(r.showIf.get('grid.color')?.({ showGrid: false })).toBe(false);
+    expect(r.showIf.get('color')).toBeUndefined();
+  });
+
+  it('a section inside a group buckets the children of that group', () => {
+    const r = resolveConfigSchema(
+      f.schema({
+        top: f.number(1).section('Outer'),
+        grid: f.group({ size: f.number(1).section('Inner'), color: f.color('#fff') }),
+      }),
+      [],
+    );
+    expect(r.sections).toEqual([
+      { at: '', label: 'Outer', paths: ['top'] },
+      { at: 'grid', label: 'Inner', paths: ['grid.size'] },
+    ]);
+  });
+
+  it('a group can itself sit under a section heading', () => {
+    const r = resolveConfigSchema(
+      f.schema({ grid: f.group({ size: f.number(1) }).section('Advanced') }),
+      [],
+    );
+    expect(r.sections).toEqual([{ at: '', label: 'Advanced', paths: ['grid'] }]);
+  });
+});

package/src/config/resolve.ts

@@ -1,8 +1,11 @@
 import type { PrefGroup, PrefLeaf } from '@weasel-js/ui';
-import { applyRules, builtinRules } from './rules';
+import { isConfigBranch } from './builder';
+import { applyRules, builtinRules, titleCase } from './rules';
 import type {
+  ConfigEntry,
   ConfigRule,
   ConfigSchema,
+  ConfigShape,
   ControlRenderer,
   LeafPatch,
   ResolvedConfig,
@@ -17,51 +20,91 @@ function defined(annotations: Record<string, unknown>): LeafPatch {
   return out as LeafPatch;
 }
 
+/** What the walk collects on the side of the `PrefGroup` tree. */
+interface Sink {
+  sections: SectionSpec[];
+  showIf: Map<string, (config: Record<string, unknown>) => boolean>;
+  renderers: Record<string, ControlRenderer>;
+  chain: readonly ConfigRule[];
+}
+
 /**
  * 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.
+ * The group mirrors the schema's own nesting: an `f.group` becomes a nested
+ * `PrefGroup`, so a leaf's dotted path within the tree is the path its value
+ * is written at, 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 sink: Sink = {
+    sections: [],
+    showIf: new Map(),
+    renderers: {},
+    chain: [...rules, ...builtinRules],
+  };
+  const group = resolveShape(schema.nodes, '', '', sink);
+  return { group, sections: sink.sections, showIf: sink.showIf, renderers: sink.renderers };
+}
 
-  const chain = [...rules, ...builtinRules];
+/** A section while it is still being filled. */
+type OpenSection = Omit<SectionSpec, 'paths'> & { paths: string[] };
 
-  for (const [key, node] of Object.entries(schema.nodes)) {
-    const seed: LeafPatch = defined({
-      ...node.annotations,
-      ...(node.kind === null ? {} : { kind: node.kind }),
-    });
+function resolveShape(shape: ConfigShape, at: string, name: string, sink: Sink): PrefGroup {
+  const children: Record<string, PrefLeaf | PrefGroup> = {};
+  const sections = new Map<string, OpenSection>();
 
-    const patch = applyRules(seed, { key, path: key, default: node.default }, chain);
-    children[key] = { ...patch, default: node.default } as PrefLeaf;
+  for (const [key, entry] of Object.entries(shape)) {
+    const path = at === '' ? key : `${at}.${key}`;
+    children[key] = resolveEntry(entry, key, path, sink);
 
-    const { section, showIf: predicate, render } = node.options;
+    const { section, showIf: predicate } = entry.options;
     if (section !== undefined) {
-      if (!sectionPaths.has(section)) {
-        sectionOrder.push(section);
-        sectionPaths.set(section, []);
+      let spec = sections.get(section.label);
+      if (!spec) {
+        spec = { at, label: section.label, paths: [] };
+        sections.set(section.label, spec);
+        sink.sections.push(spec);
+      }
+      spec.paths.push(path);
+      // One node saying `collapsed` settles the section, so a schema does not
+      // have to repeat it on every node under the heading.
+      if (section.collapsed !== undefined) {
+        spec.collapsed = (spec.collapsed ?? false) || section.collapsed;
       }
-      sectionPaths.get(section)?.push(key);
     }
-    if (predicate) showIf.set(key, predicate);
-    if (render) renderers[key] = render;
+    if (predicate) sink.showIf.set(path, predicate);
+    if (!isConfigBranch(entry) && entry.options.render) sink.renderers[path] = entry.options.render;
   }
 
-  const group: PrefGroup = { name: '', children };
-  const sections: SectionSpec[] = sectionOrder.map((label) => ({
-    label,
-    paths: sectionPaths.get(label) ?? [],
-  }));
+  return { name, children };
+}
 
-  return { group, sections, showIf, renderers };
+function resolveEntry(
+  entry: ConfigEntry,
+  key: string,
+  path: string,
+  sink: Sink,
+): PrefLeaf | PrefGroup {
+  if (isConfigBranch(entry)) {
+    const group = resolveShape(
+      entry.children,
+      path,
+      entry.annotations.name ?? titleCase(key),
+      sink,
+    );
+    return entry.annotations.description === undefined
+      ? group
+      : { ...group, description: entry.annotations.description };
+  }
+  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;
 }

package/src/config/types.ts

@@ -39,9 +39,11 @@ 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. */
+  /** The leaf's own key — its last path segment, and what a label is titled
+   *  from. */
   key: string;
-  /** Dotted path within the schema. Equal to `key` while schemas are flat. */
+  /** Dotted path within the schema, which is the path the value is written
+   *  at. Equal to `key` for a leaf sitting at the root. */
   path: string;
   /** The leaf's default value. A rule may read it but never change it. */
   default: unknown;
@@ -57,17 +59,29 @@ export interface ConfigRuleContext {
  */
 export type ConfigRule = (ctx: ConfigRuleContext) => LeafPatch | null;
 
-/** A presentational bucket of leaves, rendered under one heading. */
+/** A presentational bucket of nodes, rendered under one heading. Buckets
+ *  siblings: a section never nests a value, which is what separates it from
+ *  `f.group`. */
 export interface SectionSpec {
+  /** Dotted path of the group whose children this buckets. `''` is the root,
+   *  which is where every section of a flat schema sits. */
+  at: string;
   label: string;
+  /** Full dotted paths, so a section under a group names its children the way
+   *  everything else does. */
   paths: readonly string[];
+  /** Whether the section opens folded. Set, the panel folds this section
+   *  whether or not it was given a panel-wide `collapse`; a fold the reader
+   *  has since toggled outranks it. */
+  collapsed?: boolean;
 }
 
 /** 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. */
+  /** The schema as a `PrefGroup` tree: an `f.group` is a nested group, so a
+   *  leaf's dotted path within it is the path its value is written at. */
   group: PrefGroup;
   sections: readonly SectionSpec[];
   showIf: ReadonlyMap<string, (config: Record<string, unknown>) => boolean>;
@@ -75,14 +89,34 @@ export interface ResolvedConfig {
   renderers: Readonly<Record<string, ControlRenderer>>;
 }
 
+/** How a node names the section it belongs to: the heading, and how that
+ *  section opens. Every node in one section repeats the heading; only one of
+ *  them has to say `collapsed`. */
+export interface SectionOption {
+  label: string;
+  collapsed?: boolean;
+}
+
 /** Per-node extras that do not belong on a `PrefLeaf`. */
-export interface NodeOptions {
-  section?: string;
-  showIf?: (config: Record<string, unknown>) => boolean;
+export interface NodeOptions extends BranchOptions {
   render?: ControlRenderer;
   validate?: (leaf: PrefLeaf) => string[];
 }
 
+/** What a branch can say about itself, beyond its children. */
+export interface BranchOptions {
+  section?: SectionOption;
+  /** Show this node only while the predicate holds. On a group it hides the
+   *  whole subtree; the values stay in config either way. */
+  showIf?: (config: Record<string, unknown>) => boolean;
+}
+
+/** A group's own annotations: what it is called and, optionally, why. */
+export interface BranchAnnotations {
+  name?: string;
+  description?: 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> {
@@ -92,15 +126,71 @@ export interface ConfigNode<T = unknown> {
   readonly options: Readonly<NodeOptions>;
 }
 
+/** The builder's branch: named children, nested as deeply as the schema
+ *  wants. A branch nests the value too — `grid: f.group({ size })` puts the
+ *  value at `grid.size`, where `.section('Grid')` would have left it at
+ *  `size`. */
+export interface ConfigBranch<S extends ConfigShape = ConfigShape> {
+  readonly children: S;
+  readonly annotations: Readonly<BranchAnnotations>;
+  readonly options: Readonly<BranchOptions>;
+}
+
+/** Either half of a schema tree. */
+export type ConfigEntry = ConfigNode | ConfigBranch;
+
+/** The children of a schema or a group. */
+export type ConfigShape = { readonly [key: string]: ConfigEntry };
+
 /** The value type a node produces. */
 export type NodeValue<N> = N extends ConfigNode<infer T> ? T : never;
 
+/** The value type a schema entry produces — a leaf's own, or a branch's
+ *  nested record. */
+export type EntryValue<E> =
+  E extends ConfigBranch<infer S> ? InferConfig<S> : E extends ConfigNode<infer T> ? T : never;
+
 /** The config type a builder shape produces. */
-export type InferConfig<S> = { [K in keyof S]: NodeValue<S[K]> };
+export type InferConfig<S> = { [K in keyof S]: EntryValue<S[K]> };
+
+/** Whether a config value has children a path can descend into. Arrays and
+ *  functions are values, not branches. */
+type Branching<V> = V extends readonly unknown[]
+  ? false
+  : V extends (...args: never[]) => unknown
+    ? false
+    : V extends object
+      ? true
+      : false;
+
+/**
+ * Every dotted path a config offers, a group's own path included. A config
+ * whose shape is not known — `unknown`, or a bare record — gives `string`,
+ * which is what keeps a generic instrument writable.
+ */
+export type ConfigPath<T> = unknown extends T
+  ? string
+  : T extends object
+    ? {
+        [K in keyof T & string]: Branching<T[K]> extends true ? K | `${K}.${ConfigPath<T[K]>}` : K;
+      }[keyof T & string]
+    : never;
+
+/** The type at a dotted path, or `unknown` where the path is not one the
+ *  config's type spells out. */
+export type ValueAtPath<T, P extends string> = unknown extends T
+  ? unknown
+  : P extends `${infer Head}.${infer Rest}`
+    ? Head extends keyof T
+      ? ValueAtPath<T[Head], Rest>
+      : unknown
+    : P extends keyof T
+      ? T[P]
+      : unknown;
 
 /** An instrument's config, declared once. */
 export interface ConfigSchema<TC> {
-  readonly nodes: Readonly<Record<string, ConfigNode>>;
+  readonly nodes: ConfigShape;
   /** The starting config — what `defaultConfig()` would have returned. */
   defaults(): TC;
 }

package/src/config/visible.ts

@@ -1,9 +1,11 @@
+import { schemaNodeAtPath } from './path';
 import type { ResolvedConfig } from './types';
 
 /**
- * Whether a leaf's row should be drawn right now.
+ * Whether the row at a dotted path should be drawn right now. A group answers
+ * for its whole subtree — hiding one hides everything under it.
  *
- * `hidden` is the leaf's own static flag; `showIf` is the schema's predicate
+ * `hidden` is the node'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.
  */
@@ -13,8 +15,8 @@ export function isLeafVisible(
   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 node = schemaNodeAtPath(resolved.group, path);
+  if (node && 'hidden' in node && node.hidden === true && !showHidden) return false;
   const predicate = resolved.showIf.get(path);
   return predicate ? predicate(config) : true;
 }

package/src/controls/ControlPanel.stories.tsx

@@ -2,6 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react-vite';
 import { PropertyRow } from '@weasel-js/ui';
 import { useState } from 'react';
 import { f } from '../config/builder';
+import { withValueAtPath } from '../config/path';
 import { resolveConfigSchema } from '../config/resolve';
 import type { ConfigRule, ControlRenderer } from '../config/types';
 import { ControlPanel } from './ControlPanel';
@@ -60,7 +61,7 @@ function Harness({ fields }: { fields: ConfigField[] }) {
     <ControlPanel
       fields={fields}
       config={config}
-      setConfig={(key, value) => setConfig((prev) => ({ ...prev, [key as string]: value }))}
+      setConfig={(path, value) => setConfig((prev) => withValueAtPath(prev, path, value))}
     />
   );
 }
@@ -102,7 +103,7 @@ function SchemaHarness({
     <ControlPanel
       schema={schema}
       config={config}
-      setConfig={(key, value) => setConfig((prev) => ({ ...prev, [key as string]: value }))}
+      setConfig={(path, value) => setConfig((prev) => withValueAtPath(prev, path, value))}
       renderers={renderers}
     />
   );
@@ -169,7 +170,7 @@ export const Described: Story = {
       <ControlPanel
         schema={schema}
         config={config}
-        setConfig={(key, value) => setConfig((prev) => ({ ...prev, [key as string]: value }))}
+        setConfig={(path, value) => setConfig((prev) => withValueAtPath(prev, path, value))}
       />
     );
   },
@@ -195,8 +196,41 @@ export const Conditional: Story = {
       <ControlPanel
         schema={schema}
         config={config}
-        setConfig={(key, value) => setConfig((prev) => ({ ...prev, [key as string]: value }))}
+        setConfig={(path, value) => setConfig((prev) => withValueAtPath(prev, path, value))}
       />
     );
   },
 };
+
+const nested = f.schema({
+  showGrid: f.boolean(true),
+  grid: f
+    .group({
+      size: f.number(20).range(5, 80).step(5).label('Cell size'),
+      color: f.color('#3a86ff'),
+    })
+    .describe('Written at config.grid.size and config.grid.color.'),
+  export: f.group({
+    format: f.enum('png', ['png', 'svg']),
+    scale: f.number(2).range(1, 4).step(1),
+  }),
+});
+
+/** `f.group` nests the value as well as the heading: these rows write to
+ *  `grid.size` and `export.scale`, not to `size` and `scale`. */
+export const Nested: Story = {
+  render: () => {
+    const schema = resolveConfigSchema(nested, []);
+    const [config, setConfig] = useState<Record<string, unknown>>(nested.defaults());
+    return (
+      <>
+        <ControlPanel
+          schema={schema}
+          config={config}
+          setConfig={(path, value) => setConfig((prev) => withValueAtPath(prev, path, value))}
+        />
+        <pre>{JSON.stringify(config, null, 2)}</pre>
+      </>
+    );
+  },
+};

package/src/controls/ControlPanel.test.tsx

@@ -480,4 +480,118 @@ describe('<ControlPanel> collapsible sections', () => {
     expect(onCollapse).toHaveBeenCalledWith('Advanced', false);
     expect(screen.getByLabelText('Seed')).not.toBeVisible();
   });
+
+  describe('a section the schema declares closed', () => {
+    const closedSchema = resolveConfigSchema(
+      f.schema({
+        showGrid: f.boolean(true),
+        seed: f.number(0).section('Advanced', { collapsed: true }),
+      }),
+      [],
+    );
+
+    it('opens folded, and is foldable, with no collapse props at all', () => {
+      render(<ControlPanel schema={closedSchema} config={config} setConfig={vi.fn()} />);
+      expect(screen.getByLabelText('Seed')).not.toBeVisible();
+      fireEvent.click(screen.getByRole('button', { name: 'Advanced' }));
+      expect(screen.getByLabelText('Seed')).toBeVisible();
+    });
+
+    it('yields to a remembered fold, so a toggle the reader made survives', () => {
+      render(
+        <ControlPanel
+          schema={closedSchema}
+          config={config}
+          setConfig={vi.fn()}
+          collapsed={{ Advanced: false }}
+          onCollapse={vi.fn()}
+        />,
+      );
+      expect(screen.getByLabelText('Seed')).toBeVisible();
+    });
+  });
+});
+
+describe('<ControlPanel> nested groups', () => {
+  const nested = () =>
+    resolveConfigSchema(
+      f.schema({
+        showGrid: f.boolean(true),
+        grid: f.group({ size: f.number(20).label('Cell size'), color: f.color('#ffffff') }),
+      }),
+      [],
+    );
+
+  it('renders a nested group under its own heading', () => {
+    render(
+      <ControlPanel
+        schema={nested()}
+        config={{ showGrid: true, grid: { size: 20, color: '#ffffff' } }}
+        setConfig={vi.fn()}
+      />,
+    );
+    const group = screen.getByRole('heading', { name: 'Grid' }).parentElement;
+    expect(group?.textContent).toContain('Cell size');
+  });
+
+  it('reads a nested leaf value out of the config tree', () => {
+    render(
+      <ControlPanel
+        schema={nested()}
+        config={{ showGrid: true, grid: { size: 44, color: '#ffffff' } }}
+        setConfig={vi.fn()}
+      />,
+    );
+    expect((screen.getByLabelText('Cell size') as HTMLInputElement).value).toBe('44');
+  });
+
+  it('falls back to the leaf default when the branch is missing', () => {
+    render(<ControlPanel schema={nested()} config={{ showGrid: true }} setConfig={vi.fn()} />);
+    expect((screen.getByLabelText('Cell size') as HTMLInputElement).value).toBe('20');
+  });
+
+  it('writes back with the full dotted path', () => {
+    const setConfig = vi.fn();
+    render(
+      <ControlPanel
+        schema={nested()}
+        config={{ showGrid: true, grid: { size: 20, color: '#ffffff' } }}
+        setConfig={setConfig}
+      />,
+    );
+    fireEvent.change(screen.getByLabelText('Cell size'), { target: { value: '40' } });
+    expect(setConfig).toHaveBeenCalledWith('grid.size', 40);
+  });
+
+  it('hides a whole group whose showIf is false', () => {
+    const schema = resolveConfigSchema(
+      f.schema({
+        showGrid: f.boolean(true),
+        grid: f.group({ size: f.number(20).label('Cell size') }).showIf((c) => c.showGrid === true),
+      }),
+      [],
+    );
+    render(
+      <ControlPanel
+        schema={schema}
+        config={{ showGrid: false, grid: { size: 20 } }}
+        setConfig={vi.fn()}
+      />,
+    );
+    expect(screen.queryByLabelText('Cell size')).not.toBeInTheDocument();
+    expect(screen.queryByRole('heading', { name: 'Grid' })).not.toBeInTheDocument();
+  });
+
+  it('takes a renderer keyed by the nested path', () => {
+    const schema = nested();
+    render(
+      <ControlPanel
+        schema={schema}
+        config={{ showGrid: true, grid: { size: 44, color: '#ffffff' } }}
+        setConfig={vi.fn()}
+        renderers={{ 'grid.size': (ctx) => <span>size:{String(ctx.value)}</span> }}
+      />,
+    );
+    expect(screen.getByText('size:44')).toBeInTheDocument();
+  });
 });