@expresscsv/react 0.1.25 → 1.0.0

package/dist/index.d.ts

@@ -4,11 +4,60 @@ declare interface BICOptions {
 
 declare type BooleanControlType = 'toggle' | 'checkbox' | 'dropdown';
 
+export declare type ChunkSize = {
+    /** Size quota unit. */
+    unit: 'kb';
+    /** KB quota. Values <= 0 send all rows in one chunk. */
+    value: number;
+} | {
+    /** Chunk by row count. */
+    unit: 'rows';
+    /** Rows per chunk. Values <= 0 send all rows in one chunk. */
+    value: number;
+};
+
 /**
  * Color mode preference
  */
 export declare type ColorModePref = 'light' | 'dark' | 'system';
 
+export declare interface ColumnMatch<TTargetField extends string = string> {
+    sourceColumnIndex: number;
+    targetField: TTargetField;
+}
+
+export declare type ColumnMatchHandler<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = ColumnMatchingFn<SchemaFieldName<TSchema>>;
+
+export declare type ColumnMatchHandlerResult<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = ColumnMatchingResult<SchemaFieldName<TSchema>>;
+
+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 +1927,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';
+    columnMatchHandler: ColumnMatchHandler<TSchema>;
+};
+
+declare type CustomPromptedEditsOptions<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>;
+    promptedEditHandler: PromptedEditHandler<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,44 +1952,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
- */
-export declare type ECSVFontSource = {
-    source: 'google';
-    name: string;
-    weights?: (number | string)[];
-} | {
-    source: 'custom';
-    url: string;
-    format?: 'woff2' | 'woff';
-};
-
-/**
- * Theme - can be either dual-mode (light/dark) or single-mode (applies to both)
- */
-export declare type ECSVTheme = ECSVThemeWithModes | ECSVThemeSingle;
-
-/**
- * Single theme that applies to both light and dark modes
- */
-declare type ECSVThemeSingle = TailwindThemeVars;
-
-/**
- * Theme with light and dark mode support
- */
-declare interface ECSVThemeWithModes {
-    modes: {
-        light: TailwindThemeVars;
-        dark: TailwindThemeVars;
-    };
-}
-
 declare interface ExBaseDef {
     typeName: string;
 }
