@hsu-react/ui 0.0.13 → 0.0.15

package/src/components/Search/SearchCard/_hooks/useSearchCardValue.ts

@@ -11,7 +11,7 @@ interface UseSearchCardValueProps {
 }
 
 /**
- * 管理 SearchCard 的值状态
+ * Manages the value state of SearchCard
  */
 export function useSearchCardValue({
   defaultValue,
@@ -31,22 +31,22 @@ export function useSearchCardValue({
     }
   }, [defaultValue, searchField]);
 
-  // 处理内部值更新，将所有值保存在内部状态中
+  // Handle internal value updates, keeping all values in internal state
   const handleValueChange = useCallback((newValue: Record<string, unknown>) => {
     setValue({ ...newValue });
   }, []);
 
-  // 获取真实值
+  // Get the real values
   const getRealValuesData = useCallback(() => {
     return getRealValues(value, options, searchField);
   }, [value, options, searchField]);
 
-  // 处理值变化
+  // Handle value changes
   useMemo(() => {
     if (onChange && !Equal.ObjEqual(value, lastValue)) {
       setLastValue(value);
 
-      // 提取所有Real值
+      // Extract all Real values
       const realValues = getRealValuesData();
 
       onChange(realValues);

package/src/components/Search/SearchCard/_utils/getRealValues.ts

@@ -1,7 +1,7 @@
 import { SearchCardOption } from "../_components/OptionRow";
 
 /**
- * 获取真实值（提取所有Real值）
+ * Gets the real values (extracts all Real values)
  */
 export function getRealValues(
   value: Record<string, unknown>,
@@ -10,19 +10,19 @@ export function getRealValues(
 ): Record<string, unknown> {
   const realValues: Record<string, unknown> = {};
 
-  // 遍历所有选项，获取其Real值
+  // Iterate over all options and get their Real values
   options?.forEach((option) => {
     const realKey = `${option.name}Real`;
     if (value[realKey] !== undefined) {
-      // 将带有"Real"后缀的值使用不带后缀的原始键名
+      // Store the "Real"-suffixed value under the original key without the suffix
       realValues[option.name] = value[realKey];
     } else {
-      // 如果没有Real值，使用原始值
+      // If there is no Real value, use the original value
       realValues[option.name] = value[option.name];
     }
   });
 
-  // 保留搜索相关字段
+  // Keep search-related fields
   if (value[searchField] !== undefined) {
     realValues[searchField] = value[searchField];
   }

package/src/components/Search/SearchCard/_utils/hasSelectedChildren.ts

@@ -1,7 +1,7 @@
 import { isArrayValue, isValidValue } from "./typeGuards";
 
 /**
- * 检查是否有任何子项被选中
+ * Checks whether any child item is selected
  */
 export function hasSelectedChildren(
   value: Record<string, unknown>,
@@ -11,10 +11,10 @@ export function hasSelectedChildren(
   const childrenValue = value[childrenName];
 
   if (isMultiple) {
-    // 多选模式：检查是否为数组且长度大于0
+    // Multi-select mode: check that it is an array with length greater than 0
     return isArrayValue(childrenValue) && childrenValue.length > 0;
   } else {
-    // 单选模式：检查值是否存在且不为空字符串
+    // Single-select mode: check that the value exists and is not an empty string
     return isValidValue(childrenValue) && childrenValue !== "";
   }
 }

package/src/components/Search/SearchCard/_utils/typeGuards.ts

@@ -1,5 +1,5 @@
 /**
- * 类型守卫函数
+ * Type guard functions
  */
 export const isValidValue = (value: unknown): boolean => {
   return value !== null && value !== undefined;

package/src/components/Search/SearchCard/_utils/updateRealValue.ts

@@ -2,35 +2,35 @@ import { isStringValue } from "./typeGuards";
 import { hasSelectedChildren } from "./hasSelectedChildren";
 
 /**
- * 更新真实返回值
+ * Updates the real return value
  */
 export function updateRealValue(
   value: Record<string, unknown>,
   optionName: string,
   newValues: Record<string, unknown>
 ): void {
-  // 参数验证
+  // Parameter validation
   if (!value || !isStringValue(optionName) || !newValues) {
     return;
   }
 
-  // 合并当前值和新值以获取最新状态
+  // Merge the current values and new values to get the latest state
   const mergedValues = { ...value, ...newValues };
 
-  // 检查是否存在子项数据
+  // Check whether child item data exists
   let hasAnyChildrenSelected = false;
   let childrenValue: unknown = null;
 
-  // 遍历所有可能的子项名称
+  // Iterate over all possible child item names
   Object.keys(mergedValues)?.forEach((key) => {
     if (key.endsWith("Children")) {
-      // 找到对应的父项名称
+      // Find the corresponding parent item name
       const parentName = key.replace("Children", "");
 
-      // 只处理当前选项的子项
+      // Only handle the child items of the current option
       if (parentName === optionName) {
         try {
-          // 检查子项是否有选中值
+          // Check whether the child items have a selected value
           const currentChildrenValue = mergedValues[key];
           const hasSelected = hasSelectedChildren(
             mergedValues,
@@ -49,13 +49,13 @@ export function updateRealValue(
     }
   });
 
-  // 设置真实返回值
+  // Set the real return value
   const realValueKey = `${optionName}Real`;
   if (hasAnyChildrenSelected) {
-    // 如果有子项被选中，使用子项值
+    // If any child item is selected, use the child value
     newValues[realValueKey] = childrenValue;
   } else {
-    // 如果没有子项被选中，使用父项值
+    // If no child item is selected, use the parent value
     const parentValue = newValues[optionName] ?? value[optionName];
     newValues[realValueKey] = parentValue;
   }

package/src/components/Search/SearchCard/index.module.scss

@@ -61,7 +61,7 @@
     transition: all 0.3s, border-top 0s;
   }
 
-  // 当有搜索框时，调整选项框的样式
+  // When there is a search box, adjust the options box styles
   &:has(.searchBox) .optionsBox {
     border-radius: 0 0 8px 8px;
     padding-top: 12px;
@@ -177,9 +177,9 @@
 
           &.active,
           &:hover {
-            color: #0e59ef;
+            color: var(--primary-color);
 
-            background: rgba(14, 89, 239, 0.12);
+            background: color-mix(in srgb, var(--primary-color) 12%, transparent);
           }
         }
 
@@ -195,7 +195,7 @@
         .help {
           margin-left: 2px;
 
-          color: #7f7f7f;
+          color: var(--cf-text-2);
           font-size: 16px;
         }
       }
@@ -207,7 +207,7 @@
         height: max-content;
         padding: 3px 0px;
 
-        color: #7f7f7f;
+        color: var(--cf-text-2);
         font-weight: 400;
         font-size: 16px;
         font-family: PingFangSC-Regular, PingFang SC;
@@ -220,7 +220,7 @@
         transition: color 0.3s;
 
         &:hover {
-          color: #0e59ef;
+          color: var(--primary-color);
         }
       }
     }
@@ -252,8 +252,8 @@
 
         &.active,
         &:hover {
-          color: #0e59ef;
-          background: rgba(14, 89, 239, 0.12);
+          color: var(--primary-color);
+          background: color-mix(in srgb, var(--primary-color) 12%, transparent);
         }
       }
     }

package/src/components/Search/SearchCard/index.tsx

@@ -62,7 +62,7 @@ const SearchCard: React.FC<SearchCardProps> = memo((props) => {
     defaultCollapse,
   });
 
-  // 处理搜索
+  // Handle search
   const handleSearch = () => {
     const realValues = getRealValues();
     onChange?.({ ...realValues, [searchField]: internalValue });

package/src/components/Search/SearchCollapsible/index.module.scss

@@ -1,3 +1,3 @@
-// SearchCollapsible 组件的独立样式
-// 目前复用父级 Search 组件的样式，如需自定义可在此处添加
+// Standalone styles for the SearchCollapsible component
+// Currently reuses the parent Search component's styles; add customizations here if needed
 

package/src/components/Search/SearchCollapsible/index.tsx

@@ -13,10 +13,10 @@ export interface SearchCollapsibleProps extends SearchPropsWithFilter {
 }
 
 /**
- * 可折叠模式的 Search 组件
- * - 可以完全折叠/展开整个搜索区域
- * - 通过 defaultExpanded 控制初始展开状态
- * - 适合需要隐藏搜索栏以获得更多展示空间的场景
+ * Search component in collapsible mode
+ * - The entire search area can be fully collapsed/expanded
+ * - Initial expanded state is controlled via defaultExpanded
+ * - Suitable for scenarios where the search bar needs to be hidden to gain more display space
  */
 const SearchCollapsible: React.FC<SearchCollapsibleProps> = (props) => {
   const {
@@ -27,10 +27,10 @@ const SearchCollapsible: React.FC<SearchCollapsibleProps> = (props) => {
     ...rest
   } = props;
 
-  // collapse 的语义是反的，所以需要取反 defaultExpanded
+  // The semantics of collapse are inverted, so defaultExpanded needs to be negated
   const [collapse, setCollapse] = useState(!defaultExpanded);
 
-  // 处理折叠切换
+  // Handle collapse toggle
   const handleCollapseToggle = useCallback(() => {
     setCollapse((prev) => {
       const newCollapse = !prev;

package/src/components/Search/SearchWithFilter/index.module.scss

@@ -1,3 +1,3 @@
-// SearchWithFilter 组件的独立样式
-// 目前复用父级 Search 组件的样式，如需自定义可在此处添加
+// Standalone styles for the SearchWithFilter component
+// Currently reuses the parent Search component's styles; add customizations here if needed
 

package/src/components/Search/SearchWithFilter/index.tsx

@@ -9,10 +9,10 @@ export interface SearchWithFilterProps extends SearchPropsWithFilter {
 }
 
 /**
- * 带筛选器设置的 Search 组件
- * - 提供下拉菜单，允许用户动态选择显示哪些搜索项
- * - 用户可以自定义显示的搜索字段
- * - 提供更灵活的搜索体验
+ * Search component with filter settings
+ * - Provides a dropdown menu allowing users to dynamically choose which search items are displayed
+ * - Users can customize the displayed search fields
+ * - Offers a more flexible search experience
  */
 const SearchWithFilter: React.FC<SearchWithFilterProps> = (props) => {
   return <SearchBase {...props} showFilter />;

package/src/components/Search/SearchWithMore/index.module.scss

@@ -1,3 +1,3 @@
-// SearchWithMore 组件的独立样式
-// 目前复用父级 Search 组件的样式，如需自定义可在此处添加
+// Standalone styles for the SearchWithMore component
+// Currently reuses the parent Search component's styles; add customizations here if needed
 

package/src/components/Search/SearchWithMore/index.tsx

@@ -12,10 +12,10 @@ export interface SearchWithMoreProps
 }
 
 /**
- * 带更多搜索项的 Search 组件
- * - 将搜索项分为基础项和更多项两组
- * - 初始只显示基础搜索项，点击展开后显示更多项
- * - 适合有大量搜索字段的场景
+ * Search component with a "more items" section
+ * - Splits search items into a basic group and a "more" group
+ * - Only basic items are shown initially; expanding reveals the rest
+ * - Suitable for pages with a large number of search fields
  */
 const SearchWithMore: React.FC<SearchWithMoreProps> = (props) => {
   const { setFilter, ...rest } = props;
@@ -23,7 +23,7 @@ const SearchWithMore: React.FC<SearchWithMoreProps> = (props) => {
   return (
     <SearchBase
       {...rest}
-      // SearchWithMore 始终显示所有搜索项
+      // SearchWithMore always shows all search items
       showAllSearchItems
       showFilter={!!setFilter}
     />

package/src/components/Search/_components/ButtonGroup/index.tsx

@@ -30,7 +30,7 @@ export const ButtonGroup = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
       permitted = true,
     } = props;
 
-    // 判断是否有搜索项（children 存在且不为空）
+    // Determine whether there are search items (children exists and is not empty)
     const hasSearchItems = permitted && children;
 
     return (

package/src/components/Search/_components/SearchBase/index.tsx

@@ -11,7 +11,7 @@ import { ExpandButton } from "../ExpandButton";
 import { FilterDropdown } from "../FilterDropdown";
 import { SearchPropsWithFilter } from "../../_types";
 
-/** 暴露给变体扩展渲染（如高级筛选抽屉）的上下文 */
+/** Context exposed to variant extension rendering (e.g. the advanced filters drawer) */
 export interface SearchBaseContext {
   form: FormInstance;
   expand: boolean;
@@ -23,20 +23,20 @@ export interface SearchBaseContext {
 }
 
 export interface SearchBaseProps extends SearchPropsWithFilter {
-  /** 高级筛选模式：搜索项不显示 label，展开按钮显示为"高级筛选" */
+  /** Advanced filters mode: search items hide their label, and the expand button shows as "advanced filters" */
   advancedFilters?: boolean;
-  /** 是否渲染 FilterDropdown（筛选器设置下拉） */
+  /** Whether to render FilterDropdown (the filter settings dropdown) */
   showFilter?: boolean;
-  /** 表单区域之后、容器之内的附加内容（如折叠开关），仅在有权限时渲染 */
+  /** Extra content after the form area but inside the container (e.g. the collapse toggle); rendered only when permitted */
   afterForm?: ReactNode;
-  /** 容器之外的附加内容（如高级筛选抽屉），仅在有权限时渲染 */
+  /** Extra content outside the container (e.g. the advanced filters drawer); rendered only when permitted */
   renderOutside?: (ctx: SearchBaseContext) => ReactNode;
 }
 
 /**
- * Search 各变体共享的基础实现：
- * 表单渲染、列布局、展开/收起、按钮组、权限控制。
- * 变体只负责自身差异（筛选器、折叠开关、高级筛选抽屉等）。
+ * Base implementation shared by all Search variants:
+ * form rendering, column layout, expand/collapse, button group, permission control.
+ * Variants are only responsible for their own differences (filter, collapse toggle, advanced filters drawer, etc.).
  */
 const SearchBase: React.FC<SearchBaseProps> = (props) => {
   const {
@@ -108,7 +108,7 @@ const SearchBase: React.FC<SearchBaseProps> = (props) => {
     columnOffsetWidth,
   });
 
-  // 按列分组预计算（用于对齐同列 label 宽度），避免在 map 中逐项重复 filter
+  // Precompute grouping by column (used to align label widths within the same column), avoiding repeated per-item filtering inside map
   const columnGroups = useMemo(() => {
     const groups: FormItemProps[][] = Array.from(
       { length: totalColumnNum },

package/src/components/Search/_components/SearchButtons/index.tsx

@@ -6,9 +6,9 @@ interface SearchButtonsProps {
   onSearch: () => void;
   onReset: () => void;
   searchDisabled?: boolean;
-  /** 查询按钮文本 */
+  /** Search button text */
   searchText?: React.ReactNode;
-  /** 重置按钮文本 */
+  /** Reset button text */
   resetText?: React.ReactNode;
 }
 

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

@@ -1,15 +1,15 @@
 import { useEffect, useState, RefObject } from "react";
 
 /**
- * 根据容器宽度动态调整列数的Hook
- * @param containerRef 容器引用
- * @param totalColumnNum 基础总列数（包括按钮组）
- * @param enabled 是否启用自适应（默认true）
- * @param minColumnNum 最小列数（默认1）
- * @param maxColumnNum 最大列数（默认不限制）
- * @param breakpoints 断点配置，格式：{ width: columnNum }，例如 { 1200: 5, 800: 3 }
- * @param baseWidth 基准宽度，用于计算宽度比例（默认1200px）
- * @returns 调整后的总列数
+ * Hook that dynamically adjusts the column count based on container width
+ * @param containerRef Container ref
+ * @param totalColumnNum Base total column count (including the button group)
+ * @param enabled Whether adaptive mode is enabled (default true)
+ * @param minColumnNum Minimum column count (default 1)
+ * @param maxColumnNum Maximum column count (unlimited by default)
+ * @param breakpoints Breakpoint config, format: { width: columnNum }, e.g. { 1200: 5, 800: 3 }
+ * @param baseWidth Base width used to compute the width ratio (default 1200px)
+ * @returns Adjusted total column count
  */
 export function useAdaptiveColumnNum(
   containerRef: RefObject<HTMLDivElement>,
@@ -36,11 +36,11 @@ export function useAdaptiveColumnNum(
 
       let calculatedColumnNum = totalColumnNum;
 
-      // 如果提供了断点配置，优先使用断点
+      // If breakpoint config is provided, use breakpoints first
       if (breakpoints) {
         const sortedBreakpoints = Object.keys(breakpoints)
           ?.map(Number)
-          .sort((a, b) => b - a); // 从大到小排序
+          .sort((a, b) => b - a); // Sort descending
 
         for (const breakpoint of sortedBreakpoints) {
           if (containerWidth >= breakpoint) {
@@ -49,13 +49,13 @@ export function useAdaptiveColumnNum(
           }
         }
       } else {
-        // 默认策略：根据容器宽度自动计算
-        // 基于基础列数，根据容器宽度比例调整
+        // Default strategy: compute automatically from container width
+        // Based on the base column count, adjusted by the container width ratio
         const widthRatio = containerWidth / baseWidth;
         calculatedColumnNum = Math.round(totalColumnNum * widthRatio);
       }
 
-      // 应用最小值和最大值限制
+      // Apply min and max limits
       if (calculatedColumnNum < minColumnNum) {
         calculatedColumnNum = minColumnNum;
       }
@@ -67,24 +67,24 @@ export function useAdaptiveColumnNum(
     };
 
     const resizeObserver = new ResizeObserver(() => {
-      // 使用 requestAnimationFrame 延迟到下一帧，确保DOM已更新
+      // Use requestAnimationFrame to defer to the next frame, ensuring the DOM has updated
       requestAnimationFrame(() => {
         calculateColumnNum();
       });
     });
 
-    // 延迟观察，确保 ref 已被赋值
+    // Defer observation to ensure the ref has been assigned
     const observeContainer = () => {
       if (containerRef.current) {
         resizeObserver.observe(containerRef.current);
       } else {
-        // 如果 ref 还未赋值，稍后重试
+        // If the ref is not assigned yet, retry later
         requestAnimationFrame(observeContainer);
       }
     };
     observeContainer();
 
-    // 监听窗口大小变化
+    // Listen for window resize
     const handleWindowResize = () => {
       requestAnimationFrame(() => {
         calculateColumnNum();
@@ -92,7 +92,7 @@ export function useAdaptiveColumnNum(
     };
     window.addEventListener("resize", handleWindowResize);
 
-    // 初始计算（延迟执行以确保DOM已渲染）
+    // Initial calculation (deferred to ensure the DOM has rendered)
     requestAnimationFrame(() => {
       calculateColumnNum();
     });

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

@@ -77,7 +77,7 @@ export interface UseSearchCommonReturn {
 }
 
 /**
- * 提取所有 Search 组件的通用逻辑
+ * Extracts the common logic shared by all Search components
  */
 export const useSearchCommon = (
   params: UseSearchCommonParams,
@@ -109,23 +109,23 @@ export const useSearchCommon = (
   const buttonGroupRef = useRef<HTMLDivElement>(null);
   const cls = useMemo(() => generateRandomStr(10), []);
 
-  // 提取可见搜索项
+  // Extract visible search items
   const visibleSearchItems = useMemo(() => {
     return processedSearchItems.filter((item) => item.visible !== false);
   }, [processedSearchItems]);
 
-  // 提取可见的更多搜索项
+  // Extract visible "more" search items
   const visibleMoreSearchItems = useMemo(() => {
     return moreSearchItems.filter((item) => item.visible !== false);
   }, [moreSearchItems]);
 
-  // 计算可见的搜索项数量
+  // Count of visible search items
   const visibleSearchItemCount = visibleSearchItems.length;
 
-  // 计算总列数（包括按钮组）
+  // Total column count (including the button group)
   const baseTotalColumnNum = columnNum + 1;
 
-  // 根据容器宽度动态调整列数
+  // Dynamically adjust column count based on container width
   const totalColumnNum = useAdaptiveColumnNum(
     containerRef,
     baseTotalColumnNum,
@@ -136,10 +136,10 @@ export const useSearchCommon = (
     baseWidth,
   );
 
-  // 计算调整后的搜索项列数（不包括按钮组）
+  // Adjusted search-item column count (excluding the button group)
   const adaptiveColumnNum = Math.max(1, totalColumnNum - 1);
 
-  // 使用基于宽度的展开/收起控制
+  // Use width-based expand/collapse control
   const { expand, setExpand, toggleExpand, visibleItemCount } = useSearchExpand(
     containerRef,
     buttonGroupRef,
@@ -156,14 +156,14 @@ export const useSearchCommon = (
 
   useSearchForm({ form, searchData });
 
-  // 计算当前应该显示的搜索项
+  // Compute the search items that should currently be displayed
   const currentSearchItems = useMemo(() => {
     if (showAllSearchItems || !!moreSearchItems?.length) {
       if (expand) return [...visibleSearchItems, ...visibleMoreSearchItems];
       return visibleSearchItems;
     }
 
-    // 计算按钮组宽度和列宽（用于判断是否需要显示更多项）
+    // Compute button group width and column width (used to decide whether more items should be displayed)
     let buttonGroupWidth: number | undefined;
     let columnWidth: number | undefined;
 
@@ -178,7 +178,7 @@ export const useSearchCommon = (
       columnWidth = result.columnWidth;
     }
 
-    // 否则使用计算函数
+    // Otherwise use the calculation function
     return calculateVisibleItems(
       processedSearchItems,
       expand,
@@ -215,18 +215,18 @@ export const useSearchCommon = (
     });
   }, [form, onSearch]);
 
-  // 检查是否有自定义宽度
+  // Check whether any item has a custom width
   const hasCustomWidth = useMemo(() => {
     return processedSearchItems.some((item) => item.width !== undefined);
   }, [processedSearchItems]);
 
-  // 计算实际应该显示的项数（考虑按钮组宽度大于列宽的情况）
+  // Compute the actual number of items to display (accounting for the case where the button group is wider than a column)
   const actualDisplayCount = useMemo(() => {
     if (hasCustomWidth) {
       return visibleItemCount;
     }
 
-    // 计算按钮组宽度和列宽
+    // Compute button group width and column width
     const { buttonGroupWidth, columnWidth } =
       calculateButtonGroupAndColumnWidth(
         containerRef,
@@ -235,7 +235,7 @@ export const useSearchCommon = (
         columnOffsetWidth,
       );
 
-    // 判断按钮组宽度是否大于列宽，如果是，则显示 实际搜索项数量+1
+    // If the button group is wider than a column, display actual search item count + 1
     if (
       shouldDisplayExtraItem(
         buttonGroupWidth,
@@ -256,9 +256,9 @@ export const useSearchCommon = (
     visibleItemCount,
   ]);
 
-  // 计算是否显示展开按钮
+  // Determine whether to show the expand button
   const showExpandButton = useMemo(() => {
-    // 如果有更多搜索项，显示展开按钮
+    // If there are "more" search items, show the expand button
     if (showAllSearchItems || !!moreSearchItems?.length) {
       if (visibleMoreSearchItems?.length) {
         return true;
@@ -266,11 +266,11 @@ export const useSearchCommon = (
       return false;
     }
 
-    // 如果有自定义宽度，根据可见项数量判断
+    // If there are custom widths, decide based on the visible item count
     if (hasCustomWidth) {
       return visibleSearchItemCount > visibleItemCount;
     }
-    // 否则根据实际显示项数判断（考虑按钮组宽度大于列宽的情况）
+    // Otherwise decide based on the actual display count (accounting for the case where the button group is wider than a column)
     return visibleSearchItemCount > actualDisplayCount;
   }, [
     showAllSearchItems,
@@ -282,7 +282,7 @@ export const useSearchCommon = (
     visibleItemCount,
   ]);
 
-  // 检查按钮组是否有权限的按钮
+  // Check whether the button group contains any permitted button
   const hasPermittedButtons = useCallback(
     (buttonGroup?: ChakraButtonProps[]) => {
       if (!buttonGroup?.length) return false;
@@ -292,7 +292,7 @@ export const useSearchCommon = (
     [checkPermission],
   );
 
-  // 权限和内容检查
+  // Permission and content check
   const shouldRender = useMemo(() => {
     return Boolean(
       hasPermittedButtons(beforeButtonGroup) ||