@vuu-ui/vuu-table-extras 3.5.9 → 3.5.11

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.5.9",
+  "version": "3.5.11",
   "author": "heswell",
   "main": "./src/index.js",
   "license": "Apache-2.0",
@@ -11,19 +11,19 @@
     "lezer-generate:column": "lezer-generator --output ./src/column-expression-input/column-language-parser/generated/column-parser.js ./src/column-expression-input/column-language-parser/grammar/column.grammar"
   },
   "devDependencies": {
-    "@vuu-ui/vuu-filter-types": "3.5.9",
-    "@vuu-ui/vuu-protocol-types": "3.5.9"
+    "@vuu-ui/vuu-filter-types": "3.5.11",
+    "@vuu-ui/vuu-protocol-types": "3.5.11"
   },
   "dependencies": {
-    "@vuu-ui/vuu-codemirror": "3.5.9",
-    "@vuu-ui/vuu-data-editing": "3.5.9",
-    "@vuu-ui/vuu-data-react": "3.5.9",
-    "@vuu-ui/vuu-data-types": "3.5.9",
-    "@vuu-ui/vuu-table-types": "3.5.9",
-    "@vuu-ui/vuu-popups": "3.5.9",
-    "@vuu-ui/vuu-table": "3.5.9",
-    "@vuu-ui/vuu-utils": "3.5.9",
-    "@vuu-ui/vuu-ui-controls": "3.5.9",
+    "@vuu-ui/vuu-codemirror": "3.5.11",
+    "@vuu-ui/vuu-data-editing": "3.5.11",
+    "@vuu-ui/vuu-data-react": "3.5.11",
+    "@vuu-ui/vuu-data-types": "3.5.11",
+    "@vuu-ui/vuu-table-types": "3.5.11",
+    "@vuu-ui/vuu-popups": "3.5.11",
+    "@vuu-ui/vuu-table": "3.5.11",
+    "@vuu-ui/vuu-utils": "3.5.11",
+    "@vuu-ui/vuu-ui-controls": "3.5.11",
     "@lezer/lr": "1.4.2",
     "@salt-ds/core": "1.54.1",
     "@salt-ds/lab": "1.0.0-alpha.83",

package/src/csv-export/export-utils.js

@@ -8,6 +8,23 @@ const MAX_EXPORT_ROWS = 10000;
 const CHUNK_SIZE = 1000;
 const DEFAULT_EXPORT_TIMEOUT = 30000;
 const DEFAULT_TEMPLATE_TIMEOUT = 10000;
+const resolveHeaderLabel = (colName, headerMapping, fallbackLabel)=>{
+    if (headerMapping) if ("function" == typeof headerMapping) {
+        const mapped = headerMapping(colName);
+        if (mapped) return mapped;
+    } else {
+        if (headerMapping[colName]) return headerMapping[colName];
+        const reverseKey = Object.keys(headerMapping).find((key)=>headerMapping[key] === colName);
+        if (reverseKey) return reverseKey;
+    }
+    return fallbackLabel ?? colName;
+};
+const resolveSchemaColumn = (colName, headerMapping)=>{
+    if (headerMapping && "function" != typeof headerMapping) {
+        if (headerMapping[colName]) return headerMapping[colName];
+    }
+    return colName;
+};
 const csvCell = (value)=>{
     const s = null == value ? "" : String(value);
     return s.includes(",") || s.includes('"') || s.includes("\n") || s.includes("\r") ? `"${s.replace(/"/g, '""')}"` : s;
@@ -49,11 +66,16 @@ const isExportableColumn = (descriptor)=>{
     return true;
 };
 const exportCsvTemplate = async (dataSource, options = {})=>{
-    const { filename = "template.csv", excludeColumns = [], columns, overrides, timeout = DEFAULT_TEMPLATE_TIMEOUT, onError, onSuccess } = options;
+    const { filename = "template.csv", excludeColumns = [], columns, headerMapping, overrides, timeout = DEFAULT_TEMPLATE_TIMEOUT, onError, onSuccess } = options;
+    const labelMap = new Map();
+    if (columns) {
+        for (const col of columns)if ("string" != typeof col && col.label) labelMap.set(col.name, col.label);
+    }
     const targetColumnNames = columns ? columns.filter((col)=>"string" == typeof col ? true : isExportableColumn(col) && "client" !== col.source).map((col)=>"string" == typeof col ? col : col.name) : void 0;
     const targetColumns = targetColumnNames ?? overrides?.columns;
-    const sessionOverrides = overrides ?? (targetColumns ? {
-        columns: targetColumns
+    const serverTargetColumns = targetColumns?.map((col)=>resolveSchemaColumn(col, headerMapping));
+    const sessionOverrides = overrides ?? (serverTargetColumns ? {
+        columns: serverTargetColumns
     } : void 0);
     if (!isSessionTable(dataSource.table) && dataSource.createSessionDataSource && "initialising" !== dataSource.status && "unsubscribed" !== dataSource.status) try {
         const sessionDataSource = await dataSource.createSessionDataSource("Empty", "export", sessionOverrides);
@@ -91,7 +113,7 @@ const exportCsvTemplate = async (dataSource, options = {})=>{
                         } else reject(error);
                         return;
                     }
-                    const header = exportCols.map(csvCell).join(",");
+                    const header = exportCols.map((colName)=>resolveHeaderLabel(colName, headerMapping, labelMap.get(colName))).map(csvCell).join(",");
                     triggerCsvDownload(`${header}\r\n`, filename);
                     cleanup();
                     onSuccess?.();
@@ -124,12 +146,12 @@ const exportCsvTemplate = async (dataSource, options = {})=>{
         if (onError) return void onError(error);
         throw error;
     }
-    const header = exportCols.map(csvCell).join(",");
+    const header = exportCols.map((colName)=>resolveHeaderLabel(colName, headerMapping, labelMap.get(colName))).map(csvCell).join(",");
     triggerCsvDownload(`${header}\r\n`, filename);
     onSuccess?.();
 };
 const exportSessionTableToCsv = async (dataSource, options = {})=>{
-    const { filename = "export.csv", copyOption = "All", excludeColumns = [], maxRows = MAX_EXPORT_ROWS, columnDescriptors: rawColumnDescriptors, columns: rawColumns, overrides, timeout = DEFAULT_EXPORT_TIMEOUT, onError, onSuccess } = options;
+    const { filename = "export.csv", copyOption = "All", excludeColumns = [], maxRows = MAX_EXPORT_ROWS, columnDescriptors: rawColumnDescriptors, columns: rawColumns, headerMapping, overrides, timeout = DEFAULT_EXPORT_TIMEOUT, onError, onSuccess } = options;
     const rawInputColumns = rawColumns ?? rawColumnDescriptors;
     const columnDescriptors = rawInputColumns?.map((col)=>"string" == typeof col ? {
             name: col
@@ -215,7 +237,7 @@ const exportSessionTableToCsv = async (dataSource, options = {})=>{
                     totalSize = message.size ?? 0;
                     if (0 === totalSize) {
                         cleanup();
-                        const header = exportCols.map((name)=>csvCell(descriptorMap[name]?.label ?? name)).join(",");
+                        const header = exportCols.map((name)=>csvCell(resolveHeaderLabel(name, headerMapping, descriptorMap[name]?.label))).join(",");
                         triggerCsvDownload(`${header}\r\n`, filename);
                         onSuccess?.();
                         resolve();
@@ -233,7 +255,7 @@ const exportSessionTableToCsv = async (dataSource, options = {})=>{
                     if (collectedRows.size >= totalSize) {
                         cleanup();
                         const lines = [
-                            exportCols.map((name)=>csvCell(descriptorMap[name]?.label ?? name)).join(",")
+                            exportCols.map((name)=>csvCell(resolveHeaderLabel(name, headerMapping, descriptorMap[name]?.label))).join(",")
                         ];
                         for(let i = 0; i < totalSize; i++){
                             const row = collectedRows.get(i);
@@ -274,4 +296,4 @@ const exportSessionTableToCsv = async (dataSource, options = {})=>{
     });
 };
 const exportToCsv = async (dataSource, options)=>exportSessionTableToCsv(dataSource, options);
-export { exportCsvTemplate, exportSessionTableToCsv, exportToCsv, isExportableColumn };
+export { exportCsvTemplate, exportSessionTableToCsv, exportToCsv, isExportableColumn, resolveHeaderLabel, resolveSchemaColumn };

package/src/csv-export/index.js

@@ -1,2 +1,2 @@
-export { exportCsvTemplate, exportSessionTableToCsv, exportToCsv, isExportableColumn } from "./export-utils.js";
+export { exportCsvTemplate, exportSessionTableToCsv, exportToCsv, isExportableColumn, resolveHeaderLabel, resolveSchemaColumn } from "./export-utils.js";
 export { useCsvExport } from "./useCsvExport.js";

package/src/csv-export/useCsvExport.js

@@ -6,7 +6,7 @@ function useCsvExport(propsOrDataSource) {
     const config = propsOrDataSource && "table" in propsOrDataSource ? {
         dataSource: propsOrDataSource
     } : propsOrDataSource ?? {};
-    const { dataSource: defaultDataSource, tableConfig, columns: defaultColumns, onError, onSuccess } = config;
+    const { dataSource: defaultDataSource, tableConfig, columns: defaultColumns, headerMapping: defaultHeaderMapping, onError, onSuccess } = config;
     const exportCsv = useCallback(async (options, overrideDataSource)=>{
         const activeDataSource = overrideDataSource ?? defaultDataSource;
         if (!activeDataSource) {
@@ -20,8 +20,12 @@ function useCsvExport(propsOrDataSource) {
         setError(null);
         try {
             const columnsToExport = options?.columns ?? options?.columnDescriptors ?? defaultColumns ?? tableConfig?.columns;
+            const effectiveHeaderMapping = options?.headerMapping ?? defaultHeaderMapping;
             await exportToCsv(activeDataSource, {
                 columns: columnsToExport,
+                ...void 0 !== effectiveHeaderMapping ? {
+                    headerMapping: effectiveHeaderMapping
+                } : {},
                 ...options,
                 onError: (err)=>{
                     setError(err);
@@ -45,6 +49,7 @@ function useCsvExport(propsOrDataSource) {
     }, [
         defaultDataSource,
         defaultColumns,
+        defaultHeaderMapping,
         tableConfig,
         onError,
         onSuccess
@@ -62,8 +67,12 @@ function useCsvExport(propsOrDataSource) {
         setError(null);
         try {
             const templateColumns = options?.columns ?? defaultColumns ?? tableConfig?.columns;
+            const effectiveHeaderMapping = options?.headerMapping ?? defaultHeaderMapping;
             await exportCsvTemplate(activeDataSource, {
                 columns: templateColumns,
+                ...void 0 !== effectiveHeaderMapping ? {
+                    headerMapping: effectiveHeaderMapping
+                } : {},
                 ...options,
                 onError: (err)=>{
                     setError(err);
@@ -87,6 +96,7 @@ function useCsvExport(propsOrDataSource) {
     }, [
         defaultDataSource,
         defaultColumns,
+        defaultHeaderMapping,
         tableConfig,
         onError,
         onSuccess

package/src/csv-upload/index.js

@@ -5,3 +5,4 @@ export { validateCsvAgainstSchema } from "./parse/csv-schema-validation.js";
 export { parseCsv } from "./parse/csv-parse.js";
 export { CsvParseErrorEnum, CsvValidationErrorEnum } from "./parse/csv-errors.js";
 export { CSV_FIRST_DATA_ROW_NUMBER, CSV_HEADER_ROW_NUMBER } from "./parse/csv-constants.js";
+export { mapCsvHeaders } from "./parse/csv-upload-utils.js";

package/src/csv-upload/parse/csv-parse.js

@@ -55,7 +55,16 @@ const parseCsv = (csvText, options)=>{
         addCsvFileError(errorState, "*", CsvParseErrorEnum.EMPTY_FILE, "CSV file is empty.");
         return withError("CSV file is empty.", errorState.errorMap, errorState.errors);
     }
-    const header = records[0].map((value)=>value.trim());
+    let header;
+    let rows;
+    if (options?.customHeaders && options.customHeaders.length > 0) {
+        header = options.customHeaders.map((value)=>value.trim());
+        const hasHeaderRow = options.hasHeaderRow ?? true;
+        rows = hasHeaderRow ? records.slice(1) : records;
+    } else {
+        header = records[0].map((value)=>value.trim());
+        rows = records.slice(1);
+    }
     if (0 === header.length) addCsvFileError(errorState, "*", CsvParseErrorEnum.EMPTY_HEADER_COLUMN, "CSV header contains empty column names.");
     header.forEach((col, columnIndex)=>{
         if (0 === col.length) addCsvFileError(errorState, `column_${columnIndex + 1}`, CsvParseErrorEnum.EMPTY_HEADER_COLUMN, "CSV header contains empty column names.");
@@ -66,9 +75,9 @@ const parseCsv = (csvText, options)=>{
         addCsvFileError(errorState, duplicateHeader, CsvParseErrorEnum.DUPLICATE_HEADER_COLUMN, `CSV header contains duplicate column '${duplicateHeader}'.`, duplicateHeader);
         return withError(`CSV header contains duplicate column '${duplicateHeader}'.`, errorState.errorMap, errorState.errors, header, []);
     }
-    const rows = records.slice(1);
+    const firstDataRowNumber = options?.customHeaders && false === options.hasHeaderRow ? 1 : CSV_FIRST_DATA_ROW_NUMBER;
     rows.forEach((row, rowIndex)=>{
-        if (row.length !== header.length) addCsvRowError(errorState, rowIndex + CSV_FIRST_DATA_ROW_NUMBER, "*", CsvParseErrorEnum.ROW_COLUMN_COUNT_MISMATCH, "This row has too many or too few columns compared to the header line. Check for extra or missing commas.", row.join(","));
+        if (row.length !== header.length) addCsvRowError(errorState, rowIndex + firstDataRowNumber, "*", CsvParseErrorEnum.ROW_COLUMN_COUNT_MISMATCH, "This row has too many or too few columns compared to the header line. Check for extra or missing commas.", row.join(","));
     });
     if (hasCsvErrors(errorState.errorMap)) return withError("CSV rows must have the same number of columns as the header.", errorState.errorMap, errorState.errors, header, rows);
     return {

package/src/csv-upload/parse/csv-upload-utils.js

@@ -1,5 +1,11 @@
 import { isRpcError, metadataKeys } from "@vuu-ui/vuu-utils";
 import { CSV_FIRST_DATA_ROW_NUMBER } from "./csv-constants.js";
+const mapCsvHeaders = (headers, headerMapping)=>{
+    if (!headerMapping) return [
+        ...headers
+    ];
+    return headers.map((col)=>"function" == typeof headerMapping ? headerMapping(col) : headerMapping[col] ?? col);
+};
 const isRecord = (value)=>"object" == typeof value && null !== value;
 const toErrorMessage = (error)=>error instanceof Error ? error.message : String(error);
 const isCsvParseError = (value)=>isRecord(value) && "message" in value && "string" == typeof value.message && "errors" in value && Array.isArray(value.errors) && "errorMap" in value && isRecord(value.errorMap);
@@ -101,4 +107,4 @@ const waitForSessionErrors = (isRemote, sessionErrors, receivedRowKeys, expected
         }, timeoutMs);
     });
 };
-export { buildRowErrorMessage, createUploadError, executeBatchRpcCalls, getInlineRowErrorMessage, getRowVuuMsgError, hasFileParseErrors, isCsvParseError, mergeValidationWithParseErrors, normalizeTableData, toErrorMessage, toValidationErrorsFromParseRowErrors, waitForSessionErrors };
+export { buildRowErrorMessage, createUploadError, executeBatchRpcCalls, getInlineRowErrorMessage, getRowVuuMsgError, hasFileParseErrors, isCsvParseError, mapCsvHeaders, mergeValidationWithParseErrors, normalizeTableData, toErrorMessage, toValidationErrorsFromParseRowErrors, waitForSessionErrors };

package/src/csv-upload/useCsvUpload.js

@@ -2,10 +2,10 @@ import { Range, isSessionTable } from "@vuu-ui/vuu-utils";
 import { useCallback, useMemo, useRef, useState } from "react";
 import { parseCsv } from "./parse/csv-parse.js";
 import { CsvValidationErrorEnum, validateCsvAgainstSchema } from "./parse/csv-schema-validation.js";
-import { createUploadError, hasFileParseErrors, isCsvParseError, mergeValidationWithParseErrors, toErrorMessage } from "./parse/csv-upload-utils.js";
+import { createUploadError, hasFileParseErrors, isCsvParseError, mapCsvHeaders, mergeValidationWithParseErrors, toErrorMessage } from "./parse/csv-upload-utils.js";
 import { useImportSchema } from "./session/useImportSchema.js";
 import { useImportSession } from "./session/useImportSession.js";
-const useCsvUpload = ({ dataSource, importMode = "direct", importSchema, importTable, onImportSessionEnded, onImportSessionReady, onError, onImported, onPreview, onProcessingStarted, maxRows, parseOptions, rowDefaults, validators })=>{
+const useCsvUpload = ({ dataSource, importMode = "direct", importSchema, importTable, onImportSessionEnded, onImportSessionReady, onError, onImported, onPreview, onProcessingStarted, maxRows, parseOptions, customHeaders, hasHeaderRow, headerMapping, rowDefaults, validators })=>{
     const [validation, setValidation] = useState();
     const [isProcessingFile, setIsProcessingFile] = useState(false);
     const [isImporting, setIsImporting] = useState(false);
@@ -58,9 +58,18 @@ const useCsvUpload = ({ dataSource, importMode = "direct", importSchema, importT
         }
         if (void 0 === schema) throw Error("Table schema is not yet available.");
         if (void 0 === table) throw Error("CsvUpload requires dataSource.table to be defined.");
+        const effectiveParseOptions = {
+            ...parseOptions,
+            ...void 0 !== customHeaders ? {
+                customHeaders
+            } : {},
+            ...void 0 !== hasHeaderRow ? {
+                hasHeaderRow
+            } : {}
+        };
         const fileContents = await file.text();
         if (operationId !== operationIdRef.current) return;
-        const parsedCsv = parseCsv(fileContents, parseOptions);
+        let parsedCsv = parseCsv(fileContents, effectiveParseOptions);
         if (parsedCsv.error && hasFileParseErrors(parsedCsv.error)) {
             setValidation(void 0);
             handleError({
@@ -70,6 +79,10 @@ const useCsvUpload = ({ dataSource, importMode = "direct", importSchema, importT
             });
             return;
         }
+        if (headerMapping) parsedCsv = {
+            ...parsedCsv,
+            header: mapCsvHeaders(parsedCsv.header, headerMapping)
+        };
         const schemaValidation = validateCsvAgainstSchema(parsedCsv, schema, {
             maxRows,
             validators

package/types/csv-export/export-utils.d.ts

@@ -1,44 +1,89 @@
 import type { CopyOption, DataSource, SessionDataSourceOverrides } from "@vuu-ui/vuu-data-types";
 import type { ColumnDescriptor, RowAccessor } from "@vuu-ui/vuu-table-types";
-export type { RowAccessor };
+import type { CsvHeaderMapping } from "../csv-upload/parse/csv-upload-utils";
+export type { RowAccessor, CsvHeaderMapping };
 export type ExportServerColumnDescriptor = Omit<ColumnDescriptor, "source" | "exportFormatter"> & {
+    /** Unique identifier of the column. */
     name: string;
+    /** Marks the column as backed by the server. */
     source?: "server";
+    /** Display label for the CSV header row. If omitted, `name` is used. */
     label?: string;
+    /** Whether to include this column in the CSV export. Defaults to true. */
     exportable?: boolean;
+    /** Custom formatter function for transforming cell values during export. */
     exportFormatter?: (value: unknown, row: RowAccessor) => string;
 };
 export type ExportClientColumnDescriptor = Omit<ColumnDescriptor, "source" | "exportFormatter"> & {
+    /** Unique identifier of the column. */
     name: string;
+    /** Marks the column as client-side calculated. */
     source: "client";
+    /** Display label for the CSV header row. If omitted, `name` is used. */
     label?: string;
+    /** Whether to include this column in the CSV export. Defaults to true. */
     exportable?: boolean;
+    /** Required formatter function for deriving client column values from row data. */
     exportFormatter: (value: unknown, row: RowAccessor) => string;
 };
 export type ExportColumnDescriptor = ExportServerColumnDescriptor | ExportClientColumnDescriptor;
 export interface ExportToCsvOptions {
+    /** Downloaded filename. Defaults to `"export.csv"`. */
     filename?: string;
+    /** Row copy mode: `"All"` exports every row, `"Selected"` exports only selected rows. Defaults to `"All"`. */
     copyOption?: CopyOption;
+    /** Specific column names to exclude from export in addition to internal session columns (`vuuMsg`, `vuuAction`, `vuuRowNum`). */
     excludeColumns?: string[];
+    /** Maximum number of data rows allowed to export. Throws if the server reports more rows. Defaults to `10_000`. */
     maxRows?: number;
+    /** Explicit column definitions or overrides. Alias for `columns`. */
     columnDescriptors?: readonly (ExportColumnDescriptor | ColumnDescriptor)[];
+    /** Specific subset, order, or descriptors of columns to include in the export. */
     columns?: readonly (string | ExportColumnDescriptor | ColumnDescriptor)[];
+    /**
+     * Optional mapping from schema column name to exported header name,
+     * or a resolver function `(col: string) => string`.
+     */
+    headerMapping?: CsvHeaderMapping;
+    /** Session datasource overrides passed to `createSessionDataSource`. */
     overrides?: SessionDataSourceOverrides;
     /** Timeout in milliseconds before the export times out. Default: 30_000ms (0 to disable). */
     timeout?: number;
+    /** Callback invoked when an export error occurs. */
     onError?: (error: Error) => void;
+    /** Callback invoked once the CSV download is triggered in the browser. */
     onSuccess?: () => void;
 }
 export interface ExportCsvTemplateOptions {
+    /** Downloaded filename. Defaults to `"template.csv"`. */
     filename?: string;
+    /** Specific column names to exclude from the template. */
     excludeColumns?: string[];
+    /** Specific subset and order of columns to include in the template. When descriptors are passed, `label` is used as the header. */
     columns?: readonly (string | ColumnDescriptor)[];
+    /**
+     * Optional mapping from schema column name to exported header name,
+     * or a resolver function `(col: string) => string`.
+     */
+    headerMapping?: CsvHeaderMapping;
+    /** Divergent table schema overrides passed to `createSessionDataSource`. */
     overrides?: SessionDataSourceOverrides;
     /** Timeout in milliseconds before template generation times out. Default: 10_000ms (0 to disable). */
     timeout?: number;
+    /** Callback invoked when a template export error occurs. */
     onError?: (error: Error) => void;
+    /** Callback invoked once the template download is triggered in the browser. */
     onSuccess?: () => void;
 }
+/**
+ * Resolves an exported CSV column header label, checking headerMapping (direct or reverse)
+ * before falling back to the column descriptor's label or column name.
+ */
+export declare const resolveHeaderLabel: (colName: string, headerMapping?: CsvHeaderMapping, fallbackLabel?: string) => string;
+/**
+ * Maps a column name to its underlying schema column name if present in headerMapping.
+ */
+export declare const resolveSchemaColumn: (colName: string, headerMapping?: CsvHeaderMapping) => string;
 export declare const isExportableColumn: (descriptor?: ExportColumnDescriptor | ColumnDescriptor) => boolean;
 /** Downloads a single-row CSV containing only the column headers, for use as an import template. */
 export declare const exportCsvTemplate: (dataSource: DataSource, options?: ExportCsvTemplateOptions) => Promise<void>;

package/types/csv-export/index.d.ts

@@ -1,2 +1,2 @@
-export { exportCsvTemplate, exportSessionTableToCsv, exportToCsv, isExportableColumn, type ExportClientColumnDescriptor, type ExportColumnDescriptor, type ExportCsvTemplateOptions, type ExportServerColumnDescriptor, type ExportToCsvOptions, type RowAccessor, } from "./export-utils";
+export { exportCsvTemplate, exportSessionTableToCsv, exportToCsv, isExportableColumn, resolveHeaderLabel, resolveSchemaColumn, type ExportClientColumnDescriptor, type ExportColumnDescriptor, type ExportCsvTemplateOptions, type ExportServerColumnDescriptor, type ExportToCsvOptions, type RowAccessor, } from "./export-utils";
 export { useCsvExport, type UseCsvExportProps, type UseCsvExportResult, } from "./useCsvExport";

package/types/csv-export/useCsvExport.d.ts

@@ -1,17 +1,41 @@
 import type { DataSource } from "@vuu-ui/vuu-data-types";
 import type { ColumnDescriptor, TableConfig } from "@vuu-ui/vuu-table-types";
-import { type ExportColumnDescriptor, type ExportCsvTemplateOptions, type ExportToCsvOptions } from "./export-utils";
+import { type CsvHeaderMapping, type ExportColumnDescriptor, type ExportCsvTemplateOptions, type ExportToCsvOptions } from "./export-utils";
 export interface UseCsvExportProps {
+    /** The target Vuu DataSource to export data or templates from. */
     dataSource?: DataSource;
+    /** Optional table configuration used to derive visible columns, order, and formatters. */
     tableConfig?: TableConfig;
+    /** Explicit columns to export when not derived from tableConfig or options. */
     columns?: readonly (string | ExportColumnDescriptor | ColumnDescriptor)[];
+    /**
+     * Optional mapping from schema column name to exported header name,
+     * or a resolver function `(col: string) => string`.
+     */
+    headerMapping?: CsvHeaderMapping;
+    /** Default error callback for export operations. */
     onError?: (error: Error) => void;
+    /** Default success callback when an export or template download is initiated. */
     onSuccess?: () => void;
 }
 export interface UseCsvExportResult {
+    /** True while an export or template download operation is in progress. */
     isExporting: boolean;
+    /** The most recent export error, or null if no error occurred. */
     error: Error | null;
+    /**
+     * Exports table data to CSV and triggers a file download in the browser.
+     *
+     * @param options - Export options including filename, columns, and limits.
+     * @param overrideDataSource - Optional DataSource to export instead of the default.
+     */
     exportCsv: (options?: ExportToCsvOptions, overrideDataSource?: DataSource) => Promise<void>;
+    /**
+     * Exports a header-only CSV template suitable for importing back into the table.
+     *
+     * @param options - Template options including filename, columns, and header mapping.
+     * @param overrideDataSource - Optional DataSource to export template for instead of the default.
+     */
     exportTemplate: (options?: ExportCsvTemplateOptions, overrideDataSource?: DataSource) => Promise<void>;
 }
 export declare function useCsvExport(propsOrDataSource?: DataSource | UseCsvExportProps): UseCsvExportResult;

package/types/csv-upload/CsvUpload.d.ts

@@ -4,39 +4,59 @@ import type { CsvParseError, CsvParseOptions } from "./parse/csv-parse";
 import type { CsvValidationStructuredError, CsvColumnValidator } from "./parse/csv-schema-validation";
 import type { DataSource, TableSchema } from "@vuu-ui/vuu-data-types";
 import type { VuuTable } from "@vuu-ui/vuu-protocol-types";
-import type { CsvUploadTableData } from "./parse/csv-upload-utils";
+import type { CsvUploadTableData, CsvHeaderMapping } from "./parse/csv-upload-utils";
 export type CsvUploadImportedResult = {
+    /** Normalized table column names and 2D row data imported into the table. */
     tableData: CsvUploadTableData;
 };
 export type CsvUploadPreviewResult = {
+    /** The live session DataSource containing the staged rows. */
     dataSource: DataSource;
+    /** The active EditSession managing the staged import. */
     editSession: EditSession;
+    /** Normalized table column names and 2D row data staged for import. */
     tableData: CsvUploadTableData;
 };
 export type CsvUploadErrors = {
+    /** Error when CSV columns do not match the target or import table schema. */
     schemaError?: CsvUploadError;
+    /** Error when CSV syntax or cell values fail type coercion or custom validation. */
     validationError?: CsvUploadError;
+    /** Error during server-side row staging or session commitment. */
     importError?: CsvUploadError;
 };
 export type CsvUploadError = {
+    /** Human-readable error description. */
     message: string;
+    /** Raw CSV parser error details, if the failure occurred during file parsing. */
     parseError?: CsvParseError;
+    /** Structured validation error map, if the failure occurred during schema/row validation. */
     validationError?: CsvValidationStructuredError;
+    /** Origin phase of the error. */
     source: "schema" | "validation" | "import";
 };
 export type CsvUploadErrorResult = {
+    /** Container of populated upload errors by category. */
     errors: CsvUploadErrors;
 };
 export type CsvUploadSessionTable = VuuTable;
 export type CsvUploadSessionEndReason = "saved" | "discarded" | "failed";
 export type CsvUploadSessionEndResult = {
+    /** Outcome reason for ending the session: `"saved"`, `"discarded"`, or `"failed"`. */
     reason: CsvUploadSessionEndReason;
+    /** The Vuu session table descriptor that was closed, if one was active. */
     sessionTable?: CsvUploadSessionTable;
 };
 export type CsvUploadPhase = "idle" | "processing" | "preview-ready" | "importing" | "imported" | "failed";
 export interface CsvUploadProps {
+    /** Optional content rendered below the drop zone inside the dialog content area (e.g., error preview table). */
     children?: ReactNode;
+    /**
+     * The Vuu DataSource for the target table. Must be subscribed (`status: "subscribed"`)
+     * and support session creation, row insertion, and edit session completion.
+     */
     dataSource: DataSource;
+    /** Renders the upload content inline without a Dialog wrapper. Defaults to `false`. */
     embedded?: boolean;
     /**
      * Schema of the import table, where it differs from the target table. Used to validate
@@ -46,20 +66,41 @@ export interface CsvUploadProps {
     importSchema?: TableSchema;
     /** Expected import table, used to validate the session table returned by the server. */
     importTable?: VuuTable;
+    /** Fired when the server-side session is fully hydrated and a preview session DataSource is available. */
     onImportSessionReady?: (dataSource: DataSource) => void;
+    /** Fired when the import session ends (whether by save, discard, or failure). */
     onImportSessionEnded?: (result: CsvUploadSessionEndResult) => void;
+    /** Fired when any error occurs, or called with `undefined` when errors are cleared. */
     onError?: (result: CsvUploadErrorResult | undefined) => void;
+    /** Fired after a successful import commit with the normalized imported table data. */
     onImported?: (result: CsvUploadImportedResult) => void;
+    /** In preview mode, fired when Import is pressed with the active EditSession and session DataSource. */
     onPreview?: (result: CsvUploadPreviewResult) => void;
+    /** Fired when file parsing and validation starts. */
     onProcessingStarted?: () => void;
+    /** Header title text displayed in the dialog header. Defaults to `"Import CSV"`. */
     dialogTitle?: string;
+    /** Maximum number of data rows permitted in the uploaded CSV. Defaults to `10000`. */
     maxRows?: number;
+    /** Fired when the user clicks Cancel. */
     onCancel?: () => void;
+    /** Fired after a successful import has completed. */
     onClose?: () => void;
+    /** Controls dialog open state. When provided, the dialog is fully controlled. */
     open?: boolean;
+    /** Parser configuration options such as requiring quotes or custom headers. */
     parseOptions?: CsvParseOptions;
+    /** Optional custom header columns to use instead of reading headers from the CSV file. */
+    customHeaders?: string[];
+    /** Whether the CSV contains a header row. Defaults to true. When false and customHeaders is provided, row 0 is treated as data. */
+    hasHeaderRow?: boolean;
+    /** Optional mapping or resolver function from CSV header column names to schema column names. */
+    headerMapping?: CsvHeaderMapping;
+    /** Import mode: `"direct"` commits immediately on Import; `"preview"` returns the session via `onPreview`. Defaults to `"direct"`. */
     importMode?: "direct" | "preview";
+    /** Default column values merged into rows where a column is omitted in the CSV. Pass a stable reference. */
     rowDefaults?: RowDefaultDataItemValues;
+    /** Custom per-column validation functions. */
     validators?: Record<string, CsvColumnValidator>;
 }
 export declare const CsvUpload: (props: CsvUploadProps) => import("react/jsx-runtime").JSX.Element;

package/types/csv-upload/index.d.ts

@@ -5,3 +5,4 @@ export { validateCsvAgainstSchema, type CsvColumnValidator, type CsvValidationOp
 export { parseCsv, type CsvParseOptions, type CsvParseResult, } from "./parse/csv-parse";
 export { CsvValidationErrorEnum, CsvParseErrorEnum, type CsvError, type CsvErrorMap, type CsvStructuredError, type CsvValidationError, type CsvValidationErrorMap, type CsvValidationErrorType, type CsvValidationStructuredError, type CsvParseError, type CsvParseErrorMap, } from "./parse/csv-errors";
 export { CSV_FIRST_DATA_ROW_NUMBER, CSV_HEADER_ROW_NUMBER, } from "./parse/csv-constants";
+export { mapCsvHeaders, type CsvHeaderMapping, type CsvUploadTableData, } from "./parse/csv-upload-utils";

package/types/csv-upload/parse/csv-parse.d.ts

@@ -1,11 +1,28 @@
 import { type CsvParseError } from "./csv-errors";
 export { CsvParseErrorEnum, type CsvError, type CsvErrorMap, type CsvStructuredError, type CsvParseError, type CsvParseErrorMap, } from "./csv-errors";
 export type CsvParseResult = {
+    /** Error object if file parsing or structure validation failed. */
     error?: CsvParseError;
+    /** Resolved header column names. */
     header: string[];
+    /** 2D array of string cell values for data rows. */
     rows: string[][];
 };
 export type CsvParseOptions = {
+    /**
+     * When true, any field containing commas, quotes, or newlines must be enclosed in double quotes.
+     */
     requireQuotedValues?: boolean;
+    /**
+     * Optional custom column headers to use. If provided and hasHeaderRow is false,
+     * all rows in the CSV are treated as data rows. If hasHeaderRow is true (or omitted),
+     * the first row is discarded and customHeaders are used.
+     */
+    customHeaders?: string[];
+    /**
+     * Whether the CSV file contains a header row. Defaults to true.
+     * When false, customHeaders must be provided.
+     */
+    hasHeaderRow?: boolean;
 };
 export declare const parseCsv: (csvText: string, options?: CsvParseOptions) => CsvParseResult;

package/types/csv-upload/parse/csv-schema-validation.d.ts

@@ -4,21 +4,38 @@ import type { CsvValidationError, CsvValidationErrorMap, CsvParseError } from ".
 import type { CsvParseResult } from "./csv-parse";
 export { CsvValidationErrorEnum, type CsvValidationError, type CsvValidationErrorMap, type CsvValidationErrorType, type CsvValidationStructuredError, } from "./csv-errors";
 export interface ImportSchemaColumn extends SchemaColumn {
+    /** When true, flags an error if a cell in this column is left empty in the CSV. */
     required?: boolean;
 }
 export interface ImportTableSchema extends Omit<TableSchema, "columns"> {
+    /** Columns definition for the import table schema. */
     readonly columns: readonly ImportSchemaColumn[];
 }
+/**
+ * Custom validation function for a specific column cell value.
+ *
+ * @param value - The raw string value from the CSV cell.
+ * @param columnName - The schema column name.
+ * @param row - Key-value map of all raw column values in the same row.
+ * @returns `true` if valid, `false` for generic error, or an error message string.
+ */
 export type CsvColumnValidator = (value: string, columnName: string, row: Record<string, string>) => boolean | string;
 export type CsvValidationResult = {
+    /** Validated column names from the CSV header. */
     columns: string[];
+    /** Two-level map of errors (fileErrors and rowErrors). */
     errorMap: CsvValidationErrorMap;
+    /** Flat array of all validation error descriptors. */
     errors: CsvValidationError[];
+    /** Parse error from the raw CSV parser, if any occurred. */
     parseRowError?: CsvParseError;
+    /** Parsed rows coerced to typed Vuu values. */
     rows: Record<string, VuuRowDataItemType>[];
 };
 export type CsvValidationOptions = {
+    /** Maximum number of data rows permitted in the CSV. Defaults to `10000`. */
     maxRows?: number;
+    /** Custom validation functions keyed by column name. */
     validators?: Record<string, CsvColumnValidator>;
 };
 export declare const validateCsvAgainstSchema: (parsed: CsvParseResult, tableSchema: TableSchema | ImportTableSchema, options?: CsvValidationOptions) => CsvValidationResult;

package/types/csv-upload/parse/csv-upload-utils.d.ts

@@ -7,6 +7,16 @@ export type CsvUploadTableData = {
     columns: string[];
     rows: VuuRowDataItemType[][];
 };
+/**
+ * Optional mapping from CSV header column names to schema column names,
+ * or a resolver function `(header: string) => string`.
+ */
+export type CsvHeaderMapping = Record<string, string> | ((header: string) => string);
+/**
+ * Maps raw CSV header column names to their corresponding schema column names
+ * using a mapping dictionary or resolver function.
+ */
+export declare const mapCsvHeaders: (headers: readonly string[], headerMapping?: CsvHeaderMapping) => string[];
 export declare const toErrorMessage: (error: unknown) => string;
 export declare const isCsvParseError: (value: unknown) => value is CsvParseError;
 export declare const hasFileParseErrors: (parseError: CsvParseError) => boolean;

package/types/csv-upload/useCsvUpload.d.ts

@@ -3,9 +3,12 @@ import type { RowDefaultDataItemValues } from "@vuu-ui/vuu-data-editing";
 import type { VuuTable } from "@vuu-ui/vuu-protocol-types";
 import { type CsvParseOptions } from "./parse/csv-parse";
 import { type CsvValidationResult, type CsvColumnValidator } from "./parse/csv-schema-validation";
+import { type CsvHeaderMapping } from "./parse/csv-upload-utils";
 import type { CsvUploadErrorResult, CsvUploadImportedResult, CsvUploadPreviewResult, CsvUploadSessionEndResult, CsvUploadSessionTable } from "./CsvUpload";
 export interface CsvUploadHookProps {
+    /** The target Vuu DataSource to upload CSV data into. */
     dataSource: DataSource;
+    /** Import mode: `"direct"` commits immediately; `"preview"` emits session for caller review. Defaults to `"direct"`. */
     importMode?: "direct" | "preview";
     /**
      * Schema of the import table, where it differs from the target table. Used to validate
@@ -15,29 +18,55 @@ export interface CsvUploadHookProps {
     importSchema?: TableSchema;
     /** Expected import table, used to validate the session table returned by the server. */
     importTable?: VuuTable;
+    /** Maximum number of data rows permitted in the CSV. Defaults to `10000`. */
     maxRows?: number;
+    /** Callback fired when the import session ends (by save, discard, or failure). */
     onImportSessionEnded?: (result: CsvUploadSessionEndResult) => void;
+    /** Callback fired when the staged session DataSource is ready for preview. */
     onImportSessionReady?: (dataSource: DataSource) => void;
+    /** Callback fired when an error occurs, or with `undefined` when errors clear. */
     onError?: (result: CsvUploadErrorResult | undefined) => void;
+    /** Callback fired after a successful import commit with the normalized table data. */
     onImported?: (result: CsvUploadImportedResult) => void;
+    /** In preview mode, callback fired when Import is triggered with the live EditSession. */
     onPreview?: (result: CsvUploadPreviewResult) => void;
+    /** Callback fired when a dropped or selected file begins processing. */
     onProcessingStarted?: () => void;
+    /** Options passed to the CSV parser (e.g., requireQuotedValues, customHeaders, hasHeaderRow). */
     parseOptions?: CsvParseOptions;
+    /** Optional custom header columns to use instead of reading headers from the CSV file. */
+    customHeaders?: string[];
+    /** Whether the CSV contains a header row. Defaults to true. When false and customHeaders is provided, row 0 is treated as data. */
+    hasHeaderRow?: boolean;
+    /** Optional mapping or resolver function from CSV header column names to schema column names. */
+    headerMapping?: CsvHeaderMapping;
     /** Default column values applied to every addRow call. Pass a stable reference — a new object triggers EditSession recreation. */
     rowDefaults?: RowDefaultDataItemValues;
+    /** Custom per-column validation functions. */
     validators?: Record<string, CsvColumnValidator>;
 }
 export type UseCsvUploadReturn = {
+    /** True when the CSV passed validation, rows staged without server errors, and import can be committed. */
     canImport: boolean;
+    /** Discards the current edit session and resets upload state. */
     cancelImport: () => Promise<void>;
+    /** Commits the staged session (in direct mode) or fires onPreview (in preview mode). */
     importData: () => Promise<boolean>;
+    /** True while the import commit is in progress. */
     isImporting: boolean;
+    /** True while parsing the CSV and staging rows on the server. */
     isProcessingFile: boolean;
+    /** Event handler for file drop zone elements. */
     onDrop: (_event: React.DragEvent<HTMLDivElement>, files: File[]) => void;
+    /** Event handler for file input change elements. */
     onTriggerChange: (_event: React.ChangeEvent<HTMLInputElement>, files: File[]) => void;
+    /** Active session table descriptor from the server. */
     sessionTable: CsvUploadSessionTable | undefined;
+    /** Active table schema used for validation. */
     schema: TableSchema | undefined;
+    /** Current validation result including parsed rows and errors. */
     validation: CsvValidationResult | undefined;
+    /** Active error result, if any. */
     error: CsvUploadErrorResult | undefined;
 };
-export declare const useCsvUpload: ({ dataSource, importMode, importSchema, importTable, onImportSessionEnded, onImportSessionReady, onError, onImported, onPreview, onProcessingStarted, maxRows, parseOptions, rowDefaults, validators, }: CsvUploadHookProps) => UseCsvUploadReturn;
+export declare const useCsvUpload: ({ dataSource, importMode, importSchema, importTable, onImportSessionEnded, onImportSessionReady, onError, onImported, onPreview, onProcessingStarted, maxRows, parseOptions, customHeaders, hasHeaderRow, headerMapping, rowDefaults, validators, }: CsvUploadHookProps) => UseCsvUploadReturn;