@dynamic-field-kit/angular 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,171 @@
 # @dynamic-field-kit/angular
 
+## 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,7 +37,9 @@ 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`
 - `LayoutConfig` / `ColumnLayoutConfig` / `RowLayoutConfig` /
@@ -51,20 +53,43 @@ 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`
+
+`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,6 +166,8 @@ import {
       <dfk-multi-field-input
         [fieldDescriptions]="fields"
         [properties]="store.data()"
+        [touched]="store.touched()"
+        [errors]="store.errors()"
         (onChange)="store.handleChange($event)"
         (onBlurField)="store.handleBlur($event)"
       ></dfk-multi-field-input>
@@ -165,14 +192,20 @@ export class MyForm {
 | ----------------------------------- | --------------------------------------------------------------------------------- |
 | `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 — 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      |
 
@@ -180,6 +213,31 @@ export class MyForm {
 `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` ·