@aglyn/plugins-crm 1.0.0-beta.143

package/src/lib/components/csv-import-drawer.d.ts

@@ -0,0 +1,132 @@
+/**
+ * IMPORTING A CSV INTO A CRM COLLECTION — the screen, for whichever
+ * collection (AGL-2602, shared since AGL-2621).
+ *
+ * The contact import settled the walk from a file on disk to a result the
+ * operator can act on: choose the file, read what is in it, match its
+ * columns to fields with the first row beside each, preview the ten rows
+ * the mapping produces, run it in bounded requests with a progress bar,
+ * and report what was added, updated and skipped with the skipped rows as
+ * a file to fix. A companies file walks the same path with a different
+ * vocabulary, so the walk lives here once and each collection hands in a
+ * {@link CsvImportVocabulary}: its fields and their labels, the one field
+ * every row needs, its route, its tally, its template.
+ *
+ * ## The file is read in the browser, and judged on the server
+ *
+ * `parseCsv` — the same parser the list import and the dataset import run
+ * — turns the file into cells here, so the operator can map and preview
+ * without a round trip and without uploading a file they may still decide
+ * not to import. Nothing is VALIDATED here beyond counting the rows whose
+ * required cell is unusable, and that count is a courtesy: every row is
+ * judged by the route, through the normalizers every other door uses, and
+ * the numbers on the result panel are the server's.
+ *
+ * ## Bounded requests, and closing stops them
+ *
+ * A chunk per request, as many requests as the file needs, and a progress
+ * bar between them. Closing the drawer mid-run stops the loop after the
+ * request in flight; the rows already written stay written and the result
+ * panel says how far it got. There is no durable job to resume — an import
+ * is idempotent by construction (the door dedupes on the address, or the
+ * domain and the name), so running the same file again finishes what a
+ * closed drawer left, reporting the earlier rows as merged.
+ */
+import { type ImportChunkResult, type ImportSkippedRow } from '@aglyn/aglyn';
+import { HelpTip } from '@aglyn/shared-ui-jsx';
+import { type ComponentProps, type ReactNode } from 'react';
+/** A column's target: a standard field, or a custom one as `custom:<key>`. */
+export type CsvImportTarget<F extends string> = F | `custom:${string}`;
+/** Column index → target. A column absent from the map is not imported. */
+export type CsvImportMapping<F extends string> = Record<number, CsvImportTarget<F>>;
+/** A custom field a column may be mapped to, when the collection has any. */
+export interface CsvImportCustomField {
+    key: string;
+    label: string;
+}
+/**
+ * Everything one collection's import says for itself. Pure values and pure
+ * functions, so a vocabulary is built once outside React and handed in.
+ */
+export interface CsvImportVocabulary<F extends string, R extends Record<string, unknown>, S extends ImportSkippedRow<string>> {
+    /** The drawer's title — "Import contacts from CSV". */
+    title: string;
+    /**
+     * What the import is called where the `importMapping` zone names it —
+     * `contacts`, `companies`, `deals`, `leads` (AGL-2917). Absent, the drawer
+     * hosts no zone.
+     */
+    collection?: string;
+    help: ComponentProps<typeof HelpTip>;
+    /**
+     * What the site picker's answer decides, said under it at the
+     * organization level (AGL-2630). Absent, the picker's own sentence.
+     */
+    sitePickerHelperText?: string;
+    /** The paragraph under the title. */
+    intro: string;
+    /** The standard targets, in the order the mapping menu lists them. */
+    fields: readonly F[];
+    fieldLabels: Record<F, string>;
+    /** Custom targets, offered after the standard ones; none for most collections. */
+    customFields?: readonly CsvImportCustomField[];
+    /** The one field every row needs, and what the drawer says when it is unmapped. */
+    requiredField: F;
+    requiredWarning: string;
+    /**
+     * Whether a required cell is one the server would refuse — the courtesy
+     * count the preview shows. Absent, only a blank cell counts.
+     */
+    unusable?: (cell: string) => boolean;
+    /** The preview's sentence about them. */
+    unusableNotice: (count: number, total: number) => string;
+    guessMapping: (columns: readonly string[]) => CsvImportMapping<F>;
+    mapRow: (cells: readonly string[], mapping: CsvImportMapping<F>) => R;
+    /** The browser-side URL of the route one chunk is posted to. */
+    route: string;
+    maxRows: number;
+    chunkSize: number;
+    previewRows: number;
+    emptyResult: () => ImportChunkResult<S>;
+    mergeResults: (total: ImportChunkResult<S>, chunk: ImportChunkResult<S>, offset: number) => ImportChunkResult<S>;
+    skipLabels: Record<S['reason'], string>;
+    skippedCsv: (columns: readonly string[], entries: readonly {
+        cells: readonly string[];
+        reason: S['reason'];
+    }[]) => string;
+    skippedFileName: string;
+    /** The export's header over no rows. */
+    templateCsv: () => string;
+    templateFileName: string;
+    /** The result panel's collection-specific lines, when there are any. */
+    resultExtras?: (result: ImportChunkResult<S>) => ReactNode;
+}
+export interface CsvImportDrawerProps<F extends string, R extends Record<string, unknown>, S extends ImportSkippedRow<string>> {
+    open: boolean;
+    onClose: () => void;
+    /**
+     * The site the file is imported INTO — what the route files every row
+     * under — or `null` at the organization level (AGL-2630), where the
+     * drawer asks which site with a picker and holds the import until one is
+     * named.
+     */
+    hostId: string | null;
+    vocabulary: CsvImportVocabulary<F, R, S>;
+}
+export declare function CsvImportDrawer<F extends string, R extends Record<string, unknown>, S extends ImportSkippedRow<string>>(props: CsvImportDrawerProps<F, R, S>): import("react").JSX.Element;
+export declare namespace CsvImportDrawer {
+    var displayName: string;
+}
+/**
+ * An "Import CSV" button that mounts its drawer only once it has been
+ * opened, so the list pays nothing — no hooks, no listeners — for a
+ * feature the operator has not reached for.
+ */
+export declare function CsvImportButton(props: {
+    label?: string;
+    children: (open: boolean, onClose: () => void) => ReactNode;
+}): import("react").JSX.Element;
+export declare namespace CsvImportButton {
+    var displayName: string;
+}
+export default CsvImportDrawer;