@react-md/core 1.0.0-next.2 → 1.0.0-next.20

package/dist/files/utils.js

@@ -0,0 +1,144 @@
+/**
+ * This will first check if the mime-type of the file starts with `text/` and
+ * fallback to checking a few file names or extensions that should be considered
+ * text.
+ *
+ * This function is not guaranteed to be 100% correct and is only useful if
+ * trying to generate a preview of files uploaded to the browser.
+ *
+ * @param file - The file to check
+ * @returns `true` if the file should be considered as a text-content file.
+ * @since 2.9.0
+ */ export function isTextFile(file) {
+    return /\.((j|t)sx?|json|lock|hbs|ya?ml|log|txt|md)$/i.test(file.name);
+}
+/**
+ * This will first check if the mime-type of the file starts with `text\/` and
+ * fallback to checking a few file names or extensions that should be considered
+ * text.
+ *
+ * This function is not guaranteed to be 100% correct and is only useful if
+ * trying to generate a preview of files uploaded to the browser.
+ *
+ * @param file - The file to check
+ * @returns `true` if the file should be considered as a text content file.
+ * @since 2.9.0
+ */ export function isImageFile(file) {
+    return /\.(a?png|avif|svg|tiff|gifv?|jpe?g)/i.test(file.name);
+}
+/**
+ * This will first check if the mime-type of the file starts with `audio/` and
+ * fallback to checking a few file names or extensions that should be considered
+ * audio.
+ *
+ * This function is not guaranteed to be 100% correct and is only useful if
+ * trying to generate a preview of files uploaded to the browser.
+ *
+ * @param file - The file to check
+ * @returns `true` if the file should be considered as a audio content file.
+ * @since 2.9.0
+ */ export function isAudioFile(file) {
+    return /\.(mp3|wav|ogg|m4p|flac)$/i.test(file.name);
+}
+/**
+ * This will first check if the mime-type of the file starts with `video/` and
+ * fallback to checking a few file names or extensions that should be considered
+ * video.
+ *
+ * This function is not guaranteed to be 100% correct and is only useful if
+ * trying to generate a preview of files uploaded to the browser.
+ *
+ * @param file - The file to check
+ * @returns `true` if the file should be considered as a video content file.
+ * @since 2.9.0
+ */ export function isVideoFile(file) {
+    return /\.(mkv|mpe?g|mov|avi|flv|webm|mp4)$/i.test(file.name);
+}
+/**
+ * This function is not guaranteed to be 100% correct and is only useful if
+ * trying to generate a preview of files uploaded to the browser.
+ *
+ * @param file - The file to check
+ * @returns `true` if the file matches an image, audio, or video file.
+ * @since 2.9.0
+ */ export function isMediaFile(file) {
+    return isImageFile(file) || isAudioFile(file) || isVideoFile(file);
+}
+/**
+ * This function will attempt to read:
+ * - media (image, audio, and video) files as a data url so they can be
+ *   previewed in `<img>`, `<audio>`, and `<video>` tags
+ * - text files as plain text
+ * - everything else as an `ArrayBuffer` which can be manually converted into a
+ *   data url if needed with `URL.createObjectURL`
+ *
+ * @since 2.9.0
+ */ export const getFileParser = (file)=>{
+    if (isMediaFile(file)) {
+        return "readAsDataURL";
+    }
+    if (isTextFile(file)) {
+        return "readAsText";
+    }
+    return "readAsArrayBuffer";
+};
+/**
+ * This util will split all the current upload stats by status.
+ *
+ * @example Main Usage
+ * ```tsx
+ * import { FileUpload } from "@react-md/core/files/FileUpload";
+ * import { useFileUpload } from "@react-md/core/files/useFileUpload";
+ * import { getSplitFileUploads } from "@react-md/core/files/utils";
+ *
+ * function Example() {
+ *   const { stats, errors, accept, onChange } = useFileUpload();
+ *   const { pending, uploading, completed } = getSplitFileUploads(stats);
+ *
+ *   return (
+ *     <>
+ *       <FileUpload accept={accept} onChange={onChange} />
+ *       {pending.map(({ key, file, progress, status }) => {
+ *         // pretend some UI for each pending item with the provided data
+ *         return null;
+ *       })}
+ *       {uploading.map(({ file, key, progress, status }) => {
+ *         // pretend some UI for each uploading item with the provided data
+ *         return null;
+ *       })}
+ *       {complete.map(({ file, key, progress, result, status }) => {
+ *         // pretend some UI for each complete item with the provided data
+ *         return null;
+ *       })}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @param stats - The {@link FileUploadStats} list generally returned by the
+ * {@link useFileUpload} hook.
+ * @returns the {@link SplitFileUploads}.
+ * @since 2.9.0
+ */ export function getSplitFileUploads(stats) {
+    const pending = [];
+    const uploading = [];
+    const complete = [];
+    stats.forEach((stat)=>{
+        if (stat.status === "pending") {
+            pending.push(stat);
+        } else if (stat.status === "uploading") {
+            uploading.push(stat);
+        } else if (stat.status === "complete") {
+            complete.push(stat);
+        } else {
+            /* istanbul ignore next */ throw new Error("Invalid upload stat");
+        }
+    });
+    return {
+        pending,
+        uploading,
+        complete
+    };
+}
+
+//# sourceMappingURL=utils.js.map

