ngx-dynamic-entity 1.12.0 → 1.14.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, 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 * 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.
@@ -539,7 +724,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 +733,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 +748,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 +773,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 +788,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 +822,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.
@@ -785,7 +970,7 @@ 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>): RuleEvaluationResult;
     /**
      * Filter rules pertinent to a single tab.
      */
@@ -990,7 +1175,7 @@ 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>;
     /**
      * Critical fields whose value differs from the session baseline.
      * These drive the deferred `VALUE_CHANGED` banner — a critical edit is announced once,
@@ -1432,7 +1617,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 +1852,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`.
  *
@@ -2312,7 +2867,7 @@ declare class DropdownFieldComponent {
     readonly: boolean;
     masked: boolean;
     /** Inline `options`, or the field's named list resolved through the registry (§6.3). */
-    readonly options: i0.WritableSignal<DropdownOption[]>;
+    readonly options: i0.WritableSignal<ngx_dynamic_entity.LocalizedText[]>;
     readonly compareFn: (o1: unknown, o2: unknown) => boolean;
     isObjectVal(option: DropdownOption): boolean;
     get label(): string;
@@ -2357,7 +2912,7 @@ declare class RadioFieldComponent {
     readonly: boolean;
     masked: boolean;
     /** Inline `options`, or the field's named list resolved through the registry (§6.3). */
-    readonly options: i0.WritableSignal<DropdownOption[]>;
+    readonly options: i0.WritableSignal<ngx_dynamic_entity.LocalizedText[]>;
     get label(): string;
     getOptStoredVal(option: DropdownOption): unknown;
     /**
@@ -2415,7 +2970,7 @@ declare class MultiSelectFieldComponent {
     readonly: boolean;
     masked: boolean;
     /** Inline `options`, or the field's named list resolved through the registry (§6.3). */
-    readonly options: i0.WritableSignal<DropdownOption[]>;
+    readonly options: i0.WritableSignal<ngx_dynamic_entity.LocalizedText[]>;
     readonly compareFn: (o1: unknown, o2: unknown) => boolean;
     isObjectVal(option: DropdownOption): boolean;
     get label(): string;
@@ -2641,5 +3196,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, SheetParser, TemplateFormat, UiTextKey, UiTextOverrides, UiTextOverridesFor, UiTextParams, UiTextResolver, UiTextResolverFor, UiTextValue, ValidationMessage };