@hsu-react/ui 2.5.2 → 2.5.4

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/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/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/index.js

@@ -147,12 +147,30 @@ const Menu = props => {
   });
 
   // 次级菜单默认带一段头部（至少给出返回入口），调用方可用 secondaryHeader 整块换掉
-  return secondary ? /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
-    className: _indexModule.default.secondaryWrap,
-    children: [secondaryHeader ?? /*#__PURE__*/(0, _jsxRuntime.jsx)(_SecondaryHeader.default, {
-      collapsed: collapsed,
-      theme: theme
-    }), menu]
+  if (secondary) {
+    return /*#__PURE__*/(0, _jsxRuntime.jsxs)("div", {
+      className: (0, _classnames.default)(_indexModule.default.scrollHost, _indexModule.default.secondaryWrap),
+      children: [secondaryHeader ?? /*#__PURE__*/(0, _jsxRuntime.jsx)(_SecondaryHeader.default, {
+        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__*/(0, _jsxRuntime.jsx)("div", {
+    className: _indexModule.default.scrollHost,
+    children: menu
   }) : menu;
 };
 var _default = exports.default = Menu;

package/lib/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hsu-react/ui",
-  "version": "2.5.2",
+  "version": "2.5.4",
   "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__/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() {}
+  };
+}

package/src/components/Chart/Bubble/index.tsx

@@ -12,6 +12,7 @@ import {
   defaultBubbleColorList,
   drawCircles,
 } from "../_utils/bubble";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 
 export interface BubbleDataItem {
   name: string;
@@ -370,6 +371,10 @@ const Bubble: React.FC<ChartBubbleProps> = (props) => {
     }
   }, [chartOption, data]);
 
+  const onChartRef = useLatestRef(onChart);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   // Initialize the chart
   useEffect(() => {
     if (!chartRef.current) return;
@@ -382,7 +387,7 @@ const Bubble: React.FC<ChartBubbleProps> = (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
@@ -410,7 +415,7 @@ const Bubble: React.FC<ChartBubbleProps> = (props) => {
     containerSize.width,
     containerSize.height,
     handleResize,
-    onChart,
+    onChartRef,
     onClick,
   ]);
 

package/src/components/Chart/Common/index.tsx

@@ -3,6 +3,7 @@ import useContainerReady from "../_hooks/useContainerReady";
 import styles from "../index.module.scss";
 import { ChartCommonProps, ChartOptionType, ChartsOption } from "..";
 import * as echarts from "echarts";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 
 const Common: React.FC<ChartCommonProps> = (props) => {
   const { className, style, onChart, ...coreOption } = props;
@@ -31,6 +32,10 @@ const Common: React.FC<ChartCommonProps> = (props) => {
     chartInstanceRef.current?.resize();
   }, []);
 
+  const onChartRef = useLatestRef(onChart);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   // Initialize the chart
   useEffect(() => {
     if (!chartRef.current || !containerReady) return;
@@ -46,7 +51,7 @@ const Common: React.FC<ChartCommonProps> = (props) => {
     chart.setOption(chartOption as ChartOptionType, true);
 
     // Chart-ready callback (can be used for legend auto-scroll, etc.)
-    onChart?.(chart);
+    onChartRef.current?.(chart);
 
     // Add resize listener
     window.addEventListener("resize", handleResize);
@@ -61,7 +66,7 @@ const Common: React.FC<ChartCommonProps> = (props) => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize, onChart,
+  }, [chartOption, handleResize, onChartRef,
     containerReady,
   ]);
 

package/src/components/Chart/Heatmap/index.tsx

@@ -9,6 +9,7 @@ import {
 } from "../_utils/heatmap";
 import { resolveChartChrome } from "../_utils/chartTheme";
 import useIsDark from "../../../hooks/useIsDark";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 
 export interface HeatmapDataItem {
   /** X-axis index or name */
@@ -266,6 +267,10 @@ const Heatmap: React.FC<ChartHeatmapProps> = (props) => {
     chartInstanceRef.current?.resize();
   }, []);
 
+  const onChartRef = useLatestRef(onChart);
+
+  // 回调 prop 不进依赖数组：消费方传内联箭头时每次渲染都是新引用，effect 会跟着
+  // 重跑并再调一次回调 —— 回调里 setState 就是死循环（详见 Input/TextArea 的说明）
   // Initialize the chart
   useEffect(() => {
     if (!chartRef.current || !containerReady) return;
@@ -276,7 +281,7 @@ const Heatmap: React.FC<ChartHeatmapProps> = (props) => {
       chart = echarts.init(chartRef.current);
       chartInstanceRef.current = chart;
       // Call the onChart callback on first initialization
-      onChart?.(chart);
+      onChartRef.current?.(chart);
     }
 
     // Apply the option
@@ -304,7 +309,7 @@ const Heatmap: React.FC<ChartHeatmapProps> = (props) => {
         chartInstanceRef.current?.off("click", onClick);
       }
     };
-  }, [chartOption, handleResize, onChart, onClick,
+  }, [chartOption, handleResize, onChartRef, onClick,
     containerReady,
   ]);