@vavt/react-ui 1.0.0

package/dist/types/Announcement/type.d.cts

@@ -0,0 +1,63 @@
+/** 公告条对外类型；内容 key 是跨受控更新、动画和自动播放的唯一身份。 */
+import type { AnchorHTMLAttributes, HTMLAttributes, MouseEvent, ReactNode } from 'react';
+import type { DecorativeIcon } from '../_shared/icon.cjs';
+/** 公告条目的唯一标识类型 */
+export type AnnouncementKey = string | number;
+/** 公告条的轻量语义状态类型 */
+export type AnnouncementStatus = 'info' | 'success' | 'warning' | 'error';
+/**
+ * 单条公告条目定义
+ */
+export interface AnnouncementItem {
+    /** 在受控状态与数据更新之间保持稳定的唯一标识 */
+    key: AnnouncementKey;
+    /** 公告内容文本或 React 节点 */
+    content: ReactNode;
+    /** 目标跳转链接，传入时将渲染为链接元素 */
+    href?: string;
+    /** 链接打开方式，同原生 `<a>` 标签的 `target` 属性 */
+    target?: AnchorHTMLAttributes<HTMLAnchorElement>['target'];
+    /** 链接安全关系属性，同原生 `<a>` 标签的 `rel` 属性 */
+    rel?: string;
+}
+/**
+ * Announcement 组件属性接口
+ */
+export interface AnnouncementProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    /** 公告条目数据列表 */
+    items: AnnouncementItem[];
+    /** 受控模式：当前激活展示的公告项 key */
+    activeKey?: AnnouncementKey;
+    /** 非受控模式：初始激活展示的公告项 key */
+    defaultActiveKey?: AnnouncementKey;
+    /** 受控模式：公告条是否处于打开显示状态 */
+    open?: boolean;
+    /** 非受控模式：公告条初始是否打开，默认为 true */
+    defaultOpen?: boolean;
+    /** 是否开启多条轮播自动播放，默认为 true */
+    autoPlay?: boolean;
+    /** 轮播切换时间间隔（毫秒），默认为 3000 */
+    interval?: number;
+    /** 鼠标悬停在公告上时是否暂停轮播，默认为 true */
+    pauseOnHover?: boolean;
+    /** 焦点进入公告内部元素时是否暂停轮播，默认为 true */
+    pauseOnFocus?: boolean;
+    /** 轻量语义提示，仅影响顶部标识线与图标，不代表 Alert 阻断状态 */
+    status?: AnnouncementStatus;
+    /** 兼容扩展：传入 null 可隐藏默认公告图标 */
+    icon?: DecorativeIcon | null;
+    /** 是否显示关闭按钮，默认为 false */
+    closable?: boolean;
+    /** 自定义条目内容渲染函数 */
+    renderItem?: (item: AnnouncementItem, index: number) => ReactNode;
+    /** 激活展示的条目发生切换时的回调函数 */
+    onActiveChange?: (key: AnnouncementKey, item: AnnouncementItem, index: number) => void;
+    /** 公告开启/关闭状态变化时的回调函数 */
+    onOpenChange?: (open: boolean) => void;
+    /** 点击关闭按钮时的回调函数 */
+    onClose?: () => void;
+    /** 点击条目区域时的回调函数 */
+    onItemClick?: (item: AnnouncementItem, index: number, event: MouseEvent<HTMLAnchorElement | HTMLButtonElement>) => void;
+}
+/** Announcement 根 DOM 元素类型 */
+export type AnnouncementRef = HTMLDivElement;

package/dist/types/Announcement/type.d.ts

