vultus-core 0.5.3 → 0.5.4

package/src/fieldGroupValues.ts

@@ -0,0 +1,169 @@
+import { extendFieldContext, guardKeys, MissingKeyError, type FieldCtx } from './FieldContext.js';
+import { initialValueOf, sanitizeStored, type FieldDefinition } from './kinds.js';
+
+/**
+ * One render's values of a field group (see useFieldGroup): each field's shown value and
+ * default, computed on demand by id from the kept values, with the definitions' options
+ * evaluated in the group's context, and each computed once.
+ */
+export interface GroupValues {
+  /**
+   * The field context the group's option functions receive: the app's own keys (guarded as a
+   * provider's value is) and `values`, the fields' shown values by id.
+   */
+  ctx: object;
+  /**
+   * A field's shown value: its kept value, else its current default, made fit for its options
+   * as they are now (sanitizeStored); one that no longer fits shows the field's fallback. The
+   * kept value itself is never touched, so it shows again once it fits again.
+   */
+  valueOf(id: string): unknown;
+  /**
+   * A field's default: its `initialValue` (which cannot read `values`), else its kind's
+   * implicit initial value from its options as they are now (the first enabled choice, `min`,
+   * ...), so it moves with the fields those options read.
+   */
+  defaultOf(id: string): unknown;
+  /** The shown values by id, each computed when first read; `ctx.values` is the same object. */
+  values: Readonly<Record<string, unknown>>;
+}
+
+/** What createGroupValues computes the values from. */
+export interface GroupValuesParams {
+  /** The group's fields, as data: unique ids, no mixed-boolean. */
+  definitions: readonly FieldDefinition[];
+  /** The app's field context (useFieldContext), which `values` is added to. */
+  appCtx: FieldCtx;
+  /** A field's kept value; `undefined` when none is kept, so the field shows its current default. */
+  kept(id: string): unknown | undefined;
+  /**
+   * Where a kept value's sanitizing warnings go, with the field's id: the caller decides whether
+   * to show them (and how often). A default made fit is the definer's, not kept input, so it
+   * never warns.
+   */
+  warn(id: string, message: string): void;
+}
+
+const WHERE = 'Field group';
+const INITIAL_VALUE_READS_VALUES = "initialValue cannot read other fields' values";
+const NOT_IN_A_GROUP = 'a mixed-boolean field shows an aggregate of other data, not a value of its own, so it cannot be in a field group';
+
+function silently(_message: string): void {}
+
+/**
+ * A definition as its values are computed from it. Its `initialValue` function receives
+ * `initialCtx`, whose `values` throws: a default cannot depend on other fields' values. A
+ * number's or range's display options (`step`, `unit`, `format`) are left out, because resolving
+ * its bounds (resolveNumeric) resolves them too, and an option that never affects the value
+ * (`unit: (ctx) => ctx.values.copies === 1 ? ...`) must not count as a dependency, nor form a
+ * cycle.
+ */
+function forComputingValues(definition: FieldDefinition, initialCtx: object): FieldDefinition {
+  const computing = { ...definition };
+  const { initialValue } = definition;
+  if (typeof initialValue === 'function') {
+    Object.assign(computing, { initialValue: () => (initialValue as (ctx: object) => unknown)(initialCtx) });
+  }
+  if (computing.kind === 'numeric' || computing.kind === 'range') {
+    delete computing.step;
+    delete computing.unit;
+    delete computing.format;
+  }
+  return computing;
+}
+
+/**
+ * The values of a field group for one render, computed from its definitions and kept values.
+ *
+ * Every option function of the definitions receives `ctx`: the app's field context and
+ * `values`, the fields' shown values by id. A field's value is computed when an option (or the
+ * caller) first reads it, and kept for the rest of this snapshot; a new render makes a new one.
+ * The shown value is the kept value (else the current default) checked against the field's
+ * options as they are now, as a store's value is (sanitizeStored); one that no longer fits
+ * shows the fallback, which the other fields see too.
+ *
+ * Throws here for two definitions with the same id and for a mixed-boolean definition (naming
+ * the field), and for an app context that already has `values`. Throws when read, naming the
+ * field and the option, for an option reading an id not in the group and for `initialValue`
+ * reading `values`. Fields whose values depend on each other throw when read, naming the cycle
+ * (`Fields 'a' -> 'b' -> 'a' depend on each other's values`): a field's value and default are in
+ * progress while its options run, and reading one in progress is a cycle. Options that never
+ * affect a value (`visible`, `label`, `unit`, ...) are not run here, so they cannot form one.
+ */
+export function createGroupValues({ definitions, appCtx, kept, warn }: GroupValuesParams): GroupValues {
+  const ids = definitions.map((definition) => definition.id);
+  for (const definition of definitions) {
+    if (ids.indexOf(definition.id) !== ids.lastIndexOf(definition.id)) {
+      throw new Error(`Field '${definition.id}': another field in the group has the same id`);
+    }
+    if (definition.kind === 'mixed-boolean') throw new Error(`Field '${definition.id}': ${NOT_IN_A_GROUP}`);
+  }
+  const noField = (id: string) => `no field '${id}' in the group (fields: ${ids.join(', ')})`;
+
+  const getters: Record<string, unknown> = {};
+  for (const id of ids) Object.defineProperty(getters, id, { get: () => valueOf(id), enumerable: true });
+  // Own keys only: `values.toString` is a typo for an id, not Object's member. `constructor`
+  // reads as usual, as the probes do, because printers (vitest's) name an object by it.
+  const values = guardKeys(getters, noField, (target, key) => key === 'constructor' || Object.hasOwn(target, key)) as
+    Readonly<Record<string, unknown>>;
+  const ctx = extendFieldContext(appCtx, { values }, WHERE);
+  // `values` not enumerable: a missing key's message lists the keys provided, and this one only throws.
+  const initialCtx = extendFieldContext(appCtx, Object.defineProperty<Record<string, unknown>>({}, 'values', {
+    get(): never {
+      throw new MissingKeyError(INITIAL_VALUE_READS_VALUES);
+    },
+  }), WHERE);
+  const computingDefinitions = new Map(definitions.map((definition) => [definition.id, forComputingValues(definition, initialCtx)]));
+
+  const shown = new Map<string, unknown>();
+  const defaults = new Map<string, unknown>();
+  /** The fields whose value or default is being computed, outermost first. */
+  const inProgress: string[] = [];
+
+  function definitionOf(id: string): FieldDefinition {
+    const definition = computingDefinitions.get(id);
+    if (definition === undefined) throw new MissingKeyError(noField(id));
+    return definition;
+  }
+
+  /** Runs `compute` with `id` in progress; reading `id` again before it returns is a cycle. */
+  function computing<T>(id: string, compute: () => T): T {
+    const at = inProgress.indexOf(id);
+    if (at !== -1) {
+      const cycle = [...inProgress.slice(at), id].map((each) => `'${each}'`).join(' -> ');
+      throw new Error(`Fields ${cycle} depend on each other's values`);
+    }
+    inProgress.push(id);
+    try {
+      return compute();
+    } finally {
+      inProgress.pop();
+    }
+  }
+
+  /** The default, computed as part of `id`'s own value or default (already in progress). */
+  function ownDefault(id: string): unknown {
+    if (!defaults.has(id)) defaults.set(id, initialValueOf(definitionOf(id), ctx));
+    return defaults.get(id);
+  }
+
+  function defaultOf(id: string): unknown {
+    definitionOf(id);
+    return defaults.has(id) ? defaults.get(id) : computing(id, () => ownDefault(id));
+  }
+
+  function valueOf(id: string): unknown {
+    const definition = definitionOf(id);
+    if (!shown.has(id)) {
+      shown.set(id, computing(id, () => {
+        const value = kept(id);
+        return value === undefined
+          ? sanitizeStored(definition, ownDefault(id), ctx, silently)
+          : sanitizeStored(definition, value, ctx, (message) => warn(id, message));
+      }));
+    }
+    return shown.get(id);
+  }
+
+  return { ctx, valueOf, defaultOf, values };
+}

