@weasel-js/prefs 1.9.3 → 1.10.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { P as PrefLeaf, a as PrefGroup, b as PrefNumber, c as PrefsStore } from './store-BU2tRX5H.js';
-export { B as BuiltinPref, d as PREF_KINDS, e as PrefAtPath, f as PrefBase, g as PrefBoolean, h as PrefBooleanControl, i as PrefBooleanEncoding, j as PrefChange, k as PrefColor, l as PrefCustom, m as PrefEnum, n as PrefEnumControl, o as PrefEnumEncoding, p as PrefField, q as PrefKind, r as PrefNumberControl, s as PrefNumberUnit, t as PrefObject, u as PrefPaint, v as PrefPair, w as PrefPath, x as PrefString, y as PrefStringControl, z as PrefValueAt, A as PrefValueOf, C as isBuiltinPref, D as pairRowsOf, E as prefUnit } from './store-BU2tRX5H.js';
-import { StorageAdapter, SyncStorageAdapter } from '@weasel-js/storage';
+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 '@weasel-js/storage';
 import '@weasel-js/quantity';
 
 /**
@@ -19,63 +19,372 @@ declare function prefDisplayBounds(p: PrefNumber): {
     max?: number;
     step: number;
 };
-/** Distinguishes a leaf from a group while walking a schema tree. */
-declare function isPrefLeaf(node: PrefLeaf | PrefGroup): node is PrefLeaf;
+/** 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,
+ *  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. */
+declare function isPrefSection(node: PrefLeaf | PrefGroup | PrefSection): node is PrefSection;
+/**
+ * Every leaf under a section's `members` or an object leaf's `children`, in
+ * schema order, by its own key: the sections between contribute nothing.
+ */
+declare function prefSectionLeaves(members: PrefSection['members']): [key: string, leaf: PrefLeaf][];
+/**
+ * The leaf whose value lives at `path`, as the schema's own shape builds
+ * paths: a segment per key under a {@link PrefGroup}, the leaf's own key
+ * under a {@link PrefSection}. `undefined` for a path that names a group, a
+ * field inside an `object` leaf, or nothing.
+ */
+declare function prefLeafAt(schema: PrefGroup | PrefSection, path: string): PrefLeaf | undefined;
 /** Get the value at a dotted path inside a nested value tree. Returns
  *  `undefined` when a segment is missing or hits a non-object. */
 declare function prefValueAtPath(values: unknown, path: string): unknown;
 /**
- * Recursively drop `hidden` leaves (unless `showHidden`), pruning groups
- * that end up empty. Returns null when the entire subtree is hidden.
+ * Recursively drop `hidden` leaves (unless `showHidden`), an object leaf's
+ * hidden fields among them, pruning groups
+ * that end up empty (unless `keepEmpty`). Returns null when the entire
+ * subtree is pruned.
  */
-declare function visiblePrefSubtree<T extends PrefLeaf | PrefGroup>(node: T, showHidden: boolean): T | null;
+declare function visiblePrefSubtree<T extends PrefLeaf | PrefGroup>(node: T, showHidden: boolean, keepEmpty?: boolean): T | null;
 /** The record holding the schema version the stored values were written at.
  *  Reserved: no top-level schema key may take its name. */
 declare const VERSION_RECORD = "$version";
-/** Every leaf under `schema`, by dotted path, in schema order. */
+/** Every leaf under `schema`, by dotted path, in schema order. A group's key
+ *  is a segment; {@link prefSectionLeaves} is the walk for a section. */
 declare function prefLeaves(schema: PrefGroup): Map<string, PrefLeaf>;
 /** Each of `schema`'s leaves that `tree` holds a value for, as a path and
  *  that value — the inverse of building a tree from per-leaf records. */
 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 — a reader who typed
- * the group's name is asking for the group, not for leaves repeating it.
+ * A group whose own name matches keeps all of its leaves. An empty or
+ * whitespace query matches everything.
  *
