ngx-dynamic-entity 1.0.0 → 1.2.0

package/lib/field-types/array-field.component.d.ts

@@ -1,8 +1,14 @@
 import { AbstractControl, FormArray } from '@angular/forms';
 import type { NestedFieldConfig, EntityFormConfig } from '@dynamic-entity/core';
 import * as i0 from "@angular/core";
-/** ADR-008: ArrayFieldComponent — renders repeating rows for FormArray with + Add Item and Remove */
+/** Renders repeating rows for a FormArray, with Add Item and Remove. */
 export declare class ArrayFieldComponent {
+    /**
+     * addItem/removeItem are public and may be called from outside this component's template,
+     * which under OnPush would not re-render. The host also watches the control, but this
+     * keeps the component correct on its own.
+     */
+    private readonly cdr;
     field: NestedFieldConfig;
     control: AbstractControl;
     config: EntityFormConfig;

package/lib/field-types/dropdown-field.component.d.ts

@@ -3,6 +3,7 @@ import type { NestedFieldConfig } from '@dynamic-entity/core';
 import * as i0 from "@angular/core";
 export declare class DropdownFieldComponent {
     private readonly lookups;
+    private readonly messages;
     private _field;
     private _language;
     /** Setter-based so options resolve however the input is set — see `refreshChoiceOptions`. */
@@ -14,7 +15,7 @@ export declare class DropdownFieldComponent {
     readonly: boolean;
     masked: boolean;
     /** Inline `options`, or the field's named list resolved through the registry (§6.3). */
-    readonly options: import("@angular/core").WritableSignal<import("@dynamic-entity/core").LocalizedText[]>;
+    readonly options: import("@angular/core").WritableSignal<DropdownOption[]>;
     readonly compareFn: (o1: any, o2: any) => boolean;
     isObjectVal(option: any): boolean;
     get label(): string;

package/lib/field-types/entity-ref-field.component.d.ts

@@ -1,6 +1,6 @@
 import { OnInit } from '@angular/core';
 import { AbstractControl } from '@angular/forms';
-import type { NestedFieldConfig, ReferenceOption } from '@dynamic-entity/core';
+import type { NestedFieldConfig } from '@dynamic-entity/core';
 import * as i0 from "@angular/core";
 /**
  * EntityRefFieldComponent — a select populated from a consumer-registered loader.
@@ -29,7 +29,17 @@ export declare class EntityRefFieldComponent implements OnInit {
     ngOnInit(): void;
     /** Reload options against the parent's current value. */
     reload(): Promise<void>;
-    onSelectionChange(): void;
+    /**
+     * Publish the selected option so autoPatch can copy from its record.
+     *
+     * Driven from `valueChanges` rather than the select's `change` event: that event is the
+     * same one the `formControl` directive listens to, so reading the control inside a
+     * template `(change)` handler can see the previous value. `valueChanges` fires after the
+     * model has updated — including Playwright `selectOption`, which updates the control
+     * through the value accessor.
+     */
+    onSelectionChange(value?: string): void;
+    private publishSelection;
     getLabel(value: any): string;
     private parentValue;
     /** Reload (and drop a stale selection) whenever the parent control changes. */

package/lib/field-types/field-component.contract.d.ts

@@ -0,0 +1,49 @@
+import type { AbstractControl } from '@angular/forms';
+import type { NestedFieldConfig } from '@dynamic-entity/core';
+/**
+ * What a field component must accept to be registered with `provideFieldTypes`.
+ *
+ * The renderer instantiates a field component dynamically and assigns exactly these five
+ * inputs — no more, no less — so any component satisfying this interface can stand in for a
+ * built-in type or add a new one.
+ *
+ * Implement it explicitly and TypeScript will tell you when you have missed one:
+ *
+ * ```typescript
+ * @Component({
+ *   selector: 'app-signature-field',
+ *   standalone: true,
+ *   template: `<canvas [attr.aria-label]="field.id"></canvas>`,
+ * })
+ * export class SignatureFieldComponent implements DynamicFieldComponentContract {
+ *   @Input() field!: NestedFieldConfig;
+ *   @Input() control!: AbstractControl;
+ *   @Input() language = 'en';
+ *   @Input() readonly = false;
+ *   @Input() masked = false;
+ * }
+ *
+ * provideFieldTypes({ signature: SignatureFieldComponent });
+ * ```
+ *
+ * Two implementation notes that are easy to get wrong:
+ *
+ * - Declare the inputs with definite assignment (`field!: …`) or an initialiser. The
+ *   renderer sets them through `ComponentRef.setInput()` after construction, so they are
+ *   genuinely undefined until the first assignment.
+ * - `masked` means the value must not be displayed. Render a placeholder rather than the
+ *   control's value. This is presentational: the real value stays in the control and is
+ *   included in the submitted record, so it is not an access-control boundary.
+ */
+export interface DynamicFieldComponentContract {
+    /** The field's schema entry: id, type, label, validators, options, and so on. */
+    field: NestedFieldConfig;
+    /** The reactive control backing this field. A `FormGroup` for `group`, `FormArray` for `array`. */
+    control: AbstractControl;
+    /** Active language, for resolving `LocalizedText` labels, placeholders and options. */
+    language: string;
+    /** Render the value as text rather than an editable control. */
+    readonly: boolean;
+    /** Hide the value from display. See the note above — presentational only. */
+    masked: boolean;
+}

package/lib/field-types/group-field.component.d.ts

@@ -1,7 +1,7 @@
 import { AbstractControl } from '@angular/forms';
 import type { NestedFieldConfig, EntityFormConfig } from '@dynamic-entity/core';
 import * as i0 from "@angular/core";
-/** ADR-008: GroupFieldComponent — renders nested fieldset container for group.children */
+/** Renders a nested fieldset container for a group field's children. */
 export declare class GroupFieldComponent {
     field: NestedFieldConfig;
     control: AbstractControl;

package/lib/field-types/multi-select-field.component.d.ts

@@ -14,7 +14,7 @@ export declare class MultiSelectFieldComponent {
     readonly: boolean;
     masked: boolean;
     /** Inline `options`, or the field's named list resolved through the registry (§6.3). */
-    readonly options: import("@angular/core").WritableSignal<import("@dynamic-entity/core").LocalizedText[]>;
+    readonly options: import("@angular/core").WritableSignal<DropdownOption[]>;
     readonly compareFn: (o1: any, o2: any) => boolean;
     isObjectVal(option: any): boolean;
     get label(): string;

package/lib/field-types/number-field.component.d.ts

@@ -2,6 +2,7 @@ import { AbstractControl } from '@angular/forms';
 import type { NestedFieldConfig } from '@dynamic-entity/core';
 import * as i0 from "@angular/core";
 export declare class NumberFieldComponent {
+    private readonly messages;
     field: NestedFieldConfig;
     control: AbstractControl;
     language: string;

package/lib/field-types/radio-field.component.d.ts

@@ -15,7 +15,7 @@ export declare class RadioFieldComponent {
     readonly: boolean;
     masked: boolean;
     /** Inline `options`, or the field's named list resolved through the registry (§6.3). */
-    readonly options: import("@angular/core").WritableSignal<import("@dynamic-entity/core").LocalizedText[]>;
+    readonly options: import("@angular/core").WritableSignal<DropdownOption[]>;
     get label(): string;
     getOptStoredVal(option: any): any;
     /**

package/lib/field-types/text-field.component.d.ts

@@ -1,12 +1,20 @@
+import { OnDestroy } from '@angular/core';
 import { AbstractControl } from '@angular/forms';
 import type { NestedFieldConfig } from '@dynamic-entity/core';
 import * as i0 from "@angular/core";
-export declare class TextFieldComponent {
+export declare class TextFieldComponent implements OnDestroy {
+    private readonly messages;
+    private displaySub?;
     field: NestedFieldConfig;
-    control: AbstractControl;
+    set control(value: AbstractControl);
+    get control(): AbstractControl;
+    private _control;
     language: string;
     readonly: boolean;
     masked: boolean;
+    /** Readonly markup reads this signal so an external patch (autoPatch) is visible under OnPush. */
+    readonly displayValue: import("@angular/core").WritableSignal<unknown>;
+    ngOnDestroy(): void;
     get label(): string;
     get placeholder(): string;
     get errorMessage(): string;

package/lib/form/dynamic-field/dynamic-field.component.d.ts

@@ -1,16 +1,17 @@
-import { OnChanges, SimpleChanges } from '@angular/core';
+import { OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
 import { AbstractControl } from '@angular/forms';
 import type { NestedFieldConfig, EntityFormConfig } from '@dynamic-entity/core';
 import * as i0 from "@angular/core";
 /**
  * DynamicFieldComponent — mounts the correct field component for a given NestedFieldConfig.
- * Uses ViewContainerRef.createComponent() and passes inputs via setInput() (ADR-008).
+ * Uses ViewContainerRef.createComponent() and passes inputs via setInput(); see
+ * DynamicFieldComponentContract for the five inputs every field component receives.
  * Never add field-type-specific logic here — this component must remain generic.
  *
  * The 5 inputs (field, control, language, readonly, masked) are passed to every mounted
  * component uniformly — no special-casing per type.
  */
-export declare class DynamicFieldComponent implements OnChanges {
+export declare class DynamicFieldComponent implements OnChanges, OnDestroy {
     field: NestedFieldConfig;
     control: AbstractControl;
     config: EntityFormConfig;
@@ -21,6 +22,12 @@ export declare class DynamicFieldComponent implements OnChanges {
     private readonly fieldHost;
     private readonly fieldRegistry;
     private readonly rbacService;
+    /**
+     * Passed into `createComponent` so a hosted field sees this host's injector — including
+     * `DynamicFormComponent`'s scoped `EntityRefSelectionService`. Without it, a standalone
+     * field resolves the root bus and `autoPatch` never runs.
+     */
+    private readonly injector;
     private componentRef;
     ngOnChanges(_changes: SimpleChanges): void;
     private mountField;
@@ -32,7 +39,35 @@ export declare class DynamicFieldComponent implements OnChanges {
     private warnUnresolved;
     private static readonly warnedTypes;
     /**
-     * Pass all 5 contract inputs via ComponentRef.setInput() — uniform for all types (ADR-008).
+     * Re-check the hosted field component.
+     *
+     * The field components are OnPush, so they re-render on an input change, an event from
+     * their own template, or a signal they read. `form.markAllAsTouched()` is none of those —
+     * it flips `touched` from outside, and every field's error message depends on it. Without
+     * this, a blocked submit would mark the form touched and no error would appear.
+     */
+    refresh(): void;
+    /**
+     * Re-check the hosted component whenever its control changes from outside.
+     *
+     * The field components are OnPush, so they re-render on an input change or an event from
+     * their own template. A control mutated externally is neither — and that is not an edge
+     * case: patchForm, reset, autoPatch and patchOnTrue all do exactly that. Without this, a
+     * field patched from a record would keep rendering its previous value.
+     *
+     * `detectChanges()` rather than `markForCheck()`: a selection that arrives from a native
+     * `change` event (or Playwright) may not be followed by another Angular tick, so a dirty
+     * flag would never be flushed. Running CD on the hosted component now is the copy showing up.
+     *
+     * Done here rather than in each of the eighteen field components: the host owns the
+     * component reference, so one subscription covers every type including custom ones.
+     */
+    private watchControl;
+    private controlSub?;
+    ngOnDestroy(): void;
+    /**
+     * Pass all 5 contract inputs via ComponentRef.setInput() — uniform for all types.
+     * The public shape is DynamicFieldComponentContract.
      * Must use setInput(), not property assignment: the field components declare inputs with
      * definite assignment and no initializer, and the lib compiles with
      * useDefineForClassFields:false, so `'field' in instance` is false until first set.

package/lib/form/dynamic-form.component.d.ts

@@ -1,6 +1,7 @@
 import { EventEmitter, OnChanges, OnDestroy, OnInit, SimpleChanges } from '@angular/core';
 import { AbstractControl, FormArray, FormGroup } from '@angular/forms';
 import type { EntityFormConfig, FormRule, NestedFieldConfig, NestedTabConfig } from '@dynamic-entity/core';
+import { RbacService } from '../services/rbac.service';
 import * as i0 from "@angular/core";
 /**
  * DynamicFormComponent — the main form component.
@@ -9,7 +10,21 @@ import * as i0 from "@angular/core";
  * keyboard shortcuts (Ctrl+S, Esc), and RBAC-gated submission.
  */
 export declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
-    config: EntityFormConfig;
+    /**
+     * The schema to render.
+     *
+     * An accessor pair rather than a plain field: `ngOnChanges` normalises the option shape,
+     * and that result is kept here instead of being written back over the input. Reassigning
+     * an `@Input` works, but it mutates what the parent handed us — and a parent using OnPush
+     * or signals would never observe the replacement anyway.
+     *
+     * Reads of `this.config` get the normalised copy once it exists, so every internal caller
+     * is unaffected.
+     */
+    set config(value: EntityFormConfig);
+    get config(): EntityFormConfig;
+    private rawConfig;
+    private normalizedConfig?;
     rules?: FormRule[];
     initialData?: Record<string, any>;
     /** Session-original values for `VALUE_CHANGED` rules. Captured from the first build when omitted. */
@@ -42,6 +57,14 @@ export declare class DynamicFormComponent implements OnInit, OnChanges, OnDestro
     formReset: EventEmitter<void>;
     /** The visible tab changed. Lets a host track it without reaching into this component. */
     activeTabChange: EventEmitter<string>;
+    /**
+     * Emitted when a `beforeSave` hook aborted the save — by returning false or throwing.
+     * `formSubmit` does not fire in that case.
+     */
+    saveRejected: EventEmitter<{
+        reason: string;
+        error?: unknown;
+    }>;
     private readonly fb;
     private readonly validatorRegistry;
     private readonly hookRegistry;
@@ -49,6 +72,7 @@ export declare class DynamicFormComponent implements OnInit, OnChanges, OnDestro
     private readonly rulesEvaluation;
     private readonly entityRefSelection;
     private readonly commonModulesRegistry;
+    private readonly migrations;
     protected readonly Object: ObjectConstructor;
     readonly activeTab: import("@angular/core").WritableSignal<string>;
     readonly activeSubTab: import("@angular/core").WritableSignal<string>;
@@ -58,13 +82,17 @@ export declare class DynamicFormComponent implements OnInit, OnChanges, OnDestro
     readonly sessionBaseline: import("@angular/core").WritableSignal<Record<string, any>>;
     /** Critical fields the user has explicitly unlocked for editing. */
     readonly unlockedFields: import("@angular/core").WritableSignal<ReadonlySet<string>>;
+    /** The active tab's field panel, focused after a tab switch. */
+    private formPanel?;
+    /** The hosted field components, so an external control-state change can reach them. */
+    private fieldHosts?;
     form: FormGroup;
     private valueSub?;
     private selectionSub?;
     /** Previous values, for detecting `patchOnTrue` false→true transitions. */
     private previousValues;
     handleKeyboardEvent(event: KeyboardEvent): void;
-    readonly ruleResult: import("@angular/core").Signal<import("@dynamic-entity/core").RuleEvaluationResult>;
+    readonly ruleResult: import("@angular/core").Signal<RuleEvaluationResult>;
     /**
      * Critical fields whose value differs from the session baseline.
      * These drive the deferred `VALUE_CHANGED` banner — a critical edit is announced once,
@@ -78,12 +106,57 @@ export declare class DynamicFormComponent implements OnInit, OnChanges, OnDestro
     get activeSubTabConfig(): NestedTabConfig | null;
     get activeTabModuleComponent(): any | null;
     get fieldsForActiveTab(): NestedFieldConfig[];
-    get permissions(): {
-        canView: boolean;
-        canEdit: boolean;
-        canDelete: boolean;
-    };
+    /**
+     * Entity-level permissions for the current roles.
+     *
+     * Cached rather than recomputed: this is read from the template several times per change
+     * detection pass, and a fresh object each time is both wasted allocation and a new
+     * identity for anything comparing by reference. Invalidated in `ngOnChanges` when
+     * `config` or `userRoles` change, which are its only inputs.
+     */
+    get permissions(): ReturnType<RbacService['getPermissions']>;
+    private permissionsCache;
+    /**
+     * Whether the current roles may see this record at all.
+     *
+     * `permissions.view` used to be computed and thrown away — a user whose roles failed it
+     * still received the complete form with every value in the DOM. It is honoured now.
+     *
+     * As with masking, this is presentational: it stops the browser rendering data, it does
+     * not stop the data reaching the browser. Authorize on the server.
+     */
+    get canView(): boolean;
+    /**
+     * Whether the current roles may delete this record.
+     *
+     * The library ships no delete affordance, so this is surfaced for the consumer to gate
+     * their own — exposed rather than dropped, because a permission the schema declares
+     * should be answerable.
+     */
+    get canDelete(): boolean;
     get canSubmit(): boolean;
+    /**
+     * Errors raised by `validation` rules, keyed by the target they point at.
+     *
+     * A rule can declare the record invalid independently of Angular's validators, so form
+     * validity alone is not the whole picture. `DynamicRecordFormComponent.saveSection()`
+     * has always honoured these; `submit()` did not, which meant the same rule blocked one
+     * save path and merely painted a banner on the other — and anything wiring
+     * `(formSubmit)` to persistence wrote records the rules engine had already rejected.
+     */
+    get ruleValidationErrors(): Record<string, string>;
+    /** True when a `validation` rule is currently blocking submission. */
+    get hasRuleErrors(): boolean;
+    /**
+     * True while an async validator is still running.
+     *
+     * Angular reports a control with an outstanding async check as `pending`, and `invalid` is
+     * false until it settles — so without this a form could be submitted in the gap before a
+     * uniqueness check came back.
+     */
+    get isValidating(): boolean;
+    /** Single source of truth for both the submit guard and the button's disabled state. */
+    get submitBlocked(): boolean;
     ngOnInit(): void;
     ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
@@ -113,7 +186,38 @@ export declare class DynamicFormComponent implements OnInit, OnChanges, OnDestro
      */
     createArrayRow(field: NestedFieldConfig, value?: unknown): AbstractControl;
     private buildArrayRow;
+    /**
+     * Mark every control touched, then re-check the field components.
+     *
+     * They are OnPush and `touched` is flipped from outside their own template, so the second
+     * half is what makes the error messages actually appear.
+     */
+    private markAllTouched;
+    /**
+     * Bring a record up to the config's `version` before it reaches the form.
+     *
+     * Done here because this is the one place a record enters the renderer, so a consumer
+     * cannot forget it. Migration is a no-op unless the consumer registered steps *and* the
+     * record is behind — an unstamped record is deliberately left alone (see `migrateRecord`).
+     *
+     * A missing or broken step throws from core. That is not swallowed: rendering a
+     * half-understood record would write it back in a shape matching neither schema.
+     */
+    private upgradeRecord;
     private patchForm;
+    /**
+     * A record is nested by tab id (`{ tabId: { fieldId: value } }`) unless the tab sets
+     * `flatData: true`. Handing a flat record to a nested tab finds nothing, so the fields
+     * stay empty — with no error and no clue. That silent miss is the most expensive way to
+     * lose an hour with this library, so name it in dev builds.
+     *
+     * Only top-level keys that match a known field id are reported: anything else is assumed
+     * to be the consumer's own record metadata (ids, timestamps, `_configVersion`) and is not
+     * our business.
+     */
+    private warnUnconsumedInitialData;
+    /** Warn once per key per form instance — patchForm re-runs on every initialData change. */
+    private readonly warnedUnconsumedKeys;
     /** Assemble full nested record from per-tab FormGroups, respecting flatData, refererField & arrays. */
     extractRecord(): Record<string, any>;
     private flattenFormValues;
@@ -130,15 +234,58 @@ export declare class DynamicFormComponent implements OnInit, OnChanges, OnDestro
     private runPatchOnTrue;
     /** Prefer a control declared on the configured target tab; fall back to a top-level control. */
     private resolveTargetControl;
+    /**
+     * The fields the render filter operates on — a tab's own fields, at every tab depth.
+     * Deliberately not `allFields()`: `group` and `array` children are shown or hidden with
+     * their parent, and toggling a child's state independently would fight the parent's.
+     */
+    private tabFields;
+    /**
+     * Keep a hidden field's control out of form validity.
+     *
+     * A field hidden by a rule or a `showWhen` condition is filtered out of the render, but
+     * its validators stay attached — so a hidden *required* field holds `form.invalid` true
+     * forever, permanently disabling Save with nothing on screen to explain why.
+     *
+     * Disabling is the fix rather than stripping validators: Angular excludes disabled
+     * controls from validity, and the field's own validators survive intact for when it
+     * comes back. Values are untouched — `flattenFormValues` and `extractRecord` both read
+     * `control.value`, which a disabled control still carries, so rule evaluation and the
+     * emitted record see exactly what they saw before. That also keeps this from feeding
+     * back on itself: hiding a field cannot change the values the rules are evaluated over.
+     *
+     * The visibility predicate is the same one `fieldsForActiveTab` filters with, so what is
+     * rendered and what counts toward validity cannot drift apart.
+     */
+    private syncHiddenFieldState;
     /** Every field in the config, including `group`/`array` children. */
     private allFields;
     /** An empty `originalData` counts as "not supplied" — fall back to the captured baseline. */
     private baseline;
     private sameValue;
     getControl(fieldId: string, currentTabId?: string): AbstractControl | null;
+    /**
+     * Move focus into the newly shown panel.
+     *
+     * Activating a tab replaces everything below it while focus stays on the tab button, so a
+     * screen-reader or keyboard user is given no indication that the content changed and must
+     * tab back through the strip to reach it. Deferred a frame because the panel's contents
+     * are rendered by the change detection this call is part of.
+     */
+    private focusActivePanel;
+    /** Accessible name for the field panel — it is the tabpanel for the active tab. */
+    get activeTabLabel(): string;
+    /**
+     * Why a referenced field is flagged.
+     *
+     * `hasDrift` was written by the builder and read by nothing at runtime, so a field whose
+     * source definition had changed since it was linked looked entirely normal to the person
+     * filling the form in.
+     */
+    driftHint(field: NestedFieldConfig): string;
     resolveTabLabel(tab: NestedTabConfig): string;
     submit(): Promise<void>;
     reset(): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<DynamicFormComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<DynamicFormComponent, "ngx-dynamic-form", never, { "config": { "alias": "config"; "required": false; }; "rules": { "alias": "rules"; "required": false; }; "initialData": { "alias": "initialData"; "required": false; }; "originalData": { "alias": "originalData"; "required": false; }; "userRoles": { "alias": "userRoles"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "readOnlyFields": { "alias": "readOnlyFields"; "required": false; }; "showInfoBanners": { "alias": "showInfoBanners"; "required": false; }; "loading": { "alias": "loading"; "required": false; }; "error": { "alias": "error"; "required": false; }; "changeDebounceMs": { "alias": "changeDebounceMs"; "required": false; }; "preview": { "alias": "preview"; "required": false; }; }, { "formSubmit": "formSubmit"; "formChange": "formChange"; "formReset": "formReset"; "activeTabChange": "activeTabChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DynamicFormComponent, "ngx-dynamic-form", never, { "config": { "alias": "config"; "required": false; }; "rules": { "alias": "rules"; "required": false; }; "initialData": { "alias": "initialData"; "required": false; }; "originalData": { "alias": "originalData"; "required": false; }; "userRoles": { "alias": "userRoles"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "readOnlyFields": { "alias": "readOnlyFields"; "required": false; }; "showInfoBanners": { "alias": "showInfoBanners"; "required": false; }; "loading": { "alias": "loading"; "required": false; }; "error": { "alias": "error"; "required": false; }; "changeDebounceMs": { "alias": "changeDebounceMs"; "required": false; }; "preview": { "alias": "preview"; "required": false; }; }, { "formSubmit": "formSubmit"; "formChange": "formChange"; "formReset": "formReset"; "activeTabChange": "activeTabChange"; "saveRejected": "saveRejected"; }, never, never, true, never>;
 }

package/lib/form/dynamic-record-form.component.d.ts

@@ -70,7 +70,7 @@ export declare class DynamicRecordFormComponent implements OnChanges {
      * building a row's FormGroup inside the tab view races the tab's own initialisation, so
      * the row form is kept detached and only pushed into the FormArray on save.
      */
-    readonly inlineRowField: import("@angular/core").WritableSignal<NestedFieldConfig>;
+    readonly inlineRowField: import("@angular/core").WritableSignal<any>;
     readonly inlineRowIndex: import("@angular/core").WritableSignal<number>;
     inlineRowForm: FormGroup | null;
     /** `array` fields on the tab currently shown, so the template can list their rows. */
@@ -153,7 +153,18 @@ export declare class DynamicRecordFormComponent implements OnChanges {
     toggleHeaderStatus(): void;
     /** Locate a field's control wherever it lives, since header fields may be on any tab. */
     private controlFor;
-    /** A field's current value, read from the record so it is stable during render. */
+    /**
+     * A field's current value, read from the record so it is stable during render.
+     *
+     * Resolved through `getTabData` so it honours exactly the nesting contract the form
+     * patches with — `{ tabId: { fieldId } }`, or the record root when the tab sets
+     * `flatData`. Reading the record flat instead is not a shortcut: it makes the summary
+     * display values the form never loaded, which reads as "the data is there" while every
+     * control behind it is empty.
+     *
+     * Walks sub-tabs as well: a summary, header, or profile field may sit on any tab at any
+     * depth.
+     */
     private fieldValue;
     readonly isModified: import("@angular/core").Signal<boolean>;
     readonly summaryFields: import("@angular/core").Signal<NestedFieldConfig[]>;

package/lib/providers/provide-ngx-dynamic-entity.d.ts

@@ -1,12 +1,13 @@
 import { EnvironmentProviders, Type } from '@angular/core';
-import type { EntityReferenceLoader, LookupListSource } from '@dynamic-entity/core';
+import type { EntityReferenceLoader, LookupListSource, RecordMigration } from '@dynamic-entity/core';
+import { type HookFn } from '../tokens/injection-tokens';
 export interface NgxDynamicEntityConfig {
     /** Roles that see masked field values as XXXXXXXXX */
     maskedRoles?: string[];
     /** Custom field type components keyed by type string */
     fieldTypes?: Record<string, Type<any>>;
     /**
-     * Entity-ref option loaders keyed by entity key (ADR-006).
+     * Entity-ref option loaders keyed by entity key.
      * Each receives `{ parentValue, filters, lang }` and may return an array, Promise, or Observable.
      */
     entityRefs?: Record<string, EntityReferenceLoader>;
@@ -16,10 +17,31 @@ export interface NgxDynamicEntityConfig {
      * a loader for anything fetched, so an unused list is never loaded.
      */
     lookups?: Record<string, LookupListSource>;
+    /**
+     * Override the messages shown under invalid fields, keyed by Angular error key. A value is
+     * a string, or a function receiving `(language, error)` when it needs the error's detail.
+     * Unlisted keys keep their English default.
+     */
+    validationMessages?: Record<string, string | ((language: string, error: any) => string)>;
+    /**
+     * Async validator functions keyed by name, for checks that need a server — uniqueness,
+     * availability, a remote rule. Name them from a schema with
+     * `validators: { customAsync: ['uniqueEmail'] }`.
+     *
+     * Each is an Angular `AsyncValidatorFn`: it receives the control and returns a Promise or
+     * Observable of `ValidationErrors | null`. The control is `pending` while it runs, and the
+     * form cannot be submitted until every pending check settles.
+     */
+    asyncValidators?: Record<string, any>;
     /** Custom validator functions keyed by validator name */
     validators?: Record<string, any>;
     /** Hook functions keyed by hook name */
-    hooks?: Record<string, Function>;
+    hooks?: Record<string, HookFn>;
+    /**
+     * Ordered steps that upgrade a saved record when `EntityFormConfig.version` moves ahead
+     * of the record's `_configVersion`. Applied to `initialData` before the form is patched.
+     */
+    migrations?: RecordMigration[];
 }
 /**
  * Provider function for ngx-dynamic-entity.

package/lib/services/cascade-data.service.d.ts

@@ -3,7 +3,7 @@ import * as i0 from "@angular/core";
 /**
  * CascadeDataService — loads entity-reference options and applies parent→child cascades.
  *
- * Loaders come from the registry only (ADR-006). This service owns the three things a
+ * Loaders come from the registry only. This service owns the three things a
  * field component should not: resolving the loader, coercing whatever it returned
  * (array | Promise | Observable) into a Promise, and filtering by the parent's value.
  */

package/lib/services/entity-ref-registry.service.d.ts

@@ -2,7 +2,7 @@ import type { EntityReferenceLoader } from '@dynamic-entity/core';
 import * as i0 from "@angular/core";
 /**
  * EntityRefRegistryService — resolves entity-ref option loader functions.
- * ADR-006: Entity-ref options come ONLY from this registry.
+ * Entity-ref options come ONLY from this registry.
  * Never pass loaders via @Input() on field components.
  *
  * Consumers register loaders via provideNgxDynamicEntity({ entityRefs: { clients: () => [...] } }).

package/lib/services/lookup-registry.service.d.ts

@@ -81,7 +81,7 @@ export interface ChoiceOptionHost {
  * Point a choice component's `options` signal at the right source (parity plan §6.3).
  *
  * Called from the `field` / `language` input setters of `dropdown`, `radio` and `multiSelect` —
- * the wiring is theirs, the decision is the service's, which is what keeps the ADR-008
+ * the wiring is theirs, the decision is the service's, which is what keeps the field
  * five-input contract intact: options are never pushed in as a sixth input.
  *
  * Setters rather than `ngOnChanges` on purpose. `ngOnChanges` only fires for inputs Angular

package/lib/services/validation-messages.service.d.ts

@@ -0,0 +1,43 @@
+import type { ValidationErrors } from '@angular/forms';
+import * as i0 from "@angular/core";
+/**
+ * Resolves an Angular `ValidationErrors` object to the message shown under a field.
+ *
+ * These strings used to be hardcoded English literals inside each field component, so a
+ * German form meant re-implementing every field type — the labels honoured `language` while
+ * the errors underneath them did not.
+ *
+ * A message is a plain string, or a function when it needs the error's own detail
+ * (`minlength.requiredLength`, `min.min`, and so on). The active `language` is passed
+ * through, so one registration can serve every locale:
+ *
+ * ```typescript
+ * provideNgxDynamicEntity({
+ *   validationMessages: {
+ *     required: lang => (lang === 'de' ? 'Pflichtfeld.' : 'This field is required.'),
+ *     minlength: (lang, err) => `Mindestens ${err['requiredLength']} Zeichen.`,
+ *   },
+ * });
+ * ```
+ *
+ * Unregistered keys fall back to the defaults below, so overriding one message does not
+ * mean supplying them all.
+ */
+export type ValidationMessage = string | ((language: string, error: any) => string);
+/** The built-in English messages. Every key here can be overridden individually. */
+export declare const DEFAULT_VALIDATION_MESSAGES: Record<string, ValidationMessage>;
+export declare class ValidationMessagesService {
+    private readonly overrides;
+    /**
+     * The message for the first error present, in the order the caller lists.
+     *
+     * Order is the caller's because it is field-specific: a dropdown wants
+     * `requiredSelection` where a text input wants `required`, and the first match wins so the
+     * most specific message is the one shown.
+     */
+    resolve(errors: ValidationErrors | null | undefined, language: string, order: readonly (string | readonly [errorKey: string, messageKey: string])[], fallbackKey?: string): string;
+    /** One message by key, honouring an override before the default. */
+    messageFor(key: string, language: string, error: unknown): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ValidationMessagesService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ValidationMessagesService>;
+}