@vuu-ui/vuu-table-extras 3.3.0 → 3.3.2

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.3.0",
+  "version": "3.3.2",
   "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.0",
-    "@vuu-ui/vuu-protocol-types": "3.3.0"
+    "@vuu-ui/vuu-filter-types": "3.3.2",
+    "@vuu-ui/vuu-protocol-types": "3.3.2"
   },
   "dependencies": {
-    "@vuu-ui/vuu-codemirror": "3.3.0",
-    "@vuu-ui/vuu-data-editing": "3.3.0",
-    "@vuu-ui/vuu-data-react": "3.3.0",
-    "@vuu-ui/vuu-data-types": "3.3.0",
-    "@vuu-ui/vuu-table-types": "3.3.0",
-    "@vuu-ui/vuu-popups": "3.3.0",
-    "@vuu-ui/vuu-table": "3.3.0",
-    "@vuu-ui/vuu-utils": "3.3.0",
-    "@vuu-ui/vuu-ui-controls": "3.3.0",
+    "@vuu-ui/vuu-codemirror": "3.3.2",
+    "@vuu-ui/vuu-data-editing": "3.3.2",
+    "@vuu-ui/vuu-data-react": "3.3.2",
+    "@vuu-ui/vuu-data-types": "3.3.2",
+    "@vuu-ui/vuu-table-types": "3.3.2",
+    "@vuu-ui/vuu-popups": "3.3.2",
+    "@vuu-ui/vuu-table": "3.3.2",
+    "@vuu-ui/vuu-utils": "3.3.2",
+    "@vuu-ui/vuu-ui-controls": "3.3.2",
     "@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,164 @@
+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 csvCell = (value)=>{
+    const s = null == value ? "" : String(value);
+    return s.includes(",") || s.includes('"') || s.includes("\n") ? `"${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, filename = "template.csv", excludeColumns = [], columns, overrides)=>{
+    const sessionOverrides = overrides ?? (columns ? {
+        columns
+    } : void 0);
+    if (!isSessionTable(dataSource.table) && dataSource.createSessionDataSource) try {
+        const sessionDataSource = await dataSource.createSessionDataSource("Empty", "export", sessionOverrides);
+        if (sessionDataSource) return new Promise((resolve)=>{
+            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);
+                    sessionDataSource.unsubscribe();
+                    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) throw Error("exportCsvTemplate: tableSchema not available on dataSource");
+    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) throw Error("exportCsvTemplate: no columns available for export");
+    const header = exportCols.map(csvCell).join(",");
+    triggerCsvDownload(`${header}\r\n`, filename);
+};
+const exportSessionTableToCsv = async (dataSource, filename = "export.csv", excludeColumns = [], onError, onSuccess, maxRows = MAX_EXPORT_ROWS, columnDescriptors, copyOption = "All", overrides)=>{
+    let sessionDataSource;
+    if (!isSessionTable(dataSource.table) && dataSource.createSessionDataSource) try {
+        sessionDataSource = await dataSource.createSessionDataSource(copyOption, "export", overrides);
+    } catch (err) {
+        onError?.(err instanceof Error ? err : new Error(String(err)));
+        return;
+    }
+    else sessionDataSource = dataSource;
+    if (!sessionDataSource) return void onError?.(new Error("exportSessionTableToCsv: unable to obtain sessionDataSource"));
+    const activeSessionDataSource = sessionDataSource;
+    const excluded = new Set([
+        ...EXPORT_EXCLUDED_COLUMNS,
+        ...excludeColumns
+    ]);
+    let exportCols = [];
+    let colNameToRowIdx = {};
+    let descriptorMap = {};
+    let totalSize = 0;
+    const collectedRows = [];
+    return new Promise((resolve)=>{
+        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) {
+                        activeSessionDataSource.unsubscribe();
+                        onError?.(new Error(`exportToCsv: unknown column(s) in columnDescriptors: ${unknown.join(", ")}`));
+                        resolve();
+                        return;
+                    }
+                    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) {
+                        activeSessionDataSource.unsubscribe();
+                        onSuccess?.();
+                        resolve();
+                        return;
+                    }
+                    if (totalSize > maxRows) {
+                        activeSessionDataSource.unsubscribe();
+                        onError?.(new Error(`exportToCsv: row count ${totalSize} exceeds the ${maxRows} row limit`));
+                        resolve();
+                        return;
+                    }
+                    activeSessionDataSource.range = Range(0, Math.min(CHUNK_SIZE, totalSize));
+                } else if ("batch" === message.mode && message.rows) {
+                    collectedRows.push(...message.rows);
+                    if (void 0 !== message.size) totalSize = message.size;
+                    if (collectedRows.length >= totalSize) {
+                        activeSessionDataSource.unsubscribe();
+                        const lines = [
+                            exportCols.map((name)=>csvCell(descriptorMap[name]?.label ?? name)).join(",")
+                        ];
+                        for (const row of collectedRows)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 {
+                        const nextFrom = collectedRows.length;
+                        activeSessionDataSource.range = Range(nextFrom, Math.min(nextFrom + CHUNK_SIZE, totalSize));
+                    }
+                }
+            }
+        };
+        activeSessionDataSource.subscribe({
+            range: Range(0, 0),
+            columns: overrides?.columns
+        }, handleMessage);
+    });
+};
+const exportToCsv = async (dataSource, copyOption = "All", filename = "export.csv", excludeColumns = [], onError, onSuccess, maxRows = MAX_EXPORT_ROWS, columnDescriptors, overrides)=>exportSessionTableToCsv(dataSource, filename, excludeColumns, onError, onSuccess, maxRows, columnDescriptors, copyOption, overrides);
+export { exportCsvTemplate, exportSessionTableToCsv, exportToCsv };

package/src/csv-export/index.js

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

package/src/csv-upload/useCsvUpload.js

@@ -1,17 +1,68 @@
 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 })=>{
+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 editSession = useMemo(()=>new EditSession(dataSource), [
-        dataSource
+    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: importDataSource,
+            editSessionApi: "createSessionDataSource",
+            rowDefaults
+        }), [
+        importDataSource,
+        rowDefaults
     ]);
     const ownsEditSessionRef = useRef(true);
     const operationIdRef = useRef(0);
@@ -56,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){

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,20 @@
+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;
+};
+/** Downloads a single-row CSV containing only the column headers, for use as an import template. */
+export declare const exportCsvTemplate: (dataSource: DataSource, filename?: string, excludeColumns?: string[], columns?: string[], overrides?: SessionDataSourceOverrides) => Promise<void>;
+/**
+ * Subscribes to `dataSource` (creating an export session data source if a view data source is passed)
+ * with a full-range request to drain all rows, 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, filename?: string, excludeColumns?: string[], onError?: (error: Error) => void, onSuccess?: () => void, maxRows?: number, columnDescriptors?: ExportColumnDescriptor<TName>[], copyOption?: CopyOption, overrides?: SessionDataSourceOverrides) => Promise<void>;
+/**
+ * Creates an export session table from `dataSource` then streams all rows to a CSV download.
+ */
+export declare const exportToCsv: <TName extends string = string>(dataSource: DataSource, copyOption?: CopyOption, filename?: string, excludeColumns?: string[], onError?: (error: Error) => void, onSuccess?: () => void, maxRows?: number, columnDescriptors?: ExportColumnDescriptor<TName>[], overrides?: SessionDataSourceOverrides) => Promise<void>;

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

@@ -0,0 +1 @@
+export { exportCsvTemplate, exportSessionTableToCsv, exportToCsv, type ExportColumnDescriptor, } from "./export-utils";

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

@@ -1,9 +1,9 @@
 import { type ReactNode } from "react";
-import type { DataSource } from "@vuu-ui/vuu-data-types";
-import type { EditSession } from "@vuu-ui/vuu-data-editing";
-import type { VuuTable } from "@vuu-ui/vuu-protocol-types";
+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, 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 = {
     tableData: CsvUploadTableData;
@@ -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;
@@ -51,5 +59,6 @@ export interface CsvUploadProps {
     open?: boolean;
     parseOptions?: CsvParseOptions;
     importMode?: "direct" | "preview";
+    rowDefaults?: RowDefaultDataItemValues;
 }
 export declare const CsvUpload: (props: CsvUploadProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -1,10 +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;
@@ -13,6 +23,8 @@ export interface CsvUploadHookProps {
     onPreview?: (result: CsvUploadPreviewResult) => void;
     onProcessingStarted?: () => void;
     parseOptions?: CsvParseOptions;
+    /** Default column values applied to every addRow call. Pass a stable reference — a new object triggers EditSession recreation. */
+    rowDefaults?: RowDefaultDataItemValues;
 }
 export type UseCsvUploadReturn = {
     canImport: boolean;
@@ -26,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, }: 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;