@weasel-js/prefs 1.9.3 → 1.9.4

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

@@ -1,7 +1,117 @@
 import { Display, UnitEntry, InfinityText, UnitSystem, Unit } from '@weasel-js/quantity';
 
+/** What a {@link PrefAction}'s `run` is told. */
+interface PrefActionContext {
+    /** The path the action sits at on the surface drawing it. */
+    path: string;
+}
+/** How a schema-driven UI should present an action leaf. */
+type PrefActionControl = 'button' | 'icon';
+/**
+ * A leaf that holds no value: a button among the rows or in a bar. A store
+ * neither reads nor writes one, and its path is not a {@link PrefPath}.
+ *
+ * It fires one of two things. `action` names an action the host registered,
+ * by key, which keeps the leaf plain data: it survives JSON, so a layout
+ * holding it can be saved and exported. `run` is code the schema carries.
+ * A leaf with both fires `action`. While a promise `run` returned is
+ * pending, the button is disabled.
+ */
+interface PrefAction extends PrefBase<'action', undefined> {
+    /** The key of a registered action to fire: its id, or `id:variant` for one
+     *  variant of a parametric action. The leaf's `name` and `icon` are what
+     *  the button shows, over the registered action's own. */
+    action?: string;
+    /** What to call when no `action` is named. */
+    run?: (ctx: PrefActionContext) => void | Promise<void>;
+    /** The button's text. Default: the leaf's `name`. */
+    label?: string;
+    /** `button` reads its label; `icon` is the icon alone, with the label in
+     *  its tooltip. Unset: a button in a row, an icon in a bar. */
+    control?: PrefActionControl;
+}
+
+/**
+ * A second place for another leaf: its row draws that leaf's control and
+ * reads and writes that leaf's value, so one setting can sit on two pages.
+ * It holds no value of its own. A store neither reads nor writes one, and
+ * its path is not a {@link PrefPath}.
+ *
+ * `name` and `description` left empty are the target's.
+ */
+interface PrefAlias extends PrefBase<'alias', undefined> {
+    /** The leaf shown here, by the full path its value is read and written at (`'view.grid'`). */
+    of: string;
+}
+/**
+ * The leaf an alias stands for and the path its value lives at, following an
+ * alias of an alias to its end. `undefined` when a path along the way names
+ * no leaf, or the aliases lead back to one already passed.
+ */
+declare function prefAliasTarget(alias: PrefAlias, leafAt: (path: string) => PrefLeaf | undefined): {
+    path: string;
+    leaf: PrefLeaf;
+} | undefined;
+/** 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;
+
+/**
+ * A line of text among the rows, holding no value: `name` is the line and
+ * `description` the note under it. A store neither reads nor writes one, and
+ * its path is not a {@link PrefPath}.
+ */
+type PrefLabel = PrefBase<'label', undefined>;
+/** A rule drawn between the rows, holding no value and drawing none of its own text. */
+type PrefSeparator = PrefBase<'separator', undefined>;
+
+/**
+ * A leaf whose value is an array, every entry described by `item`.
+ *
+ * `item` is an ordinary leaf, built-in or app-defined, so a list of objects,
+ * of lists or of a custom kind is declared the way a list of numbers is, and
+ * each entry is validated and drawn as that leaf would be on its own. Its
+ * `default` is what a new entry starts as, and its `name` names one entry
+ * (`'Phase'` under a list named `'Phases'`).
+ */
+interface PrefList extends PrefBase<'list', readonly unknown[]> {
+    item: PrefLeaf;
+    /** A stored list shorter than this reads as the default, and a UI stops removing at it. */
+    minItems?: number;
+    /** A stored list longer than this reads cut to it, and a UI stops adding at it. */
+    maxItems?: number;
+}
+
+/**
+ * A leaf whose value is an object keyed by strings nobody declared, every
+ * value described by `item`: the keyed counterpart of a {@link PrefList}.
+ * `item` is an ordinary leaf of any kind; its `default` is what a new entry
+ * starts as, and its `name` names one entry's value.
+ */
+interface PrefMap extends PrefBase<'map', Readonly<Record<string, unknown>>> {
+    item: PrefLeaf;
+}
+
+/**
+ * A leaf whose value is one of several object shapes, told apart by the
+ * string its `tag` field holds: `{ type: 'linear', angle: 90 }` or
+ * `{ type: 'radial', radius: 1 }` under `tag: 'type'`.
+ *
+ * Each variant is an `object` leaf keyed by its tag value. Its `children`
+ * are the fields beside the tag, its `name` is what a person chooses, and
+ * its `default` (without the tag) is what the value becomes when they choose
+ * it. A stored value whose tag names no variant reads as the leaf's default.
+ */
+interface PrefUnion extends PrefBase<'union', unknown> {
+    tag: string;
+    variants: Record<string, PrefObject>;
+}
+/** The variant `value` is, or `undefined` when its tag names none. */
+declare function prefVariantOf(leaf: PrefUnion, value: unknown): [key: string, variant: PrefObject] | undefined;
+/** 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' | 'field';
+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 (weasel-ui
  * `SelectionPanel`, labkit's `ControlPanel`), declared on the first of them.
@@ -26,6 +136,13 @@ interface PrefBase<K extends string, Value> {
     default: Value;
     /** Hide from a host app's settings UI by default. */
     hidden?: boolean;
