@dynamic-field-kit/react 1.5.1 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,229 @@
 # @dynamic-field-kit/react
 
+## 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

@@ -41,16 +41,32 @@ 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
+- `makeErrorId` — the id a renderer puts on its message element so
+  `aria-describedby` resolves
+- `createOptionsLoader` / `isAsyncOptions` — the async options engine
+- `createMessageResolver` / `setDefaultMessages` / `MessageCatalog` — validation
+  message catalog
 - `resolveDisabled` / `resolveReadOnly` / `resolveOptions` — resolve a field's dynamic conditions and options
 - `validators` — the built-in validator helpers (`required`, `email`, `minLength`, `compose`, …)
-- `ValidationResult`
-
-`useDynamicForm` 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`
+
+`useDynamicForm` 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.
 
+For a complete UI integration, see the
+[Ant Design recipe](../../docs/ui-kit-recipes.md#react--ant-design).
+
 `FieldGroupInput` (repeatable field groups) is used internally by `FieldInput` and doesn't need to be imported directly - see "Repeatable field groups" below.
 
 Default layouts are registered automatically when you import the package root.
@@ -129,39 +145,112 @@ const form = useDynamicForm({
   initialValues: { country: 'VN' },
   validateOnBlur: true, // default
   validateOnChange: false, // default
+  messages: { required: 'Bắt buộc' }, // optional; see Validation & conditions
 });
 
 <form onSubmit={form.handleSubmit((data) => save(data))}>
-  <MultiFieldInput
-    fieldDescriptions={fields}
-    properties={form.data}
-    onChange={form.handleChange}
-    onBlurField={form.handleBlur} // wires touched + validateOnBlur
-  />
+  <MultiFieldInput fieldDescriptions={fields} form={form} />
   <button disabled={form.isSubmitting}>
     {form.isSubmitting ? 'Saving…' : 'Save'}
   </button>
 </form>;
 ```
 
-| 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 — pass to `MultiFieldInput`'s `onChange`              |
-| `setFieldValue(name, value)`        | Change one field                                                                  |
-| `handleBlur(name)`                  | Mark touched, and validate when `validateOnBlur`                                  |
-| `setFieldTouched(name, value?)`     | Set touched explicitly                                                            |
-| `setData`                           | Raw state setter, for escape hatches                                              |
-| `validate()`                        | Validate now, returns a boolean                                                   |
-| `reset(values?)`                    | Back to `initialValues` (or the values given), clearing errors/touched/submission |
-| `handleSubmit(onValid, onInvalid?)` | Returns a submit handler; calls `preventDefault`, validates, then dispatches      |
-
-`MultiFieldInput` tracks touched internally regardless; `onBlurField` is the
-hook for driving an external store like this one.
+`form` is shorthand for five state/callback props, and is the recommended wiring:
+
+```tsx
+<MultiFieldInput
+  fieldDescriptions={fields}
+  properties={form.data}
+  onChange={form.handleChange}
+  onBlurField={form.handleBlur} // touched + validateOnBlur
+  touched={form.touched} // makes the hook the only source of truth
+  errors={form.errors} // renderer and hook read the same error map
+/>
+```
+
+The `form` shorthand also carries `baselineValues`, which is what keeps
+per-field `dirty` correct across a reset. Without a form store, pass the
+baseline yourself:
+
+```tsx
+<MultiFieldInput
+  fieldDescriptions={fields}
+  properties={data}
+  initialProperties={original} // what `dirty` compares against
+/>
+```
+
+Omit it and the baseline is the first non-`undefined` `properties` the
+component sees — which is what an edit form wants when its values arrive from a
+fetch after mount. Note that `{}` counts as a real value: a form
+that opens blank cannot be told apart from one still waiting on a fetch, so
+pass `initialProperties` when `properties` starts as `{}` rather than
+`undefined`.
+
+Passing `touched` and `errors` gives the form store ownership of renderer
+metadata. `touched` is what makes an invalid submit visible: `handleSubmit`
+marks every field touched before validating, so a renderer that gates its error
+on `touched` shows it even for fields the user never focused. `reset()` clears
+touched the same way. Individually passed props win over the ones `form`
+derives, so you can pass `form` and still override one wire.
+
+| 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`                    | 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 — pass to `MultiFieldInput`'s `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                                             |
+| `setTouched`                        | Raw setter for the whole touched map                                                            |
+| `setData`                           | Raw state setter, for escape hatches                                                            |
+| `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 a submit handler; calls `preventDefault`, validates, then dispatches                    |
+
+Leave `touched` off and `MultiFieldInput` falls back to tracking it internally
+from blur alone, as it always did. In that mode nothing outside the component
+can clear it — a form that stays mounted across submits will keep showing the
+errors of the previous round after `reset()` — so it exposes a ref for it:
+
+```tsx
+const ref = useRef<MultiFieldInputHandle>(null);
+
+<MultiFieldInput ref={ref} fieldDescriptions={fields} />;
+// after a successful submit
+ref.current?.resetTouched();
+```
+
+`resetTouched()`, `setFieldTouched(name, value?)` and `getTouched()` are the
+handle's members. Controlled mode needs none of them: `form.reset()` covers it.
+
+## Field ids
+
+Each field renders with `id={`${idPrefix}-${name}`}`, where `idPrefix` defaults
+to a value unique to the `MultiFieldInput` instance (from `useId`, so server and
+client agree). Two forms containing a field of the same name therefore no longer
+emit the same DOM id twice.
+
+```tsx
+// pinned ids — reproduces the pre-1.6 `dfk-field-title`
+<MultiFieldInput fieldDescriptions={fields} idPrefix="dfk-field" />
+```
+
+For one field, set `id` on its `FieldDescription`; it wins over the prefix.
+Renderers receive the resolved value as the `id` prop, so a `<label htmlFor>` in
+a renderer points at exactly one input.
 
 ## Default renderers
 
@@ -183,6 +272,13 @@ const Base = getDefaultRenderer('date'); // undefined for an unknown type
 `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
 
 ```tsx
@@ -288,6 +384,51 @@ fieldRegistry.register('text', ({ value, onValueChange, error, disabled }) => (
 ));
 ```
 
+Forward `ariaInvalid`, `ariaRequired` and `ariaDescribedBy` too, and put
+`makeErrorId(id)` on whatever element renders 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).
+
+### Validation messages
+
+Set the built-in validators' messages once per form instead of on every field:
+
+```tsx
+const form = useDynamicForm({
+  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.
+
+### Async options
+
+`options` may return a promise, and the renderer receives `optionsStatus`
+(`'idle' | 'loading' | 'ready' | 'error'`), `optionsError` and `onOptionsQuery`:
+
+```tsx
+{
+  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.