@weasel-js/labkit 1.4.2 → 1.4.3

package/src/config/builder.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { f } from './builder';
+import type { ConfigOf, ConfigPath, ValueAtPath } from './types';
 
 describe('builder', () => {
   it('carries kind and default', () => {
@@ -63,7 +64,7 @@ describe('builder', () => {
       .section('Advanced')
       .showIf((c) => c.showGrid === true)
       .render(() => null);
-    expect(n.options.section).toBe('Advanced');
+    expect(n.options.section).toEqual({ label: 'Advanced' });
     expect(n.options.showIf?.({ showGrid: true })).toBe(true);
     expect(n.options.render).toBeTypeOf('function');
     expect(n.annotations).toEqual({});
@@ -91,8 +92,61 @@ describe('builder / node option collisions', () => {
     ];
     for (const node of nodes) {
       expect(typeof node.options).toBe('object');
-      expect(node.section('S').options.section).toBe('S');
+      expect(node.section('S').options.section).toEqual({ label: 'S' });
       expect(node.render(() => null).options.render).toBeTypeOf('function');
     }
   });
 });
+
+describe('builder / groups', () => {
+  it('f.group nests its children under the key', () => {
+    const s = f.schema({
+      showGrid: f.boolean(true),
+      grid: f.group({ size: f.number(20), color: f.color('#fff') }),
+    });
+    expect(s.defaults()).toEqual({
+      showGrid: true,
+      grid: { size: 20, color: '#fff' },
+    });
+  });
+
+  it('nests groups within groups', () => {
+    const s = f.schema({ a: f.group({ b: f.group({ c: f.number(1) }) }) });
+    expect(s.defaults()).toEqual({ a: { b: { c: 1 } } });
+  });
+
+  it('chains a group label and description immutably', () => {
+    const base = f.group({ size: f.number(20) });
+    const a = base.label('Grid').describe('How the grid is drawn');
+    expect(a.annotations.name).toBe('Grid');
+    expect(a.annotations.description).toBe('How the grid is drawn');
+    expect(base.annotations.name).toBeUndefined();
+  });
+
+  it('holds a group section and showIf off the annotation bag', () => {
+    const g = f
+      .group({ size: f.number(20) })
+      .section('Advanced')
+      .showIf((c) => c.showGrid === true);
+    expect(g.options.section).toEqual({ label: 'Advanced' });
+    expect(g.options.showIf?.({ showGrid: true })).toBe(true);
+    expect(g.annotations).toEqual({});
+  });
+});
+
+describe('builder / nested types', () => {
+  // Compile-level: these annotations are the assertion, and tsc is what runs
+  // it. A flat `InferConfig` would not give `c.grid.size` a type at all.
+  it('infers a nested config type and the paths into it', () => {
+    const schema = f.schema({
+      showGrid: f.boolean(true),
+      grid: f.group({ size: f.number(20), color: f.color('#fff') }),
+    });
+    type Config = ConfigOf<typeof schema>;
+    const c: Config = schema.defaults();
+    const size: number = c.grid.size;
+    const path: ConfigPath<Config> = 'grid.size';
+    const value: ValueAtPath<Config, 'grid.size'> = 40;
+    expect([size, path, value]).toEqual([20, 'grid.size', 40]);
+  });
+});

package/src/config/builder.ts

@@ -1,14 +1,24 @@
 import type { PrefLeaf } from '@weasel-js/ui';
 import type {
   Annotations,
+  BranchAnnotations,
+  BranchOptions,
+  ConfigBranch,
+  ConfigEntry,
   ConfigNode,
   ConfigOption,
   ConfigSchema,
+  ConfigShape,
   ControlRenderer,
   InferConfig,
   NodeOptions,
 } from './types';
 
+/** Whether a schema entry is a branch rather than a leaf. */
+export function isConfigBranch(entry: ConfigEntry): entry is ConfigBranch {
+  return 'children' in entry;
+}
+
 /** 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> {
@@ -61,9 +71,10 @@ abstract class BaseNode<T> implements ConfigNode<T> {
     return this.ann({ pair });
   }
 
-  /** Render under a named section heading. */
-  section(section: string): this {
-    return this.opt({ section });
+  /** 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 {
+    return this.opt({ section: { label, ...opts } });
   }
 
   /** Show this row only while the predicate holds. Presentational — the value
@@ -174,6 +185,55 @@ class CustomNode<T> extends BaseNode<T> {
   }
 }
 
+/**
+ * A branch of the schema: its children nest under its key, so a leaf inside
+ * one is read and written at a dotted path. Distinct from `.section()`, which
+ * puts a heading over sibling leaves and leaves their paths alone.
+ */
+class GroupNode<S extends ConfigShape> implements ConfigBranch<S> {
+  constructor(
+    readonly children: S,
+    readonly annotations: Readonly<BranchAnnotations> = {},
+    readonly options: Readonly<BranchOptions> = {},
+  ) {}
+
+  private with(annotations: BranchAnnotations, options: BranchOptions): GroupNode<S> {
+    return new GroupNode(this.children, annotations, options);
+  }
+
+  /** Heading for the group's rows. Defaults to the key, title-cased. */
+  label(name: string): GroupNode<S> {
+    return this.with({ ...this.annotations, name }, this.options);
+  }
+
+  /** Longer help text. Carried on the resolved `PrefGroup`, where weasel-ui's
+   *  `PrefsForm` draws it under the heading; `ControlPanel` has no place for
+   *  it yet and shows the heading alone. */
+  describe(description: string): GroupNode<S> {
+    return this.with({ ...this.annotations, description }, this.options);
+  }
+
+  /** Render this whole group under a named section heading. */
+  section(label: string, opts: { collapsed?: boolean } = {}): GroupNode<S> {
+    return this.with(this.annotations, { ...this.options, section: { label, ...opts } });
+  }
+
+  /** Show this group only while the predicate holds. Presentational — every
+   *  value beneath it stays in config and the instrument still reads it. */
+  showIf(predicate: (config: Record<string, unknown>) => boolean): GroupNode<S> {
+    return this.with(this.annotations, { ...this.options, showIf: predicate });
+  }
+}
+
+/** Every default in a shape, nested the way the shape is. */
+function shapeDefaults(shape: ConfigShape): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(shape)) {
+    out[key] = isConfigBranch(entry) ? shapeDefaults(entry.children) : entry.default;
+  }
+  return out;
+}
+
 const expand = <T extends string>(
   options: readonly T[] | readonly ConfigOption[],
 ): readonly ConfigOption[] =>
@@ -187,6 +247,8 @@ const expand = <T extends string>(
  * const config = f.schema({
  *   showGrid: f.boolean(true),
  *   cellSize: f.number(20).range(5, 80).step(5).label('Grid spacing'),
+ *   // Nested: read and written at `grid.color`.
+ *   grid: f.group({ color: f.color('#ffffff') }),
  * })
  * ```
  */
@@ -208,19 +270,17 @@ export const f = {
    *  states a convention like "every `*Color` key is a color picker". */
   value: <T>(def: T): ValueNode<T> => new ValueNode(def),
 
+  /** A branch: its children nest under this key, so `grid: f.group({ size })`
+   *  puts the value at `config.grid.size` and addresses it as `'grid.size'`.
+   *  Groups nest as deeply as the schema wants. */
+  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 } : {}),
 
-  /** 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>;
-      },
-    };
+  /** Collect leaves and groups into an instrument's config. */
+  schema<S extends ConfigShape>(nodes: S): ConfigSchema<InferConfig<S>> {
+    return { nodes, defaults: () => shapeDefaults(nodes) as InferConfig<S> };
   },
 };

package/src/config/index.ts

@@ -1,22 +1,37 @@
-export { f } from './builder';
+export { f, isConfigBranch } from './builder';
 export { fromConfigFields } from './fromConfigField';
+export {
+  fillConfigDefaults,
+  hasConfigPath,
+  schemaNodeAtPath,
+  valueAtPath,
+  withValueAtPath,
+} from './path';
 export { resolveConfigSchema } from './resolve';
 export { applyRules, builtinRules, titleCase } from './rules';
 export type {
   Annotations,
+  BranchAnnotations,
+  BranchOptions,
+  ConfigBranch,
+  ConfigEntry,
   ConfigNode,
   ConfigOf,
   ConfigOption,
+  ConfigPath,
   ConfigRule,
   ConfigRuleContext,
   ConfigSchema,
+  ConfigShape,
   ControlRenderer,
+  EntryValue,
   InferConfig,
   LeafPatch,
   NodeOptions,
   NodeValue,
   ResolvedConfig,
   SectionSpec,
+  ValueAtPath,
 } from './types';
 export { useConfigSchema } from './useConfigSchema';
 export { isLeafVisible } from './visible';

package/src/config/path.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest';
+import { fillConfigDefaults, hasConfigPath, valueAtPath, withValueAtPath } from './path';
+
+describe('valueAtPath', () => {
+  it('reads a single segment', () => {
+    expect(valueAtPath({ a: 1 }, 'a')).toBe(1);
+  });
+
+  it('reads down a nested path', () => {
+    expect(valueAtPath({ grid: { size: 20 } }, 'grid.size')).toBe(20);
+  });
+
+  it('returns undefined for a missing segment', () => {
+    expect(valueAtPath({ grid: {} }, 'grid.size')).toBeUndefined();
+    expect(valueAtPath({}, 'grid.size')).toBeUndefined();
+  });
+
+  it('returns undefined when the walk hits a non-object', () => {
+    expect(valueAtPath({ grid: 3 }, 'grid.size')).toBeUndefined();
+    expect(valueAtPath(null, 'a')).toBeUndefined();
+  });
+});
+
+describe('hasConfigPath', () => {
+  it('tells a missing key from one holding undefined', () => {
+    expect(hasConfigPath({ a: undefined }, 'a')).toBe(true);
+    expect(hasConfigPath({}, 'a')).toBe(false);
+  });
+
+  it('walks a nested path', () => {
+    expect(hasConfigPath({ grid: { size: 20 } }, 'grid.size')).toBe(true);
+    expect(hasConfigPath({ grid: { size: 20 } }, 'grid.color')).toBe(false);
+    expect(hasConfigPath({ grid: 3 }, 'grid.size')).toBe(false);
+  });
+});
+
+describe('withValueAtPath', () => {
+  it('writes a single segment without touching the input', () => {
+    const before = { a: 1, b: 2 };
+    const after = withValueAtPath(before, 'a', 99);
+    expect(after).toEqual({ a: 99, b: 2 });
+    expect(before).toEqual({ a: 1, b: 2 });
+  });
+
+  it('copies every object on the way down', () => {
+    const before = { grid: { size: 20, color: '#fff' }, other: { keep: true } };
+    const after = withValueAtPath(before, 'grid.size', 40);
+    expect(after.grid).toEqual({ size: 40, color: '#fff' });
+    expect(before.grid.size).toBe(20);
+    expect(after.grid).not.toBe(before.grid);
+    // Untouched branches keep their identity, so a memo keyed on one holds.
+    expect(after.other).toBe(before.other);
+  });
+
+  it('creates a missing intermediate branch', () => {
+    expect(withValueAtPath({} as Record<string, unknown>, 'grid.size', 40)).toEqual({
+      grid: { size: 40 },
+    });
+  });
+
+  it('replaces a non-object standing where a branch belongs', () => {
+    expect(withValueAtPath({ grid: 3 } as Record<string, unknown>, 'grid.size', 40)).toEqual({
+      grid: { size: 40 },
+    });
+  });
+});
+
+describe('fillConfigDefaults', () => {
+  it('takes the stored value wherever it has one', () => {
+    expect(fillConfigDefaults({ a: 1 }, { a: 0, b: 2 })).toEqual({ a: 1, b: 2 });
+  });
+
+  it('fills a whole branch a stored config never had', () => {
+    expect(fillConfigDefaults({ showGrid: false }, { showGrid: true, grid: { size: 20 } })).toEqual(
+      {
+        showGrid: false,
+        grid: { size: 20 },
+      },
+    );
+  });
+
+  it('fills a gap inside a branch the stored config half-holds', () => {
+    expect(
+      fillConfigDefaults({ grid: { size: 40 } }, { grid: { size: 20, color: '#fff' } }),
+    ).toEqual({ grid: { size: 40, color: '#fff' } });
+  });
+
+  it('keeps a key the defaults no longer mention', () => {
+    expect(fillConfigDefaults({ gridSize: 40 }, { grid: { size: 20 } })).toEqual({
+      gridSize: 40,
+      grid: { size: 20 },
+    });
+  });
+
+  it('leaves the stored config untouched', () => {
+    const stored = { grid: { size: 40 } };
+    fillConfigDefaults(stored, { grid: { size: 20, color: '#fff' } });
+    expect(stored).toEqual({ grid: { size: 40 } });
+  });
+
+  it('takes a stored array whole rather than merging it element-wise', () => {
+    expect(fillConfigDefaults({ tags: ['a'] }, { tags: ['x', 'y'] })).toEqual({ tags: ['a'] });
+  });
+
+  it('fills from defaults when the stored config is not a record', () => {
+    expect(fillConfigDefaults(undefined, { a: 1 })).toEqual({ a: 1 });
+    expect(fillConfigDefaults(7, { a: 1 })).toEqual({ a: 1 });
+  });
+});

package/src/config/path.ts

@@ -0,0 +1,76 @@
+import type { PrefGroup, PrefLeaf } from '@weasel-js/ui';
+
+/**
+ * Reading and writing a config tree by dotted path. A schema's leaves address
+ * their values this way, so a leaf nested under `f.group` and a flat one are
+ * reached by exactly the same call.
+ */
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** The value at a dotted path. `undefined` when a segment is missing or the
+ *  walk hits something that is not a record. */
+export function valueAtPath(config: unknown, path: string): unknown {
+  let cur = config;
+  for (const segment of path.split('.')) {
+    if (!isRecord(cur)) return undefined;
+    cur = cur[segment];
+  }
+  return cur;
+}
+
+/** Whether a dotted path is actually present, which a `undefined` value is
+ *  not enough to tell you. */
+export function hasConfigPath(config: unknown, path: string): boolean {
+  let cur = config;
+  for (const segment of path.split('.')) {
+    if (!isRecord(cur) || !(segment in cur)) return false;
+    cur = cur[segment];
+  }
+  return true;
+}
+
+function writeIn(node: unknown, segments: readonly string[], value: unknown): unknown {
+  const [head, ...rest] = segments;
+  if (head === undefined) return value;
+  const base = isRecord(node) ? node : {};
+  return { ...base, [head]: rest.length === 0 ? value : writeIn(base[head], rest, value) };
+}
+
+/** A copy of `config` with `value` written at a dotted path. Every record on
+ *  the way down is copied and the input is left alone; a missing — or
+ *  non-record — intermediate is replaced with the branch the path implies. */
+export function withValueAtPath<T>(config: T, path: string, value: unknown): T {
+  return writeIn(config, path.split('.'), value) as T;
+}
+
+/**
+ * `stored` with every gap filled from `defaults`, down the whole tree.
+ *
+ * This is how a config written before its schema grew a branch still loads:
+ * the branch arrives at its defaults instead of `undefined`, and a key the
+ * defaults no longer mention is kept rather than dropped, so nothing is lost
+ * to a schema change the author has not finished making.
+ */
+export function fillConfigDefaults<T>(stored: unknown, defaults: T): T {
+  if (!isRecord(defaults)) return (stored === undefined ? defaults : stored) as T;
+  const base = isRecord(stored) ? stored : {};
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(defaults)) {
+    out[key] = fillConfigDefaults(base[key], value);
+  }
+  return out as T;
+}
+
+/** A node in a resolved schema tree, by dotted path. Structural rather than
+ *  `isPrefLeaf` so this stays free of a runtime import. */
+export function schemaNodeAtPath(group: PrefGroup, path: string): PrefLeaf | PrefGroup | undefined {
+  let node: PrefLeaf | PrefGroup | undefined = group;
+  for (const segment of path.split('.')) {
+    if (node === undefined || !('children' in node)) return undefined;
+    node = node.children[segment];
+  }
+  return node;
+}

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;
 }