vultus-core 0.5.2 → 0.5.4

package/src/kinds.ts

@@ -3,13 +3,14 @@ import type { FieldBaseOptions, FieldKind } from './field.js';
 import type { FieldCtx } from './FieldContext.js';
 import { clamp, fit, resolveNumeric } from './numeric.js';
 import { resolveIn } from './resolve.js';
-import { normalizeTreeValue, type TreeNode } from './tree.js';
+import { choosableValues, normalizeTreeValue, type TreeNode } from './tree.js';
 import type { Fits, ValueOrFn } from './types.js';
 import { boolInitialValue, type useBoolField } from './useBoolField.js';
 import { manyOfInitialValue, type ManyOfOwnOptions, type useManyOfField } from './useManyOfField.js';
 import { mixedBoolInitialValue, type MixedBool, type useMixedBoolField } from './useMixedBoolField.js';
 import { numericInitialValue, type NumericOwnOptions, type useNumericField } from './useNumericField.js';
 import { oneOfInitialValue, type OneOfOwnOptions, type useOneOfField } from './useOneOfField.js';
+import { oneOfTreeInitialValue, type OneOfTreeOwnOptions, type useOneOfTreeField } from './useOneOfTreeField.js';
 import { rangeInitialValue, type NumberRange, type RangeOwnOptions, type useRangeField } from './useRangeField.js';
 import { textInitialValue, type TextOwnOptions, type useTextField } from './useTextField.js';
 import { manyOfTreeInitialValue, type ManyOfTreeOwnOptions, type useManyOfTreeField } from './useManyOfTreeField.js';
@@ -36,6 +37,7 @@ export type FieldDefinition<Ctx = any> =
   | Definition<'numeric', number, NumericOwnOptions<Ctx>, Ctx>
   | Definition<'range', NumberRange, RangeOwnOptions<Ctx>, Ctx>
   | Definition<'manyOfTree', string[], ManyOfTreeOwnOptions<string, Ctx>, Ctx>
+  | Definition<'oneOfTree', string, OneOfTreeOwnOptions<string, Ctx>, Ctx>
   | Definition<'text', string, TextOwnOptions, Ctx>;
 
 type DefinitionOf<K extends FieldKind> = Extract<FieldDefinition, { kind: K }>;
@@ -53,6 +55,7 @@ type DefinitionsFitTheirHooks = [
   Fits<DefinitionOf<'numeric'>, HookOptions<typeof useNumericField>>,
   Fits<DefinitionOf<'range'>, HookOptions<typeof useRangeField>>,
   Fits<DefinitionOf<'manyOfTree'>, HookOptions<typeof useManyOfTreeField>>,
+  Fits<DefinitionOf<'oneOfTree'>, HookOptions<typeof useOneOfTreeField>>,
   Fits<DefinitionOf<'text'>, HookOptions<typeof useTextField>>,
 ];
 
