vultus-core 0.5.2 → 0.5.4

package/README.md

@@ -31,7 +31,8 @@ npm install vultus-core
   `initialValueOf`, `valueTypeOf`, `sanitizeStored`); the argument layer
   (the value types, `memoryStore`, `localStorageStore`, `ArgStoreProvider` /
   `useArgStore`, `useArg`, `useArgWriter`, `setArg` / `resetArg`, `argOf`,
-  `useStoredField` / `useStoredFields`); `InternalLinkContext` /
+  `useStoredField` / `useStoredFields`); field groups (`useFieldGroup` and
+  its `FieldGroup` type); `InternalLinkContext` /
   `useInternalLink` / `InternalLinkComponent`, `MessageSinkContext` /
   `useMessageSink` / `MessageSink`, and `VultusComponentsContext` /
   `useVultusComponents` / `SpinnerScope` / `useSpinnerKey` /
@@ -257,6 +258,12 @@ its descendants matches (with only the children that stay), and the rest
 is trimmed, leaving the nodes given unchanged. Implicit initial value: the
 empty list.
 
+A `TreeNode`'s `choosable` (default `true`; a folder when `false`) is for the one-of tree, below;
+this hook ignores it, so one node list can feed both kinds. Its helpers: `canChooseNode(node,
+choose)` (choosable, enabled, and, under `choose: 'leaves'`, no children), `choosableValues(nodes,
+choose)` (the values it accepts, in pre-order) and `treePath(nodes, value)` (the values from the
+root down to `value`, inclusive; `[]` when no node has it).
+
 ```ts
 const field = useManyOfTreeField({
   id: 'categories',
@@ -265,6 +272,39 @@ const field = useManyOfTreeField({
 field.toggle('a'); // field.value === ['a'] — 'topmost' collapses the subtree to the parent
 ```
 
