ngx-dynamic-entity 2.4.1 → 3.0.0-rc.1

package/package.json

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

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

@@ -1,10 +1,11 @@
 import * as i0 from '@angular/core';
 import { InjectionToken, Type, EnvironmentProviders, WritableSignal, OnInit, OnChanges, OnDestroy, EventEmitter, SimpleChanges, Provider } from '@angular/core';
-import { ReferenceOption, LocalizedText, EntityFormConfig, FormRule, ImportLookups, MappingPlan, CsvDelimiter, ImportResult, TemplateSpec, SheetGrid, CommonModuleEntry, EntityReferenceLoader, LookupListSource, RecordMigration, FileUploadHandler, FieldValidators, NestedFieldConfig, ReferenceLoaderContext, DropdownOption, LookupListValue, NestedTabConfig, RuleEvaluationResult, FieldScopeEntry, EvaluateFormRulesOptions, ImportColumn, MappingEntry, UnsupportedColumn, ImportRowError, SliderBounds } from '@dynamic-entity/core';
+import { ReferenceOption, LocalizedText, EntityFormConfig, FormRule, ImportLookups, DateOrder, AnyMappingPlan, CsvDelimiter, ImportResult, TemplateSpec, SheetGrid, CommonModuleEntry, EntityReferenceLoader, LookupListSource, RecordMigration, FileUploadHandler, FieldValidators, NestedFieldConfig, ReferenceLoaderContext, DropdownOption, LookupListValue, NestedTabConfig, RuleEvaluationResult, FieldScopeEntry, EvaluateFormRulesOptions, MappingPlan, ImportColumn, MappingEntry, UnsupportedColumn, ImportRowError, SliderBounds } 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, AbstractControl, ValidationErrors, FormGroup, FormArray } from '@angular/forms';
 import * as rxjs from 'rxjs';
 import * as ngx_dynamic_entity from 'ngx-dynamic-entity';
+import * as sheet_to_schema from 'sheet-to-schema';
 
 /**
  * Backing store for cached reference options.
@@ -129,6 +130,8 @@ declare const DEFAULT_UI_TEXT: {
     importDelimiterComma: string;
     importDelimiterSemicolon: string;
     importDelimiterTab: string;
+    importDateOrderMismatch: string;
+    importDateOrderUnconfirmed: string;
     importRowRejected: string;
     importRunImport: string;
     importImporting: string;
@@ -272,6 +275,15 @@ interface ImportContext {
     /** Values for any `listName` field, already resolved — core cannot reach `LOOKUP_REGISTRY`. */
     lookups?: ImportLookups;
     lang?: string;