@@ -87,10 +90,11 @@ function nodesOf(definition: { id: string; nodes: ValueOrFn<TreeNode[]> }, ctx:
 /**
  * A definition's default: `initialValue` resolved with the field context, else its kind's
  * implicit initial value (false; the first enabled choice; the empty list; `min`, or 0, clamped
- * into the bounds; `[min, max]`; the empty string). A tree's comes normalized under its
+ * into the bounds; `[min, max]`; the empty string). A many-of tree's comes normalized under its
  * selection, as the hook shows it, so a value equal to what the field shows by default is equal
- * to the default too. It is what a store falls back to, what a reset restores, and what "is it
- * set?" compares against; the kind's hook starts at the same value.
+ * to the default too; a one-of tree's is `''` when `optional`, else the first node it can choose
+ * in pre-order, else `''` (none can be chosen). It is what a store falls back to, what a reset
+ * restores, and what "is it set?" compares against; the kind's hook starts at the same value.
  */
 export function initialValueOf(definition: FieldDefinition, ctx: FieldCtx): unknown {
   const { id } = definition;
@@ -103,6 +107,7 @@ export function initialValueOf(definition: FieldDefinition, ctx: FieldCtx): unkn
     case 'range': return rangeInitialValue(definition, ctx, id);
     case 'manyOfTree':
       return normalizeTreeValue(nodesOf(definition, ctx), manyOfTreeInitialValue(definition, ctx, id), definition.selection ?? 'topmost');
+    case 'oneOfTree': return oneOfTreeInitialValue(definition, ctx, id, nodesOf(definition, ctx));
     case 'text': return textInitialValue(definition, ctx, id);
     default: return unknownKind(definition);
   }
@@ -113,6 +118,7 @@ export function valueTypeOf(kind: FieldKind): ValueType<any> {
   switch (kind) {
     case 'boolean': return booleanType;
     case 'oneOf':
+    case 'oneOfTree':
     case 'text': return stringType;
     case 'manyOf':
     case 'manyOfTree': return stringSetType;
@@ -132,16 +138,19 @@ function warnDropped(id: string, among: 'choices' | 'nodes', dropped: string[],
 /**
  * A stored value (already parsed by the kind's value type) made fit for the definition as it is
  * now: choices, nodes and bounds follow the data, and an old URL may not. A one-of value that is
- * not a choice becomes the initial value; many-of and tree values that are not choices or nodes
- * are dropped; numbers and ranges are clamped into the bounds, then rounded when the field is
- * `integer` (so a stored `2.5` reads `3`; a whole number inside the bounds, see `fit`), with one
- * warning for whichever of the two actually changed the value: "outside its bounds" when
- * clamping did (whether or not rounding also did), "not a whole number" ("has ends that are not
- * whole numbers" for a range) when only rounding did. Each such change warns, naming the
- * field: the value came from outside, so it is not an error. Reordering is silent: lists come
- * back in choice order or normalized under the tree's selection (a store keeps them sorted, so a
- * warning would come on every read), and a range's ends in order. The warnings go to `warn`,
- * console.warn unless a caller that only summarizes (useStoredFields) silences them.
+ * not a choice becomes the initial value; many-of values that are not choices or nodes are
+ * dropped. A one-of tree value is replaced by the initial value too, when it names no node, when
+ * the node it names cannot be chosen (a folder, or one a context change disabled), or when it is
+ * `''` and the field is not optional. Numbers and ranges are clamped into the bounds, then
+ * rounded when the field is `integer` (so a stored `2.5` reads `3`; a whole number inside the
+ * bounds, see `fit`), with one warning for whichever of the two actually changed the value:
+ * "outside its bounds" when clamping did (whether or not rounding also did), "not a whole
+ * number" ("has ends that are not whole numbers" for a range) when only rounding did. Each such
+ * change warns, naming the field: the value came from outside, so it is not an error. Reordering
+ * is silent: lists come back in choice order or normalized under the tree's selection (a store
+ * keeps them sorted, so a warning would come on every read), and a range's ends in order. The
+ * warnings go to `warn`, console.warn unless a caller that only summarizes (useStoredFields)
+ * silences them.
  */
 export function sanitizeStored(
   definition: FieldDefinition,
@@ -176,6 +185,21 @@ export function sanitizeStored(
       warnDropped(id, 'nodes', stored.filter((v) => !known.has(v)), warn);
       return normalizeTreeValue(nodes, stored.filter((v) => known.has(v)), definition.selection ?? 'topmost');
     }
+    case 'oneOfTree': {
+      const stored = value as string;
+      const nodes = nodesOf(definition, ctx);
+      if (stored === '') {
+        if (definition.optional ?? false) return stored;
+        const fallback = oneOfTreeInitialValue(definition, ctx, id, nodes);
+        if (fallback !== stored) warn(`Field '${id}': stored value '' is empty but the field is not optional, using '${fallback}'`);
+        return fallback;
+      }
+      if (choosableValues(nodes, definition.choose ?? 'any').includes(stored)) return stored;
+      const fallback = oneOfTreeInitialValue(definition, ctx, id, nodes);
+      const reason = nodeValues(nodes).has(stored) ? 'cannot be chosen' : 'names no node';
+      if (fallback !== stored) warn(`Field '${id}': stored value '${stored}' ${reason}, using '${fallback}'`);
+      return fallback;
+    }
     case 'numeric': {
       const stored = value as number;
       const { min, max, integer } = resolveNumeric(id, definition, ctx);

package/src/tree.ts

@@ -5,6 +5,8 @@ import { normalizeText } from './normalizeText.js';
 /** A node of a tree field (Praeceptor's categories): a choice with children. */
 export interface TreeNode<T extends string = string> extends OneOfChoice<T> {
   children?: TreeNode<T>[];
+  /** Whether the one-of tree may choose this node (default true); a folder when false. Ignored by the many-of tree. */
+  choosable?: boolean;
 }
 
 /** A node as the widgets get it: the resolved choice, its children likewise, and whether it shows checked. */
@@ -224,3 +226,35 @@ export function filterTree<N extends { label?: string; value: string; children?:
   });
   return keep(nodes, false);
 }
+
+/**
+ * Which nodes the one-of tree field may choose: `'any'` node, or only `'leaves'` (a node with
+ * no children).
+ */
+export type TreeChoose = 'any' | 'leaves';
+
+/**
+ * Whether the one-of tree field may choose `node` under `choose` (see TreeChoose): choosable
+ * (its `choosable` is not `false`), enabled (as nodeEnabled resolves it), and, under `'leaves'`,
+ * has no children.
+ */
+export function canChooseNode(node: TreeNode, choose: TreeChoose): boolean {
+  if (node.choosable === false) return false;
+  if (!nodeEnabled(node)) return false;
+  return choose !== 'leaves' || !hasChildren(node);
+}
+
+/** The values canChooseNode accepts, in tree pre-order. */
+export function choosableValues<T extends string>(nodes: TreeNode<T>[], choose: TreeChoose): T[] {
+  const { order } = indexTree(nodes);
+  return order.filter((node) => canChooseNode(node, choose)).map((node) => node.value);
+}
+
+/** The values from the root down to `value` inclusive, in tree order; `[]` when no node has it. */
+export function treePath<T extends string>(nodes: TreeNode<T>[], value: T): T[] {
+  const { order, parent } = indexTree(nodes);
+  if (!order.some((node) => node.value === value)) return [];
+  const path: T[] = [value];
+  for (let up = parent.get(value); up !== undefined; up = parent.get(up)) path.unshift(up);
+  return path;
+}

package/src/useArg.ts

@@ -22,8 +22,12 @@ export interface ArgControls<T> {
   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. */
-function rawFor<T>(value: T, defaultValue: T, valueType: ValueType<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 function rawFor<T>(value: T, defaultValue: T, valueType: ValueType<T>): string | undefined {
   return valueType.isEqual(value, defaultValue) ? undefined : valueType.format(value);
 }
 

package/src/useFieldGroup.ts

@@ -0,0 +1,346 @@
+import { useCallback, useRef, useState, useSyncExternalStore } from 'react';
+import type { ArgStore, UpdateMethod } from './argStore.js';
+import { useArgStore } from './ArgStoreContext.js';
+import type { FieldControls } from './field.js';
+import { useFieldContext, withFieldContext, type FieldCtx } from './FieldContext.js';
+import { createGroupValues, type GroupValues } from './fieldGroupValues.js';
+import { useKindField } from './kindHooks.js';
+import { valueTypeOf, type FieldDefinition } from './kinds.js';
+import { rawFor } from './useArg.js';
+import { sameValue } from './useStoredField.js';
+import type { ValueType } from './valueTypes.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;
+}
+
+/** The values the group keeps, by field id; a field without one shows its current default. */
+type Kept = Readonly<Record<string, unknown>>;
+
+const NOTHING_KEPT: Kept = {};
+const WHERE = 'Field group';
+
+function silently(_id: string, _message: string): void {}
+
+/** A field's kept value in `kept`, or `undefined` for none (an id such as `toString` is not Object's member). */
+function keptIn(kept: Kept): (id: string) => unknown {
+  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: readonly FieldDefinition[]): string {
+  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: boolean): string {
+  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: FieldDefinition, kept: unknown, group: GroupValues): boolean {
+  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: readonly FieldDefinition[], appCtx: FieldCtx, kept: (id: string) => unknown, id: string,
+): unknown {
+  return createGroupValues({ definitions, appCtx, kept, warn: silently }).defaultOf(id);
+}
+
+/** A field's writer and link, as its kind's hook takes them (the outside form's `onChange` and `hrefFor`). */
+interface Outside {
+  onChange(value: unknown): void;
+  hrefFor?(value: unknown): string | undefined;
+}
+
+/** Where a group keeps its values (its own state, or the nearest ArgStore), as one render sees them. */
+interface Keeping {
+  /** A field's kept value; `undefined` for none, so the field shows its current default. */
+  kept(id: string): unknown;
+  /** Where a kept value's sanitizing warnings go, with the field's id (see createGroupValues). */
+  warn(id: string, message: string): void;
+  /** A field's writer and link, given this render's values. */
+  outside(definition: FieldDefinition, group: GroupValues): Outside;
+  /** Every field back to its default (see FieldGroup). */
+  resetAll(method?: UpdateMethod): void;
+}
+
+/**
+ * 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: readonly FieldDefinition[], appCtx: FieldCtx): Keeping {
+  const [kept, setKept] = useState<Kept>(NOTHING_KEPT);
+  const resetAll = useCallback(() => setKept((state) => (Object.keys(state).length === 0 ? state : NOTHING_KEPT)), []);
+
+  const write = ({ id, kind }: FieldDefinition) => (value: unknown) => 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 }: FieldDefinition): ValueType<any> {
+  try {
+    return valueTypeOf(kind);
+  } catch (error) {
+    throw new Error(`Field '${id}': ${(error as 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: FieldDefinition, raw: string | undefined): unknown {
+  return raw === undefined ? undefined : valueTypeFor(definition).parse(raw);
+}
+
+/** A field's link, with what it was made from: kept while those stay the same, so the controls' `hrefFor` keeps its identity. */
+interface Link {
+  store: ArgStore;
+  defaultValue: unknown;
+  hrefFor(value: unknown): string | undefined;
+}
+
+/**
+ * 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: readonly FieldDefinition[], appCtx: FieldCtx): Keeping {
+  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: () => void) => 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) as (string | null)[];
+  const raws = new Map(ids.map((id, i) => [id, rawList[i]]));
+
+  const seenRef = useRef(new Map<string, string | null>());
+  /** The raw value the group itself last wrote for a field, until the next render reads the store. */
+  const writtenRef = useRef(new Map<string, string | undefined>());
+  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<string>();
+  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: string, message: string) => {
+    if (fresh.delete(id)) console.warn(message);
+  };
+
+  const byId = new Map(definitions.map((definition) => [definition.id, definition]));
+  const parsed = new Map<string, unknown>();
+  const kept = (id: string) => {
+    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: string) => defaultUnder(definitions, appCtx, (key) => parseRaw(byId.get(key)!, store.read(key)), id);
+
+  const linksRef = useRef(new Map<string, Link>());
+  const outside = (definition: FieldDefinition, group: GroupValues): Outside => {
+    const { id } = definition;
+    const valueType = valueTypeFor(definition);
+    const onChange = (value: unknown) => {
+      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: UpdateMethod = '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: readonly FieldDefinition[], options: { stored?: boolean } = {}): FieldGroup {
+  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<string, unknown>());
+  const valuesRef = useRef<Readonly<Record<string, unknown>> | undefined>(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<string, unknown>();
+  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: string) => {
+    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,
+  };
+}