react-upload-pro 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,377 @@
+import { c as DropzoneOptions, f as UploadFile, F as FileMetadata, d as DropzoneState, l as ValidationError, V as ValidationConfig, T as Theme, L as Locale, e as Translations } from './types-BDyFUrlv.js';
+export { A as Accept, C as ChunkState, a as CloudAdapter, b as CloudUploadResult, D as DropzoneCallbacks, U as UploadError, g as UploadMode, h as UploadStatus, i as UploadStrategy, j as UploadTokenPayload, k as UploaderConfig, m as ValidationErrorCode } from './types-BDyFUrlv.js';
+import { c as UseDropzoneReturn, P as ProgressVariant } from './UploadProgress-uRdhENqW.js';
+export { I as InputProps, R as RootProps, U as UploadProgress, a as UploadProgressProps, b as UploadQueue, d as UseUploadQueueOptions, e as UseUploadQueueReturn, u as useDropzone, f as useUploadQueue } from './UploadProgress-uRdhENqW.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { HTMLAttributes, ReactNode, ButtonHTMLAttributes, SVGProps } from 'react';
+import { ClassValue } from 'clsx';
+
+type UseUploaderOptions = DropzoneOptions;
+type UseUploaderReturn = UseDropzoneReturn;
+/**
+ * Alias of useDropzone with an `auto` mode default. Useful when the user
+ * wants files to upload immediately on selection (no separate "Upload" button).
+ */
+declare function useUploader(options?: UseUploaderOptions): UseUploaderReturn;
+
+interface AggregateProgress {
+    total: number;
+    uploaded: number;
+    progress: number;
+    speed: number;
+    eta: number;
+    uploading: number;
+    completed: number;
+    errored: number;
+    pending: number;
+}
+/** Aggregate progress across a list of files. Pure function — no state. */
+declare function useUploadProgress(files: UploadFile[]): AggregateProgress;
+
+type PreviewKind = 'image' | 'video' | 'audio' | 'pdf' | 'text' | 'office' | 'archive' | 'other';
+interface FilePreview {
+    kind: PreviewKind;
+    url?: string;
+    /** For text files: first ~64KB as a string. */
+    text?: string;
+    /** Loading state. */
+    loading: boolean;
+    /** Any error encountered while building the preview. */
+    error?: string;
+}
+/**
+ * Lazy preview builder. For images/video/audio/pdf it returns the existing
+ * object URL; for text files it reads up to 64KB; office files return kind
+ * only (consumers can render a generic icon or call a server-side renderer).
+ */
+declare function useFilePreview(file: UploadFile | null | undefined): FilePreview;
+
+type DivAttrs$1 = Omit<HTMLAttributes<HTMLDivElement>, 'onPause' | 'onResume' | 'onAbort'>;
+interface UploadPreviewProps extends DivAttrs$1 {
+    file: UploadFile;
+    /** Layout density. */
+    density?: 'compact' | 'comfortable' | 'card';
+    /** Show speed + ETA while uploading. */
+    showStats?: boolean;
+    /** Show thumbnail for images/video. */
+    showThumb?: boolean;
+    /** Override the progress visual style. */
+    progressVariant?: ProgressVariant;
+    /** Override progress bar height (px) or circle diameter (px). */
+    progressSize?: number;
+    onRetry?: (file: UploadFile) => void;
+    onPause?: (file: UploadFile) => void;
+    onResume?: (file: UploadFile) => void;
+    onCancel?: (file: UploadFile) => void;
+    onRemove?: (file: UploadFile) => void;
+    onPreview?: (file: UploadFile) => void;
+    onDownload?: (file: UploadFile) => void;
+    onEdit?: (file: UploadFile) => void;
+}
+/**
+ * A single row/card representing one file. Used as the building block of
+ * UploadGallery and most variants.
+ */
+declare function UploadPreview({ file, density, showStats, showThumb, progressVariant, progressSize, className, onRetry, onPause, onResume, onCancel, onRemove, onPreview, onDownload, onEdit, ...rest }: UploadPreviewProps): react_jsx_runtime.JSX.Element;
+
+type GalleryLayout = 'list' | 'grid' | 'table' | 'compact';
+type DivAttrs = Omit<HTMLAttributes<HTMLDivElement>, 'onSelect' | 'onPause' | 'onResume' | 'onAbort'>;
+interface UploadGalleryProps extends DivAttrs, Omit<UploadPreviewProps, 'file'> {
+    files: UploadFile[];
+    layout?: GalleryLayout;
+    /** Allow drag-to-reorder. Requires onReorder. */
+    reorderable?: boolean;
+    onReorder?: (from: number, to: number) => void;
+    /** Allow free-text search by filename. */
+    searchable?: boolean;
+    /** Allow status filter chips. */
+    filterable?: boolean;
+    /**
+     * Enable the built-in fullscreen preview modal (images / video / pdf / text).
+     * Adds an eye icon to each row. Has no effect if a custom `onPreview` is passed.
+     */
+    previewable?: boolean;
+    /**
+     * Enable the built-in edit modal (rename + metadata). Adds a pencil icon.
+     * Has no effect if a custom `onEdit` is passed.
+     *
+     * If `onRename` / `onMetadataChange` are provided, they're called on save.
+     */
+    editable?: boolean;
+    /** Called when the edit modal renames a file. */
+    onRename?: (file: UploadFile, newName: string) => void;
+    /** Called when the edit modal saves metadata. */
+    onMetadataChange?: (file: UploadFile, metadata: FileMetadata) => void;
+    /**
+     * When the visible file count exceeds this threshold, the file list becomes
+     * a scrollable region with the height set by `maxHeight` (default ~3 rows).
+     * Set to 0 to disable. Recommended for long lists so the page doesn't grow
+     * unbounded.
+     */
+    scrollAfter?: number;
+    /**
+     * Max CSS height for the scrollable list region. Used together with
+     * `scrollAfter`. Accepts any valid CSS value ('280px', '24rem', '40vh').
+     * Default: '280px' (≈ 3 comfortable rows).
+     */
+    maxHeight?: string;
+    emptyState?: React.ReactNode;
+}
+/**
+ * Renders a list of files using one of several layouts. Search/filter/sort
+ * are built-in. Drag-to-reorder is opt-in. When `previewable` or `editable`
+ * is set, the gallery also manages the corresponding modals — pass through
+ * `onRename` / `onMetadataChange` to persist the changes.
+ */
+declare function UploadGallery({ files, layout, reorderable, onReorder, searchable, filterable, previewable, editable, onRename, onMetadataChange, scrollAfter, maxHeight, emptyState, className, density, showStats, showThumb, progressVariant, progressSize, onRetry, onPause, onResume, onCancel, onRemove, onPreview, onDownload, onEdit, ...rest }: UploadGalleryProps): react_jsx_runtime.JSX.Element;
+
+interface DropzoneProps extends DropzoneOptions {
+    /** Render-prop API for full control. */
+    children?: (api: UseDropzoneReturn) => ReactNode;
+    /** Hide the built-in file list. Default false. */
+    hideGallery?: boolean;
+    /** Layout of the built-in gallery. Default 'list'. */
+    galleryLayout?: GalleryLayout;
+    /** Pick a progress visualization. */
+    progressVariant?: ProgressVariant;
+    /** Progress bar height (px) or circle diameter (px). */
+    progressSize?: number;
+    /** Enable the built-in fullscreen preview modal. */
+    previewable?: boolean;
+    /** Enable the built-in edit modal (rename + tags + metadata). */
+    editable?: boolean;
+    /** Called when the edit modal renames a file. Defaults to queue.rename. */
+    onRename?: (file: UploadFile, newName: string) => void;
+    /** Called when the edit modal saves metadata. Defaults to queue.setMetadata. */
+    onMetadataChange?: (file: UploadFile, metadata: FileMetadata) => void;
+    /** Once the file list exceeds this count, the list becomes scrollable. 0 = off. */
+    scrollAfter?: number;
+    /** Max CSS height for the scroll region. Default '280px'. */
+    maxHeight?: string;
+    /** Outer container width (any CSS value). */
+    width?: string;
+    /** Outer container height (any CSS value). */
+    height?: string;
+    /** Extra inline style merged onto the outer container. */
+    style?: React.CSSProperties;
+    className?: string;
+    /** Hint text under the icon. */
+    hint?: ReactNode;
+}
+/**
+ * The all-in-one drop-in component. For simple cases this is all you need.
+ * For more control, pass `children` as a render-prop.
+ *
+ *   <Dropzone endpoint="/upload" maxSize={5e6} previewable editable>
+ *     {({ getRootProps, getInputProps }) => (
+ *       <div {...getRootProps()}>...</div>
+ *     )}
+ *   </Dropzone>
+ */
+declare function Dropzone({ children, hideGallery, galleryLayout, progressVariant, progressSize, previewable, editable, onRename, onMetadataChange, scrollAfter, maxHeight, width, height, style, className, hint, ...options }: DropzoneProps): react_jsx_runtime.JSX.Element;
+
+interface UploadAreaProps extends HTMLAttributes<HTMLDivElement> {
+    state?: DropzoneState;
+    disabled?: boolean;
+    /** Replaces the default label content. */
+    children?: ReactNode;
+    /** Icon override. */
+    icon?: ReactNode;
+    /** Secondary descriptive line. */
+    description?: ReactNode;
+}
+/**
+ * The visual "drop here" surface, separated from the dropzone logic so users
+ * can drop it into any container that spreads getRootProps().
+ */
+declare function UploadArea({ state, disabled, children, icon, description, className, ...rest }: UploadAreaProps): react_jsx_runtime.JSX.Element;
+
+type ButtonAttrs = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onDrop' | 'onPause' | 'onResume' | 'onAbort'>;
+interface UploadButtonProps extends ButtonAttrs, DropzoneOptions {
+    /** Visual variant. */
+    variant?: 'primary' | 'secondary' | 'ghost' | 'outline';
+    /** Show the upload icon. */
+    icon?: ReactNode;
+    /** Hide the icon entirely. */
+    iconOnly?: boolean;
+}
+/**
+ * Standalone button that opens the file picker. Internally uses useDropzone
+ * with `noBubble` so nesting inside another dropzone is safe.
+ */
+declare function UploadButton({ variant, icon, iconOnly, children, className, disabled, multiple, directory, clipboard, accept, minSize, maxSize, maxFiles, rejectDuplicates, validators, onDrop, onDropAccepted, onDropRejected, onUploadStart, onUploadProgress, onUploadSuccess, onUploadError, onRetry, onPause, onResume, onRemove, onAllComplete, endpoint, method, headers, fieldName, formData, withCredentials, concurrency, strategy, mode, retries, retryBackoffMs, chunkSize, cloud, getUploadToken, virusScan, ...buttonProps }: UploadButtonProps): react_jsx_runtime.JSX.Element;
+
+interface UploadModalProps {
+    open: boolean;
+    onClose: () => void;
+    title?: ReactNode;
+    description?: ReactNode;
+    /** Children render inside the modal body. Typically a <Dropzone /> + gallery. */
+    children: ReactNode;
+    /** Wider modal for galleries. */
+    size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+    /** Hide the close button. */
+    hideClose?: boolean;
+    className?: string;
+}
+/**
+ * SSR-safe modal with a backdrop, ESC-to-close, focus trap (basic), and
+ * scroll lock. Mounted via React portal to document.body when available;
+ * renders nothing on the server.
+ */
+declare function UploadModal({ open, onClose, title, description, children, size, hideClose, className, }: UploadModalProps): react_jsx_runtime.JSX.Element | null;
+
+interface FilePreviewModalProps {
+    file: UploadFile | null;
+    onClose: () => void;
+    /** Override download handler. By default, triggers a browser download of the local File. */
+    onDownload?: (file: UploadFile) => void;
+}
+/**
+ * Full-screen preview modal supporting images (with zoom/rotate), videos,
+ * audio, PDFs (iframe), and text files. Office files fall back to a generic
+ * "open in new tab" affordance because rendering DOCX/XLSX/PPTX client-side
+ * is out of scope for this library.
+ */
+declare function FilePreviewModal({ file, onClose, onDownload }: FilePreviewModalProps): react_jsx_runtime.JSX.Element;
+
+interface FileEditModalProps {
+    file: UploadFile | null;
+    onClose: () => void;
+    /** Persist a new name (rename). */
+    onRename?: (file: UploadFile, newName: string) => void;
+    /** Persist metadata (tags / category / description / custom fields). */
+    onSave?: (file: UploadFile, metadata: FileMetadata) => void;
+}
+/**
+ * Modal for editing a single file's name + metadata. Drives the library's
+ * built-in `rename()` / `setMetadata()` queue methods when wired through
+ * UploadGallery, but the form itself is presentational — pass `onRename` /
+ * `onSave` to integrate with your own state.
+ */
+declare function FileEditModal({ file, onClose, onRename, onSave }: FileEditModalProps): react_jsx_runtime.JSX.Element;
+
+interface ValidationErrorsModalProps {
+    open: boolean;
+    errors: ValidationError[];
+    onClose: () => void;
+    /** Modal title override. Default uses the localized "Failed" string. */
+    title?: React.ReactNode;
+}
+/**
+ * Shows validation rejections (wrong type, too large, too many, …) in a modal.
+ * Use together with the `onDropRejected` callback or by reading
+ * `api.rejected` from `useDropzone`.
+ *
+ *   const [errors, setErrors] = useState<ValidationError[]>([]);
+ *   <Dropzone accept="image/*" onDropRejected={setErrors} />
+ *   <ValidationErrorsModal open={errors.length > 0} errors={errors} onClose={() => setErrors([])} />
+ */
+declare function ValidationErrorsModal({ open, errors, onClose, title, }: ValidationErrorsModalProps): react_jsx_runtime.JSX.Element | null;
+
+declare const UploadIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const FileIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const ImageIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const TrashIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const PauseIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const PlayIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const RetryIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const CheckIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const AlertIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const CloseIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const DownloadIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const EyeIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const FolderIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const EditIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const MaximizeIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+declare const TagIcon: (p: SVGProps<SVGSVGElement>) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Match a file's MIME / extension against a list of acceptors.
+ * Supports `image/*` wildcards and `.ext` entries.
+ */
+declare function matchesAccept(file: File, acceptors: string[]): boolean;
+/**
+ * Full single-file validation including custom async validators.
+ */
+declare function validateFile(file: File, config: ValidationConfig): Promise<ValidationError | null>;
+/**
+ * Validate a batch of files. Applies built-in rules first, then maxFiles,
+ * then duplicate detection, then async validators. Returns accepted + rejected.
+ */
+declare function validateBatch(files: File[], config: ValidationConfig, existingCount?: number, existingKeys?: Set<string>): Promise<{
+    accepted: File[];
+    rejected: ValidationError[];
+}>;
+
+interface ThemeContextValue {
+    theme: Theme;
+    resolved: 'light' | 'dark';
+    setTheme: (theme: Theme) => void;
+}
+interface ThemeProviderProps {
+    /** Initial theme. Default 'auto'. */
+    defaultTheme?: Theme;
+    /** Override of resolved theme; useful for controlled mode. */
+    theme?: Theme;
+    /** Called when the user toggles the theme. */
+    onThemeChange?: (theme: Theme) => void;
+    children: ReactNode;
+}
+/**
+ * Wraps children in a theme context and applies a data-theme attribute to the
+ * scope so CSS variables can switch values. SSR-safe: `resolved` defaults to
+ * 'light' on the server and reconciles after hydration.
+ */
+declare function ThemeProvider({ defaultTheme, theme: controlled, onThemeChange, children, }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
+declare function useTheme(): ThemeContextValue;
+
+interface I18nContextValue {
+    locale: Locale;
+    t: Translations;
+    isRtl: boolean;
+}
+interface I18nProviderProps {
+    locale?: Locale;
+    /** Override or extend translations for the active locale. */
+    messages?: Partial<Translations>;
+    children: ReactNode;
+}
+declare function I18nProvider({ locale, messages, children }: I18nProviderProps): react_jsx_runtime.JSX.Element;
+declare function useI18n(): I18nContextValue;
+
+declare const translations: Record<Locale, Translations>;
+declare const rtlLocales: ReadonlySet<Locale>;
+
+/** Combine Tailwind classes safely (resolves conflicts). */
+declare function cn(...inputs: ClassValue[]): string;
+
+/** Convert a native File into an UploadFile. */
+declare function wrapFile(file: File, metadata?: FileMetadata): UploadFile;
+/**
+ * Create an object URL for previews. SSR-safe (returns undefined on server).
+ * Caller is responsible for revoking via revokePreview.
+ */
+declare function generatePreview(file: File): string | undefined;
+declare function revokePreview(url: string | undefined): void;
+/** Best-effort file category from MIME or extension. */
+declare function getFileCategory(file: File | UploadFile): 'image' | 'video' | 'audio' | 'pdf' | 'text' | 'office' | 'archive' | 'other';
+/**
+ * Read the first 16 bytes of a file to validate its magic-number signature.
+ * Returns the detected MIME type or null. Best-effort, not exhaustive.
+ *
+ * Uses a small dispatch because `Blob.arrayBuffer` isn't always available
+ * (e.g., in some jsdom versions) — we fall back to FileReader.
+ */
+declare function detectSignature(file: File): Promise<string | null>;
+
+/** Human-readable file size. */
+declare function formatBytes(bytes: number, decimals?: number): string;
+/** Human-readable bytes/sec. */
+declare function formatSpeed(bps: number): string;
+/** Human-readable ETA in seconds. */
+declare function formatEta(seconds: number): string;
+/** Format a percent (0..1). */
+declare function formatPercent(progress: number): string;
+
+export { type AggregateProgress, AlertIcon, CheckIcon, CloseIcon, DownloadIcon, Dropzone, DropzoneOptions, type DropzoneProps, DropzoneState, EditIcon, EyeIcon, FileEditModal, type FileEditModalProps, FileIcon, FileMetadata, type FilePreview, FilePreviewModal, type FilePreviewModalProps, FolderIcon, type GalleryLayout, I18nProvider, ImageIcon, Locale, MaximizeIcon, PauseIcon, PlayIcon, type PreviewKind, ProgressVariant, RetryIcon, TagIcon, Theme, ThemeProvider, Translations, TrashIcon, UploadArea, type UploadAreaProps, UploadButton, type UploadButtonProps, UploadFile, UploadGallery, type UploadGalleryProps, UploadIcon, UploadModal, type UploadModalProps, UploadPreview, type UploadPreviewProps, UseDropzoneReturn, type UseUploaderOptions, type UseUploaderReturn, ValidationConfig, ValidationError, ValidationErrorsModal, type ValidationErrorsModalProps, cn, detectSignature, formatBytes, formatEta, formatPercent, formatSpeed, generatePreview, getFileCategory, matchesAccept, revokePreview, rtlLocales, translations, useFilePreview, useI18n, useTheme, useUploadProgress, useUploader, validateBatch, validateFile, wrapFile };