ngx-dynamic-entity 2.5.0 → 3.0.0-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-dynamic-entity",
-  "version": "2.5.0",
+  "version": "3.0.0-rc.2",
   "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.5.0",
+    "@dynamic-entity/core": "^3.0.0-rc.2",
     "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, DateOrder, 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.
@@ -239,6 +240,10 @@ declare class UiTextService {
  * text is whatever a library's formatter printed. A parser returning text (`SheetData`, as 2.2's
  * did) still fits.
  *
+ * Covered cells of a merged range are `''` (as the server reader emits). The master cell at
+ * the top-left of the range holds the value; every covered cell must be `''`, never repeating
+ * the master value and never omitted.
+ *
  * The library ships a delimited-text reader 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.
@@ -247,6 +252,7 @@ declare class UiTextService {
  * // SheetJS 0.20.3+ from https://cdn.sheetjs.com — the npm `xlsx` package stopped at 0.18.5,
  * // which has known vulnerabilities. `UTC: true` matters: without it a date cell arrives at
  * // *local* midnight, which is the previous day in UTC for anyone east of Greenwich.
+ * // `defval: ''` ensures covered cells of merged ranges are `''`, matching the server reader.
  * provideNgxDynamicEntity({
  *   sheetParser: async file => {
  *     const workbook = XLSX.read(await file.arrayBuffer(), { cellDates: true });
@@ -290,7 +296,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;
     /**
@@ -335,7 +341,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.
      *
@@ -481,11 +487,11 @@ declare const UPLOAD_HANDLER: InjectionToken<FileUploadHandler>;
  * @example
  * provideNgxDynamicEntity({
  *   sheetParser: async file => {
- *     const wb = XLSX.read(await file.arrayBuffer());
+ *     const wb = XLSX.read(await file.arrayBuffer(), { cellDates: true });
  *     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) };
+ *       header: 1, raw: true, defval: '', UTC: true,
+ *     }) as unknown[][];
+ *     return { headers: (rows[0] ?? []).map(cellText), rows: rows.slice(1) };
  *   },
  * })
  */
@@ -2087,8 +2093,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>;
@@ -2117,8 +2129,9 @@ 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;
 }
@@ -2129,6 +2142,12 @@ declare class HttpImportTransport implements ImportTransport {
      * 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;
     /**
@@ -2149,8 +2168,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>;
 }
 /**
@@ -2222,11 +2248,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;
@@ -2322,11 +2348,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[]>;
     /**
@@ -2338,7 +2364,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;
@@ -2369,6 +2395,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>;
@@ -2411,7 +2441,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. */