@hsu-react/ui 2.5.3 → 2.5.5

package/src/components/Input/TextArea/index.test.tsx

@@ -0,0 +1,208 @@
+import React, { useState } from "react";
+import { makeAutoObservable } from "mobx";
+import { observer } from "mobx-react-lite";
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+
+import TextArea from ".";
+
+/** 受控消费方：`value` 从自己的 state 来，`onChange` 写回同一份 state */
+function Controlled({
+  onChange,
+  initial = "",
+  ...rest
+}: {
+  onChange: (v: string) => void;
+  initial?: string;
+} & Record<string, unknown>) {
+  const [v, setV] = useState(initial);
+
+  return (
+    <TextArea
+      value={v}
+      // 内联箭头：每次渲染都是新引用。消费方最常见的写法，组件必须扛得住
+      onChange={(next) => {
+        setV(next);
+        onChange(next);
+      }}
+      {...rest}
+    />
+  );
+}
+
+const type = (el: HTMLElement, value: string) =>
+  fireEvent.change(el, { target: { value } });
+
+describe("TextArea", () => {
+  it("消费方传内联箭头 onChange 时不进入无限循环", async () => {
+    const spy = vi.fn();
+    render(<Controlled onChange={spy} />);
+    const ta = screen.getByRole("textbox") as HTMLTextAreaElement;
+
+    type(ta, "a");
+
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("a"));
+    // 敲一个字只该回调一次；进了循环这里会是几十上百次
+    expect(spy.mock.calls.length).toBeLessThanOrEqual(2);
+    expect(ta.value).toBe("a");
+
+    spy.mockClear();
+    type(ta, "ab");
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("ab"));
+    expect(spy.mock.calls.length).toBeLessThanOrEqual(2);
+    expect(ta.value).toBe("ab");
+  });
+
+  it("全是空白的输入回调成空串，且不反复回调", async () => {
+    const spy = vi.fn();
+    render(<Controlled onChange={spy} />);
+    const ta = screen.getByRole("textbox") as HTMLTextAreaElement;
+
+    type(ta, "   ");
+
+    await waitFor(() => expect(spy).toHaveBeenCalledWith(""));
+    expect(spy.mock.calls.length).toBeLessThanOrEqual(2);
+  });
+
+  it("非受控：不传 value 时内部自己维护，onChange 照常只回调一次", async () => {
+    const spy = vi.fn();
+    render(<TextArea defaultValue="x" onChange={spy} />);
+    const ta = screen.getByRole("textbox") as HTMLTextAreaElement;
+    expect(ta.value).toBe("x");
+
+    type(ta, "xy");
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("xy"));
+    expect(spy.mock.calls.length).toBe(1);
+    expect(ta.value).toBe("xy");
+  });
+
+  it("外部改 value 会同步进输入框，且不额外触发 onChange", async () => {
+    const spy = vi.fn();
+    const { rerender } = render(<TextArea value="a" onChange={spy} />);
+    const ta = screen.getByRole("textbox") as HTMLTextAreaElement;
+    expect(ta.value).toBe("a");
+
+    rerender(<TextArea value="b" onChange={spy} />);
+    await waitFor(() => expect(ta.value).toBe("b"));
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("maxLength 生效，en 时不截断", () => {
+    const { unmount } = render(<TextArea maxLength={3} />);
+    expect(
+      (screen.getByRole("textbox") as HTMLTextAreaElement).maxLength,
+    ).toBe(3);
+    unmount();
+
+    render(<TextArea maxLength={3} en />);
+    expect(
+      (screen.getByRole("textbox") as HTMLTextAreaElement).maxLength,
+    ).toBe(-1);
+  });
+
+  it("disabled 透传", () => {
+    render(<TextArea disabled />);
+    expect((screen.getByRole("textbox") as HTMLTextAreaElement).disabled).toBe(
+      true,
+    );
+  });
+
+  it("中文输入法组字期间不回调，组完才回调一次", async () => {
+    const spy = vi.fn();
+    render(<Controlled onChange={spy} />);
+    const ta = screen.getByRole("textbox") as HTMLTextAreaElement;
+
+    fireEvent.compositionStart(ta);
+    type(ta, "n");
+    type(ta, "ni");
+    await new Promise((r) => setTimeout(r, 20));
+    expect(spy).not.toHaveBeenCalled();
+
+    fireEvent.compositionEnd(ta);
+    type(ta, "你");
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("你"));
+    expect(spy.mock.calls.length).toBeLessThanOrEqual(2);
+  });
+  /**
+   * 这一条是真正的回归用例：父级用 MobX（`useSyncExternalStore`）回写 value，
+   * React 会以同步优先级重渲，组件内排在 effect 里的 state 更新会被那一趟跳过。
+   * 旧实现用 state 记「通知过没有」，读到过期记账就会再发一次通知 → 死循环。
+   */
+  it("父级是 MobX observer、又传内联箭头时也不循环", async () => {
+    class Store {
+      private _draft: { body: string } | undefined = { body: "hello" };
+      constructor() {
+        makeAutoObservable(this);
+      }
+      get draft() {
+        return this._draft;
+      }
+      setBody = (body: string) => {
+        if (this._draft) this._draft = { ...this._draft, body };
+      };
+    }
+
+    const store = new Store();
+    const spy = vi.fn();
+    const Cmp = observer(() => {
+      const { draft, setBody } = store;
+      if (!draft) return null;
+
+      return (
+        <TextArea
+          value={draft.body}
+          onChange={(v) => {
+            spy(v);
+            setBody(v);
+          }}
+        />
+      );
+    });
+
+    render(<Cmp />);
+    const ta = screen.getByRole("textbox") as HTMLTextAreaElement;
+    type(ta, "helloX");
+
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("helloX"));
+    await new Promise((r) => setTimeout(r, 100));
+    expect(spy.mock.calls.length).toBeLessThanOrEqual(2);
+    expect(store.draft?.body).toBe("helloX");
+  });
+
+  it("内联 getRef 也不会把消费方转崩", async () => {
+    const seen: unknown[] = [];
+    const Cmp = () => {
+      const [, setTick] = useState(0);
+
+      return (
+        <TextArea
+          getRef={(r) => {
+            seen.push(r);
+            setTick((n) => n + 1);
+          }}
+        />
+      );
+    };
+
+    render(<Cmp />);
+    await new Promise((r) => setTimeout(r, 100));
+    // 只在挂载时交一次 ref；旧写法会跟着每次渲染重跑，这里会是几十上百次
+    expect(seen.length).toBe(1);
+    expect(seen[0]).not.toBeNull();
+  });
+
+  it("外部把 value 置为 undefined 会清空", async () => {
+    const { rerender } = render(<TextArea value="a" />);
+    const ta = screen.getByRole("textbox") as HTMLTextAreaElement;
+    expect(ta.value).toBe("a");
+
+    rerender(<TextArea value={undefined} />);
+    await waitFor(() => expect(ta.value).toBe(""));
+  });
+
+  it("autoSize / textAreaClassName 等透传照旧", () => {
+    render(<TextArea textAreaClassName="my-area" autoSize={{ minRows: 3 }} />);
+    const ta = screen.getByRole("textbox") as HTMLTextAreaElement;
+    expect(ta.className).toContain("my-area");
+  });
+});