package/src/index.ts

@@ -72,6 +72,7 @@ export {
 export {
   argOf, useStoredField, useStoredFields, type StoredField, type StoredFields,
 } from './useStoredField.js';
+export { useFieldGroup, type FieldGroup } from './useFieldGroup.js';
 export { InternalLinkContext, useInternalLink, type InternalLinkComponent } from './LinkContext.js';
 export { MessageSinkContext, useMessageSink, type MessageSink } from './MessageSink.js';
 export {

package/src/kindHooks.ts

@@ -0,0 +1,52 @@
+import type { FieldControls, FieldKind } from './field.js';
+import type { FieldDefinition } from './kinds.js';
+import { useBoolField } from './useBoolField.js';
+import { useManyOfField } from './useManyOfField.js';
+import { useManyOfTreeField } from './useManyOfTreeField.js';
+import { useMixedBoolField } from './useMixedBoolField.js';
+import { useNumericField } from './useNumericField.js';
+import { useOneOfField } from './useOneOfField.js';
+import { useOneOfTreeField } from './useOneOfTreeField.js';
+import { useRangeField } from './useRangeField.js';
+import { useTextField } from './useTextField.js';
+
+/**
+ * A definition in its outside form, as its kind's hook takes it: without `initialValue` (whoever
+ * keeps the value keeps its default too), with the value, its writer, and the link a value
+ * amounts to where whoever keeps it has one.
+ */
+export type KindFieldOptions = OutsideForm<FieldDefinition>;
+
+/** The outside form of a definition, member by member for a union (the conditional type distributes). */
+type OutsideForm<D> = D extends FieldDefinition
+  ? Omit<D, 'initialValue'> & { value: unknown; onChange(value: any): void; hrefFor?(value: any): string | undefined }
+  : never;
+
+/**
+ * Each kind's hook. Its options are checked against the definition in kinds.ts
+ * (DefinitionsFitTheirHooks); the mapped type makes leaving a kind out a compile error.
+ */
+const KIND_HOOKS: { [K in FieldKind]: (options: any) => FieldControls<any, any> } = {
+  boolean: useBoolField,
+  'mixed-boolean': useMixedBoolField,
+  oneOf: useOneOfField,
+  manyOf: useManyOfField,
+  numeric: useNumericField,
+  range: useRangeField,
+  manyOfTree: useManyOfTreeField,
+  oneOfTree: useOneOfTreeField,
+  text: useTextField,
+};
+
+/**
+ * Runs the hook of `definition`'s kind with `options` and returns its controls, exactly as that
+ * hook returns them. The hook called depends on the kind, so a caller running several fields
+ * (useFieldGroup) keeps each field's kind the same across renders. A kind that is none of
+ * FieldKind's (plain data can carry anything) throws, naming the field.
+ */
+export function useKindField(definition: FieldDefinition, options: KindFieldOptions): FieldControls<any, any> {
+  const { id, kind } = definition;
+  if (!Object.hasOwn(KIND_HOOKS, kind)) throw new Error(`Field '${id}': unknown kind '${String(kind)}'`);
+  const useHook = KIND_HOOKS[kind];
+  return useHook(options);
+}

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,
+  };
+}

package/src/useStoredField.ts

@@ -32,9 +32,11 @@ function warnOnConsole(message: string): void {
 /**
  * The same value element by element: a list in the same order, a range with the same ends, a
  * scalar. Stricter than the value types' `isEqual` (lists as sets), because the order a field
- * shows (choice order, tree order) matters to the identity kept below.
+ * shows (choice order, tree order) matters to the identity kept below. Exported for the field
+ * group (useFieldGroup), which keeps its values' identity by the same rule; not part of the
+ * package's API.
  */
-function sameValue(a: unknown, b: unknown): boolean {
+export function sameValue(a: unknown, b: unknown): boolean {
   if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => v === b[i]);
   return a === b;
 }