@hsu-react/ui 2.5.6 → 2.5.8

package/src/__tests__/freshObjectDeps.test.tsx

@@ -0,0 +1,380 @@
+import { fireEvent, render, renderHook, act } from "@testing-library/react";
+import { Form } from "antd";
+import React, { ReactElement, ReactNode } from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * 2.5.7：把 2.5.6 守卫钉住的「依赖数组里放每渲染新建对象」欠账逐处清掉后的收益证明。
+ *
+ * 每处缺陷两条用例：
+ * 1. **输入没变时不再重算**；
+ * 2. **输入真变时仍正确更新**——比前一条更重要，改坏了比不改糟。
+ *
+ * 「不再重算」有两种判据，按缺陷形态选：
+ *
+ * - **对照法**（字面量默认值那一类）：同一个组件渲染两次，一次**不传**那个 prop
+ *   （走解构默认值，修之前每渲染都是新对象），一次传**模块级稳定引用**的等价空值。
+ *   两边渲染出的 DOM 完全一样，antd 内部噪声完全抵消，差值只剩「默认值是不是每次
+ *   都新建」这一件事。修之前不传那边严格更多，修之后必须**相等**。
+ *   次数由下面的 hook 探针统计（包了 `useMemo` / `useEffect`，只数工厂/回调实跑次数）。
+ *
+ * - **引用法**（rest 包那一类，本来就没有「传稳定引用」的对照）：直接断言派生值
+ *   在重渲染后**还是同一个引用**，也就是 memo 真的命中了。
+ */
+
+const probe = { memo: 0, effect: 0 };
+(globalThis as Record<string, unknown>).__freshDepsProbe = probe;
+
+vi.mock("react", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react")>();
+  const counters = () =>
+    (globalThis as Record<string, unknown>).__freshDepsProbe as typeof probe;
+  const useMemo = (fn: () => unknown, deps: unknown[]) =>
+    actual.useMemo(() => {
+      counters().memo++;
+      return fn();
+    }, deps);
+  const useEffect = (fn: () => unknown, deps: unknown[]) =>
+    actual.useEffect(() => {
+      counters().effect++;
+      return fn() as ReturnType<React.EffectCallback>;
+    }, deps);
+  // 命名导入与 `React.useMemo(...)` 这两种写法库里都有，两条路都要包上，
+  // 否则漏掉的那一半会让用例「怎么改都通过」，等于没测
+  return {
+    ...actual,
+    useMemo,
+    useEffect,
+    default: {
+      ...(actual as unknown as { default: Record<string, unknown> }).default,
+      useMemo,
+      useEffect,
+    },
+  };
+});
+
+import CheckboxGroup from "../components/Checkbox/CheckboxGroup";
+import Operate from "../components/Operate";
+import Pagination from "../components/Pagination";
+import Select from "../components/Select";
+import Tree from "../components/Tree";
+import ItemContainer from "../components/FormItem/ItemContainer";
+import FormCodeMirror from "../components/FormItem/FormCodeMirror";
+import { useSearchCommon } from "../components/Search/_hooks/useSearchCommon";
+import useTableColumns from "../components/Table/_hooks/useTableColumns";
+
+/** 渲染一次再用**同样的 props** 重渲染一次，返回第二次渲染的重算次数 */
+function rerenderCost(make: () => ReactElement) {
+  const { rerender, unmount } = render(make());
+  const memo0 = probe.memo;
+  const effect0 = probe.effect;
+  // 必须新建 element：传同一个 element 对象 React 会直接跳过重渲染，测不到东西
+  rerender(make());
+  const cost = { memo: probe.memo - memo0, effect: probe.effect - effect0 };
+  unmount();
+  return cost;
+}
+
+beforeEach(() => {
+  probe.memo = 0;
+  probe.effect = 0;
+});
+
+// 对照组用的模块级稳定引用：内容与解构默认值完全一致，只是引用恒定
+const STABLE_EMPTY: never[] = [];
+
+/* --------------------------- 字面量默认值：对照法 --------------------------- */
+
+describe("Checkbox.Group：options 的默认值不再每渲染新建", () => {
+  it("不传 options 时的重算次数 = 传稳定空数组（memo 命中了）", () => {
+    const omitted = rerenderCost(() => <CheckboxGroup />);
+    const control = rerenderCost(() => <CheckboxGroup options={STABLE_EMPTY} />);
+    expect(omitted.memo).toBe(control.memo);
+  });
+
+  it("options 真变了仍然渲染出新选项", () => {
+    const { rerender, getByText, queryByText } = render(
+      <CheckboxGroup options={[{ label: "甲", value: "a" }]} />,
+    );
+    expect(getByText("甲")).toBeTruthy();
+    rerender(<CheckboxGroup options={[{ label: "乙", value: "b" }]} />);
+    expect(queryByText("甲")).toBeNull();
+    expect(getByText("乙")).toBeTruthy();
+  });
+});
+
+describe("Operate：menu 的默认值不再每渲染新建", () => {
+  it("不传 menu 时的重算次数 = 传稳定空数组", () => {
+    const omitted = rerenderCost(() => <Operate title="编辑" />);
+    const control = rerenderCost(() => (
+      <Operate title="编辑" menu={STABLE_EMPTY} />
+    ));
+    expect(omitted.memo).toBe(control.memo);
+  });
+
+  it("menu 真变了仍然重新算出可见项", () => {
+    const { rerender, getByText, queryByText } = render(
+      <Operate title="更多" menu={[{ title: "删除" }]} />,
+    );
+    expect(getByText("删除")).toBeTruthy();
+    rerender(<Operate title="更多" menu={[{ title: "归档" }]} />);
+    expect(queryByText("删除")).toBeNull();
+    expect(getByText("归档")).toBeTruthy();
+  });
+});
+
+describe("Pagination：pageSizeOptions 的默认值不再每渲染新建", () => {
+  it("不传 pageSizeOptions 时的重算次数 = 传稳定空数组", () => {
+    const omitted = rerenderCost(() => (
+      <Pagination total={100} showSizeChanger />
+    ));
+    const control = rerenderCost(() => (
+      <Pagination total={100} showSizeChanger pageSizeOptions={STABLE_EMPTY} />
+    ));
+    expect(omitted.memo).toBe(control.memo);
+  });
+
+  it("pageSizeOptions / pageSize 真变了仍然重新算出档位（当前 pageSize 始终在内）", () => {
+    const { rerender, container } = render(
+      <Pagination
+        total={100}
+        showSizeChanger
+        pageSize={10}
+        pageSizeOptions={[10, 20]}
+      />,
+    );
+    expect(container.textContent).toContain("10");
+    // 换一组档位，且当前 pageSize 不在其中：仍要被补进去（原逻辑）
+    rerender(
+      <Pagination
+        total={100}
+        showSizeChanger
+        pageSize={15}
+        pageSizeOptions={[30, 50]}
+      />,
+    );
+    expect(container.textContent).toContain("15");
+  });
+});
+
+describe("Select.AutoComplete：options 的默认值不再每渲染新建", () => {
+  it("不传 options 时的重算次数 = 传稳定空数组", () => {
+    const omitted = rerenderCost(() => <Select.AutoComplete />);
+    const control = rerenderCost(() => (
+      <Select.AutoComplete options={STABLE_EMPTY} />
+    ));
+    expect(omitted.memo).toBe(control.memo);
+  });
+
+  it("options 真变了仍然重新算出下拉项", () => {
+    const { rerender, container } = render(
+      <Select.AutoComplete options={[{ value: "alpha" }]} />,
+    );
+    const input = container.querySelector("input")!;
+    fireEvent.mouseDown(input);
+    fireEvent.focus(input);
+    expect(document.body.textContent).toContain("alpha");
+    rerender(<Select.AutoComplete options={[{ value: "beta" }]} />);
+    expect(document.body.textContent).toContain("beta");
+    expect(document.body.textContent).not.toContain("alpha");
+  });
+});
+
+describe("Tree：treeData 的默认值不再每渲染新建", () => {
+  it("不传 treeData 时的重算/重跑次数 = 传稳定空数组", () => {
+    const omitted = rerenderCost(() => <Tree defaultExpandLevel={1} />);
+    const control = rerenderCost(() => (
+      <Tree defaultExpandLevel={1} treeData={STABLE_EMPTY} />
+    ));
+    expect(omitted.memo).toBe(control.memo);
+    expect(omitted.effect).toBe(control.effect);
+  });
+
+  it("treeData 真变了仍然渲染出新节点", () => {
+    const { rerender, queryByText } = render(
+      <Tree treeData={[{ key: "1", value: "1", title: "节点甲" }]} />,
+    );
+    expect(queryByText("节点甲")).toBeTruthy();
+    rerender(<Tree treeData={[{ key: "2", value: "2", title: "节点乙" }]} />);
+    expect(queryByText("节点甲")).toBeNull();
+    expect(queryByText("节点乙")).toBeTruthy();
+  });
+});
+
+describe("FormCodeMirror：rules 的默认值不再每渲染新建", () => {
+  it("不传 rules 时的重算次数 = 传稳定空数组", () => {
+    const omitted = rerenderCost(() => (
+      <Form>
+        <FormCodeMirror name="sql" label="SQL" />
+      </Form>
+    ));
+    const control = rerenderCost(() => (
+      <Form>
+        <FormCodeMirror name="sql" label="SQL" rules={STABLE_EMPTY} />
+      </Form>
+    ));
+    expect(omitted.memo).toBe(control.memo);
+  });
+
+  it("rules 真变了仍然并进 mergedRules（必填标记跟着出现）", () => {
+    const { container, rerender } = render(
+      <Form>
+        <FormCodeMirror name="sql" label="SQL" />
+      </Form>,
+    );
+    expect(container.querySelector(".ant-form-item-required")).toBeNull();
+    rerender(
+      <Form>
+        <FormCodeMirror
+          name="sql"
+          label="SQL"
+          rules={[{ required: true, message: "必填" }]}
+        />
+      </Form>,
+    );
+    expect(container.querySelector(".ant-form-item-required")).toBeTruthy();
+  });
+});
+
+/* --------------------------- rest 包 / hook：引用法 -------------------------- */
+
+describe("ItemContainer：tips / tipsConfig 不再让 label 的 memo 恒不命中", () => {
+  /** 借 labelRender 这个出口把内部算出来的 label 原样捞出来比引用 */
+  const makeItem =
+    (seen: ReactNode[], props: Record<string, unknown> = {}) =>
+    () => (
+      <Form>
+        <ItemContainer
+          label="名称"
+          name="name"
+          labelRender={(node) => {
+            seen.push(node);
+            return node;
+          }}
+          {...props}
+        />
+      </Form>
+    );
+
+  it("不传 tips 时，重渲染复用同一份 label", () => {
+    const seen: ReactNode[] = [];
+    const make = makeItem(seen);
+    const { rerender } = render(make());
+    rerender(make());
+    expect(seen.length).toBeGreaterThanOrEqual(2);
+    expect(seen[seen.length - 1]).toBe(seen[0]);
+  });
+
+  it("传了 tips（走 tipsConfig 那条分支）时，内容没变也复用同一份 label", () => {
+    const seen: ReactNode[] = [];
+    // 每次渲染都是新的对象字面量：修之前这让 label 的 memo 恒不命中
+    const make = () =>
+      makeItem(seen, {
+        tips: { title: "说明", icon: "material-symbols:help" },
+      })();
+    const { rerender } = render(make());
+    rerender(make());
+    expect(seen.length).toBeGreaterThanOrEqual(2);
+    expect(seen[seen.length - 1]).toBe(seen[0]);
+  });
+
+  it("label 真变了仍然算出新的 label", () => {
+    const seen: ReactNode[] = [];
+    const { rerender, getByText } = render(makeItem(seen, { label: "名称" })());
+    rerender(makeItem(seen, { label: "标题" })());
+    expect(seen[seen.length - 1]).not.toBe(seen[0]);
+    expect(getByText("标题")).toBeTruthy();
+  });
+
+  it("tips 内容真变了仍然算出新的 label", () => {
+    const seen: ReactNode[] = [];
+    const { rerender } = render(
+      makeItem(seen, { tips: { title: "说明一" } })(),
+    );
+    rerender(makeItem(seen, { tips: { title: "说明二" } })());
+    expect(seen[seen.length - 1]).not.toBe(seen[0]);
+  });
+});
+
+const STABLE_SEARCH_ITEMS = [{ label: "名称", name: "name" }];
+
+describe("useSearchCommon：moreSearchItems 的默认值不再每渲染新建", () => {
+  const useSubject = (moreSearchItems?: unknown[]) => {
+    const [form] = Form.useForm();
+    return useSearchCommon({
+      form,
+      searchItems: STABLE_SEARCH_ITEMS,
+      ...(moreSearchItems ? { moreSearchItems } : {}),
+      columnNum: 3,
+      autoAdaptWidth: false,
+      defaultExpanded: false,
+      showAllSearchItems: false,
+    } as never);
+  };
+
+  it("不传 moreSearchItems 时，重渲染复用同一份派生数组", () => {
+    const { result, rerender, unmount } = renderHook(() => useSubject());
+    const firstMore = result.current.visibleMoreSearchItems;
+    const firstCurrent = result.current.currentSearchItems;
+    rerender();
+    expect(result.current.visibleMoreSearchItems).toBe(firstMore);
+    expect(result.current.currentSearchItems).toBe(firstCurrent);
+    unmount();
+  });
+
+  it("moreSearchItems 真变了仍然重新算出展开后的列表", () => {
+    const { result, rerender, unmount } = renderHook(
+      ({ more }: { more: unknown[] }) => useSubject(more),
+      { initialProps: { more: [{ label: "更多甲", name: "a" }] } },
+    );
+    act(() => result.current.setExpand?.(true));
+    const before = result.current.currentSearchItems.length;
+    rerender({
+      more: [
+        { label: "更多甲", name: "a" },
+        { label: "更多乙", name: "b" },
+      ],
+    });
+    expect(result.current.currentSearchItems.length).toBe(before + 1);
+    expect(
+      result.current.currentSearchItems.some((item) => item.label === "更多乙"),
+    ).toBe(true);
+    unmount();
+  });
+});
+
+describe("useTableColumns：columns 的默认值不再每渲染新建", () => {
+  const baseParams = {
+    enhanceColumns: (c?: unknown) => c,
+    _pageNum: 1,
+    _pageSize: 10,
+  };
+
+  it("不传 columns 时，重渲染复用同一份 _columns（cloneDeep 不再空跑）", () => {
+    const { result, rerender, unmount } = renderHook(() =>
+      useTableColumns(baseParams as never),
+    );
+    const first = result.current._columns;
+    rerender();
+    expect(result.current._columns).toBe(first);
+    unmount();
+  });
+
+  it("columns 真变了仍然重新算出列", () => {
+    const { result, rerender, unmount } = renderHook(
+      ({ columns }: { columns: unknown[] }) =>
+        useTableColumns({ ...baseParams, columns } as never),
+      { initialProps: { columns: [{ title: "甲", dataIndex: "a" }] } },
+    );
+    expect(result.current._columns[0].title).toBe("甲");
+    rerender({
+      columns: [
+        { title: "甲", dataIndex: "a" },
+        { title: "乙", dataIndex: "b" },
+      ],
+    });
+    expect(result.current._columns).toHaveLength(2);
+    expect(result.current._columns[1].title).toBe("乙");
+    unmount();
+  });
+});