- * An empty or whitespace query matches everything, so a cleared field restores
- * the tree rather than emptying it.
+ * An alias answers as the row it draws: its target's name and description
+ * where it gives none. That target is looked for in `over`, and in `node`
+ * without it; pass the whole schema when `node` is a part of it.
  */
-declare function filterPrefSubtree<T extends PrefLeaf | PrefGroup>(node: T, query: string, path?: string): T | null;
+declare function filterPrefSubtree<T extends PrefLeaf | PrefGroup>(node: T, query: string, path?: string, over?: PrefGroup | PrefSection): T | null;
 
-/** Takes stored records from one version to the next: rename, transform or
- *  delete entries in `records`, keyed by leaf path. */
-type PrefsMigration = (records: Map<string, unknown>) => void;
+/** One step of a walk over a group's children: a child on its own, or the neighboring `tab` children that share one strip. */
+type PrefTabRun<T> = {
+    item: T;
+    tabs?: undefined;
+} | {
+    tabs: readonly T[];
+    item?: undefined;
+};
+/**
+ * `items` in order, each run of neighbors `isTab` holds for folded into one step. What a surface leaves out of
+ * `items` neither joins a run nor ends one, and what it keeps and then declines to draw still holds its run together.
+ */
+declare function prefTabRuns<T>(items: readonly T[], isTab: (item: T) => boolean): PrefTabRun<T>[];
 
-/** Decides what a stored value reads as for one kind of leaf: the value to
- *  read, or `undefined` for "invalid, read the default". */
-type PrefValidator = (stored: unknown, leaf: PrefLeaf) => unknown;
-/** What `stored` reads as for `leaf`. Never writes anything back: a schema
- *  rolled back finds the original still in storage. */
-declare function repairPrefValue(leaf: PrefLeaf, stored: unknown, validators?: Readonly<Record<string, PrefValidator>>): unknown;
+/** 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
+ *  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';
+    /** The path read, where the problem is with one. */
+    path?: string;
+    problem: string;
+}
+/** A {@link PrefConditionProblem} and the node whose condition has it. */
+interface PrefSchemaConditionProblem extends PrefConditionProblem {
+    /**
+     * Where the node sits: a key per step from the root, `''` for the root
+     * itself. An object leaf's fields and sections, a union's variants, and a
+     * list's or a map's `item` are steps too, so this is not always a path a
+     * value is read at.
+     */
+    at: string;
+    field: 'showIf' | 'enableIf';
+}
+/** Where the node holding a condition sits, for what a condition alone does not say. */
+interface PrefConditionSite {
+    /** The nearest list or map the node is inside an entry of: the one it is the `item` of, or one above it. */
+    within?: PrefList | PrefMap;
+    /** The condition is the `showIf` of that list's or map's `item` itself. */
+    itemShowIf?: boolean;
+}
+/**
+ * What is wrong with `condition` as one of `schema`'s: every part of it that
+ * is not a condition, every path it reads that no leaf holds a value at,
+ * every comparison against a value the leaf's kind or options rule out, and
+ * every `in` of no values.
+ * `null` is never ruled out, and neither is anything under an app-defined
+ * kind or inside a list, a map, or a paint, which the schema does not
+ * describe. Takes `unknown`, since a schema read from JSON or built without
+ * types may hold anything where a condition goes. `site` says where the
+ * condition's node sits; without it the node is taken to be outside every
+ * list and map. A path read from the entry is held to the `item` of
+ * `site.within`, and is a problem where there is none. `over` is the schema
+ * `schema` is drawn over: a path no leaf of `schema` holds is held to it,
+ * and is a problem only where it holds none either.
+ */
+declare function checkPrefCondition(condition: unknown, schema: PrefGroup | PrefSection, site?: PrefConditionSite, over?: PrefGroup | PrefSection): PrefConditionProblem[];
+/** {@link checkPrefCondition} over every `showIf` and `enableIf` in `schema`, in schema order, each held to `over` as well. */
+declare function checkPrefConditions(schema: PrefGroup | PrefSection, over?: PrefGroup | PrefSection): PrefSchemaConditionProblem[];
 
