vxui-re 1.0.6 → 1.0.7

package/dist/src/components/Table.d.ts

@@ -0,0 +1,90 @@
+import { ReactNode, HTMLAttributes } from 'react';
+import { SelectOption } from './Select';
+export type SortDirection = 'asc' | 'desc' | null;
+export interface TableColumn<T> {
+    key: string;
+    header: ReactNode;
+    accessor: (row: T) => ReactNode;
+    sortable?: boolean;
+    width?: string | number;
+    align?: 'left' | 'center' | 'right';
+    className?: string;
+    /** 此列是否可作为筛选条件 */
+    filterable?: boolean;
+    /** 筛选类型：'text' 文本搜索 | 'select' 下拉选择 */
+    filterType?: 'text' | 'select';
+    /** 当下拉筛选时，可选的选项列表（不传则从 data 中自动提取去重值） */
+    filterOptions?: SelectOption[];
+    /** 是否参与全局文本搜索（默认 true） */
+    searchable?: boolean;
+    /**
+     * 获取该列用于搜索/筛选的纯文本值。
+     * 当 accessor 返回 ReactNode（如 Badge、Tag 等）时，String(ReactNode) 会得到 "[object Object]"，
+     * 导致搜索失效。提供 searchValue 可显式指定搜索用的文本。
+     * 不传时，仅当 accessor 返回 string | number 时才参与搜索。
+     */
+    searchValue?: (row: T) => string;
+}
+export type TableVariant = 'default' | 'dark' | 'outline';
+/** 可从哪个边移除边框 */
+export type TableBorderSide = 'top' | 'right' | 'bottom' | 'left';
+export interface TableProps<T> extends HTMLAttributes<HTMLDivElement> {
+    columns: TableColumn<T>[];
+    data: T[];
+    /** Row height preset. */
+    size?: 'sm' | 'md' | 'lg';
+    striped?: boolean;
+    hoverable?: boolean;
+    bordered?: boolean;
+    /** @deprecated Use size="sm" instead */
+    compact?: boolean;
+    stickyHeader?: boolean;
+    /** 搜索栏是否吸顶（滚动时保持可见），默认 false */
+    stickyFilter?: boolean;
+    borderless?: boolean;
+    headless?: boolean;
+    rounded?: boolean;
+    loading?: boolean;
+    caption?: string;
+    emptyText?: ReactNode;
+    sortColumn?: string | null;
+    sortDirection?: SortDirection;
+    onSortChange?: (column: string, direction: SortDirection) => void;
+    /** 表格视觉变体：'default' | 'dark' | 'outline' */
+    variant?: TableVariant;
+    /** 固定表格布局（列宽严格按 width 分配，不换行截断） */
+    fixed?: boolean;
+    /** 移除指定边边框：'all' 移除四边，或传入边列表。用于嵌入 Card 等容器场景 */
+    removeBorders?: 'all' | TableBorderSide[];
+    /** 紧凑嵌入模式：移除内边距、圆角和外边框，适合直接放入 Card 中 */
+    flush?: boolean;
+    /** 行点击回调 */
+    onRowClick?: (row: T, index: number) => void;
+    /** 自定义行类名（字符串或函数） */
+    rowClassName?: string | ((row: T, index: number) => string);
+    /** 启用行选择（显示复选框列） */
+    selectable?: boolean;
+    /** 受控选中行索引集合 */
+    selectedRows?: Set<number>;
+    /** 选中行变化回调 */
+    onSelectionChange?: (selected: Set<number>) => void;
+    /** 是否显示筛选栏（默认数据 > filterThreshold 时自动显示） */
+    filterable?: boolean;
+    /** 搜索框占位文本 */
+    filterPlaceholder?: string;
+    /** 当前筛选文本（受控） */
+    filterValue?: string;
+    /** 筛选文本变化回调 */
+    onFilterChange?: (value: string) => void;
+    /** 列筛选状态 */
+    columnFilters?: Record<string, string>;
+    /** 列筛选变化回调 */
+    onColumnFilterChange?: (columnKey: string, value: string) => void;
+    /** 数据量超过此值时自动显示筛选栏（默认 10） */
+    filterThreshold?: number;
+    /** 搜索防抖延迟（毫秒），默认 200。设为 0 禁用防抖 */
+    searchDebounce?: number;
+    /** 限定参与文本搜索的列 key 列表，不传则搜索所有 searchable !== false 的列 */
+    searchColumns?: string[];
+}
+export declare function Table<T>({ columns, data, size, striped, hoverable, bordered, compact, stickyHeader, stickyFilter, borderless, headless, rounded, loading, caption, emptyText, sortColumn: controlledSortCol, sortDirection: controlledSortDir, onSortChange, variant, fixed, removeBorders, flush, onRowClick, rowClassName, selectable, selectedRows: controlledSelectedRows, onSelectionChange, className, filterable: filterableProp, filterPlaceholder, filterValue: controlledFilterValue, onFilterChange, columnFilters: controlledColumnFilters, onColumnFilterChange, filterThreshold, searchDebounce, searchColumns, ...props }: TableProps<T>): import("react").JSX.Element;

