@kingsoft-ai/design 0.1.11 → 0.1.13

package/dist/types/DesignThemeProvider.d.ts

@@ -6,6 +6,7 @@
  */
 import type { ReactNode } from 'react';
 import type { AppTheme } from '@kingsoft-ai/theme';
+import type { DeepPartial } from './types/theme-utils';
 export interface DesignThemeProviderProps {
     /** 子组件 */
     children: ReactNode;
@@ -16,9 +17,30 @@ export interface DesignThemeProviderProps {
     mode?: 'light' | 'dark';
     /**
      * 自定义主题对象（可选）
-     * 如果提供，将覆盖默认主题
+     *
+     * 支持部分配置，会自动与默认主题进行深度合并。
+     * 只需要提供你想要覆盖的部分即可。
+     *
+     * @example
+     * ```tsx
+     * // 只覆盖 card 组件的部分 token
+     * const customTheme = {
+     *   components: {
+     *     card: {
+     *       container: {
+     *         background: { default: '#F0F4FF' },
+     *         radius: '24px',
+     *       }
+     *     }
+     *   }
+     * }
+     *
+     * <DesignThemeProvider theme={customTheme}>
+     *   <Card>自定义样式的卡片</Card>
+     * </DesignThemeProvider>
+     * ```
      */
-    theme?: AppTheme;
+    theme?: DeepPartial<AppTheme>;
 }
 /**
  * Design 组件主题提供者
@@ -35,9 +57,9 @@ export interface DesignThemeProviderProps {
  *   <Button>点击我</Button>
  * </DesignThemeProvider>
  *
- * // 使用自定义主题
- * <DesignThemeProvider theme={customTheme}>
- *   <Button>点击我</Button>
+ * // 使用部分自定义主题（自动与默认主题合并）
+ * <DesignThemeProvider theme={{ components: { card: { container: { radius: '24px' } } } }}>
+ *   <Card>自定义圆角的卡片</Card>
  * </DesignThemeProvider>
  * ```
  */

package/dist/types/button/Button.d.ts

@@ -27,6 +27,8 @@ export type ButtonProps = Omit<AriaButtonProps, 'elementType'> & {
     loading?: boolean;
     /** 全宽按钮 */
     fullWidth?: boolean;
+    /** 是否禁用（统一 API，优先级高于 isDisabled） */
+    disabled?: boolean;
     /** 自定义类名 */
     className?: string;
     /** 子元素 */
@@ -49,6 +51,8 @@ export declare const Button: import("react").ForwardRefExoticComponent<Omit<Aria
     loading?: boolean;
     /** 全宽按钮 */
     fullWidth?: boolean;
+    /** 是否禁用（统一 API，优先级高于 isDisabled） */
+    disabled?: boolean;
     /** 自定义类名 */
     className?: string;
     /** 子元素 */

package/dist/types/card/Card.d.ts

@@ -0,0 +1,34 @@
+import React, { ReactNode } from 'react';
+export interface CardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+    /**
+     * Card title
+     */
+    title?: ReactNode;
+    /**
+     * Content to render in the top-right corner of the card
+     */
+    extra?: ReactNode;
+    /**
+     * Card cover image
+     */
+    cover?: ReactNode;
+    /**
+     * Card footer content
+     */
+    footer?: ReactNode;
+    /**
+     * Lift up when hovering card
+     */
+    hoverable?: boolean;
+    /**
+     * Card variant
+     * @default 'elevated'
+     */
+    variant?: 'elevated' | 'outlined' | 'filled';
+    /**
+     * Custom padding for body
+     */
+    bodyPadding?: string;
+    children?: ReactNode;
+}
+export declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>>;

package/dist/types/card/Card.style.d.ts

@@ -0,0 +1,46 @@
+import { CardTokens } from '../types/component-tokens.types';
+export declare const CardContainer: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    tokens: CardTokens;
+    variant: "elevated" | "outlined" | "filled";
+    hoverable?: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const CardHeader: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    tokens: CardTokens;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const CardTitle: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    tokens: CardTokens;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const CardExtra: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    tokens: CardTokens;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const CardBody: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    tokens: CardTokens;
+    padding?: string;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const CardCover: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    tokens: CardTokens;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const CardFooter: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    tokens: CardTokens;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;

package/dist/types/card/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Card';
+export * from './tokens';

package/dist/types/card/tokens.d.ts

@@ -0,0 +1,3 @@
+import { TokenGenerator } from '../types/theme-utils';
+import { CardTokens } from '../types/component-tokens.types';
+export declare const getCardTokens: TokenGenerator<CardTokens>;

package/dist/types/floatButton/FloatButton.d.ts

@@ -0,0 +1,57 @@
+/**
+ * FloatButton 悬浮按钮组件
+ *
+ * 基于 react-aria 实现无障碍访问的悬浮按钮组件
+ * 参考 antd FloatButton 设计实现
+ *
+ * @example
+ * ```tsx
+ * <FloatButton
+ *   icon={<IconPlus />}
+ *   type="primary"
+ *   onClick={() => console.log('clicked')}
+ * />
+ * ```
+ */
+import type { ReactNode } from 'react';
+import type { AriaButtonProps } from 'react-aria';
+import { type FloatButtonType, type FloatButtonShape, type FloatButtonSize, type TooltipPlacement } from './FloatButton.style';
+export type { TooltipPlacement };
+export interface TooltipConfig {
+    /** Tooltip 标题 */
+    title?: ReactNode;
+    /** Tooltip 颜色 */
+    color?: string;
+    /** Tooltip 位置 */
+    placement?: TooltipPlacement;
+}
+export declare const TYPES: readonly ["default", "primary"];
+export declare const SHAPES: readonly ["circle", "square"];
+export declare const SIZES: readonly ["sm", "md", "lg"];
+export interface FloatButtonProps extends Omit<AriaButtonProps, 'elementType'> {
+    /** 按钮类型 */
+    buttonType?: FloatButtonType;
+    /** 按钮形状 */
+    shape?: FloatButtonShape;
+    /** 按钮尺寸 */
+    size?: FloatButtonSize;
+    /** 图标 */
+    icon?: ReactNode;
+    /** 文字描述 */
+    description?: ReactNode;
+    /** 提示文字或配置 */
+    tooltip?: ReactNode | TooltipConfig;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: React.CSSProperties;
+}
+/**
+ * FloatButton 悬浮按钮组件
+ *
+ * 用于页面中的悬浮操作按钮，通常固定在页面特定位置
+ * 支持圆形和方形两种形状
+ */
+export declare const FloatButton: import("react").ForwardRefExoticComponent<FloatButtonProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/types/floatButton/FloatButton.style.d.ts

@@ -0,0 +1,74 @@
+/**
+ * FloatButton 悬浮按钮样式
+ *
+ * 基于三层 Token 体系实现悬浮按钮样式
+ * 参考 antd FloatButton 设计规范
+ */
+export declare const floatButtonTypes: readonly ["default", "primary"];
+export declare const floatButtonShapes: readonly ["circle", "square"];
+export declare const floatButtonSizes: readonly ["sm", "md", "lg"];
+export declare const tooltipPlacements: readonly ["top", "bottom", "left", "right"];
+export type FloatButtonType = (typeof floatButtonTypes)[number];
+export type FloatButtonShape = (typeof floatButtonShapes)[number];
+export type FloatButtonSize = (typeof floatButtonSizes)[number];
+export type TooltipPlacement = (typeof tooltipPlacements)[number];
+/**
+ * 悬浮按钮根元素
+ */
+export declare const FloatButtonRoot: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    $buttonType: FloatButtonType;
+    $shape: FloatButtonShape;
+    $size: FloatButtonSize;
+    $isPressed: boolean;
+}, import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, {}>;
+/**
+ * 按钮内容容器
+ */
+export declare const FloatButtonContent: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, {}>;
+/**
+ * 图标包装器
+ */
+export declare const IconWrapper: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, {}>;
+/**
+ * 描述文字
+ */
+export declare const Description: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, {}>;
+/**
+ * Tooltip 包装器
+ */
+export declare const TooltipWrapper: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * Tooltip 卡片
+ */
+export declare const TooltipCard: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    $placement: TooltipPlacement;
+    $color?: string;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * Tooltip 箭头
+ */
+export declare const TooltipArrow: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    $placement: TooltipPlacement;
+    $color?: string;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, {}>;

