feat: Panel component (#318)

* chore: format * chore(typings): add typing for `remoteTabSessionKey` * chore(typings): replace deprecated `RefForwardingComponent` with `ForwardRefRenderFunction` * fix(typings): improve `fileColl` types * feat!: add `Panel` component BREAKING CHANGE: `Panel` component was undocumented but still exported. It's API and behaviour have changed. See README for the details. * fix(typing): jquery reference * chore: update dummy example * chore: refactor typing test * chore: do not call `onChange` on file add * chore: fix typings * chore: cancel group loading after value updated * chore: fix test * chore: wrap dialog api * chore: refactor DialogApi typings
uploadcare · Apr 22, 2022 · 339aeca · 339aeca
1 parent f9fc1ab
commit 339aeca
Show file tree

Hide file tree

Showing 12 changed files with 328 additions and 123 deletions.
diff --git a/README.md b/README.md
@@ -23,7 +23,8 @@ required to handle uploads.
 * [Usage](#usage)
 * [Available bundles](#available-bundles)
 * [Configuration](#configuration)
-  * [Component configuration](#component-configuration)
+  * [`Widget` component configuration](#widget-component-configuration)
+  * [`Panel` component configuration](#panel-component-configuration)
   * [Widget configuration](#widget-configuration)
 * [Security issues](#security-issues)
 * [Feedback](#feedback)
@@ -42,6 +43,14 @@ import { Widget } from "@uploadcare/react-widget";
 <Widget publicKey="YOUR_PUBLIC_KEY" />;
 ```
 
+or
+
+```jsx
+import { Panel } from "@uploadcare/react-widget";
+
+<Panel publicKey="YOUR_PUBLIC_KEY" />;
+```
+
 * [Basic usage example on CodeSandbox][sandbox-props]
 * [Gatsby basic usage example on CodeSandbox][sandbox-gatsby]
 
@@ -65,7 +74,7 @@ To reduce your bundle size, you can also import one of the following:
 
 ## Configuration
 
-### Component configuration
+### `Widget` component configuration
 
 #### `value: string`
 
@@ -236,6 +245,77 @@ be available over HTTPS.
 
 <br>
 
+### `Panel` component configuration
+
+#### `value: string[]`
+
+Set an array of [file UUID][uc-docs-files]/[group UUID][uc-docs-groups] or a [CDN URL][delivery-docs]
+as a value.
+
+```jsx
+<Panel value={[
+  '9dd2f080-cc52-442d-aa06-1d9eec7f40d1',
+  'https://ucarecdn.com/fdfe4e67-f747-4993-91f5-be21d6d3c1a6/',
+  '9ef9af26-7356-4428-b69c-1b920f947989~2'
+]} />
+```
+
+<br>
+
+#### `onChange: (fileInstanceList: FileInstance[]) => void`
+
+Set a function to be called whenever **files state changes**.
+
+* [FileInstance object description][api-refs-file-instance]
+<!-- TODO: * [Example][sandbox-on-change] -->
+
+<br>
+
+#### `onProgress: (uploadInfoList: UploadInfo[]) => void`
+
+Set a function to be called whenever **progress state changes**.
+
+* [UploadInfo object description][api-refs-upload-info]
+<!-- TODO: * [Example][sandbox-on-change] -->
+
+<br>
+
+#### `ref: panelApiRef`
+
+Define a reference object to address the Dialog API wrapper.
+
+```typescript
+interface DialogApi {
+  addFiles(files: FileInfo[]): void;
+  switchTab(tab: string): void;
+  getFileColl(): CollectionOfPromises<FileInfo>;
+  hideTab(tab: string): void;
+  showTab(tab: string): void;
+  isTabVisible(tab: string): boolean;
+  onTabVisibility(callback: OnTabVisibilityCallback): void;
+}
+```
+
+* [Dialog API reference][api-refs-dialog]
+<!-- TODO: * [Example][sandbox-ref] -->
+
+<br>
+
+#### Those methods works exactly the same way as in `Widget` component:
+
+* [`onTabChange`](#ontabchange-tabname-string--void)
+* [`customTabs`](#customtabs-key-string-customtabconstructor)
+* [`validators`](#validators-validator)
+* [`preloader`](#preloader-componenttype)
+* [`tabsCss`](#tabscss-string)
+
+#### Those methods aren't supported in `Panel` component:
+
+* [`onFileSelect`](#onfileselect-fileinfo-fileinfo--filesinfo--null--void)
+* [`onDialogOpen`](#ondialogopen-dialog-dialogapi--void)
+* [`onDialogClose`](#ondialogclose-objs-fileinfo--filesinfo--null--void)
+
+
 ### Widget configuration
 
 Uploadcare Widget can be deeply customized to suit your UX/UI. You can define
@@ -272,6 +352,8 @@ We want to hear your issue reports and feature requests at
 [react-guide]: https://uploadcare.com/docs/guides/react/?utm_source=github&utm_campaign=react-widget
 [custom-tabs-docs]: https://uploadcare.com/docs/api_reference/javascript/custom_tabs/?utm_source=github&utm_campaign=react-widget
 
+[api-refs-upload-info]: https://uploadcare.com/docs/file-uploader-api/files-uploads/#upload-info
+[api-refs-file-instance]: https://uploadcare.com/docs/file-uploader-api/files-uploads/#file-new-instance
 [api-refs-props]: https://uploadcare.com/docs/api_reference/rest/accessing_files/#properties?utm_source=github&utm_campaign=react-widget
 [api-refs-dialog]: https://uploadcare.com/docs/file_uploader_api/dialog_panel/#dialog-api?utm_source=github&utm_campaign=react-widget
 [api-refs-validation]: https://uploadcare.com/docs/file_uploads/widget/moderation/?utm_source=github&utm_campaign=react-widget

diff --git a/dummy/default-panel.js b/dummy/default-panel.js
@@ -1,5 +1,27 @@
-import React from 'react'
+import React, { useRef } from 'react'
 
 import { Panel } from '../src'
 
-export default () => <Panel publicKey='demopublickey' />
+export default () => {
+  const ref = useRef()
+
+  return (
+    <Panel
+      ref={ref}
+      value={[
+        'cced07ed-50f4-49fa-b37f-8a40b5754dff',
+        'https://ucarecdn.com/fdfe4e67-f747-4993-91f5-be21d6d3c1a6/-/preview/760x500/-/progressive/yes/-/format/auto/-/quality/normal/',
+        '9ef9af26-7356-4428-b69c-1b920f947989~2'
+      ]}
+      multiple
+      publicKey="demopublickey"
+      onTabChange={(e) => console.log('onTabChange', e)}
+      onProgress={(progress) => console.log('onProgress', progress)}
+      onChange={(files) => {
+        Promise.allSettled(files).then((results) =>
+          console.log('onChange', results)
+        )
+      }}
+    />
+  )
+}
diff --git a/package.json b/package.json
@@ -57,7 +57,9 @@
   "dependencies": {
     "@uploadcare/client-suspense": "^1.0.5",
     "react-fast-compare": "^3.2.0",
-    "uploadcare-widget": "^3.17.0"
+    "uploadcare-widget": "^3.17.0",
+    "@types/jquery": "^3.5.5",
+    "@types/jquery-deferred": "^0.3.0"
   },
   "peerDependencies": {
     "react": "^16.10.2 || ^17.0.0",
@@ -72,7 +74,6 @@
     "@rollup/plugin-replace": "2.4.2",
     "@testing-library/jest-dom": "5.11.10",
     "@testing-library/react": "11.2.5",
-    "@types/jquery": "3.5.5",
     "@types/react": "17.0.3",
     "@types/react-dom": "17.0.3",
     "babel-eslint": "10.1.0",
@@ -103,8 +104,7 @@
     "rollup-plugin-terser": "7.0.2",
     "shipjs": "0.23.1",
     "typescript": "4.2.3",
-    "uploadcare-widget-tab-effects": "1.5.0",
-    "@types/jquery-deferred": "^0.3.0"
+    "uploadcare-widget-tab-effects": "1.5.0"
   },
   "jest": {
     "setupFiles": [