@choice-ui/react 1.4.2 → 1.4.5

package/dist/components/menus/dist/index.d.ts

@@ -56,6 +56,7 @@ interface MenuScrollArrowProps {
     onScroll: (amount: number) => void;
     scrollRef: React.MutableRefObject<HTMLDivElement | null>;
     scrollTop: number;
+    variant?: "default" | "light" | "reset";
 }
 declare const MenuScrollArrow: (props: MenuScrollArrowProps) => react_jsx_runtime.JSX.Element;
 
@@ -107,22 +108,22 @@ interface MenusComponentProps extends react__default.ForwardRefExoticComponent<M
 declare const Menus: MenusComponentProps;
 
 /**
- * 基础菜单状态管理 Hook
+ * Basic menu state management Hook
  *
- * 处理所有菜单组件的通用状态：
- * - open/close 状态及受控逻辑
- * - activeIndex 状态
- * - touch 交互状态
- * - scrollTop 状态
- * - 唯一ID生成
- * - 状态变化回调
+ * Handle common state for all menu components:
+ * - open/close state and controlled logic
+ * - activeIndex state
+ * - touch interaction state
+ * - scrollTop state
+ * - Unique ID generation
+ * - State change callback
  */
 interface MenuStateConfig {
-    /** 是否禁用 */
+    /** Whether to disable */
     disabled?: boolean;
-    /** 打开状态变化回调 */
+    /** Open state change callback */
     onOpenChange?: (open: boolean) => void;
-    /** 受控的打开状态 */
+    /** Controlled open state */
     open?: boolean;
 }
 interface MenuStateResult {
@@ -142,17 +143,17 @@ interface MenuStateResult {
 declare function useMenuState(config?: MenuStateConfig): MenuStateResult;
 
 /**
- * 菜单引用管理 Hook
+ * Menu reference management Hook
  *
- * 统一管理菜单组件中所有需要的引用：
- * - 滚动容器引用
- * - 列表项引用数组
- * - 列表内容引用数组
- * - 定时器引用
- * - Select 专用引用（overflow, allowSelect 等）
+ * Unify the management of all references needed in menu components:
+ * - Scroll container reference
+ * - List item reference array
+ * - List content reference array
+ * - Timer reference
+ * - Select specific reference (overflow, allowSelect, etc.)
  */
 interface MenuRefsConfig {
-    /** 是否为 Select 类型（需要额外的选择相关引用） */
+    /** Whether to use Select type (requires additional selection related references) */
     isSelect?: boolean;
 }
 interface MenuRefsResult {
@@ -169,40 +170,40 @@ interface MenuRefsResult {
 declare function useMenuRefs(config?: MenuRefsConfig): MenuRefsResult;
 
 /**
- * 菜单滚动处理 Hook
+ * Menu scroll handling Hook
  *
- * 处理菜单组件的滚动相关逻辑：
- * - 滚动位置管理
- * - 箭头滚动处理
- * - 滚动事件处理
- * - 触摸相关的滚动隐藏逻辑
+ * Handle scroll related logic in menu components:
+ * - Scroll position management
+ * - Arrow scroll handling
+ * - Scroll event handling
+ * - Touch-related scroll hiding logic
  */
 interface MenuScrollConfig {
-    /** Select 专用：fallback 模式 */
+    /** Select specific: fallback mode */
     fallback?: boolean;
-    /** 是否是 Select 类型（使用不同的滚动逻辑） */
+    /** Whether to use Select type (uses different scroll logic) */
     isSelect?: boolean;
-    /** 滚动容器引用 */
+    /** Scroll container reference */
     scrollRef: React.RefObject<HTMLDivElement>;
-    /** 滚动位置状态 */
+    /** Scroll position state */
     scrollTop: number;
-    /** 定时器引用 */
+    /** Timer reference */
     selectTimeoutRef: React.RefObject<ReturnType<typeof setTimeout> | undefined>;
-    /** Select 专用：设置内部偏移 */
+    /** Select specific: set internal offset */
     setInnerOffset?: (offset: number | ((prev: number) => number)) => void;
-    /** 设置滚动位置 */
+    /** Set scroll position */
     setScrollTop: (scrollTop: number) => void;
-    /** 触摸状态 */
+    /** Touch state */
     touch: boolean;
 }
 interface MenuScrollResult {
-    /** 箭头隐藏处理器 */
+    /** Arrow hide handler */
     handleArrowHide: () => void;
-    /** 箭头滚动处理器 */
+    /** Arrow scroll handler */
     handleArrowScroll: (amount: number) => void;
-    /** 滚动事件处理器 */
+    /** Scroll event handler */
     handleScroll: (event: React.UIEvent) => void;
-    /** 滚动相关的属性对象（已缓存，避免每次渲染都创建新对象） */
+    /** Scroll-related property object (cached to avoid creating new objects on every render) */
     scrollProps: {
         onScroll: (event: React.UIEvent) => void;
     };
@@ -210,231 +211,231 @@ interface MenuScrollResult {
 declare function useMenuScroll(config: MenuScrollConfig): MenuScrollResult;
 
 /**
- * 菜单子元素解析 Hook
+ * Menu children parsing Hook
  *
- * 处理菜单组件的子元素解析逻辑：
- * - 从 children 中提取 trigger 元素
- * - 从 children 中提取 content 元素
- * - 支持 Select 和 Dropdown 的不同子元素类型
- * - 错误处理和警告
+ * Handle menu component child element parsing logic:
+ * - Extract trigger element from children
+ * - Extract content element from children
+ * - Support different child element types for Select and Dropdown
+ * - Error handling and warnings
  */
 interface MenuChildrenConfig<T extends react__default.ElementType = react__default.ElementType, C extends react__default.ElementType = react__default.ElementType, S extends react__default.ElementType = react__default.ElementType> {
-    /** Content 组件类型 */
+    /** Content component type */
     ContentComponent: C;
-    /** SubTrigger 组件类型（仅 Dropdown 使用） */
+    /** SubTrigger component type (only used for Dropdown) */
     SubTriggerComponent?: S;
-    /** Trigger 组件类型 */
+    /** Trigger component type */
     TriggerComponent: T;
-    /** 子元素 */
+    /** Children */
     children?: react__default.ReactNode;
-    /** 组件类型名称，用于错误提示 */
+    /** Component type name, for error提示 */
     componentName: string;
 }
 interface MenuChildrenResult {
-    /** 内容元素 */
+    /** Content element */
     contentElement: react__default.ReactElement | null;
-    /** 错误信息 */
+    /** Error message */
     error?: string;
-    /** 是否有必需的元素 */
+    /** Whether there are required elements */
     hasRequiredElements: boolean;
-    /** 子触发器元素（仅 Dropdown 使用） */
+    /** Sub-trigger element (only used for Dropdown) */
     subTriggerElement?: react__default.ReactElement | null;
-    /** 触发器元素 */
+    /** Trigger element */
     triggerElement: react__default.ReactElement | null;
 }
 declare function useMenuChildren<T extends react__default.ElementType = react__default.ElementType, C extends react__default.ElementType = react__default.ElementType, S extends react__default.ElementType = react__default.ElementType>(config: MenuChildrenConfig<T, C, S>): MenuChildrenResult;
 
 /**
- * 菜单 FloatingUI 配置 Hook
+ * Menu FloatingUI configuration Hook
  *
- * 为 Select 和 Dropdown 提供不同的 floating 配置：
- * - Select: 使用 inner 中间件 + 虚拟滚动
- * - Dropdown: 使用标准中间件 + 嵌套支持
+ * Provide different floating configurations for Select and Dropdown:
+ * - Select: use inner middleware + virtual scrolling
+ * - Dropdown: use standard middleware + nested support
  */
 interface MenuFloatingConfig {
     activeIndex: number | null;
-    /** 当前选中索引（Select 专用） */
+    /** Current selected index (Select specific) */
     currentSelectedIndex?: number;
     elementsRef: React.RefObject<Array<HTMLElement | null>>;
-    /** 是否为 fallback 模式（Select 专用） */
+    /** Whether to use fallback mode (Select specific) */
     fallback?: boolean;
-    /** 状态变化回调 */
+    /** State change callback */
     handleOpenChange: (open: boolean) => void;
-    /** 内部偏移（Select 专用） */
+    /** Internal offset (Select specific) */
     innerOffset?: number;
-    /** 当前打开状态 */
+    /** Current open state */
     isControlledOpen: boolean;
-    /** 是否为嵌套模式（仅 Dropdown 使用） */
+    /** Whether to use nested mode (only used for Dropdown) */
     isNested?: boolean;
     labelsRef: React.RefObject<Array<string | null>>;
-    /** 是否匹配触发器宽度 */
+    /** Whether to match trigger width */
     matchTriggerWidth?: boolean;
-    /** 节点 ID（仅 Dropdown 使用） */
+    /** Node ID (only used for Dropdown) */
     nodeId?: string;
-    /** 偏移距离 */
+    /** Offset distance */
     offsetDistance?: number;
-    /** overflow 引用（Select 专用） */
+    /** overflow reference (Select specific) */
     overflowRef?: React.RefObject<SideObject | null>;
-    /** 位置配置 */
+    /** Position configuration */
     placement?: Placement;
     scrollRef: React.RefObject<HTMLDivElement>;
     setActiveIndex: (index: number | null) => void;
-    /** 设置 fallback（Select 专用） */
+    /** Set fallback (Select specific) */
     setFallback?: (fallback: boolean) => void;
-    /** 设置内部偏移（Select 专用） */
+    /** Set internal offset (Select specific) */
     setInnerOffset?: (offset: number) => void;
-    /** 触摸状态 */
+    /** Touch state */
     touch?: boolean;
-    /** 组件类型 */
+    /** Component type */
     type: "select" | "dropdown";
 }
 interface MenuFloatingResult {
-    /** floating 上下文和样式 */
+    /** floating context and styles */
     floating: ReturnType<typeof useFloating>;
-    /** hover 处理器（仅 Dropdown 使用） */
+    /** hover handler (only used for Dropdown) */
     hover?: ReturnType<typeof useHover>;
-    /** 交互处理器 */
+    /** Interaction handler */
     interactions: ReturnType<typeof useInteractions>;
 }
 declare function useMenuFloating(config: MenuFloatingConfig): MenuFloatingResult;
 
 /**
- * 菜单 FloatingTree 集成 Hook
+ * Menu FloatingTree integration Hook
  *
- * 专用于 Dropdown 组件的 FloatingTree 支持：
- * - 管理 nodeId 和 parentId
- * - 处理树形结构的事件通信
- * - 支持嵌套菜单的打开/关闭协调
- * - 处理父子菜单的焦点管理
+ * Specialized for FloatingTree support for Dropdown component:
+ * - Manage nodeId and parentId
+ * - Handle event communication for tree structure
+ * - Support opening/closing coordination for nested menus
+ * - Handle focus management for parent and child menus
  */
 interface MenuTreeConfig {
-    /** 是否禁用嵌套功能 */
+    /** Whether to disable nested functionality */
     disabledNested?: boolean;
-    /** 打开状态变化处理函数 */
+    /** Open state change handling function */
     handleOpenChange: (open: boolean) => void;
-    /** 当前打开状态 */
+    /** Current open state */
     isControlledOpen: boolean;
 }
 interface MenuTreeResult {
-    /** 清理 tree 事件监听 */
+    /** Clean up tree event listening */
     cleanupTreeEvents: () => void;
-    /** 是否为嵌套模式 */
+    /** Whether to be nested mode */
     isNested: boolean;
-    /** 列表项实例 */
+    /** List item instance */
     item: ReturnType<typeof useListItem>;
-    /** 当前节点 ID */
+    /** Current node ID */
     nodeId: string | undefined;
-    /** 父节点 ID */
+    /** Parent node ID */
     parentId: string | null;
-    /** FloatingTree 实例 */
+    /** FloatingTree instance */
     tree: ReturnType<typeof useFloatingTree>;
 }
 declare function useMenuTree(config: MenuTreeConfig): MenuTreeResult;
 
 /**
- * 菜单滚动容器高度设置 Hook
+ * Menu scroll container height setting Hook
  *
- * 确保滚动容器正确设置高度，作为 size middleware 的补充
- * 在所有菜单组件中都有类似的逻辑，统一抽取到这里
+ * Ensure the scroll container is correctly set to the parent element height, as a complement to the size middleware
+ * Similar logic exists in all menu components, unified extraction here
  *
- * 功能：
- * - 在菜单打开且定位完成后，确保滚动容器正确继承父元素高度
- * - 使用 requestAnimationFrame 确保 DOM 已更新，避免与 size middleware 的时序冲突
+ * Features:
+ * - Ensure the scroll container is correctly inherited from the parent element height after opening and positioning
+ * - Use requestAnimationFrame to ensure the DOM is updated, avoiding timing conflicts with the size middleware
  */
 interface MenuScrollHeightConfig {
-    /** 是否打开 */
+    /** Whether to open */
     isControlledOpen: boolean;
-    /** 是否已定位 */
+    /** Whether to be positioned */
     isPositioned: boolean;
-    /** 滚动容器引用 */
+    /** Scroll container reference */
     scrollRef: React.RefObject<HTMLDivElement>;
 }
 /**
- * 设置滚动容器高度
- * 这个 hook 会在菜单打开且定位完成后，确保滚动容器正确设置高度
+ * Set scroll container height
+ * This hook will ensure the scroll container is correctly set to the parent element height after opening and positioning
  */
 declare function useMenuScrollHeight(config: MenuScrollHeightConfig): void;
 
 /**
- * 菜单基础引用管理 Hook
+ * Menu base refs management Hook
  *
- * 统一管理所有菜单组件需要的基础 refs：
- * - scrollRef: 滚动容器引用
- * - elementsRef: 菜单项元素引用数组
- * - labelsRef: 菜单项标签引用数组（用于 typeahead）
- * - selectTimeoutRef: 选择延迟定时器引用
+ * Unified management of all base refs needed by menu components:
+ * - scrollRef: scroll container reference
+ * - elementsRef: menu item element reference array
+ * - labelsRef: menu item label reference array (for typeahead)
+ * - selectTimeoutRef: select delay timer reference
  *
- * 这些 refs 在多个组件中都有使用，统一管理可以保持一致性
+ * These refs are used in multiple components, unified management can maintain consistency
  */
 interface MenuBaseRefsResult {
-    /** 菜单项元素引用数组 */
+    /** Menu item element reference array */
     elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
-    /** 菜单项标签引用数组（用于 typeahead） */
+    /** Menu item label reference array (for typeahead) */
     labelsRef: React.MutableRefObject<Array<string | null>>;
-    /** 滚动容器引用 */
+    /** Scroll container reference */
     scrollRef: React.RefObject<HTMLDivElement>;
-    /** 选择延迟定时器引用 */
+    /** Select delay timer reference */
     selectTimeoutRef: React.MutableRefObject<ReturnType<typeof setTimeout> | undefined>;
 }
 /**
- * 创建菜单基础引用
+ * Create menu base refs
  */
 declare function useMenuBaseRefs(): MenuBaseRefsResult;
 
 /**
- * 菜单选择状态管理 Hook
+ * Menu selection state management Hook
  *
- * 专用于 Select 组件的选择逻辑：
- * - 管理选中索引和值的映射
- * - 处理选择延迟和阻止机制
- * - 处理鼠标和键盘选择
- * - 支持受控和非受控值
+ * Specialized for Select component selection logic:
+ * - Manage the mapping of selected index and value
+ * - Handle selection delay and blocking mechanism
+ * - Handle mouse and keyboard selection
+ * - Support controlled and uncontrolled values
  */
 interface MenuSelectionConfig {
-    /** 关闭菜单回调 */
+    /** Close menu callback */
     handleOpenChange: (open: boolean) => void;
-    /** 是否控制打开状态 */
+    /** Whether to control the open state */
     isControlledOpen: boolean;
-    /** 值变化回调 */
+    /** Value change callback */
     onChange?: (value: string) => void;
-    /** 选项列表 */
+    /** Option list */
     options: Array<{
         [key: string]: unknown;
         disabled?: boolean;
         divider?: boolean;
         value?: string;
     }>;
-    /** 当前值 */
+    /** Current value */
     value?: string | null;
 }
 interface MenuSelectionResult {
-    /** 允许鼠标抬起状态 */
+    /** Allow mouse up state */
     allowMouseUp: boolean;
-    /** 允许选择状态 */
+    /** Allow select state */
     allowSelect: boolean;
-    /** 阻止选择状态 */
+    /** Block select state */
     blockSelection: boolean;
-    /** 当前选中索引（基于 value 计算） */
+    /** Current selected index (based on value calculation) */
     currentSelectedIndex: number;
-    /** 处理选择 */
+    /** Handle selection */
     handleSelect: (index: number) => void;
-    /** 当前选中索引 */
+    /** Current selected index */
     selectedIndex: number;
-    /** 设置允许鼠标抬起状态 */
+    /** Set allow mouse up state */
     setAllowMouseUp: (allow: boolean) => void;
-    /** 设置允许选择状态 */
+    /** Set allow select state */
     setAllowSelect: (allow: boolean) => void;
-    /** 设置阻止选择状态 */
+    /** Set block select state */
     setBlockSelection: (block: boolean) => void;
-    /** 设置选中索引 */
+    /** Set selected index */
     setSelectedIndex: (index: number) => void;
 }
 declare function useMenuSelection(config: MenuSelectionConfig): MenuSelectionResult;
 
 /**
- * 通用菜单上下文接口
+ * Generic menu context interface
  *
- * 用于 Select 和 Dropdown 组件的统一上下文
+ * Used for unified context of Select and Dropdown components
  */
 interface MenuContextType {
     activeIndex: number | null;
@@ -459,13 +460,13 @@ interface MenuContextItemProps extends MenuItemProps {
     value?: string;
 }
 /**
- * 通用菜单项组件
+ * Generic menu item component
  *
- * 供 Select 和 Dropdown 共用，统一所有交互逻辑：
- * - touch 事件处理
- * - 选择逻辑
- * - 键盘导航
- * - 视觉状态管理
+ * Shared by Select and Dropdown, unify all interaction logic:
+ * - touch event handling
+ * - selection logic
+ * - keyboard navigation
+ * - visual state management
  */
 declare const MenuContextItem: react.MemoExoticComponent<react.ForwardRefExoticComponent<MenuContextItemProps & react.RefAttributes<HTMLButtonElement>>>;
 
@@ -479,4 +480,4 @@ declare const MenuContextLabel: react.NamedExoticComponent<MenuLabelProps>;
 
 declare const MenuContextSubTrigger: react.MemoExoticComponent<react.ForwardRefExoticComponent<MenuItemProps & react.RefAttributes<HTMLButtonElement>>>;
 
-export { MenuButton, MenuCheckbox, MenuContext, MenuContextContent, MenuContextItem, type MenuContextItemProps, MenuContextLabel, MenuContextSubTrigger, type MenuContextType, MenuDivider, MenuInput, MenuItem, MenuLabel, MenuScrollArrow, MenuSearch, MenuSearchEmpty, MenuTrigger, MenuValue, Menus, type MenusProps, useMenuBaseRefs, useMenuChildren, useMenuFloating, useMenuRefs, useMenuScroll, useMenuScrollHeight, useMenuSelection, useMenuState, useMenuTree };
+export { MenuButton, MenuCheckbox, type MenuCheckboxProps, MenuContext, MenuContextContent, MenuContextItem, type MenuContextItemProps, MenuContextLabel, MenuContextSubTrigger, type MenuContextType, MenuDivider, MenuInput, MenuItem, type MenuItemProps, MenuLabel, type MenuLabelProps, MenuScrollArrow, type MenuScrollArrowProps, MenuSearch, MenuSearchEmpty, MenuTrigger, type MenuTriggerProps, MenuValue, Menus, type MenusProps, useMenuBaseRefs, useMenuChildren, useMenuFloating, useMenuRefs, useMenuScroll, useMenuScrollHeight, useMenuSelection, useMenuState, useMenuTree };