@weasel-js/prefs 1.9.4 → 1.10.1

package/dist/{store-CNFnA_3c.d.ts → open-C83pU7Va.d.ts}

@@ -1,4 +1,81 @@
-import { Display, UnitEntry, InfinityText, UnitSystem, Unit } from '@weasel-js/quantity';
+import { StorageAdapter, SyncStorageAdapter } from '@weasel-js/storage';
+import { UnitEntry, UnitSystem, Unit, Display, InfinityText } from '@weasel-js/quantity';
+
+/** What a condition can compare a leaf's value against. `null` stands for
+ *  nothing held: a missing value as well as a stored `null`. */
+type PrefConditionValue = string | number | boolean | null;
+/**
+ * One leaf's value, tested. `path` is the full path the value is read and
+ * written at (`'windows.paging'`), a field of an `object` or `union` leaf
+ * included (`'stroke.width'`, `'fill.type'`). With `from: 'item'` the path is
+ * read from the entry the test's node is drawn in instead: the entry of the
+ * nearest list or map the node is the `item` of, or sits inside the item of.
+ * `{ from: 'item', path: 'mode' }` on a field of a list's item reads `mode`
+ * of the same entry, and an empty path is the entry itself. The value compared is the one
+ * the leaf's control shows, where an `encoding` stores another. With
+ * several operators it holds while all of them do, so
+ * `{ path: 'count', atLeast: 1, below: 10 }` is a range.
+ *
+ * With no operator it holds while the value is set, which by kind is:
+ * a `boolean` that is on; a `number` other than 0; a `string`, a `color`, a
+ * `field`, or an `enum`'s option that is not the empty string; a `paint`
+ * that is not `null`; a `list` with an entry; a `map` with a key; an
+ * `object` or a `union` holding a field. Nothing held is never set, and the
+ * value of an app-defined kind is set by whichever of those its shape is,
+ * else while it is truthy.
+ */
+interface PrefTest {
+    path: string;
+    /** Where `path` is read from: the entry the node is drawn in. Unset: the schema root. */
+    from?: 'item';
+    is?: PrefConditionValue;
+    isNot?: PrefConditionValue;
+    /** Holds while the value is any of these. */
+    in?: readonly PrefConditionValue[];
+    /** The ordering operators hold only for a number. */
+    above?: number;
+    below?: number;
+    atLeast?: number;
+    atMost?: number;
+}
+/** A condition a schema node holds in `showIf` or `enableIf`. An empty `all`
+ *  holds and an empty `any` does not. */
+type PrefCondition = PrefTest | {
+    all: readonly PrefCondition[];
+} | {
+    any: readonly PrefCondition[];
+} | {
+    not: PrefCondition;
+};
+/** Reads the value a test compares: at `path` from the schema root, or with `from`, from the entry being drawn. */
+type PrefConditionReader = (path: string, from?: 'item') => unknown;
+/** Whether `value` is a well-formed condition, all the way down. */
+declare function isPrefCondition(value: unknown): value is PrefCondition;
+/** Whether `condition` holds, given the value `read` finds at each path it names. */
+declare function prefConditionHolds(condition: PrefCondition, read: PrefConditionReader): boolean;
+/** Whether a node is drawn: its `showIf` holds, or it has none. A node
+ *  answers for itself only; one inside a group that is not shown is not
+ *  drawn either. */
+declare function prefIsShown(node: {
+    showIf?: PrefCondition;
+}, read: PrefConditionReader): boolean;
+/** Whether a node's controls take input: its `enableIf` holds, or it has
+ *  none. As {@link prefIsShown}, a node answers for itself only. */
+declare function prefIsEnabled(node: {
+    enableIf?: PrefCondition;
+}, read: PrefConditionReader): boolean;
+/** Every path `condition` reads from the schema root, or with `from`, from the entry, once each, in the order met. */
+declare function prefConditionPaths(condition: PrefCondition, from?: 'item'): string[];
+/** Whether any test of `condition` reads from the entry, so that it has no answer until an entry is drawn. */
+declare function prefConditionReadsItem(condition: PrefCondition): boolean;
+/**
+ * `condition` with every path it reads put through `move`, for following a
+ * key that was renamed or a leaf that moved. `move` is told where a path is
+ * read from, and what it hands back is read from there too. A condition none
+ * of whose paths change comes back as the object it was given, and so does
+ * each part of one.
+ */
+declare function mapPrefConditionPaths(condition: PrefCondition, move: (path: string, from?: 'item') => string): PrefCondition;
 
 /** What a {@link PrefAction}'s `run` is told. */
 interface PrefActionContext {
@@ -52,6 +129,12 @@ declare function prefAliasTarget(alias: PrefAlias, leafAt: (path: string) => Pre
     path: string;
     leaf: PrefLeaf;
 } | undefined;
+/**
+ * What an alias is called wherever one is drawn or named: its own name, else
+ * that of `target`, the leaf it shows, else `Alias` for one that shows
+ * nothing.
+ */
+declare function prefAliasName(alias: PrefAlias, target?: PrefLeaf): string;
 /** A leaf drawn through an alias: the target, under the alias's own name and description where it gives them. */
 declare function prefAliasedLeaf(alias: PrefAlias, target: PrefLeaf): PrefLeaf;
 
@@ -81,6 +164,33 @@ interface PrefList extends PrefBase<'list', readonly unknown[]> {
     maxItems?: number;
 }
 
+/**
+ * A leaf's value split by another leaf: one member for each option of the
+ * `enum` leaf at `$by`. A member may itself be a locus, by a second selector.
+ * The alternatives are folded by weight when the value is read, and a plain
+ * setting of the selector gives one of them all of it.
+ */
+interface PrefLocus {
+    /** The full path of the `enum` leaf whose options key `$of`. */
+    $by: string;
+    $of: Record<string, unknown>;
+}
+/** A value for each selector a read is made under: its path, then the option chosen. */
+type PrefSelection = Readonly<Record<string, string>>;
+/** A weight for each option of each selector, by the selector's path. An option left out weighs nothing. */
+type PrefWeights = Readonly<Record<string, Readonly<Record<string, number>>>>;
+/** One alternative of a split value, and its share of the whole. */
+interface PrefWeighted {
+    value: unknown;
+    weight: number;
+}
+/** Whether `value` is a {@link PrefLocus}: an object of exactly `$by` and `$of`. */
+declare function isPrefLocus(value: unknown): value is PrefLocus;
+/** The one member `selection` names. A selector it leaves out, or an option the locus holds nothing for, reads as `absent`. */
+declare function memberAt(stored: unknown, selection: PrefSelection, absent: unknown): unknown;
+/** The path of every selector `stored` is split by, outermost first. */
+declare function locusSelectors(stored: unknown): Set<string>;
+
 /**
  * A leaf whose value is an object keyed by strings nobody declared, every
  * value described by `item`: the keyed counterpart of a {@link PrefList}.
@@ -110,13 +220,67 @@ declare function prefVariantOf(leaf: PrefUnion, value: unknown): [key: string, v
 /** The value a union takes on switching to the variant at `key`: that variant's default, tagged. */
 declare function prefVariantDefault(leaf: PrefUnion, key: string): Record<string, unknown>;
 
-/** The value types a built-in pref leaf can hold. */
-type PrefKind = 'number' | 'boolean' | 'string' | 'enum' | 'color' | 'paint' | 'object' | 'list' | 'map' | 'union' | 'field' | 'action' | 'alias' | 'label' | 'separator';
+/** What both forms of a unit say about the text around the number. */
+interface PrefUnitText {
+    /** Shown after the input, e.g. `'°'`. */
+    suffix?: string;
+    /** Suffixes a person may type, each mapped to the scale that turns a
+     *  number in that unit into a display number: `{ mm: 0.1, cm: 1 }` for a
+     *  field showing centimeters. A unit that disagrees with the display unit
+     *  about zero carries an `offset` as well. */
+    accepts?: Readonly<Record<string, UnitEntry>>;
+}
 /**
- * Leaves that share one row in a compact property UI (weasel-ui
- * `SelectionPanel`, labkit's `ControlPanel`), declared on the first of them.
- * Purely presentational.
+ * A display unit as data, for a conversion that is linear: `stored = display * scale + offset`, the direction a
+ * `UnitEntry` runs toward its base, so `scale` is what one display unit is worth in stored units. Degrees shown
+ * over radians stored is `{ suffix: '°', scale: Math.PI / 180 }`, and `{ scale: 1 }` changes nothing. Being data,
+ * it is written to JSON, printed in a schema literal, and edited in `PrefSchemaEditor` like any other attribute.
  */
+interface PrefLinearUnit extends PrefUnitText {
+    /** Stored units per display unit. Never 0. */
+    scale: number;
+    /** The stored value a display of 0 stands for. Absent is 0. */
+    offset?: number;
+    /** Decimal places the shown value is rounded to. Absent, the value shows unrounded and formats to two places.
+     *  What is typed is stored unrounded either way: a decimal typed at a decimal `scale` is stored as the
+     *  decimal the two multiply to, without the dust of multiplying them in binary. */
+    precision?: number;
+}
+/** A display unit as code, for a conversion that is not linear. It cannot be written to JSON or edited as data. */
+interface PrefFunctionUnit extends PrefUnitText {
+    toDisplay: (stored: number) => number;
+    fromDisplay: (display: number) => number;
+    /** The stored value as display text, suffix included. */
+    format?: (stored: number) => string;
+}
+/** Display-unit conversion for number leaves whose stored value uses a
+ *  canonical unit the user shouldn't see (e.g. radians stored, degrees
+ *  shown). Read one through {@link resolvePrefUnit}, which answers for both forms. */
+type PrefNumberUnit = PrefLinearUnit | PrefFunctionUnit;
+/** A unit of either form as the functions that convert and format with it. */
+interface ResolvedPrefUnit extends PrefFunctionUnit {
+    format: (stored: number) => string;
+}
+/** Whether `unit` is the data form, and so can be written out and edited. */
+declare function isPrefLinearUnit(unit: PrefNumberUnit): unit is PrefLinearUnit;
+/** How to convert and format with `unit`, whichever form it was written in. */
+declare function resolvePrefUnit(unit: PrefNumberUnit): ResolvedPrefUnit;
+/**
+ * A display unit built from a {@link UnitSystem}: values are stored in the
+ * system's base and shown in `display`, rounded to `precision` places when
+ * given, and every unit in the system is accepted as typed text. `suffix`
+ * defaults to the unit's name and is accepted too. Every unit of a system is
+ * linear, so what comes back is data.
+ */
+declare function prefUnit(system: UnitSystem, display: Unit, opts?: {
+    precision?: number;
+    suffix?: string;
+}): PrefLinearUnit;
+
+/** The value types a built-in pref leaf can hold. */
+type PrefKind = 'number' | 'boolean' | 'string' | 'enum' | 'color' | 'paint' | 'object' | 'list' | 'map' | 'union' | 'field' | 'action' | 'alias' | 'label' | 'separator';
+/** Leaves that share one row in a compact property UI, declared on the first
+ *  of them. Purely presentational. */
 interface PrefPair {
     /** The other leaves on the row, by the full path their values are read and
      *  written at (`'pose.y'`, `'camera.type'`), in order. Each must follow the
@@ -136,6 +300,11 @@ interface PrefBase<K extends string, Value> {
     default: Value;
     /** Hide from a host app's settings UI by default. */
     hidden?: boolean;
+    /** Drawn only while this holds. Presentational: the value stays stored
+     *  and readable while the leaf is not drawn. */
+    showIf?: PrefCondition;
+    /** Drawn, and disabled while this does not hold. */
+    enableIf?: PrefCondition;
     /** Nothing held where this leaf's value is read means `default`, because
      *  whoever reads the value takes it that way (`pose.rotation ?? 0`). A
      *  surface over sparse settings reads every leaf so already. One over a
@@ -147,6 +316,11 @@ interface PrefBase<K extends string, Value> {
      *  (weasel-ui `PrefsForm` honors this for leaves whose control brings
      *  its own chrome). */
     block?: boolean;
+    /** Draw the control in the heading of the group or section holding the
+     *  leaf, in place of a row of its own. Only a built-in `boolean` or `enum`
+     *  fits there (`prefFitsHeading`); any other leaf stays a row. Honored by
+     *  weasel-ui `PrefsForm` and labkit's `ControlPanel`. */
+    heading?: boolean;
     /** Glyph naming this leaf in a host UI's icon set (weasel-ui resolves it
      *  against `ICON_PATHS`). A plain string because this package ships no
      *  icon set and cannot depend on one. Read where a leaf's `name` has nowhere to go — a
@@ -173,6 +347,19 @@ interface PrefBase<K extends string, Value> {
      *  schema editor shows such a leaf as one closed thing and prints the name
      *  in place of its literal. */
     type?: string;
+    /** The `enum` leaves this one's value may be split by, each by the full
+     *  path its value is read at: the value may then be held once per option
+     *  of any of them (a {@link PrefLocus}), which the store folds into the one
+     *  value read. Whether it is split is the stored value's to say. The
+     *  order is the order a value split by several is stored in, the first
+     *  outermost. Each must be a plain `enum`: not `clearable`, with no
+     *  `encoding`, and not split itself. */
+    splitBy?: readonly string[];
+    /** What the leaf holds while nothing is stored for it, where that is a
+     *  split value: a default that differs by option. Split only by entries of
+     *  `splitBy`. `default` stays what a member it leaves out reads as, and
+     *  what the leaf's value type is read from. */
+    defaultLocus?: PrefLocus;
 }
 /** How a schema-driven UI should present a number pref. */
 type PrefNumberControl = 'input' | 'slider';
@@ -182,32 +369,6 @@ type PrefBooleanControl = 'checkbox' | 'switch' | 'toggle';
 type PrefStringControl = 'input' | 'textarea';
 /** How a schema-driven UI should present an enum pref. */
 type PrefEnumControl = 'select' | 'radio' | 'toggle' | 'menu';
-/** Display-unit conversion for number leaves whose stored value uses a
- *  canonical unit the user shouldn't see (e.g. radians stored, degrees
- *  shown). The stored value stays canonical; UIs convert at the edge. */
-interface PrefNumberUnit {
-    toDisplay: (stored: number) => number;
-    fromDisplay: (display: number) => number;
-    /** Shown after the input, e.g. `'°'`. */
-    suffix?: string;
-    /** Suffixes a person may type, each mapped to the scale that turns a
-     *  number in that unit into a display number: `{ mm: 0.1, cm: 1 }` for a
-     *  field showing centimeters. A unit that disagrees with the display unit
-     *  about zero carries an `offset` as well. */
-    accepts?: Readonly<Record<string, UnitEntry>>;
-    /** The stored value as display text, suffix included. */
-    format?: (stored: number) => string;
-}
-/**
- * A display unit built from a {@link UnitSystem}: values are stored in the
- * system's base and shown in `display`, rounded to `precision` places when
- * given, and every unit in the system is accepted as typed text. `suffix`
- * defaults to the unit's name and is accepted too.
- */
-declare function prefUnit(system: UnitSystem, display: Unit, opts?: {
-    precision?: number;
-    suffix?: string;
-}): PrefNumberUnit;
 /** A numeric pref, optionally bounded and stepped, and optionally stored in a
  *  different unit from the one shown. */
 interface PrefNumber extends PrefBase<'number', number> {
@@ -251,8 +412,7 @@ interface PrefString extends PrefBase<'string', string> {
  *
  * A dash array is the case that needs it: `Stroke.dash` stores lengths, and
  * the thing a person chooses is a style. The presets scale by the stroke's
- * width, so both directions are given the object's other fields — a style is
- * meaningless without the width it is a multiple of.
+ * width, so both directions are given the object's other fields.
  */
 interface PrefEnumEncoding<T extends string = string> {
     /**
@@ -315,13 +475,12 @@ interface PrefColor extends PrefBase<'color', string> {
 }
 /**
  * Open leaf: any node with a `kind` outside the built-ins. Schema-driven
- * UIs (weasel-ui `PrefsForm` / `SelectionPanel`) dispatch it to an
- * app-supplied renderer. Deliberately NOT index-signatured so concrete
- * app interfaces stay assignable. Mirrors weasel-ui's `PrefCustom`.
+ * UIs dispatch it to an app-supplied renderer. Deliberately NOT
+ * index-signatured so concrete app interfaces stay assignable.
  */
 type PrefCustom = PrefBase<string, unknown>;
 /**
- * A whole `FillStyle`, not a color inside one. Use it wherever the value is
+ * A whole `Paint`, not a color inside one. Use it wherever the value is
  * the tagged paint union — a solid color, a pattern, a gradient — rather
  * than a hex string.
  *
@@ -336,21 +495,16 @@ interface PrefPaint extends PrefBase<'paint', unknown> {
     alpha?: boolean;
 }
 /**
- * A leaf whose value is one object, with its own fields hanging off it.
- *
- * A compound value — a stroke, a shadow, a pattern spec — could be described
- * as several sibling leaves addressing into it (`data.stroke.width`,
- * `data.stroke.cap`). It shouldn't be: each control would then write one field
- * of a value it can only half see, and writing into something that is not an
- * object yet corrupts it. Here the fields are `children` of one leaf, and
- * every edit commits the parent object whole.
+ * A leaf whose value is one object, with its own fields hanging off it as
+ * `children`; every edit commits the parent object whole. Sibling leaves
+ * addressing into the value (`data.stroke.width`, `data.stroke.cap`) would
+ * each write one field of a value they can only half see, and writing into
+ * something that is not an object yet corrupts it.
  *
  * `children` paths are relative to the object. They are ordinary leaves, so a
  * field that is itself a union (a stroke's `paint`) declares the kind that
  * edits that union. A child may also be a {@link PrefSection}, which
- * organizes the fields under a heading without contributing to the path. A
- * `TextStyle` needs it: its character and paragraph fields belong to one
- * value but read as two lists.
+ * organizes the fields under a heading without contributing to the path.
  */
 interface PrefObject extends PrefBase<'object', unknown> {
     children: Record<string, PrefLeaf | PrefSection>;
@@ -377,8 +531,7 @@ type BuiltinPref = PrefNumber | PrefBoolean | PrefString | PrefEnum | PrefColor
 /**
  * The built-in kinds, as a table. A kind added to {@link PrefKind} is a
  * compile error here, and from here it is one in every renderer's `never`
- * guard — the only thing standing between a new kind and rendering as
- * nothing in four places at once.
+ * guard.
  */
 declare const PREF_KINDS: Record<PrefKind, true>;
 /** Which row each pairing among `leaves` puts a path on: a `key` the row's
@@ -408,6 +561,13 @@ type PrefLeaf = BuiltinPref | PrefCustom;
  * together: one key for their values to nest under, one node to move.
  */
 type PrefGroupAs = 'page' | 'tab' | 'panel' | 'section' | 'fragment' | 'bar';
+/**
+ * What a group or a section drawn `as: 'bar'` does with cells its line has no
+ * room for: `scroll` keeps them all on it, and `menu` opens the ones past its
+ * end from a button there. A bar set to `menu` takes all the room its host
+ * has along the line, which is why it is asked for and not the default.
+ */
+type PrefBarOverflow = 'scroll' | 'menu';
 /** How a {@link PrefSection} is drawn. */
 type PrefSectionAs = Exclude<PrefGroupAs, 'page'>;
 /**
@@ -427,6 +587,14 @@ interface PrefGroup {
     /** How the group is drawn. Unset, its depth decides: a top-level group is a
      *  `page`, and one inside another is a `section`. */
     as?: PrefGroupAs;
+    /** Drawn `as: 'bar'`: what happens to the cells its line has no room for.
+     *  Unset: `scroll`. A surface that takes drops keeps every cell on the line
+     *  whatever this says, so each is there to drop beside. */
+    overflow?: PrefBarOverflow;
+    /** Drawn, with everything under it, only while this holds. */
+    showIf?: PrefCondition;
+    /** Everything under it is disabled while this does not hold. */
+    enableIf?: PrefCondition;
     children: Record<string, PrefLeaf | PrefGroup>;
 }
 /**
@@ -445,11 +613,26 @@ interface PrefSection {
      *  `page`, since nothing that draws sections has a rail. Unset: a heading
      *  over its rows. */
     as?: PrefSectionAs;
+    /** As a {@link PrefGroup}'s. */
+    overflow?: PrefBarOverflow;
+    /** As a {@link PrefGroup}'s. */
+    showIf?: PrefCondition;
+    /** As a {@link PrefGroup}'s. */
+    enableIf?: PrefCondition;
     members: Record<string, PrefLeaf | PrefSection>;
 }
 /** Whether a top-level group gets a page of its own, and not a place on the page of the root's own leaves. */
 declare function prefGroupIsPage(group: PrefGroup): boolean;
 
+/**
+ * Folds a split value's alternatives into the one value read. `members` holds
+ * two or more, each weighing more than nothing, and their weights need not
+ * sum to 1.
+ */
+type PrefBlend = (members: readonly PrefWeighted[], leaf: PrefLeaf) => unknown;
+/** The blends of the built-in kinds that have one. Every other kind takes its heaviest member. */
+declare const PREF_BLENDS: Readonly<Record<string, PrefBlend>>;
+
 type Join<A extends string, B extends string> = A extends '' ? B : `${A}.${B}`;
 /** Every value's dotted path in a `PrefGroup` schema, where a group's key is a
  *  segment; an `object` leaf is one path, its fields are not, and an `action`,
@@ -466,10 +649,12 @@ type PrefPath<G, Prefix extends string = ''> = G extends {
         children: Record<string, unknown>;
     } ? PrefPath<C[K], Join<Prefix, K>> : never;
 }[keyof C & string] : never;
-/** The leaf at `P`. */
+/** The leaf at `P`. `unknown` under a group whose keys are not literal, as a
+ *  schema built at run time has them: nothing says which leaf is there, so
+ *  its value reads as `unknown`. */
 type PrefAtPath<G, P extends string> = G extends {
     children: infer C;
-} ? P extends `${infer H}.${infer Rest}` ? H extends keyof C ? C[H] extends {
+} ? string extends keyof C ? unknown : P extends `${infer H}.${infer Rest}` ? H extends keyof C ? C[H] extends {
     kind: string;
 } ? never : PrefAtPath<C[H], Rest> : never : P extends keyof C ? C[P] extends {
     kind: string;
@@ -528,6 +713,18 @@ type PrefValueOf<L> = L extends {
 /** What the leaf at `P` holds. */
 type PrefValueAt<G, P extends string> = PrefValueOf<PrefAtPath<G, P>>;
 
+/** 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
+ *  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 leaf changing, as a store subscriber hears it: the value readers now
  *  see, and whether this store or another writer made the change. */
 interface PrefChange {
@@ -538,26 +735,59 @@ interface PrefChange {
 /** Values for one schema, held in memory and persisted behind. */
 interface PrefsStore<S extends PrefGroup> {
     readonly schema: S;
-    /** The leaf's value, repaired against the schema; its default when unset. */
-    get<P extends PrefPath<S>>(path: P): PrefValueAt<S, P>;
-    set<P extends PrefPath<S>>(path: P, value: PrefValueAt<S, P>): void;
+    /**
+     * The leaf's value, repaired against the schema; its default when unset. A
+     * split value is folded: under the selectors' own values it is the member
+     * they name, and under `weights` it is the blend its kind makes of the
+     * members that weigh something. A selector `weights` leaves out keeps its
+     * own value.
+     */
+    get<P extends PrefPath<S>>(path: P, read?: {
+        weights?: PrefWeights;
+    }): PrefValueAt<S, P>;
+    /** On a split leaf, writes the member the selectors' own values name, or
+     *  with `at` the one named with each selector there set to the option given.
+     *  A {@link PrefLocus} given as the value replaces the whole of what is held. */
+    set<P extends PrefPath<S>>(path: P, value: PrefValueAt<S, P> | PrefLocus, write?: {
+        at?: PrefSelection;
+    }): void;
+    /** Hold the leaf's value once per option of the selector at `by`, one of
+     *  the leaf's `splitBy`, each option starting as the value it had. */
+    split(path: PrefPath<S>, by: string): void;
+    /** Stop splitting the leaf's value by the selector at `by`, keeping the
+     *  member that selector's own value names. */
+    join(path: PrefPath<S>, by: string): void;
+    /** What the leaf holds where its value is split, each member repaired. */
+    locus(path: PrefPath<S>): PrefLocus | undefined;
+    /** What every split leaf holds, by its path. The same map until something changes. */
+    loci(): ReadonlyMap<string, PrefLocus>;
     /** Unset every leaf at or under `path`; with no path, all. */
     reset(path?: string): void;
     /** Whether the leaf has a value of its own rather than following its default. */
     isSet(path: PrefPath<S>): boolean;
-    /** Every leaf's value as a nested tree. The same object until something changes. */
-    values(): Record<string, unknown>;
+    /** Every leaf's value as a nested tree. The same object until something
+     *  changes. With `at`, the tree as it would read with each selector named
+     *  there set to the option given, built for the call. */
+    values(read?: {
+        at?: PrefSelection;
+    }): Record<string, unknown>;
     /** The leaves following their default. The same set until something changes. */
     unset(): ReadonlySet<string>;
     /** Every stored record as a nested tree, unrepaired, including records no
      *  leaf describes. The same object until something changes. */
     stored(): Record<string, unknown>;
-    /** `changes` is empty when only records no leaf describes changed. */
+    /** `changes` is empty when only records no leaf describes changed. A
+     *  selector changing is a change to every leaf split by it. */
     subscribe(listener: (changes: PrefChange[]) => void): () => void;
     /** False while the store cannot persist: storage has not been read yet, or
      *  was written by a newer schema. Changes still apply for this session, and
-     *  ones made before a late read lands are persisted when it does. */
+     *  ones made before a late read lands are persisted when it does. False for
+     *  good once the store is closed. */
     readonly writable: boolean;
+    /** True once `close` was called. A write after that changes what this store
+     *  reads and reaches neither storage nor its subscribers, and the first one
+     *  warns. */
+    readonly closed: boolean;
     /** Try again now to read storage that could not be read at open, ahead of
      *  the store's own retries. Resolves whether storage has been read. */
     read(): Promise<boolean>;
@@ -569,4 +799,28 @@ interface PrefsStore<S extends PrefGroup> {
     close(): Promise<void>;
 }
 
-export { type PrefList as A, type BuiltinPref as B, type PrefMap as C, type PrefNumberControl as D, type PrefNumberUnit as E, type PrefPaint as F, type PrefPair as G, type PrefPath as H, type PrefSectionAs as I, type PrefSeparator as J, type PrefString as K, type PrefStringControl as L, type PrefUnion as M, type PrefValueAt as N, type PrefValueOf as O, type PrefLeaf as P, isBuiltinPref as Q, pairRowsOf as R, prefAliasTarget as S, prefAliasedLeaf as T, prefGroupIsPage as U, prefUnit as V, prefVariantDefault as W, prefVariantOf as X, type PrefGroup as a, type PrefSection as b, type PrefNumber as c, type PrefObject as d, type PrefsStore as e, type PrefKind as f, PREF_KINDS as g, type PrefAction as h, type PrefActionContext as i, type PrefActionControl as j, type PrefAlias as k, type PrefAtPath as l, type PrefBase as m, type PrefBoolean as n, type PrefBooleanControl as o, type PrefBooleanEncoding as p, type PrefChange as q, type PrefColor as r, type PrefCustom as s, type PrefEnum as t, type PrefEnumBase as u, type PrefEnumControl as v, type PrefEnumEncoding as w, type PrefField as x, type PrefGroupAs as y, type PrefLabel as z };
+/** 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>>;
+    /** How a split value's alternatives fold into one for app-defined kinds,
+     *  keyed by `kind`. One given for a built-in kind replaces that kind's
+     *  own. A kind with none takes its heaviest alternative. */
+    blends?: Readonly<Record<string, PrefBlend>>;
+}
+/** 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>;
+
+export { type PrefWeighted as $, type PrefBooleanEncoding as A, type BuiltinPref as B, type PrefChange as C, type PrefConditionValue as D, type PrefCustom as E, type PrefEnum as F, type PrefEnumControl as G, type PrefEnumEncoding as H, type PrefField as I, type PrefFunctionUnit as J, type PrefGroupAs as K, type PrefLabel as L, type PrefLinearUnit as M, type PrefNumberControl as N, type PrefNumberUnit as O, type PrefLeaf as P, type PrefPaint as Q, type PrefPair as R, type PrefPath as S, type PrefSectionAs as T, type PrefSeparator as U, type PrefStringControl as V, type PrefTest as W, type PrefUnion as X, type PrefValidator as Y, type PrefValueAt as Z, type PrefValueOf as _, type PrefGroup as a, type PrefWeights as a0, type PrefsMigration as a1, type PrefsOptions as a2, type PrefsStore as a3, type ResolvedPrefUnit as a4, isBuiltinPref as a5, isPrefCondition as a6, isPrefLinearUnit as a7, isPrefLocus as a8, mapPrefConditionPaths as a9, openPrefs as aa, openPrefsSync as ab, pairRowsOf as ac, prefAliasName as ad, prefAliasTarget as ae, prefAliasedLeaf as af, prefConditionHolds as ag, prefConditionPaths as ah, prefConditionReadsItem as ai, prefGroupIsPage as aj, prefIsEnabled as ak, prefIsShown as al, memberAt as am, locusSelectors as an, prefUnit as ao, prefVariantDefault as ap, prefVariantOf as aq, repairPrefValue as ar, resolvePrefUnit as as, type PrefSection as b, type PrefNumber as c, type PrefList as d, type PrefMap as e, type PrefCondition as f, type PrefConditionReader as g, type PrefBoolean as h, type PrefString as i, type PrefColor as j, type PrefEnumBase as k, type PrefSelection as l, type PrefLocus as m, type PrefAlias as n, type PrefObject as o, type PrefKind as p, PREF_BLENDS as q, PREF_KINDS as r, type PrefAction as s, type PrefActionContext as t, type PrefActionControl as u, type PrefAtPath as v, type PrefBarOverflow as w, type PrefBase as x, type PrefBlend as y, type PrefBooleanControl as z };

package/dist/react.d.ts

@@ -1,4 +1,5 @@
-import { a as PrefGroup, H as PrefPath, e as PrefsStore, N as PrefValueAt } from './store-CNFnA_3c.js';
+import { a as PrefGroup, S as PrefPath, a3 as PrefsStore, Z as PrefValueAt, m as PrefLocus, l as PrefSelection, a2 as PrefsOptions } from './open-C83pU7Va.js';
+import { SyncStorageAdapter } from '@weasel-js/storage';
 import '@weasel-js/quantity';
 
 /** One leaf of `store`, as React state. */
@@ -7,14 +8,42 @@ declare function usePref<S extends PrefGroup, P extends PrefPath<S>>(store: Pref
     (next: PrefValueAt<S, P> | ((prev: PrefValueAt<S, P>) => PrefValueAt<S, P>)) => void
 ];
 /** The whole of `store` as React state, shaped for `PrefsForm`: `values`,
- *  `onChange={set}`, `auto={unset}`, and `reset` for `onAutoChange`. `stored`
- *  is `store.stored()`. */
+ *  `onChange={set}`, `auto={unset}`, and `reset` for `onAutoChange`; for its
+ *  split values, `loci`, `onSplit={split}`, `onJoin={join}`, and
+ *  `onChangeAt={setAt}`. `stored` is `store.stored()`. */
 declare function usePrefsValues<S extends PrefGroup>(store: PrefsStore<S>): {
     values: Record<string, unknown>;
     set: (path: string, value: unknown) => void;
     unset: ReadonlySet<string>;
     stored: Record<string, unknown>;
     reset: (path?: string) => void;
+    loci: ReadonlyMap<string, PrefLocus>;
+    split: (path: string, by: string) => void;
+    join: (path: string, by: string) => void;
+    setAt: (path: string, value: unknown, at: PrefSelection) => void;
 };
 
-export { usePref, usePrefsValues };
+type SyncOptions = PrefsOptions & {
+    storage: SyncStorageAdapter;
+};
+/**
+ * A store for `schema`, open while the component is mounted: opened during
+ * the first render, so that render has values, and closed, with its queued
+ * writes sent, when the component unmounts.
+ *
+ * Components naming the same `storage`, `prefix`, and `schema` share one
+ * store, which closes when the last of them unmounts. Components naming the
+ * same `storage` and `prefix` with different schemas each get a store of
+ * their own over the same records, so a write through one is read by the
+ * others at once, and each hears it as a `local` change. They must pass the
+ * same `migrations`: the records are migrated once, when the first opens.
+ *
+ * `storage` and `schema` are compared by identity and `prefix` by value, so
+ * keep the first two out of the render body. A change to any of the three
+ * closes the store and returns the one for the new three. The `options`
+ * object itself may be new every render: `migrations` and `validators` are
+ * read when a store opens, and a change to either alone opens nothing.
+ */
+declare function usePrefsStore<S extends PrefGroup>(schema: S, options: SyncOptions): PrefsStore<S>;
+
+export { usePref, usePrefsStore, usePrefsValues };