vultus-core 0.5.2 → 0.5.4

package/dist/useArg.d.ts

@@ -15,6 +15,12 @@ export interface ArgControls<T> {
     /** The href `set(value)` would produce, where the store supports it (a URL store); `undefined` otherwise. */
     hrefFor(value: T): string | undefined;
 }
+/**
+ * The raw value a write needs for `value`: `undefined` (removes the key) when it equals the
+ * default, else its formatted form. Exported for the field group (useFieldGroup), which writes a
+ * store by the same rule; not part of the package's API.
+ */
+export declare function rawFor<T>(value: T, defaultValue: T, valueType: ValueType<T>): string | undefined;
 /**
  * An argument read from and written to the nearest ArgStore. An absent key reads as the default;
  * writing the default removes the key.

package/dist/useArg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useArg.d.ts","sourceRoot":"","sources":["../src/useArg.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,eAAe,CAAC;AAI7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,8GAA8G;AAC9G,MAAM,WAAW,aAAa,CAAC,CAAC,EAAE,GAAG,GAAG,GAAG;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACxB,OAAO,EAAE,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,KAAK,EAAE,CAAC,CAAC;IACT,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3C,KAAK,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,6GAA6G;IAC7G,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,GAAG,SAAS,CAAC;CACvC;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CA8CtE;AAED,4FAA4F;AAC5F,MAAM,MAAM,SAAS,GAAG;IAAE,UAAU,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAE1F,wBAAgB,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAE3E;AAED,wBAAgB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,CAAC,GAAG,SAAS,CAElE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,EAAE,YAAY,KAAK,IAAI,CAepF"}
+{"version":3,"file":"useArg.d.ts","sourceRoot":"","sources":["../src/useArg.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,eAAe,CAAC;AAI7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,8GAA8G;AAC9G,MAAM,WAAW,aAAa,CAAC,CAAC,EAAE,GAAG,GAAG,GAAG;IACzC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACxB,OAAO,EAAE,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,KAAK,EAAE,CAAC,CAAC;IACT,SAAS,EAAE,OAAO,CAAC;IACnB,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3C,KAAK,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,6GAA6G;IAC7G,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,GAAG,SAAS,CAAC;CACvC;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,SAAS,CAEhG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CA8CtE;AAED,4FAA4F;AAC5F,MAAM,MAAM,SAAS,GAAG;IAAE,UAAU,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAE1F,wBAAgB,MAAM,CAAC,CAAC,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAE3E;AAED,wBAAgB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,GAAG,CAAC,GAAG,SAAS,CAElE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,EAAE,YAAY,KAAK,IAAI,CAepF"}

package/dist/useArg.js

@@ -2,8 +2,12 @@ import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react';
 import { useArgStore } from './ArgStoreContext.js';
 import { useFieldContext } from './FieldContext.js';
 import { resolveIn } from './resolve.js';
-/** The raw value a write needs for `value`: `undefined` (removes the key) when it equals the default, else its formatted form. */
-function rawFor(value, defaultValue, valueType) {
+/**
+ * The raw value a write needs for `value`: `undefined` (removes the key) when it equals the
+ * default, else its formatted form. Exported for the field group (useFieldGroup), which writes a
+ * store by the same rule; not part of the package's API.
+ */
+export function rawFor(value, defaultValue, valueType) {
     return valueType.isEqual(value, defaultValue) ? undefined : valueType.format(value);
 }
 /**

package/dist/useArg.js.map

@@ -1 +1 @@
-{"version":3,"file":"useArg.js","sourceRoot":"","sources":["../src/useArg.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useArg.js","sourceRoot":"","sources":["../src/useArg.ts"],"names":[],"mappings":"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"}

package/dist/useFieldGroup.d.ts

@@ -0,0 +1,80 @@
+import type { UpdateMethod } from './argStore.js';
+import type { FieldControls } from './field.js';
+import { type FieldDefinition } from './kinds.js';
+/** A field group's fields as one component runs them (see useFieldGroup). */
+export interface FieldGroup {
+    /**
+     * Each field's controls, exactly as its kind's hook returns them, in definition order: what the
+     * widgets render. Typed `FieldControls`; for a kind's own controls, cast by kind
+     * (`group.byId.toc as OneOfTreeFieldControls<string>`).
+     */
+    fields: FieldControls<any, any>[];
+    /** The same controls, by field id. */
+    byId: Record<string, FieldControls<any, any>>;
+    /**
+     * The fields' shown values by id (after the fallback rule), as of this render: a plain object,
+     * which keeps its identity until a shown value changes (an effect keyed on it runs only then).
+     */
+    values: Readonly<Record<string, unknown>>;
+    /** Whether the field with this id shows its current default; an id not in the group throws. */
+    isDefault(id: string): boolean;
+    /** How many of the fields do not show their defaults ("more filters (3)"). */
+    changedCount: number;
+    /**
+     * Every field back to its default: no field keeps a value any more. Stored, one store write
+     * removes every field's key (`method`, 'replace' unless told otherwise); the group's own state
+     * ignores `method`.
+     */
+    resetAll(method?: UpdateMethod): void;
+}
+/**
+ * Runs a list of field definitions together, as a group: every option function of each
+ * definition (but `initialValue`) receives `ctx.values`, the fields' shown values by id, beside
+ * the app's own field context, so a field's choices, bounds or visibility can follow another
+ * field. A field's default is its `initialValue` (which cannot read `values`), else its kind's
+ * implicit initial value from its options as they are now, so it moves with the fields those
+ * read. It throws, naming the field (and the option), for an option reading an id not in the
+ * group, two definitions with the same id and a mixed-boolean definition; naming the cycle for
+ * fields whose values depend on each other; and for an app context that already has `values`
+ * (`Field group: the field context already has 'values'; a field group provides it`).
+ *
+ * Storage, for the whole group, is the caller's choice. By default the group keeps the values in
+ * its own state, as a store keeps them: a field never set, or set to its current default, keeps
+ * nothing and shows its current default, which moves with the fields its options read. A kept
+ * value that another field's change made invalid shows the field's fallback, silently (that is
+ * how a group behaves, not bad input), and shows again once it is valid again; it is never
+ * rewritten. `resetAll()` clears every kept value (the update method is for a store; here it is
+ * ignored).
+ *
+ * With `{ stored: true }` the values live in the nearest ArgStore (the URL, localStorage) under
+ * each field's id, as useStoredField keeps a field there, all read in one subscription: an absent
+ * key reads as the field's current default, and a value equal to it is written as an absent key
+ * (`'replace'`). The default compared with is the one under the store's values at the moment of
+ * the write, as in the group's own state, so a write batched after another field's (in one
+ * event) compares with the default that one gives. The controls' `hrefFor` links a value
+ * through the store's `hrefFor` (`undefined` where the store has none), as rendered. The fallback
+ * rule is the same, and the stored value is never rewritten either, but a raw value that does not
+ * parse, or falls back, warns once, as useStoredField's does: an unparsable one reads as the
+ * current default. A raw value the group itself wrote does not warn (a write chained after
+ * another field's in one event may fall back at once). `resetAll(method = 'replace')` removes
+ * every field's key in one write.
+ *
+ * Each field runs its kind's hook with the definition in its outside form (the group's value and
+ * writer), with the group's context as its field context, so its controls are the kind's own,
+ * and a request goes through the kind's own checks before it is kept. The hooks run per field,
+ * so the ids and kinds, in order, are kept from the first render, and so is the storage: a list
+ * of another shape, or another `stored`, throws (remount the component running the group, with a
+ * React `key`, to swap lists). The definitions' contents may change, and new objects of the same
+ * shape on every render (inline literals) are fine.
+ *
+ * A field's shown value, in `values` and as passed to its kind's hook, keeps its identity while it
+ * stays equal (element by element, as useStoredField's does), so a list does not become a new array
+ * on every render; the `values` object keeps its identity until a shown value changes, so an
+ * effect keyed on it (one that loads data, say, and feeds the app's field context) runs only
+ * then. A kind's own controls may still rebuild a composite value: range's `[from, to]` pair is
+ * put in order and within bounds anew on every render.
+ */
+export declare function useFieldGroup(definitions: readonly FieldDefinition[], options?: {
+    stored?: boolean;
+}): FieldGroup;
+//# sourceMappingURL=useFieldGroup.d.ts.map

package/dist/useFieldGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFieldGroup.d.ts","sourceRoot":"","sources":["../src/useFieldGroup.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,eAAe,CAAC;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAK/D,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;IAClC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C;;;OAGG;IACH,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C,+FAA+F;IAC/F,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CACvC;AAwMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,UAAU,CA6DrH"}

package/dist/useFieldGroup.js

@@ -0,0 +1,266 @@
+import { useCallback, useRef, useState, useSyncExternalStore } from 'react';
+import { useArgStore } from './ArgStoreContext.js';
+import { useFieldContext, withFieldContext } from './FieldContext.js';
+import { createGroupValues } from './fieldGroupValues.js';
+import { useKindField } from './kindHooks.js';
+import { valueTypeOf } from './kinds.js';
+import { rawFor } from './useArg.js';
+import { sameValue } from './useStoredField.js';
+const NOTHING_KEPT = {};
+const WHERE = 'Field group';
+function silently(_id, _message) { }
+/** A field's kept value in `kept`, or `undefined` for none (an id such as `toString` is not Object's member). */
+function keptIn(kept) {
+    return (id) => (Object.hasOwn(kept, id) ? kept[id] : undefined);
+}
+/** The ids and kinds of a list of definitions, in order: what has to stay the same across renders. */
+function shapeOf(definitions) {
+    return definitions.map(({ id, kind }) => `${id} (${String(kind)})`).join(', ');
+}
+/** Where a group keeps its values, in the words of the error for a change of it. */
+function storageOf(stored) {
+    return stored ? 'the nearest ArgStore ({ stored: true })' : "the group's own state";
+}
+/**
+ * Whether a field shows its default, by useStoredField's rule: nothing is kept, or the kept
+ * value equals the current default, or what it shows does (a kept value that falls back to it).
+ */
+function showsDefault(definition, kept, group) {
+    if (kept === undefined)
+        return true;
+    const { isEqual } = valueTypeOf(definition.kind);
+    const fallback = group.defaultOf(definition.id);
+    return isEqual(kept, fallback) || isEqual(group.valueOf(definition.id), fallback);
+}
+/**
+ * A field's default under the given kept values (the state a write applies to, not necessarily
+ * this render's), computed afresh and silently. A write compares with it, so a write batched
+ * after another field's (in one event) compares with the default that one gives.
+ */
+function defaultUnder(definitions, appCtx, kept, id) {
+    return createGroupValues({ definitions, appCtx, kept, warn: silently }).defaultOf(id);
+}
+/**
+ * The group's own state: the kept values by id. A write keeps the value unless it equals the
+ * field's default under the state the write applies to, so a write batched after another
+ * field's (in one event) compares with the default that one gives. A fallback is silent: a value
+ * another field made invalid is how a group behaves, not bad input. There are no links.
+ */
+function useOwnState(definitions, appCtx) {
+    const [kept, setKept] = useState(NOTHING_KEPT);
+    const resetAll = useCallback(() => setKept((state) => (Object.keys(state).length === 0 ? state : NOTHING_KEPT)), []);
+    const write = ({ id, kind }) => (value) => setKept((state) => {
+        if (!valueTypeOf(kind).isEqual(value, defaultUnder(definitions, appCtx, keptIn(state), id)))
+            return { ...state, [id]: value };
+        if (!Object.hasOwn(state, id))
+            return state;
+        const { [id]: _dropped, ...rest } = state;
+        return rest;
+    });
+    return { kept: keptIn(kept), warn: silently, outside: (definition) => ({ onChange: write(definition) }), resetAll };
+}
+/** How a field's value is kept in a store; an unknown kind throws, naming the field (as argOf does). */
+function valueTypeFor({ id, kind }) {
+    try {
+        return valueTypeOf(kind);
+    }
+    catch (error) {
+        throw new Error(`Field '${id}': ${error.message}`);
+    }
+}
+/** A stored raw value as the field's value: `undefined` for an absent key, or for a raw value its kind's value type cannot read. */
+function parseRaw(definition, raw) {
+    return raw === undefined ? undefined : valueTypeFor(definition).parse(raw);
+}
+/**
+ * The nearest ArgStore, under each field's id, as useStoredField keeps a field there, read in one
+ * subscription (as useStoredFields): its snapshot is the fields' raw values joined into one
+ * string, which changes exactly when one of them does. A raw value is parsed by the kind's value
+ * type; one that does not parse is no kept value, so the field shows its current default.
+ *
+ * A write carries the value's raw form, the key absent when the value equals the field's default
+ * as the store has it at that moment: the values computed afresh, silently, from the store's
+ * current raw values, which include its own writes not rendered yet (every store reads them back
+ * at once). So, as in the group's own state, a write batched after another field's (in one
+ * event) compares with the default that one gives. A link (the store's `hrefFor`, where it has
+ * one) is the render's: its key is absent when the value equals the default as rendered, and it
+ * keeps its identity while the store and that default stay the same (a tree list rebuilds its
+ * rows for a new one, and asks again when a link is used).
+ *
+ * A raw value warns (it does not parse, or it falls back) once, as useStoredField's does: in the
+ * render that first reads it, not again on a re-render, nor when another field's change makes it
+ * fall back later; another raw value warns again. The warnings are for raw values from elsewhere
+ * (the URL, another tab): the one the group itself last wrote for a field, read by the next render,
+ * does not warn, as a write chained after another field's in one event may fall back at once
+ * (`layout.setValue('rendered'); paper.setValue('letter')`, Letter offered under the old layout).
+ */
+function useStoredValues(definitions, appCtx) {
+    const store = useArgStore();
+    // The first render's ids: the shape check keeps them the same.
+    const [ids] = useState(() => definitions.map((definition) => definition.id));
+    // Called on the store, not passed detached: a store written as a class uses `this`.
+    const subscribe = useCallback((listener) => store.subscribe(listener), [store]);
+    const readAll = useCallback(() => JSON.stringify(ids.map((id) => store.read(id) ?? null)), [store, ids]);
+    const snapshot = useSyncExternalStore(subscribe, readAll);
+    const rawList = JSON.parse(snapshot);
+    const raws = new Map(ids.map((id, i) => [id, rawList[i]]));
+    const seenRef = useRef(new Map());
+    /** The raw value the group itself last wrote for a field, until the next render reads the store. */
+    const writtenRef = useRef(new Map());
+    const seen = seenRef.current;
+    const written = writtenRef.current;
+    /** The fields whose raw value this render reads first, from elsewhere than the group's own write: each may warn, once. */
+    const fresh = new Set();
+    for (const id of ids) {
+        const raw = raws.get(id) ?? null;
+        if (raw !== seen.get(id) && raw !== null && raw !== written.get(id))
+            fresh.add(id);
+    }
+    // Every store reads its own writes back at once, so the render after a write reads it: the memory
+    // lasts until then, and a write undone before any render is not remembered later.
+    written.clear();
+    seenRef.current = raws;
+    const warn = (id, message) => {
+        if (fresh.delete(id))
+            console.warn(message);
+    };
+    const byId = new Map(definitions.map((definition) => [definition.id, definition]));
+    const parsed = new Map();
+    const kept = (id) => {
+        if (!parsed.has(id)) {
+            const raw = raws.get(id) ?? undefined;
+            const value = parseRaw(byId.get(id), raw);
+            if (raw !== undefined && value === undefined)
+                warn(id, `Argument '${id}': cannot read '${raw}', using the default`);
+            parsed.set(id, value);
+        }
+        return parsed.get(id);
+    };
+    /** A field's default as the store has it now: under its current raw values, its own writes not rendered yet included. */
+    const defaultNow = (id) => defaultUnder(definitions, appCtx, (key) => parseRaw(byId.get(key), store.read(key)), id);
+    const linksRef = useRef(new Map());
+    const outside = (definition, group) => {
+        const { id } = definition;
+        const valueType = valueTypeFor(definition);
+        const onChange = (value) => {
+            const raw = rawFor(value, defaultNow(id), valueType);
+            written.set(id, raw);
+            store.write([{ key: id, raw }], 'replace');
+        };
+        if (store.hrefFor === undefined)
+            return { onChange };
+        const defaultValue = group.defaultOf(id);
+        let link = linksRef.current.get(id);
+        if (link === undefined || link.store !== store || !valueType.isEqual(link.defaultValue, defaultValue)) {
+            link = { store, defaultValue, hrefFor: (value) => store.hrefFor?.([{ key: id, raw: rawFor(value, defaultValue, valueType) }]) };
+            linksRef.current.set(id, link);
+        }
+        return { onChange, hrefFor: link.hrefFor };
+    };
+    const resetAll = useCallback((method = 'replace') => store.write(ids.map((id) => ({ key: id, raw: undefined })), method), [store, ids]);
+    return { kept, warn, outside, resetAll };
+}
+/**
+ * Runs a list of field definitions together, as a group: every option function of each
+ * definition (but `initialValue`) receives `ctx.values`, the fields' shown values by id, beside
+ * the app's own field context, so a field's choices, bounds or visibility can follow another
+ * field. A field's default is its `initialValue` (which cannot read `values`), else its kind's
+ * implicit initial value from its options as they are now, so it moves with the fields those
+ * read. It throws, naming the field (and the option), for an option reading an id not in the
+ * group, two definitions with the same id and a mixed-boolean definition; naming the cycle for
+ * fields whose values depend on each other; and for an app context that already has `values`
+ * (`Field group: the field context already has 'values'; a field group provides it`).
+ *
+ * Storage, for the whole group, is the caller's choice. By default the group keeps the values in
+ * its own state, as a store keeps them: a field never set, or set to its current default, keeps
+ * nothing and shows its current default, which moves with the fields its options read. A kept
+ * value that another field's change made invalid shows the field's fallback, silently (that is
+ * how a group behaves, not bad input), and shows again once it is valid again; it is never
+ * rewritten. `resetAll()` clears every kept value (the update method is for a store; here it is
+ * ignored).
+ *
+ * With `{ stored: true }` the values live in the nearest ArgStore (the URL, localStorage) under
+ * each field's id, as useStoredField keeps a field there, all read in one subscription: an absent
+ * key reads as the field's current default, and a value equal to it is written as an absent key
+ * (`'replace'`). The default compared with is the one under the store's values at the moment of
+ * the write, as in the group's own state, so a write batched after another field's (in one
+ * event) compares with the default that one gives. The controls' `hrefFor` links a value
+ * through the store's `hrefFor` (`undefined` where the store has none), as rendered. The fallback
+ * rule is the same, and the stored value is never rewritten either, but a raw value that does not
+ * parse, or falls back, warns once, as useStoredField's does: an unparsable one reads as the
+ * current default. A raw value the group itself wrote does not warn (a write chained after
+ * another field's in one event may fall back at once). `resetAll(method = 'replace')` removes
+ * every field's key in one write.
+ *
+ * Each field runs its kind's hook with the definition in its outside form (the group's value and
+ * writer), with the group's context as its field context, so its controls are the kind's own,
+ * and a request goes through the kind's own checks before it is kept. The hooks run per field,
+ * so the ids and kinds, in order, are kept from the first render, and so is the storage: a list
+ * of another shape, or another `stored`, throws (remount the component running the group, with a
+ * React `key`, to swap lists). The definitions' contents may change, and new objects of the same
+ * shape on every render (inline literals) are fine.
+ *
+ * A field's shown value, in `values` and as passed to its kind's hook, keeps its identity while it
+ * stays equal (element by element, as useStoredField's does), so a list does not become a new array
+ * on every render; the `values` object keeps its identity until a shown value changes, so an
+ * effect keyed on it (one that loads data, say, and feeds the app's field context) runs only
+ * then. A kind's own controls may still rebuild a composite value: range's `[from, to]` pair is
+ * put in order and within bounds anew on every render.
+ */
+export function useFieldGroup(definitions, options = {}) {
+    const stored = options.stored === true;
+    const appCtx = useFieldContext();
+    const shape = shapeOf(definitions);
+    const firstRef = useRef({ shape, stored });
+    const first = firstRef.current;
+    if (stored !== first.stored) {
+        throw new Error(`${WHERE}: the storage changed from ${storageOf(first.stored)} to ${storageOf(stored)}; a group runs `
+            + 'other hooks for each, so it keeps its storage across renders: to switch, remount the component running it with a React `key`');
+    }
+    if (shape !== first.shape) {
+        throw new Error(`${WHERE}: the fields changed from ${first.shape} to ${shape}; a group runs hooks per field, so it `
+            + 'keeps the same ids and kinds, in order, across renders: to swap lists, remount the component running it with a React `key`');
+    }
+    const shownRef = useRef(new Map());
+    const valuesRef = useRef(undefined);
+    // The storage is the first render's (checked above), so the hooks it runs stay the same.
+    const keeping = stored ? useStoredValues(definitions, appCtx) : useOwnState(definitions, appCtx);
+    const group = createGroupValues({ definitions, appCtx, kept: keeping.kept, warn: keeping.warn });
+    const previous = shownRef.current;
+    const shown = new Map();
+    for (const { id } of definitions) {
+        const value = group.valueOf(id);
+        shown.set(id, previous.has(id) && sameValue(previous.get(id), value) ? previous.get(id) : value);
+    }
+    shownRef.current = shown;
+    // The previous object while every shown value is the previous one (kept above while it stays
+    // equal): a host's effect keyed on `values` runs when a value changes, not on every render.
+    const unchanged = valuesRef.current !== undefined
+        && definitions.every(({ id }) => previous.has(id) && Object.is(previous.get(id), shown.get(id)));
+    const values = unchanged ? valuesRef.current : Object.fromEntries(shown);
+    valuesRef.current = values;
+    // One kind hook per definition, in order; the shape check above keeps the hooks' order.
+    const fields = definitions.map((definition) => {
+        const { initialValue: _default, ...outside } = definition;
+        const { onChange, hrefFor } = keeping.outside(definition, group);
+        return withFieldContext(group.ctx, () => useKindField(definition, {
+            ...outside, value: shown.get(definition.id), onChange, hrefFor,
+        }));
+    });
+    const changed = new Set(definitions.filter((d) => !showsDefault(d, keeping.kept(d.id), group)).map((d) => d.id));
+    const isDefault = (id) => {
+        if (!shown.has(id)) {
+            throw new Error(`${WHERE}: no field '${id}' in the group (fields: ${definitions.map((d) => d.id).join(', ')})`);
+        }
+        return !changed.has(id);
+    };
+    return {
+        fields,
+        byId: Object.fromEntries(definitions.map((d, i) => [d.id, fields[i]])),
+        values,
+        isDefault,
+        changedCount: changed.size,
+        resetAll: keeping.resetAll,
+    };
+}
+//# sourceMappingURL=useFieldGroup.js.map

package/dist/useFieldGroup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFieldGroup.js","sourceRoot":"","sources":["../src/useFieldGroup.ts"],"names":[],"mappings":"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"}

package/dist/useOneOfTreeField.d.ts

@@ -0,0 +1,79 @@
+import { type FieldControls, type FieldOptions } from './field.js';
+import { type OneOfChoiceControls } from './choices.js';
+import { type FieldCtx } from './FieldContext.js';
+import { type TreeChoose, type TreeExpand, type TreeNode } from './tree.js';
+import type { ErrorRoutesRegistry, ValueOrFn } from './types.js';
+export type OneOfTreeOwnOptions<T extends string = string, Ctx = any> = {
+    /** The roots, each with its children; static or derived (a function, of the field context if it declares a parameter). */
+    nodes: ValueOrFn<TreeNode<T>[], Ctx>;
+    /** Which nodes may be chosen; default 'any' (see TreeChoose). */
+    choose?: TreeChoose;
+    /** Whether the value may be empty (''), nothing chosen; default false (as oneOf, never empty). */
+    optional?: boolean;
+    /** Which nodes a widget opens at first; default 'selected' (the value's ancestors; see TreeExpand). */
+    expand?: TreeExpand;
+};
+export type OneOfTreeFieldOptions<T extends string = string, RouteId extends string = string, Ctx = any> = FieldOptions<T | '', T | '', RouteId, Ctx> & OneOfTreeOwnOptions<T, Ctx>;
+/** A tree node as the one-of tree's widgets get it: the resolved choice, its children likewise, and whether it may be chosen, is the value, or an ancestor of it. */
+export interface OneOfTreeNodeControls<T extends string = string> extends OneOfChoiceControls<T> {
+    children: OneOfTreeNodeControls<T>[] | undefined;
+    /** Whether the field may choose this node under `choose` (see canChooseNode). */
+    choosable: boolean;
+    /** It is the value. */
+    current: boolean;
+    /** An ancestor of the value (not the value itself). */
+    onPath: boolean;
+}
+export interface OneOfTreeFieldControls<T extends string = string> extends FieldControls<T | '', T | ''> {
+    /** The roots as the widgets get them, each with its children. */
+    nodes: OneOfTreeNodeControls<T>[];
+    /** Every node, by its value. */
+    byValue: Map<T, OneOfTreeNodeControls<T>>;
+    /** The chosen node, or undefined (the value is empty, or names no node). */
+    current: OneOfTreeNodeControls<T> | undefined;
+    /** The nodes from the root down to `current`, inclusive; empty when there is none. */
+    path: OneOfTreeNodeControls<T>[];
+    /**
+     * The choosable node just before `current` in tree pre-order — by `current`'s own position,
+     * not its position among the choosable nodes, so a `current` that cannot itself be chosen
+     * (a value naming a folder, or a node a context change disabled) still gets its true
+     * neighbours. Undefined at the start, and with no `current`.
+     */
+    previous: OneOfTreeNodeControls<T> | undefined;
+    /** The choosable node just after `current` in tree pre-order, by the same rule; with no `current`, the first choosable node. */
+    next: OneOfTreeNodeControls<T> | undefined;
+    optional: boolean;
+    choose: TreeChoose;
+    /** The nodes a widget opens at first (from `expand`). */
+    expandedKeys: T[];
+    /** Requests ''; refused (with a warning) unless `optional`, as `setValue('')` would be. */
+    clear(): void;
+}
+/**
+ * The implicit initial value for a one-of tree field: `initialValue` resolved through the field
+ * context, else '' when `optional`, else the first node `canChooseNode` accepts in tree
+ * pre-order, else '' (no node can be chosen; as oneOf's undefined choice).
+ */
+export declare function oneOfTreeInitialValue<T extends string>(opts: {
+    initialValue?: ValueOrFn<T | ''>;
+    choose?: TreeChoose;
+    optional?: boolean;
+}, ctx: FieldCtx, id: string, nodes: TreeNode<T>[]): T | '';
+/**
+ * A field whose value is a single tree node, or nothing (Praeceptor's category picker, a
+ * table of contents): `choosable` (a per-node flag, default true; a folder) and the field's
+ * `choose: 'any' | 'leaves'` together say which nodes `setValue` accepts (canChooseNode);
+ * `optional` says whether '' (nothing chosen) is one of them too. `setValue` refuses, with a
+ * warning (as useOneOfField refuses a disabled choice): a value naming no node, a node
+ * `canChooseNode` rejects, and '' unless `optional`. `clear()` requests ''. The field's current
+ * state is the chosen node's description, unless `valueDescriptions` words it differently (as
+ * oneOf). `previous` / `next` are the choosable nodes just before and after `current`'s own
+ * position in tree pre-order (so a `current` that cannot itself be chosen still gets its true
+ * neighbours, skipping only the nodes between them that cannot be chosen); with no `current`,
+ * `previous` is undefined and `next` is the first choosable node. `expandedKeys` (from `expand`,
+ * default `'selected'`) are the value's ancestors,
+ * so a table of contents opens where the reader is. Inside the field the value starts at
+ * `oneOfTreeInitialValue`.
+ */
+export declare function useOneOfTreeField<T extends string = string, RouteId extends string = string, Ctx = any>(opts: OneOfTreeFieldOptions<T, RouteId, Ctx>, registry?: ErrorRoutesRegistry<RouteId>): OneOfTreeFieldControls<T>;
+//# sourceMappingURL=useOneOfTreeField.d.ts.map

package/dist/useOneOfTreeField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOneOfTreeField.d.ts","sourceRoot":"","sources":["../src/useOneOfTreeField.ts"],"names":[],"mappings":"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"}

package/dist/useOneOfTreeField.js

@@ -0,0 +1,117 @@
+import { useFieldCore } from './field.js';
+import { resolveChoice } from './choices.js';
+import { useFieldContext } from './FieldContext.js';
+import { resolveIn } from './resolve.js';
+import { canChooseNode, choosableValues, expandedTreeKeys, treePath, } from './tree.js';
+/**
+ * The implicit initial value for a one-of tree field: `initialValue` resolved through the field
+ * context, else '' when `optional`, else the first node `canChooseNode` accepts in tree
+ * pre-order, else '' (no node can be chosen; as oneOf's undefined choice).
+ */
+export function oneOfTreeInitialValue(opts, ctx, id, nodes) {
+    const resolved = resolveIn(opts.initialValue, undefined, ctx, `Field '${id}': option 'initialValue'`);
+    if (resolved !== undefined)
+        return resolved;
+    if (opts.optional)
+        return '';
+    return choosableValues(nodes, opts.choose ?? 'any')[0] ?? '';
+}
+/**
+ * A field whose value is a single tree node, or nothing (Praeceptor's category picker, a
+ * table of contents): `choosable` (a per-node flag, default true; a folder) and the field's
+ * `choose: 'any' | 'leaves'` together say which nodes `setValue` accepts (canChooseNode);
+ * `optional` says whether '' (nothing chosen) is one of them too. `setValue` refuses, with a
+ * warning (as useOneOfField refuses a disabled choice): a value naming no node, a node
+ * `canChooseNode` rejects, and '' unless `optional`. `clear()` requests ''. The field's current
+ * state is the chosen node's description, unless `valueDescriptions` words it differently (as
+ * oneOf). `previous` / `next` are the choosable nodes just before and after `current`'s own
+ * position in tree pre-order (so a `current` that cannot itself be chosen still gets its true
+ * neighbours, skipping only the nodes between them that cannot be chosen); with no `current`,
+ * `previous` is undefined and `next` is the first choosable node. `expandedKeys` (from `expand`,
+ * default `'selected'`) are the value's ancestors,
+ * so a table of contents opens where the reader is. Inside the field the value starts at
+ * `oneOfTreeInitialValue`.
+ */
+export function useOneOfTreeField(opts, registry) {
+    const ctx = useFieldContext();
+    const nodes = resolveIn(opts.nodes, [], ctx, `Field '${opts.id}': option 'nodes'`);
+    const choose = opts.choose ?? 'any';
+    const optional = opts.optional ?? false;
+    const inside = !opts.onChange && !opts.commit;
+    const initialValue = () => oneOfTreeInitialValue(opts, ctx, opts.id, nodes);
+    const field = useFieldCore('oneOfTree', inside ? { ...opts, initialValue } : opts, registry);
+    const valuePath = field.value ? treePath(nodes, field.value) : [];
+    const ancestors = new Set(valuePath);
+    const byValue = new Map();
+    const control = (node) => {
+        const controls = {
+            ...resolveChoice(opts.id, node),
+            children: undefined,
+            choosable: canChooseNode(node, choose),
+            current: node.value === field.value,
+            onPath: ancestors.has(node.value) && node.value !== field.value,
+        };
+        byValue.set(node.value, controls);
+        if (node.children)
+            controls.children = node.children.map(control);
+        return controls;
+    };
+    const nodeControls = nodes.map(control);
+    const current = field.value ? byValue.get(field.value) : undefined;
+    const pathControls = valuePath.map((v) => byValue.get(v));
+    // byValue's insertion order is the full tree's pre-order (control() visits a node before its
+    // children), so it doubles as "every node, choosable or not" for finding current's neighbours.
+    const fullOrder = [...byValue.keys()];
+    const nearestChoosable = (from, step) => {
+        for (let i = from; i >= 0 && i < fullOrder.length; i += step) {
+            const node = byValue.get(fullOrder[i]);
+            if (node.choosable)
+                return node;
+        }
+        return undefined;
+    };
+    const index = current ? fullOrder.indexOf(current.value) : -1;
+    const previous = nearestChoosable(index - 1, -1);
+    const next = nearestChoosable(index + 1, 1);
+    const setValue = (requested) => {
+        if (requested === '') {
+            if (!optional) {
+                console.warn(`Field '${opts.id}': '' is refused — the field is not optional`);
+                return;
+            }
+            field.setValue('');
+            return;
+        }
+        const node = byValue.get(requested);
+        if (!node) {
+            console.warn(`Field '${opts.id}': '${requested}' is not one of its nodes`);
+            return;
+        }
+        if (!node.choosable) {
+            if (!node.enabled) {
+                console.warn(`Field '${opts.id}': node '${requested}' is disabled — ${node.whyDisabled ?? '(no reason)'}`);
+            }
+            else {
+                console.warn(`Field '${opts.id}': node '${requested}' cannot be chosen`);
+            }
+            return;
+        }
+        field.setValue(requested);
+    };
+    return {
+        ...field,
+        valueDescription: field.valueDescription ?? current?.description,
+        setValue,
+        nodes: nodeControls,
+        byValue,
+        current,
+        path: pathControls,
+        previous,
+        next,
+        optional,
+        choose,
+        expandedKeys: expandedTreeKeys(nodes, field.value ? [field.value] : [], opts.expand ?? 'selected'),
+        clear: () => setValue(''),
+    };
+}
+//# sourceMappingURL=useOneOfTreeField.js.map