@weasel-js/prefs 1.10.0 → 1.11.0

package/dist/index.d.ts

@@ -1,7 +1,11 @@
-import { P as PrefLeaf, a as PrefGroup, b as PrefSection, c as PrefNumber, d as PrefList, e as PrefMap, f as PrefCondition, g as PrefConditionReader, h as PrefAlias, i as PrefObject, j as PrefKind } from './open-BEY-aOGe.js';
-export { B as BuiltinPref, k as PREF_KINDS, l as PrefAction, m as PrefActionContext, n as PrefActionControl, o as PrefAtPath, p as PrefBase, q as PrefBoolean, r as PrefBooleanControl, s as PrefBooleanEncoding, t as PrefChange, u as PrefColor, v as PrefConditionValue, w as PrefCustom, x as PrefEnum, y as PrefEnumBase, z as PrefEnumControl, A as PrefEnumEncoding, C as PrefField, D as PrefFunctionUnit, E as PrefGroupAs, F as PrefLabel, G as PrefLinearUnit, H as PrefNumberControl, I as PrefNumberUnit, J as PrefPaint, K as PrefPair, L as PrefPath, M as PrefSectionAs, N as PrefSeparator, O as PrefString, Q as PrefStringControl, R as PrefTest, S as PrefUnion, T as PrefValidator, U as PrefValueAt, V as PrefValueOf, W as PrefsMigration, X as PrefsOptions, Y as PrefsStore, Z as ResolvedPrefUnit, _ as isBuiltinPref, $ as isPrefCondition, a0 as isPrefLinearUnit, a1 as mapPrefConditionPaths, a2 as openPrefs, a3 as openPrefsSync, a4 as pairRowsOf, a5 as prefAliasName, a6 as prefAliasTarget, a7 as prefAliasedLeaf, a8 as prefConditionHolds, a9 as prefConditionPaths, aa as prefConditionReadsItem, ab as prefGroupIsPage, ac as prefIsEnabled, ad as prefIsShown, ae as prefUnit, af as prefVariantDefault, ag as prefVariantOf, ah as repairPrefValue, ai as resolvePrefUnit } from './open-BEY-aOGe.js';
+import { Endless } from '@weasel-js/quantity';
+import { P as PrefLeaf, a as PrefGroup, b as PrefSection, c as PrefNumber, d as PrefList, e as PrefMap, f as PrefCondition, g as PrefConditionReader, h as PrefBoolean, i as PrefString, j as PrefColor, k as PrefEnumBase, l as PrefAction, m as PrefActions, n as PrefLabel, o as PrefSeparator, p as PrefAlias, q as PrefObject, r as PrefKind } from './groups-BDZC-ywb.js';
+export { B as BuiltinPref, s as PREF_KINDS, t as PrefActionContext, u as PrefActionControl, v as PrefBarLead, w as PrefBarOverflow, x as PrefBase, y as PrefBooleanControl, z as PrefBooleanEncoding, A as PrefBoundAt, C as PrefBoundReader, D as PrefConditionValue, E as PrefCustom, F as PrefEnum, G as PrefEnumControl, H as PrefEnumEncoding, I as PrefField, J as PrefFunctionUnit, K as PrefGroupAs, L as PrefLinearUnit, M as PrefLocus, N as PrefNumberBase, O as PrefNumberControl, Q as PrefNumberUnit, R as PrefPaint, S as PrefPair, T as PrefSectionAs, U as PrefSelection, V as PrefStringControl, W as PrefTest, X as PrefUnion, Y as PrefValueBase, Z as PrefWeighted, _ as PrefWeights, $ as ResolvedPrefUnit, a0 as isBuiltinPref, a1 as isPrefCondition, a2 as isPrefLinearUnit, a3 as isPrefLocus, a4 as mapPrefConditionPaths, a5 as pairRowsOf, a6 as prefAliasName, a7 as prefAliasTarget, a8 as prefAliasedLeaf, a9 as prefAsBox, aa as prefClampNumber, ab as prefConditionHolds, ac as prefConditionPaths, ad as prefConditionReadsItem, ae as prefGroupIsPage, af as prefIsEnabled, ag as prefIsShown, ah as prefLocusMember, ai as prefLocusSelectors, aj as prefNumberAt, ak as prefUnit, al as prefUnitAccepts, am as prefVariantDefault, an as prefVariantOf, ao as resolvePrefUnit } from './groups-BDZC-ywb.js';
+export { P as PREF_BLENDS, a as PrefAtPath, b as PrefBlend, c as PrefChange, d as PrefPath, e as PrefValidator, f as PrefValueAt, g as PrefValueOf, h as PrefsMigration, i as PrefsOptions, j as PrefsStore, o as openPrefs, k as openPrefsSync, r as repairPrefValue } from './open-VJ1zlFJz.js';
+import { P as PrefsCssSource, a as PrefsCssOptions } from './css-v-LpmTll.js';
+export { p as prefsCss, b as prefsCssAttributes } from './css-v-LpmTll.js';
+import '@weasel-js/icons';
 import '@weasel-js/storage';
