@hsu-react/ui 0.0.1

package/src/components/Tags/index.tsx

@@ -0,0 +1,80 @@
+import { Tag } from "antd";
+import React, { useRef } from "react";
+import classNames from "classnames";
+import { useVisibleTags } from "./_hooks";
+import { getTagColor } from "./_utils";
+import EllipsisTag from "./_components/EllipsisTag";
+import MeasureContainer from "./_components/MeasureContainer";
+import styles from "./index.module.less";
+
+export interface TagsProps {
+  className?: string;
+  colors?: string[];
+  tags: string[];
+  ellipsis?: boolean;
+  align?: "left" | "center" | "right";
+  gap?: number;
+}
+
+const Tags: React.FC<TagsProps> = (props) => {
+  const {
+    className,
+    colors,
+    tags = [],
+    ellipsis = true,
+    align = "left",
+    gap = 8,
+  } = props;
+  const containerRef = useRef<HTMLDivElement>(null);
+  const measureRef = useRef<HTMLDivElement>(null);
+
+  // 使用 hook 计算可见的标签数量
+  const visibleCount = useVisibleTags(containerRef, measureRef, {
+    tags,
+    ellipsis,
+    gap,
+  });
+
+  // 获取可见的 tags 和省略的 tags
+  const visibleTags = tags.slice(0, visibleCount);
+  const ellipsisTags = tags.slice(visibleCount);
+
+  return (
+    <>
+      {/* 用于测量 tag 宽度的隐藏容器（仅在启用省略时显示） */}
+      {ellipsis && (
+        <MeasureContainer ref={measureRef} tags={tags} colors={colors} />
+      )}
+      {/* 实际显示的容器 */}
+      <div
+        ref={ellipsis ? containerRef : undefined}
+        className={classNames(styles.tagsContainer, className, {
+          [styles.wrap]: !ellipsis,
+          [styles.alignLeft]: align === "left",
+          [styles.alignCenter]: align === "center",
+          [styles.alignRight]: align === "right",
+        })}
+        style={{ "--gap": gap } as React.CSSProperties}
+      >
+        {visibleTags?.map((tag, index) => (
+          <Tag
+            key={`${tag}-${index}`}
+            color={getTagColor(index, colors)}
+            className={styles.tag}
+          >
+            {tag}
+          </Tag>
+        ))}
+        {ellipsis && (
+          <EllipsisTag
+            ellipsisTags={ellipsisTags}
+            startIndex={visibleCount}
+            colors={colors}
+          />
+        )}
+      </div>
+    </>
+  );
+};
+
+export default Tags;

package/src/components/TextEllipsis/index.md

@@ -0,0 +1,17 @@
+---
+nav: 组件
+group:
+  title: 数据展示
+  order: 4
+title: TextEllipsis 文本省略
+---
+
+# TextEllipsis 文本省略
+
+> `TextEllipsis` 组件。完整 API 见源码类型定义，下方为基础用法。
+
+## 引入
+
+```ts
+import { TextEllipsis } from "@hsu-react/ui";
+```

package/src/components/TextEllipsis/index.module.less

@@ -0,0 +1,28 @@
+.container {
+  display: inline-block;
+  width: 100%;
+  flex: 1;
+  min-width: 0px;
+}
+
+.measureElement {
+  position: absolute;
+  visibility: hidden;
+  white-space: nowrap;
+  top: -9999px;
+  left: -9999px;
+}
+
+.textElement {
+  display: block;
+  overflow: hidden;
+  white-space: nowrap;
+
+  &.ellipsisEnd {
+    text-overflow: ellipsis;
+  }
+
+  &.ellipsisStart {
+    text-overflow: clip;
+  }
+}

package/src/components/TextEllipsis/index.tsx

