@react-md/form/types/file-input/useFileUpload.d.ts

This package is for creating all the different form input types.

import type { FileUploadHandlers, FileUploadStats, FileValidationError, FilesValidator, GetFileParser, FileValidationOptions } from "./utils";
/**
 *
 * @typeParam CustomError - An optional error type that gets returned from the
 * {@link FilesValidator}.
 * @remarks \@since 2.9.0
 */
export interface FileUploadState<CustomError = never> {
    /**
     * All the files that have been validated and are either:
     * - pending upload
     * - uploading
     * - complete
     *
     * Each key in this object is the {@link BaseFileUploadStats.key} generated
     * once the upload starts pending.
     */
    stats: Readonly<Record<string, Readonly<FileUploadStats>>>;
    /**
     * A list of validation errors that have occurred before starting the upload
     * process.
     *
     * @see {@link FileAccessError}
     * @see {@link TooManyFilesError}
     * @see {@link FileValidationError}
     */
    errors: readonly FileValidationError<CustomError>[];
}
/**
 *
 * @typeParam CustomError - An optional error type that gets returned from the
 * {@link FilesValidator}.
 * @remarks \@since 2.9.0
 * @internal
 */
export interface FileUploadHookState<CustomError = never> extends FileUploadState<CustomError> {
    /**
     * All the current readers used for uploading files to the browser.
     *
     * Note: Once an upload has completed, the reader will be removed.
     */
    readers: Readonly<Record<string, FileReader>>;
}
/**
 *
 * @typeParam E - An optional HTMLElement type that is used for the
 * {@link FileUploadHandlers}.
 * @typeParam CustomError - An optional error type that gets returned from the
 * {@link FilesValidator}.
 * @remarks \@since 2.9.0
 */
export interface FileUploadOptions<E extends HTMLElement, CustomError = never> extends FileUploadHandlers<E>, FileValidationOptions {
    /**
     * Setting this value to a number greater than `0` will update the browser
     * upload process to queue the uploads in chunks instead of all at once. This
     * can help prevent the browser from freezing if dealing with large files that
     * are being converted to data urls.
     *
     * @defaultValue `-1`
     */
    concurrency?: number;
    /** {@inheritDoc FilesValidator} */
    validateFiles?: FilesValidator<CustomError>;
    /** {@inheritDoc GetFileParser} */
    getFileParser?: GetFileParser;
}
/** @remarks \@since 2.9.0 */
export interface FileUploadActions {
    /**
     * Reset everything related to uploads ensuring that all file readers have
     * been aborted.
     */
    reset(): void;
    /**
     * Removes all the errors that exist in state without cancelling any of the
     * uploads already in progress.
     */
    clearErrors(): void;
    /**
     * This function is used to cancel pending and uploading files or removing
     * completed files.
     *
     * @param keyOrKeys - A single or list of {@link BaseFileUploadStats.key} to
     * remove from state.
     */
    remove(keyOrKeys: string | readonly string[]): void;
}
/**
 *
 * @typeParam E - An optional HTMLElement type that is used for the
 * {@link FileUploadHandlers}.
 * @typeParam CustomError - An optional error type that gets returned from the
 * {@link FilesValidator}.
 * @remarks \@since 2.9.0
 */
export interface FileUploadHookReturnValue<E extends HTMLElement = HTMLElement, CustomError = never> extends FileUploadActions, Required<FileUploadHandlers<E>> {
    /** {@inheritDoc FileUploadState.errors} */
    errors: readonly FileValidationError<CustomError>[];
    /**
     * A list of all the {@link FileUploadStats}.
     *
     * @see {@link getSplitFileUploads} for separating by status
     */
    stats: readonly Readonly<FileUploadStats>[];
    /**
     * The total number of bytes for all the files that exist in the
     * {@link stats} list.
     */
    totalBytes: number;
    /**
     * The total number of files in the {@link stats} list.
     */
    totalFiles: number;
    /**
     * An `accept` string that can be passed to the {@link FileInput} component
     * when the {@link FileValidationOptions.extensions} list has been provided to
     * limit which files the OS will _attempt_ to allow access to.
     *
     * @example
     * Simple example
     * ```ts
     * const extensions = ['pdf', 'docx', 'ppt'];
     * const { accept } = useFileUpload({ extensions, ...others });
     *
     * expect(accept).toBe("*.pdf,*.docx,*.ppt")
     * ```
     *
     * @defaultValue `"*"`
     */
    accept: string;
}
/**
 * This hook is generally used to upload files **to the browser** in different
 * formats to be previewed `<img>`, `<video>`, `<embed>`, etc tags. However, it
 * can also be used to upload the files as an `ArrayBuffer` and then uploaded to
 * a server.
 *
 * Note: If using the `aws-sdk` to upload files directly to S3, **do not use
 * this hook** since it uses its own upload process.
 *
 * @typeParam E - An optional HTMLElement type that is used for the
 * {@link FileUploadHandlers}.
 * @typeParam CustomError - An optional error type that gets returned from the
 * {@link FilesValidator}.
 * @param options - All the {@link FileUploadOptions}
 * @returns the {@link FileUploadHookReturnValue}
 * @remarks \@since 2.9.0
 */
export declare function useFileUpload<E extends HTMLElement, CustomError = never>({ maxFiles, extensions, minFileSize, maxFileSize, totalFileSize, concurrency, onDrop: propOnDrop, onChange: propOnChange, validateFiles, getFileParser, isValidFileName, }?: FileUploadOptions<E, CustomError>): Readonly<FileUploadHookReturnValue<E, CustomError>>;