@expresscsv/react 0.1.25 → 0.1.26

package/dist/index.d.ts

@@ -9,6 +9,39 @@ declare type BooleanControlType = 'toggle' | 'checkbox' | 'dropdown';
  */
 export declare type ColorModePref = 'light' | 'dark' | 'system';
 
+export declare interface ColumnMatch<TTargetField extends string = string> {
+    sourceColumnIndex: number;
+    targetField: TTargetField;
+}
+
+export declare type ColumnMatchingFn<TTargetField extends string = string> = (data: ColumnMatchingParams) => Promise<ColumnMatchingResult<TTargetField>>;
+
+export declare type ColumnMatchingOptions<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = ManagedColumnMatchingOptions | CustomColumnMatchingOptions<TSchema>;
+
+export declare interface ColumnMatchingParams {
+    sessionId: string;
+    sourceColumns: ColumnMatchingSourceColumn[];
+    targetFields: ColumnMatchingTargetField[];
+}
+
+export declare interface ColumnMatchingResult<TTargetField extends string = string> {
+    matches: Array<ColumnMatch<TTargetField>>;
+}
+
+export declare interface ColumnMatchingSourceColumn {
+    sourceColumnIndex: number;
+    name: string;
+    sampleValues: string[];
+}
+
+export declare interface ColumnMatchingTargetField {
+    name: string;
+    label?: string;
+    type: string;
+    description?: string;
+    aliases: string[];
+}
+
 declare const Countries: readonly [{
     readonly name: "Afghanistan";
     readonly alpha2: "AF";
@@ -1878,11 +1911,21 @@ declare const CurrencyCodes: readonly [{
     readonly numeric: "932";
 }];
 
-export declare type CustomStorageOptions = {
+declare type CustomColumnMatchingOptions<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = {
     type: 'custom';
-    get: (key: StorageKey) => Promise<StoredSession | null>;
-    set: (key: StorageKey, value: StoredSession) => Promise<void>;
-    remove: (key: StorageKey) => Promise<void>;
+    match: ColumnMatchingFn<SchemaFieldName<TSchema>>;
+};
+
+declare type CustomPromptedEditsOptions<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = {
+    type: 'custom';
+    edit: PromptedEditsFn<SchemaFieldName<TSchema>>;
+};
+
+export declare type CustomSessionRecoveryOptions = {
+    type: 'custom';
+    get: (key: SessionRecoveryKey) => Promise<RecoveredSession | null>;
+    set: (key: SessionRecoveryKey, value: RecoveredSession) => Promise<void>;
+    remove: (key: SessionRecoveryKey) => Promise<void>;
 };
 
 declare interface DatetimeOptions {
@@ -1893,11 +1936,6 @@ export declare type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
 };
 
-export declare interface DeliveryOptions<T> {
-    /** Callback for processing delivered chunks */
-    onData: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
-}
-
 /**
  * Font source configuration for custom fonts
  */
@@ -2825,6 +2863,8 @@ declare interface ExpressCSVLocale {
         showAll: string;
         moveUp: string;
         moveDown: string;
+        /** When the selected row has zero columns (cannot continue) */
+        rowNotSelectable: string;
     };
     matchColumns: {
         loading: string;
@@ -2859,6 +2899,8 @@ declare interface ExpressCSVLocale {
         previewTooltip: string;
         /** Available: {rowCount}, {columnName} */
         previewShowing: TemplateString<'rowCount' | 'columnName'>;
+        /** Available: {columnNumber} — 1-based index when the sheet header cell is empty */
+        unnamedSourceColumn: TemplateString<'columnNumber'>;
     };
     matchOptions: {
         loading: string;
@@ -2951,27 +2993,27 @@ declare interface ExpressCSVLocale {
         filteredColumns: string;
         unfilteredColumns: string;
         columnsLabel: string;
-        transformTooltip: string;
-        transformTitle: string;
-        transformClose: string;
-        transformCloseDiscardTooltip: string;
-        transformCloseTooltip: string;
-        transformError: string;
-        transformPlaceholder: string;
-        transformGenerating: string;
-        transformApplying: string;
-        transformDiscard: string;
-        transformApply: string;
-        transformUnappliedTitle: string;
-        transformUnappliedDescription: string;
-        transformKeepEditing: string;
-        transformDiscardClose: string;
-        transformAbortTitle: string;
-        transformAbortDescription: string;
-        transformAbortClose: string;
-        transformSubmit: string;
+        promptedEditsTooltip: string;
+        promptedEditsTitle: string;
+        promptedEditsClose: string;
+        promptedEditsCloseDiscardTooltip: string;
+        promptedEditsCloseTooltip: string;
+        promptedEditsError: string;
+        promptedEditsPlaceholder: string;
+        promptedEditsGenerating: string;
+        promptedEditsApplying: string;
+        promptedEditsDiscard: string;
+        promptedEditsApply: string;
+        promptedEditsUnappliedTitle: string;
+        promptedEditsUnappliedDescription: string;
+        promptedEditsKeepEditing: string;
+        promptedEditsDiscardClose: string;
+        promptedEditsAbortTitle: string;
+        promptedEditsAbortDescription: string;
+        promptedEditsAbortClose: string;
+        promptedEditsSubmit: string;
     };
-    phantomColumn: {
+    emptyColumn: {
         /** Available: {number} */
         defaultName: TemplateString<'number'>;
         remove: string;
@@ -3510,10 +3552,22 @@ export declare type Infer<T extends ExType<unknown, ExBaseDef, unknown>> = T ext
 
 declare type IPAddressVersion = 'v4' | 'v6' | 'all';
 
-export declare type LocalStorageOptions = {
+export declare type LocalSessionRecoveryOptions = {
     type: 'local';
 };
 
+declare type ManagedColumnMatchingOptions = {
+    type: 'managed';
+    exact?: boolean;
+    caseInsensitive?: boolean;
+    normalized?: boolean;
+    inference?: boolean;
+};
+
+declare type ManagedPromptedEditsOptions = {
+    type: 'managed';
+};
+
 declare interface MultiselectOptions {
     enforceCaseSensitiveMatch?: boolean;
     message?: string;
@@ -3523,7 +3577,9 @@ declare interface MultiselectOptions {
  * Options for the open() method
  * Requires an onData callback for delivery
  */
-export declare type OpenOptions<T> = DeliveryOptions<T> & {
+export declare type OpenOptions<T> = {
+    /** Callback for processing delivered chunks */
+    onData: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
     /** Number of records per chunk (default: 1000) */
     chunkSize?: number;
     /** Called when all chunks have been processed */
@@ -3643,6 +3699,51 @@ declare abstract class PrimitiveExType<Output, Def extends PrimitiveExBaseDef, I
     protected _replaceOrAddCheck(check: ValidatorCheck, existingIndex: number): void;
 }
 
+export declare type PromptedEditsChange<TField extends string = string> = {
+    type: 'add';
+    values: Partial<Record<TField, unknown>>;
+} | {
+    type: 'update';
+    rowId: string;
+    values: Partial<Record<TField, unknown>>;
+} | {
+    type: 'remove';
+    rowId: string;
+};
+
+export declare interface PromptedEditsField<TField extends string = string> {
+    key: TField;
+    name: string;
+    type: string;
+    sampleValues: unknown[];
+}
+
+export declare type PromptedEditsFn<TField extends string = string> = (data: PromptedEditsParams<TField>) => Promise<PromptedEditsResult<TField>>;
+
+export declare type PromptedEditsOptions<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = ManagedPromptedEditsOptions | CustomPromptedEditsOptions<TSchema>;
+
+export declare interface PromptedEditsParams<TField extends string = string> {
+    sessionId: string;
+    prompt: string;
+    fields: Array<PromptedEditsField<TField>>;
+    rows: Array<PromptedEditsRow<TField>>;
+    totalRows: number;
+}
+
+export declare type PromptedEditsResult<TField extends string = string> = {
+    type: 'success';
+    changes: Array<PromptedEditsChange<TField>>;
+} | {
+    type: 'no-op';
+    message: string;
+};
+
+export declare interface PromptedEditsRow<TField extends string = string> {
+    rowId: string;
+    rowIndex: number;
+    values: Partial<Record<TField, unknown>>;
+}
+
 declare type Protocol = 'http' | 'https' | 'ftp' | 'sftp' | 'file' | 'mailto' | 'tel';
 
 /**
@@ -3663,6 +3764,10 @@ export declare interface RecordsChunk<T> {
     chunkIdempotencyKey: string;
 }
 
+export declare type RecoveredSession = PersistedImportSessionData;
+
+export declare type RecoveredSessionData = PersistedImportSessionPayload;
+
 declare type RefineBatchResultItem = {
     valid: boolean;
     message?: string;
@@ -3692,6 +3797,29 @@ declare type RefineResultItem = {
     };
 };
 
+declare type SchemaFieldName<TSchema extends ExType<unknown, ExBaseDef, unknown>> = Extract<keyof Infer<TSchema>, string>;
+
+export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> {
+    schema: TSchema;
+    getSessionToken: () => Promise<string>;
+    importIdentifier: string;
+    title?: string;
+    debug?: boolean;
+    preload?: boolean;
+    theme?: ECSVTheme;
+    colorMode?: ColorModePref;
+    customCSS?: string;
+    fonts?: Record<string, ECSVFontSource>;
+    stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
+    previewSchemaBeforeUpload?: boolean;
+    columnMatching?: ColumnMatchingOptions<TSchema>;
+    promptedEdits?: PromptedEditsOptions<TSchema>;
+    templateDownload?: TemplateDownloadOptions<TSchema>;
+    sessionRecovery?: SessionRecoveryOptions;
+    locale?: DeepPartial<ExpressCSVLocaleInput>;
+    disableStatusStep?: boolean;
+}
+
 declare interface SelectOption<TValue extends string | number = string | number> {
     label: string;
     value: TValue;
@@ -3704,13 +3832,9 @@ declare interface SelectOptions {
     message?: string;
 }
 
-export declare type StorageKey = PersistedImportSessionKey;
-
-export declare type StorageOptions = LocalStorageOptions | CustomStorageOptions;
-
-export declare type StoredSession = PersistedImportSessionData;
+export declare type SessionRecoveryKey = PersistedImportSessionKey;
 
-export declare type StoredSessionData = PersistedImportSessionPayload;
+export declare type SessionRecoveryOptions = LocalSessionRecoveryOptions | CustomSessionRecoveryOptions;
 
 declare type StripBrand<T> = {
     [K in keyof T]: T[K] extends TemplateString<string> ? string : T[K] extends object ? StripBrand<T[K]> : T[K];
@@ -3800,33 +3924,14 @@ declare interface URLOptions {
     message?: string;
 }
 
-export declare function useExpressCSV<TSchema extends ExType<unknown, ExBaseDef, unknown>>({ schema, title, importIdentifier, getSessionToken, debug, preload, theme, colorMode, customCSS, fonts, stepDisplay, previewSchemaBeforeUpload, aiColumnMatching, aiTransform, templateDownload, storage, locale, disableStatusStep, }: UseExpressCSVOptions<TSchema>): {
+export declare function useExpressCSV<TSchema extends ExType<unknown, ExBaseDef, unknown>>({ schema, title, importIdentifier, getSessionToken, debug, preload, theme, colorMode, customCSS, fonts, stepDisplay, previewSchemaBeforeUpload, columnMatching, promptedEdits, templateDownload, sessionRecovery, locale, disableStatusStep, }: UseExpressCSVOptions<TSchema>): {
     open: (options: OpenOptions<Infer<TSchema>>) => void;
     importerState: ImporterState;
     isInitialising: boolean;
     isOpen: boolean;
 };
 
-export declare interface UseExpressCSVOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> {
-    schema: TSchema;
-    title?: string;
-    importIdentifier: string;
-    getSessionToken: () => Promise<string>;
-    debug?: boolean;
-    preload?: boolean;
-    theme?: ECSVTheme;
-    colorMode?: ColorModePref;
-    customCSS?: string;
-    fonts?: Record<string, ECSVFontSource>;
-    stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
-    previewSchemaBeforeUpload?: boolean;
-    aiColumnMatching?: boolean;
-    aiTransform?: boolean;
-    templateDownload?: TemplateDownloadOptions<TSchema>;
-    storage?: StorageOptions;
-    locale?: DeepPartial<ExpressCSVLocaleInput>;
-    disableStatusStep?: boolean;
-}
+export declare type UseExpressCSVOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> = SDKOptions<TSchema>;
 
 declare type UUIDVersion = 'v1' | 'v4' | 'v5' | 'all';