@wordrhyme/auto-crud 1.11.2 → 1.12.1

package/dist/index.cjs

@@ -4641,6 +4641,27 @@ function coerceRowValues(rows, schema) {
 
 //#endregion
 //#region src/lib/export.ts
+/** Snapshot rendered business columns without changing the legacy CSV column policy. */
+function getVisibleExportColumns(table, deny = []) {
+	const excluded = new Set([
+		"select",
+		"actions",
+		...deny
+	]);
+	return [
+		...table.getLeftVisibleLeafColumns(),
+		...table.getCenterVisibleLeafColumns(),
+		...table.getRightVisibleLeafColumns()
+	].filter((column) => {
+		if (excluded.has(column.id)) return false;
+		const meta = column.columnDef.meta;
+		if (meta?.autoCrudExpandColumn) return false;
+		return ![meta?.classNames?.th, meta?.classNames?.td].some((value) => typeof value === "string" && /(?:^|\s)!?hidden!?(?:\s|$)/.test(value));
+	}).map((column) => ({
+		id: column.id,
+		label: column.columnDef.meta?.label ?? (typeof column.columnDef.header === "string" ? column.columnDef.header : column.id)
+	}));
+}
 function getExportColumnIds(table) {
 	return table.getAllLeafColumns().filter((column) => column.accessorFn).map((column) => column.id);
 }
@@ -5157,7 +5178,7 @@ const filterModeConfig = {
 		tooltip: "Linear-style command filters"
 	}
 };
