@expresscsv/react 0.1.17 → 0.1.19

package/README.md

@@ -5,6 +5,8 @@
 
 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.
 
+If you want to define schemas in shared or backend code without any frontend dependencies, use [`@expresscsv/schemas`](https://www.npmjs.com/package/@expresscsv/schemas) for the schema definition itself, then pass that schema into `@expresscsv/react`.
+
 ## Installation
 
 ```bash
@@ -104,6 +106,40 @@ const { open } = useExpressCSV({
 });
 ```
 
+## Template Downloads
+
+Generated templates can include example rows that match your schema.
+
+```tsx
+import { useExpressCSV, x, type Infer } from "@expresscsv/react";
+
+const candidateSchema = x.row({
+  firstName: x.string().label("First Name"),
+  email: x.string().email().label("Email"),
+  role: x.select([
+    { label: "Admin", value: "admin" },
+    { label: "Editor", value: "editor" },
+  ]).label("Role"),
+});
+
+const { open } = useExpressCSV({
+  schema: candidateSchema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "candidate-import",
+  templateDownload: {
+    source: "generate",
+    formats: ["csv", "xlsx"],
+    exampleRows: () => [
+      {
+        firstName: "Alice",
+        email: "alice@example.com",
+        role: "admin",
+      },
+    ],
+  },
+});
+```
+
 ## Theming and Styling
 
 Customize the widget's appearance with the `theme`, `colorMode`, `customCSS`, and `fonts` options.
@@ -312,6 +348,8 @@ interface WebhookPayload {
 }
 ```
 
+When you already have a schema, prefer `InferWebhookPayload<typeof schema>` from `@expresscsv/schemas` instead of rewriting this object shape by hand.
+
 Example payload:
 
 ```json
@@ -350,6 +388,25 @@ Your endpoint should return a **2xx** status code to acknowledge each chunk. Non
 
 Chunks are delivered **serially** — the next chunk is only sent after the previous one succeeds.
 
+If your schema lives in shared or backend code via `@expresscsv/schemas`, you can reuse the built-in webhook payload helper in your webhook handler:
+
+```typescript
+import express from "express";
+import type { InferWebhookPayload } from "@expresscsv/schemas";
+import { candidateSchema } from "../shared/candidate-schema";
+
+const app = express();
+app.use(express.json());
+
+app.post("/webhooks/csv-import", async (req, res) => {
+  const payload = req.body as InferWebhookPayload<typeof candidateSchema>;
+
+  await importCandidates(payload.records);
+
+  res.status(200).json({ ok: true });
+});
+```
+
 Below is a minimal Express.js example:
 
 ```typescript
@@ -507,7 +564,7 @@ function useExpressCSV<TSchema>(
 | `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 |
+| `templateDownload` | `TemplateDownloadOptions<TSchema>` | No | - | Template download configuration with optional schema-typed example rows |
 | `saveSession` | `boolean` | No | - | Persist session state |
 | `locale` | `DeepPartial<ExpressCSVLocaleInput>` | No | - | Localization overrides |
 
@@ -566,6 +623,8 @@ interface WebhookConfig {
 
 The `x` schema builder provides a type-safe, fluent API for defining your CSV structure.
 
+For apps that share schemas with backend code or webhook receivers, prefer defining the schema in `@expresscsv/schemas` and importing it into your React app. That keeps schema authoring free of React and widget dependencies, while also giving your backend access to `InferWebhookPayload<typeof schema>`.
+
 #### Field Types
 
 ```tsx
@@ -604,6 +663,65 @@ const schema = x.row({
 });
 ```
 
+#### Runtime-Built Schemas
+
+For a fixed schema, keep it directly in `x.row(...)`:
+
+```tsx
+const schema = x.row({
+  email: x.string().email().label("Email"),
+  lifecycleStage: x
+    .select([
+      { label: "Lead", value: "lead" },
+      { label: "Customer", value: "customer" },
+      { label: "Churned", value: "churned" },
+    ])
+    .label("Lifecycle Stage"),
+  accountOwner: x.string().label("Account Owner").optional(),
+  contractValue: x.number().currency("USD").label("Contract Value").optional(),
+});
+```
+
+`x.row(...)` also works for runtime-built schemas, which is useful when the shape depends on account data, user preferences, or enabled custom fields.
+
+```tsx
+import { x } from "@expresscsv/react";
+
+function buildCustomerSchema(options: {
+  collectCrmId: boolean;
+  collectHealthScore: boolean;
+  collectSegment: boolean;
+}) {
+  return x.row({
+    email: x.string().email().label("Email"),
+    companyName: x.string().label("Company Name"),
+    ...(options.collectCrmId ? { crmId: x.string().label("CRM ID") } : {}),
+    ...(options.collectHealthScore
+      ? { healthScore: x.number().label("Health Score") }
+      : {}),
+    ...(options.collectSegment
+      ? {
+          segment: x
+            .select([
+              { label: "SMB", value: "smb" },
+              { label: "Mid-Market", value: "mid-market" },
+              { label: "Enterprise", value: "enterprise" },
+            ])
+            .label("Segment"),
+        }
+      : {}),
+  });
+}
+
+const schema = buildCustomerSchema({
+  collectCrmId: true,
+  collectHealthScore: true,
+  collectSegment: false,
+});
+```
+
+Dynamic schema assembly preserves the same runtime parsing behavior, but it can widen `Infer<typeof schema>` because the exact keys are no longer fully known to TypeScript. Use it intentionally.
+
 #### Common Modifiers
 
 All field types support:

package/dist/index.d.cts

@@ -3015,6 +3015,11 @@ declare class ExRow<T extends ExRowShape> extends ExType<{
      * Factory method to create an ExRow validator for a row of data
      *
      * @param shape - Object defining the structure of fields in the row
+     *
+     * Object literals preserve exact key inference. If callers build the shape
+     * through a widened variable or conditional assembly, TypeScript may widen
+     * the resulting row type as well.
+     *
      * @returns A new ExRow instance
      */
     static create<T extends ExRowShape>(shape: T): ExRow<T>;
@@ -3695,19 +3700,29 @@ export declare interface TailwindThemeVars {
 
 /**
  * Configuration for template download in the upload step.
- * When `source` is `"generate"`, a header-only template file is created
- * client-side from the schema column names.
+ * When `source` is `"generate"`, a template file is created client-side
+ * from the schema column names and optional example rows.
  */
 export declare interface TemplateDownloadConfig {
     source: 'generate';
     formats?: TemplateDownloadFormat[];
+    exampleRows?: TemplateDownloadExampleRow[];
 }
 
+/**
+ * A serializable example row used to populate generated templates.
+ */
+export declare type TemplateDownloadExampleRow = Record<string, unknown>;
+
 /**
  * Template download format
  */
 export declare type TemplateDownloadFormat = 'csv' | 'xlsx';
 
+export declare type TemplateDownloadOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> = Omit<TemplateDownloadConfig, 'exampleRows'> & {
+    exampleRows?: Infer<TSchema>[] | (() => Infer<TSchema>[]);
+};
+
 /**
  * A branded string type for locale entries that require interpolation via `{variable}` syntax.
  * Widget code cannot render a `TemplateString` directly in JSX — it must go through the `t()` function.
@@ -3754,7 +3769,7 @@ export declare interface UseExpressCSVOptions<TSchema extends ExType<unknown, Ex
     fonts?: Record<string, ECSVFontSource>;
     stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
     previewSchemaBeforeUpload?: boolean;
-    templateDownload?: TemplateDownloadConfig;
+    templateDownload?: TemplateDownloadOptions<TSchema>;
     saveSession?: boolean;
     locale?: DeepPartial<ExpressCSVLocaleInput>;
     disableStatusStep?: boolean;

package/dist/index.d.mts

@@ -3015,6 +3015,11 @@ declare class ExRow<T extends ExRowShape> extends ExType<{
      * Factory method to create an ExRow validator for a row of data
      *
      * @param shape - Object defining the structure of fields in the row
+     *
+     * Object literals preserve exact key inference. If callers build the shape
+     * through a widened variable or conditional assembly, TypeScript may widen
+     * the resulting row type as well.
+     *
      * @returns A new ExRow instance
      */
     static create<T extends ExRowShape>(shape: T): ExRow<T>;
@@ -3695,19 +3700,29 @@ export declare interface TailwindThemeVars {
 
 /**
  * Configuration for template download in the upload step.
- * When `source` is `"generate"`, a header-only template file is created
- * client-side from the schema column names.
+ * When `source` is `"generate"`, a template file is created client-side
+ * from the schema column names and optional example rows.
  */
 export declare interface TemplateDownloadConfig {
     source: 'generate';
     formats?: TemplateDownloadFormat[];
+    exampleRows?: TemplateDownloadExampleRow[];
 }
 
+/**
+ * A serializable example row used to populate generated templates.
+ */
+export declare type TemplateDownloadExampleRow = Record<string, unknown>;
+
 /**
  * Template download format
  */
 export declare type TemplateDownloadFormat = 'csv' | 'xlsx';
 
+export declare type TemplateDownloadOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> = Omit<TemplateDownloadConfig, 'exampleRows'> & {
+    exampleRows?: Infer<TSchema>[] | (() => Infer<TSchema>[]);
+};
+
 /**
  * A branded string type for locale entries that require interpolation via `{variable}` syntax.
  * Widget code cannot render a `TemplateString` directly in JSX — it must go through the `t()` function.
@@ -3754,7 +3769,7 @@ export declare interface UseExpressCSVOptions<TSchema extends ExType<unknown, Ex
     fonts?: Record<string, ECSVFontSource>;
     stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
     previewSchemaBeforeUpload?: boolean;
-    templateDownload?: TemplateDownloadConfig;
+    templateDownload?: TemplateDownloadOptions<TSchema>;
     saveSession?: boolean;
     locale?: DeepPartial<ExpressCSVLocaleInput>;
     disableStatusStep?: boolean;

package/dist/index.d.ts

@@ -3015,6 +3015,11 @@ declare class ExRow<T extends ExRowShape> extends ExType<{
      * Factory method to create an ExRow validator for a row of data
      *
      * @param shape - Object defining the structure of fields in the row
+     *
+     * Object literals preserve exact key inference. If callers build the shape
+     * through a widened variable or conditional assembly, TypeScript may widen
+     * the resulting row type as well.
+     *
      * @returns A new ExRow instance
      */
     static create<T extends ExRowShape>(shape: T): ExRow<T>;
@@ -3695,19 +3700,29 @@ export declare interface TailwindThemeVars {
 
 /**
  * Configuration for template download in the upload step.
- * When `source` is `"generate"`, a header-only template file is created
- * client-side from the schema column names.
+ * When `source` is `"generate"`, a template file is created client-side
+ * from the schema column names and optional example rows.
  */
 export declare interface TemplateDownloadConfig {
     source: 'generate';
     formats?: TemplateDownloadFormat[];
+    exampleRows?: TemplateDownloadExampleRow[];
 }
 
+/**
+ * A serializable example row used to populate generated templates.
+ */
+export declare type TemplateDownloadExampleRow = Record<string, unknown>;
+
 /**
  * Template download format
  */
 export declare type TemplateDownloadFormat = 'csv' | 'xlsx';
 
+export declare type TemplateDownloadOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> = Omit<TemplateDownloadConfig, 'exampleRows'> & {
+    exampleRows?: Infer<TSchema>[] | (() => Infer<TSchema>[]);
+};
+
 /**
  * A branded string type for locale entries that require interpolation via `{variable}` syntax.
  * Widget code cannot render a `TemplateString` directly in JSX — it must go through the `t()` function.
@@ -3754,7 +3769,7 @@ export declare interface UseExpressCSVOptions<TSchema extends ExType<unknown, Ex
     fonts?: Record<string, ECSVFontSource>;
     stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
     previewSchemaBeforeUpload?: boolean;
-    templateDownload?: TemplateDownloadConfig;
+    templateDownload?: TemplateDownloadOptions<TSchema>;
     saveSession?: boolean;
     locale?: DeepPartial<ExpressCSVLocaleInput>;
     disableStatusStep?: boolean;