package/dist/src/components/Tabs.d.ts

@@ -0,0 +1,5 @@
+import * as TabsPrimitive from '@radix-ui/react-tabs';
+export declare const Tabs: import('react').ForwardRefExoticComponent<TabsPrimitive.TabsProps & import('react').RefAttributes<HTMLDivElement>>;
+export declare const TabsList: import('react').ForwardRefExoticComponent<Omit<TabsPrimitive.TabsListProps & import('react').RefAttributes<HTMLDivElement>, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+export declare const TabsTrigger: import('react').ForwardRefExoticComponent<Omit<TabsPrimitive.TabsTriggerProps & import('react').RefAttributes<HTMLButtonElement>, "ref"> & import('react').RefAttributes<HTMLButtonElement>>;
+export declare const TabsContent: import('react').ForwardRefExoticComponent<Omit<TabsPrimitive.TabsContentProps & import('react').RefAttributes<HTMLDivElement>, "ref"> & import('react').RefAttributes<HTMLDivElement>>;

package/dist/src/components/TagInput.d.ts

@@ -0,0 +1,18 @@
+import { InputHTMLAttributes } from 'react';
+export interface TagInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'defaultValue'> {
+    value?: string[];
+    defaultValue?: string[];
+    onChange?: (tags: string[]) => void;
+    label?: string;
+    hint?: string;
+    error?: string;
+    placeholder?: string;
+    /** Keys that confirm a tag. Defaults to Enter and comma */
+    confirmKeys?: string[];
+    /** Maximum number of tags */
+    maxTags?: number;
+    /** Validate a tag before adding; return false or error message to reject */
+    validate?: (tag: string) => boolean | string;
+    className?: string;
+}
+export declare function TagInput({ value: controlledValue, defaultValue, onChange, label, hint, error, placeholder, confirmKeys, maxTags, validate, disabled, className, ...inputProps }: TagInputProps): import("react").JSX.Element;

package/dist/src/components/Text.d.ts

@@ -0,0 +1,14 @@
+import { HTMLAttributes } from 'react';
+type TextVariant = 'default' | 'secondary' | 'muted' | 'danger' | 'success';
+type TextSize = 'sm' | 'base' | 'lg' | 'xl';
+type TextWeight = 'normal' | 'medium' | 'semibold' | 'bold';
+type TextElement = 'p' | 'span' | 'div';
+export interface TextProps extends HTMLAttributes<HTMLElement> {
+    as?: TextElement;
+    variant?: TextVariant;
+    size?: TextSize;
+    weight?: TextWeight;
+    truncate?: boolean;
+}
+export declare function Text({ as: Component, variant, size, weight, truncate, className, ...props }: TextProps): import("react").JSX.Element;
+export {};

package/dist/src/components/Textarea.d.ts

@@ -0,0 +1,7 @@
+import { TextareaHTMLAttributes } from 'react';
+export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    label?: string;
+    hint?: string;
+    resize?: 'none' | 'vertical' | 'horizontal' | 'both';
+}
+export declare function Textarea({ className, label, hint, resize, style, ...props }: TextareaProps): import("react").JSX.Element;

