ngx-dynamic-entity 1.14.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-dynamic-entity",
-  "version": "1.14.0",
+  "version": "2.0.1",
   "description": "Angular standalone UI library for rendering dynamic entity forms.",
   "//typings": "Local workspace resolution only: ng-packagr 21 writes types/ngx-dynamic-entity.d.ts into dist/package.json. Do NOT add a 'main' field here — ng-packagr does not generate one, so it would be copied verbatim and resolve wrongly in the published package.",
   "typings": "types/ngx-dynamic-entity.d.ts",
@@ -8,7 +8,7 @@
     "@angular/common": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",
     "@angular/core": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",
     "@angular/forms": "^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",
-    "@dynamic-entity/core": "^1.14.0",
+    "@dynamic-entity/core": "^2.0.1",
     "rxjs": "^7.0.0"
   },
   "keywords": [

package/styles.css

@@ -224,6 +224,7 @@
   flex-direction: column;
   gap: var(--ngx-field-gap);
   min-width: 0;
+  width: 100%;
 }
 
 .ngx-field__label {
@@ -1057,18 +1058,7 @@ textarea.ngx-field__input:focus {
 }
 
 /*
- * A read-only record is a table of values, not a form.
- *
- * With every field at `span 12` the record view spent a full screen on six values — and no
- * control is being sized here, so the width a text input needs is not the width a value
- * needs. `auto-fit` packs them, and a long note still takes its own row when the content
- * demands one.
- */
-/*
- * Nothing is being asked of the reader, so nothing is required of them.
- *
- * The matching `.ngx-form--readonly` *grid* rule lives in the component's own styles, next to
- * the grid it overrides — see the Layout note above.
+ * In read-only mode, required markers are suppressed since no user input is expected.
  */
 .ngx-form--readonly .ngx-field__req {
   display: none;

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

@@ -1,8 +1,8 @@
 import * as i0 from '@angular/core';
 import { InjectionToken, Type, EnvironmentProviders, WritableSignal, OnInit, OnChanges, OnDestroy, EventEmitter, SimpleChanges, Provider } from '@angular/core';
-import { ReferenceOption, LocalizedText, EntityFormConfig, FormRule, ImportLookups, MappingPlan, ImportResult, TemplateSpec, SheetData, CommonModuleEntry, EntityReferenceLoader, LookupListSource, RecordMigration, FileUploadHandler, FieldValidators, NestedFieldConfig, ReferenceLoaderContext, DropdownOption, LookupListValue, NestedTabConfig, RuleEvaluationResult, ImportColumn, UnsupportedColumn, ImportRowError } from '@dynamic-entity/core';
+import { ReferenceOption, LocalizedText, EntityFormConfig, FormRule, ImportLookups, MappingPlan, ImportResult, TemplateSpec, SheetData, CommonModuleEntry, EntityReferenceLoader, LookupListSource, RecordMigration, FileUploadHandler, FieldValidators, NestedFieldConfig, ReferenceLoaderContext, DropdownOption, LookupListValue, NestedTabConfig, RuleEvaluationResult, FieldScopeEntry, EvaluateFormRulesOptions, ImportColumn, UnsupportedColumn, ImportRowError } from '@dynamic-entity/core';
 export { AutoPatchConfig, CommonModuleEntry, ComponentClass, DropdownOption, EntityFormConfig, EntityPermissions, EntityReferenceConfig, EntityReferenceLoader, FieldTableConfig, FieldValidators, FileRef, FormRule, LocalizedText, NestedFieldConfig, NestedTabConfig, PatchOnTrueMapping, RbacContext, ReferenceLoaderContext, ReferenceOption, RichFieldType, RuleAction, RuleCondition, RuleEvaluationResult, VersionedRecord, formatDisplayValue, normalizeConfig, normalizeOption, resolveLabel, resolveOptionLabel, resolveOptionValue, valuesMatch } from '@dynamic-entity/core';
-import { ValidatorFn, AsyncValidatorFn, ValidationErrors, FormGroup, FormArray, AbstractControl } from '@angular/forms';
+import { ValidatorFn, AsyncValidatorFn, AbstractControl, ValidationErrors, FormGroup, FormArray } from '@angular/forms';
 import * as rxjs from 'rxjs';
 import * as ngx_dynamic_entity from 'ngx-dynamic-entity';
 
@@ -618,7 +618,7 @@ declare const provideNgxDynamicEntity: (config?: NgxDynamicEntityConfig) => Envi
  *
  * `FieldRegistryService` imports no components. Whatever you register here is what gets
  * bundled, so an app that only uses text/number/dropdown pays for three components and
- * their imports, not nineteen.
+ * their imports, not twenty-one.
  *
  * ```ts
  * // Everything (convenient; bundles all built-ins):
@@ -634,7 +634,7 @@ declare const provideNgxDynamicEntity: (config?: NgxDynamicEntityConfig) => Envi
 declare function builtInFieldTypes(): Record<string, Type<any>>;
 /** Register a specific set of field types. Only the components you name are bundled. */
 declare function provideFieldTypes(types: Record<string, Type<any>>): EnvironmentProviders;
-/** Register all 19 built-in field type keys. Convenience for apps that use most of them. */
+/** Register all 21 built-in field type keys. Convenience for apps that use most of them. */
 declare function provideBuiltInFieldTypes(): EnvironmentProviders;
 
 /**
@@ -642,7 +642,7 @@ declare function provideBuiltInFieldTypes(): EnvironmentProviders;
  *
  * **Tree-shaking contract:** this service holds *no* static imports of field components.
  * Nothing is bundled until something registers it, which is what makes the built-ins
- * opt-in. Register them with `provideBuiltInFieldTypes()` (all 19 keys) or a narrower
+ * opt-in. Register them with `provideBuiltInFieldTypes()` (all 21 keys) or a narrower
  * subset via `provideFieldTypes({ ... })` — see `providers/provide-field-types.ts`.
  *
  * Resolution order: consumer token registry → runtime registrations → nothing.
@@ -706,6 +706,22 @@ declare class ValidatorRegistryService {
      * An unknown name is skipped rather than throwing, matching the synchronous behaviour.
      */
     resolveAsyncFromConfig(config?: FieldValidators | string[]): AsyncValidatorFn[];
+    /**
+     * Say when a named validator resolved to nothing.
+     *
+     * It used to be dropped in silence, which is the worst failure mode this library has: the
+     * schema says the field is checked, the field is not checked, the form saves, and nothing
+     * anywhere said so. For `customAsync` that is typically a uniqueness check, so the duplicate
+     * lands in the database.
+     *
+     * Dev only, once per name — this runs while controls are built, which happens on every
+     * config change. `validateConfig` with `knownValidators` is the build-time version of the
+     * same check, and it fails CI rather than a console.
+     */
+    private warnUnresolved;
+    /** Per service instance, which is per injector — so a test gets a clean slate. */
+    private readonly warned;
+    private warnOnce;
     static ɵfac: i0.ɵɵFactoryDeclaration<ValidatorRegistryService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<ValidatorRegistryService>;
 }
@@ -963,18 +979,88 @@ declare class RbacService {
     static ɵprov: i0.ɵɵInjectableDeclaration<RbacService>;
 }
 
+/** What `syncHiddenFieldState` needs from the form it is operating on. */
+interface RuleSyncContext {
+    result: RuleEvaluationResult;
+    /** The values `showWhen` is evaluated against — the flat map the rules engine reads. */
+    values: Record<string, unknown>;
+    /** Every name a field answers to: its bare id, and its bracketed path. */
+    namesOf(field: NestedFieldConfig): readonly string[];
+    /**
+     * The field's dotted address, unbracketed — `personal.address.city`.
+     *
+     * Separate from `namesOf` because it is compared as a *prefix*: a container hides its
+     * descendants, and `[personal.address]` is not a prefix of `[personal.address.city]` once
+     * the brackets are in the way.
+     */
+    addressOf(field: NestedFieldConfig): string;
+    /** The control a scope entry addresses, or `null` when it has no static path. */
+    controlFor(entry: FieldScopeEntry): AbstractControl | null;
+}
 /**
- * RulesEvaluationService — evaluates dynamic form rules against active reactive form state.
+ * RulesEvaluationService — evaluates rules, and owns what a result *means*.
+ *
+ * It used to be two passthrough methods, with the interpretation spread across the component:
+ * the render filter decided one way what a rule result did to a field, and the validity sync
+ * decided again forty lines further down. They disagreed about what "every field" meant, and
+ * the consequence was a required field inside a `group` that a rule had hidden holding
+ * `form.invalid` true forever with nothing on screen to explain it.
+ *
+ * Precedence lives here now, in one method that both callers go through. Still stateless —
+ * every method takes the result it is interpreting, so there is nothing to go stale against a
+ * rebuilt form and nothing to reset between configs.
  */
 declare class RulesEvaluationService {
     /**
      * Evaluate rules against form values and optional original baseline values.
      */
-    evaluate(rules: FormRule[] | undefined | null, values: Record<string, unknown>, originalValues?: Record<string, unknown>): RuleEvaluationResult;
+    evaluate(rules: FormRule[] | undefined | null, values: Record<string, unknown>, originalValues?: Record<string, unknown>, options?: EvaluateFormRulesOptions): RuleEvaluationResult;
     /**
      * Filter rules pertinent to a single tab.
      */
     filterForTab(rules: FormRule[] | undefined | null, tabId: string, config: EntityFormConfig): FormRule[];
+    /**
+     * Whether a field renders, under the precedence documented on `RuleEvaluationResult`.
+     *
+     * An explicit hide beats everything. A show beats static hiding — `visibility: false`, or a
+     * `showWhen` that does not currently hold — because a rule that could only hide what the
+     * config already hides would have nothing to say, and `{ visibility: true }` was a
+     * documented no-op until it did. Otherwise the config's own visibility decides.
+     */
+    isFieldVisible(result: RuleEvaluationResult, field: NestedFieldConfig, names: readonly string[], values: Record<string, unknown>): boolean;
+    /** The same precedence for a tab. */
+    isTabVisible(result: RuleEvaluationResult, tab: NestedTabConfig): boolean;
+    /**
+     * Keep a hidden field's control out of form validity.
+     *
+     * A field hidden by a rule or a `showWhen` 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 — a disabled control still carries its value, 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 predicate is `isFieldVisible`, the same one the render filter uses, so what is on
+     * screen and what counts toward validity cannot drift apart.
+     *
+     * Entries must arrive parent-first, which is what `collectFieldScopes` yields: a container's
+     * children are skipped once the container itself is hidden, because Angular's `disable()`
+     * cascades to descendants and a child's `enable()` walks back up recalculating ancestors.
+     * Toggling a child inside a hidden group would fight its parent.
+     */
+    syncHiddenFieldState(entries: readonly FieldScopeEntry[], ctx: RuleSyncContext): void;
+    /**
+     * The hidden and shown names as sets, memoised against the result they came from.
+     *
+     * `isFieldVisible` runs once per field per change-detection pass; building two sets from
+     * two arrays each time turns a rule result into allocation proportional to the form. A
+     * `WeakMap` keyed by the result means it is built once per evaluation and collected with it.
+     */
+    private nameSets;
+    private readonly nameSetCache;
     static ɵfac: i0.ɵɵFactoryDeclaration<RulesEvaluationService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<RulesEvaluationService>;
 }
@@ -1146,6 +1232,8 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     private readonly hookRegistry;
     private readonly rbacService;
     private readonly rulesEvaluation;
+    /** config ⇄ FormGroup: where a value lives. See `FormStructureService`. */
+    private readonly structure;
     /** Resolves what is wrong with a field, for the error summary — see `resolveForField`. */
     private readonly messages;
     private readonly entityRefSelection;
@@ -1176,6 +1264,9 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     private previousValues;
     handleKeyboardEvent(event: KeyboardEvent): void;
     readonly ruleResult: i0.Signal<ngx_dynamic_entity.RuleEvaluationResult>;
+    /** Warned-about rule problems, per component instance — see `warnedAmbiguousIds`. */
+    private readonly warnedProblems;
+    private warnOnce;
     /**
      * Critical fields whose value differs from the session baseline.
      * These drive the deferred `VALUE_CHANGED` banner — a critical edit is announced once,
@@ -1184,6 +1275,7 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     readonly changedCriticalFields: i0.Signal<NestedFieldConfig[]>;
     get tabs(): NestedTabConfig[];
     get visibleTabs(): NestedTabConfig[];
+    private isTabVisible;
     get activeTabConfig(): NestedTabConfig | null;
     get visibleSubTabs(): NestedTabConfig[];
     get activeSubTabConfig(): NestedTabConfig | null;
@@ -1203,6 +1295,12 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     private readonly warnedSelectorModules;
     private warnSelectorModule;
     get fieldsForActiveTab(): NestedFieldConfig[];
+    /**
+     * Whether a field renders. Precedence lives in `RulesEvaluationService`, which is also
+     * what `syncHiddenFieldState` asks — so what is on screen and what counts toward validity
+     * cannot drift apart.
+     */
+    private isFieldVisible;
     /**
      * Entity-level permissions for the current roles.
      *
@@ -1344,6 +1442,14 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      * library never reaches for the global `document`.
      */
     jumpToField(fieldId: string): void;
+    /**
+     * Which tab (and sub-tab) holds a field.
+     *
+     * Descends into `group`/`array` children: this compared top-level fields only, so "jump to
+     * the first invalid field" found nothing for a nested one and silently did nothing. Only
+     * sub-tabs one level deep are named, because that is what the tab strip can select —
+     * anything deeper resolves to the ancestor it renders under.
+     */
     private locateField;
     /** A critical field stays read-only until the user deliberately unlocks it. */
     isFieldLocked(field: NestedFieldConfig): boolean;
@@ -1370,8 +1476,6 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      */
     changedCriticalFieldLabels(): string;
     private buildForm;
-    private buildFieldControl;
-    /** One row of an `array` field: a FormGroup when the field declares columns, else a bare control. */
     /**
      * The `FormArray` behind an `array` field, for callers that manage rows themselves —
      * the record editor's inline row drawer.
@@ -1408,9 +1512,8 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      * 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.
+     * Which keys were missed is `FormStructureService`'s answer; warning once per key per form
+     * is this component's, because it is the thing that lives as long as the form does.
      */
     private warnUnconsumedInitialData;
     /** Warn once per key per form instance — patchForm re-runs on every initialData change. */
@@ -1429,7 +1532,16 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      * consumers that never call the validator still get a signal in development.
      */
     private warnAmbiguousRuleReferences;
-    private static readonly warnedAmbiguousIds;
+    /**
+     * Ids already warned about, per component instance.
+     *
+     * This was `private static`, so it was module-global mutable state that nothing ever
+     * cleared: under SSR every render of every form in the process accumulated into one set
+     * that lived as long as the server did, and the first request to render a config
+     * suppressed the warning for every request after it. Per instance, the warning is once per
+     * form — which is what "warn once" was meant to mean.
+     */
+    private readonly warnedAmbiguousIds;
     /**
      * The value map rules and `showWhen` are evaluated against.
      *
@@ -1443,17 +1555,53 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      * unknown>` and needs no knowledge of refs at all — the extra keys simply resolve.
      */
     /**
-     * Whether a rule result names this field.
+     * Every name a rule may address this field by.
      *
      * A rule target is either a bare field id — how every config so far addresses a field — or
-     * a bracketed path, which is the only way to name one of two fields that share an id.
-     * Both have to match, or a rule written either way would fail to hide what it targeted.
+     * a bracketed path, which is the only way to name one of two fields that share an id. Both
+     * have to match, or a rule written either way would fail to hide what it targeted.
+     *
+     * The path comes last, and `syncHiddenFieldState` relies on that: it uses the last entry
+     * as the field's address when deciding whether a hidden container already covers it.
      */
-    private namesField;
+    private namesOf;
+    /**
+     * The field's dotted address, unbracketed.
+     *
+     * The positional path rather than an authored `refererField`: this is compared as a prefix
+     * to decide whether a hidden container already covers a field, and containment is a fact
+     * about where the field *is*. A `refererField` is a binding override — it says where the
+     * value goes, not which group renders it.
+     */
+    private addressOf;
     /** The field's declared path, or the one its position implies when it carries none. */
     private pathFor;
+    /**
+     * Every field in the config with the scope its value is stored under, cached per config.
+     *
+     * `collectFieldScopes` walks the whole tree. It was called once per field from `pathFor`,
+     * which `namesField` calls, which the render filter calls for every field on the active
+     * tab — a quadratic walk on every change-detection pass. Keyed by config identity, so a
+     * new config invalidates it without an explicit lifecycle hook to forget.
+     */
+    private fieldScopes;
+    private scopeEntryFor;
+    private scopeCache?;
+    /**
+     * The control a scope entry addresses, named by path rather than by bare id.
+     *
+     * `getControl(field.id)` with no tab falls through to a first-match recursive search of the
+     * whole form, so with `address` on two tabs, hiding one disabled the other. The control
+     * tree mirrors the scope path exactly — `buildTabControls` nests by tab id and
+     * `buildFieldControl` nests a `group` under its own id — so a `[path]` ref resolves through
+     * `form.get()` on `getControl`'s first branch and names exactly one control.
+     *
+     * A field inside an `array` has no static path: its controls live in `FormArray` rows built
+     * per row. `form.get()` returns null for those and they are left alone, which is correct —
+     * a row's controls are created and destroyed with the row.
+     */
+    private controlForEntry;
     private flattenFormValues;
-    private getTabGroup;
     /**
      * `autoPatch` — copy mapped fields out of the record the user just selected in an
      * entity-ref field into the configured target tab's controls.
@@ -1464,37 +1612,44 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      * copy `from` → `to` within the current record.
      */
     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.
+     * Prefer a control declared on the configured target tab; fall back to a top-level control.
+     *
+     * "Declared on the tab" now means anywhere under it, sub-tabs and `group` children
+     * included. It meant the tab's own top-level fields only, so an `autoPatch` mapping onto a
+     * field inside a group resolved to `null` and copied nothing, silently.
      */
-    private tabFields;
+    private resolveTargetControl;
     /**
-     * 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.
+     * Keep a hidden field's control out of form validity — see
+     * `RulesEvaluationService.syncHiddenFieldState`, which owns the rule and the reasoning.
      *
-     * The visibility predicate is the same one `fieldsForActiveTab` filters with, so what is
-     * rendered and what counts toward validity cannot drift apart.
+     * This supplies the three things it cannot know: which fields exist and in what order
+     * (`collectFieldScopes`, parent-first), what each one is called, and which control each
+     * one addresses.
      */
     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;
+    /**
+     * Whether a critical field still holds what it held when the session started.
+     *
+     * The same question `VALUE_CHANGED` asks, so it is answered by the same comparator rather
+     * than by a third one. The local version compared objects through `JSON.stringify`, which
+     * is key-order sensitive — two serialisers writing the same option in a different key
+     * order made the field read as edited — and had its own idea of which values count as
+     * empty. `valuesEqual` is order-independent and treats `null` and `undefined` as the same
+     * absence; the empty-string case is kept here, because a cleared text input is not an edit.
+     */
     private sameValue;
+    /**
+     * Find a control by a bracketed path or a bare field id.
+     *
+     * Public API, so it stays on the component and delegates — see `FormStructureService`,
+     * which owns the resolution rule and is where the behaviour is documented.
+     */
     getControl(fieldId: string, currentTabId?: string): AbstractControl | null;
     /**
      * Move focus into the newly shown panel.
@@ -2300,7 +2455,7 @@ declare function fieldDomId(field: {
  * 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
+ * Shared rather than written into each of the twenty-one 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: {
@@ -2431,7 +2586,14 @@ declare class MarkdownFieldComponent implements OnChanges {
      * A renderer is consumer code and may throw on input it does not like. Letting that
      * escape would take down the whole form over one malformed field, so it falls back to the
      * source text — which is what the field would have shown with no renderer at all.
+     *
+     * Memoised on the source, because this is called from the template: without it the
+     * consumer's markdown parser ran on every change-detection pass, for every markdown field
+     * on screen, over the whole document — which on a form holding a few long ones is a parse
+     * per keystroke *elsewhere* in the form. The cache is keyed by the exact source string,
+     * so a value that comes back to something already rendered is free too.
      */
+    private cached?;
     protected rendered(): string | null;
     /**
      * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
@@ -2867,11 +3029,20 @@ declare class DropdownFieldComponent {
     readonly: boolean;
     masked: boolean;
     /** Inline `options`, or the field's named list resolved through the registry (§6.3). */
-    readonly options: i0.WritableSignal<ngx_dynamic_entity.LocalizedText[]>;
+    readonly options: i0.WritableSignal<DropdownOption[]>;
     readonly compareFn: (o1: unknown, o2: unknown) => boolean;
     isObjectVal(option: DropdownOption): boolean;
     get label(): string;
     get placeholder(): string;
+    /**
+     * The value this option stores — the option object itself.
+     *
+     * Kept as a method rather than binding `option` straight into the template, because it is
+     * the one place that says *why* the two are the same thing. It used to delegate to
+     * `getOptionStoredValue`, an exported identity function whose two branches returned their
+     * argument unchanged; naming a transformation that does not happen is worse than naming
+     * nothing, because a reader has to go and check.
+     */
     getOptStoredVal(option: DropdownOption): unknown;
     getOptLabel(option: DropdownOption): string;
     /**
@@ -2890,7 +3061,7 @@ declare class DropdownFieldComponent {
 }
 
 /** Radio field: a group of radio buttons built from field.options. */
-declare class RadioFieldComponent {
+declare class RadioFieldComponent implements OnDestroy {
     /**
      * 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`.
@@ -2901,19 +3072,34 @@ declare class RadioFieldComponent {
     protected readonly maskedText: string;
     private readonly messages;
     private readonly lookups;
+    private readonly cdr;
     private _field;
     private _language;
+    private _control;
+    private _controlSub?;
+    ngOnDestroy(): void;
     /** Setter-based so options resolve however the input is set — see `refreshChoiceOptions`. */
     set field(value: NestedFieldConfig);
     get field(): NestedFieldConfig;
     set language(value: string);
     get language(): string;
-    control: AbstractControl;
+    set control(value: AbstractControl);
+    get control(): AbstractControl;
     readonly: boolean;
     masked: boolean;
     /** Inline `options`, or the field's named list resolved through the registry (§6.3). */
-    readonly options: i0.WritableSignal<ngx_dynamic_entity.LocalizedText[]>;
+    readonly options: i0.WritableSignal<DropdownOption[]>;
+    onSelect(option: DropdownOption): void;
     get label(): string;
+    /**
+     * The value this option stores — the option object itself.
+     *
+     * Kept as a method rather than binding `option` straight into the template, because it is
+     * the one place that says *why* the two are the same thing. It used to delegate to
+     * `getOptionStoredValue`, an exported identity function whose two branches returned their
+     * argument unchanged; naming a transformation that does not happen is worse than naming
+     * nothing, because a reader has to go and check.
+     */
     getOptStoredVal(option: DropdownOption): unknown;
     /**
      * Stable DOM id for one radio, so the <label for> association works.
@@ -2931,6 +3117,8 @@ declare class RadioFieldComponent {
     optionSlug(option: DropdownOption): string;
     getOptVal(option: DropdownOption): string | number | boolean;
     getOptLabel(option: DropdownOption): string;
+    /** Whether the given option matches the control's current value. */
+    isChecked(option: DropdownOption): boolean;
     /** Read-only display — synchronous, per §6.2. See `DropdownFieldComponent.getLabel`. */
     getSelectedLabel(): string;
     /**
@@ -2970,10 +3158,19 @@ declare class MultiSelectFieldComponent {
     readonly: boolean;
     masked: boolean;
     /** Inline `options`, or the field's named list resolved through the registry (§6.3). */
-    readonly options: i0.WritableSignal<ngx_dynamic_entity.LocalizedText[]>;
+    readonly options: i0.WritableSignal<DropdownOption[]>;
     readonly compareFn: (o1: unknown, o2: unknown) => boolean;
     isObjectVal(option: DropdownOption): boolean;
     get label(): string;
+    /**
+     * The value this option stores — the option object itself.
+     *
+     * Kept as a method rather than binding `option` straight into the template, because it is
+     * the one place that says *why* the two are the same thing. It used to delegate to
+     * `getOptionStoredValue`, an exported identity function whose two branches returned their
+     * argument unchanged; naming a transformation that does not happen is worse than naming
+     * nothing, because a reader has to go and check.
+     */
     getOptStoredVal(option: DropdownOption): unknown;
     getOptLabel(option: DropdownOption): string;
     /** Read-only display — synchronous, per §6.2. See `DropdownFieldComponent.getLabel`. */
@@ -3197,4 +3394,4 @@ declare class FileFieldComponent {
 }
 
 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, EntityImportComponent, EntityRefFieldComponent, EntityRefRegistryService, EntityRefSelectionService, EntityReferenceService, FIELD_TYPE_REGISTRY, FIELD_TYPE_SETS, FieldRegistryService, FileFieldComponent, GroupFieldComponent, HOOK_REGISTRY, HookRegistryService, HttpImportTransport, IMPORT_TRANSPORT, ImageFieldComponent, ImportErrorsComponent, ImportMapperComponent, ImportPreviewComponent, ImportTemplateComponent, InMemoryEntityRefCacheStore, LOOKUP_REGISTRY, LocalImportTransport, LookupRegistryService, MARKDOWN_RENDERER, MASKED_PLACEHOLDER, MASKED_ROLES, MarkdownFieldComponent, MonthYearFieldComponent, MultiSelectFieldComponent, NumberFieldComponent, PasswordFieldComponent, RECORD_MIGRATIONS, RadioFieldComponent, RbacService, RulesEvaluationService, SHEET_PARSER, SYSTEM_DEFAULT_CAN_EDIT, TextFieldComponent, TextareaFieldComponent, TimeFieldComponent, UI_TEXT, UPLOAD_HANDLER, UiTextService, VALIDATION_MESSAGES, VALIDATOR_REGISTRY, ValidationMessagesService, ValidatorRegistryService, builtInFieldTypes, defaultSheetParser, fieldDescribedBy, fieldDomId, nextFieldInstanceId, provideBuiltInFieldTypes, provideFieldTypes, provideHttpImportTransport, provideNgxDynamicEntity, refreshChoiceOptions, resolveUiText };
-export type { ChoiceOptionHost, ConfigSourceHandler, DynamicFieldComponentContract, EntityRefCacheStore, EntityRefSelection, HookFn, HttpImportTransportOptions, ImportContext, ImportPreview, ImportTransport, InvalidField, MessageOrderEntry, NgxDynamicEntityConfig, SheetParser, TemplateFormat, UiTextKey, UiTextOverrides, UiTextOverridesFor, UiTextParams, UiTextResolver, UiTextResolverFor, UiTextValue, ValidationMessage };
+export type { ChoiceOptionHost, ConfigSourceHandler, DynamicFieldComponentContract, EntityRefCacheStore, EntityRefSelection, HookFn, HttpImportTransportOptions, ImportContext, ImportPreview, ImportTransport, InvalidField, MessageOrderEntry, NgxDynamicEntityConfig, RuleSyncContext, SheetParser, TemplateFormat, UiTextKey, UiTextOverrides, UiTextOverridesFor, UiTextParams, UiTextResolver, UiTextResolverFor, UiTextValue, ValidationMessage };