@expresscsv/react 0.1.5 → 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,7 +1,7 @@
 # @expresscsv/react
 
 [![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)
+![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.
 
@@ -93,7 +93,7 @@ const handleImport = () => {
 };
 ```
 
-To disable preloading:
+To disable preloading (there will be a brief loading screen instead):
 
 ```tsx
 const { open } = useExpressCSV({
@@ -104,6 +104,139 @@ const { open } = useExpressCSV({
 });
 ```
 
+## 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() {
+  const { open } = useExpressCSV({
+    schema,
+    publishableKey: "your-publishable-key",
+    importIdentifier: "user-import",
+    theme,
+  });
+  // ...
+}
+```
+
+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`:
+
+```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;
+    }
+  `,
+});
+```
+
+### Custom Fonts
+
+Load custom fonts via the `fonts` option:
+
+```tsx
+const { open } = useExpressCSV({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
+  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
 
 Deliver data to a server endpoint instead of (or in addition to) processing locally:
@@ -261,7 +394,7 @@ function useExpressCSV<TSchema>(
 | `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 |
+| `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 |
@@ -301,7 +434,7 @@ Options passed to `open()`. At least one of `onData` or `webhook` must be provid
 
 ```typescript
 interface RecordsChunk<T> {
-  records: T[];
+  records: T[]; // Automatically typed to your schema
   totalChunks: number;
   currentChunkIndex: number;
   totalRecords: number;
@@ -323,24 +456,86 @@ interface WebhookConfig {
 
 ### Schema Builder
 
-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.
+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({
-  name: x.string().label("Name").min(2).max(100),
+  // Strings with validation
+  name: x.string().label("Full Name").min(2).max(100),
   email: x.string().email().label("Email"),
-  age: x.number().label("Age").min(0).integer(),
+  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: "Editor", value: "editor" },
+    { label: "Viewer", value: "viewer" },
   ]).label("Role"),
-  startDate: x.date().label("Start Date"),
-  isActive: x.boolean().label("Active"),
+
+  // Multi-selection
+  tags: x.multiselect([
+    { label: "Engineering", value: "eng" },
+    { label: "Design", value: "design" },
+    { label: "Marketing", value: "mkt" },
+  ]).label("Tags"),
 });
 ```
 
+#### 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:

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.5",
+  "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"
   }
 }