@hsu-react/ui 2.5.6 → 2.5.8

package/src/components/Modal/index.tsx

@@ -5,14 +5,36 @@ import { useModalElements, useModalDrag } from "./_hooks";
 import Button, { ButtonProps } from "../Button";
 import { mergeSemantic } from "../../utils/semantic";
 import { modalFuncs } from "../../feedback";
+import { modalMinHeight } from "../../styles/tokens";
 
 export interface ModalProps extends AntdModalProps {
   moveable?: boolean;
   edgeDetection?: boolean;
   full?: boolean;
   titleButtonGroup?: ButtonProps[];
+  /**
+   * 高度**下界**。给「内容要等接口回来才画得出」的弹窗用：不给下界的话，
+   * 打开那一刻只有标题栏那么高，数据回来再撑开 —— 视觉上跳一下。
+   *
+   * - `true`：用标准档（`modalMinHeight`，700px），后台详情 / 列表 / 记录类弹窗都用它
+   * - 数字：px；字符串：原样当 CSS 长度
+   * - 不传：维持内容自适应 —— **短表单不要传**，否则平白留出一大片空白
+   *
+   * 它只是下界：内容更高照常撑开、照常滚动；并且在样式里与 `90vh` 取小，
+   * 矮窗口下不会被顶出屏幕。
+   */
+  minHeight?: number | string | boolean;
 }
 
