upload-pulse 1.0.0

package/README.md

@@ -0,0 +1,127 @@
+# upload-pulse
+
+React 文件上传进度 UI 组件库：深色/浅色主题、拖拽投放、格式限制、多选与数量上限、XHR / Mock Hooks。
+
+## 安装
+
+```bash
+npm install upload-pulse
+```
+
+**Peer dependencies：** `react`、`react-dom`（>=18）
+
+**样式：** 需配合 [Tailwind CSS v4](https://tailwindcss.com/) 使用。
+
+## 快速开始
+
+### 1. 引入样式
+
+在应用入口 CSS 中：
+
+```css
+@import 'tailwindcss';
+@import 'upload-pulse/styles.css';
+```
+
+`upload-pulse/styles.css` 已包含组件所需的 Tailwind utility 与动画，一般无需再 `@source` 扫描包内 JS。
+
+若你自行从源码集成组件（非 npm 包），需确保 Tailwind 能扫描到组件目录，例如：
+
+```css
+@import 'tailwindcss';
+@source "./node_modules/upload-pulse/dist/index.js";
+@import 'upload-pulse/styles.css';
+```
+
+### 2. 使用组件
+
+```tsx
+import { Upload, UploadPicker, UploadWithUpload } from 'upload-pulse';
+
+function App() {
+  return (
+    <>
+      <UploadPicker
+        config={{
+          accept: ['.xlsx', '.xls'],
+          multiple: true,
+          maxCount: 5,
+          showButton: true,
+          drag: { enabled: true, showDropzone: true },
+        }}
+        currentCount={0}
+        onFilesSelected={(files) => console.log(files)}
+      />
+
+      <UploadWithUpload
+        file={file}
+        url="/api/upload"
+        config={{ theme: 'dark', pausable: false }}
+        onComplete={() => {}}
+      />
+    </>
+  );
+}
+```
+
+## 导出
+
+| 组件 / Hook | 说明 |
+|-------------|------|
+| `Upload` | 受控进度卡片 |
+| `UploadPicker` | 选文件 + 拖拽 + 校验 |
+| `UploadDropzone` | 拖拽投放区 |
+| `UploadWithUpload` | XHR 上传封装 |
+| `UploadWithMock` | Mock 演示 |
+| `useUpload` | XHR Hook |
+| `useUploadPicker` | 选文件校验 |
+| `useUploadDragDrop` | 拖拽逻辑 |
+| `useUploadDisplay` | 进度展示计算 |
+
+类型与常量：`UploadConfig`、`UploadPickerConfig`、`DARK_THEME_COLORS`、`LIGHT_THEME_COLORS` 等。
+
+## 本地开发
+
+源码目录遵循 [Ant Design](https://github.com/ant-design/ant-design) 规范：`src/components/upload/` 下按组件分子目录，`interface.ts` 定义类型，`hooks/`、`style/`、`utils/` 分模块组织。
+
+```bash
+npm install
+npm run dev
+```
+
+浏览器会打开预览页，可直接体验 `UploadPicker` 与 `UploadWithMock` 的交互效果。修改 `src/` 下组件源码会热更新。
+
+构建组件库：
+
+```bash
+npm run build
+```
+
+预览生产构建：
+
+```bash
+npm run preview
+```
+
+## 发布
+
+```bash
+npm run build
+npm publish --access public
+```
+
+## 在其他项目中链接本地包
+
+```json
+{
+  "dependencies": {
+    "upload-pulse": "file:../UploadPulse"
+  }
+}
+```
+
+安装后执行 `npm install`，用法与 npm 包相同。
+
+## License
+
+MIT

package/dist/components/upload/Dropzone.d.ts

@@ -0,0 +1,19 @@
+import type { UploadDropzoneLabels, UploadDropzoneStyle } from './interface';
+interface UploadDropzoneProps {
+    disabled: boolean;
+    isDragging: boolean;
+    labels: Required<UploadDropzoneLabels>;
+    style: Required<UploadDropzoneStyle>;
+    dropHandlers: {
+        onDragEnter?: (event: React.DragEvent) => void;
+        onDragLeave?: (event: React.DragEvent) => void;
+        onDragOver?: (event: React.DragEvent) => void;
+        onDrop?: (event: React.DragEvent) => void;
+    };
+    onOpen: () => void;
+    className?: string;
+    /** 是否显示「或点击选择文件」提示，与独立按钮并存时可设为 false */
+    showClickHint?: boolean;
+}
+export declare function Dropzone({ disabled, isDragging, labels, style, dropHandlers, onOpen, className, showClickHint, }: UploadDropzoneProps): import("react").JSX.Element;
+export {};

package/dist/components/upload/FileTypeIcon.d.ts

@@ -0,0 +1,6 @@
+interface FileTypeIconProps {
+    filename: string;
+    className?: string;
+}
+export declare function FileTypeIcon({ filename, className }: FileTypeIconProps): import("react").JSX.Element;
+export {};

package/dist/components/upload/MockUpload.d.ts

@@ -0,0 +1,2 @@
+import type { UploadWithMockProps } from './interface';
+export declare function MockUpload({ file, completedVariant, config, speed, onComplete, onCancel, onDelete, onChange, onDownload, className, }: UploadWithMockProps): import("react").JSX.Element | null;

package/dist/components/upload/Picker.d.ts

@@ -0,0 +1,2 @@
+import type { UploadPickerProps } from './interface';
+export declare function Picker({ config, currentCount, onFilesSelected, onReject, disabled, className, buttonClassName, dropzoneClassName, wrapperClassName, children, }: UploadPickerProps): import("react").JSX.Element;

package/dist/components/upload/Upload.d.ts

@@ -0,0 +1,2 @@
+import type { UploadProps } from './interface';
+export declare function Upload({ file, status, progress, errorMessage, completedVariant, config, onPause, onResume, onCancel, onDelete, onChange, onDownload, onRetry, className, exiting, }: UploadProps): import("react").JSX.Element;

package/dist/components/upload/UploadActions.d.ts

@@ -0,0 +1,11 @@
+import type { UploadCallbacks, UploadStatus } from './interface';
+interface UploadActionsProps extends Pick<UploadCallbacks, 'onPause' | 'onResume' | 'onCancel' | 'onDelete' | 'onRetry'> {
+    status: UploadStatus;
+    pausable: boolean;
+    cancelable: boolean;
+    deletable: boolean;
+    retryable: boolean;
+    retryLabel: string;
+}
+export declare function UploadActions({ status, pausable, cancelable, deletable, retryable, retryLabel, onPause, onResume, onCancel, onDelete, onRetry, }: UploadActionsProps): import("react").JSX.Element | null;
+export {};

package/dist/components/upload/UploadRequest.d.ts

@@ -0,0 +1,2 @@
+import type { UploadWithUploadProps } from './interface';
+export declare function UploadRequest({ file, url, method, fieldName, headers, withCredentials, extraFields, completedVariant, config, onComplete, onError, onCancel, onDelete, onChange, onDownload, onRetry, className, }: UploadWithUploadProps): import("react").JSX.Element | null;

package/dist/components/upload/config.d.ts

@@ -0,0 +1,116 @@
+import type { UploadConfig, UploadDropzoneLabels, UploadDropzoneStyle, UploadLabels, UploadPickerConfig, UploadPickerDragConfig, UploadPickerLabels, UploadTheme, UploadThemeColors } from './interface';
+export declare const DARK_THEME_COLORS: Required<UploadThemeColors>;
+export declare const LIGHT_THEME_COLORS: Required<UploadThemeColors>;
+export declare const DEFAULT_UPLOAD_CONFIG: Required<Omit<UploadConfig, 'labels' | 'colors'>> & {
+    labels: Required<UploadLabels>;
+    colors: Required<UploadThemeColors>;
+};
+export declare const DEFAULT_PICKER_LABELS: Required<UploadPickerLabels>;
+export declare const DEFAULT_DROPZONE_LABELS: Required<UploadDropzoneLabels>;
+export declare const LIGHT_DROPZONE_STYLE: Required<UploadDropzoneStyle>;
+export declare const DEFAULT_DROPZONE_STYLE: Required<UploadDropzoneStyle>;
+export declare const DEFAULT_DRAG_CONFIG: Required<Omit<UploadPickerDragConfig, 'labels' | 'style'>> & {
+    labels: Required<UploadDropzoneLabels>;
+    style: Required<UploadDropzoneStyle>;
+};
+export declare const PICKER_BUTTON_CLASS: {
+    readonly dark: "cursor-pointer rounded-lg border border-gray-700 bg-neutral-800 px-4 py-2 text-[13px] text-gray-100 transition-colors duration-150 hover:bg-gray-700 disabled:cursor-not-allowed disabled:opacity-50";
+    readonly light: "cursor-pointer rounded-lg border border-gray-300 bg-white px-4 py-2 text-[13px] text-gray-900 transition-colors duration-150 hover:bg-gray-50 disabled:cursor-not-allowed disabled:opacity-50";
+};
+export declare const DEFAULT_PICKER_CONFIG: Required<Omit<UploadPickerConfig, 'accept' | 'maxCount' | 'labels' | 'drag'>> & {
+    labels: Required<UploadPickerLabels>;
+    drag: typeof DEFAULT_DRAG_CONFIG;
+};
+export declare function resolveUploadConfig(config?: UploadConfig): {
+    theme: UploadTheme;
+    colors: {
+        cardBackground: string;
+        cardShadow: string;
+        fileName: string;
+        statusUploading: string;
+        statusPaused: string;
+        statusError: string;
+        statusCompleted: string;
+        metaMuted: string;
+        metaSeparator: string;
+        progressTrack: string;
+        progressBackground: string;
+        progressFill: string;
+        progressGlow: string;
+        iconButtonBackground: string;
+        iconButtonHover: string;
+        iconButtonText: string;
+        closeButtonText: string;
+        closeButtonHover: string;
+        deleteButtonBackground: string;
+        deleteButtonText: string;
+        deleteButtonHoverBackground: string;
+        deleteButtonHoverText: string;
+        deleteButtonShadow: string;
+        deleteButtonHoverShadow: string;
+        successBadgeBackground: string;
+        changeButtonBackground: string;
+        changeButtonHover: string;
+        changeButtonText: string;
+        downloadButtonBackground: string;
+        downloadButtonHover: string;
+        downloadButtonText: string;
+    };
+    labels: {
+        uploading: (percent: number) => string;
+        paused: (percent: number) => string;
+        completed: string;
+        error: string | ((message?: string) => string);
+        change: string;
+        download: string;
+        retry: string;
+    };
+    progressInset: number;
+    maxWidth: number;
+    showProgressBar: boolean;
+    showBackgroundProgress: boolean;
+    pausable: boolean;
+    cancelable: boolean;
+    deletable: boolean;
+    retryable: boolean;
+};
+export declare function resolveUploadPickerConfig(config?: UploadPickerConfig): {
+    theme: UploadTheme;
+    buttonClassName: "cursor-pointer rounded-lg border border-gray-700 bg-neutral-800 px-4 py-2 text-[13px] text-gray-100 transition-colors duration-150 hover:bg-gray-700 disabled:cursor-not-allowed disabled:opacity-50" | "cursor-pointer rounded-lg border border-gray-300 bg-white px-4 py-2 text-[13px] text-gray-900 transition-colors duration-150 hover:bg-gray-50 disabled:cursor-not-allowed disabled:opacity-50";
+    labels: {
+        maxCountExceeded: (max: number) => string;
+        invalidFormat: (filename: string) => string;
+    };
+    drag: {
+        labels: {
+            hint: string;
+            hintActive: string;
+            hintDisabled: string;
+            clickHint: string;
+        };
+        style: {
+            borderColor: string;
+            borderColorActive: string;
+            borderColorDisabled: string;
+            background: string;
+            backgroundActive: string;
+            textColor: string;
+            textColorActive: string;
+            textColorDisabled: string;
+            minHeight: number;
+            borderRadius: number;
+        };
+        enabled: boolean;
+        showDropzone: boolean;
+        global: boolean;
+        preventDocumentDrop: boolean;
+    };
+    accept?: string | string[];
+    multiple: boolean;
+    maxCount?: number;
+    showButton: boolean;
+    buttonLabel: string;
+};
+export declare function themeColorsToCssVars(colors: Required<UploadThemeColors>): Record<string, string>;
+export declare const BTN_BASE = "inline-flex items-center justify-center border-none cursor-pointer p-0 transition-[background,opacity,transform,color,box-shadow] duration-150 hover:opacity-85 active:scale-95";
+export declare const CARD_BASE = "relative w-full overflow-hidden rounded-2xl font-sans bg-[var(--upload-card-bg)] shadow-[var(--upload-card-shadow)]";

package/dist/components/upload/hooks/useMockUpload.d.ts

@@ -0,0 +1,15 @@
+import type { UploadStatus } from '../interface';
+interface UseMockUploadOptions {
+    file: File;
+    speed?: number;
+    onComplete?: () => void;
+}
+interface UseMockUploadReturn {
+    status: UploadStatus;
+    progress: number;
+    pause: () => void;
+    resume: () => void;
+    cancel: () => void;
+}
+export declare function useMockUpload({ file, speed, onComplete, }: UseMockUploadOptions): UseMockUploadReturn;
+export {};

package/dist/components/upload/hooks/useUpload.d.ts

@@ -0,0 +1,9 @@
+import type { UploadStatus, UseUploadOptions } from '../interface';
+export interface UseUploadReturn {
+    status: UploadStatus;
+    progress: number;
+    error: string | null;
+    cancel: () => void;
+    retry: () => void;
+}
+export declare function useUpload({ file, url, method, fieldName, headers, withCredentials, extraFields, onComplete, onError, }: UseUploadOptions): UseUploadReturn;

package/dist/components/upload/hooks/useUploadDisplay.d.ts

@@ -0,0 +1,34 @@
+import type { UploadStatus, UploadThemeColors } from '../interface';
+interface UseUploadDisplayOptions {
+    file: File;
+    status: UploadStatus;
+    progress: number;
+    progressInset: number;
+    errorMessage?: string;
+    colors: Required<UploadThemeColors>;
+    labels: {
+        uploading: (percent: number) => string;
+        paused: (percent: number) => string;
+        completed: string;
+        error: string | ((message?: string) => string);
+    };
+}
+export declare function useUploadDisplay({ file, status, progress, progressInset, errorMessage, colors, labels, }: UseUploadDisplayOptions): {
+    displayPct: number;
+    isActive: boolean;
+    progressWidth: string;
+    bgProgressStyle: {
+        width: string;
+        background: string;
+    };
+    progressFillStyle: {
+        width: string;
+        background: string;
+    };
+    statusText: string;
+    sizeText: string;
+    statusColor: string;
+    progressInsetPx: number;
+    showProgressGlow: boolean;
+};
+export {};

package/dist/components/upload/hooks/useUploadDragDrop.d.ts

@@ -0,0 +1,22 @@
+interface UseUploadDragDropOptions {
+    enabled: boolean;
+    global?: boolean;
+    preventDocumentDrop?: boolean;
+    disabled?: boolean;
+    onDropFiles: (files: File[]) => void;
+}
+export declare function useUploadDragDrop({ enabled, global, preventDocumentDrop, disabled, onDropFiles, }: UseUploadDragDropOptions): {
+    isDragging: boolean;
+    dropHandlers: {
+        onDragEnter: (event: React.DragEvent) => void;
+        onDragLeave: (event: React.DragEvent) => void;
+        onDragOver: (event: React.DragEvent) => void;
+        onDrop: (event: React.DragEvent) => void;
+    } | {
+        onDragEnter?: undefined;
+        onDragLeave?: undefined;
+        onDragOver?: undefined;
+        onDrop?: undefined;
+    };
+};
+export {};

package/dist/components/upload/hooks/useUploadPicker.d.ts

@@ -0,0 +1,17 @@
+import type { UploadPickerConfig, UploadRejectReason } from '../interface';
+interface UseUploadPickerOptions {
+    config?: UploadPickerConfig;
+    currentCount?: number;
+    onFilesSelected: (files: File[]) => void;
+    onReject?: (reason: UploadRejectReason, files: File[]) => void;
+}
+export declare function useUploadPicker({ config, currentCount, onFilesSelected, onReject, }: UseUploadPickerOptions): {
+    accept: string | undefined;
+    multiple: boolean;
+    labels: {
+        maxCountExceeded: (max: number) => string;
+        invalidFormat: (filename: string) => string;
+    };
+    processFiles: (fileList: FileList | File[]) => void;
+};
+export {};

package/dist/components/upload/icons.d.ts

@@ -0,0 +1,10 @@
+interface IconProps {
+    className?: string;
+}
+export declare function PauseIcon({ className }: IconProps): import("react").JSX.Element;
+export declare function PlayIcon({ className }: IconProps): import("react").JSX.Element;
+export declare function CloseIcon({ className }: IconProps): import("react").JSX.Element;
+export declare function TrashIcon({ className }: IconProps): import("react").JSX.Element;
+export declare function CheckIcon({ className }: IconProps): import("react").JSX.Element;
+export declare function RetryIcon({ className }: IconProps): import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,26 @@
+import { Upload as InternalUpload } from './Upload';
+import { Dropzone } from './Dropzone';
+import { Picker } from './Picker';
+import { MockUpload } from './MockUpload';
+import { UploadRequest } from './UploadRequest';
+export { UploadActions } from './UploadActions';
+export { FileTypeIcon } from './FileTypeIcon';
+export { Dropzone, Dropzone as UploadDropzone };
+export { Picker, Picker as UploadPicker };
+export { MockUpload, MockUpload as UploadWithMock };
+export { UploadRequest, UploadRequest as UploadWithUpload };
+export { useMockUpload } from './hooks/useMockUpload';
+export { useUpload } from './hooks/useUpload';
+export type { UseUploadReturn } from './hooks/useUpload';
+export { useUploadDisplay } from './hooks/useUploadDisplay';
+export { useUploadDragDrop } from './hooks/useUploadDragDrop';
+export { useUploadPicker } from './hooks/useUploadPicker';
+export { DARK_THEME_COLORS, DEFAULT_DROPZONE_STYLE, DEFAULT_DRAG_CONFIG, DEFAULT_PICKER_CONFIG, DEFAULT_UPLOAD_CONFIG, LIGHT_THEME_COLORS, resolveUploadConfig, resolveUploadPickerConfig, } from './config';
+export { applyMaxCount, filterAcceptedFiles, isFileAccepted, normalizeAccept, } from './utils/fileAccept';
+export type { CompletedVariant, UploadCallbacks, UploadConfig, UploadLabels, UploadDropzoneLabels, UploadDropzoneStyle, UploadPickerConfig, UploadPickerDragConfig, UploadPickerLabels, UploadPickerProps, UploadProps, UploadRejectReason, UploadStatus, UploadTheme, UploadThemeColors, UploadWithMockProps, UploadWithUploadProps, UseUploadOptions, } from './interface';
+export { cn, formatBytes, getFileExtension } from './utils';
+type UploadComponent = typeof InternalUpload & {
+    Dropzone: typeof Dropzone;
+    Picker: typeof Picker;
+};
+export declare const Upload: UploadComponent;

package/dist/components/upload/interface.d.ts

@@ -0,0 +1,237 @@
+import type { ReactNode } from 'react';
+export type UploadStatus = 'uploading' | 'paused' | 'completed' | 'error';
+export type CompletedVariant = 'compact' | 'expanded';
+export type UploadTheme = 'dark' | 'light';
+export interface UploadThemeColors {
+    /** 卡片背景 */
+    cardBackground?: string;
+    /** 卡片阴影 */
+    cardShadow?: string;
+    /** 文件名 */
+    fileName?: string;
+    /** 上传中状态文字 */
+    statusUploading?: string;
+    /** 暂停状态文字 */
+    statusPaused?: string;
+    /** 失败状态文字 */
+    statusError?: string;
+    /** 完成状态文字 */
+    statusCompleted?: string;
+    /** 次要信息（文件大小等） */
+    metaMuted?: string;
+    /** 分隔符 */
+    metaSeparator?: string;
+    /** 底部进度条轨道 */
+    progressTrack?: string;
+    /** 背景进度渐变 */
+    progressBackground?: string;
+    /** 底部进度条填充渐变 */
+    progressFill?: string;
+    /** 进度条发光色（rgba） */
+    progressGlow?: string;
+    /** 圆形操作按钮背景 */
+    iconButtonBackground?: string;
+    /** 圆形操作按钮 hover */
+    iconButtonHover?: string;
+    /** 圆形操作按钮文字 */
+    iconButtonText?: string;
+    /** 关闭/取消按钮文字 */
+    closeButtonText?: string;
+    /** 关闭/取消按钮 hover 文字 */
+    closeButtonHover?: string;
+    /** 删除按钮背景 */
+    deleteButtonBackground?: string;
+    /** 删除按钮文字 */
+    deleteButtonText?: string;
+    /** 删除按钮 hover 背景 */
+    deleteButtonHoverBackground?: string;
+    /** 删除按钮 hover 文字 */
+    deleteButtonHoverText?: string;
+    /** 删除按钮阴影 */
+    deleteButtonShadow?: string;
+    /** 删除按钮 hover 阴影 */
+    deleteButtonHoverShadow?: string;
+    /** 完成勾选徽章背景 */
+    successBadgeBackground?: string;
+    /** expanded 态 Change 按钮背景 */
+    changeButtonBackground?: string;
+    changeButtonHover?: string;
+    changeButtonText?: string;
+    /** expanded 态 Download 按钮背景 */
+    downloadButtonBackground?: string;
+    downloadButtonHover?: string;
+    downloadButtonText?: string;
+}
+export interface UploadLabels {
+    uploading?: (percent: number) => string;
+    paused?: (percent: number) => string;
+    completed?: string;
+    error?: string | ((message?: string) => string);
+    change?: string;
+    download?: string;
+    retry?: string;
+}
+export interface UploadConfig {
+    /** 主题：light 浅色（默认）| dark 深色 */
+    theme?: UploadTheme;
+    /** 覆盖主题预设颜色 */
+    colors?: UploadThemeColors;
+    /** 底部进度条左右内边距；背景进度左贴边，右边缘与线条对齐 */
+    progressInset?: number;
+    /** 卡片最大宽度，默认 480 */
+    maxWidth?: number;
+    /** 是否显示底部进度条 */
+    showProgressBar?: boolean;
+    /** 是否显示背景进度渐变 */
+    showBackgroundProgress?: boolean;
+    /** 是否允许暂停/恢复（真实上传无断点续传时应设为 false） */
+    pausable?: boolean;
+    /** 是否允许取消 */
+    cancelable?: boolean;
+    /** 是否允许删除 */
+    deletable?: boolean;
+    /** 失败时是否显示重试按钮 */
+    retryable?: boolean;
+    /** 文案配置 */
+    labels?: UploadLabels;
+}
+export interface UploadPickerLabels {
+    maxCountExceeded?: (max: number) => string;
+    invalidFormat?: (filename: string) => string;
+}
+export interface UploadDropzoneLabels {
+    /** 默认提示 */
+    hint?: string;
+    /** 拖拽悬停提示 */
+    hintActive?: string;
+    /** 禁用态提示 */
+    hintDisabled?: string;
+    /** 点击选择补充文案 */
+    clickHint?: string;
+}
+export interface UploadDropzoneStyle {
+    borderColor?: string;
+    borderColorActive?: string;
+    borderColorDisabled?: string;
+    background?: string;
+    backgroundActive?: string;
+    textColor?: string;
+    textColorActive?: string;
+    textColorDisabled?: string;
+    minHeight?: number;
+    borderRadius?: number;
+}
+export interface UploadPickerDragConfig {
+    /** 是否启用拖拽上传，默认 false */
+    enabled?: boolean;
+    /** 是否渲染内置拖拽投放区，默认 true（enabled 时） */
+    showDropzone?: boolean;
+    /** 是否在 document 级别监听拖拽（整页投放），默认 false */
+    global?: boolean;
+    /** 阻止浏览器默认打开拖拽文件，默认 true */
+    preventDocumentDrop?: boolean;
+    /** 投放区文案 */
+    labels?: UploadDropzoneLabels;
+    /** 投放区样式 */
+    style?: UploadDropzoneStyle;
+}
+export interface UploadPickerConfig {
+    /** 主题：light 浅色（默认）| dark 深色 */
+    theme?: UploadTheme;
+    /** 允许的文件格式，如 `.xlsx`、`.pdf` 或 MIME `image/*` */
+    accept?: string | string[];
+    /** 是否允许多选，默认 false */
+    multiple?: boolean;
+    /** 最多上传数量（含已选列表），不设则不限制 */
+    maxCount?: number;
+    /** 是否显示「选择文件」按钮，可与拖拽投放区同时存在，默认 true */
+    showButton?: boolean;
+    /** 选择按钮文案 */
+    buttonLabel?: string;
+    /** 校验失败文案 */
+    labels?: UploadPickerLabels;
+    /** 拖拽上传配置 */
+    drag?: UploadPickerDragConfig;
+}
+export type UploadRejectReason = 'max-count' | 'invalid-format';
+export interface UploadCallbacks {
+    onPause?: () => void;
+    onResume?: () => void;
+    onCancel?: () => void;
+    onDelete?: () => void;
+    onChange?: () => void;
+    onDownload?: () => void;
+    onRetry?: () => void;
+}
+export interface UploadProps extends UploadCallbacks {
+    file: File;
+    status?: UploadStatus;
+    progress?: number;
+    errorMessage?: string;
+    completedVariant?: CompletedVariant;
+    config?: UploadConfig;
+    className?: string;
+    exiting?: boolean;
+}
+export interface UploadWithMockProps extends UploadCallbacks {
+    file: File;
+    completedVariant?: CompletedVariant;
+    config?: UploadConfig;
+    speed?: number;
+    onComplete?: () => void;
+    className?: string;
+}
+export interface UseUploadOptions {
+    file: File;
+    url: string;
+    method?: 'POST' | 'PUT';
+    fieldName?: string;
+    headers?: Record<string, string>;
+    withCredentials?: boolean;
+    extraFields?: Record<string, string>;
+    onComplete?: (response: XMLHttpRequest) => void;
+    onError?: (error: Error) => void;
+}
+export interface UploadWithUploadProps extends UploadCallbacks {
+    file: File;
+    url: string;
+    method?: 'POST' | 'PUT';
+    fieldName?: string;
+    headers?: Record<string, string>;
+    withCredentials?: boolean;
+    extraFields?: Record<string, string>;
+    completedVariant?: CompletedVariant;
+    config?: UploadConfig;
+    onComplete?: (response: XMLHttpRequest) => void;
+    onError?: (error: Error) => void;
+    className?: string;
+}
+export interface UploadPickerProps {
+    config?: UploadPickerConfig;
+    /** 当前已选文件数，用于 maxCount 校验 */
+    currentCount?: number;
+    onFilesSelected: (files: File[]) => void;
+    onReject?: (reason: UploadRejectReason, files: File[]) => void;
+    disabled?: boolean;
+    className?: string;
+    /** 选择按钮 className */
+    buttonClassName?: string;
+    /** 拖拽投放区容器 className */
+    dropzoneClassName?: string;
+    /** 默认布局容器 className（按钮 + 投放区） */
+    wrapperClassName?: string;
+    /** 自定义布局；可通过 button / dropzone 分别放置 */
+    children?: (api: {
+        open: () => void;
+        disabled: boolean;
+        isDragging: boolean;
+        dropHandlers: {
+            onDragEnter?: (event: React.DragEvent) => void;
+            onDragLeave?: (event: React.DragEvent) => void;
+            onDragOver?: (event: React.DragEvent) => void;
+            onDrop?: (event: React.DragEvent) => void;
+        };
+        button: ReactNode;
+        dropzone: ReactNode | null;
+    }) => ReactNode;
+}