@expresscsv/react 0.1.4 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ExpressCSV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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)
+
+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.
+> **Peer dependency:** React 18+
 
-### Basic Usage
-
-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,299 @@ 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.
+
+## Preloading
 
-By default, the widget preloads in the background for instant display. This provides the best user experience with minimal perceived loading time.
+By default the widget preloads in a hidden iframe so it appears instantly when `open()` is called:
 
 ```tsx
-import { useExpressCSV, x } from '@expresscsv/react';
+const { open } = useExpressCSV({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
+});
 
-const schema = x.row({
-  name: x.string().label('Full Name'),
-  email: x.string().email().label('Email Address'),
+// Widget displays instantly
+const handleImport = () => {
+  open({
+    onData: (chunk, next) => {
+      console.log("Records:", chunk.records);
+      next();
+    },
+  });
+};
+```
+
+To disable preloading (there will be a brief loading screen instead):
+
+```tsx
+const { open } = useExpressCSV({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
+  preload: false,
 });
+```
+
+## Theming and Styling
+
+Customize the widget's appearance with the `theme`, `colorMode`, `customCSS`, and `fonts` options.
+
+### Theme
+
+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";
+
+// Single theme (both modes)
+const theme: ECSVTheme = {
+  primary: "#4F46E5",
+  "primary-foreground": "#ffffff",
+  background: "#ffffff",
+  foreground: "#0f172a",
+  border: "#e5e7eb",
+  ring: "#A5B4FC",
+  radius: "0.5rem",
+};
+
+// Dual-mode (light and dark)
+const dualTheme: ECSVTheme = {
+  modes: {
+    light: {
+      primary: "#4F46E5",
+      background: "#ffffff",
+      foreground: "#0f172a",
+    },
+    dark: {
+      primary: "#a5b4fc",
+      background: "#09090b",
+      foreground: "#fafafa",
+    },
+  },
+};
 
 function App() {
-  // Preload is enabled by default
   const { open } = useExpressCSV({
     schema,
-    title: "Import Users",
+    publishableKey: "your-publishable-key",
     importIdentifier: "user-import",
+    theme,
   });
+  // ...
+}
+```
 
-  const handleImport = () => {
-    open({
-      onData: async (chunk, next) => {
-        console.log('CSV data:', chunk.records);
-        next();
-      },
-    });
-  };
+Theme variables (light mode defaults):
+
+| Variable | Default |
+|---|---|
+| `radius` | `0.625rem` |
+| `background` | `oklch(1 0 0)` |
+| `foreground` | `oklch(0.145 0 0)` |
+| `card` | `oklch(1 0 0)` |
+| `card-foreground` | `oklch(0.145 0 0)` |
+| `popover` | `oklch(1 0 0)` |
+| `popover-foreground` | `oklch(0.145 0 0)` |
+| `primary` | `oklch(0.205 0 0)` |
+| `primary-foreground` | `oklch(0.985 0 0)` |
+| `secondary` | `oklch(0.97 0 0)` |
+| `secondary-foreground` | `oklch(0.205 0 0)` |
+| `muted` | `oklch(0.97 0 0)` |
+| `muted-foreground` | `oklch(0.556 0 0)` |
+| `accent` | `oklch(0.7 0.2 145)` |
+| `accent-foreground` | `oklch(0.985 0 0)` |
+| `destructive` | `oklch(0.577 0.245 27.325)` |
+| `destructive-foreground` | `oklch(0.985 0 0)` |
+| `success` | `oklch(0.7 0.2 145)` |
+| `success-foreground` | `oklch(0.985 0 0)` |
+| `warning` | `oklch(0.769 0.188 70)` |
+| `warning-foreground` | `oklch(0.985 0 0)` |
+| `border` | `oklch(0.922 0 0)` |
+| `input` | `oklch(0.922 0 0)` |
+| `ring` | `oklch(0.708 0 0)` |
+| `font-title` | `inherit` |
+| `font-body` | `inherit` |
+
+### Color Mode
+
+Control light/dark mode with `colorMode`:
 
-  return (
-    <button onClick={handleImport}>
-      Import CSV
-    </button>
-  );
-}
+```tsx
+const { open } = useExpressCSV({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
+  colorMode: "system", // 'light' | 'dark' | 'system'
+});
+```
+
+### Custom CSS
+
+Inject custom CSS for fine-grained styling overrides.
+
+```tsx
+const { open } = useExpressCSV({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
+  customCSS: `
+    .ecsv [data-step="upload"] {
+      border-radius: 1rem;
+    }
+    .ecsv button {
+      font-weight: 600;
+    }
+  `,
+});
 ```
 
-To disable preload for specific use cases (not recommended for most scenarios):
+### Custom Fonts
+
+Load custom fonts via the `fonts` option:
 
 ```tsx
 const { open } = useExpressCSV({
   schema,
-  title: "Import Users",
+  publishableKey: "your-publishable-key",
   importIdentifier: "user-import",
-  preload: false, // Disable preload
+  fonts: {
+    title: { source: "google", name: "Space Grotesk", weights: [400, 600, 700] },
+    body: { source: "custom", url: "https://example.com/font.woff2", format: "woff2" },
+  },
+  theme: {
+    "font-title": "'Space Grotesk', sans-serif",
+    "font-body": "'Custom Font', sans-serif",
+  },
 });
 ```
 
-### 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 +369,196 @@ function CandidateImporter() {
 
 ## API Reference
 
-### useExpressCSV Hook
-
-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
+### `useExpressCSV(options)`
 
-```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` | `ColorModePref` | No | - | Light/dark mode (`'light'`, `'dark'`, or `'system'`) |
+| `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[]; // Automatically typed to your schema
+  totalChunks: number;
+  currentChunkIndex: number;
+  totalRecords: number;
 }
 ```
 
-### WebhookConfig
+### `WebhookConfig`
 
-Configuration for webhook delivery:
-
-```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 provides a type-safe, fluent API for defining your CSV structure.
+
+#### Field Types
 
 ```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
+  // Strings with validation
+  name: x.string().label("Full Name").min(2).max(100),
+  email: x.string().email().label("Email"),
+  website: x.string().url().label("Website").optional(),
+
+  // Numbers with constraints
+  age: x.number().label("Age").min(0).max(150).integer(),
+  salary: x.number().currency("USD").label("Salary").min(0),
+
+  // Boolean
+  isActive: x.boolean().label("Active"),
+
+  // Dates and times
+  startDate: x.date().label("Start Date"),
+  createdAt: x.datetime().label("Created At"),
+
+  // Single selection (requires { label, value } objects)
   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: "Editor", value: "editor" },
+    { label: "Viewer", value: "viewer" },
+  ]).label("Role"),
+
+  // Multi-selection
+  tags: x.multiselect([
+    { label: "Engineering", value: "eng" },
+    { label: "Design", value: "design" },
+    { label: "Marketing", value: "mkt" },
+  ]).label("Tags"),
 });
 ```
 