package/dist/types/floatButton/__tests__/FloatButton.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * FloatButton 组件测试
+ */
+export {};

package/dist/types/floatButton/index.d.ts

@@ -0,0 +1,4 @@
+export { FloatButton } from './FloatButton';
+export type { FloatButtonProps, TooltipConfig } from './FloatButton';
+export type { FloatButtonType, FloatButtonShape, FloatButtonSize } from './FloatButton.style';
+export { TYPES, SHAPES } from './FloatButton';

package/dist/types/floatButton/tokens.d.ts

@@ -0,0 +1,3 @@
+import { TokenGenerator } from '../types/theme-utils';
+import { FloatButtonTokens } from '../types/component-tokens.types';
+export declare const getFloatButtonTokens: TokenGenerator<FloatButtonTokens>;

package/dist/types/index.d.ts

@@ -1,8 +1,11 @@
 export * from './button';
 export * from './checkbox';
 export * from './collapse';
+export * from './floatButton';
 export * from './input';
 export * from './menu';
+export * from './link';
+export * from './modal';
 export * from './numberInput';
 export * from './radio';
 export * from './skeleton';
@@ -12,9 +15,12 @@ export * from './select';
 export * from './table';
 export * from './switch';
 export * from './tag';
+export * from './transfer';
 export * from './upload';