-/** Options for `openPrefs` and `openPrefsSync`. */
-interface PrefsOptions {
-    storage: StorageAdapter;
-    /** Prepended to every record's key: `'myapp.prefs.'`. */
-    prefix: string;
-    /** `migrations[i]` takes stored records from version `i` to `i + 1`. The
-     *  current version is `migrations.length`. */
-    migrations?: readonly PrefsMigration[];
-    /** Validators for app-defined kinds, keyed by `kind`. One given for a
-     *  built-in kind replaces that kind's own rule. */
-    validators?: Readonly<Record<string, PrefValidator>>;
+/** Which of a node's two conditions a {@link PrefConditionJudge} is asked about. */
+type PrefConditionField = 'showIf' | 'enableIf';
+/**
+ * Says whether one condition holds. {@link prefJudge} makes one from a value
+ * reader; a surface drawing several values at once writes its own, to say
+ * what a condition that holds for some and not for others comes to.
+ */
+type PrefConditionJudge = (condition: PrefCondition, field: PrefConditionField) => boolean;
+/** One entry of a list or a map: the `item` leaf describing it, and what it holds. */
+interface PrefEntry {
+    item: PrefLeaf;
+    value: unknown;
+}
+/**
+ * A judge over one set of values, read by path. A condition compares each
+ * value as the control over its leaf in `schema` shows it
+ * ({@link prefShownReader}), so `read` hands back what is stored. A test
+ * that reads from the entry (`from: 'item'`) reads `entry`, and finds nothing
+ * held where none is given. `over` is the schema `schema` is drawn over: a
+ * path no leaf of `schema` holds is compared as the leaf of `over` there
+ * shows it.
+ */
+declare function prefJudge(schema: PrefGroup | PrefSection, read: (path: string) => unknown, entry?: PrefEntry, over?: PrefGroup | PrefSection): PrefConditionJudge;
+/**
+ * Reads a value by path the way a form over `schema` shows it: what `values`
+ * holds there, else the default of the leaf at that path, or the part of a
+ * leaf's default the rest of the path names. `over` is the schema `schema`
+ * is drawn over: a path no leaf of `schema` holds takes its default there.
+ */
+declare function prefReader(schema: PrefGroup | PrefSection, values: unknown, over?: PrefGroup | PrefSection): (path: string) => unknown;
+
+/** Whether a node is drawn and whether it takes input, with what is above it counted. */
+interface PrefScope {
+    shown: boolean;
+    enabled: boolean;
+}
+/** The step that stands for any entry of a `list` or a `map` in a path: `'phases.*.hold'` answers for that field of
+ *  each, by every condition that comes to the same for every entry. */
+declare const PREF_ENTRY = "*";
+/** The scope a schema's root sits in. */
+declare const PREF_SCOPE: PrefScope;
+/** The scope of `node`, which sits directly under something whose scope is `above`. */
+declare function prefScopeUnder(above: PrefScope, node: {
+    showIf?: PrefCondition;
+    enableIf?: PrefCondition;
+}, holds: PrefConditionJudge): PrefScope;
+/** What {@link prefScopeAt} is told beyond the schema. */
+interface PrefScopeAtOptions {
+    /** The schema an alias's `of` names a leaf of. Default: the schema asked. */
+    aliasOver?: PrefGroup | PrefSection;
+    /** Says which conditions of `aliasOver` hold, where its values are not the ones `holds` reads. Default: `holds`. */
+    aliasHolds?: PrefConditionJudge;
+}
+/**
+ * The scope of the node at `path`: a group, a leaf, a field of an `object`
+ * or a `union` leaf, or an entry of a `list` or a `map`, whose step may be
+ * any key. Under a {@link PrefSection} schema a leaf's key is its whole
+ * path. A path that runs past the schema answers for the last node it
+ * reaches. An alias answers for itself and for the leaf it shows, as
+ * `applyPrefConditions` has it. Inside an entry, a condition that reads the
+ * entry (`from: 'item'`) is not asked and counts as holding, there being no
+ * entry here to read: `applyPrefEntryConditions` answers it.
+ */
+declare function prefScopeAt(schema: PrefGroup | PrefSection, path: string, holds: PrefConditionJudge, { aliasOver, aliasHolds }?: PrefScopeAtOptions): PrefScope;
+
+/** A schema with its conditions applied. */
+interface PrefConditionsApplied<T> {
+    /** The schema without the nodes that are not shown. The schema itself when
+     *  that is all of it, and `null` when its root is not shown. */
+    shown: T | null;
+    /**
+     * The value path of every leaf that is disabled, a field of an `object` or
+     * a `union` leaf included (`'stroke.width'`), and under a {@link PrefGroup}
+     * schema the path of every group that is. A `list`'s or a `map`'s item is
+     * named once for every entry, with {@link PREF_ENTRY} as the entry's step:
+     * `'phases.*'`, and `'phases.*.hold'` for a field of it.
+     */
+    disabled: ReadonlySet<string>;
+    /**
+     * With `keepHidden`, the path of everything `shown` holds that is not
+     * shown, named as `disabled` names what is disabled. Empty without it,
+     * since `shown` then holds none.
+     */
+    hidden: ReadonlySet<string>;
+}
+/** How {@link applyPrefConditions} treats what it would leave out. */
+interface PrefConditionsOptions {
+    /** Keep a group or a section that leaves with nothing to draw. */
+    keepEmpty?: boolean;
+    /**
+     * Keep every node whose `showIf` fails, and name it in `hidden`: for a
+     * surface that edits the schema, where a node not drawn cannot be picked.
+     */
+    keepHidden?: boolean;
+    /** The schema an alias's `of` names a leaf of. Default: the schema walked. */
+    aliasOver?: PrefGroup | PrefSection;
+    /** Says which conditions of `aliasOver` hold, where its values are not the ones `holds` reads. Default: `holds`. */
+    aliasHolds?: PrefConditionJudge;
+}
+/**
+ * `schema` as it is drawn while `holds` says which conditions hold. A node
+ * whose `showIf` fails is dropped with everything under it, unless
+ * `keepHidden`, and so is a group or a section that leaves with nothing to
+ * draw, unless `keepEmpty`. A node
+ * whose `enableIf` fails is disabled with everything under it. The item of
+ * a `list` or a `map` is walked as its entries are drawn: its fields hide and
+ * disable by their conditions, and its own `enableIf` disables every entry.
+ * A condition there that reads the entry (`from: 'item'`) has no one answer
+ * for every entry and is left holding: {@link applyPrefEntryConditions}
+ * answers it for each.
+ * An alias is shown only while it and the leaf it shows both are, and enabled
+ * only while both are, with everything above that leaf counted. That leaf is
+ * looked for in `aliasOver`, and its side is asked of `aliasHolds`.
+ * Parts with nothing dropped come back as the objects they were.
+ */
+declare function applyPrefConditions<T extends PrefGroup | PrefSection>(schema: T, holds: PrefConditionJudge, { keepEmpty, keepHidden, aliasOver, aliasHolds }?: PrefConditionsOptions): PrefConditionsApplied<T>;
+/** One entry of a list or a map with the conditions that read it applied. */
+interface PrefEntryApplied {
+    /** The item as this entry draws it: without the fields not shown, and the item itself when that is all of them. */
+    item: PrefLeaf;
+    /** The path of the entry, and of every field in it, that is disabled, named as {@link PrefConditionsApplied} names them. */
+    disabled: ReadonlySet<string>;
+    /** With `keepHidden`, the path of every field of the entry that is not shown. */
+    hidden: ReadonlySet<string>;
 }
-/** Load every stored value for `schema`, migrate it, and return the store. */
-declare function openPrefs<S extends PrefGroup>(schema: S, options: PrefsOptions): Promise<PrefsStore<S>>;
-/** `openPrefs` for an adapter that reads synchronously: the store is ready
- *  on return, so values can be read before anything renders. */
-declare function openPrefsSync<S extends PrefGroup>(schema: S, options: PrefsOptions & {
-    storage: SyncStorageAdapter;
-}): PrefsStore<S>;
+/**
+ * The conditions {@link applyPrefConditions} leaves unanswered, answered for
+ * one entry: `item`, as that pass left it, drawn for the entry at `path`
+ * (`'phases.2'`) while `holds` says which conditions hold. `holds` reads the
+ * entry: `prefJudge` given it. Only a condition that reads the entry is
+ * asked, the rest being applied already, and one inside a list or a map
+ * within the entry is left for that one's own entries.
+ */
+declare function applyPrefEntryConditions(item: PrefLeaf, path: string, holds: PrefConditionJudge, { keepEmpty, keepHidden }?: Pick<PrefConditionsOptions, 'keepEmpty' | 'keepHidden'>): PrefEntryApplied;
+
+/** What the control over `leaf` shows for `stored`: what its `encoding` reads it as, else `stored` itself.
+ *  `siblings` is the object the leaf is a field of. */
+declare function prefShownValue(leaf: PrefLeaf, stored: unknown, siblings?: Record<string, unknown>): unknown;
+/**
+ * `read` with each value handed back as {@link prefShownValue} gives it, for
+ * the leaf of `schema` at that path, a field of an `object` or a `union` leaf
+ * included. A field's siblings are what `read` finds at its leaf's path. A
+ * path read from the entry is held to `item`, the leaf describing that entry.
+ * A path no leaf of `schema` holds is held to `over`, the schema it is drawn
+ * over.
+ */
+declare function prefShownReader(schema: PrefGroup | PrefSection, read: PrefConditionReader, item?: PrefLeaf, over?: PrefGroup | PrefSection): PrefConditionReader;
+
+/**
+ * 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.
+ * So a path both hold is `schema`'s. Every reader of a condition's paths
+ * that takes a second schema asks here which one to read.
+ */
+declare function prefSchemaHolding(schema: PrefGroup | PrefSection, path: string, over?: PrefGroup | PrefSection): PrefGroup | PrefSection;
+
+/** What an alias row reads of the leaf it shows: the schema that leaf is in, as that schema's own conditions leave it. */
+interface PrefAliasTargets {
+    /** Says which conditions of that schema hold. */
+    holds: PrefConditionJudge;
+    /** The leaf at a path of that schema, without the fields the surface would leave out of the leaf's own row: one
+     *  marked `hidden`, and one a `showIf` hides, unless the surface draws those. */
+    leafAt: (path: string) => PrefLeaf | undefined;
+    /** The leaf `alias` is drawn as, under the alias's own name and description where it gives them, and the path
+     *  its value is read and written at. `undefined` for an alias of nothing. */
+    shown: (alias: PrefAlias) => {
+        path: string;
+        leaf: PrefLeaf;
+    } | undefined;
+    /** Whether the field at a path of that schema is one an `enableIf` disables. */
+    disabledAt: (path: string) => boolean;
+    /** Whether the field at a path of that schema is one a `showIf` hides, on a surface that draws those. */
+    hiddenAt?: (path: string) => boolean;
+    /** An entry of a list or a map of that schema, as the conditions that read the entry leave it. */
+    entryAt: (item: PrefLeaf, path: string, value: unknown) => PrefEntryApplied;
+}
+/** What a surface draws beyond the default, which its alias rows follow. */
+interface PrefAliasTargetsOptions {
+    /** The surface draws fields marked `hidden`. */
+    showHidden?: boolean;
+    /** The surface draws what a `showIf` hides, marked. */
+    markHidden?: boolean;
+}
+/**
+ * {@link PrefAliasTargets} over `over`, the schema a surface's aliases point
+ * into: the surface's own, or another's. `judge` answers `over`'s conditions
+ * as the surface reads values, for one entry of a list or a map where it is
+ * given one: `prefJudge` over `over`. A surface's own pass drops a leaf it
+ * leaves out and keeps no path of another schema, so the leaves aliases show
+ * are conditioned here, the first time one is asked for.
+ */
+declare function prefAliasTargets(over: PrefGroup | PrefSection, judge: (entry?: PrefEntry) => PrefConditionJudge, { showHidden, markHidden }?: PrefAliasTargetsOptions): PrefAliasTargets;
+
+/**
+ * The object a write to one field of an `object` leaf starts from: `held` itself where it is one. Where it is
+ * not, the write has to make a whole object, so it starts from the scalar lifted by the leaf's `fromScalar`, else
+ * from the leaf's `default`: one field on its own is a stroke with a width and no paint.
+ */
+declare function prefObjectBase(pref: PrefObject, held: unknown): Record<string, unknown>;
+/** The object an `object` leaf holds after one of its fields is set: {@link prefObjectBase} with `key` at
+ *  `value`, or without the key for `undefined`. */
+declare function prefObjectWithField(pref: PrefObject, held: unknown, key: string, value: unknown): Record<string, unknown>;
+
+/**
+ * `leaf` as a named type: the same leaf carrying `name` in its `type` field.
+ * Declared once beside the code that reads its value and used wherever a
+ * schema wants one, spread with what that place sets for itself
+ * (`{ ...GradientStop, name: 'First stop' }`), or as a list's or a map's
+ * `item`. `name` is the identifier the type is exported under, which a schema
+ * editor prints in place of the leaf's literal.
+ */
+declare function prefType<L extends PrefLeaf>(name: string, leaf: L): L & {
+    type: string;
+};
+
+/** Neighboring items one row draws, in {@link pairRuns}' answer. */
+interface PairRun<T> {
+    items: T[];
+    /** The pairing the items share: the path of the leaf that declared it, and what the row reads. Absent on a
+     *  run of one, which is no pair. */
+    pair?: {
+        key: string;
+        label: string;
+    };
+}
+/**
+ * `items` as the rows they draw, in order: each leaf a `pair` names joins the row of the leaf naming it where
+ * the two are neighbors, and every other item is a run of its own. `leafOf` gives an item's leaf and the path a
+ * `pair` would name it by, or nothing for an item that shares no row, which ends a run.
+ */
+declare function pairRuns<T>(items: readonly T[], leafOf: (item: T) => readonly [path: string, leaf: PrefLeaf] | undefined): PairRun<T>[];
+
+/** What a surface has to know about a kind before it can lay its control out. */
+interface PrefKindTraits {
+    /** Its value is made of other leaves' values: too much for one control on a
+     *  line, so a bar opens it in a popover and a compact panel in a dialog. */
+    compound: boolean;
+    /** Its control is several controls, or a button. A row drawn as a `<label>`
+     *  would hand a click on its text to the first of them. */
+    several: boolean;
+}
+/**
+ * The traits of every built-in kind. A `Record` over {@link PrefKind}, so a
+ * kind added to the union does not compile until it says what it is here:
+ * a plain set of kind names lets a new one through to draw inline in a
+ * `<label>`, on a bar's line, and with no dialog row.
+ */
+declare const PREF_KIND_TRAITS: Record<PrefKind, PrefKindTraits>;
+/** Whether a leaf's value is made of other leaves' values. An app-defined kind is not: its renderer is one control. */
+declare function prefIsCompound(leaf: {
+    kind: string;
+}): boolean;
+/** Whether a leaf's control is several controls or a button. */
+declare function prefDrawsSeveral(leaf: {
+    kind: string;
+}): boolean;
 
-export { PrefGroup, PrefLeaf, PrefNumber, type PrefValidator, type PrefsMigration, type PrefsOptions, PrefsStore, VERSION_RECORD, filterPrefSubtree, flattenPrefValues, isPrefLeaf, openPrefs, openPrefsSync, prefDisplayBounds, prefLeaves, prefValueAtPath, repairPrefValue, visiblePrefSubtree };
+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 };