ngx-dynamic-entity 1.9.1 → 1.11.0

package/types/ngx-dynamic-entity.d.ts

@@ -53,6 +53,8 @@ declare const DEFAULT_UI_TEXT: {
     reset: string;
     saveShortcutHint: string;
     loading: string;
+    errorSummaryTitle: string;
+    tabErrorCount: string;
     editSection: string;
     saveSection: string;
     editingSection: string;
@@ -831,6 +833,8 @@ declare class ConfigSourceService {
 type ValidationMessage = string | ((language: string, error: any) => string);
 /** The built-in English messages. Every key here can be overridden individually. */
 declare const DEFAULT_VALIDATION_MESSAGES: Record<string, ValidationMessage>;
+/** An error key, or a pair mapping one to a different message key. */
+type MessageOrderEntry = string | readonly [errorKey: string, messageKey: string];
 declare class ValidationMessagesService {
     private readonly overrides;
     /**
@@ -841,12 +845,39 @@ declare class ValidationMessagesService {
      * 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;
+    /**
+     * The message for a field, chosen by its **type** rather than by a list the caller supplies.
+     *
+     * Every field component used to pass its own copy of the key order, and the copies were
+     * near-identical — which was tolerable while the field itself was the only thing that
+     * rendered a message. It stopped being tolerable when the error summary above the form
+     * started naming what is wrong with each field: the summary has no field component to ask
+     * (the offending field is usually on a tab that is not rendered), so it would have needed a
+     * second copy of the same table, and a dropdown would have said "This field is required" in
+     * the summary and "Please select an option" under the control.
+     *
+     * One table, read from both places, is what keeps those two sentences the same sentence.
+     */
+    resolveForField(errors: ValidationErrors | null | undefined, language: string, fieldType: string): string;
+    /** A field type's key order. An unrecognised type — a consumer's own — gets the common list. */
+    orderFor(fieldType: string): {
+        order: readonly MessageOrderEntry[];
+        fallback: 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>;
 }
 
+/** A field the form will not save, with what is wrong and where to find it. */
+interface InvalidField {
+    field: NestedFieldConfig;
+    /** The same message the field renders under itself. */
+    message: string;
+    tabId: string;
+    subTabId?: string;
+}
 /**
  * DynamicFormComponent — the main form component.
  * Renders a reactive form from EntityFormConfig with tab support, responsive 12-col grid,
@@ -898,6 +929,19 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      * disable the form. Used by the builder's live preview.
      */
     preview: boolean;
+    /**
+     * How a field with no `colSpan` of its own is sized in the 12-column grid.
+     *
+     * `stack` — the historic behaviour — gives every such field the full twelve, so a form of
+     * eight short text fields renders as an eight-row ladder with two thirds of its width
+     * empty. `auto` sizes them by field type instead: a date or a number is half a row, a
+     * textarea or a nested group still takes all twelve.
+     *
+     * An explicit `colSpan` always wins in both modes, so turning `auto` on cannot override a
+     * layout somebody authored. The default stays `stack` because changing how existing configs
+     * render is not this input's business — opting in is.
+     */
+    layout: 'stack' | 'auto';
     formSubmit: EventEmitter<Record<string, any>>;
     formChange: EventEmitter<Record<string, any>>;
     formReset: EventEmitter<void>;
@@ -917,9 +961,15 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     private readonly hookRegistry;
     private readonly rbacService;
     private readonly rulesEvaluation;
+    /** Resolves what is wrong with a field, for the error summary — see `resolveForField`. */
+    private readonly messages;
     private readonly entityRefSelection;
     private readonly commonModulesRegistry;
     private readonly migrations;
+    /** Scopes the field-slot lookup a jump does, so the library never touches global `document`. */
+    private readonly host;
+    /** Ties `afterNextRender` to this component, so destroying it cancels a pending jump. */
+    private readonly injector;
     protected readonly Object: ObjectConstructor;
     readonly activeTab: i0.WritableSignal<string>;
     readonly activeSubTab: i0.WritableSignal<string>;
@@ -1017,8 +1067,31 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      * uniqueness check came back.
      */
     get isValidating(): boolean;
-    /** Single source of truth for both the submit guard and the button's disabled state. */
+    /**
+     * Whether a submit would be refused. The guard `submit()` checks — not the button's state.
+     *
+     * See `submitDisabled` for why those are no longer the same question.
+     */
     get submitBlocked(): boolean;
+    /**
+     * Whether the Save button is unavailable.
+     *
+     * This used to be `submitBlocked`, so an invalid form greyed Save out — and a greyed button
+     * is the worst possible answer to "why can't I save?". It cannot be clicked, so there is no
+     * moment at which the form gets to say which field is at fault or which tab it is on; the
+     * user is left comparing a disabled button against a form that looks, to them, filled in.
+     * On a tabbed form the offending field is usually not even on screen.
+     *
+     * Save now stays available while the form is merely invalid. Clicking it still saves
+     * nothing — `submit()` checks `submitBlocked` and refuses — but the refusal is where the
+     * error summary, the tab badges and the jump to the first bad field come from, so pressing
+     * Save produces an explanation instead of silence.
+     *
+     * What is still disabled is what a *retry cannot fix*: a save already in flight, and an
+     * async validator whose answer has not come back. Those are moments where the right answer
+     * is genuinely "wait", and a button that accepts a click would be lying.
+     */
+    get submitDisabled(): boolean;
     ngOnInit(): void;
     ngOnChanges(changes: SimpleChanges): void;
     /**
@@ -1046,6 +1119,47 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
         focusPanel?: boolean;
     }): void;
     getFieldSpan(field: NestedFieldConfig): string;
+    /**
+     * Set by a submit that validation refused, cleared by one that went through.
+     *
+     * Gates the error summary rather than `form.invalid` doing it: a form opened on an empty
+     * required field is invalid from the first render, and leading with a block of red before
+     * the user has typed anything is an accusation, not help. The summary is the answer to
+     * "why did Save do nothing", so it appears when Save does nothing.
+     */
+    readonly submitAttempted: i0.WritableSignal<boolean>;
+    /**
+     * Every rendered field whose control is currently invalid, with the tab it lives on.
+     *
+     * Read by the tab badges, the error summary and the jump, so all three agree on what
+     * counts. Hidden fields are excluded because `syncHiddenFieldState` disables them and a
+     * disabled control is not part of validity — pointing the user at one would send them to a
+     * field that is not on screen, or worse, switch tabs to show them nothing.
+     *
+     * Cached per change-detection pass. The walk calls `getControl` once per field and that
+     * falls back to a recursive search of the whole form; the template reads this three times
+     * for the summary and once per tab for the badges, so recomputing it each time turns one
+     * traversal into a dozen on every keystroke. `form.statusChanges` is the only thing that
+     * can alter the answer, and it already runs `markForCheck` — dropping the cache there keeps
+     * it honest without a second subscription.
+     */
+    invalidFields(): InvalidField[];
+    private invalidFieldsCache?;
+    /** How many invalid fields sit on a tab — its own and its sub-tabs'. */
+    tabErrorCount(tab: NestedTabConfig): number;
+    /** The same count for a sub-tab, which is addressed by its own id rather than its parent's. */
+    subTabErrorCount(subTab: NestedTabConfig): number;
+    /**
+     * Switch to the tab holding `fieldId`, scroll it into view, and move focus onto it.
+     *
+     * `afterNextRender` rather than a timer: the panel the field lives in is rendered by the
+     * change detection this call is part of, so the element does not exist yet — and a timeout
+     * is both a guess at how long that takes and something that keeps running after the
+     * component is destroyed. The query is scoped to this component's own element, so the
+     * library never reaches for the global `document`.
+     */
+    jumpToField(fieldId: string): void;
+    private locateField;
     /** A critical field stays read-only until the user deliberately unlocks it. */
     isFieldLocked(field: NestedFieldConfig): boolean;
     /**
@@ -1054,6 +1168,13 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      */
     isFieldReadonly(field: NestedFieldConfig): boolean;
     toggleFieldLock(field: NestedFieldConfig): void;
+    /**
+     * A field's label in the form's language, falling back to its id.
+     *
+     * The fallback matters wherever the label stands alone rather than beside its control: an
+     * error-summary chip or a critical-change banner naming a field with no label for this
+     * language would otherwise be blank, and a blank chip is worse than a raw id.
+     */
     resolveFieldLabel(field: NestedFieldConfig): string;
     /**
      * The changed critical fields as one comma-separated string.
@@ -1213,7 +1334,7 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     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"; "saveRejected": "saveRejected"; }, 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; }; "layout": { "alias": "layout"; "required": false; }; }, { "formSubmit": "formSubmit"; "formChange": "formChange"; "formReset": "formReset"; "activeTabChange": "activeTabChange"; "saveRejected": "saveRejected"; }, never, never, true, never>;
 }
 
 /**
@@ -1236,6 +1357,8 @@ declare class DynamicRecordFormComponent implements OnChanges {
     isReadOnly: boolean;
     /** Specific field ids forced read-only while the rest of the record stays editable. */
     readOnlyFields: string[];
+    /** Forwarded verbatim to the hosted form — see `DynamicFormComponent.layout`. */
+    layout: 'stack' | 'auto';
     /**
      * Open the record read-only, with a per-tab "Edit section" flow — one tab is edited and
      * validated at a time. This is the framework's `EntityRecordComponent` model and the
@@ -1252,11 +1375,22 @@ declare class DynamicRecordFormComponent implements OnChanges {
         tabId: string;
         record: Record<string, any>;
     }>;
+    /**
+     * A `beforeSave` hook aborted the save — by returning false or throwing.
+     *
+     * Re-exposed from the embedded `ngx-dynamic-form`, and emitted by `saveSection` too. The
+     * inner form already ran the hook and already refused the save, but nothing carried that
+     * out to a host binding this component: the veto worked and looked exactly like a Save
+     * button that did nothing, which is the failure `saveRejected` exists to prevent.
+     */
+    saveRejected: EventEmitter<{
+        reason: string;
+        error?: unknown;
+    }>;
     dynamicFormComp?: DynamicFormComponent;
     private readonly rulesEvaluation;
     private readonly rbacService;
-    private readonly host;
-    private readonly injector;
+    private readonly hookRegistry;
     readonly currentData: i0.WritableSignal<Record<string, any>>;
     readonly originalBaseline: i0.WritableSignal<Record<string, any>>;
     /**
@@ -1355,7 +1489,18 @@ declare class DynamicRecordFormComponent implements OnChanges {
      * validity of the tab's own controls, and rules filtered to this tab — a rule targeting
      * a hidden tab must not block the save (the reference's OV0-968 fix).
      */
-    saveSection(): void;
+    saveSection(): Promise<void>;
+    /**
+     * Put a record to the entity's `beforeSave` hook.
+     *
+     * `sectionSave` carries the *whole* record — `extractRecord()`, not the tab's slice — so
+     * the same payload reached persistence through two buttons, one of which asked the hook
+     * and one of which did not. A hook registered to veto a save is a data-integrity
+     * mechanism; having a second route around it made it advisory.
+     *
+     * @returns the record to emit, or `null` when the hook aborted (already reported).
+     */
+    private runBeforeSave;
     /**
      * Seed the session baseline from the loaded record so `VALUE_CHANGED` rules and the
      * modification banner compare against the record as it was opened — not as it was
@@ -1363,6 +1508,30 @@ declare class DynamicRecordFormComponent implements OnChanges {
      */
     ngOnChanges(changes: SimpleChanges): void;
     get recordTitle(): string;
+    /**
+     * What this record is called, as opposed to what kind of thing it is.
+     *
+     * The header used to show the entity's name twice — "clients", with "Entity: clients"
+     * underneath — so the one question a record header exists to answer, *which* record am I
+     * looking at, was the one thing it did not say. The entity keeps the subtitle; this takes
+     * the heading.
+     *
+     * The order is deliberate. `showOnMinimize` is the author saying "this is what identifies a
+     * record" — it is what the summary panel and the collapsed view already show — so it is
+     * asked first. A text or email field is the fallback because those are what a name is
+     * stored in; a number or a date is a property of the record, not its identity, and would
+     * give a header reading "42". When neither exists there is nothing to name it with and the
+     * entity label stands in, which is the behaviour this replaced.
+     *
+     * A masked field is never a candidate. Masking is presentational (see SECURITY.md), but
+     * that is exactly why: the whole point is that this role does not get to read the value, and
+     * promoting it into the page heading would print in full what every field renders as
+     * `XXXXXXXXX`. A record whose only text field is masked keeps the entity label.
+     *
+     * One pass rather than two filtered ones: this is a getter the header reads on every change
+     * detection, and the preferred candidate is usually the first field it meets.
+     */
+    get recordHeading(): string;
     get avatarLetter(): string;
     /** Every field in the config, at any depth. */
     private allFields;
@@ -1409,21 +1578,18 @@ declare class DynamicRecordFormComponent implements OnChanges {
      * field. The walk used to check top-level `fields` only, so every field in a sub-tab was
      * simply not found and the jump did nothing at all.
      */
-    private locateField;
     /**
      * Switches to the tab holding `fieldId`, then scrolls it into view and moves focus to it.
      *
-     * The wait for the new tab to render used to be a 50 ms `setTimeout`, which was wrong three
-     * ways: `document` is undefined on a server render, 50 ms is a guess that a large tab can
-     * outrun, and nothing cancelled the timer if the component went away first.
-     * `afterNextRender` fixes all three — it never runs on the server, it runs when the panel
-     * has actually rendered rather than when a guess expires, and it is tied to the injector so
-     * destroying the component cancels it. The query is scoped to this component's own element,
-     * so the library no longer reaches for the global `document` at all.
+     * Delegated rather than implemented twice. The hosted form grew the same jump when a
+     * refused save had to be able to take the user to the first invalid field, and the form is
+     * where it belongs: it owns the tab state, the panel that renders the field, and the
+     * element the jump is looking for. This is kept as the record editor's public entry point
+     * because the summary panel's quick-jump calls it and a host may too.
      */
     jumpToField(fieldId: string): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<DynamicRecordFormComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<DynamicRecordFormComponent, "ngx-dynamic-record-form", never, { "config": { "alias": "config"; "required": false; }; "rules": { "alias": "rules"; "required": false; }; "initialData": { "alias": "initialData"; "required": false; }; "userRoles": { "alias": "userRoles"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "loading": { "alias": "loading"; "required": false; }; "error": { "alias": "error"; "required": false; }; "isReadOnly": { "alias": "isReadOnly"; "required": false; }; "readOnlyFields": { "alias": "readOnlyFields"; "required": false; }; "viewMode": { "alias": "viewMode"; "required": false; }; }, { "formSubmit": "formSubmit"; "formChange": "formChange"; "formReset": "formReset"; "sectionSave": "sectionSave"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<DynamicRecordFormComponent, "ngx-dynamic-record-form", never, { "config": { "alias": "config"; "required": false; }; "rules": { "alias": "rules"; "required": false; }; "initialData": { "alias": "initialData"; "required": false; }; "userRoles": { "alias": "userRoles"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "loading": { "alias": "loading"; "required": false; }; "error": { "alias": "error"; "required": false; }; "isReadOnly": { "alias": "isReadOnly"; "required": false; }; "readOnlyFields": { "alias": "readOnlyFields"; "required": false; }; "layout": { "alias": "layout"; "required": false; }; "viewMode": { "alias": "viewMode"; "required": false; }; }, { "formSubmit": "formSubmit"; "formChange": "formChange"; "formReset": "formReset"; "sectionSave": "sectionSave"; "saveRejected": "saveRejected"; }, never, never, true, never>;
 }
 
 /**
@@ -1567,6 +1733,25 @@ declare function nextFieldInstanceId(): string;
 declare function fieldDomId(field: {
     id?: string;
 } | undefined, instance: string, suffix?: string): string;
+/**
+ * The `aria-describedby` a control needs, given what is rendered beside it right now.
+ *
+ * A field can show two things under its control — the author's help text and, once touched, a
+ * validation message — and a screen reader announces only what this attribute names. Three
+ * field components named the error; the other sixteen named nothing at all, so their error
+ * messages were on screen and silent. Help text would have inherited the same gap.
+ *
+ * Order matters: the hint describes the field and the error describes the attempt, so the hint
+ * is read first. `null` rather than an empty string when there is nothing to describe — an
+ * empty `aria-describedby` is a dangling reference, not an absent one.
+ *
+ * Shared rather than written into each of the nineteen field components, because the rule is
+ * the same everywhere and getting it wrong is invisible until somebody uses a screen reader.
+ */
+declare function fieldDescribedBy(domId: (suffix?: string) => string, parts: {
+    hint?: boolean;
+    error?: boolean;
+}): string | null;
 
 declare class TextFieldComponent implements OnDestroy {
     /**
@@ -1591,6 +1776,10 @@ declare class TextFieldComponent implements OnDestroy {
     ngOnDestroy(): void;
     get label(): string;
     get placeholder(): string;
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<TextFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<TextFieldComponent, "ngx-text-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -1619,6 +1808,10 @@ declare class TextareaFieldComponent {
      * "This field has an error", which made a documented, configurable feature work on three
      * of fifteen field types.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<TextareaFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<TextareaFieldComponent, "ngx-textarea-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -1691,6 +1884,10 @@ declare class MarkdownFieldComponent implements OnChanges {
      * "This field has an error", which made a documented, configurable feature work on three
      * of fifteen field types.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<MarkdownFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<MarkdownFieldComponent, "ngx-markdown-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -1713,6 +1910,10 @@ declare class NumberFieldComponent {
     masked: boolean;
     get label(): string;
     get placeholder(): string;
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<NumberFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<NumberFieldComponent, "ngx-number-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -1744,6 +1945,10 @@ declare class CurrencyFieldComponent {
      * "This field has an error", which made a documented, configurable feature work on three
      * of fifteen field types.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<CurrencyFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<CurrencyFieldComponent, "ngx-currency-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -1773,6 +1978,10 @@ declare class EmailFieldComponent {
      * "This field has an error", which made a documented, configurable feature work on three
      * of fifteen field types.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<EmailFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<EmailFieldComponent, "ngx-email-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -1806,6 +2015,10 @@ declare class PasswordFieldComponent {
      * "This field has an error", which made a documented, configurable feature work on three
      * of fifteen field types.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<PasswordFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<PasswordFieldComponent, "ngx-password-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -1835,6 +2048,10 @@ declare class CheckboxFieldComponent {
      * It rendered no error element at all, so a required checkbox left unticked told the user
      * nothing — and `validationMessages` could not reach a field that never displayed one.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<CheckboxFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<CheckboxFieldComponent, "ngx-checkbox-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -1846,6 +2063,12 @@ declare class CheckboxFieldComponent {
  * toggle switch with Yes/No labels for clearer binary state communication.
  */
 declare class BooleanFieldComponent {
+    /**
+     * Unique to this component instance: an `array` renders the same field once per row, and a
+     * DOM id may not repeat. See `field-dom-id.ts`.
+     */
+    private readonly instanceId;
+    protected domId(suffix?: string): string;
     /** Library chrome, overridable via UI_TEXT. */
     protected readonly ui: UiTextService;
     /** Overridable via MASKED_PLACEHOLDER; the default is the historic literal. */
@@ -1863,6 +2086,10 @@ declare class BooleanFieldComponent {
      * It rendered no error element at all, so a required checkbox left unticked told the user
      * nothing — and `validationMessages` could not reach a field that never displayed one.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<BooleanFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<BooleanFieldComponent, "ngx-boolean-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -1884,7 +2111,18 @@ declare class DateFieldComponent {
     readonly: boolean;
     masked: boolean;
     get label(): string;
-    /** ISO 8601 date → locale display string (ONEHERMES convention: always UTC, display in user locale) */
+    /**
+     * ISO 8601 date → display string, through the formatter the host configured.
+     *
+     * This used to call `toLocaleDateString()` directly, which meant `setDateFormatters` — the
+     * one seam for choosing how a date is rendered — reached the record summary and the `time`
+     * field but not this one. A host that configured formatters got them almost everywhere,
+     * and silently did not get them on the field type most likely to be the reason they
+     * configured formatters at all.
+     *
+     * The default formatter is `toLocaleDateString()` with no locale, so an application that
+     * has not called `setDateFormatters` renders exactly what it rendered before.
+     */
     formatDate(value: string | null): string;
     /**
      * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
@@ -1892,6 +2130,10 @@ declare class DateFieldComponent {
      * "This field has an error", which made a documented, configurable feature work on three
      * of fifteen field types.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<DateFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<DateFieldComponent, "ngx-date-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -1925,9 +2167,17 @@ declare class DateTimeFieldComponent {
     /** The input's local `YYYY-MM-DDTHH:mm` → stored ISO 8601 UTC. */
     onInput(value: string): void;
     /**
-     * Displays date *and* time. `DateFieldComponent` used `toLocaleDateString()` here, so a
-     * datetime read back through the field showed no time while the same value in the record
-     * summary — which goes through core's `formatDisplayValue` — showed it.
+     * Displays date *and* time, through the formatter the host configured.
+     *
+     * Two rounds of the same fault. First this called `toLocaleDateString()`, so a datetime
+     * read back through the field showed no time while the record summary showed it. Then it
+     * called `toLocaleString()` directly, which fixed the time but kept the field outside
+     * `setDateFormatters` — so a host that configured formatters still saw them apply to the
+     * summary and not to the field. Going through `formatDisplayValue` is what makes the two
+     * paths agree by construction rather than by matching literals.
+     *
+     * `parseStored` accepts shapes `new Date(raw)` alone does not, so the *parsed* instant is
+     * handed on as ISO rather than the raw value.
      */
     formatDateTime(value: unknown): string;
     /**
@@ -1936,6 +2186,10 @@ declare class DateTimeFieldComponent {
      * "This field has an error", which made a documented, configurable feature work on three
      * of fifteen field types.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<DateTimeFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<DateTimeFieldComponent, "ngx-date-time-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -1977,6 +2231,10 @@ declare class TimeFieldComponent {
      * "This field has an error", which made a documented, configurable feature work on three
      * of fifteen field types.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<TimeFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<TimeFieldComponent, "ngx-time-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -2021,6 +2279,10 @@ declare class MonthYearFieldComponent {
      * "This field has an error", which made a documented, configurable feature work on three
      * of fifteen field types.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<MonthYearFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<MonthYearFieldComponent, "ngx-month-year-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -2063,6 +2325,10 @@ declare class DropdownFieldComponent {
      * never wrong, only unlocalised.
      */
     getLabel(value: unknown): string;
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<DropdownFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<DropdownFieldComponent, "ngx-dropdown-field", never, { "field": { "alias": "field"; "required": false; }; "language": { "alias": "language"; "required": false; }; "control": { "alias": "control"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -2118,6 +2384,10 @@ declare class RadioFieldComponent {
      * "This field has an error", which made a documented, configurable feature work on three
      * of fifteen field types.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<RadioFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<RadioFieldComponent, "ngx-radio-field", never, { "field": { "alias": "field"; "required": false; }; "language": { "alias": "language"; "required": false; }; "control": { "alias": "control"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -2159,6 +2429,10 @@ declare class MultiSelectFieldComponent {
      * "This field has an error", which made a documented, configurable feature work on three
      * of fifteen field types.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<MultiSelectFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<MultiSelectFieldComponent, "ngx-multi-select-field", never, { "field": { "alias": "field"; "required": false; }; "language": { "alias": "language"; "required": false; }; "control": { "alias": "control"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -2223,6 +2497,10 @@ declare class EntityRefFieldComponent implements OnInit {
      * "This field has an error", which made a documented, configurable feature work on three
      * of fifteen field types.
      */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<EntityRefFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<EntityRefFieldComponent, "ngx-entity-ref-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -2239,6 +2517,8 @@ declare class GroupFieldComponent {
     readonly: boolean;
     masked: boolean;
     userRoles: string[];
+    /** Author help text for the section as a whole. */
+    get hint(): string;
     get label(): string;
     getChildControl(childId: string): AbstractControl;
     static ɵfac: i0.ɵɵFactoryDeclaration<GroupFieldComponent, never>;
@@ -2266,6 +2546,8 @@ declare class ArrayFieldComponent {
     userRoles: string[];
     private readonly fb;
     private readonly validatorRegistry;
+    /** Author help text for the section as a whole. */
+    get hint(): string;
     get label(): string;
     get formArray(): FormArray;
     getItemChildControl(itemGroup: AbstractControl, childId: string): AbstractControl;
@@ -2310,6 +2592,10 @@ declare class ImageFieldComponent implements OnDestroy {
     remove(): void;
     ngOnDestroy(): void;
     /** Validation, as distinct from the upload failures this field already reported. */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<ImageFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<ImageFieldComponent, "ngx-image-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
@@ -2346,10 +2632,14 @@ declare class FileFieldComponent {
     onFileSelect(file: File | undefined): Promise<void>;
     remove(): void;
     /** Validation, as distinct from the upload failures this field already reported. */
+    /** Author help text, shown under the control and named by `aria-describedby`. */
+    get hint(): string;
+    /** The ids of whatever is describing this control right now. */
+    protected describedBy(): string | null;
     get errorMessage(): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<FileFieldComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<FileFieldComponent, "ngx-file-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
 }
 
-export { ASYNC_VALIDATOR_REGISTRY, ArrayFieldComponent, BooleanFieldComponent, COMMON_MODULES_REGISTRY, CONFIG_SOURCE, CascadeDataService, CheckboxFieldComponent, ConfigSourceService, CurrencyFieldComponent, DEFAULT_UI_TEXT, DEFAULT_VALIDATION_MESSAGES, DateFieldComponent, DateTimeFieldComponent, DropdownFieldComponent, DynamicFieldComponent, DynamicFormComponent, DynamicRecordFormComponent, ENTITY_REF_CACHE_STORE, ENTITY_REF_REGISTRY, EmailFieldComponent, EntityRefFieldComponent, EntityRefRegistryService, EntityRefSelectionService, EntityReferenceService, FIELD_TYPE_REGISTRY, FIELD_TYPE_SETS, FieldRegistryService, FileFieldComponent, GroupFieldComponent, HOOK_REGISTRY, HookRegistryService, ImageFieldComponent, InMemoryEntityRefCacheStore, LOOKUP_REGISTRY, LookupRegistryService, MARKDOWN_RENDERER, MASKED_PLACEHOLDER, MASKED_ROLES, MarkdownFieldComponent, MonthYearFieldComponent, MultiSelectFieldComponent, NumberFieldComponent, PasswordFieldComponent, RECORD_MIGRATIONS, RadioFieldComponent, RbacService, RulesEvaluationService, SYSTEM_DEFAULT_CAN_EDIT, TextFieldComponent, TextareaFieldComponent, TimeFieldComponent, UI_TEXT, UPLOAD_HANDLER, UiTextService, VALIDATION_MESSAGES, VALIDATOR_REGISTRY, ValidationMessagesService, ValidatorRegistryService, builtInFieldTypes, fieldDomId, nextFieldInstanceId, provideBuiltInFieldTypes, provideFieldTypes, provideNgxDynamicEntity, refreshChoiceOptions, resolveUiText };
-export type { ChoiceOptionHost, ConfigSourceHandler, DynamicFieldComponentContract, EntityRefCacheStore, EntityRefSelection, HookFn, NgxDynamicEntityConfig, UiTextKey, UiTextOverrides, UiTextOverridesFor, UiTextParams, UiTextResolver, UiTextResolverFor, UiTextValue, ValidationMessage };
+export { ASYNC_VALIDATOR_REGISTRY, ArrayFieldComponent, BooleanFieldComponent, COMMON_MODULES_REGISTRY, CONFIG_SOURCE, CascadeDataService, CheckboxFieldComponent, ConfigSourceService, CurrencyFieldComponent, DEFAULT_UI_TEXT, DEFAULT_VALIDATION_MESSAGES, DateFieldComponent, DateTimeFieldComponent, DropdownFieldComponent, DynamicFieldComponent, DynamicFormComponent, DynamicRecordFormComponent, ENTITY_REF_CACHE_STORE, ENTITY_REF_REGISTRY, EmailFieldComponent, EntityRefFieldComponent, EntityRefRegistryService, EntityRefSelectionService, EntityReferenceService, FIELD_TYPE_REGISTRY, FIELD_TYPE_SETS, FieldRegistryService, FileFieldComponent, GroupFieldComponent, HOOK_REGISTRY, HookRegistryService, ImageFieldComponent, InMemoryEntityRefCacheStore, LOOKUP_REGISTRY, LookupRegistryService, MARKDOWN_RENDERER, MASKED_PLACEHOLDER, MASKED_ROLES, MarkdownFieldComponent, MonthYearFieldComponent, MultiSelectFieldComponent, NumberFieldComponent, PasswordFieldComponent, RECORD_MIGRATIONS, RadioFieldComponent, RbacService, RulesEvaluationService, SYSTEM_DEFAULT_CAN_EDIT, TextFieldComponent, TextareaFieldComponent, TimeFieldComponent, UI_TEXT, UPLOAD_HANDLER, UiTextService, VALIDATION_MESSAGES, VALIDATOR_REGISTRY, ValidationMessagesService, ValidatorRegistryService, builtInFieldTypes, fieldDescribedBy, fieldDomId, nextFieldInstanceId, provideBuiltInFieldTypes, provideFieldTypes, provideNgxDynamicEntity, refreshChoiceOptions, resolveUiText };
+export type { ChoiceOptionHost, ConfigSourceHandler, DynamicFieldComponentContract, EntityRefCacheStore, EntityRefSelection, HookFn, InvalidField, MessageOrderEntry, NgxDynamicEntityConfig, UiTextKey, UiTextOverrides, UiTextOverridesFor, UiTextParams, UiTextResolver, UiTextResolverFor, UiTextValue, ValidationMessage };