@vuu-ui/vuu-table-extras 3.3.1 → 3.3.3

package/README.md

@@ -0,0 +1,32 @@
+# @vuu-ui/vuu-table-extras
+
+Extended components and utilities for Vuu tables, including CSV export, CSV upload and validation, column settings, column pickers, custom cell renderers, and table footer controls.
+
+---
+
+## Features
+
+### [CSV Export](./src/csv-export/README.md)
+Standalone utilities and a React hook for exporting table data and template schemas to CSV:
+- `exportToCsv(dataSource, options)`: Subscribes to a session table, collects rows in memory in index order, formats values, and triggers browser downloads.
+- `exportCsvTemplate(dataSource, options)`: Generates a header-only CSV template for import workflows.
+- `useCsvExport(dataSource)`: React hook with built-in `isExporting` state, error handling, and helper methods.
+
+### [CSV Upload](./src/csv-upload/README.md)
+Dialog and hook workflow for importing CSV data into Vuu tables via server-side session tables:
+- `CsvUpload`: Complete dialog component with file drag-and-drop, client-side validation, error summaries, and staging controls.
+- `useCsvUpload`: Headless hook managing file parsing, schema validation, session table staging, and RPC row batching.
+- `DataUploadPreview`: Inline editable table preview for inspecting and correcting invalid staged rows before commit.
+
+### Column Management
+- `ColumnMenu` & `useColumnActions`: Context menus for sorting, grouping, filtering, and column configuration.
+- `ColumnPicker` & `useTableColumnPicker`: Dialog and drawer controls for selecting and reordering visible columns.
+- `CalculatedColumnPanel`: UI panel for defining custom expression-based columns.
+
+### Cell Renderers & Formatters
+- Pre-built cell renderers including `BackgroundCell`, `DropdownCell`, `IconButtonCell`, and undo support.
+- Cell edit validators for ensuring valid data entry.
+
+### Table Footer & Status Controls
+- `TableFooter` & `TableFooterTray`: Status bar and pagination trays.
+- `DataSourceStats`: Live indicators for row count, connection state, freeze status, and filter metrics.

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.3.1",
+  "version": "3.3.3",
   "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.3.1",
