@scaleflex/widget-core 0.0.1

package/README.md

@@ -0,0 +1,1089 @@
+# Scaleflex Media Asset Widget (FMAW)
+
+> This package contains both the main/global readme for the whole widget and the readme for (@scaleflex/widget-core)[#scaleflexwidget-core] plugin itself.
+
+[![Plugins][plugins-image]](#plugins)
+[![Website][filerobot-image]][sfx-url]
+[![Version][filerobot-version]][version-url]
+[![Version][filerobot-version-latest]][version-url-latest]
+[![Version][filerobot-version-stable]][version-url-stable]
+[![Scaleflex team][made-by-image]][sfx-url]
+[![License][license-image]][license-url]
+[![CodeSandbox][codeSandbox-image]][codeSandbox-url]
+
+<div align='center'>
+<img title="Scaleflex Widget logo" alt="Scaleflex Widget logo" src="https://cdn.scaleflex.com/plugins/filerobot-widget/assets/filerobot_widget_logo_with_fire.png?vh=b2ff09" width="140"/>
+</div>
+
+The **FMAW** is a file uploader and media gallery in one easy-to-integrate modal or inline widget. It is the storefront of the [**Scaleflex**](https://scaleflex.com) DAM (Digital Asset Management) and enables accelerated uploads through Scaleflex's content ingestion network and reverse CDN.
+
+Various plugins like for example the [**Scaleflex Image Editor**](https://www.npmjs.com/package/@scaleflex/widget-image-editor/#scaleflexwidgetimage-editor) can be enabled to address use cases requiring the interaction with images, videos and static files in your web application. The modular architecture only loads relevant code, thus making the widget as lightweight as possible.
+
+<!-- <img src="https://cdn.scaleflex.com/demo/widget-npm_v8.gif?vh=4780be" title="Overview of the widget GIF" alt="Overview of the widget GIF" width="600" /> -->
+
+**[Check it live in action](https://cdn.scaleflex.com/plugins/filerobot-widget/v3/demo/index.html)**
+
+<details>
+  <summary>Table of contents</summary>
+
+- [Scaleflex Media Asset Widget (FMAW)](#scaleflexwidget-media-asset-widget-fmaw)
+  - [Main features:](#main-features)
+  - [Installation](#installation)
+  - [Quickstart](#quickstart)
+    - [Demo](#demo)
+    - [React](#react)
+    - [Vanilla (plain) JS](#vanilla-plain-js)
+  - [Modules](#modules)
+  - [Plugins](#plugins)
+    - [UI Elements](#ui-elements)
+    - [Upload connectors](#upload-connectors)
+    - [Destinations](#destinations)
+    - [Miscellaneous](#miscellaneous)
+  - [Widget modes](#modes)
+  - [@scaleflex/widget-core](#scaleflexwidget-core)
+    - [Usage](#usage)
+    - [Properties](#properties)
+    - [Events](#events)
+  - [License](#license)
+</details>
+
+## Main features:
+
+- Single and multiple file upload into a Scaleflex storage container (project)
+- Upload via Drag & Drop or Copy & Paste
+- Upload from 3rd party storages such as Google Drive, Dropbox, OneDrive, Facebook, Instagram
+- Webcam and screen cast integration to upload realtime videos and screen recordings
+- File explorer and media gallery with file management capabilites (folder creation, file move, rename, ...)
+- Zipped download of multiple files
+- File versioning with history, version browsing
+- File and media asset sharing via accelerated CDN links
+- Media gallery with powerful search capabilities based on tags and customizable metadata (taxonomy)
+- AI-based tagging of images
+- Embedded Scaleflex Image Editor for inline image editing
+- Image annotator and comments for collaboration
+- Image variant generator with customizable template to generate optimal sizes for social media posts (example)
+- Post-upload video transcoding for delivering HLS & DASH playlists for adaptive streaming
+- On-the-fly image resizing via [Cloudimage](https://cloudimage.io)
+
+The widget can be integrated in a web page HTML element, as a pop-up modal on button click.
+
+## Installation
+
+The widget's architecture contains the [**Core**](#scaleflexwidget-core) module and various [**plugins**](#plugins). Each [**plugin**](#plugins) has its own dedicated documentation.
+
+**CDN links to JS and CSS (containing all plugins)**
+
+- Add the following CSS file before the end of `</head>` in your `HTML` file
+
+```html
+<link
+  rel="stylesheet"
+  type="text/css"
+  href="https://cdn.scaleflex.com/plugins/filerobot-widget/v3/stable/filerobot-widget.min.css"
+/>
+```
+
+- Add the following JS file before the end of `</body>` in your `HTML` file.
+
+```html
+<script
+  type="text/javascript"
+  src="https://cdn.scaleflex.com/plugins/filerobot-widget/v3/stable/filerobot-widget.min.js"
+></script>
+```
+
+> The CDN versions of the library contains all plugins whereas npm gives you flexibility to include only plugins/modules you need to have lighter lib files. For example, you can just use the [**Core**](https://www.npmjs.com/package/@scaleflex/widget-core/#scaleflexwidget-core) module and the [**XHR Upload**](https://www.npmjs.com/package/@scaleflex/widget-xhr-upload/#scaleflexwidgetxhr-upload) plugin to integrate a simple uploader to your application, without file explorer, media gallery and image editor.
+
+## Quickstart
+
+### Demo
+
+[See the FMAW in action here](https://cdn.scaleflex.com/plugins/filerobot-widget/v3/demo/index.html).
+
+The following implementation examples build a FMAW for uploading files, showing the [**Scaleflex Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer/#scaleflexwidgetexplorer) as a file explorer/media gallery, enabling the [**Webcam**](https://www.npmjs.com/package/@scaleflex/widget-webcam/#scaleflexwidgetwebcam) for capturing photos and videos and the [**Scaleflex Image Editor**](https://www.npmjs.com/package/@scaleflex/widget-image-editor/#scaleflexwidgetimage-editor) for editing images inline.
+
+At minima, you will need the following 3 packages to display a basic FMAW:
+
+- [**Core**](#scaleflexwidget-core)
+- [**Scaleflex Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer/#scaleflexwidgetexplorer)
+- [**XHR Upload**](https://www.npmjs.com/package/@scaleflex/widget-xhr-upload/#scaleflexwidgetxhr-upload)
+
+You can obtain a `container` name and `securityTemplateId` from your [Scaleflex](https://www.scaleflex.com/) account in order for files to be uploaded in the specified Scaleflex storage container (also called project in Scaleflex).
+
+### React
+
+```js
+import ScaleflexWidget from "@scaleflex/widget-core";
+import Explorer from "@scaleflex/widget-explorer";
+import XHRUpload from "@scaleflex/widget-xhr-upload";
+import ImageEditor from "@scaleflex/widget-image-editor";
+import Webcam from "@scaleflex/widget-webcam";
+
+import "@scaleflex/widget-core/dist/style.min.css";
+import "@scaleflex/widget-explorer/dist/style.min.css";
+import "@scaleflex/widget-image-editor/dist/style.min.css";
+import "@scaleflex/widget-webcam/dist/style.min.css";
+
+const App = () => {
+  const scaleflexWidget = useRef(null);
+
+  useEffect(() => {
+    const demoContainer = "scaleflex-tests-v5a";
+    const demoSecurityTemplateId = "......";
+
+    scaleflexWidget.current = ScaleflexWidget({
+      securityTemplateId: demoSecurityTemplateId,
+      container: demoContainer,
+      dev: false,
+    })
+      .use(Explorer, { target: "#scaleflex-widget", inline: true })
+      .use(XHRUpload)
+      .use(ImageEditor)
+      .use(Webcam);
+
+    return () => {
+      scaleflexWidget.current.close();
+    };
+  }, []);
+
+  return (
+    <div>
+      <h1>React Example</h1>
+      <div id="scaleflex-widget" />
+    </div>
+  );
+};
+
+render(<App />, document.getElementById("app"));
+```
+
+### Vanilla (plain) JS
+
+```html
+<html>
+  <head>
+    <link
+      rel="stylesheet"
+      type="text/css"
+      href="https://cdn.scaleflex.com/plugins/filerobot-widget/v3/stable/filerobot-widget.min.css"
+    />
+  </head>
+  <body>
+    <div id="scaleflex-widget"></div>
+
+    <script src="https://cdn.scaleflex.com/plugins/filerobot-widget/v3/stable/filerobot-widget.min.js"></script>
+
+    <script type="text/javascript">
+      const widget = window.ScaleflexWidget;
+      const demoContainer = "scaleflex-tests-v5a";
+      const demoSecurityTemplateId = "......";
+
+      const scaleflexWidget = widget.Core({
+        securityTemplateId: demoSecurityTemplateId,
+        container: demoContainer,
+        dev: false, // optional, default: false
+      });
+      const Explorer = widget.Explorer;
+      const XHRUpload = widget.XHRUpload;
+      const ImageEditor = widget.ImageEditor;
+      const Webcam = widget.Webcam;
+
+      scaleflexWidget
+        .use(Explorer, { target: "#scaleflex-widget", inline: true })
+        .use(XHRUpload)
+        .use(ImageEditor)
+        .use(Webcam);
+    </script>
+  </body>
+</html>
+```
+
+## Modules
+
+The Scaleflex Core module: [**Core**](#scaleflexwidget-core)
+
+## Plugins
+
+### UI Elements
+
+- [**Scaleflex Explorer**](https://www.npmjs.com/package/@scaleflex/widget-explorer/#scaleflexwidgetexplorer): Scaleflex File Explorer provides different modes to achieve different capabilities like basic uploader, light DAM for managing your assets or even a file picker for your assets with customizing your functionality.
+
+  Following plugins can be added to augment the Scaleflex's File Explorer capabilities:
+
+  - [**Progress Panel**](https://www.npmjs.com/package/@scaleflex/widget-progress-panel/#scaleflexwidgetprogress-panel): displays upload, download, video activities and other processes status in a progress panel.
+
+  - [**Informer**](https://www.npmjs.com/package/@scaleflex/widget-informer/#scaleflexwidgetinformer): displays pop-up messages/statuses related to file operations.
+
+  - [**Scaleflex Image Editor**](https://www.npmjs.com/package/@scaleflex/widget-image-editor/#scaleflexwidgetimage-editor): inline image editor with functionalities such as `filters, crop, resizing, watermark, collages, etc...`. Also used by other features of the Widget such as the variant generator and export function.
+
+  - [**Pre-Upload Image Processor**](https://www.npmjs.com/package/@scaleflex/widget-preupload-processors/#scaleflexwidgetpreupload-processors): ability to resize a large image into the storage container before upload.
+
+### Upload connectors
+
+- [**Google Drive**](https://www.npmjs.com/package/@scaleflex/widget-google-drive/#scaleflexwidgetgoogle-drive): import files from Google Drive.
+
+- [**Dropbox**](https://www.npmjs.com/package/@scaleflex/widget-dropbox/#scaleflexwidgetdropbox): import files from Dropbox.
+
+- [**Box**](https://www.npmjs.com/package/@scaleflex/widget-box/#scaleflexwidgetbox): import files from Box.
+
+- [**Instagram**](https://www.npmjs.com/package/@scaleflex/widget-instagram/#scaleflexwidgetinstagram): import images and videos from Instagram.
+
+- [**Facebook**](https://www.npmjs.com/package/@scaleflex/widget-facebook/#scaleflexwidgetfacebook): import images and videos from Facebook.
+
+- [**OneDrive**](https://www.npmjs.com/package/@scaleflex/widget-onedrive/#scaleflexwidgetonedrive): import files from Microsoft OneDrive.
+
+- [**Import From URL**](https://www.npmjs.com/package/@scaleflex/widget-url/#scaleflexwidgeturl): import direct URLs from anywhere on the web.
+
+- [**Webcam**](https://www.npmjs.com/package/@scaleflex/widget-webcam/#scaleflexwidgetwebcam): capture photos or videos from the device's camera and upload them to the Scaleflex storage container.
+
+- [**Screen Capture**](https://www.npmjs.com/package/@scaleflex/widget-screen-capture/#scaleflexwidgetscreen-capture): device screen recorder.
+
+- [**Attach Drag & Drop zone**](https://www.npmjs.com/package/@scaleflex/widget-attach-dnd/#scaleflexwidgetattach-dnd): Plugin for attaching drag & drop zone for some specific HTML element in your page.
+
+- [**Pixaforge**](https://www.npmjs.com/package/@scaleflex/widget-pixaforge/#scaleflexwidgetpixaforge): Plugin for importing free images & icons from Pixaforge that contains free gallery for different categories & tags.
+
+- [**Canva**](https://www.npmjs.com/package/@scaleflex/widget-canva/#scaleflexwidgetcanva): Create your own design & customize it then upload it through the widget on the go by integrating this plugin inside the widget.
+
+- [**Unsplash**](https://www.npmjs.com/package/@scaleflex/widget-unsplash/#scaleflexwidgetunsplash): import files from unsplash.
+
+### Destinations
+
+- [**XHR Upload**](https://www.npmjs.com/package/@scaleflex/widget-xhr-upload/#scaleflexwidgetxhr-upload): handles multipart file upload.
+
+- [**Tus**](https://www.npmjs.com/package/@scaleflex/widget-Tus/#scaleflexwidgettus): applies resumable upload (BE must support that).
+
+### Miscellaneous
+
+- [**Thumbnail Generator**](https://www.npmjs.com/package/@scaleflex/widget-thumbnail-generator/#scaleflexwidgethumbnail-generator): thumbnail generator for different files to be used as file preview.
+
+## Widget modes
+
+Go to the [Explorer plugin modes](https://www.npmjs.com/package/@scaleflex/widget-explorer#explorermodes) as it is responsible about utilizing the different modes of the widget.
+
+## `@scaleflex/widget-core`
+
+The core module of the Scaleflex Media Asset Widget. This module contains all common settings shared across all FMAW plugins and can be used standalone in your upload workflows to interact with Scaleflex DAM.
+
+## Usage
+
+### NPM
+
+```bash
+npm install --save @scaleflex/widget-core
+```
+
+### YARN
+
+```bash
+yarn add @scaleflex/widget-core
+```
+
+then
+
+```js
+import ScaleflexWidget from '@scaleflex/widget-core'
+...
+...
+...
+const scaleflexWidget = ScaleflexWidget(propertiesObject)
+```
+
+### CDN
+
+If installed via the [CDN link](../@scaleflex/widget-core#installation), the plugin is inside the `ScaleflexWidget` global object as `ScaleflexWidget.Core`
+
+```js
+const scaleflexWidgetCore = window.ScaleflexWidget.Core
+...
+...
+...
+const scaleflexWidget = scaleflexWidgetCore(propertiesObject)
+```
+
+### Module's styles
+
+```js
+import "@scaleflex/widget-core/dist/style.css";
+```
+
+or via the minified versions
+
+```js
+import "@scaleflex/widget-core/dist/style.min.css";
+```
+
+> The Core's styles must be imported before the scaleflexWidget's plugins' styles.
+
+## Properties
+
+Required attributes are marked with **_(Required)_**.
+
+### `container`
+
+<u>Type:</u> `string` **_Required_**.
+
+<u>Default:</u> `undefined`
+
+The container token (Scaleflex token) that will be used in all the widget's modes & plugins ex. (listing files/folders, uploading, renaming, deleting...etc.). Register for an account at [scaleflex.com](www.scaleflex.com) to obtain a token.
+
+### `securityTemplateId`
+
+**PREVIOUSLY**: `securityTemplateID`
+
+<u>Type:</u> `string` **_Required_**.
+
+<u>Default:</u> `undefined`
+
+The Security Template Id is used for the the FMAW to request session-specific API access keys, also known as SASS key. [Security Templates](https://docs.filerobot.com/go/filerobot-documentation/en/dam-api/api-authentication/security-templates#85e64ad9266588659bf160f345eb46ca87ab1362) are created in the Scaleflex Asset Hub and define permissions and validity for SASS keys. They work similar to oAuth2 tokens.
+
+### `id`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `'scaleflexWidget'`
+
+The unique identifier used for identifying the widget's instance (# in HTML selector).
+
+### `dev`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`.
+
+Enables the development mode which sends all requests to development server, otherwise all the endpoints defaults to the production server.
+
+> Note: enabling development mode, will show some features that won't work (they're hidden in production mode) with u cause of the generated sass key permissions (that is generated through the security template id).
+
+### `theme`
+
+<u>Type:</u> `object`.
+
+<u>Default:</u>
+
+```
+{
+  palette: {...},
+  breakpoints: {...},
+  typography: {...}
+  shadows: {...}
+}
+```
+
+> You can check default values for each property here:
+
+- [color palette](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/palette/entity/default-palette.ts)
+- [typography](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/typography/entity/default-typography.ts)
+- [breakpoints](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/breakpoints/entity/default-breakpoints.ts)
+- [shadows](https://github.com/scaleflex/ui/blob/master/packages/ui/src/theme/roots/shadows/entity/default-shadows.ts)
+
+We are using [**@scaleflex/ui**](https://github.com/scaleflex/ui/tree/master/packages/ui/src/theme) theme system to have global theme wrapping the project and you can customize it by overriding the default theme values.
+
+You can check the values you can override for each property:
+
+- For color palette you can select the property key from this [**list**](https://github.com/scaleflex/ui/blob/master/packages/ui/src/utils/types/palette/color.ts#L1)
+- For typography, you can change [**font variant**](https://github.com/scaleflex/ui/blob/master/packages/ui/src/utils/types/typography/font-variant.ts) and [**font weight**](https://github.com/scaleflex/ui/blob/master/packages/ui/src/utils/types/typography/font-weight.ts)
+- For breakpoints [**list**](https://github.com/scaleflex/ui/blob/master/packages/ui/src/utils/types/css/breakpoint.ts)
+- For Shadows [**list**](https://github.com/scaleflex/ui/blob/master/packages/ui/src/utils/types/shadows/shadows.ts)
+
+```
+  theme: {
+      palette: {
+         "accent-primary": "#479898",
+         "accent-primary-hover": "#479898",
+         "accent-primary-active": "#479898",
+         "accent-stateless": "#479898",
+         "link-pressed": "#479898",
+         "border-active-bottom": "#479898"
+       },
+       typography: {
+          "title-h6": {
+            fontWeight: FontWeight.Medium, // 500
+            fontSize: '12px',
+            lineHeight: '18px',
+          },
+       },
+       breakpoints: {
+         values: {
+           xs: 0,
+           md: 900,
+           xl: 1400
+         }
+       },
+       shadows: {
+         "shadow-sm": '6px -4px 12px 0px rgba(146, 166, 188, 0.14)'
+       }
+    }
+```
+
+> NOTE: You must import the font family from your side in 2 weights (Normal === 400, Medium === 500) to have fonts work properly and show text as expected, which means `Roboto` is not included in the plugin by default so you must import it from your side too if you have provided another font family value through theme don't forget to import it from your side too.
+
+### `autoProceed`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`.
+
+If set to `true`, the upload process of one or multiple assets will start automatically after drag and drop in the upload area or selection from the user's local explorer. If set to `false`, the pre-upload features will be available to the user before starting the upload via the **Upload** button.
+
+> Note: this won't open the progress-panel automatically.
+
+### `allowMultipleUploads`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `true`.
+
+If set to `false`, only one upload will be possible simultaneously.
+
+### `debug`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`.
+
+Turns on the debug mode by exposing the plugin's debug information to the global window object and turns on the logger.
+
+### `logger`
+
+<u>Type:</u> `object`.
+
+<u>Default:</u>
+
+```js
+errorsLogger = {
+  debug: (...args) => {},
+  warn: (...args) => {},
+  error: (...args) => console.error(`[Scaleflex] [${getTimeStamp()}]`, ...args),
+};
+```
+
+### `restrictions`
+
+<u>Type:</u> `object`.
+
+<u>Default:</u>
+
+```js
+{
+  maxFileSize: null,
+  maxNumberOfFiles: null,
+  minNumberOfFiles: null,
+  allowedFileTypes: null,
+  maxItemsSizeForCompression: null,
+}
+```
+
+Upload restrictions:
+
+| Property                       | Type                | Default | Description                                                                |
+| ------------------------------ | ------------------- | ------- | -------------------------------------------------------------------------- |
+| **`maxFileSize`**              | `number` \| `null`  | `null`  | maximum file size in bytes                                                 |
+| **`maxTotalFilesSize`**        | `number` \| `null`  | `null`  | maximum files size in megabyte                                             |
+| **`totalUploadedFilesSize`**   | `number` \| `null`  | `null`  | total uploaded files size in megabyte                                      |
+| **`hideRestrictionsInformer`** | `boolean` \| `null` | `null`  | hide restrictions informer message                                         |
+| **`maxNumberOfFiles`**         | `number` \| `null`  | `null`  | maximum number of files to be uploaded simultaneously                      |
+| **`minNumberOfFiles`**         | `number` \| `null`  | `null`  | minimum number of files before upload can star                             |
+| **`allowedFileTypes`**         | `array` \| `null`   | `null`  | accepted file types or extensions, eg. `['image/*', 'image/jpeg', '.jpg']` |
+
+Upload restrictions can also be governed in the backend by the [Security Template](#securitytemplateid) configured.
+
+Download restrictions:
+
+| Property                         | Type               | Default | Description                                 |
+| -------------------------------- | ------------------ | ------- | ------------------------------------------- |
+| **`maxItemsSizeForCompression`** | `number` \| `null` | `null`  | maximum items size for compression in bytes |
+
+### `onBeforeFileAdded`
+
+<u>Type:</u> `function`.
+
+<u>Default:</u> `(currentFile, files) => currentFile`
+
+Gives the possibility to do some checks before adding the file to the state's object,
+
+- if the function returns `true`, the file is added to the state.
+- if the function returns a modified `file` object the returned object would be added to the state.
+- if the function returns `false`, the file is not added to the state.
+
+### `onBeforeUpload`
+
+<u>Type:</u> `function`.
+
+<u>Default:</u> `onBeforeUpload: (files) => files`
+
+Gives the possibility to do some checks before starting the upload process
+
+- if the function returned `true` the upload would start.
+- if returned `files` object the returned object would be processed.
+- if returned `false` the uploading process won't start.
+
+### `language`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u>`'en'`
+
+Used to determine which language to use from the widget's backend translated languages.
+
+### `locale`
+
+<u>Type:</u> `object`.
+
+<u>Default:</u> default locales inside `lib/defaultLocale.js`
+
+You can override some labels by specifying a translation object here, such as:
+
+````js
+{
+  strings: {
+    loaderLoadingLabel: 'Loading'
+  }
+}
+
+## Methods
+
+### `scaleflexWidget.getId()`
+
+Gets the Scaleflex Media Asset Widget's instance id.
+
+### `scaleflexWidget.use(plugin, pluignOptions)`
+
+Adds a plugin to the Scaleflex Media Asset Widget's instance:
+
+```js
+import ScaleflexWidget from '@scaleflex/widget-core'
+import Explorer from '@scaleflex/widget-explorer'
+
+const scaleflexWidget = ScaleflexWidget()
+scaleflexWidget.use(Explorer, {...})
+````
+
+Refer to the individual plugin's documentation page for available configuration and customization options.
+
+### `scaleflexWidget.getPlugin(pluginId)`
+
+Returns the plugin's instance with the provided id for accessing its methods & state.
+
+### `scaleflexWidget.removePlugin(pluginInstance)`
+
+Removes a currently initialized plugin by passing the plugin's instance retrieved from the [getPlugin](#scaleflexwidgetgetpluginpluginid) method.
+
+### `scaleflexWidget.setOptions(options)`
+
+Passes [Properties](#properties) to the Widget to change properties set during initialization:
+
+```js
+import ScaleflexWidget from "@scaleflex/widget-core";
+
+const scaleflexWidget = ScaleflexWidget();
+scaleflexWidget.setOptions({
+  autoProceed: true,
+});
+```
+
+Individual plugin options can also be changed by using [getPlugin](#scaleflexwidgetgetpluginpluginid)
+
+```js
+import Scaleflex from "@scaleflex/widget-core";
+
+const scaleflexWidget = ScaleflexWidget();
+scaleflexWidget.use(Explorer, { id: "Explorer" });
+scaleflexWidget.getPlugin("Explorer").setOptions({
+  animateOpenClose: false,
+});
+```
+
+### `scaleflexWidget.addFile(fileObject)`
+
+Adds a file into the widget's state and returns the temporary generated id for that file.
+
+> [restrictions](#restrictions) are checked and [onBeforeFileAdded](#onbeforefileadded) called before adding the file.
+
+### `scaleflexWidget.getFile(fileId)`
+
+Gets the file object using its id.
+
+### `scaleflexWidget.removeFile(fileId)`
+
+Removes a file from the widget's state via its id.
+
+### `scaleflexWidget.getFiles()`
+
+Returns all the file objects currently loaded in the widget.
+
+### `scaleflexWidget.upload(files, callback)`
+
+An async function that starts uploading files, returns a promise resolved with an object `result: { successful, failed }` containing:
+
+- `successful`: array with file objects successfully uploaded.
+- `failed`: array with files objects for which upload failed.
+
+### `scaleflexWidget.retryAll()` _Deprecated_
+
+Retries all the failed uploads.
+
+### `scaleflexWidget.retryUpload(fileId)`
+
+Retries a failed upload for a file referenced by its id.
+
+### `scaleflexWidget.cancelUploads()`
+
+emit [cancel-uploads](#cancel-uploads) event and cancel uploads.
+
+### `scaleflexWidget.setCoreCommonState(object)`
+
+Updates the internal state of the widget's core common state.
+
+### `scaleflexWidget.getGlobalState()`
+
+Returns the internal state/store of the widget's.
+
+### `scaleflexWidget.setUploadPanelFileState(fileId, state)` _Deprecated_ - changed to setFileStateBeforeUpload
+
+updates the state of a file inside the uploads panel before triggering upload.
+
+### `scaleflexWidget.setProgressPanelFileState(fileId, state)` _Deprecated_ - use [`setFileUploadingState`](#setFileUploadingState) instead
+
+updates the state of a file inside the [Progress Panel](../@scaleflex/widget-progress-panel/#scaleflexwidgetprogress-panel).
+
+### `scaleflexWidget.setFileUploadingState(fileId, state)`
+
+updates the state of a file uploading.
+
+### `scaleflexWidget.getFileUploading(fileId)`
+
+Returns a file that is uploading.
+
+### `scaleflexWidget.setFilesInfoMetaTags(fileIds, filesInfoMetaTagsData, forceUpdate)`
+
+Updates the info and/or meta object(s) of the passed files that would be uploaded with the provided `info` and `meta` objects parameters received from `filesInfoMetaTagsData` object in the following format `{ info: {}, meta: {}, tags: {} }`, `forceUpdate` means replace the current tags instead of deep merging with the current ones.
+
+### `scaleflexWidget.reset()` _Deprecated_
+
+Returns everything to the initial state of the widget ex. stops all the files uploading, reset their progress and removes all of them.
+
+### `scaleflexWidget.close()`
+
+Removes all the installed plugins & closes the current widget's instance.
+
+### `scaleflexWidget.on('event', handler)`
+
+Adds/Subscribe a handler/callback function to be called on emitting/firing the specified `scaleflexWidget event`, [full list of available events](#events).
+
+### `scaleflexWidget.once('event', handler)`
+
+Same as `scaleflexWidget.on` but the handler is removed after being called once.
+
+### `scaleflexWidget.off('event', handler)`
+
+Un-subscribe/Removes the specified handler for scaleflexWidget's event.
+
+### `scaleflexWidget.info(message, type, timeout)`
+
+Shows an informer with the specified message to the user:
+
+| Property      | Type                              | Default     | Description                                                                                                                                                                                    |
+| ------------- | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`message`** | `string` \| `object` _*Required*_ | `undefined` | Defines the message to be shown to the user, either a string ex. `Some message` or `{ message: 'Some headline message', details: 'Detailed message would be shown on hovering the informer' }` |
+| **`type`**    | `string`                          | `info`      | choses the type of the informer whether `info, warning or success`                                                                                                                             |
+| **`timeout`** | `number`                          | `3000`      | The duration which the message would still be shown for in milliseconds                                                                                                                        |
+
+#### `scaleflexWidget.log(message, type)`
+
+Logs a message in the [`logger`](#logger):
+
+| Property      | Type                  | Default     | Description                                                            |
+| ------------- | --------------------- | ----------- | ---------------------------------------------------------------------- |
+| **`message`** | `string` _*Required*_ | `undefined` | the message would be logged/added/shown in the logger.                 |
+| **`type`**    | `string`              | `debug`     | the type of that logged message whether `debug/info, warning or error` |
+
+## Events
+
+The widget emits different events that you could subscribe to or add your handler to be called with the provided arguments passed while emitting/firing the event, the events are listed below with examples show the parameters for handler:
+
+### `file-added`
+
+Emitted when a file has been added to the selected files for uploading.
+
+`params`:
+
+- `file`: The file object whom thumbnail is generated.
+
+example
+
+```js
+scaleflexWidget.on("file-added", (newFile) => {
+  console.log("The new file object which is added:", newFile);
+});
+```
+
+### `file-removed`
+
+Emitted when a file has been removed from the selected files for uploading.
+
+`params`:
+
+- `file`: The file object removed.
+- `deletionReason`: The reason for deleting the file or from where the deletion has done might be provided or not.
+
+example
+
+```js
+scaleflexWidget.on("file-removed", (removedFile, reason) => {
+  console.log(
+    `The file ${removedFile.name} is removed because ${reason}, file's object:`,
+    removedFile
+  );
+});
+```
+
+### `upload`
+
+Emitted on creating a new upload process.
+
+`params`:
+
+- `object`: An object contains both the uploading process id and the the files ids for files to be uploaded, ex. `{ id: uploadId, filesIds: fileIds, files }`.
+
+example
+
+```js
+scaleflexWidget.on("upload", (uploadProcess) => {
+  console.log("Upload started with upload id: ", uploadProcess.id);
+  console.log("Contains the following file ids", uploadProcess.filesIds);
+});
+```
+
+### `restriction-failed`
+
+Emitted when the restriction checking is failed and there is a file doesn't meet the restrictions.
+
+`params`:
+
+- `file`: The file object that has failed the check.
+- `error`: The error faced/fired during the check.
+
+example
+
+```js
+scaleflexWidget.on("restriction-failed", (file, error) => {
+  console.log("Couldnt process the following file object", file);
+  console.log("As the following error fired:", error);
+});
+```
+
+### `upload-started`
+
+Emitted when upload is started.
+
+`params`:
+
+- `file`: The file object that started uploading.
+- `started`: An object contains upload Id, ex. `{ uploadId: upload id assigned to current file }`.
+
+### `upload-progress`
+
+Emitted when there is a progress of some file uploading in the upload process.
+
+`params`:
+
+- `file`: The file object that has some progress in its uploading.
+- `progress`: An object contains the progress of the file being uploaded, ex. `{ filerobot: plugin's instance, bytesFinished: 1500, bytesTotal: 3500, uploadId: upload id assigned to current file }`.
+
+example
+
+```js
+scaleflexWidget.on("upload-progress", (file, progress) => {
+  console.log("The following file object progressed", file);
+  console.log("The progress object is as following", progress);
+});
+```
+
+### `upload-success`
+
+Emitted when a file is successfully uploaded.
+
+`params`:
+
+- `file`: The file object that has uploaded.
+- `response`: The upload request response received.
+- `options`: object that contains the uploadId
+
+example
+
+```js
+scaleflexWidget.on("upload-success", (file, response, { uploadId }) => {
+  console.log(
+    `The ${file.name} with the object ${file} is uploaded ${uploadId} and the whole response`,
+    response
+  );
+});
+```
+
+### `upload-error`
+
+Emitted when a file faced some error/issue while uploading.
+
+`params`:
+
+- `file`: The file object which fired the error.
+- `error`: object that contains error details, upload response and uploadId that was assigned to current file.
+- `options`: object that contains the upload response and uploadId
+
+example
+
+```js
+scaleflexWidget.on("upload-error", (file, error, { response, uploadId }) => {
+  console.log(
+    "File faced that error while uploading",
+    file,
+    error,
+    response,
+    uploadId
+  );
+});
+```
+
+### `upload-retry`
+
+Emitted on some file uploading is retried.
+
+`params`:
+
+- `fileId`: The id of the file which its upload process is retried.
+
+example
+
+```js
+scaleflexWidget.on("upload-retry", (fileId) => {
+  console.log("The following file id is being re-uploaded:", fileId);
+});
+```
+
+### `progress`
+
+Emitted on having a progress of an upload process's total progress.
+
+`params`:
+
+- `totalProgress`: The total progress value of the current uploading process.
+
+example
+
+```js
+scaleflexWidget.on("progress", (totalProgress) => {
+  console.log("The uploading total progress for now: ", totalProgress);
+});
+```
+
+### `cancel-uploads`
+
+Emitted when the whole upload process is canceled (all files uploading are canceled).
+
+`params`: No params returned.
+
+example
+
+```js
+scaleflexWidget.on("cancel-uploads", () => {
+  console.log("The upload is canceled");
+});
+```
+
+### `complete`
+
+Emitted when the whole upload process done and completed.
+
+`params`:
+
+- `completionObject`: An object contains the results of the completed upload process, ex. `{ failed: failedFiles, uploadId: ..., successful: uploadedFiles }`.
+
+example
+
+```js
+scaleflexWidget.on("complete", ({ failed, uploadId, successful }) => {
+  console.log(
+    `The upload ${uploadId} is completed with following results success then failed files`,
+    successful,
+    failed
+  );
+});
+```
+
+### `items-deleted`
+
+Emitted when files/folders are deleted.
+
+`params`:
+
+- `detailsObject`: An object contains details of removed items, ex. `{ removedFolders: [...], removedFiles: [...] }`.
+
+example
+
+```js
+scaleflexWidget.on("items-deleted", ({ removedFolders, removedFiles }) => {
+  console.log("Items deleted:");
+  console.log("Removed folders:", removedFolders);
+  console.log("Removed files:", removedFiles);
+});
+```
+
+### `error`
+
+Emitted when the whole upload process faced an error.
+
+`params`:
+
+- `filesIds`: files ids that have an error.
+- `error`: The error shown of the uploading process.
+- `uploadId`: The id of the errored uploading process.
+
+example
+
+```js
+scaleflexWidget.on("error", (filesIds, error, { uploadId }) => {
+  console.log(
+    `The upload with id ${uploadId} faced this error while uploading`,
+    error
+  );
+});
+```
+
+### `reset-progress`
+
+Emitted when the upload's progress is reset to 0.
+
+`params`: No params returned.
+
+example
+
+```js
+scaleflexWidget.on("reset-progress", () => {
+  console.log("The progress is reset");
+});
+```
+
+### `info-visible`
+
+Emitted on showing an `info` message to the user.
+
+`params`: No params returned.
+
+example
+
+```js
+scaleflexWidget.on("info-visible", () => {
+  console.log("inFo message shown.");
+});
+```
+
+### `info-hidden`
+
+Emitted on hiding an `info` message that were shown to the user.
+
+`params`: No params returned.
+
+example
+
+```js
+scaleflexWidget.on("info-hidden", () => {
+  console.log("The progress is hidden.");
+});
+```
+
+### `explorer:modal-open`
+
+Emitted on opening the widget in a modal through the [explorer](../@scaleflex/widget-explorer) plugin.
+
+`params`: No params returned.
+
+example
+
+```js
+scaleflexWidget.on("explorer:modal-open", () => {
+  console.log("The widget's explorer modal is opened .");
+});
+```
+
+### `explorer:modal-close`
+
+Emitted on closing the widget's main modal.
+
+`params`: No params returned.
+
+example
+
+```js
+scaleflexWidget.on("explorer:modal-close", () => {
+  console.log("The widget's modal is closed.");
+});
+```
+
+### `export`
+
+emitted when the user downloads a file.
+
+`params`:
+
+- `files`: An array of files checked/selected for exporting.
+- `popupExportSucessMsgFn`: A function if called will show exported successfully pop-up to the user.
+- `downloadFilesPackagedFn`: A function if called will download files (the files passed in the first argument if nothing passed then the files exported will be used) as ZIP and show download progress in widget (item's Uuid is used & must exists on backend's side -- NOT FULLY WORKING --).
+- `downloadFileFn`: A function if called will download one file (the file passed as first argument if nothing passed then the first file in exported files will be used) directly without packaging/zipping it and show download progress in widget (`file.url.download` link is used in download and fallbacks to `file.url.permalink`).
+
+example
+
+```js
+scaleflexWidget.on(
+  "export",
+  (files, popupExportSucessMsgFn, downloadFilesPackagedFn, downloadFileFn) => {
+    console.log("The following files are chosen to be exported", files);
+    popupExportSucessMsgFn(); // shows exported successfully message as pop-up.
+    downloadFilesPackagedFn(files.slice(1).map(({ file }) => file)); // no need to pass file.slice(1) if u would download all exported files.
+    const { file } = file[0];
+    downloadFileFn({ ...file, url: { ...file.url, download: files[0].link } }); // no need to pass file[0] if u would download the first file of exported files.
+  }
+);
+```
+
+### `url-modified`
+
+Emitted when the user uses the [image editor plugin](../@scaleflex/widget-image-editor) in cloudimage mode and changes the url.
+
+`params`:
+
+- `modifiedUrl`: The modified url for the image.
+- `designState`: The image editor's design state object.
+- `info`: the function that gives you possibility to show a [`@scaleflex/widget-informer`](../@scaleflex/widget-informer/#scaleflexwidgetinformer) message.
+
+example
+
+```
+scaleflexWidget.on('modified-url', (modifiedUrl, designState, info) => {
+  console.log('The new url is', modifiedUrl)
+  console.log('Image editor design state:', designState)
+  info('Url has changed', 'success', 3000)
+})
+```
+
+<!-- Variables -->
+
+[npm-url]: https://www.npmjs.com/package/@scaleflex/widget-core
+[license-url]: https://opensource.org/licenses/MIT
+[sfx-url]: https://www.scaleflex.com/
+[version-url-latest]: https://www.npmjs.com/package/@scaleflex/widget-core
+[version-url-stable]: https://www.npmjs.com/package/@scaleflex/widget-core/v/stable
+[version-url]: https://www.npmjs.com/package/@scaleflex/widget-core
+[codeSandbox-url]: https://codesandbox.io/s/filerobot-widget-v3-c5l9th
+[npm-image]: https://img.shields.io/npm/v/@telus/remark-config.svg?style=for-the-badge&logo=npm
+[license-image]: https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge
+[made-by-image]: https://img.shields.io/badge/%3C%2F%3E%20with%20%E2%99%A5%20by-the%20Scaleflex%20team-6986fa.svg?style=for-the-badge
+[plugins-image]: https://img.shields.io/static/v1?label=Scaleflex&message=Plugins&color=yellow&style=for-the-badge
+[filerobot-image]: https://img.shields.io/static/v1?label=Scaleflex&message=website&color=orange&style=for-the-badge
+[filerobot-version-latest]: https://img.shields.io/npm/v/@scaleflex/widget-core?label=latest&style=for-the-badge&logo=npm
+[filerobot-version-stable]: https://img.shields.io/npm/v/@scaleflex/widget-core/stable?label=stable&style=for-the-badge&logo=npm
+[filerobot-version]: https://img.shields.io/npm/v/@scaleflex/widget-core?label=Version&style=for-the-badge&logo=npm
+[codeSandbox-image]: https://img.shields.io/badge/CodeSandbox-black?style=for-the-badge&logo=CodeSandbox
+
+## License
+
+The Scaleflex Media Asset Widget (FMAW) is provided under the [MIT License](https://opensource.org/licenses/MIT)