@@ -2825,6 +2846,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 +2882,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 +2976,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;
@@ -3002,11 +3027,6 @@ declare interface ExpressCSVLocale {
 /** User-facing locale type where every leaf is a plain `string`. */
 export declare type ExpressCSVLocaleInput = StripBrand<ExpressCSVLocale>;
 
-/**
- * Core step identifiers for the CSV import wizard
- */
-export declare type ExpressCSVStep = 'upload' | 'select-sheet' | 'select-header' | 'match-columns' | 'match-options' | 'review';
-
 declare type ExPrimitiveType = ExString | ExNumber | ExCurrencyNumber | ExPercentageNumber | ExBoolean | ExDate | ExTime | ExDatetime | ExSelect<string | number> | ExMultiselect<string | number> | ExOptionalPrimitiveType;
 
 declare class ExRow<T extends ExRowShape> extends ExType<{
@@ -3462,6 +3482,19 @@ declare abstract class ExType<Output, Def extends ExBaseDef, Input = Output> {
     protected _addCheck(type: string, params?: Record<string, unknown>, message?: string): ValidatorCheck;
 }
 
+/**
+ * Font source configuration for custom fonts
+ */
+export declare type FontSource = {
+    source: 'google';
+    name: string;
+    weights?: (number | string)[];
+} | {
+    source: 'custom';
+    url: string;
+    format?: 'woff2' | 'woff';
+};
+
 declare interface GTINOptions {
     message?: string;
 }
@@ -3478,6 +3511,11 @@ export declare class ImportCancelledError extends Error {
     constructor(message?: string);
 }
 
+export declare interface ImportDeliveryContext extends ImportSessionContext {
+    /** Stable ID for the delivery attempt that completed or failed */
+    deliveryId: string;
+}
+
 /**
  * Importer preload mode
  */
@@ -3486,10 +3524,15 @@ export declare enum ImporterMode {
     PRELOAD = "preload"
 }
 
+export declare type ImportErrorContext = ImportSessionContext & {
+    /** Present when an error occurs while delivering records */
+    deliveryId?: string;
+};
+
 /**
- * Importer lifecycle state
+ * Importer lifecycle status
  */
-export declare enum ImporterState {
+export declare enum ImporterStatus {
     UNINITIALIZED = "uninitialized",
     INITIALIZING = "initializing",
     READY = "ready",
@@ -3501,8 +3544,13 @@ export declare enum ImporterState {
     DESTROYED = "destroyed"
 }
 
+/**
+ * Core step identifiers for the CSV importer
+ */
+export declare type ImporterStep = 'upload' | 'select-sheet' | 'select-header' | 'match-columns' | 'match-options' | 'review';
+
 export declare interface ImportSessionContext {
-    /** Generated session ID for the current import run */
+    /** Stable ID that groups one import run across chunks and lifecycle callbacks */
     sessionId: string;
 }
 
@@ -3510,10 +3558,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,21 +3583,21 @@ declare interface MultiselectOptions {
  * Options for the open() method
  * Requires an onData callback for delivery
  */
-export declare type OpenOptions<T> = DeliveryOptions<T> & {
-    /** Number of records per chunk (default: 1000) */
-    chunkSize?: number;
+export declare type OpenOptions<T> = {
+    /** Callback for processing delivered chunks */
+    onData: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
+    /** Chunk size by KB quota or row count. Defaults to 500 KB. Values <= 0 send one chunk. */
+    chunkSize?: ChunkSize;
     /** Called when all chunks have been processed */
-    onComplete?: (context: ImportSessionContext) => void;
+    onComplete?: (context: ImportDeliveryContext) => void;
     /** Called when the user cancels the import */
     onCancel?: (context: ImportSessionContext) => void;
     /** Called when an error occurs */
-    onError?: (error: Error, context: ImportSessionContext) => void;
+    onError?: (error: Error, context: ImportErrorContext) => void;
     /** Called when the importer opens */
-    onImporterOpen?: () => void;
-    /** Called when the importer closes */
-    onImporterClose?: (reason: 'user_close' | 'cancel' | 'complete' | 'error') => void;
-    /** Called when the step changes in the wizard */
-    onStepChange?: (stepId: ExpressCSVStep, previousStepId?: ExpressCSVStep) => void;
+    onOpen?: (context: ImportSessionContext) => void;
+    /** Called when the importer step changes */
+    onStepChange?: (stepId: ImporterStep, previousStepId?: ImporterStep) => void;
 };
 
 declare interface PersistedImportSessionData {
@@ -3566,7 +3626,6 @@ declare interface PrimitiveExBaseDef extends ExBaseDef {
     columnNameAliases?: string[];
     description?: string;
     label?: string;
-    example?: string;
     message?: string;
     checks?: ValidatorCheck[];
     defaultValue?: unknown | (() => unknown);
@@ -3594,13 +3653,6 @@ declare abstract class PrimitiveExType<Output, Def extends PrimitiveExBaseDef, I
      * @returns The type instance for method chaining
      */
     label(text: string): this;
-    /**
-     * Sets an example value for this field
-     *
-     * @param text - Example text
-     * @returns The type instance for method chaining
-     */
-    example(text: string): this;
     /**
      * Adds a custom refinement validator to this field.
      *
@@ -3643,6 +3695,55 @@ declare abstract class PrimitiveExType<Output, Def extends PrimitiveExBaseDef, I
     protected _replaceOrAddCheck(check: ValidatorCheck, existingIndex: number): void;
 }
 
+export declare type PromptedEditHandler<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = PromptedEditsFn<SchemaFieldName<TSchema>>;
+
+export declare type PromptedEditResult<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = PromptedEditsResult<SchemaFieldName<TSchema>>;
+
+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';
 
 /**
@@ -3653,16 +3754,20 @@ export declare interface RecordsChunk<T> {
     records: T[];
     /** Total number of chunks */
     totalChunks: number;
-    /** Current chunk index (0-based) */
-    currentChunkIndex: number;
+    /** Chunk index within this delivery (0-based) */
+    chunkIndex: number;
     /** Total number of records across all chunks */
     totalRecords: number;
-    /** Generated session ID for the current import run */
+    /** Stable ID that groups one import run across chunks and lifecycle callbacks */
     sessionId: string;
-    /** Stable per-chunk idempotency key */
-    chunkIdempotencyKey: string;
+    /** Stable ID for this delivery attempt within the import session */
+    deliveryId: string;
 }
 
+export declare type RecoveredSession = PersistedImportSessionData;
+
+export declare type RecoveredSessionData = PersistedImportSessionPayload;
+
 declare type RefineBatchResultItem = {
     valid: boolean;
     message?: string;
@@ -3692,6 +3797,30 @@ declare type RefineResultItem = {
     };
 };
 
+export 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>;
+    /** Stable namespace string your app assigns to this importer configuration or workflow */
+    importNamespace: string;
+    title?: string;
+    debug?: boolean;
+    preload?: boolean;
+    theme?: Theme;
+    colorMode?: ColorModePref;
+    customCSS?: string;
+    fonts?: Record<string, FontSource>;
+    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 +3833,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];
@@ -3784,6 +3909,26 @@ declare type TemplateString<TVars extends string = string> = string & {
     readonly __vars: TVars;
 };
 
+/**
+ * Theme - can be either dual-mode (light/dark) or single-mode (applies to both)
+ */
+export declare type Theme = ThemeWithModes | ThemeSingle;
+
+/**
+ * Single theme that applies to both light and dark modes
+ */
+declare type ThemeSingle = TailwindThemeVars;
+
+/**
+ * Theme with light and dark mode support
+ */
+declare interface ThemeWithModes {
+    modes: {
+        light: TailwindThemeVars;
+        dark: TailwindThemeVars;
+    };
+}
+
 /**
  * Time validation options
  */
@@ -3800,33 +3945,12 @@ 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, importNamespace, 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;
+    status: ImporterStatus;
 };
 
-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';