package/dist/src/components/ThemeProvider.d.ts

@@ -0,0 +1,51 @@
+import { ReactNode } from 'react';
+export type ThemeMode = 'light' | 'dark';
+export type ThemeTokens = Partial<Record<`--vx-${string}`, string>>;
+export interface ThemeDefinition {
+    label?: string;
+    mode: ThemeMode;
+    tokens?: ThemeTokens;
+}
+export type ThemeRegistry = Record<string, ThemeDefinition>;
+interface CreateThemeOptions {
+    label?: string;
+    tokens?: ThemeTokens;
+}
+export declare function createTheme(mode: ThemeMode, options?: CreateThemeOptions): ThemeDefinition;
+export declare const themePresets: {
+    sunset: ThemeDefinition;
+    mint: ThemeDefinition;
+    graphite: ThemeDefinition;
+    'ivory-gold': ThemeDefinition;
+    'black-gold': ThemeDefinition;
+    ocean: ThemeDefinition;
+    indigo: ThemeDefinition;
+    violet: ThemeDefinition;
+    'violet-dark': ThemeDefinition;
+    vxai: ThemeDefinition;
+    'vxai-dark': ThemeDefinition;
+    light: {
+        label: string;
+        mode: "light";
+    };
+    dark: {
+        label: string;
+        mode: "dark";
+    };
+};
+interface ThemeContextValue {
+    theme: string;
+    mode: ThemeMode;
+    themes: ThemeRegistry;
+    setTheme: (theme: string) => void;
+    toggleTheme: () => void;
+}
+interface ThemeProviderProps {
+    children: ReactNode;
+    defaultTheme?: string;
+    storageKey?: string;
+    themes?: ThemeRegistry;
+}
+export declare function ThemeProvider({ children, defaultTheme, storageKey, themes, }: ThemeProviderProps): import("react").JSX.Element;
+export declare function useTheme(): ThemeContextValue;
+export {};

package/dist/src/components/TimePicker.d.ts

@@ -0,0 +1,14 @@
+export interface TimePickerProps {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    placeholder?: string;
+    label?: string;
+    hint?: string;
+    error?: string;
+    disabled?: boolean;
+    /** Show seconds column. Default false */
+    seconds?: boolean;
+    className?: string;
+}
+export declare function TimePicker({ value: controlledValue, defaultValue, onChange, placeholder, label, hint, error, disabled, seconds, className, }: TimePickerProps): import("react").JSX.Element;

package/dist/src/components/Timeline.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+export type TimelineItemStatus = 'default' | 'success' | 'warning' | 'danger' | 'info';
+export interface TimelineItem {
+    title: string;
+    description?: string;
+    time?: string;
+    icon?: ReactNode;
+    status?: TimelineItemStatus;
+}
+export interface TimelineProps {
+    items: TimelineItem[];
+    className?: string;
+}
+export declare function Timeline({ items, className }: TimelineProps): import("react").JSX.Element;

package/dist/src/components/Toast.d.ts

