@kingsoft-ai/design 0.1.11 → 0.1.12

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/index.d.ts

@@ -3,6 +3,8 @@ export * from './checkbox';
 export * from './collapse';
 export * from './input';
 export * from './menu';
+export * from './link';
+export * from './modal';
 export * from './numberInput';
 export * from './radio';
 export * from './skeleton';

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/modal/Modal.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Modal 弹窗组件
+ *
+ * 基于 React Portal 实现的高性能弹窗组件
+ * 支持无障碍访问、键盘操作、焦点管理
+ *
+ * @example
+ * ```tsx
+ * <Modal
+ *   open={isOpen}
+ *   onClose={() => setIsOpen(false)}
+ *   title="确认操作"
+ *   size="md"
+ * >
+ *   <p>确定要执行此操作吗？</p>
+ * </Modal>
+ * ```
+ */
+import { type ReactNode } from 'react';
+import { ModalHeader, ModalTitle, ModalDescription, ModalCloseButton, ModalContent, ModalFooter, type ModalSize } from './Modal.style';
+export declare const SIZES: readonly ["sm", "md", "lg", "xl", "fullscreen"];
+export interface ModalProps {
+    /** 是否打开弹窗 */
+    open: boolean;
+    /** 关闭弹窗回调 */
+    onClose: () => void;
+    /** 弹窗标题 */
+    title?: ReactNode;
+    /** 弹窗描述/副标题 */
+    description?: ReactNode;
+    /** 弹窗内容 */
+    children?: ReactNode;
+    /** 底部操作区域 */
+    footer?: ReactNode;
+    /** 弹窗尺寸 */
+    size?: ModalSize;
+    /** 是否全屏 */
+    fullscreen?: boolean;
+    /** 是否垂直居中 */
+    centered?: boolean;
+    /** 是否显示关闭按钮 */
+    closable?: boolean;
+    /** 点击遮罩是否关闭 */
+    maskClosable?: boolean;
+    /** 按 ESC 是否关闭 */
+    keyboard?: boolean;
+    /** 是否显示遮罩 */
+    mask?: boolean;
+    /** 关闭后是否销毁子元素 */
+    destroyOnClose?: boolean;
+    /** 动画类型 */
+    animationType?: 'scale' | 'slide' | 'fade';
+    /** 挂载的 DOM 节点（默认为 document.body） */
+    container?: HTMLElement | null;
+    /** 自定义类名 */
+    className?: string;
+    /** 内容区域自定义类名 */
+    contentClassName?: string;
+    /** 自定义 z-index */
+    zIndex?: number;
+    /** 动画结束后的回调 */
+    afterClose?: () => void;
+    /** 动画开始前的回调 */
+    afterOpen?: () => void;
+    /** 自定义关闭图标 */
+    closeIcon?: ReactNode;
+    /** 无障碍：描述 ID */
+    'aria-describedby'?: string;
+    /** 无障碍：标签 ID */
+    'aria-labelledby'?: string;
+}
+/**
+ * Modal 弹窗组件
+ *
+ * 高性能、无障碍、可定制的弹窗组件
+ */
+export declare const Modal: import("react").ForwardRefExoticComponent<ModalProps & import("react").RefAttributes<HTMLDivElement>>;
+export { ModalHeader, ModalContent, ModalFooter, ModalTitle, ModalDescription, ModalCloseButton, };

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

@@ -0,0 +1,121 @@
+/**
+ * Modal 弹窗样式
+ *
+ * 基于三层 Token 体系：
+ * - Tier 1 (Global): 全局基础值
+ * - Tier 2 (Semantic): 语义化映射
+ * - Tier 3 (Component): 组件专用 Token
+ *
+ * 特性：
+ * - 优雅的入场/退场动画
+ * - 响应式尺寸支持
+ * - 无障碍访问友好
+ * - 支持暗色主题
+ */
+export declare const modalSizes: readonly ["sm", "md", "lg", "xl", "fullscreen"];
+export type ModalSize = (typeof modalSizes)[number];
+/**
+ * Modal 遮罩层
+ *
+ * 特性：
+ * - 毛玻璃效果
+ * - 点击关闭支持
+ * - 优雅的淡入淡出动画
+ */
+export declare const ModalOverlay: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    isOpen: boolean;
+    isClosing: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * Modal 容器（用于 Portal 和定位）
+ */
+export declare const ModalPortalContainer: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    isOpen: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * Modal 主容器
+ *
+ * 特性：
+ * - 居中定位
+ * - 响应式宽度
+ * - 弹性动画效果
+ */
+export declare const ModalContainer: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    size: ModalSize;
+    isOpen: boolean;
+    isClosing: boolean;
+    isFullscreen: boolean;
+    animationType: "scale" | "slide" | "fade";
+    centered: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * Modal 头部
+ *
+ * 包含标题、描述和关闭按钮
+ */
+export declare const ModalHeader: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    size: ModalSize;
+    hasDescription: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLElement>, HTMLElement>, {}>;
+/**
+ * 标题容器
+ */
+export declare const ModalTitleWrapper: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * Modal 标题
+ */
+export declare const ModalTitle: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    size: ModalSize;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLHeadingElement>, HTMLHeadingElement>, {}>;
+/**
+ * Modal 描述
+ */
+export declare const ModalDescription: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>, {}>;
+/**
+ * Modal 关闭按钮
+ */
+export declare const ModalCloseButton: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+}, import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, {}>;
+/**
+ * Modal 内容区域
+ */
+export declare const ModalContent: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    size: ModalSize;
+    hasHeader: boolean;
+    hasFooter: boolean;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, {}>;
+/**
+ * Modal 底部
+ */
+export declare const ModalFooter: import("@emotion/styled").StyledComponent<{
+    theme?: import("@emotion/react").Theme;
+    as?: React.ElementType;
+} & {
+    size: ModalSize;
+}, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLElement>, HTMLElement>, {}>;

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

