ngx-dynamic-entity 1.13.0 → 2.0.0

package/fesm2022/ngx-dynamic-entity.mjs

@@ -1,8 +1,8 @@
 import * as i0 from '@angular/core';
 import { InjectionToken, makeEnvironmentProviders, inject, Injectable, signal, Input, ChangeDetectionStrategy, Component, ChangeDetectorRef, DestroyRef, Injector, isDevMode, ViewContainerRef, ViewChild, forwardRef, Optional, Inject, EventEmitter, ElementRef, computed, afterNextRender, HostListener, ViewChildren, Output } from '@angular/core';
 import * as i1 from '@angular/forms';
-import { ReactiveFormsModule, Validators, FormBuilder, FormArray, FormGroup } from '@angular/forms';
-import { resolveLabel, formatDisplayValue, normalizeLookupValues, lookupValuesToOptions, valuesMatch, getOptionStoredValue, resolveOptionLabel, resolveOptionValue, buildReferenceCacheKey, normalizeReferenceOptions, entityKeyFromCacheKey, applyCascadeFilter, resolveEffectiveMask, shouldMaskField, findTab, fileRefName, evaluateFormRules, filterRulesForTab, evaluateFieldVisibility, normalizeConfigOptions, migrateRecord, getTabData, getValueByPath, setTabData, setValueByPath, normalizeArrayStructures, ambiguousFieldIds, parseFieldRef, toRefToken, collectFieldScopes, fieldRefFor, refOf, getTabPath, applyAutoPatch, applyPatchOnTrue } from '@dynamic-entity/core';
+import { ReactiveFormsModule, Validators, FormBuilder, FormGroup, FormArray, FormsModule } from '@angular/forms';
+import { resolveLabel, formatDisplayValue, normalizeLookupValues, lookupValuesToOptions, valuesMatch, resolveOptionLabel, resolveOptionValue, buildReferenceCacheKey, normalizeReferenceOptions, entityKeyFromCacheKey, applyCascadeFilter, resolveEffectiveMask, shouldMaskField, findTab, fileRefName, evaluateFormRules, filterRulesForTab, evaluateFieldVisibility, getTabPath, parseFieldRef, setTabData, setValueByPath, normalizeArrayStructures, getTabData, getValueByPath, normalizeConfigOptions, migrateRecord, ambiguousFieldIds, toRefToken, fieldRefFor, collectFieldScopes, refOf, applyAutoPatch, applyPatchOnTrue, fieldsUnderTab, valuesEqual, parseCsv, deriveImportColumns, suggestMapping, applyMapping, toCsv, stripIndices, CORE_VERSION, coerceCell, buildTemplateSpec, collectLeafTargets, formatConfigProblems } from '@dynamic-entity/core';
 export { formatDisplayValue, normalizeConfig, normalizeOption, resolveLabel, resolveOptionLabel, resolveOptionValue, valuesMatch } from '@dynamic-entity/core';
 import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import { Subject, isObservable, firstValueFrom } from 'rxjs';
@@ -139,6 +139,46 @@ const COMMON_MODULES_REGISTRY = new InjectionToken('COMMON_MODULES_REGISTRY');
  * { provide: UPLOAD_HANDLER, useFactory: () => (file: File) => myUploadService.upload(file) }
  */
 const UPLOAD_HANDLER = new InjectionToken('UPLOAD_HANDLER');
+/**
+ * Reads an uploaded spreadsheet into headers and positional rows, for the import wizard.
+ *
+ * Unregistered, the wizard reads CSV with the dependency-free parser in
+ * `@dynamic-entity/core`, so it works with nothing provided. Register one to accept `.xlsx`
+ * — which spreadsheet library that uses stays the consumer's choice, and this package keeps
+ * having no runtime dependency.
+ *
+ * Rows come back **positional** (`string[][]`) rather than keyed by header, because a real
+ * sheet has duplicate headers and blank ones; a header-keyed row silently loses the second
+ * of two columns both called "Notes".
+ *
+ * @example
+ * provideNgxDynamicEntity({
+ *   sheetParser: async file => {
+ *     const wb = XLSX.read(await file.arrayBuffer());
+ *     const rows = XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]], {
+ *       header: 1, raw: false, defval: '',
+ *     }) as string[][];
+ *     return { headers: rows[0] ?? [], rows: rows.slice(1) };
+ *   },
+ * })
+ */
+const SHEET_PARSER = new InjectionToken('SHEET_PARSER');
+/**
+ * Where an import's work happens.
+ *
+ * Unregistered, everything runs in the browser through `@dynamic-entity/core` and nothing
+ * touches the network — the wizard is fully usable with no backend. Register one that posts
+ * to a server and the same components drive that instead, over the same pure mapping engine,
+ * which is what keeps a client-side import and a server-side one from disagreeing about what
+ * they produced.
+ *
+ * The reason to register one is size: the default reads the whole file into memory, which is
+ * right for a sheet somebody assembled and wrong for a fifty-thousand-row export.
+ *
+ * @example
+ * { provide: IMPORT_TRANSPORT, useClass: HttpImportTransport }
+ */
+const IMPORT_TRANSPORT = new InjectionToken('IMPORT_TRANSPORT');
 /**
  * Backing store for the entity-reference options cache. Defaults to in-memory.
  * Provide your own to make the cache outlive a page refresh.
@@ -252,6 +292,10 @@ const provideNgxDynamicEntity = (config = {}) => makeEnvironmentProviders([
     { provide: RECORD_MIGRATIONS, useValue: config.migrations ?? [] },
     { provide: VALIDATION_MESSAGES, useValue: config.validationMessages ?? {} },
     { provide: UI_TEXT, useValue: config.uiText ?? {} },
+    // Both optional and both null when unset: the wizard falls back to the built-in CSV
+    // parser and the in-browser transport, so it works with nothing registered.
+    { provide: SHEET_PARSER, useValue: config.sheetParser ?? null },
+    { provide: IMPORT_TRANSPORT, useValue: config.importTransport ?? null },
 ]);
 
 /** The built-in English messages. Every key here can be overridden individually. */
@@ -399,7 +443,7 @@ function fieldDomId(field, instance, suffix = '') {
  * 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.
  */
 function fieldDescribedBy(domId, parts) {
@@ -837,6 +881,49 @@ const DEFAULT_UI_TEXT = {
     criticalFieldUnlockHint: 'Critical field — click to unlock for editing',
     dismissBanner: 'Dismiss: {message}',
     jumpToField: 'Click to jump to {field}',
+    // Import wizard — the steps, in order
+    importUpload: 'Choose a file',
+    importMap: 'Match columns',
+    importReview: 'Review',
+    importDone: 'Done',
+    // Import wizard — choosing a file
+    importChooseFile: 'Choose a spreadsheet',
+    importFileChosen: '{name} — {rows} row(s)',
+    importReading: 'Reading the file…',
+    importNeedFile: 'Choose a file to continue.',
+    // Import wizard — the template a user can start from
+    importTemplateHeading: 'Start from a template',
+    importTemplateExplain: 'Download a sheet with the right columns, fill it in, and upload it.',
+    importTemplateDownload: 'Download template',
+    importTemplateSelectAll: 'Select all',
+    importTemplateSelectNone: 'Select none',
+    importTemplateUnsupported: '{count} field(s) cannot be carried by a spreadsheet.',
+    // Import wizard — matching columns
+    importColumnInFile: 'Column in your file',
+    importTargetField: 'Field',
+    importUnmapped: 'Not imported',
+    importGuessed: 'Guessed',
+    importMappedCount: '{mapped} of {total} field(s) matched.',
+    importRequiredUnmapped: '{count} required field(s) still need a column.',
+    // Import wizard — review and result
+    importPreviewHeading: 'First {count} row(s), as they will be saved',
+    importRowRejected: 'This row will not be imported: {reason}',
+    importRunImport: 'Import {count} row(s)',
+    importImporting: 'Importing…',
+    importSucceeded: 'Imported {count} record(s).',
+    importSkippedRows: '{count} blank row(s) skipped.',
+    importFailedRows: '{count} row(s) could not be imported.',
+    // A streaming transport caps what it retains — fifty thousand error objects is the same
+    // unbounded growth as holding the file — so the count and the sample are different numbers
+    // and the user is told which they are looking at.
+    importErrorsTruncated: 'Showing the first {shown} of {count} problem(s).',
+    importStartOver: 'Import another file',
+    // Import wizard — what went wrong
+    importErrorsHeading: 'Rows that need attention',
+    importErrorRow: 'Row {row}',
+    importErrorField: 'Field',
+    importErrorReason: 'Reason',
+    importPlanProblem: 'This mapping cannot be used: {message}',
     // Banners and whole-record states
     entityLabel: 'Entity: {entity}',
     criticalFieldChanged: '🔒 Critical field changed: {fields} — this differs from the value at the start of this session.',
@@ -1013,17 +1100,29 @@ class MarkdownFieldComponent {
      * 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.
      */
+    cached;
     rendered() {
         const source = this.control?.value;
         if (!this.render || typeof source !== 'string' || source === '')
             return null;
+        if (this.cached?.source === source)
+            return this.cached.html;
+        let html;
         try {
-            return this.render(source);
+            html = this.render(source);
         }
         catch {
-            return null;
+            html = null;
         }
+        this.cached = { source, html };
+        return html;
     }
     /**
      * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
@@ -3491,8 +3590,7 @@ class DropdownFieldComponent {
     options = signal([], ...(ngDevMode ? [{ debugName: "options" }] : /* istanbul ignore next */ []));
     compareFn = (o1, o2) => valuesMatch(o1, o2, this.language);
     isObjectVal(option) {
-        const val = getOptionStoredValue(option);
-        return typeof val === 'object' && val !== null;
+        return typeof option === 'object' && option !== null;
     }
     get label() {
         return resolveLabel(this.field?.label, this.language);
@@ -3500,8 +3598,17 @@ class DropdownFieldComponent {
     get placeholder() {
         return resolveLabel(this.field?.placeholder, this.language);
     }
+    /**
+     * 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) {
-        return getOptionStoredValue(option);
+        return option;
     }
     getOptLabel(option) {
         return resolveOptionLabel(option, this.language);
@@ -3514,7 +3621,7 @@ class DropdownFieldComponent {
     getLabel(value) {
         if (value == null || value === '')
             return '—';
-        const option = this.options().find(o => valuesMatch(getOptionStoredValue(o), value, this.language));
+        const option = this.options().find(o => valuesMatch(o, value, this.language));
         if (option)
             return this.getOptLabel(option);
         const cached = this.lookups.labelFor(this.field?.listName, value, this.language);
@@ -3736,8 +3843,17 @@ class RadioFieldComponent {
     get label() {
         return resolveLabel(this.field?.label, this.language);
     }
+    /**
+     * 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) {
-        return getOptionStoredValue(option);
+        return option;
     }
     /**
      * Stable DOM id for one radio, so the <label for> association works.
@@ -3772,7 +3888,7 @@ class RadioFieldComponent {
         // `resolveLabel(null)` and rendered as blank — dropdown and multiSelect both show an em dash.
         if (value === null || value === undefined || value === '')
             return '—';
-        const selected = this.options().find(o => valuesMatch(getOptionStoredValue(o), value, this.language));
+        const selected = this.options().find(o => valuesMatch(o, value, this.language));
         if (selected)
             return this.getOptLabel(selected);
         const cached = this.lookups.labelFor(this.field?.listName, value, this.language);
@@ -3980,14 +4096,22 @@ class MultiSelectFieldComponent {
     options = signal([], ...(ngDevMode ? [{ debugName: "options" }] : /* istanbul ignore next */ []));
     compareFn = (o1, o2) => valuesMatch(o1, o2, this.language);
     isObjectVal(option) {
-        const val = getOptionStoredValue(option);
-        return typeof val === 'object' && val !== null;
+        return typeof option === 'object' && option !== null;
     }
     get label() {
         return resolveLabel(this.field?.label, this.language);
     }
+    /**
+     * 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) {
-        return getOptionStoredValue(option);
+        return option;
     }
     getOptLabel(option) {
         return resolveOptionLabel(option, this.language);
@@ -3998,7 +4122,7 @@ class MultiSelectFieldComponent {
             return '—';
         return values
             .map(v => {
-            const opt = this.options().find(o => valuesMatch(getOptionStoredValue(o), v, this.language));
+            const opt = this.options().find(o => valuesMatch(o, v, this.language));
             if (opt)
                 return this.getOptLabel(opt);
             const cached = this.lookups.labelFor(this.field?.listName, v, this.language);
@@ -4790,7 +4914,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
  *
  * **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.
@@ -5199,8 +5323,20 @@ class ValidatorRegistryService {
             fnList.push(Validators.minLength(config.minLength));
         if (config.maxLength !== undefined)
             fnList.push(Validators.maxLength(config.maxLength));
-        if (config.pattern)
-            fnList.push(Validators.pattern(config.pattern));
+        if (config.pattern) {
+            // `Validators.pattern` compiles the string, so an unparseable one threw here — during
+            // control construction, which takes the whole form down rather than one field's format
+            // check. `validateConfig` reports it as an error; at runtime the field degrades to no
+            // pattern validation, which is exactly what the server-side import path already does.
+            try {
+                fnList.push(Validators.pattern(config.pattern));
+            }
+            catch (err) {
+                this.warnOnce(`pattern:${config.pattern}`, `The pattern "${config.pattern}" is not a valid regular expression ` +
+                    `(${err instanceof Error ? err.message : String(err)}), so no format check is ` +
+                    `applied to this field. Run "dynamic-entity validate" over the config to find it.`);
+            }
+        }
         if (config.email)
             fnList.push(Validators.email);
         // Named validators from the consumer registry. This branch previously hardcoded the
@@ -5211,6 +5347,8 @@ class ValidatorRegistryService {
             const fn = this.resolve(key);
             if (fn)
                 fnList.push(fn);
+            else
+                this.warnUnresolved('custom', key);
         }
         return fnList;
     }
@@ -5232,9 +5370,35 @@ class ValidatorRegistryService {
             const fn = this.asyncRegistry.get(key);
             if (fn)
                 out.push(fn);
+            else
+                this.warnUnresolved('customAsync', key);
         }
         return out;
     }
+    /**
+     * 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.
+     */
+    warnUnresolved(kind, key) {
+        this.warnOnce(`${kind}:${key}`, `No validator named "${key}" is registered, so validators.${kind} drops it and it never ` +
+            `runs. Register it with provideNgxDynamicEntity({ ${kind === 'customAsync' ? 'asyncValidators' : 'validators'}: { '${key}': ... } }).`);
+    }
+    /** Per service instance, which is per injector — so a test gets a clean slate. */
+    warned = new Set();
+    warnOnce(id, message) {
+        if (!isDevMode() || this.warned.has(id))
+            return;
+        this.warned.add(id);
+        console.warn(`[ngx-dynamic-entity] ${message}`);
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: ValidatorRegistryService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: ValidatorRegistryService, providedIn: 'root' });
 }