package/dist/files/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/files/utils.ts"],"sourcesContent":["import { type ChangeEventHandler, type DragEventHandler } from \"react\";\n\n/** @since 2.9.0 */\nexport interface BaseFileUploadStats {\n  /**\n   * A unique key associated with each upload generated by `nanoid`.\n   */\n  key: string;\n\n  /**\n   * The file instance that is being uploaded.\n   */\n  file: File;\n\n  /**\n   * The current upload progress as a percentage from 0 - 100 percent.\n   */\n  progress: number;\n}\n\n/** @since 2.9.0 */\nexport interface ProcessingFileUploadStats extends BaseFileUploadStats {\n  status: \"pending\" | \"uploading\";\n}\n\n/** @since 2.9.0 */\nexport type FileReaderResult = FileReader[\"result\"];\n\n/** @since 2.9.0 */\nexport interface CompletedFileUploadStats extends BaseFileUploadStats {\n  status: \"complete\";\n\n  /**\n   * The result after a `FileReader` has read a file completely.\n   *\n   * Note: This _should_ be an `ArrayBuffer` if the next step is to upload to a\n   * server.\n   *\n   * @see {@link FileReaderParser}\n   * @see {@link getFileParser}\n   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileReader | FileReader}\n   */\n  result: FileReaderResult;\n}\n\n/** @since 2.9.0 */\nexport type FileUploadStats =\n  | ProcessingFileUploadStats\n  | CompletedFileUploadStats;\n\n/** @since 2.9.0 */\nexport type FileUploadStatus = FileUploadStats[\"status\"];\n\n/** @since 2.9.0 */\nexport interface FileUploadHandlers<E extends HTMLElement> {\n  onDrop?: DragEventHandler<E>;\n  onChange?: ChangeEventHandler<HTMLInputElement>;\n}\n\n/**\n * This will first check if the mime-type of the file starts with `text/` and\n * fallback to checking a few file names or extensions that should be considered\n * text.\n *\n * This function is not guaranteed to be 100% correct and is only useful if\n * trying to generate a preview of files uploaded to the browser.\n *\n * @param file - The file to check\n * @returns `true` if the file should be considered as a text-content file.\n * @since 2.9.0\n */\nexport function isTextFile(file: File): boolean {\n  return /\\.((j|t)sx?|json|lock|hbs|ya?ml|log|txt|md)$/i.test(file.name);\n}\n\n/**\n * This will first check if the mime-type of the file starts with `text\\/` and\n * fallback to checking a few file names or extensions that should be considered\n * text.\n *\n * This function is not guaranteed to be 100% correct and is only useful if\n * trying to generate a preview of files uploaded to the browser.\n *\n * @param file - The file to check\n * @returns `true` if the file should be considered as a text content file.\n * @since 2.9.0\n */\nexport function isImageFile(file: File): boolean {\n  return /\\.(a?png|avif|svg|tiff|gifv?|jpe?g)/i.test(file.name);\n}\n\n/**\n * This will first check if the mime-type of the file starts with `audio/` and\n * fallback to checking a few file names or extensions that should be considered\n * audio.\n *\n * This function is not guaranteed to be 100% correct and is only useful if\n * trying to generate a preview of files uploaded to the browser.\n *\n * @param file - The file to check\n * @returns `true` if the file should be considered as a audio content file.\n * @since 2.9.0\n */\nexport function isAudioFile(file: File): boolean {\n  return /\\.(mp3|wav|ogg|m4p|flac)$/i.test(file.name);\n}\n\n/**\n * This will first check if the mime-type of the file starts with `video/` and\n * fallback to checking a few file names or extensions that should be considered\n * video.\n *\n * This function is not guaranteed to be 100% correct and is only useful if\n * trying to generate a preview of files uploaded to the browser.\n *\n * @param file - The file to check\n * @returns `true` if the file should be considered as a video content file.\n * @since 2.9.0\n */\nexport function isVideoFile(file: File): boolean {\n  return /\\.(mkv|mpe?g|mov|avi|flv|webm|mp4)$/i.test(file.name);\n}\n\n/**\n * This function is not guaranteed to be 100% correct and is only useful if\n * trying to generate a preview of files uploaded to the browser.\n *\n * @param file - The file to check\n * @returns `true` if the file matches an image, audio, or video file.\n * @since 2.9.0\n */\nexport function isMediaFile(file: File): boolean {\n  return isImageFile(file) || isAudioFile(file) || isVideoFile(file);\n}\n\n/**\n * One of the function names from a `FileReader` to upload a file to the\n * client.\n *\n * Note: If this file does not need to be previewed in the browser and will\n * immediately be uploaded to a server, use `readAsArrayBuffer`.\n *\n * @since 2.9.0\n * @since 6.0.0 Removed `\"readAsBinaryString` since it is deprecated\n * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsBinaryString}\n */\nexport type FileReaderParser =\n  | \"readAsText\"\n  | \"readAsDataURL\"\n  | \"readAsArrayBuffer\";\n\n/**\n * A function that should return one of the {@link FileReaderParser} functions\n * to start uploading a file to the browser.\n *\n * @example The Default File Upload Parser\n * ```ts\n * export const getFileParser: GetFileParser = (file) => {\n *   if (isMediaFile(file)) {\n *     return \"readAsDataURL\";\n *   }\n *\n *   if (isTextFile(file)) {\n *     return \"readAsText\";\n *   }\n *\n *   return \"readAsArrayBuffer\";\n * };\n * ```\n *\n * @param file - The file to get a parser for\n * @returns the {@link FileReaderParser} string.\n * @since 2.9.0\n */\nexport type GetFileParser = (file: File) => FileReaderParser;\n\n/**\n * This function will attempt to read:\n * - media (image, audio, and video) files as a data url so they can be\n *   previewed in `<img>`, `<audio>`, and `<video>` tags\n * - text files as plain text\n * - everything else as an `ArrayBuffer` which can be manually converted into a\n *   data url if needed with `URL.createObjectURL`\n *\n * @since 2.9.0\n */\nexport const getFileParser: GetFileParser = (file) => {\n  if (isMediaFile(file)) {\n    return \"readAsDataURL\";\n  }\n\n  if (isTextFile(file)) {\n    return \"readAsText\";\n  }\n\n  return \"readAsArrayBuffer\";\n};\n\n/** @since 2.9.0 */\nexport interface SplitFileUploads {\n  readonly pending: readonly ProcessingFileUploadStats[];\n  readonly uploading: readonly ProcessingFileUploadStats[];\n  readonly complete: readonly CompletedFileUploadStats[];\n}\n\n/**\n * This util will split all the current upload stats by status.\n *\n * @example Main Usage\n * ```tsx\n * import { FileUpload } from \"@react-md/core/files/FileUpload\";\n * import { useFileUpload } from \"@react-md/core/files/useFileUpload\";\n * import { getSplitFileUploads } from \"@react-md/core/files/utils\";\n *\n * function Example() {\n *   const { stats, errors, accept, onChange } = useFileUpload();\n *   const { pending, uploading, completed } = getSplitFileUploads(stats);\n *\n *   return (\n *     <>\n *       <FileUpload accept={accept} onChange={onChange} />\n *       {pending.map(({ key, file, progress, status }) => {\n *         // pretend some UI for each pending item with the provided data\n *         return null;\n *       })}\n *       {uploading.map(({ file, key, progress, status }) => {\n *         // pretend some UI for each uploading item with the provided data\n *         return null;\n *       })}\n *       {complete.map(({ file, key, progress, result, status }) => {\n *         // pretend some UI for each complete item with the provided data\n *         return null;\n *       })}\n *     </>\n *   );\n * }\n * ```\n *\n * @param stats - The {@link FileUploadStats} list generally returned by the\n * {@link useFileUpload} hook.\n * @returns the {@link SplitFileUploads}.\n * @since 2.9.0\n */\nexport function getSplitFileUploads(\n  stats: readonly FileUploadStats[]\n): SplitFileUploads {\n  const pending: ProcessingFileUploadStats[] = [];\n  const uploading: ProcessingFileUploadStats[] = [];\n  const complete: CompletedFileUploadStats[] = [];\n  stats.forEach((stat) => {\n    if (stat.status === \"pending\") {\n      pending.push(stat);\n    } else if (stat.status === \"uploading\") {\n      uploading.push(stat);\n    } else if (stat.status === \"complete\") {\n      complete.push(stat);\n    } else {\n      /* istanbul ignore next */\n      throw new Error(\"Invalid upload stat\");\n    }\n  });\n\n  return { pending, uploading, complete };\n}\n"],"names":["isTextFile","file","test","name","isImageFile","isAudioFile","isVideoFile","isMediaFile","getFileParser","getSplitFileUploads","stats","pending","uploading","complete","forEach","stat","status","push","Error"],"mappings":"AA2DA;;;;;;;;;;;CAWC,GACD,OAAO,SAASA,WAAWC,IAAU;IACnC,OAAO,gDAAgDC,IAAI,CAACD,KAAKE,IAAI;AACvE;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,SAASC,YAAYH,IAAU;IACpC,OAAO,uCAAuCC,IAAI,CAACD,KAAKE,IAAI;AAC9D;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,SAASE,YAAYJ,IAAU;IACpC,OAAO,6BAA6BC,IAAI,CAACD,KAAKE,IAAI;AACpD;AAEA;;;;;;;;;;;CAWC,GACD,OAAO,SAASG,YAAYL,IAAU;IACpC,OAAO,uCAAuCC,IAAI,CAACD,KAAKE,IAAI;AAC9D;AAEA;;;;;;;CAOC,GACD,OAAO,SAASI,YAAYN,IAAU;IACpC,OAAOG,YAAYH,SAASI,YAAYJ,SAASK,YAAYL;AAC/D;AA2CA;;;;;;;;;CASC,GACD,OAAO,MAAMO,gBAA+B,CAACP;IAC3C,IAAIM,YAAYN,OAAO;QACrB,OAAO;IACT;IAEA,IAAID,WAAWC,OAAO;QACpB,OAAO;IACT;IAEA,OAAO;AACT,EAAE;AASF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCC,GACD,OAAO,SAASQ,oBACdC,KAAiC;IAEjC,MAAMC,UAAuC,EAAE;IAC/C,MAAMC,YAAyC,EAAE;IACjD,MAAMC,WAAuC,EAAE;IAC/CH,MAAMI,OAAO,CAAC,CAACC;QACb,IAAIA,KAAKC,MAAM,KAAK,WAAW;YAC7BL,QAAQM,IAAI,CAACF;QACf,OAAO,IAAIA,KAAKC,MAAM,KAAK,aAAa;YACtCJ,UAAUK,IAAI,CAACF;QACjB,OAAO,IAAIA,KAAKC,MAAM,KAAK,YAAY;YACrCH,SAASI,IAAI,CAACF;QAChB,OAAO;YACL,wBAAwB,GACxB,MAAM,IAAIG,MAAM;QAClB;IACF;IAEA,OAAO;QAAEP;QAASC;QAAWC;IAAS;AACxC"}

