@expresscsv/sdk 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/sdk
 
 [![npm version](https://img.shields.io/npm/v/@expresscsv/sdk.svg)](https://www.npmjs.com/package/@expresscsv/sdk)
-[![license](https://img.shields.io/npm/l/@expresscsv/sdk.svg)](https://github.com/nicholasgriffintn/expresscsv/blob/main/LICENSE)
+![license](https://img.shields.io/npm/l/@expresscsv/sdk.svg)
 
 A TypeScript SDK for embedding the [ExpressCSV](https://expresscsv.com) CSV import widget into any web application. Define a schema, open the widget, and receive validated, typed data in chunks.
 
@@ -120,7 +120,7 @@ const importer = new CSVImporter({
 importer.open({ onData: (chunk, next) => { /* ... */ next(); } });
 ```
 
-To disable preloading:
+To disable preloading (there will be a brief loading screen instead):
 
 ```typescript
 const importer = new CSVImporter({
@@ -131,6 +131,136 @@ const importer = new CSVImporter({
 });
 ```
 
+## 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:
+
+```typescript
+import { CSVImporter, x, type ECSVTheme } from "@expresscsv/sdk";
+
+// 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",
+    },
+  },
+};
+
+const importer = new CSVImporter({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
+  theme,
+});
+```
+
+Theme variables:
+
+| 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`:
+
+```typescript
+const importer = new CSVImporter({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
+  colorMode: "system", // 'light' | 'dark' | 'system'
+});
+```
+
+### Custom CSS
+
+Inject custom CSS for fine-grained styling overrides.
+
+```typescript
+const importer = new CSVImporter({
+  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:
+
+```typescript
+const importer = new CSVImporter({
+  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",
+  },
+});
+```
+
 ## Schema Builder
 
 The `x` schema builder provides a type-safe, fluent API for defining your CSV structure.
@@ -233,7 +363,7 @@ new CSVImporter(options: SDKOptions)
 | `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 |
@@ -274,6 +404,8 @@ await importer.close(reason?: 'user_close' | 'cancel' | 'complete' | 'error'): P
 
 #### Status Methods
 
+
+
 | Method | Returns | Description |
 |---|---|---|
 | `getState()` | `WidgetState` | Current widget state |
@@ -285,10 +417,6 @@ await importer.close(reason?: 'user_close' | 'cancel' | 'complete' | 'error'): P
 | `getStatus()` | `object` | Comprehensive status snapshot |
 | `getVersion()` | `string` | SDK version |
 
-#### `resetWidget()`
-
-Resets the widget state. Returns `Promise<void>`.
-
 #### `restart(newOptions?)`
 
 Restarts the widget, optionally with updated options. Returns `Promise<void>`.
@@ -299,7 +427,7 @@ The object passed to `onData` callbacks:
 
 ```typescript
 interface RecordsChunk<T> {
-  records: T[];
+  records: T[]; // Automatically typed to your schema
   totalChunks: number;
   currentChunkIndex: number;
   totalRecords: number;

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
  */
@@ -1326,7 +1317,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private createAndAppendIframe;
     private destroy;
     close(reason?: 'user_close' | 'cancel' | 'complete' | 'error'): Promise<void>;
-    resetWidget(): Promise<void>;
+    private resetWidget;
     restart(newOptions?: Partial<SDKOptions<TSchema>>): Promise<void>;
     private handleWidgetClosed;
     private hideContainer;
@@ -3755,7 +3746,7 @@ export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, u
     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/sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "SDK for integrating widget",
   "module": "dist/index.mjs",
   "types": "dist/index.d.mts",