@@ -0,0 +1,4 @@
+export { Modal, SIZES } from './Modal';
+export type { ModalProps } from './Modal';
+export type { ModalSize } from './Modal.style';
+export { ModalHeader, ModalContent, ModalFooter, ModalTitle, ModalDescription, ModalCloseButton, } 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;

package/dist/types/types/component-tokens.types.d.ts

@@ -747,6 +747,145 @@ export interface SelectTokens {
         };
     };
 }
+export interface LinkTokens {
+    variant: {
+        primary: LinkStateTokens;
+        neutral: LinkStateTokens;
+    };
+    size: {
+        sm: {
+            fontSize: string;
+        };
+        md: {
+            fontSize: string;
+        };
+        lg: {
+            fontSize: string;
+        };
+    };
+    transition: string;
+    borderRadius: string;
+    focusRing: {
+        color: string;
+        offset: string;
+    };
+}
+interface LinkStateTokens {
+    text: {
+        default: string;
+        hover: string;
+        active: string;
+        disabled: string;
+    };
+    decoration: {
+        default: string;
+        hover: string;
+    };
+}
+export interface ModalTokens {
+    size: {
+        sm: {
+            width: string;
+            maxWidth: string;
+            padding: string;
+            headerPadding: string;
+            footerPadding: string;
+            titleFontSize: string;
+        };
+        md: {
+            width: string;
+            maxWidth: string;
+            padding: string;
+            headerPadding: string;
+            footerPadding: string;
+            titleFontSize: string;
+        };
+        lg: {
+            width: string;
+            maxWidth: string;
+            padding: string;
+            headerPadding: string;
+            footerPadding: string;
+            titleFontSize: string;
+        };
+        xl: {
+            width: string;
+            maxWidth: string;
+            padding: string;
+            headerPadding: string;
+            footerPadding: string;
+            titleFontSize: string;
+        };
+        fullscreen: {
+            width: string;
+            maxWidth: string;
+            padding: string;
+            headerPadding: string;
+            footerPadding: string;
+            titleFontSize: string;
+        };
+    };
+    overlay: {
+        background: string;
+        backdropFilter: string;
+    };
+    container: {
+        background: string;
+        borderRadius: string;
+        boxShadow: string;
+        border: string;
+        maxHeight: string;
+    };
+    header: {
+        background: string;
+        borderBottom: string;
+        minHeight: string;
+        gap: string;
+    };
+    title: {
+        color: string;
+        fontWeight: number;
+        lineHeight: string;
+    };
+    description: {
+        color: string;
+        fontSize: string;
+        lineHeight: string;
+        marginTop: string;
+    };
+    closeButton: {
+        size: string;
+        iconSize: string;
+        color: string;
+        hoverColor: string;
+        hoverBackground: string;
+        borderRadius: string;
+    };
+    content: {
+        color: string;
+        fontSize: string;
+        lineHeight: string;
+        maxHeight: string;
+    };
+    footer: {
+        background: string;
+        borderTop: string;
+        minHeight: string;
+        gap: string;
+        justifyContent: string;
+    };
+    animation: {
+        duration: string;
+        easing: string;
+        scaleFrom: string;
+        scaleTo: string;
+    };
+    zIndex: {
+        overlay: number;
+        container: number;
+    };
+    transition: string;
+}
 export interface ComponentTokens {
     button: ButtonTokens;
     iconButton: IconButtonTokens;
@@ -761,5 +900,7 @@ export interface ComponentTokens {
     stepper: StepperTokens;
     numberfield: NumberFieldTokens;
     menu: MenuTokens;
+    link: LinkTokens;
+    modal: ModalTokens;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kingsoft-ai/design",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "type": "module",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -24,8 +24,8 @@
     "@react-stately/list": "^3.13.1",
     "@react-stately/select": "^3.8.0",
     "@react-types/shared": "^3.32.1",
-    "@kingsoft-ai/icons": "^0.1.4",
-    "@kingsoft-ai/theme": "^0.1.5"
+    "@kingsoft-ai/theme": "^0.1.5",
+    "@kingsoft-ai/icons": "^0.1.4"
   },
   "peerDependencies": {
     "@emotion/react": ">=11",