-import '@weasel-js/quantity';
 
 /**
  * A number leaf's bounds in the unit it is displayed in.
@@ -12,16 +16,17 @@ import '@weasel-js/quantity';
  * `max` are points, so they convert the way the value does; `step` is a
  * distance, and a unit with an offset maps zero somewhere else, so converting
  * it as a point would scale it wrong. A decreasing conversion swaps which end
- * is the lower one.
+ * is the lower one, and which end is `endless`.
  */
 declare function prefDisplayBounds(p: PrefNumber): {
     min?: number;
     max?: number;
     step: number;
+    endless?: Endless;
 };
 /** Distinguishes a leaf from a group or a section while walking a schema tree. */
 declare function isPrefLeaf(node: PrefLeaf | PrefGroup | PrefSection): node is PrefLeaf;
-/** Whether a leaf has a value to store: an `action` is a button and holds none, an `alias` shows another leaf's,
+/** Whether a leaf has a value to store: an `action` is a button and holds none, nor does an `actions` run of them, an `alias` shows another leaf's,
  *  and a `label` and a `separator` are text and a rule. */
 declare function prefHoldsValue(leaf: PrefLeaf): boolean;
 /** Distinguishes a section, whose key adds nothing to a path, from a group, whose key is a segment. */
@@ -59,7 +64,7 @@ declare function prefLeaves(schema: PrefGroup): Map<string, PrefLeaf>;
 declare function flattenPrefValues(schema: PrefGroup, tree: unknown): [string, unknown][];
 /**
  * Drop every leaf that does not answer to `query`, pruning groups left empty.
- * A group whose own name matches keeps all of its leaves. An empty or
+ * A group whose own name or tag matches keeps all of its leaves. An empty or
  * whitespace query matches everything.
  *
  * An alias answers as the row it draws: its target's name and description
@@ -82,13 +87,22 @@ type PrefTabRun<T> = {
  */
 declare function prefTabRuns<T>(items: readonly T[], isTab: (item: T) => boolean): PrefTabRun<T>[];
 