-## TypeScript Support
-
-The component provides full TypeScript support with automatic type inference:
+#### Common Modifiers
+
+All field types support:
+
+| Modifier | Description |
+|---|---|
+| `.label(text)` | User-facing label shown in the widget |
+| `.description(text)` | Help text for the field |
+| `.example(text)` | Example value shown as placeholder |
+| `.optional()` | Makes the field optional (default is required) |
+| `.refine(fn)` | Custom validation function |
+
+#### String Modifiers
+
+| Modifier | Description |
+|---|---|
+| `.email()` | Validates email format |
+| `.url()` | Validates URL format |
+| `.uuid()` | Validates UUID format |
+| `.ip()` | Validates IP address |
+| `.phone()` | Validates phone number |
+| `.regex(pattern)` | Matches a regular expression |
+| `.min(n)` | Minimum string length |
+| `.max(n)` | Maximum string length |
+| `.length(n)` | Exact string length |
+| `.includes(str)` | Must contain substring |
+| `.startsWith(str)` | Must start with prefix |
+| `.endsWith(str)` | Must end with suffix |
+
+#### Number Modifiers
+
+| Modifier | Description |
+|---|---|
+| `.min(n)` | Minimum value |
+| `.max(n)` | Maximum value |
+| `.integer()` | Must be a whole number |
+| `.multipleOf(n)` | Must be a multiple of n |
+| `.currency(code)` | Formats as currency (e.g. `"USD"`) |
+| `.percentage()` | Formats as percentage |
+
+## TypeScript
+
+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)