+export * from './card';
+export * from './tooltip';
 export * from './theme';
-export * from './types/theme-utils';
+export type { ThemeContext, TokenGenerator, DeepPartial } from './types/theme-utils';
 export { DesignThemeProvider } from './DesignThemeProvider';
 export type { DesignThemeProviderProps } from './DesignThemeProvider';
 export { CustomThemeProvider, globalColors, globalSpacing, globalRadii, globalTypography, globalShadows, globalGradients, lightSemantic, darkSemantic, } from '@kingsoft-ai/theme';

package/dist/types/link/Link.d.ts

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+import { useLink } from 'react-aria';
+import { type LinkVariant, type LinkSize } from './Link.style';
+type UseLinkProps = Parameters<typeof useLink>[0];
+export type LinkProps = UseLinkProps & {
+    /** 链接变体：primary (主色), neutral (中性色) */
+    variant?: LinkVariant;
+    /** 链接尺寸：sm (12px), md (14px), lg (16px) */
+    size?: LinkSize;
+    /** 是否禁用（统一 API，优先级高于 isDisabled） */
+    disabled?: boolean;
+    /** 自定义类名 */
+    className?: string;
+    /** 子元素 */
+    children?: ReactNode;
+};
+/**
+ * Link 文字链接组件
+ *
+ * 用于页面内的跳转或操作，支持多种状态和尺寸。
+ * 基于 react-aria useLink 实现无障碍访问。
+ */
+export declare const Link: import("react").ForwardRefExoticComponent<import("react-aria").AriaLinkOptions & {
+    /** 链接变体：primary (主色), neutral (中性色) */
+    variant?: LinkVariant;
+    /** 链接尺寸：sm (12px), md (14px), lg (16px) */
+    size?: LinkSize;
+    /** 是否禁用（统一 API，优先级高于 isDisabled） */
+    disabled?: boolean;
+    /** 自定义类名 */
+    className?: string;
+    /** 子元素 */
+    children?: ReactNode;
+} & import("react").RefAttributes<HTMLAnchorElement>>;
+export {};

package/dist/types/link/Link.style.d.ts

@@ -0,0 +1,9 @@
+export type LinkVariant = 'primary' | 'neutral';
+export type LinkSize = 'sm' | 'md' | 'lg';
+export declare const LinkRoot: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    variant: LinkVariant;
+    size: LinkSize;
+}, import("react").DetailedHTMLProps<import("react").AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, {}>;

package/dist/types/link/index.d.ts

@@ -0,0 +1,3 @@
+export { Link } from './Link';
+export type { LinkProps } from './Link';
+export * from './Link.style';

package/dist/types/link/tokens.d.ts

@@ -0,0 +1,3 @@
+import { TokenGenerator } from '../types/theme-utils';
+import { LinkTokens } from '../types/component-tokens.types';
+export declare const getLinkTokens: TokenGenerator<LinkTokens>;

package/dist/types/menu/SubMenuPopover.d.ts