-    "@vuu-ui/vuu-protocol-types": "3.3.1"
+    "@vuu-ui/vuu-filter-types": "3.3.3",
+    "@vuu-ui/vuu-protocol-types": "3.3.3"
   },
   "dependencies": {
-    "@vuu-ui/vuu-codemirror": "3.3.1",
-    "@vuu-ui/vuu-data-editing": "3.3.1",
-    "@vuu-ui/vuu-data-react": "3.3.1",
-    "@vuu-ui/vuu-data-types": "3.3.1",
-    "@vuu-ui/vuu-table-types": "3.3.1",
-    "@vuu-ui/vuu-popups": "3.3.1",
-    "@vuu-ui/vuu-table": "3.3.1",
-    "@vuu-ui/vuu-utils": "3.3.1",
-    "@vuu-ui/vuu-ui-controls": "3.3.1",
+    "@vuu-ui/vuu-codemirror": "3.3.3",
+    "@vuu-ui/vuu-data-editing": "3.3.3",
+    "@vuu-ui/vuu-data-react": "3.3.3",
+    "@vuu-ui/vuu-data-types": "3.3.3",
+    "@vuu-ui/vuu-table-types": "3.3.3",
+    "@vuu-ui/vuu-popups": "3.3.3",
+    "@vuu-ui/vuu-table": "3.3.3",
+    "@vuu-ui/vuu-utils": "3.3.3",
+    "@vuu-ui/vuu-ui-controls": "3.3.3",
     "@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

@@ -0,0 +1,221 @@
+import { Range, isSessionTable, metadataKeys } from "@vuu-ui/vuu-utils";
+const EXPORT_EXCLUDED_COLUMNS = new Set([
+    "vuuMsg",
+    "vuuAction",
+    "vuuRowNum"
+]);
+const MAX_EXPORT_ROWS = 10000;
+const CHUNK_SIZE = 1000;
+const DEFAULT_EXPORT_TIMEOUT = 30000;
+const DEFAULT_TEMPLATE_TIMEOUT = 10000;
+const csvCell = (value)=>{
+    const s = null == value ? "" : String(value);
+    return s.includes(",") || s.includes('"') || s.includes("\n") || s.includes("\r") ? `"${s.replace(/"/g, '""')}"` : s;
+};
+const triggerCsvDownload = (csv, filename)=>{
+    const blob = new Blob([
+        csv
+    ], {
+        type: "text/csv;charset=utf-8;"
+    });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = filename;
+    a.style.display = "none";
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    setTimeout(()=>URL.revokeObjectURL(url), 10000);
+};
+const exportCsvTemplate = async (dataSource, options = {})=>{
+    const { filename = "template.csv", excludeColumns = [], columns, overrides, timeout = DEFAULT_TEMPLATE_TIMEOUT, onError, onSuccess } = options;
+    const sessionOverrides = overrides ?? (columns ? {
+        columns
+    } : void 0);
+    if (!isSessionTable(dataSource.table) && dataSource.createSessionDataSource && "initialising" !== dataSource.status && "unsubscribed" !== dataSource.status) try {
+        const sessionDataSource = await dataSource.createSessionDataSource("Empty", "export", sessionOverrides);
+        if (sessionDataSource) return new Promise((resolve, reject)=>{
+            let timer;
+            const cleanup = ()=>{
+                if (timer) clearTimeout(timer);
+                sessionDataSource.unsubscribe();
+            };
+            if (timeout > 0) timer = setTimeout(()=>{
+                cleanup();
+                const err = new Error(`exportCsvTemplate: timed out after ${timeout}ms waiting for subscription`);
+                if (onError) {
+                    onError(err);
+                    resolve();
+                } else reject(err);
+            }, timeout);
+            const excluded = new Set([
+                ...EXPORT_EXCLUDED_COLUMNS,
+                ...excludeColumns
+            ]);
+            sessionDataSource.subscribe({
+                range: Range(0, 0),
+                columns: sessionOverrides?.columns
+            }, (message)=>{
+                if ("subscribed" === message.type) {
+                    const { columns: subColumns } = message;
+                    const exportCols = subColumns.filter((name)=>!excluded.has(name));
+                    const header = exportCols.map(csvCell).join(",");
+                    triggerCsvDownload(`${header}\r\n`, filename);
+                    cleanup();
+                    onSuccess?.();
+                    resolve();
+                }
+            });
+        });
+    } catch (error) {
+        console.warn("[exportCsvTemplate] createSessionDataSource failed, falling back to tableSchema", error);
+    }
+    const schema = dataSource.tableSchema;
+    const targetColumns = columns ?? overrides?.columns;
+    if (void 0 !== targetColumns) {
+        if (schema) {
+            const schemaColumnNames = new Set(schema.columns.map((col)=>col.name));
+            const unknown = targetColumns.filter((name)=>!schemaColumnNames.has(name));
+            if (unknown.length > 0) console.warn(`[exportCsvTemplate] unknown column(s) in view tableSchema: ${unknown.join(", ")}`);
+        }
+    } else if (!schema) {
+        const error = new Error("exportCsvTemplate: tableSchema not available on dataSource");
+        if (onError) return void onError(error);
+        throw error;
+    }
+    const excluded = new Set([
+        ...EXPORT_EXCLUDED_COLUMNS,
+        ...excludeColumns
+    ]);
+    const exportCols = targetColumns ? targetColumns.filter((name)=>!excluded.has(name)) : schema?.columns.filter((col)=>!excluded.has(col.name)).map((col)=>col.name) ?? [];
+    if (0 === exportCols.length) {
+        const error = new Error("exportCsvTemplate: no columns available for export");
+        if (onError) return void onError(error);
+        throw error;
+    }
+    const header = exportCols.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, overrides, timeout = DEFAULT_EXPORT_TIMEOUT, onError, onSuccess } = options;
+    const isRemote = !!dataSource.isRemote;
+    if (isRemote && !isSessionTable(dataSource.table) && ("initialising" === dataSource.status || "unsubscribed" === dataSource.status)) {
+        const error = new Error(`exportSessionTableToCsv: dataSource must be subscribed before exporting (current status: "${dataSource.status}")`);
+        if (onError) return void onError(error);
+        throw error;
+    }
+    let sessionDataSource;
+    if (!isSessionTable(dataSource.table) && dataSource.createSessionDataSource) try {
+        sessionDataSource = await dataSource.createSessionDataSource(copyOption, "export", overrides);
+    } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        if (onError) return void onError(error);
+        throw error;
+    }
+    else sessionDataSource = dataSource;
+    if (!sessionDataSource) {
+        const error = new Error("exportSessionTableToCsv: unable to obtain sessionDataSource");
+        if (onError) return void onError(error);
+        throw error;
+    }
+    const activeSessionDataSource = sessionDataSource;
+    const excluded = new Set([
+        ...EXPORT_EXCLUDED_COLUMNS,
+        ...excludeColumns
+    ]);
+    let exportCols = [];
+    let colNameToRowIdx = {};
+    let descriptorMap = {};
+    let totalSize = 0;
+    let nextRequestedFrom = 0;
+    const collectedRows = new Map();
+    return new Promise((resolve, reject)=>{
+        let timer;
+        const cleanup = ()=>{
+            if (timer) clearTimeout(timer);
+            activeSessionDataSource.unsubscribe();
+        };
+        const fail = (err)=>{
+            cleanup();
+            if (onError) {
+                onError(err);
+                resolve();
+            } else reject(err);
+        };
+        if (timeout > 0) timer = setTimeout(()=>{
+            fail(new Error(`exportToCsv: export timed out after ${timeout}ms waiting for data`));
+        }, timeout);
+        const handleMessage = (message)=>{
+            if ("subscribed" === message.type) {
+                const { columns } = message;
+                if (columnDescriptors) {
+                    const subscribedSet = new Set(columns);
+                    const unknown = columnDescriptors.filter((d)=>!excluded.has(d.name) && !subscribedSet.has(d.name)).map((d)=>d.name);
+                    if (unknown.length > 0) return void fail(new Error(`exportToCsv: unknown column(s) in columnDescriptors: ${unknown.join(", ")}`));
+                    descriptorMap = Object.fromEntries(columnDescriptors.map((d)=>[
+                            d.name,
+                            d
+                        ]));
+                }
+                exportCols = columns.filter((name)=>!excluded.has(name));
+                colNameToRowIdx = Object.fromEntries(columns.map((name, i)=>[
+                        name,
+                        metadataKeys.count + i
+                    ]));
+            } else if ("viewport-update" === message.type) {
+                if ("size-only" === message.mode) {
+                    totalSize = message.size ?? 0;
+                    if (0 === totalSize) {
+                        cleanup();
+                        const header = exportCols.map((name)=>csvCell(descriptorMap[name]?.label ?? name)).join(",");
+                        triggerCsvDownload(`${header}\r\n`, filename);
+                        onSuccess?.();
+                        resolve();
+                        return;
+                    }
+                    if (totalSize > maxRows) return void fail(new Error(`exportToCsv: row count ${totalSize} exceeds the ${maxRows} row limit`));
+                    nextRequestedFrom = Math.min(CHUNK_SIZE, totalSize);
+                    activeSessionDataSource.range = Range(0, nextRequestedFrom);
+                } else if ("batch" === message.mode && message.rows) {
+                    for (const row of message.rows){
+                        const rowIndex = row[metadataKeys.IDX];
+                        if ("number" == typeof rowIndex) collectedRows.set(rowIndex, row);
+                    }
+                    if (void 0 !== message.size) totalSize = message.size;
+                    if (collectedRows.size >= totalSize) {
+                        cleanup();
+                        const lines = [
+                            exportCols.map((name)=>csvCell(descriptorMap[name]?.label ?? name)).join(",")
+                        ];
+                        for(let i = 0; i < totalSize; i++){
+                            const row = collectedRows.get(i);
+                            if (row) lines.push(exportCols.map((c)=>{
+                                const raw = row[colNameToRowIdx[c]];
+                                const formatter = descriptorMap[c]?.exportFormatter;
+                                return csvCell(formatter ? formatter(raw) : raw);
+                            }).join(","));
+                        }
+                        triggerCsvDownload(lines.join("\r\n"), filename);
+                        onSuccess?.();
+                        resolve();
+                    } else if (collectedRows.size >= nextRequestedFrom && nextRequestedFrom < totalSize) {
+                        const nextTo = Math.min(nextRequestedFrom + CHUNK_SIZE, totalSize);
+                        const requestedFrom = nextRequestedFrom;
+                        nextRequestedFrom = nextTo;
+                        setTimeout(()=>{
+                            activeSessionDataSource.range = Range(requestedFrom, nextTo);
+                        }, 0);
+                    }
+                }
+            }
+        };
+        activeSessionDataSource.subscribe({
+            range: Range(0, 0),
+            columns: overrides?.columns
+        }, handleMessage);
+    });
+};
+const exportToCsv = async (dataSource, options)=>exportSessionTableToCsv(dataSource, options);
+export { exportCsvTemplate, exportSessionTableToCsv, exportToCsv };

