@expresscsv/sdk 0.1.18 → 0.1.19

package/README.md

@@ -57,7 +57,7 @@ importer.open({
 });
 ```
 
-If your schema is assembled dynamically at runtime, use `x.dynamicRow(...)` instead of `x.row(...)`. It keeps the same runtime parsing behavior while intentionally widening TypeScript inference for runtime-built shapes.
+If your schema is assembled dynamically at runtime, still use `x.row(...)`. Just note that dynamic schema assembly can widen TypeScript inference, so use it intentionally when you need runtime-driven columns.
 
 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.
 
@@ -266,6 +266,40 @@ const importer = new CSVImporter({
 });
 ```
 
+## Template Downloads
+
+Generated templates can include example rows that match your schema.
+
+```typescript
+import { CSVImporter, x, type Infer } from "@expresscsv/sdk";
+
+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 importer = new CSVImporter({
+  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.
@@ -459,7 +493,7 @@ const schema = x.row({
 });
 ```
 
-`x.dynamicRow(...)` lets you build the row at runtime, which is useful when the schema depends on account data, user preferences, or enabled custom fields.
+`x.row(...)` also works for runtime-built schemas, which is useful when the shape depends on account data, user preferences, or enabled custom fields.
 
 ```typescript
 import { x } from "@expresscsv/sdk";
@@ -469,7 +503,7 @@ function buildCustomerSchema(options: {
   collectHealthScore: boolean;
   collectSegment: boolean;
 }) {
-  return x.dynamicRow({
+  return x.row({
     email: x.string().email().label("Email"),
     companyName: x.string().label("Company Name"),
     ...(options.collectCrmId ? { crmId: x.string().label("CRM ID") } : {}),
@@ -497,6 +531,8 @@ const schema = buildCustomerSchema({
 });
 ```
 
+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:
@@ -655,7 +691,7 @@ new CSVImporter(options: SDKOptions)
 | `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 |
 

package/dist/index.d.cts

@@ -1256,6 +1256,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private cachedSchemaJson;
     private initCompletePromise;
     private resolveInitComplete;
+    private resolvedTemplateDownload;
     constructor(options: SDKOptions<TSchema>);
     /**
      * Enhanced state management
@@ -3126,16 +3127,14 @@ 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>;
-    /**
-     * Factory method for runtime-built row shapes.
-     *
-     * This intentionally widens the returned type to ExRow<ExRowShape> so callers
-     * can assemble fields conditionally without relying on exact key inference.
-     */
-    static createDynamic(shape: ExRowShape): ExRow<ExRowShape>;
     /**
      * Specifies columns that can be null/optional with conditional logic
      *
@@ -3777,7 +3776,7 @@ export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, u
     fonts?: Record<string, ECSVFontSource>;
     stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
     previewSchemaBeforeUpload?: boolean;
-    templateDownload?: TemplateDownloadConfig;
+    templateDownload?: TemplateDownloadOptions<TSchema>;
     saveSession?: boolean;
     locale?: DeepPartial<ExpressCSVLocaleInput>;
     disableStatusStep?: boolean;
@@ -3834,18 +3833,28 @@ 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.
  */
-declare interface TemplateDownloadConfig {
+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
  */
-declare type TemplateDownloadFormat = 'csv' | 'xlsx';
+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.
@@ -3937,7 +3946,6 @@ export declare const x: {
     time: typeof ExTime.create;
     datetime: typeof ExDatetime.create;
     row: typeof ExRow.create;
-    dynamicRow: typeof ExRow.createDynamic;
     select: typeof ExSelect.create;
     multiselect: typeof ExMultiselect.create;
     infer: <T extends ExType<unknown, ExBaseDef, unknown>>(_schema: T) => Infer<T>;

package/dist/index.d.mts

@@ -1256,6 +1256,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private cachedSchemaJson;
     private initCompletePromise;
     private resolveInitComplete;
+    private resolvedTemplateDownload;
     constructor(options: SDKOptions<TSchema>);
     /**
      * Enhanced state management
@@ -3126,16 +3127,14 @@ 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>;
-    /**
-     * Factory method for runtime-built row shapes.
-     *
-     * This intentionally widens the returned type to ExRow<ExRowShape> so callers
-     * can assemble fields conditionally without relying on exact key inference.
-     */
-    static createDynamic(shape: ExRowShape): ExRow<ExRowShape>;
     /**
      * Specifies columns that can be null/optional with conditional logic
      *
@@ -3777,7 +3776,7 @@ export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, u
     fonts?: Record<string, ECSVFontSource>;
     stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
     previewSchemaBeforeUpload?: boolean;
-    templateDownload?: TemplateDownloadConfig;
+    templateDownload?: TemplateDownloadOptions<TSchema>;
     saveSession?: boolean;
     locale?: DeepPartial<ExpressCSVLocaleInput>;
     disableStatusStep?: boolean;
@@ -3834,18 +3833,28 @@ 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.
  */
-declare interface TemplateDownloadConfig {
+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
  */
-declare type TemplateDownloadFormat = 'csv' | 'xlsx';
+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.
@@ -3937,7 +3946,6 @@ export declare const x: {
     time: typeof ExTime.create;
     datetime: typeof ExDatetime.create;
     row: typeof ExRow.create;
-    dynamicRow: typeof ExRow.createDynamic;
     select: typeof ExSelect.create;
     multiselect: typeof ExMultiselect.create;
     infer: <T extends ExType<unknown, ExBaseDef, unknown>>(_schema: T) => Infer<T>;

package/dist/index.d.ts

@@ -1256,6 +1256,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private cachedSchemaJson;
     private initCompletePromise;
     private resolveInitComplete;
+    private resolvedTemplateDownload;
     constructor(options: SDKOptions<TSchema>);
     /**
      * Enhanced state management
@@ -3126,16 +3127,14 @@ 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>;
-    /**
-     * Factory method for runtime-built row shapes.
-     *
-     * This intentionally widens the returned type to ExRow<ExRowShape> so callers
-     * can assemble fields conditionally without relying on exact key inference.
-     */
-    static createDynamic(shape: ExRowShape): ExRow<ExRowShape>;
     /**
      * Specifies columns that can be null/optional with conditional logic
      *
@@ -3777,7 +3776,7 @@ export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, u
     fonts?: Record<string, ECSVFontSource>;
     stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
     previewSchemaBeforeUpload?: boolean;
-    templateDownload?: TemplateDownloadConfig;
+    templateDownload?: TemplateDownloadOptions<TSchema>;
     saveSession?: boolean;
     locale?: DeepPartial<ExpressCSVLocaleInput>;
     disableStatusStep?: boolean;
@@ -3834,18 +3833,28 @@ 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.
  */
-declare interface TemplateDownloadConfig {
+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
  */
-declare type TemplateDownloadFormat = 'csv' | 'xlsx';
+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.
@@ -3937,7 +3946,6 @@ export declare const x: {
     time: typeof ExTime.create;
     datetime: typeof ExDatetime.create;
     row: typeof ExRow.create;
-    dynamicRow: typeof ExRow.createDynamic;
     select: typeof ExSelect.create;
     multiselect: typeof ExMultiselect.create;
     infer: <T extends ExType<unknown, ExBaseDef, unknown>>(_schema: T) => Infer<T>;