@dynamic-field-kit/react 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,195 @@
 # @dynamic-field-kit/react
 
+## 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
+
+- Findable on npm: every package now carries real search keywords, and homepage points at the live demo instead of the README the npm page already renders.
+- b22a6a1: Make the packages findable on npm, and point `homepage` at something worth
+  landing on.
+
+  The keyword lists were three entries long and two of those were the package's
+  own name — nobody searches `dynamic-field-kit/core`. npm ranks search partly on
+  keywords, so in practice these packages could only be found by someone who
+  already knew what they were called. The repository has carried the right
+  vocabulary as GitHub topics all along (`dynamic-forms`, `form-builder`,
+  `form-engine`, `form-validation`, `schema-driven`, `headless`, and the three
+  framework names); npm simply never saw any of it. Each package now carries that
+  vocabulary plus the terms its own users would type, including the schema
+  libraries it actually adapts — zod, yup, valibot and Standard Schema. Not JSON
+  Schema, which it does not support.
+
+  `homepage` pointed at the package's README on GitHub, which is the same text
+  npm already renders on the package page from the shipped README. It now points
+  at the live demo instead, where the forms actually run. The source stays one
+  click away in `repository`.
+
 ## 1.5.0
 
 ### Minor Changes

package/README.md

@@ -41,16 +41,27 @@ 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`, …)
-- `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.
@@ -132,36 +143,87 @@ const form = useDynamicForm({
 });
 
 <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>;
 ```
 
+`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
+/>
+```
+
+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`               | No errors recorded / any value has changed                                        |
+| `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      |
 
-`MultiFieldInput` tracks touched internally regardless; `onBlurField` is the
-hook for driving an external store like this one.
+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
 

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 { FieldDescription, FieldRegistry, FieldRendererProps, FieldTypeKey, LayoutConfig, ValidationResult, resolveDisabled, resolveOptions, resolveReadOnly, validateField, validateFieldAsync, validateFields, validateFieldsAsync, validators } 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';
 
 type LayoutRenderer<C = unknown> = (props: {
     children: React.ReactNode;
@@ -19,6 +19,7 @@ interface Props$2<T extends FieldTypeKey> {
     onChange?: (value: unknown) => void;
     onBlur?: () => void;
     label?: string;
+    placeholder?: string;
     options?: Properties[];
     className?: string;
     description?: ReactNode;
@@ -32,28 +33,68 @@ interface Props$2<T extends FieldTypeKey> {
     ariaInvalid?: boolean;
     ariaDescribedBy?: string;
     ariaRequired?: boolean;
+    min?: number | string;
+    max?: number | string;
+    step?: number | string;
+    accept?: string;
+    multiple?: boolean;
     /** Extra, framework-agnostic props forwarded verbatim to the renderer. */
     extraProps?: Properties;
 }
-declare const DynamicInputInner: <T extends FieldTypeKey>({ type, value, onChange, onBlur, label, options, className, description, disabled, readOnly, required, touched, dirty, error, id, ariaInvalid, ariaDescribedBy, ariaRequired, extraProps, }: Props$2<T>) => React.JSX.Element;
+declare const DynamicInputInner: <T extends FieldTypeKey>({ type, onChange, onBlur, extraProps, ...rendererProps }: Props$2<T>) => React.JSX.Element;
 declare const DynamicInput: typeof DynamicInputInner;
 
 interface Props$1 {
     fieldDescription: FieldDescription;
     renderInfos: Properties;
     rootData?: Properties;
+    /** Per-form-instance id namespace; see core's `makeFieldId`. */
+    idPrefix?: string;
     touched?: boolean;
+    touchedMap?: Record<string, boolean>;
     dirty?: boolean;
+    errors?: Record<string, string[]>;
     onBlurField?: (key: string) => void;
     onValueChangeField: (value: unknown, key: string) => void;
 }
-declare const FieldInput: React.MemoExoticComponent<({ fieldDescription, renderInfos, rootData, touched, dirty, onBlurField, onValueChangeField, }: Props$1) => React.JSX.Element>;
+declare const FieldInput: React.MemoExoticComponent<({ fieldDescription, renderInfos, rootData, idPrefix, touched, touchedMap, dirty, errors, onBlurField, onValueChangeField, }: Props$1) => React.JSX.Element>;
 
+/**
+ * The slice of `useDynamicForm`'s result `MultiFieldInput` needs to drive
+ * itself. Structural, so the hook result can be passed straight in.
+ */
+interface DynamicFormBinding {
+    data: Properties;
+    errors: Record<string, string[]>;
+    touched: Record<string, boolean>;
+    handleChange: (data: Properties) => void;
+    handleBlur: (fieldName: string) => void;
+}
+/** Imperative handle exposed on a `MultiFieldInput` ref. */
+interface MultiFieldInputHandle {
+    /**
+     * Clears the internally tracked touched state. Only meaningful in
+     * uncontrolled mode - when `touched` is passed as a prop, resetting the form
+     * store (e.g. `useDynamicForm().reset()`) already clears it.
+     */
+    resetTouched: () => void;
+    setFieldTouched: (fieldName: string, isTouched?: boolean) => void;
+    /** The touched map currently in effect, controlled or internal. */
+    getTouched: () => Record<string, boolean>;
+}
 interface Props {
     fieldDescriptions: FieldDescription[];
     properties?: Properties;
     onChange?: (data: Properties) => void;
     layout?: LayoutConfig;
+    /**
+     * Namespace for generated field ids: a field renders with
+     * `${idPrefix}-${name}`. Defaults to a value unique to this component
+     * instance, so two forms containing the same field name do not emit
+     * duplicate DOM ids. Pass a fixed string to pin ids (`idPrefix="dfk-field"`
+     * restores the pre-1.6 ids), or set `FieldDescription.id` per field.
+     */
+    idPrefix?: string;
     /**
      * Top-level form data, threaded down through repeatable groups so a nested
      * field's `appearCondition`/`computeValue` can read the root form. Omitted at
@@ -73,8 +114,26 @@ interface Props {
      * map and `validateOnBlur` behaviour.
      */
     onBlurField?: (fieldName: string) => void;
+    /**
+     * Controlled touched map. When provided it is the single source of truth and
+     * the internal tracker is bypassed entirely, so `useDynamicForm().touched`
+     * (updated by `setFieldTouched`, `touchAll`, `handleSubmit` and cleared by
+     * `reset`) is what renderers actually see. Omit it to keep the internal,
+     * blur-only tracker.
+     */
+    touched?: Record<string, boolean>;
+    /** Controlled validation errors. Empty means no renderer error. */
+    errors?: Record<string, string[]>;
+    /** Fires with the next touched map whenever a field is blurred. */
+    onTouchedChange?: (touched: Record<string, boolean>) => void;
+    /**
+     * Shorthand that wires `properties`, `onChange`, `onBlurField` and `touched`
+     * from a `useDynamicForm` result in one prop. Individually passed props win
+     * over the ones derived from here.
+     */
+    form?: DynamicFormBinding;
 }
-declare const MultiFieldInput: ({ fieldDescriptions, properties, onChange, layout, rootData, onValidityChange, onBlurField, }: Props) => React.JSX.Element;
+declare const MultiFieldInput: React.ForwardRefExoticComponent<Props & React.RefAttributes<MultiFieldInputHandle>>;
 
 interface DynamicFormDevToolsProps {
     data: Properties;
@@ -96,6 +155,9 @@ interface UseDynamicFormResult {
     data: Properties;
     errors: Record<string, string[]>;
     isValid: boolean;
+    isValidating: boolean;
+    isValidationComplete: boolean;
+    validationStatus: ValidationResult['status'];
     isDirty: boolean;
     isSubmitting: boolean;
     isSubmitted: boolean;
@@ -103,10 +165,22 @@ interface UseDynamicFormResult {
     setData: React.Dispatch<React.SetStateAction<Properties>>;
     setFieldValue: (name: string, value: unknown) => void;
     setFieldTouched: (name: string, isTouched?: boolean) => void;
+    /** Replaces the whole touched map. */
+    setTouched: React.Dispatch<React.SetStateAction<Record<string, boolean>>>;
+    /**
+     * Marks every field touched at once. `handleSubmit` calls this for you, so
+     * an invalid submit surfaces errors on fields the user never focused - pass
+     * `touched` into `MultiFieldInput` for it to take effect.
+     */
+    touchAll: () => void;
+    /** Clears the touched map without touching data, errors or dirty state. */
+    resetTouched: () => void;
     handleChange: (newData: Properties) => void;
     handleBlur: (fieldName: string) => void;
     reset: (newValues?: Properties) => void;
     validate: () => boolean;
+    /** Validate all fields and await Promise-based rules. */
+    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;
@@ -129,4 +203,4 @@ declare const FieldRegistryProvider: ({ registry, children, }: FieldRegistryProv
 /** The registry for the nearest provider, or the global singleton. */
 declare function useFieldRegistry(): ReactFieldRegistry;
 
-export { DynamicFormDevTools, DynamicInput, FieldInput, FieldRegistryProvider, type FieldRegistryProviderProps, MultiFieldInput, type ReactFieldRegistry, type ReactFieldRenderer, defaultRenderersMap, fieldRegistry, getDefaultRenderer, layoutRegistry, useDynamicForm, useFieldRegistry };
+export { type DynamicFormBinding, DynamicFormDevTools, DynamicInput, FieldInput, FieldRegistryProvider, type FieldRegistryProviderProps, MultiFieldInput, type MultiFieldInputHandle, type ReactFieldRegistry, type ReactFieldRenderer, type UseDynamicFormOptions, type UseDynamicFormResult, defaultRenderersMap, fieldRegistry, getDefaultRenderer, layoutRegistry, useDynamicForm, useFieldRegistry };

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 { FieldDescription, FieldRegistry, FieldRendererProps, FieldTypeKey, LayoutConfig, ValidationResult, resolveDisabled, resolveOptions, resolveReadOnly, validateField, validateFieldAsync, validateFields, validateFieldsAsync, validators } 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';
 
 type LayoutRenderer<C = unknown> = (props: {
     children: React.ReactNode;
@@ -19,6 +19,7 @@ interface Props$2<T extends FieldTypeKey> {
     onChange?: (value: unknown) => void;
     onBlur?: () => void;
     label?: string;
+    placeholder?: string;
     options?: Properties[];
     className?: string;
     description?: ReactNode;
@@ -32,28 +33,68 @@ interface Props$2<T extends FieldTypeKey> {
     ariaInvalid?: boolean;
     ariaDescribedBy?: string;
     ariaRequired?: boolean;
+    min?: number | string;
+    max?: number | string;
+    step?: number | string;
+    accept?: string;
+    multiple?: boolean;
     /** Extra, framework-agnostic props forwarded verbatim to the renderer. */
     extraProps?: Properties;
 }
-declare const DynamicInputInner: <T extends FieldTypeKey>({ type, value, onChange, onBlur, label, options, className, description, disabled, readOnly, required, touched, dirty, error, id, ariaInvalid, ariaDescribedBy, ariaRequired, extraProps, }: Props$2<T>) => React.JSX.Element;
+declare const DynamicInputInner: <T extends FieldTypeKey>({ type, onChange, onBlur, extraProps, ...rendererProps }: Props$2<T>) => React.JSX.Element;
 declare const DynamicInput: typeof DynamicInputInner;
 
 interface Props$1 {
     fieldDescription: FieldDescription;
     renderInfos: Properties;
     rootData?: Properties;
+    /** Per-form-instance id namespace; see core's `makeFieldId`. */
+    idPrefix?: string;
     touched?: boolean;
+    touchedMap?: Record<string, boolean>;
     dirty?: boolean;
+    errors?: Record<string, string[]>;
     onBlurField?: (key: string) => void;
     onValueChangeField: (value: unknown, key: string) => void;
 }
-declare const FieldInput: React.MemoExoticComponent<({ fieldDescription, renderInfos, rootData, touched, dirty, onBlurField, onValueChangeField, }: Props$1) => React.JSX.Element>;
+declare const FieldInput: React.MemoExoticComponent<({ fieldDescription, renderInfos, rootData, idPrefix, touched, touchedMap, dirty, errors, onBlurField, onValueChangeField, }: Props$1) => React.JSX.Element>;
 
+/**
+ * The slice of `useDynamicForm`'s result `MultiFieldInput` needs to drive
+ * itself. Structural, so the hook result can be passed straight in.
+ */
+interface DynamicFormBinding {
+    data: Properties;
+    errors: Record<string, string[]>;
+    touched: Record<string, boolean>;
+    handleChange: (data: Properties) => void;
+    handleBlur: (fieldName: string) => void;
+}
+/** Imperative handle exposed on a `MultiFieldInput` ref. */
+interface MultiFieldInputHandle {
+    /**
+     * Clears the internally tracked touched state. Only meaningful in
+     * uncontrolled mode - when `touched` is passed as a prop, resetting the form
+     * store (e.g. `useDynamicForm().reset()`) already clears it.
+     */
+    resetTouched: () => void;
+    setFieldTouched: (fieldName: string, isTouched?: boolean) => void;
+    /** The touched map currently in effect, controlled or internal. */
+    getTouched: () => Record<string, boolean>;
+}
 interface Props {
     fieldDescriptions: FieldDescription[];
     properties?: Properties;
     onChange?: (data: Properties) => void;
     layout?: LayoutConfig;
+    /**
+     * Namespace for generated field ids: a field renders with
+     * `${idPrefix}-${name}`. Defaults to a value unique to this component
+     * instance, so two forms containing the same field name do not emit
+     * duplicate DOM ids. Pass a fixed string to pin ids (`idPrefix="dfk-field"`
+     * restores the pre-1.6 ids), or set `FieldDescription.id` per field.
+     */
+    idPrefix?: string;
     /**
      * Top-level form data, threaded down through repeatable groups so a nested
      * field's `appearCondition`/`computeValue` can read the root form. Omitted at
@@ -73,8 +114,26 @@ interface Props {
      * map and `validateOnBlur` behaviour.
      */
     onBlurField?: (fieldName: string) => void;
+    /**
+     * Controlled touched map. When provided it is the single source of truth and
+     * the internal tracker is bypassed entirely, so `useDynamicForm().touched`
+     * (updated by `setFieldTouched`, `touchAll`, `handleSubmit` and cleared by
+     * `reset`) is what renderers actually see. Omit it to keep the internal,
+     * blur-only tracker.
+     */
+    touched?: Record<string, boolean>;
+    /** Controlled validation errors. Empty means no renderer error. */
+    errors?: Record<string, string[]>;
+    /** Fires with the next touched map whenever a field is blurred. */
+    onTouchedChange?: (touched: Record<string, boolean>) => void;
+    /**
+     * Shorthand that wires `properties`, `onChange`, `onBlurField` and `touched`
+     * from a `useDynamicForm` result in one prop. Individually passed props win
+     * over the ones derived from here.
+     */
+    form?: DynamicFormBinding;
 }
-declare const MultiFieldInput: ({ fieldDescriptions, properties, onChange, layout, rootData, onValidityChange, onBlurField, }: Props) => React.JSX.Element;
+declare const MultiFieldInput: React.ForwardRefExoticComponent<Props & React.RefAttributes<MultiFieldInputHandle>>;
 
 interface DynamicFormDevToolsProps {
     data: Properties;
@@ -96,6 +155,9 @@ interface UseDynamicFormResult {
     data: Properties;
     errors: Record<string, string[]>;
     isValid: boolean;
+    isValidating: boolean;
+    isValidationComplete: boolean;
+    validationStatus: ValidationResult['status'];
     isDirty: boolean;
     isSubmitting: boolean;
     isSubmitted: boolean;
@@ -103,10 +165,22 @@ interface UseDynamicFormResult {
     setData: React.Dispatch<React.SetStateAction<Properties>>;
     setFieldValue: (name: string, value: unknown) => void;
     setFieldTouched: (name: string, isTouched?: boolean) => void;
+    /** Replaces the whole touched map. */
+    setTouched: React.Dispatch<React.SetStateAction<Record<string, boolean>>>;
+    /**
+     * Marks every field touched at once. `handleSubmit` calls this for you, so
+     * an invalid submit surfaces errors on fields the user never focused - pass
+     * `touched` into `MultiFieldInput` for it to take effect.
+     */
+    touchAll: () => void;
+    /** Clears the touched map without touching data, errors or dirty state. */
+    resetTouched: () => void;
     handleChange: (newData: Properties) => void;
     handleBlur: (fieldName: string) => void;
     reset: (newValues?: Properties) => void;
     validate: () => boolean;
+    /** Validate all fields and await Promise-based rules. */
+    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;
@@ -129,4 +203,4 @@ declare const FieldRegistryProvider: ({ registry, children, }: FieldRegistryProv
 /** The registry for the nearest provider, or the global singleton. */
 declare function useFieldRegistry(): ReactFieldRegistry;
 
-export { DynamicFormDevTools, DynamicInput, FieldInput, FieldRegistryProvider, type FieldRegistryProviderProps, MultiFieldInput, type ReactFieldRegistry, type ReactFieldRenderer, defaultRenderersMap, fieldRegistry, getDefaultRenderer, layoutRegistry, useDynamicForm, useFieldRegistry };
+export { type DynamicFormBinding, DynamicFormDevTools, DynamicInput, FieldInput, FieldRegistryProvider, type FieldRegistryProviderProps, MultiFieldInput, type MultiFieldInputHandle, type ReactFieldRegistry, type ReactFieldRenderer, type UseDynamicFormOptions, type UseDynamicFormResult, defaultRenderersMap, fieldRegistry, getDefaultRenderer, layoutRegistry, useDynamicForm, useFieldRegistry };