@@ -0,0 +1,15 @@
+import { ReactNode } from 'react';
+type ToastTone = 'info' | 'success' | 'warning' | 'danger';
+interface ToastInput {
+    title: string;
+    description?: string;
+    tone?: ToastTone;
+}
+interface ToastContextValue {
+    push: (toast: ToastInput) => void;
+}
+export declare function ToastProvider({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useToast(): ToastContextValue;
+export {};

package/dist/src/components/Toggle.d.ts

@@ -0,0 +1,24 @@
+import { ButtonHTMLAttributes, ReactNode } from 'react';
+export interface ToggleProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onChange'> {
+    pressed?: boolean;
+    defaultPressed?: boolean;
+    onPressedChange?: (pressed: boolean) => void;
+    size?: 'sm' | 'md' | 'lg';
+    children: ReactNode;
+}
+export declare function Toggle({ pressed: controlledPressed, defaultPressed, onPressedChange, size, className, children, onClick, ...props }: ToggleProps): import("react").JSX.Element;
+export interface ToggleGroupItem {
+    value: string;
+    label: ReactNode;
+    disabled?: boolean;
+}
+export interface ToggleGroupProps {
+    items: ToggleGroupItem[];
+    value?: string | string[];
+    defaultValue?: string | string[];
+    onValueChange?: (value: string | string[]) => void;
+    type?: 'single' | 'multiple';
+    size?: 'sm' | 'md' | 'lg';
+    className?: string;
+}
+export declare function ToggleGroup({ items, value: controlledValue, defaultValue, onValueChange, type, size, className, }: ToggleGroupProps): import("react").JSX.Element;

package/dist/src/components/Tooltip.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+export interface TooltipProps {
+    content: ReactNode;
+    placement?: TooltipPlacement;
+    delay?: number;
+    children: ReactNode;
+    className?: string;
+}
+export declare function Tooltip({ content, placement, delay, children, className }: TooltipProps): import("react").JSX.Element;
+export {};

package/dist/src/components/TreeView.d.ts

@@ -0,0 +1,20 @@
+import { ReactNode } from 'react';
+export interface TreeNode {
+    id: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    children?: TreeNode[];
+    disabled?: boolean;
+    data?: unknown;
+}
+export interface TreeViewProps {
+    nodes: TreeNode[];
+    selected?: string;
+    defaultSelected?: string;
+    onSelect?: (id: string, node: TreeNode) => void;
+    defaultExpanded?: string[];
+    expanded?: string[];
+    onExpandedChange?: (ids: string[]) => void;
+    className?: string;
+}
+export declare function TreeView({ nodes, selected: controlledSelected, defaultSelected, onSelect, defaultExpanded, expanded: controlledExpanded, onExpandedChange, className, }: TreeViewProps): import("react").JSX.Element;

package/dist/src/components/mobile/ActionSheet.d.ts

@@ -0,0 +1,15 @@
+import { ReactNode, ButtonHTMLAttributes } from 'react';
+export interface ActionSheetProps {
+    open: boolean;
+    onClose: () => void;
+    title?: string;
+    description?: string;
+    children: ReactNode;
+    className?: string;
+}
+export declare function ActionSheet({ open, onClose, title, description, children, className, }: ActionSheetProps): import("react").JSX.Element | null;
+export interface ActionSheetItemProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    icon?: ReactNode;
+    destructive?: boolean;
+}
+export declare function ActionSheetItem({ icon, destructive, className, children, ...props }: ActionSheetItemProps): import("react").JSX.Element;

package/dist/src/components/mobile/BottomNav.d.ts

@@ -0,0 +1,23 @@
+import { ReactNode } from 'react';
+export interface BottomNavSubMenuItem {
+    key: string;
+    label: string;
+    icon?: ReactNode;
+    onSelect?: () => void;
+}
+export interface BottomNavItem {
+    key: string;
+    label: string;
+    icon: ReactNode;
+    /** 数字或字符串角标，超过 99 建议传 '99+' */
+    badge?: string | number;
+    active?: boolean;
+    onSelect?: () => void;
+    /** 子菜单项，有值时点击 item 将弹出子菜单而非直接触发 onSelect */
+    submenu?: BottomNavSubMenuItem[];
+}
+export interface BottomNavProps {
+    items: BottomNavItem[];
+    className?: string;
+}
+export declare function BottomNav({ items, className }: BottomNavProps): import("react").JSX.Element;

package/dist/src/components/mobile/MobileApp.d.ts

@@ -0,0 +1 @@
+export declare function MobileApp(): import("react").JSX.Element;

package/dist/src/components/mobile/MobileDrawer.d.ts

