@vuu-ui/vuu-table-extras 3.0.0-beta.3 → 3.1.0-beta.1

package/src/csv-upload/data-upload-preview/useDataUploadPreview.js

@@ -0,0 +1,63 @@
+import { useCallback, useEffect, useState } from "react";
+const getSessionDataSource = (editSession)=>{
+    const dataSource = editSession.sessionDataSource;
+    if (!dataSource) throw new Error("[DataUploadPreview] requires an active edit session");
+    return dataSource;
+};
+const useDataUploadPreview = ({ dataSource, editSession, onClose })=>{
+    const [editState, setEditState] = useState(editSession.editState);
+    const [lifecycle, setLifecycle] = useState(editSession.lifecycle);
+    const [selectionCount, setSelectionCount] = useState(0);
+    const [sessionError, setSessionError] = useState();
+    const endSession = useCallback(async (save, force = false)=>{
+        try {
+            await editSession.end(save, force);
+            onClose();
+        } catch (error) {
+            setSessionError(error instanceof Error ? error.message : "Unable to end edit session");
+        }
+    }, [
+        editSession,
+        onClose
+    ]);
+    const onCancel = useCallback(()=>endSession(false), [
+        endSession
+    ]);
+    const onDelete = useCallback(()=>editSession.deleteSelectedRows(), [
+        editSession
+    ]);
+    const onSave = useCallback((force = false)=>endSession(true, force), [
+        endSession
+    ]);
+    useEffect(()=>{
+        const handleEditState = (nextEditState)=>{
+            setEditState(nextEditState);
+        };
+        const handleLifecycle = (nextLifecycle)=>{
+            setLifecycle(nextLifecycle);
+        };
+        editSession.on("editState", handleEditState);
+        editSession.on("lifecycle", handleLifecycle);
+        dataSource.on("row-selection", setSelectionCount);
+        return ()=>{
+            editSession.removeListener("editState", handleEditState);
+            editSession.removeListener("lifecycle", handleLifecycle);
+            dataSource.removeListener("row-selection", setSelectionCount);
+        };
+    }, [
+        dataSource,
+        editSession
+    ]);
+    const canCancel = "active" === lifecycle.status || "error" === lifecycle.status && "end" === lifecycle.operation;
+    const canSave = canCancel && ("dirty" === editState || "stale" === editState) && 0 === editSession.invalidCount;
+    return {
+        canCancel,
+        canSave,
+        hasSelection: selectionCount > 0,
+        onCancel,
+        onDelete,
+        onSave,
+        sessionError
+    };
+};
+export { getSessionDataSource, useDataUploadPreview };

package/src/csv-upload/index.js

@@ -0,0 +1,7 @@
+export { CsvUpload } from "./CsvUpload.js";
+export { useCsvUpload } from "./useCsvUpload.js";
+export { DataUploadPreview } from "./data-upload-preview/DataUploadPreview.js";
+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";

package/{esm/packages/vuu-table-extras/src → src}/csv-upload/parse/csv-constants.js

@@ -1,5 +1,3 @@
 const CSV_HEADER_ROW_NUMBER = 1;
 const CSV_FIRST_DATA_ROW_NUMBER = 2;
-
 export { CSV_FIRST_DATA_ROW_NUMBER, CSV_HEADER_ROW_NUMBER };
-//# sourceMappingURL=csv-constants.js.map

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