@@ -0,0 +1,63 @@
+/** 公告条对外类型；内容 key 是跨受控更新、动画和自动播放的唯一身份。 */
+import type { AnchorHTMLAttributes, HTMLAttributes, MouseEvent, ReactNode } from 'react';
+import type { DecorativeIcon } from '../_shared/icon.js';
+/** 公告条目的唯一标识类型 */
+export type AnnouncementKey = string | number;
+/** 公告条的轻量语义状态类型 */
+export type AnnouncementStatus = 'info' | 'success' | 'warning' | 'error';
+/**
+ * 单条公告条目定义
+ */
+export interface AnnouncementItem {
+    /** 在受控状态与数据更新之间保持稳定的唯一标识 */
+    key: AnnouncementKey;
+    /** 公告内容文本或 React 节点 */
+    content: ReactNode;
+    /** 目标跳转链接，传入时将渲染为链接元素 */
+    href?: string;
+    /** 链接打开方式，同原生 `<a>` 标签的 `target` 属性 */
+    target?: AnchorHTMLAttributes<HTMLAnchorElement>['target'];
+    /** 链接安全关系属性，同原生 `<a>` 标签的 `rel` 属性 */
+    rel?: string;
+}
+/**
+ * Announcement 组件属性接口
+ */
+export interface AnnouncementProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    /** 公告条目数据列表 */
+    items: AnnouncementItem[];
+    /** 受控模式：当前激活展示的公告项 key */
+    activeKey?: AnnouncementKey;
+    /** 非受控模式：初始激活展示的公告项 key */
+    defaultActiveKey?: AnnouncementKey;
+    /** 受控模式：公告条是否处于打开显示状态 */
+    open?: boolean;
+    /** 非受控模式：公告条初始是否打开，默认为 true */
+    defaultOpen?: boolean;
+    /** 是否开启多条轮播自动播放，默认为 true */
+    autoPlay?: boolean;
+    /** 轮播切换时间间隔（毫秒），默认为 3000 */
+    interval?: number;
+    /** 鼠标悬停在公告上时是否暂停轮播，默认为 true */
+    pauseOnHover?: boolean;
+    /** 焦点进入公告内部元素时是否暂停轮播，默认为 true */
+    pauseOnFocus?: boolean;
+    /** 轻量语义提示，仅影响顶部标识线与图标，不代表 Alert 阻断状态 */
+    status?: AnnouncementStatus;
+    /** 兼容扩展：传入 null 可隐藏默认公告图标 */
+    icon?: DecorativeIcon | null;
+    /** 是否显示关闭按钮，默认为 false */
+    closable?: boolean;
+    /** 自定义条目内容渲染函数 */
+    renderItem?: (item: AnnouncementItem, index: number) => ReactNode;
+    /** 激活展示的条目发生切换时的回调函数 */
+    onActiveChange?: (key: AnnouncementKey, item: AnnouncementItem, index: number) => void;
+    /** 公告开启/关闭状态变化时的回调函数 */
+    onOpenChange?: (open: boolean) => void;
+    /** 点击关闭按钮时的回调函数 */
+    onClose?: () => void;
+    /** 点击条目区域时的回调函数 */
+    onItemClick?: (item: AnnouncementItem, index: number, event: MouseEvent<HTMLAnchorElement | HTMLButtonElement>) => void;
+}
+/** Announcement 根 DOM 元素类型 */
+export type AnnouncementRef = HTMLDivElement;

package/dist/types/Button/Button.d.cts

@@ -0,0 +1,23 @@
+import type { ButtonProps } from './type.cjs';
+/**
+ * Button 只负责把公开属性转换成稳定的原生 `<button>` 语义；颜色、边框、
+ * 交互态和主题差异全部交给同名的 SCSS Token 处理。这样组件层不需要知道
+ * Light / Dark 的具体色值，也不会因为新增语义状态而复制一套渲染分支。
+ *
+ * 这里有四个容易被后续修改破坏的约束：
+ * 1. Group 只提供 size/status/variant 默认值，子 Button 显式属性优先；
+ *    disabled/loading 始终由当前按钮独立管理，不能被容器隐式改写。
+ * 2. `loading` 的优先级高于业务 `icon` 和点击能力。加载时先选自定义
+ *    `loadingIcon`，否则使用默认 spinner；两者都会替换业务图标，并通过
+ *    原生 `disabled` 与 `aria-busy` 同时阻断交互、告知辅助技术当前状态。
+ *    外部传入的 `aria-busy` 只在非加载态透传。
+ * 3. `iconPosition` 只改变视觉节点的排列，不改变按钮的可访问名称。纯图标
+ *    按钮仍由调用方提供 `aria-label`，而文案始终包在 label 容器中，避免
+ *    图标、加载动画和文本在不同组合下改变布局或语义顺序。
+ * 4. 中文双字间距只增加表现类名，不拆分或改写文本节点；否则视觉优化会
+ *    意外改变复制结果、测试查询和读屏器获得的按钮名称。
+ * 5. 波纹只作为 aria-hidden 的瞬时装饰层；指针事件从实际落点扩散，键盘、
+ *    辅助技术和程序化 click 则从中心扩散，不能改变原生事件与表单语义。
+ */
+declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+export default Button;

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

