@dynamic-field-kit/react 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @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

package/README.md

@@ -43,6 +43,11 @@ both packages:
 - `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` / `ValidationContext`
@@ -140,6 +145,7 @@ 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))}>
@@ -163,6 +169,25 @@ const form = useDynamicForm({
 />
 ```
 
+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
@@ -170,28 +195,30 @@ 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                              |
-| `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      |
+| 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
@@ -245,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
@@ -350,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.

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import React, { ReactNode, ComponentType } from 'react';
-import { FieldTypeKey, Properties, FieldDescription, LayoutConfig, ValidationResult, FieldRendererProps, FieldTypeMap } from '@dynamic-field-kit/core';
-export { FIELD_RENDERER_PROP_KEYS, FieldDescription, FieldRegistry, FieldRendererProps, FieldTypeKey, LayoutConfig, ValidationContext, ValidationResult, buildFieldRendererProps, collectFieldPaths, indexGroupPathMap, makeFieldId, resolveDisabled, resolveOptions, resolveReadOnly, validateField, validateFieldAsync, validateFields, validateFieldsAsync, validators } from '@dynamic-field-kit/core';
+import { FieldTypeKey, Properties, OptionsStatus, FieldDescription, LayoutConfig, ValidationResult, MessageCatalog, FieldRendererProps, FieldTypeMap } from '@dynamic-field-kit/core';
+export { FIELD_RENDERER_PROP_KEYS, FieldDescription, FieldRegistry, FieldRendererProps, FieldTypeKey, LayoutConfig, ValidationContext, ValidationResult, buildFieldRendererProps, collectFieldPaths, indexGroupPathMap, makeErrorId, makeFieldId, resolveDisabled, resolveOptions, resolveReadOnly, validateField, validateFieldAsync, validateFields, validateFieldsAsync, validators } from '@dynamic-field-kit/core';
 
 type LayoutRenderer<C = unknown> = (props: {
     children: React.ReactNode;
@@ -21,6 +21,8 @@ interface Props$2<T extends FieldTypeKey> {
     label?: string;
     placeholder?: string;
     options?: Properties[];
+    optionsStatus?: OptionsStatus;
+    optionsError?: unknown;
     className?: string;
     description?: ReactNode;
     disabled?: boolean;
@@ -40,8 +42,10 @@ interface Props$2<T extends FieldTypeKey> {
     multiple?: boolean;
     /** Extra, framework-agnostic props forwarded verbatim to the renderer. */
     extraProps?: Properties;
+    /** Renderer-driven refetch for a search-remote field. */
+    onOptionsQuery?: (query: string) => void;
 }
-declare const DynamicInputInner: <T extends FieldTypeKey>({ type, onChange, onBlur, extraProps, ...rendererProps }: Props$2<T>) => React.JSX.Element;
+declare const DynamicInputInner: <T extends FieldTypeKey>({ type, onChange, onBlur, extraProps, onOptionsQuery, ...rendererProps }: Props$2<T>) => React.JSX.Element;
 declare const DynamicInput: typeof DynamicInputInner;
 
 interface Props$1 {
@@ -67,6 +71,8 @@ interface DynamicFormBinding {
     data: Properties;
     errors: Record<string, string[]>;
     touched: Record<string, boolean>;
+    /** The values per-field `dirty` is measured against. See `useDynamicForm`. */
+    baselineValues?: Properties;
     handleChange: (data: Properties) => void;
     handleBlur: (fieldName: string) => void;
 }
@@ -95,6 +101,14 @@ interface Props {
      * restores the pre-1.6 ids), or set `FieldDescription.id` per field.
      */
     idPrefix?: string;
+    /**
+     * The values per-field `dirty` is measured against. Defaults to the first
+     * non-`undefined` `properties` this component sees - which is what an edit
+     * form wants when its values arrive from a fetch after mount. Supplied
+     * automatically by the `form` shorthand; pass it explicitly to re-base
+     * `dirty` without going through a form store.
+     */
+    initialProperties?: Properties;
     /**
      * Top-level form data, threaded down through repeatable groups so a nested
      * field's `appearCondition`/`computeValue` can read the root form. Omitted at
@@ -150,6 +164,13 @@ interface UseDynamicFormOptions {
     initialValues?: Properties;
     validateOnBlur?: boolean;
     validateOnChange?: boolean;
+    /**
+     * Messages for the built-in validators, set once for the whole form instead
+     * of per field. A message passed directly to a validator still wins, and any
+     * key omitted here falls back to the validator's English default. See core's
+     * `MessageCatalog`.
+     */
+    messages?: MessageCatalog;
 }
 interface UseDynamicFormResult {
     data: Properties;
@@ -159,6 +180,18 @@ interface UseDynamicFormResult {
     isValidationComplete: boolean;
     validationStatus: ValidationResult['status'];
     isDirty: boolean;
+    /**
+     * The values `dirty` is measured against: the `initialValues` option until
+     * `reset(newValues)` replaces them. Distinct from that option, which never
+     * changes - pass this to `MultiFieldInput` (or use the `form` shorthand) so
+     * per-field `dirty` survives a reset.
+     */
+    baselineValues: Properties;
+    /**
+     * The entries of `data` that differ from `baselineValues`. Intended for
+     * PATCH-style submits that should carry only what the user actually edited.
+     */
+    getDirtyValues: () => Properties;
     isSubmitting: boolean;
     isSubmitted: boolean;
     touched: Record<string, boolean>;
@@ -183,7 +216,7 @@ interface UseDynamicFormResult {
     validateAsync: () => Promise<boolean>;
     handleSubmit: (onValid: (data: Properties) => void | Promise<void>, onInvalid?: (errors: Record<string, string[]>) => void) => (e?: React.FormEvent) => Promise<void>;
 }
-declare function useDynamicForm({ fields, initialValues, validateOnBlur, validateOnChange, }: UseDynamicFormOptions): UseDynamicFormResult;
+declare function useDynamicForm({ fields, initialValues, validateOnBlur, validateOnChange, messages, }: UseDynamicFormOptions): UseDynamicFormResult;
 
 declare const defaultRenderersMap: Record<string, React.FC<FieldRendererProps>>;
 declare function getDefaultRenderer(type: string): React.FC<FieldRendererProps> | undefined;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import React, { ReactNode, ComponentType } from 'react';
-import { FieldTypeKey, Properties, FieldDescription, LayoutConfig, ValidationResult, FieldRendererProps, FieldTypeMap } from '@dynamic-field-kit/core';
-export { FIELD_RENDERER_PROP_KEYS, FieldDescription, FieldRegistry, FieldRendererProps, FieldTypeKey, LayoutConfig, ValidationContext, ValidationResult, buildFieldRendererProps, collectFieldPaths, indexGroupPathMap, makeFieldId, resolveDisabled, resolveOptions, resolveReadOnly, validateField, validateFieldAsync, validateFields, validateFieldsAsync, validators } from '@dynamic-field-kit/core';
+import { FieldTypeKey, Properties, OptionsStatus, FieldDescription, LayoutConfig, ValidationResult, MessageCatalog, FieldRendererProps, FieldTypeMap } from '@dynamic-field-kit/core';
+export { FIELD_RENDERER_PROP_KEYS, FieldDescription, FieldRegistry, FieldRendererProps, FieldTypeKey, LayoutConfig, ValidationContext, ValidationResult, buildFieldRendererProps, collectFieldPaths, indexGroupPathMap, makeErrorId, makeFieldId, resolveDisabled, resolveOptions, resolveReadOnly, validateField, validateFieldAsync, validateFields, validateFieldsAsync, validators } from '@dynamic-field-kit/core';
 
 type LayoutRenderer<C = unknown> = (props: {
     children: React.ReactNode;
@@ -21,6 +21,8 @@ interface Props$2<T extends FieldTypeKey> {
     label?: string;
     placeholder?: string;
     options?: Properties[];
+    optionsStatus?: OptionsStatus;
+    optionsError?: unknown;
     className?: string;
     description?: ReactNode;
     disabled?: boolean;
@@ -40,8 +42,10 @@ interface Props$2<T extends FieldTypeKey> {
     multiple?: boolean;
     /** Extra, framework-agnostic props forwarded verbatim to the renderer. */
     extraProps?: Properties;
+    /** Renderer-driven refetch for a search-remote field. */
+    onOptionsQuery?: (query: string) => void;
 }
-declare const DynamicInputInner: <T extends FieldTypeKey>({ type, onChange, onBlur, extraProps, ...rendererProps }: Props$2<T>) => React.JSX.Element;
+declare const DynamicInputInner: <T extends FieldTypeKey>({ type, onChange, onBlur, extraProps, onOptionsQuery, ...rendererProps }: Props$2<T>) => React.JSX.Element;
 declare const DynamicInput: typeof DynamicInputInner;
 
 interface Props$1 {
@@ -67,6 +71,8 @@ interface DynamicFormBinding {
     data: Properties;
     errors: Record<string, string[]>;
     touched: Record<string, boolean>;
+    /** The values per-field `dirty` is measured against. See `useDynamicForm`. */
+    baselineValues?: Properties;
     handleChange: (data: Properties) => void;
     handleBlur: (fieldName: string) => void;
 }
@@ -95,6 +101,14 @@ interface Props {
      * restores the pre-1.6 ids), or set `FieldDescription.id` per field.
      */
     idPrefix?: string;
+    /**
+     * The values per-field `dirty` is measured against. Defaults to the first
+     * non-`undefined` `properties` this component sees - which is what an edit
+     * form wants when its values arrive from a fetch after mount. Supplied
+     * automatically by the `form` shorthand; pass it explicitly to re-base
+     * `dirty` without going through a form store.
+     */
+    initialProperties?: Properties;
     /**
      * Top-level form data, threaded down through repeatable groups so a nested
      * field's `appearCondition`/`computeValue` can read the root form. Omitted at
@@ -150,6 +164,13 @@ interface UseDynamicFormOptions {
     initialValues?: Properties;
     validateOnBlur?: boolean;
     validateOnChange?: boolean;
+    /**
+     * Messages for the built-in validators, set once for the whole form instead
+     * of per field. A message passed directly to a validator still wins, and any
+     * key omitted here falls back to the validator's English default. See core's
+     * `MessageCatalog`.
+     */
+    messages?: MessageCatalog;
 }
 interface UseDynamicFormResult {
     data: Properties;
@@ -159,6 +180,18 @@ interface UseDynamicFormResult {
     isValidationComplete: boolean;
     validationStatus: ValidationResult['status'];
     isDirty: boolean;
+    /**
+     * The values `dirty` is measured against: the `initialValues` option until
+     * `reset(newValues)` replaces them. Distinct from that option, which never
+     * changes - pass this to `MultiFieldInput` (or use the `form` shorthand) so
+     * per-field `dirty` survives a reset.
+     */
+    baselineValues: Properties;
+    /**
+     * The entries of `data` that differ from `baselineValues`. Intended for
+     * PATCH-style submits that should carry only what the user actually edited.
+     */
+    getDirtyValues: () => Properties;
     isSubmitting: boolean;
     isSubmitted: boolean;
     touched: Record<string, boolean>;
@@ -183,7 +216,7 @@ interface UseDynamicFormResult {
     validateAsync: () => Promise<boolean>;
     handleSubmit: (onValid: (data: Properties) => void | Promise<void>, onInvalid?: (errors: Record<string, string[]>) => void) => (e?: React.FormEvent) => Promise<void>;
 }
-declare function useDynamicForm({ fields, initialValues, validateOnBlur, validateOnChange, }: UseDynamicFormOptions): UseDynamicFormResult;
+declare function useDynamicForm({ fields, initialValues, validateOnBlur, validateOnChange, messages, }: UseDynamicFormOptions): UseDynamicFormResult;
 
 declare const defaultRenderersMap: Record<string, React.FC<FieldRendererProps>>;
 declare function getDefaultRenderer(type: string): React.FC<FieldRendererProps> | undefined;