@@ -0,0 +1,203 @@
+import { Tooltip, TooltipProps } from "antd";
+import { ReactNode, useEffect, useRef, useState } from "react";
+import cssStyles from "./index.module.less";
+
+// 默认 Tooltip 宽度
+const DEFAULT_TOOLTIP_WIDTH = 200;
+
+export interface TextEllipsisProps {
+  /** 要显示的文本内容 */
+  children: ReactNode;
+  /** 容器宽度，用于计算 Tooltip 宽度 */
+  width?: number | string;
+  /** Tooltip 配置 */
+  tooltipConfig?: Omit<TooltipProps, "title" | "children"> & {
+    /** 默认 Tooltip 宽度（当没有设置 width 时使用） */
+    defaultWidth?: number;
+  };
+  /** 自定义样式 */
+  style?: React.CSSProperties;
+  /** 自定义类名 */
+  className?: string;
+  /** 是否禁用 Tooltip（即使文本溢出也不显示） */
+  disabled?: boolean;
+  /** 省略号位置，'start' 表示省略前面(...xxx)，'end' 表示省略后面(xxx...) */
+  ellipsisPosition?: "start" | "end";
+  /** container 样式 */
+  containerStyle?: React.CSSProperties;
+}
+
+/**
+ * 文本溢出组件
+ * 当文本溢出时自动显示 Tooltip，并省略超出文本
+ */
+const TextEllipsis: React.FC<TextEllipsisProps> = ({
+  children,
+  width,
+  tooltipConfig,
+  style,
+  className,
+  disabled = false,
+  ellipsisPosition = "end",
+  containerStyle,
+}) => {
+  const textRef = useRef<HTMLSpanElement>(null);
+  const measureRef = useRef<HTMLSpanElement>(null);
+  const [isOverflow, setIsOverflow] = useState(false);
+  const [truncatedText, setTruncatedText] = useState<ReactNode>(children);
+
+  useEffect(() => {
+    const element = textRef.current;
+    const measureElement = measureRef.current;
+    if (!element || !measureElement) return;
+
+    // 将 children 转换为字符串
+    const getTextContent = (node: ReactNode): string => {
+      if (typeof node === "string" || typeof node === "number") {
+        return String(node);
+      }
+      if (Array.isArray(node)) {
+        return node?.map(getTextContent).join("");
+      }
+      return "";
+    };
+
+    // 同步测量元素的样式
+    const computedStyle = window.getComputedStyle(element);
+    measureElement.style.fontSize = computedStyle.fontSize;
+    measureElement.style.fontFamily = computedStyle.fontFamily;
+    measureElement.style.fontWeight = computedStyle.fontWeight;
+    measureElement.style.fontStyle = computedStyle.fontStyle;
+    measureElement.style.letterSpacing = computedStyle.letterSpacing;
+    measureElement.style.padding = computedStyle.padding;
+    measureElement.style.border = computedStyle.border;
+    measureElement.style.boxSizing = computedStyle.boxSizing;
+
+    // 计算截断后的文本（省略前面）
+    const calculateTruncatedText = (text: string, maxWidth: number): string => {
+      const ellipsis = "...";
+
+      // 如果整个文本都不溢出，直接返回
+      measureElement.textContent = text;
+      if (measureElement.offsetWidth <= maxWidth) {
+        return text;
+      }
+
+      // 二分查找找到合适的截断点
+      let left = 0;
+      let right = text.length;
+      let result = text;
+
+      while (left <= right) {
+        const mid = Math.floor((left + right) / 2);
+        const truncated = ellipsis + text.slice(mid);
+        measureElement.textContent = truncated;
+
+        if (measureElement.offsetWidth <= maxWidth) {
+          result = truncated;
+          right = mid - 1;
+        } else {
+          left = mid + 1;
+        }
+      }
+
+      return result;
+    };
+
+    const textContent = getTextContent(children);
+    const isTextOverflow =
+      element.scrollWidth > element.clientWidth ||
+      element.scrollHeight > element.clientHeight;
+
+    setIsOverflow(isTextOverflow);
+
+    // 如果是省略前面且文本溢出，需要计算截断后的文本
+    if (ellipsisPosition === "start" && isTextOverflow && textContent) {
+      const maxWidth = element.clientWidth;
+      const truncated = calculateTruncatedText(textContent, maxWidth);
+      setTruncatedText(truncated);
+    } else {
+      setTruncatedText(children);
+    }
+  }, [children, ellipsisPosition, style]);
+
+  // 计算 Tooltip 的宽度
+  const getTooltipWidth = () => {
+    const defaultWidth = tooltipConfig?.defaultWidth ?? DEFAULT_TOOLTIP_WIDTH;
+    if (!width) return defaultWidth;
+    if (typeof width === "number") return width;
+    if (typeof width === "string" && width.includes("%")) return defaultWidth;
+    return parseInt(width) || defaultWidth;
+  };
+
+  const tooltipWidth = getTooltipWidth();
+
+  // 从 tooltipConfig 中提取配置，移除 defaultWidth
+  const { defaultWidth, styles, ...restTooltipConfig } = tooltipConfig || {};
+  void defaultWidth;
+
+  // 尝试将 children 格式化为 JSON
+  const formatTooltipTitle = (content: ReactNode): ReactNode => {
+    if (typeof content !== "string") return content;
+
+    try {
+      const parsed = JSON.parse(content);
+      return JSON.stringify(parsed, null, 2);
+    } catch {
+      // 如果不是有效的 JSON，返回原内容
+      return content;
+    }
+  };
+
+  const tooltipTitle = formatTooltipTitle(children);
+
+  const content = (
+    <span className={cssStyles.container} style={containerStyle}>
+      {/* 隐藏的测量元素 */}
+      <span
+        ref={measureRef}
+        className={cssStyles.measureElement}
+        aria-hidden="true"
+      />
+      <span
+        ref={textRef}
+        className={`${cssStyles.textElement} ${
+          ellipsisPosition === "end"
+            ? cssStyles.ellipsisEnd
+            : cssStyles.ellipsisStart
+        } ${className || ""}`}
+        style={style}
+        title="" // 禁用浏览器默认 tooltip
+      >
+        {ellipsisPosition === "start" ? truncatedText : children}
+      </span>
+    </span>
+  );
+
+  // 只在溢出且未禁用时显示 Tooltip
+  if (isOverflow && !disabled) {
+    return (
+      <Tooltip
+        arrow={false}
+        placement="bottomLeft"
+        {...restTooltipConfig}
+        title={tooltipTitle}
+        styles={{
+          body: {
+            width: tooltipWidth,
+            overflow: "auto",
+            maxHeight: "300px",
+            whiteSpace: "pre-wrap",
+          },
+          ...styles,
+        }}
+      >
+        {content}
+      </Tooltip>
+    );
+  }
+
+  return content;
+};
+
+export default TextEllipsis;