@@ -0,0 +1,23 @@
+import type { ButtonProps } from './type.js';
+/**
+ * Button 只负责把公开属性转换成稳定的原生 `<button>` 语义；颜色、边框、
+ * 交互态和主题差异全部交给同名的 SCSS Token 处理。这样组件层不需要知道
+ * Light / Dark 的具体色值，也不会因为新增语义状态而复制一套渲染分支。
+ *
+ * 这里有四个容易被后续修改破坏的约束：
+ * 1. Group 只提供 size/status/variant 默认值，子 Button 显式属性优先；
+ *    disabled/loading 始终由当前按钮独立管理，不能被容器隐式改写。
+ * 2. `loading` 的优先级高于业务 `icon` 和点击能力。加载时先选自定义
+ *    `loadingIcon`，否则使用默认 spinner；两者都会替换业务图标，并通过
+ *    原生 `disabled` 与 `aria-busy` 同时阻断交互、告知辅助技术当前状态。
+ *    外部传入的 `aria-busy` 只在非加载态透传。
+ * 3. `iconPosition` 只改变视觉节点的排列，不改变按钮的可访问名称。纯图标
+ *    按钮仍由调用方提供 `aria-label`，而文案始终包在 label 容器中，避免
+ *    图标、加载动画和文本在不同组合下改变布局或语义顺序。
+ * 4. 中文双字间距只增加表现类名，不拆分或改写文本节点；否则视觉优化会
+ *    意外改变复制结果、测试查询和读屏器获得的按钮名称。
+ * 5. 波纹只作为 aria-hidden 的瞬时装饰层；指针事件从实际落点扩散，键盘、
+ *    辅助技术和程序化 click 则从中心扩散，不能改变原生事件与表单语义。
+ */
+declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+export default Button;

package/dist/types/Button/ButtonGroup.d.cts

@@ -0,0 +1,14 @@
+import type { ButtonGroupProps } from './type.cjs';
+/**
+ * ButtonGroup 负责建立组合按钮的语义边界和几何上下文。
+ *
+ * 它不会克隆或重排 children：Button 自己读取 Context 并解析最终属性，
+ * 因而显式写在子按钮上的 size/status/variant 永远覆盖 Group 默认值。disabled
+ * 与 loading 则始终属于单个按钮，避免容器声明“整组禁用”时又允许子项覆盖，
+ * 造成视觉、原生 disabled 和 aria-disabled 三套状态互相矛盾。
+ *
+ * direction 只影响容器布局，不需要进入 Context。视觉上的相邻圆角和边框
+ * 收敛全部交给 Button.scss，组件层只提供稳定的方向类和原生 group 语义。
+ */
+declare const ButtonGroup: import("react").ForwardRefExoticComponent<ButtonGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export default ButtonGroup;

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

@@ -0,0 +1,14 @@
+import type { ButtonGroupProps } from './type.js';
+/**
+ * ButtonGroup 负责建立组合按钮的语义边界和几何上下文。
+ *
+ * 它不会克隆或重排 children：Button 自己读取 Context 并解析最终属性，
+ * 因而显式写在子按钮上的 size/status/variant 永远覆盖 Group 默认值。disabled
+ * 与 loading 则始终属于单个按钮，避免容器声明“整组禁用”时又允许子项覆盖，
+ * 造成视觉、原生 disabled 和 aria-disabled 三套状态互相矛盾。
+ *
+ * direction 只影响容器布局，不需要进入 Context。视觉上的相邻圆角和边框
+ * 收敛全部交给 Button.scss，组件层只提供稳定的方向类和原生 group 语义。
+ */
+declare const ButtonGroup: import("react").ForwardRefExoticComponent<ButtonGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export default ButtonGroup;

package/dist/types/Button/context.d.cts

@@ -0,0 +1,15 @@
+import type { ButtonSize, ButtonStatus, ButtonVariant } from './type.cjs';
+/**
+ * ButtonGroup 只保存“默认值”，不保存子按钮实例，也不克隆 children。
+ *
+ * 这种边界让 Button 仍然是普通的原生 button：子组件的 ref、事件、key 和
+ * aria 属性都由 React 原样处理。后续如果扩展 Group API，也应优先增加这里的
+ * 默认语义，而不是通过遍历 children 改写调用方已经显式传入的属性。
+ */
+export interface ButtonGroupContextValue {
+    size?: ButtonSize;
+    status?: ButtonStatus;
+    variant?: ButtonVariant;
+}
+export declare const ButtonGroupProvider: import("react").Provider<ButtonGroupContextValue | null>;
+export declare const useButtonGroupContext: () => ButtonGroupContextValue | null;

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