package/src/csv-export/index.js

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

package/src/csv-export/useCsvExport.js

@@ -0,0 +1,93 @@
+import { useCallback, useState } from "react";
+import { exportCsvTemplate, exportToCsv } from "./export-utils.js";
+function useCsvExport(propsOrDataSource) {
+    const [isExporting, setIsExporting] = useState(false);
+    const [error, setError] = useState(null);
+    const config = propsOrDataSource && "table" in propsOrDataSource ? {
+        dataSource: propsOrDataSource
+    } : propsOrDataSource ?? {};
+    const { dataSource: defaultDataSource, onError, onSuccess } = config;
+    const exportCsv = useCallback(async (options, overrideDataSource)=>{
+        const activeDataSource = overrideDataSource ?? defaultDataSource;
+        if (!activeDataSource) {
+            const err = new Error("useCsvExport: dataSource is required to export to CSV");
+            setError(err);
+            onError?.(err);
+            options?.onError?.(err);
+            throw err;
+        }
+        setIsExporting(true);
+        setError(null);
+        try {
+            await exportToCsv(activeDataSource, {
+                ...options,
+                onError: (err)=>{
+                    setError(err);
+                    onError?.(err);
+                    options?.onError?.(err);
+                },
+                onSuccess: ()=>{
+                    onSuccess?.();
+                    options?.onSuccess?.();
+                }
+            });
+        } catch (err) {
+            const catchedError = err instanceof Error ? err : new Error(String(err));
+            setError(catchedError);
+            onError?.(catchedError);
+            options?.onError?.(catchedError);
+            throw catchedError;
+        } finally{
+            setIsExporting(false);
+        }
+    }, [
+        defaultDataSource,
+        onError,
+        onSuccess
+    ]);
+    const exportTemplate = useCallback(async (options, overrideDataSource)=>{
+        const activeDataSource = overrideDataSource ?? defaultDataSource;
+        if (!activeDataSource) {
+            const err = new Error("useCsvExport: dataSource is required to export CSV template");
+            setError(err);
+            onError?.(err);
+            options?.onError?.(err);
+            throw err;
+        }
+        setIsExporting(true);
+        setError(null);
+        try {
+            await exportCsvTemplate(activeDataSource, {
+                ...options,
+                onError: (err)=>{
+                    setError(err);
+                    onError?.(err);
+                    options?.onError?.(err);
+                },
+                onSuccess: ()=>{
+                    onSuccess?.();
+                    options?.onSuccess?.();
+                }
+            });
+        } catch (err) {
+            const catchedError = err instanceof Error ? err : new Error(String(err));
+            setError(catchedError);
+            onError?.(catchedError);
+            options?.onError?.(catchedError);
+            throw catchedError;
+        } finally{
+            setIsExporting(false);
+        }
+    }, [
+        defaultDataSource,
+        onError,
+        onSuccess
+    ]);
+    return {
+        isExporting,
+        error,
+        exportCsv,
+        exportTemplate
+    };
+}
+export { useCsvExport };

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