@@ -0,0 +1,31 @@
+import { ReactNode } from 'react';
+export interface MobileDrawerProps {
+    open: boolean;
+    onClose: () => void;
+    /** 抽屉宽度，默认 280px */
+    width?: number;
+    /** 抽屉头部内容（品牌 logo、用户信息等） */
+    header?: ReactNode;
+    /** 抽屉底部内容（设置、登出等） */
+    footer?: ReactNode;
+    children: ReactNode;
+    className?: string;
+}
+export declare function MobileDrawer({ open, onClose, width, header, footer, children, className, }: MobileDrawerProps): import("react").JSX.Element | null;
+export interface DrawerNavItemProps {
+    icon?: ReactNode;
+    label: ReactNode;
+    badge?: string | number;
+    active?: boolean;
+    onClick?: () => void;
+}
+export declare function DrawerNavItem({ icon, label, badge, active, onClick }: DrawerNavItemProps): import("react").JSX.Element;
+export interface DrawerNavSectionProps {
+    title?: string;
+    /** 是否可折叠，默认 false */
+    collapsible?: boolean;
+    /** 初始展开状态，collapsible=true 时有效，默认 true */
+    defaultOpen?: boolean;
+    children: ReactNode;
+}
+export declare function DrawerNavSection({ title, collapsible, defaultOpen, children }: DrawerNavSectionProps): import("react").JSX.Element;

package/dist/src/components/mobile/MobileList.d.ts

@@ -0,0 +1,24 @@
+import { HTMLAttributes, ReactNode } from 'react';
+export declare function MobileList({ className, ...props }: HTMLAttributes<HTMLUListElement>): import("react").JSX.Element;
+export interface MobileListSectionProps extends HTMLAttributes<HTMLDivElement> {
+    title?: string;
+}
+export declare function MobileListSection({ title, className, children, ...props }: MobileListSectionProps): import("react").JSX.Element;
+export interface MobileListItemProps {
+    /** 左侧图标或头像区域 */
+    leading?: ReactNode;
+    /** 右侧自定义内容（如状态标签、数值） */
+    trailing?: ReactNode;
+    /** 主标签文本 */
+    label: ReactNode;
+    /** 副文本描述 */
+    description?: ReactNode;
+    /** 是否显示右侧箭头（表示可进入下一层） */
+    chevron?: boolean;
+    /** 破坏性操作，文字变为危险色 */
+    destructive?: boolean;
+    disabled?: boolean;
+    onClick?: () => void;
+    className?: string;
+}
+export declare function MobileListItem({ leading, trailing, label, description, chevron, destructive, disabled, onClick, className, }: MobileListItemProps): import("react").JSX.Element;

package/dist/src/components/mobile/MobilePreviewPage.d.ts

@@ -0,0 +1,5 @@
+interface MobilePreviewPageProps {
+    onExit: () => void;
+}
+export declare function MobilePreviewPage({ onExit }: MobilePreviewPageProps): import("react").JSX.Element;
+export {};

package/dist/src/components/mobile/MobileShell.d.ts

@@ -0,0 +1,24 @@
+import { ReactNode } from 'react';
+export interface MobileShellProps {
+    /** 固定在顶部的导航栏区域 */
+    topBar?: ReactNode;
+    /** 固定在底部的导航栏区域 */
+    bottomNav?: ReactNode;
+    children: ReactNode;
+    className?: string;
+}
+export declare function MobileShell({ topBar, bottomNav, children, className }: MobileShellProps): import("react").JSX.Element;
+export interface MobileTopBarProps {
+    /** 标题文本或节点 */
+    title?: ReactNode;
+    /** 左侧区域，通常为返回按钮 */
+    leading?: ReactNode;
+    /** 右侧区域，通常为操作按钮 */
+    trailing?: ReactNode;
+    className?: string;
+}
+export declare function MobileTopBar({ title, leading, trailing, className }: MobileTopBarProps): import("react").JSX.Element;
+export interface MobileIconButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    label: string;
+}
+export declare function MobileIconButton({ label, className, children, ...props }: MobileIconButtonProps): import("react").JSX.Element;

package/dist/src/components/pages/ErrorPage.d.ts

@@ -0,0 +1,9 @@
+interface ErrorPageProps {
+    statusCode?: number;
+    requestedPath?: string;
+    onHome: () => void;
+    onDocs: () => void;
+    onBack: () => void;
+}
+export declare function ErrorPage({ statusCode, requestedPath, onHome, onDocs, onBack, }: ErrorPageProps): import("react").JSX.Element;
+export {};

package/dist/src/components/pages/HomePage.d.ts