package/src/components/Input/TextArea/index.tsx

@@ -6,6 +6,7 @@ import React, { ReactNode, useEffect, useRef, useState } from "react";
 
 import classNames from "classnames";
 import styles from "./index.module.scss";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 
 export interface TextAreaProps
   extends Omit<
@@ -43,51 +44,71 @@ const TextArea: React.FC<TextAreaProps> = (props) => {
     style,
     ...inputConfig
   } = props;
-  const [isComposing, setComposing] = useState<boolean>(false);
   const ref = useRef<TextAreaRef>(null);
   const [focused, setFocused] = useState<boolean>(false);
 
   // On initialization, prefer value, then fall back to defaultValue
   const initialValue =
     value !== undefined
-      ? value?.toString() ?? ""
+      ? (value?.toString() ?? "")
       : defaultValue !== undefined
-      ? defaultValue?.toString() ?? ""
-      : "";
+        ? (defaultValue?.toString() ?? "")
+        : "";
 
   const [_value, setValue] = useState<string>(initialValue);
-  const [lastValue, setLastValue] = useState<string>(initialValue);
   const [hasError, setHasError] = useState<boolean>(false);
   const prevValueRef = useRef<typeof value>(undefined);
 
-  useEffect(() => {
-    if (!isComposing && _value !== lastValue) {
-      const trimmedValue = _value.trim();
-      const finalValue = trimmedValue === "" ? "" : _value;
-      setLastValue(finalValue);
-      onChange?.(finalValue);
-    }
-  }, [isComposing, onChange, _value, lastValue]);
+  const getRefRef = useLatestRef(getRef);
+
+  // 输入法组字期间不往外通知。放 ref 不放 state：它只影响「要不要发通知」，
+  // 不参与渲染，而且必须在同一次事件里立刻生效
+  const composingRef = useRef(false);
+  // 最近一次通知出去的原文。只用来去掉 compositionend 与 input 两个事件的重复通知
+  const notifiedRef = useRef<string>(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` 的引用稳不稳定完全不影响正确性：永远调到最新的那个回调，
+   * 且只在真的有新文本时调一次。
+   */
+  const notify = (next: string) => {
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    // 全是空白等同于空：外部拿到的是 ""，但输入框里用户敲的空格照旧留着
+    onChange?.(next.trim() === "" ? "" : next);
+  };
 
   useEffect(() => {
     // Update internal state only when the external value prop actually changes
     if (prevValueRef.current !== value) {
       prevValueRef.current = value;
 
-      if (value !== undefined) {
-        setValue(value?.toString());
-        setLastValue(value?.toString());
-      } else {
-        // Clear only on initialization or when explicitly set to undefined externally
-        setValue("");
-        setLastValue("");
-      }
+      // 外部把值改了，之前通知过什么就不作数了，重新以外部值为准
+      const next = value !== undefined ? (value?.toString() ?? "") : "";
+      notifiedRef.current = next;
+      setValue(next);
     }
   }, [value]);
 
+  // 只在挂载时把 ref 交出去。`getRef` 进依赖数组同样会被内联箭头带着每次渲染重跑，
+  // 消费方在里面 setState 就是一个死循环
   useEffect(() => {
-    getRef?.(ref.current);
-  }, [getRef]);
+    getRefRef.current?.(ref.current);
+  }, [getRefRef]);
 
   useEffect(() => {
     // Use a MutationObserver to watch for error state changes
@@ -95,7 +116,7 @@ const TextArea: React.FC<TextAreaProps> = (props) => {
       if (ref.current?.resizableTextArea?.textArea) {
         const textAreaElement = ref.current.resizableTextArea.textArea;
         const hasErrorClass = textAreaElement.classList.contains(
-          "ant-input-status-error"
+          "ant-input-status-error",
         );
         setHasError(hasErrorClass);
       }
@@ -135,16 +156,21 @@ const TextArea: React.FC<TextAreaProps> = (props) => {
       {prefix}
       <AntdTextArea
         ref={ref}
-        onCompositionStart={() => setComposing(true)}
-        onCompositionEnd={() => {
-          setTimeout(() => {
-            setComposing(false);
-          }, 1);
+        onCompositionStart={() => {
+          composingRef.current = true;
+        }}
+        onCompositionEnd={(e) => {
+          composingRef.current = false;
+          // 组完字的那一下自己发通知。浏览器之间 compositionend 与 input 的先后
+          // 不一致，`notify` 里按原文去重，两种顺序都只会发出一次
+          notify(e.currentTarget.value);
         }}
         value={_value}
         autoSize={disabled && text ? autoSize || { minRows: 1 } : autoSize}
         onChange={(e) => {
-          setValue(e.target.value);
+          const next = e.target.value;
+          setValue(next);
+          if (!composingRef.current) notify(next);
         }}
         onFocus={(e) => {
           setFocused(true);

package/src/components/Input/index.test.tsx

@@ -0,0 +1,189 @@
+import React, { useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { makeAutoObservable } from "mobx";
+import { observer } from "mobx-react-lite";
+
+import Input from ".";
+import Slider from "../Slider";
+
+/**
+ * `Input` / `Password` / `Search` / `Number` / `Slider` 与 `TextArea` 是同一套写法，
+ * 也曾是同一个缺陷：`onChange` 进 effect 依赖数组、effect 体内又调它。
+ * 这里逐个盯住「消费方传内联箭头也不会死循环」这条底线。
+ */
+
+class Store {
+  private _v = "";
+  constructor() {
+    makeAutoObservable(this);
+  }
+  get v() {
+    return this._v;
+  }
+  set = (v: string) => {
+    this._v = v;
+  };
+}
+
+const type = (el: HTMLElement, value: string) =>
+  fireEvent.change(el, { target: { value } });
+
+const cases: Array<[string, React.FC<{ value: string; onChange: (v: string) => void }>]> = [
+  ["Input", (p) => <Input {...p} />],
+  ["Input.Password", (p) => <Input.Password {...p} />],
+  ["Input.Search", (p) => <Input.Search {...p} />],
+];
+
+describe.each(cases)("%s", (name, Cmp) => {
+  it("父级是 MobX observer、又传内联箭头时不进入无限循环", async () => {
+    const store = new Store();
+    const spy = vi.fn();
+    const Page = observer(() => (
+      <Cmp
+        value={store.v}
+        onChange={(v) => {
+          spy(v);
+          store.set(v);
+        }}
+      />
+    ));
+
+    render(<Page />);
+    const el = document.querySelector("input") as HTMLInputElement;
+    type(el, "a");
+
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("a"));
+    await new Promise((r) => setTimeout(r, 100));
+    expect(spy.mock.calls.length).toBeLessThanOrEqual(2);
+    expect(store.v).toBe("a");
+  });
+
+  it("受控回写、外部改值、组字期间不通知", async () => {
+    const spy = vi.fn();
+    const Page = () => {
+      const [v, setV] = useState("");
+
+      return (
+        <Cmp
+          value={v}
+          onChange={(next) => {
+            spy(next);
+            setV(next);
+          }}
+        />
+      );
+    };
+
+    render(<Page />);
+    const el = document.querySelector("input") as HTMLInputElement;
+
+    fireEvent.compositionStart(el);
+    type(el, "n");
+    await new Promise((r) => setTimeout(r, 20));
+    expect(spy).not.toHaveBeenCalled();
+
+    fireEvent.compositionEnd(el, { currentTarget: el });
+    type(el, "你");
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("你"));
+    expect(el.value).toBe("你");
+  });
+});
+
+describe("Input", () => {
+  it("escapeCharacters：对内显示原文，对外给转义值", async () => {
+    const spy = vi.fn();
+    render(<Input escapeCharacters={[","]} onChange={spy} />);
+    const el = screen.getByRole("textbox") as HTMLInputElement;
+
+    type(el, "a,b");
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("a\\,b"));
+    expect(el.value).toBe("a,b");
+    expect(spy.mock.calls.length).toBe(1);
+  });
+
+  it("外部改 value 会同步进输入框，且不额外触发 onChange", async () => {
+    const spy = vi.fn();
+    const { rerender } = render(<Input value="a" onChange={spy} />);
+    const el = screen.getByRole("textbox") as HTMLInputElement;
+    expect(el.value).toBe("a");
+
+    rerender(<Input value="b" onChange={spy} />);
+    await waitFor(() => expect(el.value).toBe("b"));
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("内联 getRef 只在挂载时交一次 ref", async () => {
+    const seen: unknown[] = [];
+    const Page = () => {
+      const [, setTick] = useState(0);
+
+      return (
+        <Input
+          getRef={(r) => {
+            seen.push(r);
+            setTick((n) => n + 1);
+          }}
+        />
+      );
+    };
+
+    render(<Page />);
+    await new Promise((r) => setTimeout(r, 100));
+    expect(seen.length).toBe(1);
+  });
+});
+
+describe("Input.Number", () => {
+  it("父级把值转成数字回写、又传内联箭头时不进入无限循环", async () => {
+    const spy = vi.fn();
+    const Page = () => {
+      const [v, setV] = useState<string | number>("");
+
+      return (
+        <Input.Number
+          value={v}
+          onChange={(next) => {
+            spy(next);
+            // 模拟上游把值转成数字（FormItem 的默认行为），制造一个回环
+            setV(next === "" ? "" : Number(next));
+          }}
+        />
+      );
+    };
+
+    render(<Page />);
+    const el = document.querySelector("input") as HTMLInputElement;
+
+    type(el, "1");
+    await waitFor(() => expect(spy).toHaveBeenCalledWith("1"));
+    await new Promise((r) => setTimeout(r, 100));
+    expect(spy.mock.calls.length).toBeLessThanOrEqual(2);
+    expect(el.value).toBe("1");
+  });
+});
+
+describe("Slider", () => {
+  it("内联箭头不循环", async () => {
+    const spy = vi.fn();
+    const Page = () => {
+      const [v, setV] = useState(0);
+
+      return (
+        <Slider
+          value={v}
+          onChange={(next) => {
+            spy(next);
+            setV(next as number);
+          }}
+        />
+      );
+    };
+
+    const { container } = render(<Page />);
+    expect(container.querySelector(".ant-slider")).toBeTruthy();
+    await new Promise((r) => setTimeout(r, 50));
+    // 没有交互就不该有任何通知
+    expect(spy).not.toHaveBeenCalled();
+  });
+});

package/src/components/Input/index.tsx

@@ -14,7 +14,7 @@ import TextArea, { TextAreaProps } from "./TextArea";
 import classNames from "classnames";
 import styles from "./index.module.scss";
 import RangeInput, { RangeInputProps } from "./Range";
-import { useDebounceEffect } from "ahooks";
+import { useLatestRef } from "../../hooks/useLatestRef";
 
 export interface InputProps extends Omit<
   AntdInputProps,
@@ -54,8 +54,11 @@ const Input: InputFC = (props) => {
     escapeCharacters,
     ...inputConfig
   } = props;
-  const [isComposing, setComposing] = useState<boolean>(false);
   const ref = useRef<InputRef>(null);
+  const getRefRef = useLatestRef(getRef);
+  // 输入法组字期间不往外通知。放 ref 不放 state：它只决定「要不要发通知」，
+  // 不参与渲染，而且必须在同一次事件里立刻生效
+  const composingRef = useRef(false);
 
   // Handle escaping: if the value contains characters listed in escapeCharacters, prefix them with an escape
   const escapeValue = useCallback(
@@ -143,25 +146,23 @@ const Input: InputFC = (props) => {
   const initialValue = getInitialValue();
 
   const [_value, setValue] = useState<string>(initialValue);
-  const [lastValue, setLastValue] = useState<string>(initialValue);
   const prevValueRef = useRef<typeof value>(undefined);
-
-  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 = useRef<string>(initialValue);
+
+  /**
+   * `onChange` 是「用户改了输入」这个**事件**的通知，不是从 state 推导出来的结果，
+   * 所以在事件处理里发，不在 effect 里发。详见 `TextArea/index.tsx` 里那段说明——
+   * 旧写法（依赖数组里放 `onChange`、体内又调它、用 state 记「通知过没有」）
+   * 会让传内联箭头的消费方死循环。
+   */
+  const notify = (next: string) => {
+    if (next === notifiedRef.current) return;
+    notifiedRef.current = next;
+    // 全是空白等同于空；escapeCharacters 命中时对外给转义后的值
+    onChange?.(escapeValue(next.trim() === "" ? "" : next));
+  };
 
   useEffect(() => {
     // Update internal state only when the external value prop actually changes
@@ -173,19 +174,21 @@ const Input: InputFC = (props) => {
           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` 进依赖数组同样会被内联箭头带着每次渲染重跑
   useEffect(() => {
-    getRef?.(ref.current);
-  }, [getRef]);
+    getRefRef.current?.(ref.current);
+  }, [getRefRef]);
 
   return (
     <Tooltip placement="topLeft" {...tooltip}>
@@ -193,11 +196,14 @@ const Input: InputFC = (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) => {
@@ -205,6 +211,7 @@ const Input: InputFC = (props) => {
           const inputValue = e.target.value;
           const unescapedInput = unescapeValue(inputValue);
           setValue(unescapedInput);
+          if (!composingRef.current) notify(unescapedInput);
         }}
         className={classNames(styles.antdInput, className)}
         type={type}