@wordrhyme/auto-crud 1.1.2 → 1.1.3

package/dist/index.cjs

@@ -59,6 +59,8 @@ let __pixpilot_formily_shadcn = require("@pixpilot/formily-shadcn");
 __pixpilot_formily_shadcn = __toESM(__pixpilot_formily_shadcn);
 let __formily_react = require("@formily/react");
 __formily_react = __toESM(__formily_react);
+let __pixpilot_shadcn_ui = require("@pixpilot/shadcn-ui");
+__pixpilot_shadcn_ui = __toESM(__pixpilot_shadcn_ui);
 let sonner = require("sonner");
 sonner = __toESM(sonner);
 
@@ -2705,8 +2707,17 @@ function DataTableViewOptions({ table, disabled,...props }) {
 
 //#endregion
 //#region src/components/auto-crud/auto-table-simple-filters.tsx
-function AutoTableSimpleFilters({ table, shallow = false, filters: externalFilters, onFiltersChange }) {
-	const columns = react.useMemo(() => table.getAllColumns().filter((col) => col.getCanFilter()), [table]);
+function AutoTableSimpleFilters({ table, shallow = false, filters: externalFilters, onFiltersChange, leading }) {
+	const columns = react.useMemo(() => table.getAllColumns().filter((col) => col.getCanFilter()).sort((a, b) => {
+		const readOrder = (column) => {
+			const metaIndex = column.columnDef.meta?.index;
+			const columnIndex = column.columnDef.index;
+			return typeof metaIndex === "number" ? metaIndex : typeof columnIndex === "number" ? columnIndex : 1e4;
+		};
+		const orderDiff = readOrder(a) - readOrder(b);
+		if (orderDiff !== 0) return orderDiff;
+		return a.getIndex() - b.getIndex();
+	}), [table]);
 	const queryStateOptions = table.options.meta?.queryStateOptions;
 	const [queryFilters, setQueryFilters] = useReadableFilters(columns, {
 		...queryStateOptions,
@@ -2823,8 +2834,9 @@ function AutoTableSimpleFilters({ table, shallow = false, filters: externalFilte
 	if (!mounted) return null;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		ref: containerRef,
-		className: "flex flex-wrap items-center gap-2 min-w-0",
+		className: "flex flex-1 flex-wrap items-center gap-2 min-w-0",
 		children: [
+			leading,
 			filterColumns.map((column, index) => {
 				const meta = column.columnDef.meta;
 				const value = getFilterValue(column.id);
@@ -3957,7 +3969,7 @@ function createTableSchema(schema, options) {
 		if (cached) return [...cached];
 	}
 	const shape = schema.shape;
-	const columns = [];
+	const columnEntries = [];
 	for (const [key, fieldSchema] of Object.entries(shape)) {
 		if (exclude.includes(key)) continue;
 		const override = overrides?.[key];
@@ -3978,20 +3990,31 @@ function createTableSchema(schema, options) {
 			options: override?.meta?.options ?? autoOptions
 		};
 		const { meta: _ignoredMeta,...restOverride } = override ?? {};
-		columns.push({
-			id: key,
-			accessorKey: key,
-			header: ({ column }) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DataTableColumnHeader, {
-				column,
-				label
-			}),
-			cell: ({ row }) => renderCell(row.getValue(key), parsed.type),
-			enableColumnFilter: true,
-			enableSorting: true,
-			meta,
-			...restOverride
+		const sourceIndex = columnEntries.length;
+		const order = typeof restOverride.index === "number" ? restOverride.index : typeof meta.index === "number" ? meta.index : 1e4 + sourceIndex;
+		columnEntries.push({
+			order,
+			sourceIndex,
+			column: {
+				id: key,
+				accessorKey: key,
+				header: ({ column }) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DataTableColumnHeader, {
+					column,
+					label
+				}),
+				cell: ({ row }) => renderCell(row.getValue(key), parsed.type),
+				enableColumnFilter: true,
+				enableSorting: true,
+				meta,
+				...restOverride
+			}
 		});
 	}
+	const columns = columnEntries.sort((a, b) => {
+		const orderDiff = a.order - b.order;
+		if (orderDiff !== 0) return orderDiff;
+		return a.sourceIndex - b.sourceIndex;
+	}).map((entry) => entry.column);
 	if (canCache) baseTableSchemaCache.set(schema, columns);
 	return columns;
 }
@@ -4663,10 +4686,19 @@ const filterModeConfig = {
 		tooltip: "Linear-style command filters"
 	}
 };
-function AutoTable({ schema, data, pageCount = 1, overrides, enableRowSelection = true, exclude, actions, pinnedColumns, filterMode = "simple", onDeleteSelected, onUpdateSelected, batchUpdateFields, actionBarExtra, actionBarActions, initialSorting, enableExport = true, showDefaultExport = true, onSelectedCountChange, getSelectedRows }) {
+function AutoTable({ schema, data, pageCount = 1, overrides, enableRowSelection = true, exclude, actions, pinnedColumns, filterMode = "simple", search = false, onDeleteSelected, onUpdateSelected, batchUpdateFields, actionBarExtra, actionBarActions, initialSorting, enableExport = true, showDefaultExport = true, onSelectedCountChange, getSelectedRows }) {
 	const modes = filterMode ? Array.isArray(filterMode) ? filterMode : [filterMode] : DEFAULT_MODES;
 	const [currentMode, setCurrentMode] = useQueryState("filterMode", parseAsStringEnum(modes).withDefault(modes[0] ?? "simple"));
 	const showToggle = modes.length > 1;
+	const [searchValue, setSearchValue] = useUrlState("search", parseAsString.withDefault(""), {
+		shallow: false,
+		clearOnDefault: true
+	});
+	const [, setSearchPage] = useUrlState("page", parseAsInteger.withDefault(1), {
+		shallow: false,
+		clearOnDefault: true
+	});
+	const searchConfig = search && typeof search === "object" ? search : {};
 	const { table, shallow, debounceMs, throttleMs } = useDataTable({
 		data,
 		columns: (0, react.useMemo)(() => {
@@ -4738,11 +4770,21 @@ function AutoTable({ schema, data, pageCount = 1, overrides, enableRowSelection
 			})
 		})
 	})] }) : null;
+	const searchInput = search ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__pixpilot_shadcn.Input, {
+		value: searchValue,
+		onChange: (event) => {
+			setSearchValue(event.target.value);
+			setSearchPage(1);
+		},
+		placeholder: searchConfig.placeholder ?? "搜索",
+		className: "h-8 w-48 shrink-0"
+	}) : null;
 	const filtersContent = (0, react.useMemo)(() => {
 		switch (currentMode) {
 			case "simple": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AutoTableSimpleFilters, {
 				table,
-				shallow
+				shallow,
+				leading: searchInput
 			});
 			case "command": return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DataTableFilterMenu, {
 				table,
@@ -4762,6 +4804,7 @@ function AutoTable({ schema, data, pageCount = 1, overrides, enableRowSelection
 		currentMode,
 		table,
 		shallow,
+		searchInput,
 		debounceMs,
 		throttleMs
 	]);
@@ -4773,10 +4816,14 @@ function AutoTable({ schema, data, pageCount = 1, overrides, enableRowSelection
 				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 					className: "flex flex-1 items-start gap-2 min-h-[40px]",
 					"data-filter-parent": true,
-					children: [currentMode !== "simple" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DataTableSortList, {
-						table,
-						align: "start"
-					}), filtersContent]
+					children: [
+						currentMode !== "simple" && searchInput,
+						currentMode !== "simple" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(DataTableSortList, {
+							table,
+							align: "start"
+						}),
+						filtersContent
+					]
 				}), /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 					className: "flex items-center gap-2",
 					children: [
@@ -4965,10 +5012,44 @@ function createEditFormSchema(schema, options) {
 
 //#endregion
 //#region src/components/auto-crud/auto-form.tsx
+const COMBOBOX_LIST_CLASS = "[&_[cmdk-list]]:max-h-[360px]";
 const FormilySwitch = (0, __formily_react.connect)(__pixpilot_shadcn.Switch, (0, __formily_react.mapProps)({
 	value: "checked",
 	onInput: "onCheckedChange"
 }));
+const FormilyCombobox = (0, __formily_react.connect)(AutoCrudCombobox, (0, __formily_react.mapProps)({ dataSource: "options" }));
+function AutoCrudCombobox({ options = [], filter, className,...props }) {
+	const resolvedFilter = (0, react.useMemo)(() => {
+		if (typeof filter === "function") return filter;
+		return createComboboxFilter(options);
+	}, [filter, options]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__pixpilot_shadcn_ui.Combobox, {
+		...props,
+		options,
+		filter: resolvedFilter,
+		className: (0, __pixpilot_shadcn.cn)(COMBOBOX_LIST_CLASS, className)
+	});
+}
+function createComboboxFilter(options) {
+	const searchTextByValue = new Map(options.map((option) => [option.value, collectSearchText(option.value, option.label, option.searchText, option.keywords).toLocaleLowerCase()]));
+	return (value, search, keywords) => {
+		const query = search.trim().toLocaleLowerCase();
+		if (!query) return 1;
+		const searchText = collectSearchText(searchTextByValue.get(value), keywords).toLocaleLowerCase();
+		if (searchText === query) return 2;
+		return searchText.includes(query) ? 1 : 0;
+	};
+}
+function collectSearchText(...parts) {
+	const texts = [];
+	for (const part of parts) {
+		if (!part) continue;
+		if (Array.isArray(part)) texts.push(...part.map(String));
+		else if (typeof part === "object") texts.push(...Object.values(part).filter(Boolean).map(String));
+		else texts.push(String(part));
+	}
+	return texts.join(" ");
+}
 function AutoFormInner({ schema: zodSchema, initialValues, onSubmit, overrides, mode = "create", loading = false, gridColumns = 1, labelAlign = "top", labelWidth, showSubmitButton = true }, ref) {
 	const form = (0, react.useMemo)(() => (0, __formily_core.createForm)({ initialValues }), [JSON.stringify(initialValues)]);
 	const formSchema = (0, react.useMemo)(() => createEditFormSchema(zodSchema, {
@@ -4993,10 +5074,16 @@ function AutoFormInner({ schema: zodSchema, initialValues, onSubmit, overrides,
 		form,
 		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)(__pixpilot_formily_shadcn.JsonSchemaField, {
 			schema: formSchema,
-			components: { fields: { Switch: {
-				component: FormilySwitch,
-				decorator: "FormItem"
-			} } }
+			components: { fields: {
+				Combobox: {
+					component: FormilyCombobox,
+					decorator: "FormItem"
+				},
+				Switch: {
+					component: FormilySwitch,
+					decorator: "FormItem"
+				}
+			} }
 		}), showSubmitButton && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 			className: "flex justify-end gap-2 mt-6",
 			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__pixpilot_shadcn.Button, {
@@ -6088,6 +6175,11 @@ function resolveActions(actionsOrFn, defaults, rowActionsLocale) {
 */
 function AutoCrudTable({ title, description, schema, resource, fields, table: tableConfig, form: formConfig, permissions, actions: actionItems, toolbarActions, locale: localeProp, onCreate }) {
 	const locale = resolveLocale(localeProp);
+	const resolvedSchema = resource.schema ?? schema;
+	const resolvedFields = react.useMemo(() => ({
+		...fields,
+		...resource.fields
+	}), [fields, resource.fields]);
 	const can = {
 		create: permissions?.can?.create ?? true,
 		update: permissions?.can?.update ?? true,
@@ -6103,10 +6195,10 @@ function AutoCrudTable({ title, description, schema, resource, fields, table: ta
 	const [exporting, setExporting] = react.useState(false);
 	const getSelectedRowsRef = react.useRef(null);
 	const importColumns = react.useMemo(() => {
-		const shape = schema.shape;
+		const shape = resolvedSchema.shape;
 		const denySet = new Set(denyFields ?? []);
 		return Object.keys(shape).filter((key) => !denySet.has(key));
-	}, [schema, denyFields]);
+	}, [resolvedSchema, denyFields]);
 	const handleExport = react.useCallback(async (mode) => {
 		const filename = title ?? "export";
 		const excludeColumns = denyFields;
@@ -6138,21 +6230,34 @@ function AutoCrudTable({ title, description, schema, resource, fields, table: ta
 			setExporting(false);
 		}
 	}, [selectedCount, handleExport]);
-	const tableOverrides = react.useMemo(() => buildTableOverrides(fields, tableConfig?.overrides), [fields, tableConfig?.overrides]);
-	const formOverrides = react.useMemo(() => buildFormOverrides(fields, formConfig?.overrides, denyFields), [
-		fields,
+	const tableOverrides = react.useMemo(() => buildTableOverrides(resolvedFields, tableConfig?.overrides), [resolvedFields, tableConfig?.overrides]);
+	const formOverrides = react.useMemo(() => buildFormOverrides(resolvedFields, formConfig?.overrides, denyFields), [
+		resolvedFields,
 		formConfig?.overrides,
 		denyFields
 	]);
-	const hiddenColumns = react.useMemo(() => buildHiddenColumns(fields, tableConfig?.hidden, denyFields), [
-		fields,
+	const hiddenColumns = react.useMemo(() => buildHiddenColumns(resolvedFields, tableConfig?.hidden, denyFields), [
+		resolvedFields,
 		tableConfig?.hidden,
 		denyFields
 	]);
-	const batchFields = react.useMemo(() => buildBatchUpdateFields(schema, tableConfig?.batchFields, fields), [
-		schema,
+	const searchConfig = react.useMemo(() => {
+		const tableSearch = tableConfig?.search;
+		if (tableSearch === false) return false;
+		if (tableSearch && typeof tableSearch === "object") return tableSearch;
+		return Object.values(resolvedFields).some((field) => field?.search === true) ? true : false;
+	}, [resolvedFields, tableConfig?.search]);
+	const batchFields = react.useMemo(() => buildBatchUpdateFields(resolvedSchema, tableConfig?.batchFields, resolvedFields), [
+		resolvedSchema,
 		tableConfig?.batchFields,
-		fields
+		resolvedFields
+	]);
+	const formInitialValues = react.useMemo(() => {
+		return resource.modal.createOpen ? resource.modal.copySource ?? void 0 : resource.modal.selected ?? void 0;
+	}, [
+		resource.modal.createOpen,
+		resource.modal.copySource,
+		resource.modal.selected
 	]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className: "space-y-4",
@@ -6233,11 +6338,12 @@ function AutoCrudTable({ title, description, schema, resource, fields, table: ta
 			}),
 			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(AutoTable, {
 				data: resource.tableData.data,
-				schema,
+				schema: resolvedSchema,
 				pageCount: resource.tableData.pageCount,
 				overrides: tableOverrides,
 				exclude: hiddenColumns,
 				filterMode: tableConfig?.filterModes,
+				search: searchConfig,
 				actions: resolveActions(actionItems, {
 					openView: resource.handlers.openView,
 					openEdit: can.update ? resource.handlers.openEdit : void 0,
@@ -6258,8 +6364,8 @@ function AutoCrudTable({ title, description, schema, resource, fields, table: ta
 				open: resource.modal.createOpen || resource.modal.editOpen,
 				onOpenChange: (open) => !open && resource.handlers.closeModals(),
 				mode: resource.modal.createOpen ? "create" : "edit",
-				schema,
-				initialValues: resource.modal.createOpen ? resource.modal.copySource ?? void 0 : resource.modal.selected ?? void 0,
+				schema: resolvedSchema,
+				initialValues: formInitialValues,
 				onSubmit: (values) => {
 					if (resource.modal.createOpen) resource.handlers.submitCreate(values);
 					else resource.handlers.submitUpdate(values);
@@ -6276,8 +6382,8 @@ function AutoCrudTable({ title, description, schema, resource, fields, table: ta
 				onOpenChange: (open) => !open && resource.handlers.closeModals(),
 				variant: resource.modal.variant,
 				data: resource.modal.selected,
-				schema,
-				fields,
+				schema: resolvedSchema,
+				fields: resolvedFields,
 				denyFields,
 				locale
 			}),
@@ -6996,6 +7102,53 @@ const noopToastAdapter = {
 	info: () => {},
 	warning: () => {}
 };
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isJsonSchemaObject(value) {
+	return isRecord(value) && isRecord(value.properties);
+}
+function readJsonSchemaType(property) {
+	return Array.isArray(property.type) ? property.type.find((item) => item !== "null") : property.type;
+}
+function jsonPropertyToZod(property, required) {
+	const enumValues = property.enum?.filter((value) => typeof value === "string");
+	let schema;
+	if (enumValues && enumValues.length > 0) schema = zod.z.enum(enumValues);
+	else switch (readJsonSchemaType(property)) {
+		case "number":
+		case "integer":
+			schema = zod.z.number();
+			break;
+		case "boolean":
+			schema = zod.z.boolean();
+			break;
+		case "array":
+			schema = zod.z.array(zod.z.unknown());
+			break;
+		case "object":
+			schema = zod.z.record(zod.z.string(), zod.z.unknown());
+			break;
+		case "string":
+			schema = property.format === "date" || property.format === "date-time" ? zod.z.coerce.date() : zod.z.string();
+			break;
+		default: schema = zod.z.unknown();
+	}
+	return required ? schema : schema.optional();
+}
+function mergeMetadataSchema(baseSchema, metadataSchema) {
+	if (!isJsonSchemaObject(metadataSchema)) return baseSchema;
+	const required = new Set(Array.isArray(metadataSchema.required) ? metadataSchema.required.filter((field) => typeof field === "string") : []);
+	const extensionShape = {};
+	for (const [field, property] of Object.entries(metadataSchema.properties ?? {})) {
+		if (field in baseSchema.shape) continue;
+		extensionShape[field] = jsonPropertyToZod(property, required.has(field));
+	}
+	return Object.keys(extensionShape).length > 0 ? baseSchema.extend(extensionShape) : baseSchema;
+}
+function readMetadataFields(fields) {
+	return isRecord(fields) ? fields : void 0;
+}
 /**
 * Modal 状态 Reducer
 */
@@ -7054,12 +7207,16 @@ function useAutoCrudResource({ router, schema, query: queryTransform, options =
 	(0, react.useEffect)(() => {
 		hooksRef.current = hooks;
 	}, [hooks]);
-	const columns = (0, react.useMemo)(() => createTableSchema(schema), [schema]);
+	const metadata = (router.meta?.useQuery(void 0, { staleTime: 3e4 }))?.data;
+	const resolvedSchema = (0, react.useMemo)(() => mergeMetadataSchema(schema, metadata?.schema), [schema, metadata?.schema]);
+	const metadataFields = (0, react.useMemo)(() => readMetadataFields(metadata?.fields), [metadata?.fields]);
+	const columns = (0, react.useMemo)(() => createTableSchema(resolvedSchema), [resolvedSchema]);
 	const [urlParams] = useQueryStates({
 		page: parseAsInteger.withDefault(1),
 		perPage: parseAsInteger.withDefault(10),
 		sort: getSortingStateParser().withDefault([]),
-		joinOperator: parseAsStringEnum(["and", "or"]).withDefault("and")
+		joinOperator: parseAsStringEnum(["and", "or"]).withDefault("and"),
+		search: parseAsString.withDefault("")
 	}, { shallow: false });
 	const [filters] = useReadableFilters(columns, { shallow: false });
 	const queryInput = (0, react.useMemo)(() => {
@@ -7068,7 +7225,8 @@ function useAutoCrudResource({ router, schema, query: queryTransform, options =
 			perPage: urlParams.perPage,
 			sort: urlParams.sort,
 			filters,
-			joinOperator: urlParams.joinOperator
+			joinOperator: urlParams.joinOperator,
+			...urlParams.search.trim() ? { search: urlParams.search.trim() } : {}
 		};
 		return queryTransform ? queryTransform(autoParams) : autoParams;
 	}, [
@@ -7080,6 +7238,7 @@ function useAutoCrudResource({ router, schema, query: queryTransform, options =
 		placeholderData: keepPreviousData,
 		staleTime: 0
 	});
+	const tableRows = listQuery.data?.data ?? [];
 	const createMutation = router.create.useMutation();
 	const updateMutation = router.update.useMutation();
 	const deleteMutation = router.delete.useMutation();
@@ -7332,11 +7491,13 @@ function useAutoCrudResource({ router, schema, query: queryTransform, options =
 	const canExport = !!(exportFetcher || exportQuery);
 	return {
 		tableData: {
-			data: listQuery.data?.data ?? [],
+			data: tableRows,
 			pageCount: listQuery.data?.pageCount ?? 0,
 			isLoading: listQuery.isLoading,
 			isFetching: listQuery.isFetching
 		},
+		schema: resolvedSchema,
+		fields: metadataFields,
 		modal,
 		mutations: {
 			isCreating: createMutation.isPending,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import * as react_jsx_runtime6 from "react/jsx-runtime";
+import * as react_jsx_runtime3 from "react/jsx-runtime";
 import { z } from "zod";
 import * as _tanstack_react_table0 from "@tanstack/react-table";
 import { Column, ColumnDef, ColumnSort, Row, RowData, Table, TableOptions, TableState } from "@tanstack/react-table";
@@ -125,6 +125,10 @@ interface UseAutoCrudResourceReturn<TSchema extends z.ZodObject<z.ZodRawShape>,
     /** 是否正在获取数据（用于显示微妙的加载指示器） */
     isFetching: boolean;
   };
+  /** Optional schema override from host metadata. */
+  schema?: z.ZodObject<z.ZodRawShape>;
+  /** Optional field config override from host metadata. */
+  fields?: Fields;
   modal: ModalState<TListItem>;
   mutations: {
     isCreating: boolean;
@@ -182,6 +186,10 @@ interface CrudRouter {
   export?: {
     useQuery: (input?: any, opts?: any) => any;
   };
+  /** 元数据路由（query，由 createCrudRouter 自动生成） */
+  meta?: {
+    useQuery: (input?: any, opts?: any) => any;
+  };
 }
 /**
  * 自动生成的查询参数（由内部 URL 状态管理生成）
@@ -193,6 +201,7 @@ interface AutoQueryParams {
     id: string;
     desc: boolean;
   }>;
+  search?: string;
   filters: any[];
   joinOperator: "and" | "or";
 }
@@ -352,7 +361,7 @@ declare function AutoTableActionBar<TData>({
   enableDelete,
   extraActions,
   actions
-}: AutoTableActionBarProps<TData>): react_jsx_runtime6.JSX.Element;
+}: AutoTableActionBarProps<TData>): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/lib/schema-bridge/types.d.ts
 /**
@@ -379,6 +388,7 @@ interface ParsedZodField {
 type ColumnOverrides<T> = Partial<{ [K in keyof T]: Partial<ColumnDef<T, unknown>> & {
   hidden?: boolean;
   label?: string;
+  index?: number;
 } }>;
 /**
  * Formily Schema 覆盖选项
@@ -473,6 +483,10 @@ interface AutoTableProps<T extends z.ZodObject<z.ZodRawShape>> {
    * 默认: ["simple", "advanced", "command"] (全部显示)
    */
   filterMode?: FilterMode | FilterMode[];
+  /** 全局搜索框 */
+  search?: boolean | {
+    placeholder?: string;
+  };
   /** 批量删除回调 */
   onDeleteSelected?: (rows: z.infer<T>[]) => void;
   /** 批量更新回调 */
@@ -504,6 +518,7 @@ declare function AutoTable<T extends z.ZodObject<z.ZodRawShape>>({
   actions,
   pinnedColumns,
   filterMode,
+  search,
   onDeleteSelected,
   onUpdateSelected,
   batchUpdateFields,
@@ -514,7 +529,7 @@ declare function AutoTable<T extends z.ZodObject<z.ZodRawShape>>({
   showDefaultExport,
   onSelectedCountChange,
   getSelectedRows
-}: AutoTableProps<T>): react_jsx_runtime6.JSX.Element;
+}: AutoTableProps<T>): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/i18n/locale.d.ts
 /**
@@ -629,6 +644,8 @@ interface FilterConfig {
   unit?: string;
   /** 过滤器占位符 */
   placeholder?: string;
+  /** 排序权重，数值越小越靠前 */
+  index?: number;
   /** 是否在筛选栏中隐藏（隐藏筛选但不影响表格列显示） */
   hidden?: boolean;
   /** 控制在哪些筛选模式下显示（未设置则在所有模式显示） */
@@ -643,6 +660,8 @@ interface Field {
   label?: string;
   /** 是否隐藏（表格和表单都隐藏） */
   hidden?: boolean;
+  /** 是否参与 AutoCrud 全局搜索 */
+  search?: boolean;
   /**
    * 筛选器独立配置
    * - FilterConfig: 详细配置
@@ -658,6 +677,8 @@ interface Field {
   table?: {
     /** 是否在表格中隐藏 */
     hidden?: boolean;
+    /** 排序权重，数值越小越靠前 */
+    index?: number;
     /** 筛选器配置 */
     meta?: Record<string, unknown>;
     /** 其他列配置 */
@@ -734,6 +755,8 @@ type ToolbarActionConfig = ToolbarActionItem[] | ((defaults: ToolbarBuiltinActio
  * AutoCrudTable Props 接口
  */
 interface AutoCrudTableProps<TSchema extends z.ZodObject<z.ZodRawShape>> {
+  /** Public CRUD id. Used by hosts to document the extension target. */
+  id?: string;
   /** 页面标题 */
   title?: string;
   /** 页面描述 */
@@ -759,6 +782,10 @@ interface AutoCrudTableProps<TSchema extends z.ZodObject<z.ZodRawShape>> {
      * - 数组: 第一个为默认值，显示切换按钮
      */
     filterModes?: FilterMode | FilterMode[];
+    /** 全局搜索框；默认在存在 search: true 字段时显示 */
+    search?: boolean | {
+      placeholder?: string;
+    };
     /**
      * 批量更新字段配置
      * - 只需传字段名数组，options 自动从 schema enum 推导
@@ -847,7 +874,7 @@ declare function AutoCrudTable<TSchema extends z.ZodObject<z.ZodRawShape>>({
   toolbarActions,
   locale: localeProp,
   onCreate
-}: AutoCrudTableProps<TSchema>): react_jsx_runtime6.JSX.Element;
+}: AutoCrudTableProps<TSchema>): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/components/auto-crud/auto-form.d.ts
 interface AutoFormProps<T extends z.ZodObject<z.ZodRawShape>> {
@@ -879,7 +906,7 @@ declare function AutoFormInner<T extends z.ZodObject<z.ZodRawShape>>({
   labelAlign,
   labelWidth,
   showSubmitButton
-}: AutoFormProps<T>, ref: React.Ref<AutoFormRef>): react_jsx_runtime6.JSX.Element;
+}: AutoFormProps<T>, ref: React.Ref<AutoFormRef>): react_jsx_runtime3.JSX.Element;
 declare const AutoForm: <T extends z.ZodObject<z.ZodRawShape>>(props: AutoFormProps<T> & {
   ref?: React.Ref<AutoFormRef>;
 }) => ReturnType<typeof AutoFormInner>;
@@ -1093,12 +1120,12 @@ declare const filterItemSchema: z.ZodObject<{
   variant: z.ZodEnum<{
     number: "number";
     boolean: "boolean";
-    date: "date";
     text: "text";
+    range: "range";
+    date: "date";
+    dateRange: "dateRange";
     select: "select";
     multiSelect: "multiSelect";
-    dateRange: "dateRange";
-    range: "range";
   }>;
   operator: z.ZodEnum<{
     iLike: "iLike";
@@ -1128,6 +1155,7 @@ declare module "@tanstack/react-table" {
   }
   interface ColumnMeta<TData extends RowData, TValue> {
     label?: string;
+    index?: number;
     placeholder?: string;
     variant?: FilterVariant$1;
     options?: Option[];
@@ -1171,13 +1199,15 @@ interface AutoTableSimpleFiltersProps<TData> {
   shallow?: boolean;
   filters?: ExtendedColumnFilter<TData>[];
   onFiltersChange?: (filters: ExtendedColumnFilter<TData>[]) => void;
+  leading?: React$1.ReactNode;
 }
 declare function AutoTableSimpleFilters<TData>({
   table,
   shallow,
   filters: externalFilters,
-  onFiltersChange
-}: AutoTableSimpleFiltersProps<TData>): react_jsx_runtime6.JSX.Element | null;
+  onFiltersChange,
+  leading
+}: AutoTableSimpleFiltersProps<TData>): react_jsx_runtime3.JSX.Element | null;
 //#endregion
 //#region src/components/auto-crud/form-modal.d.ts
 type ModalVariant = "dialog" | "sheet";
@@ -1219,7 +1249,7 @@ declare function CrudFormModal<T extends z.ZodObject<z.ZodRawShape>>({
   labelAlign,
   labelWidth,
   className
-}: CrudFormModalProps<T>): react_jsx_runtime6.JSX.Element;
+}: CrudFormModalProps<T>): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/components/auto-crud/import-dialog.d.ts
 interface ImportDialogProps {
@@ -1241,7 +1271,7 @@ declare function ImportDialog({
   columns,
   title,
   locale
-}: ImportDialogProps): react_jsx_runtime6.JSX.Element;
+}: ImportDialogProps): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/components/auto-crud/export-dialog.d.ts
 type ExportMode = "selected" | "filtered";
@@ -1261,7 +1291,7 @@ declare function ExportDialog({
   selectedCount,
   onExport,
   canExportFiltered
-}: ExportDialogProps): react_jsx_runtime6.JSX.Element;
+}: ExportDialogProps): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table.d.ts
 interface DataTableProps<TData> extends React$1.ComponentProps<"div"> {
@@ -1274,7 +1304,7 @@ declare function DataTable<TData>({
   children,
   className,
   ...props
-}: DataTableProps<TData>): react_jsx_runtime6.JSX.Element;
+}: DataTableProps<TData>): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table-advanced-toolbar.d.ts
 interface DataTableAdvancedToolbarProps<TData> extends React$1.ComponentProps<"div"> {
@@ -1285,7 +1315,7 @@ declare function DataTableAdvancedToolbar<TData>({
   children,
   className,
   ...props
-}: DataTableAdvancedToolbarProps<TData>): react_jsx_runtime6.JSX.Element;
+}: DataTableAdvancedToolbarProps<TData>): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table-column-header.d.ts
 interface DataTableColumnHeaderProps<TData, TValue> extends React.ComponentProps<typeof DropdownMenuTrigger> {
@@ -1297,7 +1327,7 @@ declare function DataTableColumnHeader<TData, TValue>({
   label,
   className,
   ...props
-}: DataTableColumnHeaderProps<TData, TValue>): react_jsx_runtime6.JSX.Element;
+}: DataTableColumnHeaderProps<TData, TValue>): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table-faceted-filter.d.ts
 interface DataTableFacetedFilterProps<TData, TValue> {
@@ -1311,7 +1341,7 @@ declare function DataTableFacetedFilter<TData, TValue>({
   title,
   options,
   multiple
-}: DataTableFacetedFilterProps<TData, TValue>): react_jsx_runtime6.JSX.Element;
+}: DataTableFacetedFilterProps<TData, TValue>): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table-pagination.d.ts
 interface DataTablePaginationProps<TData> extends React.ComponentProps<"div"> {
@@ -1323,7 +1353,7 @@ declare function DataTablePagination<TData>({
   pageSizeOptions,
   className,
   ...props
-}: DataTablePaginationProps<TData>): react_jsx_runtime6.JSX.Element;
+}: DataTablePaginationProps<TData>): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table-toolbar.d.ts
 interface DataTableToolbarProps<TData> extends React$1.ComponentProps<"div"> {
@@ -1334,7 +1364,7 @@ declare function DataTableToolbar<TData>({
   children,
   className,
   ...props
-}: DataTableToolbarProps<TData>): react_jsx_runtime6.JSX.Element;
+}: DataTableToolbarProps<TData>): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/components/data-table/data-table-view-options.d.ts
 interface DataTableViewOptionsProps<TData> extends React$1.ComponentProps<typeof PopoverContent> {
@@ -1345,7 +1375,7 @@ declare function DataTableViewOptions<TData>({
   table,
   disabled,
   ...props
-}: DataTableViewOptionsProps<TData>): react_jsx_runtime6.JSX.Element;
+}: DataTableViewOptionsProps<TData>): react_jsx_runtime3.JSX.Element;
 //#endregion
 //#region src/hooks/use-data-table.d.ts
 interface UseDataTableProps<TData> extends Omit<TableOptions<TData>, "state" | "pageCount" | "getCoreRowModel" | "manualFiltering" | "manualPagination" | "manualSorting">, Required<Pick<TableOptions<TData>, "pageCount">> {
@@ -1512,6 +1542,7 @@ interface ListParams {
     id: string;
     desc: boolean;
   }>;
+  search?: string;
   filters?: Array<{
     id: string;
     value: any;

package/dist/index.d.ts

@@ -125,6 +125,10 @@ interface UseAutoCrudResourceReturn<TSchema extends z.ZodObject<z.ZodRawShape>,
     /** 是否正在获取数据（用于显示微妙的加载指示器） */
     isFetching: boolean;
   };
+  /** Optional schema override from host metadata. */
+  schema?: z.ZodObject<z.ZodRawShape>;
+  /** Optional field config override from host metadata. */
+  fields?: Fields;
   modal: ModalState<TListItem>;
   mutations: {
     isCreating: boolean;
@@ -182,6 +186,10 @@ interface CrudRouter {
   export?: {
     useQuery: (input?: any, opts?: any) => any;
   };
+  /** 元数据路由（query，由 createCrudRouter 自动生成） */
+  meta?: {
+    useQuery: (input?: any, opts?: any) => any;
+  };
 }
 /**
  * 自动生成的查询参数（由内部 URL 状态管理生成）
@@ -193,6 +201,7 @@ interface AutoQueryParams {
     id: string;
     desc: boolean;
   }>;
+  search?: string;
   filters: any[];
   joinOperator: "and" | "or";
 }
@@ -379,6 +388,7 @@ interface ParsedZodField {
 type ColumnOverrides<T> = Partial<{ [K in keyof T]: Partial<ColumnDef<T, unknown>> & {
   hidden?: boolean;
   label?: string;
+  index?: number;
 } }>;
 /**
  * Formily Schema 覆盖选项
@@ -473,6 +483,10 @@ interface AutoTableProps<T extends z.ZodObject<z.ZodRawShape>> {
    * 默认: ["simple", "advanced", "command"] (全部显示)
    */
   filterMode?: FilterMode | FilterMode[];
+  /** 全局搜索框 */
+  search?: boolean | {
+    placeholder?: string;
+  };
   /** 批量删除回调 */
   onDeleteSelected?: (rows: z.infer<T>[]) => void;
   /** 批量更新回调 */
@@ -504,6 +518,7 @@ declare function AutoTable<T extends z.ZodObject<z.ZodRawShape>>({
   actions,
   pinnedColumns,
   filterMode,
+  search,
   onDeleteSelected,
   onUpdateSelected,
   batchUpdateFields,
@@ -629,6 +644,8 @@ interface FilterConfig {
   unit?: string;
   /** 过滤器占位符 */
   placeholder?: string;
+  /** 排序权重，数值越小越靠前 */
+  index?: number;
   /** 是否在筛选栏中隐藏（隐藏筛选但不影响表格列显示） */
   hidden?: boolean;
   /** 控制在哪些筛选模式下显示（未设置则在所有模式显示） */
@@ -643,6 +660,8 @@ interface Field {
   label?: string;
   /** 是否隐藏（表格和表单都隐藏） */
   hidden?: boolean;
+  /** 是否参与 AutoCrud 全局搜索 */
+  search?: boolean;
   /**
    * 筛选器独立配置
    * - FilterConfig: 详细配置
@@ -658,6 +677,8 @@ interface Field {
   table?: {
     /** 是否在表格中隐藏 */
     hidden?: boolean;
+    /** 排序权重，数值越小越靠前 */
+    index?: number;
     /** 筛选器配置 */
     meta?: Record<string, unknown>;
     /** 其他列配置 */
@@ -734,6 +755,8 @@ type ToolbarActionConfig = ToolbarActionItem[] | ((defaults: ToolbarBuiltinActio
  * AutoCrudTable Props 接口
  */
 interface AutoCrudTableProps<TSchema extends z.ZodObject<z.ZodRawShape>> {
+  /** Public CRUD id. Used by hosts to document the extension target. */
+  id?: string;
   /** 页面标题 */
   title?: string;
   /** 页面描述 */
@@ -759,6 +782,10 @@ interface AutoCrudTableProps<TSchema extends z.ZodObject<z.ZodRawShape>> {
      * - 数组: 第一个为默认值，显示切换按钮
      */
     filterModes?: FilterMode | FilterMode[];
+    /** 全局搜索框；默认在存在 search: true 字段时显示 */
+    search?: boolean | {
+      placeholder?: string;
+    };
     /**
      * 批量更新字段配置
      * - 只需传字段名数组，options 自动从 schema enum 推导
@@ -1093,12 +1120,12 @@ declare const filterItemSchema: z.ZodObject<{
   variant: z.ZodEnum<{
     number: "number";
     boolean: "boolean";
-    date: "date";
     text: "text";
+    range: "range";
+    date: "date";
+    dateRange: "dateRange";
     select: "select";
     multiSelect: "multiSelect";
-    dateRange: "dateRange";
-    range: "range";
   }>;
   operator: z.ZodEnum<{
     iLike: "iLike";
@@ -1128,6 +1155,7 @@ declare module "@tanstack/react-table" {
   }
   interface ColumnMeta<TData extends RowData, TValue> {
     label?: string;
+    index?: number;
     placeholder?: string;
     variant?: FilterVariant$1;
     options?: Option[];
@@ -1171,12 +1199,14 @@ interface AutoTableSimpleFiltersProps<TData> {
   shallow?: boolean;
   filters?: ExtendedColumnFilter<TData>[];
   onFiltersChange?: (filters: ExtendedColumnFilter<TData>[]) => void;
+  leading?: React$1.ReactNode;
 }
 declare function AutoTableSimpleFilters<TData>({
   table,
   shallow,
   filters: externalFilters,
-  onFiltersChange
+  onFiltersChange,
+  leading
 }: AutoTableSimpleFiltersProps<TData>): react_jsx_runtime2.JSX.Element | null;
 //#endregion
 //#region src/components/auto-crud/form-modal.d.ts
@@ -1512,6 +1542,7 @@ interface ListParams {
     id: string;
     desc: boolean;
   }>;
+  search?: string;
   filters?: Array<{
     id: string;
     value: any;

package/dist/index.js

@@ -2,7 +2,7 @@ import * as React from "react";
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useReducer, useRef } from "react";
 import { ArrowDownUp, BadgeCheck, CalendarIcon, Check, CheckCircle2, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, ChevronsLeft, ChevronsRight, ChevronsUpDown, CommandIcon, Download, Ellipsis, EyeOff, FileDown, FileSpreadsheetIcon, GripVertical, ListFilter, ListFilterIcon, Loader2, PlusCircle, Settings2, Text, Trash2, Upload, X, XCircle } from "lucide-react";
 import { flexRender, getCoreRowModel, getFacetedMinMaxValues, getFacetedRowModel, getFacetedUniqueValues, getFilteredRowModel, getPaginationRowModel, getSortedRowModel, useReactTable } from "@tanstack/react-table";
-import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, Badge, Button, Calendar, Checkbox, Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuTrigger, Input, Label, Popover, PopoverContent, PopoverTrigger, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, Separator, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, Slider, Switch } from "@pixpilot/shadcn";
+import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogTitle, Badge, Button, Calendar, Checkbox, Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuTrigger, Input, Label, Popover, PopoverContent, PopoverTrigger, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, Separator, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, Slider, Switch, cn as cn$1 } from "@pixpilot/shadcn";
 import { clsx } from "clsx";
 import { twMerge } from "tailwind-merge";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
@@ -18,6 +18,7 @@ import { z } from "zod";
 import { createForm } from "@formily/core";
 import { Form, JsonSchemaField } from "@pixpilot/formily-shadcn";
 import { connect, mapProps } from "@formily/react";
+import { Combobox } from "@pixpilot/shadcn-ui";
 import { toast } from "sonner";
 
 //#region src/lib/utils.ts
@@ -2663,8 +2664,17 @@ function DataTableViewOptions({ table, disabled,...props }) {
 
 //#endregion
 //#region src/components/auto-crud/auto-table-simple-filters.tsx
-function AutoTableSimpleFilters({ table, shallow = false, filters: externalFilters, onFiltersChange }) {
-	const columns = React.useMemo(() => table.getAllColumns().filter((col) => col.getCanFilter()), [table]);
+function AutoTableSimpleFilters({ table, shallow = false, filters: externalFilters, onFiltersChange, leading }) {
+	const columns = React.useMemo(() => table.getAllColumns().filter((col) => col.getCanFilter()).sort((a, b) => {
+		const readOrder = (column) => {
+			const metaIndex = column.columnDef.meta?.index;
+			const columnIndex = column.columnDef.index;
+			return typeof metaIndex === "number" ? metaIndex : typeof columnIndex === "number" ? columnIndex : 1e4;
+		};
+		const orderDiff = readOrder(a) - readOrder(b);
+		if (orderDiff !== 0) return orderDiff;
+		return a.getIndex() - b.getIndex();
+	}), [table]);
 	const queryStateOptions = table.options.meta?.queryStateOptions;
 	const [queryFilters, setQueryFilters] = useReadableFilters(columns, {
 		...queryStateOptions,
@@ -2781,8 +2791,9 @@ function AutoTableSimpleFilters({ table, shallow = false, filters: externalFilte
 	if (!mounted) return null;
 	return /* @__PURE__ */ jsxs("div", {
 		ref: containerRef,
-		className: "flex flex-wrap items-center gap-2 min-w-0",
+		className: "flex flex-1 flex-wrap items-center gap-2 min-w-0",
 		children: [
+			leading,
 			filterColumns.map((column, index) => {
 				const meta = column.columnDef.meta;
 				const value = getFilterValue(column.id);
@@ -3915,7 +3926,7 @@ function createTableSchema(schema, options) {
 		if (cached) return [...cached];
 	}
 	const shape = schema.shape;
-	const columns = [];
+	const columnEntries = [];
 	for (const [key, fieldSchema] of Object.entries(shape)) {
 		if (exclude.includes(key)) continue;
 		const override = overrides?.[key];
@@ -3936,20 +3947,31 @@ function createTableSchema(schema, options) {
 			options: override?.meta?.options ?? autoOptions
 		};
 		const { meta: _ignoredMeta,...restOverride } = override ?? {};
-		columns.push({
-			id: key,
-			accessorKey: key,
-			header: ({ column }) => /* @__PURE__ */ jsx(DataTableColumnHeader, {
-				column,
-				label
-			}),
-			cell: ({ row }) => renderCell(row.getValue(key), parsed.type),
-			enableColumnFilter: true,
-			enableSorting: true,
-			meta,
-			...restOverride
+		const sourceIndex = columnEntries.length;
+		const order = typeof restOverride.index === "number" ? restOverride.index : typeof meta.index === "number" ? meta.index : 1e4 + sourceIndex;
+		columnEntries.push({
+			order,
+			sourceIndex,
+			column: {
+				id: key,
+				accessorKey: key,
+				header: ({ column }) => /* @__PURE__ */ jsx(DataTableColumnHeader, {
+					column,
+					label
+				}),
+				cell: ({ row }) => renderCell(row.getValue(key), parsed.type),
+				enableColumnFilter: true,
+				enableSorting: true,
+				meta,
+				...restOverride
+			}
 		});
 	}
+	const columns = columnEntries.sort((a, b) => {
+		const orderDiff = a.order - b.order;
+		if (orderDiff !== 0) return orderDiff;
+		return a.sourceIndex - b.sourceIndex;
+	}).map((entry) => entry.column);
 	if (canCache) baseTableSchemaCache.set(schema, columns);
 	return columns;
 }
@@ -4621,10 +4643,19 @@ const filterModeConfig = {
 		tooltip: "Linear-style command filters"
 	}
 };
-function AutoTable({ schema, data, pageCount = 1, overrides, enableRowSelection = true, exclude, actions, pinnedColumns, filterMode = "simple", onDeleteSelected, onUpdateSelected, batchUpdateFields, actionBarExtra, actionBarActions, initialSorting, enableExport = true, showDefaultExport = true, onSelectedCountChange, getSelectedRows }) {
+function AutoTable({ schema, data, pageCount = 1, overrides, enableRowSelection = true, exclude, actions, pinnedColumns, filterMode = "simple", search = false, onDeleteSelected, onUpdateSelected, batchUpdateFields, actionBarExtra, actionBarActions, initialSorting, enableExport = true, showDefaultExport = true, onSelectedCountChange, getSelectedRows }) {
 	const modes = filterMode ? Array.isArray(filterMode) ? filterMode : [filterMode] : DEFAULT_MODES;
 	const [currentMode, setCurrentMode] = useQueryState("filterMode", parseAsStringEnum(modes).withDefault(modes[0] ?? "simple"));
 	const showToggle = modes.length > 1;
+	const [searchValue, setSearchValue] = useUrlState("search", parseAsString.withDefault(""), {
+		shallow: false,
+		clearOnDefault: true
+	});
+	const [, setSearchPage] = useUrlState("page", parseAsInteger.withDefault(1), {
+		shallow: false,
+		clearOnDefault: true
+	});
+	const searchConfig = search && typeof search === "object" ? search : {};
 	const { table, shallow, debounceMs, throttleMs } = useDataTable({
 		data,
 		columns: useMemo(() => {
@@ -4696,11 +4727,21 @@ function AutoTable({ schema, data, pageCount = 1, overrides, enableRowSelection
 			})
 		})
 	})] }) : null;
+	const searchInput = search ? /* @__PURE__ */ jsx(Input, {
+		value: searchValue,
+		onChange: (event) => {
+			setSearchValue(event.target.value);
+			setSearchPage(1);
+		},
+		placeholder: searchConfig.placeholder ?? "搜索",
+		className: "h-8 w-48 shrink-0"
+	}) : null;
 	const filtersContent = useMemo(() => {
 		switch (currentMode) {
 			case "simple": return /* @__PURE__ */ jsx(AutoTableSimpleFilters, {
 				table,
-				shallow
+				shallow,
+				leading: searchInput
 			});
 			case "command": return /* @__PURE__ */ jsx(DataTableFilterMenu, {
 				table,
@@ -4720,6 +4761,7 @@ function AutoTable({ schema, data, pageCount = 1, overrides, enableRowSelection
 		currentMode,
 		table,
 		shallow,
+		searchInput,
 		debounceMs,
 		throttleMs
 	]);
@@ -4731,10 +4773,14 @@ function AutoTable({ schema, data, pageCount = 1, overrides, enableRowSelection
 				children: [/* @__PURE__ */ jsxs("div", {
 					className: "flex flex-1 items-start gap-2 min-h-[40px]",
 					"data-filter-parent": true,
-					children: [currentMode !== "simple" && /* @__PURE__ */ jsx(DataTableSortList, {
-						table,
-						align: "start"
-					}), filtersContent]
+					children: [
+						currentMode !== "simple" && searchInput,
+						currentMode !== "simple" && /* @__PURE__ */ jsx(DataTableSortList, {
+							table,
+							align: "start"
+						}),
+						filtersContent
+					]
 				}), /* @__PURE__ */ jsxs("div", {
 					className: "flex items-center gap-2",
 					children: [
@@ -4923,10 +4969,44 @@ function createEditFormSchema(schema, options) {
 
 //#endregion
 //#region src/components/auto-crud/auto-form.tsx
+const COMBOBOX_LIST_CLASS = "[&_[cmdk-list]]:max-h-[360px]";
 const FormilySwitch = connect(Switch, mapProps({
 	value: "checked",
 	onInput: "onCheckedChange"
 }));
+const FormilyCombobox = connect(AutoCrudCombobox, mapProps({ dataSource: "options" }));
+function AutoCrudCombobox({ options = [], filter, className,...props }) {
+	const resolvedFilter = useMemo(() => {
+		if (typeof filter === "function") return filter;
+		return createComboboxFilter(options);
+	}, [filter, options]);
+	return /* @__PURE__ */ jsx(Combobox, {
+		...props,
+		options,
+		filter: resolvedFilter,
+		className: cn$1(COMBOBOX_LIST_CLASS, className)
+	});
+}
+function createComboboxFilter(options) {
+	const searchTextByValue = new Map(options.map((option) => [option.value, collectSearchText(option.value, option.label, option.searchText, option.keywords).toLocaleLowerCase()]));
+	return (value, search, keywords) => {
+		const query = search.trim().toLocaleLowerCase();
+		if (!query) return 1;
+		const searchText = collectSearchText(searchTextByValue.get(value), keywords).toLocaleLowerCase();
+		if (searchText === query) return 2;
+		return searchText.includes(query) ? 1 : 0;
+	};
+}
+function collectSearchText(...parts) {
+	const texts = [];
+	for (const part of parts) {
+		if (!part) continue;
+		if (Array.isArray(part)) texts.push(...part.map(String));
+		else if (typeof part === "object") texts.push(...Object.values(part).filter(Boolean).map(String));
+		else texts.push(String(part));
+	}
+	return texts.join(" ");
+}
 function AutoFormInner({ schema: zodSchema, initialValues, onSubmit, overrides, mode = "create", loading = false, gridColumns = 1, labelAlign = "top", labelWidth, showSubmitButton = true }, ref) {
 	const form = useMemo(() => createForm({ initialValues }), [JSON.stringify(initialValues)]);
 	const formSchema = useMemo(() => createEditFormSchema(zodSchema, {
@@ -4951,10 +5031,16 @@ function AutoFormInner({ schema: zodSchema, initialValues, onSubmit, overrides,
 		form,
 		children: [/* @__PURE__ */ jsx(JsonSchemaField, {
 			schema: formSchema,
-			components: { fields: { Switch: {
-				component: FormilySwitch,
-				decorator: "FormItem"
-			} } }
+			components: { fields: {
+				Combobox: {
+					component: FormilyCombobox,
+					decorator: "FormItem"
+				},
+				Switch: {
+					component: FormilySwitch,
+					decorator: "FormItem"
+				}
+			} }
 		}), showSubmitButton && /* @__PURE__ */ jsx("div", {
 			className: "flex justify-end gap-2 mt-6",
 			children: /* @__PURE__ */ jsx(Button, {
@@ -6046,6 +6132,11 @@ function resolveActions(actionsOrFn, defaults, rowActionsLocale) {
 */
 function AutoCrudTable({ title, description, schema, resource, fields, table: tableConfig, form: formConfig, permissions, actions: actionItems, toolbarActions, locale: localeProp, onCreate }) {
 	const locale = resolveLocale(localeProp);
+	const resolvedSchema = resource.schema ?? schema;
+	const resolvedFields = React.useMemo(() => ({
+		...fields,
+		...resource.fields
+	}), [fields, resource.fields]);
 	const can = {
 		create: permissions?.can?.create ?? true,
 		update: permissions?.can?.update ?? true,
@@ -6061,10 +6152,10 @@ function AutoCrudTable({ title, description, schema, resource, fields, table: ta
 	const [exporting, setExporting] = React.useState(false);
 	const getSelectedRowsRef = React.useRef(null);
 	const importColumns = React.useMemo(() => {
-		const shape = schema.shape;
+		const shape = resolvedSchema.shape;
 		const denySet = new Set(denyFields ?? []);
 		return Object.keys(shape).filter((key) => !denySet.has(key));
-	}, [schema, denyFields]);
+	}, [resolvedSchema, denyFields]);
 	const handleExport = React.useCallback(async (mode) => {
 		const filename = title ?? "export";
 		const excludeColumns = denyFields;
@@ -6096,21 +6187,34 @@ function AutoCrudTable({ title, description, schema, resource, fields, table: ta
 			setExporting(false);
 		}
 	}, [selectedCount, handleExport]);
-	const tableOverrides = React.useMemo(() => buildTableOverrides(fields, tableConfig?.overrides), [fields, tableConfig?.overrides]);
-	const formOverrides = React.useMemo(() => buildFormOverrides(fields, formConfig?.overrides, denyFields), [
-		fields,
+	const tableOverrides = React.useMemo(() => buildTableOverrides(resolvedFields, tableConfig?.overrides), [resolvedFields, tableConfig?.overrides]);
+	const formOverrides = React.useMemo(() => buildFormOverrides(resolvedFields, formConfig?.overrides, denyFields), [
+		resolvedFields,
 		formConfig?.overrides,
 		denyFields
 	]);
-	const hiddenColumns = React.useMemo(() => buildHiddenColumns(fields, tableConfig?.hidden, denyFields), [
-		fields,
+	const hiddenColumns = React.useMemo(() => buildHiddenColumns(resolvedFields, tableConfig?.hidden, denyFields), [
+		resolvedFields,
 		tableConfig?.hidden,
 		denyFields
 	]);
-	const batchFields = React.useMemo(() => buildBatchUpdateFields(schema, tableConfig?.batchFields, fields), [
-		schema,
+	const searchConfig = React.useMemo(() => {
+		const tableSearch = tableConfig?.search;
+		if (tableSearch === false) return false;
+		if (tableSearch && typeof tableSearch === "object") return tableSearch;
+		return Object.values(resolvedFields).some((field) => field?.search === true) ? true : false;
+	}, [resolvedFields, tableConfig?.search]);
+	const batchFields = React.useMemo(() => buildBatchUpdateFields(resolvedSchema, tableConfig?.batchFields, resolvedFields), [
+		resolvedSchema,
 		tableConfig?.batchFields,
-		fields
+		resolvedFields
+	]);
+	const formInitialValues = React.useMemo(() => {
+		return resource.modal.createOpen ? resource.modal.copySource ?? void 0 : resource.modal.selected ?? void 0;
+	}, [
+		resource.modal.createOpen,
+		resource.modal.copySource,
+		resource.modal.selected
 	]);
 	return /* @__PURE__ */ jsxs("div", {
 		className: "space-y-4",
@@ -6191,11 +6295,12 @@ function AutoCrudTable({ title, description, schema, resource, fields, table: ta
 			}),
 			/* @__PURE__ */ jsx(AutoTable, {
 				data: resource.tableData.data,
-				schema,
+				schema: resolvedSchema,
 				pageCount: resource.tableData.pageCount,
 				overrides: tableOverrides,
 				exclude: hiddenColumns,
 				filterMode: tableConfig?.filterModes,
+				search: searchConfig,
 				actions: resolveActions(actionItems, {
 					openView: resource.handlers.openView,
 					openEdit: can.update ? resource.handlers.openEdit : void 0,
@@ -6216,8 +6321,8 @@ function AutoCrudTable({ title, description, schema, resource, fields, table: ta
 				open: resource.modal.createOpen || resource.modal.editOpen,
 				onOpenChange: (open) => !open && resource.handlers.closeModals(),
 				mode: resource.modal.createOpen ? "create" : "edit",
-				schema,
-				initialValues: resource.modal.createOpen ? resource.modal.copySource ?? void 0 : resource.modal.selected ?? void 0,
+				schema: resolvedSchema,
+				initialValues: formInitialValues,
 				onSubmit: (values) => {
 					if (resource.modal.createOpen) resource.handlers.submitCreate(values);
 					else resource.handlers.submitUpdate(values);
@@ -6234,8 +6339,8 @@ function AutoCrudTable({ title, description, schema, resource, fields, table: ta
 				onOpenChange: (open) => !open && resource.handlers.closeModals(),
 				variant: resource.modal.variant,
 				data: resource.modal.selected,
-				schema,
-				fields,
+				schema: resolvedSchema,
+				fields: resolvedFields,
 				denyFields,
 				locale
 			}),
@@ -6954,6 +7059,53 @@ const noopToastAdapter = {
 	info: () => {},
 	warning: () => {}
 };
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isJsonSchemaObject(value) {
+	return isRecord(value) && isRecord(value.properties);
+}
+function readJsonSchemaType(property) {
+	return Array.isArray(property.type) ? property.type.find((item) => item !== "null") : property.type;
+}
+function jsonPropertyToZod(property, required) {
+	const enumValues = property.enum?.filter((value) => typeof value === "string");
+	let schema;
+	if (enumValues && enumValues.length > 0) schema = z.enum(enumValues);
+	else switch (readJsonSchemaType(property)) {
+		case "number":
+		case "integer":
+			schema = z.number();
+			break;
+		case "boolean":
+			schema = z.boolean();
+			break;
+		case "array":
+			schema = z.array(z.unknown());
+			break;
+		case "object":
+			schema = z.record(z.string(), z.unknown());
+			break;
+		case "string":
+			schema = property.format === "date" || property.format === "date-time" ? z.coerce.date() : z.string();
+			break;
+		default: schema = z.unknown();
+	}
+	return required ? schema : schema.optional();
+}
+function mergeMetadataSchema(baseSchema, metadataSchema) {
+	if (!isJsonSchemaObject(metadataSchema)) return baseSchema;
+	const required = new Set(Array.isArray(metadataSchema.required) ? metadataSchema.required.filter((field) => typeof field === "string") : []);
+	const extensionShape = {};
+	for (const [field, property] of Object.entries(metadataSchema.properties ?? {})) {
+		if (field in baseSchema.shape) continue;
+		extensionShape[field] = jsonPropertyToZod(property, required.has(field));
+	}
+	return Object.keys(extensionShape).length > 0 ? baseSchema.extend(extensionShape) : baseSchema;
+}
+function readMetadataFields(fields) {
+	return isRecord(fields) ? fields : void 0;
+}
 /**
 * Modal 状态 Reducer
 */
@@ -7012,12 +7164,16 @@ function useAutoCrudResource({ router, schema, query: queryTransform, options =
 	useEffect(() => {
 		hooksRef.current = hooks;
 	}, [hooks]);
-	const columns = useMemo(() => createTableSchema(schema), [schema]);
+	const metadata = (router.meta?.useQuery(void 0, { staleTime: 3e4 }))?.data;
+	const resolvedSchema = useMemo(() => mergeMetadataSchema(schema, metadata?.schema), [schema, metadata?.schema]);
+	const metadataFields = useMemo(() => readMetadataFields(metadata?.fields), [metadata?.fields]);
+	const columns = useMemo(() => createTableSchema(resolvedSchema), [resolvedSchema]);
 	const [urlParams] = useQueryStates({
 		page: parseAsInteger.withDefault(1),
 		perPage: parseAsInteger.withDefault(10),
 		sort: getSortingStateParser().withDefault([]),
-		joinOperator: parseAsStringEnum(["and", "or"]).withDefault("and")
+		joinOperator: parseAsStringEnum(["and", "or"]).withDefault("and"),
+		search: parseAsString.withDefault("")
 	}, { shallow: false });
 	const [filters] = useReadableFilters(columns, { shallow: false });
 	const queryInput = useMemo(() => {
@@ -7026,7 +7182,8 @@ function useAutoCrudResource({ router, schema, query: queryTransform, options =
 			perPage: urlParams.perPage,
 			sort: urlParams.sort,
 			filters,
-			joinOperator: urlParams.joinOperator
+			joinOperator: urlParams.joinOperator,
+			...urlParams.search.trim() ? { search: urlParams.search.trim() } : {}
 		};
 		return queryTransform ? queryTransform(autoParams) : autoParams;
 	}, [
@@ -7038,6 +7195,7 @@ function useAutoCrudResource({ router, schema, query: queryTransform, options =
 		placeholderData: keepPreviousData,
 		staleTime: 0
 	});
+	const tableRows = listQuery.data?.data ?? [];
 	const createMutation = router.create.useMutation();
 	const updateMutation = router.update.useMutation();
 	const deleteMutation = router.delete.useMutation();
@@ -7290,11 +7448,13 @@ function useAutoCrudResource({ router, schema, query: queryTransform, options =
 	const canExport = !!(exportFetcher || exportQuery);
 	return {
 		tableData: {
-			data: listQuery.data?.data ?? [],
+			data: tableRows,
 			pageCount: listQuery.data?.pageCount ?? 0,
 			isLoading: listQuery.isLoading,
 			isFetching: listQuery.isFetching
 		},
+		schema: resolvedSchema,
+		fields: metadataFields,
 		modal,
 		mutations: {
 			isCreating: createMutation.isPending,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wordrhyme/auto-crud",
   "type": "module",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Schema-first CRUD components with auto-generated tables and forms",
   "author": "wordrhyme",
   "license": "MIT",
@@ -66,8 +66,8 @@
     "tailwind-merge": "^3.5.0",
     "vaul": "^1.1.2",
     "@pixpilot/formily-shadcn": "1.11.20",
-    "@pixpilot/shadcn": "1.2.7",
-    "@pixpilot/shadcn-ui": "1.21.1"
+    "@pixpilot/shadcn-ui": "1.21.1",
+    "@pixpilot/shadcn": "1.2.7"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.90.15",
@@ -82,11 +82,11 @@
     "react-dom": "19.2.4",
     "tsdown": "^0.15.12",
     "typescript": "^5.9.3",
-    "@internal/prettier-config": "0.0.1",
-    "@internal/tsconfig": "0.1.0",
     "@internal/eslint-config": "0.3.0",
-    "@internal/vitest-config": "0.1.0",
-    "@internal/tsdown-config": "0.1.0"
+    "@internal/tsconfig": "0.1.0",
+    "@internal/tsdown-config": "0.1.0",
+    "@internal/prettier-config": "0.0.1",
+    "@internal/vitest-config": "0.1.0"
   },
   "prettier": "@internal/prettier-config",
   "scripts": {