@@ -0,0 +1,10 @@
+interface HomePageProps {
+    viewerName?: string | null;
+    onLogin: () => void;
+    onRegister: () => void;
+    onDocs: (pageKey?: string) => void;
+    onPrivacy: () => void;
+    onLogout?: () => void;
+}
+export declare function HomePage({ viewerName, onLogin, onRegister, onDocs, onPrivacy, onLogout, }: HomePageProps): import("react").JSX.Element;
+export {};

package/dist/src/components/pages/LoginPage.d.ts

@@ -0,0 +1,12 @@
+interface LoginPageProps {
+    onLogin: (payload: {
+        email: string;
+        password: string;
+        remember: boolean;
+    }) => Promise<void> | void;
+    onRegister: () => void;
+    onGuest: () => void;
+    onBack: () => void;
+}
+export declare function LoginPage({ onLogin, onRegister, onGuest, onBack }: LoginPageProps): import("react").JSX.Element;
+export {};

package/dist/src/components/pages/PrivacyPolicyPage.d.ts

@@ -0,0 +1,5 @@
+interface PrivacyPolicyPageProps {
+    onBack: () => void;
+}
+export declare function PrivacyPolicyPage({ onBack }: PrivacyPolicyPageProps): import("react").JSX.Element;
+export {};

package/dist/src/components/pages/RegisterPage.d.ts

@@ -0,0 +1,14 @@
+interface RegisterPageProps {
+    onRegister: (payload: {
+        name: string;
+        email: string;
+        password: string;
+    }) => Promise<void> | void;
+    onLogin: () => void;
+    onGuest: () => void;
+    onPrivacy: () => void;
+    onTerms: () => void;
+    onBack: () => void;
+}
+export declare function RegisterPage({ onRegister, onLogin, onGuest, onPrivacy, onTerms, onBack }: RegisterPageProps): import("react").JSX.Element;
+export {};

package/dist/src/components/pages/TermsOfServicePage.d.ts

@@ -0,0 +1,5 @@
+interface TermsOfServicePageProps {
+    onBack: () => void;
+}
+export declare function TermsOfServicePage({ onBack }: TermsOfServicePageProps): import("react").JSX.Element;
+export {};

package/dist/src/components/pages/homePageContent.d.ts

@@ -0,0 +1,25 @@
+import { LucideIcon } from 'lucide-react';
+import { Translations } from '../../i18n';
+export interface PublicHomeFeature {
+    key: string;
+    icon: LucideIcon;
+    title: string;
+    description: string;
+}
+export interface PublicHomePreviewSection {
+    id: string;
+    icon: LucideIcon;
+    label: string;
+    meta: string;
+}
+export interface PublicHomeMetaItem {
+    key: string;
+    icon: LucideIcon;
+    title: string;
+    lines: string[];
+}
+export declare function getPublicHomeContent(t: Translations): {
+    features: PublicHomeFeature[];
+    previewSections: PublicHomePreviewSection[];
+    metaItems: PublicHomeMetaItem[];
+};

package/dist/src/components/pages/legalPageContent.d.ts

@@ -0,0 +1,15 @@
+export interface LegalPageSection {
+    title: string;
+    paragraphs: string[];
+}
+export interface LegalPageContent {
+    badgeLabel: string;
+    title: string;
+    lead: string;
+    meta: string[];
+    summaryTitle: string;
+    summaryItems: string[];
+    sections: LegalPageSection[];
+}
+export declare function getPrivacyPolicyContent(locale: string): LegalPageContent;
+export declare function getTermsOfServiceContent(locale: string): LegalPageContent;

package/dist/src/lib/VXUIProvider.d.ts

@@ -0,0 +1,29 @@
+import { ReactNode } from 'react';
+import { ThemeRegistry } from '../components/ThemeProvider';
+export interface VXUIProviderProps {
+    children: ReactNode;
+    /**
+     * 主题配置，传递给 ThemeProvider。
+     * 包含预设主题和自定义主题。
+     */
+    themes?: ThemeRegistry;
+    /** 默认主题名称 */
+    defaultTheme?: string;
+    /** localStorage 存储键名 */
+    storageKey?: string;
+}
+/**
+ * 组合 Provider，一次性挂载 ThemeProvider、ViewportProvider、ToastProvider。
+ *
+ * 等价于：
+ * ```tsx
+ * <ThemeProvider themes={themes} defaultTheme={defaultTheme}>
+ *   <ViewportProvider>
+ *     <ToastProvider>
+ *       {children}
+ *     </ToastProvider>
+ *   </ViewportProvider>
+ * </ThemeProvider>
+ * ```
+ */
+export declare function VXUIProvider({ children, themes, defaultTheme, storageKey, }: VXUIProviderProps): import("react").JSX.Element;