+/** The leaves carrying `tag`, themselves or through a group above them, by
+ *  path, in schema order. */
+declare function prefLeavesTagged(schema: PrefGroup | PrefSection, tag: string): Map<string, PrefLeaf>;
+/** The tags the leaf at `path` carries: each group's above it, outermost
+ *  first, then its own. Empty for a path that names no leaf. */
+declare function prefLeafTags(schema: PrefGroup | PrefSection, path: string): readonly string[];
+
 /** One thing wrong with a condition: it is not one, it reads a path no leaf
- *  holds a value at, it compares a leaf against a value it never holds, it
+ *  holds a value at, it compares a leaf against a value it never holds — an
+ *  enum against a string none of its options is being `option`, which a
+ *  surface may take as a test that never matches — it
  *  never holds whatever the leaf does, as an `in` of no values, it is the
  *  `showIf` of a list's or a map's item, which is drawn with each entry, or
  *  it reads from the entry on a node that no list or map draws. */
 interface PrefConditionProblem {
-    code: 'malformed' | 'no-leaf' | 'no-value' | 'value' | 'never' | 'item-show' | 'no-item';
+    code: 'malformed' | 'no-leaf' | 'no-value' | 'value' | 'option' | 'never' | 'item-show' | 'no-item';
     /** The path read, where the problem is with one. */
     path?: string;
     problem: string;
@@ -278,6 +292,69 @@ declare function prefShownValue(leaf: PrefLeaf, stored: unknown, siblings?: Reco
  */
 declare function prefShownReader(schema: PrefGroup | PrefSection, read: PrefConditionReader, item?: PrefLeaf, over?: PrefGroup | PrefSection): PrefConditionReader;
 
+/** One thing wrong with a leaf's `splitBy`. */
+interface PrefSplitProblem {
+    code: 'valueless' | 'no-leaf' | 'not-enum' | 'encoded' | 'clearable' | 'split' | 'twice' | 'default';
+    /** The path of the leaf whose `splitBy` it is. */
+    at: string;
+    /** The entry of `splitBy` the problem is with, where it is with one. */
+    path?: string;
+    problem: string;
+}
+/** Everything wrong with the `splitBy` lists of `schema`'s leaves, in schema order. */
+declare function checkPrefSplits(schema: PrefGroup): PrefSplitProblem[];
+
+/** What a builder takes after the leaf's name and default: any of the leaf's other fields. */
+type Rest<L> = Partial<Omit<L, 'kind' | 'name' | 'default'>>;
+/**
+ * Builders for a preferences schema, each returning what the literal would
+ * hold. `pref.group('View', { grid: pref.boolean('Grid', true) })` is
+ * `{ name: 'View', children: { grid: { kind: 'boolean', name: 'Grid', description: '', default: true } } }`,
+ * and its paths and value types are read from it the same way.
+ */
+declare const pref: {
+    /** A group: `children` nest under its key, which is a segment of their paths. */
+    group<const C extends Record<string, PrefLeaf | PrefGroup>>(name: string, children: C, options?: Omit<PrefGroup, "name" | "children">): Omit<PrefGroup, "children"> & {
+        children: C;
+    };
+    /** A section: a heading over `members`, whose key adds nothing to their paths. */
+    section<const M extends Record<string, PrefLeaf | PrefSection>>(name: string, members: M, options?: Omit<PrefSection, "name" | "members">): Omit<PrefSection, "members"> & {
+        members: M;
+    };
+    number: (name: string, def: number, rest?: Rest<PrefNumber>) => PrefNumber & {
+        default: number;
+    };
+    boolean: (name: string, def: boolean, rest?: Rest<PrefBoolean>) => PrefBoolean;
+    string: (name: string, def: string, rest?: Rest<PrefString>) => PrefString;
+    color: (name: string, def: string, rest?: Rest<PrefColor>) => PrefColor;
+    /** A fixed set of choices. An option given as its value alone is labeled with that value, its first letter raised. */
+    enum<const T extends string>(name: string, def: NoInfer<T>, options: readonly (T | PrefEnumBase<T>["options"][number])[], rest?: Omit<Rest<PrefEnumBase<T>>, "options">): PrefEnumBase<T> & {
+        default: T;
+        clearable?: false;
+    };
+    /** A button firing the registered action `action` (`id` or `id:variant`). Its name defaults to empty, which shows the action's own label. */
+    action: (action: string, rest?: Partial<Omit<PrefAction, "kind" | "default" | "action">>) => PrefAction;
+    /** Every action registered in the action group `group`. */
+    actions: (group: string, rest?: Partial<Omit<PrefActions, "kind" | "default" | "group">>) => PrefActions;
+    label: (name: string, rest?: Rest<PrefLabel>) => PrefLabel;
+    separator: () => PrefSeparator;
+};
+
+/**
+ * A schema's defaults read the way a store at defaults reads them, a split
+ * default by its `defaultLocus` — what `prefsCss` needs to write a schema's
+ * stylesheet with no store and no storage, at build time say.
+ */
+declare function prefsDefaultsSource(schema: PrefGroup): PrefsCssSource;
+
+/**
+ * `prefsCss` names for the kit's own settings: `tree.typeaheadMs` writes as
+ * `--wzl-kit-tree-typeahead-ms`, clear of theme tokens. With `at`, only the
+ * leaves under it are written, each named from below it; a selector outside
+ * `at` keeps its whole path in its attribute name.
+ */
+declare function kitSettingsCssOptions(at?: string): PrefsCssOptions;
+
 /**
  * The schema that answers for the value at `path`: `schema` where a leaf of
  * it describes that value, else `over`, the schema `schema` is drawn over.
@@ -345,6 +422,15 @@ declare function prefType<L extends PrefLeaf>(name: string, leaf: L): L & {
     type: string;
 };
 
+/** Whether a leaf's control fits beside a heading's words: a built-in `boolean`'s or `enum`'s does. */
+declare function prefFitsHeading(leaf: PrefLeaf): boolean;
+/**
+ * The key of the leaf a group or a section draws in its heading: the first
+ * directly in it that is marked `heading` and whose control fits there.
+ * Undefined for a node with no name, which has no heading to draw it in.
+ */
+declare function prefHeadingKey(node: PrefGroup | PrefSection): string | undefined;
+
 /** Neighboring items one row draws, in {@link pairRuns}' answer. */
 interface PairRun<T> {
     items: T[];
@@ -387,4 +473,12 @@ declare function prefDrawsSeveral(leaf: {
     kind: string;
 }): boolean;
 
-export { PREF_ENTRY, PREF_KIND_TRAITS, PREF_SCOPE, type PairRun, PrefAlias, type PrefAliasTargets, type PrefAliasTargetsOptions, PrefCondition, type PrefConditionField, type PrefConditionJudge, type PrefConditionProblem, PrefConditionReader, type PrefConditionSite, type PrefConditionsApplied, type PrefConditionsOptions, type PrefEntry, type PrefEntryApplied, PrefGroup, PrefKind, type PrefKindTraits, PrefLeaf, PrefList, PrefMap, PrefNumber, PrefObject, type PrefSchemaConditionProblem, type PrefScope, type PrefScopeAtOptions, PrefSection, type PrefTabRun, VERSION_RECORD, applyPrefConditions, applyPrefEntryConditions, checkPrefCondition, checkPrefConditions, filterPrefSubtree, flattenPrefValues, isPrefLeaf, isPrefSection, pairRuns, prefAliasTargets, prefDisplayBounds, prefDrawsSeveral, prefHoldsValue, prefIsCompound, prefJudge, prefLeafAt, prefLeaves, prefObjectBase, prefObjectWithField, prefReader, prefSchemaHolding, prefScopeAt, prefScopeUnder, prefSectionLeaves, prefShownReader, prefShownValue, prefTabRuns, prefType, prefValueAtPath, visiblePrefSubtree };
+/**
+ * One group named `name` holding every child of `groups`. Groups at the same
+ * key merge, the first one's own fields kept; a leaf meeting anything at the
+ * same key throws. Composes schemas that each add to the same areas, such as
+ * the kit settings groups that `ui` and `core` both give a `targets` group.
+ */
+declare function mergePrefGroups(name: string, ...groups: readonly PrefGroup[]): PrefGroup;
+
+export { PREF_ENTRY, PREF_KIND_TRAITS, PREF_SCOPE, type PairRun, PrefAction, PrefActions, PrefAlias, type PrefAliasTargets, type PrefAliasTargetsOptions, PrefBoolean, PrefColor, PrefCondition, type PrefConditionField, type PrefConditionJudge, type PrefConditionProblem, PrefConditionReader, type PrefConditionSite, type PrefConditionsApplied, type PrefConditionsOptions, type PrefEntry, type PrefEntryApplied, PrefEnumBase, PrefGroup, PrefKind, type PrefKindTraits, PrefLabel, PrefLeaf, PrefList, PrefMap, PrefNumber, PrefObject, type PrefSchemaConditionProblem, type PrefScope, type PrefScopeAtOptions, PrefSection, PrefSeparator, type PrefSplitProblem, PrefString, type PrefTabRun, PrefsCssOptions, PrefsCssSource, VERSION_RECORD, applyPrefConditions, applyPrefEntryConditions, checkPrefCondition, checkPrefConditions, checkPrefSplits, filterPrefSubtree, flattenPrefValues, isPrefLeaf, isPrefSection, kitSettingsCssOptions, mergePrefGroups, pairRuns, pref, prefAliasTargets, prefDisplayBounds, prefDrawsSeveral, prefFitsHeading, prefHeadingKey, prefHoldsValue, prefIsCompound, prefJudge, prefLeafAt, prefLeafTags, prefLeaves, prefLeavesTagged, prefObjectBase, prefObjectWithField, prefReader, prefSchemaHolding, prefScopeAt, prefScopeUnder, prefSectionLeaves, prefShownReader, prefShownValue, prefTabRuns, prefType, prefValueAtPath, prefsDefaultsSource, visiblePrefSubtree };

package/dist/index.js

@@ -1,5 +1,9 @@
-import { prefLeafHoldingIn, prefLeafHolding, prefSchemaHolding, UNSEEN, prefConditionHolds, prefValueAtPath, isPrefSection, prefSectionLeaves, isPrefLeaf, prefLeafAt, prefAliasTarget, prefAliasedLeaf, pairRowsOf, prefConditionReadsItem, visiblePrefSubtree } from './chunk-5KB3WBJZ.js';
-export { PREF_KINDS, VERSION_RECORD, checkPrefCondition, checkPrefConditions, filterPrefSubtree, flattenPrefValues, isBuiltinPref, isPrefCondition, isPrefLeaf, isPrefLinearUnit, isPrefSection, mapPrefConditionPaths, openPrefs, openPrefsSync, pairRowsOf, prefAliasName, prefAliasTarget, prefAliasedLeaf, prefConditionHolds, prefConditionPaths, prefConditionReadsItem, prefDisplayBounds, prefHoldsValue, prefIsEnabled, prefIsShown, prefLeafAt, prefLeaves, prefSchemaHolding, prefSectionLeaves, prefUnit, prefValueAtPath, prefVariantDefault, prefVariantOf, repairPrefValue, resolvePrefUnit, visiblePrefSubtree } from './chunk-5KB3WBJZ.js';
+import { prefLeafHoldingIn, prefLeafHolding, prefSchemaHolding, UNSEEN, prefConditionHolds, isBuiltinPref, pairRowsOf, prefConditionReadsItem } from './chunk-WN6QQICK.js';
+export { PREF_KINDS, checkPrefCondition, checkPrefConditions, isBuiltinPref, isPrefCondition, kitSettingsCssOptions, mapPrefConditionPaths, openPrefs, openPrefsSync, pairRowsOf, prefConditionHolds, prefConditionPaths, prefConditionReadsItem, prefIsEnabled, prefIsShown, prefSchemaHolding } from './chunk-WN6QQICK.js';
+export { prefsDefaultsSource } from './chunk-ZLXZRX73.js';
+import { prefValueAtPath, isPrefSection, prefSectionLeaves, isPrefLeaf, prefLeafAt, prefAliasTarget, prefAliasedLeaf, visiblePrefSubtree } from './chunk-OZFER7VN.js';
+export { PREF_BLENDS, VERSION_RECORD, checkPrefSplits, filterPrefSubtree, flattenPrefValues, isPrefLeaf, isPrefLinearUnit, isPrefLocus, isPrefSection, prefAliasName, prefAliasTarget, prefAliasedLeaf, prefClampNumber, prefDisplayBounds, prefHoldsValue, prefLeafAt, prefLeaves, memberAt as prefLocusMember, locusSelectors as prefLocusSelectors, prefNumberAt, prefSectionLeaves, prefUnit, prefUnitAccepts, prefValueAtPath, prefVariantDefault, prefVariantOf, prefsCss, prefsCssAttributes, repairPrefValue, resolvePrefUnit, visiblePrefSubtree } from './chunk-OZFER7VN.js';
+import { hasTag } from '@weasel-js/registry';
 
 // src/tabRuns.ts
 function prefTabRuns(items, isTab) {
@@ -17,11 +21,31 @@ function prefTabRuns(items, isTab) {
   }
   return out;
 }
+function taggedLeaves(schema) {
+  const out = [];
+  const walk = (node, prefix, above) => {
+    const section = isPrefSection(node);
+    for (const [key, child] of Object.entries(section ? node.members : node.children)) {
+      const path = section || prefix === "" ? key : `${prefix}.${key}`;
+      const tags = child.tags ? [...above, ...child.tags] : above;
+      if (isPrefLeaf(child)) out.push([path, child, tags]);
+      else walk(child, section ? prefix : path, tags);
+    }
+  };
+  walk(schema, "", schema.tags ?? []);
+  return out;
+}
+function prefLeavesTagged(schema, tag) {
+  return new Map(taggedLeaves(schema).filter(([, , tags]) => hasTag(tags, tag)).map(([path, leaf2]) => [path, leaf2]));
+}
+function prefLeafTags(schema, path) {
+  return taggedLeaves(schema).find(([p]) => p === path)?.[2] ?? [];
+}
 
 // src/shown.ts
-function prefShownValue(leaf, stored, siblings) {
-  if (leaf.kind !== "boolean" && leaf.kind !== "enum") return stored;
-  const { encoding } = leaf;
+function prefShownValue(leaf2, stored, siblings) {
+  if (leaf2.kind !== "boolean" && leaf2.kind !== "enum") return stored;
+  const { encoding } = leaf2;
   return encoding ? encoding.read(stored, siblings) : stored;
 }
 function prefShownReader(schema, read, item, over) {
@@ -55,9 +79,9 @@ function prefReader(schema, values, over) {
     if (held !== void 0) return held;
     if (beyond && prefSchemaHolding(schema, path, over) === over) return beyond(path);
     if (isPrefSection(schema)) {
-      for (const [key, leaf] of prefSectionLeaves(schema.members)) {
-        if (path === key) return leaf.default;
-        if (path.startsWith(`${key}.`)) return prefValueAtPath(leaf.default, path.slice(key.length + 1));
+      for (const [key, leaf2] of prefSectionLeaves(schema.members)) {
+        if (path === key) return leaf2.default;
+        if (path.startsWith(`${key}.`)) return prefValueAtPath(leaf2.default, path.slice(key.length + 1));
       }
       return void 0;
     }
@@ -91,18 +115,18 @@ function scopeAmong(held, rest, above, holds) {
   }
   return void 0;
 }
-function scopeInside(leaf, rest, scope, holds) {
-  if (leaf.kind === "object") return scopeAmong(leaf.children, rest, scope, holds) ?? scope;
-  if (leaf.kind === "list" || leaf.kind === "map") {
-    const { item } = leaf;
+function scopeInside(leaf2, rest, scope, holds) {
+  if (leaf2.kind === "object") return scopeAmong(leaf2.children, rest, scope, holds) ?? scope;
+  if (leaf2.kind === "list" || leaf2.kind === "map") {
+    const { item } = leaf2;
     if (item === void 0) return scope;
     const inItem = deferEntryConditions(holds);
     const entry = prefScopeUnder(scope, { enableIf: item.enableIf }, inItem);
     const dot = rest.indexOf(".");
     return dot < 0 ? entry : scopeInside(item, rest.slice(dot + 1), entry, inItem);
   }
-  if (leaf.kind !== "union") return scope;
-  for (const variant of Object.values(leaf.variants)) {
+  if (leaf2.kind !== "union") return scope;
+  for (const variant of Object.values(leaf2.variants)) {
     const found = scopeAmong(variant.children, rest, scope, holds);
     if (found) return found;
   }
@@ -133,8 +157,8 @@ function prefAliasScope(own, alias, over, holds) {
 }
 function prefScopeAt(schema, path, holds, { aliasOver, aliasHolds } = {}) {
   const own = scopeAt(schema, path, holds);
-  const leaf = prefLeafAt(schema, path);
-  return leaf?.kind === "alias" ? prefAliasScope(own, leaf, aliasOver ?? schema, aliasHolds ?? holds) : own;
+  const leaf2 = prefLeafAt(schema, path);
+  return leaf2?.kind === "alias" ? prefAliasScope(own, leaf2, aliasOver ?? schema, aliasHolds ?? holds) : own;
 }
 
 // src/scope.ts
@@ -142,7 +166,7 @@ var under = (prefix, key) => prefix === "" ? key : `${prefix}.${key}`;
 function leafWalk({ keepEmpty, keepHidden, inItem, aliasOver, aliasHolds }) {
   const disabled = /* @__PURE__ */ new Set();
   const hidden = /* @__PURE__ */ new Set();
-  const leaf = (node, path, above, holds) => {
+  const leaf2 = (node, path, above, holds) => {
     const own = prefScopeUnder(above, node, holds);
     const scope = node.kind === "alias" && aliasOver ? prefAliasScope(own, node, aliasOver, aliasHolds ?? holds) : own;
     return scope.shown || keepHidden ? inside(node, path, scope, holds) : null;
@@ -175,7 +199,7 @@ function leafWalk({ keepEmpty, keepHidden, inItem, aliasOver, aliasHolds }) {
     let changed = false;
     const out = {};
     for (const [key, child] of Object.entries(held)) {
-      const kept = isPrefLeaf(child) ? leaf(child, under(prefix, key), above, holds) : section(child, prefix, above, holds);
+      const kept = isPrefLeaf(child) ? leaf2(child, under(prefix, key), above, holds) : section(child, prefix, above, holds);
       changed ||= kept !== child;
       if (kept !== null) out[key] = kept;
     }
@@ -188,7 +212,7 @@ function leafWalk({ keepEmpty, keepHidden, inItem, aliasOver, aliasHolds }) {
     if (kept === node.members) return node;
     return Object.keys(kept).length === 0 && !keepEmpty ? null : { ...node, members: kept };
   };
-  return { disabled, hidden, leaf, inside, members };
+  return { disabled, hidden, leaf: leaf2, inside, members };
 }
 function applyPrefConditions(schema, holds, { keepEmpty = false, keepHidden = false, aliasOver, aliasHolds } = {}) {
   const walk = leafWalk({ keepEmpty, keepHidden, inItem: deferEntryConditions(holds), aliasOver: aliasOver ?? schema, aliasHolds });
@@ -223,11 +247,40 @@ function applyPrefEntryConditions(item, path, holds, { keepEmpty = false, keepHi
   return { item: walk.inside(item, path, scope, asked), disabled: walk.disabled, hidden: walk.hidden };
 }
 
+// src/build.ts
+var leaf = (kind, name, def, rest) => ({ kind, name, description: "", default: def, ...rest });
+var labeled = (value) => value === "" ? value : value[0].toUpperCase() + value.slice(1);
+var pref = {
+  /** A group: `children` nest under its key, which is a segment of their paths. */
+  group(name, children, options) {
+    return { name, ...options, children };
+  },
+  /** A section: a heading over `members`, whose key adds nothing to their paths. */
+  section(name, members, options) {
+    return { name, ...options, members };
+  },
+  number: (name, def, rest) => leaf("number", name, def, rest),
+  boolean: (name, def, rest) => leaf("boolean", name, def, rest),
+  string: (name, def, rest) => leaf("string", name, def, rest),
+  color: (name, def, rest) => leaf("color", name, def, rest),
+  /** A fixed set of choices. An option given as its value alone is labeled with that value, its first letter raised. */
+  enum(name, def, options, rest) {
+    const full = options.map((option) => typeof option === "string" ? { value: option, label: labeled(option) } : option);
+    return { kind: "enum", name, description: "", default: def, ...rest, options: full };
+  },
+  /** A button firing the registered action `action` (`id` or `id:variant`). Its name defaults to empty, which shows the action's own label. */
+  action: (action, rest) => leaf("action", "", void 0, { action, ...rest }),
+  /** Every action registered in the action group `group`. */
+  actions: (group, rest) => leaf("actions", "", void 0, { group, ...rest }),
+  label: (name, rest) => leaf("label", name, void 0, rest),
+  separator: () => leaf("separator", "", void 0, void 0)
+};
+
 // src/aliasTargets.ts
-function visibleFieldsOf(leaf) {
-  if (leaf.kind !== "object") return leaf;
-  const shown = visiblePrefSubtree({ ...leaf, hidden: false }, false, true);
-  return { ...leaf, children: shown.children };
+function visibleFieldsOf(leaf2) {
+  if (leaf2.kind !== "object") return leaf2;
+  const shown = visiblePrefSubtree({ ...leaf2, hidden: false }, false, true);
+  return { ...leaf2, children: shown.children };
 }
 function prefAliasTargets(over, judge, { showHidden = false, markHidden = false } = {}) {
   const holds = judge();
@@ -235,8 +288,8 @@ function prefAliasTargets(over, judge, { showHidden = false, markHidden = false
   const get = () => applied ??= applyPrefConditions(over, holds, { keepEmpty: true, keepHidden: markHidden });
   const leafAt = (path) => {
     const { shown } = get();
-    const leaf = shown === null ? void 0 : prefLeafAt(shown, path);
-    return leaf === void 0 || showHidden ? leaf : visibleFieldsOf(leaf);
+    const leaf2 = shown === null ? void 0 : prefLeafAt(shown, path);
+    return leaf2 === void 0 || showHidden ? leaf2 : visibleFieldsOf(leaf2);
   };
   return {
     holds,
@@ -253,27 +306,43 @@ function prefAliasTargets(over, judge, { showHidden = false, markHidden = false
 
 // src/object.ts
 var isObject = (v) => typeof v === "object" && v !== null;
-function prefObjectBase(pref, held) {
+function prefObjectBase(pref2, held) {
   if (isObject(held)) return held;
-  return pref.fromScalar?.(held) ?? (isObject(pref.default) ? pref.default : {});
+  return pref2.fromScalar?.(held) ?? (isObject(pref2.default) ? pref2.default : {});
 }
-function prefObjectWithField(pref, held, key, value) {
-  const base = prefObjectBase(pref, held);
+function prefObjectWithField(pref2, held, key, value) {
+  const base = prefObjectBase(pref2, held);
   if (value !== void 0) return { ...base, [key]: value };
   const { [key]: _dropped, ...rest } = base;
   return rest;
 }
 
 // src/type.ts
-function prefType(name, leaf) {
-  return { ...leaf, type: name };
+function prefType(name, leaf2) {
+  return { ...leaf2, type: name };
 }
 
 // src/groups.ts
+function prefAsBox(as) {
+  return as === "panel" || as === "menu";
+}
 function prefGroupIsPage(group) {
   return group.as === void 0 || group.as === "page";
 }
 
+// src/heading.ts
+function prefFitsHeading(leaf2) {
+  return (leaf2.kind === "boolean" || leaf2.kind === "enum") && isBuiltinPref(leaf2);
+}
+function prefHeadingKey(node) {
+  if (node.name === "") return void 0;
+  const held = "members" in node ? node.members : node.children;
+  for (const [key, child] of Object.entries(held)) {
+    if (isPrefLeaf(child) && child.heading === true && prefFitsHeading(child)) return key;
+  }
+  return void 0;
+}
+
 // src/pair.ts
 function pairRuns(items, leafOf) {
   const leaves = items.map(leafOf);
@@ -306,18 +375,41 @@ var PREF_KIND_TRAITS = {
   union: MANY,
   field: ONE,
   action: { compound: false, several: true },
+  actions: { compound: false, several: true },
   alias: ONE,
   label: ONE,
   separator: ONE
 };
-var traitsOf = (leaf) => Object.hasOwn(PREF_KIND_TRAITS, leaf.kind) ? PREF_KIND_TRAITS[leaf.kind] : ONE;
-function prefIsCompound(leaf) {
-  return traitsOf(leaf).compound;
+var traitsOf = (leaf2) => Object.hasOwn(PREF_KIND_TRAITS, leaf2.kind) ? PREF_KIND_TRAITS[leaf2.kind] : ONE;
+function prefIsCompound(leaf2) {
+  return traitsOf(leaf2).compound;
+}
+function prefDrawsSeveral(leaf2) {
+  return traitsOf(leaf2).several;
+}
+
+// src/merge.ts
+function mergeChildren(into, from, at) {
+  for (const [key, child] of Object.entries(from)) {
+    const path = at === "" ? key : `${at}.${key}`;
+    const held = into[key];
+    if (held === void 0) {
+      into[key] = child;
+    } else if (!isPrefLeaf(held) && !isPrefLeaf(child)) {
+      const children = { ...held.children };
+      mergeChildren(children, child.children, path);
+      into[key] = { ...held, children };
+    } else {
+      throw new Error(`mergePrefGroups: two groups give "${path}", and one of them is a leaf`);
+    }
+  }
 }
-function prefDrawsSeveral(leaf) {
-  return traitsOf(leaf).several;
+function mergePrefGroups(name, ...groups) {
+  const children = {};
+  for (const group of groups) mergeChildren(children, group.children, "");
+  return { name, children };
 }
 
-export { PREF_ENTRY, PREF_KIND_TRAITS, PREF_SCOPE, applyPrefConditions, applyPrefEntryConditions, pairRuns, prefAliasTargets, prefDrawsSeveral, prefGroupIsPage, prefIsCompound, prefJudge, prefObjectBase, prefObjectWithField, prefReader, prefScopeAt, prefScopeUnder, prefShownReader, prefShownValue, prefTabRuns, prefType };
+export { PREF_ENTRY, PREF_KIND_TRAITS, PREF_SCOPE, applyPrefConditions, applyPrefEntryConditions, mergePrefGroups, pairRuns, pref, prefAliasTargets, prefAsBox, prefDrawsSeveral, prefFitsHeading, prefGroupIsPage, prefHeadingKey, prefIsCompound, prefJudge, prefLeafTags, prefLeavesTagged, prefObjectBase, prefObjectWithField, prefReader, prefScopeAt, prefScopeUnder, prefShownReader, prefShownValue, prefTabRuns, prefType };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map