+    /** 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
+     *  scene node, where a missing key otherwise means the node has no such
+     *  property, shows the default only for a leaf that says this, and still
+     *  writes nothing until an edit. */
+    absentIsDefault?: boolean;
     /** Render full-width with no label row in schema-driven settings UIs
      *  (weasel-ui `PrefsForm` honors this for leaves whose control brings
      *  its own chrome). */
@@ -43,6 +160,19 @@ interface PrefBase<K extends string, Value> {
      *  shows the longest of them that fits. `name` stays the accessible name, so
      *  these abbreviate without costing anything. */
     short?: readonly string[];
+    /** Never auto. A surface that lets a leaf be left for its owner to decide
+     *  (weasel-ui `PrefsForm`'s `onAutoChange`, labkit's `ControlPanel`) gives
+     *  this one no way to. */
+    manual?: boolean;
+    /** Starts auto, where it would start pinned at `default`. */
+    unpinned?: boolean;
+    /** What the leaf reads while it is auto, where its owner computes nothing
+     *  for it. Unset, an auto leaf has no value. */
+    autoValue?: Value;
+    /** The name of the type this leaf was made from, set by `prefType`. A
+     *  schema editor shows such a leaf as one closed thing and prints the name
+     *  in place of its literal. */
+    type?: string;
 }
 /** How a schema-driven UI should present a number pref. */
 type PrefNumberControl = 'input' | 'slider';
@@ -51,7 +181,7 @@ type PrefBooleanControl = 'checkbox' | 'switch' | 'toggle';
 /** How a schema-driven UI should present a string pref. */
 type PrefStringControl = 'input' | 'textarea';
 /** How a schema-driven UI should present an enum pref. */
