@expresscsv/react 0.1.25 → 1.0.0

package/README.md

@@ -25,7 +25,7 @@ yarn add @expresscsv/react
 ## Quick Start
 
 ```tsx
-import { useExpressCSV, x } from "@expresscsv/react";
+import { ImporterStatus, useExpressCSV, x } from "@expresscsv/react";
 
 const schema = x.row({
   name: x.string().label("Full Name"),
@@ -34,26 +34,26 @@ const schema = x.row({
 });
 
 function App() {
-  const { open, isOpen } = useExpressCSV({
+  const { open, status } = useExpressCSV({
     schema,
     getSessionToken: async () => fetchSessionToken(),
-    importIdentifier: "user-import",
+    importNamespace: "user-import",
     title: "Import Users",
   });
 
   const handleImport = () => {
     open({
-      chunkSize: 500,
+      chunkSize: { unit: "kb", value: 500 },
       onData: async (chunk, next) => {
         console.log(
-          `Chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}`
+          `Chunk ${chunk.chunkIndex + 1}/${chunk.totalChunks}`
         );
         console.log("Session:", chunk.sessionId);
-        console.log("Idempotency key:", chunk.chunkIdempotencyKey);
+        console.log("Delivery ID:", chunk.deliveryId);
         console.log("Records:", chunk.records);
         next();
       },
-      onComplete: ({ sessionId }) => {
+      onComplete: ({ sessionId, deliveryId }) => {
         console.log("All chunks processed for", sessionId);
       },
       onCancel: ({ sessionId }) => {
@@ -66,7 +66,7 @@ function App() {
   };
 
   return (
-    <button onClick={handleImport} disabled={isOpen}>
+    <button onClick={handleImport} disabled={status === ImporterStatus.OPEN}>
       Import CSV
     </button>
   );
@@ -83,7 +83,7 @@ By default the importer preloads in a hidden iframe so it appears instantly when
 const { open } = useExpressCSV({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
 });
 
 // Importer displays instantly
@@ -103,7 +103,7 @@ To disable preloading (there will be a brief loading screen instead):
 const { open } = useExpressCSV({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   preload: false,
 });
 ```