package/dist/files/validation.d.ts

@@ -0,0 +1,287 @@
+/**
+ * An error that will be created if a user tries dragging and dropping files
+ * from a shared directory that they do not have access to. This error will not
+ * occur much.
+ *
+ * @since 2.9.0
+ */
+export declare class FileAccessError extends Error {
+    /**
+     * A unique key generated by `nanoid` that can be used as a `React` key
+     */
+    key: string;
+    /**
+     *
+     * @param message - An optional message for the error.
+     */
+    constructor(message?: string);
+}
+/**
+ * An error that just requires a `File` to be passed as the first argument.
+ *
+ * @since 2.9.0
+ */
+export declare class GenericFileError extends Error {
+    files: readonly File[];
+    reason?: string | undefined;
+    /**
+     * A unique key generated by `nanoid` that can be used as a `React` key
+     */
+    key: string;
+    /**
+     *
+     * @param files - A list of files that caused the error.
+     * @param reason - An optional reason for the error
+     */
+    constructor(files: readonly File[], reason?: string | undefined);
+}
+/**
+ * An error that is created during the upload process if the number of files
+ * exceeds the {@link FileUploadOptions.maxFiles} amount.
+ *
+ * @since 2.9.0
+ */
+export declare class TooManyFilesError extends GenericFileError {
+    limit: number;
+    /**
+     *
+     * @param files - The list of files that could not be uploaded due to the file
+     * limit defined.
+     * @param limit - The max limit of files allowed.
+     */
+    constructor(files: readonly File[], limit: number);
+}
+/**
+ * An error that will be created if a user tries to upload a file that
+ * is either:
+ * - less than the {@link FileValidationOptions.minFileSize}
+ * - greater than the {@link FileValidationOptions.maxFileSize}
+ * - including the file would be greater than the {@link FileValidationOptions.totalFileSize}
+ *
+ * @since 2.9.0
+ */
+export declare class FileSizeError extends GenericFileError {
+    type: "min" | "max" | "total";
+    limit: number;
+    /**
+     *
+     * @param files - The list of files that have the file size error
+     * @param type - The file size error type
+     * @param limit - The number of bytes allowed based on the type
+     */
+    constructor(files: readonly File[], type: "min" | "max" | "total", limit: number);
+}
+/**
+ * An error that will be created if a user tries to upload a file that does not
+ * end with one of the {@link FileValidationOptions.extensions}.
+ *
+ * @since 2.9.0
+ */
+export declare class FileExtensionError extends GenericFileError {
+    extensions: readonly string[];
+    /**
+     *
+     * @param files - The file that caused the error
+     * @param extensions - The allowed list of file extensions
+     */
+    constructor(files: readonly File[], extensions: readonly string[]);
+}
+/**
+ * Mostly an internal type that is used to allow custom validation errors
+ *
+ * @since 2.9.0
+ */
+export type FileValidationError<E = GenericFileError> = FileAccessError | TooManyFilesError | FileSizeError | FileExtensionError | E;
+/**
+ * A simple type-guard that can be used to check if the
+ * {@link FileValidationError} is the {@link GenericFileError} which can be
+ * useful when displaying the errors to the user.
+ *
+ * @param error - The error to check
+ * @returns true if the error is a {@link FileAccessError}
+ */
+export declare function isGenericFileError<CustomError extends object>(error: FileValidationError<CustomError>): error is GenericFileError;
+/**
+ * A simple type-guard that can be used to check if the
+ * {@link FileValidationError} is the {@link FileAccessError} which can be
+ * useful when displaying the errors to the user.
+ *
+ * @param error - The error to check
+ * @returns true if the error is a {@link FileAccessError}
+ */
+export declare function isFileAccessError<CustomError extends object>(error: FileValidationError<CustomError>): error is FileAccessError;
+/**
+ * A simple type-guard that can be used to check if the
+ * {@link FileValidationError} is the {@link TooManyFilesError} which can be
+ * useful when displaying the errors to the user.
+ *
+ * @param error - The error to check
+ * @returns true if the error is a {@link TooManyFilesError}
+ */
+export declare function isTooManyFilesError<CustomError extends object>(error: FileValidationError<CustomError>): error is TooManyFilesError;
+/**
+ * A simple type-guard that can be used to check if the
+ * {@link FileValidationError} is the {@link FileSizeError} which can be
+ * useful when displaying the errors to the user.
+ *
+ * @param error - The error to check
+ * @returns true if the error is a {@link FileSizeError}
+ */
+export declare function isFileSizeError<CustomError extends object>(error: FileValidationError<CustomError>): error is FileSizeError;
+/**
+ * A simple type-guard that can be used to check if the
+ * {@link FileValidationError} is the {@link FileExtensionError} which can be
+ * useful when displaying the errors to the user.
+ *
+ * @param error - The error to check
+ * @returns true if the error is a {@link FileExtensionError}
+ */
+export declare function isFileExtensionError<CustomError extends object>(error: FileValidationError<CustomError>): error is FileExtensionError;
+/**
+ * This function is used to determine if a file should be added to the
+ * {@link FileExtensionError}. The default implementation should work for most
+ * use cases except when files that do not have extensions can be uploaded. i.e.
+ * LICENSE files.
+ *
+ * @param file - The file being checked
+ * @param extensionRegExp - A regex that will only be defined if the
+ * `extensions` list had at least one value.
+ * @param extensions - The list of extensions allowed
+ * @returns true if the file has a valid name.
+ * @since 3.1.0
+ */
+export type IsValidFileName = (file: File, extensionRegExp: RegExp | undefined, extensions: readonly string[]) => boolean;
+/**
+ *
+ * @defaultValue `matcher?.test(file.name) ?? true`
+ * @since 3.1.0
+ */
+export declare const isValidFileName: IsValidFileName;
+/** @since 2.9.0 */
+export interface FileValidationOptions {
+    /**
+     * If the number of files should be limited, set this value to a number
+     * greater than `0`.
+     *
+     * Note: This still allows "infinite" files when set to `0` since the
+     * `<input>` element should normally be set to `disabled` if files should not
+     * be able to be uploaded.
+     *
+     * @defaultValue `-1`
+     */
+    maxFiles?: number;
+    /**
+     * An optional minimum file size to enforce for each file. This will only be
+     * used when it is greater than `0`.
+     *
+     * @defaultValue `-1`
+     */
+    minFileSize?: number;
+    /**
+     * An optional maximum file size to enforce for each file. This will only be
+     * used when it is greater than `0`.
+     *
+     * @defaultValue `-1`
+     */
+    maxFileSize?: number;
+    /**
+     * An optional list of extensions to enforce when uploading files.
+     *
+     * Note: The extensions and file names will be compared ignoring case.
+     *
+     * @example Only Allow Images
+     * ```ts
+     * const extensions = ["png", "jpeg", "jpg", "gif"];
+     * ```
+     */
+    extensions?: readonly string[];
+    /** {@inheritDoc IsValidFileName} */
+    isValidFileName?: IsValidFileName;
+    /**
+     * An optional total file size to enforce when the {@link maxFiles} option is
+     * not set to `1`.
+     *
+     * @defaultValue `-1`
+     */
+    totalFileSize?: number;
+}
+/** @since 2.9.0 */
+export interface FilesValidationOptions extends Required<FileValidationOptions> {
+    /**
+     * The total number of bytes in the {@link FileUploadHookReturnValue.stats}
+     * list. This is really just:
+     *
+     * ```ts
+     * const totalBytes = stats.reduce((total, stat) => total + stat.file.size, 0);
+     * ```
+     */
+    totalBytes: number;
+    /**
+     * The total number of files in the {@link FileUploadHookReturnValue.stats}.
+     */
+    totalFiles: number;
+}
+/**
+ * @since 2.9.0
+ */
+export interface ValidatedFilesResult<CustomError> {
+    /**
+     * A filtered list of files that have been validated and can be queued for the
+     * upload process.
+     */
+    pending: readonly File[];
+    /**
+     * A list of {@link FileValidationError} that occurred during the validation
+     * step.
+     *
+     * Note: If an error has occurred, the file **should not** be added to the
+     * {@link pending} list of files.
+     */
+    errors: readonly FileValidationError<CustomError>[];
+}
+/**
+ * This function will be called whenever a file has been uploaded by the user
+ * either through an `<input type="file">` or drag and drop behavior.
+ *
+ * @example Simple Example
+ * ```ts
+ * const validateFiles: FilesValidator = (files, options) => {
+ *   const invalid: File[] = [];
+ *   const pending: File[] = [];
+ *   for (const file of files) {
+ *     if (!/\.(jpe?g|svg|png)$/i.test(name)) {
+ *       invalid.push(file);
+ *     } else {
+ *       pending.push(file);
+ *     }
+ *   }
+ *
+ *   const errors: FileValidationError[] = [];
+ *   if (invalid.length) {
+ *     errors.push(new GenericFileError(invalid))
+ *   }
+ *
+ *   return { pending, errors };
+ * };
+ * ```
+ *
+ * @typeParam E - An optional custom file validation error.
+ * @param files - The list of files to check
+ * @param options - The {@link FilesValidationOptions}
+ * @returns the {@link ValidatedFilesResult}
+ * @see {@link validateFiles} for the default implementation
+ * @since 2.9.0
+ */
+export type FilesValidator<CustomError = never> = (files: readonly File[], options: FilesValidationOptions) => ValidatedFilesResult<CustomError>;
+/**
+ * A pretty decent default implementation for validating files with the
+ * {@link useFileUpload} that ensures the {@link FilesValidationOptions} are
+ * enforced before allowing a file to be uploaded.
+ *
+ * @typeParam E - An optional custom file validation error.
+ * @param files - The list of files to check
+ * @param options - The {@link FilesValidationOptions}
+ * @returns the {@link ValidatedFilesResult}
+ * @since 2.9.0
+ */
+export declare function validateFiles<CustomError>(files: readonly File[], options: FilesValidationOptions): ValidatedFilesResult<CustomError>;