@@ -0,0 +1,54 @@
+import { CSV_HEADER_ROW_NUMBER } from "./csv-constants.js";
+var csv_errors_CsvParseErrorEnum = /*#__PURE__*/ function(CsvParseErrorEnum) {
+    CsvParseErrorEnum["EMPTY_FILE"] = "EMPTY_FILE";
+    CsvParseErrorEnum["INVALID_SEPARATOR"] = "INVALID_SEPARATOR";
+    CsvParseErrorEnum["INVALID_FORMAT"] = "INVALID_FORMAT";
+    CsvParseErrorEnum["UNQUOTED_VALUE"] = "UNQUOTED_VALUE";
+    CsvParseErrorEnum["EMPTY_HEADER_COLUMN"] = "EMPTY_HEADER_COLUMN";
+    CsvParseErrorEnum["DUPLICATE_HEADER_COLUMN"] = "DUPLICATE_HEADER_COLUMN";
+    CsvParseErrorEnum["ROW_COLUMN_COUNT_MISMATCH"] = "ROW_COLUMN_COUNT_MISMATCH";
+    return CsvParseErrorEnum;
+}({});
+var csv_errors_CsvValidationErrorEnum = /*#__PURE__*/ function(CsvValidationErrorEnum) {
+    CsvValidationErrorEnum["MISSING_KEY_COLUMN"] = "MISSING_KEY_COLUMN";
+    CsvValidationErrorEnum["UNKNOWN_COLUMN"] = "UNKNOWN_COLUMN";
+    CsvValidationErrorEnum["MAX_ROWS_EXCEEDED"] = "MAX_ROWS_EXCEEDED";
+    CsvValidationErrorEnum["EMPTY_NON_STRING_VALUE"] = "EMPTY_NON_STRING_VALUE";
+    CsvValidationErrorEnum["TYPE_MISMATCH"] = "TYPE_MISMATCH";
+    return CsvValidationErrorEnum;
+}({});
+const createCsvErrorState = ()=>({
+        errorMap: {
+            rowErrors: {},
+            fileErrors: {}
+        },
+        errors: []
+    });
+const addCsvFileError = (state, columnName, error, message, value = "")=>{
+    const existing = state.errorMap.fileErrors[columnName] ?? [];
+    existing.push(error);
+    state.errorMap.fileErrors[columnName] = existing;
+    state.errors.push({
+        rowNum: CSV_HEADER_ROW_NUMBER,
+        column: columnName,
+        value,
+        message,
+        errorEnum: error
+    });
+};
+const addCsvRowError = (state, rowNum, columnName, error, message, value = "")=>{
+    const rowErrors = state.errorMap.rowErrors[rowNum] ?? {};
+    const existing = rowErrors[columnName] ?? [];
+    existing.push(error);
+    rowErrors[columnName] = existing;
+    state.errorMap.rowErrors[rowNum] = rowErrors;
+    state.errors.push({
+        rowNum,
+        column: columnName,
+        value,
+        message,
+        errorEnum: error
+    });
+};
+const hasCsvErrors = (errorMap)=>Object.keys(errorMap.fileErrors).length > 0 || Object.keys(errorMap.rowErrors).length > 0;
+export { addCsvFileError, addCsvRowError, createCsvErrorState, csv_errors_CsvParseErrorEnum as CsvParseErrorEnum, csv_errors_CsvValidationErrorEnum as CsvValidationErrorEnum, hasCsvErrors };

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

