@dynamic-field-kit/angular 1.10.0 → 1.11.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @dynamic-field-kit/angular
 
+## 1.11.1
+
+### Patch Changes
+
+- ba3538b: Angular 22 is accepted: `@angular/core` and `@angular/common` are now `>=16 <23`. An app on Angular 22 could not install the package before, as npm refused the peer range. `scripts/verify-angular-peer-range.js` now checks Angular 16 and 22, and the demo app was built with the Angular 22 CLI and used in a browser.
+- ba3538b: A registered field component that uses `OnPush` change detection now shows the props the form hands it after the first render. They were assigned to the component without marking it for check, so a value the form set itself, such as a computed field, did not show. From Angular 22 every component that names no strategy is `OnPush`, so on 22 this hit every registered field component.
+- Angular 22 support.
+
+## 1.11.0
+
+### Minor Changes
+
+- Input masks, titled sections and errors from the server; the built-in controls of the Vue and Angular adapters keep the focus and stay one element.
+- b7ffb5c: Input masks. A field takes `mask`: a pattern such as `'(999) 999-9999'` (`9` a digit, `a` a letter, `*` either, anything else fixed) or a `{ format, parse }` pair. The renderer receives the formatted text as `value`, the form stores the unformatted value (`'5551234567'`), and validators, `computeValue`, drafts and `onSubmit` see that stored value. A separator appears with the character after it, a character that does not fit is neither stored nor left on screen, and Backspace on a separator removes the character before it. Renderers need no change. Core gains `createInputMask(pattern)` for the same formatting outside a form, the `InputMask` and `FieldMask` types, and `applyMask` / `parseInput` on `buildFieldRendererProps` for adapters; a mask takes effect when both core and the adapter are 1.11 or newer.
+- 4326470: Sections. A field with `section: FieldDescription[]` is a titled section: `data[name]` is one object shaped by the nested fields, the non-repeating sibling of a group. Every adapter's `MultiFieldInput` renders it as a `<fieldset>` with `label` as its `<legend>`. Errors, pending rules and touched flags of the fields inside are keyed by path (`address.street`), `appearCondition` and `disabled` / `disabledCondition` on the section apply to all of it, and sections nest in groups and in each other. `validateFields`, `validateFieldsAsync` and `collectFieldPaths` look inside sections; `fieldsFromJsonSchema` now turns a nested object into a section instead of reporting it, and `fieldsToJsonSchema` writes a section as a nested object. Core gains `isFieldSection` and `sectionPathMap`. Sections need core and the adapter at 1.11 or newer.
+- 5eaa3ca: Errors from the server. Every form store (`useDynamicForm` in React and Vue, `createDynamicForm` in Svelte, `createDynamicFormStore` in Angular) gains `setServerErrors(errors)`, `clearServerErrors(name?)` and `serverErrors`: what a backend refused is shown in `errors` after a field's own errors, its fields are marked touched, and an error stays until the value it was about changes, until it is cleared or the form is reset, or until the next submit. `isValid` keeps speaking for the form's own rules. Core gains `serverErrorsFrom(body, { paths })`, which reads the usual response shapes (a field map, `errors` as a map or a list, Zod's `issues` and flattened error, JSON Pointers) into that map, and `FORM_ERROR_KEY` for errors that name no field.
+
+### Patch Changes
+
+- 673fce2: The built-in controls, used when no renderer is registered for a field type, are no longer drawn again on every change. Each change used to add a new input, textarea, select or checkbox to the page and leave the earlier ones there, so a form filled in with the built-in controls ended up with several copies of each field; the same happened to the HTML of a function renderer and to the "Unknown field type" message. A built-in control is now updated where it stands: it stays one element, keeps the focus while it is typed in, and a number that is still being typed (`1.50`) is not rewritten under the caret. Its `aria-describedby` is taken off again when the error it pointed at is gone.
+
 ## 1.10.0
 
 ### Minor Changes

package/README.md

@@ -86,16 +86,23 @@ For a complete UI integration, see the
 
 ## Supported Angular versions
 
-The package declares `@angular/core` and `@angular/common` as `>=16 <22`,
+The package declares `@angular/core` and `@angular/common` as `>=16 <23`,
 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 packed tarballs against Angular 16 and 22 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.
+the setup below is written for. The setup works unchanged on 22.
+
+Angular 22 makes `OnPush` the default for a component that names no change
+detection strategy, and that includes the field components you register. They
+need nothing extra for it: the adapter marks a rendered field component for
+check whenever it hands it new props. Up to 1.11.0 it did not, so on Angular 22
+a value the form set itself, such as a computed field, did not show in a
+registered component.
 
 ## Basic setup
 

package/dist/fesm2022/dynamic-field-kit-angular.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { EventEmitter, Output, Input, Component, InjectionToken, inject, ViewContainerRef, ViewChild, ChangeDetectionStrategy, HostListener, signal, computed, NgModule } from '@angular/core';
+import { EventEmitter, Output, Input, Component, InjectionToken, inject, ChangeDetectorRef, ViewContainerRef, ViewChild, ChangeDetectionStrategy, HostListener, signal, computed, NgModule } from '@angular/core';
 import * as i1 from '@angular/common';
 import { CommonModule, NgIf, NgClass, NgFor, JsonPipe } from '@angular/common';
 import { fieldRegistry, makeErrorId, isAsyncOptions, createOptionsLoader, buildFieldRendererProps, makeFieldId, indexGroupPathMap, applyComputedValues, validateFields, canAddGroupItem, canRemoveGroupItem, createGroupItem, createMessageResolver, validateFieldsAsync, collectFieldPaths } from '@dynamic-field-kit/core';
@@ -162,6 +162,11 @@ class DynamicInput extends BaseInputComponent {
     host;
     compRef;
     inputInstance;
+    // The built-in control in use, the type it was built for and the options it lists. Kept so that a
+    // change updates the control where it stands.
+    builtIn;
+    builtInType;
+    builtInOptions;
     subscriptions = [];
     // Tracks which KNOWN_PROPS were actually supplied to DynamicInput (via
     // SimpleChanges), independent of TS class-field emit. See applyProps.
@@ -204,6 +209,12 @@ class DynamicInput extends BaseInputComponent {
         if (changes['extraProps']) {
             this.applyExtraProps(this.inputInstance);
         }
+        // The props above are assigned to the instance, which Angular does not
+        // see. Checking the host view alone skips an OnPush renderer that is not
+        // marked, and from Angular 22 every renderer that names no strategy is
+        // OnPush: a value the form set itself (a computed field, a reset) never
+        // showed. The renderer's own view is marked first.
+        this.compRef?.injector.get(ChangeDetectorRef).markForCheck();
         this.compRef?.changeDetectorRef?.detectChanges();
     }
     cleanup() {
@@ -219,6 +230,21 @@ class DynamicInput extends BaseInputComponent {
         this.compRef = undefined;
         this.inputInstance = undefined;
     }
+    /**
+     * Removes what this component put into the host element itself: a built-in
+     * control, the HTML of a function renderer, an error message. `host.clear()`
+     * does not: it only knows the components it created, which sit beside the
+     * host element, not inside it.
+     */
+    clearOwnNodes() {
+        const element = this.host.element.nativeElement;
+        while (element.firstChild) {
+            element.removeChild(element.firstChild);
+        }
+        this.builtIn = undefined;
+        this.builtInType = undefined;
+        this.builtInOptions = undefined;
+    }
     /** The id `ariaDescribedBy` points at. See core's `makeErrorId`. */
     errorNodeId() {
         return makeErrorId(this.id ?? '');
@@ -241,8 +267,17 @@ class DynamicInput extends BaseInputComponent {
     }
     render() {
         const Renderer = this.registry.get(this.type);
+        // A built-in control of the same type is updated where it stands. Built
+        // again on every change, as it used to be, it would lose the focus after
+        // each character typed - and the ones built before stayed in the page.
+        if (!Renderer && this.builtIn && this.builtInType === this.type) {
+            this.syncBuiltIn(this.builtIn);
+            this.applyFallbackAria();
+            return;
+        }
         this.cleanup();
         this.host.clear();
+        this.clearOwnNodes();
         if (!Renderer) {
             if (this.renderDefaultFallbackHTML5(this.type)) {
                 this.applyFallbackAria();
@@ -411,146 +446,155 @@ class DynamicInput extends BaseInputComponent {
      *
      * `render()` re-runs on every ngOnChanges while the fallback is in use (there
      * is no component instance to sync props into), so this stays current as the
-     * field's error comes and goes.
+     * field's error comes and goes. The control is the same one from change to
+     * change, so a flag that is no longer given is taken off again.
      */
     applyFallbackAria() {
         const control = this.host.element.nativeElement.querySelector('input, select, textarea');
         if (!control) {
             return;
         }
-        if (this.ariaInvalid !== undefined) {
-            control.setAttribute('aria-invalid', String(this.ariaInvalid));
-        }
-        if (this.ariaRequired !== undefined) {
-            control.setAttribute('aria-required', String(this.ariaRequired));
-        }
-        if (this.ariaDescribedBy) {
-            control.setAttribute('aria-describedby', this.ariaDescribedBy);
-        }
+        const flag = (name, value) => {
+            if (value === undefined) {
+                control.removeAttribute(name);
+            }
+            else {
+                control.setAttribute(name, value);
+            }
+        };
+        flag('aria-invalid', this.ariaInvalid === undefined ? undefined : String(this.ariaInvalid));
+        flag('aria-required', this.ariaRequired === undefined ? undefined : String(this.ariaRequired));
+        flag('aria-describedby', this.ariaDescribedBy || undefined);
     }
+    /**
+     * Builds the built-in control for `type` and puts it in the host element.
+     * What the control shows is set by `syncBuiltIn`, here and on every later
+     * change.
+     */
     renderDefaultFallbackHTML5(type) {
-        const nativeEl = this.host.element.nativeElement;
+        const control = this.createBuiltIn(type);
+        if (!control) {
+            return false;
+        }
+        this.builtIn = control;
+        this.builtInType = type;
+        this.syncBuiltIn(control);
+        this.host.element.nativeElement.appendChild(control);
+        return true;
+    }
+    createBuiltIn(type) {
         if (type === 'text' ||
             type === 'password' ||
             type === 'email' ||
             type === 'number') {
             const input = document.createElement('input');
             input.type = type;
-            if (this.id) {
-                input.id = this.id;
-            }
-            if (this.className) {
-                input.className = this.className;
-            }
-            if (this.placeholder) {
-                input.placeholder = this.placeholder;
-            }
-            if (this.disabled) {
-                input.disabled = true;
-            }
-            if (this.readOnly) {
-                input.readOnly = true;
-            }
-            if (this.required) {
-                input.required = true;
-            }
-            input.value = (this.value ?? '').toString();
-            input.addEventListener('input', (e) => {
-                const raw = e.target.value;
+            input.addEventListener('input', () => {
+                const raw = input.value;
                 const val = type === 'number' ? (raw === '' ? undefined : Number(raw)) : raw;
                 this.emitValue(val);
             });
-            nativeEl.appendChild(input);
-            return true;
+            return input;
         }
         if (type === 'textarea') {
             const textarea = document.createElement('textarea');
-            if (this.id) {
-                textarea.id = this.id;
-            }
-            if (this.className) {
-                textarea.className = this.className;
-            }
-            if (this.placeholder) {
-                textarea.placeholder = this.placeholder;
-            }
-            if (this.disabled) {
-                textarea.disabled = true;
-            }
-            if (this.readOnly) {
-                textarea.readOnly = true;
-            }
-            if (this.required) {
-                textarea.required = true;
-            }
-            textarea.value = this.value ?? '';
-            textarea.addEventListener('input', (e) => {
-                this.emitValue(e.target.value);
+            textarea.addEventListener('input', () => {
+                this.emitValue(textarea.value);
             });
-            nativeEl.appendChild(textarea);
-            return true;
+            return textarea;
         }
         if (type === 'checkbox') {
             const checkbox = document.createElement('input');
             checkbox.type = 'checkbox';
-            if (this.id) {
-                checkbox.id = this.id;
-            }
-            if (this.className) {
-                checkbox.className = this.className;
-            }
-            if (this.disabled || this.readOnly) {
-                checkbox.disabled = true;
-            }
-            if (this.required) {
-                checkbox.required = true;
-            }
-            checkbox.checked = Boolean(this.value);
-            checkbox.addEventListener('change', (e) => {
-                this.emitValue(e.target.checked);
+            checkbox.addEventListener('change', () => {
+                this.emitValue(checkbox.checked);
             });
-            nativeEl.appendChild(checkbox);
-            return true;
+            return checkbox;
         }
         if (type === 'select') {
             const select = document.createElement('select');
-            if (this.id) {
-                select.id = this.id;
-            }
-            if (this.className) {
-                select.className = this.className;
+            select.addEventListener('change', () => {
+                this.emitValue(select.value);
+            });
+            return select;
+        }
+        return null;
+    }
+    /** Brings a built-in control in line with the current inputs. */
+    syncBuiltIn(control) {
+        const attribute = (name, value) => {
+            if (value) {
+                control.setAttribute(name, value);
             }
-            if (this.disabled || this.readOnly) {
-                select.disabled = true;
+            else {
+                control.removeAttribute(name);
             }
-            if (this.required) {
-                select.required = true;
+        };
+        attribute('id', this.id);
+        attribute('class', this.className);
+        control.required = Boolean(this.required);
+        if (control instanceof HTMLSelectElement) {
+            // a select has no read-only state of its own
+            control.disabled = Boolean(this.disabled || this.readOnly);
+            this.syncBuiltInOptions(control);
+            return;
+        }
+        if (control instanceof HTMLInputElement && control.type === 'checkbox') {
+            // nor has a checkbox
+            control.disabled = Boolean(this.disabled || this.readOnly);
+            control.checked = Boolean(this.value);
+            return;
+        }
+        attribute('placeholder', this.placeholder);
+        control.disabled = Boolean(this.disabled);
+        control.readOnly = Boolean(this.readOnly);
+        const next = (this.value ?? '').toString();
+        // Written only when it says something else than the control already
+        // does: writing the text a user is in the middle of typing moves the
+        // caret to its end. For a number, "the same" is the same number: "1.50"
+        // is 1.5, and must not be rewritten to "1.5" under the caret.
+        const same = control.type === 'number' && control.value !== '' && next !== ''
+            ? Number(control.value) === Number(next)
+            : control.value === next;
+        if (!same) {
+            control.value = next;
+        }
+    }
+    /** The options of a built-in select, rebuilt only when the list changed, and the one that is chosen. */
+    syncBuiltInOptions(select) {
+        const options = (this.options || []).map((opt) => {
+            const optObj = opt;
+            const optVal = optObj['value'] ?? optObj['id'] ?? opt;
+            const optLabel = optObj['label'] ?? optObj['name'] ?? String(optVal);
+            return { value: String(optVal), label: String(optLabel) };
+        });
+        const listed = JSON.stringify(options);
+        if (listed !== this.builtInOptions) {
+            this.builtInOptions = listed;
+            while (select.firstChild) {
+                select.removeChild(select.firstChild);
             }
             const defaultOpt = document.createElement('option');
             defaultOpt.value = '';
             defaultOpt.disabled = true;
             defaultOpt.textContent = '-- Select --';
             select.appendChild(defaultOpt);
-            const options = this.options || [];
-            options.forEach((opt) => {
-                const optObj = opt;
-                const optVal = optObj['value'] ?? optObj['id'] ?? opt;
-                const optLabel = optObj['label'] ?? optObj['name'] ?? String(optVal);
+            for (const option of options) {
                 const optionEl = document.createElement('option');
-                optionEl.value = String(optVal);
-                optionEl.textContent = String(optLabel);
-                if (String(optVal) === String(this.value)) {
-                    optionEl.selected = true;
-                }
+                optionEl.value = option.value;
+                optionEl.textContent = option.label;
                 select.appendChild(optionEl);
-            });
-            select.addEventListener('change', (e) => {
-                this.emitValue(e.target.value);
-            });
-            nativeEl.appendChild(select);
-            return true;
+            }
+        }
+        const wanted = String(this.value);
+        const all = Array.from(select.options);
+        // Without a match the first option that can be chosen is shown, which is
+        // what a select built from scratch shows.
+        const chosen = all.find((option) => !option.disabled && option.value === wanted) ??
+            all.find((option) => !option.disabled);
+        if (chosen && !chosen.selected) {
+            chosen.selected = true;
         }
-        return false;
     }
     renderError(message) {
         const el = document.createElement('div');
@@ -650,6 +694,33 @@ class FieldInput {
     onOptionsQuery = (query) => {
         this.loader?.setQuery(query);
     };
+    /**
+     * A masked field shows formatted text; `parseInput` turns what its renderer
+     * reports back into the value to store.
+     */
+    handleValueChange(input) {
+        const props = this.rendererProps;
+        const parseInput = props?.parseInput;
+        if (props &&
+            parseInput &&
+            typeof input === 'string' &&
+            input !== props.value) {
+            // The text on screen is no longer the text this field last handed down,
+            // and the text to show next may well be that same one: the mask takes
+            // nothing from a letter where a digit belongs, or from a character past
+            // its last place. A binding that does not change writes nothing, so the
+            // refused character would stay on screen. Tell the renderer what it
+            // holds now; whatever is shown next is then a change.
+            this.rendererProps = { ...props, value: input };
+            this.cdr.detectChanges();
+            this.rendererProps = props;
+            this.cdr.markForCheck();
+        }
+        this.onValueChangeField.emit({
+            value: parseInput ? parseInput(input) : input,
+            key: this.fieldDescription.name,
+        });
+    }
     ngOnChanges(_changes) {
         this.syncOptionsLoader();
         this.rendererProps = this.buildProps();
@@ -696,6 +767,7 @@ class FieldInput {
             touched: this.touched,
             dirty: this.dirty,
             optionsState: this.optionsState,
+            applyMask: true,
         });
         // Explicitly bound inputs override what the field description resolves to,
         // so a host can still drive options/disabled/error itself.
@@ -739,9 +811,7 @@ class FieldInput {
       [step]="p.step"
       [accept]="p.accept"
       [multiple]="p.multiple"
-      (valueChange)="
-        onValueChangeField.emit({ value: $event, key: fieldDescription!.name })
-      "
+      (valueChange)="handleValueChange($event)"
       (focusout)="onBlurField.emit(fieldDescription!.name)"
       [extraProps]="p.extraProps"
       [onOptionsQuery]="onOptionsQuery"
@@ -782,9 +852,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
       [step]="p.step"
       [accept]="p.accept"
       [multiple]="p.multiple"
-      (valueChange)="
-        onValueChangeField.emit({ value: $event, key: fieldDescription!.name })
-      "
+      (valueChange)="handleValueChange($event)"
       (focusout)="onBlurField.emit(fieldDescription!.name)"
       [extraProps]="p.extraProps"
       [onOptionsQuery]="onOptionsQuery"
@@ -821,6 +889,50 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
                 type: Output
             }] } });
 
+const NO_VALUES = Object.freeze({});
+/**
+ * The fields of a titled section, or undefined for any other field. A field
+ * that also has `fields` is a repeatable group.
+ */
+function sectionFieldsOf(field) {
+    return Array.isArray(field.section) && !Array.isArray(field.fields)
+        ? field.section
+        : undefined;
+}
+/** The object a section stores, or an empty one that keeps its identity. */
+function sectionValuesOf(data, name) {
+    const value = data[name];
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : NO_VALUES;
+}
+/**
+ * The entries of one section, keyed from inside it: `address.street` becomes
+ * `street`. An absent map stays absent, which a nested form reads as
+ * "uncontrolled".
+ */
+function sectionPathMap(source, sectionName) {
+    if (source === undefined) {
+        return undefined;
+    }
+    const scoped = {};
+    const prefix = `${sectionName}.`;
+    for (const [path, value] of Object.entries(source)) {
+        if (path.startsWith(prefix) && path.length > prefix.length) {
+            scoped[path.slice(prefix.length)] = value;
+        }
+    }
+    return scoped;
+}
+/**
+ * Whether a section is disabled, by its flag or by its condition: the test
+ * validation applies before it skips the section.
+ */
+function isSectionDisabled(field, data, rootData) {
+    return (field.disabled === true ||
+        field.disabledCondition?.(data, rootData) === true);
+}
+
 const DEFAULT_BREAKPOINT = 768;
 // Per-instance id counter, so two forms rendering the same field name emit
 // different DOM ids.
@@ -886,6 +998,10 @@ class MultiFieldInput {
     indexedErrors = new Map();
     indexedTouchedSource;
     indexedTouched = new Map();
+    sectionErrorsSource;
+    sectionErrors = new Map();
+    sectionTouchedSource;
+    sectionTouched = new Map();
     get effectiveIdPrefix() {
         return this.idPrefix ?? `dfk-${this.instanceId}`;
     }
@@ -944,6 +1060,41 @@ class MultiFieldInput {
     handleGroupBlur(fieldName, index, key) {
         this.handleBlurField(`${fieldName}[${index}].${key}`);
     }
+    /** The fields of a titled section, or undefined for any other field. */
+    sectionOf(field) {
+        return sectionFieldsOf(field);
+    }
+    sectionValues(fieldName) {
+        return sectionValuesOf(this.data, fieldName);
+    }
+    isSectionDisabled(field) {
+        return isSectionDisabled(field, this.data, this.rootData ?? this.data);
+    }
+    // Cached per source map for the reason given at `touchedForItem`: a fresh
+    // object in a template binding is a new identity on every pass.
+    errorsForSection(fieldName) {
+        if (this.sectionErrorsSource !== this.errors) {
+            this.sectionErrorsSource = this.errors;
+            this.sectionErrors.clear();
+        }
+        if (!this.sectionErrors.has(fieldName)) {
+            this.sectionErrors.set(fieldName, sectionPathMap(this.errors, fieldName));
+        }
+        return this.sectionErrors.get(fieldName);
+    }
+    touchedForSection(fieldName) {
+        const current = this.effectiveTouched;
+        if (this.sectionTouchedSource !== current) {
+            this.sectionTouchedSource = current;
+            this.sectionTouched.clear();
+        }
+        let scoped = this.sectionTouched.get(fieldName);
+        if (!scoped) {
+            scoped = sectionPathMap(current, fieldName) ?? EMPTY_TOUCHED;
+            this.sectionTouched.set(fieldName, scoped);
+        }
+        return scoped;
+    }
     /**
      * Clears the internally tracked touched state. Only meaningful in
      * uncontrolled mode - when `touched` is bound, resetting the form store
@@ -1125,7 +1276,7 @@ class MultiFieldInput {
     >
       <ng-container *ngFor="let field of visibleFields; trackBy: trackByFn">
         <dfk-field-input
-          *ngIf="!field.fields"
+          *ngIf="!field.fields && !sectionOf(field)"
           [fieldDescription]="field"
           [data]="data"
           [rootData]="rootData"
@@ -1138,6 +1289,29 @@ class MultiFieldInput {
           (onBlurField)="handleBlurField($event)"
         ></dfk-field-input>
 
+        <!--
+          A titled section: one nested form over the object data[name], with
+          the errors, touched flags and blur of its fields keyed
+          name.childName. A fieldset names the group through its legend and
+          disables every control inside it natively.
+        -->
+        <fieldset
+          *ngIf="!field.fields && sectionOf(field) as section"
+          [class]="field.className"
+          [disabled]="isSectionDisabled(field)"
+        >
+          <legend *ngIf="field.label">{{ field.label }}</legend>
+          <dfk-multi-field-input
+            [fieldDescriptions]="section"
+            [properties]="sectionValues(field.name)"
+            [rootData]="rootData ?? data"
+            [errors]="errorsForSection(field.name)"
+            [touched]="touchedForSection(field.name)"
+            (onBlurField)="handleBlurField(field.name + '.' + $event)"
+            (onChange)="onFieldChange({ value: $event, key: field.name })"
+          ></dfk-multi-field-input>
+        </fieldset>
+
         <div *ngIf="field.fields" [class]="field.className">
           <div *ngIf="field.label">{{ field.label }}</div>
           <div
@@ -1217,7 +1391,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
     >
       <ng-container *ngFor="let field of visibleFields; trackBy: trackByFn">
         <dfk-field-input
-          *ngIf="!field.fields"
+          *ngIf="!field.fields && !sectionOf(field)"
           [fieldDescription]="field"
           [data]="data"
           [rootData]="rootData"
@@ -1230,6 +1404,29 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
           (onBlurField)="handleBlurField($event)"
         ></dfk-field-input>
 
+        <!--
+          A titled section: one nested form over the object data[name], with
+          the errors, touched flags and blur of its fields keyed
+          name.childName. A fieldset names the group through its legend and
+          disables every control inside it natively.
+        -->
+        <fieldset
+          *ngIf="!field.fields && sectionOf(field) as section"
+          [class]="field.className"
+          [disabled]="isSectionDisabled(field)"
+        >
+          <legend *ngIf="field.label">{{ field.label }}</legend>
+          <dfk-multi-field-input
+            [fieldDescriptions]="section"
+            [properties]="sectionValues(field.name)"
+            [rootData]="rootData ?? data"
+            [errors]="errorsForSection(field.name)"
+            [touched]="touchedForSection(field.name)"
+            (onBlurField)="handleBlurField(field.name + '.' + $event)"
+            (onChange)="onFieldChange({ value: $event, key: field.name })"
+          ></dfk-multi-field-input>
+        </fieldset>
+
         <div *ngIf="field.fields" [class]="field.className">
           <div *ngIf="field.label">{{ field.label }}</div>
           <div
@@ -1616,6 +1813,58 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
                 type: Input
             }] } });
 
+function toFieldErrors(input) {
+    const errors = {};
+    for (const [path, value] of Object.entries(input)) {
+        const messages = (typeof value === 'string' ? [value] : [...(value ?? [])])
+            .filter((message) => typeof message === 'string')
+            .map((message) => message.trim())
+            .filter((message) => message !== '');
+        if (messages.length > 0) {
+            errors[path] = messages;
+        }
+    }
+    return errors;
+}
+/** The form's own errors with the server's after them, field by field. */
+function mergeFieldErrors(own, server) {
+    const paths = Object.keys(server);
+    if (paths.length === 0) {
+        return own;
+    }
+    const merged = { ...own };
+    for (const path of paths) {
+        merged[path] = [...(own[path] ?? []), ...server[path]];
+    }
+    return merged;
+}
+function valueAt(data, path) {
+    let value = data;
+    for (const segment of path.match(/[^.[\]]+/g) ?? []) {
+        if (value === null || typeof value !== 'object') {
+            return undefined;
+        }
+        value = value[segment];
+    }
+    return value;
+}
+/**
+ * The server's errors without those of the fields whose value changed: the
+ * server judged a value that is no longer the one in the field.
+ */
+function withoutChangedFields(server, previous, next) {
+    const paths = Object.keys(server);
+    const kept = paths.filter((path) => Object.is(valueAt(previous, path), valueAt(next, path)));
+    if (kept.length === paths.length) {
+        return server;
+    }
+    return Object.fromEntries(kept.map((path) => [path, server[path]]));
+}
+/** The errors without those of one field. */
+function withoutField(errors, name) {
+    return Object.fromEntries(Object.entries(errors).filter(([path]) => path !== name));
+}
+
 function createDynamicFormStore(options) {
     const fields = options.fields;
     const initialValues = options.initialValues || {};
@@ -1630,6 +1879,22 @@ function createDynamicFormStore(options) {
     // changes. See the React adapter for the full rationale.
     const baselineValues = signal({ ...data() }, ...(ngDevMode ? [{ debugName: "baselineValues" }] : /* istanbul ignore next */ []));
     const errors = signal({}, ...(ngDevMode ? [{ debugName: "errors" }] : /* istanbul ignore next */ []));
+    // `errors` stays the writable signal it was, holding what is shown: the
+    // form's own errors with the server's after them. The two parts are kept
+    // apart here so that either can change without losing the other.
+    let ownErrors = {};
+    const serverErrors = signal({}, ...(ngDevMode ? [{ debugName: "serverErrors" }] : /* istanbul ignore next */ []));
+    function showErrors(own) {
+        ownErrors = own;
+        errors.set(mergeFieldErrors(own, serverErrors()));
+    }
+    function showServerErrors(server) {
+        if (server === serverErrors()) {
+            return;
+        }
+        serverErrors.set(server);
+        errors.set(mergeFieldErrors(ownErrors, server));
+    }
     const isDirty = signal(false, ...(ngDevMode ? [{ debugName: "isDirty" }] : /* istanbul ignore next */ []));
     const touched = signal({}, ...(ngDevMode ? [{ debugName: "touched" }] : /* istanbul ignore next */ []));
     const isSubmitting = signal(false, ...(ngDevMode ? [{ debugName: "isSubmitting" }] : /* istanbul ignore next */ []));
@@ -1651,7 +1916,7 @@ function createDynamicFormStore(options) {
     }
     function validate() {
         const res = validateFields(fields, data(), undefined, validationContext);
-        errors.set(res.errors);
+        showErrors(res.errors);
         return commitSyncResult(res);
     }
     async function validateAsync() {
@@ -1669,7 +1934,7 @@ function createDynamicFormStore(options) {
             if (run !== validationRun || data() !== snapshot) {
                 return res.valid;
             }
-            errors.set(res.errors);
+            showErrors(res.errors);
             validationResult.set(res);
             return res.valid;
         }
@@ -1681,6 +1946,8 @@ function createDynamicFormStore(options) {
     }
     function handleChange(newData) {
         const next = applyComputedValues(fields, newData);
+        // The server judged the old value: its verdict goes with it.
+        showServerErrors(withoutChangedFields(serverErrors(), data(), next));
         data.set(next);
         isDirty.set(true);
         validationController?.abort();
@@ -1689,7 +1956,7 @@ function createDynamicFormStore(options) {
         const res = validateFields(fields, next, undefined, validationContext);
         commitSyncResult(res);
         if (validateOnChange) {
-            errors.set(res.errors);
+            showErrors(res.errors);
         }
     }
     function setFieldValue(name, value) {
@@ -1721,11 +1988,36 @@ function createDynamicFormStore(options) {
     function resetTouched() {
         touched.set({});
     }
+    /**
+     * Shows the errors a backend answered with, and marks their fields touched
+     * so they are displayed. An error stays until the value it was about
+     * changes, until `clearServerErrors` or `reset`, or until the next submit.
+     * `isValid` is not affected: it speaks for the form's own rules. Core's
+     * `serverErrorsFrom(body)` turns the usual response shapes into this map.
+     */
+    function setServerErrors(input) {
+        const next = toFieldErrors(input);
+        showServerErrors(next);
+        touched.set({
+            ...touched(),
+            ...Object.fromEntries(Object.keys(next).map((path) => [path, true])),
+        });
+    }
+    /** Removes the server errors of one field, or all of them. */
+    function clearServerErrors(name) {
+        if (name === undefined) {
+            showServerErrors({});
+            return;
+        }
+        if (name in serverErrors()) {
+            showServerErrors(withoutField(serverErrors(), name));
+        }
+    }
     function handleBlur(fieldName) {
         setFieldTouched(fieldName, true);
         if (validateOnBlur) {
             const res = validateFields(fields, data(), undefined, validationContext);
-            errors.set(res.errors);
+            showErrors(res.errors);
             commitSyncResult(res);
         }
     }
@@ -1734,7 +2026,8 @@ function createDynamicFormStore(options) {
         const next = applyComputedValues(fields, seed);
         data.set(next);
         baselineValues.set({ ...next });
-        errors.set({});
+        serverErrors.set({});
+        showErrors({});
         isDirty.set(false);
         touched.set({});
         isSubmitting.set(false);
@@ -1755,6 +2048,8 @@ function createDynamicFormStore(options) {
                 e.preventDefault();
             }
             isSubmitting.set(true);
+            // A new attempt: what the server said about the last one is history.
+            showServerErrors({});
             const thisSubmit = ++submitRun;
             try {
                 // Touch everything before validating: a submit is the user asserting
@@ -1783,12 +2078,12 @@ function createDynamicFormStore(options) {
                 // still has to describe the data on screen, so when it moved on, the
                 // displayed state is re-derived instead of showing the old pass.
                 if (data() === snapshot && run === validationRun) {
-                    errors.set(res.errors);
+                    showErrors(res.errors);
                     validationResult.set(res);
                 }
                 else {
                     const live = validateFields(fields, data(), undefined, validationContext);
-                    errors.set(live.errors);
+                    showErrors(live.errors);
                     validationResult.set(live);
                 }
                 isSubmitted.set(true);
@@ -1829,6 +2124,10 @@ function createDynamicFormStore(options) {
         reset,
         validate,
         validateAsync,
+        /** What the server refused, by field path; already part of `errors`. */
+        serverErrors: serverErrors.asReadonly(),
+        setServerErrors,
+        clearServerErrors,
         handleSubmit,
     };
 }

package/dist/types/dynamic-field-kit-angular.d.ts

@@ -81,6 +81,9 @@ declare class DynamicInput extends BaseInputComponent implements OnChanges, Afte
     host: ViewContainerRef;
     private compRef?;
     private inputInstance?;
+    private builtIn?;
+    private builtInType?;
+    private builtInOptions?;
     private subscriptions;
     private supplied;
     ngOnChanges(changes: SimpleChanges): void;
@@ -90,6 +93,13 @@ declare class DynamicInput extends BaseInputComponent implements OnChanges, Afte
     private cleanup;
     private cleanupSubscriptions;
     private cleanupRenderedComponent;
+    /**
+     * Removes what this component put into the host element itself: a built-in
+     * control, the HTML of a function renderer, an error message. `host.clear()`
+     * does not: it only knows the components it created, which sit beside the
+     * host element, not inside it.
+     */
+    private clearOwnNodes;
     /** The id `ariaDescribedBy` points at. See core's `makeErrorId`. */
     errorNodeId(): string;
     /** `error` may arrive as a bare string, so index 0 would be a character. */
@@ -132,10 +142,21 @@ declare class DynamicInput extends BaseInputComponent implements OnChanges, Afte
      *
      * `render()` re-runs on every ngOnChanges while the fallback is in use (there
      * is no component instance to sync props into), so this stays current as the
-     * field's error comes and goes.
+     * field's error comes and goes. The control is the same one from change to
+     * change, so a flag that is no longer given is taken off again.
      */
     private applyFallbackAria;
+    /**
+     * Builds the built-in control for `type` and puts it in the host element.
+     * What the control shows is set by `syncBuiltIn`, here and on every later
+     * change.
+     */
     private renderDefaultFallbackHTML5;
+    private createBuiltIn;
+    /** Brings a built-in control in line with the current inputs. */
+    private syncBuiltIn;
+    /** The options of a built-in select, rebuilt only when the list changed, and the one that is chosen. */
+    private syncBuiltInOptions;
     private renderError;
     static ɵfac: i0.ɵɵFactoryDeclaration<DynamicInput, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<DynamicInput, "dfk-dynamic-input", never, { "type": { "alias": "type"; "required": false; }; "extraProps": { "alias": "extraProps"; "required": false; }; }, { "valueChange": "valueChange"; "onChange": "onChange"; }, never, never, true, never>;
@@ -188,6 +209,11 @@ declare class FieldInput implements OnChanges, OnDestroy {
     private optionsState?;
     /** Bound into the template so a renderer can drive a search-remote refetch. */
     onOptionsQuery: (query: string) => void;
+    /**
+     * A masked field shows formatted text; `parseInput` turns what its renderer
+     * reports back into the value to store.
+     */
+    handleValueChange(input: unknown): void;
     ngOnChanges(_changes: SimpleChanges): void;
     ngOnDestroy(): void;
     private syncOptionsLoader;
@@ -246,6 +272,10 @@ declare class MultiFieldInput implements OnInit, OnChanges {
     private indexedErrors;
     private indexedTouchedSource?;
     private indexedTouched;
+    private sectionErrorsSource?;
+    private sectionErrors;
+    private sectionTouchedSource?;
+    private sectionTouched;
     get effectiveIdPrefix(): string;
     /** The touched map in effect: the controlled input, else the internal one. */
     private get effectiveTouched();
@@ -258,6 +288,12 @@ declare class MultiFieldInput implements OnInit, OnChanges {
     errorsForItem(fieldName: string, index: number): Record<string, string[]> | undefined;
     touchedForItem(fieldName: string, index: number): Record<string, boolean>;
     handleGroupBlur(fieldName: string, index: number, key: string): void;
+    /** The fields of a titled section, or undefined for any other field. */
+    sectionOf(field: FieldDescription): FieldDescription[] | undefined;
+    sectionValues(fieldName: string): Properties;
+    isSectionDisabled(field: FieldDescription): boolean;
+    errorsForSection(fieldName: string): Record<string, string[]> | undefined;
+    touchedForSection(fieldName: string): Record<string, boolean>;
     /**
      * Clears the internally tracked touched state. Only meaningful in
      * uncontrolled mode - when `touched` is bound, resetting the form store
@@ -316,6 +352,10 @@ declare class DynamicFormDevToolsComponent {
     static ɵcmp: i0.ɵɵComponentDeclaration<DynamicFormDevToolsComponent, "dfk-dev-tools", never, { "data": { "alias": "data"; "required": false; }; "errors": { "alias": "errors"; "required": false; }; "touched": { "alias": "touched"; "required": false; }; "isDirty": { "alias": "isDirty"; "required": false; }; "fields": { "alias": "fields"; "required": false; }; }, {}, never, never, true, never>;
 }
 
+/** What `setServerErrors` takes: a message or messages by field path. */
+type ServerErrorsInput = Record<string, string | readonly string[] | null | undefined>;
+type FieldErrors = Record<string, string[]>;
+
 interface DynamicFormOptions {
     fields: FieldDescription[];
     initialValues?: Properties;
@@ -351,6 +391,10 @@ declare function createDynamicFormStore(options: DynamicFormOptions): {
     reset: (newValues?: Properties) => void;
     validate: () => boolean;
     validateAsync: () => Promise<boolean>;
+    /** What the server refused, by field path; already part of `errors`. */
+    serverErrors: i0.Signal<FieldErrors>;
+    setServerErrors: (input: ServerErrorsInput) => void;
+    clearServerErrors: (name?: string) => void;
     handleSubmit: (onValid: (data: Properties) => void | Promise<void>, onInvalid?: (errors: Record<string, string[]>) => void) => (e?: Event) => Promise<void>;
 };
 
@@ -401,4 +445,4 @@ declare class DynamicFieldKitModule {
 declare const FIELD_REGISTRY: InjectionToken<FieldRegistry>;
 
 export { BaseInputComponent, ColumnLayout, DynamicFieldKitModule, DynamicFormDevToolsComponent, DynamicInput, FIELD_REGISTRY, FieldInput, GridLayout, LayoutRegistry, MultiFieldInput, RowLayout, createDynamicFormStore, layoutRegistry };
-export type { BaseLayoutConfig, DynamicFormOptions, FieldInputProps, ResponsiveLayoutConfig };
+export type { BaseLayoutConfig, DynamicFormOptions, FieldInputProps, ResponsiveLayoutConfig, ServerErrorsInput };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynamic-field-kit/angular",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "Angular renderer for dynamic-field-kit",
   "license": "MIT",
   "private": false,
@@ -27,8 +27,8 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "@angular/common": ">=16 <22",
-    "@angular/core": ">=16 <22",
+    "@angular/common": ">=16 <23",
+    "@angular/core": ">=16 <23",
     "@dynamic-field-kit/core": "^1.3.0"
   },
   "publishConfig": {
@@ -44,8 +44,8 @@
     "lint": "eslint ."
   },
   "devDependencies": {
-    "@analogjs/vite-plugin-angular": "^2.7.1",
-    "@analogjs/vitest-angular": "^2.7.1",
+    "@analogjs/vite-plugin-angular": "^2.8.0",
+    "@analogjs/vitest-angular": "^2.8.0",
     "@angular-devkit/build-angular": "^21.2.0",
     "@angular/cdk": "^21.2.14",
     "@angular/common": "^21.2.0",
@@ -54,7 +54,7 @@
     "@angular/core": "^21.2.0",
     "@angular/forms": "^21.2.0",
     "@angular/platform-browser": "^21.2.0",
-    "@dynamic-field-kit/core": "^1.10.0",
+    "@dynamic-field-kit/core": "^1.11.0",
     "@vitest/coverage-istanbul": "^4.1.11",
     "jsdom": "^29.1.1",
     "ng-packagr": "^21.2.0",