@@ -1,6 +1,9 @@
 import { getTypedValue } from "@vuu-ui/vuu-utils";
 import { CsvValidationErrorEnum, addCsvFileError, addCsvRowError, createCsvErrorState } from "./csv-errors.js";
 import { CSV_FIRST_DATA_ROW_NUMBER, MAX_ROWS_IN_CSV } from "./csv-constants.js";
+const INTERNAL_KEY_COLUMNS = new Set([
+    "vuuRowNum"
+]);
 const validateCsvAgainstSchema = (parsed, tableSchema, options)=>{
     const schemaColumns = new Map(tableSchema.columns.map((col)=>[
             col.name,
@@ -8,7 +11,7 @@ const validateCsvAgainstSchema = (parsed, tableSchema, options)=>{
         ]));
     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}'.`);
+    if (tableSchema.key && !INTERNAL_KEY_COLUMNS.has(tableSchema.key) && !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 ${column} is not present in table schema.`, column);
     });

package/src/csv-upload/useCsvUpload.js

@@ -1,21 +1,67 @@
 import { EditSession } from "@vuu-ui/vuu-data-editing";
-import { isRpcError, isSessionTable } from "@vuu-ui/vuu-utils";
+import { isRpcError, isSessionTable, useData } 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, rowDefaults })=>{
+const useCsvUpload = ({ dataSource, importMode = "direct", importSchema, importTable, onImportSessionEnded, onImportSessionStarted, onError, onImported, onPreview, onProcessingStarted, maxRows, parseOptions, rowDefaults })=>{
+    const { getServerAPI } = useData();
     const [validation, setValidation] = useState();
     const [sessionTable, setSessionTable] = useState();
     const [isProcessingFile, setIsProcessingFile] = useState(false);
     const [isImporting, setIsImporting] = useState(false);
+    const [fetchedImportSchema, setFetchedImportSchema] = useState();
+    useEffect(()=>{
+        if (importSchema || void 0 === importTable) return void setFetchedImportSchema(void 0);
+        let cancelled = false;
+        (async ()=>{
+            try {
+                const server = await getServerAPI();
+                const tableSchema = await server.getTableSchema(importTable);
+                if (!cancelled) setFetchedImportSchema(tableSchema);
+            } catch (error) {
+                console.error("[useCsvUpload] failed to fetch import table schema", error);
+            }
+        })();
+        return ()=>{
+            cancelled = true;
+        };
+    }, [
+        getServerAPI,
+        importSchema,
+        importTable
+    ]);
+    const resolvedImportSchema = importSchema ?? fetchedImportSchema;
+    const sessionOverrides = useMemo(()=>{
+        const columns = resolvedImportSchema?.columns.map(({ name })=>name);
+        return columns || importTable ? {
+            columns,
+            table: importTable
+        } : void 0;
+    }, [
+        resolvedImportSchema,
+        importTable
+    ]);
+    const importDataSource = useMemo(()=>{
+        if (!sessionOverrides) return dataSource;
+        return {
+            tableSchema: dataSource.tableSchema,
+            createSessionDataSource: async (copyOption, sessionType)=>{
+                if (!dataSource.createSessionDataSource) throw Error("[useCsvUpload] dataSource does not support createSessionDataSource");
+                return dataSource.createSessionDataSource(copyOption, sessionType, sessionOverrides);
+            }
+        };
+    }, [
+        dataSource,
+        sessionOverrides
+    ]);
     const editSession = useMemo(()=>new EditSession({
-            dataSource,
+            dataSource: importDataSource,
             editSessionApi: "createSessionDataSource",
             rowDefaults
         }), [
-        dataSource,
+        importDataSource,
         rowDefaults
     ]);
     const ownsEditSessionRef = useRef(true);
@@ -61,7 +107,7 @@ const useCsvUpload = ({ dataSource, importMode = "direct", onImportSessionEnded,
         setActiveSessionDataSource
     ]);
     const table = dataSource.table;
-    const schema = dataSource.tableSchema;
+    const schema = importTable ? resolvedImportSchema : resolvedImportSchema ?? dataSource.tableSchema;
     const addAllRows = useCallback(async (mergedValidation, operationId)=>{
         const vuuMsgByRow = new Map();
         for (const { rowNum, column, message } of mergedValidation.errors){
@@ -143,6 +189,15 @@ const useCsvUpload = ({ dataSource, importMode = "direct", onImportSessionEnded,
         onError?.(void 0);
         await closePendingEditSession(false);
         if (operationId !== operationIdRef.current) return;
+        if (!isSessionTable(dataSource.table) && ("initialising" === dataSource.status || "unsubscribed" === dataSource.status)) {
+            const errorMessage = `CsvUpload requires dataSource to be subscribed before uploading (current status: "${dataSource.status}").`;
+            onError?.({
+                errors: {
+                    validationError: createUploadError("validation", errorMessage)
+                }
+            });
+            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();
@@ -198,6 +253,8 @@ const useCsvUpload = ({ dataSource, importMode = "direct", onImportSessionEnded,
         parseOptions,
         beginEditSession,
         closePendingEditSession,
+        dataSource.status,
+        dataSource.table,
         table,
         endEditSessionAndNotify,
         schema

package/src/index.js

@@ -1,3 +1,4 @@
+export * from "./csv-export/index.js";
 export * from "./csv-upload/index.js";
 export * from "./cell-edit-validators/index.js";
 export * from "./cell-renderers/index.js";

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

@@ -0,0 +1,42 @@
+import type { CopyOption, DataSource, SessionDataSourceOverrides } from "@vuu-ui/vuu-data-types";
+export type ExportColumnDescriptor<TName extends string = string> = {
+    name: TName;
+    /** Override the column name used as the CSV header label. */
+    label?: string;
+    exportFormatter?: (value: unknown) => string;
+};
+export interface ExportToCsvOptions<TName extends string = string> {
+    filename?: string;
+    copyOption?: CopyOption;
+    excludeColumns?: string[];
+    maxRows?: number;
+    columnDescriptors?: ExportColumnDescriptor<TName>[];
+    overrides?: SessionDataSourceOverrides;
+    /** Timeout in milliseconds before the export times out. Default: 30_000ms (0 to disable). */
+    timeout?: number;
+    onError?: (error: Error) => void;
+    onSuccess?: () => void;
+}
+export interface ExportCsvTemplateOptions {
+    filename?: string;
+    excludeColumns?: string[];
+    columns?: string[];
+    overrides?: SessionDataSourceOverrides;
+    /** Timeout in milliseconds before template generation times out. Default: 10_000ms (0 to disable). */
+    timeout?: number;
+    onError?: (error: Error) => void;
+    onSuccess?: () => void;
+}
+/** 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>;
+/**
+ * Subscribes to `dataSource` (creating an export session data source if a view data source is passed),
+ * collects all rows in memory in index order, serialises them to CSV (excluding internal session columns),
+ * then triggers a browser download. The session data source is unsubscribed automatically once the download
+ * is initiated.
+ */
+export declare const exportSessionTableToCsv: <TName extends string = string>(dataSource: DataSource, options?: ExportToCsvOptions<TName>) => Promise<void>;
+/**
+ * Creates an export session table from `dataSource`, collects all rows in memory, then triggers a CSV download.
+ */
+export declare const exportToCsv: <TName extends string = string>(dataSource: DataSource, options?: ExportToCsvOptions<TName>) => Promise<void>;

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

@@ -0,0 +1,2 @@
+export { exportCsvTemplate, exportSessionTableToCsv, exportToCsv, type ExportColumnDescriptor, type ExportCsvTemplateOptions, type ExportToCsvOptions, } from "./export-utils";
+export { useCsvExport, type UseCsvExportProps, type UseCsvExportResult, } from "./useCsvExport";

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

@@ -0,0 +1,14 @@
+import type { DataSource } from "@vuu-ui/vuu-data-types";
+import { type ExportCsvTemplateOptions, type ExportToCsvOptions } from "./export-utils";
+export interface UseCsvExportProps {
+    dataSource?: DataSource;
+    onError?: (error: Error) => void;
+    onSuccess?: () => void;
+}
+export interface UseCsvExportResult {
+    isExporting: boolean;
+    error: Error | null;
+    exportCsv: <TName extends string = string>(options?: ExportToCsvOptions<TName>, overrideDataSource?: DataSource) => Promise<void>;
+    exportTemplate: (options?: ExportCsvTemplateOptions, overrideDataSource?: DataSource) => Promise<void>;
+}
+export declare function useCsvExport(propsOrDataSource?: DataSource | UseCsvExportProps): UseCsvExportResult;

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

@@ -2,7 +2,7 @@ import { type ReactNode } from "react";
 import type { RowDefaultDataItemValues, EditSession } from "@vuu-ui/vuu-data-editing";
 import type { CsvParseError, CsvParseOptions } from "./parse/csv-parse";
 import type { CsvValidationStructuredError } from "./parse/csv-schema-validation";
-import type { DataSource } from "@vuu-ui/vuu-data-types";
+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";
 export type CsvUploadImportedResult = {
@@ -38,6 +38,14 @@ export interface CsvUploadProps {
     children?: ReactNode;
     dataSource: DataSource;
     embedded?: boolean;
+    /**
+     * Schema of the import table, where it differs from the target table. Used to validate
+     * the CSV and to determine the session datasource columns. If omitted and importTable is
+     * provided, the schema is fetched via getTableSchema. Pass a stable reference.
+     */
+    importSchema?: TableSchema;
+    /** Expected import table, used to validate the session table returned by the server. */
+    importTable?: VuuTable;
     onImportSessionStarted?: (dataSource: DataSource) => void;
     onImportSessionEnded?: (result: CsvUploadSessionEndResult) => void;
     onError?: (result: CsvUploadErrorResult | undefined) => void;

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

@@ -1,11 +1,20 @@
 import type { DataSource, TableSchema } from "@vuu-ui/vuu-data-types";
 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 } from "./parse/csv-schema-validation";
 import type { CsvUploadErrorResult, CsvUploadImportedResult, CsvUploadPreviewResult, CsvUploadSessionEndResult, CsvUploadSessionTable } from "./CsvUpload";
 export interface CsvUploadHookProps {
     dataSource: DataSource;
     importMode?: "direct" | "preview";
+    /**
+     * Schema of the import table, where it differs from the target table. Used to validate
+     * the CSV and to determine the session datasource columns. If omitted and importTable is
+     * provided, the schema is fetched via getTableSchema. Pass a stable reference.
+     */
+    importSchema?: TableSchema;
+    /** Expected import table, used to validate the session table returned by the server. */
+    importTable?: VuuTable;
     maxRows?: number;
     onImportSessionEnded?: (result: CsvUploadSessionEndResult) => void;
     onImportSessionStarted?: (dataSource: DataSource) => void;
@@ -29,4 +38,4 @@ export type UseCsvUploadReturn = {
     schema: TableSchema | undefined;
     validation: CsvValidationResult | undefined;
 };
-export declare const useCsvUpload: ({ dataSource, importMode, onImportSessionEnded, onImportSessionStarted, onError, onImported, onPreview, onProcessingStarted, maxRows, parseOptions, rowDefaults, }: CsvUploadHookProps) => UseCsvUploadReturn;
+export declare const useCsvUpload: ({ dataSource, importMode, importSchema, importTable, onImportSessionEnded, onImportSessionStarted, onError, onImported, onPreview, onProcessingStarted, maxRows, parseOptions, rowDefaults, }: CsvUploadHookProps) => UseCsvUploadReturn;

package/types/index.d.ts

@@ -1,4 +1,5 @@
 export { CalculatedColumnPanel } from "./calculated-column/CalculatedColumnPanel";
+export * from "./csv-export";
 export * from "./csv-upload";
 export * from "./cell-edit-validators";
 export * from "./cell-renderers";
@@ -10,7 +11,7 @@ export { useColumnActions } from "./column-menu/useColumnActions";
 export { ColumnChangeSource, ColumnModel, isColumnAdded, isColumnRemoved, isColumnsReordered, SelectedColumnChangeType, type ColumnEvents, type ColumnsChangeHandler, } from "./column-picker/ColumnModel";
 export { ColumnPicker, type ColumnPickerProps, } from "./column-picker/ColumnPicker";
 export { ColumnPickerAction } from "./column-picker/ColumnPickerAction";
-export { type SelectedColumnsChangeHandler } from "./column-picker/useColumnPicker";
+export type { SelectedColumnsChangeHandler } from "./column-picker/useColumnPicker";
 export { useTableColumnPicker } from "./column-picker/useTableColumnPicker";
 export { ColumnSettingsPanel } from "./column-settings-panel/ColumnSettingsPanel";
 export { useColumnSettings } from "./column-settings-panel/useColumnSettings";

package/types/inline-add-row/useInlineAddRow.d.ts

@@ -38,6 +38,7 @@ export declare const useInlineAddRow: ({ columns }: UseInlineAddRowProps) => {
         allowColumnHeaderMenu?: false;
         colHeaderContentRenderer?: string;
         colHeaderLabelRenderer?: string;
+        exportFormatter?: (value: unknown) => string;
         getIcon?: (row: DataRow) => string | undefined;
         groupable?: boolean;
         hidden?: boolean;