package/dist/src/lib/breakpoints.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Unified breakpoint constants shared between JS and CSS.
+ *
+ * ── 断点系统说明 ─────────────────────────────────────────────
+ *
+ * 本系统有两套断点，用途不同，请勿混淆：
+ *
+ * 1. CSS 布局断点 (CSS Media Query Breakpoints)
+ *    ──────────────────────────────────────────
+ *    用于控制页面布局在不同视口宽度下的表现。
+ *    sm: 640px  — 手机布局断点
+ *    md: 768px  — 平板布局断点
+ *    lg: 1000px — 桌面布局断点
+ *
+ *    这些值必须与 CSS 变量保持一致：
+ *      --vx-breakpoint-sm: 640px
+ *      --vx-breakpoint-md: 768px
+ *      --vx-breakpoint-lg: 1000px
+ *
+ * 2. 设备检测断点 (Device Detection Breakpoints)
+ *    ──────────────────────────────────────────
+ *    用于 JS 端判断设备类型（phone / tablet / desktop）。
+ *    基于物理屏幕尺寸（window.screen.width），而非视口宽度。
+ *    PHONE_MAX_WIDTH = 1000
+ *
+ *    为什么设备检测使用 1000px 而不是 640px？
+ *    - 物理屏幕宽度 ≤ 1000px 的设备可能是手机或平板
+ *    - 物理屏幕宽度 > 1000px 的肯定是桌面显示器
+ *    - 手机和平板的区分通过宽高比（aspect ratio）实现
+ *    - 这样可以避免桌面浏览器窗口缩小时被误判为手机
+ *
+ * 3. 为什么 CSS 布局断点用 640px 而设备检测用 1000px？
+ *    ──────────────────────────────────────────
+ *    CSS 媒体查询基于视口宽度（viewport width），
+ *    而设备检测基于物理屏幕宽度（screen.width）。
+ *    两者是不同的概念：
+ *    - 一个 1024px 物理宽度的平板，在分屏模式下视口可能只有 512px
+ *    - CSS 需要在视口 640px 时就切换到手机布局
+ *    - 但设备检测仍应识别为平板（物理宽度 > 640px）
+ *
+ *    因此这两套断点值不同是合理的，不需要强行统一。
+ *    关键是要在代码中明确区分它们的用途。
+ *
+ * ─────────────────────────────────────────────────────────────
+ */
+export declare const BREAKPOINTS: {
+    /** CSS 布局断点 - 手机布局 (max-width: 640px) */
+    readonly sm: 640;
+    /** CSS 布局断点 - 平板布局 (max-width: 768px) */
+    readonly md: 768;
+    /** CSS 布局断点 - 桌面布局 (min-width: 1000px) */
+    readonly lg: 1000;
+};
+/**
+ * 设备检测 - 物理屏幕宽度阈值。
+ * 物理宽度 ≤ PHONE_MAX_WIDTH 的设备可能是手机或平板，
+ * 具体通过宽高比进一步区分。
+ */
+export declare const PHONE_MAX_WIDTH: 1000;
+/** 宽高比阈值：低于此值判定为手机（窄屏设备） */
+export declare const PHONE_ASPECT_RATIO_THRESHOLD = 0.7;
+/** 宽高比阈值：低于此值且宽度 ≤ PHONE_MAX_WIDTH 判定为手机 */
+export declare const TABLET_ASPECT_RATIO_THRESHOLD = 0.75;

package/dist/src/lib/cx.d.ts

@@ -0,0 +1 @@
+export declare function cx(...values: Array<string | false | null | undefined>): string;