+    /**
+     * The order of a date written in digits, such as `05/09/2026`: `DMY` for day first, `MDY`
+     * for month first. Without it, a date that reads two ways fails its row; it is never guessed.
+     *
+     * The local transport reads cells with it. A server transport reads with whatever its own
+     * router was given, so state the same order on both, or the review step shows one reading
+     * and the server stores another.
+     */
+    dateOrder?: DateOrder;
 }
 /** What a first look at an uploaded file yields. */
 interface ImportPreview {
@@ -279,7 +291,7 @@ interface ImportPreview {
     /** 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;
+    suggestion: AnyMappingPlan;
     /** Total data rows in the file, which may be far more than `sample` holds. */
     rowCount: number;
     /**
@@ -289,7 +301,26 @@ interface ImportPreview {
     arrayBound?: number;
     /** The field separator a delimited-text file used. Absent for a workbook. */
     delimiter?: CsvDelimiter;
+    /**
+     * The order this transport will read a date written in digits in when it commits. Absent
+     * when it will read with none, or cannot say.
+     *
+     * The wizard reads the review sample with it, so the review shows what the commit will
+     * store. When the host stated a different order the wizard refuses to commit, and when the
+     * host stated one and the transport reports none it warns.
+     */
+    dateOrder?: DateOrder;
 }
+/**
+ * How the order the host states compares with the one the transport reports it reads with.
+ *
+ * - `mismatch`: both state one and they differ. Committing would store dates read one way
+ *   after a review that showed them the other, so nothing may be committed.
+ * - `unconfirmed`: the host states one and the transport reports none. The transport reads the
+ *   file, so the host's order is not applied: worth a warning, not a refusal.
+ * - `agreed`: anything else. Only the transport stating one is fine: it is the one that reads.
+ */
+declare function compareDateOrders(stated: DateOrder | undefined, reported: DateOrder | undefined): 'agreed' | 'mismatch' | 'unconfirmed';
 /**
  * Where the work happens.
  *
@@ -305,7 +336,7 @@ 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>;
+    commit(file: File, plan: AnyMappingPlan, context: ImportContext): Promise<ImportResult>;
     /**
      * Render a template for download.
      *
@@ -2057,8 +2088,14 @@ declare class LocalImportTransport implements ImportTransport {
     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>;
+    /**
+     * The suggestion made here is always plan v2, and the return type says so. The contract's is
+     * a plan in either shape, because a 2.x server sends the older one.
+     */
+    preview(file: File, context: ImportContext): Promise<ImportPreview & {
+        suggestion: MappingPlan;
+    }>;
+    commit(file: File, plan: AnyMappingPlan, context: ImportContext): Promise<ImportResult>;
     template(spec: TemplateSpec, format: TemplateFormat): Promise<Blob>;
     static ɵfac: i0.ɵɵFactoryDeclaration<LocalImportTransport, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<LocalImportTransport>;
@@ -2087,21 +2124,33 @@ interface HttpImportTransportOptions {
     /**
      * 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.
+     * What is warned about is the two deploys having moved apart: the engine version, the
+     * adapter, the date order the server did not confirm. Those are a developer's problem, not
+     * a user's, so they do 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;
+    /**
+     * The date order each previewed file's server reported, for `commit` to compare against.
+     * Keyed on the `File`, so it lives exactly as long as the file does.
+     */
+    private readonly reported;
+    /**
+     * The plan versions each previewed file's server said it reads. A file with no entry was
+     * never previewed here, and one whose server said nothing is from before plan v2: either
+     * way `commit` sends nothing that only a v2 reader would understand.
+     */
+    private readonly planVersions;
     constructor(options: HttpImportTransportOptions);
+    private warn;
+    /**
+     * The server reads the file, so its date order is the one that is applied. When the host
+     * stated one and the server confirms none, the host's order does nothing there: say so, and
+     * say what the server will do instead, which depends on how old it is.
+     */
+    private checkDateOrder;
     private get base();
     private get send();
     private entityOf;
@@ -2114,8 +2163,15 @@ declare class HttpImportTransport implements ImportTransport {
      * patch release is not a reason to stop somebody importing.
      */
     private checkEngine;
+    /**
+     * Warn when the server runs another adapter, or this one at another major version.
+     *
+     * Since 3.0 a server says which adapter turned its rows into records. A server from before
+     * that says nothing, and `checkEngine` has already compared the one version it does report.
+     */
+    private checkAdapter;
     preview(file: File, context: ImportContext): Promise<ImportPreview>;
-    commit(file: File, plan: MappingPlan, context: ImportContext): Promise<ImportResult>;
+    commit(file: File, plan: AnyMappingPlan, context: ImportContext): Promise<ImportResult>;
     template(spec: TemplateSpec, format: TemplateFormat, context: ImportContext, fields?: readonly string[]): Promise<Blob>;
 }
 /**
@@ -2162,6 +2218,16 @@ declare class EntityImportComponent {
      */
     lookups?: ImportLookups;
     language: string;
+    /**
+     * The order of a date written in digits in the sheets this wizard imports: `DMY` for day
+     * first, `MDY` for month first. Without it, a date that reads two ways (`05/09/2026`) is
+     * shown, and imported, as an error rather than guessed.
+     *
+     * The transport reads the file, so the order it reports at preview is the one applied, and
+     * the one the review step shows. If that differs from this, the wizard refuses to commit;
+     * if the transport reports none, the wizard warns that this order is not being applied.
+     */
+    dateOrder?: DateOrder;
     /** Format asked of the transport when a template is downloaded. */
     templateFormat: TemplateFormat;
     /** The finished import, once it has run. */
@@ -2177,9 +2243,11 @@ declare class EntityImportComponent {
     protected readonly sample: i0.WritableSignal<string[][]>;
     protected readonly rowCount: i0.WritableSignal<number>;
     /** The separator a delimited file turned out to use, so the user can see how it was read. */
-    protected readonly delimiter: i0.WritableSignal<CsvDelimiter>;
+    protected readonly delimiter: i0.WritableSignal<sheet_to_schema.CsvDelimiter>;
+    /** The date order the transport said it will read with at commit, from its preview. */
+    protected readonly reportedDateOrder: i0.WritableSignal<DateOrder>;
     protected readonly fileName: i0.WritableSignal<string>;
-    protected readonly plan: i0.WritableSignal<MappingPlan>;
+    protected readonly plan: i0.WritableSignal<AnyMappingPlan>;
     protected readonly result: i0.WritableSignal<ImportResult>;
     private readonly registered;
     private readonly local;
@@ -2229,13 +2297,20 @@ declare class EntityImportComponent {
      * exact and `failed` is absent.
      */
     protected failedRowCount(result: ImportResult): number;
+    /** How the order the host states compares with the one the transport reads with. */
+    protected dateOrderCheck(): 'agreed' | 'mismatch' | 'unconfirmed';
+    /** The two orders, for a message that names them. Only asked for when they do not agree. */
+    protected dateOrders(): {
+        stated: string;
+        reported: string;
+    };
     /** The decimal mark the commit will read numbers with, so the preview reads them the same. */
     protected decimal(): '.' | ',';
     /** How the file's columns were split, in words — or nothing for a workbook. */
     protected delimiterText(): string | null;
     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>;
+    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; }; "dateOrder": { "alias": "dateOrder"; "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. */
@@ -2268,11 +2343,11 @@ interface ArraySlots {
 declare class ImportMapperComponent implements OnChanges {
     config: EntityFormConfig;
     headers: readonly string[];
-    /** The starting point, normally `suggestMapping`'s output. */
-    plan: MappingPlan | null;
+    /** The starting point, normally `suggestMapping`'s output. A stored 2.x plan is taken too. */
+    plan: AnyMappingPlan | null;
     language: string;
-    /** Emitted whenever the user changes a selection. */
-    readonly planChange: EventEmitter<MappingPlan>;
+    /** Emitted whenever the user changes a selection. Always plan v2, whichever shape came in. */
+    readonly planChange: EventEmitter<sheet_to_schema.MappingPlan>;
     protected readonly ui: UiTextService;
     protected readonly rows: i0.WritableSignal<MappingRow[]>;
     /**
@@ -2284,7 +2359,7 @@ declare class ImportMapperComponent implements OnChanges {
      */
     protected readonly unsupported: i0.WritableSignal<number>;
     /** A plan entry whose field this config no longer has. Kept, and emitted, until removed. */
-    protected readonly stale: i0.WritableSignal<MappingEntry[]>;
+    protected readonly stale: i0.WritableSignal<sheet_to_schema.MappingEntry[]>;
     /** Repeating fields the user can add a row to. */
     protected readonly arrays: i0.WritableSignal<ArraySlots[]>;
     protected readonly constant = -1;
@@ -2315,6 +2390,10 @@ declare class ImportMapperComponent implements OnChanges {
      * Every entry of the incoming plan survives in its own position — a fixed value, a ref the
      * config no longer has — unless the user changed or removed it, and an untouched entry is
      * emitted exactly as it arrived. New selections follow, in field order.
+     *
+     * What is emitted is plan v2, whichever shape came in: `target` and `schemaVersion`, where a
+     * 2.x plan said `entity` and `configVersion`. Anything else the incoming plan carried, such
+     * as its lists and its grouping, is kept.
      */
     private toPlan;
     static ɵfac: i0.ɵɵFactoryDeclaration<ImportMapperComponent, never>;
@@ -2357,7 +2436,7 @@ interface PreviewRow {
  */
 declare class ImportPreviewComponent implements OnChanges {
     config: EntityFormConfig;
-    plan: MappingPlan;
+    plan: AnyMappingPlan;
     rows: readonly (readonly string[])[];
     lookups?: ImportLookups;
     /** The same rules the commit will apply; without them a rule-driven rejection is invisible. */
@@ -2365,13 +2444,15 @@ declare class ImportPreviewComponent implements OnChanges {
     language: string;
     /** The decimal mark number cells use — the one the commit will read them with. */
     decimal: '.' | ',';
+    /** The order of a date written in digits — the one the commit will read them in. */
+    dateOrder?: DateOrder;
     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; }; "decimal": { "alias": "decimal"; "required": false; }; }, {}, never, never, true, 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; }; "decimal": { "alias": "decimal"; "required": false; }; "dateOrder": { "alias": "dateOrder"; "required": false; }; }, {}, never, never, true, never>;
 }
 
 /** One field offered for the template, with the guidance that belongs to it. */
@@ -3607,5 +3688,5 @@ declare class TagsFieldComponent implements OnDestroy {
     static ɵcmp: i0.ɵɵComponentDeclaration<TagsFieldComponent, "ngx-tags-field", never, { "field": { "alias": "field"; "required": false; }; "language": { "alias": "language"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "masked": { "alias": "masked"; "required": false; }; "control": { "alias": "control"; "required": false; }; }, {}, never, never, true, never>;
 }
 
-export { ASYNC_VALIDATOR_REGISTRY, ArrayFieldComponent, BooleanFieldComponent, COMMON_MODULES_REGISTRY, CONFIG_SOURCE, CascadeDataService, CheckboxFieldComponent, ColorFieldComponent, 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, PhoneFieldComponent, RECORD_MIGRATIONS, RadioFieldComponent, RatingFieldComponent, RbacService, RulesEvaluationService, SHEET_PARSER, SYSTEM_DEFAULT_CAN_EDIT, SliderFieldComponent, TagsFieldComponent, TextFieldComponent, TextareaFieldComponent, TimeFieldComponent, UI_TEXT, UPLOAD_HANDLER, UiTextService, UrlFieldComponent, VALIDATION_MESSAGES, VALIDATOR_REGISTRY, ValidationMessagesService, ValidatorRegistryService, builtInFieldTypes, defaultSheetParser, fieldDescribedBy, fieldDomId, nextFieldInstanceId, phoneValidator, provideBuiltInFieldTypes, provideFieldTypes, provideHttpImportTransport, provideNgxDynamicEntity, refreshChoiceOptions, resolveUiText, urlValidator };
+export { ASYNC_VALIDATOR_REGISTRY, ArrayFieldComponent, BooleanFieldComponent, COMMON_MODULES_REGISTRY, CONFIG_SOURCE, CascadeDataService, CheckboxFieldComponent, ColorFieldComponent, 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, PhoneFieldComponent, RECORD_MIGRATIONS, RadioFieldComponent, RatingFieldComponent, RbacService, RulesEvaluationService, SHEET_PARSER, SYSTEM_DEFAULT_CAN_EDIT, SliderFieldComponent, TagsFieldComponent, TextFieldComponent, TextareaFieldComponent, TimeFieldComponent, UI_TEXT, UPLOAD_HANDLER, UiTextService, UrlFieldComponent, VALIDATION_MESSAGES, VALIDATOR_REGISTRY, ValidationMessagesService, ValidatorRegistryService, builtInFieldTypes, compareDateOrders, defaultSheetParser, fieldDescribedBy, fieldDomId, nextFieldInstanceId, phoneValidator, provideBuiltInFieldTypes, provideFieldTypes, provideHttpImportTransport, provideNgxDynamicEntity, refreshChoiceOptions, resolveUiText, urlValidator };
 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 };