package/src/components/Tree/_components/TitleSearchBar/index.tsx

@@ -0,0 +1,71 @@
+import React, { useMemo } from "react";
+import classNames from "classnames";
+import Input, { InputProps } from "../../../Input";
+import Icon from "../../../Icon";
+import Button, { ButtonProps } from "../../../Button";
+import styles from "../../index.module.less";
+
+export interface TitleSearchBarProps {
+  title?: React.ReactNode;
+  search?: boolean;
+  searchValue?: string;
+  onSearchChange?: (value: string) => void;
+  searchProps?: InputProps;
+  buttonGroup?: ButtonProps[];
+  btnPosition?: "left" | "right";
+  titleClassName?: string;
+  className?: string;
+}
+
+const TitleSearchBar: React.FC<TitleSearchBarProps> = ({
+  title,
+  search,
+  searchValue,
+  onSearchChange,
+  searchProps,
+  buttonGroup,
+  btnPosition = "right",
+  titleClassName,
+  className,
+}) => {
+  // 渲染按钮组
+  const renderButtonGroup = useMemo(() => {
+    if (!buttonGroup?.length) {
+      return null;
+    }
+
+    return (
+      <div className={styles.buttonGroup}>
+        {buttonGroup?.map((button, idx) => (
+          <Button key={idx} {...button} />
+        ))}
+      </div>
+    );
+  }, [buttonGroup]);
+  // 如果没有内容，不渲染
+  if (!search && !title && !buttonGroup?.length) {
+    return null;
+  }
+
+  return (
+    <div className={classNames(styles.title_search, className)}>
+      {title && (
+        <div className={classNames(styles.title, titleClassName)}>{title}</div>
+      )}
+      {btnPosition === "left" && renderButtonGroup}
+      {search && (
+        <Input
+          prefix={<Icon icon="mdi:search" className={styles.searchIcon} />}
+          placeholder="输入搜索"
+          {...searchProps}
+          value={searchValue}
+          onChange={onSearchChange}
+          className={classNames(styles.search, searchProps?.className)}
+        />
+      )}
+      {btnPosition === "right" && renderButtonGroup}
+    </div>
+  );
+};
+
+export default TitleSearchBar;

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