-type PrefEnumControl = 'select' | 'radio' | 'toggle';
+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. */
@@ -89,7 +219,7 @@ interface PrefNumber extends PrefBase<'number', number> {
      *  reads `2.00M`. Presentation only: the stored value stays a number. */
     display?: Display;
     unit?: PrefNumberUnit;
-    /** Which end of a slider stands for infinity: the value there is ±Infinity. */
+    /** Which end of a slider gets a stop for ±Infinity, one step beyond the range. */
     endless?: 'min' | 'max' | 'both';
     /** The word infinity shows as — `'never'`, `'uncapped'`. Default `∞`. */
     infinity?: InfinityText;
@@ -136,16 +266,8 @@ interface PrefEnumEncoding<T extends string = string> {
     /** What to store for `option`. `undefined` removes the field. */
     write: (option: T, siblings: Record<string, unknown> | undefined) => unknown;
 }
-/** A pref with a fixed set of labeled choices. `default` is `undefined` only
- *  for a {@link PrefEnum.clearable} leaf, whose absence is a value. */
-interface PrefEnum<T extends string = string> extends PrefBase<'enum', T | undefined> {
-    /**
-     * The field may hold none of the options, and that absence is a state of
-     * its own rather than a missing value — a script that is neither super nor
-     * sub. A toggle control then lets the chosen segment be clicked off, which
-     * removes the field.
-     */
-    clearable?: boolean;
+/** What every enum leaf carries; {@link PrefEnum} adds `clearable`. */
+interface PrefEnumBase<T extends string = string> extends PrefBase<'enum', T | undefined> {
     /** `short` holds shorter forms of `label`, longest first, for a segmented
      *  control too narrow for the full one — down to a capital or two. `icon`
      *  names a glyph in the host UI's set (weasel-ui resolves it against
@@ -168,6 +290,22 @@ interface PrefEnum<T extends string = string> extends PrefBase<'enum', T | undef
     control?: PrefEnumControl;
     encoding?: PrefEnumEncoding<T>;
 }
+/**
+ * A pref with a fixed set of labeled choices.
+ *
+ * `clearable` says the field may hold none of the options, and that absence
+ * is a state of its own rather than a missing value — a script that is
+ * neither super nor sub. A toggle control then lets the chosen segment be
+ * clicked off, which removes the field. Such a leaf's `default` is
+ * `undefined`: a missing value is the only stored form of cleared, so a
+ * default would bring an option back the moment the field was cleared.
+ */
+type PrefEnum<T extends string = string> = PrefEnumBase<T> & ({
+    clearable?: false;
+} | {
+    clearable: true;
+    default: undefined;
+});
 /** A single color, stored as a hex string. For a value that may also be a
  *  gradient or a pattern, use {@link PrefPaint} instead. */
 interface PrefColor extends PrefBase<'color', string> {
@@ -209,19 +347,18 @@ interface PrefPaint extends PrefBase<'paint', unknown> {
  *
  * `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 PrefGroup}, which
- * organises the fields under a heading without contributing to the path —
- * the same rule group keys follow at the top level. A `TextStyle` needs it:
- * its character and paragraph fields belong to one value but read as two
- * lists.
+ * 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.
  */
 interface PrefObject extends PrefBase<'object', unknown> {
-    children: Record<string, PrefLeaf | PrefGroup>;
+    children: Record<string, PrefLeaf | PrefSection>;
     /**
      * Lift a non-object value into the object form, for a consumer field that
      * may also be held as a scalar. Called before a child edit is applied;
-     * without it a scalar-valued leaf shows its children empty and refuses the
-     * edit.
+     * without it a scalar-valued leaf shows its children empty, and an edit
+     * starts from the leaf's `default`.
      */
     fromScalar?: (value: unknown) => Record<string, unknown>;
 }
@@ -236,7 +373,7 @@ interface PrefField extends PrefBase<'field', string> {
 }
 /** One built-in pref leaf. `PrefLeaf` widens this to include
  *  app-defined kinds. */
-type BuiltinPref = PrefNumber | PrefBoolean | PrefString | PrefEnum | PrefColor | PrefPaint | PrefObject | PrefField;
+type BuiltinPref = PrefNumber | PrefBoolean | PrefString | PrefEnum | PrefColor | PrefPaint | PrefObject | PrefList | PrefMap | PrefUnion | PrefField | PrefAction | PrefAlias | PrefLabel | PrefSeparator;
 /**
  * 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`
@@ -261,27 +398,71 @@ declare function pairRowsOf(leaves: Iterable<readonly [path: string, leaf: PrefL
 declare function isBuiltinPref(leaf: PrefLeaf): leaf is BuiltinPref;
 /** Built-in or app-defined leaf. */
 type PrefLeaf = BuiltinPref | PrefCustom;
-/** Nestable group: branch nodes a tool can use to organize its prefs. */
+
+/**
+ * How a {@link PrefGroup} is drawn: `page` gets an entry in a form's rail and
+ * a pane of its own; `tab` shares a tab strip with the `tab` groups beside it;
+ * `panel` is a bordered, titled box; `section` is a heading over its rows;
+ * `fragment` draws nothing of its own, so its rows sit among its neighbors'
+ * as though they were written there. A fragment exists to hold things
+ * together: one key for their values to nest under, one node to move.
+ */
+type PrefGroupAs = 'page' | 'tab' | 'panel' | 'section' | 'fragment' | 'bar';
+/** How a {@link PrefSection} is drawn. */
+type PrefSectionAs = Exclude<PrefGroupAs, 'page'>;
+/**
+ * A group whose key is a path segment: `view` > `gridDensity` is the leaf at
+ * `view.gridDensity`, and its value nests the same way. The shape of a
+ * preferences schema — what `openPrefs` stores, `PrefsForm` renders, and a
+ * tool declares its options as. A key holds no `.`.
+ */
 interface PrefGroup {
     /** Heading for the group's rows. **Empty means no heading** — for a group
-     *  that exists to organise, not to name: one whose children are themselves
+     *  that exists to organize, not to name: one whose children are themselves
      *  groups carrying the labels a reader needs. Give it a name whenever the
      *  name is the referent (a `Border` group over `Top` / `Right` / `Bottom`
      *  reads as nothing without it). */
     name: string;
     description?: string;
+    /** 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;
     children: Record<string, PrefLeaf | PrefGroup>;
 }
+/**
+ * A heading over leaves that adds nothing to their paths: each member is
+ * addressed by its own key alone, and the section's key only identifies the
+ * section. The shape of a node's property schema, where a leaf's key is the
+ * whole dotted node path (`pose.x`, `data.fill`), and of the headings inside
+ * a {@link PrefObject}, where a key is relative to the object.
+ */
+interface PrefSection {
+    /** Heading for the section's rows. Empty means no heading, as for a
+     *  {@link PrefGroup}. */
+    name: string;
+    description?: string;
+    /** How the section is drawn, as a {@link PrefGroup}'s `as` — without
+     *  `page`, since nothing that draws sections has a rail. Unset: a heading
+     *  over its rows. */
+    as?: PrefSectionAs;
+    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;
 
 type Join<A extends string, B extends string> = A extends '' ? B : `${A}.${B}`;
-/** Every leaf's dotted path in a schema. A group's key is a segment; an
- *  `object` leaf is one path, its fields are not. */
+/** 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`,
+ *  `alias`, `label`, or `separator` leaf, holding no value, has none. A `PrefSection`
+ *  has no such paths: each of its leaves is addressed by its own key. */
 type PrefPath<G, Prefix extends string = ''> = G extends {
     children: infer C;
 } ? string extends keyof C ? Join<Prefix, string> : {
     [K in keyof C & string]: C[K] extends {
         kind: string;
-    } ? Join<Prefix, K> : C[K] extends {
+    } ? C[K] extends {
+        kind: 'action' | 'alias' | 'label' | 'separator';
+    } ? never : Join<Prefix, K> : C[K] extends {
         children: Record<string, unknown>;
     } ? PrefPath<C[K], Join<Prefix, K>> : never;
 }[keyof C & string] : never;
@@ -293,8 +474,22 @@ type PrefAtPath<G, P extends string> = G extends {
 } ? never : PrefAtPath<C[H], Rest> : never : P extends keyof C ? C[P] extends {
     kind: string;
 } ? C[P] : never : never : never;
+type AllOf<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/** The fields an `object` leaf's `children` describe, sections folded in. Each is optional: an object may omit any. */
+type PrefFieldsOf<C> = {
+    [K in keyof C as C[K] extends {
+        kind: string;
+    } ? K : never]?: PrefValueOf<C[K]>;
+} & AllOf<{
+    [K in keyof C]: C[K] extends {
+        members: infer M;
+    } ? PrefFieldsOf<M> : never;
+}[keyof C]>;
 /** What a leaf holds: its kind's value type for a built-in kind, the type of
- *  its `default` for an app-defined one. */
+ *  its `default` for an app-defined one. A list holds an array of what its
+ *  `item` holds, a map a record of it, and a union one variant's fields
+ *  under that variant's tag — where the schema keeps `tag` a literal
+ *  (`tag: 'type' as const`); one widened to `string` is typed by its default. */
 type PrefValueOf<L> = L extends {
     kind: 'number';
 } ? number : L extends {
@@ -311,6 +506,23 @@ type PrefValueOf<L> = L extends {
 } ? L extends {
     clearable: true;
 } ? T | undefined : T : L extends {
+    kind: 'list';
+    item: infer I;
+} ? PrefValueOf<I>[] : L extends {
+    kind: 'map';
+    item: infer I;
+} ? Record<string, PrefValueOf<I>> : L extends {
+    kind: 'union';
+    tag: infer T extends string;
+    variants: infer V;
+    default: infer D;
+} ? string extends keyof V | T ? D : {
+    [K in keyof V & string]: {
+        [P in T]: K;
+    } & (V[K] extends {
+        children: infer C;
+    } ? PrefFieldsOf<C> : unknown);
+}[keyof V & string] : L extends {
     default: infer D;
 } ? D : unknown;
 /** What the leaf at `P` holds. */
@@ -342,12 +554,19 @@ interface PrefsStore<S extends PrefGroup> {
     stored(): Record<string, unknown>;
     /** `changes` is empty when only records no leaf describes changed. */
     subscribe(listener: (changes: PrefChange[]) => void): () => void;
-    /** False when the store cannot persist: storage was unreadable, or written
-     *  by a newer schema. Changes still apply for this session. */
+    /** 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. */
     readonly writable: 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>;
+    /** Resolves once storage has been read: at once for a store that opened
+     *  with its values, and when a later read lands for one that could not. */
+    whenRead(): Promise<void>;
     /** Resolves true when every queued write reached storage. */
     flush(): Promise<boolean>;
     close(): Promise<void>;
 }
 
-export { type PrefValueOf as A, type BuiltinPref as B, isBuiltinPref as C, pairRowsOf as D, prefUnit as E, type PrefLeaf as P, type PrefGroup as a, type PrefNumber as b, type PrefsStore as c, PREF_KINDS as d, type PrefAtPath as e, type PrefBase as f, type PrefBoolean as g, type PrefBooleanControl as h, type PrefBooleanEncoding as i, type PrefChange as j, type PrefColor as k, type PrefCustom as l, type PrefEnum as m, type PrefEnumControl as n, type PrefEnumEncoding as o, type PrefField as p, type PrefKind as q, type PrefNumberControl as r, type PrefNumberUnit as s, type PrefObject as t, type PrefPaint as u, type PrefPair as v, type PrefPath as w, type PrefString as x, type PrefStringControl as y, type PrefValueAt as z };
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/prefs",
-  "version": "1.9.3",
+  "version": "1.9.4",
   "description": "A preferences schema, a store that loads, validates, migrates and persists values against it, and React hooks over the store.",
   "license": "MIT",
   "type": "module",
@@ -41,8 +41,9 @@
     "build": "tsup"
   },
   "dependencies": {
-    "@weasel-js/quantity": "1.9.3",
-    "@weasel-js/storage": "1.9.3"
+    "@weasel-js/quantity": "1.9.4",
+    "@weasel-js/registry": "1.9.4",
+    "@weasel-js/storage": "1.9.4"
   },
   "peerDependencies": {
     "react": ">=18"