@weasel-js/prefs 1.9.3 → 1.9.4

package/README.md

@@ -18,3 +18,13 @@ repair stored values that no longer fit the schema without writing them back.
 `usePref(store, path)` and `usePrefsValues(store)` bind it to React. They
 live in `@weasel-js/prefs/react`, so the main entry never loads React.
 `usePrefsValues` returns the pieces `@weasel-js/ui`'s `PrefsForm` takes.
+
+## Ranges
+
+A number leaf's range is one scale: the low end is the least of what its label
+names and the high end the most. Do not give zero a second meaning such as
+"no limit" or "automatic" — on a slider it reads as the least, and the form
+draws it there. Put an unlimited setting at the end of the range it is nearest:
+a 0–100% limit is off at 100, and a scale with no such end takes `endless`,
+which adds a stop one step past the range that stores `Infinity` and reads the
+leaf's `infinity` word.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 { P as PrefLeaf, a as PrefGroup, b as PrefSection, c as PrefNumber, d as PrefObject, e as PrefsStore, f as PrefKind } from './store-CNFnA_3c.js';
+export { B as BuiltinPref, g as PREF_KINDS, h as PrefAction, i as PrefActionContext, j as PrefActionControl, k as PrefAlias, l as PrefAtPath, m as PrefBase, n as PrefBoolean, o as PrefBooleanControl, p as PrefBooleanEncoding, q as PrefChange, r as PrefColor, s as PrefCustom, t as PrefEnum, u as PrefEnumBase, v as PrefEnumControl, w as PrefEnumEncoding, x as PrefField, y as PrefGroupAs, z as PrefLabel, A as PrefList, C as PrefMap, D as PrefNumberControl, E as PrefNumberUnit, F as PrefPaint, G as PrefPair, H as PrefPath, I as PrefSectionAs, J as PrefSeparator, K as PrefString, L as PrefStringControl, M as PrefUnion, N as PrefValueAt, O as PrefValueOf, Q as isBuiltinPref, R as pairRowsOf, S as prefAliasTarget, T as prefAliasedLeaf, U as prefGroupIsPage, V as prefUnit, W as prefVariantDefault, X as prefVariantOf } from './store-CNFnA_3c.js';
 import { StorageAdapter, SyncStorageAdapter } from '@weasel-js/storage';
 import '@weasel-js/quantity';
 
@@ -19,20 +19,40 @@ 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. */
@@ -44,11 +64,38 @@ declare function flattenPrefValues(schema: PrefGroup, tree: unknown): [string, u
  *
  * 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. `leafAt` finds that target, and defaults to looking in
+ * `node`; pass one over the whole schema when `node` is a part of it.
+ */
+declare function filterPrefSubtree<T extends PrefLeaf | PrefGroup>(node: T, query: string, path?: string, leafAt?: (path: string) => PrefLeaf | undefined): T | null;
+
+/**
+ * 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 filterPrefSubtree<T extends PrefLeaf | PrefGroup>(node: T, query: string, path?: string): T | null;
+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>;
 
-/** Takes stored records from one version to the next: rename, transform or
- *  delete entries in `records`, keyed by leaf path. */
+/**
+ * `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;
+};
+
+/** Takes stored values from one version to the next: rename, transform or
+ *  delete entries in `records`, keyed by leaf path. It sees the values, not
+ *  the stamps they are stored under, and only those at its own version. */
 type PrefsMigration = (records: Map<string, unknown>) => void;
 
 /** Decides what a stored value reads as for one kind of leaf: the value to
@@ -78,4 +125,29 @@ declare function openPrefsSync<S extends PrefGroup>(schema: S, options: PrefsOpt
     storage: SyncStorageAdapter;
 }): PrefsStore<S>;
 
-export { PrefGroup, PrefLeaf, PrefNumber, type PrefValidator, type PrefsMigration, type PrefsOptions, PrefsStore, VERSION_RECORD, filterPrefSubtree, flattenPrefValues, isPrefLeaf, openPrefs, openPrefsSync, prefDisplayBounds, prefLeaves, prefValueAtPath, repairPrefValue, visiblePrefSubtree };
+/** 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 { PREF_KIND_TRAITS, PrefGroup, PrefKind, type PrefKindTraits, PrefLeaf, PrefNumber, PrefObject, PrefSection, type PrefValidator, type PrefsMigration, type PrefsOptions, PrefsStore, VERSION_RECORD, filterPrefSubtree, flattenPrefValues, isPrefLeaf, isPrefSection, openPrefs, openPrefsSync, prefDisplayBounds, prefDrawsSeveral, prefHoldsValue, prefIsCompound, prefLeafAt, prefLeaves, prefObjectBase, prefObjectWithField, prefSectionLeaves, prefType, prefValueAtPath, repairPrefValue, visiblePrefSubtree };