@@ -0,0 +1,46 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * 清除树节点 title 属性的 Hook
+ * 当数据变更后，将所有 span.ant-tree-node-content-wrapper 的 title 设置为空
+ * @param treeData 树数据
+ * @param cls 树组件的唯一类名（用于精确定位）
+ */
+export const useClearNodeTitle = <T extends unknown[]>(
+  treeData: T,
+  cls?: string
+) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    // 使用 requestAnimationFrame 确保 DOM 已更新
+    const timer = requestAnimationFrame(() => {
+      // 根据类名查找或使用 ref
+      const container = cls
+        ? document.querySelector(`.${cls}`)
+        : containerRef.current;
+
+      if (!container) return;
+
+      setTimeout(() => {
+        // 获取所有 ant-tree-node-content-wrapper 元素
+        const nodes = container.querySelectorAll(
+          "span.ant-tree-node-content-wrapper"
+        );
+
+        // 清空每个元素的 title 属性
+        nodes?.forEach((node) => {
+          if (node instanceof HTMLElement) {
+            node.title = "";
+          }
+        });
+      }, 100);
+    });
+
+    return () => {
+      cancelAnimationFrame(timer);
+    };
+  }, [treeData, cls]);
+
+  return containerRef;
+};

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

@@ -0,0 +1,39 @@
+import { useCallback } from "react";
+import { TreeProps as AntdTreeProps } from "antd";
+import { CheckedKeys } from "..";
+
+/**
+ * 处理树勾选的 hook
+ * 使用 antd 默认逻辑，不做额外操作
+ */
+export const useTreeCheck = (
+  setCheckedKeys: React.Dispatch<React.SetStateAction<CheckedKeys | undefined>>,
+  onCheck?: AntdTreeProps["onCheck"],
+  onChange?: (checked: CheckedKeys) => void
+) => {
+  // 处理勾选逻辑：直接使用 antd 的默认行为
+  const handleCheck = useCallback(
+    (
+      checked: CheckedKeys,
+      info: Parameters<NonNullable<AntdTreeProps["onCheck"]>>[1]
+    ) => {
+      setCheckedKeys(checked);
+      onCheck?.(checked, info);
+
+      // 触发 onChange 回调
+      if (onChange) {
+        if (Array.isArray(checked)) {
+          onChange({
+            checked,
+            halfChecked: info.halfCheckedKeys || [],
+          });
+        } else {
+          onChange(checked);
+        }
+      }
+    },
+    [setCheckedKeys, onCheck, onChange]
+  );
+
+  return handleCheck;
+};

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

@@ -0,0 +1,77 @@
+import { useCallback, useMemo, useEffect, useState, Key, useRef } from "react";
+import { TreeData } from "..";
+import { filterTreeData } from "../_utils";
+
+/**
+ * 处理树搜索的 hook
+ */
+export const useTreeSearch = (
+  treeData: TreeData[],
+  setExpandedKeys: React.Dispatch<React.SetStateAction<Key[] | undefined>>
+) => {
+  const [searchKey, setSearchKey] = useState<string>("");
+  const prevSearchKeyRef = useRef<string>("");
+
+  // 处理树数据（搜索过滤）
+  // filterTreeData 内部已经处理了数据拷贝，无需额外 cloneDeep
+  const filteredTreeData = useMemo(() => {
+    if (!searchKey.trim()) {
+      return treeData;
+    }
+    return filterTreeData(searchKey, treeData);
+  }, [searchKey, treeData]);
+
+  // 处理搜索时的展开逻辑
+  useEffect(() => {
+    const trimmedSearchKey = searchKey.trim();
+    const prevTrimmedKey = prevSearchKeyRef.current.trim();
+
+    // 如果搜索关键词没有变化，跳过处理
+    if (trimmedSearchKey === prevTrimmedKey) {
+      return;
+    }
+
+    prevSearchKeyRef.current = searchKey;
+
+    // 清空搜索时，重置展开状态
+    if (!trimmedSearchKey) {
+      setExpandedKeys([]);
+      return;
+    }
+
+    // 有搜索关键词时，展开所有匹配的节点
+    if (!filteredTreeData.length) {
+      return;
+    }
+
+    const keysToExpandSet = new Set<Key>();
+    const collectExpandKeys = (nodes: TreeData[]): void => {
+      for (const node of nodes) {
+        if (node.children?.length) {
+          keysToExpandSet.add(node.key);
+          collectExpandKeys(node.children);
+        }
+      }
+    };
+
+    collectExpandKeys(filteredTreeData);
+
+    if (keysToExpandSet.size > 0) {
+      setExpandedKeys((prev) => {
+        const prevSet = new Set(prev ?? []);
+        keysToExpandSet?.forEach((key) => prevSet.add(key));
+        return Array.from(prevSet);
+      });
+    }
+  }, [searchKey, filteredTreeData, setExpandedKeys]);
+
+  const handleSearchChange = useCallback((value: string) => {
+    setSearchKey(value);
+  }, []);
+
+  return {
+    searchKey,
+    handleSearchChange,
+    filteredTreeData,
+  };
+};

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

