@hsu-react/ui 0.0.13 → 0.0.14

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

@@ -3,21 +3,21 @@ import { useEffect, useState, RefObject, useCallback } from "react";
 import { createRoot } from "react-dom/client";
 import { ElementItem, Font, SearchCardOption } from "../_components/OptionRow";
 
-// 优化：缓存测量结果
+// Optimization: cache measurement results
 const measurementCache = new Map<string, number>();
 
 function directMeasureWidth(element: React.ReactElement): Promise<number> {
-  // 尝试从缓存获取
+  // Try to get from the cache
   const cacheKey = JSON.stringify(element.props);
   if (measurementCache.has(cacheKey)) {
     return Promise.resolve(measurementCache.get(cacheKey)!);
   }
 
   return new Promise((resolve) => {
-    // 创建隐藏容器
+    // Create a hidden container
     const container = document.createElement("div");
 
-    // 设置样式使其不可见但能正确计算尺寸
+    // Set styles so it is invisible but its size can be computed correctly
     Object.assign(container.style, {
       position: "absolute",
       visibility: "hidden",
@@ -30,27 +30,27 @@ function directMeasureWidth(element: React.ReactElement): Promise<number> {
 
     document.body.appendChild(container);
 
-    // 创建根并渲染
+    // Create a root and render
     const root = createRoot(container);
 
     try {
-      // 直接渲染元素
+      // Render the element directly
       root.render(element);
 
-      // 等待渲染完成
+      // Wait for rendering to finish
       setTimeout(() => {
         try {
-          // 获取容器中第一个子元素的宽度
+          // Get the width of the first child element in the container
           const width = container.clientWidth || 0;
 
-          // 缓存结果
+          // Cache the result
           measurementCache.set(cacheKey, width);
           resolve(width);
         } catch {
           resolve(0);
         }
 
-        // 清理
+        // Clean up
         try {
           root.unmount();
           if (document.body.contains(container)) {
@@ -63,7 +63,7 @@ function directMeasureWidth(element: React.ReactElement): Promise<number> {
     } catch {
       resolve(0);
 
-      // 清理
+      // Clean up
       try {
         if (document.body.contains(container)) {
           document.body.removeChild(container);
@@ -76,7 +76,7 @@ function directMeasureWidth(element: React.ReactElement): Promise<number> {
 }
 
 /**
- * 自定义Hook，用于计算需要显示"更多"按钮的选项
+ * Custom hook that computes which options need to display the "More" button
  */
 export function useSearchCardMoreOptions(
   containerRef: RefObject<HTMLDivElement>,
@@ -91,7 +91,7 @@ export function useSearchCardMoreOptions(
 ) {
   const [showMore, setShowMore] = useState<Record<string, boolean>>({});
 
-  // 优化：缓存计算函数
+  // Optimization: cache the calculation function
   const calculateMoreOptions = useCallback(async () => {
     if (containerRef.current) {
       const div = containerRef.current;
@@ -162,7 +162,7 @@ export function useSearchCardMoreOptions(
   useEffect(() => {
     calculateMoreOptions();
 
-    // 添加窗口大小调整监听器
+    // Add a window resize listener
     window.addEventListener("resize", calculateMoreOptions);
 
     return () => {

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();
     });