ngx-dynamic-entity 2.2.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-dynamic-entity",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "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.2.0",
+    "@dynamic-entity/core": "^2.3.0",
     "rxjs": "^7.0.0"
   },
   "keywords": [
@@ -31,6 +31,9 @@
   "author": "Nizamudeen",
   "module": "fesm2022/ngx-dynamic-entity.mjs",
   "exports": {
+    "./styles.css": {
+      "default": "./styles.css"
+    },
     "./package.json": {
       "default": "./package.json"
     },
@@ -43,4 +46,4 @@
   "dependencies": {
     "tslib": "^2.3.0"
   }
-}
+}

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

@@ -1,6 +1,6 @@
 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, ImportResult, TemplateSpec, SheetData, CommonModuleEntry, EntityReferenceLoader, LookupListSource, RecordMigration, FileUploadHandler, FieldValidators, NestedFieldConfig, ReferenceLoaderContext, DropdownOption, LookupListValue, NestedTabConfig, RuleEvaluationResult, FieldScopeEntry, EvaluateFormRulesOptions, ImportColumn, UnsupportedColumn, ImportRowError, SliderBounds } from '@dynamic-entity/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';
 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';
@@ -120,7 +120,15 @@ declare const DEFAULT_UI_TEXT: {
     importGuessed: string;
     importMappedCount: string;
     importRequiredUnmapped: string;
+    importConstant: string;
+    importAddSlot: string;
+    importStaleHeading: string;
+    importStaleExplain: string;
+    importRemoveEntry: string;
     importPreviewHeading: string;
+    importDelimiterComma: string;
+    importDelimiterSemicolon: string;
+    importDelimiterTab: string;
     importRowRejected: string;
     importRunImport: string;
     importImporting: string;
@@ -219,27 +227,35 @@ declare class UiTextService {
 /**
  * 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".
+ * Positional, 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
+ * Cells may keep their types (`SheetGrid`): a date cell handed over as a `Date` at UTC midnight
+ * is imported as that calendar date, exactly as the server reads the same workbook, where its
+ * text is whatever a library's formatter printed. A parser returning text (`SheetData`, as 2.2's
+ * did) still fits.
+ *
+ * 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.
  *
  * @example
+ * // 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.
  * provideNgxDynamicEntity({
  *   sheetParser: async file => {
- *     const workbook = XLSX.read(await file.arrayBuffer());
+ *     const workbook = XLSX.read(await file.arrayBuffer(), { cellDates: true });
  *     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) };
+ *       header: 1, raw: true, defval: '', UTC: true,
+ *     }) as unknown[][];
+ *     return { headers: (rows[0] ?? []).map(cellText), rows: rows.slice(1) };
  *   },
  * })
  */
-type SheetParser = (file: File) => SheetData | Promise<SheetData>;
+type SheetParser = (file: File) => SheetGrid | Promise<SheetGrid>;
 /** 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. */
@@ -266,6 +282,13 @@ interface ImportPreview {
     suggestion: MappingPlan;
     /** Total data rows in the file, which may be far more than `sample` holds. */
     rowCount: number;
+    /**
+     * Rows of each repeating field the suggestion was sized for (`arrayBoundFor`). Optional so a
+     * transport written for 2.2 keeps compiling; the mapper sizes itself the same way regardless.
+     */
+    arrayBound?: number;
+    /** The field separator a delimited-text file used. Absent for a workbook. */
+    delimiter?: CsvDelimiter;
 }
 /**
  * Where the work happens.
@@ -1001,6 +1024,11 @@ interface RuleSyncContext {
     addressOf(field: NestedFieldConfig): string;
     /** The control a scope entry addresses, or `null` when it has no static path. */
     controlFor(entry: FieldScopeEntry): AbstractControl | null;
+    /**
+     * The config the entries came from. Needed to know which tab owns each field: a tab that is
+     * not rendered hides every field it owns. Omitted, only field-level visibility applies.
+     */
+    config?: EntityFormConfig | null;
 }
 /**
  * RulesEvaluationService — evaluates rules, and owns what a result *means*.
@@ -1046,12 +1074,25 @@ declare class RulesEvaluationService {
      * The predicate is `isFieldVisible`, the same one the render filter uses, so what is on
      * screen and what counts toward validity cannot drift apart.
      *
+     * A tab that is not rendered — hidden by a rule, or `visibility: false` with no rule showing
+     * it — hides everything it owns, sub-tabs and container children included. Only fields were
+     * checked here, so a rule hiding a tab with a required field on it left the form invalid
+     * with the field out of sight and out of the error summary: Save did nothing, silently.
+     * Import already relaxed a hidden tab's fields, so the form refused rows import accepted.
+     *
      * 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;
+    /**
+     * Every field owned by a tab that does not render, under `isTabVisible`'s precedence.
+     *
+     * Stops descending at the first hidden tab: `fieldsUnderTab` already covers its sub-tabs,
+     * and a sub-tab of a hidden tab is not rendered whatever its own visibility says.
+     */
+    private fieldsOnHiddenTabs;
     /**
      * The hidden and shown names as sets, memoised against the result they came from.
      *
@@ -2135,6 +2176,8 @@ declare class EntityImportComponent {
     protected readonly headers: i0.WritableSignal<string[]>;
     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 fileName: i0.WritableSignal<string>;
     protected readonly plan: i0.WritableSignal<MappingPlan>;
     protected readonly result: i0.WritableSignal<ImportResult>;
@@ -2186,6 +2229,10 @@ declare class EntityImportComponent {
      * exact and `failed` is absent.
      */
     protected failedRowCount(result: ImportResult): number;
+    /** 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>;
@@ -2194,9 +2241,18 @@ declare class EntityImportComponent {
 /** 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". */
+    /** Index into the sheet's headers, `CONSTANT` for a fixed value, or `null` for "not imported". */
     source: number | null;
     guessed: boolean;
+    /** The incoming plan's entry for this field, emitted untouched until the user changes it. */
+    entry?: MappingEntry;
+    /** The user changed this row, so `entry` no longer describes it. */
+    dirty: boolean;
+}
+/** A repeating field, for its "Add a row" button. */
+interface ArraySlots {
+    arrayRef: string;
+    label: string;
 }
 /**
  * Match the sheet's columns to the config's fields.
@@ -2227,11 +2283,39 @@ declare class ImportMapperComponent implements OnChanges {
      * attachment column was never going to arrive.
      */
     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[]>;
