@dynamic-field-kit/angular 1.5.1 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,229 @@
 # @dynamic-field-kit/angular
 
+## 1.7.0
+
+### Minor Changes
+
+- Dirty-baseline rebasing, accessible validation errors, form-level message catalogs, and async field options across React, Vue, and Angular.
+- 9b06e3f: Validation messages can be set once per form via `useDynamicForm({ messages })`,
+  or process-wide via `setDefaultMessages`, instead of passing a string to every
+  validator on every field. Built-in validators now resolve their message when
+  they run rather than when the field description is built, which is what made a
+  catalog impossible before. A message passed directly to a validator still wins,
+  and the English defaults are unchanged when no catalog is supplied.
+
+  `ValidationContext` - already `validate`'s fourth argument - gains an optional
+  `t` resolver, so a hand-written validator can translate its own messages too.
+
+  Adds `validators.matches(otherFieldName)` for confirm-password and
+  confirm-email fields, which every consumer was hand-writing.
+
+  No locale bundles ship: the mechanism is here, the translations are yours.
+
+- a7358f9: Fix per-field `dirty`, which was measured against a baseline captured at mount
+  and never re-based - wrong after `reset(newValues)` on all three adapters, and
+  wrong on React and Vue for values that arrive after mount, where every field
+  reported dirty forever.
+
+  Adds `baselineValues` and `getDirtyValues()` to the form store on all three
+  adapters, and an `initialProperties` prop to `MultiFieldInput` for re-basing
+  without a store. Comparison moves from `!==` to `Object.is`, so a `NaN` numeric
+  field no longer reads as permanently dirty.
+
+  React's `useDynamicForm` no longer validates the same data twice per change.
+
+- 53ed45a: `options` can now return a promise, covering both dependent selects
+  (`optionsDeps`) and search-remote pickers (`onOptionsQuery`). Renderers receive
+  `optionsStatus` and `optionsError` alongside `options`.
+
+  `debounceMs` was declared on `FieldDescription`, published in the `.d.ts` and
+  read by no implementation anywhere - setting it did nothing. It now debounces
+  these loads.
+
+  Debounce, abort of a superseded request, and discarding a response that lands
+  out of order all live in core's `createOptionsLoader`, so the three adapters
+  share one implementation. Synchronous and static options are untouched and never
+  enter a loading state.
+
+- e35e876: `ariaDescribedBy` is now `${id}-error` when a field has an error instead of
+  being hard-coded `undefined`, and `makeErrorId` is exported so a custom renderer
+  can put the matching id on its message element. Without this,
+  `focusFirstInvalidField` had nothing to find for anyone following the official
+  renderer recipe.
+
+  Default renderers now render the validation message they were already being
+  handed - the one visible change in this release. Custom renderers are untouched,
+  so nobody gets two copies of their own message.
+
+  Development builds now warn when `FieldDescription.props` carries a key the
+  renderer prop contract owns, which 1.6.0 made possible to lose silently.
+
+## 1.6.0
+
+### Minor Changes
+
+- Cancellable, status-aware async validation; touched state that reaches inside repeatable groups; Angular 21 and TypeScript 5.9 support; and peer ranges corrected to the versions that actually work, proven at both ends in CI.
+- 67e4eec: Give every adapter one renderer-prop contract, unique field ids, and a touched
+  state the form store can actually drive.
+
+  Five things went wrong at once for anyone building a real form on 1.5.1, and
+  four of them share a cause: `FieldRendererProps` was a type nobody enforced.
+  Each adapter hand-wrote the object it handed the registered renderer, and the
+  three lists drifted. React dropped `placeholder`, `min`, `max`, `step`,
+  `accept` and `multiple`. Vue dropped `required`, `id`, `dirty` and the aria
+  flags. Angular dropped `touched`, `dirty` and `id` — so an Angular renderer had
+  no way to know whether a field had been touched, and "only show the error once
+  the user leaves the field" had to be rebuilt by hand. Setting
+  `placeholder` on a `FieldDescription` therefore did nothing at all on React and
+  Vue: no error, no warning, the value simply vanished. Core now owns the list as
+  `FIELD_RENDERER_PROP_KEYS` and builds the bag once in
+  `buildFieldRendererProps`, which all three adapters call, and
+  `scripts/check-renderer-prop-parity.js` fails the build if an adapter stops
+  forwarding one. The single deliberate deviation is Vue's `class` in place of
+  `className`: forwarding `className` lets it fall through to a renderer's root
+  element, where Vue assigns `el.className` and wipes the class the renderer set
+  on itself.
+
+  Field ids were `dfk-field-${name}`, derived from the field name alone. Two
+  forms holding a field of the same name — a create form beside an edit form, the
+  most ordinary layout there is — emitted the same DOM id twice, which is invalid
+  HTML and leaves every `label[for]` pointing at two inputs. Ids are now
+  namespaced per `MultiFieldInput` instance (React `useId`, so it is SSR-safe;
+  Vue's instance uid; a counter on Angular). Set `idPrefix` to pin them —
+  `idPrefix="dfk-field"` reproduces the old ids exactly — or give a single field
+  its own id with the new `FieldDescription.id`.
+
+  Touched state had two independent trackers that never met: the one in
+  `useDynamicForm`, and a private one inside `MultiFieldInput` that only blur
+  could set and that was the one renderers actually saw. So
+  `setFieldTouched` in an `onInvalid` handler changed nothing visible, submitting
+  a form nobody had focused showed no errors at all (the button looked broken),
+  and `reset()` could not clear the touched state a previous submit had left
+  behind. `MultiFieldInput` now accepts `touched` as a controlled prop —
+  `useDynamicForm` becomes the single source of truth for it, exactly as
+  `properties`/`onChange` already were for data — plus `onTouchedChange`, and a
+  `form` shorthand (React and Vue) that wires data, change, blur and touched in
+  one prop. `handleSubmit` marks every field touched before validating, and the
+  new `touchAll()`/`resetTouched()` sit alongside it. Omit `touched` and the old
+  internal tracker still runs, so nothing breaks; for that mode a ref
+  (`resetTouched()` on React and Vue, a public method on Angular) can clear it
+  without remounting the component.
+
+  The only behaviour change to watch for is the generated ids. Anything pinned to
+  a literal `dfk-field-*` id in CSS or a test needs either `idPrefix="dfk-field"`
+  or a per-field `id`. Angular's `MultiFieldInput` also loses four undocumented
+  template helpers — `getResolvedOptions`, `getDisabled`, `getReadOnly` and
+  `getError` — which its own template no longer calls now that `FieldInput`
+  resolves all of it through core. Keeping a second copy of that logic beside the
+  shared one is how the adapters drifted apart to begin with; the equivalents are
+  `resolveOptions`, `resolveDisabled`, `resolveReadOnly` and `validateField`,
+  already re-exported from this package.
+
+  Form validity now reflects current data immediately instead of merely checking
+  the lazily populated `errors` map. The error map remains lazy for display, and
+  passing a form binding (or the new controlled `errors` input) makes that same
+  map the renderer's source of truth, removing the previous timing mismatch.
+
+  Promise-based validators are no longer silently accepted on submit.
+  `validateFields` reports unresolved field names in `pending`; every framework
+  form helper uses one async-capable validation pass before dispatching submit
+  callbacks. React, Vue and Angular also expose
+  `validateAsync()` for explicit pre-submit checks. Live `isValid` remains a
+  synchronous answer because a property/computed/signal cannot await.
+
+  The new UI-kit recipes show complete touched/error wiring for Ant Design,
+  Vuetify and Angular Material.
+
+- 5e0b08f: Make async validation answerable: a status you can act on, runs that cancel
+  cleanly, and touched state that reaches inside repeatable groups.
+
+  `ValidationResult` gains `complete` and `status` (`'valid' | 'invalid' |
+'pending'`). Combining `valid` with `pending` was the only way to tell "nothing
+  is wrong" from "nothing is wrong _yet_", and everyone got it wrong the same
+  way — a `valid: true` with async rules still in flight reads as a green light.
+  `status` is the single answer; `complete` says whether every applicable
+  validator finished. Both are always present on a result the library returns, so
+  reading them needs no fallback; code that constructs a `ValidationResult` by
+  hand (a mock, a wrapper typed to return one) has to supply them.
+
+  `FieldDescription.validationMode: 'async'` declares a validator that returns a
+  Promise without the `async` keyword, which detection cannot see. Declaring it
+  keeps the synchronous pass from invoking the validator at all — and, unlike
+  detection, it is an explicit opt-in, so the dev warning about a field the live
+  pass cannot check stays quiet for it.
+
+  `validateFieldsAsync` now takes a `ValidationContext` and forwards its
+  `AbortSignal` to every validator, runs independent validators in parallel
+  instead of awaiting them one after another, skips validators once the signal is
+  aborted, and reports an aborted run as `complete: false` / `status: 'pending'`.
+  A validator that honours the signal the conventional way — rejecting with an
+  `AbortError` — no longer rejects the caller's `handleSubmit`; an error that is
+  not an abort still propagates.
+
+  Each adapter's form helper exposes `isValidating`, `isValidationComplete` and
+  `validationStatus`, and applies latest-run-wins: typing cancels an in-flight
+  live validation so a stale result cannot overwrite a newer one. A submit is not
+  collateral damage of that — it validates the snapshot the user submitted under
+  a controller of its own, so editing a field mid-flight no longer leaves the
+  form with the submit silently dropped, no `onValid`/`onInvalid`, and a button
+  that just re-enables.
+
+  `touchAll()` now expands to the concrete leaf paths that exist in the data
+  (`contacts[0].email`, not `contacts`) via the new `collectFieldPaths`, skipping
+  fields validation itself skips — hidden by `appearCondition`, or disabled.
+  Repeatable group items receive `touched` and report blur with their full path,
+  so a UI kit that only shows an error once a field is touched now works inside a
+  group. An item with no touched keys still receives a map rather than
+  `undefined`, which previously flipped the nested input into tracking touched by
+  itself and left it stale after the owner cleared the map. The new
+  `indexGroupPathMap` is what indexes those maps by item, exported so a custom
+  renderer can do the same without filtering the whole map per item.
+
+  React's `isValid` is now seeded from the initial data instead of from an
+  effect. An effect never runs on the server, so a server-rendered form shipped
+  `isValid: true` for an empty required field and never corrected it — a submit
+  button rendered enabled and stayed that way.
+
+  `@dynamic-field-kit/angular`'s `types` entry pointed at `dist/index.d.ts`,
+  which is not where its type declarations are emitted any more; it and the
+  `exports` block now point at the file that actually ships, so TypeScript
+  consumers resolve the package's types again.
+
+- eec9386: Correct the peer ranges to the ones that actually work, and prove both ends of
+  each in CI.
+
+  `@dynamic-field-kit/angular` declared `@angular/core` and `@angular/common` as
+  `>=14 <22`, but the form store is built on `signal` and `computed`, which
+  Angular introduced in **16**. On 14 or 15 npm accepted the install and the
+  package then failed on import - the manifest promised something it could not
+  do. The range is now `>=16 <22`, so the same install is refused up front.
+
+  `@dynamic-field-kit/vue` moves from `vue ^3.0.0` to `^3.2.0`.
+  `useDynamicForm` now aborts an in-flight validation when the owning effect
+  scope is disposed, using `getCurrentScope` / `onScopeDispose` - both Vue 3.2.
+  Without this an unmounted form held its request open until the response came
+  back. If you are on Vue 3.0 or 3.1, stay on 1.5.x; nothing else in the package
+  ever required 3.2, but nothing tested below it either.
+
+  Both ranges are now verified rather than asserted:
+  `scripts/verify-vue-peer-range.js` server-renders the packed tarballs under Vue
+  3.2 and the newest 3.x, and `scripts/verify-angular-peer-range.js` installs
+  them against Angular 16 and 21 and checks the package imports, its components
+  evaluate and it shares one registry with core. Both run in the CI verify job,
+  next to the React one that has existed since 1.5.0. A render is out of reach
+  for Angular - the published fesm2022 needs the CLI's linker to instantiate a
+  component - but import-and-wire is the level that breaks across majors, which
+  is exactly how a floor of 14 survived years of `signal()`.
+
+  The three adapters now re-export `collectFieldPaths`, `indexGroupPathMap` and
+  the `ValidationContext` type from core, so typing a validator's `context`
+  argument no longer means importing `@dynamic-field-kit/core` alongside the
+  adapter.
+
+  `@angular/platform-browser-dynamic`, which Angular 21 deprecates, is gone from
+  the package's devDependencies and from the demo app, which never used it - the
+  test setup now initialises through `@angular/platform-browser/testing`.
+
 ## 1.5.1
 
 ### Patch Changes

package/README.md

@@ -37,9 +37,11 @@ npm install @dynamic-field-kit/core@^1.5.0 @dynamic-field-kit/angular@^1.5.0
 - `ColumnLayout` / `RowLayout` / `GridLayout` (the standalone layout components, registered for you)
 - `BaseInputComponent` — the abstract base your custom renderers extend
 - `FieldInputProps` — the inputs `BaseInputComponent` declares; the Angular
-  mirror of core's `FieldRendererProps`
+  mirror of core's `FieldRendererProps`, and complete as of 1.6 — `touched`,
+  `dirty`, `id` and the aria flags used to be missing here, which left an
+  Angular renderer no way to tell whether a field had been touched
 - `DynamicFormOptions` — what `createDynamicFormStore` takes: `fields`,
-  `initialValues`, `validateOnBlur`, `validateOnChange`
+  `initialValues`, `validateOnBlur`, `validateOnChange`, `messages`
 - `LayoutConfig` / `ColumnLayoutConfig` / `RowLayoutConfig` /
   `GridLayoutConfig` — the layout config types, re-exported from core
 - `BaseLayoutConfig` / `ResponsiveLayoutConfig` — this adapter's historical
@@ -51,20 +53,51 @@ both packages:
 
 - `validateField` / `validateFieldAsync` — one field, returns `string[]`
 - `validateFields` / `validateFieldsAsync` — a whole schema, returns `ValidationResult`
+- `collectFieldPaths` — the leaf paths a schema actually has in the data (`contacts[0].email`)
+- `indexGroupPathMap` — index an error or touched map by repeatable-group item
 - `resolveDisabled` / `resolveReadOnly` / `resolveOptions` — resolve a field's dynamic conditions and options
 - `validators` — the built-in validator helpers (`required`, `email`, `minLength`, `compose`, …)
 - `FieldDescription` / `FieldTypeKey` / `FieldRendererProps` — the schema and
   renderer contracts every adapter shares
-- `ValidationResult`
-
-`createDynamicFormStore` validates **synchronously** via `validateFields`,
-including on submit. Fields whose `validate` hook returns a Promise are treated
-as valid on that path, so run async rules through `validateFieldsAsync`
-yourself. See the
+- `ValidationResult` / `ValidationContext` — the context carries `signal` and the
+  optional `t` message resolver
+- `buildFieldRendererProps` / `makeFieldId` / `makeErrorId` /
+  `FIELD_RENDERER_PROP_KEYS` — the renderer prop contract. `makeErrorId(id)` is
+  what a custom renderer puts on its message element so `aria-describedby`
+  resolves
+- `createOptionsLoader` / `isAsyncOptions` — the async options engine
+- `createMessageResolver` / `setDefaultMessages` / `MessageCatalog` — validation
+  message catalog
+
+`createDynamicFormStore` keeps live validation synchronous - a validator declared or
+detected as async is never invoked on that path. Its `handleSubmit` runs one
+async-capable pass, and `validateAsync()` is there when you need that answer
+before submit. Runs are latest-wins: typing aborts the live run in flight, so a
+stale result cannot overwrite a newer one, and a submit validates the snapshot
+it was given under a controller of its own, so editing mid-submit no longer
+cancels it. Declare a Promise-returning validator with
+`validationMode: 'async'` and read `context.signal` (the fourth argument) to
+cancel the request itself. See the
 [core README](https://github.com/vannt-dev/dynamic-field-kit/tree/develop/packages/core#sync-vs-async-validation)
 for the full rules.
 
-## Basic setup (Angular 19+)
+For a complete UI integration, see the
+[Angular Material recipe](../../docs/ui-kit-recipes.md#angular--angular-material).
+
+## Supported Angular versions
+
+The package declares `@angular/core` and `@angular/common` as `>=16 <22`,
+and `scripts/verify-angular-peer-range.js` proves both ends in CI by installing
+the packed tarballs against Angular 16 and 21 outside the workspace.
+
+The floor is 16 because the form store is built on `signal` and `computed`,
+which Angular introduced in 16. It read `>=14` until 1.6.0: npm accepted the
+install on 14 and 15 and the package then failed on import.
+
+The suite, the build and the demo app all run Angular 21, which is the version
+the setup below is written for.
+
+## Basic setup
 
 1. Import the component and register fields before bootstrap.
 
@@ -141,8 +174,11 @@ import {
       <dfk-multi-field-input
         [fieldDescriptions]="fields"
         [properties]="store.data()"
+        [touched]="store.touched()"
+        [errors]="store.errors()"
         (onChange)="store.handleChange($event)"
         (onBlurField)="store.handleBlur($event)"
+        [initialProperties]="store.baselineValues()"
       ></dfk-multi-field-input>
       <button [disabled]="store.isSubmitting()">Save</button>
     </form>
@@ -154,6 +190,7 @@ export class MyForm {
     fields,
     initialValues: { country: 'VN' },
     validateOnBlur: true, // default
+    messages: { required: 'Bắt buộc' }, // optional; see Validation & conditions
   });
 
   // handleSubmit returns a handler, exactly like React and Vue.
@@ -161,25 +198,58 @@ export class MyForm {
 }
 ```
 
-| Member                              | Description                                                                       |
-| ----------------------------------- | --------------------------------------------------------------------------------- |
-| `data()`                            | Current form data, with `computeValue` fields applied                             |
-| `errors()`                          | `Record<string, string[]>`, keyed like `validateFields`                           |
-| `isValid()` / `isDirty()`           | No errors recorded / any value has changed                                        |
-| `isSubmitting()` / `isSubmitted()`  | In-flight submit / at least one submit attempted                                  |
-| `touched()`                         | Fields that have been blurred                                                     |
-| `handleChange(data)`                | Replace the whole form data — bind to `(onChange)`                                |
-| `setFieldValue(name, value)`        | Change one field                                                                  |
-| `handleBlur(name)`                  | Mark touched, and validate when `validateOnBlur`                                  |
-| `setFieldTouched(name, value?)`     | Set touched explicitly                                                            |
-| `validate()`                        | Validate now, returns a boolean                                                   |
-| `reset(values?)`                    | Back to `initialValues` (or the values given), clearing errors/touched/submission |
-| `handleSubmit(onValid, onInvalid?)` | Returns an async handler; calls `preventDefault`, validates, then dispatches      |
+| Member                              | Description                                                                                                    |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `data()`                            | Current form data, with `computeValue` fields applied                                                          |
+| `errors()`                          | `Record<string, string[]>`, keyed like `validateFields`                                                        |
+| `isValid()` / `isDirty()`           | Current synchronous validity / any value has changed                                                           |
+| `baselineValues()`                  | Signal holding the values `dirty` is measured against - `initialValues` until `reset(newValues)` replaces them |
+| `getDirtyValues()`                  | Only the entries differing from `baselineValues`, for PATCH-style submits                                      |
+| `isValidating()`                    | An async validation pass is in flight                                                                          |
+| `isValidationComplete()`            | Every applicable validator finished and none is in flight                                                      |
+| `validationStatus()`                | `'valid'                                                                                                       | 'invalid' | 'pending'`— prefer it over`isValid`alone:`valid` cannot tell "nothing is wrong" from "nothing is wrong yet" |
+| `isSubmitting()` / `isSubmitted()`  | In-flight submit / at least one submit attempted                                                               |
+| `touched()`                         | Fields that have been blurred                                                                                  |
+| `handleChange(data)`                | Replace the whole form data — bind to `(onChange)`                                                             |
+| `setFieldValue(name, value)`        | Change one field                                                                                               |
+| `handleBlur(name)`                  | Mark touched, and validate when `validateOnBlur`                                                               |
+| `setFieldTouched(name, value?)`     | Set touched explicitly                                                                                         |
+| `touchAll()`                        | Mark every field touched — `handleSubmit` already calls it                                                     |
+| `resetTouched()`                    | Clear touched only, leaving data/errors/dirty alone                                                            |
+| `validate()`                        | Validate now, returns a boolean                                                                                |
+| `validateAsync()`                   | Validate now, awaiting Promise-based rules                                                                     |
+| `reset(values?)`                    | Back to `initialValues` (or the values given), clearing errors/touched/submission                              |
+| `handleSubmit(onValid, onInvalid?)` | Returns an async handler; calls `preventDefault`, validates, then dispatches                                   |
 
 `MultiFieldInput` emits `(onBlurField)` with the field's name, driven by a
 `focusout` listener — so it works with any renderer, without the renderer
 needing a blur output of its own.
 
+Binding `[touched]="store.touched()"` and `[errors]="store.errors()"` makes the
+store the single source of truth for renderer metadata. Touched state is what
+makes an invalid submit visible: `handleSubmit` marks every
+field touched before validating, so a renderer that gates its error on the
+`touched` input shows it even for fields the user never focused. `reset()`
+clears touched the same way. Leave `[touched]` unbound and `MultiFieldInput`
+falls back to tracking it internally from blur alone; in that mode call its
+public `resetTouched()` / `setFieldTouched(name, value?)` (via a `@ViewChild`)
+to clear it, and listen to `(touchedChange)` for the next map.
+
+## Field ids
+
+Each field renders with ``id={`${idPrefix}-${name}`}``, where `idPrefix`
+defaults to a value unique to the `dfk-multi-field-input` instance. Two forms
+containing a field of the same name therefore no longer emit the same DOM id
+twice, and the id now reaches renderers as the `id` input.
+
+```html
+<!-- pinned ids — reproduces the pre-1.6 `dfk-field-title` -->
+<dfk-multi-field-input [fieldDescriptions]="fields" idPrefix="dfk-field">
+</dfk-multi-field-input>
+```
+
+For one field, set `id` on its `FieldDescription`; it wins over the prefix.
+
 ## Default renderers
 
 `text` · `number` · `password` · `email` · `textarea` · `checkbox` · `select` ·
@@ -189,6 +259,13 @@ Any type you have not registered falls back to one of these. `file` emits a
 `File` (or `File[]` when `multiple` is set), `range` and `number` emit numbers,
 `checkbox` / `switch` emit booleans; everything else emits strings.
 
+Since 1.7.0 a default renderer also renders its validation message, as
+`<div id="{fieldId}-error" class="dfk-field-error" role="alert">`, which is what
+`aria-describedby` points at. Before that they were handed `error` and dropped
+it, so the form showed nothing. A registered custom renderer is unaffected — the
+node is emitted only where a default was used, so you never get two copies. Hide
+it with `.dfk-field-error { display: none }` if you want the old silence.
+
 ## DevTools
 
 ```html
@@ -281,6 +358,52 @@ your renderer component receives `error`, `disabled`, and `readOnly` inputs, and
 
 For submit-time whole-form validation, call `validateFields(fields, data)`.
 
+### Validation messages
+
+Set the built-in validators' messages once per form instead of on every field:
+
+```ts
+const store = createDynamicFormStore({
+  fields,
+  messages: { required: 'Bắt buộc', minLength: 'Tối thiểu {min} ký tự' },
+});
+```
+
+A message passed straight to a validator still wins, and any key omitted falls
+back to the English default. `setDefaultMessages(catalog)` sets a process-wide
+one for code calling `validateFields` directly. Full key list in the
+[core README](../core/README.md#validation-messages). **No locale bundles
+ship** — the mechanism is here, the translations are yours.
+
+Forward `ariaInvalid`, `ariaRequired` and `ariaDescribedBy` from your renderer
+too, and put `makeErrorId(id)` on whatever element shows the message.
+`focusFirstInvalidField` selects `[aria-invalid="true"]`, so a renderer that
+drops those props makes that helper silently do nothing. See
+[the recipes](../../docs/ui-kit-recipes.md#forward-the-aria-props).
+
+### Async options
+
+`options` may return a promise. The renderer receives `optionsStatus`
+(`'idle' | 'loading' | 'ready' | 'error'`), `optionsError` and
+`onOptionsQuery`:
+
+```ts
+{
+  name: 'assignee',
+  type: 'userPicker',
+  options: async (data, _rootData, ctx) =>
+    fetch(`/api/users?q=${ctx?.query ?? ''}`, { signal: ctx?.signal })
+      .then((r) => r.json()),
+  optionsDeps: (data) => [data.team],  // reload when this changes; default []
+  debounceMs: 300,                     // collapses rapid reloads into one fetch
+}
+```
+
+Superseded requests are aborted and out-of-order responses discarded, so the
+list always reflects the newest request. Static and synchronous options are
+untouched and never enter a loading state. See the
+[core README](../core/README.md#async-options).
+
 ## Repeatable field groups
 
 A field with `fields` renders as a repeatable group: `data[name]` becomes an array of items, each shaped by the nested `fields`, with "Add"/"Remove" controls rendered automatically.