@wordrhyme/auto-crud 1.14.2 → 1.14.3

package/README.md

@@ -357,6 +357,8 @@ const resource = useAutoCrudResource({
 
 未配置的参数名保留默认值。搜索仍使用共享的 `search` 参数，字段筛选仍使用字段名；`queryKeys` 不隔离这些值。筛选或搜索变化时，仅重置该表格对应的页码。直接使用 `AutoTable` 时传入相同的 `queryKeys`；`table.queryKeys` 可覆盖资源提供的整组配置。
 
+全局搜索输入立即显示，停止输入 200ms 后提交查询并回到第一页；清空立即提交，中文输入法组词期间不查询。可以通过 `table.search: { debounceMs: 0 }` 恢复即时查询，或指定其他延时；直接使用 `AutoTable` 时配置 `search.debounceMs`。浏览器导航或其他 URL 状态变化会取消尚未提交的搜索，并按 URL 恢复输入框。
+
 `enableRowSelection` 默认 `true`，设为 `false` 后关闭行选择并隐藏选择列和批量操作栏。`initialColumnVisibility` 只设置首次显示的列，用户仍可通过列设置切换；它不同于 `table.hidden` 对列的排除。
 
 ### `useAutoCrudResource()`

package/dist/index.cjs

@@ -1166,11 +1166,15 @@ function useCallbackRef(callback) {
 function useDebouncedCallback(callback, delay) {
 	const handleCallback = useCallbackRef(callback);
 	const debounceTimerRef = react.useRef(0);
-	react.useEffect(() => () => window.clearTimeout(debounceTimerRef.current), []);
-	return react.useCallback((...args) => {
+	const cancel = react.useCallback(() => {
+		window.clearTimeout(debounceTimerRef.current);
+	}, []);
+	react.useEffect(() => cancel, [cancel, delay]);
+	const setValue = react.useCallback((...args) => {
 		window.clearTimeout(debounceTimerRef.current);
 		debounceTimerRef.current = window.setTimeout(() => handleCallback(...args), delay);
 	}, [handleCallback, delay]);
+	return Object.assign(setValue, { cancel });
 }
 
 //#endregion
@@ -4015,6 +4019,57 @@ function SimpleDateFilter({ title, maxDate, multiple, value, onChange }) {
 	});
 }
 
+//#endregion
+//#region src/components/auto-crud/auto-table-search.tsx
+function AutoTableSearch({ placeholder = "搜索", debounceMs = 200, pageKey = "page" }) {
+	const [value, setValue] = (0, react.useState)(() => getUrlParams().get("search") ?? "");
+	const composing = (0, react.useRef)(false);
+	const commit = (0, react.useCallback)((next) => {
+		const params = getUrlParams();
+		if ((params.get("search") ?? "") === next) return;
+		if (next) params.set("search", next);
+		else params.delete("search");
+		params.delete(pageKey);
+		setSearchParams(params);
+	}, [pageKey]);
+	const debouncedCommit = useDebouncedCallback(commit, debounceMs);
+	const { cancel } = debouncedCommit;
+	(0, react.useEffect)(() => {
+		const sync = () => {
+			cancel();
+			setValue(getUrlParams().get("search") ?? "");
+		};
+		window.addEventListener("popstate", sync);
+		window.addEventListener("urlchange", sync);
+		return () => {
+			cancel();
+			window.removeEventListener("popstate", sync);
+			window.removeEventListener("urlchange", sync);
+		};
+	}, [cancel, pageKey]);
+	const change = (next) => {
+		setValue(next);
+		cancel();
+		if (composing.current) return;
+		if (!next || debounceMs <= 0) commit(next);
+		else debouncedCommit(next);
+	};
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__wordrhyme_shadcn.Input, {
+		value,
+		onChange: (event) => change(event.target.value),
+		onCompositionStart: () => {
+			composing.current = true;
+			cancel();
+		},
+		onCompositionEnd: (event) => {
+			composing.current = false;
+			change(event.currentTarget.value);
+		},
+		placeholder,
+		className: "h-8 w-48 shrink-0"
+	});
+}
+
 //#endregion
 //#region src/components/data-table/data-table-column-header.tsx
 function DataTableColumnHeader({ column, label, className,...props }) {
@@ -5194,14 +5249,6 @@ function AutoTable({ schema, data, getRowId, expandedRow, defaultExpanded = fals
 	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(queryKeys?.page ?? "page", parseAsInteger.withDefault(1), {
-		shallow: false,
-		clearOnDefault: true
-	});
 	const searchConfig = search && typeof search === "object" ? search : {};
 	const enableAdvancedFilter = true;
 	const { columns, expandColumnId } = (0, react.useMemo)(() => {
@@ -5363,14 +5410,9 @@ function AutoTable({ schema, data, getRowId, expandedRow, defaultExpanded = fals
 			})
 		})
 	})] }) : null;
