@expresscsv/react 0.1.3 → 0.1.5

package/README.md

@@ -1,6 +1,9 @@
-# ExpressCSV React SDK
+# @expresscsv/react
 
-A React component wrapper for the ExpressCSV SDK that provides a simple, declarative way to integrate CSV import functionality into your React applications.
+[![npm version](https://img.shields.io/npm/v/@expresscsv/react.svg)](https://www.npmjs.com/package/@expresscsv/react)
+[![license](https://img.shields.io/npm/l/@expresscsv/react.svg)](https://github.com/nicholasgriffintn/expresscsv/blob/main/LICENSE)
+
+React hook for embedding the [ExpressCSV](https://expresscsv.com) CSV import widget. Wraps [`@expresscsv/sdk`](https://www.npmjs.com/package/@expresscsv/sdk) with automatic lifecycle management and reactive state.
 
 ## Installation
 
@@ -15,47 +18,45 @@ npm install @expresscsv/react
 yarn add @expresscsv/react
 ```
 
-## Usage
-
-The React SDK provides a `useExpressCSV` hook for easy integration into your React components.
-
-### Basic Usage
+> **Peer dependency:** React 18+
 
-The React SDK provides a `useExpressCSV` hook for easy integration:
+## Quick Start
 
 ```tsx
-import { useExpressCSV, x, type Infer } from '@expresscsv/react';
+import { useExpressCSV, x } from "@expresscsv/react";
 
 const schema = x.row({
-  name: x.string().label('Full Name'),
-  email: x.string().email().label('Email Address'),
-  age: x.number().label('Age').min(18),
+  name: x.string().label("Full Name"),
+  email: x.string().email().label("Email Address"),
+  age: x.number().label("Age").min(18),
 });
 
 function App() {
-  const { open, isOpen, widgetState } = useExpressCSV({
+  const { open, isOpen } = useExpressCSV({
     schema,
-    title: "Import Users",
+    publishableKey: "your-publishable-key",
     importIdentifier: "user-import",
+    title: "Import Users",
   });
 
   const handleImport = () => {
     open({
-      chunkSize: 100,
+      chunkSize: 500,
       onData: async (chunk, next) => {
-        console.log(`Processing chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}`);
-        console.log('CSV data:', chunk.records);
-        // Process your validated data here
+        console.log(
+          `Chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}`
+        );
+        console.log("Records:", chunk.records);
         next();
       },
       onComplete: () => {
-        console.log('All chunks processed');
+        console.log("All chunks processed");
       },
       onCancel: () => {
-        console.log('User cancelled import');
+        console.log("User cancelled");
       },
       onError: (error) => {
-        console.error('Import error:', error);
+        console.error("Import error:", error);
       },
     });
   };
@@ -68,226 +69,166 @@ function App() {
 }
 ```
 
-### Preload for Instant Display
+Your `publishableKey` is available from the [ExpressCSV dashboard](https://expresscsv.com). Two key types are available: **production** keys for live usage, and **dev/testing** keys that provide unlimited test imports.
 
-By default, the widget preloads in the background for instant display. This provides the best user experience with minimal perceived loading time.
+## Preloading
 
-```tsx
-import { useExpressCSV, x } from '@expresscsv/react';
+By default the widget preloads in a hidden iframe so it appears instantly when `open()` is called:
 
-const schema = x.row({
-  name: x.string().label('Full Name'),
-  email: x.string().email().label('Email Address'),
+```tsx
+const { open } = useExpressCSV({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
 });
 
-function App() {
-  // Preload is enabled by default
-  const { open } = useExpressCSV({
-    schema,
-    title: "Import Users",
-    importIdentifier: "user-import",
+// Widget displays instantly
+const handleImport = () => {
+  open({
+    onData: (chunk, next) => {
+      console.log("Records:", chunk.records);
+      next();
+    },
   });
-
-  const handleImport = () => {
-    open({
-      onData: async (chunk, next) => {
-        console.log('CSV data:', chunk.records);
-        next();
-      },
-    });
-  };
-
-  return (
-    <button onClick={handleImport}>
-      Import CSV
-    </button>
-  );
-}
+};
 ```
 
-To disable preload for specific use cases (not recommended for most scenarios):
+To disable preloading:
 
 ```tsx
 const { open } = useExpressCSV({
   schema,
-  title: "Import Users",
+  publishableKey: "your-publishable-key",
   importIdentifier: "user-import",
-  preload: false, // Disable preload
+  preload: false,
 });
 ```
 
-### Webhook Delivery
+## Webhook Delivery
 
-You can deliver CSV data to a webhook endpoint instead of (or in addition to) using local callbacks. The backend will handle retries, exponential backoff, and deliver data in chunks:
+Deliver data to a server endpoint instead of (or in addition to) processing locally:
 
 ```tsx
-import { useExpressCSV, x, type Infer, type WebhookConfig } from '@expresscsv/react';
+import { useExpressCSV, x } from "@expresscsv/react";
 
 const schema = x.row({
-  name: x.string().label('Full Name'),
-  email: x.string().email().label('Email Address'),
+  name: x.string().label("Full Name"),
+  email: x.string().email().label("Email Address"),
 });
 
 function App() {
   const { open } = useExpressCSV({
     schema,
-    title: "Import Users",
+    publishableKey: "your-publishable-key",
     importIdentifier: "user-import",
+    title: "Import Users",
   });
 
   const handleImport = () => {
     open({
-      chunkSize: 500, // Optional: chunk size for webhook delivery (default: 1000)
       webhook: {
-        url: 'https://api.example.com/webhooks/csv-import',
-        method: 'POST',
+        url: "https://api.example.com/webhooks/csv-import",
+        method: "POST",
         headers: {
-          'Authorization': 'Bearer your-api-token',
-          'X-Custom-Header': 'custom-value',
+          Authorization: "Bearer your-api-token",
         },
         metadata: {
-          // Optional: arbitrary metadata to include in webhook payload
-          source: 'react-app',
-          userId: 'user-123',
+          source: "react-app",
+          userId: "user-123",
         },
       },
       onComplete: () => {
-        console.log('Webhook delivery initiated');
+        console.log("Webhook delivery initiated");
       },
       onError: (error) => {
-        console.error('Webhook delivery error:', error);
+        console.error("Delivery error:", error);
       },
     });
   };
 
-  return (
-    <button onClick={handleImport}>
-      Import CSV via Webhook
-    </button>
-  );
+  return <button onClick={handleImport}>Import CSV via Webhook</button>;
 }
 ```
 
 ### Combined Local Callback and Webhook
 
-You can use both `onData` callback and webhook delivery simultaneously:
-
 ```tsx
-import { useExpressCSV, x, type Infer } from '@expresscsv/react';
-
-const schema = x.row({
-  name: x.string().label('Full Name'),
-  email: x.string().email().label('Email Address'),
+open({
+  chunkSize: 500,
+  onData: async (chunk, next) => {
+    await saveToLocalDatabase(chunk.records);
+    next();
+  },
+  webhook: {
+    url: "https://api.example.com/webhooks/csv-import",
+    headers: { Authorization: "Bearer your-api-token" },
+  },
+  onComplete: () => {
+    console.log("Local processing and webhook delivery complete");
+  },
 });
-
-function App() {
-  const { open } = useExpressCSV({
-    schema,
-    title: "Import Users",
-    importIdentifier: "user-import",
-  });
-
-  const handleImport = () => {
-    open({
-      chunkSize: 100,
-      // Process locally
-      onData: async (chunk, next) => {
-        console.log(`Processing chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}`);
-        // Your local processing logic
-        await processChunkLocally(chunk.records);
-        next();
-      },
-      // Also deliver to webhook
-      webhook: {
-        url: 'https://api.example.com/webhooks/csv-import',
-        headers: {
-          'Authorization': 'Bearer your-api-token',
-        },
-      },
-      onComplete: () => {
-        console.log('All chunks processed and webhook delivery initiated');
-      },
-    });
-  };
-
-  return (
-    <button onClick={handleImport}>
-      Import CSV
-    </button>
-  );
-}
 ```
 
-### Advanced Example with Error Handling
+## Advanced Example
 
 ```tsx
-import { useExpressCSV, x, type Infer } from '@expresscsv/react';
-import { useState } from 'react';
+import { useExpressCSV, x, type Infer } from "@expresscsv/react";
+import { useState } from "react";
 
 const candidateSchema = x.row({
-  firstName: x.string().label('First Name'),
-  lastName: x.string().label('Last Name'),
-  email: x.string().email().label('Email'),
-  experienceLevel: x.select([
-    { label: 'Entry Level', value: 'entry' },
-    { label: 'Mid Level', value: 'mid' },
-    { label: 'Senior Level', value: 'senior' },
-  ]).label('Experience Level'),
-  salary: x.number().currency('USD').min(30000).label('Expected Salary'),
+  firstName: x.string().label("First Name"),
+  lastName: x.string().label("Last Name"),
+  email: x.string().email().label("Email"),
+  level: x
+    .select([
+      { label: "Entry Level", value: "entry" },
+      { label: "Mid Level", value: "mid" },
+      { label: "Senior Level", value: "senior" },
+    ])
+    .label("Experience Level"),
+  salary: x.number().currency("USD").min(30000).label("Expected Salary"),
 });
 
 function CandidateImporter() {
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
+  const [status, setStatus] = useState<string | null>(null);
 
-  const { open } = useExpressCSV({
+  const { open, isOpen } = useExpressCSV({
     schema: candidateSchema,
-    title: "Import Candidates",
+    publishableKey: "your-publishable-key",
     importIdentifier: "candidate-import",
-    developerMode: process.env.NODE_ENV === 'development',
-    debug: process.env.NODE_ENV === 'development',
+    title: "Import Candidates",
+    developerMode: process.env.NODE_ENV === "development",
   });
 
   const handleImport = () => {
-    setIsLoading(true);
-    setError(null);
+    setStatus(null);
 
     open({
       onData: async (chunk, next) => {
-        try {
-          // Process the candidates chunk
-          await importCandidates(chunk.records);
-          next();
-        } catch (err) {
-          setError('Failed to import candidates. Please try again.');
-          throw err;
-        }
+        setStatus(
+          `Processing chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}...`
+        );
+        await importCandidates(chunk.records);
+        next();
       },
       onComplete: () => {
-        setIsLoading(false);
-        alert('Successfully imported all candidates!');
+        setStatus("Import complete!");
       },
       onError: (error) => {
-        setIsLoading(false);
-        setError(`Import failed: ${error.message}`);
+        setStatus(`Error: ${error.message}`);
       },
       onCancel: () => {
-        setIsLoading(false);
+        setStatus(null);
       },
     });
   };
 
   return (
     <div>
-      {error && <div className="error">{error}</div>}
-      
-      <button 
-        onClick={handleImport}
-        disabled={isLoading}
-        className="import-button"
-      >
-        {isLoading ? 'Processing...' : 'Import Candidates'}
+      <button onClick={handleImport} disabled={isOpen}>
+        {isOpen ? "Importing..." : "Import Candidates"}
       </button>
+      {status && <p>{status}</p>}
     </div>
   );
 }
@@ -295,126 +236,134 @@ function CandidateImporter() {
 
 ## API Reference
 
-### useExpressCSV Hook
+### `useExpressCSV(options)`
 
-A custom hook that provides access to the CSV importer functionality.
-
-#### Parameters
-
-```tsx
-interface UseExpressCSVOptions<TSchema> {
-  schema: TSchema;
-  title?: string;
-  importIdentifier: string;
-  publishableKey: string;
-  debug?: boolean;
-  developerMode?: boolean;
-  preload?: boolean; // Defaults to true
-  theme?: ECSVTheme;
-  colorMode?: ColorModeConfig;
-  customCSS?: string;
-  fonts?: Record<string, ECSVFontSource>;
-  stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
-}
-```
-
-#### Returns
-
-```tsx
-{
+```typescript
+function useExpressCSV<TSchema>(
+  options: UseExpressCSVOptions<TSchema>
+): {
   open: (options: OpenOptions<Infer<TSchema>>) => void;
   widgetState: WidgetState;
   isInitialising: boolean;
   isOpen: boolean;
-}
+};
 ```
 
-### OpenOptions
-
-Options passed to the `open` method:
-
-```tsx
-interface OpenOptions<T> {
-  // At least one of onData or webhook must be provided
-  onData?: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
-  webhook?: WebhookConfig;
-  
-  // Optional configuration
-  chunkSize?: number; // Default: 1000
-  onComplete?: () => void;
-  onCancel?: () => void;
-  onError?: (error: Error) => void;
+#### Options
+
+| Option | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `schema` | Schema | Yes | - | Schema definition created with `x.row()` |
+| `publishableKey` | `string` | Yes | - | Your publishable key from the [dashboard](https://expresscsv.com) |
+| `importIdentifier` | `string` | Yes | - | Unique identifier for this import type |
+| `title` | `string` | No | - | Title shown in the widget header |
+| `preload` | `boolean` | No | `true` | Preload widget for instant display |
+| `debug` | `boolean` | No | `false` | Enable debug logging |
+| `developerMode` | `boolean` | No | `false` | Enable developer mode features |
+| `theme` | `ECSVTheme` | No | - | Custom theme configuration |
+| `colorMode` | `ColorModeConfig` | No | - | Light/dark mode settings |
+| `customCSS` | `string` | No | - | Custom CSS to inject into the widget |
+| `fonts` | `Record<string, ECSVFontSource>` | No | - | Custom font sources |
+| `stepDisplay` | `'progressBar' \| 'segmented' \| 'numbered'` | No | `'progressBar'` | Step indicator style |
+| `previewSchemaBeforeUpload` | `boolean` | No | `true` | Show schema preview before upload |
+| `templateDownload` | `TemplateDownloadConfig` | No | - | Template download configuration |
+| `saveSession` | `boolean` | No | - | Persist session state |
+| `locale` | `DeepPartial<ExpressCSVLocaleInput>` | No | - | Localization overrides |
+
+#### Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `open` | `(options: OpenOptions) => void` | Opens the widget. Requires at least one of `onData` or `webhook`. |
+| `widgetState` | `WidgetState` | Current widget state (reactive) |
+| `isInitialising` | `boolean` | `true` while the widget is initializing or opening |
+| `isOpen` | `boolean` | `true` while the widget is open |
+
+### `OpenOptions<T>`
+
+Options passed to `open()`. At least one of `onData` or `webhook` must be provided.
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `onData` | `(chunk: RecordsChunk<T>, next: () => void) => void` | * | Callback for each chunk. Call `next()` to continue. |
+| `webhook` | `WebhookConfig` | * | Webhook endpoint for server-side delivery |
+| `chunkSize` | `number` | No | Records per chunk (default: 1000) |
+| `onComplete` | `() => void` | No | Called when all chunks have been processed |
+| `onCancel` | `() => void` | No | Called when the user cancels the import |
+| `onError` | `(error: Error) => void` | No | Called when an error occurs |
+| `onWidgetOpen` | `() => void` | No | Called when the widget opens |
+| `onWidgetClose` | `(reason: string) => void` | No | Called when the widget closes |
+| `onStepChange` | `(stepId, previousStepId?) => void` | No | Called when the wizard step changes |
+
+\* At least one of `onData` or `webhook` is required.
+
+### `RecordsChunk<T>`
+
+```typescript
+interface RecordsChunk<T> {
+  records: T[];
+  totalChunks: number;
+  currentChunkIndex: number;
+  totalRecords: number;
 }
 ```
 
-### WebhookConfig
-
-Configuration for webhook delivery:
+### `WebhookConfig`
 
-```tsx
+```typescript
 interface WebhookConfig {
-  url: string; // Required: Webhook endpoint URL
-  headers?: Record<string, string>; // Optional HTTP headers
-  method?: 'POST' | 'PUT' | 'PATCH'; // Default: 'POST'
-  timeout?: number; // Request timeout in milliseconds (default: 30000)
-  retries?: number; // Number of retry attempts (default: 0)
-  metadata?: Record<string, unknown>; // Optional metadata to include in webhook payload
+  url: string;
+  headers?: Record<string, string>;
+  method?: "POST" | "PUT" | "PATCH";
+  timeout?: number;
+  retries?: number;
+  metadata?: Record<string, unknown>;
 }
 ```
 
-**Note:** The `chunkSize` option in `OpenOptions` controls the chunk size for both `onData` callbacks and webhook delivery. The backend will deliver webhooks in chunks of this size (or default 1000 if not specified).
-
 ### Schema Builder
 
-The schema builder (`x`) provides a fluent API for defining field validation:
+The `x` schema builder is re-exported from `@expresscsv/sdk`. See the [SDK README](https://www.npmjs.com/package/@expresscsv/sdk#schema-builder) for the full field type and modifier reference.
 
 ```tsx
+import { x } from "@expresscsv/react";
+
 const schema = x.row({
-  // String fields
-  name: x.string().label('Name').minLength(2).maxLength(50),
-  
-  // Email validation
-  email: x.string().email().label('Email Address'),
-  
-  // Number fields with constraints
-  age: x.number().label('Age').min(18).max(100),
-  
-  // Currency fields
-  salary: x.number().currency('USD').min(30000),
-  
-  // Select dropdowns
+  name: x.string().label("Name").min(2).max(100),
+  email: x.string().email().label("Email"),
+  age: x.number().label("Age").min(0).integer(),
   role: x.select([
-    { label: 'Admin', value: 'admin' },
-    { label: 'User', value: 'user' },
-  ]).label('Role'),
-  
-  // Date fields
-  startDate: x.date().label('Start Date'),
-  
-  // Boolean fields
-  isActive: x.boolean().label('Active Status'),
+    { label: "Admin", value: "admin" },
+    { label: "User", value: "user" },
+  ]).label("Role"),
+  startDate: x.date().label("Start Date"),
+  isActive: x.boolean().label("Active"),
 });
 ```
 
-## TypeScript Support
+## TypeScript
 
-The component provides full TypeScript support with automatic type inference:
+Full type inference from your schema is built in:
 
 ```tsx
+import { x, type Infer } from "@expresscsv/react";
+
 const schema = x.row({
   name: x.string(),
   age: x.number(),
 });
 
-// results is automatically typed as { name: string; age: number }[]
-const handleResults = (results: Infer<typeof schema>[]) => {
-  results.forEach(row => {
-    console.log(row.name); // string
-    console.log(row.age);  // number
-  });
-};
+type Row = Infer<typeof schema>;
+// { name: string; age: number }
 ```
 
+The `onData` callback receives `RecordsChunk<Row>` automatically -- no manual type annotations needed.
+
+## Resources
+
+- [ExpressCSV Dashboard](https://expresscsv.com) -- manage your imports and API keys
+- [`@expresscsv/sdk`](https://www.npmjs.com/package/@expresscsv/sdk) -- vanilla JS SDK (no React dependency)
+
 ## License
 
-ISC 
+[MIT](./LICENSE)