@@ -0,0 +1,15 @@
+import type { ButtonSize, ButtonStatus, ButtonVariant } from './type.js';
+/**
+ * ButtonGroup 只保存“默认值”，不保存子按钮实例，也不克隆 children。
+ *
+ * 这种边界让 Button 仍然是普通的原生 button：子组件的 ref、事件、key 和
+ * aria 属性都由 React 原样处理。后续如果扩展 Group API，也应优先增加这里的
+ * 默认语义，而不是通过遍历 children 改写调用方已经显式传入的属性。
+ */
+export interface ButtonGroupContextValue {
+    size?: ButtonSize;
+    status?: ButtonStatus;
+    variant?: ButtonVariant;
+}
+export declare const ButtonGroupProvider: import("react").Provider<ButtonGroupContextValue | null>;
+export declare const useButtonGroupContext: () => ButtonGroupContextValue | null;

package/dist/types/Button/index.d.cts

@@ -0,0 +1,7 @@
+import Button from './Button.cjs';
+/** Button 按钮组件 */
+export declare const VlButton: import("react").ForwardRefExoticComponent<import("./type.cjs").ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+/** ButtonGroup 按钮组组件 */
+export declare const VlButtonGroup: import("react").ForwardRefExoticComponent<import("./type.cjs").ButtonGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export type { ButtonProps, ButtonStatus, ButtonSize, ButtonShape, ButtonVariant, ButtonIcon, ButtonIconPosition, ButtonRef, ButtonGroupProps, ButtonGroupDirection, ButtonGroupRef } from './type.cjs';
+export default Button;

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

@@ -0,0 +1,7 @@
+import Button from './Button.js';
+/** Button 按钮组件 */
+export declare const VlButton: import("react").ForwardRefExoticComponent<import("./type.js").ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+/** ButtonGroup 按钮组组件 */
+export declare const VlButtonGroup: import("react").ForwardRefExoticComponent<import("./type.js").ButtonGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export type { ButtonProps, ButtonStatus, ButtonSize, ButtonShape, ButtonVariant, ButtonIcon, ButtonIconPosition, ButtonRef, ButtonGroupProps, ButtonGroupDirection, ButtonGroupRef } from './type.js';
+export default Button;

package/dist/types/Button/type.d.cts

@@ -0,0 +1,66 @@
+import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from 'react';
+import type { ComponentIcon } from '../_shared/icon.cjs';
+export type ButtonStatus = 'default' | 'primary' | 'success' | 'info' | 'warning' | 'error';
+export type ButtonSize = 'sm' | 'md' | 'lg';
+export type ButtonShape = 'rectangle' | 'square' | 'round' | 'circle';
+export type ButtonVariant = 'outline' | 'solid' | 'dashed' | 'text';
+export type ButtonIconPosition = 'start' | 'end';
+export type ButtonGroupDirection = 'horizontal' | 'vertical';
+export type ButtonRef = HTMLButtonElement;
+export type ButtonGroupRef = HTMLDivElement;
+export type ButtonIcon = ComponentIcon;
+/**
+ * Button 的公共属性保持“语义、视觉层级、几何、交互状态”彼此正交。
+ *
+ * status 只表达操作语义，variant 决定强调程度，shape/size 决定几何；组件不会
+ * 根据 Light / Dark 在 React 层计算颜色。所有主题差异都由同名 Button Token
+ * 处理，因此自定义主题可以替换色板而不改变 JSX 或状态分支。
+ */
+export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type'> {
+    /** 语义状态；`default` 与不传值都使用中性按钮 Token。 */
+    status?: ButtonStatus;
+    /** 控件高度与横向内边距档位，默认 `md`。 */
+    size?: ButtonSize;
+    /** 按钮外形，默认 `round`；square/circle 会锁定等宽高。 */
+    shape?: ButtonShape;
+    /** 视觉强调层级，默认 `outline`；dashed 只改变描边线型。 */
+    variant?: ButtonVariant;
+    /** 原生禁用状态；与 loading 一样会阻断点击，但不会显示加载语义。 */
+    disabled?: boolean;
+    /**
+     * 加载态会优先替换业务 icon，强制根 button disabled，并设置
+     * `aria-busy="true"`。组件不会同时展示加载符号和业务图标。
+     */
+    loading?: boolean;
+    /** 加载时替换 children 的文案；显式空字符串也会被保留。 */
+    loadingText?: ReactNode;
+    /** 加载态的装饰图标；传入后优先于默认 spinner，业务 icon 仍会被隐藏。 */
+    loadingIcon?: ButtonIcon;
+    /** 占满父容器可用宽度；square/circle 仍保持固定等宽高。 */
+    block?: boolean;
+    /** 仅在内容是恰好两个中文表意文字时，通过 CSS 增加字间距，不修改可访问名称。 */
+    autoInsertSpace?: boolean;
+    /** 映射到原生 button 的 type，默认 `button`，避免在表单中意外提交。 */
+    nativeType?: 'button' | 'submit' | 'reset';
+    /** 业务装饰图标；加载态会暂时隐藏。纯图标按钮仍需提供 aria-label。 */
+    icon?: ButtonIcon;
+    /** 业务图标或加载符号位于文案前后的位置，默认 `start`。 */
+    iconPosition?: ButtonIconPosition;
+}
+/**
+ * ButtonGroup 只向后代 Button 提供 size/status/variant 默认值。
+ *
+ * 子 Button 显式属性优先；Group 不克隆 children，也不统一接管 disabled/loading，
+ * 从而保留每个原生 button 独立的 ref、事件、可访问状态和表单行为。
+ */
+export interface ButtonGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'role'> {
+    /** 组内 Button 的默认尺寸；子 Button 显式传入 size 时优先。 */
+    size?: ButtonSize;
+    /** 组内 Button 的默认语义状态；子 Button 显式传入 status 时优先。 */
+    status?: ButtonStatus;
+    /** 组内 Button 的默认视觉层级；子 Button 显式传入 variant 时优先。 */
+    variant?: ButtonVariant;
+    /** 组合方向；相邻按钮的圆角和边框会按方向收敛。 */
+    direction?: ButtonGroupDirection;
+    children?: ReactNode;
+}

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