-	const searchInput = search ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__wordrhyme_shadcn.Input, {
-		value: searchValue,
-		onChange: (event) => {
-			setSearchValue(event.target.value);
-			setSearchPage(1);
-		},
-		placeholder: searchConfig.placeholder ?? "搜索",
-		className: "h-8 w-48 shrink-0"
+	const searchInput = search ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AutoTableSearch, {
+		...searchConfig,
+		pageKey: queryKeys?.page
 	}) : null;
 	const filtersContent = (0, react.useMemo)(() => {
 		switch (currentMode) {

package/dist/index.d.cts

@@ -1042,6 +1042,8 @@ interface AutoTableProps<T extends z.ZodObject<z.ZodRawShape>> extends Pick<Data
   /** 全局搜索框 */
   search?: boolean | {
     placeholder?: string;
+    /** Search delay in milliseconds. Defaults to 200; use 0 for immediate queries. */
+    debounceMs?: number;
   };
   /** Extra table controls rendered between sorting and column visibility. */
   toolbarExtra?: React.ReactNode;
@@ -1515,9 +1517,7 @@ interface AutoCrudTableProps<TSchema extends z.ZodObject<z.ZodRawShape>> {
      */
     filterModes?: FilterMode | FilterMode[];
     /** 全局搜索框；默认在存在 search: true 字段时显示 */
-    search?: boolean | {
-      placeholder?: string;
-    };
+    search?: AutoTableProps<TSchema>['search'];
     /**
      * 批量更新字段配置
      * - 只需传字段名数组，options 自动从 schema enum 推导

package/dist/index.d.ts

@@ -1042,6 +1042,8 @@ interface AutoTableProps<T extends z.ZodObject<z.ZodRawShape>> extends Pick<Data
   /** 全局搜索框 */
   search?: boolean | {
     placeholder?: string;
+    /** Search delay in milliseconds. Defaults to 200; use 0 for immediate queries. */
+    debounceMs?: number;
   };
   /** Extra table controls rendered between sorting and column visibility. */
   toolbarExtra?: React.ReactNode;
@@ -1515,9 +1517,7 @@ interface AutoCrudTableProps<TSchema extends z.ZodObject<z.ZodRawShape>> {
      */
     filterModes?: FilterMode | FilterMode[];
     /** 全局搜索框；默认在存在 search: true 字段时显示 */
-    search?: boolean | {
-      placeholder?: string;
-    };
+    search?: AutoTableProps<TSchema>['search'];
     /**
      * 批量更新字段配置
      * - 只需传字段名数组，options 自动从 schema enum 推导

package/dist/index.js

@@ -1150,11 +1150,15 @@ function useCallbackRef(callback) {
 function useDebouncedCallback(callback, delay) {
 	const handleCallback = useCallbackRef(callback);
 	const debounceTimerRef = React.useRef(0);
-	React.useEffect(() => () => window.clearTimeout(debounceTimerRef.current), []);
-	return React.useCallback((...args) => {
+	const cancel = React.useCallback(() => {
+		window.clearTimeout(debounceTimerRef.current);
+	}, []);
+	React.useEffect(() => cancel, [cancel, delay]);
+	const setValue = React.useCallback((...args) => {
 		window.clearTimeout(debounceTimerRef.current);
 		debounceTimerRef.current = window.setTimeout(() => handleCallback(...args), delay);
 	}, [handleCallback, delay]);
+	return Object.assign(setValue, { cancel });
 }
 
 //#endregion
@@ -3999,6 +4003,57 @@ function SimpleDateFilter({ title, maxDate, multiple, value, onChange }) {
 	});
 }
 
+//#endregion
+//#region src/components/auto-crud/auto-table-search.tsx
+function AutoTableSearch({ placeholder = "搜索", debounceMs = 200, pageKey = "page" }) {
+	const [value, setValue] = useState(() => getUrlParams().get("search") ?? "");
+	const composing = useRef(false);
+	const commit = useCallback((next) => {
+		const params = getUrlParams();
+		if ((params.get("search") ?? "") === next) return;
+		if (next) params.set("search", next);
+		else params.delete("search");
+		params.delete(pageKey);
+		setSearchParams(params);
+	}, [pageKey]);
+	const debouncedCommit = useDebouncedCallback(commit, debounceMs);
+	const { cancel } = debouncedCommit;
+	useEffect(() => {
+		const sync = () => {
+			cancel();
+			setValue(getUrlParams().get("search") ?? "");
+		};
+		window.addEventListener("popstate", sync);
+		window.addEventListener("urlchange", sync);
+		return () => {
+			cancel();
+			window.removeEventListener("popstate", sync);
+			window.removeEventListener("urlchange", sync);
+		};
+	}, [cancel, pageKey]);
+	const change = (next) => {
+		setValue(next);
+		cancel();
+		if (composing.current) return;
+		if (!next || debounceMs <= 0) commit(next);
+		else debouncedCommit(next);
+	};
+	return /* @__PURE__ */ jsx(Input, {
+		value,
+		onChange: (event) => change(event.target.value),
+		onCompositionStart: () => {
+			composing.current = true;
+			cancel();
+		},
+		onCompositionEnd: (event) => {
+			composing.current = false;
+			change(event.currentTarget.value);
+		},
+		placeholder,
+		className: "h-8 w-48 shrink-0"
+	});
+}
+
 //#endregion
 //#region src/components/data-table/data-table-column-header.tsx
 function DataTableColumnHeader({ column, label, className,...props }) {
@@ -5178,14 +5233,6 @@ function AutoTable({ schema, data, getRowId, expandedRow, defaultExpanded = fals
 	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(queryKeys?.page ?? "page", parseAsInteger.withDefault(1), {
-		shallow: false,
-		clearOnDefault: true
-	});
 	const searchConfig = search && typeof search === "object" ? search : {};
 	const enableAdvancedFilter = true;
 	const { columns, expandColumnId } = useMemo(() => {
@@ -5347,14 +5394,9 @@ function AutoTable({ schema, data, getRowId, expandedRow, defaultExpanded = fals
 			})
 		})
 	})] }) : 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"
+	const searchInput = search ? /* @__PURE__ */ jsx(AutoTableSearch, {
+		...searchConfig,
+		pageKey: queryKeys?.page
 	}) : null;
 	const filtersContent = useMemo(() => {
 		switch (currentMode) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wordrhyme/auto-crud",
   "type": "module",
-  "version": "1.14.2",
+  "version": "1.14.3",
   "description": "Schema-first CRUD components with auto-generated tables and forms",
   "author": "wordrhyme",
   "license": "MIT",
@@ -95,10 +95,10 @@
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
     "@internal/eslint-config": "0.3.0",
+    "@internal/prettier-config": "0.0.1",
     "@internal/tsconfig": "0.1.0",
-    "@internal/tsdown-config": "0.1.0",
     "@internal/vitest-config": "0.1.0",
-    "@internal/prettier-config": "0.0.1"
+    "@internal/tsdown-config": "0.1.0"
   },
   "prettier": "@internal/prettier-config",
   "scripts": {