@cubone/react-file-manager 1.36.0 → 1.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +49 -5
  2. package/dist/index.d.ts +3 -2
  3. package/dist/react-file-manager.es.js +4221 -3207
  4. package/dist/style.css +1 -1
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -27,6 +27,8 @@ An open-source React.js package with TypeScript support for easy integration of
27
27
  intuitive keyboard shortcuts.
28
28
  - **Drag-and-Drop**: Move selected files and folders by dragging them to the desired directory,
29
29
  making file organization effortless.
30
+ - **Folder Upload**: Upload a whole folder with its subfolders from the Upload menu or by dragging it
31
+ into the upload dialog. Works with your existing create-folder and upload endpoints.
30
32
  - **Column Sorting**: Click on column headers in list view to sort files by name, modified date, or
31
33
  size. Click again to toggle between ascending (▲) and descending (▼) order. Folders are always
32
34
  displayed before files regardless of the sort criteria.
@@ -84,7 +86,13 @@ export default App;
84
86
  ```
85
87
 
86
88
  > **Using TypeScript?** Import the `FileItem` type and pass it to `useState`:
87
- > `const [files, setFiles] = useState<FileItem[]>([...]);`
89
+ >
90
+ > ```tsx
91
+ > import { FileManager, type FileItem } from "@cubone/react-file-manager";
92
+ >
93
+ > const [files, setFiles] = useState<FileItem[]>([...]);
94
+ > ```
95
+ >
88
96
  > See the [TypeScript](#-typescript) section for all available types.
89
97
 
90
98
  More detailed samples can be found in the [samples folder](https://github.com/Saifullah-dev/react-file-manager/tree/main/samples).
@@ -137,7 +145,7 @@ interface FileItem {
137
145
 
138
146
  | Name | Type | Description |
139
147
  | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
140
- | `acceptedFileTypes` | string | (Optional) A comma-separated list of allowed file extensions for uploading specific file types (e.g., `.txt, .png, .pdf`). If omitted, all file types are accepted. |
148
+ | `acceptedFileTypes` | string | (Optional) A comma-separated list of allowed file extensions for uploading specific file types (e.g., `.txt, .png, .pdf`). Extensions match regardless of case, and MIME types such as `image/*` also work. If omitted, all file types are accepted. |
141
149
  | `className` | string | CSS class names to apply to the FileManager root element. |
142
150
  | `collapsibleNav` | boolean | Enables a collapsible navigation pane on the left side. When `true`, a toggle will be shown to expand or collapse the navigation pane. `default: false`. |
143
151
  | `defaultNavExpanded` | boolean | Sets the default expanded (`true`) or collapsed (`false`) state of the navigation pane when `collapsibleNav` is enabled. This only affects the initial render. `default: true`. |
@@ -156,14 +164,14 @@ interface FileItem {
156
164
  | `maxFileSize` | number | For limiting the maximum upload file size in bytes. |
157
165
  | `onCopy` | (files: Array<[FileItem](#-file-structure)>) => void | (Optional) A callback function triggered when one or more files or folders are copied providing copied files as an argument. Use this function to perform custom actions on copy event. |
158
166
  | `onCut` | (files: Array<[FileItem](#-file-structure)>) => void | (Optional) A callback function triggered when one or more files or folders are cut, providing the cut files as an argument. Use this function to perform custom actions on the cut event. |
159
- | `onCreateFolder` | (name: string, parentFolder: [FileItem](#-file-structure)) => void | A callback function triggered when a new folder is created. Use this function to update the files state to include the new folder under the specified parent folder using create folder API call to your server. |
167
+ | `onCreateFolder` | (name: string, parentFolder: [FileItem](#-file-structure)) => void \| [FileItem](#-file-structure) \| Promise<void \| [FileItem](#-file-structure)> | A callback function triggered when a new folder is created. Use this function to update the files state to include the new folder under the specified parent folder using create folder API call to your server. Folder uploads also use it to create subfolders: return the created folder (or a promise of it) so files can upload into it right away. If nothing is returned, the file manager waits for the folder to appear in `files`. Throw or reject if the folder can't be created. |
160
168
  | `onDelete` | (files: Array<[FileItem](#-file-structure)>) => void | A callback function is triggered when one or more files or folders are deleted. |
161
169
  | `onDownload` | (files: Array<[FileItem](#-file-structure)>) => void | A callback function triggered when one or more files or folders are downloaded. |
162
- | `onError` | (error: { type: string, message: string }, file: [FileItem](#-file-structure) \| File) => void | A callback function triggered whenever there is an error in the file manager. Where error is an object containing `type` ("upload", etc.) and a descriptive error `message`. |
170
+ | `onError` | (error: { type: string, message: string }, file: [FileItem](#-file-structure) \| File) => void | A callback function triggered whenever there is an error in the file manager. Where error is an object containing `type` ("upload", "createFolder", etc.) and a descriptive error `message`. |
163
171
  | `onFileOpen` | (file: [FileItem](#-file-structure)) => void | A callback function triggered when a file or folder is opened. |
164
172
  | `onFolderChange` | (path: string) => void | A callback function triggered when the active folder changes. Receives the full path of the current folder as a string parameter. Useful for tracking the active folder path. |
165
173
  | `onFileUploaded` | (response: { [key: string]: any }) => void | A callback function triggered after a file is successfully uploaded. Provides JSON `response` holding uploaded file details, use it to extract the uploaded file details and add it to the `files` state e.g. `setFiles((prev) => [...prev, JSON.parse(response)]);` |
166
- | `onFileUploading` | (file: File, parentFolder: [FileItem](#-file-structure)) => { [key: string]: any } | A callback function triggered during the file upload process, receiving the browser `File` being uploaded. You can also return an object with key-value pairs that will be appended to the `FormData` along with the file being uploaded. The object can contain any number of valid properties. |
174
+ | `onFileUploading` | (file: File, parentFolder: [FileItem](#-file-structure)) => { [key: string]: any } | A callback function triggered during the file upload process, receiving the browser `File` being uploaded. You can also return an object with key-value pairs that will be appended to the `FormData` along with the file being uploaded. The object can contain any number of valid properties. For folder uploads, `parentFolder` is the subfolder the file is uploaded into. |
167
175
  | `onLayoutChange` | (layout: "list" \| "grid") => void | A callback function triggered when the layout of the file manager is changed. |
168
176
  | `onPaste` | (files: Array<[FileItem](#-file-structure)>, destinationFolder: [FileItem](#-file-structure), operationType: "copy" \| "move") => void | A callback function triggered when when one or more files or folders are pasted into a new location. Depending on `operationType`, use this to either copy or move the `sourceItem` to the `destinationFolder`, updating the files state accordingly. |
169
177
  | `onRefresh` | () => void | A callback function triggered when the file manager is refreshed. Use this to refresh the `files` state to reflect any changes or updates. |
@@ -174,6 +182,7 @@ interface FileItem {
174
182
  | `permissions` | { create?: boolean; upload?: boolean; move?: boolean; copy?: boolean; rename?: boolean; download?: boolean; delete?: boolean; } | An object that controls the availability of specific file management actions. Setting an action to `false` hides it from the toolbar, context menu, and any relevant UI. All actions default to `true` if not specified. This is useful for implementing role-based access control or restricting certain operations. Example: `{ create: false, delete: false }` disables folder creation and file deletion. |
175
183
  | `primaryColor` | string | The primary color for the component's theme. Accepts any valid CSS color format (e.g., `'blue'`, `'#E97451'`, `'rgb(52, 152, 219)'`). This color will be applied to buttons, highlights, and other key elements. `default: #6155b4`. |
176
184
  | `style` | object | Inline styles applied to the FileManager root element. |
185
+ | `uploadConcurrency` | number | The maximum number of files uploaded at the same time. Remaining files wait in a queue. `default: 4`. |
177
186
  | `width` | string \| number | The width of the component `default: 100%`. Can be a string (e.g., `'100%'`, `'10rem'`) or a number (in pixels). |
178
187
 
179
188
  ## ⌨️ Keyboard Shortcuts
@@ -218,6 +227,41 @@ if not specified.
218
227
  />
219
228
  ```
220
229
 
230
+ ## 📁 Folder Uploads
231
+
232
+ Users can upload a whole folder, including its subfolders, by choosing **Upload → Upload folder**
233
+ (toolbar, context menu, or the upload dialog) or by dragging a folder into the upload dialog.
234
+
235
+ No extra backend endpoint is needed. The file manager recreates the folder structure with your
236
+ `onCreateFolder` callback, then uploads each file to `fileUploadConfig.url` with its own subfolder
237
+ as `parentFolder` in `onFileUploading`:
238
+
239
+ ```tsx
240
+ const handleCreateFolder: OnCreateFolder = async (name, parentFolder) => {
241
+ const response = await api.post("/folder", { name, parentId: parentFolder?._id });
242
+ setFiles((prev) => [...prev, response.data]);
243
+ return response.data; // Lets folder uploads continue into the new folder right away
244
+ };
245
+
246
+ const handleFileUploading: OnFileUploading = (file, parentFolder) => {
247
+ return { parentId: parentFolder?._id }; // The subfolder this file belongs in
248
+ };
249
+ ```
250
+
251
+ - Throw (or reject) from `onCreateFolder` when a folder can't be created. The files waiting on it
252
+ then fail right away and can be retried. If it returns nothing without throwing, the file manager
253
+ waits up to 30 seconds for the folder to appear in `files` before failing those files.
254
+ - Folders that already exist are reused, so uploading into an existing folder merges into it.
255
+ - Subfolders are created parent-first. Files start uploading as soon as their folder exists.
256
+ - Uploads run `uploadConcurrency` at a time (default `4`). Each file can be canceled or retried.
257
+ - In the upload dialog, each folder shows as one row with its combined progress. Expand it to see
258
+ every file, with failed files listed first. The whole folder can be canceled, and failed files
259
+ retried, from that row.
260
+ - `maxFileSize`, `acceptedFileTypes` and the existing-file check apply to every file in the folder.
261
+ - Folder upload is available when `onCreateFolder` is provided and both the `create` and `upload`
262
+ permissions are enabled. Otherwise the Upload button works as before and dropped folders are
263
+ skipped with an `onError` call.
264
+
221
265
  ## </> Custom File Preview
222
266
 
223
267
  The `FileManager` component allows you to provide a custom file preview by passing the
package/dist/index.d.ts CHANGED
@@ -10,7 +10,7 @@ export declare interface FileItem {
10
10
  }
11
11
 
12
12
  declare const FileManager: {
13
- ({ files, fileUploadConfig, isLoading, onCreateFolder, onFileUploading, onFileUploaded, onCut, onCopy, onPaste, onRename, onDownload, onDelete, onLayoutChange, onRefresh, onFileOpen, onFolderChange, onSelect, onSelectionChange, onError, onSortChange, layout, enableFilePreview, maxFileSize, filePreviewPath, acceptedFileTypes, height, width, initialPath, filePreviewComponent, primaryColor, fontFamily, language, permissions: userPermissions, collapsibleNav, defaultNavExpanded, className, style, formatDate, }: FileManagerProps): JSX.Element;
13
+ ({ files, fileUploadConfig, isLoading, onCreateFolder, onFileUploading, onFileUploaded, onCut, onCopy, onPaste, onRename, onDownload, onDelete, onLayoutChange, onRefresh, onFileOpen, onFolderChange, onSelect, onSelectionChange, onError, onSortChange, layout, enableFilePreview, maxFileSize, uploadConcurrency, filePreviewPath, acceptedFileTypes, height, width, initialPath, filePreviewComponent, primaryColor, fontFamily, language, permissions: userPermissions, collapsibleNav, defaultNavExpanded, className, style, formatDate, }: FileManagerProps): JSX.Element;
14
14
  displayName: string;
15
15
  };
16
16
  export { FileManager }
@@ -41,6 +41,7 @@ export declare interface FileManagerProps {
41
41
  layout?: Layout;
42
42
  enableFilePreview?: boolean;
43
43
  maxFileSize?: number;
44
+ uploadConcurrency?: number;
44
45
  filePreviewPath?: string;
45
46
  acceptedFileTypes?: string;
46
47
  height?: string | number;
@@ -75,7 +76,7 @@ export declare type Layout = "grid" | "list";
75
76
 
76
77
  export declare type OnCopy = (files: FileItem[]) => void;
77
78
 
78
- export declare type OnCreateFolder = (name: string, parentFolder: FileItem) => void;
79
+ export declare type OnCreateFolder = (name: string, parentFolder: FileItem) => void | FileItem | Promise<void | FileItem>;
79
80
 
80
81
  export declare type OnCut = (files: FileItem[]) => void;
81
82