+    /** Repeating fields the user can add a row to. */
+    protected readonly arrays: i0.WritableSignal<ArraySlots[]>;
+    protected readonly constant = -1;
+    /** Rows added by hand per repeating field, on top of what the sheet and plan imply. */
+    private readonly extraSlots;
+    /** The incoming plan, read through the 2.2 alias. Every entry in it survives `toPlan`. */
+    private incoming;
     ngOnChanges(): void;
+    /**
+     * Rows for every field, sized so nothing the plan or the sheet names is out of reach.
+     *
+     * Sizing from the default three meant a sheet with `Phone 4` could not be mapped at all,
+     * and a stored plan reaching further lost those entries on the next change — `toPlan` only
+     * ever emitted rows, and there were none for them.
+     */
+    private rebuild;
     protected mappedCount(): number;
     protected missingRequired(): number;
+    protected hasConstant(row: MappingRow): boolean;
+    protected constantText(entry: MappingEntry): string;
     protected choose(row: MappingRow, source: number | null): void;
-    /** The current selections as the plan that will be applied. */
+    /** One more row for one repeating field, for this session. */
+    protected addSlot(arrayRef: string): void;
+    protected removeStale(entry: MappingEntry): void;
+    /**
+     * The current selections as the plan that will be applied.
+     *
+     * 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.
+     */
     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>;
@@ -2279,13 +2363,15 @@ declare class ImportPreviewComponent implements OnChanges {
     /** The same rules the commit will apply; without them a rule-driven rejection is invisible. */
     rules?: readonly FormRule[];
     language: string;
+    /** The decimal mark number cells use — the one the commit will read them with. */
+    decimal: '.' | ',';
     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>;
+    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>;
 }
 
 /** One field offered for the template, with the guidance that belongs to it. */