@@ -0,0 +1,79 @@
+import { parse } from "csv-parse/browser/esm/sync";
+import { CsvParseErrorEnum, addCsvFileError, addCsvRowError, createCsvErrorState, hasCsvErrors } from "./csv-errors.js";
+import { CSV_FIRST_DATA_ROW_NUMBER, CSV_HEADER_ROW_NUMBER } from "./csv-constants.js";
+const normaliseLineEndings = (input)=>input.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+const quotedCsvLinePattern = /^\s*"(?:""|[^"])*"\s*(,\s*"(?:""|[^"])*"\s*)*$/;
+const withError = (message, errorMap, errors, header = [], rows = [])=>({
+        error: {
+            errorMap,
+            errors,
+            message
+        },
+        header,
+        rows
+    });
+const parseCsv = (csvText, options)=>{
+    const errorState = createCsvErrorState();
+    const text = normaliseLineEndings(csvText);
+    if (0 === text.trim().length) {
+        addCsvFileError(errorState, "*", CsvParseErrorEnum.EMPTY_FILE, "CSV file is empty.");
+        return withError("CSV file is empty.", errorState.errorMap, errorState.errors);
+    }
+    const allLines = text.split("\n");
+    const nonEmptyLines = allLines.filter((line)=>line.trim().length > 0);
+    if (0 === nonEmptyLines.length) {
+        addCsvFileError(errorState, "*", CsvParseErrorEnum.EMPTY_FILE, "CSV file is empty.");
+        return withError("CSV file is empty.", errorState.errorMap, errorState.errors);
+    }
+    const firstLine = nonEmptyLines[0];
+    if (firstLine.includes(";") && !firstLine.includes(",")) {
+        addCsvFileError(errorState, "*", CsvParseErrorEnum.INVALID_SEPARATOR, "CSV must use comma separators.", firstLine);
+        return withError("CSV must use comma separators.", errorState.errorMap, errorState.errors);
+    }
+    if (options?.requireQuotedValues === true) {
+        nonEmptyLines.forEach((line, lineIndex)=>{
+            if (!quotedCsvLinePattern.test(line)) if (0 === lineIndex) addCsvFileError(errorState, "*", CsvParseErrorEnum.UNQUOTED_VALUE, "CSV values must be enclosed in double quotes.", line);
+            else addCsvRowError(errorState, lineIndex + CSV_HEADER_ROW_NUMBER, "*", CsvParseErrorEnum.UNQUOTED_VALUE, "CSV values must be enclosed in double quotes.", line);
+        });
+        if (hasCsvErrors(errorState.errorMap)) return withError("CSV values must be enclosed in double quotes.", errorState.errorMap, errorState.errors);
+    }
+    let records;
+    try {
+        records = parse(text, {
+            bom: true,
+            delimiter: ",",
+            escape: '"',
+            quote: '"',
+            relax_column_count: true,
+            skip_empty_lines: true
+        });
+    } catch (err) {
+        addCsvFileError(errorState, "*", CsvParseErrorEnum.INVALID_FORMAT, err instanceof Error ? err.message : "Invalid CSV format.");
+        return withError("Invalid CSV format.", errorState.errorMap, errorState.errors);
+    }
+    if (0 === records.length) {
+        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());
+    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.");
+    });
+    if (hasCsvErrors(errorState.errorMap)) return withError("CSV header contains empty column names.", errorState.errorMap, errorState.errors);
+    const duplicateHeader = header.find((col, idx)=>header.indexOf(col) !== idx);
+    if (duplicateHeader) {
+        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);
+    rows.forEach((row, rowIndex)=>{
+        if (row.length !== header.length) addCsvRowError(errorState, rowIndex + CSV_FIRST_DATA_ROW_NUMBER, "*", CsvParseErrorEnum.ROW_COLUMN_COUNT_MISMATCH, "CSV rows must have the same number of columns as the header.", 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 {
+        header,
+        rows
+    };
+};
+export { CsvParseErrorEnum, parseCsv };

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

@@ -0,0 +1,45 @@
+import { getTypedValue } from "@vuu-ui/vuu-utils";
+import { CsvValidationErrorEnum, addCsvFileError, addCsvRowError, createCsvErrorState } from "./csv-errors.js";
+import { CSV_FIRST_DATA_ROW_NUMBER } from "./csv-constants.js";
+const MAX_ROWS_IN_CSV = 25000;
+const validateCsvAgainstSchema = (parsed, tableSchema, options)=>{
+    const schemaColumns = new Map(tableSchema.columns.map((col)=>[
+            col.name,
+            col.serverDataType
+        ]));
+    const maxRows = options?.maxRows ?? MAX_ROWS_IN_CSV;
+    const errorState = createCsvErrorState();
+    if (!parsed.header.includes(tableSchema.key)) addCsvFileError(errorState, tableSchema.key, CsvValidationErrorEnum.MISSING_KEY_COLUMN, `CSV must include key column '${tableSchema.key}'.`);
+    parsed.header.forEach((column)=>{
+        if (!schemaColumns.has(column)) addCsvFileError(errorState, column, CsvValidationErrorEnum.UNKNOWN_COLUMN, "Column is not present in table schema.", column);
+    });
+    if (parsed.rows.length > maxRows) addCsvFileError(errorState, "*", CsvValidationErrorEnum.MAX_ROWS_EXCEEDED, `CSV row count ${parsed.rows.length} exceeds maxRows ${maxRows}.`, String(parsed.rows.length));
+    const typedRows = [];
+    parsed.rows.forEach((rowValues, rowIndex)=>{
+        const rowNum = rowIndex + CSV_FIRST_DATA_ROW_NUMBER;
+        const typedRow = {};
+        parsed.header.forEach((columnName, columnIndex)=>{
+            const rawValue = rowValues[columnIndex];
+            const schemaType = schemaColumns.get(columnName);
+            if (0 === rawValue.length && "string" !== schemaType) return void addCsvRowError(errorState, rowNum, columnName, CsvValidationErrorEnum.EMPTY_NON_STRING_VALUE, "Empty value is not allowed for non-string columns.", rawValue);
+            let value;
+            const toType = schemaType ?? "string";
+            try {
+                value = getTypedValue(rawValue, toType);
+            } catch (err) {
+                addCsvRowError(errorState, rowNum, columnName, CsvValidationErrorEnum.TYPE_MISMATCH, err instanceof Error ? err.message : String(err), rawValue);
+                return;
+            }
+            if (void 0 === value) return void addCsvRowError(errorState, rowNum, columnName, CsvValidationErrorEnum.TYPE_MISMATCH, `Value '${rawValue}' is not a valid ${toType}`, rawValue);
+            typedRow[columnName] = value;
+        });
+        typedRows.push(typedRow);
+    });
+    return {
+        columns: parsed.header,
+        errorMap: errorState.errorMap,
+        errors: errorState.errors,
+        rows: typedRows
+    };
+};
+export { CsvValidationErrorEnum, validateCsvAgainstSchema };

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

@@ -0,0 +1,59 @@
+import { isRpcError } from "@vuu-ui/vuu-utils";
+import { CSV_FIRST_DATA_ROW_NUMBER } from "./csv-constants.js";
+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);
+const hasFileParseErrors = (parseError)=>Object.keys(parseError.errorMap.fileErrors).length > 0;
+const createUploadError = (source, message, parseError, validationError)=>({
+        message,
+        parseError,
+        validationError,
+        source
+    });
+const mergeValidationWithParseErrors = (schemaValidation, parseError)=>parseError ? {
+        ...schemaValidation,
+        errors: [
+            ...schemaValidation.errors,
+            ...toValidationErrorsFromParseRowErrors(parseError)
+        ],
+        parseRowError: parseError
+    } : schemaValidation;
+const buildRowErrorMessage = (prefix, rowErrors)=>{
+    const details = rowErrors.slice(0, 8).join("; ");
+    const remaining = rowErrors.length - 8;
+    const suffix = remaining > 0 ? `; and ${remaining} more` : "";
+    return `${prefix} for ${rowErrors.length} row(s): ${details}${suffix}`;
+};
+const toValidationErrorsFromParseRowErrors = (parseError)=>parseError.errors.filter((error)=>error.rowNum >= CSV_FIRST_DATA_ROW_NUMBER);
+const normalizeTableData = (value, fallback)=>{
+    const tableData = isRecord(value) && "data" in value ? value.data : value;
+    if (!isRecord(tableData)) return fallback;
+    const columns = tableData.columns;
+    const rows = tableData.rows;
+    if (!Array.isArray(columns) || columns.some((column)=>"string" != typeof column) || !Array.isArray(rows)) return fallback;
+    return {
+        columns,
+        rows: rows.map((row)=>{
+            if (Array.isArray(row)) return row;
+            if (!isRecord(row)) return columns.map(()=>"");
+            return columns.map((column)=>row[column] ?? "");
+        })
+    };
+};
+const executeBatchRpcCalls = async (items, executor, errorFormatter)=>{
+    const errors = [];
+    const results = [];
+    for (const item of items)try {
+        const result = await executor(item);
+        const rpcResult = result;
+        if (isRpcError(rpcResult)) errors.push(errorFormatter(item, rpcResult.errorMessage));
+        else results.push(result);
+    } catch (err) {
+        errors.push(errorFormatter(item, toErrorMessage(err)));
+    }
+    return {
+        errors,
+        results
+    };
+};
+export { buildRowErrorMessage, createUploadError, executeBatchRpcCalls, hasFileParseErrors, isCsvParseError, mergeValidationWithParseErrors, normalizeTableData, toErrorMessage, toValidationErrorsFromParseRowErrors };

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

@@ -0,0 +1,5 @@
+export { CSV_FIRST_DATA_ROW_NUMBER, CSV_HEADER_ROW_NUMBER } from "./csv-constants.js";
+export { CsvParseErrorEnum, CsvValidationErrorEnum, addCsvFileError, addCsvRowError, createCsvErrorState, hasCsvErrors } from "./csv-errors.js";
+export { parseCsv } from "./csv-parse.js";
+export { validateCsvAgainstSchema } from "./csv-schema-validation.js";
+export { buildRowErrorMessage, executeBatchRpcCalls, hasFileParseErrors, isCsvParseError, mergeValidationWithParseErrors, normalizeTableData, toErrorMessage, toValidationErrorsFromParseRowErrors } from "./csv-upload-utils.js";

package/src/csv-upload/useCsvUpload.js

@@ -0,0 +1,305 @@
+import { EditSession } from "@vuu-ui/vuu-data-editing";
+import { isRpcError, isSessionTable } from "@vuu-ui/vuu-utils";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { parseCsv } from "./parse/csv-parse.js";
+import { validateCsvAgainstSchema } from "./parse/csv-schema-validation.js";
+import { buildRowErrorMessage, createUploadError, hasFileParseErrors, isCsvParseError, mergeValidationWithParseErrors, toErrorMessage } from "./parse/csv-upload-utils.js";
+import { CSV_FIRST_DATA_ROW_NUMBER } from "./parse/csv-constants.js";
+const useCsvUpload = ({ dataSource, importMode = "direct", onImportSessionEnded, onImportSessionStarted, onError, onImported, onPreview, onProcessingStarted, maxRows, parseOptions })=>{
+    const [validation, setValidation] = useState();
+    const [sessionTable, setSessionTable] = useState();
+    const [isProcessingFile, setIsProcessingFile] = useState(false);
+    const [isImporting, setIsImporting] = useState(false);
+    const editSession = useMemo(()=>new EditSession(dataSource), [
+        dataSource
+    ]);
+    const ownsEditSessionRef = useRef(true);
+    const operationIdRef = useRef(0);
+    const processingPromiseRef = useRef(void 0);
+    const sessionDataSourceRef = useRef(void 0);
+    useEffect(()=>()=>{
+            operationIdRef.current++;
+            const processingPromise = processingPromiseRef.current;
+            (async ()=>{
+                try {
+                    await processingPromise;
+                } finally{
+                    if (ownsEditSessionRef.current) try {
+                        await editSession.end(false);
+                    } catch (error) {
+                        console.error("[useCsvUpload] failed to discard edit session during cleanup", error);
+                    }
+                }
+            })();
+        }, [
+        editSession
+    ]);
+    const setActiveSessionDataSource = useCallback((sessionDataSource)=>{
+        sessionDataSourceRef.current = sessionDataSource;
+        const table = sessionDataSource?.table;
+        setSessionTable(table && isSessionTable(table) ? table : void 0);
+    }, []);
+    const endEditSessionAndNotify = useCallback(async (save, reason)=>{
+        const sessionDataSource = sessionDataSourceRef.current;
+        if (!sessionDataSource) throw Error("CsvUpload has no active edit session.");
+        if (!sessionDataSource.endEditSession) throw Error("CsvUpload requires the session datasource to support endEditSession.");
+        const currentSessionTable = sessionDataSource.table;
+        await editSession.end(save);
+        setActiveSessionDataSource(void 0);
+        onImportSessionEnded?.({
+            reason,
+            sessionTable: currentSessionTable && isSessionTable(currentSessionTable) ? currentSessionTable : void 0
+        });
+    }, [
+        editSession,
+        onImportSessionEnded,
+        setActiveSessionDataSource
+    ]);
+    const table = dataSource.table;
+    const schema = dataSource.tableSchema;
+    const addAllRows = useCallback(async (mergedValidation, operationId)=>{
+        const vuuMsgByRow = new Map();
+        for (const { rowNum, column, message } of mergedValidation.errors){
+            if (rowNum < CSV_FIRST_DATA_ROW_NUMBER) continue;
+            const existing = vuuMsgByRow.get(rowNum);
+            const columnError = `${column}: ${message}`;
+            vuuMsgByRow.set(rowNum, existing ? `${existing}; ${columnError}` : `Row ${rowNum}: ${columnError}`);
+        }
+        const parsedRowCount = mergedValidation.rows.length;
+        const unparsedErrorRows = [
+            ...vuuMsgByRow.keys()
+        ].filter((rowNum)=>rowNum - CSV_FIRST_DATA_ROW_NUMBER >= parsedRowCount).map((rowNum)=>({
+                rowNum,
+                rowData: {},
+                vuuMsg: vuuMsgByRow.get(rowNum) ?? ""
+            }));
+        const allRows = [
+            ...mergedValidation.rows.map((rowData, idx)=>({
+                    rowNum: idx + CSV_FIRST_DATA_ROW_NUMBER,
+                    rowData: rowData ?? {},
+                    vuuMsg: vuuMsgByRow.get(idx + CSV_FIRST_DATA_ROW_NUMBER) ?? ""
+                })),
+            ...unparsedErrorRows
+        ];
+        const rpcErrors = [];
+        for (const { rowNum, rowData, vuuMsg } of allRows){
+            if (operationId !== operationIdRef.current) return false;
+            try {
+                const payload = {
+                    ...rowData,
+                    rowNum,
+                    vuuMsg
+                };
+                const result = await editSession.addRow(payload);
+                if (isRpcError(result)) throw Error(result.errorMessage);
+                if ("string" == typeof result) throw Error(result);
+            } catch (error) {
+                rpcErrors.push(`Row ${rowNum}: ${toErrorMessage(error)}`);
+            }
+        }
+        if (rpcErrors.length > 0) throw Error(buildRowErrorMessage("Import failed", rpcErrors));
+        return true;
+    }, [
+        editSession
+    ]);
+    const beginEditSession = useCallback(async ()=>{
+        const sessionDataSource = await editSession.begin("Empty");
+        const sessionVuuTable = sessionDataSource?.table;
+        if (void 0 === sessionDataSource || void 0 === sessionVuuTable || !isSessionTable(sessionVuuTable)) throw Error("CsvUpload createSessionDataSource returned no session datasource.");
+        if (!sessionDataSource.columns.includes("vuuMsg")) sessionDataSource.columns = sessionDataSource.columns.concat("vuuMsg");
+        setActiveSessionDataSource(sessionDataSource);
+        onImportSessionStarted?.(sessionDataSource);
+        return sessionDataSource;
+    }, [
+        editSession,
+        onImportSessionStarted,
+        setActiveSessionDataSource
+    ]);
+    const closePendingEditSession = useCallback(async (save)=>{
+        if (void 0 === sessionDataSourceRef.current) return;
+        await endEditSessionAndNotify(save, save ? "saved" : "discarded");
+    }, [
+        endEditSessionAndNotify
+    ]);
+    const cancelImport = useCallback(async ()=>{
+        operationIdRef.current++;
+        try {
+            await processingPromiseRef.current;
+        } catch  {}
+        await closePendingEditSession(false);
+    }, [
+        closePendingEditSession
+    ]);
+    const processFile = useCallback(async (file, operationId)=>{
+        setValidation(void 0);
+        onError?.(void 0);
+        await closePendingEditSession(false);
+        if (operationId !== operationIdRef.current) return;
+        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 fileContents = await file.text();
+        if (operationId !== operationIdRef.current) return;
+        const parsedCsv = parseCsv(fileContents, parseOptions);
+        if (parsedCsv.error && hasFileParseErrors(parsedCsv.error)) {
+            setValidation(void 0);
+            onError?.({
+                errors: {
+                    validationError: createUploadError("validation", `Validation failed: ${parsedCsv.error.message}`, parsedCsv.error)
+                }
+            });
+            return;
+        }
+        const schemaValidation = validateCsvAgainstSchema(parsedCsv, schema, {
+            maxRows
+        });
+        if (Object.keys(schemaValidation.errorMap.fileErrors).length > 0) {
+            setValidation(schemaValidation);
+            onError?.({
+                errors: {
+                    schemaError: createUploadError("schema", "CSV validation failed.", parsedCsv.error, {
+                        errorMap: schemaValidation.errorMap,
+                        errors: schemaValidation.errors,
+                        message: "CSV validation failed."
+                    })
+                }
+            });
+            return;
+        }
+        const mergedValidation = mergeValidationWithParseErrors(schemaValidation, parsedCsv.error);
+        setValidation(mergedValidation);
+        if (mergedValidation.rows.length > 0) {
+            await beginEditSession();
+            if (operationId !== operationIdRef.current) return;
+            try {
+                const rowsAdded = await addAllRows(mergedValidation, operationId);
+                if (!rowsAdded) return;
+            } catch (error) {
+                await endEditSessionAndNotify(false, "failed");
+                setValidation(void 0);
+                onError?.({
+                    errors: {
+                        importError: createUploadError("import", `RPC import failed: ${toErrorMessage(error)}`)
+                    }
+                });
+            }
+        }
+    }, [
+        onError,
+        addAllRows,
+        maxRows,
+        parseOptions,
+        beginEditSession,
+        closePendingEditSession,
+        table,
+        endEditSessionAndNotify,
+        schema
+    ]);
+    const handleFiles = useCallback(async (files)=>{
+        const file = files[0];
+        if (void 0 === file) return;
+        setIsProcessingFile(true);
+        onProcessingStarted?.();
+        const operationId = ++operationIdRef.current;
+        const processingPromise = processFile(file, operationId);
+        processingPromiseRef.current = processingPromise;
+        try {
+            await processingPromise;
+        } catch (err) {
+            setValidation(void 0);
+            setActiveSessionDataSource(void 0);
+            const parseError = isCsvParseError(err) ? err : void 0;
+            const errorMessage = parseError ? `Validation failed: ${parseError.message}` : `Validation failed: ${toErrorMessage(err)}`;
+            const errors = {
+                errors: {
+                    validationError: createUploadError("validation", errorMessage, parseError)
+                }
+            };
+            onError?.(errors);
+        } finally{
+            if (processingPromiseRef.current === processingPromise) processingPromiseRef.current = void 0;
+            setIsProcessingFile(false);
+        }
+    }, [
+        onError,
+        onProcessingStarted,
+        processFile,
+        setActiveSessionDataSource
+    ]);
+    const onDrop = useCallback((_event, files)=>{
+        handleFiles(files);
+    }, [
+        handleFiles
+    ]);
+    const onTriggerChange = useCallback((_event, files)=>{
+        handleFiles(files);
+    }, [
+        handleFiles
+    ]);
+    const canImport = useMemo(()=>void 0 !== validation && 0 === validation.errors.length && validation.rows.length > 0 && !isProcessingFile && !isImporting, [
+        isImporting,
+        isProcessingFile,
+        validation
+    ]);
+    const importData = useCallback(async ()=>{
+        if (!canImport || void 0 === validation) return false;
+        setIsImporting(true);
+        onError?.(void 0);
+        try {
+            const fallbackTableData = {
+                columns: validation.columns,
+                rows: validation.rows.map((row)=>validation.columns.map((column)=>row[column] ?? ""))
+            };
+            const tableData = fallbackTableData;
+            if ("preview" === importMode) {
+                const sessionDataSource = sessionDataSourceRef.current;
+                if (!sessionDataSource) throw Error("CsvUpload has no session datasource to preview.");
+                if (!onPreview) throw Error("CsvUpload preview mode requires an onPreview callback.");
+                onPreview({
+                    dataSource: sessionDataSource,
+                    editSession,
+                    tableData
+                });
+                ownsEditSessionRef.current = false;
+            } else {
+                await endEditSessionAndNotify(true, "saved");
+                onImported?.({
+                    tableData
+                });
+            }
+            return true;
+        } catch (err) {
+            const errorMessage = `RPC import failed: ${String(err)}`;
+            const errors = {
+                errors: {
+                    importError: createUploadError("import", errorMessage)
+                }
+            };
+            onError?.(errors);
+            return false;
+        } finally{
+            setIsImporting(false);
+        }
+    }, [
+        canImport,
+        editSession,
+        endEditSessionAndNotify,
+        onError,
+        onImported,
+        onPreview,
+        importMode,
+        validation
+    ]);
+    return {
+        canImport,
+        cancelImport,
+        importData,
+        isImporting,
+        isProcessingFile,
+        onDrop,
+        onTriggerChange,
+        sessionTable,
+        schema,
+        validation
+    };
+};
+export { useCsvUpload };