@@ -6072,7 +6236,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
  *
  * `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):
@@ -6116,7 +6280,7 @@ function provideFieldTypes(types) {
         { provide: FIELD_TYPE_SETS, useValue: types, multi: true },
     ]);
 }
-/** 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. */
 function provideBuiltInFieldTypes() {
     return provideFieldTypes(builtInFieldTypes());
 }
@@ -6145,14 +6309,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
         }] });
 
 /**
- * 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.
  */
 class RulesEvaluationService {
     /**
      * Evaluate rules against form values and optional original baseline values.
      */
-    evaluate(rules, values, originalValues) {
-        return evaluateFormRules(rules, values, originalValues);
+    evaluate(rules, values, originalValues, options) {
+        return evaluateFormRules(rules, values, originalValues, options);
     }
     /**
      * Filter rules pertinent to a single tab.
@@ -6160,6 +6334,89 @@ class RulesEvaluationService {
     filterForTab(rules, tabId, config) {
         return filterRulesForTab(rules, tabId, config);
     }
+    /**
+     * 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, field, names, values) {
+        const sets = this.nameSets(result);
+        if (names.some(name => sets.hidden.has(name)))
+            return false;
+        if (names.some(name => sets.shown.has(name)))
+            return true;
+        return evaluateFieldVisibility(field, values);
+    }
+    /** The same precedence for a tab. */
+    isTabVisible(result, tab) {
+        if (result.hiddenTabs.includes(tab.id))
+            return false;
+        return tab.visibility !== false || result.shownTabs.includes(tab.id);
+    }
+    /**
+     * 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, ctx) {
+        const hiddenContainers = [];
+        for (const entry of entries) {
+            const field = entry.field;
+            if (!field?.id)
+                continue;
+            const address = ctx.addressOf(field);
+            if (hiddenContainers.some(prefix => address.startsWith(`${prefix}.`)))
+                continue;
+            const hidden = !this.isFieldVisible(ctx.result, field, ctx.namesOf(field), ctx.values);
+            if (hidden && (field.type === 'group' || field.type === 'array'))
+                hiddenContainers.push(address);
+            const ctrl = ctx.controlFor(entry);
+            if (!ctrl)
+                continue;
+            if (hidden) {
+                if (ctrl.enabled)
+                    ctrl.disable({ emitEvent: false });
+            }
+            else if (ctrl.disabled && !field.disabled) {
+                ctrl.enable({ emitEvent: false });
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    nameSets(result) {
+        let sets = this.nameSetCache.get(result);
+        if (!sets) {
+            sets = { hidden: new Set(result.hiddenFields), shown: new Set(result.shownFields) };
+            this.nameSetCache.set(result, sets);
+        }
+        return sets;
+    }
+    nameSetCache = new WeakMap();
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: RulesEvaluationService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: RulesEvaluationService, providedIn: 'root' });
 }
@@ -6231,6 +6488,255 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
                     args: [CONFIG_SOURCE]
                 }] }] });
 
+/**
+ * FormStructureService — config ⇄ `FormGroup`, and nothing else.
+ *
+ * The one question this answers is *where a value lives*: which control a field owns, how
+ * the tab tree nests into groups, how a record is read out of the tree and patched back in.
+ * It was half of `DynamicFormComponent`, mixed in with tab state, focus management, rule
+ * evaluation and RBAC — and the cost of that was not length but ownership: the bug Phase 2
+ * fixed was two methods forty lines apart disagreeing about what "every field" meant.
+ *
+ * Deliberately stateless. Every method takes the form and the config it is operating on, so
+ * there is no cached `this.form` to go stale against a rebuilt one, and every method is
+ * testable without a component or a TestBed.
+ *
+ * Provided at the component, not the root: `FormBuilder` and the validator registry are the
+ * only things injected, but keeping the service per form leaves room for that to change
+ * without turning into shared mutable state.
+ */
+class FormStructureService {
+    fb = inject(FormBuilder);
+    validatorRegistry = inject(ValidatorRegistryService);
+    /**
+     * Build the control tree for a config.
+     *
+     * The tree mirrors the record's shape exactly: a tab opens a `FormGroup` under its id, a
+     * `flatData` tab merges into its parent's, and a `group` field opens one for its children.
+     * That correspondence is what lets a `[path]` ref resolve through `form.get()` and name
+     * exactly one control — see `getControl`.
+     */
+    buildForm(config) {
+        const group = {};
+        const buildTabControls = (tabs, parentGroup) => {
+            for (const tab of tabs) {
+                if (tab.flatData) {
+                    for (const field of tab.fields || []) {
+                        this.buildFieldControl(field, parentGroup);
+                    }
+                    if (tab.children)
+                        buildTabControls(tab.children, parentGroup);
+                }
+                else {
+                    const tabGroup = {};
+                    for (const field of tab.fields || []) {
+                        this.buildFieldControl(field, tabGroup);
+                    }
+                    if (tab.children)
+                        buildTabControls(tab.children, tabGroup);
+                    parentGroup[tab.id] = this.fb.group(tabGroup);
+                }
+            }
+        };
+        buildTabControls(config.tabs || [], group);
+        return this.fb.group(group);
+    }
+    /** One field's control: a nested group, an empty array, or a leaf carrying its validators. */
+    buildFieldControl(field, group) {
+        if (field.type === 'group') {
+            const subGroup = {};
+            for (const child of field.children || []) {
+                this.buildFieldControl(child, subGroup);
+            }
+            group[field.id] = this.fb.group(subGroup);
+        }
+        else if (field.type === 'array') {
+            group[field.id] = this.fb.array([]);
+        }
+        else {
+            const validators = this.validatorRegistry.resolveFromConfig(field.validators);
+            const asyncValidators = this.validatorRegistry.resolveAsyncFromConfig(field.validators);
+            group[field.id] = this.fb.control({ value: field.defaultValue ?? null, disabled: field.disabled ?? false }, validators, asyncValidators);
+        }
+    }
+    /** One row of an `array` field: a FormGroup when the field declares columns, else a bare control. */
+    buildArrayRow(field, item) {
+        if (!field?.children?.length)
+            return this.fb.control(item);
+        const rowGroup = {};
+        for (const child of field.children) {
+            this.buildFieldControl(child, rowGroup);
+        }
+        const group = this.fb.group(rowGroup);
+        if (item && typeof item === 'object')
+            group.patchValue(item);
+        return group;
+    }
+    /** The `FormGroup` a tab's fields live in, honouring `flatData`. */
+    getTabGroup(form, config, tabId) {
+        if (!form)
+            return null;
+        const path = getTabPath(config?.tabs, tabId);
+        if (!path || path.length === 0)
+            return form;
+        let curr = form;
+        for (const p of path) {
+            if (!curr || !(curr instanceof FormGroup))
+                return null;
+            curr = curr.get(p);
+        }
+        return curr instanceof FormGroup ? curr : null;
+    }
+    /**
+     * Find a control by reference: a bracketed path, or a bare field id.
+     *
+     * A bracketed path names exactly one control, because the tree nests exactly as the path
+     * does — so `form.get('work.address.city')` walks straight to it. A bare id is what every
+     * config written before paths existed uses: it is looked for on `currentTabId` first, then
+     * at the root, then by a recursive search whose result is whichever the walk reaches first.
+     * That last branch is the ambiguity refs exist to remove, and callers that can name a path
+     * should.
+     */
+    getControl(form, config, fieldId, currentTabId) {
+        if (!form)
+            return null;
+        const parsed = parseFieldRef(fieldId);
+        if (parsed.kind === 'ref')
+            return form.get(parsed.value);
+        if (currentTabId) {
+            const tabGrp = this.getTabGroup(form, config, currentTabId);
+            const ctrl = tabGrp?.get(fieldId);
+            if (ctrl)
+                return ctrl;
+        }
+        const rootCtrl = form.get(fieldId);
+        if (rootCtrl)
+            return rootCtrl;
+        const findInGroup = (group) => {
+            for (const key of Object.keys(group.controls)) {
+                const c = group.controls[key];
+                if (key === fieldId)
+                    return c;
+                if (c instanceof FormGroup) {
+                    const found = findInGroup(c);
+                    if (found)
+                        return found;
+                }
+            }
+            return null;
+        };
+        return findInGroup(form);
+    }
+    /** Assemble the full nested record from per-tab groups, respecting flatData, refererField & arrays. */
+    extractRecord(form, config) {
+        if (!form || !config)
+            return {};
+        let record = {};
+        const walkTabs = (tabs) => {
+            for (const tab of tabs) {
+                const fieldValBag = {};
+                for (const field of tab.fields || []) {
+                    const ctrl = this.getControl(form, config, field.id, tab.id);
+                    if (ctrl)
+                        fieldValBag[field.id] = ctrl.value;
+                }
+                setTabData(record, tab.id, fieldValBag, config);
+                for (const field of tab.fields || []) {
+                    if (field.refererField) {
+                        const ctrl = this.getControl(form, config, field.id, tab.id);
+                        if (ctrl)
+                            setValueByPath(record, field.refererField, ctrl.value);
+                    }
+                }
+                if (tab.children)
+                    walkTabs(tab.children);
+            }
+        };
+        walkTabs(config.tabs || []);
+        record = normalizeArrayStructures(record, config);
+        return record;
+    }
+    /**
+     * Write a record into the control tree.
+     *
+     * Returns the top-level keys that named a known field and were *not* consumed, so the
+     * caller can say so — see `DynamicFormComponent.warnUnconsumedInitialData`. Reporting
+     * rather than logging keeps the "warn once per form" bookkeeping with the form, and keeps
+     * this service free of console output.
+     */
+    patchForm(form, config, data, fieldsById) {
+        if (!data || !form || !config)
+            return [];
+        const patchedFieldIds = new Set();
+        const walkTabs = (tabs) => {
+            for (const tab of tabs) {
+                const tabData = getTabData(tab.id, data, config);
+                for (const field of tab.fields || []) {
+                    let val = tabData && typeof tabData === 'object' ? tabData[field.id] : undefined;
+                    if (field.refererField) {
+                        const refVal = getValueByPath(data, field.refererField);
+                        if (refVal !== undefined)
+                            val = refVal;
+                    }
+                    if (val === undefined)
+                        continue;
+                    const ctrl = this.getControl(form, config, field.id, tab.id);
+                    if (!ctrl)
+                        continue;
+                    if (ctrl instanceof FormArray && Array.isArray(val)) {
+                        ctrl.clear();
+                        for (const item of val) {
+                            ctrl.push(this.buildArrayRow(fieldsById.get(field.id), item));
+                        }
+                    }
+                    else {
+                        ctrl.patchValue(val, { emitEvent: false });
+                    }
+                    patchedFieldIds.add(field.id);
+                }
+                if (tab.children)
+                    walkTabs(tab.children);
+            }
+        };
+        walkTabs(config.tabs || []);
+        return this.unconsumedKeys(config, data, fieldsById, patchedFieldIds);
+    }
+    /**
+     * Top-level keys that name a field but reached no control.
+     *
+     * 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.
+     *
+     * Only keys matching a known field id count: anything else is the consumer's own record
+     * metadata (ids, timestamps, `_configVersion`) and is not our business.
+     */
+    unconsumedKeys(config, data, fieldsById, patchedFieldIds) {
+        if (!isDevMode())
+            return [];
+        const tabIds = new Set();
+        const collectTabIds = (tabs) => {
+            for (const tab of tabs) {
+                tabIds.add(tab.id);
+                if (tab.children)
+                    collectTabIds(tab.children);
+            }
+        };
+        collectTabIds(config.tabs || []);
+        return Object.keys(data).filter(key => 
+        // A tab id at the root is the nested container, not a stray field.
+        !tabIds.has(key) &&
+            data[key] !== undefined &&
+            fieldsById.has(key) &&
+            !patchedFieldIds.has(key));
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: FormStructureService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: FormStructureService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: FormStructureService, decorators: [{
+            type: Injectable
+        }] });
+
 /**
  * Grid width per field type, used only under `layout="auto"` and only where the field itself
  * names no `colSpan`.
@@ -6350,6 +6856,8 @@ class DynamicFormComponent {
     hookRegistry = inject(HookRegistryService);
     rbacService = inject(RbacService);
     rulesEvaluation = inject(RulesEvaluationService);
+    /** config ⇄ FormGroup: where a value lives. See `FormStructureService`. */
+    structure = inject(FormStructureService);
     /** Resolves what is wrong with a field, for the error summary — see `resolveForField`. */
     messages = inject(ValidationMessagesService);
     entityRefSelection = inject(EntityRefSelectionService);
@@ -6388,12 +6896,29 @@ class DynamicFormComponent {
             // invalid form is what produces the error summary. Guarding here instead meant Ctrl+S
             // on an incomplete form did nothing at all — and unlike the button, a shortcut cannot
             // even look disabled.
+            // `void`, not an `await`: a `@HostListener` cannot be async without changing what
+            // Angular does with its return value, and `submit()` reports its own failures through
+            // `saveRejected`. Nothing here would have anywhere to put a rejection.
             if (!this.readonly && this.canSubmit)
-                this.submit();
+                void this.submit();
         }
     }
     // ─── Computed ─────────────────────────────────────────────────────────────
-    ruleResult = computed(() => this.rulesEvaluation.evaluate(this.rules, this.formValues(), this.baseline()), ...(ngDevMode ? [{ debugName: "ruleResult" }] : /* istanbul ignore next */ []));
+    ruleResult = computed(() => this.rulesEvaluation.evaluate(this.rules, this.formValues(), this.baseline(), {
+        // The engine reports rather than logs, because it also runs on a server. This is the
+        // client's answer: say it once per distinct problem, in dev only. A rule the author
+        // half-finished used to throw out of change detection; now it is skipped, and a
+        // silently skipped rule is exactly as hard to diagnose as a thrown one.
+        onProblem: message => this.warnOnce(message),
+    }), ...(ngDevMode ? [{ debugName: "ruleResult" }] : /* istanbul ignore next */ []));
+    /** Warned-about rule problems, per component instance — see `warnedAmbiguousIds`. */
+    warnedProblems = new Set();
+    warnOnce(message) {
+        if (!isDevMode() || this.warnedProblems.has(message))
+            return;
+        this.warnedProblems.add(message);
+        console.warn(`[ngx-dynamic-entity] ${message}`);
+    }
     /**
      * Critical fields whose value differs from the session baseline.
      * These drive the deferred `VALUE_CHANGED` banner — a critical edit is announced once,
@@ -6410,8 +6935,10 @@ class DynamicFormComponent {
         return this.config?.tabs || [];
     }
     get visibleTabs() {
-        const hidden = this.ruleResult().hiddenTabs;
-        return this.tabs.filter(tab => tab.visibility !== false && !hidden.includes(tab.id));
+        return this.tabs.filter(tab => this.isTabVisible(tab));
+    }
+    isTabVisible(tab) {
+        return this.rulesEvaluation.isTabVisible(this.ruleResult(), tab);
     }
     get activeTabConfig() {
         const tabId = this.activeTab();
@@ -6423,8 +6950,7 @@ class DynamicFormComponent {
         const active = this.activeTabConfig;
         if (!active?.children || active.children.length === 0)
             return [];
-        const hidden = this.ruleResult().hiddenTabs;
-        return active.children.filter(tab => tab.visibility !== false && !hidden.includes(tab.id));
+        return active.children.filter(tab => this.isTabVisible(tab));
     }
     get activeSubTabConfig() {
         const subTabs = this.visibleSubTabs;
@@ -6474,8 +7000,15 @@ class DynamicFormComponent {
             return [];
         const rawFields = active ? active.fields || [] : (this.config?.tabs || []).flatMap(t => t.fields || []);
         const currentValues = this.formValues();
-        const hiddenFields = new Set(this.ruleResult().hiddenFields);
-        return rawFields.filter(field => evaluateFieldVisibility(field, currentValues) && !this.namesField(hiddenFields, field));
+        return rawFields.filter(field => this.isFieldVisible(field, currentValues));
+    }
+    /**
+     * 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.
+     */
+    isFieldVisible(field, values) {
+        return this.rulesEvaluation.isFieldVisible(this.ruleResult(), field, this.namesOf(field), values);
     }
     /**
      * Entity-level permissions for the current roles.
@@ -6701,19 +7234,36 @@ class DynamicFormComponent {
         if (this.invalidFieldsCache)
             return this.invalidFieldsCache;
         const out = [];
-        const collect = (tab, parentId) => {
-            for (const field of tab.fields ?? []) {
-                const control = this.getControl(field.id, tab.id);
-                if (!control || control.disabled || control.valid || control.pending)
-                    continue;
-                // The same message the field renders under itself — see `resolveForField`. Saying
-                // only *which* field is wrong leaves the user to go and look at each one; saying what
-                // is wrong with it is usually enough to fix it without leaving the summary.
-                const message = this.messages.resolveForField(control.errors, this.language, field.type);
-                out.push(parentId
-                    ? { field, message, tabId: parentId, subTabId: tab.id }
-                    : { field, message, tabId: tab.id });
-            }
+        /*
+         * Descends into `group` children rather than stopping at the container.
+         *
+         * A `FormGroup` is invalid whenever any descendant is, so reporting the container said
+         * "Contacts is invalid" and left the user to open it and hunt. The offending leaf is
+         * both the useful answer and the one `jumpToField` can actually move focus to.
+         *
+         * An `array` is reported as itself: its rows are built and destroyed at runtime, so
+         * there is no configured child to name and nothing stable to jump to.
+         */
+        const collectField = (field, tab, parentId) => {
+            const control = this.getControl(field.id, tab.id);
+            if (!control || control.disabled || control.valid || control.pending)
+                return;
+            if (field.type === 'group' && field.children?.length) {
+                for (const child of field.children)
+                    collectField(child, tab, parentId);
+                return;
+            }
+            // The same message the field renders under itself — see `resolveForField`. Saying
+            // only *which* field is wrong leaves the user to go and look at each one; saying what
+            // is wrong with it is usually enough to fix it without leaving the summary.
+            const message = this.messages.resolveForField(control.errors, this.language, field.type);
+            out.push(parentId
+                ? { field, message, tabId: parentId, subTabId: tab.id }
+                : { field, message, tabId: tab.id });
+        };
+        const collect = (tab, parentId) => {
+            for (const field of tab.fields ?? [])
+                collectField(field, tab, parentId);
             for (const child of tab.children ?? [])
                 collect(child, parentId ?? tab.id);
         };
@@ -6765,16 +7315,31 @@ class DynamicFormComponent {
             el.focus();
         }, { injector: this.injector });
     }
+    /**
+     * 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.
+     */
     locateField(fieldId) {
-        for (const tab of this.tabs) {
-            if ((tab.fields ?? []).some(f => f.id === fieldId))
-                return { tabId: tab.id };
-            for (const child of tab.children ?? []) {
-                if ((child.fields ?? []).some(f => f.id === fieldId))
-                    return { tabId: tab.id, subTabId: child.id };
+        const holds = (fields) => (fields ?? []).some(f => f?.id === fieldId || holds(f?.children));
+        const search = (tabs, tabId, subTabId) => {
+            for (const tab of tabs ?? []) {
+                if (!tab?.id)
+                    continue;
+                const at = tabId ?? tab.id;
+                const sub = tabId ? (subTabId ?? tab.id) : undefined;
+                if (holds(tab.fields))
+                    return sub ? { tabId: at, subTabId: sub } : { tabId: at };
+                const found = search(tab.children, at, sub);
+                if (found)
+                    return found;
             }
-        }
-        return null;
+            return null;
+        };
+        return search(this.tabs);
     }
     // ─── criticalField locking ────────────────────────────────────────────────
     /** A critical field stays read-only until the user deliberately unlocks it. */
@@ -6834,29 +7399,9 @@ class DynamicFormComponent {
     buildForm() {
         if (!this.config)
             return;
-        const group = {};
-        const buildTabControls = (tabs, parentGroup) => {
-            for (const tab of tabs) {
-                if (tab.flatData) {
-                    for (const field of tab.fields || []) {
-                        this.buildFieldControl(field, parentGroup);
-                    }
-                    if (tab.children)
-                        buildTabControls(tab.children, parentGroup);
-                }
-                else {
-                    const tabGroup = {};
-                    for (const field of tab.fields || []) {
-                        this.buildFieldControl(field, tabGroup);
-                    }
-                    if (tab.children)
-                        buildTabControls(tab.children, tabGroup);
-                    parentGroup[tab.id] = this.fb.group(tabGroup);
-                }
-            }
-        };
-        buildTabControls(this.config.tabs || [], group);
-        this.form = this.fb.group(group);
+        this.form = this.structure.buildForm(this.config);
+        // A rebuild replaces every control, and the scope index is keyed by config identity.
+        this.scopeCache = undefined;
         this.warnAmbiguousRuleReferences();
         if (this.initialData) {
             this.patchForm(this.upgradeRecord(this.initialData));
@@ -6902,24 +7447,6 @@ class DynamicFormComponent {
             this.formChange.emit(this.extractRecord());
         });
     }
-    buildFieldControl(field, group) {
-        if (field.type === 'group') {
-            const subGroup = {};
-            for (const child of field.children || []) {
-                this.buildFieldControl(child, subGroup);
-            }
-            group[field.id] = this.fb.group(subGroup);
-        }
-        else if (field.type === 'array') {
-            group[field.id] = this.fb.array([]);
-        }
-        else {
-            const validators = this.validatorRegistry.resolveFromConfig(field.validators);
-            const asyncValidators = this.validatorRegistry.resolveAsyncFromConfig(field.validators);
-            group[field.id] = this.fb.control({ value: field.defaultValue ?? null, disabled: field.disabled ?? false }, validators, asyncValidators);
-        }
-    }
-    /** 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.
@@ -6936,16 +7463,7 @@ class DynamicFormComponent {
         return this.buildArrayRow(field, value);
     }
     buildArrayRow(field, item) {
-        if (!field?.children?.length)
-            return this.fb.control(item);
-        const rowGroup = {};
-        for (const child of field.children) {
-            this.buildFieldControl(child, rowGroup);
-        }
-        const group = this.fb.group(rowGroup);
-        if (item && typeof item === 'object')
-            group.patchValue(item);
-        return group;
+        return this.structure.buildArrayRow(field, item);
     }
     /**
      * Mark every control touched, then re-check the field components.
@@ -6978,42 +7496,11 @@ class DynamicFormComponent {
         return result.record;
     }
     patchForm(data) {
-        if (!data || !this.form)
+        if (!data || !this.form || !this.config)
             return;
         const fieldsById = new Map(this.allFields().map(f => [f.id, f]));
-        const patchedFieldIds = new Set();
-        const walkTabs = (tabs) => {
-            for (const tab of tabs) {
-                const tabData = getTabData(tab.id, data, this.config);
-                for (const field of tab.fields || []) {
-                    let val = tabData && typeof tabData === 'object' ? tabData[field.id] : undefined;
-                    if (field.refererField) {
-                        const refVal = getValueByPath(data, field.refererField);
-                        if (refVal !== undefined)
-                            val = refVal;
-                    }
-                    if (val === undefined)
-                        continue;
-                    const ctrl = this.getControl(field.id, tab.id);
-                    if (!ctrl)
-                        continue;
-                    if (ctrl instanceof FormArray && Array.isArray(val)) {
-                        ctrl.clear();
-                        for (const item of val) {
-                            ctrl.push(this.buildArrayRow(fieldsById.get(field.id), item));
-                        }
-                    }
-                    else {
-                        ctrl.patchValue(val, { emitEvent: false });
-                    }
-                    patchedFieldIds.add(field.id);
-                }
-                if (tab.children)
-                    walkTabs(tab.children);
-            }
-        };
-        walkTabs(this.config.tabs || []);
-        this.warnUnconsumedInitialData(data, fieldsById, patchedFieldIds);
+        const unconsumed = this.structure.patchForm(this.form, this.config, data, fieldsById);
+        this.warnUnconsumedInitialData(unconsumed);
     }
     /**
      * A record is nested by tab id (`{ tabId: { fieldId: value } }`) unless the tab sets
@@ -7021,34 +7508,18 @@ class DynamicFormComponent {
      * 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.
      */
-    warnUnconsumedInitialData(data, fieldsById, patchedFieldIds) {
-        if (!isDevMode() || !this.config)
-            return;
-        const tabIds = new Set();
-        const collectTabIds = (tabs) => {
-            for (const tab of tabs) {
-                tabIds.add(tab.id);
-                if (tab.children)
-                    collectTabIds(tab.children);
-            }
-        };
-        collectTabIds(this.config.tabs || []);
-        const unconsumed = Object.keys(data).filter(key => !tabIds.has(key) && // a tab id at the root is the nested container, not a stray field
-            data[key] !== undefined &&
-            fieldsById.has(key) &&
-            !patchedFieldIds.has(key) &&
-            !this.warnedUnconsumedKeys.has(key));
-        if (!unconsumed.length)
+    warnUnconsumedInitialData(keys) {
+        const fresh = keys.filter(key => !this.warnedUnconsumedKeys.has(key));
+        if (!fresh.length)
             return;
-        for (const key of unconsumed)
+        for (const key of fresh)
             this.warnedUnconsumedKeys.add(key);
-        const shown = unconsumed.slice(0, 5).join(', ');
-        const more = unconsumed.length > 5 ? ` (+${unconsumed.length - 5} more)` : '';
-        const plural = unconsumed.length === 1;
+        const shown = fresh.slice(0, 5).join(', ');
+        const more = fresh.length > 5 ? ` (+${fresh.length - 5} more)` : '';
+        const plural = fresh.length === 1;
         console.warn(`[ngx-dynamic-entity] initialData has top-level ${plural ? 'key' : 'keys'} matching ` +
             `${plural ? 'a field that was' : 'fields that were'} not populated: ${shown}${more}. ` +
             `A record is nested by tab id ({ tabId: { fieldId: value } }) unless the tab sets ` +
@@ -7059,34 +7530,7 @@ class DynamicFormComponent {
     warnedUnconsumedKeys = new Set();
     /** Assemble full nested record from per-tab FormGroups, respecting flatData, refererField & arrays. */
     extractRecord() {
-        if (!this.form || !this.config)
-            return {};
-        let record = {};
-        const walkTabs = (tabs) => {
-            for (const tab of tabs) {
-                const fieldValBag = {};
-                for (const field of tab.fields || []) {
-                    const ctrl = this.getControl(field.id, tab.id);
-                    if (ctrl) {
-                        fieldValBag[field.id] = ctrl.value;
-                    }
-                }
-                setTabData(record, tab.id, fieldValBag, this.config);
-                for (const field of tab.fields || []) {
-                    if (field.refererField) {
-                        const ctrl = this.getControl(field.id, tab.id);
-                        if (ctrl) {
-                            setValueByPath(record, field.refererField, ctrl.value);
-                        }
-                    }
-                }
-                if (tab.children)
-                    walkTabs(tab.children);
-            }
-        };
-        walkTabs(this.config.tabs || []);
-        record = normalizeArrayStructures(record, this.config);
-        return record;
+        return this.structure.extractRecord(this.form, this.config);
     }
     /**
      * Warns when a rule names a field id that two scopes define.
@@ -7124,15 +7568,24 @@ class DynamicFormComponent {
                 continue;
             const id = parsed.value;
             const scopes = ambiguous.get(id);
-            if (!scopes || DynamicFormComponent.warnedAmbiguousIds.has(id))
+            if (!scopes || this.warnedAmbiguousIds.has(id))
                 continue;
-            DynamicFormComponent.warnedAmbiguousIds.add(id);
+            this.warnedAmbiguousIds.add(id);
             console.warn(`[ngx-dynamic-entity] A rule references field "${id}", which is defined in ${scopes.join(' and ')}. ` +
                 `A bare id cannot say which one is meant, so the rule will read whichever the form finds first. ` +
                 `Name it by path instead, as [${scopes[0]}.${id}].`);
         }
     }
-    static warnedAmbiguousIds = new Set();
+    /**
+     * 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.
+     */
+    warnedAmbiguousIds = new Set();
     /**
      * The value map rules and `showWhen` are evaluated against.
      *
@@ -7146,23 +7599,75 @@ class DynamicFormComponent {
      * 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.
      */
-    namesField(names, field) {
-        if (names.has(field.id))
-            return true;
-        const ref = field.refererField ?? this.pathFor(field);
-        return ref ? names.has(toRefToken(ref)) : false;
+    namesOf(field) {
+        const path = field.refererField ?? this.pathFor(field);
+        return path ? [field.id, toRefToken(path)] : [field.id];
+    }
+    /**
+     * 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.
+     */
+    addressOf(field) {
+        return this.pathFor(field) ?? field.id;
     }
     /** The field's declared path, or the one its position implies when it carries none. */
     pathFor(field) {
-        const entry = collectFieldScopes(this.config).find(e => e.field === field);
+        const entry = this.scopeEntryFor(field);
         return entry ? fieldRefFor(entry.scope, field.id) : null;
     }
+    /**
+     * 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.
+     */
+    fieldScopes() {
+        if (this.scopeCache?.config !== this.config) {
+            const entries = collectFieldScopes(this.config);
+            this.scopeCache = {
+                config: this.config,
+                entries,
+                byField: new Map(entries.map(entry => [entry.field, entry])),
+            };
+        }
+        return this.scopeCache.entries;
+    }
+    scopeEntryFor(field) {
+        this.fieldScopes();
+        return this.scopeCache?.byField.get(field);
+    }
+    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.
+     */
+    controlForEntry(entry) {
+        return this.getControl(toRefToken(fieldRefFor(entry.scope, entry.field.id)));
+    }
     flattenFormValues() {
         const out = {};
         for (const entry of collectFieldScopes(this.config)) {
@@ -7177,18 +7682,6 @@ class DynamicFormComponent {
         }
         return out;
     }
-    getTabGroup(tabId) {
-        const path = getTabPath(this.config?.tabs, tabId);
-        if (!path || path.length === 0)
-            return this.form;
-        let curr = this.form;
-        for (const p of path) {
-            if (!curr || !(curr instanceof FormGroup))
-                return null;
-            curr = curr.get(p);
-        }
-        return curr instanceof FormGroup ? curr : null;
-    }
     // ─── autoPatch / patchOnTrue ──────────────────────────────────────────────
     /**
      * `autoPatch` — copy mapped fields out of the record the user just selected in an
@@ -7230,65 +7723,48 @@ class DynamicFormComponent {
             }
         }
     }
-    /** Prefer a control declared on the configured target tab; fall back to a top-level control. */
+    /**
+     * 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.
+     */
     resolveTargetControl(autoPatch, targetId) {
         const tab = findTab(this.tabs, autoPatch.targetTab);
-        const inTargetTab = (tab?.fields ?? []).some(f => f.id === targetId);
-        if (tab && !inTargetTab)
+        if (!tab)
+            return this.getControl(targetId, autoPatch.targetTab);
+        const entry = fieldsUnderTab(this.config, autoPatch.targetTab).find(e => {
+            if (!e.field?.id)
+                return false;
+            const parsed = parseFieldRef(targetId);
+            return parsed.kind === 'ref'
+                ? fieldRefFor(e.scope, e.field.id) === parsed.value
+                : e.field.id === parsed.value;
+        });
+        if (!entry)
             return null;
-        return this.getControl(targetId, autoPatch.targetTab);
+        return this.controlForEntry(entry);
     }
     // ─── Helpers ──────────────────────────────────────────────────────────────
     /**
-     * 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.
-     */
-    tabFields() {
-        const out = [];
-        const walk = (tabs) => {
-            for (const tab of tabs ?? []) {
-                out.push(...(tab.fields ?? []));
-                walk(tab.children);
-            }
-        };
-        walk(this.config?.tabs);
-        return out;
-    }
-    /**
-     * 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.
+     * Keep a hidden field's control out of form validity — see
+     * `RulesEvaluationService.syncHiddenFieldState`, which owns the rule and the reasoning.
      *
-     * 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.
+     * 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.
      */
     syncHiddenFieldState(values) {
         if (this.preview)
             return; // preview freezes the whole form on purpose
-        const hiddenByRule = new Set(this.ruleResult().hiddenFields);
-        for (const field of this.tabFields()) {
-            const ctrl = this.getControl(field.id);
-            if (!ctrl)
-                continue;
-            const hidden = this.namesField(hiddenByRule, field) || !evaluateFieldVisibility(field, values);
-            if (hidden) {
-                if (ctrl.enabled)
-                    ctrl.disable({ emitEvent: false });
-            }
-            else if (ctrl.disabled && !field.disabled) {
-                ctrl.enable({ emitEvent: false });
-            }
-        }
+        this.rulesEvaluation.syncHiddenFieldState(this.fieldScopes(), {
+            result: this.ruleResult(),
+            values,
+            namesOf: field => this.namesOf(field),
+            addressOf: field => this.addressOf(field),
+            controlFor: entry => this.controlForEntry(entry),
+        });
     }
     /** Every field in the config, including `group`/`array` children. */
     allFields() {
@@ -7316,51 +7792,31 @@ class DynamicFormComponent {
             return supplied;
         return this.sessionBaseline();
     }
+    /**
+     * 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.
+     */
     sameValue(a, b) {
-        if (a === b)
-            return true;
         const aEmpty = a === null || a === undefined || a === '';
         const bEmpty = b === null || b === undefined || b === '';
         if (aEmpty && bEmpty)
             return true;
-        if (typeof a === 'object' || typeof b === 'object') {
-            return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
-        }
-        return false;
+        return valuesEqual(a, b);
     }
+    /**
+     * 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, currentTabId) {
-        if (!this.form)
-            return null;
-        // A bracketed path names exactly one control, and the form nests by tab exactly as the
-        // path does — so `form.get('work.address')` walks straight to it. Anything that names a
-        // field can therefore use a path: `showWhen` keys, `patchOnTrue` mappings and `autoPatch`
-        // targets, not only rules.
-        const parsed = parseFieldRef(fieldId);
-        if (parsed.kind === 'ref')
-            return this.form.get(parsed.value);
-        if (currentTabId) {
-            const tabGrp = this.getTabGroup(currentTabId);
-            const ctrl = tabGrp?.get(fieldId);
-            if (ctrl)
-                return ctrl;
-        }
-        const rootCtrl = this.form.get(fieldId);
-        if (rootCtrl)
-            return rootCtrl;
-        const findInGroup = (group) => {
-            for (const key of Object.keys(group.controls)) {
-                const c = group.controls[key];
-                if (key === fieldId)
-                    return c;
-                if (c instanceof FormGroup) {
-                    const found = findInGroup(c);
-                    if (found)
-                        return found;
-                }
-            }
-            return null;
-        };
-        return findInGroup(this.form);
+        return this.structure.getControl(this.form, this.config, fieldId, currentTabId);
     }
     /**
      * Move focus into the newly shown panel.
@@ -7460,11 +7916,11 @@ class DynamicFormComponent {
         this.formReset.emit();
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: DynamicFormComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: DynamicFormComponent, isStandalone: true, selector: "ngx-dynamic-form", inputs: { config: "config", rules: "rules", initialData: "initialData", originalData: "originalData", userRoles: "userRoles", language: "language", readonly: "readonly", readOnlyFields: "readOnlyFields", showInfoBanners: "showInfoBanners", loading: "loading", error: "error", changeDebounceMs: "changeDebounceMs", preview: "preview", layout: "layout" }, outputs: { formSubmit: "formSubmit", formChange: "formChange", formReset: "formReset", activeTabChange: "activeTabChange", saveRejected: "saveRejected" }, host: { listeners: { "window:keydown": "handleKeyboardEvent($event)" } }, providers: [EntityRefSelectionService], viewQueries: [{ propertyName: "formPanel", first: true, predicate: ["formPanel"], descendants: true }, { propertyName: "fieldHosts", predicate: DynamicFieldComponent, descendants: true }], usesOnChanges: true, ngImport: i0, template: "@if (canView) {\n  <form [formGroup]=\"form\" (ngSubmit)=\"submit()\" class=\"ngx-form\" [class.ngx-form--readonly]=\"readonly\" novalidate>\n    <!-- Error message banner -->\n    @if (error) {\n      <div class=\"ngx-form__error-banner\" role=\"alert\" data-testid=\"form-error\">{{ error }}</div>\n    }\n\n    <!--\n      Why the last Save did nothing.\n      Only after a refused submit \u2014 see `submitAttempted`. Each entry jumps to its field,\n      switching tabs on the way, because the field is usually not the one on screen.\n    -->\n    @if (submitAttempted() && invalidFields().length > 0) {\n      <div class=\"ngx-form__error-summary\" role=\"alert\" data-testid=\"error-summary\" tabindex=\"-1\">\n        <!--\n          `error-summary-heading`, not `-title`: the links below are `error-summary-<fieldId>`,\n          and a field whose id happens to be `title` would then share a test id with this line.\n          The `extensions` entity has exactly such a field.\n        -->\n        <p class=\"ngx-form__error-summary-title\" data-testid=\"error-summary-heading\">\n          {{ ui.text('errorSummaryTitle', language, { count: invalidFields().length }) }}\n        </p>\n        <ul class=\"ngx-form__error-summary-list\">\n          @for (entry of invalidFields(); track entry.field.id) {\n            <li>\n              <!--\n                The field, and what is wrong with it \u2014 the same sentence the field renders\n                under itself, so the summary is not a second opinion. Naming only the field\n                left the user to visit each one to find out what it wanted.\n              -->\n              <button\n                type=\"button\"\n                class=\"ngx-form__error-summary-link\"\n                [attr.data-testid]=\"'error-summary-' + entry.field.id\"\n                (click)=\"jumpToField(entry.field.id)\"\n              >\n                <span class=\"ngx-form__error-summary-field\">{{ resolveFieldLabel(entry.field) }}</span>\n                @if (entry.message) {\n                  <span class=\"ngx-form__error-summary-reason\">{{ entry.message }}</span>\n                }\n              </button>\n            </li>\n          }\n        </ul>\n      </div>\n    }\n\n    <!-- Rules Info Banners -->\n    @for (infoKey of showInfoBanners ? Object.keys(ruleResult().infoBanners) : []; track infoKey) {\n      <div class=\"ngx-form__info-banner\" role=\"status\" [attr.data-testid]=\"'info-banner-' + infoKey\">\n        \u2139\uFE0F {{ ruleResult().infoBanners[infoKey] }}\n      </div>\n    }\n\n    <!-- Rules Validation Errors & Warnings -->\n    @for (errKey of Object.keys(ruleResult().validationErrors); track errKey) {\n      <div class=\"ngx-form__error-banner\" role=\"alert\" [attr.data-testid]=\"'rule-error-' + errKey\">\n        \u26A0\uFE0F {{ ruleResult().validationErrors[errKey] }}\n      </div>\n    }\n    @for (warnKey of Object.keys(ruleResult().validationWarnings); track warnKey) {\n      <div class=\"ngx-form__warning-banner\" role=\"status\" [attr.data-testid]=\"'rule-warning-' + warnKey\">\n        \u26A1 {{ ruleResult().validationWarnings[warnKey] }}\n      </div>\n    }\n\n    <!-- Deferred VALUE_CHANGED notice for criticalField edits (vs session baseline) -->\n    @if (changedCriticalFields().length > 0) {\n      <div class=\"ngx-form__warning-banner\" role=\"status\" data-testid=\"critical-change-banner\">\n        {{ ui.text('criticalFieldChanged', language, { fields: changedCriticalFieldLabels() }) }}\n      </div>\n    }\n\n    <!-- Primary Tab bar \u2014 only if visible tabs defined -->\n    @if (visibleTabs.length > 0) {\n      <div class=\"ngx-form__tabs\" role=\"tablist\" data-testid=\"tab-strip\">\n        @for (tab of visibleTabs; track tab.id) {\n          <button\n            type=\"button\"\n            class=\"ngx-form__tab\"\n            [attr.data-testid]=\"'tab-' + tab.id\"\n            [class.ngx-form__tab--active]=\"activeTab() === tab.id\"\n            (click)=\"setActiveTab(tab.id)\"\n            role=\"tab\"\n            [attr.aria-selected]=\"activeTab() === tab.id\"\n          >\n            {{ resolveTabLabel(tab) }}\n            <!--\n              How many fields on this tab are stopping the save.\n              The count is in the accessible name rather than the badge, because \"3\" read out\n              after a tab name says nothing about what it counts.\n            -->\n            @if (tabErrorCount(tab); as errors) {\n              <span\n                class=\"ngx-form__tab-badge\"\n                [attr.data-testid]=\"'tab-errors-' + tab.id\"\n                [attr.aria-label]=\"ui.text('tabErrorCount', language, { count: errors })\"\n                >{{ errors }}</span\n              >\n            }\n          </button>\n        }\n      </div>\n    }\n\n    <!-- Sub-tab bar \u2014 only if active tab has sub-tabs -->\n    @if (visibleSubTabs.length > 0) {\n      <div\n        class=\"ngx-form__tabs ngx-form__tabs--sub\"\n        role=\"tablist\"\n        data-testid=\"subtab-strip\"\n        style=\"margin-top: -12px; margin-bottom: 12px; font-size: 13px\"\n      >\n        @for (subTab of visibleSubTabs; track subTab.id) {\n          <button\n            type=\"button\"\n            class=\"ngx-form__tab ngx-form__tab--sub\"\n            [attr.data-testid]=\"'subtab-' + subTab.id\"\n            [class.ngx-form__tab--active]=\"activeSubTabConfig?.id === subTab.id\"\n            (click)=\"setActiveSubTab(subTab.id)\"\n            role=\"tab\"\n            [attr.aria-selected]=\"activeSubTabConfig?.id === subTab.id\"\n          >\n            {{ resolveTabLabel(subTab) }}\n            @if (subTabErrorCount(subTab); as errors) {\n              <span\n                class=\"ngx-form__tab-badge\"\n                [attr.data-testid]=\"'subtab-errors-' + subTab.id\"\n                [attr.aria-label]=\"ui.text('tabErrorCount', language, { count: errors })\"\n                >{{ errors }}</span\n              >\n            }\n          </button>\n        }\n      </div>\n    }\n\n    <!--\n      One tabpanel per tab, wrapping both branches. Focus moves here on a tab switch, and a\n      module tab is still a tab \u2014 putting the panel semantics on only the fields branch left\n      a module tab with nowhere for focus to land.\n    -->\n    <div role=\"tabpanel\" tabindex=\"-1\" #formPanel class=\"ngx-form__tabpanel\" [attr.aria-label]=\"activeTabLabel\">\n      @if (activeTabModuleComponent) {\n        <div class=\"ngx-form__module-panel\" data-testid=\"module-panel\">\n          <ng-container\n            *ngComponentOutlet=\"activeTabModuleComponent; inputs: (activeSubTabConfig || activeTabConfig)?.moduleInputs\"\n          ></ng-container>\n        </div>\n      } @else {\n        <!-- Fields for active tab (Responsive 12-column grid) -->\n        <div class=\"ngx-form__panel\" data-testid=\"form-panel\">\n          @for (field of fieldsForActiveTab; track field.id) {\n            <div\n              class=\"ngx-form__field-slot\"\n              [style.gridColumn]=\"getFieldSpan(field)\"\n              [attr.id]=\"'field-container-' + field.id\"\n              tabindex=\"-1\"\n            >\n              <ngx-dynamic-field\n                [field]=\"field\"\n                [control]=\"getControl(field.id, (activeSubTabConfig || activeTabConfig)?.id)!\"\n                [config]=\"config\"\n                [currentTabId]=\"(activeSubTabConfig || activeTabConfig)?.id\"\n                [language]=\"language\"\n                [readonly]=\"isFieldReadonly(field)\"\n                [userRoles]=\"userRoles\"\n              />\n              @if (field.hasDrift) {\n                <!--\n                Drift was previously visible only in the builder, so a referenced field whose\n                source had changed looked completely normal to the person filling the form in.\n                role=\"status\" rather than \"alert\": it is information, not an error.\n              -->\n                <span\n                  class=\"ngx-field__drift\"\n                  role=\"status\"\n                  [attr.data-testid]=\"'field-' + field.id + '-drift'\"\n                  [title]=\"driftHint(field)\"\n                  >\u26A0 {{ driftHint(field) }}</span\n                >\n              }\n              @if (field.criticalField && !readonly) {\n                <button\n                  type=\"button\"\n                  class=\"ngx-form__lock\"\n                  [attr.data-testid]=\"'lock-' + field.id\"\n                  [attr.aria-pressed]=\"!isFieldLocked(field)\"\n                  [attr.aria-label]=\"\n                    ui.text(isFieldLocked(field) ? 'unlockField' : 'lockField', language, {\n                      field: resolveFieldLabel(field),\n                    })\n                  \"\n                  [title]=\"ui.text(isFieldLocked(field) ? 'criticalFieldUnlockHint' : 'criticalFieldLockHint', language)\"\n                  (click)=\"toggleFieldLock(field)\"\n                >\n                  {{ isFieldLocked(field) ? '\uD83D\uDD12' : '\uD83D\uDD13' }}\n                </button>\n              }\n            </div>\n          }\n        </div>\n      }\n    </div>\n\n    <!-- Submit button \u2014 gated by RBAC and isSaving lock -->\n    @if (!readonly && permissions.canEdit) {\n      <div class=\"ngx-form__actions\" data-testid=\"form-actions\">\n        <button type=\"button\" class=\"ngx-form__reset\" data-testid=\"form-reset\" (click)=\"reset()\" [disabled]=\"isSaving()\">\n          {{ ui.text('reset', language) }}\n        </button>\n        <!--\n          Two different \"unavailable\" states, and they are not the same thing.\n\n          `disabled` is for what a retry cannot fix \u2014 a save in flight, an async check still\n          outstanding. `data-blocked` is for validation: the button stays fully operable,\n          because pressing it is how the user gets the error summary, but it should not look\n          ready either. The stylesheet mutes it without taking the click away.\n\n          Deliberately not `aria-disabled`. That announces a control as present-but-inoperable,\n          and this one is operable and useful \u2014 pressing it raises a `role=\"alert\"` naming\n          every field at fault, which is more than a disabled button could ever say. Tooling\n          agrees: Playwright refuses to click through `aria-disabled`, and it would be right\n          to, because the attribute would be claiming something untrue.\n        -->\n        <button\n          type=\"submit\"\n          class=\"ngx-form__submit\"\n          data-testid=\"form-submit\"\n          [disabled]=\"submitDisabled\"\n          [attr.data-blocked]=\"submitBlocked ? '' : null\"\n          [title]=\"ui.text('saveShortcutHint', language)\"\n        >\n          @if (isSaving() || loading) {\n            {{ ui.text('saving', language) }}\n          } @else {\n            {{ ui.text('save', language) }}\n          }\n        </button>\n      </div>\n    }\n  </form>\n} @else {\n  <!-- permissions.view denied: render nothing of the record.\n       Presentational only \u2014 the server must not send data this user may not see. -->\n  <div class=\"ngx-form__denied\" role=\"status\" data-testid=\"form-access-denied\">\n    {{ ui.text('accessDenied', language) }}\n  </div>\n}\n", styles: [".ngx-form__panel{display:grid;grid-template-columns:repeat(12,minmax(0,1fr));gap:var(--ngx-gap, 18px);align-items:start}.ngx-form--readonly .ngx-form__panel{grid-template-columns:repeat(auto-fit,minmax(230px,1fr));gap:2px var(--ngx-gap, 18px)}.ngx-form--readonly .ngx-form__field-slot{grid-column:auto}.ngx-form__field-slot{display:flex;align-items:flex-start;gap:6px;min-width:0}.ngx-form__field-slot ngx-dynamic-field{flex:1;min-width:0}.ngx-form__lock{flex:0 0 auto;margin-top:22px;background:none;border:1px solid transparent;border-radius:var(--ngx-radius-sm, 6px);cursor:pointer;font-size:14px;line-height:1;padding:4px 6px}.ngx-form__lock:hover{border-color:var(--ngx-color-border, #d1d5db);background:var(--ngx-color-surface-alt, #f9fafb)}@media(max-width:640px){.ngx-form__panel,.ngx-form--readonly .ngx-form__panel{grid-template-columns:minmax(0,1fr)}.ngx-form__field-slot{grid-column:1 / -1!important}}\n"], dependencies: [{ kind: "ngmodule", type: ReactiveFormsModule }, { kind: "directive", type: i1.ɵNgNoValidate, selector: "form:not([ngNoForm]):not([ngNativeValidate])" }, { kind: "directive", type: i1.NgControlStatusGroup, selector: "[formGroupName],[formArrayName],[ngModelGroup],[formGroup],[formArray],form:not([ngNoForm]),[ngForm]" }, { kind: "directive", type: i1.FormGroupDirective, selector: "[formGroup]", inputs: ["formGroup"], outputs: ["ngSubmit"], exportAs: ["ngForm"] }, { kind: "component", type: DynamicFieldComponent, selector: "ngx-dynamic-field", inputs: ["field", "control", "config", "currentTabId", "language", "readonly", "userRoles"] }, { kind: "directive", type: NgComponentOutlet, selector: "[ngComponentOutlet]", inputs: ["ngComponentOutlet", "ngComponentOutletInputs", "ngComponentOutletInjector", "ngComponentOutletEnvironmentInjector", "ngComponentOutletContent", "ngComponentOutletNgModule"], exportAs: ["ngComponentOutlet"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: DynamicFormComponent, isStandalone: true, selector: "ngx-dynamic-form", inputs: { config: "config", rules: "rules", initialData: "initialData", originalData: "originalData", userRoles: "userRoles", language: "language", readonly: "readonly", readOnlyFields: "readOnlyFields", showInfoBanners: "showInfoBanners", loading: "loading", error: "error", changeDebounceMs: "changeDebounceMs", preview: "preview", layout: "layout" }, outputs: { formSubmit: "formSubmit", formChange: "formChange", formReset: "formReset", activeTabChange: "activeTabChange", saveRejected: "saveRejected" }, host: { listeners: { "window:keydown": "handleKeyboardEvent($event)" } }, providers: [EntityRefSelectionService, FormStructureService], viewQueries: [{ propertyName: "formPanel", first: true, predicate: ["formPanel"], descendants: true }, { propertyName: "fieldHosts", predicate: DynamicFieldComponent, descendants: true }], usesOnChanges: true, ngImport: i0, template: "@if (canView) {\n  <form [formGroup]=\"form\" (ngSubmit)=\"submit()\" class=\"ngx-form\" [class.ngx-form--readonly]=\"readonly\" novalidate>\n    <!-- Error message banner -->\n    @if (error) {\n      <div class=\"ngx-form__error-banner\" role=\"alert\" data-testid=\"form-error\">{{ error }}</div>\n    }\n\n    <!--\n      Why the last Save did nothing.\n      Only after a refused submit \u2014 see `submitAttempted`. Each entry jumps to its field,\n      switching tabs on the way, because the field is usually not the one on screen.\n    -->\n    @if (submitAttempted() && invalidFields().length > 0) {\n      <div class=\"ngx-form__error-summary\" role=\"alert\" data-testid=\"error-summary\" tabindex=\"-1\">\n        <!--\n          `error-summary-heading`, not `-title`: the links below are `error-summary-<fieldId>`,\n          and a field whose id happens to be `title` would then share a test id with this line.\n          The `extensions` entity has exactly such a field.\n        -->\n        <p class=\"ngx-form__error-summary-title\" data-testid=\"error-summary-heading\">\n          {{ ui.text('errorSummaryTitle', language, { count: invalidFields().length }) }}\n        </p>\n        <ul class=\"ngx-form__error-summary-list\">\n          @for (entry of invalidFields(); track entry.field.id) {\n            <li>\n              <!--\n                The field, and what is wrong with it \u2014 the same sentence the field renders\n                under itself, so the summary is not a second opinion. Naming only the field\n                left the user to visit each one to find out what it wanted.\n              -->\n              <button\n                type=\"button\"\n                class=\"ngx-form__error-summary-link\"\n                [attr.data-testid]=\"'error-summary-' + entry.field.id\"\n                (click)=\"jumpToField(entry.field.id)\"\n              >\n                <span class=\"ngx-form__error-summary-field\">{{ resolveFieldLabel(entry.field) }}</span>\n                @if (entry.message) {\n                  <span class=\"ngx-form__error-summary-reason\">{{ entry.message }}</span>\n                }\n              </button>\n            </li>\n          }\n        </ul>\n      </div>\n    }\n\n    <!-- Rules Info Banners -->\n    @for (infoKey of showInfoBanners ? Object.keys(ruleResult().infoBanners) : []; track infoKey) {\n      <div class=\"ngx-form__info-banner\" role=\"status\" [attr.data-testid]=\"'info-banner-' + infoKey\">\n        \u2139\uFE0F {{ ruleResult().infoBanners[infoKey] }}\n      </div>\n    }\n\n    <!-- Rules Validation Errors & Warnings -->\n    @for (errKey of Object.keys(ruleResult().validationErrors); track errKey) {\n      <div class=\"ngx-form__error-banner\" role=\"alert\" [attr.data-testid]=\"'rule-error-' + errKey\">\n        \u26A0\uFE0F {{ ruleResult().validationErrors[errKey] }}\n      </div>\n    }\n    @for (warnKey of Object.keys(ruleResult().validationWarnings); track warnKey) {\n      <div class=\"ngx-form__warning-banner\" role=\"status\" [attr.data-testid]=\"'rule-warning-' + warnKey\">\n        \u26A1 {{ ruleResult().validationWarnings[warnKey] }}\n      </div>\n    }\n\n    <!-- Deferred VALUE_CHANGED notice for criticalField edits (vs session baseline) -->\n    @if (changedCriticalFields().length > 0) {\n      <div class=\"ngx-form__warning-banner\" role=\"status\" data-testid=\"critical-change-banner\">\n        {{ ui.text('criticalFieldChanged', language, { fields: changedCriticalFieldLabels() }) }}\n      </div>\n    }\n\n    <!-- Primary Tab bar \u2014 only if visible tabs defined -->\n    @if (visibleTabs.length > 0) {\n      <div class=\"ngx-form__tabs\" role=\"tablist\" data-testid=\"tab-strip\">\n        @for (tab of visibleTabs; track tab.id) {\n          <button\n            type=\"button\"\n            class=\"ngx-form__tab\"\n            [attr.data-testid]=\"'tab-' + tab.id\"\n            [class.ngx-form__tab--active]=\"activeTab() === tab.id\"\n            (click)=\"setActiveTab(tab.id)\"\n            role=\"tab\"\n            [attr.aria-selected]=\"activeTab() === tab.id\"\n          >\n            {{ resolveTabLabel(tab) }}\n            <!--\n              How many fields on this tab are stopping the save.\n              The count is in the accessible name rather than the badge, because \"3\" read out\n              after a tab name says nothing about what it counts.\n            -->\n            @if (tabErrorCount(tab); as errors) {\n              <span\n                class=\"ngx-form__tab-badge\"\n                [attr.data-testid]=\"'tab-errors-' + tab.id\"\n                [attr.aria-label]=\"ui.text('tabErrorCount', language, { count: errors })\"\n                >{{ errors }}</span\n              >\n            }\n          </button>\n        }\n      </div>\n    }\n\n    <!-- Sub-tab bar \u2014 only if active tab has sub-tabs -->\n    @if (visibleSubTabs.length > 0) {\n      <div\n        class=\"ngx-form__tabs ngx-form__tabs--sub\"\n        role=\"tablist\"\n        data-testid=\"subtab-strip\"\n        style=\"margin-top: -12px; margin-bottom: 12px; font-size: 13px\"\n      >\n        @for (subTab of visibleSubTabs; track subTab.id) {\n          <button\n            type=\"button\"\n            class=\"ngx-form__tab ngx-form__tab--sub\"\n            [attr.data-testid]=\"'subtab-' + subTab.id\"\n            [class.ngx-form__tab--active]=\"activeSubTabConfig?.id === subTab.id\"\n            (click)=\"setActiveSubTab(subTab.id)\"\n            role=\"tab\"\n            [attr.aria-selected]=\"activeSubTabConfig?.id === subTab.id\"\n          >\n            {{ resolveTabLabel(subTab) }}\n            @if (subTabErrorCount(subTab); as errors) {\n              <span\n                class=\"ngx-form__tab-badge\"\n                [attr.data-testid]=\"'subtab-errors-' + subTab.id\"\n                [attr.aria-label]=\"ui.text('tabErrorCount', language, { count: errors })\"\n                >{{ errors }}</span\n              >\n            }\n          </button>\n        }\n      </div>\n    }\n\n    <!--\n      One tabpanel per tab, wrapping both branches. Focus moves here on a tab switch, and a\n      module tab is still a tab \u2014 putting the panel semantics on only the fields branch left\n      a module tab with nowhere for focus to land.\n    -->\n    <div role=\"tabpanel\" tabindex=\"-1\" #formPanel class=\"ngx-form__tabpanel\" [attr.aria-label]=\"activeTabLabel\">\n      @if (activeTabModuleComponent) {\n        <div class=\"ngx-form__module-panel\" data-testid=\"module-panel\">\n          <ng-container\n            *ngComponentOutlet=\"activeTabModuleComponent; inputs: (activeSubTabConfig || activeTabConfig)?.moduleInputs\"\n          ></ng-container>\n        </div>\n      } @else {\n        <!-- Fields for active tab (Responsive 12-column grid) -->\n        <div class=\"ngx-form__panel\" data-testid=\"form-panel\">\n          @for (field of fieldsForActiveTab; track field.id) {\n            <div\n              class=\"ngx-form__field-slot\"\n              [style.gridColumn]=\"getFieldSpan(field)\"\n              [attr.id]=\"'field-container-' + field.id\"\n              tabindex=\"-1\"\n            >\n              <ngx-dynamic-field\n                [field]=\"field\"\n                [control]=\"getControl(field.id, (activeSubTabConfig || activeTabConfig)?.id)!\"\n                [config]=\"config\"\n                [currentTabId]=\"(activeSubTabConfig || activeTabConfig)?.id\"\n                [language]=\"language\"\n                [readonly]=\"isFieldReadonly(field)\"\n                [userRoles]=\"userRoles\"\n              />\n              @if (field.hasDrift) {\n                <!--\n                Drift was previously visible only in the builder, so a referenced field whose\n                source had changed looked completely normal to the person filling the form in.\n                role=\"status\" rather than \"alert\": it is information, not an error.\n              -->\n                <span\n                  class=\"ngx-field__drift\"\n                  role=\"status\"\n                  [attr.data-testid]=\"'field-' + field.id + '-drift'\"\n                  [title]=\"driftHint(field)\"\n                  >\u26A0 {{ driftHint(field) }}</span\n                >\n              }\n              @if (field.criticalField && !readonly) {\n                <button\n                  type=\"button\"\n                  class=\"ngx-form__lock\"\n                  [attr.data-testid]=\"'lock-' + field.id\"\n                  [attr.aria-pressed]=\"!isFieldLocked(field)\"\n                  [attr.aria-label]=\"\n                    ui.text(isFieldLocked(field) ? 'unlockField' : 'lockField', language, {\n                      field: resolveFieldLabel(field),\n                    })\n                  \"\n                  [title]=\"ui.text(isFieldLocked(field) ? 'criticalFieldUnlockHint' : 'criticalFieldLockHint', language)\"\n                  (click)=\"toggleFieldLock(field)\"\n                >\n                  {{ isFieldLocked(field) ? '\uD83D\uDD12' : '\uD83D\uDD13' }}\n                </button>\n              }\n            </div>\n          }\n        </div>\n      }\n    </div>\n\n    <!-- Submit button \u2014 gated by RBAC and isSaving lock -->\n    @if (!readonly && permissions.canEdit) {\n      <div class=\"ngx-form__actions\" data-testid=\"form-actions\">\n        <button type=\"button\" class=\"ngx-form__reset\" data-testid=\"form-reset\" (click)=\"reset()\" [disabled]=\"isSaving()\">\n          {{ ui.text('reset', language) }}\n        </button>\n        <!--\n          Two different \"unavailable\" states, and they are not the same thing.\n\n          `disabled` is for what a retry cannot fix \u2014 a save in flight, an async check still\n          outstanding. `data-blocked` is for validation: the button stays fully operable,\n          because pressing it is how the user gets the error summary, but it should not look\n          ready either. The stylesheet mutes it without taking the click away.\n\n          Deliberately not `aria-disabled`. That announces a control as present-but-inoperable,\n          and this one is operable and useful \u2014 pressing it raises a `role=\"alert\"` naming\n          every field at fault, which is more than a disabled button could ever say. Tooling\n          agrees: Playwright refuses to click through `aria-disabled`, and it would be right\n          to, because the attribute would be claiming something untrue.\n        -->\n        <button\n          type=\"submit\"\n          class=\"ngx-form__submit\"\n          data-testid=\"form-submit\"\n          [disabled]=\"submitDisabled\"\n          [attr.data-blocked]=\"submitBlocked ? '' : null\"\n          [title]=\"ui.text('saveShortcutHint', language)\"\n        >\n          @if (isSaving() || loading) {\n            {{ ui.text('saving', language) }}\n          } @else {\n            {{ ui.text('save', language) }}\n          }\n        </button>\n      </div>\n    }\n  </form>\n} @else {\n  <!-- permissions.view denied: render nothing of the record.\n       Presentational only \u2014 the server must not send data this user may not see. -->\n  <div class=\"ngx-form__denied\" role=\"status\" data-testid=\"form-access-denied\">\n    {{ ui.text('accessDenied', language) }}\n  </div>\n}\n", styles: [".ngx-form__panel{display:grid;grid-template-columns:repeat(12,minmax(0,1fr));gap:var(--ngx-gap, 18px);align-items:start}.ngx-form--readonly .ngx-form__panel{grid-template-columns:repeat(auto-fit,minmax(230px,1fr));gap:2px var(--ngx-gap, 18px)}.ngx-form--readonly .ngx-form__field-slot{grid-column:auto}.ngx-form__field-slot{display:flex;align-items:flex-start;gap:6px;min-width:0}.ngx-form__field-slot ngx-dynamic-field{flex:1;min-width:0}.ngx-form__lock{flex:0 0 auto;margin-top:22px;background:none;border:1px solid transparent;border-radius:var(--ngx-radius-sm, 6px);cursor:pointer;font-size:14px;line-height:1;padding:4px 6px}.ngx-form__lock:hover{border-color:var(--ngx-color-border, #d1d5db);background:var(--ngx-color-surface-alt, #f9fafb)}@media(max-width:640px){.ngx-form__panel,.ngx-form--readonly .ngx-form__panel{grid-template-columns:minmax(0,1fr)}.ngx-form__field-slot{grid-column:1 / -1!important}}\n"], dependencies: [{ kind: "ngmodule", type: ReactiveFormsModule }, { kind: "directive", type: i1.ɵNgNoValidate, selector: "form:not([ngNoForm]):not([ngNativeValidate])" }, { kind: "directive", type: i1.NgControlStatusGroup, selector: "[formGroupName],[formArrayName],[ngModelGroup],[formGroup],[formArray],form:not([ngNoForm]),[ngForm]" }, { kind: "directive", type: i1.FormGroupDirective, selector: "[formGroup]", inputs: ["formGroup"], outputs: ["ngSubmit"], exportAs: ["ngForm"] }, { kind: "component", type: DynamicFieldComponent, selector: "ngx-dynamic-field", inputs: ["field", "control", "config", "currentTabId", "language", "readonly", "userRoles"] }, { kind: "directive", type: NgComponentOutlet, selector: "[ngComponentOutlet]", inputs: ["ngComponentOutlet", "ngComponentOutletInputs", "ngComponentOutletInjector", "ngComponentOutletEnvironmentInjector", "ngComponentOutletContent", "ngComponentOutletNgModule"], exportAs: ["ngComponentOutlet"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: DynamicFormComponent, decorators: [{
             type: Component,
-            args: [{ changeDetection: ChangeDetectionStrategy.OnPush, selector: 'ngx-dynamic-form', standalone: true, imports: [ReactiveFormsModule, DynamicFieldComponent, NgComponentOutlet], providers: [EntityRefSelectionService], template: "@if (canView) {\n  <form [formGroup]=\"form\" (ngSubmit)=\"submit()\" class=\"ngx-form\" [class.ngx-form--readonly]=\"readonly\" novalidate>\n    <!-- Error message banner -->\n    @if (error) {\n      <div class=\"ngx-form__error-banner\" role=\"alert\" data-testid=\"form-error\">{{ error }}</div>\n    }\n\n    <!--\n      Why the last Save did nothing.\n      Only after a refused submit \u2014 see `submitAttempted`. Each entry jumps to its field,\n      switching tabs on the way, because the field is usually not the one on screen.\n    -->\n    @if (submitAttempted() && invalidFields().length > 0) {\n      <div class=\"ngx-form__error-summary\" role=\"alert\" data-testid=\"error-summary\" tabindex=\"-1\">\n        <!--\n          `error-summary-heading`, not `-title`: the links below are `error-summary-<fieldId>`,\n          and a field whose id happens to be `title` would then share a test id with this line.\n          The `extensions` entity has exactly such a field.\n        -->\n        <p class=\"ngx-form__error-summary-title\" data-testid=\"error-summary-heading\">\n          {{ ui.text('errorSummaryTitle', language, { count: invalidFields().length }) }}\n        </p>\n        <ul class=\"ngx-form__error-summary-list\">\n          @for (entry of invalidFields(); track entry.field.id) {\n            <li>\n              <!--\n                The field, and what is wrong with it \u2014 the same sentence the field renders\n                under itself, so the summary is not a second opinion. Naming only the field\n                left the user to visit each one to find out what it wanted.\n              -->\n              <button\n                type=\"button\"\n                class=\"ngx-form__error-summary-link\"\n                [attr.data-testid]=\"'error-summary-' + entry.field.id\"\n                (click)=\"jumpToField(entry.field.id)\"\n              >\n                <span class=\"ngx-form__error-summary-field\">{{ resolveFieldLabel(entry.field) }}</span>\n                @if (entry.message) {\n                  <span class=\"ngx-form__error-summary-reason\">{{ entry.message }}</span>\n                }\n              </button>\n            </li>\n          }\n        </ul>\n      </div>\n    }\n\n    <!-- Rules Info Banners -->\n    @for (infoKey of showInfoBanners ? Object.keys(ruleResult().infoBanners) : []; track infoKey) {\n      <div class=\"ngx-form__info-banner\" role=\"status\" [attr.data-testid]=\"'info-banner-' + infoKey\">\n        \u2139\uFE0F {{ ruleResult().infoBanners[infoKey] }}\n      </div>\n    }\n\n    <!-- Rules Validation Errors & Warnings -->\n    @for (errKey of Object.keys(ruleResult().validationErrors); track errKey) {\n      <div class=\"ngx-form__error-banner\" role=\"alert\" [attr.data-testid]=\"'rule-error-' + errKey\">\n        \u26A0\uFE0F {{ ruleResult().validationErrors[errKey] }}\n      </div>\n    }\n    @for (warnKey of Object.keys(ruleResult().validationWarnings); track warnKey) {\n      <div class=\"ngx-form__warning-banner\" role=\"status\" [attr.data-testid]=\"'rule-warning-' + warnKey\">\n        \u26A1 {{ ruleResult().validationWarnings[warnKey] }}\n      </div>\n    }\n\n    <!-- Deferred VALUE_CHANGED notice for criticalField edits (vs session baseline) -->\n    @if (changedCriticalFields().length > 0) {\n      <div class=\"ngx-form__warning-banner\" role=\"status\" data-testid=\"critical-change-banner\">\n        {{ ui.text('criticalFieldChanged', language, { fields: changedCriticalFieldLabels() }) }}\n      </div>\n    }\n\n    <!-- Primary Tab bar \u2014 only if visible tabs defined -->\n    @if (visibleTabs.length > 0) {\n      <div class=\"ngx-form__tabs\" role=\"tablist\" data-testid=\"tab-strip\">\n        @for (tab of visibleTabs; track tab.id) {\n          <button\n            type=\"button\"\n            class=\"ngx-form__tab\"\n            [attr.data-testid]=\"'tab-' + tab.id\"\n            [class.ngx-form__tab--active]=\"activeTab() === tab.id\"\n            (click)=\"setActiveTab(tab.id)\"\n            role=\"tab\"\n            [attr.aria-selected]=\"activeTab() === tab.id\"\n          >\n            {{ resolveTabLabel(tab) }}\n            <!--\n              How many fields on this tab are stopping the save.\n              The count is in the accessible name rather than the badge, because \"3\" read out\n              after a tab name says nothing about what it counts.\n            -->\n            @if (tabErrorCount(tab); as errors) {\n              <span\n                class=\"ngx-form__tab-badge\"\n                [attr.data-testid]=\"'tab-errors-' + tab.id\"\n                [attr.aria-label]=\"ui.text('tabErrorCount', language, { count: errors })\"\n                >{{ errors }}</span\n              >\n            }\n          </button>\n        }\n      </div>\n    }\n\n    <!-- Sub-tab bar \u2014 only if active tab has sub-tabs -->\n    @if (visibleSubTabs.length > 0) {\n      <div\n        class=\"ngx-form__tabs ngx-form__tabs--sub\"\n        role=\"tablist\"\n        data-testid=\"subtab-strip\"\n        style=\"margin-top: -12px; margin-bottom: 12px; font-size: 13px\"\n      >\n        @for (subTab of visibleSubTabs; track subTab.id) {\n          <button\n            type=\"button\"\n            class=\"ngx-form__tab ngx-form__tab--sub\"\n            [attr.data-testid]=\"'subtab-' + subTab.id\"\n            [class.ngx-form__tab--active]=\"activeSubTabConfig?.id === subTab.id\"\n            (click)=\"setActiveSubTab(subTab.id)\"\n            role=\"tab\"\n            [attr.aria-selected]=\"activeSubTabConfig?.id === subTab.id\"\n          >\n            {{ resolveTabLabel(subTab) }}\n            @if (subTabErrorCount(subTab); as errors) {\n              <span\n                class=\"ngx-form__tab-badge\"\n                [attr.data-testid]=\"'subtab-errors-' + subTab.id\"\n                [attr.aria-label]=\"ui.text('tabErrorCount', language, { count: errors })\"\n                >{{ errors }}</span\n              >\n            }\n          </button>\n        }\n      </div>\n    }\n\n    <!--\n      One tabpanel per tab, wrapping both branches. Focus moves here on a tab switch, and a\n      module tab is still a tab \u2014 putting the panel semantics on only the fields branch left\n      a module tab with nowhere for focus to land.\n    -->\n    <div role=\"tabpanel\" tabindex=\"-1\" #formPanel class=\"ngx-form__tabpanel\" [attr.aria-label]=\"activeTabLabel\">\n      @if (activeTabModuleComponent) {\n        <div class=\"ngx-form__module-panel\" data-testid=\"module-panel\">\n          <ng-container\n            *ngComponentOutlet=\"activeTabModuleComponent; inputs: (activeSubTabConfig || activeTabConfig)?.moduleInputs\"\n          ></ng-container>\n        </div>\n      } @else {\n        <!-- Fields for active tab (Responsive 12-column grid) -->\n        <div class=\"ngx-form__panel\" data-testid=\"form-panel\">\n          @for (field of fieldsForActiveTab; track field.id) {\n            <div\n              class=\"ngx-form__field-slot\"\n              [style.gridColumn]=\"getFieldSpan(field)\"\n              [attr.id]=\"'field-container-' + field.id\"\n              tabindex=\"-1\"\n            >\n              <ngx-dynamic-field\n                [field]=\"field\"\n                [control]=\"getControl(field.id, (activeSubTabConfig || activeTabConfig)?.id)!\"\n                [config]=\"config\"\n                [currentTabId]=\"(activeSubTabConfig || activeTabConfig)?.id\"\n                [language]=\"language\"\n                [readonly]=\"isFieldReadonly(field)\"\n                [userRoles]=\"userRoles\"\n              />\n              @if (field.hasDrift) {\n                <!--\n                Drift was previously visible only in the builder, so a referenced field whose\n                source had changed looked completely normal to the person filling the form in.\n                role=\"status\" rather than \"alert\": it is information, not an error.\n              -->\n                <span\n                  class=\"ngx-field__drift\"\n                  role=\"status\"\n                  [attr.data-testid]=\"'field-' + field.id + '-drift'\"\n                  [title]=\"driftHint(field)\"\n                  >\u26A0 {{ driftHint(field) }}</span\n                >\n              }\n              @if (field.criticalField && !readonly) {\n                <button\n                  type=\"button\"\n                  class=\"ngx-form__lock\"\n                  [attr.data-testid]=\"'lock-' + field.id\"\n                  [attr.aria-pressed]=\"!isFieldLocked(field)\"\n                  [attr.aria-label]=\"\n                    ui.text(isFieldLocked(field) ? 'unlockField' : 'lockField', language, {\n                      field: resolveFieldLabel(field),\n                    })\n                  \"\n                  [title]=\"ui.text(isFieldLocked(field) ? 'criticalFieldUnlockHint' : 'criticalFieldLockHint', language)\"\n                  (click)=\"toggleFieldLock(field)\"\n                >\n                  {{ isFieldLocked(field) ? '\uD83D\uDD12' : '\uD83D\uDD13' }}\n                </button>\n              }\n            </div>\n          }\n        </div>\n      }\n    </div>\n\n    <!-- Submit button \u2014 gated by RBAC and isSaving lock -->\n    @if (!readonly && permissions.canEdit) {\n      <div class=\"ngx-form__actions\" data-testid=\"form-actions\">\n        <button type=\"button\" class=\"ngx-form__reset\" data-testid=\"form-reset\" (click)=\"reset()\" [disabled]=\"isSaving()\">\n          {{ ui.text('reset', language) }}\n        </button>\n        <!--\n          Two different \"unavailable\" states, and they are not the same thing.\n\n          `disabled` is for what a retry cannot fix \u2014 a save in flight, an async check still\n          outstanding. `data-blocked` is for validation: the button stays fully operable,\n          because pressing it is how the user gets the error summary, but it should not look\n          ready either. The stylesheet mutes it without taking the click away.\n\n          Deliberately not `aria-disabled`. That announces a control as present-but-inoperable,\n          and this one is operable and useful \u2014 pressing it raises a `role=\"alert\"` naming\n          every field at fault, which is more than a disabled button could ever say. Tooling\n          agrees: Playwright refuses to click through `aria-disabled`, and it would be right\n          to, because the attribute would be claiming something untrue.\n        -->\n        <button\n          type=\"submit\"\n          class=\"ngx-form__submit\"\n          data-testid=\"form-submit\"\n          [disabled]=\"submitDisabled\"\n          [attr.data-blocked]=\"submitBlocked ? '' : null\"\n          [title]=\"ui.text('saveShortcutHint', language)\"\n        >\n          @if (isSaving() || loading) {\n            {{ ui.text('saving', language) }}\n          } @else {\n            {{ ui.text('save', language) }}\n          }\n        </button>\n      </div>\n    }\n  </form>\n} @else {\n  <!-- permissions.view denied: render nothing of the record.\n       Presentational only \u2014 the server must not send data this user may not see. -->\n  <div class=\"ngx-form__denied\" role=\"status\" data-testid=\"form-access-denied\">\n    {{ ui.text('accessDenied', language) }}\n  </div>\n}\n", styles: [".ngx-form__panel{display:grid;grid-template-columns:repeat(12,minmax(0,1fr));gap:var(--ngx-gap, 18px);align-items:start}.ngx-form--readonly .ngx-form__panel{grid-template-columns:repeat(auto-fit,minmax(230px,1fr));gap:2px var(--ngx-gap, 18px)}.ngx-form--readonly .ngx-form__field-slot{grid-column:auto}.ngx-form__field-slot{display:flex;align-items:flex-start;gap:6px;min-width:0}.ngx-form__field-slot ngx-dynamic-field{flex:1;min-width:0}.ngx-form__lock{flex:0 0 auto;margin-top:22px;background:none;border:1px solid transparent;border-radius:var(--ngx-radius-sm, 6px);cursor:pointer;font-size:14px;line-height:1;padding:4px 6px}.ngx-form__lock:hover{border-color:var(--ngx-color-border, #d1d5db);background:var(--ngx-color-surface-alt, #f9fafb)}@media(max-width:640px){.ngx-form__panel,.ngx-form--readonly .ngx-form__panel{grid-template-columns:minmax(0,1fr)}.ngx-form__field-slot{grid-column:1 / -1!important}}\n"] }]
+            args: [{ changeDetection: ChangeDetectionStrategy.OnPush, selector: 'ngx-dynamic-form', standalone: true, imports: [ReactiveFormsModule, DynamicFieldComponent, NgComponentOutlet], providers: [EntityRefSelectionService, FormStructureService], template: "@if (canView) {\n  <form [formGroup]=\"form\" (ngSubmit)=\"submit()\" class=\"ngx-form\" [class.ngx-form--readonly]=\"readonly\" novalidate>\n    <!-- Error message banner -->\n    @if (error) {\n      <div class=\"ngx-form__error-banner\" role=\"alert\" data-testid=\"form-error\">{{ error }}</div>\n    }\n\n    <!--\n      Why the last Save did nothing.\n      Only after a refused submit \u2014 see `submitAttempted`. Each entry jumps to its field,\n      switching tabs on the way, because the field is usually not the one on screen.\n    -->\n    @if (submitAttempted() && invalidFields().length > 0) {\n      <div class=\"ngx-form__error-summary\" role=\"alert\" data-testid=\"error-summary\" tabindex=\"-1\">\n        <!--\n          `error-summary-heading`, not `-title`: the links below are `error-summary-<fieldId>`,\n          and a field whose id happens to be `title` would then share a test id with this line.\n          The `extensions` entity has exactly such a field.\n        -->\n        <p class=\"ngx-form__error-summary-title\" data-testid=\"error-summary-heading\">\n          {{ ui.text('errorSummaryTitle', language, { count: invalidFields().length }) }}\n        </p>\n        <ul class=\"ngx-form__error-summary-list\">\n          @for (entry of invalidFields(); track entry.field.id) {\n            <li>\n              <!--\n                The field, and what is wrong with it \u2014 the same sentence the field renders\n                under itself, so the summary is not a second opinion. Naming only the field\n                left the user to visit each one to find out what it wanted.\n              -->\n              <button\n                type=\"button\"\n                class=\"ngx-form__error-summary-link\"\n                [attr.data-testid]=\"'error-summary-' + entry.field.id\"\n                (click)=\"jumpToField(entry.field.id)\"\n              >\n                <span class=\"ngx-form__error-summary-field\">{{ resolveFieldLabel(entry.field) }}</span>\n                @if (entry.message) {\n                  <span class=\"ngx-form__error-summary-reason\">{{ entry.message }}</span>\n                }\n              </button>\n            </li>\n          }\n        </ul>\n      </div>\n    }\n\n    <!-- Rules Info Banners -->\n    @for (infoKey of showInfoBanners ? Object.keys(ruleResult().infoBanners) : []; track infoKey) {\n      <div class=\"ngx-form__info-banner\" role=\"status\" [attr.data-testid]=\"'info-banner-' + infoKey\">\n        \u2139\uFE0F {{ ruleResult().infoBanners[infoKey] }}\n      </div>\n    }\n\n    <!-- Rules Validation Errors & Warnings -->\n    @for (errKey of Object.keys(ruleResult().validationErrors); track errKey) {\n      <div class=\"ngx-form__error-banner\" role=\"alert\" [attr.data-testid]=\"'rule-error-' + errKey\">\n        \u26A0\uFE0F {{ ruleResult().validationErrors[errKey] }}\n      </div>\n    }\n    @for (warnKey of Object.keys(ruleResult().validationWarnings); track warnKey) {\n      <div class=\"ngx-form__warning-banner\" role=\"status\" [attr.data-testid]=\"'rule-warning-' + warnKey\">\n        \u26A1 {{ ruleResult().validationWarnings[warnKey] }}\n      </div>\n    }\n\n    <!-- Deferred VALUE_CHANGED notice for criticalField edits (vs session baseline) -->\n    @if (changedCriticalFields().length > 0) {\n      <div class=\"ngx-form__warning-banner\" role=\"status\" data-testid=\"critical-change-banner\">\n        {{ ui.text('criticalFieldChanged', language, { fields: changedCriticalFieldLabels() }) }}\n      </div>\n    }\n\n    <!-- Primary Tab bar \u2014 only if visible tabs defined -->\n    @if (visibleTabs.length > 0) {\n      <div class=\"ngx-form__tabs\" role=\"tablist\" data-testid=\"tab-strip\">\n        @for (tab of visibleTabs; track tab.id) {\n          <button\n            type=\"button\"\n            class=\"ngx-form__tab\"\n            [attr.data-testid]=\"'tab-' + tab.id\"\n            [class.ngx-form__tab--active]=\"activeTab() === tab.id\"\n            (click)=\"setActiveTab(tab.id)\"\n            role=\"tab\"\n            [attr.aria-selected]=\"activeTab() === tab.id\"\n          >\n            {{ resolveTabLabel(tab) }}\n            <!--\n              How many fields on this tab are stopping the save.\n              The count is in the accessible name rather than the badge, because \"3\" read out\n              after a tab name says nothing about what it counts.\n            -->\n            @if (tabErrorCount(tab); as errors) {\n              <span\n                class=\"ngx-form__tab-badge\"\n                [attr.data-testid]=\"'tab-errors-' + tab.id\"\n                [attr.aria-label]=\"ui.text('tabErrorCount', language, { count: errors })\"\n                >{{ errors }}</span\n              >\n            }\n          </button>\n        }\n      </div>\n    }\n\n    <!-- Sub-tab bar \u2014 only if active tab has sub-tabs -->\n    @if (visibleSubTabs.length > 0) {\n      <div\n        class=\"ngx-form__tabs ngx-form__tabs--sub\"\n        role=\"tablist\"\n        data-testid=\"subtab-strip\"\n        style=\"margin-top: -12px; margin-bottom: 12px; font-size: 13px\"\n      >\n        @for (subTab of visibleSubTabs; track subTab.id) {\n          <button\n            type=\"button\"\n            class=\"ngx-form__tab ngx-form__tab--sub\"\n            [attr.data-testid]=\"'subtab-' + subTab.id\"\n            [class.ngx-form__tab--active]=\"activeSubTabConfig?.id === subTab.id\"\n            (click)=\"setActiveSubTab(subTab.id)\"\n            role=\"tab\"\n            [attr.aria-selected]=\"activeSubTabConfig?.id === subTab.id\"\n          >\n            {{ resolveTabLabel(subTab) }}\n            @if (subTabErrorCount(subTab); as errors) {\n              <span\n                class=\"ngx-form__tab-badge\"\n                [attr.data-testid]=\"'subtab-errors-' + subTab.id\"\n                [attr.aria-label]=\"ui.text('tabErrorCount', language, { count: errors })\"\n                >{{ errors }}</span\n              >\n            }\n          </button>\n        }\n      </div>\n    }\n\n    <!--\n      One tabpanel per tab, wrapping both branches. Focus moves here on a tab switch, and a\n      module tab is still a tab \u2014 putting the panel semantics on only the fields branch left\n      a module tab with nowhere for focus to land.\n    -->\n    <div role=\"tabpanel\" tabindex=\"-1\" #formPanel class=\"ngx-form__tabpanel\" [attr.aria-label]=\"activeTabLabel\">\n      @if (activeTabModuleComponent) {\n        <div class=\"ngx-form__module-panel\" data-testid=\"module-panel\">\n          <ng-container\n            *ngComponentOutlet=\"activeTabModuleComponent; inputs: (activeSubTabConfig || activeTabConfig)?.moduleInputs\"\n          ></ng-container>\n        </div>\n      } @else {\n        <!-- Fields for active tab (Responsive 12-column grid) -->\n        <div class=\"ngx-form__panel\" data-testid=\"form-panel\">\n          @for (field of fieldsForActiveTab; track field.id) {\n            <div\n              class=\"ngx-form__field-slot\"\n              [style.gridColumn]=\"getFieldSpan(field)\"\n              [attr.id]=\"'field-container-' + field.id\"\n              tabindex=\"-1\"\n            >\n              <ngx-dynamic-field\n                [field]=\"field\"\n                [control]=\"getControl(field.id, (activeSubTabConfig || activeTabConfig)?.id)!\"\n                [config]=\"config\"\n                [currentTabId]=\"(activeSubTabConfig || activeTabConfig)?.id\"\n                [language]=\"language\"\n                [readonly]=\"isFieldReadonly(field)\"\n                [userRoles]=\"userRoles\"\n              />\n              @if (field.hasDrift) {\n                <!--\n                Drift was previously visible only in the builder, so a referenced field whose\n                source had changed looked completely normal to the person filling the form in.\n                role=\"status\" rather than \"alert\": it is information, not an error.\n              -->\n                <span\n                  class=\"ngx-field__drift\"\n                  role=\"status\"\n                  [attr.data-testid]=\"'field-' + field.id + '-drift'\"\n                  [title]=\"driftHint(field)\"\n                  >\u26A0 {{ driftHint(field) }}</span\n                >\n              }\n              @if (field.criticalField && !readonly) {\n                <button\n                  type=\"button\"\n                  class=\"ngx-form__lock\"\n                  [attr.data-testid]=\"'lock-' + field.id\"\n                  [attr.aria-pressed]=\"!isFieldLocked(field)\"\n                  [attr.aria-label]=\"\n                    ui.text(isFieldLocked(field) ? 'unlockField' : 'lockField', language, {\n                      field: resolveFieldLabel(field),\n                    })\n                  \"\n                  [title]=\"ui.text(isFieldLocked(field) ? 'criticalFieldUnlockHint' : 'criticalFieldLockHint', language)\"\n                  (click)=\"toggleFieldLock(field)\"\n                >\n                  {{ isFieldLocked(field) ? '\uD83D\uDD12' : '\uD83D\uDD13' }}\n                </button>\n              }\n            </div>\n          }\n        </div>\n      }\n    </div>\n\n    <!-- Submit button \u2014 gated by RBAC and isSaving lock -->\n    @if (!readonly && permissions.canEdit) {\n      <div class=\"ngx-form__actions\" data-testid=\"form-actions\">\n        <button type=\"button\" class=\"ngx-form__reset\" data-testid=\"form-reset\" (click)=\"reset()\" [disabled]=\"isSaving()\">\n          {{ ui.text('reset', language) }}\n        </button>\n        <!--\n          Two different \"unavailable\" states, and they are not the same thing.\n\n          `disabled` is for what a retry cannot fix \u2014 a save in flight, an async check still\n          outstanding. `data-blocked` is for validation: the button stays fully operable,\n          because pressing it is how the user gets the error summary, but it should not look\n          ready either. The stylesheet mutes it without taking the click away.\n\n          Deliberately not `aria-disabled`. That announces a control as present-but-inoperable,\n          and this one is operable and useful \u2014 pressing it raises a `role=\"alert\"` naming\n          every field at fault, which is more than a disabled button could ever say. Tooling\n          agrees: Playwright refuses to click through `aria-disabled`, and it would be right\n          to, because the attribute would be claiming something untrue.\n        -->\n        <button\n          type=\"submit\"\n          class=\"ngx-form__submit\"\n          data-testid=\"form-submit\"\n          [disabled]=\"submitDisabled\"\n          [attr.data-blocked]=\"submitBlocked ? '' : null\"\n          [title]=\"ui.text('saveShortcutHint', language)\"\n        >\n          @if (isSaving() || loading) {\n            {{ ui.text('saving', language) }}\n          } @else {\n            {{ ui.text('save', language) }}\n          }\n        </button>\n      </div>\n    }\n  </form>\n} @else {\n  <!-- permissions.view denied: render nothing of the record.\n       Presentational only \u2014 the server must not send data this user may not see. -->\n  <div class=\"ngx-form__denied\" role=\"status\" data-testid=\"form-access-denied\">\n    {{ ui.text('accessDenied', language) }}\n  </div>\n}\n", styles: [".ngx-form__panel{display:grid;grid-template-columns:repeat(12,minmax(0,1fr));gap:var(--ngx-gap, 18px);align-items:start}.ngx-form--readonly .ngx-form__panel{grid-template-columns:repeat(auto-fit,minmax(230px,1fr));gap:2px var(--ngx-gap, 18px)}.ngx-form--readonly .ngx-form__field-slot{grid-column:auto}.ngx-form__field-slot{display:flex;align-items:flex-start;gap:6px;min-width:0}.ngx-form__field-slot ngx-dynamic-field{flex:1;min-width:0}.ngx-form__lock{flex:0 0 auto;margin-top:22px;background:none;border:1px solid transparent;border-radius:var(--ngx-radius-sm, 6px);cursor:pointer;font-size:14px;line-height:1;padding:4px 6px}.ngx-form__lock:hover{border-color:var(--ngx-color-border, #d1d5db);background:var(--ngx-color-surface-alt, #f9fafb)}@media(max-width:640px){.ngx-form__panel,.ngx-form--readonly .ngx-form__panel{grid-template-columns:minmax(0,1fr)}.ngx-form__field-slot{grid-column:1 / -1!important}}\n"] }]
         }], propDecorators: { config: [{
                 type: Input
             }], rules: [{
@@ -8127,11 +8583,1476 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImpo
                 args: [DynamicFormComponent]
             }] } });
 
+/**
+ * import-contracts.ts — the two seams the import wizard hangs on.
+ *
+ * Both follow the pattern the rest of this package already uses for anything the library
+ * cannot decide for a consumer — `FileUploadHandler`, `EntityReferenceLoader`,
+ * `LookupListLoader`: a function type here, a token to register it against, and a default
+ * that works without registering anything.
+ *
+ * **Why two rather than one.** Reading a file and deciding where the work happens are
+ * different questions with different answers. A consumer may want `.xlsx` support in a
+ * wizard that still runs entirely in the browser, or plain CSV that is nonetheless processed
+ * on a server because their files have fifty thousand rows. Collapsing them into one option
+ * would make each answer imply the other.
+ */
+
+/**
+ * sheet-parser.ts — the built-in CSV reader, and the reason it is the only one.
+ *
+ * CSV is what every spreadsheet tool exports and what a text editor can produce, and
+ * `@dynamic-entity/core` parses it with no dependency. Shipping that as the default means the
+ * import wizard works on a fresh `npm install` with nothing registered — `SHEET_PARSER` then
+ * exists for the consumer who *also* wants `.xlsx`, rather than for the consumer who wants
+ * the feature to work at all.
+ *
+ * The alternative was a hard dependency on a spreadsheet library in a package that currently
+ * has none, for a file format many consumers will never see.
+ */
+/** Extensions the built-in parser will attempt. */
+const TEXT_EXTENSIONS = /\.(csv|tsv|txt)$/i;
+/**
+ * Read a text file as CSV.
+ *
+ * A binary workbook is refused by name rather than attempted: `.xlsx` is a zip, so reading it
+ * as text yields a header row of mojibake and a mapping screen full of nonsense, which is a
+ * much harder thing to diagnose than being told the format is not supported.
+ */
+const defaultSheetParser = async (file) => {
+    if (file?.name && !TEXT_EXTENSIONS.test(file.name)) {
+        throw new Error(`Cannot read "${file.name}". The built-in parser handles CSV only — register a ` +
+            'sheetParser with provideNgxDynamicEntity({ sheetParser }) to accept other formats.');
+    }
+    return parseCsv(await file.text());
+};
+
+/**
+ * local-import-transport.ts — the whole import, in the browser, with no server.
+ *
+ * This is the default `IMPORT_TRANSPORT`, and it is a thin arrangement of pure functions
+ * from `@dynamic-entity/core` rather than an implementation of anything. That matters: a
+ * consumer who later registers a server transport is not switching to a second set of
+ * mapping rules, they are moving the same ones to a different machine.
+ *
+ * Its limit is the one every browser has — the file is read into memory whole. That is fine
+ * for the sizes a person assembles by hand and wrong for a fifty-thousand-row export, which
+ * is what a streaming server transport is for.
+ */
+/** How many rows the mapping screen shows under each column. */
+const SAMPLE_ROWS = 5;
+class LocalImportTransport {
+    registered = inject(SHEET_PARSER, { optional: true });
+    /**
+     * One parse per file, not one per call.
+     *
+     * A wizard run reads the same file twice — once to show its headers, once to import it —
+     * and this is the transport whose stated limit is that it holds the file in memory. Doing
+     * the work twice doubled both the parse and the peak memory of the one implementation that
+     * can least afford it.
+     *
+     * A `WeakMap` keyed on the `File` itself: the entry lives exactly as long as something
+     * still holds the file, so choosing a different file drops the old sheet without anything
+     * having to remember to. Keying on a name or a size would collide between two files a user
+     * picked in sequence.
+     */
+    parsed = new WeakMap();
+    /** The registered parser, or the built-in CSV one. */
+    read(file) {
+        const cached = this.parsed.get(file);
+        if (cached)
+            return cached;
+        // The *promise* is cached, not its result, so two calls that overlap share one parse
+        // rather than starting a second before the first resolves.
+        const pending = Promise.resolve((this.registered ?? defaultSheetParser)(file));
+        this.parsed.set(file, pending);
+        // A failed parse must not be remembered: the user may fix the file and pick it again.
+        pending.catch(() => this.parsed.delete(file));
+        return pending;
+    }
+    async preview(file, context) {
+        const sheet = await this.read(file);
+        const { columns } = deriveImportColumns(context.config, { lang: context.lang });
+        return {
+            headers: sheet.headers,
+            sample: sheet.rows.slice(0, SAMPLE_ROWS),
+            rowCount: sheet.rows.length,
+            suggestion: suggestMapping(sheet.headers, columns, context.config?.entity ?? ''),
+        };
+    }
+    async commit(file, plan, context) {
+        const sheet = await this.read(file);
+        return applyMapping(sheet.rows, plan, context.config, {
+            lang: context.lang,
+            rules: context.rules,
+            lookups: context.lookups,
+        });
+    }
+    async template(spec, format) {
+        if (format === 'xlsx') {
+            // Deliberately not a silent fallback to CSV. A file named `.xlsx` that is really CSV
+            // opens with a warning in Excel and imports wrongly elsewhere, and the consumer would
+            // have no idea why — where this message says exactly which seam to fill.
+            throw new Error('This build can only write CSV templates. Register an IMPORT_TRANSPORT that writes ' +
+                'xlsx — see provideNgxDynamicEntity({ importTransport }) — or request csv.');
+        }
+        // Headers only, and `spec.notes` deliberately left out of the file.
+        //
+        // A guidance row under the headers reads well and breaks the round trip: CSV has one
+        // header row and no concept of a second, so re-importing the template the user filled in
+        // would treat the guidance as a record and report a failed row 2 on every single import.
+        // The notes are shown beside each column in the picker instead, where they can be read
+        // without being parsed. A format with somewhere to put them — an xlsx cell comment, a
+        // second sheet — can carry them; CSV has nowhere that is not data.
+        const csv = toCsv(spec.columns.map(column => column.header));
+        return new Blob([csv], { type: 'text/csv;charset=utf-8' });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: LocalImportTransport, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: LocalImportTransport, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: LocalImportTransport, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * http-import-transport.ts — the same wizard, with the work happening on a server.
+ *
+ * The components do not change at all: they already talk to an `ImportTransport`, which was
+ * the point of the seam. Registering this one moves the mapping, coercion and validation from
+ * the tab to a server that runs the *same* `@dynamic-entity/core` functions — so the reason to
+ * do it is size, not behaviour.
+ *
+ * **Built on `fetch`, not `HttpClient`.** This package has no `@angular/common/http` dependency
+ * today, and four requests is not the reason to acquire one — a consumer who wants interceptors
+ * passes their own `fetch`, which is a smaller seam than a dependency.
+ */
+/** `Content-Type` is deliberately not settable: `fetch` must set the multipart boundary. */
+function resolveHeaders(options) {
+    const headers = typeof options.headers === 'function' ? options.headers() : options.headers ?? {};
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (name.toLowerCase() === 'content-type')
+            continue;
+        out[name] = value;
+    }
+    return out;
+}
+const trimSlash = (url) => String(url ?? '').replace(/\/+$/, '');
+/** Same major and minor. Two engines a patch apart are the same engine. */
+function sameLine(a, b) {
+    const line = (version) => version.split('.').slice(0, 2).join('.');
+    return line(a) === line(b);
+}
+/**
+ * Turn a failed response into an `Error` the wizard can show.
+ *
+ * The server's envelope carries a code and a message it wrote itself; anything else — a proxy's
+ * HTML error page, a network failure — has no message worth showing, so a status line is what
+ * the user gets rather than a page of markup.
+ */
+async function failureOf(response) {
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        /* not our envelope */
+    }
+    const message = body?.error?.message;
+    return new Error(message || `The import server answered ${response.status}.`);
+}
+/**
+ * The field selection, as short as it can be said without changing what it means.
+ *
+ * Two reductions, and both are exact rather than approximate:
+ *
+ * - **Row numbers come off.** `buildTemplateSpec` matches a column by its ref *or* by its ref
+ *   with indices stripped, and the picker that produced this selection worked in stripped refs
+ *   to begin with — so `contacts.0.email, contacts.1.email, contacts.2.email` is the expansion
+ *   of one choice, and collapsing it back recovers exactly what the user ticked.
+ * - **A full selection is sent as no selection at all**, because omitting `fields` already
+ *   means every column.
+ *
+ * Without them a wide config produced a query string of ten kilobytes or more — past the eight
+ * nginx and Node default to — and the request most likely to hit it is "give me a template with
+ * everything", which is the one this now sends as a bare `?format=`.
+ */
+function selectionOf(spec, context, fields) {
+    // The caller's own selection when it gave one — the wizard does — and the expanded spec
+    // reduced back to it otherwise, for a host calling `template` directly.
+    const chosen = new Set(fields ?? spec.columns.map(column => stripIndices(column.ref)));
+    const all = new Set(deriveImportColumns(context?.config, { lang: context?.lang }).columns.map(column => stripIndices(column.ref)));
+    if (all.size && chosen.size === all.size && [...all].every(ref => chosen.has(ref)))
+        return '';
+    return [...chosen].join(',');
+}
+/**
+ * Not `@Injectable`, and registered by value rather than by class.
+ *
+ * Its constructor takes options rather than dependencies, so there is nothing for an injector
+ * to resolve — and a consumer who wants two of them, pointed at two backends, gets that for
+ * free.
+ */
+class HttpImportTransport {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    get base() {
+        return trimSlash(this.options.baseUrl);
+    }
+    get send() {
+        // Bound rather than referenced: a bare `globalThis.fetch` passed around as a value throws
+        // "Illegal invocation" in a browser, because it needs `window` as its receiver.
+        return this.options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    entityOf(context) {
+        return encodeURIComponent(context?.config?.entity ?? '');
+    }
+    /**
+     * Warn when the server's engine is not the one this bundle was built against.
+     *
+     * The two halves are separately deployed and may differ. `MappingPlan.configVersion` catches
+     * *config* drift and says nothing about *engine* drift, so "one engine, both sides" is only
+     * true if something checks — and this is the something. A warning rather than a refusal: a
+     * patch release is not a reason to stop somebody importing.
+     */
+    checkEngine(version) {
+        // Compared at major.minor. A patch difference between two deploys is the normal state of
+        // a rolling release and says nothing about whether the engines agree; warning on it puts a
+        // line in the console on every preview and every commit, which is how people learn to
+        // scroll past the warning that does matter.
+        if (!version || sameLine(version, CORE_VERSION))
+            return;
+        const warn = this.options.warn ?? ((message) => console.warn(message));
+        warn(`[ngx-dynamic-entity] The import server runs @dynamic-entity/core ${version}; this app ` +
+            `was built against ${CORE_VERSION}. The two halves of an import are supposed to be the ` +
+            'same engine — bring them into step before trusting a difference in what they produce.');
+    }
+    async preview(file, context) {
+        const body = new FormData();
+        body.append('file', file, file.name || 'upload');
+        const response = await this.send(`${this.base}/${this.entityOf(context)}/preview`, {
+            method: 'POST',
+            headers: resolveHeaders(this.options),
+            body,
+        });
+        if (!response.ok)
+            throw await failureOf(response);
+        const preview = (await response.json());
+        this.checkEngine(preview.engineVersion);
+        return {
+            headers: preview.headers ?? [],
+            sample: preview.sample ?? [],
+            suggestion: preview.suggestion,
+            rowCount: preview.rowCount ?? 0,
+        };
+    }
+    async commit(file, plan, context) {
+        const body = new FormData();
+        // **The plan first, and the file second.** The server starts importing while the file is
+        // still arriving — that is the whole reason it exists — so the plan has to have arrived
+        // already. `FormData` preserves append order, so this ordering is the contract.
+        body.append('plan', JSON.stringify(plan));
+        body.append('file', file, file.name || 'upload');
+        const response = await this.send(`${this.base}/${this.entityOf(context)}/import`, {
+            method: 'POST',
+            headers: resolveHeaders(this.options),
+            body,
+        });
+        if (!response.ok)
+            throw await failureOf(response);
+        const result = (await response.json());
+        this.checkEngine(result.engineVersion);
+        return {
+            // Empty, and not because nothing was imported. The server streamed the file precisely so
+            // that fifty thousand records never had to exist at once; sending them back would undo
+            // that on the way out. `imported` is the count, and the records are in the consumer's
+            // database.
+            records: [],
+            imported: result.imported ?? 0,
+            skipped: result.skipped ?? 0,
+            failed: result.failed ?? 0,
+            errors: result.errors ?? [],
+            errorCount: result.errorCount ?? result.errors?.length ?? 0,
+            truncated: result.truncated ?? false,
+            planProblems: result.planProblems ?? [],
+        };
+    }
+    async template(spec, format, context, fields) {
+        // The server rebuilds the spec from its own config; only the selection crosses the wire.
+        // Posting a whole spec would let a client choose the headers of a file the server signs
+        // its name to, and the server has the config anyway.
+        const query = new URLSearchParams({ format });
+        const selection = selectionOf(spec, context, fields);
+        if (selection)
+            query.set('fields', selection);
+        const response = await this.send(`${this.base}/${this.entityOf(context)}/template?${query.toString()}`, { method: 'GET', headers: resolveHeaders(this.options) });
+        if (!response.ok)
+            throw await failureOf(response);
+        return response.blob();
+    }
+}
+/**
+ * Register the HTTP transport.
+ *
+ * ```ts
+ * provideNgxDynamicEntity({}),
+ * provideHttpImportTransport({ baseUrl: '/api/import' }),
+ * ```
+ *
+ * A plain `Provider` rather than `EnvironmentProviders`, so it composes inside a component's
+ * or a route's `providers` array as well as at the root — which is how a consumer points one
+ * part of an app at a different backend.
+ */
+function provideHttpImportTransport(options) {
+    return { provide: IMPORT_TRANSPORT, useValue: new HttpImportTransport(options) };
+}
+
+/**
+ * The rows an import could not take, and why.
+ *
+ * Grouped by row rather than listed flat: a row with four problems is one row to go and fix,
+ * and four separate lines invite the reader to think there are four. The row number is the
+ * one the spreadsheet shows in its gutter — header counted as row 1 — because that is the
+ * number they will scroll to.
+ */
+class ImportErrorsComponent {
+    errors = [];
+    language = 'en';
+    ui = inject(UiTextService);
+    /** Row number → its problems, in the order the rows appear in the file. */
+    grouped() {
+        const byRow = new Map();
+        for (const error of this.errors) {
+            const list = byRow.get(error.row) ?? [];
+            list.push(error);
+            byRow.set(error.row, list);
+        }
+        return [...byRow.entries()]
+            .sort((a, b) => a[0] - b[0])
+            .map(([row, problems]) => ({ row, problems }));
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: ImportErrorsComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: ImportErrorsComponent, isStandalone: true, selector: "ngx-import-errors", inputs: { errors: "errors", language: "language" }, ngImport: i0, template: `
+    @if (errors.length) {
+      <section class="ngx-import-errors" data-testid="import-errors">
+        <h4 class="ngx-import-errors__heading">{{ ui.text('importErrorsHeading', language) }}</h4>
+        <table class="ngx-import-errors__table">
+          <thead>
+            <tr>
+              <th scope="col">{{ ui.text('importErrorRow', language, { row: '#' }) }}</th>
+              <th scope="col">{{ ui.text('importErrorField', language) }}</th>
+              <th scope="col">{{ ui.text('importErrorReason', language) }}</th>
+            </tr>
+          </thead>
+          <tbody>
+            @for (group of grouped(); track group.row) {
+              @for (problem of group.problems; track $index) {
+                <tr [attr.data-testid]="'import-error-row-' + group.row">
+                  @if ($first) {
+                    <th scope="row" [attr.rowspan]="group.problems.length">
+                      {{ ui.text('importErrorRow', language, { row: group.row }) }}
+                    </th>
+                  }
+                  <td>{{ problem.ref }}</td>
+                  <td>{{ problem.message }}</td>
+                </tr>
+              }
+            }
+          </tbody>
+        </table>
+      </section>
+    }
+  `, isInline: true, styles: [".ngx-import-errors__heading{margin:0 0 8px;font-size:var(--ngx-font-size, 14px);color:var(--ngx-color-error, #b91c1c)}.ngx-import-errors__table{width:100%;border-collapse:collapse}.ngx-import-errors__table th,.ngx-import-errors__table td{text-align:left;padding:6px 10px;border-bottom:1px solid var(--ngx-color-border, #e5e7eb);vertical-align:top}.ngx-import-errors__table thead th{color:var(--ngx-color-muted, #6b7280)}.ngx-import-errors__table tbody th{white-space:nowrap;color:var(--ngx-color-error, #b91c1c)}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: ImportErrorsComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'ngx-import-errors', standalone: true, changeDetection: ChangeDetectionStrategy.OnPush, imports: [], template: `
+    @if (errors.length) {
+      <section class="ngx-import-errors" data-testid="import-errors">
+        <h4 class="ngx-import-errors__heading">{{ ui.text('importErrorsHeading', language) }}</h4>
+        <table class="ngx-import-errors__table">
+          <thead>
+            <tr>
+              <th scope="col">{{ ui.text('importErrorRow', language, { row: '#' }) }}</th>
+              <th scope="col">{{ ui.text('importErrorField', language) }}</th>
+              <th scope="col">{{ ui.text('importErrorReason', language) }}</th>
+            </tr>
+          </thead>
+          <tbody>
+            @for (group of grouped(); track group.row) {
+              @for (problem of group.problems; track $index) {
+                <tr [attr.data-testid]="'import-error-row-' + group.row">
+                  @if ($first) {
+                    <th scope="row" [attr.rowspan]="group.problems.length">
+                      {{ ui.text('importErrorRow', language, { row: group.row }) }}
+                    </th>
+                  }
+                  <td>{{ problem.ref }}</td>
+                  <td>{{ problem.message }}</td>
+                </tr>
+              }
+            }
+          </tbody>
+        </table>
+      </section>
+    }
+  `, styles: [".ngx-import-errors__heading{margin:0 0 8px;font-size:var(--ngx-font-size, 14px);color:var(--ngx-color-error, #b91c1c)}.ngx-import-errors__table{width:100%;border-collapse:collapse}.ngx-import-errors__table th,.ngx-import-errors__table td{text-align:left;padding:6px 10px;border-bottom:1px solid var(--ngx-color-border, #e5e7eb);vertical-align:top}.ngx-import-errors__table thead th{color:var(--ngx-color-muted, #6b7280)}.ngx-import-errors__table tbody th{white-space:nowrap;color:var(--ngx-color-error, #b91c1c)}\n"] }]
+        }], propDecorators: { errors: [{
+                type: Input
+            }], language: [{
+                type: Input
+            }] } });
+
+/**
+ * Match the sheet's columns to the config's fields.
+ *
+ * The table is driven by the **target fields**, not by the sheet's columns, which is the
+ * choice that decides how the screen reads. A user is answering "where does Start Date come
+ * from?", which they can do; column-first would ask "what is column G?", which they often
+ * cannot, and would make a sheet with forty irrelevant columns forty questions long.
+ *
+ * A selection is a **column index**, never header text. Two columns headed "Notes" are two
+ * different answers, and text cannot tell them apart.
+ */
+class ImportMapperComponent {
+    config;
+    headers = [];
+    /** The starting point, normally `suggestMapping`'s output. */
+    plan = null;
+    language = 'en';
+    /** Emitted whenever the user changes a selection. */
+    planChange = new EventEmitter();
+    ui = inject(UiTextService);
+    rows = signal([], ...(ngDevMode ? [{ debugName: "rows" }] : /* istanbul ignore next */ []));
+    /**
+     * How many fields a spreadsheet cannot carry at all.
+     *
+     * Shown here as well as in the template picker, because a user who already had a sheet
+     * skipped that screen — and this is the only place they would otherwise find out that an
+     * attachment column was never going to arrive.
+     */
+    unsupported = signal(0, ...(ngDevMode ? [{ debugName: "unsupported" }] : /* istanbul ignore next */ []));
+    ngOnChanges() {
+        const { columns, unsupported } = deriveImportColumns(this.config, { lang: this.language });
+        this.unsupported.set(unsupported.length);
+        const byRef = new Map((this.plan?.entries ?? []).map(entry => [entry.ref, entry]));
+        this.rows.set(columns.map(column => {
+            const entry = byRef.get(column.ref);
+            return {
+                column,
+                source: entry?.column ?? null,
+                guessed: entry?.confidence === 'guess',
+            };
+        }));
+    }
+    mappedCount() {
+        return this.rows().filter(row => row.source !== null).length;
+    }
+    missingRequired() {
+        return this.rows().filter(row => row.column.required && row.source === null).length;
+    }
+    choose(row, source) {
+        this.rows.update(rows => rows.map(candidate => candidate.column.ref === row.column.ref
+            ? // A hand-made choice is not a guess any more, so the badge goes.
+                { ...candidate, source, guessed: false }
+            : candidate));
+        this.planChange.emit(this.toPlan());
+    }
+    /** The current selections as the plan that will be applied. */
+    toPlan() {
+        const entries = this.rows()
+            .filter(row => row.source !== null)
+            .map(row => ({
+            ref: row.column.ref,
+            column: row.source,
+            header: this.headers[row.source],
+            confidence: row.guessed ? 'guess' : 'exact',
+        }));
+        return {
+            entity: this.config?.entity ?? '',
+            configVersion: this.config?.version,
+            sourceHeaders: [...this.headers],
+            entries,
+        };
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: ImportMapperComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: ImportMapperComponent, isStandalone: true, selector: "ngx-import-mapper", inputs: { config: "config", headers: "headers", plan: "plan", language: "language" }, outputs: { planChange: "planChange" }, usesOnChanges: true, ngImport: i0, template: `
+    <section class="ngx-import-mapper" data-testid="import-mapper">
+      <p class="ngx-import-mapper__summary" data-testid="import-mapped-count">
+        {{ ui.text('importMappedCount', language, { mapped: mappedCount(), total: rows().length }) }}
+      </p>
+      @if (missingRequired() > 0) {
+        <p class="ngx-import-mapper__warning" data-testid="import-required-unmapped" role="status">
+          {{ ui.text('importRequiredUnmapped', language, { count: missingRequired() }) }}
+        </p>
+      }
+      @if (unsupported() > 0) {
+        <p class="ngx-import-mapper__note" data-testid="import-mapper-unsupported">
+          {{ ui.text('importTemplateUnsupported', language, { count: unsupported() }) }}
+        </p>
+      }
+
+      <table class="ngx-import-mapper__table">
+        <thead>
+          <tr>
+            <th scope="col">{{ ui.text('importTargetField', language) }}</th>
+            <th scope="col">{{ ui.text('importColumnInFile', language) }}</th>
+          </tr>
+        </thead>
+        <tbody>
+          @for (row of rows(); track row.column.ref) {
+            <tr [attr.data-testid]="'import-map-' + row.column.ref">
+              <th scope="row">
+                {{ row.column.header }}
+                @if (row.column.required) {
+                  <span class="ngx-import-mapper__required" aria-hidden="true">*</span>
+                }
+              </th>
+              <td>
+                <select
+                  class="ngx-import-mapper__select"
+                  [attr.data-testid]="'import-select-' + row.column.ref"
+                  [attr.aria-label]="row.column.header"
+                  [ngModel]="row.source"
+                  (ngModelChange)="choose(row, $event)"
+                >
+                  <option [ngValue]="null">{{ ui.text('importUnmapped', language) }}</option>
+                  @for (header of headers; track $index) {
+                    <option [ngValue]="$index">{{ header || '—' }}</option>
+                  }
+                </select>
+                @if (row.guessed && row.source !== null) {
+                  <span class="ngx-import-mapper__guess" [attr.data-testid]="'import-guess-' + row.column.ref">
+                    {{ ui.text('importGuessed', language) }}
+                  </span>
+                }
+              </td>
+            </tr>
+          }
+        </tbody>
+      </table>
+    </section>
+  `, isInline: true, styles: [".ngx-import-mapper__summary,.ngx-import-mapper__warning,.ngx-import-mapper__note{margin:0 0 10px}.ngx-import-mapper__warning{color:var(--ngx-color-warning, #b45309);background:var(--ngx-color-warning-soft, #fffbeb);border:1px solid var(--ngx-color-border, #fef3c7);border-radius:var(--ngx-radius-sm, 6px);padding:8px 12px}.ngx-import-mapper__note{color:var(--ngx-color-muted, #6b7280)}.ngx-import-mapper__table{width:100%;border-collapse:collapse}.ngx-import-mapper__table th,.ngx-import-mapper__table td{text-align:left;padding:8px 10px;border-bottom:1px solid var(--ngx-color-border, #e5e7eb);vertical-align:middle}.ngx-import-mapper__table thead th{color:var(--ngx-color-muted, #6b7280);font-size:var(--ngx-font-size, 13px);text-transform:uppercase;letter-spacing:.04em}.ngx-import-mapper__required{color:var(--ngx-color-error, #b91c1c);margin-left:2px}.ngx-import-mapper__select{min-width:220px;max-width:100%;padding:6px 8px;border:1px solid var(--ngx-color-border, #d1d5db);border-radius:var(--ngx-radius-sm, 6px);background:var(--ngx-color-surface, #ffffff);color:inherit;font:inherit}.ngx-import-mapper__guess{margin-left:8px;padding:2px 8px;border-radius:999px;font-size:12px;color:var(--ngx-color-info, #1d4ed8);background:var(--ngx-color-info-soft, #eff6ff)}@media(max-width:640px){.ngx-import-mapper__select{min-width:0;width:100%}}\n"], dependencies: [{ kind: "ngmodule", type: FormsModule }, { kind: "directive", type: i1.NgSelectOption, selector: "option", inputs: ["ngValue", "value"] }, { kind: "directive", type: i1.ɵNgSelectMultipleOption, selector: "option", inputs: ["ngValue", "value"] }, { kind: "directive", type: i1.SelectControlValueAccessor, selector: "select:not([multiple])[formControlName],select:not([multiple])[formControl],select:not([multiple])[ngModel]", inputs: ["compareWith"] }, { kind: "directive", type: i1.NgControlStatus, selector: "[formControlName],[ngModel],[formControl]" }, { kind: "directive", type: i1.NgModel, selector: "[ngModel]:not([formControlName]):not([formControl])", inputs: ["name", "disabled", "ngModel", "ngModelOptions"], outputs: ["ngModelChange"], exportAs: ["ngModel"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: ImportMapperComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'ngx-import-mapper', standalone: true, changeDetection: ChangeDetectionStrategy.OnPush, imports: [FormsModule], template: `
+    <section class="ngx-import-mapper" data-testid="import-mapper">
+      <p class="ngx-import-mapper__summary" data-testid="import-mapped-count">
+        {{ ui.text('importMappedCount', language, { mapped: mappedCount(), total: rows().length }) }}
+      </p>
+      @if (missingRequired() > 0) {
+        <p class="ngx-import-mapper__warning" data-testid="import-required-unmapped" role="status">
+          {{ ui.text('importRequiredUnmapped', language, { count: missingRequired() }) }}
+        </p>
+      }
+      @if (unsupported() > 0) {
+        <p class="ngx-import-mapper__note" data-testid="import-mapper-unsupported">
+          {{ ui.text('importTemplateUnsupported', language, { count: unsupported() }) }}
+        </p>
+      }
+
+      <table class="ngx-import-mapper__table">
+        <thead>
+          <tr>
+            <th scope="col">{{ ui.text('importTargetField', language) }}</th>
+            <th scope="col">{{ ui.text('importColumnInFile', language) }}</th>
+          </tr>
+        </thead>
+        <tbody>
+          @for (row of rows(); track row.column.ref) {
+            <tr [attr.data-testid]="'import-map-' + row.column.ref">
+              <th scope="row">
+                {{ row.column.header }}
+                @if (row.column.required) {
+                  <span class="ngx-import-mapper__required" aria-hidden="true">*</span>
+                }
+              </th>
+              <td>
+                <select
+                  class="ngx-import-mapper__select"
+                  [attr.data-testid]="'import-select-' + row.column.ref"
+                  [attr.aria-label]="row.column.header"
+                  [ngModel]="row.source"
+                  (ngModelChange)="choose(row, $event)"
+                >
+                  <option [ngValue]="null">{{ ui.text('importUnmapped', language) }}</option>
+                  @for (header of headers; track $index) {
+                    <option [ngValue]="$index">{{ header || '—' }}</option>
+                  }
+                </select>
+                @if (row.guessed && row.source !== null) {
+                  <span class="ngx-import-mapper__guess" [attr.data-testid]="'import-guess-' + row.column.ref">
+                    {{ ui.text('importGuessed', language) }}
+                  </span>
+                }
+              </td>
+            </tr>
+          }
+        </tbody>
+      </table>
+    </section>
+  `, styles: [".ngx-import-mapper__summary,.ngx-import-mapper__warning,.ngx-import-mapper__note{margin:0 0 10px}.ngx-import-mapper__warning{color:var(--ngx-color-warning, #b45309);background:var(--ngx-color-warning-soft, #fffbeb);border:1px solid var(--ngx-color-border, #fef3c7);border-radius:var(--ngx-radius-sm, 6px);padding:8px 12px}.ngx-import-mapper__note{color:var(--ngx-color-muted, #6b7280)}.ngx-import-mapper__table{width:100%;border-collapse:collapse}.ngx-import-mapper__table th,.ngx-import-mapper__table td{text-align:left;padding:8px 10px;border-bottom:1px solid var(--ngx-color-border, #e5e7eb);vertical-align:middle}.ngx-import-mapper__table thead th{color:var(--ngx-color-muted, #6b7280);font-size:var(--ngx-font-size, 13px);text-transform:uppercase;letter-spacing:.04em}.ngx-import-mapper__required{color:var(--ngx-color-error, #b91c1c);margin-left:2px}.ngx-import-mapper__select{min-width:220px;max-width:100%;padding:6px 8px;border:1px solid var(--ngx-color-border, #d1d5db);border-radius:var(--ngx-radius-sm, 6px);background:var(--ngx-color-surface, #ffffff);color:inherit;font:inherit}.ngx-import-mapper__guess{margin-left:8px;padding:2px 8px;border-radius:999px;font-size:12px;color:var(--ngx-color-info, #1d4ed8);background:var(--ngx-color-info-soft, #eff6ff)}@media(max-width:640px){.ngx-import-mapper__select{min-width:0;width:100%}}\n"] }]
+        }], propDecorators: { config: [{
+                type: Input,
+                args: [{ required: true }]
+            }], headers: [{
+                type: Input
+            }], plan: [{
+                type: Input
+            }], language: [{
+                type: Input
+            }], planChange: [{
+                type: Output
+            }] } });
+
+/**
+ * The first few rows as the record will hold them, not as the sheet holds them.
+ *
+ * Every cell goes through the same `coerceCell` the import will use and then through
+ * `formatDisplayValue`, which is what the renderer uses to show a stored value. So a
+ * `dropdown` cell reading `Aktiv` shows as `Active` here if that is the option it resolved
+ * to, and a cell that will fail shows its reason before anyone commits to anything.
+ *
+ * Showing the raw text instead would be easier and would preview the wrong thing: the point
+ * of this screen is to catch a mapping that is subtly wrong, and a column of unchanged text
+ * looks correct whatever field it was pointed at.
+ *
+ * **The rows are also run through the real import**, not just through coercion. `coerceCell`
+ * alone catches a cell that will not parse and says nothing about a row that will be rejected
+ * — a missing required field, a rule that forbids the combination — so a heading promising
+ * "as they will be saved" was showing rows that would never be saved at all, looking exactly
+ * like the ones that would. `applyMapping` over the sample answers that with the same engine
+ * the commit uses, rather than a second opinion about what counts as valid.
+ *
+ * The whole grid is built once per input change rather than from template method calls.
+ * Deriving the config's columns inside a `@for` means re-walking the entire schema for every
+ * cell on every change-detection pass, which is a lot of work to produce five rows.
+ */
+class ImportPreviewComponent {
+    config;
+    plan;
+    rows = [];
+    lookups;
+    /** The same rules the commit will apply; without them a rule-driven rejection is invisible. */
+    rules;
+    language = 'en';
+    ui = inject(UiTextService);
+    /** The columns this plan fills, in the plan's own order. */
+    columns = signal([], ...(ngDevMode ? [{ debugName: "columns" }] : /* istanbul ignore next */ []));
+    grid = signal([], ...(ngDevMode ? [{ debugName: "grid" }] : /* istanbul ignore next */ []));
+    ngOnChanges() {
+        const byRef = new Map(deriveImportColumns(this.config, { lang: this.language }).columns.map(c => [c.ref, c]));
+        const entries = (this.plan?.entries ?? []).filter(entry => byRef.has(entry.ref));
+        this.columns.set(entries.map(entry => byRef.get(entry.ref)));
+        // The same engine the commit runs, over the sample only. Row 0 of the sample is numbered
+        // 0 here rather than 2, because these row numbers index the preview, not the file.
+        const dryRun = applyMapping(this.rows, this.plan, this.config, {
+            lang: this.language,
+            lookups: this.lookups,
+            rules: this.rules,
+            stamp: false,
+            firstRowNumber: 0,
+        });
+        const rejectionsByRow = new Map();
+        for (const error of dryRun.errors) {
+            rejectionsByRow.set(error.row, [...(rejectionsByRow.get(error.row) ?? []), error.message]);
+        }
+        this.grid.set(this.rows.map((row, index) => ({
+            rejections: rejectionsByRow.get(index) ?? [],
+            cells: entries.map(entry => {
+                const field = byRef.get(entry.ref).field;
+                const raw = entry.column === undefined ? entry.constant : row[entry.column];
+                const outcome = coerceCell(field, raw, {
+                    lang: this.language,
+                    lookups: this.lookups,
+                });
+                if ('error' in outcome)
+                    return { text: outcome.error, failed: true };
+                return {
+                    text: formatDisplayValue(field.type, field.options, outcome.value, this.language),
+                    failed: false,
+                };
+            }),
+        })));
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: ImportPreviewComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: ImportPreviewComponent, isStandalone: true, selector: "ngx-import-preview", inputs: { config: "config", plan: "plan", rows: "rows", lookups: "lookups", rules: "rules", language: "language" }, usesOnChanges: true, ngImport: i0, template: `
+    <section class="ngx-import-preview" data-testid="import-preview">
+      <h4 class="ngx-import-preview__heading">
+        {{ ui.text('importPreviewHeading', language, { count: rows.length }) }}
+      </h4>
+      <div class="ngx-import-preview__scroll">
+        <table class="ngx-import-preview__table">
+          <thead>
+            <tr>
+              @for (column of columns(); track column.ref) {
+                <th scope="col">{{ column.header }}</th>
+              }
+            </tr>
+          </thead>
+          <tbody>
+            @for (row of grid(); track $index) {
+              <tr
+                [attr.data-testid]="'import-preview-row-' + $index"
+                [class.ngx-import-preview__row--rejected]="row.rejections.length"
+              >
+                @for (cell of row.cells; track $index) {
+                  <td [class.ngx-import-preview__cell--error]="cell.failed">{{ cell.text }}</td>
+                }
+              </tr>
+              @if (row.rejections.length) {
+                <tr class="ngx-import-preview__reason">
+                  <td [attr.colspan]="columns().length" [attr.data-testid]="'import-preview-rejected-' + $index">
+                    {{ ui.text('importRowRejected', language, { reason: row.rejections.join('; ') }) }}
+                  </td>
+                </tr>
+              }
+            }
+          </tbody>
+        </table>
+      </div>
+    </section>
+  `, isInline: true, styles: [".ngx-import-preview__heading{margin:0 0 8px;font-size:var(--ngx-font-size, 14px)}.ngx-import-preview__scroll{overflow-x:auto;border:1px solid var(--ngx-color-border, #e5e7eb);border-radius:var(--ngx-radius-sm, 6px)}.ngx-import-preview__table{width:100%;border-collapse:collapse;white-space:nowrap}.ngx-import-preview__table th,.ngx-import-preview__table td{text-align:left;padding:6px 10px;border-bottom:1px solid var(--ngx-color-border, #f3f4f6)}.ngx-import-preview__table thead th{background:var(--ngx-color-surface-alt, #f9fafb);color:var(--ngx-color-muted, #6b7280)}.ngx-import-preview__cell--error{color:var(--ngx-color-error, #b91c1c);background:var(--ngx-color-error-soft, #fef2f2)}.ngx-import-preview__row--rejected td{opacity:.65}.ngx-import-preview__reason td{white-space:normal;color:var(--ngx-color-error, #b91c1c);background:var(--ngx-color-error-soft, #fef2f2)}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: ImportPreviewComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'ngx-import-preview', standalone: true, changeDetection: ChangeDetectionStrategy.OnPush, imports: [], template: `
+    <section class="ngx-import-preview" data-testid="import-preview">
+      <h4 class="ngx-import-preview__heading">
+        {{ ui.text('importPreviewHeading', language, { count: rows.length }) }}
+      </h4>
+      <div class="ngx-import-preview__scroll">
+        <table class="ngx-import-preview__table">
+          <thead>
+            <tr>
+              @for (column of columns(); track column.ref) {
+                <th scope="col">{{ column.header }}</th>
+              }
+            </tr>
+          </thead>
+          <tbody>
+            @for (row of grid(); track $index) {
+              <tr
+                [attr.data-testid]="'import-preview-row-' + $index"
+                [class.ngx-import-preview__row--rejected]="row.rejections.length"
+              >
+                @for (cell of row.cells; track $index) {
+                  <td [class.ngx-import-preview__cell--error]="cell.failed">{{ cell.text }}</td>
+                }
+              </tr>
+              @if (row.rejections.length) {
+                <tr class="ngx-import-preview__reason">
+                  <td [attr.colspan]="columns().length" [attr.data-testid]="'import-preview-rejected-' + $index">
+                    {{ ui.text('importRowRejected', language, { reason: row.rejections.join('; ') }) }}
+                  </td>
+                </tr>
+              }
+            }
+          </tbody>
+        </table>
+      </div>
+    </section>
+  `, styles: [".ngx-import-preview__heading{margin:0 0 8px;font-size:var(--ngx-font-size, 14px)}.ngx-import-preview__scroll{overflow-x:auto;border:1px solid var(--ngx-color-border, #e5e7eb);border-radius:var(--ngx-radius-sm, 6px)}.ngx-import-preview__table{width:100%;border-collapse:collapse;white-space:nowrap}.ngx-import-preview__table th,.ngx-import-preview__table td{text-align:left;padding:6px 10px;border-bottom:1px solid var(--ngx-color-border, #f3f4f6)}.ngx-import-preview__table thead th{background:var(--ngx-color-surface-alt, #f9fafb);color:var(--ngx-color-muted, #6b7280)}.ngx-import-preview__cell--error{color:var(--ngx-color-error, #b91c1c);background:var(--ngx-color-error-soft, #fef2f2)}.ngx-import-preview__row--rejected td{opacity:.65}.ngx-import-preview__reason td{white-space:normal;color:var(--ngx-color-error, #b91c1c);background:var(--ngx-color-error-soft, #fef2f2)}\n"] }]
+        }], propDecorators: { config: [{
+                type: Input,
+                args: [{ required: true }]
+            }], plan: [{
+                type: Input,
+                args: [{ required: true }]
+            }], rows: [{
+                type: Input
+            }], lookups: [{
+                type: Input
+            }], rules: [{
+                type: Input
+            }], language: [{
+                type: Input
+            }] } });
+
+/**
+ * Pick the fields a template should carry, then download it.
+ *
+ * The guidance for each field is shown **here**, beside the checkbox, rather than written
+ * into the file as a second header row. CSV has one header row and no concept of a second,
+ * so a guidance row inside the file would come back as a record on re-import and fail row 2
+ * of every import the user ever ran.
+ *
+ * A repeating field is offered once, not once per row number: "Contacts / Name" is a decision,
+ * and "Contacts / Name 1", "Contacts / Name 2", "Contacts / Name 3" is the same decision
+ * asked three times.
+ */
+class ImportTemplateComponent {
+    config;
+    language = 'en';
+    /** The refs to include, with row numbers stripped — the caller builds the spec. */
+    download = new EventEmitter();
+    ui = inject(UiTextService);
+    choices = signal([], ...(ngDevMode ? [{ debugName: "choices" }] : /* istanbul ignore next */ []));
+    unsupported = signal([], ...(ngDevMode ? [{ debugName: "unsupported" }] : /* istanbul ignore next */ []));
+    ngOnChanges() {
+        const spec = buildTemplateSpec(this.config, { lang: this.language });
+        const derived = deriveImportColumns(this.config, { lang: this.language });
+        // One entry per field, keyed on the ref with its row number removed, so a repeating
+        // field collapses back into the single choice it is.
+        const seen = new Map();
+        spec.columns.forEach((column, i) => {
+            const ref = stripIndices(column.ref);
+            if (seen.has(ref))
+                return;
+            seen.set(ref, {
+                ref,
+                header: column.arrayIndex === undefined ? column.header : stripRowNumber(column.header),
+                note: spec.notes[i] ?? '',
+                selected: true,
+            });
+        });
+        this.choices.set([...seen.values()]);
+        this.unsupported.set(derived.unsupported);
+    }
+    selectedCount() {
+        return this.choices().filter(choice => choice.selected).length;
+    }
+    selectedRefs() {
+        return this.choices()
+            .filter(choice => choice.selected)
+            .map(choice => choice.ref);
+    }
+    toggle(ref) {
+        this.choices.update(choices => choices.map(choice => choice.ref === ref ? { ...choice, selected: !choice.selected } : choice));
+    }
+    selectAll(selected) {
+        this.choices.update(choices => choices.map(choice => ({ ...choice, selected })));
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: ImportTemplateComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: ImportTemplateComponent, isStandalone: true, selector: "ngx-import-template", inputs: { config: "config", language: "language" }, outputs: { download: "download" }, usesOnChanges: true, ngImport: i0, template: `
+    <section class="ngx-import-template" data-testid="import-template">
+      <h4 class="ngx-import-template__heading">{{ ui.text('importTemplateHeading', language) }}</h4>
+      <p class="ngx-import-template__explain">{{ ui.text('importTemplateExplain', language) }}</p>
+
+      <div class="ngx-import-template__bulk">
+        <button type="button" (click)="selectAll(true)" data-testid="import-template-all">
+          {{ ui.text('importTemplateSelectAll', language) }}
+        </button>
+        <button type="button" (click)="selectAll(false)" data-testid="import-template-none">
+          {{ ui.text('importTemplateSelectNone', language) }}
+        </button>
+      </div>
+
+      <ul class="ngx-import-template__list">
+        @for (choice of choices(); track choice.ref) {
+          <li class="ngx-import-template__item">
+            <label>
+              <input
+                type="checkbox"
+                [checked]="choice.selected"
+                (change)="toggle(choice.ref)"
+                [attr.data-testid]="'import-template-field-' + choice.ref"
+              />
+              <span class="ngx-import-template__label">{{ choice.header }}</span>
+            </label>
+            @if (choice.note) {
+              <span class="ngx-import-template__note">{{ choice.note }}</span>
+            }
+          </li>
+        }
+      </ul>
+
+      @if (unsupported().length) {
+        <p class="ngx-import-template__unsupported" data-testid="import-template-unsupported">
+          {{ ui.text('importTemplateUnsupported', language, { count: unsupported().length }) }}
+        </p>
+      }
+
+      <button
+        type="button"
+        class="ngx-import-template__download"
+        data-testid="import-template-download"
+        [disabled]="!selectedCount()"
+        (click)="download.emit(selectedRefs())"
+      >
+        {{ ui.text('importTemplateDownload', language) }}
+      </button>
+    </section>
+  `, isInline: true, styles: [".ngx-import-template{padding:14px;border:1px solid var(--ngx-color-border, #e5e7eb);border-radius:var(--ngx-radius-sm, 6px);background:var(--ngx-color-surface-alt, #f9fafb)}.ngx-import-template__heading{margin:0 0 4px;font-size:var(--ngx-font-size, 14px)}.ngx-import-template__explain{margin:0 0 10px;color:var(--ngx-color-muted, #6b7280)}.ngx-import-template__bulk{display:flex;gap:8px;margin-bottom:10px}.ngx-import-template__list{list-style:none;margin:0 0 10px;padding:0;max-height:240px;overflow-y:auto;display:grid;gap:4px}.ngx-import-template__item{display:flex;flex-wrap:wrap;align-items:baseline;gap:8px}.ngx-import-template__item label{display:flex;align-items:center;gap:6px;cursor:pointer}.ngx-import-template__note{color:var(--ngx-color-muted, #6b7280);font-size:12px}.ngx-import-template__unsupported{margin:0 0 10px;color:var(--ngx-color-muted, #6b7280)}.ngx-import-template button{padding:6px 12px;border:1px solid var(--ngx-color-border, #d1d5db);border-radius:var(--ngx-radius-sm, 6px);background:var(--ngx-color-surface, #ffffff);color:inherit;font:inherit;cursor:pointer}.ngx-import-template button:disabled{opacity:.55;cursor:not-allowed}\n"], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: ImportTemplateComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'ngx-import-template', standalone: true, changeDetection: ChangeDetectionStrategy.OnPush, imports: [], template: `
+    <section class="ngx-import-template" data-testid="import-template">
+      <h4 class="ngx-import-template__heading">{{ ui.text('importTemplateHeading', language) }}</h4>
+      <p class="ngx-import-template__explain">{{ ui.text('importTemplateExplain', language) }}</p>
+
+      <div class="ngx-import-template__bulk">
+        <button type="button" (click)="selectAll(true)" data-testid="import-template-all">
+          {{ ui.text('importTemplateSelectAll', language) }}
+        </button>
+        <button type="button" (click)="selectAll(false)" data-testid="import-template-none">
+          {{ ui.text('importTemplateSelectNone', language) }}
+        </button>
+      </div>
+
+      <ul class="ngx-import-template__list">
+        @for (choice of choices(); track choice.ref) {
+          <li class="ngx-import-template__item">
+            <label>
+              <input
+                type="checkbox"
+                [checked]="choice.selected"
+                (change)="toggle(choice.ref)"
+                [attr.data-testid]="'import-template-field-' + choice.ref"
+              />
+              <span class="ngx-import-template__label">{{ choice.header }}</span>
+            </label>
+            @if (choice.note) {
+              <span class="ngx-import-template__note">{{ choice.note }}</span>
+            }
+          </li>
+        }
+      </ul>
+
+      @if (unsupported().length) {
+        <p class="ngx-import-template__unsupported" data-testid="import-template-unsupported">
+          {{ ui.text('importTemplateUnsupported', language, { count: unsupported().length }) }}
+        </p>
+      }
+
+      <button
+        type="button"
+        class="ngx-import-template__download"
+        data-testid="import-template-download"
+        [disabled]="!selectedCount()"
+        (click)="download.emit(selectedRefs())"
+      >
+        {{ ui.text('importTemplateDownload', language) }}
+      </button>
+    </section>
+  `, styles: [".ngx-import-template{padding:14px;border:1px solid var(--ngx-color-border, #e5e7eb);border-radius:var(--ngx-radius-sm, 6px);background:var(--ngx-color-surface-alt, #f9fafb)}.ngx-import-template__heading{margin:0 0 4px;font-size:var(--ngx-font-size, 14px)}.ngx-import-template__explain{margin:0 0 10px;color:var(--ngx-color-muted, #6b7280)}.ngx-import-template__bulk{display:flex;gap:8px;margin-bottom:10px}.ngx-import-template__list{list-style:none;margin:0 0 10px;padding:0;max-height:240px;overflow-y:auto;display:grid;gap:4px}.ngx-import-template__item{display:flex;flex-wrap:wrap;align-items:baseline;gap:8px}.ngx-import-template__item label{display:flex;align-items:center;gap:6px;cursor:pointer}.ngx-import-template__note{color:var(--ngx-color-muted, #6b7280);font-size:12px}.ngx-import-template__unsupported{margin:0 0 10px;color:var(--ngx-color-muted, #6b7280)}.ngx-import-template button{padding:6px 12px;border:1px solid var(--ngx-color-border, #d1d5db);border-radius:var(--ngx-radius-sm, 6px);background:var(--ngx-color-surface, #ffffff);color:inherit;font:inherit;cursor:pointer}.ngx-import-template button:disabled{opacity:.55;cursor:not-allowed}\n"] }]
+        }], propDecorators: { config: [{
+                type: Input,
+                args: [{ required: true }]
+            }], language: [{
+                type: Input
+            }], download: [{
+                type: Output
+            }] } });
+/** "Contacts / Name 1" → "Contacts / Name", for the collapsed choice. */
+function stripRowNumber(header) {
+    return header.replace(/ \d+$/, '');
+}
+
+/**
+ * The import wizard: choose a file, match its columns, look at what that produced, commit.
+ *
+ * It holds no import logic of its own. Everything it does goes through an `ImportTransport`,
+ * which by default is the in-browser one built on `@dynamic-entity/core` — so the wizard
+ * works with no backend, and a consumer who registers a server transport gets the same
+ * screens over the same mapping rules rather than a second implementation of them.
+ *
+ * The review step exists because the expensive mistake here is not a file that fails to
+ * import, it is one that imports *successfully into the wrong fields*. That is invisible in a
+ * summary and obvious in five rendered rows.
+ */
+class EntityImportComponent {
+    config;
+    /**
+     * The rules the form is rendered with.
+     *
+     * Pass them, or the import checks field validators only — which is not what the form
+     * enforces, and a required field hidden by a rule will fail every row.
+     */
+    rules;
+    /**
+     * Named lists, overriding what the wizard already resolves from `LOOKUP_REGISTRY`.
+     *
+     * Not something a host has to supply: every `listName` a config mentions is loaded from the
+     * registry the renderer is already holding. Pass this only to override one.
+     */
+    lookups;
+    language = 'en';
+    /** Format asked of the transport when a template is downloaded. */
+    templateFormat = 'csv';
+    /** The finished import, once it has run. */
+    importComplete = new EventEmitter();
+    /** A template the transport produced, for a host that would rather save it its own way. */
+    templateReady = new EventEmitter();
+    ui = inject(UiTextService);
+    steps = ['upload', 'map', 'review', 'done'];
+    step = signal('upload', ...(ngDevMode ? [{ debugName: "step" }] : /* istanbul ignore next */ []));
+    busy = signal(false, ...(ngDevMode ? [{ debugName: "busy" }] : /* istanbul ignore next */ []));
+    problem = signal(null, ...(ngDevMode ? [{ debugName: "problem" }] : /* istanbul ignore next */ []));
+    headers = signal([], ...(ngDevMode ? [{ debugName: "headers" }] : /* istanbul ignore next */ []));
+    sample = signal([], ...(ngDevMode ? [{ debugName: "sample" }] : /* istanbul ignore next */ []));
+    rowCount = signal(0, ...(ngDevMode ? [{ debugName: "rowCount" }] : /* istanbul ignore next */ []));
+    fileName = signal('', ...(ngDevMode ? [{ debugName: "fileName" }] : /* istanbul ignore next */ []));
+    plan = signal(null, ...(ngDevMode ? [{ debugName: "plan" }] : /* istanbul ignore next */ []));
+    result = signal(null, ...(ngDevMode ? [{ debugName: "result" }] : /* istanbul ignore next */ []));
+    registered = inject(IMPORT_TRANSPORT, { optional: true });
+    local = inject(LocalImportTransport);
+    lookupRegistry = inject(LookupRegistryService);
+    file = null;
+    /** Named lists resolved from `LOOKUP_REGISTRY`, merged under the `lookups` input. */
+    resolvedLookups = signal({}, ...(ngDevMode ? [{ debugName: "resolvedLookups" }] : /* istanbul ignore next */ []));
+    get transport() {
+        return this.registered ?? this.local;
+    }
+    context() {
+        return {
+            config: this.config,
+            rules: this.rules,
+            lookups: this.resolvedLookups(),
+            lang: this.language,
+        };
+    }
+    /**
+     * Load every named list this config's fields refer to.
+     *
+     * `@dynamic-entity/core` is framework-agnostic and cannot reach `LOOKUP_REGISTRY`, so
+     * `coerceCell` takes the values as an argument. That is a reason for *core* to ask, not a
+     * reason for the host to be asked — this package is holding the registry, and making the
+     * consumer re-supply what the library already has is how a `listName` column ends up
+     * storing the raw text `"Gold"` instead of the option object. Such a record renders
+     * correctly and then matches no rule, which is the exact failure the option-shape contract
+     * exists to prevent.
+     *
+     * The `lookups` input still wins where it names a list, so a host can override one without
+     * having to provide all of them.
+     */
+    async loadLookups() {
+        const fromRegistry = {};
+        const names = new Set();
+        for (const target of collectLeafTargets(this.config)) {
+            if (target.field.listName)
+                names.add(target.field.listName);
+        }
+        for (const listName of names) {
+            // A list that fails to load is not a reason to refuse the import: the field falls back
+            // to passing its text through, which is what happens today for an unregistered list.
+            try {
+                const options = await this.lookupRegistry.resolveOptions({ id: listName, type: 'dropdown', label: {}, listName }, this.language);
+                if (options.length)
+                    fromRegistry[listName] = options;
+            }
+            catch {
+                /* left out, so the field passes its text through */
+            }
+        }
+        this.resolvedLookups.set({ ...fromRegistry, ...(this.lookups ?? {}) });
+    }
+    stepLabel(step) {
+        // One key per step rather than an index, so a translator sees words and not positions.
+        const keys = {
+            upload: 'importUpload',
+            map: 'importMap',
+            review: 'importReview',
+            done: 'importDone',
+        };
+        return this.ui.text(keys[step], this.language);
+    }
+    async chooseFile(event) {
+        const input = event.target;
+        const file = input.files?.[0] ?? null;
+        if (!file) {
+            this.problem.set(this.ui.text('importNeedFile', this.language));
+            return;
+        }
+        this.problem.set(null);
+        this.busy.set(true);
+        try {
+            await this.loadLookups();
+            const preview = await this.transport.preview(file, this.context());
+            // Assigned only once the file has been read: holding a file whose headers describe the
+            // previous one is an invariant worth not having to reason about.
+            this.file = file;
+            this.fileName.set(file.name);
+            this.headers.set(preview.headers);
+            this.sample.set(preview.sample);
+            this.rowCount.set(preview.rowCount);
+            this.plan.set(preview.suggestion);
+            this.step.set('map');
+        }
+        catch (error) {
+            // A parser refusing a format, or a file that is not what it claims, is ordinary user
+            // input rather than a defect — it is reported where the user is looking.
+            this.problem.set(messageOf(error));
+        }
+        finally {
+            this.busy.set(false);
+        }
+    }
+    async commit() {
+        const plan = this.plan();
+        if (!this.file || !plan) {
+            this.problem.set(this.ui.text('importNeedFile', this.language));
+            return;
+        }
+        this.busy.set(true);
+        this.problem.set(null);
+        try {
+            const result = await this.transport.commit(this.file, plan, this.context());
+            // A plan-level error means nothing was imported, and saying "imported 0 records" would
+            // describe that as a successful run of an empty file.
+            const fatal = result.planProblems?.filter(p => p.level === 'error') ?? [];
+            if (fatal.length) {
+                this.problem.set(this.ui.text('importPlanProblem', this.language, {
+                    message: formatConfigProblems(fatal),
+                }));
+                this.step.set('map');
+                return;
+            }
+            this.result.set(result);
+            this.step.set('done');
+            this.importComplete.emit(result);
+        }
+        catch (error) {
+            this.problem.set(messageOf(error));
+        }
+        finally {
+            this.busy.set(false);
+        }
+    }
+    async downloadTemplate(fields) {
+        this.problem.set(null);
+        try {
+            const spec = buildTemplateSpec(this.config, { lang: this.language, fields });
+            // The selection as well as the spec. A server transport needs the choice, not the
+            // expansion of it — and recovering one from the other is a round trip that only works
+            // while the expansion stays exactly invertible.
+            const blob = await this.transport.template(spec, this.templateFormat, this.context(), fields);
+            this.templateReady.emit(blob);
+            saveBlob(blob, `${this.config?.entity || 'import'}-template.${this.templateFormat}`);
+        }
+        catch (error) {
+            this.problem.set(messageOf(error));
+        }
+    }
+    /**
+     * How many records were written.
+     *
+     * `records.length` for the in-browser transport, which returns every record it built, and
+     * `imported` for a server one, which streamed the file precisely so that fifty thousand
+     * records never had to exist at once and therefore has a number rather than a list. Reading
+     * `records.length` alone would report a successful import of nothing.
+     */
+    importedCount(result) {
+        return result.imported ?? result.records.length;
+    }
+    /**
+     * How many distinct rows failed, not how many problems they had between them.
+     *
+     * `failed` when the transport reports it, and the distinct rows in `errors` only when it does
+     * not. Counting the errors alone was wrong the moment a transport started capping them: a run
+     * of a thousand rows where two hundred failed said **seven**, because seven was how many
+     * distinct rows fitted inside the first twenty retained problems. This is the number a user
+     * acts on — which rows do I go and fix — so a confident wrong answer is the worst of the
+     * available ones. The in-browser transport returns every error, so counting them there is
+     * exact and `failed` is absent.
+     */
+    failedRowCount(result) {
+        return result.failed ?? new Set(result.errors.map(error => error.row)).size;
+    }
+    restart() {
+        this.file = null;
+        this.fileName.set('');
+        this.headers.set([]);
+        this.sample.set([]);
+        this.rowCount.set(0);
+        this.plan.set(null);
+        this.result.set(null);
+        this.problem.set(null);
+        this.step.set('upload');
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: EntityImportComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "21.2.22", type: EntityImportComponent, isStandalone: true, selector: "ngx-entity-import", inputs: { config: "config", rules: "rules", lookups: "lookups", language: "language", templateFormat: "templateFormat" }, outputs: { importComplete: "importComplete", templateReady: "templateReady" }, ngImport: i0, template: `
+    <div class="ngx-import" data-testid="entity-import">
+      <ol class="ngx-import__steps" data-testid="import-steps">
+        @for (name of steps; track name) {
+          <li
+            class="ngx-import__step"
+            [class.ngx-import__step--current]="step() === name"
+            [attr.aria-current]="step() === name ? 'step' : null"
+            [attr.data-testid]="'import-step-' + name"
+          >
+            {{ stepLabel(name) }}
+          </li>
+        }
+      </ol>
+
+      @if (problem(); as text) {
+        <p class="ngx-import__problem" role="alert" data-testid="import-problem">{{ text }}</p>
+      }
+
+      @switch (step()) {
+        @case ('upload') {
+          <ngx-import-template
+            [config]="config"
+            [language]="language"
+            (download)="downloadTemplate($event)"
+          />
+
+          <label class="ngx-import__file">
+            <span>{{ ui.text('importChooseFile', language) }}</span>
+            <input type="file" data-testid="import-file" (change)="chooseFile($event)" />
+          </label>
+
+          @if (busy()) {
+            <p data-testid="import-reading">{{ ui.text('importReading', language) }}</p>
+          }
+          @if (fileName()) {
+            <p data-testid="import-file-chosen">
+              {{ ui.text('importFileChosen', language, { name: fileName(), rows: rowCount() }) }}
+            </p>
+          }
+        }
+
+        @case ('map') {
+          <ngx-import-mapper
+            [config]="config"
+            [headers]="headers()"
+            [plan]="plan()"
+            [language]="language"
+            (planChange)="plan.set($event)"
+          />
+          <button type="button" data-testid="import-to-review" (click)="step.set('review')">
+            {{ ui.text('importReview', language) }}
+          </button>
+        }
+
+        @case ('review') {
+          @if (plan(); as current) {
+            <ngx-import-preview
+              [config]="config"
+              [plan]="current"
+              [rows]="sample()"
+              [lookups]="resolvedLookups()"
+              [rules]="rules"
+              [language]="language"
+            />
+          }
+          <button
+            type="button"
+            data-testid="import-commit"
+            [disabled]="busy()"
+            (click)="commit()"
+          >
+            {{
+              busy()
+                ? ui.text('importImporting', language)
+                : ui.text('importRunImport', language, { count: rowCount() })
+            }}
+          </button>
+          <button type="button" data-testid="import-back" (click)="step.set('map')">
+            {{ ui.text('importMap', language) }}
+          </button>
+        }
+
+        @case ('done') {
+          @if (result(); as done) {
+            <p data-testid="import-succeeded">
+              {{ ui.text('importSucceeded', language, { count: importedCount(done) }) }}
+            </p>
+            @if (done.skipped) {
+              <p data-testid="import-skipped">
+                {{ ui.text('importSkippedRows', language, { count: done.skipped }) }}
+              </p>
+            }
+            @if (failedRowCount(done)) {
+              <p data-testid="import-failed">
+                {{ ui.text('importFailedRows', language, { count: failedRowCount(done) }) }}
+              </p>
+            }
+            @if (done.truncated) {
+              <p data-testid="import-errors-truncated">
+                {{
+                  ui.text('importErrorsTruncated', language, {
+                    shown: done.errors.length,
+                    count: done.errorCount ?? done.errors.length,
+                  })
+                }}
+              </p>
+            }
+            <ngx-import-errors [errors]="done.errors" [language]="language" />
+          }
+          <button type="button" data-testid="import-restart" (click)="restart()">
+            {{ ui.text('importStartOver', language) }}
+          </button>
+        }
+      }
+    </div>
+  `, isInline: true, styles: [".ngx-import{display:flex;flex-direction:column;gap:var(--ngx-gap, 16px);color:var(--ngx-color-text, #1f2937);font-size:var(--ngx-font-size, 14px)}.ngx-import__steps{display:flex;flex-wrap:wrap;gap:8px;list-style:none;margin:0;padding:0}.ngx-import__step{padding:4px 12px;border:1px solid var(--ngx-color-border, #e5e7eb);border-radius:var(--ngx-radius-sm, 6px);color:var(--ngx-color-muted, #6b7280);background:var(--ngx-color-surface-alt, #f9fafb)}.ngx-import__step--current{color:var(--ngx-color-accent, #4f46e5);border-color:var(--ngx-color-accent, #4f46e5);background:var(--ngx-color-accent-soft, #e0e7ff);font-weight:600}.ngx-import__problem{margin:0;padding:10px 12px;border:1px solid var(--ngx-color-border, #fecaca);border-radius:var(--ngx-radius-sm, 6px);background:var(--ngx-color-error-soft, #fef2f2);color:var(--ngx-color-error, #b91c1c);overflow-wrap:anywhere}.ngx-import__file{display:flex;flex-direction:column;gap:6px;padding:14px;border:1px dashed var(--ngx-color-border, #d1d5db);border-radius:var(--ngx-radius-sm, 6px);background:var(--ngx-color-surface, #ffffff)}.ngx-import button{align-self:flex-start;padding:8px 16px;border:1px solid var(--ngx-color-border, #d1d5db);border-radius:var(--ngx-radius-sm, 6px);background:var(--ngx-color-surface, #ffffff);color:inherit;font:inherit;cursor:pointer}.ngx-import button:hover:not(:disabled){border-color:var(--ngx-color-accent, #4f46e5);background:var(--ngx-color-accent-soft, #e0e7ff)}.ngx-import button:disabled{opacity:.55;cursor:not-allowed}\n"], dependencies: [{ kind: "component", type: ImportTemplateComponent, selector: "ngx-import-template", inputs: ["config", "language"], outputs: ["download"] }, { kind: "component", type: ImportMapperComponent, selector: "ngx-import-mapper", inputs: ["config", "headers", "plan", "language"], outputs: ["planChange"] }, { kind: "component", type: ImportPreviewComponent, selector: "ngx-import-preview", inputs: ["config", "plan", "rows", "lookups", "rules", "language"] }, { kind: "component", type: ImportErrorsComponent, selector: "ngx-import-errors", inputs: ["errors", "language"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.22", ngImport: i0, type: EntityImportComponent, decorators: [{
+            type: Component,
+            args: [{ selector: 'ngx-entity-import', standalone: true, changeDetection: ChangeDetectionStrategy.OnPush, imports: [
+                        ImportTemplateComponent,
+                        ImportMapperComponent,
+                        ImportPreviewComponent,
+                        ImportErrorsComponent,
+                    ], template: `
+    <div class="ngx-import" data-testid="entity-import">
+      <ol class="ngx-import__steps" data-testid="import-steps">
+        @for (name of steps; track name) {
+          <li
+            class="ngx-import__step"
+            [class.ngx-import__step--current]="step() === name"
+            [attr.aria-current]="step() === name ? 'step' : null"
+            [attr.data-testid]="'import-step-' + name"
+          >
+            {{ stepLabel(name) }}
+          </li>
+        }
+      </ol>
+
+      @if (problem(); as text) {
+        <p class="ngx-import__problem" role="alert" data-testid="import-problem">{{ text }}</p>
+      }
+
+      @switch (step()) {
+        @case ('upload') {
+          <ngx-import-template
+            [config]="config"
+            [language]="language"
+            (download)="downloadTemplate($event)"
+          />
+
+          <label class="ngx-import__file">
+            <span>{{ ui.text('importChooseFile', language) }}</span>
+            <input type="file" data-testid="import-file" (change)="chooseFile($event)" />
+          </label>
+
+          @if (busy()) {
+            <p data-testid="import-reading">{{ ui.text('importReading', language) }}</p>
+          }
+          @if (fileName()) {
+            <p data-testid="import-file-chosen">
+              {{ ui.text('importFileChosen', language, { name: fileName(), rows: rowCount() }) }}
+            </p>
+          }
+        }
+
+        @case ('map') {
+          <ngx-import-mapper
+            [config]="config"
+            [headers]="headers()"
+            [plan]="plan()"
+            [language]="language"
+            (planChange)="plan.set($event)"
+          />
+          <button type="button" data-testid="import-to-review" (click)="step.set('review')">
+            {{ ui.text('importReview', language) }}
+          </button>
+        }
+
+        @case ('review') {
+          @if (plan(); as current) {
+            <ngx-import-preview
+              [config]="config"
+              [plan]="current"
+              [rows]="sample()"
+              [lookups]="resolvedLookups()"
+              [rules]="rules"
+              [language]="language"
+            />
+          }
+          <button
+            type="button"
+            data-testid="import-commit"
+            [disabled]="busy()"
+            (click)="commit()"
+          >
+            {{
+              busy()
+                ? ui.text('importImporting', language)
+                : ui.text('importRunImport', language, { count: rowCount() })
+            }}
+          </button>
+          <button type="button" data-testid="import-back" (click)="step.set('map')">
+            {{ ui.text('importMap', language) }}
+          </button>
+        }
+
+        @case ('done') {
+          @if (result(); as done) {
+            <p data-testid="import-succeeded">
+              {{ ui.text('importSucceeded', language, { count: importedCount(done) }) }}
+            </p>
+            @if (done.skipped) {
+              <p data-testid="import-skipped">
+                {{ ui.text('importSkippedRows', language, { count: done.skipped }) }}
+              </p>
+            }
+            @if (failedRowCount(done)) {
+              <p data-testid="import-failed">
+                {{ ui.text('importFailedRows', language, { count: failedRowCount(done) }) }}
+              </p>
+            }
+            @if (done.truncated) {
+              <p data-testid="import-errors-truncated">
+                {{
+                  ui.text('importErrorsTruncated', language, {
+                    shown: done.errors.length,
+                    count: done.errorCount ?? done.errors.length,
+                  })
+                }}
+              </p>
+            }
+            <ngx-import-errors [errors]="done.errors" [language]="language" />
+          }
+          <button type="button" data-testid="import-restart" (click)="restart()">
+            {{ ui.text('importStartOver', language) }}
+          </button>
+        }
+      }
+    </div>
+  `, styles: [".ngx-import{display:flex;flex-direction:column;gap:var(--ngx-gap, 16px);color:var(--ngx-color-text, #1f2937);font-size:var(--ngx-font-size, 14px)}.ngx-import__steps{display:flex;flex-wrap:wrap;gap:8px;list-style:none;margin:0;padding:0}.ngx-import__step{padding:4px 12px;border:1px solid var(--ngx-color-border, #e5e7eb);border-radius:var(--ngx-radius-sm, 6px);color:var(--ngx-color-muted, #6b7280);background:var(--ngx-color-surface-alt, #f9fafb)}.ngx-import__step--current{color:var(--ngx-color-accent, #4f46e5);border-color:var(--ngx-color-accent, #4f46e5);background:var(--ngx-color-accent-soft, #e0e7ff);font-weight:600}.ngx-import__problem{margin:0;padding:10px 12px;border:1px solid var(--ngx-color-border, #fecaca);border-radius:var(--ngx-radius-sm, 6px);background:var(--ngx-color-error-soft, #fef2f2);color:var(--ngx-color-error, #b91c1c);overflow-wrap:anywhere}.ngx-import__file{display:flex;flex-direction:column;gap:6px;padding:14px;border:1px dashed var(--ngx-color-border, #d1d5db);border-radius:var(--ngx-radius-sm, 6px);background:var(--ngx-color-surface, #ffffff)}.ngx-import button{align-self:flex-start;padding:8px 16px;border:1px solid var(--ngx-color-border, #d1d5db);border-radius:var(--ngx-radius-sm, 6px);background:var(--ngx-color-surface, #ffffff);color:inherit;font:inherit;cursor:pointer}.ngx-import button:hover:not(:disabled){border-color:var(--ngx-color-accent, #4f46e5);background:var(--ngx-color-accent-soft, #e0e7ff)}.ngx-import button:disabled{opacity:.55;cursor:not-allowed}\n"] }]
+        }], propDecorators: { config: [{
+                type: Input,
+                args: [{ required: true }]
+            }], rules: [{
+                type: Input
+            }], lookups: [{
+                type: Input
+            }], language: [{
+                type: Input
+            }], templateFormat: [{
+                type: Input
+            }], importComplete: [{
+                type: Output
+            }], templateReady: [{
+                type: Output
+            }] } });
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Hand a generated file to the browser.
+ *
+ * The object URL is revoked on the next turn rather than immediately: revoking it in the same
+ * task can cancel the download that was just started, and the leak of waiting one tick is a
+ * single URL.
+ */
+function saveBlob(blob, filename) {
+    if (typeof document === 'undefined')
+        return;
+    const url = URL.createObjectURL(blob);
+    const anchor = document.createElement('a');
+    anchor.href = url;
+    anchor.download = filename;
+    anchor.style.display = 'none';
+    document.body.appendChild(anchor);
+    anchor.click();
+    document.body.removeChild(anchor);
+    setTimeout(() => URL.revokeObjectURL(url));
+}
+
 // Tokens
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-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 { 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 };
 //# sourceMappingURL=ngx-dynamic-entity.mjs.map