@hsu-react/ui 2.5.4 → 2.5.6

package/src/__tests__/depsScan.ts

@@ -0,0 +1,158 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * 两条防回归守卫（`callbackDepsGuard` / `freshObjectDepsGuard`）共用的源码扫描工具。
+ * 只做静态文本扫描，故意不引入 AST 依赖——守卫本身要足够轻，才不会被人嫌慢删掉。
+ */
+
+/** 去掉注释再扫描：文档注释里的示例代码不是真实代码，不能算命中 */
+export function stripComments(src: string) {
+  let out = "";
+  let i = 0;
+  let quote: string | null = null;
+  while (i < src.length) {
+    const c = src[i];
+    const next = src[i + 1];
+    if (quote) {
+      out += c;
+      if (c === "\\") {
+        out += next ?? "";
+        i += 2;
+        continue;
+      }
+      if (c === quote) quote = null;
+      i++;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      quote = c;
+      out += c;
+      i++;
+      continue;
+    }
+    if (c === "/" && next === "/") {
+      while (i < src.length && src[i] !== "\n") i++;
+      continue;
+    }
+    if (c === "/" && next === "*") {
+      i += 2;
+      // 把块注释里的换行原样留下，报出来的行号才对得上
+      while (i < src.length && !(src[i] === "*" && src[i + 1] === "/")) {
+        if (src[i] === "\n") out += "\n";
+        i++;
+      }
+      i += 2;
+      continue;
+    }
+    out += c;
+    i++;
+  }
+  return out;
+}
+
+/** 遍历 `src/` 下的源码文件；守卫自己的目录不参与扫描 */
+export function walkSources(dir: string, out: string[] = []) {
+  for (const name of fs.readdirSync(dir)) {
+    if (name === "__tests__") continue;
+    const full = path.join(dir, name);
+    if (fs.statSync(full).isDirectory()) walkSources(full, out);
+    else if (/\.(tsx?|jsx?)$/.test(name) && !/\.test\./.test(name))
+      out.push(full);
+  }
+  return out;
+}
+
+/**
+ * 找出每个匹配 `hookRe` 的 hook 调用的依赖数组，返回 `[行号, 依赖名]`。
+ * `hookRe` 必须带 `g`，且以 `\(` 结尾（例如 `/use(?:Layout)?Effect\(/g`）。
+ */
+export function hookDeps(
+  src: string,
+  hookRe: RegExp,
+): Array<[number, string]> {
+  const found: Array<[number, string]> = [];
+  const re = new RegExp(hookRe.source, "g");
+  let m: RegExpExecArray | null;
+
+  while ((m = re.exec(src))) {
+    let i = m.index + m[0].length;
+    let depth = 1;
+    let quote: string | null = null;
+    let prev = "";
+
+    while (i < src.length && depth > 0) {
+      const c = src[i];
+      if (quote) {
+        if (c === quote && prev !== "\\") quote = null;
+      } else if (c === '"' || c === "'" || c === "`") quote = c;
+      else if (c === "(" || c === "[" || c === "{") depth++;
+      else if (c === ")" || c === "]" || c === "}") depth--;
+      prev = c;
+      i++;
+    }
+
+    const body = src.slice(m.index, i).replace(/\)\s*$/, "");
+    const deps = body.match(/,\s*\[([\s\S]*)\]\s*$/);
+    if (!deps) continue;
+
+    const line = src.slice(0, m.index).split("\n").length;
+    for (const raw of deps[1].split(",")) {
+      const name = raw
+        .replace(/\/\/.*$/gm, "")
+        .trim()
+        .split(/[.?[]/)[0]
+        .trim();
+      if (name) found.push([line, name]);
+    }
+  }
+
+  return found;
+}
+
+/**
+ * 找出「每次渲染都会新建一个对象/数组」的解构绑定，返回 `绑定名 → 说明`。
+ *
+ * 两种形态：
+ * - rest 包：`const { a, ...rest } = props` —— `rest` 每次都是新对象；
+ * - 字面量默认值：`const { list = [] } = props` —— 消费方没传时每次都是新数组。
+ */
+export function freshObjectBindings(src: string): Map<string, string> {
+  const found = new Map<string, string>();
+
+  const re = /\b(?:const|let|var)\s*\{/g;
+  let m: RegExpExecArray | null;
+
+  while ((m = re.exec(src))) {
+    // 取出与 `{` 配对的那一段解构模式
+    let i = re.lastIndex;
+    let depth = 1;
+    let quote: string | null = null;
+    let prev = "";
+    while (i < src.length && depth > 0) {
+      const c = src[i];
+      if (quote) {
+        if (c === quote && prev !== "\\") quote = null;
+      } else if (c === '"' || c === "'" || c === "`") quote = c;
+      else if (c === "(" || c === "[" || c === "{") depth++;
+      else if (c === ")" || c === "]" || c === "}") depth--;
+      prev = c;
+      i++;
+    }
+    // 后面必须紧跟 `=`，否则不是解构赋值
+    if (!/^\s*=/.test(src.slice(i))) continue;
+
+    const pattern = src.slice(re.lastIndex, i - 1);
+
+    for (const r of pattern.matchAll(/\.\.\.\s*([A-Za-z_$][\w$]*)/g)) {
+      found.set(r[1], "rest 解构包：每次渲染都是新对象");
+    }
+    for (const r of pattern.matchAll(
+      /([A-Za-z_$][\w$]*)\s*=\s*(?:[[{])/g,
+    )) {
+      found.set(r[1], "解构默认值是对象/数组字面量：不传时每次渲染都是新对象");
+    }
+  }
+
+  return found;
+}

package/src/__tests__/freshObjectDepsGuard.test.ts

@@ -0,0 +1,144 @@
+import path from "node:path";
+import fs from "node:fs";
+import { describe, expect, it } from "vitest";
+import {
+  freshObjectBindings,
+  hookDeps,
+  stripComments,
+  walkSources,
+} from "./depsScan";
+
+/**
+ * 防回归守卫：**每次渲染都新建的对象不许进 hook 依赖数组**。
+ *
+ * React 的依赖数组按 `Object.is` 比引用。依赖里只要有一个「组件自己每次渲染新建
+ * 的对象」，`useMemo` 就**恒不命中**、`useEffect` 就**每渲染必重跑**。
+ * 组件内部最常见的两个来源：
+ *
+ * ```tsx
+ * const { className, ...coreOption } = props;   // rest 包，每次都是新对象
+ * const { inRangeColor = ["#fff"] } = props;    // 字面量默认值，不传时每次都是新数组
+ * ```
+ *
+ * 这条缺陷和回调那条一样没有任何信号：不报错、不崩，只是图表每渲染一次就
+ * `setOption(notMerge)` 整个重设——动画重播、鼠标悬浮态被清掉，人工 review 拦不住。
+ *
+ * 正确写法：
+ * - rest 包 → `useShallowStable(rest)`（见 `src/hooks/useShallowStable.ts`）；
+ * - 字面量默认值 → 提到模块级常量。
+ */
+
+const SRC = path.resolve(__dirname, "..");
+const HOOK_RE = /use(?:Memo|Callback|(?:Layout)?Effect)\(/g;
+
+/** `文件相对路径::依赖名` → 无害的理由（确实无害才登记这里） */
+const ALLOWED: Record<string, string> = {};
+
+/**
+ * 存量欠账：守卫上线（2.5.6）时就已经存在的命中。**它们不是无害的**，只是不在这
+ * 一轮的改动范围内（这轮只修 Chart 一族）。修法与 Chart 相同：rest 包走
+ * `useShallowStable`，字面量默认值提到模块级常量。
+ *
+ * 这份名单**只许变短**——下面「只许变短」那条用例会在某项修好却忘了删时报错。
+ * 新写的代码一律直接失败，不许往这里加。
+ */
+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",
+];
+
+interface Hit {
+  /** `文件相对路径::依赖名` */
+  key: string;
+  file: string;
+  line: number;
+  why: string;
+}
+
+function scan(): Hit[] {
+  const hits: Hit[] = [];
+
+  for (const file of walkSources(SRC)) {
+    const rel = path.relative(SRC, file).split(path.sep).join("/");
+    const src = stripComments(fs.readFileSync(file, "utf8"));
+    const fresh = freshObjectBindings(src);
+    if (!fresh.size) continue;
+
+    for (const [line, dep] of hookDeps(src, HOOK_RE)) {
+      const why = fresh.get(dep);
+      if (!why) continue;
+      hits.push({ key: `${rel}::${dep}`, file: rel, line, why });
+    }
+  }
+
+  return hits;
+}
+
+describe("每次渲染都新建的对象不进 hook 依赖数组", () => {
+  it("全库无未登记的新命中", () => {
+    const offenders = scan()
+      .filter(({ key }) => !ALLOWED[key] && !KNOWN_DEBT.includes(key))
+      .map(({ file, line, why }) => `${file}:${line}  ${why}`);
+
+    expect(offenders).toEqual([]);
+  });
+
+  it("Chart 一族一条都不剩（这一轮修的就是它）", () => {
+    const chartHits = scan()
+      .filter(({ file }) => file.startsWith("components/Chart/"))
+      .map(({ key, line }) => `${key}@${line}`);
+
+    expect(chartHits).toEqual([]);
+  });
+
+  it("存量欠账名单只许变短", () => {
+    const live = new Set(scan().map(({ key }) => key));
+    // 修好了就把它从 KNOWN_DEBT 里删掉，别留着已经不存在的条目
+    expect(KNOWN_DEBT.filter((key) => !live.has(key))).toEqual([]);
+  });
+
+  it("守卫本身能抓到问题（自测）", () => {
+    const restCase = `
+      const { className, ...coreOption } = props;
+      const option = useMemo(() => ({ ...coreOption }), [coreOption]);
+    `;
+    expect(freshObjectBindings(restCase).has("coreOption")).toBe(true);
+    expect(hookDeps(restCase, HOOK_RE).map(([, d]) => d)).toContain(
+      "coreOption",
+    );
+
+    const defaultCase = `
+      const { colors = ["#fff"], size = { w: 1 }, name = "x" } = props;
+      useEffect(() => {}, [colors, size, name]);
+    `;
+    const fresh = freshObjectBindings(defaultCase);
+    expect(fresh.has("colors")).toBe(true);
+    expect(fresh.has("size")).toBe(true);
+    // 原始值默认值不是新对象，不该被误判
+    expect(fresh.has("name")).toBe(false);
+
+    // 稳定引用（useShallowStable 的返回值 / 模块级常量）不该被误判
+    const fixed = `
+      const { className, ...restOption } = props;
+      const coreOption = useShallowStable(restOption);
+      const option = useMemo(() => ({ ...coreOption }), [coreOption]);
+    `;
+    expect(freshObjectBindings(fixed).has("coreOption")).toBe(false);
+
+    // 注释里的示例代码不算命中
+    expect(
+      freshObjectBindings(
+        stripComments(`/** const { ...coreOption } = props; */\nconst a = 1;`),
+      ).size,
+    ).toBe(0);
+  });
+});

package/src/components/ChainGraph/_hooks/callbacks.test.tsx

@@ -0,0 +1,155 @@
+import { describe, expect, it, vi } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+
+vi.mock("../ChainGraphServices", () => ({ default: class {} }));
+
+import { useChainGraphLayout } from "./useChainGraphLayout";
+import { useChainGraphData } from "./useChainGraphData";
+import type ChainGraphServices from "../ChainGraphServices";
+import type { TreeGraphData } from "..";
+
+/**
+ * ChainGraph 把回调交给图实例，由图实例在后续事件里回调。
+ * 这类「出口型」回调进依赖数组，会让消费方传内联箭头时反复触发重排 / 重新 setData。
+ */
+
+const DATA = { id: "root", label: "root" } as unknown as TreeGraphData;
+
+describe("useChainGraphLayout", () => {
+  const makeGraph = () =>
+    ({ changeLayout: vi.fn() }) as unknown as ChainGraphServices & {
+      changeLayout: ReturnType<typeof vi.fn>;
+    };
+
+  it("getImage 换引用不会重新 changeLayout（整张图重排）", () => {
+    const graph = makeGraph();
+    const { rerender } = renderHook(
+      ({ getImage }: { getImage?: (img: string) => void }) =>
+        useChainGraphLayout({ graph, octopus: true, rootLevel: 0, getImage }),
+      { initialProps: { getImage: vi.fn() } },
+    );
+
+    expect(graph.changeLayout).toHaveBeenCalledTimes(1);
+
+    rerender({ getImage: vi.fn() });
+    rerender({ getImage: vi.fn() });
+
+    expect(graph.changeLayout).toHaveBeenCalledTimes(1);
+  });
+
+  it("出图时调到的是最新的 getImage，包括从无到有传入的情况", () => {
+    const graph = makeGraph();
+    const { rerender } = renderHook(
+      ({ getImage }: { getImage?: (img: string) => void }) =>
+        useChainGraphLayout({ graph, octopus: true, rootLevel: 0, getImage }),
+      { initialProps: {} as { getImage?: (img: string) => void } },
+    );
+
+    const forwarded = graph.changeLayout.mock.calls[0][2] as (
+      img: string,
+    ) => void;
+    // 没传回调时转发函数照样存在，调用不报错
+    expect(() => forwarded("img-0")).not.toThrow();
+
+    const later = vi.fn();
+    rerender({ getImage: later });
+    // 图实例里存的还是同一个转发函数，但它现在会转给新传入的回调
+    forwarded("img-1");
+    expect(later).toHaveBeenCalledWith("img-1");
+  });
+});
+
+describe("useChainGraphData", () => {
+  const makeGraph = () =>
+    ({ setData: vi.fn() }) as unknown as ChainGraphServices & {
+      setData: ReturnType<typeof vi.fn>;
+    };
+
+  type Props = {
+    getImage?: (img: string) => void;
+    labelRender?: (label: TreeGraphData) => string;
+    onLayoutingChange?: (v: boolean) => void;
+  };
+
+  it("三个回调换引用都不会重新 setData", () => {
+    const graph = makeGraph();
+    const { rerender } = renderHook(
+      (props: Props) => useChainGraphData({ graph, data: DATA, ...props }),
+      {
+        initialProps: {
+          getImage: vi.fn(),
+          labelRender: vi.fn(() => "a"),
+          onLayoutingChange: vi.fn(),
+        } as Props,
+      },
+    );
+
+    expect(graph.setData).toHaveBeenCalledTimes(1);
+
+    rerender({
+      getImage: vi.fn(),
+      labelRender: vi.fn(() => "b"),
+      onLayoutingChange: vi.fn(),
+    });
+
+    expect(graph.setData).toHaveBeenCalledTimes(1);
+  });
+
+  it("图实例回调时取到的是最新引用，不是首次 setData 时的那个", () => {
+    const graph = makeGraph();
+    const firstLabel = vi.fn(() => "first");
+    const { rerender } = renderHook(
+      (props: Props) => useChainGraphData({ graph, data: DATA, ...props }),
+      {
+        initialProps: {
+          getImage: vi.fn(),
+          labelRender: firstLabel,
+          onLayoutingChange: vi.fn(),
+        } as Props,
+      },
+    );
+
+    const pushed = graph.setData.mock.calls[0][0] as {
+      getImage: (img: string) => void;
+      labelRender?: (label: TreeGraphData) => string;
+      isLayouting: (v: boolean) => void;
+    };
+
+    const nextImage = vi.fn();
+    const nextLabel = vi.fn(() => "next");
+    const nextLayouting = vi.fn();
+    rerender({
+      getImage: nextImage,
+      labelRender: nextLabel,
+      onLayoutingChange: nextLayouting,
+    });
+
+    pushed.getImage("img");
+    expect(nextImage).toHaveBeenCalledWith("img");
+
+    expect(pushed.labelRender!(DATA)).toBe("next");
+    expect(firstLabel).not.toHaveBeenCalled();
+
+    act(() => pushed.isLayouting(false));
+    expect(nextLayouting).toHaveBeenCalledWith(false);
+  });
+
+  it("labelRender 的「传了才改写 label」语义保留：没传就是 undefined，从无到有会带上", () => {
+    const graph = makeGraph();
+    const { rerender } = renderHook(
+      ({ data, labelRender }: { data: TreeGraphData; labelRender?: Props["labelRender"] }) =>
+        useChainGraphData({ graph, data, labelRender }),
+      { initialProps: { data: DATA } as { data: TreeGraphData; labelRender?: Props["labelRender"] } },
+    );
+
+    expect(graph.setData.mock.calls[0][0].labelRender).toBeUndefined();
+
+    const label = vi.fn(() => "x");
+    const nextData = { id: "root2", label: "root2" } as unknown as TreeGraphData;
+    rerender({ data: nextData, labelRender: label });
+
+    expect(graph.setData).toHaveBeenCalledTimes(2);
+    expect(typeof graph.setData.mock.calls[1][0].labelRender).toBe("function");
+    expect(graph.setData.mock.calls[1][0].labelRender(DATA)).toBe("x");
+  });
+});

package/src/components/ChainGraph/_hooks/useChainGraphData.ts

@@ -1,7 +1,8 @@
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { Equal } from "hsu-utils";
 import ChainGraphServices from "../ChainGraphServices";
 import { TreeGraphData } from "..";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 
 interface UseChainGraphDataProps {
   graph: ChainGraphServices | null;
@@ -28,6 +29,35 @@ export function useChainGraphData(props: UseChainGraphDataProps) {
   );
   const [isLayouting, setIsLayouting] = useState(true);
 
+  // 这三个回调都是「交给图实例、由它在后续事件里回调」的出口，不是数据本身。
+  // 它们进依赖数组是条死依赖：effect 体被 ObjEqual(lastData, data) 挡住，
+  // 引用变了也不会重新 setData —— 图里存的还是首次 setData 时那个闭包，
+  // 换了引用永远调不到（stale closure）。改成引用恒定的转发函数：
+  // 依赖数组只留真正的输入（graph/data/level/rootLevel），调用时总是取到最新的回调。
+  const getImageRef = useLatestRef(getImage);
+  const labelRenderRef = useLatestRef(labelRender);
+  const onLayoutingChangeRef = useLatestRef(onLayoutingChange);
+
+  const emitImage = useCallback(
+    (img: string) => {
+      getImageRef.current?.(img);
+    },
+    [getImageRef]
+  );
+  // labelRender 在 ChainGraphServices.setData 里是「传了才改写 label」的真值判断，
+  // 所以这里保留「有没有传」的语义：没传就传 undefined，传了才给转发函数。
+  const renderLabel = useCallback(
+    (label: TreeGraphData) => labelRenderRef.current!(label),
+    [labelRenderRef]
+  );
+  const emitLayouting = useCallback(
+    (value: boolean) => {
+      setIsLayouting(value);
+      onLayoutingChangeRef.current?.(value);
+    },
+    [onLayoutingChangeRef]
+  );
+
   useEffect(() => {
     if (graph && !Equal.ObjEqual(lastData, data)) {
       setLastData(data);
@@ -35,12 +65,9 @@ export function useChainGraphData(props: UseChainGraphDataProps) {
         data,
         level,
         rootLevel,
-        getImage,
-        isLayouting: (value) => {
-          setIsLayouting(value);
-          onLayoutingChange?.(value);
-        },
-        labelRender,
+        getImage: emitImage,
+        isLayouting: emitLayouting,
+        labelRender: labelRenderRef.current ? renderLabel : undefined,
       });
     }
   }, [
@@ -48,10 +75,11 @@ export function useChainGraphData(props: UseChainGraphDataProps) {
     data,
     level,
     rootLevel,
-    getImage,
-    labelRender,
-    onLayoutingChange,
     lastData,
+    emitImage,
+    emitLayouting,
+    renderLabel,
+    labelRenderRef,
   ]);
 
   return { isLayouting };

package/src/components/ChainGraph/_hooks/useChainGraphLayout.ts

@@ -1,5 +1,6 @@
-import { useEffect } from "react";
+import { useCallback, useEffect } from "react";
 import ChainGraphServices from "../ChainGraphServices";
+import { useLatestRef } from "../../../hooks/useLatestRef";
 
 interface UseChainGraphLayoutProps {
   graph: ChainGraphServices | null;
@@ -11,9 +12,21 @@ interface UseChainGraphLayoutProps {
 export function useChainGraphLayout(props: UseChainGraphLayoutProps) {
   const { graph, octopus, rootLevel, getImage } = props;
 
+  // getImage 只是「布局完成后把截图 dataURL 交出去」的出口，不是布局的输入。
+  // 它进依赖数组会让消费方每传一次内联箭头就重新 changeLayout 一次 —— 整张图重排；
+  // 消费方再把截图存进 state，就变成「重排 → 出图 → setState → 新引用 → 再重排」的死循环。
+  // 用引用恒定的转发函数注册，调用时再取最新的 getImage。
+  const getImageRef = useLatestRef(getImage);
+  const emitImage = useCallback(
+    (img: string) => {
+      getImageRef.current?.(img);
+    },
+    [getImageRef],
+  );
+
   useEffect(() => {
     if (graph && octopus !== undefined) {
-      graph.changeLayout(octopus, rootLevel, getImage);
+      graph.changeLayout(octopus, rootLevel, emitImage);
     }
-  }, [graph, octopus, rootLevel, getImage]);
+  }, [graph, octopus, rootLevel, emitImage]);
 }