@@ -0,0 +1,66 @@
+import type { ButtonHTMLAttributes, HTMLAttributes, ReactNode } from 'react';
+import type { ComponentIcon } from '../_shared/icon.js';
+export type ButtonStatus = 'default' | 'primary' | 'success' | 'info' | 'warning' | 'error';
+export type ButtonSize = 'sm' | 'md' | 'lg';
+export type ButtonShape = 'rectangle' | 'square' | 'round' | 'circle';
+export type ButtonVariant = 'outline' | 'solid' | 'dashed' | 'text';
+export type ButtonIconPosition = 'start' | 'end';
+export type ButtonGroupDirection = 'horizontal' | 'vertical';
+export type ButtonRef = HTMLButtonElement;
+export type ButtonGroupRef = HTMLDivElement;
+export type ButtonIcon = ComponentIcon;
+/**
+ * Button 的公共属性保持“语义、视觉层级、几何、交互状态”彼此正交。
+ *
+ * status 只表达操作语义，variant 决定强调程度，shape/size 决定几何；组件不会
+ * 根据 Light / Dark 在 React 层计算颜色。所有主题差异都由同名 Button Token
+ * 处理，因此自定义主题可以替换色板而不改变 JSX 或状态分支。
+ */
+export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type'> {
+    /** 语义状态；`default` 与不传值都使用中性按钮 Token。 */
+    status?: ButtonStatus;
+    /** 控件高度与横向内边距档位，默认 `md`。 */
+    size?: ButtonSize;
+    /** 按钮外形，默认 `round`；square/circle 会锁定等宽高。 */
+    shape?: ButtonShape;
+    /** 视觉强调层级，默认 `outline`；dashed 只改变描边线型。 */
+    variant?: ButtonVariant;
+    /** 原生禁用状态；与 loading 一样会阻断点击，但不会显示加载语义。 */
+    disabled?: boolean;
+    /**
+     * 加载态会优先替换业务 icon，强制根 button disabled，并设置
+     * `aria-busy="true"`。组件不会同时展示加载符号和业务图标。
+     */
+    loading?: boolean;
+    /** 加载时替换 children 的文案；显式空字符串也会被保留。 */
+    loadingText?: ReactNode;
+    /** 加载态的装饰图标；传入后优先于默认 spinner，业务 icon 仍会被隐藏。 */
+    loadingIcon?: ButtonIcon;
+    /** 占满父容器可用宽度；square/circle 仍保持固定等宽高。 */
+    block?: boolean;
+    /** 仅在内容是恰好两个中文表意文字时，通过 CSS 增加字间距，不修改可访问名称。 */
+    autoInsertSpace?: boolean;
+    /** 映射到原生 button 的 type，默认 `button`，避免在表单中意外提交。 */
+    nativeType?: 'button' | 'submit' | 'reset';
+    /** 业务装饰图标；加载态会暂时隐藏。纯图标按钮仍需提供 aria-label。 */
+    icon?: ButtonIcon;
+    /** 业务图标或加载符号位于文案前后的位置，默认 `start`。 */
+    iconPosition?: ButtonIconPosition;
+}
+/**
+ * ButtonGroup 只向后代 Button 提供 size/status/variant 默认值。
+ *
+ * 子 Button 显式属性优先；Group 不克隆 children，也不统一接管 disabled/loading，
+ * 从而保留每个原生 button 独立的 ref、事件、可访问状态和表单行为。
+ */
+export interface ButtonGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'role'> {
+    /** 组内 Button 的默认尺寸；子 Button 显式传入 size 时优先。 */
+    size?: ButtonSize;
+    /** 组内 Button 的默认语义状态；子 Button 显式传入 status 时优先。 */
+    status?: ButtonStatus;
+    /** 组内 Button 的默认视觉层级；子 Button 显式传入 variant 时优先。 */
+    variant?: ButtonVariant;
+    /** 组合方向；相邻按钮的圆角和边框会按方向收敛。 */
+    direction?: ButtonGroupDirection;
+    children?: ReactNode;
+}