package/dist/files/validation.js

@@ -0,0 +1,226 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+import { nanoid } from "nanoid";
+/**
+ * An error that will be created if a user tries dragging and dropping files
+ * from a shared directory that they do not have access to. This error will not
+ * occur much.
+ *
+ * @since 2.9.0
+ */ export class FileAccessError extends Error {
+    /**
+   *
+   * @param message - An optional message for the error.
+   */ constructor(message){
+        super(message), /**
+   * A unique key generated by `nanoid` that can be used as a `React` key
+   */ _define_property(this, "key", void 0);
+        this.key = nanoid();
+        this.name = "FileAccessError";
+    }
+}
+/**
+ * An error that just requires a `File` to be passed as the first argument.
+ *
+ * @since 2.9.0
+ */ export class GenericFileError extends Error {
+    /**
+   *
+   * @param files - A list of files that caused the error.
+   * @param reason - An optional reason for the error
+   */ constructor(files, reason){
+        super("Invalid files"), _define_property(this, "files", void 0), _define_property(this, "reason", void 0), /**
+   * A unique key generated by `nanoid` that can be used as a `React` key
+   */ _define_property(this, "key", void 0), this.files = files, this.reason = reason;
+        this.key = nanoid();
+        this.name = "GenericFileError";
+    }
+}
+/**
+ * An error that is created during the upload process if the number of files
+ * exceeds the {@link FileUploadOptions.maxFiles} amount.
+ *
+ * @since 2.9.0
+ */ export class TooManyFilesError extends GenericFileError {
+    /**
+   *
+   * @param files - The list of files that could not be uploaded due to the file
+   * limit defined.
+   * @param limit - The max limit of files allowed.
+   */ constructor(files, limit){
+        super(files, "file limit"), _define_property(this, "limit", void 0), this.limit = limit;
+        this.name = "TooManyFilesError";
+    }
+}
+/**
+ * An error that will be created if a user tries to upload a file that
+ * is either:
+ * - less than the {@link FileValidationOptions.minFileSize}
+ * - greater than the {@link FileValidationOptions.maxFileSize}
+ * - including the file would be greater than the {@link FileValidationOptions.totalFileSize}
+ *
+ * @since 2.9.0
+ */ export class FileSizeError extends GenericFileError {
+    /**
+   *
+   * @param files - The list of files that have the file size error
+   * @param type - The file size error type
+   * @param limit - The number of bytes allowed based on the type
+   */ constructor(files, type, limit){
+        super(files, "file size"), _define_property(this, "type", void 0), _define_property(this, "limit", void 0), this.type = type, this.limit = limit;
+        this.name = "FileSizeError";
+    }
+}
+/**
+ * An error that will be created if a user tries to upload a file that does not
+ * end with one of the {@link FileValidationOptions.extensions}.
+ *
+ * @since 2.9.0
+ */ export class FileExtensionError extends GenericFileError {
+    /**
+   *
+   * @param files - The file that caused the error
+   * @param extensions - The allowed list of file extensions
+   */ constructor(files, extensions){
+        super(files, "extension"), _define_property(this, "extensions", void 0), this.extensions = extensions;
+        this.name = "FileExtensionError";
+    }
+}
+/**
+ * A simple type-guard that can be used to check if the
+ * {@link FileValidationError} is the {@link GenericFileError} which can be
+ * useful when displaying the errors to the user.
+ *
+ * @param error - The error to check
+ * @returns true if the error is a {@link FileAccessError}
+ */ export function isGenericFileError(error) {
+    return "name" in error && error.name === "GenericFileError";
+}
+/**
+ * A simple type-guard that can be used to check if the
+ * {@link FileValidationError} is the {@link FileAccessError} which can be
+ * useful when displaying the errors to the user.
+ *
+ * @param error - The error to check
+ * @returns true if the error is a {@link FileAccessError}
+ */ export function isFileAccessError(error) {
+    return "name" in error && error.name === "FileAccessError";
+}
+/**
+ * A simple type-guard that can be used to check if the
+ * {@link FileValidationError} is the {@link TooManyFilesError} which can be
+ * useful when displaying the errors to the user.
+ *
+ * @param error - The error to check
+ * @returns true if the error is a {@link TooManyFilesError}
+ */ export function isTooManyFilesError(error) {
+    return "name" in error && error.name === "TooManyFilesError";
+}
+/**
+ * A simple type-guard that can be used to check if the
+ * {@link FileValidationError} is the {@link FileSizeError} which can be
+ * useful when displaying the errors to the user.
+ *
+ * @param error - The error to check
+ * @returns true if the error is a {@link FileSizeError}
+ */ export function isFileSizeError(error) {
+    return "name" in error && error.name === "FileSizeError";
+}
+/**
+ * A simple type-guard that can be used to check if the
+ * {@link FileValidationError} is the {@link FileExtensionError} which can be
+ * useful when displaying the errors to the user.
+ *
+ * @param error - The error to check
+ * @returns true if the error is a {@link FileExtensionError}
+ */ export function isFileExtensionError(error) {
+    return "name" in error && error.name === "FileExtensionError";
+}
+/**
+ *
+ * @defaultValue `matcher?.test(file.name) ?? true`
+ * @since 3.1.0
+ */ export const isValidFileName = (file, matcher)=>matcher?.test(file.name) ?? true;
+/**
+ * A pretty decent default implementation for validating files with the
+ * {@link useFileUpload} that ensures the {@link FilesValidationOptions} are
+ * enforced before allowing a file to be uploaded.
+ *
+ * @typeParam E - An optional custom file validation error.
+ * @param files - The list of files to check
+ * @param options - The {@link FilesValidationOptions}
+ * @returns the {@link ValidatedFilesResult}
+ * @since 2.9.0
+ */ export function validateFiles(files, options) {
+    const { maxFiles, extensions, minFileSize, maxFileSize, totalBytes, totalFiles, totalFileSize, isValidFileName } = options;
+    const errors = [];
+    const pending = [];
+    const extraFiles = [];
+    const extensionRegExp = extensions.length > 0 ? new RegExp(`\\.(${extensions.join("|")})$`, "i") : undefined;
+    let maxFilesReached = maxFiles > 0 && totalFiles >= maxFiles;
+    let remainingBytes = totalFileSize - totalBytes;
+    const extensionErrors = [];
+    const minErrors = [];
+    const maxErrors = [];
+    const totalSizeErrors = [];
+    for(let i = 0; i < files.length; i += 1){
+        const file = files[i];
+        let valid = true;
+        const { size } = file;
+        if (!isValidFileName(file, extensionRegExp, extensions)) {
+            valid = false;
+            extensionErrors.push(file);
+        }
+        if (minFileSize > 0 && size < minFileSize) {
+            valid = false;
+            minErrors.push(file);
+        }
+        if (maxFileSize > 0 && size > maxFileSize) {
+            valid = false;
+            maxErrors.push(file);
+        } else if (totalFileSize > 0 && remainingBytes - file.size < 0) {
+            // don't want both errors displaying
+            valid = false;
+            totalSizeErrors.push(file);
+        }
+        if (maxFilesReached && valid) {
+            extraFiles.push(file);
+        } else if (!maxFilesReached && valid) {
+            pending.push(file);
+            remainingBytes -= file.size;
+            maxFilesReached = maxFilesReached || maxFiles > 0 && totalFiles + pending.length >= maxFiles;
+        }
+    }
+    if (extensionErrors.length) {
+        errors.push(new FileExtensionError(extensionErrors, extensions));
+    }
+    if (minErrors.length) {
+        errors.push(new FileSizeError(minErrors, "min", minFileSize));
+    }
+    if (maxErrors.length) {
+        errors.push(new FileSizeError(maxErrors, "max", maxFileSize));
+    }
+    if (totalSizeErrors.length) {
+        errors.push(new FileSizeError(totalSizeErrors, "total", totalFileSize));
+    }
+    if (extraFiles.length) {
+        errors.push(new TooManyFilesError(extraFiles, maxFiles));
+    }
+    return {
+        pending,
+        errors
+    };
+}
+
+//# sourceMappingURL=validation.js.map