ngx-dynamic-entity 0.0.1 → 1.1.0

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

@@ -1,52 +1,231 @@
-import { EventEmitter, OnChanges, SimpleChanges } from '@angular/core';
-import { FormGroup } from '@angular/forms';
-import type { EntityConfig } from '@dynamic-entity/core';
-import { VersionService } from '../services/version.service';
+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.
- * Renders a reactive form from EntityConfig with tab support, dependencies,
- * migration banner, and RBAC-gated submission.
- *
- * ONEHERMES pattern: isSaving state lock prevents subscription cyclones (ADR-002).
- * ONEHERMES bug fix: visibility rules re-evaluated after initialData loads (form-fixes doc).
- * ONEHERMES bug fix: use @for + @if separately, not both on same element (form-fixes doc).
+ * Renders a reactive form from EntityFormConfig with tab support, responsive 12-col grid,
+ * rules evaluation, conditional visibility, autoPatch/patchOnTrue, criticalField locking,
+ * keyboard shortcuts (Ctrl+S, Esc), and RBAC-gated submission.
  */
-export declare class DynamicFormComponent implements OnChanges {
-    config: EntityConfig;
+export declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
+    config: EntityFormConfig;
+    rules?: FormRule[];
     initialData?: Record<string, any>;
+    /** Session-original values for `VALUE_CHANGED` rules. Captured from the first build when omitted. */
+    originalData?: Record<string, any>;
     userRoles: string[];
     language: string;
     readonly: boolean;
+    /** Field ids forced read-only while the rest of the form stays editable. */
+    readOnlyFields: string[];
+    /**
+     * Render rule `info` banners inline. The record editor sets this false and renders its
+     * own dismissible versions, so the two do not double up.
+     */
+    showInfoBanners: boolean;
     loading: boolean;
     error: string | null;
+    /**
+     * Milliseconds to debounce `formChange`. The reference debounces at 300ms so a consumer
+     * re-rendering on every value change is not driven per keystroke. Zero emits
+     * synchronously, which the record editor relies on for its own bookkeeping.
+     */
+    changeDebounceMs: number;
+    /**
+     * Preview mode: seed one empty row per `array` field so the structure is visible, then
+     * disable the form. Used by the builder's live preview.
+     */
+    preview: boolean;
     formSubmit: EventEmitter<Record<string, any>>;
     formChange: EventEmitter<Record<string, any>>;
     formReset: EventEmitter<void>;
+    /** The visible tab changed. Lets a host track it without reaching into this component. */
+    activeTabChange: EventEmitter<string>;
     private readonly fb;
     private readonly validatorRegistry;
     private readonly hookRegistry;
-    protected readonly versionService: VersionService;
     private readonly rbacService;
+    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>;
     readonly isSaving: import("@angular/core").WritableSignal<boolean>;
+    readonly formValues: import("@angular/core").WritableSignal<Record<string, any>>;
+    /** Baseline captured at first build, used when `originalData` is not supplied. */
+    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>>;
     form: FormGroup;
-    get tabs(): import("@dynamic-entity/core").TabConfig[];
-    get fieldsForActiveTab(): import("@dynamic-entity/core").FieldConfig[];
-    get permissions(): {
-        canView: boolean;
-        canEdit: boolean;
-        canDelete: boolean;
-    };
-    get needsMigration(): boolean;
+    private valueSub?;
+    private selectionSub?;
+    /** Previous values, for detecting `patchOnTrue` false→true transitions. */
+    private previousValues;
+    handleKeyboardEvent(event: KeyboardEvent): void;
+    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,
+     * against the value the record had when the session started, not per keystroke.
+     */
+    readonly changedCriticalFields: import("@angular/core").Signal<NestedFieldConfig[]>;
+    get tabs(): NestedTabConfig[];
+    get visibleTabs(): NestedTabConfig[];
+    get activeTabConfig(): NestedTabConfig | null;
+    get visibleSubTabs(): NestedTabConfig[];
+    get activeSubTabConfig(): NestedTabConfig | null;
+    get activeTabModuleComponent(): any | null;
+    get fieldsForActiveTab(): NestedFieldConfig[];
+    /**
+     * 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;
+    /** 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;
+    setActiveTab(tabId: string): void;
+    setActiveSubTab(subTabId: string): void;
+    getFieldSpan(field: NestedFieldConfig): string;
+    /** A critical field stays read-only until the user deliberately unlocks it. */
+    isFieldLocked(field: NestedFieldConfig): boolean;
+    /**
+     * Whether this field renders read-only, from any of the four reasons: the whole form,
+     * the field's own flag, a caller-supplied `readOnlyFields` entry, or a criticalField lock.
+     */
+    isFieldReadonly(field: NestedFieldConfig): boolean;
+    toggleFieldLock(field: NestedFieldConfig): void;
+    resolveFieldLabel(field: NestedFieldConfig): 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.
+     */
+    getArrayControl(fieldId: string, tabId?: string): FormArray | null;
+    /**
+     * Build one detached row for an `array` field, with the field's own validators applied.
+     * Exposed so a row can be edited outside the form and pushed on save.
+     */
+    createArrayRow(field: NestedFieldConfig, value?: unknown): AbstractControl;
+    private buildArrayRow;
+    /**
+     * 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;
-    setActiveTab(tabId: string): void;
+    /**
+     * 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;
+    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.
+     */
+    private runAutoPatch;
+    /**
+     * `patchOnTrue` — when a boolean/checkbox field transitions to `true`,
+     * 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.
+     */
+    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;
+    resolveTabLabel(tab: NestedTabConfig): string;
     submit(): Promise<void>;
     reset(): void;
-    getControl(fieldId: string): import("@angular/forms").AbstractControl<any, any>;
     static ɵfac: i0.ɵɵFactoryDeclaration<DynamicFormComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<DynamicFormComponent, "ngx-dynamic-form", never, { "config": { "alias": "config"; "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; }; }, { "formSubmit": "formSubmit"; "formChange": "formChange"; "formReset": "formReset"; }, 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"; }, never, never, true, never>;
 }

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

@@ -0,0 +1,180 @@
+import { EventEmitter, OnChanges, SimpleChanges } from '@angular/core';
+import { FormGroup } from '@angular/forms';
+import type { EntityFormConfig, FormRule, NestedFieldConfig } from '@dynamic-entity/core';
+import { DynamicFormComponent } from './dynamic-form.component';
+import * as i0 from "@angular/core";
+/**
+ * DynamicRecordFormComponent — comprehensive tabbed record view & edit component.
+ * Supports cross-tab rule evaluation, profile header, summary drawer (showOnMinimize),
+ * interactive quick-jump links, and baseline modification tracking.
+ */
+export declare class DynamicRecordFormComponent implements OnChanges {
+    config: EntityFormConfig;
+    rules?: FormRule[];
+    initialData?: Record<string, any>;
+    userRoles: string[];
+    language: string;
+    readonly: boolean;
+    loading: boolean;
+    error: string | null;
+    /** Whole record read-only, regardless of RBAC. Equivalent to the reference's `isReadOnly`. */
+    isReadOnly: boolean;
+    /** Specific field ids forced read-only while the rest of the record stays editable. */
+    readOnlyFields: string[];
+    /**
+     * 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
+     * default here.
+     *
+     * Set false for a directly editable record with no view/edit distinction.
+     */
+    viewMode: boolean;
+    formSubmit: EventEmitter<Record<string, any>>;
+    formChange: EventEmitter<Record<string, any>>;
+    formReset: EventEmitter<void>;
+    /** One tab section was saved. Carries the whole record, plus which tab was edited. */
+    sectionSave: EventEmitter<{
+        tabId: string;
+        record: Record<string, any>;
+    }>;
+    dynamicFormComp?: DynamicFormComponent;
+    private readonly rulesEvaluation;
+    readonly currentData: import("@angular/core").WritableSignal<Record<string, any>>;
+    readonly originalBaseline: import("@angular/core").WritableSignal<Record<string, any>>;
+    /**
+     * Info banners the user has dismissed, by field id.
+     *
+     * The reference's contract: an info banner persists until dismissed, **not** until the
+     * value changes. Dismissal is keyed by field so re-triggering a different field's rule
+     * still shows. Re-armed when a different record is loaded.
+     */
+    private readonly dismissed;
+    /**
+     * Info banners from the rules engine that are still showing.
+     *
+     * A getter, not a `computed`: the source is `dynamicFormComp`, a ViewChild. A computed
+     * evaluated before the view initialises would capture no dependency on the child's
+     * `ruleResult` signal and then never recompute. Read per change-detection pass instead.
+     */
+    get infoBanners(): {
+        fieldId: string;
+        message: string;
+    }[];
+    dismissInfoBanner(fieldId: string): void;
+    /** True when nothing in the record may be edited. */
+    get recordReadOnly(): boolean;
+    /**
+     * A row of an `array` field is edited in a drawer, not inline in the tab panel.
+     *
+     * The drawer is rendered outside the tab container on purpose: the reference found that
+     * 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<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. */
+    get arrayFieldsForActiveTab(): NestedFieldConfig[];
+    /**
+     * Rows currently held by an `array` field, read from the record value.
+     *
+     * Deliberately not read off the child's FormArray: that control only exists once the
+     * child has initialised, so rendering from it changed value mid-pass. `currentData` is a
+     * signal seeded from `initialData` and kept current by the child's `formChange`.
+     */
+    rowsOf(field: NestedFieldConfig): Record<string, unknown>[];
+    /** One row rendered as text, so the list is readable without opening the drawer. */
+    rowSummary(field: NestedFieldConfig, row: Record<string, unknown>): string;
+    openAddRow(field: NestedFieldConfig): void;
+    openEditRow(field: NestedFieldConfig, index: number): void;
+    cancelRow(): void;
+    /** Commit the drawer into the FormArray. Rules re-evaluate off the resulting value change. */
+    saveRow(): void;
+    deleteRow(field: NestedFieldConfig, index: number): void;
+    /**
+     * The tab currently open for editing, or null when the record is being viewed.
+     *
+     * The reference edits one tab section at a time rather than the whole record, and
+     * validates only that section on save — a required field on an untouched tab must not
+     * block saving the tab you are actually working on.
+     */
+    readonly editingTabId: import("@angular/core").WritableSignal<string>;
+    /**
+     * The tab the inner form is showing.
+     *
+     * Tracked here rather than read off the ViewChild. The child resolves its first tab as
+     * part of its own initialisation, so reading it during this component's render changed
+     * value mid-pass — an ExpressionChangedAfterItHasBeenChecked error. Seeded from the
+     * config and kept in step by the child's `activeTabChange` output.
+     */
+    private readonly activeTabIdSig;
+    get activeTabId(): string | null;
+    onActiveTabChange(tabId: string): void;
+    /** First tab a user can see, used to seed the active tab before the child reports one. */
+    private firstVisibleTabId;
+    /** Errors from the last save attempt, by field id. */
+    readonly sectionErrors: import("@angular/core").WritableSignal<Record<string, string>>;
+    /** Template access to `Object.keys` for iterating the error map. */
+    protected readonly Object: ObjectConstructor;
+    get isEditingActiveTab(): boolean;
+    /** Fields render read-only unless their own tab is the one being edited. */
+    get sectionReadOnly(): boolean;
+    editSection(): void;
+    /** Discard this section's edits, restoring each field from the session baseline. */
+    cancelSection(): void;
+    /**
+     * Validate this section only, then emit it. Validation is scoped two ways: Angular
+     * 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;
+    /**
+     * 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
+     * after the first keystroke.
+     */
+    ngOnChanges(changes: SimpleChanges): void;
+    get recordTitle(): string;
+    get avatarLetter(): string;
+    /** Every field in the config, at any depth. */
+    private allFields;
+    /** The field flagged `isProfileImage`, rendered as the record avatar. */
+    get headerProfileField(): NestedFieldConfig | null;
+    /** The field flagged `isHeaderToggle`, rendered as a status switch in the header. */
+    get headerToggleField(): NestedFieldConfig | null;
+    /** Avatar image URL, when the profile field holds a persisted FileRef. */
+    get profileImageUrl(): string | null;
+    get headerToggleValue(): boolean;
+    /**
+     * Flip the header toggle. It writes straight to the control rather than going through
+     * section editing — the reference treats it as a record-level status switch, not part of
+     * any one tab's section.
+     */
+    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.
+     *
+     * 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[]>;
+    onFormChange(data: Record<string, any>): void;
+    onFormSubmit(data: Record<string, any>): void;
+    onFormReset(): void;
+    formatFieldLabel(field: NestedFieldConfig): string;
+    /** Summary values render through the shared core formatter, not a local stringifier. */
+    formatFieldValue(field: NestedFieldConfig): string;
+    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>;
+}

package/lib/providers/provide-field-types.d.ts

@@ -0,0 +1,24 @@
+import { EnvironmentProviders, Type } from '@angular/core';
+/**
+ * Field-type registration — the tree-shaking seam.
+ *
+ * `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.
+ *
+ * ```ts
+ * // Everything (convenient; bundles all built-ins):
+ * provideNgxDynamicEntity(), provideBuiltInFieldTypes()
+ *
+ * // Only what this app renders:
+ * provideFieldTypes({ text: TextFieldComponent, number: NumberFieldComponent })
+ * ```
+ *
+ * Both merge into `FIELD_TYPE_REGISTRY`; later registrations win on key collision.
+ */
+/** Map of every built-in field type key → component. Referencing this pulls in all of them. */
+export declare function builtInFieldTypes(): Record<string, Type<any>>;
+/** Register a specific set of field types. Only the components you name are bundled. */
+export 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. */
+export declare function provideBuiltInFieldTypes(): EnvironmentProviders;

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

@@ -1,19 +1,31 @@
 import { EnvironmentProviders, Type } from '@angular/core';
+import type { EntityReferenceLoader, LookupListSource, RecordMigration } from '@dynamic-entity/core';
+import { type HookFn } from '../tokens/injection-tokens';
 export interface NgxDynamicEntityConfig {
-    /** Base URL of the dynamic-entity-server API. Example: 'http://localhost:3000/api/entities' */
-    apiUrl?: string;
     /** Roles that see masked field values as XXXXXXXXX */
     maskedRoles?: string[];
-    /** Migration strategy: 'strict' rejects stale records, 'graceful' flags them. Never 'auto' (ADR-005). */
-    migrationStrategy?: 'strict' | 'graceful';
     /** Custom field type components keyed by type string */
     fieldTypes?: Record<string, Type<any>>;
-    /** Entity-ref option loaders keyed by entity key (ADR-006) */
-    entityRefs?: Record<string, () => Promise<any[]>>;
+    /**
+     * Entity-ref option loaders keyed by entity key (ADR-006).
+     * Each receives `{ parentValue, filters, lang }` and may return an array, Promise, or Observable.
+     */
+    entityRefs?: Record<string, EntityReferenceLoader>;
+    /**
+     * Named master lists keyed by list name, for fields that set `listName`.
+     * Each may be the values themselves (array/Promise/Observable) or a loader function — prefer
+     * a loader for anything fetched, so an unused list is never loaded.
+     */
+    lookups?: Record<string, LookupListSource>;
     /** 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.
@@ -21,7 +33,6 @@ export interface NgxDynamicEntityConfig {
  *
  * Usage in app.config.ts:
  *   provideNgxDynamicEntity({
- *     apiUrl: 'http://localhost:3000/api/entities',
  *     maskedRoles: ['IT_SUPPORT'],
  *     entityRefs: { clients: () => clientService.getOptions() },
  *   })

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

@@ -0,0 +1,45 @@
+import type { EntityFormConfig, NestedFieldConfig, ReferenceLoaderContext, ReferenceOption } from '@dynamic-entity/core';
+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
+ * field component should not: resolving the loader, coercing whatever it returned
+ * (array | Promise | Observable) into a Promise, and filtering by the parent's value.
+ */
+export declare class CascadeDataService {
+    private readonly registry;
+    private readonly references;
+    /** Preload runs by formConfigId, so a second call joins the first rather than re-fetching. */
+    private readonly preloads;
+    /** Registry key for a field: explicit `linkedEntityKey`, else the field id. */
+    entityKeyFor(field: NestedFieldConfig): string;
+    /** Whether a loader is registered for this field. */
+    canLoad(field: NestedFieldConfig): boolean;
+    /**
+     * Load the options for a field, cascade-filtered against `parentValue`.
+     * Returns `[]` when no loader is registered, or when a cascade child has no parent value yet.
+     */
+    load(field: NestedFieldConfig, ctx?: ReferenceLoaderContext): Promise<ReferenceOption[]>;
+    /**
+     * Warm the cache for every entity a config's cascades depend on, so changing a parent
+     * resolves from memory instead of a round-trip.
+     *
+     * Idempotent per `formConfigId`: calling it again returns the in-flight or completed run
+     * rather than re-fetching.
+     */
+    initializeCascadeData(formConfigId: string, config: EntityFormConfig, lang?: string): Promise<void>;
+    /** Resolves true once `initializeCascadeData` for this config has finished. */
+    waitForData(formConfigId: string): Promise<boolean>;
+    /**
+     * Child options for a parent selection, from cache only — no load is triggered.
+     * Returns `[]` when the entity has not been preloaded.
+     */
+    getCachedChildOptions(field: NestedFieldConfig, parentValue: unknown, lang?: string): ReferenceOption[];
+    /** Forget the preload for one config. The option cache itself is untouched. */
+    clearCache(formConfigId: string): void;
+    /** Every entity-ref field in the config that participates in a cascade. */
+    private cascadeFields;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CascadeDataService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CascadeDataService>;
+}

package/lib/services/config-source.service.d.ts

@@ -0,0 +1,14 @@
+import type { EntityFormConfig } from '@dynamic-entity/core';
+import * as i0 from "@angular/core";
+export declare class ConfigSourceService {
+    private readonly cache;
+    private readonly inFlight;
+    private readonly handler?;
+    constructor(handler?: any);
+    /** Retrieve an entity config by key, with caching and in-flight deduplication. */
+    getConfig(entityKey: string): Promise<EntityFormConfig | undefined>;
+    /** Clear cached configs (e.g. after a config edit in the builder). */
+    clearCache(entityKey?: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ConfigSourceService, [{ optional: true; }]>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ConfigSourceService>;
+}

package/lib/services/entity-ref-cache.d.ts

@@ -0,0 +1,27 @@
+import type { ReferenceOption } from '@dynamic-entity/core';
+/**
+ * Backing store for cached reference options.
+ *
+ * Pluggable on purpose. The reference implementation kept its cache in a service instance,
+ * so every entity label was re-fetched on a browser refresh (issue #22 in the architecture
+ * doc). A consumer that wants the cache to survive a reload can back this with
+ * sessionStorage; the default keeps it in memory, which is the right call for a library
+ * that must not silently persist a tenant's data.
+ */
+export interface EntityRefCacheStore {
+    get(key: string): ReferenceOption[] | undefined;
+    set(key: string, value: ReferenceOption[]): void;
+    delete(key: string): void;
+    /** Every key currently held — used for prefix invalidation of one entity. */
+    keys(): string[];
+    clear(): void;
+}
+/** Default in-memory store. Lives as long as the injector that created it. */
+export declare class InMemoryEntityRefCacheStore implements EntityRefCacheStore {
+    private readonly map;
+    get(key: string): ReferenceOption[] | undefined;
+    set(key: string, value: ReferenceOption[]): void;
+    delete(key: string): void;
+    keys(): string[];
+    clear(): void;
+}

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

@@ -1,3 +1,4 @@
+import type { EntityReferenceLoader } from '@dynamic-entity/core';
 import * as i0 from "@angular/core";
 /**
  * EntityRefRegistryService — resolves entity-ref option loader functions.
@@ -10,10 +11,10 @@ import * as i0 from "@angular/core";
 export declare class EntityRefRegistryService {
     private readonly registry;
     /**
-     * Get the option loader function for an entity key.
-     * @returns Async function that returns options array, or null if not registered.
+     * Get the option loader for an entity key.
+     * @returns The loader, or null if none is registered.
      */
-    resolve(entityKey: string): (() => Promise<any[]>) | null;
+    resolve(entityKey: string): EntityReferenceLoader | null;
     has(entityKey: string): boolean;
     static ɵfac: i0.ɵɵFactoryDeclaration<EntityRefRegistryService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<EntityRefRegistryService>;

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

@@ -0,0 +1,24 @@
+import type { ReferenceOption } from '@dynamic-entity/core';
+import * as i0 from "@angular/core";
+export interface EntityRefSelection {
+    fieldId: string;
+    /** The chosen option, or `null` when the selection was cleared. */
+    option: ReferenceOption | null;
+}
+/**
+ * EntityRefSelectionService — the channel an entity-ref field uses to publish *which record*
+ * the user picked, so the owning form can run `autoPatch` against it.
+ *
+ * The control value alone is not enough: `autoPatch` copies fields out of the selected
+ * record, which only the field component has after loading its options.
+ *
+ * Provided at `DynamicFormComponent` level so each form instance gets its own channel;
+ * the `root` fallback keeps standalone field components injectable in isolation.
+ */
+export declare class EntityRefSelectionService {
+    private readonly subject;
+    readonly selection$: import("rxjs").Observable<EntityRefSelection>;
+    emit(fieldId: string, option: ReferenceOption | null): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EntityRefSelectionService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<EntityRefSelectionService>;
+}