@@ -24,6 +24,6 @@ export interface SubMenuPopoverProps {
  * 在折叠状态下，鼠标悬浮一级菜单时展示二级菜单
  */
 export declare const SubMenuPopover: {
-    ({ visible, anchorRef, children, onClose, onMouseEnter, onMouseLeave, }: SubMenuPopoverProps): any;
+    ({ visible, anchorRef, children, onClose, onMouseEnter, onMouseLeave, }: SubMenuPopoverProps): import("react").ReactPortal | null;
     displayName: string;
 };

package/dist/types/modal/Modal.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Modal 弹窗组件（React Aria）
+ *
+ * - 受控：open + onOpenChange（所有关闭路径统一出口）
+ * - 基于 react-aria overlays/dialog：焦点管理、ESC、无障碍语义
+ * - 支持 portalContainer（微前端 / iframe / shadow dom）
+ * - 样式分层：overlay / dialog / close button 分别支持 className 与 style
+ */
+import { type CSSProperties, type ReactNode } from 'react';
+export type ModalProps = {
+    /** 是否展示 Modal */
+    open: boolean;
+    /**
+     * open 状态变更回调
+     * 所有关闭路径（ESC / 遮罩 / 关闭按钮 / outside）统一出口
+     */
+    onOpenChange: (open: boolean) => void;
+    /** 内容（完全自定义） */
+    children: ReactNode;
+    /** 标题（用于默认头部与 aria 标注） */
+    title?: ReactNode;
+    /**
+     * 是否隐藏默认头部（标题 + 右上角关闭按钮）
+     * - true：不渲染默认 Header，你可以在 children 内完全自定义标题区与关闭按钮
+     * - false：按默认逻辑渲染（有 title 或可关闭时显示 Header）
+     * @default false
+     */
+    hideHeader?: boolean;
+    /**
+     * 是否允许“用户主动关闭”
+     * - false：禁用 ESC/遮罩/close button/outside 关闭（只能由外部控制 open）
+     * - true：按各关闭开关控制
+     * @default true
+     */
+    isDismissable?: boolean;
+    /** 是否允许 ESC 关闭（在 isDismissable=true 前提下生效）@default true */
+    closeOnEsc?: boolean;
+    /** 是否允许点击遮罩关闭（在 isDismissable=true 前提下生效）@default true */
+    closeOnOverlay?: boolean;
+    /**
+     * 是否允许点击外部关闭（在 isDismissable=true 前提下生效）
+     * 对应 react-aria shouldCloseOnInteractOutside
+     * @default true
+     */
+    closeOnOutside?: boolean;
+    /**
+     * 外部点击白名单/黑名单
+     * 返回 true 表示允许触发关闭
+     */
+    shouldCloseOnInteractOutside?: (element: Element) => boolean;
+    /** Portal 挂载容器，默认 document.body（SSR 环境下不回退） */
+    portalContainer?: Element;
+    /** overlay（遮罩层）样式分层 */
+    overlayClassName?: string;
+    overlayStyle?: CSSProperties;
+    /** dialog（弹层容器）样式分层 */
+    dialogClassName?: string;
+    dialogStyle?: CSSProperties;
+    /** close button 样式分层 */
+    closeButtonClassName?: string;
+    closeButtonStyle?: CSSProperties;
+};
+export declare const Modal: import("react").ForwardRefExoticComponent<ModalProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/types/modal/Modal.style.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Modal 样式（React Aria）
+ *
+ * 设计目标：
+ * - 轻盈、科技、极简阴影（避免厚重“Antd 弹窗”观感）
+ * - overlay / dialog / close button 三层明确分工
+ */
+export declare const ModalPortalRoot: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const ModalBackdrop: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const ModalDialog: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+export declare const ModalDialogHeader: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLElement>, HTMLElement>, {}>;
+export declare const ModalDialogTitle: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>, {}>;
+export declare const ModalCloseButton: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, {}>;
+export declare const ModalDialogBody: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;

package/dist/types/modal/__tests__/Modal.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modal/index.d.ts

@@ -0,0 +1,2 @@
+export { Modal } from './Modal';
+export type { ModalProps } from './Modal';

package/dist/types/modal/tokens.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Modal 组件 Token
+ *
+ * 基于三层 Token 体系：
+ * - Tier 1 (Global): 全局基础值
+ * - Tier 2 (Semantic): 语义化映射
+ * - Tier 3 (Component): 组件专用 Token
+ */
+import { TokenGenerator } from '../types/theme-utils';
+import { ModalTokens } from '../types/component-tokens.types';
+export declare const getModalTokens: TokenGenerator<ModalTokens>;

package/dist/types/numberInput/NumberInput.d.ts

@@ -35,8 +35,16 @@ export type NumberInputProps = {
     controls?: 'buttons' | 'arrows';
     /** 大小：'md' | 'lg' */
     size?: 'md' | 'lg';
-    /** 值变化回调（返回 number | undefined） */
-    onValueChange?: (v: number | undefined) => void;
+    /**
+     * 值变化回调（统一 API，推荐使用）
+     * 等同于其他表单组件的 onChange，返回 number | undefined
+     */
+    onValueChange?: (value: number | undefined) => void;
+    /**
+     * 值变化回调别名（统一 API）
+     * 与 onValueChange 功能相同，提供与其他表单组件一致的 API 命名
+     */
+    onChangeValue?: (value: number | undefined) => void;
     /** 标签文本 */
     label?: ReactNode;
     /** 描述文本 */
@@ -51,7 +59,7 @@ export type NumberInputProps = {
     className?: string;
     /** 自定义 ID */
     id?: string;
-    /** 原生 onChange 保留以便外部使用 */
+    /** 原生 input onChange 事件（用于表单库等场景） */
     onChange?: (e: ChangeEvent<HTMLInputElement>) => void;
 };
 /** 数字输入框组件 */

package/dist/types/select/Select.d.ts

@@ -17,7 +17,7 @@ export interface SelectOptionType {
     /** 是否禁用该选项 */
     disabled?: boolean;
 }
-export interface SelectProps<T> extends Omit<AriaSelectProps<T>, 'errorMessage' | 'selectedKey' | 'defaultSelectedKey' | 'onSelectionChange' | 'selectionMode' | 'children' | 'isDisabled'> {
+export interface SelectProps<T> extends Omit<AriaSelectProps<T>, 'errorMessage' | 'selectedKey' | 'defaultSelectedKey' | 'onSelectionChange' | 'selectionMode' | 'children' | 'isDisabled' | 'value' | 'defaultValue' | 'onChange'> {
     /** 选择模式：single 单选 | multiple 多选 */
     selectionMode?: SelectionMode;
     /** 是否正在加载 */
@@ -40,15 +40,21 @@ export interface SelectProps<T> extends Omit<AriaSelectProps<T>, 'errorMessage'
     errorMessage?: React.ReactNode;
     /** 多选时最大展示的 Tag 数量 */
     maxTagCount?: number;
-    /** 单选时选中的 key */
+    /** 受控值（统一 API，单选时为 Key，多选时为 Iterable<Key>，优先级高于 selectedKey/selectedKeys） */
+    value?: React.Key | null | Iterable<React.Key>;
+    /** 默认值（统一 API，单选时为 Key，多选时为 Iterable<Key>，优先级高于 defaultSelectedKey/defaultSelectedKeys） */
+    defaultValue?: React.Key | Iterable<React.Key>;
+    /** 值变化回调（统一 API，优先级高于 onSelectionChange） */
+    onChange?: (value: SelectionType) => void;
+    /** 单选时选中的 key（兼容旧 API） */
     selectedKey?: React.Key | null;
-    /** 单选时默认选中的 key */
+    /** 单选时默认选中的 key（兼容旧 API） */
     defaultSelectedKey?: React.Key;
-    /** 多选时选中的 keys */
+    /** 多选时选中的 keys（兼容旧 API） */
     selectedKeys?: Iterable<React.Key>;
-    /** 多选时默认选中的 keys */
+    /** 多选时默认选中的 keys（兼容旧 API） */
     defaultSelectedKeys?: Iterable<React.Key>;
-    /** 选择变化回调（单选返回 key，多选返回 Set） */
+    /** 选择变化回调（兼容旧 API，单选返回 key，多选返回 Set） */
     onSelectionChange?: (keys: SelectionType) => void;
     /**
      * 选项数据（推荐使用）

package/dist/types/switch/Switch.d.ts

@@ -41,6 +41,10 @@ export type SwitchProps = Omit<AriaSwitchProps, 'children' | 'isDisabled'> & Omi
     uncheckedLabel?: string;
     /** 是否禁用（替代 isDisabled） */
     disabled?: boolean;
+    /** 受控值（统一 API，优先级高于 isSelected） */
+    value?: boolean;
+    /** 默认值（统一 API，优先级高于 defaultSelected） */
+    defaultValue?: boolean;
     /** 外部描述性标签（显示在开关旁边） */
     children?: ReactNode;
     /** 自定义类名 */
@@ -61,6 +65,10 @@ export declare const Switch: import("react").ForwardRefExoticComponent<Omit<Aria
     uncheckedLabel?: string;
     /** 是否禁用（替代 isDisabled） */
     disabled?: boolean;
+    /** 受控值（统一 API，优先级高于 isSelected） */
+    value?: boolean;
+    /** 默认值（统一 API，优先级高于 defaultSelected） */
+    defaultValue?: boolean;
     /** 外部描述性标签（显示在开关旁边） */
     children?: ReactNode;
     /** 自定义类名 */

package/dist/types/theme.d.ts

@@ -1,5 +1,6 @@
-import { AppTheme, ComponentTokens, SemanticColors, SemanticSpacing, SemanticBorderRadius, SemanticTypography, SemanticShadows } from '@kingsoft-ai/theme';
+import { AppTheme, SemanticColors, SemanticSpacing, SemanticBorderRadius, SemanticTypography, SemanticShadows } from '@kingsoft-ai/theme';
 import { ThemeContext } from './types/theme-utils';
+import { ComponentTokens } from './types/component-tokens.types';
 export declare const createComponentTokens: (context: ThemeContext) => ComponentTokens;
 interface SemanticTheme {
     colors: SemanticColors;