ngx-dynamic-entity 1.13.0 → 2.0.0

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

@@ -1,9 +1,10 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, Type, EnvironmentProviders, WritableSignal, OnInit, OnChanges, OnDestroy, EventEmitter, SimpleChanges } from '@angular/core';
-import { ReferenceOption as ReferenceOption$1, LocalizedText, EntityReferenceLoader as EntityReferenceLoader$1, LookupListSource as LookupListSource$1, RecordMigration as RecordMigration$1, FieldValidators, NestedFieldConfig, ReferenceLoaderContext, EntityFormConfig, DropdownOption, LookupListValue, NestedTabConfig, FormRule, RuleEvaluationResult as RuleEvaluationResult$1 } from '@dynamic-entity/core';
+import { InjectionToken, Type, EnvironmentProviders, WritableSignal, OnInit, OnChanges, OnDestroy, EventEmitter, SimpleChanges, Provider } from '@angular/core';
+import { ReferenceOption, LocalizedText, EntityFormConfig, FormRule, ImportLookups, MappingPlan, ImportResult, TemplateSpec, SheetData, CommonModuleEntry, EntityReferenceLoader, LookupListSource, RecordMigration, FileUploadHandler, FieldValidators, NestedFieldConfig, ReferenceLoaderContext, DropdownOption, LookupListValue, NestedTabConfig, RuleEvaluationResult, FieldScopeEntry, EvaluateFormRulesOptions, ImportColumn, UnsupportedColumn, ImportRowError } from '@dynamic-entity/core';
 export { AutoPatchConfig, CommonModuleEntry, ComponentClass, DropdownOption, EntityFormConfig, EntityPermissions, EntityReferenceConfig, EntityReferenceLoader, FieldTableConfig, FieldValidators, FileRef, FormRule, LocalizedText, NestedFieldConfig, NestedTabConfig, PatchOnTrueMapping, RbacContext, ReferenceLoaderContext, ReferenceOption, RichFieldType, RuleAction, RuleCondition, RuleEvaluationResult, VersionedRecord, formatDisplayValue, normalizeConfig, normalizeOption, resolveLabel, resolveOptionLabel, resolveOptionValue, valuesMatch } from '@dynamic-entity/core';
-import { ValidatorFn, AsyncValidatorFn, ValidationErrors, FormGroup, FormArray, AbstractControl } from '@angular/forms';
+import { ValidatorFn, AsyncValidatorFn, AbstractControl, ValidationErrors, FormGroup, FormArray } from '@angular/forms';
 import * as rxjs from 'rxjs';