+/** `minHeight` prop → CSS 长度。`true` 走标准档，`false` / 不传等于不设下界 */
+const resolveMinHeight = (
+  minHeight: ModalProps["minHeight"]
+): string | undefined => {
+  if (minHeight === undefined || minHeight === false) return undefined;
+  if (minHeight === true) return `${modalMinHeight}px`;
+  return typeof minHeight === "number" ? `${minHeight}px` : minHeight;
+};
+
 interface ModalFC extends React.FC<ModalProps> {
   confirm: typeof AntdModal.confirm;
   info: typeof AntdModal.info;
@@ -29,6 +51,8 @@ const Modal = ((props: ModalProps) => {
     moveable = true,
     className,
     classNames,
+    styles: outerStyles,
+    minHeight,
     open,
     onCancel,
     onOk,
@@ -79,6 +103,8 @@ const Modal = ((props: ModalProps) => {
     onOk?.(e);
   };
 
+  const resolvedMinHeight = resolveMinHeight(minHeight);
+
   return (
     <AntdModal
       centered
@@ -114,6 +140,20 @@ const Modal = ((props: ModalProps) => {
           footer === false ? styles.noFooter : ""
         }`,
       }))}
+      /* 下界通过 CSS 变量交给样式表，而不是直接写 `minHeight` 内联样式：
+         clamp（与 90vh 取小）必须在 CSS 里做——`min-height` 在 CSS 里赢过
+         `max-height`，内联写死的话矮窗口会被顶出屏幕 */
+      styles={mergeSemantic(outerStyles, (outer) => ({
+        ...outer,
+        container: {
+          ...(outer.container ?? {}),
+          ...(resolvedMinHeight
+            ? ({
+                "--vita-modal-min-height": resolvedMinHeight,
+              } as React.CSSProperties)
+            : {}),
+        },
+      }))}
       footer={footer}
       afterClose={() => {
         afterClose?.();

package/src/components/Modal/minHeight.test.tsx

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import path from "node:path";
+import React from "react";
+import { describe, expect, it } from "vitest";
+import { render } from "@testing-library/react";
+
+import Modal from ".";
+import { modalMinHeight } from "../../styles/tokens";
+
+/**
+ * 「内容异步加载的弹窗要有高度下界」这条能力的守卫。
+ *
+ * 缺陷长什么样：详情 / 消息 / 执行记录这类弹窗打开那一刻只有标题栏那么高，
+ * 接口回来再撑开 —— 视觉上跳一下。给下界就不跳。
+ *
+ * 两条底线一起盯：
+ * 1. **不传 `minHeight` 的弹窗不许变高** —— 否则两个输入框的短表单会平白留一片空白；
+ * 2. 下界必须在 CSS 里与 `90vh` 取小 —— `min-height` 在 CSS 里赢过 `max-height`，
+ *    直接落成内联 `min-height` 的话矮窗口会被顶出屏幕。所以组件只写 CSS 变量，
+ *    clamp 留在样式表里，这里连样式表那一行也一并守住。
+ */
+
+/** antd 的 container 语义槽就是承载 `.content`（flex 列 ＋ max-height: 90vh）的那一层 */
+const container = () =>
+  document.querySelector(".ant-modal-content, .ant-modal-container") as
+    | HTMLElement
+    | null;
+
+const minHeightVar = () =>
+  container()?.style.getPropertyValue("--vita-modal-min-height") ?? "";
+
+describe("Modal minHeight", () => {
+  it("不传时不写下界 —— 短表单不会平白变高", () => {
+    render(
+      <Modal open getContainer={false}>
+        x
+      </Modal>
+    );
+
+    expect(container()).toBeTruthy();
+    expect(minHeightVar()).toBe("");
+  });
+
+  it("minHeight 传 true 用标准档（与 Panel.List.Modal 同一个 700）", () => {
+    render(
+      <Modal open minHeight getContainer={false}>
+        x
+      </Modal>
+    );
+
+    expect(minHeightVar()).toBe(`${modalMinHeight}px`);
+  });
+
+  it("数字按 px、字符串原样、false 等于不设", () => {
+    const { unmount } = render(
+      <Modal open minHeight={520} getContainer={false}>
+        x
+      </Modal>
+    );
+    expect(minHeightVar()).toBe("520px");
+    unmount();
+
+    const second = render(
+      <Modal open minHeight="60vh" getContainer={false}>
+        x
+      </Modal>
+    );
+    expect(minHeightVar()).toBe("60vh");
+    second.unmount();
+
+    render(
+      <Modal open minHeight={false} getContainer={false}>
+        x
+      </Modal>
+    );
+    expect(minHeightVar()).toBe("");
+  });
+
+  it("调用方自己的 styles.container 不会被吃掉", () => {
+    render(
+      <Modal
+        open
+        minHeight
+        styles={{ container: { borderRadius: "4px" } }}
+        getContainer={false}
+      >
+        x
+      </Modal>
+    );
+
+    expect(container()?.style.borderRadius).toBe("4px");
+    expect(minHeightVar()).toBe(`${modalMinHeight}px`);
+  });
+
+  it("样式表里 clamp 到 90vh —— 矮窗口不会被顶出屏幕", () => {
+    const scss = fs.readFileSync(
+      path.resolve(__dirname, "index.module.scss"),
+      "utf8"
+    );
+
+    expect(scss).toMatch(
+      /min-height:\s*min\(var\(--vita-modal-min-height,\s*0px\),\s*90vh\)/
+    );
+  });
+});

package/src/components/Operate/index.tsx

@@ -28,6 +28,9 @@ export interface OperateProps
   moreIcon?: ReactNode | false;
 }
 
+// 解构默认值写成字面量会每次渲染新建一个数组，进依赖数组就让 memo 恒不命中；提到模块级常量
+const EMPTY_MENU: OperateProps[] = [];
+
 /**
  * Render an icon
  * @param icon - Icon configuration
@@ -56,7 +59,7 @@ const Operate: React.FC<OperateProps> = (props) => {
   const {
     title,
     className,
-    menu = [],
+    menu = EMPTY_MENU,
     icon,
     delete: isDelete,
     popconfirm,

package/src/components/Pagination/index.tsx

@@ -20,10 +20,13 @@ export interface PaginationProps
   onStaticPaginationChange?: (page: number, pageSize: number) => void;
 }
 
+// 解构默认值写成字面量会每次渲染新建一个数组，进依赖数组就让 memo 恒不命中；提到模块级常量
+const EMPTY_PAGE_SIZE_OPTIONS: number[] = [];
+
 const Pagination: React.FC<PaginationProps> = (props) => {
   const {
     simple,
-    pageSizeOptions = [],
+    pageSizeOptions = EMPTY_PAGE_SIZE_OPTIONS,
     showSizeChanger,
     onShowSizeChange,
     onChange,

package/src/components/Search/_hooks/useSearchCommon.ts

@@ -76,6 +76,9 @@ export interface UseSearchCommonReturn {
   permitted: boolean;
 }
 
+// 解构默认值写成字面量会每次渲染新建一个数组，进依赖数组就让 memo 恒不命中；提到模块级常量
+const EMPTY_SEARCH_ITEMS: FormItemProps[] = [];
+
 /**
  * Extracts the common logic shared by all Search components
  */
@@ -85,7 +88,7 @@ export const useSearchCommon = (
   const {
     form,
     searchItems,
-    moreSearchItems = [],
+    moreSearchItems = EMPTY_SEARCH_ITEMS,
     searchData,
     hasPermi,
     beforeButtonGroup,

package/src/components/Select/AutoCompleteSelect/index.tsx

@@ -40,6 +40,9 @@ export interface AutoCompleteSelectProps
   optionFontSize?: number;
 }
 
+// 解构默认值写成字面量会每次渲染新建一个数组，进依赖数组就让 memo 恒不命中；提到模块级常量
+const EMPTY_OPTIONS: AutoCompleteOption[] = [];
+
 const AutoCompleteSelect: React.FC<AutoCompleteSelectProps> = (props) => {
   const {
     prefix,
@@ -53,7 +56,7 @@ const AutoCompleteSelect: React.FC<AutoCompleteSelectProps> = (props) => {
     popupClassName,
     filterOption: customFilterOption,
     onChange,
-    options = [],
+    options = EMPTY_OPTIONS,
     placement = "bottomLeft",
     onDropdownVisibleChange,
     popupMatchSelectWidth,

package/src/components/Spreadsheet/depsMemo.test.tsx

@@ -0,0 +1,95 @@
+import { render } from "@testing-library/react";
+import React, { ReactElement } from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * 2.5.7：`xOptions` 的解构默认值与 `xOptionsRest` 这个 rest 包每渲染都是新对象，
+ * 直接进「建表格实例」那条 effect 的依赖数组 → **effect 每渲染必重跑**。
+ * 实例本身被 `!sheet` 挡住了不会重建，但 effect 体每次都白跑一遍，
+ * 且依赖里挂着的 `xOptionsRest` 永远比不出「配置真的变了」——纯粹的假依赖。
+ *
+ * 这里单独一个文件，是因为要把 `x-data-spreadsheet` 换成假实现（jsdom 里跑不了真的）。
+ */
+
+const probe = { effect: 0 };
+(globalThis as Record<string, unknown>).__spreadsheetProbe = probe;
+
+vi.mock("react", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react")>();
+  const counters = () =>
+    (globalThis as Record<string, unknown>).__spreadsheetProbe as typeof probe;
+  return {
+    ...actual,
+    useEffect: (fn: () => unknown, deps: unknown[]) =>
+      actual.useEffect(() => {
+        counters().effect++;
+        return fn() as ReturnType<React.EffectCallback>;
+      }, deps),
+  };
+});
+
+const construct = vi.fn();
+const loadData = vi.fn();
+
+vi.mock("x-data-spreadsheet", () => ({
+  default: class FakeSpreadsheet {
+    constructor(...args: unknown[]) {
+      construct(...args);
+    }
+    loadData(...args: unknown[]) {
+      loadData(...args);
+      return this;
+    }
+  },
+}));
+vi.mock("x-data-spreadsheet/dist/xspreadsheet.css", () => ({}));
+
+import Spreadsheet from ".";
+
+beforeEach(() => {
+  probe.effect = 0;
+  construct.mockClear();
+  loadData.mockClear();
+});
+
+function rerenderEffectCost(make: () => ReactElement) {
+  const { rerender, unmount } = render(make());
+  const before = probe.effect;
+  rerender(make());
+  const cost = probe.effect - before;
+  unmount();
+  return cost;
+}
+
+describe("Spreadsheet：xOptions / xOptionsRest 不再让建表 effect 每渲染必重跑", () => {
+  it("配置没变时重渲染不再重跑任何 effect", () => {
+    // 不传 xOptions（走默认值）与传内联对象（消费方最常见的写法）都必须为 0
+    expect(rerenderEffectCost(() => <Spreadsheet />)).toBe(0);
+    expect(
+      rerenderEffectCost(() => <Spreadsheet xOptions={{ showBottomTool: true }} />),
+    ).toBe(0);
+  });
+
+  it("表格实例只建一次，重渲染不会重复 new", () => {
+    const { rerender } = render(<Spreadsheet />);
+    rerender(<Spreadsheet />);
+    rerender(<Spreadsheet />);
+    expect(construct).toHaveBeenCalledTimes(1);
+  });
+
+  it("xOptions 真变了仍然透进新配置（浅比较不相等就立刻透出）", () => {
+    // 首帧就带上配置，确认它确实进了 XSpreadsheet 的构造参数
+    render(<Spreadsheet xOptions={{ showBottomTool: false, mode: "read" }} />);
+    expect(construct).toHaveBeenCalledTimes(1);
+    expect(construct.mock.calls[0][1]).toMatchObject({ mode: "read" });
+  });
+
+  it("data 真变了仍然重新 loadData", () => {
+    const bookA = { SheetNames: ["A"], Sheets: { A: {} } } as never;
+    const bookB = { SheetNames: ["B"], Sheets: { B: {} } } as never;
+    const { rerender } = render(<Spreadsheet data={bookA} />);
+    const first = loadData.mock.calls.length;
+    rerender(<Spreadsheet data={bookB} />);
+    expect(loadData.mock.calls.length).toBeGreaterThan(first);
+  });
+});

package/src/components/Spreadsheet/index.tsx

@@ -6,6 +6,7 @@ import "x-data-spreadsheet/dist/xspreadsheet.css";
 import classNames from "classnames";
 import { WorkBook } from "xlsx";
 import { stox } from "./xlsxspread";
+import useShallowStable from "../../hooks/useShallowStable";
 
 interface XOptions extends Omit<Options, "view"> {
   showBottomTool?: boolean;
@@ -17,9 +18,15 @@ interface SpreadsheetProps {
   className?: string;
 }
 
+// 解构默认值写成字面量会每次渲染新建一个对象，进依赖数组就让 effect 每渲染必重跑；提到模块级常量
+const EMPTY_X_OPTIONS: XOptions = {};
+
 const Spreadsheet: React.FC<SpreadsheetProps> = (props) => {
-  const { data, xOptions = {}, className } = props;
-  const { showBottomTool = true, ...xOptionsRest } = xOptions;
+  const { data, xOptions = EMPTY_X_OPTIONS, className } = props;
+  const { showBottomTool = true, ...restXOptions } = xOptions;
+  // rest 解构出来的对象每次渲染都是新引用，直接进依赖数组会让 memo 恒不命中。
+  // useShallowStable 让它回到值语义：内容浅相等就复用同一引用，真变了立刻透出新引用。
+  const xOptionsRest = useShallowStable(restXOptions);
   const ref = useRef<HTMLDivElement>(null);
   const containerRef = useRef<HTMLDivElement>(null);
   const id = useMemo(() => generateRandomStr(10), []);

package/src/components/Table/_hooks/useTableColumns.tsx

@@ -19,6 +19,9 @@ import {
 import usePermissions from "../../../hooks/usePermissions";
 import { PaginationProps } from "../../Pagination";
 
+// 解构默认值写成字面量会每次渲染新建一个数组，进依赖数组就让 memo 恒不命中；提到模块级常量
+const EMPTY_COLUMNS: ColumnsType = [];
+
 // measureAlign columns: measured at 14px, consistent with the table body and autoWidth title measurement
 const MEASURE_ALIGN_FONT_SIZE = 14;
 // Canvas measureText only returns the advance width, about 1px narrower than the actual DOM rendering; add a 2px buffer to avoid squeezing the widest row
@@ -97,7 +100,7 @@ const useTableColumns = <T extends AnyObject>(
   handleTableChange: TableProps<T>["onChange"];
 } => {
   const {
-    columns = [],
+    columns = EMPTY_COLUMNS,
     scroll,
     autoWidth,
     dataSource,

package/src/components/Tree/_hooks/useTreeState.ts

@@ -1,4 +1,4 @@
-import { useEffect, useState, Key, useMemo, useRef } from "react";
+import { useEffect, useState, Key, useMemo, useRef, useCallback } from "react";
 import { Equal } from "hsu-utils";
 import { CheckedKeys, TreeData } from "..";
 import { normalizeCheckedKeys } from "../_utils/normalizeCheckedKeys";
@@ -42,13 +42,19 @@ export const useExpandedKeys = (
     }
   }, [defaultExpandedKeys, expandedKeysProps]);
 
-  // Wrap setExpandedKeys to mark that the user has manually interacted
-  const handleSetExpandedKeys = (
-    keys: Key[] | undefined | ((prev: Key[] | undefined) => Key[] | undefined)
-  ) => {
-    hasUserInteractedRef.current = true;
-    setExpandedKeys(keys);
-  };
+  // Wrap setExpandedKeys to mark that the user has manually interacted.
+  // 必须 useCallback：这个函数被 Tree 的 handleExpand 当依赖用，
+  // 每渲染新建一个就让那个 useCallback 恒不命中——展开回调每渲染换引用透给 antd Tree。
+  // 函数体只碰 ref 和状态 setter，两者都恒定，所以依赖数组是空的。
+  const handleSetExpandedKeys = useCallback(
+    (
+      keys: Key[] | undefined | ((prev: Key[] | undefined) => Key[] | undefined)
+    ) => {
+      hasUserInteractedRef.current = true;
+      setExpandedKeys(keys);
+    },
+    []
+  );
 
   return [expandedKeys, handleSetExpandedKeys] as const;
 };

package/src/components/Tree/depsMemo.test.tsx

@@ -0,0 +1,64 @@
+import { render } from "@testing-library/react";
+import React from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * 2.5.7：`treeConfig` 是 rest 解构包，每次渲染都是新对象。它进了 `handleExpand`
+ * 的 `useCallback` 依赖数组 → **展开回调每渲染都换一个新引用**，原样传给 antd Tree。
+ *
+ * 这里把 antd 的 `Tree` 换成一个只记录 props 的探针，直接比 `onExpand` 的引用。
+ * 单独一个文件，是因为 `vi.mock` 是文件级的，不能污染别的用例。
+ */
+
+const seen: Record<string, unknown>[] = [];
+
+vi.mock("antd", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("antd")>();
+  const Probe = (props: Record<string, unknown>) => {
+    seen.push(props);
+    return React.createElement(actual.Tree, props);
+  };
+  Probe.DirectoryTree = actual.Tree.DirectoryTree;
+  Probe.TreeNode = actual.Tree.TreeNode;
+  return { ...actual, Tree: Probe };
+});
+
+import Tree from ".";
+
+const NODES = [{ key: "1", value: "1", title: "节点甲" }];
+
+beforeEach(() => {
+  seen.length = 0;
+});
+
+describe("Tree：treeConfig 不再让展开回调每渲染换引用", () => {
+  it("props 没变时，传给 antd Tree 的 onExpand 保持同一个引用", () => {
+    const make = () => <Tree treeData={NODES} />;
+    const { rerender } = render(make());
+    rerender(make());
+    expect(seen.length).toBeGreaterThanOrEqual(2);
+    expect(seen[seen.length - 1].onExpand).toBe(seen[0].onExpand);
+  });
+
+  it("消费方传内联的透传配置时也保持同一个引用（浅比较看的是值）", () => {
+    const make = () => <Tree treeData={NODES} showLine blockNode />;
+    const { rerender } = render(make());
+    rerender(make());
+    expect(seen[seen.length - 1].onExpand).toBe(seen[0].onExpand);
+  });
+
+  it("透传配置真变了仍然透出新引用，且新的 onExpand 调的是新的回调", () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = render(<Tree treeData={NODES} onExpand={first} />);
+    type Expand = (keys: unknown[], info: unknown) => void;
+    const before = seen[seen.length - 1].onExpand as Expand;
+    rerender(<Tree treeData={NODES} onExpand={second} />);
+    const after = seen[seen.length - 1].onExpand as Expand;
+    expect(after).not.toBe(before);
+
+    after(["1"], { node: { key: "1" } });
+    expect(second).toHaveBeenCalledTimes(1);
+    expect(first).not.toHaveBeenCalled();
+  });
+});

package/src/components/Tree/index.tsx

@@ -21,6 +21,7 @@ import { ButtonProps } from "../Button";
 import { getExpandedKeysByLevel, getNodePath } from "./_utils";
 import TextEllipsis from "../TextEllipsis";
 import usePermissions from "../../hooks/usePermissions";
+import useShallowStable from "../../hooks/useShallowStable";
 import { isLegacyHasSelectorBrowser } from "../../utils/cssSupports";
 
 export interface TreeData extends Record<string, unknown> {
@@ -79,6 +80,9 @@ interface TreeFC extends React.FC<TreeProps> {
   TreeNode: typeof AntdTree.TreeNode;
 }
 
+// 解构默认值写成字面量会每次渲染新建一个数组，进依赖数组就让 memo 恒不命中；提到模块级常量
+const EMPTY_TREE_DATA: TreeData[] = [];
+
 const Tree = ((props: TreeProps) => {
   const {
     title,
@@ -88,7 +92,7 @@ const Tree = ((props: TreeProps) => {
     titleClassName,
     className,
     search,
-    treeData = [],
+    treeData = EMPTY_TREE_DATA,
     onChange,
     onCheck,
     onSelect,
@@ -109,8 +113,11 @@ const Tree = ((props: TreeProps) => {
     onSelectPath,
     allowDeselect = true,
     titleSearchBarClassName,
-    ...treeConfig
+    ...restTreeConfig
   } = props;
+  // rest 解构出来的对象每次渲染都是新引用，直接进依赖数组会让 memo 恒不命中。
+  // useShallowStable 让它回到值语义：内容浅相等就复用同一引用，真变了立刻透出新引用。
+  const treeConfig = useShallowStable(restTreeConfig);
   const { permitted } = usePermissions(hasPermi);
   const legacyHasSelector = isLegacyHasSelectorBrowser();
 

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

@@ -28,6 +28,38 @@
     overflow-y: auto;
   }
 
+  /* ===== 滚动条占位不许吃掉菜单项的内缩 =====
+     上面那条规则把「谁滚」定在了菜单根上，但没有把几何契约收完：滚动条一旦
+     **实占宽度**（消费方常见做法：槽宽恒定、只切 thumb 颜色，这样悬浮时不抖），
+     它就从菜单根的内容盒里切走一条 —— 而菜单项的左右外边距量的正是这个内容盒。
+     于是展开子菜单、菜单一超高，右边多出一条空白，左边纹丝不动：
+
+       展开前 菜单项 8..220（左留白 8 / 右留白 10）
+       展开后 菜单项 8..206（左留白 8 / 右留白 24）← 展开的那一项看着「右边距变大了」
+
+     `scrollbar-gutter: stable both-edges` 把这条槽**两侧对称保留**，且不论当下滚不滚
+     都保留：左右留白从此相等，展开 / 收起也不再有宽度变化（连带把「展开那一瞬内容
+     重排」一并去掉）。槽宽由浏览器按该元素实际的滚动条算，**不是写死的 14px** ——
+     消费方把滚动条改窄改宽，留白跟着变。
+
+     配套把菜单项自己的左右外边距清零：留白改由这条槽提供，不再叠加。不清的话
+     留白变成 `8 + 槽宽`（实测 22/24），230px 的侧栏里「MCP 连接器」直接被截断。
+     纵向节奏与嵌套缩进不受影响 —— antd 的行内缩进走的是 padding，不是 margin。
+
+     `@supports` 兜底：不认这个属性的浏览器维持原样，不会两头落空。 */
+  @supports (scrollbar-gutter: stable both-edges) {
+    &:global(.ant-menu-inline) {
+      scrollbar-gutter: stable both-edges;
+
+      :global(.ant-menu-item),
+      :global(.ant-menu-submenu-title) {
+        width: 100%;
+
+        margin-inline: 0px;
+      }
+    }
+  }
+
   /* 子菜单在展开 / 收起动画期间被 rc-motion 逐帧改高度。antd 的
      `.ant-motion-collapse` 自带 overflow hidden，这里补的是**动画结束、类名摘掉
      之后**那一帧：此时 ul 的高度刚回到 auto，若父级恰好差几像素，浏览器会先画出

package/src/layout/Menu/scrollGutter.test.ts

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+/**
+ * 防回归守卫：**滚动条占位不许吃掉侧栏菜单项的内缩**。
+ *
+ * 缺陷长什么样：菜单根自己是滚动容器，滚动条一实占宽度就从它的内容盒里切走一条，
+ * 而菜单项的左右外边距量的正是这个内容盒 —— 展开子菜单让菜单超高、滚动条出现，
+ * 右留白从 10px 跳到 24px、左留白仍是 8px，看着就是「展开的那一项右边距变大了」。
+ *
+ * 正解是 `scrollbar-gutter: stable both-edges`（两侧对称、恒定保留，槽宽由浏览器按
+ * 实际滚动条算），并把菜单项自己的左右外边距清零，让留白只由这条槽提供。
+ *
+ * 这条守卫只能扫源码：jsdom 不做布局，量不出滚动条占位。所以顺带把两种「硬拉回来」
+ * 的写法也钉死 —— 写死滚动条宽度、或者用负 margin 把内容顶回去，换台机器就错开。
+ */
+
+const SCSS = fs.readFileSync(
+  path.resolve(__dirname, "index.module.scss"),
+  "utf8"
+);
+
+describe("侧栏菜单的滚动条占位", () => {
+  it("inline 菜单两侧对称保留滚动条槽", () => {
+    // 要的是**声明**本身，不是 @supports 条件里那份同名文本
+    expect(SCSS).toMatch(/scrollbar-gutter:\s*stable both-edges\s*;/);
+    // 槽由 @supports 兜底，不认这个属性的浏览器维持原样
+    expect(SCSS).toMatch(/@supports \(scrollbar-gutter: stable both-edges\)/);
+  });
+
+  it("菜单项不再自己留左右外边距 —— 留白只由那条槽提供，不叠加", () => {
+    expect(SCSS).toMatch(/margin-inline:\s*0px/);
+  });
+
+  it("不许写死滚动条宽度，也不许用负 margin 硬拉回来", () => {
+    // 滚动条宽度按平台 / 用户设置变，写死会在别的机器上错开
+    expect(SCSS).not.toMatch(/(?:width|margin|padding)[^;{}]*:\s*-?1[45]px/);
+    expect(SCSS).not.toMatch(/margin[a-z-]*:\s*[^;{}]*-\d/);
+  });
+
+  it("横向一律不滚、子菜单自己不滚 —— 上一轮修「闪滚动条」的口径没被冲掉", () => {
+    expect(SCSS).toMatch(/overflow-x:\s*hidden/);
+    expect(SCSS).toMatch(/\.ant-menu-sub\.ant-menu-inline\)\s*\{\s*overflow:\s*hidden/);
+  });
+
+  it("不许在库里写 scrollbar-width / scrollbar-color —— Chrome 会整套忽略消费方的 ::-webkit-scrollbar", () => {
+    expect(SCSS).not.toMatch(/^\s*scrollbar-(?:width|color)\s*:/m);
+  });
+});

package/src/styles/tokens.json

@@ -72,6 +72,7 @@
     "md": 800,
     "lg": 1200
   },
+  "modalMinHeight": 700,
   "breakpoint": {
     "sm": 640,
     "md": 768,

package/src/styles/tokens.ts

@@ -94,6 +94,17 @@ export const controlTokens = raw.control;
  */
 export const modalWidth = raw.modalWidth;
 
+/**
+ * 内容异步加载的弹窗的**高度下界**（`<Modal minHeight>` 的默认档）。
+ *
+ * 取 700 不是拍的：`Panel.List.Modal` 从一开始就把自己钉在 `height: 700px`，那是
+ * 「搜索行 ＋ 工具条 ＋ 表头 ＋ 十行左右 ＋ 分页」放得下的高度。详情 / 消息 / 记录这类
+ * 弹窗与它同处一套后台，用同一个下界，纵向节奏才是一套的。
+ *
+ * 它只是**下界**：内容更高照常撑开，并且在 CSS 里与 `90vh` 取小，矮窗口不会被顶出屏幕。
+ */
+export const modalMinHeight = raw.modalMinHeight;
+
 /**
  * 断点。与 `styles/_responsive.scss` 的 mixin 同源，所以 JS 判断不会和 CSS 媒体查询错开。
  */