-function AutoTable({ schema, data, getRowId, expandedRow, defaultExpanded = false, pageCount = 1, pagination, total, overrides, classNames, enableRowSelection = true, exclude, filterOnly, actions, pinnedColumns, filterMode, search = false, toolbarExtra, locale = enUSTableControls, onDeleteSelected, onUpdateSelected, batchUpdateFields, actionBarExtra, actionBarActions, deleteConfirmation, initialSorting, enableExport = true, showDefaultExport = true, onSelectedCountChange, onSelectedRowsChange, getSelectedRows }) {
+function AutoTable({ schema, data, getRowId, expandedRow, defaultExpanded = false, pageCount = 1, pagination, total, overrides, classNames, enableRowSelection = true, exclude, filterOnly, actions, pinnedColumns, filterMode, search = false, toolbarExtra, locale = enUSTableControls, onDeleteSelected, onUpdateSelected, batchUpdateFields, actionBarExtra, actionBarActions, deleteConfirmation, initialSorting, enableExport = true, showDefaultExport = true, onSelectedCountChange, onSelectedRowsChange, getSelectedRows, exportTableRef }) {
 	if (expandedRow && !getRowId) throw new Error("AutoTable requires getRowId when expandedRow is provided.");
 	const enableExpansion = !!expandedRow;
 	const modes = filterMode ? Array.isArray(filterMode) ? filterMode : [filterMode] : DEFAULT_MODES;
@@ -5199,6 +5220,7 @@ function AutoTable({ schema, data, getRowId, expandedRow, defaultExpanded = fals
 			while (expandColumnId$1 in schema.shape || result.some((column) => column.id === expandColumnId$1)) expandColumnId$1 = `_${expandColumnId$1}`;
 			result.unshift({
 				id: expandColumnId$1,
+				meta: { autoCrudExpandColumn: true },
 				header: () => /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 					className: "sr-only",
 					children: "Row details"
@@ -5272,6 +5294,13 @@ function AutoTable({ schema, data, getRowId, expandedRow, defaultExpanded = fals
 			};
 		});
 	}, [table, filterOnly]);
+	(0, react.useEffect)(() => {
+		if (!exportTableRef) return;
+		exportTableRef.current = table;
+		return () => {
+			exportTableRef.current = null;
+		};
+	}, [table, exportTableRef]);
 	const rowSelection = table.getState().rowSelection;
 	const columnFilters = table.getState().columnFilters;
 	const selectedRows = (0, react.useMemo)(() => table.getFilteredSelectedRowModel().rows.map((row) => row.original), [
@@ -6830,6 +6859,9 @@ function resolveToolbarActionsWithResolver(targetId, ownerActions, context) {
 	const resolver = autoCrudToolbarResolver;
 	return targetId !== void 0 && targetId.length > 0 && resolver !== null ? resolver(targetId, ownerActions, context) : ownerActions;
 }
+function reportExportError(error) {
+	sonner.toast.error(error instanceof Error ? error.message : String(error));
+}
 function applyResourceTablePresentation(fields, resourceFields) {
 	if (!fields || !resourceFields) return fields;
 	return Object.fromEntries(Object.entries(fields).map(([key, config]) => {
@@ -7709,7 +7741,7 @@ function resolveActions(actions, defaults, rowActionsLocale, context) {
 *
 * 高级 CRUD 表格组件，封装了完整的增删改查流程
 */
-function AutoCrudTable({ id, title, description, schema, resource, fields, table: tableConfig, form: formConfig, view: viewConfig, permissions, actions: actionItems, toolbar, toolbarActions, locale: localeProp, onCreate }) {
+function AutoCrudTable({ id, title, description, schema, resource, fields, table: tableConfig, form: formConfig, view: viewConfig, permissions, actions: actionItems, toolbar, toolbarActions, locale: localeProp, onCreate, onExport }) {
 	const locale = resolveLocale(localeProp);
 	const getPagination = react.useCallback(() => id ? tablePagination.get(id) : void 0, [id]);
 	const registeredPagination = react.useSyncExternalStore(tablePagination.subscribe, getPagination, getPagination);
@@ -7729,6 +7761,8 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 	const [importOpen, setImportOpen] = react.useState(false);
 	const [selectedRows, setSelectedRows] = react.useState([]);
 	const [exporting, setExporting] = react.useState(false);
+	const exportBusyRef = react.useRef(false);
+	const exportTableRef = react.useRef(null);
 	const getSelectedRowsRef = react.useRef(null);
 	const dynamicFilterOptions = useDynamicFilterOptions(resolvedFields);
 	const filterOnly = react.useMemo(() => Object.entries(resolvedFields).filter(([key, config]) => config.table === false && config.filter && config.hidden !== true && !denyFields?.includes(key) && !tableConfig?.hidden?.includes(key) && tableConfig?.overrides?.[key]?.hidden !== true).map(([key]) => key), [
@@ -7787,6 +7821,26 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 		return Object.keys(shape).filter((key) => !denySet.has(key));
 	}, [resolvedSchema, denyFields]);
 	const handleExport = react.useCallback(async (mode) => {
+		if (onExport) {
+			if (exportBusyRef.current || !exportTableRef.current) return;
+			exportBusyRef.current = true;
+			setExporting(true);
+			try {
+				const denied = new Set(denyFields);
+				const columns = getVisibleExportColumns(exportTableRef.current, denyFields);
+				const rows = mode === "selected" ? getSelectedRowsRef.current?.() : await resource.handlers.export?.();
+				if (!rows || mode === "selected" && rows.length === 0) return;
+				await onExport({
+					mode,
+					rows: denied.size ? rows.map((row) => Object.fromEntries(Object.entries(row).filter(([key]) => !denied.has(key)))) : rows,
+					columns
+				});
+			} finally {
+				exportBusyRef.current = false;
+				setExporting(false);
+			}
+			return;
+		}
 		const filename = title ?? "export";
 		const excludeColumns = denyFields;
 		if (mode === "selected") {
@@ -7807,18 +7861,30 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 		resource.handlers.export,
 		title,
 		denyFields,
-		resolvedFields
+		resolvedFields,
+		onExport
 	]);
 	const handleExportClick = react.useCallback(async () => {
 		const mode = selectedCount > 0 ? "selected" : "filtered";
+		if (onExport) return handleExport(mode);
 		setExporting(true);
 		try {
 			await handleExport(mode);
 		} finally {
 			setExporting(false);
 		}
-	}, [selectedCount, handleExport]);
+	}, [
+		selectedCount,
+		handleExport,
+		onExport
+	]);
 	const exportBatchActions = react.useMemo(() => {
+		if (onExport) return registryBatchActions.map((action$1) => action$1.type === "export" && action$1.onClick === void 0 && !action$1.component ? {
+			...action$1,
+			onClick: () => {
+				handleExport("selected").catch(reportExportError);
+			}
+		} : action$1);
 		if (!Object.values(resolvedFields).some((field) => field.format)) return registryBatchActions;
 		return registryBatchActions.map((action$1) => {
 			if (action$1.type !== "export" || action$1.onClick !== void 0 || Boolean(action$1.component)) return action$1;
@@ -7836,7 +7902,9 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 	}, [
 		registryBatchActions,
 		resolvedFields,
-		denyFields
+		denyFields,
+		onExport,
+		handleExport
 	]);
 	const toolbarRefresh = react.useMemo(() => {
 		const refresh = ownerRefreshAction?.onClick ?? resource.handlers.refresh;
@@ -8013,7 +8081,9 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 		if (type === "export" && canExport) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(__wordrhyme_shadcn.Button, {
 			variant: "outline",
 			size: "sm",
-			onClick: overrides?.onClick ?? toolbarExportData,
+			onClick: overrides?.onClick ?? (!ownerExportAction?.onClick ? () => {
+				toolbarExportData?.().catch(reportExportError);
+			} : toolbarExportData),
 			disabled: exporting || selectedCount === 0 && !resource.handlers.export,
 			children: [exporting ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Loader2, { className: "mr-2 h-4 w-4 animate-spin" }) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(lucide_react.Upload, { className: "mr-2 h-4 w-4" }), overrides?.label ?? (selectedCount > 0 ? locale.toolbar.exportSelected(selectedCount) : locale.toolbar.export)]
 		}, "export");
@@ -8092,7 +8162,8 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 				showDefaultExport: false,
 				initialSorting: defaultSort,
 				onSelectedRowsChange: handleSelectedRowsChange,
-				getSelectedRows: getSelectedRowsRef
+				getSelectedRows: getSelectedRowsRef,
+				...onExport ? { exportTableRef } : {}
 			}),
 			rowActionDialog,
 			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(CrudFormModal, {
@@ -8914,12 +8985,13 @@ function modalReducer(state, action$1) {
 */
 function useAutoCrudResource({ router, schema, query: queryTransform, fields, options = {} }) {
 	const { idKey = "id", defaultVariant = "dialog", hooks, toast: toastAdapter, exportFetcher, defaultSort: defaultSortOption } = options;
-	const toast = (0, react.useMemo)(() => toastAdapter === false ? noopToastAdapter : toastAdapter ?? defaultToastAdapter, [toastAdapter]);
+	const toast$1 = (0, react.useMemo)(() => toastAdapter === false ? noopToastAdapter : toastAdapter ?? defaultToastAdapter, [toastAdapter]);
 	const hooksRef = (0, react.useRef)(hooks);
 	(0, react.useEffect)(() => {
 		hooksRef.current = hooks;
 	}, [hooks]);
-	const metadata = (router.meta?.useQuery(void 0, { staleTime: 3e4 }))?.data;
+	const metadataQuery = router.meta?.useQuery(void 0, { staleTime: 3e4 });
+	const metadata = metadataQuery?.data;
 	const resolvedSchema = (0, react.useMemo)(() => mergeMetadataSchema(schema, metadata?.schema), [schema, metadata?.schema]);
 	const defaultSorting = (0, react.useMemo)(() => defaultSortOption === false ? [] : defaultSortOption ?? getDefaultSortingForSchema(resolvedSchema), [defaultSortOption, resolvedSchema]);
 	const metadataFields = (0, react.useMemo)(() => readMetadataFields(metadata?.fields), [metadata?.fields]);
@@ -8940,6 +9012,10 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 		search: parseAsString.withDefault("")
 	}, { shallow: false });
 	const [filters] = useReadableFilters(columns, { shallow: false });
+	const metadataPending = Boolean(metadataQuery?.isPending);
+	const [filtersReady, setFiltersReady] = (0, react.useState)(!metadataPending);
+	(0, react.useEffect)(() => setFiltersReady(!metadataPending), [metadataPending]);
+	const listReady = !metadataPending && filtersReady;
 	const queryInput = (0, react.useMemo)(() => {
 		const autoParams = {
 			page: urlParams.page,
@@ -8955,11 +9031,17 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 		filters,
 		queryTransform
 	]);
+	const hasReadyListData = (0, react.useRef)(false);
 	const listQuery = router.list.useQuery(queryInput, {
-		placeholderData: __tanstack_react_query.keepPreviousData,
+		enabled: listReady,
+		placeholderData: hasReadyListData.current ? __tanstack_react_query.keepPreviousData : void 0,
 		staleTime: 0
 	});
-	const tableRows = listQuery.data?.data ?? [];
+	(0, react.useEffect)(() => {
+		if (listReady && listQuery.data !== void 0) hasReadyListData.current = true;
+	}, [listReady, listQuery.data]);
+	const listData = listReady ? listQuery.data : void 0;
+	const tableRows = listData?.data ?? [];
 	const createMutation = router.create.useMutation();
 	const updateMutation = router.update.useMutation();
 	const deleteMutation = router.delete.useMutation();
@@ -9006,7 +9088,7 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 				const result = await currentHooks.beforeCreate(values);
 				if (typeof result === "boolean") {
 					if (result) {
-						toast.success("创建成功");
+						toast$1.success("创建成功");
 						closeModals();
 						listQuery.refetch();
 						currentHooks?.onSuccess?.("create", values);
@@ -9017,20 +9099,20 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 			}
 			createMutation.mutate(values, {
 				onSuccess: (data) => {
-					toast.success("创建成功");
+					toast$1.success("创建成功");
 					closeModals();
 					listQuery.refetch();
 					currentHooks?.onSuccess?.("create", data);
 				},
 				onError: (error) => {
 					const err = error;
-					toast.error(`创建失败: ${err.message}`);
+					toast$1.error(`创建失败: ${err.message}`);
 					currentHooks?.onError?.("create", err);
 				}
 			});
 		} catch (error) {
 			const err = error;
-			toast.error(`创建失败: ${err.message}`);
+			toast$1.error(`创建失败: ${err.message}`);
 			currentHooks?.onError?.("create", err);
 		}
 	}, [
@@ -9046,7 +9128,7 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 				const result = await currentHooks.beforeUpdate(values, modal.selected);
 				if (typeof result === "boolean") {
 					if (result) {
-						toast.success("更新成功");
+						toast$1.success("更新成功");
 						closeModals();
 						listQuery.refetch();
 						currentHooks?.onSuccess?.("update", values);
@@ -9061,20 +9143,20 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 				data: values
 			}, {
 				onSuccess: (data) => {
-					toast.success("更新成功");
+					toast$1.success("更新成功");
 					closeModals();
 					listQuery.refetch();
 					currentHooks?.onSuccess?.("update", data);
 				},
 				onError: (error) => {
 					const err = error;
-					toast.error(`更新失败: ${err.message}`);
+					toast$1.error(`更新失败: ${err.message}`);
 					currentHooks?.onError?.("update", err);
 				}
 			});
 		} catch (error) {
 			const err = error;
-			toast.error(`更新失败: ${err.message}`);
+			toast$1.error(`更新失败: ${err.message}`);
 			currentHooks?.onError?.("update", err);
 		}
 	}, [
@@ -9092,7 +9174,7 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 				const result = await currentHooks.beforeDelete(modal.selected);
 				if (typeof result === "boolean") {
 					if (result) {
-						toast.success("删除成功");
+						toast$1.success("删除成功");
 						closeModals();
 						listQuery.refetch();
 						currentHooks?.onSuccess?.("delete", modal.selected);
@@ -9103,20 +9185,20 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 			const id = modal.selected[idKey];
 			deleteMutation.mutate(id, {
 				onSuccess: (data) => {
-					toast.success("删除成功");
+					toast$1.success("删除成功");
 					closeModals();
 					listQuery.refetch();
 					currentHooks?.onSuccess?.("delete", data);
 				},
 				onError: (error) => {
 					const err = error;
-					toast.error(`删除失败: ${err.message}`);
+					toast$1.error(`删除失败: ${err.message}`);
 					currentHooks?.onError?.("delete", err);
 				}
 			});
 		} catch (error) {
 			const err = error;
-			toast.error(`删除失败: ${err.message}`);
+			toast$1.error(`删除失败: ${err.message}`);
 			currentHooks?.onError?.("delete", err);
 		}
 	}, [
@@ -9129,19 +9211,19 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 	const deleteMany = (0, react.useCallback)((rows) => {
 		const currentHooks = hooksRef.current;
 		if (!deleteManyMutation) {
-			toast.error("批量删除功能未启用");
+			toast$1.error("批量删除功能未启用");
 			return;
 		}
 		const ids = rows.map((row) => row[idKey]);
 		deleteManyMutation.mutate(ids, {
 			onSuccess: (data) => {
-				toast.success(`成功删除 ${ids.length} 条记录`);
+				toast$1.success(`成功删除 ${ids.length} 条记录`);
 				listQuery.refetch();
 				currentHooks?.onSuccess?.("delete", data);
 			},
 			onError: (error) => {
 				const err = error;
-				toast.error(`批量删除失败: ${err.message}`);
+				toast$1.error(`批量删除失败: ${err.message}`);
 				currentHooks?.onError?.("delete", err);
 			}
 		});
@@ -9153,7 +9235,7 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 	const updateMany = (0, react.useCallback)((rows, data) => {
 		const currentHooks = hooksRef.current;
 		if (!updateManyMutation) {
-			toast.error("批量更新功能未启用");
+			toast$1.error("批量更新功能未启用");
 			return;
 		}
 		const ids = rows.map((row) => row[idKey]);
@@ -9162,13 +9244,13 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 			data
 		}, {
 			onSuccess: (result) => {
-				toast.success(`成功更新 ${ids.length} 条记录`);
+				toast$1.success(`成功更新 ${ids.length} 条记录`);
 				listQuery.refetch();
 				currentHooks?.onSuccess?.("update", result);
 			},
 			onError: (error) => {
 				const err = error;
-				toast.error(`批量更新失败: ${err.message}`);
+				toast$1.error(`批量更新失败: ${err.message}`);
 				currentHooks?.onError?.("update", err);
 			}
 		});
@@ -9198,12 +9280,18 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 		schema
 	]);
 	const handleExport = (0, react.useCallback)(async () => {
+		let result;
 		if (exportFetcher) {
 			const { page: _p, perPage: _pp,...exportParams } = queryInput ?? {};
-			return (await exportFetcher(exportParams))?.data ?? [];
-		}
-		if (exportQuery) return (await exportQuery.refetch())?.data?.data ?? [];
-		throw new Error("Export not supported");
+			result = await exportFetcher(exportParams);
+		} else if (exportQuery) {
+			const response = await exportQuery.refetch();
+			if (response.error) throw response.error;
+			result = response.data;
+		} else throw new Error("Export not supported");
+		if (!result || !Array.isArray(result.data)) throw new Error("Export returned no data. Please retry.");
+		if (result.hasMore !== false || result.total > result.data.length) throw new Error("Export results are incomplete. Narrow your filters and retry.");
+		return result.data;
 	}, [
 		exportFetcher,
 		exportQuery,
@@ -9211,16 +9299,17 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 	]);
 	const canExport = !!(exportFetcher || exportQuery);
 	const refresh = (0, react.useCallback)(async () => {
+		if (!listReady) return;
 		return listQuery.refetch();
-	}, [listQuery]);
+	}, [listQuery, listReady]);
 	return {
 		idKey,
 		tableData: {
 			data: tableRows,
-			pageCount: listQuery.data?.pageCount ?? 0,
-			...typeof listQuery.data?.total === "number" ? { total: listQuery.data.total } : {},
-			isLoading: listQuery.isLoading,
-			isFetching: listQuery.isFetching
+			pageCount: listData?.pageCount ?? 0,
+			...typeof listData?.total === "number" ? { total: listData.total } : {},
+			isLoading: !listReady || listQuery.isLoading,
+			isFetching: !listReady || listQuery.isFetching
 		},
 		schema: resolvedSchema,
 		fields: metadataFields,
@@ -9557,6 +9646,72 @@ function createMemoryDataSource(initialData = []) {
 	};
 }
 
+//#endregion
+//#region src/lib/workbook.ts
+const MAX_ROWS = 1048576;
+const MAX_COLUMNS = 16384;
+const MAX_CELL_LENGTH = 32767;
+const MAX_LINE_FEEDS = 253;
+function validateCell(value) {
+	if (typeof value === "string") {
+		if (value.length > MAX_CELL_LENGTH) throw new RangeError(`Excel cells cannot exceed ${MAX_CELL_LENGTH} characters.`);
+		if ((value.match(/\n/g)?.length ?? 0) > MAX_LINE_FEEDS) throw new RangeError(`Excel cells cannot exceed ${MAX_LINE_FEEDS} line feeds.`);
+	} else if (value != null && (typeof value !== "number" || !Number.isFinite(value))) throw new TypeError("Workbook cells must contain text, finite numbers, or null.");
+}
+function validateSheets(sheets) {
+	if (sheets.length === 0) throw new Error("A workbook needs at least one sheet.");
+	const names = /* @__PURE__ */ new Set();
+	for (const sheet of sheets) {
+		if (!sheet.name || sheet.name.length > 31 || /[*?:\\/\[\]]/.test(sheet.name) || sheet.name.startsWith("'") || sheet.name.endsWith("'")) throw new Error("Worksheet names must be valid Excel names of 1–31 characters.");
+		const name = sheet.name.toLowerCase();
+		if (names.has(name)) throw new Error("Worksheet names must be unique.");
+		names.add(name);
+		if (sheet.rows.length + 1 > MAX_ROWS) throw new RangeError(`Excel worksheets cannot exceed ${MAX_ROWS} rows including headers.`);
+		if (sheet.headers.length > MAX_COLUMNS) throw new RangeError(`Excel worksheets cannot exceed ${MAX_COLUMNS} columns.`);
+		sheet.headers.forEach(validateCell);
+		for (const row of sheet.rows) {
+			if (row.length > MAX_COLUMNS) throw new RangeError(`Excel worksheets cannot exceed ${MAX_COLUMNS} columns.`);
+			row.forEach(validateCell);
+		}
+	}
+}
+/** Internal byte builder, exported from this module for real workbook roundtrip tests. */
+async function buildWorkbookBytes(sheets) {
+	validateSheets(sheets);
+	const { default: ExcelJS } = await import("exceljs");
+	const workbook = new ExcelJS.Workbook();
+	for (const sheet of sheets) {
+		const worksheet = workbook.addWorksheet(sheet.name);
+		const append = (values) => {
+			worksheet.addRow(values.map((value) => value ?? null)).eachCell((cell, column) => {
+				const numberFormat = sheet.numberFormats?.[column - 1];
+				if (typeof cell.value === "number" && numberFormat !== void 0) cell.numFmt = numberFormat;
+				if (typeof cell.value === "string" && /[\r\n]/.test(cell.value)) cell.alignment = { wrapText: true };
+			});
+		};
+		append(sheet.headers);
+		sheet.rows.forEach(append);
+	}
+	return new Uint8Array(await workbook.xlsx.writeBuffer()).buffer;
+}
+/** Download a real XLSX workbook. Errors reject; no CSV or raw-value fallback. */
+async function exportWorkbook(sheets, { filename }) {
+	const bytes = await buildWorkbookBytes(sheets);
+	const blob = new Blob([bytes], { type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" });
+	const url = URL.createObjectURL(blob);
+	const link = document.createElement("a");
+	try {
+		link.href = url;
+		link.download = /\.xlsx$/i.test(filename) ? filename : `${filename}.xlsx`;
+		link.hidden = true;
+		document.body.appendChild(link);
+		link.click();
+	} finally {
+		link.remove();
+		setTimeout(() => URL.revokeObjectURL(url), 0);
+	}
+}
+
 //#endregion
 exports.AutoCrudTable = AutoCrudTable;
 exports.AutoForm = AutoForm;
@@ -9607,6 +9762,7 @@ exports.enUS = enUS;
 exports.esES = esES;
 exports.exportAllToCSV = exportAllToCSV;
 exports.exportTableToCSV = exportTableToCSV;
+exports.exportWorkbook = exportWorkbook;
 exports.formComponents = formComponents;
 exports.formatDate = formatDate;
 exports.frFR = frFR;

package/dist/index.d.cts

@@ -276,6 +276,8 @@ declare module '@tanstack/react-table' {
   interface ColumnMeta<TData extends RowData, TValue> {
     label?: string;
     index?: number;
+    /** @internal Identifies the generated row expansion control, regardless of its id. */
+    autoCrudExpandColumn?: boolean;
     /** 按元素分组的列类名，优先于全局单元格类名 */
     classNames?: Pick<DataTableClassNames, 'th' | 'td'>;
     placeholder?: string;
@@ -1059,6 +1061,8 @@ interface AutoTableProps<T extends z.ZodObject<z.ZodRawShape>> extends Pick<Data
   onSelectedCountChange?: (count: number) => void;
   /** 选中行数据变化回调（用于外层组件获知选中行身份变化） */
   onSelectedRowsChange?: (rows: z.infer<T>[]) => void;
+  /** @internal Supplies the current table for opt-in export snapshots. */
+  exportTableRef?: React.MutableRefObject<Table<z.infer<T>> | null>;
   /** 获取选中行数据的回调（由外层组件调用） */
   getSelectedRows?: React.MutableRefObject<(() => z.infer<T>[]) | null>;
 }
@@ -1093,7 +1097,8 @@ declare function AutoTable<T extends z.ZodObject<z.ZodRawShape>>({
   showDefaultExport,
   onSelectedCountChange,
   onSelectedRowsChange,
-  getSelectedRows
+  getSelectedRows,
+  exportTableRef
 }: AutoTableProps<T>): react_jsx_runtime9.JSX.Element;
 //#endregion
 //#region src/lib/row-action-dialog.d.ts
@@ -1405,9 +1410,15 @@ interface AutoCrudToolbarContext {
 }
 type AutoCrudToolbarResolver = (targetId: string, ownerActions: readonly ToolbarActionItem[], context: AutoCrudToolbarContext) => ToolbarActionItem[];
 declare function setToolbarResolver(resolver: AutoCrudToolbarResolver | null): void;
-/**
- * AutoCrudTable Props 接口
- */
+/** Unformatted rows without denied fields, and visible localized business columns. */
+interface AutoCrudExportContext {
+  mode: 'selected' | 'filtered';
+  rows: Record<string, unknown>[];
+  columns: Array<{
+    id: string;
+    label: string;
+  }>;
+}
 interface AutoCrudTableProps<TSchema extends z.ZodObject<z.ZodRawShape>> {
   /** Public CRUD id. Used by hosts to document the extension target. */
   id?: string;
@@ -1526,6 +1537,8 @@ interface AutoCrudTableProps<TSchema extends z.ZodObject<z.ZodRawShape>> {
    * 如果提供，将覆盖默认的打开新建弹窗行为
    */
   onCreate?: () => void;
+  /** Owns export delivery when supplied. Rejections propagate without CSV fallback. */
+  onExport?: (context: AutoCrudExportContext) => Promise<void>;
 }
 /**
  * AutoCrudTable 组件
@@ -1547,7 +1560,8 @@ declare function AutoCrudTable<TSchema extends z.ZodObject<z.ZodRawShape>>({
   toolbar,
   toolbarActions,
   locale: localeProp,
-  onCreate
+  onCreate,
+  onExport
 }: AutoCrudTableProps<TSchema>): react_jsx_runtime9.JSX.Element;
 //#endregion
 //#region src/components/auto-crud/auto-form.d.ts
@@ -2163,4 +2177,19 @@ declare function exportAllToCSV<T extends Record<string, unknown>>(data: T[], op
  */
 declare function downloadCSVTemplate(headers: string[], filename?: string): void;
 //#endregion
-export { type ActionConfig, type ActionItem, type ActionPosition, type ActionsColumnConfig, type AutoCrudActionConfig, type AutoCrudActionsConfig, type AutoCrudDataSourceConfig, type AutoCrudDataSourceContext, type AutoCrudDataSourceEntry, type AutoCrudDataSourceLoader, type AutoCrudDataSourceRegistration, type AutoCrudFormComponentConfig, type AutoCrudLocale, type AutoCrudOption, type AutoCrudQueryCapabilities, type AutoCrudRowActionContext, type AutoCrudRowOpenOptions, AutoCrudTable, type AutoCrudTableProps, type AutoCrudToolbarContext, type AutoCrudToolbarResolver, AutoForm, type AutoFormProps, type AutoQueryParams, AutoTable, AutoTableActionBar, type AutoTableProps, AutoTableSimpleFilters, type BatchActionConfig, type BatchActionContext, type BatchActionItem, type BatchBuiltinActionItem, type BatchBuiltinActionType, type BatchCustomActionItem, type BatchUpdateField, type ColumnOverrides, type CreateFormSchemaOptions, type CreateTableSchemaOptions, type CrudActionBase, type CrudActionEntry, type CrudActionRegistration, type CrudActionZone, CrudFormModal, type CrudHooks, type CrudOperationPermissions, type CrudPermissions, type DataSource, DataTable, DataTableAdvancedToolbar, DataTableClassNames, DataTableColumnHeader, DataTableFacetedFilter, DataTablePagination, type DataTableProps, DataTableRowAction, DataTableToolbar, DataTableViewOptions, type DataTableViewOptionsProps, type DateFormatPreset, type DateFormatter, type DateLocaleOptions, type EnumOption, ExportDialog, type ExportDialogProps, type ExportMode, ExtendedColumnFilter, ExtendedColumnSort, type Field, type FieldOption, type FieldTableDisplay, type FieldType, type Fields, type FilterConfig, FilterOperator, type FilterVariant, type FormSchemaOverrides, ImportDialog, type ImportDialogProps, type ImportResult, type JSONSchema, type JSONSchemaProperty, JoinOperator, type ListParams, type ListResult, type LocaleProp, MultiCombobox, type MultiComboboxOption, type MultiComboboxProps, type MultiComboboxTriggerRenderProps, Option, type ParsedImportData, type ParsedZodField, type Parser, QueryKeys, type RowActionConfig, type RowActionDialogProps, type RowActionItem, type RowBuiltinActionItem, type RowBuiltinActionType, type RowCustomActionItem, SchemaAdapter, Select, type SelectMode, type SelectOption, type SelectProps, type SelectSearchableDynamicProps, type SelectSearchableMultipleProps, type SelectSearchableProps, type SelectSearchableSingleProps, type SelectSimpleProps, type SelectTriggerRenderProps, type SimpleFieldConfig, type SimpleFieldsConfig, type TableControlsLocale, type TablePaginationOptions, type ToastAdapter, type ToolbarActionConfig, type ToolbarActionItem, type ToolbarBuiltinActionItem, type ToolbarBuiltinActionType, type ToolbarCustomActionItem, type UnifiedField, type UnifiedSchema, type UrlStateOptions, type UseAutoCrudResourceOptions, type UseAutoCrudResourceParams, type UseAutoCrudResourceReturn, actionPositionSchema, cn, coerceRowValues, compareOrder, components, createActionsColumn, createEditFormSchema, createFormSchema, createMemoryDataSource, createSelectColumn, createTRPCDataSource, createTableSchema, crudActions, dataSources, dataToCSV, deDE, downloadCSVTemplate, enUS, esES, exportAllToCSV, exportTableToCSV, formComponents, formatDate, frFR, generateCSVTemplate, getUrlParams, humanize, jaJP, koKR, matchesPosition, noopToastAdapter, normalizeDataSourceConfig, normalizeOptions, parseAsArrayOf, parseAsInteger, parseAsString, parseAsStringEnum, parseCSV, parseImportFile, parseJSON, parseZodField, positionActions, resolveLocale, setDateFormatter, setSearchParams, setToolbarResolver, tablePagination, useAutoCrudResource, useDataTable, useQueryState, useQueryStates, useReadableFilters, useUrlState, useUrlStates, zhCN };
+//#region src/lib/workbook.d.ts
+interface WorkbookSheet {
+  name: string;
+  headers: string[];
+  /** Excel formats by header index; applied only to numeric cells. */
+  numberFormats?: (string | undefined)[];
+  rows: (string | number | null | undefined)[][];
+}
+/** Download a real XLSX workbook. Errors reject; no CSV or raw-value fallback. */
+declare function exportWorkbook(sheets: WorkbookSheet[], {
+  filename
+}: {
+  filename: string;
+}): Promise<void>;
+//#endregion
+export { type ActionConfig, type ActionItem, type ActionPosition, type ActionsColumnConfig, type AutoCrudActionConfig, type AutoCrudActionsConfig, type AutoCrudDataSourceConfig, type AutoCrudDataSourceContext, type AutoCrudDataSourceEntry, type AutoCrudDataSourceLoader, type AutoCrudDataSourceRegistration, type AutoCrudExportContext, type AutoCrudFormComponentConfig, type AutoCrudLocale, type AutoCrudOption, type AutoCrudQueryCapabilities, type AutoCrudRowActionContext, type AutoCrudRowOpenOptions, AutoCrudTable, type AutoCrudTableProps, type AutoCrudToolbarContext, type AutoCrudToolbarResolver, AutoForm, type AutoFormProps, type AutoQueryParams, AutoTable, AutoTableActionBar, type AutoTableProps, AutoTableSimpleFilters, type BatchActionConfig, type BatchActionContext, type BatchActionItem, type BatchBuiltinActionItem, type BatchBuiltinActionType, type BatchCustomActionItem, type BatchUpdateField, type ColumnOverrides, type CreateFormSchemaOptions, type CreateTableSchemaOptions, type CrudActionBase, type CrudActionEntry, type CrudActionRegistration, type CrudActionZone, CrudFormModal, type CrudHooks, type CrudOperationPermissions, type CrudPermissions, type DataSource, DataTable, DataTableAdvancedToolbar, DataTableClassNames, DataTableColumnHeader, DataTableFacetedFilter, DataTablePagination, type DataTableProps, DataTableRowAction, DataTableToolbar, DataTableViewOptions, type DataTableViewOptionsProps, type DateFormatPreset, type DateFormatter, type DateLocaleOptions, type EnumOption, ExportDialog, type ExportDialogProps, type ExportMode, ExtendedColumnFilter, ExtendedColumnSort, type Field, type FieldOption, type FieldTableDisplay, type FieldType, type Fields, type FilterConfig, FilterOperator, type FilterVariant, type FormSchemaOverrides, ImportDialog, type ImportDialogProps, type ImportResult, type JSONSchema, type JSONSchemaProperty, JoinOperator, type ListParams, type ListResult, type LocaleProp, MultiCombobox, type MultiComboboxOption, type MultiComboboxProps, type MultiComboboxTriggerRenderProps, Option, type ParsedImportData, type ParsedZodField, type Parser, QueryKeys, type RowActionConfig, type RowActionDialogProps, type RowActionItem, type RowBuiltinActionItem, type RowBuiltinActionType, type RowCustomActionItem, SchemaAdapter, Select, type SelectMode, type SelectOption, type SelectProps, type SelectSearchableDynamicProps, type SelectSearchableMultipleProps, type SelectSearchableProps, type SelectSearchableSingleProps, type SelectSimpleProps, type SelectTriggerRenderProps, type SimpleFieldConfig, type SimpleFieldsConfig, type TableControlsLocale, type TablePaginationOptions, type ToastAdapter, type ToolbarActionConfig, type ToolbarActionItem, type ToolbarBuiltinActionItem, type ToolbarBuiltinActionType, type ToolbarCustomActionItem, type UnifiedField, type UnifiedSchema, type UrlStateOptions, type UseAutoCrudResourceOptions, type UseAutoCrudResourceParams, type UseAutoCrudResourceReturn, type WorkbookSheet, actionPositionSchema, cn, coerceRowValues, compareOrder, components, createActionsColumn, createEditFormSchema, createFormSchema, createMemoryDataSource, createSelectColumn, createTRPCDataSource, createTableSchema, crudActions, dataSources, dataToCSV, deDE, downloadCSVTemplate, enUS, esES, exportAllToCSV, exportTableToCSV, exportWorkbook, formComponents, formatDate, frFR, generateCSVTemplate, getUrlParams, humanize, jaJP, koKR, matchesPosition, noopToastAdapter, normalizeDataSourceConfig, normalizeOptions, parseAsArrayOf, parseAsInteger, parseAsString, parseAsStringEnum, parseCSV, parseImportFile, parseJSON, parseZodField, positionActions, resolveLocale, setDateFormatter, setSearchParams, setToolbarResolver, tablePagination, useAutoCrudResource, useDataTable, useQueryState, useQueryStates, useReadableFilters, useUrlState, useUrlStates, zhCN };

package/dist/index.d.ts

@@ -276,6 +276,8 @@ declare module '@tanstack/react-table' {
   interface ColumnMeta<TData extends RowData, TValue> {
     label?: string;
     index?: number;
+    /** @internal Identifies the generated row expansion control, regardless of its id. */
+    autoCrudExpandColumn?: boolean;
     /** 按元素分组的列类名，优先于全局单元格类名 */
     classNames?: Pick<DataTableClassNames, 'th' | 'td'>;
     placeholder?: string;
@@ -1059,6 +1061,8 @@ interface AutoTableProps<T extends z.ZodObject<z.ZodRawShape>> extends Pick<Data
   onSelectedCountChange?: (count: number) => void;
   /** 选中行数据变化回调（用于外层组件获知选中行身份变化） */
   onSelectedRowsChange?: (rows: z.infer<T>[]) => void;
+  /** @internal Supplies the current table for opt-in export snapshots. */
+  exportTableRef?: React.MutableRefObject<Table<z.infer<T>> | null>;
   /** 获取选中行数据的回调（由外层组件调用） */
   getSelectedRows?: React.MutableRefObject<(() => z.infer<T>[]) | null>;
 }
@@ -1093,7 +1097,8 @@ declare function AutoTable<T extends z.ZodObject<z.ZodRawShape>>({
   showDefaultExport,
   onSelectedCountChange,
   onSelectedRowsChange,
-  getSelectedRows
+  getSelectedRows,
+  exportTableRef
 }: AutoTableProps<T>): react_jsx_runtime8.JSX.Element;
 //#endregion
 //#region src/lib/row-action-dialog.d.ts
@@ -1405,9 +1410,15 @@ interface AutoCrudToolbarContext {
 }
 type AutoCrudToolbarResolver = (targetId: string, ownerActions: readonly ToolbarActionItem[], context: AutoCrudToolbarContext) => ToolbarActionItem[];
 declare function setToolbarResolver(resolver: AutoCrudToolbarResolver | null): void;
-/**
- * AutoCrudTable Props 接口
- */
+/** Unformatted rows without denied fields, and visible localized business columns. */
+interface AutoCrudExportContext {
+  mode: 'selected' | 'filtered';
+  rows: Record<string, unknown>[];
+  columns: Array<{
+    id: string;
+    label: string;
+  }>;
+}
 interface AutoCrudTableProps<TSchema extends z.ZodObject<z.ZodRawShape>> {
   /** Public CRUD id. Used by hosts to document the extension target. */
   id?: string;
@@ -1526,6 +1537,8 @@ interface AutoCrudTableProps<TSchema extends z.ZodObject<z.ZodRawShape>> {
    * 如果提供，将覆盖默认的打开新建弹窗行为
    */
   onCreate?: () => void;
+  /** Owns export delivery when supplied. Rejections propagate without CSV fallback. */
+  onExport?: (context: AutoCrudExportContext) => Promise<void>;
 }
 /**
  * AutoCrudTable 组件
@@ -1547,7 +1560,8 @@ declare function AutoCrudTable<TSchema extends z.ZodObject<z.ZodRawShape>>({
   toolbar,
   toolbarActions,
   locale: localeProp,
-  onCreate
+  onCreate,
+  onExport
 }: AutoCrudTableProps<TSchema>): react_jsx_runtime8.JSX.Element;
 //#endregion
 //#region src/components/auto-crud/auto-form.d.ts
@@ -2163,4 +2177,19 @@ declare function exportAllToCSV<T extends Record<string, unknown>>(data: T[], op
  */
 declare function downloadCSVTemplate(headers: string[], filename?: string): void;
 //#endregion
-export { type ActionConfig, type ActionItem, type ActionPosition, type ActionsColumnConfig, type AutoCrudActionConfig, type AutoCrudActionsConfig, type AutoCrudDataSourceConfig, type AutoCrudDataSourceContext, type AutoCrudDataSourceEntry, type AutoCrudDataSourceLoader, type AutoCrudDataSourceRegistration, type AutoCrudFormComponentConfig, type AutoCrudLocale, type AutoCrudOption, type AutoCrudQueryCapabilities, type AutoCrudRowActionContext, type AutoCrudRowOpenOptions, AutoCrudTable, type AutoCrudTableProps, type AutoCrudToolbarContext, type AutoCrudToolbarResolver, AutoForm, type AutoFormProps, type AutoQueryParams, AutoTable, AutoTableActionBar, type AutoTableProps, AutoTableSimpleFilters, type BatchActionConfig, type BatchActionContext, type BatchActionItem, type BatchBuiltinActionItem, type BatchBuiltinActionType, type BatchCustomActionItem, type BatchUpdateField, type ColumnOverrides, type CreateFormSchemaOptions, type CreateTableSchemaOptions, type CrudActionBase, type CrudActionEntry, type CrudActionRegistration, type CrudActionZone, CrudFormModal, type CrudHooks, type CrudOperationPermissions, type CrudPermissions, type DataSource, DataTable, DataTableAdvancedToolbar, DataTableClassNames, DataTableColumnHeader, DataTableFacetedFilter, DataTablePagination, type DataTableProps, DataTableRowAction, DataTableToolbar, DataTableViewOptions, type DataTableViewOptionsProps, type DateFormatPreset, type DateFormatter, type DateLocaleOptions, type EnumOption, ExportDialog, type ExportDialogProps, type ExportMode, ExtendedColumnFilter, ExtendedColumnSort, type Field, type FieldOption, type FieldTableDisplay, type FieldType, type Fields, type FilterConfig, FilterOperator, type FilterVariant, type FormSchemaOverrides, ImportDialog, type ImportDialogProps, type ImportResult, type JSONSchema, type JSONSchemaProperty, JoinOperator, type ListParams, type ListResult, type LocaleProp, MultiCombobox, type MultiComboboxOption, type MultiComboboxProps, type MultiComboboxTriggerRenderProps, Option, type ParsedImportData, type ParsedZodField, type Parser, QueryKeys, type RowActionConfig, type RowActionDialogProps, type RowActionItem, type RowBuiltinActionItem, type RowBuiltinActionType, type RowCustomActionItem, SchemaAdapter, Select, type SelectMode, type SelectOption, type SelectProps, type SelectSearchableDynamicProps, type SelectSearchableMultipleProps, type SelectSearchableProps, type SelectSearchableSingleProps, type SelectSimpleProps, type SelectTriggerRenderProps, type SimpleFieldConfig, type SimpleFieldsConfig, type TableControlsLocale, type TablePaginationOptions, type ToastAdapter, type ToolbarActionConfig, type ToolbarActionItem, type ToolbarBuiltinActionItem, type ToolbarBuiltinActionType, type ToolbarCustomActionItem, type UnifiedField, type UnifiedSchema, type UrlStateOptions, type UseAutoCrudResourceOptions, type UseAutoCrudResourceParams, type UseAutoCrudResourceReturn, actionPositionSchema, cn, coerceRowValues, compareOrder, components, createActionsColumn, createEditFormSchema, createFormSchema, createMemoryDataSource, createSelectColumn, createTRPCDataSource, createTableSchema, crudActions, dataSources, dataToCSV, deDE, downloadCSVTemplate, enUS, esES, exportAllToCSV, exportTableToCSV, formComponents, formatDate, frFR, generateCSVTemplate, getUrlParams, humanize, jaJP, koKR, matchesPosition, noopToastAdapter, normalizeDataSourceConfig, normalizeOptions, parseAsArrayOf, parseAsInteger, parseAsString, parseAsStringEnum, parseCSV, parseImportFile, parseJSON, parseZodField, positionActions, resolveLocale, setDateFormatter, setSearchParams, setToolbarResolver, tablePagination, useAutoCrudResource, useDataTable, useQueryState, useQueryStates, useReadableFilters, useUrlState, useUrlStates, zhCN };
+//#region src/lib/workbook.d.ts
+interface WorkbookSheet {
+  name: string;
+  headers: string[];
+  /** Excel formats by header index; applied only to numeric cells. */
+  numberFormats?: (string | undefined)[];
+  rows: (string | number | null | undefined)[][];
+}
+/** Download a real XLSX workbook. Errors reject; no CSV or raw-value fallback. */
+declare function exportWorkbook(sheets: WorkbookSheet[], {
+  filename
+}: {
+  filename: string;
+}): Promise<void>;
+//#endregion
+export { type ActionConfig, type ActionItem, type ActionPosition, type ActionsColumnConfig, type AutoCrudActionConfig, type AutoCrudActionsConfig, type AutoCrudDataSourceConfig, type AutoCrudDataSourceContext, type AutoCrudDataSourceEntry, type AutoCrudDataSourceLoader, type AutoCrudDataSourceRegistration, type AutoCrudExportContext, type AutoCrudFormComponentConfig, type AutoCrudLocale, type AutoCrudOption, type AutoCrudQueryCapabilities, type AutoCrudRowActionContext, type AutoCrudRowOpenOptions, AutoCrudTable, type AutoCrudTableProps, type AutoCrudToolbarContext, type AutoCrudToolbarResolver, AutoForm, type AutoFormProps, type AutoQueryParams, AutoTable, AutoTableActionBar, type AutoTableProps, AutoTableSimpleFilters, type BatchActionConfig, type BatchActionContext, type BatchActionItem, type BatchBuiltinActionItem, type BatchBuiltinActionType, type BatchCustomActionItem, type BatchUpdateField, type ColumnOverrides, type CreateFormSchemaOptions, type CreateTableSchemaOptions, type CrudActionBase, type CrudActionEntry, type CrudActionRegistration, type CrudActionZone, CrudFormModal, type CrudHooks, type CrudOperationPermissions, type CrudPermissions, type DataSource, DataTable, DataTableAdvancedToolbar, DataTableClassNames, DataTableColumnHeader, DataTableFacetedFilter, DataTablePagination, type DataTableProps, DataTableRowAction, DataTableToolbar, DataTableViewOptions, type DataTableViewOptionsProps, type DateFormatPreset, type DateFormatter, type DateLocaleOptions, type EnumOption, ExportDialog, type ExportDialogProps, type ExportMode, ExtendedColumnFilter, ExtendedColumnSort, type Field, type FieldOption, type FieldTableDisplay, type FieldType, type Fields, type FilterConfig, FilterOperator, type FilterVariant, type FormSchemaOverrides, ImportDialog, type ImportDialogProps, type ImportResult, type JSONSchema, type JSONSchemaProperty, JoinOperator, type ListParams, type ListResult, type LocaleProp, MultiCombobox, type MultiComboboxOption, type MultiComboboxProps, type MultiComboboxTriggerRenderProps, Option, type ParsedImportData, type ParsedZodField, type Parser, QueryKeys, type RowActionConfig, type RowActionDialogProps, type RowActionItem, type RowBuiltinActionItem, type RowBuiltinActionType, type RowCustomActionItem, SchemaAdapter, Select, type SelectMode, type SelectOption, type SelectProps, type SelectSearchableDynamicProps, type SelectSearchableMultipleProps, type SelectSearchableProps, type SelectSearchableSingleProps, type SelectSimpleProps, type SelectTriggerRenderProps, type SimpleFieldConfig, type SimpleFieldsConfig, type TableControlsLocale, type TablePaginationOptions, type ToastAdapter, type ToolbarActionConfig, type ToolbarActionItem, type ToolbarBuiltinActionItem, type ToolbarBuiltinActionType, type ToolbarCustomActionItem, type UnifiedField, type UnifiedSchema, type UrlStateOptions, type UseAutoCrudResourceOptions, type UseAutoCrudResourceParams, type UseAutoCrudResourceReturn, type WorkbookSheet, actionPositionSchema, cn, coerceRowValues, compareOrder, components, createActionsColumn, createEditFormSchema, createFormSchema, createMemoryDataSource, createSelectColumn, createTRPCDataSource, createTableSchema, crudActions, dataSources, dataToCSV, deDE, downloadCSVTemplate, enUS, esES, exportAllToCSV, exportTableToCSV, exportWorkbook, formComponents, formatDate, frFR, generateCSVTemplate, getUrlParams, humanize, jaJP, koKR, matchesPosition, noopToastAdapter, normalizeDataSourceConfig, normalizeOptions, parseAsArrayOf, parseAsInteger, parseAsString, parseAsStringEnum, parseCSV, parseImportFile, parseJSON, parseZodField, positionActions, resolveLocale, setDateFormatter, setSearchParams, setToolbarResolver, tablePagination, useAutoCrudResource, useDataTable, useQueryState, useQueryStates, useReadableFilters, useUrlState, useUrlStates, zhCN };

package/dist/index.js

@@ -4626,6 +4626,27 @@ function coerceRowValues(rows, schema) {
 
 //#endregion
 //#region src/lib/export.ts
+/** Snapshot rendered business columns without changing the legacy CSV column policy. */
+function getVisibleExportColumns(table, deny = []) {
+	const excluded = new Set([
+		"select",
+		"actions",
+		...deny
+	]);
+	return [
+		...table.getLeftVisibleLeafColumns(),
+		...table.getCenterVisibleLeafColumns(),
+		...table.getRightVisibleLeafColumns()
+	].filter((column) => {
+		if (excluded.has(column.id)) return false;
+		const meta = column.columnDef.meta;
+		if (meta?.autoCrudExpandColumn) return false;
+		return ![meta?.classNames?.th, meta?.classNames?.td].some((value) => typeof value === "string" && /(?:^|\s)!?hidden!?(?:\s|$)/.test(value));
+	}).map((column) => ({
+		id: column.id,
+		label: column.columnDef.meta?.label ?? (typeof column.columnDef.header === "string" ? column.columnDef.header : column.id)
+	}));
+}
 function getExportColumnIds(table) {
 	return table.getAllLeafColumns().filter((column) => column.accessorFn).map((column) => column.id);
 }
@@ -5142,7 +5163,7 @@ const filterModeConfig = {
 		tooltip: "Linear-style command filters"
 	}
 };
-function AutoTable({ schema, data, getRowId, expandedRow, defaultExpanded = false, pageCount = 1, pagination, total, overrides, classNames, enableRowSelection = true, exclude, filterOnly, actions, pinnedColumns, filterMode, search = false, toolbarExtra, locale = enUSTableControls, onDeleteSelected, onUpdateSelected, batchUpdateFields, actionBarExtra, actionBarActions, deleteConfirmation, initialSorting, enableExport = true, showDefaultExport = true, onSelectedCountChange, onSelectedRowsChange, getSelectedRows }) {
+function AutoTable({ schema, data, getRowId, expandedRow, defaultExpanded = false, pageCount = 1, pagination, total, overrides, classNames, enableRowSelection = true, exclude, filterOnly, actions, pinnedColumns, filterMode, search = false, toolbarExtra, locale = enUSTableControls, onDeleteSelected, onUpdateSelected, batchUpdateFields, actionBarExtra, actionBarActions, deleteConfirmation, initialSorting, enableExport = true, showDefaultExport = true, onSelectedCountChange, onSelectedRowsChange, getSelectedRows, exportTableRef }) {
 	if (expandedRow && !getRowId) throw new Error("AutoTable requires getRowId when expandedRow is provided.");
 	const enableExpansion = !!expandedRow;
 	const modes = filterMode ? Array.isArray(filterMode) ? filterMode : [filterMode] : DEFAULT_MODES;
@@ -5184,6 +5205,7 @@ function AutoTable({ schema, data, getRowId, expandedRow, defaultExpanded = fals
 			while (expandColumnId$1 in schema.shape || result.some((column) => column.id === expandColumnId$1)) expandColumnId$1 = `_${expandColumnId$1}`;
 			result.unshift({
 				id: expandColumnId$1,
+				meta: { autoCrudExpandColumn: true },
 				header: () => /* @__PURE__ */ jsx("span", {
 					className: "sr-only",
 					children: "Row details"
@@ -5257,6 +5279,13 @@ function AutoTable({ schema, data, getRowId, expandedRow, defaultExpanded = fals
 			};
 		});
 	}, [table, filterOnly]);
+	useEffect(() => {
+		if (!exportTableRef) return;
+		exportTableRef.current = table;
+		return () => {
+			exportTableRef.current = null;
+		};
+	}, [table, exportTableRef]);
 	const rowSelection = table.getState().rowSelection;
 	const columnFilters = table.getState().columnFilters;
 	const selectedRows = useMemo(() => table.getFilteredSelectedRowModel().rows.map((row) => row.original), [
@@ -6815,6 +6844,9 @@ function resolveToolbarActionsWithResolver(targetId, ownerActions, context) {
 	const resolver = autoCrudToolbarResolver;
 	return targetId !== void 0 && targetId.length > 0 && resolver !== null ? resolver(targetId, ownerActions, context) : ownerActions;
 }
+function reportExportError(error) {
+	toast.error(error instanceof Error ? error.message : String(error));
+}
 function applyResourceTablePresentation(fields, resourceFields) {
 	if (!fields || !resourceFields) return fields;
 	return Object.fromEntries(Object.entries(fields).map(([key, config]) => {
@@ -7694,7 +7726,7 @@ function resolveActions(actions, defaults, rowActionsLocale, context) {
 *
 * 高级 CRUD 表格组件，封装了完整的增删改查流程
 */
-function AutoCrudTable({ id, title, description, schema, resource, fields, table: tableConfig, form: formConfig, view: viewConfig, permissions, actions: actionItems, toolbar, toolbarActions, locale: localeProp, onCreate }) {
+function AutoCrudTable({ id, title, description, schema, resource, fields, table: tableConfig, form: formConfig, view: viewConfig, permissions, actions: actionItems, toolbar, toolbarActions, locale: localeProp, onCreate, onExport }) {
 	const locale = resolveLocale(localeProp);
 	const getPagination = React.useCallback(() => id ? tablePagination.get(id) : void 0, [id]);
 	const registeredPagination = React.useSyncExternalStore(tablePagination.subscribe, getPagination, getPagination);
@@ -7714,6 +7746,8 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 	const [importOpen, setImportOpen] = React.useState(false);
 	const [selectedRows, setSelectedRows] = React.useState([]);
 	const [exporting, setExporting] = React.useState(false);
+	const exportBusyRef = React.useRef(false);
+	const exportTableRef = React.useRef(null);
 	const getSelectedRowsRef = React.useRef(null);
 	const dynamicFilterOptions = useDynamicFilterOptions(resolvedFields);
 	const filterOnly = React.useMemo(() => Object.entries(resolvedFields).filter(([key, config]) => config.table === false && config.filter && config.hidden !== true && !denyFields?.includes(key) && !tableConfig?.hidden?.includes(key) && tableConfig?.overrides?.[key]?.hidden !== true).map(([key]) => key), [
@@ -7772,6 +7806,26 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 		return Object.keys(shape).filter((key) => !denySet.has(key));
 	}, [resolvedSchema, denyFields]);
 	const handleExport = React.useCallback(async (mode) => {
+		if (onExport) {
+			if (exportBusyRef.current || !exportTableRef.current) return;
+			exportBusyRef.current = true;
+			setExporting(true);
+			try {
+				const denied = new Set(denyFields);
+				const columns = getVisibleExportColumns(exportTableRef.current, denyFields);
+				const rows = mode === "selected" ? getSelectedRowsRef.current?.() : await resource.handlers.export?.();
+				if (!rows || mode === "selected" && rows.length === 0) return;
+				await onExport({
+					mode,
+					rows: denied.size ? rows.map((row) => Object.fromEntries(Object.entries(row).filter(([key]) => !denied.has(key)))) : rows,
+					columns
+				});
+			} finally {
+				exportBusyRef.current = false;
+				setExporting(false);
+			}
+			return;
+		}
 		const filename = title ?? "export";
 		const excludeColumns = denyFields;
 		if (mode === "selected") {
@@ -7792,18 +7846,30 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 		resource.handlers.export,
 		title,
 		denyFields,
-		resolvedFields
+		resolvedFields,
+		onExport
 	]);
 	const handleExportClick = React.useCallback(async () => {
 		const mode = selectedCount > 0 ? "selected" : "filtered";
+		if (onExport) return handleExport(mode);
 		setExporting(true);
 		try {
 			await handleExport(mode);
 		} finally {
 			setExporting(false);
 		}
-	}, [selectedCount, handleExport]);
+	}, [
+		selectedCount,
+		handleExport,
+		onExport
+	]);
 	const exportBatchActions = React.useMemo(() => {
+		if (onExport) return registryBatchActions.map((action$1) => action$1.type === "export" && action$1.onClick === void 0 && !action$1.component ? {
+			...action$1,
+			onClick: () => {
+				handleExport("selected").catch(reportExportError);
+			}
+		} : action$1);
 		if (!Object.values(resolvedFields).some((field) => field.format)) return registryBatchActions;
 		return registryBatchActions.map((action$1) => {
 			if (action$1.type !== "export" || action$1.onClick !== void 0 || Boolean(action$1.component)) return action$1;
@@ -7821,7 +7887,9 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 	}, [
 		registryBatchActions,
 		resolvedFields,
-		denyFields
+		denyFields,
+		onExport,
+		handleExport
 	]);
 	const toolbarRefresh = React.useMemo(() => {
 		const refresh = ownerRefreshAction?.onClick ?? resource.handlers.refresh;
@@ -7998,7 +8066,9 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 		if (type === "export" && canExport) return /* @__PURE__ */ jsxs(Button, {
 			variant: "outline",
 			size: "sm",
-			onClick: overrides?.onClick ?? toolbarExportData,
+			onClick: overrides?.onClick ?? (!ownerExportAction?.onClick ? () => {
+				toolbarExportData?.().catch(reportExportError);
+			} : toolbarExportData),
 			disabled: exporting || selectedCount === 0 && !resource.handlers.export,
 			children: [exporting ? /* @__PURE__ */ jsx(Loader2, { className: "mr-2 h-4 w-4 animate-spin" }) : /* @__PURE__ */ jsx(Upload, { className: "mr-2 h-4 w-4" }), overrides?.label ?? (selectedCount > 0 ? locale.toolbar.exportSelected(selectedCount) : locale.toolbar.export)]
 		}, "export");
@@ -8077,7 +8147,8 @@ function AutoCrudTable({ id, title, description, schema, resource, fields, table
 				showDefaultExport: false,
 				initialSorting: defaultSort,
 				onSelectedRowsChange: handleSelectedRowsChange,
-				getSelectedRows: getSelectedRowsRef
+				getSelectedRows: getSelectedRowsRef,
+				...onExport ? { exportTableRef } : {}
 			}),
 			rowActionDialog,
 			/* @__PURE__ */ jsx(CrudFormModal, {
@@ -8904,7 +8975,8 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 	useEffect(() => {
 		hooksRef.current = hooks;
 	}, [hooks]);
-	const metadata = (router.meta?.useQuery(void 0, { staleTime: 3e4 }))?.data;
+	const metadataQuery = router.meta?.useQuery(void 0, { staleTime: 3e4 });
+	const metadata = metadataQuery?.data;
 	const resolvedSchema = useMemo(() => mergeMetadataSchema(schema, metadata?.schema), [schema, metadata?.schema]);
 	const defaultSorting = useMemo(() => defaultSortOption === false ? [] : defaultSortOption ?? getDefaultSortingForSchema(resolvedSchema), [defaultSortOption, resolvedSchema]);
 	const metadataFields = useMemo(() => readMetadataFields(metadata?.fields), [metadata?.fields]);
@@ -8925,6 +8997,10 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 		search: parseAsString.withDefault("")
 	}, { shallow: false });
 	const [filters] = useReadableFilters(columns, { shallow: false });
+	const metadataPending = Boolean(metadataQuery?.isPending);
+	const [filtersReady, setFiltersReady] = useState(!metadataPending);
+	useEffect(() => setFiltersReady(!metadataPending), [metadataPending]);
+	const listReady = !metadataPending && filtersReady;
 	const queryInput = useMemo(() => {
 		const autoParams = {
 			page: urlParams.page,
@@ -8940,11 +9016,17 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 		filters,
 		queryTransform
 	]);
+	const hasReadyListData = useRef(false);
 	const listQuery = router.list.useQuery(queryInput, {
-		placeholderData: keepPreviousData,
+		enabled: listReady,
+		placeholderData: hasReadyListData.current ? keepPreviousData : void 0,
 		staleTime: 0
 	});
-	const tableRows = listQuery.data?.data ?? [];
+	useEffect(() => {
+		if (listReady && listQuery.data !== void 0) hasReadyListData.current = true;
+	}, [listReady, listQuery.data]);
+	const listData = listReady ? listQuery.data : void 0;
+	const tableRows = listData?.data ?? [];
 	const createMutation = router.create.useMutation();
 	const updateMutation = router.update.useMutation();
 	const deleteMutation = router.delete.useMutation();
@@ -9183,12 +9265,18 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 		schema
 	]);
 	const handleExport = useCallback(async () => {
+		let result;
 		if (exportFetcher) {
 			const { page: _p, perPage: _pp,...exportParams } = queryInput ?? {};
-			return (await exportFetcher(exportParams))?.data ?? [];
-		}
-		if (exportQuery) return (await exportQuery.refetch())?.data?.data ?? [];
-		throw new Error("Export not supported");
+			result = await exportFetcher(exportParams);
+		} else if (exportQuery) {
+			const response = await exportQuery.refetch();
+			if (response.error) throw response.error;
+			result = response.data;
+		} else throw new Error("Export not supported");
+		if (!result || !Array.isArray(result.data)) throw new Error("Export returned no data. Please retry.");
+		if (result.hasMore !== false || result.total > result.data.length) throw new Error("Export results are incomplete. Narrow your filters and retry.");
+		return result.data;
 	}, [
 		exportFetcher,
 		exportQuery,
@@ -9196,16 +9284,17 @@ function useAutoCrudResource({ router, schema, query: queryTransform, fields, op
 	]);
 	const canExport = !!(exportFetcher || exportQuery);
 	const refresh = useCallback(async () => {
+		if (!listReady) return;
 		return listQuery.refetch();
-	}, [listQuery]);
+	}, [listQuery, listReady]);
 	return {
 		idKey,
 		tableData: {
 			data: tableRows,
-			pageCount: listQuery.data?.pageCount ?? 0,
-			...typeof listQuery.data?.total === "number" ? { total: listQuery.data.total } : {},
-			isLoading: listQuery.isLoading,
-			isFetching: listQuery.isFetching
+			pageCount: listData?.pageCount ?? 0,
+			...typeof listData?.total === "number" ? { total: listData.total } : {},
+			isLoading: !listReady || listQuery.isLoading,
+			isFetching: !listReady || listQuery.isFetching
 		},
 		schema: resolvedSchema,
 		fields: metadataFields,
@@ -9543,4 +9632,70 @@ function createMemoryDataSource(initialData = []) {
 }
 
 //#endregion
-export { AutoCrudTable, AutoForm, AutoTable, AutoTableActionBar, AutoTableSimpleFilters, CrudFormModal, DataTable, DataTableAdvancedToolbar, DataTableColumnHeader, DataTableFacetedFilter, DataTablePagination, DataTableToolbar, DataTableViewOptions, ExportDialog, ImportDialog, MultiCombobox, SchemaAdapter, Select, actionPositionSchema, cn, coerceRowValues, compareOrder, components, createActionsColumn, createEditFormSchema, createFormSchema, createMemoryDataSource, createSelectColumn, createTRPCDataSource, createTableSchema, crudActions, dataSources, dataToCSV, deDE, downloadCSVTemplate, enUS, esES, exportAllToCSV, exportTableToCSV, formComponents, formatDate, frFR, generateCSVTemplate, getUrlParams, humanize, jaJP, koKR, matchesPosition, noopToastAdapter, normalizeDataSourceConfig, normalizeOptions, parseAsArrayOf, parseAsInteger, parseAsString, parseAsStringEnum, parseCSV, parseImportFile, parseJSON, parseZodField, positionActions, resolveLocale, setDateFormatter, setSearchParams, setToolbarResolver, tablePagination, useAutoCrudResource, useDataTable, useQueryState, useQueryStates, useReadableFilters, useUrlState, useUrlStates, zhCN };
+//#region src/lib/workbook.ts
+const MAX_ROWS = 1048576;
+const MAX_COLUMNS = 16384;
+const MAX_CELL_LENGTH = 32767;
+const MAX_LINE_FEEDS = 253;
+function validateCell(value) {
+	if (typeof value === "string") {
+		if (value.length > MAX_CELL_LENGTH) throw new RangeError(`Excel cells cannot exceed ${MAX_CELL_LENGTH} characters.`);
+		if ((value.match(/\n/g)?.length ?? 0) > MAX_LINE_FEEDS) throw new RangeError(`Excel cells cannot exceed ${MAX_LINE_FEEDS} line feeds.`);
+	} else if (value != null && (typeof value !== "number" || !Number.isFinite(value))) throw new TypeError("Workbook cells must contain text, finite numbers, or null.");
+}
+function validateSheets(sheets) {
+	if (sheets.length === 0) throw new Error("A workbook needs at least one sheet.");
+	const names = /* @__PURE__ */ new Set();
+	for (const sheet of sheets) {
+		if (!sheet.name || sheet.name.length > 31 || /[*?:\\/\[\]]/.test(sheet.name) || sheet.name.startsWith("'") || sheet.name.endsWith("'")) throw new Error("Worksheet names must be valid Excel names of 1–31 characters.");
+		const name = sheet.name.toLowerCase();
+		if (names.has(name)) throw new Error("Worksheet names must be unique.");
+		names.add(name);
+		if (sheet.rows.length + 1 > MAX_ROWS) throw new RangeError(`Excel worksheets cannot exceed ${MAX_ROWS} rows including headers.`);
+		if (sheet.headers.length > MAX_COLUMNS) throw new RangeError(`Excel worksheets cannot exceed ${MAX_COLUMNS} columns.`);
+		sheet.headers.forEach(validateCell);
+		for (const row of sheet.rows) {
+			if (row.length > MAX_COLUMNS) throw new RangeError(`Excel worksheets cannot exceed ${MAX_COLUMNS} columns.`);
+			row.forEach(validateCell);
+		}
+	}
+}
+/** Internal byte builder, exported from this module for real workbook roundtrip tests. */
+async function buildWorkbookBytes(sheets) {
+	validateSheets(sheets);
+	const { default: ExcelJS } = await import("exceljs");
+	const workbook = new ExcelJS.Workbook();
+	for (const sheet of sheets) {
+		const worksheet = workbook.addWorksheet(sheet.name);
+		const append = (values) => {
+			worksheet.addRow(values.map((value) => value ?? null)).eachCell((cell, column) => {
+				const numberFormat = sheet.numberFormats?.[column - 1];
+				if (typeof cell.value === "number" && numberFormat !== void 0) cell.numFmt = numberFormat;
+				if (typeof cell.value === "string" && /[\r\n]/.test(cell.value)) cell.alignment = { wrapText: true };
+			});
+		};
+		append(sheet.headers);
+		sheet.rows.forEach(append);
+	}
+	return new Uint8Array(await workbook.xlsx.writeBuffer()).buffer;
+}
+/** Download a real XLSX workbook. Errors reject; no CSV or raw-value fallback. */
+async function exportWorkbook(sheets, { filename }) {
+	const bytes = await buildWorkbookBytes(sheets);
+	const blob = new Blob([bytes], { type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" });
+	const url = URL.createObjectURL(blob);
+	const link = document.createElement("a");
+	try {
+		link.href = url;
+		link.download = /\.xlsx$/i.test(filename) ? filename : `${filename}.xlsx`;
+		link.hidden = true;
+		document.body.appendChild(link);
+		link.click();
+	} finally {
+		link.remove();
+		setTimeout(() => URL.revokeObjectURL(url), 0);
+	}
+}
+
+//#endregion
+export { AutoCrudTable, AutoForm, AutoTable, AutoTableActionBar, AutoTableSimpleFilters, CrudFormModal, DataTable, DataTableAdvancedToolbar, DataTableColumnHeader, DataTableFacetedFilter, DataTablePagination, DataTableToolbar, DataTableViewOptions, ExportDialog, ImportDialog, MultiCombobox, SchemaAdapter, Select, actionPositionSchema, cn, coerceRowValues, compareOrder, components, createActionsColumn, createEditFormSchema, createFormSchema, createMemoryDataSource, createSelectColumn, createTRPCDataSource, createTableSchema, crudActions, dataSources, dataToCSV, deDE, downloadCSVTemplate, enUS, esES, exportAllToCSV, exportTableToCSV, exportWorkbook, formComponents, formatDate, frFR, generateCSVTemplate, getUrlParams, humanize, jaJP, koKR, matchesPosition, noopToastAdapter, normalizeDataSourceConfig, normalizeOptions, parseAsArrayOf, parseAsInteger, parseAsString, parseAsStringEnum, parseCSV, parseImportFile, parseJSON, parseZodField, positionActions, resolveLocale, setDateFormatter, setSearchParams, setToolbarResolver, tablePagination, useAutoCrudResource, useDataTable, useQueryState, useQueryStates, useReadableFilters, useUrlState, useUrlStates, zhCN };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wordrhyme/auto-crud",
   "type": "module",
-  "version": "1.11.2",
+  "version": "1.12.1",
   "description": "Schema-first CRUD components with auto-generated tables and forms",
   "author": "wordrhyme",
   "license": "MIT",
@@ -66,6 +66,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "exceljs": "4.4.0",
     "lucide-react": "0.553.0",
     "nanoid": "^5.1.6",
     "tailwind-merge": "^3.5.0",
@@ -93,11 +94,11 @@
     "tsdown": "^0.15.12",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
+    "@internal/eslint-config": "0.3.0",
+    "@internal/tsconfig": "0.1.0",
     "@internal/tsdown-config": "0.1.0",
     "@internal/vitest-config": "0.1.0",
-    "@internal/tsconfig": "0.1.0",
-    "@internal/prettier-config": "0.0.1",
-    "@internal/eslint-config": "0.3.0"
+    "@internal/prettier-config": "0.0.1"
   },
   "prettier": "@internal/prettier-config",
   "scripts": {