@hsu-react/ui 2.5.3 → 2.5.5

package/lib/components/Input/index.js

@@ -13,7 +13,7 @@ var _TextArea = _interopRequireDefault(require("./TextArea"));
 var _classnames = _interopRequireDefault(require("classnames"));
 var _indexModule = _interopRequireDefault(require("./index.module.scss"));
 var _Range = _interopRequireDefault(require("./Range"));
-var _ahooks = require("ahooks");
+var _useLatestRef = require("../../hooks/useLatestRef");
 var _jsxRuntime = require("react/jsx-runtime");
 function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
 function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
@@ -34,8 +34,11 @@ const Input = props => {
     escapeCharacters,
     ...inputConfig
   } = props;
-  const [isComposing, setComposing] = (0, _react.useState)(false);
   const ref = (0, _react.useRef)(null);
+  const getRefRef = (0, _useLatestRef.useLatestRef)(getRef);
+  // 输入法组字期间不往外通知。放 ref 不放 state：它只决定「要不要发通知」，
+  // 不参与渲染，而且必须在同一次事件里立刻生效
+  const composingRef = (0, _react.useRef)(false);
 
   // Handle escaping: if the value contains characters listed in escapeCharacters, prefix them with an escape
   const escapeValue = (0, _react.useCallback)(val => {
@@ -104,20 +107,23 @@ const Input = props => {
   };
   const initialValue = getInitialValue();
   const [_value, setValue] = (0, _react.useState)(initialValue);
-  const [lastValue, setLastValue] = (0, _react.useState)(initialValue);
   const prevValueRef = (0, _react.useRef)(undefined);
-  (0, _ahooks.useDebounceEffect)(() => {
-    if (!isComposing && _value !== lastValue) {
-      const trimmedValue = _value.trim();
-      const finalValue = trimmedValue === "" ? "" : _value;
-      setLastValue(finalValue);
-      // If escapeCharacters is set and the value matches, return the escaped value
-      const escapedValue = escapeValue(finalValue);
-      onChange?.(escapedValue);
-    }
-  }, [_value, isComposing, lastValue, onChange, escapeValue], {
-    wait: 10
-  });
+  // 最近一次通知出去的原文（未转义）。只用来去掉 compositionend 与 input
+  // 两个事件的重复通知
+  const notifiedRef = (0, _react.useRef)(initialValue);
+
+  /**
+   * `onChange` 是「用户改了输入」这个**事件**的通知，不是从 state 推导出来的结果，
+   * 所以在事件处理里发，不在 effect 里发。详见 `TextArea/index.tsx` 里那段说明——
+   * 旧写法（依赖数组里放 `onChange`、体内又调它、用 state 记「通知过没有」）
+   * 会让传内联箭头的消费方死循环。
+   */
+  const notify = next => {
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    // 全是空白等同于空；escapeCharacters 命中时对外给转义后的值
+    onChange?.(escapeValue(next.trim() === "" ? "" : next));
+  };
   (0, _react.useEffect)(() => {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
@@ -126,18 +132,21 @@ const Input = props => {
         const rawValue = typeof value === "number" ? `${value}` : value?.toString();
         // Unescape before displaying
         const newValue = unescapeValue(rawValue);
+        // 外部把值改了，之前通知过什么就不作数了，重新以外部值为准
+        notifiedRef.current = newValue;
         setValue(newValue);
-        setLastValue(newValue);
       } else {
         // Clear only on initialization or when explicitly set to undefined externally
+        notifiedRef.current = "";
         setValue("");
-        setLastValue("");
       }
     }
   }, [value, unescapeValue]);
+
+  // 只在挂载时把 ref 交出去。`getRef` 进依赖数组同样会被内联箭头带着每次渲染重跑
   (0, _react.useEffect)(() => {
-    getRef?.(ref.current);
-  }, [getRef]);
+    getRefRef.current?.(ref.current);
+  }, [getRefRef]);
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_antd.Tooltip, {
     placement: "topLeft",
     ...tooltip,
@@ -145,11 +154,14 @@ const Input = props => {
       ref: ref,
       disabled: disabled,
       placeholder: disabled ? "" : placeholder,
-      onCompositionStart: () => setComposing(true),
-      onCompositionEnd: () => {
-        setTimeout(() => {
-          setComposing(false);
-        }, 1);
+      onCompositionStart: () => {
+        composingRef.current = true;
+      },
+      onCompositionEnd: e => {
+        composingRef.current = false;
+        // 组完字的那一下自己发通知。浏览器之间 compositionend 与 input 的先后
+        // 不一致，`notify` 里按原文去重，两种顺序都只会发出一次
+        notify(unescapeValue(e.currentTarget.value));
       },
       value: _value,
       onChange: e => {
@@ -157,6 +169,7 @@ const Input = props => {
         const inputValue = e.target.value;
         const unescapedInput = unescapeValue(inputValue);
         setValue(unescapedInput);
+        if (!composingRef.current) notify(unescapedInput);
       },
       className: (0, _classnames.default)(_indexModule.default.antdInput, className),
       type: type,

package/lib/components/Select/_hooks/useSelectComposition.js

@@ -12,6 +12,7 @@ function useSelectComposition({
   onSearch
 }) {
   const [isComposing, setComposing] = (0, _react.useState)(false);
+  const hasOnSearch = !!onSearch;
   (0, _react.useEffect)(() => {
     const compositionend = () => {
       setComposing(false);
@@ -19,7 +20,7 @@ function useSelectComposition({
     const compositionstart = () => {
       setComposing(true);
     };
-    if (onSearch) {
+    if (hasOnSearch) {
       window.addEventListener("compositionstart", compositionstart);
       window.addEventListener("compositionend", compositionend);
     }
@@ -27,7 +28,10 @@ function useSelectComposition({
       window.removeEventListener("compositionstart", compositionstart);
       window.removeEventListener("compositionend", compositionend);
     };
-  }, [onSearch]);
+    // onSearch 在这里只被当作「要不要监听输入法事件」的真值判断，effect 体从不调它。
+    // 直接进依赖数组的话，消费方传内联箭头就会每渲染一次拆一次、装一次 window 监听；
+    // 只取「有没有传」这个布尔量，从无到有时照样会重新注册。
+  }, [hasOnSearch]);
   return {
     isComposing
   };

package/lib/components/Select/_hooks/useSelectInputOptions.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.useSelectInputOptions = useSelectInputOptions;
 var _react = require("react");
+var _useLatestRef = require("../../../hooks/useLatestRef");
 /**
  * Manage input options (when there are no matching options)
  */
@@ -16,11 +17,15 @@ function useSelectInputOptions({
   optionsLength
 }) {
   const [inputOptions, setInputOptions] = (0, _react.useState)([]);
+  const onSearchRef = (0, _useLatestRef.useLatestRef)(onSearch);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   (0, _react.useEffect)(() => {
     if (!isComposing) {
-      onSearch?.(searchValue);
+      onSearchRef.current?.(searchValue);
     }
-  }, [inputOptions, isComposing, onChange, onSearch, optionsLength, searchValue]);
+  }, [inputOptions, isComposing, onSearchRef, optionsLength, searchValue]);
   return {
     inputOptions,
     setInputOptions

package/lib/components/Slider/index.js

@@ -21,25 +21,37 @@ const Slider = props => {
     ...sliderConfig
   } = props;
   const [_value, setValue] = (0, _react.useState)(value);
-  const [lastValue, setLastValue] = (0, _react.useState)(value);
-  (0, _react.useEffect)(() => {
-    if (_value !== lastValue) {
-      setLastValue(_value);
-      onChange?.(_value);
-    }
-  }, [lastValue, onChange, _value]);
+  // 最近一次通知出去的值，代替原来那个用 state 记账的写法
+  const notifiedRef = (0, _react.useRef)(value);
+
+  /**
+   * `onChange` 是「用户拖了滑块」这个**事件**的通知，不是从 state 推导出来的结果，
+   * 所以在事件处理里发，不在 effect 里发。详见 `Input/TextArea/index.tsx` 里那段
+   * 说明——旧写法（依赖数组里放 `onChange`、体内又调它、用 state 记「通知过没有」）
+   * 会让传内联箭头的消费方死循环。
+   */
+  const handleChange = next => {
+    setValue(next);
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    onChange?.(next);
+  };
+
+  // 外部值（`value` / `topValue`）变了才回写，不跟着通知走
   (0, _react.useEffect)(() => {
-    if ((topValue || value) !== lastValue) {
-      setValue(topValue || value);
+    const next = topValue || value;
+    if (next !== notifiedRef.current) {
+      notifiedRef.current = next;
+      setValue(next);
     }
-  }, [lastValue, topValue, value]);
+  }, [topValue, value]);
   return /*#__PURE__*/(0, _jsxRuntime.jsx)(_antd.Slider, {
     className: (0, _classnames.default)([_indexModule.default.slider, className]),
     tooltip: {
       open: false
     },
     value: _value,
-    onChange: setValue,
+    onChange: handleChange,
     ...sliderConfig
   });
 };

package/lib/components/Table/_hooks/useAutoScrolling.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 var _ahooks = require("ahooks");
 var _react = require("react");
+var _useLatestRef = require("../../../hooks/useLatestRef");
 const DEFAULT_INTERVAL = 2000;
 const DEFAULT_SPEED = 25;
 const SMOOTH_SCROLL_TICK = 10;
@@ -24,6 +25,13 @@ const useAutoScrolling = props => {
     autoScrollLoopMode = "reset",
     autoScrollingOffset = 0
   } = props;
+
+  // onAutoScrollEndAdd 在这里身兼两职：既是「有没有加载更多」的开关，又是真正去加载的动作。
+  // 整个 rAF 循环（loop → 依赖它 → 启停 effect 依赖 loop）都挂在它的引用上，
+  // 消费方传内联箭头就会每渲染一次重启一次滚动循环 —— 表格滚到一半被打回起点。
+  // 拆成两半：开关看布尔量（从无到有传入时仍会正确接上加载更多），动作取 ref 里的最新引用。
+  const onAutoScrollEndAddRef = (0, _useLatestRef.useLatestRef)(onAutoScrollEndAdd);
+  const hasOnAutoScrollEndAdd = !!onAutoScrollEndAdd;
   const validSpeed = autoScrollingSpeed > 0 ? autoScrollingSpeed : DEFAULT_SPEED;
   const smoothStep = validSpeed * SMOOTH_SCROLL_TICK / 1000;
   const [ready, setReady] = (0, _react.useState)(false);
@@ -237,11 +245,12 @@ const useAutoScrolling = props => {
     }, SMOOTH_SCROLL_TICK);
   }, [bindHover, checkSeamlessReset, clearSmoothTimer, getBody, interval, isAtBottom, isBodyScrollable, isSeamless, smoothStep]);
   const runLoadMore = (0, _react.useCallback)(() => {
-    if (!onAutoScrollEndAdd || pendingLoadMoreRef.current) return;
+    const loadMore = onAutoScrollEndAddRef.current;
+    if (!loadMore || pendingLoadMoreRef.current) return;
     pendingLoadMoreRef.current = true;
     phaseRef.current = "loading";
     const token = ++loadTokenRef.current;
-    onAutoScrollEndAdd().then(hasMore => {
+    loadMore().then(hasMore => {
       if (token !== loadTokenRef.current) return;
       const currentBody = getBody();
       if (hasMore) {
@@ -261,7 +270,7 @@ const useAutoScrolling = props => {
       if (token !== loadTokenRef.current) return;
       pendingLoadMoreRef.current = false;
     });
-  }, [autoScrollLoop, getBody, onAutoScrollEndAdd]);
+  }, [autoScrollLoop, getBody, onAutoScrollEndAddRef]);
   const loop = (0, _react.useCallback)(() => {
     rafRef.current = requestAnimationFrame(loop);
     if (!autoScrolling || !ready || !dataSource?.length || !ref?.current) {
@@ -293,7 +302,7 @@ const useAutoScrolling = props => {
         // In seamless mode the scroll never actually reaches the bottom; just keep scrolling
         phaseRef.current = "idle";
       } else if (isAtBottom(body)) {
-        if (onAutoScrollEndAdd) {
+        if (hasOnAutoScrollEndAdd) {
           runLoadMore();
         } else {
           if (autoScrollLoop) {
@@ -339,7 +348,7 @@ const useAutoScrolling = props => {
       return;
     }
     startSmoothStep(body, targetTop);
-  }, [autoScrollMode, autoScrollLoop, autoScrolling, bindHover, checkSeamlessReset, dataSource, getBody, getRowHeight, interval, isAtBottom, isBodyScrollable, isSeamless, onAutoScrollEndAdd, ready, ref, runLoadMore, setupSeamlessClones, startSmoothStep]);
+  }, [autoScrollMode, autoScrollLoop, autoScrolling, bindHover, checkSeamlessReset, dataSource, getBody, getRowHeight, interval, isAtBottom, isBodyScrollable, isSeamless, hasOnAutoScrollEndAdd, ready, ref, runLoadMore, setupSeamlessClones, startSmoothStep]);
   (0, _react.useEffect)(() => {
     if (!autoScrolling || !ready || !dataSource?.length || !ref?.current) {
       cleanup();
@@ -364,7 +373,7 @@ const useAutoScrolling = props => {
       cleanupClones();
       return;
     }
-    if (onAutoScrollEndAdd) {
+    if (hasOnAutoScrollEndAdd) {
       // In load-more mode, if scrolling had stopped, resume auto-scrolling when new data arrives
       if (phaseRef.current === "stopped") {
         phaseRef.current = autoScrollMode === "row" ? "wait" : "idle";
@@ -377,7 +386,7 @@ const useAutoScrolling = props => {
       phaseRef.current = autoScrollMode === "row" ? "wait" : "idle";
       waitUntilRef.current = autoScrollMode === "row" ? performance.now() + interval : 0;
     }
-  }, [autoScrollMode, cleanupClones, dataSource, getBody, interval, isBodyScrollable, isSeamless, onAutoScrollEndAdd]);
+  }, [autoScrollMode, cleanupClones, dataSource, getBody, interval, isBodyScrollable, isSeamless, hasOnAutoScrollEndAdd]);
   (0, _react.useEffect)(() => {
     if (!autoScrolling || !ref?.current) return;
     let resizeRaf = null;

package/lib/components/Upload/_hooks/useUploadFileList.js

@@ -7,6 +7,7 @@ exports.useUploadFileList = useUploadFileList;
 var _react = require("react");
 var _hsuUtils = require("hsu-utils");
 var _utils = require("../_utils");
+var _useLatestRef = require("../../../hooks/useLatestRef");
 /**
  * Manage the upload file list state
  */
@@ -17,6 +18,10 @@ function useUploadFileList({
 }) {
   const [_fileList, setFilelist] = (0, _react.useState)([]);
   const [lastFileList, setLastFileList] = (0, _react.useState)([]);
+  const onChangeRef = (0, _useLatestRef.useLatestRef)(onChange);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   (0, _react.useEffect)(() => {
     if (rmFile) {
       const file = _fileList.find(item => item.uid === rmFile);
@@ -24,14 +29,14 @@ function useUploadFileList({
       if (file) {
         setFilelist(filteredList);
         setTimeout(() => {
-          onChange?.({
+          onChangeRef.current?.({
             file,
             fileList: filteredList
           });
         }, 100);
       }
     }
-  }, [_fileList, onChange, rmFile]);
+  }, [_fileList, onChangeRef, rmFile]);
   (0, _react.useEffect)(() => {
     if (!_hsuUtils.Equal.ObjEqual(fileList ?? [], lastFileList)) {
       if (fileList?.length) {

package/lib/components/Upload/_hooks/useUploadOperations.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 exports.useUploadOperations = useUploadOperations;
 var _react = require("react");
 var _hsuUtils = require("hsu-utils");
+var _useLatestRef = require("../../../hooks/useLatestRef");
 /**
  * Manage upload and download operations
  */
@@ -19,6 +20,7 @@ function useUploadOperations({
     downloading: {},
     uploadingList: {}
   });
+  const onUploadingListRef = (0, _useLatestRef.useLatestRef)(onUploadingList);
 
   // Sync to the ref on update
   (0, _react.useEffect)(() => {
@@ -27,12 +29,15 @@ function useUploadOperations({
   (0, _react.useEffect)(() => {
     operationsRef.current.uploadingList = uploadingList;
   }, [uploadingList]);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   (0, _react.useEffect)(() => {
     if (!_hsuUtils.Equal.ObjEqual(uploadingList, lastUploadList)) {
-      onUploadingList?.((0, _hsuUtils.deepCopy)(uploadingList));
+      onUploadingListRef.current?.((0, _hsuUtils.deepCopy)(uploadingList));
       setLastUploadList((0, _hsuUtils.deepCopy)(uploadingList));
     }
-  }, [uploadingList, lastUploadList, onUploadingList]);
+  }, [uploadingList, lastUploadList, onUploadingListRef]);
 
   // Cleanup function
   (0, _react.useEffect)(() => {

package/lib/hooks/useLatestRef.d.ts

@@ -0,0 +1,24 @@
+/// <reference types="react" />
+/**
+ * 把一个每次渲染都可能换引用的值（通常是回调 prop）装进一个**引用恒定**的 ref。
+ *
+ * 用途只有一个：让 effect 不必把回调放进依赖数组。
+ * 回调放进依赖数组、effect 体内又调它，是一条会让消费方死循环的写法——
+ * 消费方传内联箭头（`onChange={(v) => setX(v)}`，React 里最常见的写法）时
+ * 每次渲染都是新引用 → effect 重跑 → 调回调 → 父级 setState → 再渲染 →
+ * 又是新引用 …… 直到 React 抛 `Maximum update depth exceeded`。
+ *
+ * ```ts
+ * const onDoneRef = useLatestRef(onDone);
+ * useEffect(() => {
+ *   const t = setTimeout(() => onDoneRef.current?.(), 1000);
+ *   return () => clearTimeout(t);
+ * }, [onDoneRef]); // 只在挂载时跑一次，且永远调到最新的 onDone
+ * ```
+ *
+ * 注意：渲染期间就地赋值。React 官方对 ref 的约束是「不要在渲染中**读**可变值」，
+ * 写入最新的 props 是 useEffectEvent 落地前的通行做法（ahooks 的 `useLatest`、
+ * React 文档里的 `useEvent` polyfill 都是这么写的）。
+ */
+export declare function useLatestRef<T>(value: T): import("react").MutableRefObject<T>;
+export default useLatestRef;

package/lib/hooks/useLatestRef.js

@@ -0,0 +1,35 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+exports.useLatestRef = useLatestRef;
+var _react = require("react");
+/**
+ * 把一个每次渲染都可能换引用的值（通常是回调 prop）装进一个**引用恒定**的 ref。
+ *
+ * 用途只有一个：让 effect 不必把回调放进依赖数组。
+ * 回调放进依赖数组、effect 体内又调它，是一条会让消费方死循环的写法——
+ * 消费方传内联箭头（`onChange={(v) => setX(v)}`，React 里最常见的写法）时
+ * 每次渲染都是新引用 → effect 重跑 → 调回调 → 父级 setState → 再渲染 →
+ * 又是新引用 …… 直到 React 抛 `Maximum update depth exceeded`。
+ *
+ * ```ts
+ * const onDoneRef = useLatestRef(onDone);
+ * useEffect(() => {
+ *   const t = setTimeout(() => onDoneRef.current?.(), 1000);
+ *   return () => clearTimeout(t);
+ * }, [onDoneRef]); // 只在挂载时跑一次，且永远调到最新的 onDone
+ * ```
+ *
+ * 注意：渲染期间就地赋值。React 官方对 ref 的约束是「不要在渲染中**读**可变值」，
+ * 写入最新的 props 是 useEffectEvent 落地前的通行做法（ahooks 的 `useLatest`、
+ * React 文档里的 `useEvent` polyfill 都是这么写的）。
+ */
+function useLatestRef(value) {
+  const ref = (0, _react.useRef)(value);
+  ref.current = value;
+  return ref;
+}
+var _default = exports.default = useLatestRef;

package/lib/layout/Menu/_hooks/useOnlyLvOneMenu.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.useOnlyLvOneMenu = void 0;
 var _react = require("react");
+var _useLatestRef = require("../../../hooks/useLatestRef");
 var _reactRouter = require("react-router");
 /**
  * Handle the top-level-only menu logic
@@ -17,15 +18,20 @@ const useOnlyLvOneMenu = ({
   setMenuKey
 }) => {
   const location = (0, _reactRouter.useLocation)();
+  // getCurrChildItems 是 effect 体里发出去的通知，本身进依赖数组是这一类死循环的标准配方：
+  // 消费方传内联箭头 → 每次渲染新引用 → effect 重跑 → setOpenkeys([item.key]) 每次都是
+  // 新数组必定触发重渲染 → 又是新引用 …… 直到 React 抛 Maximum update depth exceeded。
+  // 通知取 ref 里的最新引用，依赖数组只留真正的输入。
+  const getCurrChildItemsRef = (0, _useLatestRef.useLatestRef)(getCurrChildItems);
   (0, _react.useEffect)(() => {
     if (onlyLvOneMenu) {
       const item = items.find(i => i.key === "/" + location.pathname.split("/").filter(Boolean)[0]);
       if (item) {
-        getCurrChildItems?.(item.children || []);
+        getCurrChildItemsRef.current?.(item.children || []);
         setOpenkeys([item.key]);
         setMenuKey(item.key);
       }
     }
-  }, [items, getCurrChildItems, location, onlyLvOneMenu, setOpenkeys, setMenuKey]);
+  }, [items, getCurrChildItemsRef, location, onlyLvOneMenu, setOpenkeys, setMenuKey]);
 };
 exports.useOnlyLvOneMenu = useOnlyLvOneMenu;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hsu-react/ui",
-  "version": "2.5.3",
+  "version": "2.5.5",
   "description": "一套基于 React + Ant Design 的中后台业务组件库",
   "license": "MIT",
   "type": "module",
@@ -42,7 +42,9 @@
     "docs:build": "dumi build",
     "docs:preview": "dumi preview",
     "build": "node scripts/clean-dist.cjs && node scripts/gen-tokens-scss.cjs && father build && node scripts/mark-cjs.cjs && node scripts/check-heavy-deps.cjs",
-    "prepublishOnly": "node scripts/clean-dist.cjs && node scripts/gen-tokens-scss.cjs --check && father build && node scripts/mark-cjs.cjs && node scripts/check-heavy-deps.cjs",
+    "prepublishOnly": "node scripts/clean-dist.cjs && node scripts/gen-tokens-scss.cjs --check && vitest run && father build && node scripts/mark-cjs.cjs && node scripts/check-heavy-deps.cjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "check:deps": "node scripts/check-heavy-deps.cjs",
     "tokens": "node scripts/gen-tokens-scss.cjs",
     "check:tokens": "node scripts/gen-tokens-scss.cjs --check"
@@ -115,6 +117,8 @@
   },
   "devDependencies": {
     "@ant-design/icons": "^6.3.2",
+    "@testing-library/dom": "^10",
+    "@testing-library/react": "^16",
     "@types/js-cookie": "^3.0.6",
     "@types/lodash": "^4.17.4",
     "@types/markdown-it": "^14.1.2",
@@ -126,6 +130,7 @@
     "antd": "6.5.4",
     "dumi": "^2.4.0",
     "father": "^4.5.0",
+    "jsdom": "^25",
     "mobx": "^6.12.3",
     "mobx-react-lite": "^4.0.7",
     "react": "^18.3.1",
@@ -134,7 +139,8 @@
     "react-router": "^6.23.1",
     "react-router-dom": "^6.23.1",
     "sass": "^1.101.0",
-    "typescript": "^5.4.5"
+    "typescript": "^5.4.5",
+    "vitest": "^2"
   },
   "peerDependenciesMeta": {
     "react-router": {

package/src/__tests__/callbackDepsGuard.test.ts

@@ -0,0 +1,119 @@
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+/**
+ * 防回归守卫：**回调 prop 不许进 effect 依赖数组**。
+ *
+ * 这条缺陷没有任何信号——不报错、不变慢，只是消费方一传内联箭头
+ * （`onXxx={(v) => setV(v)}`，React 里最常见的写法）就重复订阅 / 重复通知，
+ * 严重的直接死循环到 `Maximum update depth exceeded`。
+ * 靠人工 review 拦不住，所以扫源码。
+ *
+ * 正确写法见 `src/hooks/useLatestRef.ts`：
+ * - 调用取 ref 里的最新引用；
+ * - 「有没有传回调」若决定要不要注册监听，就单独拆一个布尔量进依赖数组，
+ *   这样「从无到有传入回调」仍会正确注册。
+ *
+ * 确实无害的写法登记在 ALLOWED 里，每条都要写清为什么无害。
+ */
+
+const SRC = path.resolve(__dirname, "..");
+
+/** 回调型标识符：`onXxx` 形态，外加几个明确的出口型回调名 */
+const EXTRA_CALLBACK_NAMES = new Set(["getImage", "labelRender"]);
+const isCallbackDep = (name: string) =>
+  (/^on[A-Z]/.test(name) && !name.endsWith("Ref")) ||
+  EXTRA_CALLBACK_NAMES.has(name);
+
+/** `文件相对路径::依赖名` → 无害的理由 */
+const ALLOWED: Record<string, string> = {
+  "components/Chat/ChatHistory/index.tsx::onScrollEnd":
+    "只在 DOM scroll 监听里调，effect 体不调它；重订阅是同一节点上摘一个装一个，无副作用",
+  "components/DatePicker/index.tsx::onChange":
+    "纯 ref 同步 effect：effect 体只写 ref，不调回调、不订阅任何东西",
+  "components/DatePicker/RangePicker/index.tsx::onChange":
+    "同上，纯 ref 同步 effect",
+  "components/Tree/index.tsx::onSelectPath": "同上，纯 ref 同步 effect",
+};
+
+function walk(dir: string, out: string[] = []) {
+  for (const name of fs.readdirSync(dir)) {
+    const full = path.join(dir, name);
+    if (fs.statSync(full).isDirectory()) walk(full, out);
+    else if (/\.(tsx?|jsx?)$/.test(name) && !/\.test\./.test(name))
+      out.push(full);
+  }
+  return out;
+}
+
+/** 找出每个 useEffect / useLayoutEffect 的依赖数组，返回 [行号, 依赖名] */
+function effectDeps(src: string): Array<[number, string]> {
+  const found: Array<[number, string]> = [];
+  const re = /use(?:Layout)?Effect\(/g;
+  let m: RegExpExecArray | null;
+
+  while ((m = re.exec(src))) {
+    let i = m.index + m[0].length;
+    let depth = 1;
+    let quote: string | null = null;
+    let prev = "";
+
+    while (i < src.length && depth > 0) {
+      const c = src[i];
+      if (quote) {
+        if (c === quote && prev !== "\\") quote = null;
+      } else if (c === '"' || c === "'" || c === "`") quote = c;
+      else if (c === "(" || c === "[" || c === "{") depth++;
+      else if (c === ")" || c === "]" || c === "}") depth--;
+      prev = c;
+      i++;
+    }
+
+    const body = src.slice(m.index, i).replace(/\)\s*$/, "");
+    const deps = body.match(/,\s*\[([\s\S]*)\]\s*$/);
+    if (!deps) continue;
+
+    const line = src.slice(0, m.index).split("\n").length;
+    for (const raw of deps[1].split(",")) {
+      const name = raw
+        .replace(/\/\/.*$/gm, "")
+        .trim()
+        .split(/[.?[]/)[0]
+        .trim();
+      if (name) found.push([line, name]);
+    }
+  }
+
+  return found;
+}
+
+describe("回调 prop 不进 effect 依赖数组", () => {
+  it("全库无未登记的命中", () => {
+    const offenders: string[] = [];
+
+    for (const file of walk(SRC)) {
+      const rel = path.relative(SRC, file).split(path.sep).join("/");
+      const src = fs.readFileSync(file, "utf8");
+
+      for (const [line, dep] of effectDeps(src)) {
+        if (!isCallbackDep(dep)) continue;
+        if (ALLOWED[`${rel}::${dep}`]) continue;
+        offenders.push(`${rel}:${line}  ${dep}`);
+      }
+    }
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("守卫本身能抓到问题（自测）", () => {
+    const bad = `
+      useEffect(() => {
+        onDone?.();
+      }, [value, onDone]);
+    `;
+    expect(effectDeps(bad).map(([, d]) => d)).toContain("onDone");
+    expect(isCallbackDep("onDone")).toBe(true);
+    expect(isCallbackDep("onDoneRef")).toBe(false);
+  });
+});

package/src/__tests__/setup.ts

@@ -0,0 +1,26 @@
+/**
+ * jsdom 没有 `matchMedia` / `ResizeObserver`，antd 与 rc-* 会直接调它们。
+ * 这里补齐，缺一个就整个测试文件起不来
+ */
+import "@testing-library/react";
+
+if (!window.matchMedia) {
+  window.matchMedia = ((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: () => {},
+    removeListener: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => false,
+  })) as unknown as typeof window.matchMedia;
+}
+
+if (!(globalThis as { ResizeObserver?: unknown }).ResizeObserver) {
+  (globalThis as { ResizeObserver?: unknown }).ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  };
+}