@weasel-js/prefs 0.0.0-stage → 1.9.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @weasel-js/prefs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A preferences schema — groups of typed leaves with names, defaults and
+rendering hints — and a store that keeps values for it.
+
+```ts
+const store = await openPrefs(SCHEMA, { storage: indexedDbAdapter, prefix: 'myapp.prefs.' });
+store.get('view.gridVisible');
+store.set('view.gridVisible', false);
+```
+
+One record per leaf. A leaf with no record follows its schema default. Reads
+repair stored values that no longer fit the schema without writing them back.
+`migrations[i]` takes stored records from version `i` to `i + 1`.
+`openPrefsSync` opens from an adapter that reads synchronously, such as
+`localStorageAdapter`, with no `await`.
+
+`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

@@ -0,0 +1,153 @@
+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';
+
+/**
+ * A number leaf's bounds in the unit it is displayed in.
+ *
+ * Only what the leaf declares converts: an omitted bound has no stored
+ * counterpart to put through the conversion, and its fallback — 0..100 for a
+ * slider's track, a step of 1 — is a display-space number already. `min` and
+ * `max` are points, so they convert the way the value does; `step` is a
+ * distance, and a unit with an offset maps zero somewhere else, so converting
+ * it as a point would scale it wrong. A decreasing conversion swaps which end
+ * is the lower one.
+ */
+declare function prefDisplayBounds(p: PrefNumber): {
+    min?: number;
+    max?: number;
+    step: number;
+};
+/** 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`), 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, 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. 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.
+ *
+ * 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 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;
+};
+
+/** 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;
+
+/** 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>>;
+}
+/** 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>;
+
+/** 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 };