package/dist/types/Card/Card.d.cts

@@ -0,0 +1,15 @@
+/**
+ * Card 卡片容器组件。
+ *
+ * 作为通用的信息聚合容器，支持封面、标题扩展区和底部操作区；视觉变体通过
+ * 明确的 modifier 属性开启，默认仍然是无交互反馈的静态 Surface。
+ */
+import { type ComponentRef, type ElementType, type ReactElement, type RefAttributes } from 'react';
+import type { CardProps } from './type.cjs';
+/**
+ * forwardRef 本身无法推断多态泛型，这个公开签名把 `tag` 与对应的 ref 类型重新关联起来。
+ * 实现内部仍以 HTMLElement 作为共同约束，和 CardRef 的公共契约保持一致。
+ */
+type CardComponent = <T extends ElementType = 'div'>(props: CardProps<T> & RefAttributes<ComponentRef<T>>) => ReactElement | null;
+declare const _default: CardComponent;
+export default _default;

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

@@ -0,0 +1,15 @@
+/**
+ * Card 卡片容器组件。
+ *
+ * 作为通用的信息聚合容器，支持封面、标题扩展区和底部操作区；视觉变体通过
+ * 明确的 modifier 属性开启，默认仍然是无交互反馈的静态 Surface。
+ */
+import { type ComponentRef, type ElementType, type ReactElement, type RefAttributes } from 'react';
+import type { CardProps } from './type.js';
+/**
+ * forwardRef 本身无法推断多态泛型，这个公开签名把 `tag` 与对应的 ref 类型重新关联起来。
+ * 实现内部仍以 HTMLElement 作为共同约束，和 CardRef 的公共契约保持一致。
+ */
+type CardComponent = <T extends ElementType = 'div'>(props: CardProps<T> & RefAttributes<ComponentRef<T>>) => ReactElement | null;
+declare const _default: CardComponent;
+export default _default;

package/dist/types/Card/index.d.cts

@@ -0,0 +1,5 @@
+import Card from './Card.cjs';
+/** Card 卡片组件 */
+export declare const VlCard: <T extends import("react").ElementType = "div">(props: import("./type.cjs").CardProps<T> & import("react").RefAttributes<import("react").ComponentRef<T>>) => import("react").ReactElement | null;
+export type { CardProps, CardRef, CardShadow, CardSize } from './type.cjs';
+export default Card;

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

@@ -0,0 +1,5 @@
+import Card from './Card.js';
+/** Card 卡片组件 */
+export declare const VlCard: <T extends import("react").ElementType = "div">(props: import("./type.js").CardProps<T> & import("react").RefAttributes<import("react").ComponentRef<T>>) => import("react").ReactElement | null;
+export type { CardProps, CardRef, CardShadow, CardSize } from './type.js';
+export default Card;

package/dist/types/Card/type.d.cts

