@expresscsv/react 0.1.1 → 0.1.3

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

@@ -0,0 +1,27 @@
+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

@@ -0,0 +1,4 @@
+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';

package/dist/index.d.mts

@@ -1,31 +1,426 @@
-import { TemplateDownloadConfig, DeepPartial, ExpressCSVLocaleInput } from '@expresscsv/core';
-export { DeepPartial, ExpressCSVLocaleInput, TemplateDownloadConfig, TemplateDownloadFormat } from '@expresscsv/core';
-import { ExType, ExBaseDef, ECSVTheme, ColorModeConfig, ECSVFontSource, OpenOptions, Infer, WidgetState } from '@expresscsv/sdk';
-export { ColorModeConfig, ColorModePref, DeliveryOptions, ECSVFontSource, ECSVTheme, ExpressCSVStep, ImportCancelledError, Infer, OpenOptions, RecordsChunk, TailwindThemeVars, WebhookConfig, WidgetMode, WidgetState, x } from '@expresscsv/sdk';
-
-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>;
-}
-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;
-};
-
-export { type UseExpressCSVOptions, useExpressCSV };
+import { ColorModeConfig } from '@expresscsv/theme';
+import { ColorModePref } from '@expresscsv/theme';
+import { ECSVFontSource } from '@expresscsv/theme';
+import { ECSVTheme } from '@expresscsv/theme';
+import { ExBaseDef } from '@expresscsv/fields';
+import { ExType } from '@expresscsv/fields';
+import { Infer } from '@expresscsv/fields';
+import { TailwindThemeVars } from '@expresscsv/theme';
+import { WidgetMode } from '@expresscsv/iframe-comm';
+import { WidgetState } from '@expresscsv/iframe-comm';
+import { x } from '@expresscsv/fields';
+
+export { ColorModeConfig }
+
+export { ColorModePref }
+
+export declare type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/**
+ * Delivery options - requires at least one of onData or webhook
+ */
+export declare type DeliveryOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, 'onData' | 'webhook'>;
+
+/**
+ * Base delivery options - at least one must be provided
+ */
+declare interface DeliveryOptionsBase<T> {
+    /** Local callback for processing chunks */
+    onData?: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
+    /** Webhook configuration for remote delivery */
+    webhook?: WebhookConfig;
+}
+
+export { ECSVFontSource }
+
+export { ECSVTheme }
+
+declare interface ExpressCSVLocale {
+    general: {
+        cancel: string;
+        back: string;
+        next: string;
+        finish: string;
+        required: string;
+        optional: string;
+        matched: string;
+        unmatched: string;
+        custom: string;
+    };
+    widget: {
+        title: string;
+        loading: string;
+        closeConfirmTitle: string;
+        closeConfirmDescription: string;
+        closeConfirmCancel: string;
+        closeConfirmContinue: string;
+        errorTitle: string;
+        startOver: string;
+    };
+    sessionRecovery: {
+        message: string;
+        discard: string;
+        resume: string;
+    };
+    dropzone: {
+        ariaLabel: string;
+        clearAriaLabel: string;
+        clearTooltip: string;
+        clearConfirmTitle: string;
+        clearConfirmDescription: string;
+        processing: string;
+        restoredSession: string;
+        prompt: string;
+        or: string;
+        browse: string;
+    };
+    upload: {
+        expectedColumns: string;
+        templatePrompt: string;
+        templateCSV: string;
+        templateXLSX: string;
+        templateGenerating: string;
+        /** Available: {format} */
+        templateDownloadFormat: TemplateString<'format'>;
+        templateDownload: string;
+    };
+    selectSheet: {
+        title: string;
+        subtitle: string;
+        noWorksheets: string;
+        preview: string;
+        /** Available: {count} */
+        columnCount: TemplateString<'count'>;
+        /** Available: {count} */
+        rowCount: TemplateString<'count'>;
+        /** Available: {name} */
+        inSheet: TemplateString<'name'>;
+        sheetSelected: string;
+        noColumns: string;
+        needsMoreRows: string;
+    };
+    selectHeader: {
+        loading: string;
+        noData: string;
+        noDataDescription: string;
+        title: string;
+        subtitle: string;
+        validHeader: string;
+        /** Available: {count} */
+        emptyColumns: TemplateString<'count'>;
+        allColumnsEmpty: string;
+        emptyColumnsTooltip: string;
+        /** Available: {displayed}, {total} */
+        showingRows: TemplateString<'displayed' | 'total'>;
+        showAll: string;
+        moveUp: string;
+        moveDown: string;
+    };
+    matchColumns: {
+        loading: string;
+        autoMatching: string;
+        title: string;
+        subtitle: string;
+        csvColumnHeader: string;
+        matchFieldHeader: string;
+        selectFieldPlaceholder: string;
+        searchFieldsPlaceholder: string;
+        noFieldsFound: string;
+        unmatchAll: string;
+        unmatchAllConfirmTitle: string;
+        unmatchAllConfirmDescription: string;
+        allRequiredMatched: string;
+        /** Available: {count} */
+        matchingConflicts: TemplateString<'count'>;
+        validationIssuesFound: string;
+        goToNextConflict: string;
+        /** Available: {count} */
+        unmatchedRequiredFields: TemplateString<'count'>;
+        requiredFieldsNotMatched: string;
+        goToUnmatchedFields: string;
+        /** Available: {count} */
+        validationIssues: TemplateString<'count'>;
+        goToNextIssue: string;
+        addEmptyColumnsForRequired: string;
+        /** Available: {fieldName} */
+        createEmptyColumn: TemplateString<'fieldName'>;
+        requiredFieldsNotAssigned: string;
+        addEmptyColumnTooltip: string;
+        previewTooltip: string;
+        /** Available: {rowCount}, {columnName} */
+        previewShowing: TemplateString<'rowCount' | 'columnName'>;
+    };
+    matchOptions: {
+        loading: string;
+        title: string;
+        subtitle: string;
+        csvValueHeader: string;
+        matchOptionHeader: string;
+        selectOptionPlaceholder: string;
+        searchOptionsPlaceholder: string;
+        noOptionsFound: string;
+        optionalBadge: string;
+        customValuesHint: string;
+        /** Available: {count}, {remaining} */
+        showMore: TemplateString<'count' | 'remaining'>;
+        /** Available: {value} */
+        useCustomValue: TemplateString<'value'>;
+        allValuesMatched: string;
+        /** Available: {count} */
+        unmatchedValues: TemplateString<'count'>;
+        unmatchedValuesFound: string;
+        goToNextUnmatched: string;
+        /** Available: {count} */
+        valueCount: TemplateString<'count'>;
+    };
+    review: {
+        completing: string;
+        loading: string;
+        title: string;
+        subtitle: string;
+        validating: string;
+        noRecords: string;
+        validatingCells: string;
+        /** Available: {count} */
+        allRecordsValid: TemplateString<'count'>;
+        /** Available: {count} */
+        recordCount: TemplateString<'count'>;
+        filterAll: string;
+        filterValid: string;
+        filterInvalid: string;
+        clearFilters: string;
+        noInvalidRows: string;
+        applyAutofix: string;
+        invalidValue: string;
+        undo: string;
+        redo: string;
+        /** Available: {count} */
+        autofixCount: TemplateString<'count'>;
+        /** Available: {count} */
+        applyAllAutofixes: TemplateString<'count'>;
+        /** Available: {description}, {count} */
+        autofixItem: TemplateString<'description' | 'count'>;
+        filter: string;
+        actions: string;
+        addRecord: string;
+        /** Available: {count} */
+        deleteSelectedRecords: TemplateString<'count'>;
+        /** Available: {count} */
+        exportSelectedRecords: TemplateString<'count'>;
+        /** Available: {count} */
+        exportFilteredRecords: TemplateString<'count'>;
+        /** Available: {count} */
+        exportAllRecords: TemplateString<'count'>;
+        exportCSV: string;
+        exportXLSX: string;
+        sortAZ: string;
+        sortZA: string;
+        sortLowHigh: string;
+        sortHighLow: string;
+        sortOldestNewest: string;
+        sortNewestOldest: string;
+        sortEarlyLate: string;
+        sortLateEarly: string;
+        sortFalseTrue: string;
+        sortTrueFalse: string;
+        sortAscending: string;
+        sortDescending: string;
+        removeSort: string;
+        unpinColumn: string;
+        pinColumn: string;
+        clearColumn: string;
+        /** Available: {description} */
+        columnAutofix: TemplateString<'description'>;
+        applyAllColumnAutofixes: string;
+        removeFilter: string;
+        columnMenu: string;
+        emptyDataTitle: string;
+        emptyDataDescription: string;
+        editFilter: string;
+        filteredColumns: string;
+        unfilteredColumns: string;
+        columnsLabel: string;
+        transformTooltip: string;
+        transformTitle: string;
+        transformClose: string;
+        transformCloseDiscardTooltip: string;
+        transformCloseTooltip: string;
+        transformError: string;
+        transformPlaceholder: string;
+        transformGenerating: string;
+        transformApplying: string;
+        transformDiscard: string;
+        transformApply: string;
+        transformUnappliedTitle: string;
+        transformUnappliedDescription: string;
+        transformKeepEditing: string;
+        transformDiscardClose: string;
+        transformAbortTitle: string;
+        transformAbortDescription: string;
+        transformAbortClose: string;
+        transformSubmit: string;
+    };
+    phantomColumn: {
+        /** Available: {number} */
+        defaultName: TemplateString<'number'>;
+        remove: string;
+        removeTooltip: string;
+    };
+    validation: {
+        showOtherMatch: string;
+    };
+    steps: {
+        upload: string;
+        selectSheet: string;
+        selectHeader: string;
+        matchColumns: string;
+        matchOptions: string;
+        review: string;
+        /** Available: {currentStep}, {totalSteps} */
+        progress: TemplateString<'currentStep' | 'totalSteps'>;
+    };
+}
+
+/** User-facing locale type where every leaf is a plain `string`. */
+export declare type ExpressCSVLocaleInput = StripBrand<ExpressCSVLocale>;
+
+/**
+ * Core step identifiers for the CSV import wizard
+ */
+export declare type ExpressCSVStep = 'upload' | 'select-sheet' | 'select-header' | 'match-columns' | 'match-options' | 'review';
+
+/**
+ * Error thrown when the user cancels the import operation
+ */
+export declare class ImportCancelledError extends Error {
+    constructor(message?: string);
+}
+
+export { Infer }
+
+/**
+ * Options for the open() method
+ * Requires at least one of onData or webhook for delivery
+ */
+export declare type OpenOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, 'onData' | 'webhook'> & {
+    /** Number of records per chunk (default: 1000) */
+    chunkSize?: number;
+    /** Called when all chunks have been processed */
+    onComplete?: () => void;
+    /** Called when the user cancels the import */
+    onCancel?: () => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+    /** Called when the widget opens */
+    onWidgetOpen?: () => void;
+    /** Called when the step changes in the wizard */
+    onStepChange?: (stepId: ExpressCSVStep, previousStepId?: ExpressCSVStep) => void;
+    /** Called when the widget closes */
+    onWidgetClose?: (reason: 'user_close' | 'cancel' | 'complete' | 'error') => void;
+};
+
+/**
+ * A chunk of records passed to the onData callback
+ */
+export declare interface RecordsChunk<T> {
+    /** The records in this chunk */
+    records: T[];
+    /** Total number of chunks */
+    totalChunks: number;
+    /** Current chunk index (0-based) */
+    currentChunkIndex: number;
+    /** Total number of records across all chunks */
+    totalRecords: number;
+}
+
+/**
+ * Type helper that requires at least one of the specified keys to be present
+ */
+declare type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> & {
+    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
+}[Keys];
+
+declare type StripBrand<T> = {
+    [K in keyof T]: T[K] extends TemplateString<string> ? string : T[K] extends object ? StripBrand<T[K]> : T[K];
+};
+
+export { 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.
+ */
+export declare interface TemplateDownloadConfig {
+    source: 'generate';
+    formats?: TemplateDownloadFormat[];
+}
+
+/**
+ * Template download format
+ */
+export declare type TemplateDownloadFormat = 'csv' | 'xlsx';
+
+/**
+ * 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.
+ * The generic `TVars` encodes the expected variable names so `t()` enforces the correct vars argument.
+ */
+declare type TemplateString<TVars extends string = string> = string & {
+    readonly __brand: 'TemplateString';
+    readonly __vars: TVars;
+};
+
+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;
+};
+
+export declare 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>;
+}
+
+/**
+ * Webhook configuration for remote delivery of results
+ */
+export declare interface WebhookConfig {
+    /** The URL to send webhook requests to */
+    url: string;
+    /** Optional HTTP headers to include in the request */
+    headers?: Record<string, string>;
+    /** HTTP method to use (default: 'POST') */
+    method?: 'POST' | 'PUT' | 'PATCH';
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Number of retry attempts on failure (default: 0) */
+    retries?: number;
+    /** Arbitrary developer-provided metadata */
+    metadata?: Record<string, unknown>;
+}
+
+export { WidgetMode }
+
+export { WidgetState }
+
+export { x }
+
+export { }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expresscsv/react",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "React component wrapper for ExpressCSV SDK",
   "module": "dist/index.mjs",
   "types": "dist/index.d.mts",