ngx-t-forms-types 0.0.33 → 0.0.34

package/dist/interfaces/Import/ImportIdentity.d.ts

@@ -0,0 +1,32 @@
+/**
+ * How an import session decides that two rows are the same record.
+ *
+ * Passed to the import controller's `runImport` / `runMultipleInputImport`
+ * as per-import data — which fields identify a record in *this* form — not
+ * as application configuration. Only rows of the one session are compared;
+ * records already persisted are the server's to check.
+ *
+ * @public
+ */
+export interface ImportIdentity {
+    /**
+     * `formControlName`s that together identify a record (for a multiple-input
+     * import: the child inputs' `formControlName`s). A row whose values for all
+     * of them repeat an earlier row's is a duplicate of that row. Empty or
+     * absent disables duplicate detection. A name the form does not have
+     * rejects the run rather than matching nothing.
+     */
+    readonly distinctKeys: readonly string[];
+    /**
+     * What to do with a duplicate.
+     *
+     * - `skip` — the row is never processed: no tower, no fetches. It is
+     *   reported with status `duplicate` and `duplicateOf` naming the row it
+     *   repeats. The default.
+     * - `flag` — the row is processed and validated like any other and keeps
+     *   its real status; only `duplicateOf` marks it. For hosts that want to
+     *   show what the duplicate contained. Such a row still must not be
+     *   imported.
+     */
+    readonly onDuplicate?: 'skip' | 'flag';
+}

package/dist/interfaces/Import/ImportIdentity.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/Import/ImportProgress.d.ts

@@ -14,7 +14,11 @@ export interface ImportProgress {
     pending: number;
     /** Rows currently processing. */
     processing: number;
-    /** `valid` + `overridable` + `invalid` — i.e. rows that fully settled (regardless of validity). */
+    /**
+     * `valid` + `overridable` + `invalid` + rows held with status `duplicate` —
+     * i.e. rows that reached an outcome. `complete + error === total` once a
+     * run has finished, duplicates included.
+     */
     complete: number;
     /** Rows that settled with no errors. */
     valid: number;
@@ -24,6 +28,13 @@ export interface ImportProgress {
     invalid: number;
     /** Rows that threw before settling. */
     error: number;
+    /**
+     * Rows recognised as repeating an earlier row (`duplicateOf` set). Under
+     * the default `skip` policy these carry status `duplicate` and are counted
+     * in `complete`; under `flag` they keep their real status and are counted
+     * there as well.
+     */
+    duplicate: number;
     /** Underlying array — useful for rendering per-row UI. */
     rows: ImportRowState[];
 }

package/dist/interfaces/Import/ImportRowState.d.ts

@@ -13,12 +13,19 @@
  *   pre-process error (a row carrying both blocking and overridable errors is
  *   `invalid`, not `overridable`).
  * - `error`       — `_processRow` threw before settle (tower init failure, etc.).
+ * - `duplicate`   — the row repeats an earlier row of the session on the
+ *   fields the import was given as its identity (`ImportIdentity`), and is
+ *   held out of the import; {@link ImportRowState.duplicateOf} names the row
+ *   it repeats. A row skipped before its tower was built has no other
+ *   verdict; one recognised only after it settled keeps its settled value
+ *   and errors under this status. Under `onDuplicate: 'flag'` a duplicate
+ *   keeps its real status instead and only `duplicateOf` marks it.
  *
  * Upstreamed from `ngx-t-forms` per DECISIONS.md D-016.
  *
  * @public
  */
-export type ImportRowStatus = 'pending' | 'processing' | 'valid' | 'overridable' | 'invalid' | 'error';
+export type ImportRowStatus = 'pending' | 'processing' | 'valid' | 'overridable' | 'invalid' | 'error' | 'duplicate';
 /**
  * Per-row state recorded throughout an import session.
  *
@@ -63,4 +70,48 @@ export interface ImportRowState {
     colErrors?: Record<string, string>;
     /** Free-form message attached when `status === 'error'`. */
     errorMessage?: string;
+    /**
+     * formControlName → the cells of a choice field (select, autocomplete,
+     * paginated selection table) whose text matched MORE THAN ONE of the
+     * field's options, with the options it could be. The import accepts an
+     * option's visible label (or, for a table, any of its column values) in
+     * place of its stored value; a unique match is substituted silently, a
+     * tie is reported here so the user can pick, and the row stays `invalid`
+     * (`colErrors` carries `ambiguousOption:<text>`) until each is settled.
+     * A multi-select cell lists one entry per unsettled value.
+     */
+    optionChoices?: Record<string, ImportOptionChoice[]>;
+    /**
+     * The `rowIndex` of the earlier row this row repeats, when the session was
+     * given an `ImportIdentity` and this row's identity matches. Always the
+     * LOWEST index of the matching group — first wins — so the relation is
+     * stable and a host can offer "go to row N". Set under both duplicate
+     * policies; under `skip` the row's `status` is `duplicate` as well. Cleared
+     * when a re-run changes the identities so that the row no longer repeats
+     * anything.
+     */
+    duplicateOf?: number;
+}
+/**
+ * One option an imported cell could stand for.
+ *
+ * @public
+ */
+export interface ImportOptionCandidate {
+    /** The value the form stores when this option is chosen. */
+    value: unknown;
+    /** What the form shows for the option — its label, or a table row's column values. */
+    label: string;
+}
+/**
+ * An imported cell (or one value of a multi-select cell) whose text matched
+ * several options of a choice field. See {@link ImportRowState.optionChoices}.
+ *
+ * @public
+ */
+export interface ImportOptionChoice {
+    /** The text as it was imported. */
+    text: string;
+    /** The options it matched, in the field's option order. */
+    candidates: ImportOptionCandidate[];
 }

package/dist/interfaces/Import/index.d.ts

@@ -1,2 +1,3 @@
-export { ImportRowState, ImportRowStatus } from './ImportRowState.js';
+export { ImportOptionCandidate, ImportOptionChoice, ImportRowState, ImportRowStatus } from './ImportRowState.js';
 export { ImportProgress } from './ImportProgress.js';
+export { ImportIdentity } from './ImportIdentity.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-t-forms-types",
-  "version": "0.0.33",
+  "version": "0.0.34",
   "description": "Typings and interfaces for the ngx-t-forms library for dynamic forms.",
   "keywords": [
     "typings",