@hsu-react/ui 2.5.2 → 2.5.4

package/es/components/Input/TextArea/index.js

@@ -17,6 +17,7 @@ import AntdTextArea from "antd/es/input/TextArea";
 import React, { useEffect, useRef, useState } from "react";
 import classNames from "classnames";
 import styles from "./index.module.scss";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { jsxs as _jsxs } from "react/jsx-runtime";
 var TextArea = function TextArea(props) {
@@ -40,56 +41,74 @@ var TextArea = function TextArea(props) {
     autoSize = props.autoSize,
     style = props.style,
     inputConfig = _objectWithoutProperties(props, _excluded);
+  var ref = useRef(null);
   var _useState = useState(false),
     _useState2 = _slicedToArray(_useState, 2),
-    isComposing = _useState2[0],
-    setComposing = _useState2[1];
-  var ref = useRef(null);
-  var _useState3 = useState(false),
-    _useState4 = _slicedToArray(_useState3, 2),
-    focused = _useState4[0],
-    setFocused = _useState4[1];
+    focused = _useState2[0],
+    setFocused = _useState2[1];
 
   // On initialization, prefer value, then fall back to defaultValue
   var initialValue = value !== undefined ? (_value$toString = value === null || value === void 0 ? void 0 : value.toString()) !== null && _value$toString !== void 0 ? _value$toString : "" : defaultValue !== undefined ? (_defaultValue$toStrin = defaultValue === null || defaultValue === void 0 ? void 0 : defaultValue.toString()) !== null && _defaultValue$toStrin !== void 0 ? _defaultValue$toStrin : "" : "";
-  var _useState5 = useState(initialValue),
+  var _useState3 = useState(initialValue),
+    _useState4 = _slicedToArray(_useState3, 2),
+    _value = _useState4[0],
+    setValue = _useState4[1];
+  var _useState5 = useState(false),
     _useState6 = _slicedToArray(_useState5, 2),
-    _value = _useState6[0],
-    setValue = _useState6[1];
-  var _useState7 = useState(initialValue),
-    _useState8 = _slicedToArray(_useState7, 2),
-    lastValue = _useState8[0],
-    setLastValue = _useState8[1];
-  var _useState9 = useState(false),
-    _useState10 = _slicedToArray(_useState9, 2),
-    hasError = _useState10[0],
-    setHasError = _useState10[1];
+    hasError = _useState6[0],
+    setHasError = _useState6[1];
   var prevValueRef = useRef(undefined);
-  useEffect(function () {
-    if (!isComposing && _value !== lastValue) {
-      var trimmedValue = _value.trim();
-      var finalValue = trimmedValue === "" ? "" : _value;
-      setLastValue(finalValue);
-      onChange === null || onChange === void 0 || onChange(finalValue);
-    }
-  }, [isComposing, onChange, _value, lastValue]);
+  var getRefRef = useLatestRef(getRef);
+
+  // 输入法组字期间不往外通知。放 ref 不放 state：它只影响「要不要发通知」，
+  // 不参与渲染，而且必须在同一次事件里立刻生效
+  var composingRef = useRef(false);
+  // 最近一次通知出去的原文。只用来去掉 compositionend 与 input 两个事件的重复通知
+  var notifiedRef = useRef(initialValue);
+
+  /**
+   * `onChange` 是「用户改了输入」这个**事件**的通知，不是从 state 推导出来的结果，
+   * 所以它在事件处理里发，不在 effect 里发。
+   *
+   * 早先是一个 effect 在发：依赖数组里放着 `onChange`，effect 体内又调它，
+   * 还用一个 `lastValue` state 记「这个值通知过没有」。两处都是错的——
+   * 1. 消费方传内联箭头（`onChange={(v) => setX(v)}`，React 里最常见的写法）时
+   *    每次渲染都是新引用，effect 每次渲染都重跑；
+   * 2. 「通知过没有」的记账放在 React state 里就**不可靠**：父级用 MobX /
+   *    `useSyncExternalStore` 这类外部 store 回写 `value` 时，React 会以更高的
+   *    同步优先级重渲一次，effect 里排的那次 `setLastValue` 会被这一趟**跳过**，
+   *    于是 effect 读到过期的记账、判定「还没通知」，再发一次 → 父级再回写 →
+   *    死循环，React 抛 `Maximum update depth exceeded`，输入框被上层
+   *    ErrorBoundary 整块摘掉。
+   *
+   * 现在 `onChange` 的引用稳不稳定完全不影响正确性：永远调到最新的那个回调，
+   * 且只在真的有新文本时调一次。
+   */
+  var notify = function notify(next) {
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    // 全是空白等同于空：外部拿到的是 ""，但输入框里用户敲的空格照旧留着
+    onChange === null || onChange === void 0 || onChange(next.trim() === "" ? "" : next);
+  };
   useEffect(function () {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
+      var _value$toString2;
       prevValueRef.current = value;
-      if (value !== undefined) {
-        setValue(value === null || value === void 0 ? void 0 : value.toString());
-        setLastValue(value === null || value === void 0 ? void 0 : value.toString());
-      } else {
-        // Clear only on initialization or when explicitly set to undefined externally
-        setValue("");
-        setLastValue("");
-      }
+
+      // 外部把值改了，之前通知过什么就不作数了，重新以外部值为准
+      var next = value !== undefined ? (_value$toString2 = value === null || value === void 0 ? void 0 : value.toString()) !== null && _value$toString2 !== void 0 ? _value$toString2 : "" : "";
+      notifiedRef.current = next;
+      setValue(next);
     }
   }, [value]);
+
+  // 只在挂载时把 ref 交出去。`getRef` 进依赖数组同样会被内联箭头带着每次渲染重跑，
+  // 消费方在里面 setState 就是一个死循环
   useEffect(function () {
-    getRef === null || getRef === void 0 || getRef(ref.current);
-  }, [getRef]);
+    var _getRefRef$current;
+    (_getRefRef$current = getRefRef.current) === null || _getRefRef$current === void 0 || _getRefRef$current.call(getRefRef, ref.current);
+  }, [getRefRef]);
   useEffect(function () {
     var _ref$current2;
     // Use a MutationObserver to watch for error state changes
@@ -124,19 +143,22 @@ var TextArea = function TextArea(props) {
     children: [prefix, /*#__PURE__*/_jsx(AntdTextArea, _objectSpread({
       ref: ref,
       onCompositionStart: function onCompositionStart() {
-        return setComposing(true);
+        composingRef.current = true;
       },
-      onCompositionEnd: function onCompositionEnd() {
-        setTimeout(function () {
-          setComposing(false);
-        }, 1);
+      onCompositionEnd: function onCompositionEnd(e) {
+        composingRef.current = false;
+        // 组完字的那一下自己发通知。浏览器之间 compositionend 与 input 的先后
+        // 不一致，`notify` 里按原文去重，两种顺序都只会发出一次
+        notify(e.currentTarget.value);
       },
       value: _value,
       autoSize: disabled && text ? autoSize || {
         minRows: 1
       } : autoSize,
       onChange: function onChange(e) {
-        setValue(e.target.value);
+        var next = e.target.value;
+        setValue(next);
+        if (!composingRef.current) notify(next);
       },
       onFocus: function onFocus(e) {
         setFocused(true);

package/es/components/Input/index.js

@@ -22,7 +22,7 @@ import TextArea from "./TextArea";
 import classNames from "classnames";
 import styles from "./index.module.scss";
 import RangeInput from "./Range";
-import { useDebounceEffect } from "ahooks";
+import { useLatestRef } from "../../hooks/useLatestRef";
 import { jsx as _jsx } from "react/jsx-runtime";
 var Input = function Input(props) {
   var onChange = props.onChange,
@@ -39,11 +39,11 @@ var Input = function Input(props) {
     tooltip = props.tooltip,
     escapeCharacters = props.escapeCharacters,
     inputConfig = _objectWithoutProperties(props, _excluded);
-  var _useState = useState(false),
-    _useState2 = _slicedToArray(_useState, 2),
-    isComposing = _useState2[0],
-    setComposing = _useState2[1];
   var ref = useRef(null);
+  var getRefRef = useLatestRef(getRef);
+  // 输入法组字期间不往外通知。放 ref 不放 state：它只决定「要不要发通知」，
+  // 不参与渲染，而且必须在同一次事件里立刻生效
+  var composingRef = useRef(false);
 
   // Handle escaping: if the value contains characters listed in escapeCharacters, prefix them with an escape
   var escapeValue = useCallback(function (val) {
@@ -112,27 +112,27 @@ var Input = function Input(props) {
     return unescapeValue(rawValue);
   };
   var initialValue = getInitialValue();
-  var _useState3 = useState(initialValue),
-    _useState4 = _slicedToArray(_useState3, 2),
-    _value = _useState4[0],
-    setValue = _useState4[1];
-  var _useState5 = useState(initialValue),
-    _useState6 = _slicedToArray(_useState5, 2),
-    lastValue = _useState6[0],
-    setLastValue = _useState6[1];
+  var _useState = useState(initialValue),
+    _useState2 = _slicedToArray(_useState, 2),
+    _value = _useState2[0],
+    setValue = _useState2[1];
   var prevValueRef = useRef(undefined);
-  useDebounceEffect(function () {
-    if (!isComposing && _value !== lastValue) {
-      var trimmedValue = _value.trim();
-      var finalValue = trimmedValue === "" ? "" : _value;
-      setLastValue(finalValue);
-      // If escapeCharacters is set and the value matches, return the escaped value
-      var escapedValue = escapeValue(finalValue);
-      onChange === null || onChange === void 0 || onChange(escapedValue);
-    }
-  }, [_value, isComposing, lastValue, onChange, escapeValue], {
-    wait: 10
-  });
+  // 最近一次通知出去的原文（未转义）。只用来去掉 compositionend 与 input
+  // 两个事件的重复通知
+  var notifiedRef = useRef(initialValue);
+
+  /**
+   * `onChange` 是「用户改了输入」这个**事件**的通知，不是从 state 推导出来的结果，
+   * 所以在事件处理里发，不在 effect 里发。详见 `TextArea/index.tsx` 里那段说明——
+   * 旧写法（依赖数组里放 `onChange`、体内又调它、用 state 记「通知过没有」）
+   * 会让传内联箭头的消费方死循环。
+   */
+  var notify = function notify(next) {
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    // 全是空白等同于空；escapeCharacters 命中时对外给转义后的值
+    onChange === null || onChange === void 0 || onChange(escapeValue(next.trim() === "" ? "" : next));
+  };
   useEffect(function () {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
@@ -141,18 +141,22 @@ var Input = function Input(props) {
         var rawValue = typeof value === "number" ? "".concat(value) : value === null || value === void 0 ? void 0 : value.toString();
         // Unescape before displaying
         var 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` 进依赖数组同样会被内联箭头带着每次渲染重跑
   useEffect(function () {
-    getRef === null || getRef === void 0 || getRef(ref.current);
-  }, [getRef]);
+    var _getRefRef$current;
+    (_getRefRef$current = getRefRef.current) === null || _getRefRef$current === void 0 || _getRefRef$current.call(getRefRef, ref.current);
+  }, [getRefRef]);
   return /*#__PURE__*/_jsx(Tooltip, _objectSpread(_objectSpread({
     placement: "topLeft"
   }, tooltip), {}, {
@@ -161,12 +165,13 @@ var Input = function Input(props) {
       disabled: disabled,
       placeholder: disabled ? "" : placeholder,
       onCompositionStart: function onCompositionStart() {
-        return setComposing(true);
+        composingRef.current = true;
       },
-      onCompositionEnd: function onCompositionEnd() {
-        setTimeout(function () {
-          setComposing(false);
-        }, 1);
+      onCompositionEnd: function onCompositionEnd(e) {
+        composingRef.current = false;
+        // 组完字的那一下自己发通知。浏览器之间 compositionend 与 input 的先后
+        // 不一致，`notify` 里按原文去重，两种顺序都只会发出一次
+        notify(unescapeValue(e.currentTarget.value));
       },
       value: _value,
       onChange: function onChange(e) {
@@ -174,6 +179,7 @@ var Input = function Input(props) {
         var inputValue = e.target.value;
         var unescapedInput = unescapeValue(inputValue);
         setValue(unescapedInput);
+        if (!composingRef.current) notify(unescapedInput);
       },
       className: classNames(styles.antdInput, className),
       type: type,

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

@@ -5,6 +5,7 @@ function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len
 function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t.return && (u = t.return(), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
 function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 import { useEffect, useState } from "react";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 /**
  * Manage input options (when there are no matching options)
  */
@@ -18,11 +19,16 @@ export function useSelectInputOptions(_ref) {
     _useState2 = _slicedToArray(_useState, 2),
     inputOptions = _useState2[0],
     setInputOptions = _useState2[1];
+  var onSearchRef = useLatestRef(onSearch);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   useEffect(function () {
     if (!isComposing) {
-      onSearch === null || onSearch === void 0 || onSearch(searchValue);
+      var _onSearchRef$current;
+      (_onSearchRef$current = onSearchRef.current) === null || _onSearchRef$current === void 0 || _onSearchRef$current.call(onSearchRef, searchValue);
     }
-  }, [inputOptions, isComposing, onChange, onSearch, optionsLength, searchValue]);
+  }, [inputOptions, isComposing, onSearchRef, optionsLength, searchValue]);
   return {
     inputOptions: inputOptions,
     setInputOptions: setInputOptions

package/es/components/Slider/index.js

@@ -14,7 +14,7 @@ function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 function _objectWithoutProperties(source, excluded) { if (source == null) return {}; var target = _objectWithoutPropertiesLoose(source, excluded); var key, i; if (Object.getOwnPropertySymbols) { var sourceSymbolKeys = Object.getOwnPropertySymbols(source); for (i = 0; i < sourceSymbolKeys.length; i++) { key = sourceSymbolKeys[i]; if (excluded.indexOf(key) >= 0) continue; if (!Object.prototype.propertyIsEnumerable.call(source, key)) continue; target[key] = source[key]; } } return target; }
 function _objectWithoutPropertiesLoose(source, excluded) { if (source == null) return {}; var target = {}; var sourceKeys = Object.keys(source); var key, i; for (i = 0; i < sourceKeys.length; i++) { key = sourceKeys[i]; if (excluded.indexOf(key) >= 0) continue; target[key] = source[key]; } return target; }
 import { Slider as AntdSlider } from "antd";
-import React, { useEffect, useState } from "react";
+import React, { useEffect, useRef, useState } from "react";
 import classNames from "classnames";
 import styles from "./index.module.scss";
 import { jsx as _jsx } from "react/jsx-runtime";
@@ -29,28 +29,37 @@ var Slider = function Slider(props) {
     _useState2 = _slicedToArray(_useState, 2),
     _value = _useState2[0],
     setValue = _useState2[1];
-  var _useState3 = useState(value),
-    _useState4 = _slicedToArray(_useState3, 2),
-    lastValue = _useState4[0],
-    setLastValue = _useState4[1];
+  // 最近一次通知出去的值，代替原来那个用 state 记账的写法
+  var notifiedRef = useRef(value);
+
+  /**
+   * `onChange` 是「用户拖了滑块」这个**事件**的通知，不是从 state 推导出来的结果，
+   * 所以在事件处理里发，不在 effect 里发。详见 `Input/TextArea/index.tsx` 里那段
+   * 说明——旧写法（依赖数组里放 `onChange`、体内又调它、用 state 记「通知过没有」）
+   * 会让传内联箭头的消费方死循环。
+   */
+  var handleChange = function handleChange(next) {
+    setValue(next);
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    onChange === null || onChange === void 0 || onChange(next);
+  };
+
+  // 外部值（`value` / `topValue`）变了才回写，不跟着通知走
   useEffect(function () {
-    if (_value !== lastValue) {
-      setLastValue(_value);
-      onChange === null || onChange === void 0 || onChange(_value);
+    var next = topValue || value;
+    if (next !== notifiedRef.current) {
+      notifiedRef.current = next;
+      setValue(next);
     }
-  }, [lastValue, onChange, _value]);
-  useEffect(function () {
-    if ((topValue || value) !== lastValue) {
-      setValue(topValue || value);
-    }
-  }, [lastValue, topValue, value]);
+  }, [topValue, value]);
   return /*#__PURE__*/_jsx(AntdSlider, _objectSpread({
     className: classNames([styles.slider, className]),
     tooltip: {
       open: false
     },
     value: _value,
-    onChange: setValue
+    onChange: handleChange
   }, sliderConfig));
 };
 export default Slider;

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

@@ -7,6 +7,7 @@ function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 import { useEffect, useState } from "react";
 import { deepCopy, Equal } from "hsu-utils";
 import { extractFileUrl } from "../_utils";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 /**
  * Manage the upload file list state
  */
@@ -22,6 +23,10 @@ export function useUploadFileList(_ref) {
     _useState4 = _slicedToArray(_useState3, 2),
     lastFileList = _useState4[0],
     setLastFileList = _useState4[1];
+  var onChangeRef = useLatestRef(onChange);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   useEffect(function () {
     if (rmFile) {
       var file = _fileList.find(function (item) {
@@ -33,14 +38,15 @@ export function useUploadFileList(_ref) {
       if (file) {
         setFilelist(filteredList);
         setTimeout(function () {
-          onChange === null || onChange === void 0 || onChange({
+          var _onChangeRef$current;
+          (_onChangeRef$current = onChangeRef.current) === null || _onChangeRef$current === void 0 || _onChangeRef$current.call(onChangeRef, {
             file: file,
             fileList: filteredList
           });
         }, 100);
       }
     }
-  }, [_fileList, onChange, rmFile]);
+  }, [_fileList, onChangeRef, rmFile]);
   useEffect(function () {
     if (!Equal.ObjEqual(fileList !== null && fileList !== void 0 ? fileList : [], lastFileList)) {
       if (fileList !== null && fileList !== void 0 && fileList.length) {

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

@@ -6,6 +6,7 @@ function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" !=
 function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
 import { useEffect, useRef, useState } from "react";
 import { deepCopy, Equal } from "hsu-utils";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 /**
  * Manage upload and download operations
  */
@@ -27,6 +28,7 @@ export function useUploadOperations(_ref) {
     downloading: {},
     uploadingList: {}
   });
+  var onUploadingListRef = useLatestRef(onUploadingList);
 
   // Sync to the ref on update
   useEffect(function () {
@@ -35,12 +37,16 @@ export function useUploadOperations(_ref) {
   useEffect(function () {
     operationsRef.current.uploadingList = uploadingList;
   }, [uploadingList]);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   useEffect(function () {
     if (!Equal.ObjEqual(uploadingList, lastUploadList)) {
-      onUploadingList === null || onUploadingList === void 0 || onUploadingList(deepCopy(uploadingList));
+      var _onUploadingListRef$c;
+      (_onUploadingListRef$c = onUploadingListRef.current) === null || _onUploadingListRef$c === void 0 || _onUploadingListRef$c.call(onUploadingListRef, deepCopy(uploadingList));
       setLastUploadList(deepCopy(uploadingList));
     }
-  }, [uploadingList, lastUploadList, onUploadingList]);
+  }, [uploadingList, lastUploadList, onUploadingListRef]);
 
   // Cleanup function
   useEffect(function () {

package/es/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/es/hooks/useLatestRef.js

@@ -0,0 +1,29 @@
+import { useRef } from "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 function useLatestRef(value) {
+  var ref = useRef(value);
+  ref.current = value;
+  return ref;
+}
+export default useLatestRef;

package/es/layout/Menu/index.js

@@ -184,12 +184,30 @@ var Menu = function Menu(props) {
   }));
 
   // 次级菜单默认带一段头部（至少给出返回入口），调用方可用 secondaryHeader 整块换掉
-  return secondary ? /*#__PURE__*/_jsxs("div", {
-    className: styles.secondaryWrap,
-    children: [secondaryHeader !== null && secondaryHeader !== void 0 ? secondaryHeader : /*#__PURE__*/_jsx(SecondaryHeader, {
-      collapsed: collapsed,
-      theme: theme
-    }), menu]
+  if (secondary) {
+    return /*#__PURE__*/_jsxs("div", {
+      className: classNames(styles.scrollHost, styles.secondaryWrap),
+      children: [secondaryHeader !== null && secondaryHeader !== void 0 ? secondaryHeader : /*#__PURE__*/_jsx(SecondaryHeader, {
+        collapsed: collapsed,
+        theme: theme
+      }), menu]
+    });
+  }
+
+  /**
+   * 侧栏（inline）菜单自带滚动宿主：宿主不滚、菜单根滚。
+   *
+   * 不这么做的话「谁滚」就落在消费方的 Sider 上 —— 而 antd 的
+   * `.ant-layout-sider` / `.ant-layout-sider-children` 都没有 overflow，
+   * 展开子菜单的动画期间高度先超出再收回，滚动条会闪一下。几何契约必须由组件
+   * 自己闭合，不能指望每个消费方都补一遍 overflow 规则。
+   *
+   * 横向菜单不需要（rc-overflow 自己收成 “…”），也不能加：那层 div 会把
+   * `.menu` 从 Header 的 flex 行里挪走。
+   */
+  return mode === "inline" ? /*#__PURE__*/_jsx("div", {
+    className: styles.scrollHost,
+    children: menu
   }) : menu;
 };
 export default Menu;

package/es/layout/Menu/index.module.scss

@@ -1,13 +1,6 @@
 // 注意：CSS Module 里的类名都会被哈希，antd 的类名必须写在 :global() 中，否则
 // `.ant-menu-horizontal` 会变成 `.ant-menu-horizontal___xxxxx`，静悄悄地永不生效。
 .menu {
-  &::-webkit-scrollbar {
-    width: 0px;
-    height: 0px;
-  }
-
-  scrollbar-width: none;
-
   // 顶部横向菜单：占满剩余宽度，背景交给外层的导航渐变
   &:global(.ant-menu-horizontal) {
     flex: 1;
@@ -15,6 +8,50 @@
 
     background-color: transparent;
   }
+
+  /* ===== inline（侧栏）：菜单根**就是**那个滚动容器 =====
+     antd 的 `.ant-layout-sider` / `.ant-layout-sider-children` 都没有设 overflow，
+     所以在这条路径上，「谁滚」原本是没人规定的 —— 展开子菜单那 200ms 里
+     rc-motion 会逐帧改高度，容器先超出再收回，滚动条由**当时**恰好溢出的那个
+     元素临时长出来，于是闪一下。
+
+     这里把它定死：菜单根 `flex: 1 / min-height: 0 / overflow-y: auto`，配上外面
+     那层不滚的 `.scrollHost`，中间态怎么抖都轮不到别人显示滚动条；菜单长过一屏
+     时也仍然滚得到底部。 */
+  &:global(.ant-menu-inline),
+  &:global(.ant-menu-inline-collapsed) {
+    flex: 1;
+    min-height: 0px;
+
+    // 横向一律不滚：菜单文字过长时该省略，不该把侧栏推出一条横向滚动条
+    overflow-x: hidden;
+    overflow-y: auto;
+  }
+
+  /* 子菜单在展开 / 收起动画期间被 rc-motion 逐帧改高度。antd 的
+     `.ant-motion-collapse` 自带 overflow hidden，这里补的是**动画结束、类名摘掉
+     之后**那一帧：此时 ul 的高度刚回到 auto，若父级恰好差几像素，浏览器会先画出
+     滚动条再重排。子菜单本来也永远不需要自己滚。 */
+  :global(.ant-menu-sub.ant-menu-inline) {
+    overflow: hidden;
+  }
+
+  /* ===== 滚动条外观：本组件不管，交给消费方 =====
+     这里曾经写着 `scrollbar-width: none` ＋ `::-webkit-scrollbar { width: 0 }`，
+     用「把滚动条永久藏掉」来遮上面那个闪动。现在闪动由 overflow 归属治本了，
+     这份「藏」不但多余，还有两处害处，所以整段删掉：
+
+     1. **Chrome 121+ 一旦读到 `scrollbar-width` / `scrollbar-color` 的非默认值，
+        就会整套忽略该元素上的 `::-webkit-scrollbar` 规则。** 库里无差别写下一句
+        `scrollbar-width: none`，等于在每个消费方的侧栏上悄悄废掉他们全站那套
+        滚动条皮肤，只剩系统细条 —— 而且不报错、很难查。
+        （所以本库任何地方要写这两个属性，都必须锁在
+        `@supports (-moz-appearance: none)` 里，让 Chrome 读不到。）
+     2. 滚动条的「显 / 隐 / 配色」是应用级的设计语言（有的应用要常驻，有的要
+        悬浮才显现），不是菜单组件的行为。库只该规定**谁滚**，不该用高权重规则
+        把可见性堵死、逼消费方回过头来盖。
+
+     消费方在全局写 `::-webkit-scrollbar` 那一套即可，会自然落到菜单根上。 */
 }
 
 // 弹出的子菜单挂在 body 上，够不到 .menu，所以由组件把这个类挂到 popup 上
@@ -37,14 +74,20 @@
   }
 }
 
-// 次级菜单：头部固定在上，菜单撑满剩余高度
-.secondaryWrap {
+/* inline 菜单的滚动宿主：撑满侧栏高度、自己**不滚**，把高度整份让给菜单根。
+   有它在，菜单组件才是自带滚动容器语义的一整块 —— 消费方把 Menu 塞进任何一个
+   有高度的容器（antd 的 Sider、或自己的 div）都不必再补 overflow 规则。 */
+.scrollHost {
   height: 100%;
   display: flex;
   flex-direction: column;
 
+  overflow: hidden;
+}
+
+// 次级菜单：头部固定在上，菜单撑满剩余高度（滚动归属见 .scrollHost）
+.secondaryWrap {
   :global(.ant-menu) {
-    flex: 1;
     border-inline-end: none !important;
   }
 }

package/lib/components/Chart/Bubble/index.js

@@ -8,6 +8,7 @@ var _react = _interopRequireWildcard(require("react"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var echarts = _interopRequireWildcard(require("echarts"));
 var _bubble = require("../_utils/bubble");
+var _useLatestRef = require("../../../hooks/useLatestRef");
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 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); }
@@ -254,7 +255,10 @@ const Bubble = props => {
       chartInstanceRef.current.setOption(chartOption, true);
     }
   }, [chartOption, data]);
+  const onChartRef = (0, _useLatestRef.useLatestRef)(onChart);
 
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   // Initialize the chart
   (0, _react.useEffect)(() => {
     if (!chartRef.current) return;
@@ -267,7 +271,7 @@ const Bubble = props => {
       chart = echarts.init(chartRef.current);
       chartInstanceRef.current = chart;
       // Call the onChart callback on first initialization
-      onChart?.(chart);
+      onChartRef.current?.(chart);
     }
 
     // Resize first so echarts picks up the correct container size, then apply the option
@@ -289,7 +293,7 @@ const Bubble = props => {
         chartInstanceRef.current?.off("click", onClick);
       }
     };
-  }, [chartOption, containerSize.width, containerSize.height, handleResize, onChart, onClick]);
+  }, [chartOption, containerSize.width, containerSize.height, handleResize, onChartRef, onClick]);
 
   // Dispose the chart instance when the component unmounts
   (0, _react.useEffect)(() => {