@@ -127,7 +127,7 @@ const candidateSchema = x.row({
 const { open } = useExpressCSV({
   schema: candidateSchema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "candidate-import",
+  importNamespace: "candidate-import",
   templateDownload: {
     source: "generate",
     formats: ["csv", "xlsx"],
@@ -151,10 +151,10 @@ Customize the importer's appearance with the `theme`, `colorMode`, `customCSS`,
 Use the `theme` option to override CSS variables (colors, radius, typography). Pass either a single theme (applies to both light and dark) or a dual-mode theme with separate light/dark values:
 
 ```tsx
-import { useExpressCSV, x, type ECSVTheme } from "@expresscsv/react";
+import { useExpressCSV, x, type Theme } from "@expresscsv/react";
 
 // Single theme (both modes)
-const theme: ECSVTheme = {
+const theme: Theme = {
   primary: "#4F46E5",
   "primary-foreground": "#ffffff",
   background: "#ffffff",
@@ -165,7 +165,7 @@ const theme: ECSVTheme = {
 };
 
 // Dual-mode (light and dark)
-const dualTheme: ECSVTheme = {
+const dualTheme: Theme = {
   modes: {
     light: {
       primary: "#4F46E5",
@@ -184,7 +184,7 @@ function App() {
   const { open } = useExpressCSV({
     schema,
     getSessionToken: async () => fetchSessionToken(),
-    importIdentifier: "user-import",
+    importNamespace: "user-import",
     theme,
   });
   // ...
@@ -230,7 +230,7 @@ Control light/dark mode with `colorMode`:
 const { open } = useExpressCSV({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   colorMode: "system", // 'light' | 'dark' | 'system'
 });
 ```
@@ -243,7 +243,7 @@ Inject custom CSS for fine-grained styling overrides.
 const { open } = useExpressCSV({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   customCSS: `
     .ecsv [data-step="upload"] {
       border-radius: 1rem;
@@ -263,7 +263,7 @@ Load custom fonts via the `fonts` option:
 const { open } = useExpressCSV({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   fonts: {
     title: { source: "google", name: "Space Grotesk", weights: [400, 600, 700] },
     body: { source: "custom", url: "https://example.com/font.woff2", format: "woff2" },
@@ -281,18 +281,19 @@ ExpressCSV delivers imported data through `onData`. Your app receives validated
 
 ```tsx
 open({
-  chunkSize: 500,
+  chunkSize: { unit: "kb", value: 500 },
   onData: async (chunk, next) => {
-    const response = await fetch("/api/import-users/chunks", {
+    const response = await fetch("/your-api/import-users/chunks", {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
+        Authorization: `Bearer ${accessToken}`,
       },
       body: JSON.stringify({
         sessionId: chunk.sessionId,
-        chunkIdempotencyKey: chunk.chunkIdempotencyKey,
+        deliveryId: chunk.deliveryId,
+        chunkIndex: chunk.chunkIndex,
         records: chunk.records,
-        currentChunkIndex: chunk.currentChunkIndex,
         totalChunks: chunk.totalChunks,
         totalRecords: chunk.totalRecords,
       }),
@@ -304,8 +305,15 @@ open({
 
     next();
   },
-  onComplete: ({ sessionId }) => {
-    console.log("Import complete for", sessionId);
+  onComplete: async ({ sessionId, deliveryId }) => {
+    await fetch("/your-api/import-users/complete", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${accessToken}`,
+      },
+      body: JSON.stringify({ sessionId, deliveryId }),
+    });
   },
 });
 ```
@@ -314,15 +322,18 @@ Each delivered chunk includes:
 
 - `records`
 - `sessionId`
-- `chunkIdempotencyKey`
-- `currentChunkIndex`
+- `deliveryId`
+- `chunkIndex`
 - `totalChunks`
 - `totalRecords`
 
+Each time the user finishes the import, ExpressCSV creates a new `deliveryId` for that `sessionId`. Your `onData` code can fail, and the user can retry delivery without starting the import over. Store chunks by `(sessionId, deliveryId, chunkIndex)`, then finalize the `deliveryId` from `onComplete` after all of its chunks are accepted.
+
+
 ## Advanced Example
 
 ```tsx
-import { useExpressCSV, x, type Infer } from "@expresscsv/react";
+import { ImporterStatus, useExpressCSV, x, type Infer } from "@expresscsv/react";
 import { useState } from "react";
 
 const candidateSchema = x.row({
@@ -342,10 +353,10 @@ const candidateSchema = x.row({
 function CandidateImporter() {
   const [status, setStatus] = useState<string | null>(null);
 
-  const { open, isOpen } = useExpressCSV({
+  const { open, status: importerStatus } = useExpressCSV({
     schema: candidateSchema,
     getSessionToken: async () => fetchSessionToken(),
-    importIdentifier: "candidate-import",
+    importNamespace: "candidate-import",
     title: "Import Candidates",
   });
 
@@ -355,12 +366,12 @@ function CandidateImporter() {
     open({
       onData: async (chunk, next) => {
         setStatus(
-          `Processing chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}...`
+          `Processing chunk ${chunk.chunkIndex + 1}/${chunk.totalChunks}...`
         );
         await importCandidates(chunk.records);
         next();
       },
-      onComplete: ({ sessionId }) => {
+      onComplete: ({ sessionId, deliveryId }) => {
         setStatus(`Import complete: ${sessionId}`);
       },
       onError: (error, { sessionId }) => {
@@ -375,8 +386,13 @@ function CandidateImporter() {
 
   return (
     <div>
-      <button onClick={handleImport} disabled={isOpen}>
-        {isOpen ? "Importing..." : "Import Candidates"}
+      <button
+        onClick={handleImport}
+        disabled={importerStatus === ImporterStatus.OPEN}
+      >
+        {importerStatus === ImporterStatus.OPEN
+          ? "Importing..."
+          : "Import Candidates"}
       </button>
       {status && <p>{status}</p>}
     </div>
@@ -393,9 +409,7 @@ function useExpressCSV<TSchema>(
   options: UseExpressCSVOptions<TSchema>
 ): {
   open: (options: OpenOptions<Infer<TSchema>>) => void;
-  importerState: ImporterState;
-  isInitialising: boolean;
-  isOpen: boolean;
+  status: ImporterStatus;
 };
 ```
 
@@ -405,20 +419,20 @@ function useExpressCSV<TSchema>(
 |---|---|---|---|---|
 | `schema` | Schema | Yes | - | Schema definition created with `x.row()` |
 | `getSessionToken` | `() => Promise<string>` | Yes | - | Async callback that asks your backend for a short-lived importer session token |
-| `importIdentifier` | `string` | Yes | - | Unique identifier for this import type |
+| `importNamespace` | `string` | Yes | - | Stable namespace string your app assigns to this importer configuration. Keep it the same for the same workflow; use a different value for different importers. |
 | `title` | `string` | No | - | Title shown in the importer header |
 | `preload` | `boolean` | No | `true` | Preload the importer for instant display |
 | `debug` | `boolean` | No | `false` | Enable debug logging |
-| `theme` | `ECSVTheme` | No | - | Custom theme configuration |
+| `theme` | `Theme` | No | - | Custom theme configuration |
 | `colorMode` | `ColorModePref` | No | - | Light/dark mode (`'light'`, `'dark'`, or `'system'`) |
 | `customCSS` | `string` | No | - | Custom CSS to inject into the importer |
-| `fonts` | `Record<string, ECSVFontSource>` | No | - | Custom font sources |
+| `fonts` | `Record<string, FontSource>` | No | - | Custom font sources |
 | `stepDisplay` | `'progressBar' \| 'segmented' \| 'numbered'` | No | `'progressBar'` | Step indicator style |
 | `previewSchemaBeforeUpload` | `boolean` | No | `true` | Show schema preview before upload |
-| `aiColumnMatching` | `boolean` | No | `true` | Enable AI-assisted column matching |
-| `aiTransform` | `boolean` | No | `true` | Enable AI-assisted transform generation |
+| `columnMatching` | `{ type: "managed"; exact?: boolean; caseInsensitive?: boolean; normalized?: boolean; inference?: boolean } \| { type: "custom"; columnMatchHandler: (...) => Promise<...> }` | No | `undefined` | Configure managed column matching or provide a custom matcher |
+| `promptedEdits` | `{ type: "managed" } \| { type: "custom"; promptedEditHandler: (...) => Promise<...> }` | No | `undefined` | Enable managed prompted edits or provide a custom edit handler |
 | `templateDownload` | `TemplateDownloadOptions<TSchema>` | No | - | Template download configuration with optional schema-typed example rows |
-| `storage` | `{ type: "local" } \| { type: "custom", ... }` | No | - | Enable Recovered Sessions with the built-in local backend or a custom adapter implementing `get`, `set`, and `remove` |
+| `sessionRecovery` | `SessionRecoveryOptions` | No | - | Enable Recovered sessions with the built-in local backend or a custom adapter implementing `get`, `set`, and `remove` |
 | `locale` | `DeepPartial<ExpressCSVLocaleInput>` | No | - | Localization overrides |
 | `disableStatusStep` | `boolean` | No | - | Skip the success/error status screen |
 
@@ -427,9 +441,7 @@ function useExpressCSV<TSchema>(
 | Property | Type | Description |
 |---|---|---|
 | `open` | `(options: OpenOptions) => void` | Opens the importer. Requires `onData` for delivery. |
-| `importerState` | `ImporterState` | Current importer lifecycle state (reactive) |
-| `isInitialising` | `boolean` | `true` while the importer is initializing or opening |
-| `isOpen` | `boolean` | `true` while the importer is open |
+| `status` | `ImporterStatus` | Current importer lifecycle status (reactive) |
 
 ### `OpenOptions<T>`
 
@@ -437,14 +449,13 @@ Options passed to `open()`.
 
 | Option | Type | Required | Description |
 |---|---|---|---|
-| `onData` | `(chunk: RecordsChunk<T>, next: () => void) => void` | Yes | Callback for each delivered chunk. Call `next()` to continue. |
-| `chunkSize` | `number` | No | Records per chunk (default: 1000) |
+| `onData` | `(chunk: RecordsChunk<T>, next: () => void) => void` | Yes | Callback for each delivered chunk. Call `next()` after your backend accepts the current chunk. |
+| `chunkSize` | `ChunkSize` | No | Delivery packet size. Defaults to `{ unit: "kb", value: 500 }`. `kb` uses decimal kilobytes (`1 KB = 1000 bytes`). Use `{ unit: "kb", value: 500 }` for KB or `{ unit: "rows", value: 500 }` for row counts. Zero or negative values send all records in one chunk. |
 | `onComplete` | `(context: { sessionId: string }) => void` | No | Called when all chunks have been processed |
 | `onCancel` | `(context: { sessionId: string }) => void` | No | Called when the user cancels the import |
 | `onError` | `(error: Error, context: { sessionId: string }) => void` | No | Called when an error occurs |
-| `onImporterOpen` | `() => void` | No | Called when the importer opens |
-| `onImporterClose` | `(reason: 'user_close' \| 'cancel' \| 'complete' \| 'error') => void` | No | Called when the importer closes |
-| `onStepChange` | `(stepId, previousStepId?) => void` | No | Called when the wizard step changes |
+| `onOpen` | `(context: { sessionId: string }) => void` | No | Called when the importer opens |
+| `onStepChange` | `(stepId, previousStepId?) => void` | No | Called when the importer step changes |
 
 ### `RecordsChunk<T>`
 
@@ -452,10 +463,10 @@ Options passed to `open()`.
 interface RecordsChunk<T> {
   records: T[]; // Automatically typed to your schema
   totalChunks: number;
-  currentChunkIndex: number;
+  chunkIndex: number;
   totalRecords: number;
   sessionId: string;
-  chunkIdempotencyKey: string;
+  deliveryId: string;
 }
 ```
 
@@ -570,7 +581,6 @@ All field types support:
 |---|---|
 | `.label(text)` | User-facing label shown in the importer |
 | `.description(text)` | Help text for the field |
-| `.example(text)` | Example value shown as placeholder |
 | `.optional()` | Makes the field optional (default is required) |
 | `.refine(fn, params?)` | Custom per-value validation — any sync or async JS function |
 | `.refineBatch(fn, params?)` | Custom whole-column validation — receives all values at once |