@@ -0,0 +1,91 @@
+import { useEffect, useState, Key, useMemo, useRef } from "react";
+import { Equal } from "hsu-utils";
+import { CheckedKeys, TreeData } from "..";
+import { normalizeCheckedKeys } from "../_utils/normalizeCheckedKeys";
+
+/**
+ * 同步外部 expandedKeys 的 hook
+ */
+export const useExpandedKeys = (
+  expandedKeysProps?: Key[],
+  defaultExpandedKeys?: Key[]
+) => {
+  const [expandedKeys, setExpandedKeys] = useState<Key[] | undefined>(
+    defaultExpandedKeys
+  );
+  const prevPropsRef = useRef<Key[] | undefined>(expandedKeysProps);
+  const prevDefaultRef = useRef<Key[] | undefined>(defaultExpandedKeys);
+  // 标记用户是否已手动操作过展开状态
+  const hasUserInteractedRef = useRef(false);
+
+  // 监听受控模式的 expandedKeysProps 变化
+  useEffect(() => {
+    if (
+      expandedKeysProps !== undefined &&
+      !Equal.ObjEqual(prevPropsRef.current, expandedKeysProps)
+    ) {
+      prevPropsRef.current = expandedKeysProps;
+      setExpandedKeys(expandedKeysProps);
+    }
+  }, [expandedKeysProps]);
+
+  // 监听 defaultExpandedKeys 变化（非受控模式下，用于响应异步数据加载）
+  useEffect(() => {
+    // 只有在非受控模式下，且用户未手动操作过，才响应 defaultExpandedKeys 变化
+    if (
+      expandedKeysProps === undefined &&
+      !hasUserInteractedRef.current &&
+      !Equal.ObjEqual(prevDefaultRef.current, defaultExpandedKeys)
+    ) {
+      prevDefaultRef.current = defaultExpandedKeys;
+      setExpandedKeys(defaultExpandedKeys);
+    }
+  }, [defaultExpandedKeys, expandedKeysProps]);
+
+  // 包装 setExpandedKeys，标记用户已手动操作
+  const handleSetExpandedKeys = (
+    keys: Key[] | undefined | ((prev: Key[] | undefined) => Key[] | undefined)
+  ) => {
+    hasUserInteractedRef.current = true;
+    setExpandedKeys(keys);
+  };
+
+  return [expandedKeys, handleSetExpandedKeys] as const;
+};
+
+/**
+ * 同步外部 checkedKeys 的 hook
+ * 自动规范化：当父级在 checked 中但子项未全选时，将父级设为半选
+ */
+export const useCheckedKeys = (
+  checkedKeysProps?: CheckedKeys,
+  treeData?: TreeData[]
+) => {
+  // 规范化 checkedKeys
+  const normalizedCheckedKeys = useMemo(() => {
+    if (!checkedKeysProps || !treeData?.length) {
+      return checkedKeysProps;
+    }
+    return normalizeCheckedKeys(checkedKeysProps, treeData);
+  }, [checkedKeysProps, treeData]);
+
+  const [checkedKeys, setCheckedKeys] = useState<CheckedKeys | undefined>(
+    () => normalizedCheckedKeys
+  );
+  const prevNormalizedRef = useRef<CheckedKeys | undefined>(
+    normalizedCheckedKeys
+  );
+
+  useEffect(() => {
+    // 只有当规范化后的值真正变化时才更新
+    if (
+      normalizedCheckedKeys !== undefined &&
+      !Equal.ObjEqual(prevNormalizedRef.current, normalizedCheckedKeys)
+    ) {
+      prevNormalizedRef.current = normalizedCheckedKeys;
+      setCheckedKeys(normalizedCheckedKeys);
+    }
+  }, [normalizedCheckedKeys]);
+
+  return [checkedKeys, setCheckedKeys] as const;
+};