@@ -0,0 +1,40 @@
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
+/** Card 根 DOM 元素类型。自定义组件作为 tag 时需要转发兼容的 HTMLElement ref。 */
+export type CardRef = HTMLElement;
+/** Card 尺寸档位：小 (sm) | 中等 (md) | 大 (lg)。 */
+export type CardSize = 'sm' | 'md' | 'lg';
+/** Card 阴影档位；`none` 保持无阴影的默认 Surface 外观。 */
+export type CardShadow = 'none' | 'sm' | 'md' | 'lg';
+/** Card 自身属性，独立于根节点 tag 的原生属性。 */
+interface CardOwnProps<T extends ElementType> {
+    /** 自定义卡片渲染的 HTML 标签或组件，默认为 `div`。 */
+    tag?: T;
+    /** 卡片头部标题内容；可以传入需要的语义化标题元素。 */
+    title?: ReactNode;
+    /** 卡片头部右侧的扩展内容，通常用于状态或快捷操作。 */
+    extra?: ReactNode;
+    /** 卡片顶部封面内容。 */
+    cover?: ReactNode;
+    /** 卡片底部操作内容。 */
+    actions?: ReactNode;
+    /** 卡片尺寸，默认为 `md`。 */
+    size?: CardSize;
+    /** 是否显示卡片边框，默认为 `true`。 */
+    bordered?: boolean;
+    /** 卡片阴影档位，默认为 `none`。 */
+    shadow?: CardShadow;
+    /** 是否启用 hover 边框反馈，默认为 `false`。 */
+    hoverable?: boolean;
+    /** 卡片主体内容。 */
+    children?: ReactNode;
+    /** 追加到根元素的 class。 */
+    className?: string;
+}
+/**
+ * Card 多态属性接口。
+ *
+ * 根据 `tag` 合并对应根元素的原生属性，避免把所有场景都错误地收窄为
+ * `HTMLAttributes<HTMLElement>`；例如 `tag="a"` 时可以安全使用 `href`。
+ */
+export type CardProps<T extends ElementType = 'div'> = CardOwnProps<T> & Omit<ComponentPropsWithoutRef<T>, keyof CardOwnProps<T>>;
+export {};

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

@@ -0,0 +1,40 @@
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
+/** Card 根 DOM 元素类型。自定义组件作为 tag 时需要转发兼容的 HTMLElement ref。 */
+export type CardRef = HTMLElement;
+/** Card 尺寸档位：小 (sm) | 中等 (md) | 大 (lg)。 */
+export type CardSize = 'sm' | 'md' | 'lg';
+/** Card 阴影档位；`none` 保持无阴影的默认 Surface 外观。 */
+export type CardShadow = 'none' | 'sm' | 'md' | 'lg';
+/** Card 自身属性，独立于根节点 tag 的原生属性。 */
+interface CardOwnProps<T extends ElementType> {
+    /** 自定义卡片渲染的 HTML 标签或组件，默认为 `div`。 */
+    tag?: T;
+    /** 卡片头部标题内容；可以传入需要的语义化标题元素。 */
+    title?: ReactNode;
+    /** 卡片头部右侧的扩展内容，通常用于状态或快捷操作。 */
+    extra?: ReactNode;
+    /** 卡片顶部封面内容。 */
+    cover?: ReactNode;
+    /** 卡片底部操作内容。 */
+    actions?: ReactNode;
+    /** 卡片尺寸，默认为 `md`。 */
+    size?: CardSize;
+    /** 是否显示卡片边框，默认为 `true`。 */
+    bordered?: boolean;
+    /** 卡片阴影档位，默认为 `none`。 */
+    shadow?: CardShadow;
+    /** 是否启用 hover 边框反馈，默认为 `false`。 */
+    hoverable?: boolean;
+    /** 卡片主体内容。 */
+    children?: ReactNode;
+    /** 追加到根元素的 class。 */
+    className?: string;
+}
+/**
+ * Card 多态属性接口。
+ *
+ * 根据 `tag` 合并对应根元素的原生属性，避免把所有场景都错误地收窄为
+ * `HTMLAttributes<HTMLElement>`；例如 `tag="a"` 时可以安全使用 `href`。
+ */
+export type CardProps<T extends ElementType = 'div'> = CardOwnProps<T> & Omit<ComponentPropsWithoutRef<T>, keyof CardOwnProps<T>>;
+export {};

package/dist/types/Checkbox/Checkbox.d.cts