+### one-of tree (`useOneOfTreeField`)
+
+The value is a single node id (`nodes`, the many-of tree's `TreeNode`), or `''` meaning nothing
+chosen (Praeceptor's category picker, a table of contents). A node is choosable when its own
+`choosable` is not `false` (a folder — a part heading with no page, a category group — is
+`choosable: false`; the many-of tree ignores it, so one node list can feed both kinds), it is
+enabled, and, under `choose: 'leaves'` (default `'any'`), has no children (`canChooseNode`,
+`choosableValues`, `treePath` — see many-of tree, above). `setValue` refuses, with a warning (as
+`useOneOfField` refuses a disabled choice): a value naming no node, a node that cannot be
+chosen, and `''` unless `optional` (default `false`, as `oneOf`'s value is never empty); `clear()`
+requests `''`. Controls add `nodes` (each with `choosable`, `current` — it is the value — and
+`onPath` — an ancestor of it) and `byValue`, as the many-of tree's; `current` (the chosen node, or
+undefined when the value is empty or names no node), `path` (the nodes from the root down to
+`current`, inclusive; empty when there is none), `previous` / `next` (the choosable nodes just
+before and after `current`'s own position in tree pre-order — so a `current` that cannot itself
+be chosen, e.g. a value naming a folder or a node a context change disabled, still gets its true
+neighbours; undefined at the ends, and with no `current`, `previous` undefined and `next` the
+first choosable node), `optional`, `choose` and `expandedKeys`
+(from `expand`, default `'selected'` — the value's ancestors, so a table of contents opens where
+the reader is; `'top'`, `'none'` and `'all'` as the many-of tree's). The field's current state is
+the chosen node's description, unless `valueDescriptions` words it differently (as `oneOf`).
+Implicit initial value: `initialValue`, else `''` when `optional`, else the first node that can be
+chosen in tree pre-order, else `''` (no node can be chosen; as `oneOf`'s undefined choice).
+
+```ts
+const field = useOneOfTreeField({
+  id: 'category',
+  nodes: [{ value: 'geo', choosable: false, children: [{ value: 'sik' }, { value: 'ter' }] }],
+});
+field.value; // 'sik' — the first node that can be chosen ('geo' is a folder)
+field.next?.value; // 'ter'
+```
+
 ### text (`useTextField`)
 
 The value is a string. `control: 'input' | 'textarea'` (default `'input'`)
@@ -285,7 +325,7 @@ const field = useTextField({ id: 'search', control: 'input' });
 A `FieldDefinition` is a field's options in their "inside" form (no `value`
 plus `onChange` or `commit`), tagged with a required `kind` — one of
 `'boolean'`, `'mixed-boolean'`, `'oneOf'`, `'manyOf'`, `'numeric'`,
-`'range'`, `'manyOfTree'`, `'text'` (the same strings `FieldControls.type` already
+`'range'`, `'manyOfTree'`, `'oneOfTree'`, `'text'` (the same strings `FieldControls.type` already
 carries). `kind` stays optional on each hook's own options — a hook knows
 its own kind, and throws if a definition names a different one — but is
 required once a field becomes plain data: a module declares its filters as a
@@ -333,7 +373,7 @@ b)`) say how a value is kept as a string and compared; equality is the
 type's own meaning (a list as a set, a range by both ends), used everywhere
 two values of that type are compared — including whether a value is the
 default, so it's left out of the store. `valueTypeOf(kind)` gives each field
-kind's: `booleanType` (`'1'` / `'0'`), `stringType` (one-of, text),
+kind's: `booleanType` (`'1'` / `'0'`), `stringType` (one-of, one-of tree, text),
 `stringSetType` (many-of, many-of tree — a sorted comma list; a *present but empty*
 value reads as the empty list, which differs from the key being absent
 altogether), `numberType`, `rangeType` (`from..to`). A mixed-boolean field
@@ -381,7 +421,9 @@ is the definition's `id`, its value type comes from the kind, its default
 is `initialValueOf`. It returns `{ options, isDefault, reset }` — `options`
 is the definition in its outside form (`value` plus `onChange`, ready for
 the kind's hook), with the stored raw value made to fit the definition as
-it is now (`sanitizeStored`: unknown choices or nodes dropped, numbers and
+it is now (`sanitizeStored`: unknown choices or nodes dropped; a one-of
+tree value naming no node, a folder or a node it cannot choose, or `''`
+when the field is not optional, replaced by the initial value; numbers and
 ranges clamped, and rounded when `integer`). A value that needed fixing up
 warns once per field and per raw value — not again on every render, and not
 at all when the key is simply absent (then the default applies, and an
@@ -392,6 +434,21 @@ definitions), `changedCount`, and `resetAll(method)` (one write for every
 field). Being a summary, it never warns — only `useStoredField` on the
 field itself does.
 
+**Links.** Every kind's hook gives its controls `hrefFor(value)`: the link that requesting `value`
+amounts to, or `undefined` where nothing gives one. With `value` + `onChange` or `value` +
+`commit`, the caller passes it; inside the field it is always `undefined` (an `hrefFor` passed
+anyway is ignored). `FieldControls` has it optional (`hrefFor?(value)`), so controls built by
+hand need none; a widget calls `field.hrefFor?.(value)`. `useStoredField` wires its own from the
+store (`useArg`'s `hrefFor`, itself from the store's), so a field stored over a URL store
+(vultus-react-router's) links each value it could be set to, e.g.
+`field.hrefFor?.(field.choices[0].value)` next to the field's own widget. A link built from
+`hrefFor` is as fresh as the render that built it: a URL that changes without re-rendering its
+component (another key of the query, the path) leaves it stale. Render an app's own links (a
+previous / next pair) in a component that re-renders on location changes (with react-router,
+one that calls `useLocation`), or compute them at interaction time (vultus-antd's
+`OneOfTreeList` asks again as the pointer enters a link, on its focus, a button press, its
+context menu, a modified click).
+
 ```tsx
 const store = memoryStore();
 
@@ -410,6 +467,121 @@ function Category() {
 }
 ```
 
+## Field groups
+
+A field's options sometimes depend on another field's value: a print dialog offers some paper
+sizes only for one layout, a filter shows a sub-filter only when another is on. With hooks, an
+option takes a value computed from the other field's controls. Definitions as data say it
+through the field context: `useFieldGroup(definitions)` runs a list of definitions together, and
+every option function of each one receives `ctx.values`, the group's values by field id.
+
+```tsx
+const printOptions: FieldDefinition[] = [
+  { kind: 'oneOf', id: 'layout', choices: [{ value: 'rendered' }, { value: 'original' }] },
+  { kind: 'oneOf', id: 'paper', choices: (ctx) => (ctx.values.layout === 'rendered' ? A_SIZES : ALL_SIZES) },
+  { kind: 'numeric', id: 'copies', min: 1, visible: (ctx) => ctx.values.layout === 'original' },
+];
+
+function PrintDialog() {
+  const group = useFieldGroup(printOptions);
+  return <>{group.fields.map((f) => <FieldWidget key={f.id} field={f} item />)}</>;
+}
+```
+
+It returns `fields`, each field's controls exactly as its kind's hook returns them, in definition
+order; `byId`, the same controls by id; `values`, the shown values by id as of this render (a
+plain object, which keeps its identity until a shown value changes, so an effect keyed on it runs
+only then); `isDefault(id)` (an id not in the group throws), `changedCount` and `resetAll()`
+("more filters (3)", "clear all"). The controls are typed `FieldControls`, which every widget
+takes; for a kind's own controls (a tree's `nodes`, numeric's `format`), cast by kind:
+`group.byId.toc as OneOfTreeFieldControls<string>`.
+
+**References.** Every option function of a group's definition receives `ctx.values` (`label`,
+`description`, `placeholder`, `visible` / `hidden`, `enabled` / `disabled`, `choices`, a tree's
+`nodes`, `min` / `max`, numeric's `format(n, ctx)`, ...), beside the keys of the app's own field
+context (the nearest `FieldContextProvider`), which keep working. A function the controls keep
+and call later (`format`, through `field.format(n)`) sees the group's values too. `initialValue`
+cannot read them. In a plain `FieldDefinition` the context is untyped (`any`); an app wanting
+`ctx.values` typed declares `values` in its context type (`FieldDefinition<Ctx>`,
+`createFieldContext<Ctx>()`).
+
+**The fallback rule.** A field's shown value is its kept value checked as a stored value is
+(`sanitizeStored`), with its options evaluated in the group's context. A value that another
+field's change made invalid (a paper size the layout no longer offers) shows the field's
+fallback, and the other fields see that fallback. Nothing is rewritten: the kept value shows
+again once it is valid again (the layout back). A hidden field keeps its value, and the others
+still see it.
+
+**Defaults follow the options.** A field's default is its `initialValue`, else its kind's
+implicit initial value from its options as they are now (the first enabled choice of its current
+`choices`, a tree's first choosable node, `min`, ...), so it moves with the fields those options
+read. A field never set, or set to its current default, keeps nothing and shows its current
+default as it moves. `isDefault(id)` is useStoredFields' rule: nothing kept, or the kept value or
+the value shown equals the current default.
+
+**Errors.** These fail loudly, naming the field and the option where there is one:
+
+- an option reading an id not in the group: `Field 'paper': option 'choices': no field 'layot'
+  in the group (fields: layout, paper, copies)`;
+- reading `ctx.values` outside a group, with a `FieldContextProvider` above: `... ctx.values is
+  only available inside a field group`; with none, a function declaring `ctx` gets the existing
+  `... is a function of the field context, but no FieldContextProvider is above it`;
+- `initialValue` reading `ctx.values`: `... initialValue cannot read other fields' values`;
+- fields whose values depend on each other (A's choices read B, and B's read A): `Fields 'a' ->
+  'b' -> 'a' depend on each other's values`. Options that never affect a value (`visible`,
+  `enabled`, `label`, `unit`, `format`, ...) cannot form a cycle;
+- two definitions with the same id; a mixed-boolean definition (it shows an aggregate of other
+  data, not a value of its own); an app field context that already has `values` (the group
+  would shadow it);
+- a list of another shape than the first render's. The hooks run per field, so the ids and kinds
+  stay the same, in the same order: to swap lists, remount the component running the group with
+  a React `key`. The definitions' contents may change, and new objects of the same shape on
+  every render (inline literals) are fine.
+
+**Storage**, for the whole group, is the runner's choice. By default the group keeps the values
+in its own state, as a store keeps them: a field without a kept value shows its current default,
+and a value set equal to it is not kept. A fallback is silent here, as it is the designed
+behaviour, not bad input. `resetAll()` clears every kept value.
+
+With `useFieldGroup(definitions, { stored: true })` the values live in the nearest `ArgStore`
+(the URL through vultus-react-router's `<ReactRouterArgStore>`, or localStorage) under each
+field's id, as `useStoredField` keeps a single field there, all read in one store subscription:
+
+```tsx
+const filters: FieldDefinition[] = [
+  { kind: 'text', id: 'search' },
+  { kind: 'oneOfTree', id: 'toc', optional: true, nodes: CHAPTERS, widget: 'list', visible: (ctx) => ctx.values.search === '' },
+];
+
+function Filters() {
+  const group = useFieldGroup(filters, { stored: true }); // ?search=...&toc=...
+  return <>{group.fields.map((f) => <FieldWidget key={f.id} field={f} />)}</>;
+}
+```
+
+An absent key reads as the field's current default, and a value equal to it is written as an
+absent key (with `'replace'`). The default compared with is the one under the store's values at
+the moment of the write (a store reads its own writes back at once), so, as in the group's own
+state, `layout.setValue('original'); paper.setValue('a4')` in one handler keeps `a4` even where
+`a4` was paper's default under the old layout. Each field's `hrefFor` links a value through the
+store, as rendered (`undefined` where the store has no links). The fallback rule is the same,
+and the stored value is never rewritten (the search above hides `toc`; `?toc=` stays). A stored
+raw value that does not parse, or does not fit its field, warns once, in the render that first
+reads it, as `useStoredField`'s does; one that does not parse reads as the current default. A
+value that another field's change makes fall back later does not warn: that is how a group
+behaves, not bad input. Nor does a raw value the group itself wrote:
+`layout.setValue('rendered'); paper.setValue('letter')` in one handler (Letter offered under the
+original layout) stores `letter`, which falls back at once; the warnings are for raw values from
+elsewhere (the URL, another tab). `resetAll(method = 'replace')` removes every field's key in one store
+write (one history entry). Switching between the two storages is a change of shape: it throws
+(remount with a React `key`).
+
+**Rendering.** vultus-antd's `<FieldWidget>` renders the controls (by the definition's `widget`
+hint; `item` for a labelled form item), in order as above or by id
+(`<FieldWidget field={group.byId.paper} />`). A request goes through the kind's own checks (a
+paper size the layout does not offer is refused with a warning, as the kind's hook alone refuses
+it). The group then keeps the value and re-renders, so every option is computed again.
+
 ## Components
 
 `VultusComponentsContext` (default `{}`) / `useVultusComponents()` is how an app lends its own

package/dist/FieldContext.d.ts

@@ -6,6 +6,22 @@ import { type JSX, type ReactNode } from 'react';
 export declare const NO_FIELD_CONTEXT: unique symbol;
 /** The field context as the hooks hold it: the guarded value, or the mark that there is none. */
 export type FieldCtx = object | typeof NO_FIELD_CONTEXT;
+/**
+ * What the guard throws for a key no provider gave, so readingContext can tell it from the
+ * function's own errors. Exported for the field group (fieldGroupValues), whose own reads that
+ * fail (an id not in the group, `values` read from `initialValue`) get the field and option in
+ * front the same way; not part of the package's API.
+ */
+export declare class MissingKeyError extends Error {
+}
+/**
+ * `raw` guarded against reading a key it lacks: such a read throws a MissingKeyError with
+ * `missing(key)` as its message, which readingContext puts the field and the option in front
+ * of. `has` says whether `raw` has the key; by default inherited members (`toString`) count,
+ * and `Object.hasOwn` makes them missing too. Probes and symbol keys read as usual. Exported for
+ * the field group's `values` (an id not in the group); not part of the package's API.
+ */
+export declare function guardKeys(raw: object, missing: (key: string) => string, has?: (target: object, key: string) => boolean): object;
 /**
  * Runs `read`, a call of a definition's function with the field context. A key it reads that
  * no provider gave throws with `where` (`Field '<id>': option '<name>'`) in front of the
@@ -33,6 +49,26 @@ export declare function createFieldContext<Ctx extends object>(): {
         children?: ReactNode;
     }) => JSX.Element;
 };
-/** The field context the hooks resolve functions with: the guarded value, or NO_FIELD_CONTEXT. */
+/**
+ * A field context with `base`'s keys (none for NO_FIELD_CONTEXT) and `extra`'s, guarded as a
+ * provider's value is: how a field group gives its fields' functions `values` beside the app's
+ * own keys. `extra`'s properties are copied as defined, so a getter among them runs when its
+ * key is read, not here. A key of `extra` that `base` already has throws, `where` in front,
+ * instead of shadowing the app's value; every key the copy takes is checked (non-enumerable
+ * and symbol keys too).
+ */
+export declare function extendFieldContext(base: FieldCtx, extra: Record<string, unknown>, where: string): object;
+/**
+ * Runs `run` with `ctx` as the field context: a hook it calls gets `ctx` from useFieldContext
+ * instead of the providers' value. It is for a hook that calls other hooks in its own render,
+ * each with its own context (a field group runs each field's kind hook with the group's); the
+ * components rendered below do not see it. `run` must be synchronous: the previous context
+ * comes back when it returns or throws. Calls nest.
+ */
+export declare function withFieldContext<T>(ctx: FieldCtx, run: () => T): T;
+/**
+ * The field context the hooks resolve functions with: the one withFieldContext gives while it
+ * runs, else the providers' guarded value, or NO_FIELD_CONTEXT.
+ */
 export declare function useFieldContext(): FieldCtx;
 //# sourceMappingURL=FieldContext.d.ts.map

package/dist/FieldContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FieldContext.d.ts","sourceRoot":"","sources":["../src/FieldContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,GAAG,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAErF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAwC,CAAC;AAE/E,iGAAiG;AACjG,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,gBAAgB,CAAC;AA2CxD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,eAShG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,SAAS,MAAM,KAAK;IACxD,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;KAAE,KAAK,GAAG,CAAC,OAAO,CAAC;CACjF,CAEA;AAED,kGAAkG;AAClG,wBAAgB,eAAe,IAAI,QAAQ,CAE1C"}
+{"version":3,"file":"FieldContext.d.ts","sourceRoot":"","sources":["../src/FieldContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,GAAG,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAErF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAwC,CAAC;AAE/E,iGAAiG;AACjG,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,gBAAgB,CAAC;AAwBxD;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,KAAK;CAAG;AAE7C;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,EAChC,GAAG,GAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAwC,GAC7E,MAAM,CAOR;AAcD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;CAAE,eAShG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,SAAS,MAAM,KAAK;IACxD,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,SAAS,CAAA;KAAE,KAAK,GAAG,CAAC,OAAO,CAAC;CACjF,CAEA;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAMxG;AAKD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAQlE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,QAAQ,CAI1C"}

package/dist/FieldContext.js

@@ -18,24 +18,41 @@ const PROBED_KEYS = new Set([
 function isProbe(key) {
     return PROBED_KEYS.has(key) || key.startsWith('@@');
 }
-/** What the guard throws for a key no provider gave, so readingContext can tell it from the function's own errors. */
-class MissingKeyError extends Error {
+/**
+ * What the guard throws for a key no provider gave, so readingContext can tell it from the
+ * function's own errors. Exported for the field group (fieldGroupValues), whose own reads that
+ * fail (an id not in the group, `values` read from `initialValue`) get the field and option in
+ * front the same way; not part of the package's API.
+ */
+export class MissingKeyError extends Error {
 }
 /**
- * The context value as the definitions' functions receive it: reading a key that no provider
- * gave throws, naming it and the keys present, so a forgotten value fails loudly instead of
- * passing `undefined` along. A key provided with the value `undefined` is fine.
+ * `raw` guarded against reading a key it lacks: such a read throws a MissingKeyError with
+ * `missing(key)` as its message, which readingContext puts the field and the option in front
+ * of. `has` says whether `raw` has the key; by default inherited members (`toString`) count,
+ * and `Object.hasOwn` makes them missing too. Probes and symbol keys read as usual. Exported for
+ * the field group's `values` (an id not in the group); not part of the package's API.
  */
-function guard(raw) {
+export function guardKeys(raw, missing, has = (target, key) => key in target) {
     return new Proxy(raw, {
         get(target, key, receiver) {
-            if (typeof key === 'string' && !isProbe(key) && !(key in target)) {
-                throw new MissingKeyError(`Field context: '${key}' was never provided (provided: ${Object.keys(target).join(', ')})`);
-            }
+            if (typeof key === 'string' && !isProbe(key) && !has(target, key))
+                throw new MissingKeyError(missing(key));
             return Reflect.get(target, key, receiver);
         },
     });
 }
+/**
+ * The context value as the definitions' functions receive it: reading a key that no provider
+ * gave throws, naming it and the keys present, so a forgotten value fails loudly instead of
+ * passing `undefined` along. A key provided with the value `undefined` is fine. `values` is the
+ * key a field group adds (extendFieldContext), so reading it from any other context says so.
+ */
+function guard(raw) {
+    return guardKeys(raw, (key) => (key === 'values'
+        ? 'ctx.values is only available inside a field group'
+        : `Field context: '${key}' was never provided (provided: ${Object.keys(raw).join(', ')})`));
+}
 /**
  * Runs `read`, a call of a definition's function with the field context. A key it reads that
  * no provider gave throws with `where` (`Field '<id>': option '<name>'`) in front of the
@@ -75,8 +92,48 @@ export function FieldContextProvider({ value, children }) {
 export function createFieldContext() {
     return { Provider: FieldContextProvider };
 }
-/** The field context the hooks resolve functions with: the guarded value, or NO_FIELD_CONTEXT. */
+/**
+ * A field context with `base`'s keys (none for NO_FIELD_CONTEXT) and `extra`'s, guarded as a
+ * provider's value is: how a field group gives its fields' functions `values` beside the app's
+ * own keys. `extra`'s properties are copied as defined, so a getter among them runs when its
+ * key is read, not here. A key of `extra` that `base` already has throws, `where` in front,
+ * instead of shadowing the app's value; every key the copy takes is checked (non-enumerable
+ * and symbol keys too).
+ */
+export function extendFieldContext(base, extra, where) {
+    const raw = base === NO_FIELD_CONTEXT ? {} : { ...base };
+    for (const key of Reflect.ownKeys(extra)) {
+        if (Object.hasOwn(raw, key))
+            throw new Error(`${where}: the field context already has '${String(key)}'; a field group provides it`);
+    }
+    return guard(Object.defineProperties(raw, Object.getOwnPropertyDescriptors(extra)));
+}
+/** The context withFieldContext gives the hooks it is running, if any. */
+let override;
+/**
+ * Runs `run` with `ctx` as the field context: a hook it calls gets `ctx` from useFieldContext
+ * instead of the providers' value. It is for a hook that calls other hooks in its own render,
+ * each with its own context (a field group runs each field's kind hook with the group's); the
+ * components rendered below do not see it. `run` must be synchronous: the previous context
+ * comes back when it returns or throws. Calls nest.
+ */
+export function withFieldContext(ctx, run) {
+    const previous = override;
+    override = ctx;
+    try {
+        return run();
+    }
+    finally {
+        override = previous;
+    }
+}
+/**
+ * The field context the hooks resolve functions with: the one withFieldContext gives while it
+ * runs, else the providers' guarded value, or NO_FIELD_CONTEXT.
+ */
 export function useFieldContext() {
-    return useContext(FieldContext)?.guarded ?? NO_FIELD_CONTEXT;
+    // Called under an override too, so that the hooks' order never depends on one.
+    const provided = useContext(FieldContext);
+    return override ?? provided?.guarded ?? NO_FIELD_CONTEXT;
 }
 //# sourceMappingURL=FieldContext.js.map

package/dist/FieldContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"FieldContext.js","sourceRoot":"","sources":["../src/FieldContext.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAA4B,MAAM,OAAO,CAAC;AAErF;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAkB,MAAM,CAAC,uBAAuB,CAAC,CAAC;AAW/E,MAAM,YAAY,GAAG,aAAa,CAAuB,SAAS,CAAC,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC;IAC1B,MAAM,EAAE,QAAQ,EAAE,iBAAiB,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,EAAE,iBAAiB;CAC1G,CAAC,CAAC;AAEH,SAAS,OAAO,CAAC,GAAW;IAC1B,OAAO,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAED,sHAAsH;AACtH,MAAM,eAAgB,SAAQ,KAAK;CAAG;AAEtC;;;;GAIG;AACH,SAAS,KAAK,CAAC,GAAW;IACxB,OAAO,IAAI,KAAK,CAAC,GAAG,EAAE;QACpB,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ;YACvB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,EAAE,CAAC;gBACjE,MAAM,IAAI,eAAe,CAAC,mBAAmB,GAAG,mCAAmC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACxH,CAAC;YACD,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC5C,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAI,KAAa,EAAE,IAAa;IAC5D,IAAI,CAAC;QACH,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,eAAe;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,KAAK,KAAK,KAAK,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QACtG,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAA2C;IAC/F,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IACvC,4FAA4F;IAC5F,8FAA8F;IAC9F,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE;QAC5B,MAAM,GAAG,GAAG,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;QACxC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;IACtC,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IACnB,OAAO,KAAC,YAAY,CAAC,QAAQ,IAAC,KAAK,EAAE,QAAQ,YAAG,QAAQ,GAAyB,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB;IAGhC,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,CAAC;AAC5C,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,eAAe;IAC7B,OAAO,UAAU,CAAC,YAAY,CAAC,EAAE,OAAO,IAAI,gBAAgB,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"FieldContext.js","sourceRoot":"","sources":["../src/FieldContext.tsx"],"names":[],"mappings":"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"}

package/dist/field.d.ts

@@ -9,7 +9,7 @@ import type { ConfirmationSpec, Decision, ErrorRoutesRegistry, ExecutionContext,
  * Design notes: unitas docs/2026-10-05-vultus-field-model-design.md.
  */
 /** The field kinds (FieldControls.type and a FieldDefinition's `kind`). */
-export type FieldKind = 'boolean' | 'mixed-boolean' | 'oneOf' | 'manyOf' | 'numeric' | 'range' | 'manyOfTree' | 'text';
+export type FieldKind = 'boolean' | 'mixed-boolean' | 'oneOf' | 'manyOf' | 'numeric' | 'range' | 'manyOfTree' | 'oneOfTree' | 'text';
 /** The widget to render a field with: a name, or a name with display options overriding its defaults. */
 export type WidgetHint = string | {
     name: string;
@@ -67,6 +67,7 @@ export type FieldStorage<TValue, TRequest = TValue, RouteId extends string = str
     value?: never;
     onChange?: never;
     commit?: never;
+    hrefFor?: never;
 }
 /** Outside, changed locally: the caller owns the value and applies `onChange`. */
  | {
@@ -74,6 +75,8 @@ export type FieldStorage<TValue, TRequest = TValue, RouteId extends string = str
     onChange: (value: TRequest) => void;
     initialValue?: never;
     commit?: never;
+    /** The link that requesting `value` amounts to, where the caller has one (e.g. a URL store). */
+    hrefFor?: (value: TRequest) => string | undefined;
 }
 /** Outside, committed immediately: `commit.fire` stores the change (pending, messages, confirmation). */
  | {
@@ -81,6 +84,7 @@ export type FieldStorage<TValue, TRequest = TValue, RouteId extends string = str
     commit: FieldCommit<TRequest, RouteId>;
     initialValue?: never;
     onChange?: never;
+    hrefFor?: (value: TRequest) => string | undefined;
 };
 export type FieldOptions<TValue, TRequest = TValue, RouteId extends string = string, Ctx = any> = FieldBaseOptions<TValue, Ctx> & FieldStorage<TValue, TRequest, RouteId, Ctx>;
 /** What a field widget receives: everything it shows, and the one way to change the value. */
@@ -106,6 +110,13 @@ export interface FieldControls<TValue, TRequest = TValue> {
     messages: Message[];
     /** The confirmation a widget must obtain before requesting `next`, if any. */
     confirmationFor(next: TRequest): ConfirmationSpec | undefined;
+    /**
+     * The link that requesting `value` amounts to, where whoever keeps the value gave one (a URL
+     * store does); `undefined` otherwise, and always inside the field. Every kind's hook provides
+     * it; optional here so that controls built by hand (as before vultus-core 0.5.3) need none, so
+     * a widget calls it as `field.hrefFor?.(value)`.
+     */
+    hrefFor?(value: TRequest): string | undefined;
     widget: WidgetHint | undefined;
 }
 export type FieldStorageMode = 'inside' | 'local' | 'commit';

package/dist/field.d.ts.map

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

package/dist/field.js

@@ -1,4 +1,4 @@
-import { useState } from 'react';
+import { useCallback, useState } from 'react';
 import { getReason, getVerdict, invertDecision } from './decision.js';
 import { useFieldContext } from './FieldContext.js';
 import { resolveIn } from './resolve.js';
@@ -86,6 +86,10 @@ export function useFieldCore(type, opts, registry) {
         const spec = opts.commit?.confirmation;
         return typeof spec === 'function' ? spec(next) : spec;
     };
+    // Inside the field nothing outside keeps the value, so nothing gives a link: an `hrefFor` that
+    // came anyway (untyped options; the types forbid it) is ignored.
+    const hrefForOpt = mode === 'inside' ? undefined : opts.hrefFor;
+    const hrefFor = useCallback((next) => hrefForOpt?.(next), [hrefForOpt]);
     return {
         type,
         id: opts.id,
@@ -102,6 +106,7 @@ export function useFieldCore(type, opts, registry) {
         commits: mode === 'commit',
         messages: mode === 'commit' ? (setter.messages ?? []) : [],
         confirmationFor,
+        hrefFor,
         widget: opts.widget,
     };
 }

package/dist/field.js.map

@@ -1 +1 @@
-{"version":3,"file":"field.js","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"field.js","sourceRoot":"","sources":["../src/field.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AA+H3C,MAAM,UAAU,gBAAgB,CAAC,EAAU,EAAE,IAA4C;IACvF,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAEjD,CAAC;IACF,IAAI,MAAM,IAAI,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,UAAU,EAAE,mDAAmD,CAAC,CAAC;IACzG,IAAI,CAAC,MAAM,IAAI,QAAQ,CAAC,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,UAAU,EAAE,4DAA4D,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,6BAA6B,CAAC,CAAC;IACvJ,CAAC;IACD,IAAI,MAAM;QAAE,OAAO,QAAQ,CAAC;IAC5B,IAAI,QAAQ;QAAE,OAAO,OAAO,CAAC;IAC7B,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,UAAU,EAAE,yCAAyC,CAAC,CAAC;IAChG,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,EAAU,EAAE,OAA4B,EAAE,MAA2B;IACpG,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACxE,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,OAAO,CAAC;IAC/D,MAAM,IAAI,KAAK,CAAC,UAAU,EAAE,iDAAiD,CAAC,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,EAAU,EAAE,OAA6B,EAAE,QAA8B;IACxG,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC3F,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC;IAC3C,IAAI,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;QAC/D,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;IACpG,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,UAAU,EAAE,mDAAmD,CAAC,CAAC;AACnF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAe,EACf,IAAkD,EAClD,QAAuC;IAEvC,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,CAAC,EAAE,4BAA4B,IAAI,CAAC,IAAI,wBAAwB,IAAI,QAAQ,CAAC,CAAC;IAC9G,CAAC;IACD,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,EAAE,IAA8C,CAAC,CAAC;IACvF,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,UAAU,IAAI,CAAC,EAAE,cAAc,IAAI,GAAG,CAAC;IACvE,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAChC,GAAG,EAAE,CAAC,SAAS,CAAqB,IAAI,CAAC,YAAY,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,cAAc,CAAC,CAAW,CACxG,CAAC;IAEF,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IAC7D,MAAM,WAAW,GAAG,SAAS,CAAqB,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;IAC1G,MAAM,WAAW,GAAG,SAAS,CAAqB,IAAI,CAAC,WAAW,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC;IAC1G,MAAM,OAAO,GAAG,gBAAgB,CAC9B,IAAI,CAAC,EAAE,EACP,SAAS,CAAsB,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,EAC9E,SAAS,CAAsB,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAC7E,CAAC;IACF,MAAM,eAAe,GAAG,gBAAgB,CACtC,IAAI,CAAC,EAAE,EACP,SAAS,CAAuB,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,EAC/E,SAAS,CAAuB,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,CAClF,CAAC;IACF,MAAM,OAAO,GAAG,UAAU,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;IAClD,MAAM,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,eAAe,CAAC,CAAC;IAErE,6EAA6E;IAC7E,MAAM,MAAM,GAAG,SAAS,CACtB;QACE,EAAE,EAAE,GAAG,IAAI,CAAC,EAAE,MAAM;QACpB,KAAK;QACL,OAAO,EAAE,eAAe;QACxB,SAAS,EAAE,CAAC,OAAO;QACnB,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU;QACnC,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC;KAClD,EACD,QAAQ,CACT,CAAC;IAEF,MAAM,KAAK,GAAG,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,IAAI,CAAC,KAAgB,CAAC;IACjE,MAAM,OAAO,GAAG,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC;IACpD,MAAM,gBAAgB,GAAI,IAAI,CAAC,iBAAoE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAErH,MAAM,QAAQ,GAAG,CAAC,IAAc,EAAE,EAAE;QAClC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,EAAE,iBAAiB,WAAW,IAAI,aAAa,EAAE,CAAC,CAAC;YAC/E,OAAO;QACT,CAAC;QACD,IAAI,IAAI,KAAK,QAAQ;YAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;aACjC,IAAI,IAAI,KAAK,OAAO;YAAE,IAAI,CAAC,QAAS,CAAC,IAAI,CAAC,CAAC;;YAC1C,MAAM,CAAC,IAAiC,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC,CAAC;IAEF,MAAM,eAAe,GAAG,CAAC,IAAc,EAAgC,EAAE;QACvE,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,YAAY,CAAC;QACvC,OAAO,OAAO,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxD,CAAC,CAAC;IAEF,+FAA+F;IAC/F,iEAAiE;IACjE,MAAM,UAAU,GAAG,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,IAA8D,CAAC,OAAO,CAAC;IAC3H,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,IAAc,EAAE,EAAE,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;IAElF,OAAO;QACL,IAAI;QACJ,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,KAAK;QACL,WAAW;QACX,WAAW;QACX,gBAAgB;QAChB,OAAO;QACP,OAAO;QACP,WAAW;QACX,KAAK;QACL,QAAQ;QACR,OAAO;QACP,OAAO,EAAE,IAAI,KAAK,QAAQ;QAC1B,QAAQ,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE;QAC1D,eAAe;QACf,OAAO;QACP,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC;AACJ,CAAC"}

package/dist/fieldGroupValues.d.ts

@@ -0,0 +1,63 @@
+import { type FieldCtx } from './FieldContext.js';
+import { 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;
+}
+/**
+ * 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 declare function createGroupValues({ definitions, appCtx, kept, warn }: GroupValuesParams): GroupValues;
+//# sourceMappingURL=fieldGroupValues.d.ts.map

package/dist/fieldGroupValues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fieldGroupValues.d.ts","sourceRoot":"","sources":["../src/fieldGroupValues.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkD,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClG,OAAO,EAAkC,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAElF;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,8FAA8F;IAC9F,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3C;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,WAAW,EAAE,SAAS,eAAe,EAAE,CAAC;IACxC,6EAA6E;IAC7E,MAAM,EAAE,QAAQ,CAAC;IACjB,mGAAmG;IACnG,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACtC;;;;OAIG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACzC;AA8BD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,iBAAiB,GAAG,WAAW,CA4ErG"}