package/src/__tests__/freshObjectDepsGuard.test.ts

@@ -31,36 +31,35 @@ import {
 const SRC = path.resolve(__dirname, "..");
 const HOOK_RE = /use(?:Memo|Callback|(?:Layout)?Effect)\(/g;
 
-/** `文件相对路径::依赖名` → 无害的理由（确实无害才登记这里） */
-const ALLOWED: Record<string, string> = {};
+/**
+ * 正式白名单：`文件相对路径::依赖名` → `{ raw, why }`。
+ *
+ * 只登记**经过逐处判断、确认不是缺陷**的写法，且必须精确到依赖原文 `raw`：
+ * 同一个绑定换一种写法（比如从 `x.open` 变成裸 `x`）就不再匹配，会照常失败。
+ * 这样白名单不会变成整文件整绑定的免死金牌。
+ */
+const ALLOWED: Record<string, { raw: string; why: string }> = {
+  "components/Panel/ListPanel/ListModalPanel/index.tsx::modalConfig": {
+    raw: "modalConfig.open",
+    why: "依赖取的是 modalConfig.open 这个布尔值，不是那个新对象本身；布尔值按值比较，effect 只在弹窗真的开合时重跑，不存在恒不命中",
+  },
+};
 
 /**
- * 存量欠账：守卫上线（2.5.6）时就已经存在的命中。**它们不是无害的**，只是不在这
- * 一轮的改动范围内（这轮只修 Chart 一族）。修法与 Chart 相同：rest 包走
- * `useShallowStable`，字面量默认值提到模块级常量。
+ * 存量欠账：守卫上线（2.5.6）时就已经存在的命中。2.5.7 已逐处清完，名单为空。
  *
  * 这份名单**只许变短**——下面「只许变短」那条用例会在某项修好却忘了删时报错。
  * 新写的代码一律直接失败，不许往这里加。
  */
-const KNOWN_DEBT = [
-  "components/Checkbox/CheckboxGroup/index.tsx::options",
-  "components/FormItem/FormCodeMirror/index.tsx::rules",
-  "components/FormItem/ItemContainer/index.tsx::tipsConfig",
-  "components/Operate/index.tsx::menu",
-  "components/Pagination/index.tsx::pageSizeOptions",
-  "components/Panel/ListPanel/ListModalPanel/index.tsx::modalConfig",
-  "components/Search/_hooks/useSearchCommon.ts::moreSearchItems",
-  "components/Select/AutoCompleteSelect/index.tsx::options",
-  "components/Spreadsheet/index.tsx::xOptionsRest",
-  "components/Table/_hooks/useTableColumns.tsx::columns",
-  "components/Tree/index.tsx::treeData",
-];
+const KNOWN_DEBT: string[] = [];
 
 interface Hit {
   /** `文件相对路径::依赖名` */
   key: string;
   file: string;
   line: number;
+  /** 依赖数组里的原文（`x` 还是 `x.open`），白名单按它精确匹配 */
+  raw: string;
   why: string;
 }
 
@@ -73,10 +72,10 @@ function scan(): Hit[] {
     const fresh = freshObjectBindings(src);
     if (!fresh.size) continue;
 
-    for (const [line, dep] of hookDeps(src, HOOK_RE)) {
+    for (const [line, dep, raw] of hookDeps(src, HOOK_RE)) {
       const why = fresh.get(dep);
       if (!why) continue;
-      hits.push({ key: `${rel}::${dep}`, file: rel, line, why });
+      hits.push({ key: `${rel}::${dep}`, file: rel, line, raw, why });
     }
   }
 
@@ -86,13 +85,22 @@ function scan(): Hit[] {
 describe("每次渲染都新建的对象不进 hook 依赖数组", () => {
   it("全库无未登记的新命中", () => {
     const offenders = scan()
-      .filter(({ key }) => !ALLOWED[key] && !KNOWN_DEBT.includes(key))
+      .filter(({ key, raw }) => ALLOWED[key]?.raw !== raw && !KNOWN_DEBT.includes(key))
       .map(({ file, line, why }) => `${file}:${line}  ${why}`);
 
     expect(offenders).toEqual([]);
   });
 
-  it("Chart 一族一条都不剩（这一轮修的就是它）", () => {
+  it("白名单不许留过期条目（对应写法改掉了就删掉它）", () => {
+    const live = new Set(scan().map(({ key, raw }) => `${key}::${raw}`));
+    expect(
+      Object.entries(ALLOWED)
+        .filter(([key, { raw }]) => !live.has(`${key}::${raw}`))
+        .map(([key]) => key),
+    ).toEqual([]);
+  });
+
+  it("Chart 一族一条都不剩（2.5.6 修的就是它）", () => {
     const chartHits = scan()
       .filter(({ file }) => file.startsWith("components/Chart/"))
       .map(({ key, line }) => `${key}@${line}`);
@@ -100,7 +108,7 @@ describe("每次渲染都新建的对象不进 hook 依赖数组", () => {
     expect(chartHits).toEqual([]);
   });
 
-  it("存量欠账名单只许变短", () => {
+  it("存量欠账名单只许变短（2.5.7 起应恒为空）", () => {
     const live = new Set(scan().map(({ key }) => key));
     // 修好了就把它从 KNOWN_DEBT 里删掉，别留着已经不存在的条目
     expect(KNOWN_DEBT.filter((key) => !live.has(key))).toEqual([]);
@@ -134,6 +142,29 @@ describe("每次渲染都新建的对象不进 hook 依赖数组", () => {
     `;
     expect(freshObjectBindings(fixed).has("coreOption")).toBe(false);
 
+    // 回调体里出现过 `, [`（JSX 的 classNames 常写成这样）时，依赖数组仍要切对：
+    // 旧的贪婪正则会从最左那个 `, [` 起一路吞到结尾，把真命中静默漏掉
+    const jsxCase = `
+      const { colors = ["#fff"] } = props;
+      const node = useMemo(() => (
+        <span className={classNames(styles.a, { [styles.b]: on })} />
+      ), [colors, on]);
+    `;
+    expect(hookDeps(jsxCase, HOOK_RE).map(([, d]) => d)).toEqual([
+      "colors",
+      "on",
+    ]);
+
+    // 依赖原文要原样带出来，白名单才能按 `x` / `x.open` 精确区分
+    expect(
+      hookDeps(`useEffect(() => {}, [cfg.open, cfg]);`, HOOK_RE).map(
+        ([, , raw]) => raw,
+      ),
+    ).toEqual(["cfg.open", "cfg"]);
+
+    // 最后一个实参不是依赖数组时不算依赖（例如 `useMemo(() => [1, 2])`）
+    expect(hookDeps(`const a = useMemo(() => [x, y]);`, HOOK_RE)).toEqual([]);
+
     // 注释里的示例代码不算命中
     expect(
       freshObjectBindings(

package/src/components/Checkbox/CheckboxGroup/index.tsx

@@ -9,6 +9,9 @@ import styles from "./index.module.scss";
 
 const Group = Checkbox.Group;
 
+// 解构默认值写成字面量会每次渲染新建一个数组，进依赖数组就让 memo 恒不命中；提到模块级常量
+const EMPTY_OPTIONS: AntdCheckboxGroupProps["options"] = [];
+
 export interface CheckboxGroupProps extends AntdCheckboxGroupProps {
   outline?: boolean;
   hasAll?: boolean;
@@ -21,7 +24,7 @@ const CheckboxGroup: React.FC<CheckboxGroupProps> = (props) => {
     className,
     outline,
     hasAll,
-    options = [],
+    options = EMPTY_OPTIONS,
     value,
     onChange,
     layout = "horizontal",

package/src/components/FormItem/FormCodeMirror/index.tsx

@@ -7,12 +7,15 @@ export interface FormCodeMirrorProps extends ItemContainerProps {
   componentProps?: CodeMirrorProps;
 }
 
+// 解构默认值写成字面量会每次渲染新建一个数组，进依赖数组就让 memo 恒不命中；提到模块级常量
+const EMPTY_RULES: ItemContainerProps["rules"] = [];
+
 const FormCodeMirror: React.FC<FormCodeMirrorProps> = (props) => {
   const {
     componentProps = {},
     className: itemClassName,
     disabled,
-    rules = [],
+    rules = EMPTY_RULES,
     name,
     ...formItemProps
   } = props;

package/src/components/FormItem/ItemContainer/index.tsx

@@ -9,6 +9,7 @@ import usePermissions from "../../../hooks/usePermissions";
 import { isLegacyHasSelectorBrowser } from "../../../utils/cssSupports";
 import { generateRandomStr } from "hsu-utils";
 import useLabelSize from "./_hooks/useLabelSize";
+import useShallowStable from "../../../hooks/useShallowStable";
 import useInputSize from "./_hooks/useInputSize";
 
 interface TipsProps {
@@ -50,6 +51,9 @@ export interface ItemContainerProps extends FormItemProps {
   visible?: boolean;
 }
 
+// 解构默认值写成字面量会每次渲染新建一个对象，进依赖数组就让 memo 恒不命中；提到模块级常量
+const EMPTY_TIPS: NonNullable<ItemContainerProps["tips"]> = {};
+
 const ItemContainer: React.FC<ItemContainerProps> = (props) => {
   const {
     children,
@@ -73,7 +77,7 @@ const ItemContainer: React.FC<ItemContainerProps> = (props) => {
     colon,
     label,
     labelRender,
-    tips = {},
+    tips = EMPTY_TIPS,
     horizontalAlignment = "start",
     hideRequired = false,
     labelClassName,
@@ -89,7 +93,18 @@ const ItemContainer: React.FC<ItemContainerProps> = (props) => {
     visible: _visible,
     ...formItemProps
   } = props;
-  const { icon = "material-symbols:help", iconClassName, ...tipsConfig } = tips;
+  const {
+    icon = "material-symbols:help",
+    iconClassName,
+    ...restTipsConfig
+  } = tips;
+  // rest 解构出来的对象每次渲染都是新引用，直接进依赖数组会让 memo 恒不命中。
+  // useShallowStable 让它回到值语义：内容浅相等就复用同一引用，真变了立刻透出新引用。
+  const tipsConfig = useShallowStable(restTipsConfig);
+  // memo 只需要知道「有没有配 tips」，把对象本身放进依赖数组等于按引用比：
+  // 消费方写内联 `tips={{ ... }}`（最常见的写法）就让 label 的 memo 恒不命中。
+  // 拆成布尔量后依赖回到值语义。
+  const hasTips = Object.keys(tips).length > 0;
   const { permitted } = usePermissions(hasPermi);
   const cls = useMemo(() => generateRandomStr(10), []);
   const legacyHasSelector = isLegacyHasSelectorBrowser();
@@ -99,7 +114,7 @@ const ItemContainer: React.FC<ItemContainerProps> = (props) => {
       return undefined;
     }
 
-    return Object.keys(tips).length ? (
+    return hasTips ? (
       <>
         <span className={classNames(styles.labelContent, labelClassName)}>
           <span
@@ -160,7 +175,7 @@ const ItemContainer: React.FC<ItemContainerProps> = (props) => {
       </>
     ) : undefined;
   }, [
-    tips,
+    hasTips,
     labelClassName,
     label,
     tipsConfig,
@@ -225,7 +240,7 @@ const ItemContainer: React.FC<ItemContainerProps> = (props) => {
         [styles.hideRequired]: hideRequired,
         [styles[horizontalAlignment]]:
           layout === "horizontal" && horizontalAlignment,
-        [styles.hasLabelContent]: !!Object.keys(tips).length,
+        [styles.hasLabelContent]: hasTips,
         [styles.hideAdditiona]: hideAdditiona,
         [styles.legacyHasLabelExtra]:
           legacyHasSelector &&
@@ -233,7 +248,7 @@ const ItemContainer: React.FC<ItemContainerProps> = (props) => {
           !hideLabel &&
           !!label &&
           !!labelExtra &&
-          !Object.keys(tips).length,
+          !hasTips,
       })}
       colon={
         typeof colon === "boolean"

package/src/components/Modal/index.md

@@ -74,6 +74,7 @@ Modal.config
 | edgeDetection | 拖拽时是否进行边缘检测，防止拖出视口 | `boolean` | `true` |
 | full | 是否以全屏方式展示 | `boolean` | `false` |
 | titleButtonGroup | 标题区右侧的按钮组配置 | `ButtonProps[]` | - |
+| minHeight | 高度**下界**，给内容要等接口回来才画得出的弹窗用（详情 / 消息 / 记录）。`true` 走标准档 700px；数字按 px；字符串原样当 CSS 长度。只是下界，内容更高照常撑开与滚动，并且与 `90vh` 取小，矮窗口不会被顶出屏幕。**短表单不要传**，否则平白留一片空白 | `number \| string \| boolean` | - |
 
 > 其余属性（`open`、`onOk`、`onCancel`、`footer`、`width` 等）与 antd `Modal` 一致。
 >

package/src/components/Modal/index.module.scss

@@ -31,6 +31,13 @@
     width: 100%;
     height: 100%;
     max-height: 90vh;
+    // 高度下界，由 `<Modal minHeight>` 写入 `--vita-modal-min-height`（不传就是 0）。
+    // 内容异步加载的弹窗不给下界的话，打开那一刻只有标题栏那么高，数据回来再撑开。
+    //
+    // 必须在这里与 90vh 取小：CSS 里 `min-height` 的优先级高于 `max-height`，
+    // 直接写 `min-height: 700px` 会让上面那行 `max-height: 90vh` 在矮窗口上失效，
+    // 弹窗被顶出屏幕。
+    min-height: min(var(--vita-modal-min-height, 0px), 90vh);
     padding: 0px 0px 15px;
   }