@availity/mui-file-selector 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
 
+## [1.1.1](https://github.com/Availity/element/compare/@availity/mui-file-selector@1.1.0...@availity/mui-file-selector@1.1.1) (2025-03-07)
+
+### Dependency Updates
+
+* `mui-paper` updated to version `1.1.0`
+* `mui-alert` updated to version `1.1.0`
+* `mui-button` updated to version `1.1.0`
+* `mui-divider` updated to version `1.1.0`
+* `mui-form-utils` updated to version `1.1.0`
+* `mui-icon` updated to version `1.1.0`
+* `mui-layout` updated to version `1.1.0`
+* `mui-list` updated to version `1.1.0`
+* `mui-progress` updated to version `1.1.0`
+* `mui-typography` updated to version `1.1.0`
+## [1.1.0](https://github.com/Availity/element/compare/@availity/mui-file-selector@1.0.0...@availity/mui-file-selector@1.1.0) (2025-03-04)
+
+
+### Features
+
+* **mui-file-selector:** add ability to disable remove button on FileList ([df1f7f0](https://github.com/Availity/element/commit/df1f7f05016bf625208db18ee1d4ef96912abaac))
+
+
+### Bug Fixes
+
+* **mui-file-selector:** add ability to override file row ([5dd864b](https://github.com/Availity/element/commit/5dd864baf323fe879de6efda6b6176be09e058d0))
+* **mui-file-selector:** add ability to toggle dropzone area ([2c80730](https://github.com/Availity/element/commit/2c807309f1e387a2531b56421f2d7e08d4c50e19))
+* **mui-file-selector:** add exports ([c7c50d1](https://github.com/Availity/element/commit/c7c50d1a90bafa424f9758c191f25c1772cc945d))
+* **mui-file-selector:** add metadata prop ([757b747](https://github.com/Availity/element/commit/757b747d66f6d2fe2414cf14e30ec72c33b1547e))
+* **mui-file-selector:** add uploadOptions prop ([afaabe7](https://github.com/Availity/element/commit/afaabe7498535d40ea426a88c8c6d81701ff078e))
+* **mui-file-selector:** display divider with OR on the FileSelector dropzone ([8f5fd5a](https://github.com/Availity/element/commit/8f5fd5a3a813a6244a4a72b6cd6878325c095d7a))
+* **mui-file-selector:** fix bugs, add onDrop and validator props ([01d4257](https://github.com/Availity/element/commit/01d42570496797b080f5d5552e4cdaf2843d621b))
+* **mui-file-selector:** fix spacing ([b9964bc](https://github.com/Availity/element/commit/b9964bc9446a7b2d2bc07f999a93cce4af524f3b))
+* **mui-file-selector:** fix type and add docs ([704454f](https://github.com/Availity/element/commit/704454f7fde50ddb4154f287355026810dd152dc))
+* **mui-file-selector:** fix unit test ([92f08fc](https://github.com/Availity/element/commit/92f08fc7c3e86e27d4436090ba2b781c2a26c024))
+* **mui-file-selector:** fix unit test ([f892c12](https://github.com/Availity/element/commit/f892c1268bd20acdd2be7cc39eeb7f9dd7260f5e))
+* **mui-file-selector:** fix unit test ([c4282c1](https://github.com/Availity/element/commit/c4282c1a93c1ef3ec5380aed09b02d07ce26dab1))
+* **mui-file-selector:** remove form and make input standalone ([a6b6e81](https://github.com/Availity/element/commit/a6b6e81f5c4f8133676b5e07b58d208d2bf46a11))
+* **mui-file-selector:** update query format ([0372a45](https://github.com/Availity/element/commit/0372a45864aadf42aa1c2e23aca132f7bea4ad23))
+
 ## [1.0.0](https://github.com/Availity/element/compare/@availity/mui-file-selector@1.0.0-alpha.0...@availity/mui-file-selector@1.0.0) (2025-02-25)
 
 ### Dependency Updates

package/README.md

@@ -62,49 +62,111 @@ import { FileSelector } from '@availity/mui-file-selector';
 
 #### Basic Example
 
-Here's a basic example of how to use the FileSelector component:
+The `FileSelector` component must be used inside a `FormProvider` from `react-hook-form` and a `QueryClientProvider` from `@tanstack/react-query`. Each provider has its own state that is necessary for using the component. The `FormProvider` stores the `Files` that are selected while the `QueryClientProvider` has the `upload` response data.
 
 ```tsx
 import React from 'react';
 import { FileSelector } from '@availity/mui-file-selector';
 
 const MyComponent = () => {
-  const handleSubmit = (uploads, values) => {
-    console.log('Submitted files:', uploads);
-    console.log('Form values:', values);
+  const methods = useForm({
+    defaultValues: {
+      myFiles: [] as File[],
+    },
+  });
+
+  const client = useQueryClient();
+
+  const files = methods.watch(props.name);
+
+  const handleOnSubmit = (values: Record<string, File[]>) => {
+    if (values.myFiles.length === 0) return;
+
+    const queries = client.getQueriesData<Upload>(['upload']);
+    const uploads = [];
+    for (const [, data] of queries) {
+      if (data) uploads.push(data);
+    }
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(handleOnSubmit)}>
+        <FileSelector
+          name="myFiles"
+          bucketId="your-bucket-id"
+          customerId="your-customer-id"
+          clientId="your-client-id"
+          maxSize={5 * 1024 * 1024} // 5MB
+          maxFiles={3}
+          allowedFileTypes={['.pdf', '.doc', '.docx']}
+        />
+      </form>
+    </FormProvider>
+  );
+};
+
+export default MyComponent;
+```
+
+#### Advanced Examples
+
+> Note: the following examples assume you have setup `react-hook-form` and `react-query` already
+
+##### File Selection Events
+
+```tsx
+import React from 'react';
+import { FileSelector } from '@availity/mui-file-selector';
+
+const MyFileUploadComponent = () => {
+  const handleOnDrop = (acceptedFiles, fileRejections, event) => {
+    // Use this callback for interacting with the files before they are uploaded
+  };
+
+  const handleValidation = (file) => {
+    // Custom validation can be added with the `validator` prop.
+    // If an error fails validation here it should show up
+    // in the `fileRejections` array from `onDrop`.
+    //
+    // To return a custom error, return an object with a code
+    // and message.
+    // return { code: 'an-error', message: 'An error occurred' };
   };
 
   return (
     <FileSelector
-      name="myFiles"
+      name="documentUpload"
       bucketId="your-bucket-id"
       customerId="your-customer-id"
       clientId="your-client-id"
-      maxSize={5 * 1024 * 1024} // 5MB
+      maxSize={10 * 1024 * 1024} // 10MB
       allowedFileTypes={['.pdf', '.doc', '.docx']}
-      maxFiles={3}
-      onSubmit={handleSubmit}
+      multiple={true}
+      maxFiles={5}
+      onDrop={handleOnDrop}
+      validator={handleValidation}
     />
   );
 };
 
-export default MyComponent;
+export default MyFileUploadComponent;
 ```
 
-#### Advanced Examples
+##### Upload Callbacks
 
-The `onSuccess` and `onError` callbacks are available to use to add logic for after the file is uploaded or in the event there is an error with the api call.
+It is possible to pass callbacks based on whether the upload finished successfully or there was an error.
 
 ```tsx
 import React from 'react';
 import { FileSelector } from '@availity/mui-file-selector';
 
 const MyFileUploadComponent = () => {
-  const handleSuccess = () => {
+  const handleOnSuccess = () => {
     // Handle successful upload - e.g., show success message, update UI
   };
 
-  const handleError = (error) => {
+  const handleOnError = (error) => {
     // Handle upload error - e.g., show error message, retry upload
   };
 
@@ -118,11 +180,101 @@ const MyFileUploadComponent = () => {
       allowedFileTypes={['.pdf', '.doc', '.docx']}
       multiple={true}
       maxFiles={5}
-      onSuccess={handleSuccess}
-      onError={handleError}
+      uploadOptions={{
+        onSuccess: handleOnSuccess,
+        onError: handleOnError,
+      }}
     />
   );
 };
 
 export default MyFileUploadComponent;
 ```
+
+##### Custom File Row
+
+If you would like to show different information in each row then you are able to pass a custom `FileRow` component. We recommend using the `ListItem` component. The upload object from `@availity/upload-core`, the options passed to its constructor, and the `onRemoveFile` function will all be passed as props.
+
+```tsx
+import React from 'react';
+import { FileSelector } from '@availity/mui-file-selector';
+import { ListItem } from '@availity/mui-list';
+
+const FileRow = ({ upload, options, onRemoveFile }) => {
+  return <ListItem>Your code here</ListItem>;
+};
+
+const MyFileUploadComponent = () => {
+  return (
+    <FileSelector
+      name="documentUpload"
+      bucketId="your-bucket-id"
+      customerId="your-customer-id"
+      clientId="your-client-id"
+      maxSize={10 * 1024 * 1024} // 10MB
+      allowedFileTypes={['.pdf', '.doc', '.docx']}
+      multiple={true}
+      maxFiles={5}
+      customFileRow={FileRow}
+    />
+  );
+};
+
+export default MyFileUploadComponent;
+```
+
+##### Custom `helpText`
+
+To provide custom help text, pass it as a child of the `<FileSelector />` component. The help text should be formatted using the `<Typography />` component with the `'caption'` variant.
+
+```tsx
+import React from 'react';
+import { FileSelector } from '@availity/mui-file-selector';
+import { Typography } from '@availity/mui-typography';
+
+const MyComponent = () => {
+  const methods = useForm({
+    defaultValues: {
+      myFiles: [] as File[],
+    },
+  });
+
+  const client = useQueryClient();
+
+  const files = methods.watch('myFiles);
+
+  const handleOnSubmit = (values: Record<string, File[]>) => {
+    if (values.myFiles.length === 0) return;
+
+    const queries = client.getQueriesData<Upload>(['upload']);
+    const uploads = [];
+    for (const [, data] of queries) {
+      if (data) uploads.push(data);
+    }
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={methods.handleSubmit(handleOnSubmit)}>
+        <FileSelector
+          name="myFiles"
+          bucketId="your-bucket-id"
+          customerId="your-customer-id"
+          clientId="your-client-id"
+          maxSize={5 * 1024 * 1024} // 5MB
+          maxFiles={3}
+          allowedFileTypes={['.pdf', '.doc', '.docx']}
+        >
+          <Typography component="div" variant="caption">Here is some help text.</Typography>
+        </FileSelector>
+      </form>
+    </FormProvider>
+  );
+};
+
+export default MyComponent;
+```
+
+
+
+

package/dist/index.d.mts

@@ -1,6 +1,160 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode, ChangeEvent } from 'react';
+import { MouseEvent, Dispatch, ChangeEvent, RefObject, ReactNode, ElementType } from 'react';
+import { DropEvent, FileRejection, FileError, DropzoneInputProps } from 'react-dropzone';
 import Upload, { UploadOptions } from '@availity/upload-core';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { UseQueryOptions } from '@tanstack/react-query';
+import { ButtonProps } from '@availity/mui-button';
+import { FileRejection as FileRejection$1, DropEvent as DropEvent$1, FileError as FileError$1 } from 'react-dropzone/typings/react-dropzone';
+
+type DropzoneProps = {
+    /**
+     * Name given to the input field. Used by react-hook-form
+     */
+    name: string;
+    /**
+     * List of allowed file extensions (e.g. ['.pdf', '.doc']). Each extension must start with a dot
+     */
+    allowedFileTypes?: `.${string}`[];
+    /**
+     * Whether the dropzone is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Whether to enable the dropzone area
+     */
+    enableDropArea?: boolean;
+    /**
+     * Maximum number of files that can be uploaded
+     */
+    maxFiles?: number;
+    /**
+     * Maximum size of each file in bytes
+     */
+    maxSize?: number;
+    /**
+     * Whether multiple file selection is allowed
+     */
+    multiple?: boolean;
+    /**
+     * Handler called when the file input's value changes
+     */
+    onChange?: (event: DropEvent) => void;
+    /**
+     * Handler called when the file picker button is clicked
+     */
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * More sophisticated version of "onChange". This is the recommend function to use for changes to the form state
+     */
+    onDrop?: (acceptedFiles: File[], fileRejections: (FileRejection & {
+        id: number;
+    })[], event: DropEvent) => void;
+    /**
+     * Callback to handle rejected files that don't meet validation criteria
+     */
+    setFileRejections?: (fileRejections: (FileRejection & {
+        id: number;
+    })[]) => void;
+    /**
+     * Callback to update the total size of all uploaded files
+     */
+    setTotalSize: Dispatch<React.SetStateAction<number>>;
+    /**
+     * Validation function used for custom validation that is not covered with the other props
+     * */
+    validator?: (file: File) => FileError | FileError[] | null;
+};
+declare const Dropzone: ({ allowedFileTypes, disabled, enableDropArea, maxFiles, maxSize, multiple, name, onChange, onClick, onDrop, setFileRejections, setTotalSize, validator, }: DropzoneProps) => react_jsx_runtime.JSX.Element;
+
+type ErrorAlertProps = {
+    /**
+     * Array of file rejection errors
+     */
+    errors: FileRejection['errors'];
+    /**
+     * Name of the file that encountered errors
+     */
+    fileName: string;
+    /**
+     * Unique identifier for the error alert
+     */
+    id: number;
+    onClose: () => void;
+};
+declare const ErrorAlert: ({ errors, fileName, id, onClose }: ErrorAlertProps) => react_jsx_runtime.JSX.Element | null;
+
+type Options = {
+    onError?: (error: Error) => void;
+    onSuccess?: () => void;
+} & UploadOptions;
+type UploadQueryOptions = UseQueryOptions<Upload, Error, Upload, [string, string, Options]>;
+declare function useUploadCore(file: File, options: Options, queryOptions?: UploadQueryOptions): _tanstack_react_query.UseQueryResult<Upload, Error>;
+
+type FileRowProps = {
+    /**
+     * The File object containing information about the uploaded file
+     * */
+    file: File;
+    /**
+     * Callback function called when a file is removed
+     * @param id - The unique identifier of the file being removed
+     * @param upload - The Upload instance associated with the file
+     */
+    onRemoveFile: (id: string, upload: Upload) => void;
+    /**
+     * Configuration options for the upload call
+     * */
+    options: Options;
+    /**
+     * Query options from `react-query` for the upload call
+     * */
+    queryOptions?: UploadQueryOptions;
+    customFileRow?: React.ElementType<{
+        upload?: Upload;
+        options: Options;
+        onRemoveFile: (id: string, upload: Upload) => void;
+    }>;
+    /**
+     * Whether the remove button is disabled
+     * @default false
+     */
+    disableRemove?: boolean;
+};
+declare const FileRow: ({ file, options, onRemoveFile, queryOptions, customFileRow: CustomRow, disableRemove, }: FileRowProps) => react_jsx_runtime.JSX.Element | null;
+type FileListProps = {
+    /**
+     * Array of File objects to be displayed in the list
+     */
+    files: File[];
+} & Omit<FileRowProps, 'file'>;
+declare const FileList: ({ files, options, onRemoveFile, queryOptions, customFileRow, disableRemove, }: FileListProps) => JSX.Element | null;
+
+type FilePickerBtnProps = {
+    /**
+     * Name attribute for the input field, used by react-hook-form for form state management.
+     */
+    name: string;
+    /**
+     *  Callback function triggered when files are selected through the input.
+     */
+    onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+    /**
+     * Optional ID attribute for the file input element.
+     */
+    inputId?: string;
+    /**
+     * Additional props to customize the underlying input element.
+     */
+    inputProps?: DropzoneInputProps & {
+        ref?: RefObject<HTMLInputElement>;
+    };
+    /**
+     * Maximum allowed size per file in bytes. Files exceeding this size will be rejected.
+     */
+    maxSize?: number;
+} & Omit<ButtonProps, 'onChange'>;
+declare const FilePickerBtn: ({ name, children, color, inputId, inputProps, maxSize, onChange, onClick, ...rest }: FilePickerBtnProps) => react_jsx_runtime.JSX.Element;
 
 type FileSelectorProps = {
     /**
@@ -40,10 +194,18 @@ type FileSelectorProps = {
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Whether to enable the dropzone area
+     */
+    enableDropArea?: boolean;
     /**
      * Custom endpoint URL for file uploads. If not provided, default endpoint will be used
      */
     endpoint?: string;
+    /**
+     * Componet to render the File information. This should return a `ListItem`
+     */
+    customFileRow?: ElementType<FileListProps>;
     /**
      * Whether to use the cloud upload endpoint
      * When true, uses '/cloud/web/appl/vault/upload/v1/resumable'
@@ -57,7 +219,7 @@ type FileSelectorProps = {
     /**
      * Maximum number of files that can be uploaded simultaneously
      */
-    maxFiles?: number;
+    maxFiles: number;
     /**
      * Maximum file size allowed per file in bytes
      * Use Kibi or Mibibytes. eg: 1kb = 1024 bytes; 1mb = 1024kb
@@ -74,37 +236,61 @@ type FileSelectorProps = {
      */
     onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
     /**
-     * Callback fired when the form is submitted
-     * @param uploads - Array of Upload instances for the submitted files
-     * @param values - Object containing the form values, with files indexed by the name prop
+     *
      */
-    onSubmit?: (uploads: Upload[], values: Record<string, File[]>) => void;
+    onDrop?: (acceptedFiles: File[], fileRejections: (FileRejection$1 & {
+        id: number;
+    })[], event: DropEvent$1) => void;
     /**
-     * Callback fired when a file is successfully uploaded
+     * Callback fired when a file is removed from the upload list
+     * @param files - Array of remaining files
+     * @param removedUploadId - ID of the removed upload
      */
-    onSuccess?: () => void;
+    onUploadRemove?: (files: File[], removedUploadId: string) => void;
+    /**
+     * Query options from `react-query` for the upload call
+     * */
+    queryOptions?: UploadQueryOptions;
     /**
-     * Callback fired when an error occurs during upload
+     * Options that are passed to the Upload class from `@availity/upload-core`
      */
-    onError?: (error: Error) => void;
+    uploadOptions?: Partial<Options>;
     /**
-     * Array of functions to execute before file upload begins.
-     * Each function should return a boolean indicating whether to proceed with the upload.
-     * @default []
+     * Validation function used for custom validation that is not covered with the other props
+     * */
+    validator?: (file: File) => FileError$1 | FileError$1[] | null;
+    /**
+     * Whether the remove button is disabled
+     * @default false
+     */
+    disableRemove?: boolean;
+};
+declare const FileSelector: ({ name, allowedFileNameCharacters, allowedFileTypes, bucketId, clientId, children, customerId, customFileRow, disabled, enableDropArea, endpoint, isCloud, label, maxFiles, maxSize, multiple, onChange, onDrop, onUploadRemove, queryOptions, uploadOptions, validator, disableRemove, }: FileSelectorProps) => react_jsx_runtime.JSX.Element;
+
+type FileTypesMessageProps = {
+    /**
+     * Allowed file type extensions. Each extension should be prefixed with a ".". eg: .txt, .pdf, .png
      */
-    onFilePreUpload?: (() => boolean)[];
+    allowedFileTypes?: `.${string}`[];
     /**
-     * Callback fired when a file is removed from the upload list
-     * @param files - Array of remaining files
-     * @param removedUploadId - ID of the removed upload
+     * Maximum size per file in bytes. This will be formatted. eg: 1024 * 20 = 20 KB
      */
-    onUploadRemove?: (files: File[], removedUploadId: string) => void;
+    maxFileSize?: number;
+    variant?: 'caption' | 'body2';
+};
+declare const FileTypesMessage: ({ allowedFileTypes, maxFileSize, variant, }: FileTypesMessageProps) => react_jsx_runtime.JSX.Element;
+
+type HeaderMessageProps = {
     /**
-     * Array of delays (in milliseconds) between upload retry attempts
+     * Maximum number of files allowed
      */
-    retryDelays?: UploadOptions['retryDelays'];
+    maxFiles: number;
+    /**
+     * Maximum combined total size of all files
+     */
+    maxSize: number;
 };
-declare const FileSelector: ({ name, allowedFileNameCharacters, allowedFileTypes, bucketId, clientId, children, customerId, disabled, endpoint, isCloud, label, maxFiles, maxSize, multiple, onChange, onSubmit, onSuccess, onError, onFilePreUpload, onUploadRemove, retryDelays, }: FileSelectorProps) => react_jsx_runtime.JSX.Element;
+declare const HeaderMessage: ({ maxFiles, maxSize }: HeaderMessageProps) => react_jsx_runtime.JSX.Element;
 
 type UploadProgressBarProps = {
     /**
@@ -126,4 +312,4 @@ type UploadProgressBarProps = {
 };
 declare const UploadProgressBar: ({ upload, onProgress, onError, onSuccess }: UploadProgressBarProps) => react_jsx_runtime.JSX.Element;
 
-export { FileSelector, type FileSelectorProps, UploadProgressBar, type UploadProgressBarProps };
+export { Dropzone, type DropzoneProps, ErrorAlert, type ErrorAlertProps, FileList, type FileListProps, FilePickerBtn, type FilePickerBtnProps, FileRow, type FileRowProps, FileSelector, type FileSelectorProps, FileTypesMessage, type FileTypesMessageProps, HeaderMessage, type HeaderMessageProps, type Options, UploadProgressBar, type UploadProgressBarProps, type UploadQueryOptions, useUploadCore };