@@ -0,0 +1,3 @@
+import type { CheckboxProps } from './type.cjs';
+declare const Checkbox: import("react").ForwardRefExoticComponent<CheckboxProps & import("react").RefAttributes<HTMLInputElement>>;
+export default Checkbox;

package/dist/types/Checkbox/Checkbox.d.ts

@@ -0,0 +1,3 @@
+import type { CheckboxProps } from './type.js';
+declare const Checkbox: import("react").ForwardRefExoticComponent<CheckboxProps & import("react").RefAttributes<HTMLInputElement>>;
+export default Checkbox;

package/dist/types/Checkbox/CheckboxGroup.d.cts

@@ -0,0 +1,3 @@
+import type { CheckboxGroupProps } from './type.cjs';
+declare const CheckboxGroup: import("react").ForwardRefExoticComponent<CheckboxGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export default CheckboxGroup;

package/dist/types/Checkbox/CheckboxGroup.d.ts

@@ -0,0 +1,3 @@
+import type { CheckboxGroupProps } from './type.js';
+declare const CheckboxGroup: import("react").ForwardRefExoticComponent<CheckboxGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export default CheckboxGroup;

package/dist/types/Checkbox/context.d.cts

@@ -0,0 +1,19 @@
+import type { CheckboxSize, CheckboxValue } from './type.cjs';
+/** CheckboxGroup 共享上下文数据接口 */
+export interface CheckboxGroupContextValue {
+    /** 当前选中的值数组 */
+    value: CheckboxValue[];
+    /** 整组是否禁用 */
+    disabled?: boolean;
+    /** 是否使用边框卡片样式 */
+    bordered?: boolean;
+    /** 表单字段名 */
+    name?: string;
+    /** 尺寸大小 */
+    size?: CheckboxSize;
+    /** 切换特定选项选中状态的方法 */
+    toggleValue: (value: CheckboxValue, checked: boolean) => void;
+}
+export declare const CheckboxGroupProvider: import("react").Provider<CheckboxGroupContextValue | null>;
+/** 获取 CheckboxGroup 上下文的 Hook */
+export declare const useCheckboxGroupContext: () => CheckboxGroupContextValue | null;

package/dist/types/Checkbox/context.d.ts

@@ -0,0 +1,19 @@
+import type { CheckboxSize, CheckboxValue } from './type.js';
+/** CheckboxGroup 共享上下文数据接口 */
+export interface CheckboxGroupContextValue {
+    /** 当前选中的值数组 */
+    value: CheckboxValue[];
+    /** 整组是否禁用 */
+    disabled?: boolean;
+    /** 是否使用边框卡片样式 */
+    bordered?: boolean;
+    /** 表单字段名 */
+    name?: string;
+    /** 尺寸大小 */
+    size?: CheckboxSize;
+    /** 切换特定选项选中状态的方法 */
+    toggleValue: (value: CheckboxValue, checked: boolean) => void;
+}
+export declare const CheckboxGroupProvider: import("react").Provider<CheckboxGroupContextValue | null>;
+/** 获取 CheckboxGroup 上下文的 Hook */
+export declare const useCheckboxGroupContext: () => CheckboxGroupContextValue | null;

package/dist/types/Checkbox/index.d.cts

@@ -0,0 +1,7 @@
+import Checkbox from './Checkbox.cjs';
+/** Checkbox 多选框组件 */
+export declare const VlCheckbox: import("react").ForwardRefExoticComponent<import("./type.cjs").CheckboxProps & import("react").RefAttributes<HTMLInputElement>>;
+/** CheckboxGroup 多选框组组件 */
+export declare const VlCheckboxGroup: import("react").ForwardRefExoticComponent<import("./type.cjs").CheckboxGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export type { CheckboxProps, CheckboxGroupProps, CheckboxSize, CheckboxValue, CheckboxRef, CheckboxGroupRef } from './type.cjs';
+export default Checkbox;

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

@@ -0,0 +1,7 @@
+import Checkbox from './Checkbox.js';
+/** Checkbox 多选框组件 */
+export declare const VlCheckbox: import("react").ForwardRefExoticComponent<import("./type.js").CheckboxProps & import("react").RefAttributes<HTMLInputElement>>;
+/** CheckboxGroup 多选框组组件 */
+export declare const VlCheckboxGroup: import("react").ForwardRefExoticComponent<import("./type.js").CheckboxGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export type { CheckboxProps, CheckboxGroupProps, CheckboxSize, CheckboxValue, CheckboxRef, CheckboxGroupRef } from './type.js';
+export default Checkbox;