package/dist/index.d.mts

@@ -4,15 +4,6 @@ declare interface BICOptions {
 
 declare type BooleanControlType = 'toggle' | 'checkbox' | 'dropdown';
 
-/**
- * Color mode configuration
- */
-export declare interface ColorModeConfig {
-    default?: ColorModePref;
-    persist?: boolean;
-    onChange?: (mode: ColorModePref) => void;
-}
-
 /**
  * Color mode preference
  */
@@ -3744,7 +3735,7 @@ export declare interface UseExpressCSVOptions<TSchema extends ExType<unknown, Ex
     developerMode?: boolean;
     preload?: boolean;
     theme?: ECSVTheme;
-    colorMode?: ColorModeConfig;
+    colorMode?: ColorModePref;
     customCSS?: string;
     fonts?: Record<string, ECSVFontSource>;
     stepDisplay?: 'progressBar' | 'segmented' | 'numbered';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expresscsv/react",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "React component wrapper for ExpressCSV SDK",
   "module": "dist/index.mjs",
   "types": "dist/index.d.mts",
@@ -25,6 +25,6 @@
     "access": "public"
   },
   "peerDependencies": {
-    "react": "^18.0.0"
+    "react": ">=16.8.0"
   }
 }

package/dist/.dts/CSVImporter.d.ts

@@ -1,27 +0,0 @@
-import type { DeepPartial, ExpressCSVLocaleInput, TemplateDownloadConfig } from '@expresscsv/core';
-import { type ColorModeConfig, type ECSVFontSource, type ECSVTheme, type ExBaseDef, type ExType, type Infer, type OpenOptions, WidgetState } from '@expresscsv/sdk';
-export type { ColorModeConfig, ColorModePref, ECSVTheme, TailwindThemeVars, } from '@expresscsv/sdk';
-export interface UseExpressCSVOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> {
-    schema: TSchema;
-    title?: string;
-    importIdentifier: string;
-    publishableKey: string;
-    debug?: boolean;
-    developerMode?: boolean;
-    preload?: boolean;
-    theme?: ECSVTheme;
-    colorMode?: ColorModeConfig;
-    customCSS?: string;
-    fonts?: Record<string, ECSVFontSource>;
-    stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
-    previewSchemaBeforeUpload?: boolean;
-    templateDownload?: TemplateDownloadConfig;
-    saveSession?: boolean;
-    locale?: DeepPartial<ExpressCSVLocaleInput>;
-}
-export declare function useExpressCSV<TSchema extends ExType<unknown, ExBaseDef, unknown>>({ schema, title, importIdentifier, publishableKey, debug, developerMode, preload, theme, colorMode, customCSS, fonts, stepDisplay, previewSchemaBeforeUpload, templateDownload, saveSession, locale, }: UseExpressCSVOptions<TSchema>): {
-    open: (options: OpenOptions<Infer<TSchema>>) => void;
-    widgetState: WidgetState;
-    isInitialising: boolean;
-    isOpen: boolean;
-};

package/dist/.dts/index.d.ts

@@ -1,4 +0,0 @@
-export { useExpressCSV, type UseExpressCSVOptions, } from './CSVImporter';
-export { x, WidgetState, WidgetMode, ImportCancelledError, } from '@expresscsv/sdk';
-export type { Infer, ECSVFontSource, ECSVTheme, TailwindThemeVars, ColorModeConfig, ColorModePref, ExpressCSVStep, RecordsChunk, OpenOptions, WebhookConfig, DeliveryOptions, } from '@expresscsv/sdk';
-export type { TemplateDownloadConfig, TemplateDownloadFormat, ExpressCSVLocaleInput, DeepPartial, } from '@expresscsv/core';