+import * as ngx_dynamic_entity from 'ngx-dynamic-entity';
 
 /**
  * Backing store for cached reference options.
@@ -15,8 +16,8 @@ import * as rxjs from 'rxjs';
  * that must not silently persist a tenant's data.
  */
 interface EntityRefCacheStore {
-    get(key: string): ReferenceOption$1[] | undefined;
-    set(key: string, value: ReferenceOption$1[]): void;
+    get(key: string): ReferenceOption[] | undefined;
+    set(key: string, value: ReferenceOption[]): void;
     delete(key: string): void;
     /** Every key currently held — used for prefix invalidation of one entity. */
     keys(): string[];
@@ -25,8 +26,8 @@ interface EntityRefCacheStore {
 /** Default in-memory store. Lives as long as the injector that created it. */
 declare class InMemoryEntityRefCacheStore implements EntityRefCacheStore {
     private readonly map;
-    get(key: string): ReferenceOption$1[] | undefined;
-    set(key: string, value: ReferenceOption$1[]): void;
+    get(key: string): ReferenceOption[] | undefined;
+    set(key: string, value: ReferenceOption[]): void;
     delete(key: string): void;
     keys(): string[];
     clear(): void;
@@ -95,6 +96,40 @@ declare const DEFAULT_UI_TEXT: {
     criticalFieldUnlockHint: string;
     dismissBanner: string;
     jumpToField: string;
+    importUpload: string;
+    importMap: string;
+    importReview: string;
+    importDone: string;
+    importChooseFile: string;
+    importFileChosen: string;
+    importReading: string;
+    importNeedFile: string;
+    importTemplateHeading: string;
+    importTemplateExplain: string;
+    importTemplateDownload: string;
+    importTemplateSelectAll: string;
+    importTemplateSelectNone: string;
+    importTemplateUnsupported: string;
+    importColumnInFile: string;
+    importTargetField: string;
+    importUnmapped: string;
+    importGuessed: string;
+    importMappedCount: string;
+    importRequiredUnmapped: string;
+    importPreviewHeading: string;
+    importRowRejected: string;
+    importRunImport: string;
+    importImporting: string;
+    importSucceeded: string;
+    importSkippedRows: string;
+    importFailedRows: string;
+    importErrorsTruncated: string;
+    importStartOver: string;
+    importErrorsHeading: string;
+    importErrorRow: string;
+    importErrorField: string;
+    importErrorReason: string;
+    importPlanProblem: string;
     entityLabel: string;
     criticalFieldChanged: string;
     recordModified: string;
@@ -162,6 +197,102 @@ declare class UiTextService {
     static ɵprov: i0.ɵɵInjectableDeclaration<UiTextService>;
 }
 
+/**
+ * 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.
+ */
+
+/**
+ * Reads an uploaded file into headers and positional rows.
+ *
+ * Positional (`string[][]`), not keyed by header, because a real sheet carries duplicate
+ * headers and blank ones — and because a mapping entry addresses a column by index for
+ * exactly that reason. A parser that returned objects keyed by header would silently lose
+ * the second of two columns both called "Notes".
+ *
+ * The library ships a CSV implementation and no more. Registering one that understands
+ * `.xlsx` is how a consumer adds it, and which spreadsheet library they use stays their
+ * choice — this package has no runtime dependency and gains none here.
+ *
+ * @example
+ * provideNgxDynamicEntity({
+ *   sheetParser: async file => {
+ *     const workbook = XLSX.read(await file.arrayBuffer());
+ *     const rows = XLSX.utils.sheet_to_json(workbook.Sheets[workbook.SheetNames[0]], {
+ *       header: 1, raw: false, defval: '',
+ *     }) as string[][];
+ *     return { headers: rows[0] ?? [], rows: rows.slice(1) };
+ *   },
+ * })
+ */
+type SheetParser = (file: File) => SheetData | Promise<SheetData>;
+/** The formats a generated template can be written in. CSV needs no dependency. */
+type TemplateFormat = 'csv' | 'xlsx';
+/** What the wizard needs to know about the entity it is importing into. */
+interface ImportContext {
+    config: EntityFormConfig;
+    /**
+     * Rules that apply to this entity.
+     *
+     * Without them an import checks field validators only, which is **not** what the form
+     * enforces: a rule can attach an error, and a rule can hide a field, which must relax
+     * `required`. Pass the same rules the form is rendered with or the two disagree.
+     */
+    rules?: readonly FormRule[];
+    /** Values for any `listName` field, already resolved — core cannot reach `LOOKUP_REGISTRY`. */
+    lookups?: ImportLookups;
+    lang?: string;
+}
+/** What a first look at an uploaded file yields. */
+interface ImportPreview {
+    headers: string[];
+    /** The first few rows, for the mapping screen to show under each column. */
+    sample: string[][];
+    /** Where the suggester got to. Every inferred match is tagged `guess`. */
+    suggestion: MappingPlan;
+    /** Total data rows in the file, which may be far more than `sample` holds. */
+    rowCount: number;
+}
+/**
+ * Where the work happens.
+ *
+ * The default implementation does everything in the browser with `@dynamic-entity/core` and
+ * never touches the network, so the wizard is fully usable with no backend at all. Register
+ * an implementation that posts to a server and the same components drive it instead — the
+ * engine underneath is the same code either way, which is the point of it being pure.
+ *
+ * This is the real answer to "should parsing happen on the client or the server?": both,
+ * chosen at registration, without a second implementation of the mapping rules.
+ */
+interface ImportTransport {
+    /** Headers, a sample, and a suggested mapping for a freshly chosen file. */
+    preview(file: File, context: ImportContext): Promise<ImportPreview>;
+    /** Apply a plan to the whole file. */
+    commit(file: File, plan: MappingPlan, context: ImportContext): Promise<ImportResult>;
+    /**
+     * Render a template for download.
+     *
+     * `fields` is the selection the user actually made — refs with row numbers stripped, one per
+     * choice — and `spec` is that selection already expanded against the config. A transport that
+     * renders locally wants the spec; one that asks a server wants the selection, because the
+     * server has the config and only the choice needs to cross the wire. Passing both means
+     * neither has to reconstruct the other: the HTTP transport used to recover the selection from
+     * the expanded spec, which worked only because `stripIndices` happens to be exactly the
+     * inverse of the expansion. Optional, so an existing implementation keeps compiling.
+     */
+    template(spec: TemplateSpec, format: TemplateFormat, context: ImportContext, fields?: readonly string[]): Promise<Blob>;
+}
+
 /** Roles that see XXXXXXXXX for masked fields. Presentational only — enforce authz server-side. */
 declare const MASKED_ROLES: InjectionToken<string[]>;
 /**
@@ -279,6 +410,46 @@ declare const COMMON_MODULES_REGISTRY: InjectionToken<CommonModuleEntry[]>;
  * { provide: UPLOAD_HANDLER, useFactory: () => (file: File) => myUploadService.upload(file) }
  */
 declare const UPLOAD_HANDLER: InjectionToken<FileUploadHandler>;
+/**
+ * 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) };
+ *   },
+ * })
+ */
+declare const SHEET_PARSER: InjectionToken<SheetParser>;
+/**
+ * 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 }
+ */
+declare const IMPORT_TRANSPORT: InjectionToken<ImportTransport>;
 /**
  * Backing store for the entity-reference options cache. Defaults to in-memory.
  * Provide your own to make the cache outlive a page refresh.
@@ -375,13 +546,13 @@ interface NgxDynamicEntityConfig {
      * Entity-ref option loaders keyed by entity key.
      * Each receives `{ parentValue, filters, lang }` and may return an array, Promise, or Observable.
      */
-    entityRefs?: Record<string, EntityReferenceLoader$1>;
+    entityRefs?: Record<string, EntityReferenceLoader>;
     /**
      * Named master lists keyed by list name, for fields that set `listName`.
      * Each may be the values themselves (array/Promise/Observable) or a loader function — prefer
      * a loader for anything fetched, so an unused list is never loaded.
      */
-    lookups?: Record<string, LookupListSource$1>;
+    lookups?: Record<string, LookupListSource>;
     /**
      * Override the messages shown under invalid fields, keyed by Angular error key. A value is
      * a string, or a function receiving `(language, error)` when it needs the error's detail.
@@ -414,7 +585,21 @@ interface NgxDynamicEntityConfig {
      * Ordered steps that upgrade a saved record when `EntityFormConfig.version` moves ahead
      * of the record's `_configVersion`. Applied to `initialData` before the form is patched.
      */
-    migrations?: RecordMigration$1[];
+    migrations?: RecordMigration[];
+    /**
+     * Reads an uploaded spreadsheet for the import wizard, as `{ headers, rows }` with rows
+     * positional rather than keyed by header.
+     *
+     * Omit it and CSV is read by the dependency-free parser in `@dynamic-entity/core`; supply
+     * one to accept `.xlsx`, using whichever spreadsheet library you already have.
+     */
+    sheetParser?: SheetParser;
+    /**
+     * Where an import's work happens. Omit it and the whole import runs in the browser with no
+     * network at all; supply one that posts to a server for files too large to hold in memory.
+     * Either way the mapping, coercion and validation are the same pure functions.
+     */
+    importTransport?: ImportTransport;
 }
 /**
  * Provider function for ngx-dynamic-entity.
@@ -433,7 +618,7 @@ declare const provideNgxDynamicEntity: (config?: NgxDynamicEntityConfig) => Envi
  *
  * `FieldRegistryService` imports no components. Whatever you register here is what gets
  * bundled, so an app that only uses text/number/dropdown pays for three components and
- * their imports, not nineteen.
+ * their imports, not twenty-one.
  *
  * ```ts
  * // Everything (convenient; bundles all built-ins):
@@ -449,7 +634,7 @@ declare const provideNgxDynamicEntity: (config?: NgxDynamicEntityConfig) => Envi
 declare function builtInFieldTypes(): Record<string, Type<any>>;
 /** Register a specific set of field types. Only the components you name are bundled. */
 declare function provideFieldTypes(types: Record<string, Type<any>>): EnvironmentProviders;
-/** Register all 19 built-in field type keys. Convenience for apps that use most of them. */
+/** Register all 21 built-in field type keys. Convenience for apps that use most of them. */
 declare function provideBuiltInFieldTypes(): EnvironmentProviders;
 
 /**
@@ -457,7 +642,7 @@ declare function provideBuiltInFieldTypes(): EnvironmentProviders;
  *
  * **Tree-shaking contract:** this service holds *no* static imports of field components.
  * Nothing is bundled until something registers it, which is what makes the built-ins
- * opt-in. Register them with `provideBuiltInFieldTypes()` (all 19 keys) or a narrower
+ * opt-in. Register them with `provideBuiltInFieldTypes()` (all 21 keys) or a narrower
  * subset via `provideFieldTypes({ ... })` — see `providers/provide-field-types.ts`.
  *
  * Resolution order: consumer token registry → runtime registrations → nothing.
@@ -521,6 +706,22 @@ declare class ValidatorRegistryService {
      * An unknown name is skipped rather than throwing, matching the synchronous behaviour.
      */
     resolveAsyncFromConfig(config?: FieldValidators | string[]): AsyncValidatorFn[];
+    /**
+     * Say when a named validator resolved to nothing.
+     *
+     * It used to be dropped in silence, which is the worst failure mode this library has: the
+     * schema says the field is checked, the field is not checked, the form saves, and nothing
+     * anywhere said so. For `customAsync` that is typically a uniqueness check, so the duplicate
+     * lands in the database.
+     *
+     * Dev only, once per name — this runs while controls are built, which happens on every
+     * config change. `validateConfig` with `knownValidators` is the build-time version of the
+     * same check, and it fails CI rather than a console.
+     */
+    private warnUnresolved;
+    /** Per service instance, which is per injector — so a test gets a clean slate. */
+    private readonly warned;
+    private warnOnce;
     static ɵfac: i0.ɵɵFactoryDeclaration<ValidatorRegistryService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<ValidatorRegistryService>;
 }
@@ -539,7 +740,7 @@ declare class EntityRefRegistryService {
      * Get the option loader for an entity key.
      * @returns The loader, or null if none is registered.
      */
-    resolve(entityKey: string): EntityReferenceLoader$1 | null;
+    resolve(entityKey: string): EntityReferenceLoader | null;
     has(entityKey: string): boolean;
     static ɵfac: i0.ɵɵFactoryDeclaration<EntityRefRegistryService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<EntityRefRegistryService>;
@@ -548,7 +749,7 @@ declare class EntityRefRegistryService {
 interface EntityRefSelection {
     fieldId: string;
     /** The chosen option, or `null` when the selection was cleared. */
-    option: ReferenceOption$1 | null;
+    option: ReferenceOption | null;
 }
 /**
  * EntityRefSelectionService — the channel an entity-ref field uses to publish *which record*
@@ -563,7 +764,7 @@ interface EntityRefSelection {
 declare class EntityRefSelectionService {
     private readonly subject;
     readonly selection$: rxjs.Observable<EntityRefSelection>;
-    emit(fieldId: string, option: ReferenceOption$1 | null): void;
+    emit(fieldId: string, option: ReferenceOption | null): void;
     static ɵfac: i0.ɵɵFactoryDeclaration<EntityRefSelectionService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<EntityRefSelectionService>;
 }
@@ -588,7 +789,7 @@ declare class CascadeDataService {
      * Load the options for a field, cascade-filtered against `parentValue`.
      * Returns `[]` when no loader is registered, or when a cascade child has no parent value yet.
      */
-    load(field: NestedFieldConfig, ctx?: ReferenceLoaderContext): Promise<ReferenceOption$1[]>;
+    load(field: NestedFieldConfig, ctx?: ReferenceLoaderContext): Promise<ReferenceOption[]>;
     /**
      * Warm the cache for every entity a config's cascades depend on, so changing a parent
      * resolves from memory instead of a round-trip.
@@ -603,7 +804,7 @@ declare class CascadeDataService {
      * Child options for a parent selection, from cache only — no load is triggered.
      * Returns `[]` when the entity has not been preloaded.
      */
-    getCachedChildOptions(field: NestedFieldConfig, parentValue: unknown, lang?: string): ReferenceOption$1[];
+    getCachedChildOptions(field: NestedFieldConfig, parentValue: unknown, lang?: string): ReferenceOption[];
     /** Forget the preload for one config. The option cache itself is untouched. */
     clearCache(formConfigId: string): void;
     /** Every entity-ref field in the config that participates in a cascade. */
@@ -637,9 +838,9 @@ declare class EntityReferenceService {
      * Options for an entity, from cache when present.
      * Concurrent callers with the same key share one load.
      */
-    load(entityKey: string, ctx?: ReferenceLoaderContext): Promise<ReferenceOption$1[]>;
+    load(entityKey: string, ctx?: ReferenceLoaderContext): Promise<ReferenceOption[]>;
     /** Cached options without triggering a load. `undefined` when not cached. */
-    peek(entityKey: string, ctx?: ReferenceLoaderContext): ReferenceOption$1[] | undefined;
+    peek(entityKey: string, ctx?: ReferenceLoaderContext): ReferenceOption[] | undefined;
     /**
      * Display text for a stored reference value, synchronously.
      * Returns `undefined` when the entity's options have never been loaded.
@@ -778,18 +979,88 @@ declare class RbacService {
     static ɵprov: i0.ɵɵInjectableDeclaration<RbacService>;
 }
 
+/** What `syncHiddenFieldState` needs from the form it is operating on. */
+interface RuleSyncContext {
+    result: RuleEvaluationResult;
+    /** The values `showWhen` is evaluated against — the flat map the rules engine reads. */
+    values: Record<string, unknown>;
+    /** Every name a field answers to: its bare id, and its bracketed path. */
+    namesOf(field: NestedFieldConfig): readonly string[];
+    /**
+     * The field's dotted address, unbracketed — `personal.address.city`.
+     *
+     * Separate from `namesOf` because it is compared as a *prefix*: a container hides its
+     * descendants, and `[personal.address]` is not a prefix of `[personal.address.city]` once
+     * the brackets are in the way.
+     */
+    addressOf(field: NestedFieldConfig): string;
+    /** The control a scope entry addresses, or `null` when it has no static path. */
+    controlFor(entry: FieldScopeEntry): AbstractControl | null;
+}
 /**
- * RulesEvaluationService — evaluates dynamic form rules against active reactive form state.
+ * RulesEvaluationService — evaluates rules, and owns what a result *means*.
+ *
+ * It used to be two passthrough methods, with the interpretation spread across the component:
+ * the render filter decided one way what a rule result did to a field, and the validity sync
+ * decided again forty lines further down. They disagreed about what "every field" meant, and
+ * the consequence was a required field inside a `group` that a rule had hidden holding
+ * `form.invalid` true forever with nothing on screen to explain it.
+ *
+ * Precedence lives here now, in one method that both callers go through. Still stateless —
+ * every method takes the result it is interpreting, so there is nothing to go stale against a
+ * rebuilt form and nothing to reset between configs.
  */
 declare class RulesEvaluationService {
     /**
      * Evaluate rules against form values and optional original baseline values.
      */
-    evaluate(rules: FormRule[] | undefined | null, values: Record<string, unknown>, originalValues?: Record<string, unknown>): RuleEvaluationResult$1;
+    evaluate(rules: FormRule[] | undefined | null, values: Record<string, unknown>, originalValues?: Record<string, unknown>, options?: EvaluateFormRulesOptions): RuleEvaluationResult;
     /**
      * Filter rules pertinent to a single tab.
      */
     filterForTab(rules: FormRule[] | undefined | null, tabId: string, config: EntityFormConfig): FormRule[];
+    /**
+     * Whether a field renders, under the precedence documented on `RuleEvaluationResult`.
+     *
+     * An explicit hide beats everything. A show beats static hiding — `visibility: false`, or a
+     * `showWhen` that does not currently hold — because a rule that could only hide what the
+     * config already hides would have nothing to say, and `{ visibility: true }` was a
+     * documented no-op until it did. Otherwise the config's own visibility decides.
+     */
+    isFieldVisible(result: RuleEvaluationResult, field: NestedFieldConfig, names: readonly string[], values: Record<string, unknown>): boolean;
+    /** The same precedence for a tab. */
+    isTabVisible(result: RuleEvaluationResult, tab: NestedTabConfig): boolean;
+    /**
+     * Keep a hidden field's control out of form validity.
+     *
+     * A field hidden by a rule or a `showWhen` is filtered out of the render, but its
+     * validators stay attached — so a hidden *required* field holds `form.invalid` true
+     * forever, permanently disabling Save with nothing on screen to explain why.
+     *
+     * Disabling is the fix rather than stripping validators: Angular excludes disabled controls
+     * from validity, and the field's own validators survive intact for when it comes back.
+     * Values are untouched — a disabled control still carries its value, so rule evaluation and
+     * the emitted record see exactly what they saw before. That also keeps this from feeding
+     * back on itself: hiding a field cannot change the values the rules are evaluated over.
+     *
+     * The predicate is `isFieldVisible`, the same one the render filter uses, so what is on
+     * screen and what counts toward validity cannot drift apart.
+     *
+     * Entries must arrive parent-first, which is what `collectFieldScopes` yields: a container's
+     * children are skipped once the container itself is hidden, because Angular's `disable()`
+     * cascades to descendants and a child's `enable()` walks back up recalculating ancestors.
+     * Toggling a child inside a hidden group would fight its parent.
+     */
+    syncHiddenFieldState(entries: readonly FieldScopeEntry[], ctx: RuleSyncContext): void;
+    /**
+     * The hidden and shown names as sets, memoised against the result they came from.
+     *
+     * `isFieldVisible` runs once per field per change-detection pass; building two sets from
+     * two arrays each time turns a rule result into allocation proportional to the form. A
+     * `WeakMap` keyed by the result means it is built once per evaluation and collected with it.
+     */
+    private nameSets;
+    private readonly nameSetCache;
     static ɵfac: i0.ɵɵFactoryDeclaration<RulesEvaluationService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<RulesEvaluationService>;
 }
@@ -961,6 +1232,8 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     private readonly hookRegistry;
     private readonly rbacService;
     private readonly rulesEvaluation;
+    /** config ⇄ FormGroup: where a value lives. See `FormStructureService`. */
+    private readonly structure;
     /** Resolves what is wrong with a field, for the error summary — see `resolveForField`. */
     private readonly messages;
     private readonly entityRefSelection;
@@ -990,7 +1263,10 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     /** Previous values, for detecting `patchOnTrue` false→true transitions. */
     private previousValues;
     handleKeyboardEvent(event: KeyboardEvent): void;
-    readonly ruleResult: i0.Signal<RuleEvaluationResult>;
+    readonly ruleResult: i0.Signal<ngx_dynamic_entity.RuleEvaluationResult>;
+    /** Warned-about rule problems, per component instance — see `warnedAmbiguousIds`. */
+    private readonly warnedProblems;
+    private warnOnce;
     /**
      * Critical fields whose value differs from the session baseline.
      * These drive the deferred `VALUE_CHANGED` banner — a critical edit is announced once,
@@ -999,6 +1275,7 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     readonly changedCriticalFields: i0.Signal<NestedFieldConfig[]>;
     get tabs(): NestedTabConfig[];
     get visibleTabs(): NestedTabConfig[];
+    private isTabVisible;
     get activeTabConfig(): NestedTabConfig | null;
     get visibleSubTabs(): NestedTabConfig[];
     get activeSubTabConfig(): NestedTabConfig | null;
@@ -1018,6 +1295,12 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
     private readonly warnedSelectorModules;
     private warnSelectorModule;
     get fieldsForActiveTab(): NestedFieldConfig[];
+    /**
+     * Whether a field renders. Precedence lives in `RulesEvaluationService`, which is also
+     * what `syncHiddenFieldState` asks — so what is on screen and what counts toward validity
+     * cannot drift apart.
+     */
+    private isFieldVisible;
     /**
      * Entity-level permissions for the current roles.
      *
@@ -1159,6 +1442,14 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      * library never reaches for the global `document`.
      */
     jumpToField(fieldId: string): void;
+    /**
+     * Which tab (and sub-tab) holds a field.
+     *
+     * Descends into `group`/`array` children: this compared top-level fields only, so "jump to
+     * the first invalid field" found nothing for a nested one and silently did nothing. Only
+     * sub-tabs one level deep are named, because that is what the tab strip can select —
+     * anything deeper resolves to the ancestor it renders under.
+     */
     private locateField;
     /** A critical field stays read-only until the user deliberately unlocks it. */
     isFieldLocked(field: NestedFieldConfig): boolean;
@@ -1185,8 +1476,6 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      */
     changedCriticalFieldLabels(): string;
     private buildForm;
-    private buildFieldControl;
-    /** One row of an `array` field: a FormGroup when the field declares columns, else a bare control. */
     /**
      * The `FormArray` behind an `array` field, for callers that manage rows themselves —
      * the record editor's inline row drawer.
@@ -1223,9 +1512,8 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      * stay empty — with no error and no clue. That silent miss is the most expensive way to
      * lose an hour with this library, so name it in dev builds.
      *
-     * Only top-level keys that match a known field id are reported: anything else is assumed
-     * to be the consumer's own record metadata (ids, timestamps, `_configVersion`) and is not
-     * our business.
+     * Which keys were missed is `FormStructureService`'s answer; warning once per key per form
+     * is this component's, because it is the thing that lives as long as the form does.
      */
     private warnUnconsumedInitialData;
     /** Warn once per key per form instance — patchForm re-runs on every initialData change. */
@@ -1244,7 +1532,16 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      * consumers that never call the validator still get a signal in development.
      */
     private warnAmbiguousRuleReferences;
-    private static readonly warnedAmbiguousIds;
+    /**
+     * Ids already warned about, per component instance.
+     *
+     * This was `private static`, so it was module-global mutable state that nothing ever
+     * cleared: under SSR every render of every form in the process accumulated into one set
+     * that lived as long as the server did, and the first request to render a config
+     * suppressed the warning for every request after it. Per instance, the warning is once per
+     * form — which is what "warn once" was meant to mean.
+     */
+    private readonly warnedAmbiguousIds;
     /**
      * The value map rules and `showWhen` are evaluated against.
      *
@@ -1258,17 +1555,53 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      * unknown>` and needs no knowledge of refs at all — the extra keys simply resolve.
      */
     /**
-     * Whether a rule result names this field.
+     * Every name a rule may address this field by.
      *
      * A rule target is either a bare field id — how every config so far addresses a field — or
-     * a bracketed path, which is the only way to name one of two fields that share an id.
-     * Both have to match, or a rule written either way would fail to hide what it targeted.
+     * a bracketed path, which is the only way to name one of two fields that share an id. Both
+     * have to match, or a rule written either way would fail to hide what it targeted.
+     *
+     * The path comes last, and `syncHiddenFieldState` relies on that: it uses the last entry
+     * as the field's address when deciding whether a hidden container already covers it.
+     */
+    private namesOf;
+    /**
+     * The field's dotted address, unbracketed.
+     *
+     * The positional path rather than an authored `refererField`: this is compared as a prefix
+     * to decide whether a hidden container already covers a field, and containment is a fact
+     * about where the field *is*. A `refererField` is a binding override — it says where the
+     * value goes, not which group renders it.
      */
-    private namesField;
+    private addressOf;
     /** The field's declared path, or the one its position implies when it carries none. */
     private pathFor;
+    /**
+     * Every field in the config with the scope its value is stored under, cached per config.
+     *
+     * `collectFieldScopes` walks the whole tree. It was called once per field from `pathFor`,
+     * which `namesField` calls, which the render filter calls for every field on the active
+     * tab — a quadratic walk on every change-detection pass. Keyed by config identity, so a
+     * new config invalidates it without an explicit lifecycle hook to forget.
+     */
+    private fieldScopes;
+    private scopeEntryFor;
+    private scopeCache?;
+    /**
+     * The control a scope entry addresses, named by path rather than by bare id.
+     *
+     * `getControl(field.id)` with no tab falls through to a first-match recursive search of the
+     * whole form, so with `address` on two tabs, hiding one disabled the other. The control
+     * tree mirrors the scope path exactly — `buildTabControls` nests by tab id and
+     * `buildFieldControl` nests a `group` under its own id — so a `[path]` ref resolves through
+     * `form.get()` on `getControl`'s first branch and names exactly one control.
+     *
+     * A field inside an `array` has no static path: its controls live in `FormArray` rows built
+     * per row. `form.get()` returns null for those and they are left alone, which is correct —
+     * a row's controls are created and destroyed with the row.
+     */
+    private controlForEntry;
     private flattenFormValues;
-    private getTabGroup;
     /**
      * `autoPatch` — copy mapped fields out of the record the user just selected in an
      * entity-ref field into the configured target tab's controls.
@@ -1279,37 +1612,44 @@ declare class DynamicFormComponent implements OnInit, OnChanges, OnDestroy {
      * copy `from` → `to` within the current record.
      */
     private runPatchOnTrue;
-    /** Prefer a control declared on the configured target tab; fall back to a top-level control. */
-    private resolveTargetControl;
     /**
-     * The fields the render filter operates on — a tab's own fields, at every tab depth.
-     * Deliberately not `allFields()`: `group` and `array` children are shown or hidden with
-     * their parent, and toggling a child's state independently would fight the parent's.
+     * Prefer a control declared on the configured target tab; fall back to a top-level control.
+     *
+     * "Declared on the tab" now means anywhere under it, sub-tabs and `group` children
+     * included. It meant the tab's own top-level fields only, so an `autoPatch` mapping onto a
+     * field inside a group resolved to `null` and copied nothing, silently.
      */
-    private tabFields;
+    private resolveTargetControl;
     /**
-     * Keep a hidden field's control out of form validity.
-     *
-     * A field hidden by a rule or a `showWhen` condition is filtered out of the render, but
-     * its validators stay attached — so a hidden *required* field holds `form.invalid` true
-     * forever, permanently disabling Save with nothing on screen to explain why.
-     *
-     * Disabling is the fix rather than stripping validators: Angular excludes disabled
-     * controls from validity, and the field's own validators survive intact for when it
-     * comes back. Values are untouched — `flattenFormValues` and `extractRecord` both read
-     * `control.value`, which a disabled control still carries, so rule evaluation and the
-     * emitted record see exactly what they saw before. That also keeps this from feeding
-     * back on itself: hiding a field cannot change the values the rules are evaluated over.
+     * Keep a hidden field's control out of form validity — see
+     * `RulesEvaluationService.syncHiddenFieldState`, which owns the rule and the reasoning.
      *
-     * The visibility predicate is the same one `fieldsForActiveTab` filters with, so what is
-     * rendered and what counts toward validity cannot drift apart.
+     * This supplies the three things it cannot know: which fields exist and in what order
+     * (`collectFieldScopes`, parent-first), what each one is called, and which control each
+     * one addresses.
      */
     private syncHiddenFieldState;
     /** Every field in the config, including `group`/`array` children. */
     private allFields;
     /** An empty `originalData` counts as "not supplied" — fall back to the captured baseline. */
     private baseline;
+    /**
+     * Whether a critical field still holds what it held when the session started.
+     *
+     * The same question `VALUE_CHANGED` asks, so it is answered by the same comparator rather
+     * than by a third one. The local version compared objects through `JSON.stringify`, which
+     * is key-order sensitive — two serialisers writing the same option in a different key
+     * order made the field read as edited — and had its own idea of which values count as
+     * empty. `valuesEqual` is order-independent and treats `null` and `undefined` as the same
+     * absence; the empty-string case is kept here, because a cleared text input is not an edit.
+     */
     private sameValue;
+    /**
+     * Find a control by a bracketed path or a bare field id.
+     *
+     * Public API, so it stays on the component and delegates — see `FormStructureService`,
+     * which owns the resolution rule and is where the behaviour is documented.
+     */
     getControl(fieldId: string, currentTabId?: string): AbstractControl | null;
     /**
      * Move focus into the newly shown panel.
@@ -1432,7 +1772,7 @@ declare class DynamicRecordFormComponent implements OnChanges {
      * building a row's FormGroup inside the tab view races the tab's own initialisation, so
      * the row form is kept detached and only pushed into the FormArray on save.
      */
-    readonly inlineRowField: i0.WritableSignal<any>;
+    readonly inlineRowField: i0.WritableSignal<NestedFieldConfig>;
     readonly inlineRowIndex: i0.WritableSignal<number>;
     inlineRowForm: FormGroup | null;
     /** `array` fields on the tab currently shown, so the template can list their rows. */
@@ -1667,6 +2007,376 @@ declare class DynamicFieldComponent implements OnChanges, OnDestroy {
     static ɵcmp: i0.ɵɵComponentDeclaration<DynamicFieldComponent, "ngx-dynamic-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "config": { "alias": "config"; "required": false; }; "currentTabId": { "alias": "currentTabId"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "userRoles": { "alias": "userRoles"; "required": false; }; }, {}, never, never, true, never>;
 }
 
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+declare const defaultSheetParser: SheetParser;
+
+declare class LocalImportTransport implements ImportTransport {
+    private readonly registered;
+    /**
+     * 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.
+     */
+    private readonly parsed;
+    /** The registered parser, or the built-in CSV one. */
+    private read;
+    preview(file: File, context: ImportContext): Promise<ImportPreview>;
+    commit(file: File, plan: MappingPlan, context: ImportContext): Promise<ImportResult>;
+    template(spec: TemplateSpec, format: TemplateFormat): Promise<Blob>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<LocalImportTransport, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<LocalImportTransport>;
+}
+
+/**
+ * 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.
+ */
+
+interface HttpImportTransportOptions {
+    /** Where the router is mounted, e.g. `/api/import`. A trailing slash is ignored. */
+    baseUrl: string;
+    /** Supply one to add interceptors, retries, or credentials. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Headers on every request — an `Authorization`, a tenant id. Never a `Content-Type`. */
+    headers?: Record<string, string> | (() => Record<string, string>);
+    /**
+     * Where a warning goes. Defaults to `console.warn`.
+     *
+     * There is exactly one warning, and it is the engine-version mismatch below — which is a
+     * developer's problem, not a user's, so it does not belong in the wizard's error banner.
+     */
+    warn?: (message: string) => void;
+}
+/**
+ * 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.
+ */
+declare class HttpImportTransport implements ImportTransport {
+    private readonly options;
+    constructor(options: HttpImportTransportOptions);
+    private get base();
+    private get send();
+    private entityOf;
+    /**
+     * 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.
+     */
+    private checkEngine;
+    preview(file: File, context: ImportContext): Promise<ImportPreview>;
+    commit(file: File, plan: MappingPlan, context: ImportContext): Promise<ImportResult>;
+    template(spec: TemplateSpec, format: TemplateFormat, context: ImportContext, fields?: readonly string[]): Promise<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.
+ */
+declare function provideHttpImportTransport(options: HttpImportTransportOptions): Provider;
+
+type Step = 'upload' | 'map' | 'review' | 'done';
+/**
+ * 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.
+ */
+declare class EntityImportComponent {
+    config: EntityFormConfig;
+    /**
+     * 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?: readonly FormRule[];
+    /**
+     * 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?: ImportLookups;
+    language: string;
+    /** Format asked of the transport when a template is downloaded. */
+    templateFormat: TemplateFormat;
+    /** The finished import, once it has run. */
+    readonly importComplete: EventEmitter<ImportResult>;
+    /** A template the transport produced, for a host that would rather save it its own way. */
+    readonly templateReady: EventEmitter<Blob>;
+    protected readonly ui: UiTextService;
+    protected readonly steps: Step[];
+    protected readonly step: i0.WritableSignal<Step>;
+    protected readonly busy: i0.WritableSignal<boolean>;
+    protected readonly problem: i0.WritableSignal<string>;
+    protected readonly headers: i0.WritableSignal<string[]>;
+    protected readonly sample: i0.WritableSignal<string[][]>;
+    protected readonly rowCount: i0.WritableSignal<number>;
+    protected readonly fileName: i0.WritableSignal<string>;
+    protected readonly plan: i0.WritableSignal<MappingPlan>;
+    protected readonly result: i0.WritableSignal<ImportResult>;
+    private readonly registered;
+    private readonly local;
+    private readonly lookupRegistry;
+    private file;
+    /** Named lists resolved from `LOOKUP_REGISTRY`, merged under the `lookups` input. */
+    protected readonly resolvedLookups: i0.WritableSignal<ImportLookups>;
+    private get transport();
+    private context;
+    /**
+     * 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.
+     */
+    private loadLookups;
+    protected stepLabel(step: Step): string;
+    protected chooseFile(event: Event): Promise<void>;
+    protected commit(): Promise<void>;
+    protected downloadTemplate(fields: string[]): Promise<void>;
+    /**
+     * 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.
+     */
+    protected importedCount(result: ImportResult): number;
+    /**
+     * 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.
+     */
+    protected failedRowCount(result: ImportResult): number;
+    protected restart(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EntityImportComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EntityImportComponent, "ngx-entity-import", never, { "config": { "alias": "config"; "required": true; }; "rules": { "alias": "rules"; "required": false; }; "lookups": { "alias": "lookups"; "required": false; }; "language": { "alias": "language"; "required": false; }; "templateFormat": { "alias": "templateFormat"; "required": false; }; }, { "importComplete": "importComplete"; "templateReady": "templateReady"; }, never, never, true, never>;
+}
+
+/** One target field, and which of the sheet's columns feeds it. */
+interface MappingRow {
+    column: ImportColumn;
+    /** Index into the sheet's headers, or `null` for "not imported". */
+    source: number | null;
+    guessed: boolean;
+}
+/**
+ * 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.
+ */
+declare class ImportMapperComponent implements OnChanges {
+    config: EntityFormConfig;
+    headers: readonly string[];
+    /** The starting point, normally `suggestMapping`'s output. */
+    plan: MappingPlan | null;
+    language: string;
+    /** Emitted whenever the user changes a selection. */
+    readonly planChange: EventEmitter<MappingPlan>;
+    protected readonly ui: UiTextService;
+    protected readonly rows: i0.WritableSignal<MappingRow[]>;
+    /**
+     * 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.
+     */
+    protected readonly unsupported: i0.WritableSignal<number>;
+    ngOnChanges(): void;
+    protected mappedCount(): number;
+    protected missingRequired(): number;
+    protected choose(row: MappingRow, source: number | null): void;
+    /** The current selections as the plan that will be applied. */
+    private toPlan;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ImportMapperComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ImportMapperComponent, "ngx-import-mapper", never, { "config": { "alias": "config"; "required": true; }; "headers": { "alias": "headers"; "required": false; }; "plan": { "alias": "plan"; "required": false; }; "language": { "alias": "language"; "required": false; }; }, { "planChange": "planChange"; }, never, never, true, never>;
+}
+
+/** One cell, already turned into the text the record will show. */
+interface PreviewCell {
+    text: string;
+    failed: boolean;
+}
+/** A row of cells, plus why the import will refuse it — if it will. */
+interface PreviewRow {
+    cells: PreviewCell[];
+    /** Empty when the row will be imported. */
+    rejections: string[];
+}
+/**
+ * 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.
+ */
+declare class ImportPreviewComponent implements OnChanges {
+    config: EntityFormConfig;
+    plan: MappingPlan;
+    rows: readonly (readonly string[])[];
+    lookups?: ImportLookups;
+    /** The same rules the commit will apply; without them a rule-driven rejection is invisible. */
+    rules?: readonly FormRule[];
+    language: string;
+    protected readonly ui: UiTextService;
+    /** The columns this plan fills, in the plan's own order. */
+    protected readonly columns: i0.WritableSignal<ImportColumn[]>;
+    protected readonly grid: i0.WritableSignal<PreviewRow[]>;
+    ngOnChanges(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ImportPreviewComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ImportPreviewComponent, "ngx-import-preview", never, { "config": { "alias": "config"; "required": true; }; "plan": { "alias": "plan"; "required": true; }; "rows": { "alias": "rows"; "required": false; }; "lookups": { "alias": "lookups"; "required": false; }; "rules": { "alias": "rules"; "required": false; }; "language": { "alias": "language"; "required": false; }; }, {}, never, never, true, never>;
+}
+
+/** One field offered for the template, with the guidance that belongs to it. */
+interface TemplateChoice {
+    /** The ref with any row number removed, so a repeating field is offered once. */
+    ref: string;
+    header: string;
+    note: string;
+    selected: boolean;
+}
+/**
+ * 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.
+ */
+declare class ImportTemplateComponent implements OnChanges {
+    config: EntityFormConfig;
+    language: string;
+    /** The refs to include, with row numbers stripped — the caller builds the spec. */
+    readonly download: EventEmitter<string[]>;
+    protected readonly ui: UiTextService;
+    protected readonly choices: i0.WritableSignal<TemplateChoice[]>;
+    protected readonly unsupported: i0.WritableSignal<UnsupportedColumn[]>;
+    ngOnChanges(): void;
+    protected selectedCount(): number;
+    protected selectedRefs(): string[];
+    protected toggle(ref: string): void;
+    protected selectAll(selected: boolean): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ImportTemplateComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ImportTemplateComponent, "ngx-import-template", never, { "config": { "alias": "config"; "required": true; }; "language": { "alias": "language"; "required": false; }; }, { "download": "download"; }, never, never, true, never>;
+}
+
+/**
+ * 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.
+ */
+declare class ImportErrorsComponent {
+    errors: readonly ImportRowError[];
+    language: string;
+    protected readonly ui: UiTextService;
+    /** Row number → its problems, in the order the rows appear in the file. */
+    protected grouped(): {
+        row: number;
+        problems: ImportRowError[];
+    }[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<ImportErrorsComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ImportErrorsComponent, "ngx-import-errors", never, { "errors": { "alias": "errors"; "required": false; }; "language": { "alias": "language"; "required": false; }; }, {}, never, never, true, never>;
+}
+
 /**
  * What a field component must accept to be registered with `provideFieldTypes`.
  *
@@ -1745,7 +2455,7 @@ declare function fieldDomId(field: {
  * is read first. `null` rather than an empty string when there is nothing to describe — an
  * empty `aria-describedby` is a dangling reference, not an absent one.
  *
- * Shared rather than written into each of the nineteen field components, because the rule is
+ * Shared rather than written into each of the twenty-one field components, because the rule is
  * the same everywhere and getting it wrong is invisible until somebody uses a screen reader.
  */
 declare function fieldDescribedBy(domId: (suffix?: string) => string, parts: {
@@ -1876,7 +2586,14 @@ declare class MarkdownFieldComponent implements OnChanges {
      * A renderer is consumer code and may throw on input it does not like. Letting that
      * escape would take down the whole form over one malformed field, so it falls back to the
      * source text — which is what the field would have shown with no renderer at all.
+     *
+     * Memoised on the source, because this is called from the template: without it the
+     * consumer's markdown parser ran on every change-detection pass, for every markdown field
+     * on screen, over the whole document — which on a form holding a few long ones is a parse
+     * per keystroke *elsewhere* in the form. The cache is keyed by the exact source string,
+     * so a value that comes back to something already rendered is free too.
      */
+    private cached?;
     protected rendered(): string | null;
     /**
      * Resolved through `ValidationMessagesService`, so `provideNgxDynamicEntity({
@@ -2317,6 +3034,15 @@ declare class DropdownFieldComponent {
     isObjectVal(option: DropdownOption): boolean;
     get label(): string;
     get placeholder(): string;
+    /**
+     * The value this option stores — the option object itself.
+     *
+     * Kept as a method rather than binding `option` straight into the template, because it is
+     * the one place that says *why* the two are the same thing. It used to delegate to
+     * `getOptionStoredValue`, an exported identity function whose two branches returned their
+     * argument unchanged; naming a transformation that does not happen is worse than naming
+     * nothing, because a reader has to go and check.
+     */
     getOptStoredVal(option: DropdownOption): unknown;
     getOptLabel(option: DropdownOption): string;
     /**
@@ -2359,6 +3085,15 @@ declare class RadioFieldComponent {
     /** Inline `options`, or the field's named list resolved through the registry (§6.3). */
     readonly options: i0.WritableSignal<DropdownOption[]>;
     get label(): string;
+    /**
+     * The value this option stores — the option object itself.
+     *
+     * Kept as a method rather than binding `option` straight into the template, because it is
+     * the one place that says *why* the two are the same thing. It used to delegate to
+     * `getOptionStoredValue`, an exported identity function whose two branches returned their
+     * argument unchanged; naming a transformation that does not happen is worse than naming
+     * nothing, because a reader has to go and check.
+     */
     getOptStoredVal(option: DropdownOption): unknown;
     /**
      * Stable DOM id for one radio, so the <label for> association works.
@@ -2419,6 +3154,15 @@ declare class MultiSelectFieldComponent {
     readonly compareFn: (o1: unknown, o2: unknown) => boolean;
     isObjectVal(option: DropdownOption): boolean;
     get label(): string;
+    /**
+     * The value this option stores — the option object itself.
+     *
+     * Kept as a method rather than binding `option` straight into the template, because it is
+     * the one place that says *why* the two are the same thing. It used to delegate to
+     * `getOptionStoredValue`, an exported identity function whose two branches returned their
+     * argument unchanged; naming a transformation that does not happen is worse than naming
+     * nothing, because a reader has to go and check.
+     */
     getOptStoredVal(option: DropdownOption): unknown;
     getOptLabel(option: DropdownOption): string;
     /** Read-only display — synchronous, per §6.2. See `DropdownFieldComponent.getLabel`. */
@@ -2641,5 +3385,5 @@ declare class FileFieldComponent {
     static ɵcmp: i0.ɵɵComponentDeclaration<FileFieldComponent, "ngx-file-field", never, { "field": { "alias": "field"; "required": false; }; "control": { "alias": "control"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; }, {}, never, never, true, never>;
 }
 
-export { ASYNC_VALIDATOR_REGISTRY, ArrayFieldComponent, BooleanFieldComponent, COMMON_MODULES_REGISTRY, CONFIG_SOURCE, CascadeDataService, CheckboxFieldComponent, ConfigSourceService, CurrencyFieldComponent, DEFAULT_UI_TEXT, DEFAULT_VALIDATION_MESSAGES, DateFieldComponent, DateTimeFieldComponent, DropdownFieldComponent, DynamicFieldComponent, DynamicFormComponent, DynamicRecordFormComponent, ENTITY_REF_CACHE_STORE, ENTITY_REF_REGISTRY, EmailFieldComponent, EntityRefFieldComponent, EntityRefRegistryService, EntityRefSelectionService, EntityReferenceService, FIELD_TYPE_REGISTRY, FIELD_TYPE_SETS, FieldRegistryService, FileFieldComponent, GroupFieldComponent, HOOK_REGISTRY, HookRegistryService, ImageFieldComponent, InMemoryEntityRefCacheStore, LOOKUP_REGISTRY, LookupRegistryService, MARKDOWN_RENDERER, MASKED_PLACEHOLDER, MASKED_ROLES, MarkdownFieldComponent, MonthYearFieldComponent, MultiSelectFieldComponent, NumberFieldComponent, PasswordFieldComponent, RECORD_MIGRATIONS, RadioFieldComponent, RbacService, RulesEvaluationService, SYSTEM_DEFAULT_CAN_EDIT, TextFieldComponent, TextareaFieldComponent, TimeFieldComponent, UI_TEXT, UPLOAD_HANDLER, UiTextService, VALIDATION_MESSAGES, VALIDATOR_REGISTRY, ValidationMessagesService, ValidatorRegistryService, builtInFieldTypes, fieldDescribedBy, fieldDomId, nextFieldInstanceId, provideBuiltInFieldTypes, provideFieldTypes, provideNgxDynamicEntity, refreshChoiceOptions, resolveUiText };
-export type { ChoiceOptionHost, ConfigSourceHandler, DynamicFieldComponentContract, EntityRefCacheStore, EntityRefSelection, HookFn, InvalidField, MessageOrderEntry, NgxDynamicEntityConfig, UiTextKey, UiTextOverrides, UiTextOverridesFor, UiTextParams, UiTextResolver, UiTextResolverFor, UiTextValue, ValidationMessage };
+export { ASYNC_VALIDATOR_REGISTRY, ArrayFieldComponent, BooleanFieldComponent, COMMON_MODULES_REGISTRY, CONFIG_SOURCE, CascadeDataService, CheckboxFieldComponent, ConfigSourceService, CurrencyFieldComponent, DEFAULT_UI_TEXT, DEFAULT_VALIDATION_MESSAGES, DateFieldComponent, DateTimeFieldComponent, DropdownFieldComponent, DynamicFieldComponent, DynamicFormComponent, DynamicRecordFormComponent, ENTITY_REF_CACHE_STORE, ENTITY_REF_REGISTRY, EmailFieldComponent, EntityImportComponent, EntityRefFieldComponent, EntityRefRegistryService, EntityRefSelectionService, EntityReferenceService, FIELD_TYPE_REGISTRY, FIELD_TYPE_SETS, FieldRegistryService, FileFieldComponent, GroupFieldComponent, HOOK_REGISTRY, HookRegistryService, HttpImportTransport, IMPORT_TRANSPORT, ImageFieldComponent, ImportErrorsComponent, ImportMapperComponent, ImportPreviewComponent, ImportTemplateComponent, InMemoryEntityRefCacheStore, LOOKUP_REGISTRY, LocalImportTransport, LookupRegistryService, MARKDOWN_RENDERER, MASKED_PLACEHOLDER, MASKED_ROLES, MarkdownFieldComponent, MonthYearFieldComponent, MultiSelectFieldComponent, NumberFieldComponent, PasswordFieldComponent, RECORD_MIGRATIONS, RadioFieldComponent, RbacService, RulesEvaluationService, SHEET_PARSER, SYSTEM_DEFAULT_CAN_EDIT, TextFieldComponent, TextareaFieldComponent, TimeFieldComponent, UI_TEXT, UPLOAD_HANDLER, UiTextService, VALIDATION_MESSAGES, VALIDATOR_REGISTRY, ValidationMessagesService, ValidatorRegistryService, builtInFieldTypes, defaultSheetParser, fieldDescribedBy, fieldDomId, nextFieldInstanceId, provideBuiltInFieldTypes, provideFieldTypes, provideHttpImportTransport, provideNgxDynamicEntity, refreshChoiceOptions, resolveUiText };
+export type { ChoiceOptionHost, ConfigSourceHandler, DynamicFieldComponentContract, EntityRefCacheStore, EntityRefSelection, HookFn, HttpImportTransportOptions, ImportContext, ImportPreview, ImportTransport, InvalidField, MessageOrderEntry, NgxDynamicEntityConfig, RuleSyncContext, SheetParser, TemplateFormat, UiTextKey, UiTextOverrides, UiTextOverridesFor, UiTextParams, UiTextResolver, UiTextResolverFor, UiTextValue, ValidationMessage };