@scaleflex/widget-explorer 0.0.1

package/README.md

@@ -0,0 +1,1258 @@
+# `@scaleflex/widget-explorer`
+
+[![Plugins][plugins-image]](#plugins)
+[![Website][filerobot-image]][sfx-url]
+[![Version][filerobot-version]][version-url]
+[![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 file Explorer and media gallery plugin of the [Scaleflex Media Asset Widget](https://www.npmjs.com/package/@scaleflex/widget-core).
+
+## Usage
+
+### NPM
+
+```bash
+npm install --save @scaleflex/widget-explorer
+```
+
+### YARN
+
+```bash
+yarn add @scaleflex/widget-explorer
+```
+
+then
+
+```js
+import Explorer from '@scaleflex/widget-explorer'
+...
+...
+...
+scaleflexWidget.use(Explorer, propertiesObject)
+```
+
+### CDN
+
+If installed via a [CDN link](../@scaleflex/widget-core#installation), the plugin is inside the `Scaleflex` global object as `Scaleflex.Explorer`
+
+```js
+const Explorer = window.ScaleflexWidget.Explorer
+...
+...
+...
+scaleflexWidget.use(Explorer, propertiesObject)
+```
+
+### Plugin styles
+
+```js
+import "@scaleflex/widget-core/dist/style.css";
+import "@scaleflex/widget-explorer/dist/style.css";
+```
+
+or via the minified versions
+
+```js
+import "@scaleflex/widget-core/dist/style.min.css";
+import "@scaleflex/widget-explorer/dist/style.min.css";
+```
+
+> The plugin's css file should be imported after the [Core's css file](../@scaleflex/widget-core/#modules-styles) for having the styles shown correctly.
+
+## Explorer modes
+
+### Uploader mode (default mode)
+
+The mode used for uploading files using your chosen/configured uploading provider to your token and chosen path.
+
+#### how to?
+
+Just initialize the widget normally and keep [`ExploreViewComponent`](#exploreviewcomponent) property in Explorer plugin with a null/empty value.
+
+```js
+// ScaleflexWidget.Core initializations
+scaleflexWidget.use(Explorer, {
+  // ...otherParams,
+  ExploreViewComponent: null
+})
+scaleflexWidget.use(XHRUpload, {
+  uploadToFolderPath: '/test'
+})
+```
+
+### Browser/Light-DAM mode
+
+The mode used for browsing files/folders using the Explorer's main view and do some light-weight/quick functionalities like reading & writing files metadata in addition to uploading files.
+
+#### how to?
+
+Initialize the plugin with providing the component `@scaleflex/widget-explorer/lib/components/ExploreView` to the [`ExploreViewComponent`](#exploreviewcomponent) property.
+
+```js
+import ExploreView from '@scaleflex/widget-explorer/lib/components/ExploreView'
+// ...scaleflexWidget and other plugins initializations
+
+scaleflexWidget.use(Explorer, {
+  // ...otherParams,
+  ExploreViewComponent: ExploreView
+})
+```
+
+### Assets picker mode
+
+Enabling the ability to browse the files/folders and preview them with and their metadata. Select files from the current token and do your own custom functionality after selecting the files.
+
+#### how to?
+
+1. Initialize the plugin and provide the component `@scaleflex/widget-explorer/lib/components/ExploreView` to the [`ExploreViewComponent`](#exploreviewcomponent) property.
+2. provide `useAssetsPicker` property with a `true` value.
+
+```js
+import ExploreView from '@scaleflex/widget-explorer/lib/components/ExploreView'
+// ...scaleflexWidget and other plugins initializations
+
+scaleflexWidget.use(Explorer, {
+  // ...otherParams,
+  ExploreViewComponent: ExploreView,
+  useAssetsPicker: true,
+  hideDownloadButtonIcon: true
+})
+```
+
+> Note: please check the plugin's properties in-case you want to customize anything else related to any of the mentioned 3 modes above (some of the properties might work only for specific mode).
+
+## Properties
+
+The Explorer supports multiple properties to customize the plugin according to your needs. Required attributes are marked with **_(Required)_**.
+
+### `config`
+
+<u>Type:</u> `object` **_Required_**.
+
+<u>Default:</u>
+
+```js
+{
+  config: {
+    companyName: 'scaleflex',
+    foldersLimit: 200,
+    filesLimit: 50,
+    rootFolderPath: '/',
+    defaultSort: {
+      by: '',
+      order: ''
+    },
+    tagging: {...} // check tagging section
+  }
+}
+```
+
+The config objects contains the main configuration for the plugin to interact with your Scaleflex project:
+
+#### `companyName`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `scaleflex`
+
+Your company name, used when sharing assets.
+
+#### `foldersLimit`
+
+<u>Type:</u> `number`.
+
+<u>Default:</u> `200`
+
+Number of folders to be retrieved with folders initial request.
+
+#### `maxCountOfSelectedFiles`
+
+<u>Type:</u> `number`.
+
+<u>Default:</u> `undefined`
+
+Maximum number of files that can be selected.
+
+#### `filesLimit`
+
+<u>Type:</u> `number`.
+
+<u>Default:</u> `50`
+
+Number of files to be retrieved with files initial request.
+
+#### `rootFolderPath`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `/`
+
+Overrides the root folder path when there is no `list scope` linked with the [securityTemplateId](..@scaleflex/widget-core/README.md/#securitytemplateid) or at least 2 folders or more in the `list scope` otherwise it has no effect.
+
+> Note: If the [securityTemplateId](..@scaleflex/widget-core/README.md/#securitytemplateid) has 2 folders at least, then the provided folder path must be one of these folders or one of their sub-folders.
+
+#### `defaultSort`
+
+<u>Type:</u> `object`.
+
+<u>Default:</u> `{ by: 'name', order: 'asc' }`
+
+Customize the default selected sort option for both files & folders shown in the main view (not applicable for folders tree or objects' trees) applied for all the files shown regardless of the opened view.
+
+The options available sorting
+
+| Property    | Type     | Default | Description                                                                                               |
+| ----------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
+| **`by`**    | `string` | `name`  | Defines the default sort by param, should be one of ['name', 'created_at', 'modified_at', 'size', 'type'] |
+| **`order`** | `string` | `asc`   | Defines the default sort order param, should be one of ['asc', 'desc']                                    |
+
+> Note: its value is considered only on plugin's install/mount.
+
+#### `defaultSearchSort`
+
+<u>Type:</u> `object`.
+
+<u>Default:</u>
+
+```js
+{
+  text: {
+    by: 'name',
+    order: 'asc'
+  }
+}
+```
+
+Customize the default selected sort option for search shown in the main view, applied for all the files shown regardless of the opened view.
+
+The options available sorting
+
+| Property         | Type     | Default | Description                                                                                                                   |
+| ---------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| **text.`by`**    | `string` | `name`  | Defines the default search sort by param, should be one of ['relevance', 'name', 'created_at', 'modified_at', 'size', 'type'] |
+| **text.`order`** | `string` | `asc`   | Defines the default search sort order param, should be one of ['asc', 'desc']                                                 |
+
+#### `tagging`
+
+<u>Type:</u> `object`.
+
+<u>Default:</u>
+
+```js
+{
+  tagging: {
+    enabled: false,
+    autoTagging: false,
+    suggestedTagsOnly: false,
+    language: 'en',
+    confidence: 60,
+    limit: 10,
+    provider: 'google',
+    suggestionList: []
+  }
+}
+```
+
+The options available for tagging
+
+| Property                | Type       | Default | Description                                                                                                                                                                       |
+| ----------------------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`enabled`**           | `boolean`  | `false` | Enable/disable tags                                                                                                                                                               |
+| **`autoTagging`**       | `boolean`  | `false` | Enable/disable auto-tagging                                                                                                                                                       |
+| **`suggestedTagsOnly`** | `boolean`  | `false` | Enable/disable suggested tags only. When it's TRUE, users can only select tags from a pre-defined list. Notice that when suggestedTagsOnly is TRUE, autoTagging will be disabled. |
+| **`language`**          | `string`   | `en`    | AutoTagging config that we add in POST process/autoTag request data.meta                                                                                                          |
+| **`confidence`**        | `number`   | `60`    | AutoTagging config that we add in POST process/autoTag request data.meta                                                                                                          |
+| **`limit`**             | `number`   | `10`    | AutoTagging config that we add in POST process/autoTag request data.meta                                                                                                          |
+| **`provider`**          | `string`   | `[]`    | AutoTagging config that we add in POST process/autoTag request data.meta                                                                                                          |
+| **`suggestionList`**    | `object[]` | `1 `    | Tags suggestions list that is shown under tags field. By default we show primary tags, but when user start typing we filter full suggestionList. Object format:                   |
+
+```js
+    {
+      sid: string, // Short id like: '#tg1885f'
+      names: {
+        en: string,
+        fr: string
+      },
+      primary: boolean // If true, tag will be shown in Suggestions list below tags field
+    }
+```
+
+### `inline`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If set to `true`, the plugin will be displayed as inline element in the element referred by the [target](#target) property. Otherwise, it will pop up in a modal upon [trigger](#trigger), see below.
+
+### `trigger`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `null`
+
+The selector used for triggering the display of the plugin modal, if passed to `querySelectorAll` function. Available options:
+
+- HTML tag, eg. `body`
+- CSS selector, eg. `#scaleflex-widget-trigger-button` or `.scaleflex-widget-trigger-button`
+
+Multiple triggers are supported as click events.
+
+> **_Required if_** [inline](#inline): false
+
+### `target`
+
+<u>Type:</u> `string` **_Required_**.
+
+<u>Default:</u> `body`
+
+The selector used for displaying the plugin, if passed to `querySelector` function. Options:
+
+- HTML tag, eg. `body`
+- CSS selector, eg. `#scaleflex-widget-container` or `.scaleflex-widget-container`
+
+### `width`
+
+<u>Type:</u> `number`| `string`.
+
+<u>Default:</u> `768`
+
+Width of the plugin as a number if specified in pixels or a percentage, eg. `'50%'`
+
+### `height`
+
+<u>Type:</u> `number`| `string`.
+
+<u>Default:</u> `538`
+
+Height of the plugin as a number if specified in `px` or a percentage eg. `'35%'`
+
+### `thumbnailWidth`
+
+<u>Type:</u> `number`.
+
+<u>Default:</u> `280`
+
+Pixel width of the asset thumbnails displayed in the gallery. Apect ratio of images is kept in case of image assets.
+
+### `thumbnailHeight`
+
+<u>Type:</u> `number`.
+
+<u>Default:</u> `170`
+
+Pixel height of the asset thumbnails displayed in the gallery. Aspect ratio of images is kept in case of image assets.
+
+### `ExploreViewComponent`
+
+<u>Type:</u> `ReactComponent`.
+
+<u>Default:</u> `null`
+
+<u>Expected value:</u> `@scaleflex/widget-explorer/lib/components/ExploreView`
+
+The view component that is responsible about showing the objects (folders/files...etc.) with the possibility to browse them and enable other functionalities.
+
+### `mutedFilesUuids`
+
+<u>Type:</u> `array`.
+
+<u>Default:</u> `[]`
+
+List of file UUIDs with the state "muted". These files cannot be selected or have any actions performed on them.
+
+### `views`
+
+<u>Type:</u> `array`.
+
+<u>Default:</u> `['ASSETS', 'FOLDERS']`
+
+List of available views.
+
+> **NOTE** some views can be hidden if you don't have permission provided in [securityTemplateId](..@scaleflex/widget-core/README.md/#securitytemplateid).
+
+### `defaultView` _Deprecated_ - use [`view`](#view) instead
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `'FOLDERS'`
+
+View which will be opened by default.
+
+### `view`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `'FOLDERS'`
+
+View which will be currently opened.
+
+### `viewItem`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `null`
+
+Open the provided view's item/object for ex. (folders view => folder path, labels view => label sid or uuid ...etc.)
+
+> Note: No auto redirect to the view, you have to provide the proper view from [`view prop`](#view).
+
+### `viewSubItem`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `null`
+
+A sub item that should be opened inside the provided [`view`](#view) & [`viewItem`](#viewitem).
+
+> Note: No auto redirect to the view, you have to provide the proper view from [`view prop`](#view).
+
+### `layoutType`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `grid`
+
+Specifies the default layout in the view:
+
+| Value      | Description                                 |
+| ---------- | ------------------------------------------- |
+| **`grid`** | shows folders/assets as cards in a grid     |
+| **`list`** | shows the folders/assets as rows in a table |
+
+you can switch between layouts from the layout selector button in the right side in header bar.
+
+### `waitForThumbnailsBeforeUpload`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If set to `true`, delays the start of the upload process until the asset thumbnails are generated and displayed in the plugin.
+
+### `showBar`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `true`
+
+If set to `false`, hides the top bar with **Upload** button, searchBar, create folder button and view button.
+
+### `showImportFromDamButton`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If set to `true`, shows the **Import from DAM** button in the uploads panel to upload from DAM.
+
+> Note: this property requires `ExploreViewComponent` to be provided to be able to browse the objects.
+
+### `hideUploadButton`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If set to `true`, hides the **Upload** button at the top of the plugin.
+
+### `hideSearch`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Hides **Search** field at the top of the plugin.
+
+### `note`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `null`
+
+A custom note displayed in the upload screen for drag&drop.
+
+### `hint`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `null`
+
+A custom hint displayed in the upload screen at the bottom.
+
+### `closeModalOnClickOutside`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Plugin modal will be closed when clicking outside of the modal.
+
+> **_Only relevant if_** [inline](#inline): false
+
+### `preventModalOverlayClickOnUpload`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Plugin modal still opened when click outside of it, if there's selected files to be uploaded
+
+> **_Only relevant if_** [closeModalOnClickOutside](#closeModalOnClickOutside): true
+
+### `closeAfterFinish`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Modal will close after upload is finished.
+
+> **_Only relevant if_** [inline](#inline): false
+
+### `onClickUploadButton`
+
+<u>Type:</u> `function`.
+
+<u>Default:</u> `() => {}`
+
+A callback function that would be triggered when the user clicks on upload button that is shown in the uploads panel, if returned `true` then the default upload functionality won't be triggered.
+
+### `disableInformer`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Disables the [informer](../@scaleflex/widget-informer/#scaleflexwidget-informer) plugin used to show warnings and errors.
+
+### `disableThumbnailGenerator`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Disables the [thumbnail-generator](../@scaleflex/widget-thumbnail-generator/#scaleflexwidget-thumbnail-generator) plugin that generates image thumbnails.
+
+### `disablePageScrollWhenModalOpen`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `true`
+
+If set to `true`, disables scrolling for the document while the plugin modal is open.
+
+> **_Only relevant if_** [inline](#inline): false
+
+### `disableDownloadButton`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Hides the download button shown in the action bar when selecting files.
+
+### `preventDownloadDefaultBehavior`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Prevent default behavior of download/export.
+
+### `hideDownloadVariationsOption`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Hide transformation in download options in context menu and action bar.
+
+### `hideDownloadButtonIcon`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Hides the download/export button icon.
+
+### `hideHeaderBar`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Hides the header bar, header bar contains breadcrumbs and other action buttons.
+
+### `hideExportCropPanel`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+The crop button in the export options modal will be hidden.
+
+### `forceDownload`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Adds `download=1` param to the CDN download link
+
+### `defaultFilters` _Deprecated_ - use [`filters`](#filters) instead
+
+<u>Type:</u> `object`.
+
+<u>Default:</u> `null`
+
+Apply the provided filters on initial load.
+
+### `defaultSearchQuery` _Deprecated_ - use [`search.query`](#search) instead
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `''`
+
+Apply the provided search query on initial load.
+
+### `imageEditorMode`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `'default'`
+
+Possible values: `'default' | 'cloudimage' `
+
+Set imageEditorMode for the image editor plugin.
+
+### `hideModalAfterExport`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Hides the modal after finish download/export.
+
+### `closeAfterImageEdit`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Hides the modal after finish editing image.
+
+### `onRequestCloseModal`
+
+<u>Type:</u> `() => undefined`.
+
+<u>Default:</u> `closeModal` function
+
+Specified a custom function to be executed when trying to close the modal. Default closing modal behavior is overridden
+
+> **_Only relevant if_** [inline](#inline): false
+
+### `animateOpenClose`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `true`
+
+Disable the modal's opening and closing.
+
+> **_Only relevant if_** [inline](#inline): false
+
+### `locale`
+
+<u>Type:</u> `object`.
+
+<u>Default:</u> locales from scaleflexWidget's backend then default locale file with all labels is under `lib/defaultLocale.js`.
+
+You can override some labels by specifying a translation object here, such as:
+
+```js
+{
+  strings: {
+    baseFolderTitle: "Root"; // overrides the default Home value to Root
+  }
+}
+```
+
+<!-- not supported yet -->
+<!-- ### `theme: string`
+
+<u>Default:</u> `'light'`
+
+- **light**: uses the light theme
+- **dark**: uses the dark theme
+- **auto**: respects the user's default mode -->
+
+### `browserBackButtonCloseModal`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+The browser **Back** button will close the modal, otherwise it will trigger the standard back browser behavior.
+
+> **_Only relevant if_** [inline](#inline): false
+
+### `enableFoldersStatsApiRequest`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+When enabled it will send extra folders/stats API request with the folders request to get folders count.
+
+### `isUploadBarAddMoreButtonHidden`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+The 'Add More' button in upload module is hidden preventing users to upload more item.
+
+### `showFoldersTree`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Shows/hides on initial load the folder tree as a sidebar at the left of the plugin to navigate folders. The user can shows/hides the folder tree from the tree icon in the breadcrumbs.
+
+> **_Only relevant if_** folders view is provided in [views](#views)
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Shows/hides the label tree as a sidebar at the left of the plugin to navigate labels. The user can shows/hides the label tree from the tree icon in the breadcrumbs.
+
+### `showDetailsView`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Shows/hides the asset details view as a sidebar at the right of the plugin to view various details about selected assets. The user can shows/hides the details view from the info icon in the right side of the breadcrumbs.
+
+### `hideDetailsViewButton`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Hides the asset details view button from the info icon in the right side of the breadcrumbs.
+
+### `videoTranscoding`
+
+<u>Type:</u> `object`.
+
+<u>Default:</u>
+
+```js
+{
+  resolution: 'auto',
+  protocol: 'HLS'
+}
+```
+
+Video transcoding options for post-upload video transcoding:
+
+| Property         | Type                | Default | Description                              |
+| ---------------- | ------------------- | ------- | ---------------------------------------- |
+| **`resolution`** | `string` _required_ | `auto`  | target resolutions for video transcoding |
+| **`protocol`**   | `string` _required_ | `HLS`   | which protocol to use while transcoding  |
+
+### `cropPresets`
+
+<u>Type:</u> `object`.
+
+<u>Default:</u> `{}`
+
+Defines additional crop types & presets besides the freehand one and their presets and its shape as follows
+
+```js
+{
+  'Social media': [
+    /**
+     * label: possible to be a string or string in form of i18n key provided through locale object
+     * value: value follows this format (width:height:autoResize) or one of the following stringy values (original/ellipse) which defines the width & height of the crop preset autoResize which is a boolean value if `true` then resizing inputs will be disabled and auto resize will be applied automatically otherwise they're enabled, ratio of crop will be determined from width / height.
+     */
+    { label: 'Facebook profile', value: '400:400:true' },
+    { label: 'linkedInCover', value: '1128:191:false' }
+  ],
+  custom: [
+    { label: 'logoSize', value: '320:100' }
+  ],
+  ellipse: {
+    label: 'ellipse', value: 'ellipse'
+  },
+  original: {
+    label: 'original', value: 'original'
+  }
+}
+```
+
+> NOTE: The object's keys will be used the label for crop type (it is possible to be label string or i18n key string that is provided through locale object)
+
+### `showRemoveBackgroundOption`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `true`
+
+Remove background option will appear in context menu.
+
+### `disableMultipleSelect`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Multiple files/folders selections will be disabled and only 1 file/folder possible to be selected.
+
+### `dismissUrlPathQueryUpdate`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+The url query `fmaw_path` won't be added/updated to the current url.
+
+### `showScaleflexCopyright`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Hides Scaleflex copyright at the bottom of the plugin.
+
+### `useAssetsPicker`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If set to `true`, actions like deleting, editing, or downloading assets will not be allowed, explore and insert actions allowed.
+
+### `assetsPickerModelTitle`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `explorerTopSectionImportFileTitle`
+
+changing it's value changes the asset picker's model title
+
+### `disableFolderSelection`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If set to `true`, disable the possiblity to select folder(s).
+
+### `hideFolderOptions`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If set to `true`, hide the folder item top options.
+
+### `hideDetailsTab`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If set to `true`, hide toggle details tab button.
+
+### `hideActionBarSelectionButtons`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If set to `true`, hide the selection buttons in the action bar.
+
+### `disableDnDActions`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If set to `true`, disable the drag and drop actions to move assets/folders or upload
+
+### `noImgOperationsAndDownload`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If set to `true`, hides some options in asset contextual menu:
+
+- Download (context menu)
+- Transformation (action bar)
+- Edit image (context menu and action bar)
+
+### `queryParamPrefix`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `fmaw_`
+
+Override the query params
+
+### `showDragDropPanel`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Changes the design for the addFiles panel in uploads.
+
+### `showSort`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `true`
+
+shows/hides sort button in Explorer.
+
+### `isDownloadUsageRightsEnabled`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Enables/disables the download of usage rights file with assets.
+
+### `useLoginMode`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Enables/disables the login mode which gives the user the possibility to login by his credentials (email & password) through a form shown to the user while using the widget, respecting the provided `container` in the core class of the widget.
+
+> Note: Don't provide security template key nor sass key if you need to use enable this feature by providing its value to `true`.
+
+### `prefilledLoginModeEmail`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `null`
+
+The property used to add a default email address in the email address field of the login mode form, if not provided the email address will be empty. In both cases, the user will be able to change/add his email address and this property is used by having [`useLoginMode`](#useloginmode) enabled.
+
+### `hideAddingComment`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Removes the add comment textarea from the comments tab.
+
+### `findAssetLocationEnabled`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `true`
+
+Providing `false`, will hide `Open asset location` option in the context menu and file window.
+
+### `restrictedSearchContext`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Providing `true`, will disable the possibility of selecting other search contexts and always force the user to use the current opened view's context.
+
+### `facetedSearchEnabled`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Faceted search allows users to filter files using metadata filters. When this feature is enabled:
+
+- The filters bar will be hidden.
+- Only metadata filters with select, select-one, and boolean fields will be displayed.
+
+_Note_: Faceted search is only active in the assets view.
+
+### `facetedSearchSidebarExpanded`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `true`
+
+expands faceted search sidebar by default.
+
+_Note_: if `facetedSearchEnabled` is false, this property will be ignored.
+
+### `activeFacetedSearchMetadataFields`
+
+<u>Type:</u> `array`.
+
+<u>Default:</u> `[]`
+
+Array of metadata fields keys to be shown on faceted search.
+
+_Note_: only exist filters will be shown.
+
+### `filters`
+
+<u>Type:</u> `object`.
+
+<u>Default:</u> `{}`
+
+Filters to be applied to the views that accept filters, and will be locked if `disableFiltersAndSearch` or `forceFilters` is `true`, consists of the following:
+
+| Property                  | Type                                                                                                                                                             | Default                                                | Description                                                                                                                                        |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
+| **`date`**                | `object`                                                                                                                                                         | `{ key: 'created', value: undefined, operator: ':' } ` | the date filter that combines both the option/type and range with the operator                                                                     |
+| **`dateOption`**          | `string` \| `integer`                                                                                                                                            | `CREATED === 0`                                        | the date option/type to filter with                                                                                                                |
+| **`dateRange`**           | `integer`(1, 2, 3, 4, 5) \| `string` \| `string['yyyy-mm-dd', 'yyyy-mm-dd']`                                                                                     | `undefined`                                            | The date range used in filtering with the date option                                                                                              |
+| **`mimeTypes`**           | `string[]`                                                                                                                                                       | `undefined`                                            | File mimetypes (in the UI called types)                                                                                                            |
+| **`fileTypes`**           | `string[]`                                                                                                                                                       | `undefined`                                            | File types (in the UI called Format)                                                                                                               |
+| **`size`**                | `integers[minMB, maxMB]`                                                                                                                                         | `undefined`                                            | the date option/type to filter with                                                                                                                |
+| **`tags`**                | `string[] `                                                                                                                                                      | `undefined`                                            | The tags that should be contain in the files, the values consist of tag sids without #                                                             |
+| **`imageOrientations`**   | `string[]`                                                                                                                                                       | `undefined`                                            | The image orientation values                                                                                                                       |
+| **`imageResolutions`**    | `string[]`                                                                                                                                                       | `undefined`                                            | The image resolution values                                                                                                                        |
+| **`imageFaces`**          | `string[]`                                                                                                                                                       | `undefined`                                            | The number of faces found in an image                                                                                                              |
+| **`imageMainColors`**     | `string[]`                                                                                                                                                       | `undefined`                                            | The main colors of the image which represents significant proportion in the image                                                                  |
+| **`imageDominantColors`** | `string[]`s                                                                                                                                                      | `undefined`                                            | The dominant colors of the image                                                                                                                   |
+| **`metadata`**            | `{ key: string, operator: string\|undefined ,value: string\|string[], condition:{                      {operator:string ,value: string\|string[]}\| undefined }` | `undefined`                                            | The metadata objects used in filtering                                                                                                             |
+| **`labels`**              | `string[]`                                                                                                                                                       | `undefined`                                            | The label sids without # used in filtering files contain that value **(Only 1 label/value is supported currently) -- doesn't work in labels view** |
+| **`folders`**             | `string[]`                                                                                                                                                       | `undefined`                                            | The path of the folders to be used while filtering **(Only 1 folder/value is supported currently) -- doesn't work in folders view**                |
+| **`licenseExpiry`**       | `number[]                                                                                                                                                        | string[]                                               | string`\|`string`                                                                                                                                  | `undefined` | The asset license expiry date, possible to be a value of the constant values or custom/specific dates |
+
+> Note: you could apply the filter value directly as in the following example, or you could add another customer filter operator by providing `operator` property. Ex. { date: { key: 'created', value: ['2022-02-04'], operator: '>' } } // means return the files created after that date.
+
+> Available filter operators are one of the following: ['>', '<', '<=', '>=', '!=', '=', ':', '~', '~~', '~~~', '~^', '~=']
+
+```js
+{
+  date: {
+    key: 'created', // Either a string 'created'/'updated',
+    // `value` Either a string 'LAST_DAY'/'LAST_7_DAYS'/'LAST_30_DAYS'/'LAST_90_DAYS'/'LAST_180_DAYS' or integer 1/2/3/4/5 -- constants are preferred -- or for custom range provide an array [from, to] each date in the form yyyy-mm-dd .
+    value: ['2024-10-11'],
+    // `operator` one of ['>', '<', '<=', '>=', '!=', '=', ':', '~', '~~', '~~~', '~^', '~=']
+    operator: '>',
+  },
+
+  // Not used if `date` is used.
+  // `dateOption`: Either a string 'CREATED'/'UPDATED' or integer 0/1.
+  dateOption: 0,
+
+  // Not used if `date` is used.
+  // `dateRange` Either a string 'LAST_DAY'/'LAST_7_DAYS'/'LAST_30_DAYS'/'LAST_90_DAYS'/'LAST_180_DAYS' or integer 1/2/3/4/5 -- constants are preferred -- or for custom range provide an array [from, to] each date in the form yyyy-mm-dd .
+  dateRange: 'LAST_7_DAYS',
+
+   // `mimeTypes`: An Array of strings, acceptable values any/all of the following ['IMAGE', 'VIDEO', 'AUDIO', 'DOCUMENT', 'ARCHIVE'] or ['image', 'video', 'audio', 'application', 'application/zip, application/x-zip-compressed, application/vnd.rar, application/x-rar-compressed'] -- constants are preferred --.
+  mimeTypes: ['IMAGE', 'VIDEO'],
+
+  // `fileTypes`: An Array of strings, acceptable values are provided from BE filters API value property found in file type objects, ex. ['img|x-icon', 'img|jpeg'].
+  fileTypes: ['img|png', 'img|jpeg'],
+
+  // `size`: An Array of integers (only 2), values provided are considered as MB. [minMB, maxMB].
+  size: [0, 10],
+
+  // `tags`: An Array of strings, values are tag sids coming from BE but without (#).
+  tags: ['tge3c9d', 'tgdeaa9'],
+
+  // `imageOrientations`: An Array of strings, any/all of the following values are valid ['PORTRAIT', 'PANORAMA', 'SQUARE', 'LANDSCAPE'] or ['portrait', 'panorama', 'square', 'landscape'] -- constants are preferred --.
+  imageOrientations: ['PORTRAIT', 'SQUARE'],
+
+  // `imageResolutions`: An Array of strings, any/all of the following values are possible ['SMALL', 'MEDIUM', 'LARGE'] or ['small', 'medium', 'large'] -- constants are preferred --.
+  imageResolutions: ['MEDIUM', 'LARGE'],
+
+  // `imageFaces`: An Array of strings, any/all of the following values are possible ['NO_FACES', 'ONE_FACE', 'TWO_FACES', 'ANY'] or ['0', '1', '2', '*'] -- constants(capitalized) are preferred -- (* => means group/multiple of faces).
+  imageFaces: ['1', '*'],
+
+  // `imageMainColors`: An Array of strings, represents the color stringy value it must be any/all of the following only no other colors ['PURPLE', 'RED', 'ORANGE', 'PINK', 'GRASS_GREEN', 'YELLOW', 'AZURE', 'CHARTREUSE', 'TEAL'] or ['purple', 'red', 'orange', 'pink', 'grass_green', 'yellow', 'azure', 'chartreuse', 'teal'] -- constants(capitalized) are preferred --.
+  imageMainColors: ['TEAL', 'YELLOW'],
+
+  // `imageDominantColors`: An Array of strings, represents the color stringy value it must be any/all of the following only no other colors ['PURPLE', 'RED', 'ORANGE', 'PINK', 'GRASS_GREEN', 'YELLOW', 'AZURE', 'CHARTREUSE', 'TEAL'] or ['purple', 'red', 'orange', 'pink', 'grass_green', 'yellow', 'azure', 'chartreuse', 'teal'] -- constants(capitalized) are preferred --.
+  imageDominantColors: ['pink', 'red'],
+
+  // `metadata`: An Array of objects contains { key, operator, value, condition }, key and value are required for all metadata types, operator is required for single and multiple select metadatas only, condition is required in case operator is 'HAS' to add extra condition (another operator and value) to have metadata working properly, the value either the api_key or the internal unique value, the operators are [IS, NOT, HAS], condition operators are ['AND', 'OR', 'NOT'], all operators must be upper case, also for 'IS' operator we support empty and non empty options to filter all empty/non empty metadata
+  metadata: [
+    { key: 'cities', value: ['@itm_v1_08bbe7e5_4@', '@itm_v1_905066ed_9@'] },
+    { key: 'brand', value: 'adidas' },
+    { key: 'color', operator: 'IS', value: 'yellow' },
+    { key: 'file', operator: 'HAS', value: 'png', condition: {operator: 'OR', value: 'jpg'} },
+  ],
+
+  // `labels`: An Array of strings, currently accepts 1 label only and the value should be label sid **with** (#).
+  labels: ['#lbbp8dnyu'],
+
+  // `folders`: An Array of strings, currently accepts 1 folder path only.
+  folders: ['/hello-world'],
+
+  // possible values: 'empty' | 'non-empty' | 'specific' (Specific date) | 'range' (Range of 2 dates) | ['', -1] (Before today) | [0] (today) | [1, ''] (After today) | [0, 2] (Within 7 days) | [0, 3] (Within 30 days)
+  licenseExpiry: { value: [1, ''], operator: ':' }
+}
+```
+
+```js
+ // filter with operator syntax example
+ {
+  [property]: {
+    value: '...', // required, depends on the filter its type is provided
+    operator: ':' // optional, if needed otherwise the default one is used ':'
+    key: '...', // optional, if needed.
+   }
+ }
+```
+
+> Note: Constant values are better to be used as they are less prone for changes.
+
+> Note: To lock any of the above properties by using `disabledFiltersAndSearch` or `forceFilters` then you have to provide a value for the property to be locked.
+
+> Note: Operators are allowed to be provided for all the above filters but some of them are not supported on BE.
+
+### `search`
+
+<u>Type:</u> `object`.
+
+<u>Default:</u> `{}`
+
+Search object to be considered in the views have searching enabled and will be locked if `disableFiltersAndSearch` is `true`, consists of the following:
+
+| Property      | Type         | Default     | Description                                                                                                                                                                                                                                                                     |
+| ------------- | ------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`query`**   | `string`     | `undefined` | The search query string shown in the search input and used in searching, if using with `disabledFiltersAndSearch` then the property must contain a stringy value to lock the search or at least empty text `''`                                                                 |
+| **`tags`**    | `string[]`   | `undefined` | The search tags found in the search input as advanced search prefxed with symbol (#) -- different from tags of filters --                                                                                                                                                       |
+| **`filters`** | `string[][]` | `undefined` | The advanced search filters found also in search input by prefixing with the symbol (@) the value consists of array of 2 strings array the first string represents the key, second string represents the value and whole array represents an item -- different from filters --. |
+
+```js
+{
+  // `query`: A string search query shown in the search input.
+  query: '',
+
+  // `tags`: An array of strings **contains** (#). The search input's tags used as advanced search on writing inside the input starting with (#) symbol and spaced tags are surrounded with double quote "" .
+  tags: ['#Cairo', '"#Las Vegas"'],
+
+  // `filters`: An Array of array consists of 2 strings, the 1st string refers to the filter's key and 2nd refers to the filter's value. The search input's filters used as advanced search on writing inside the input starting with (@) symbol.
+  filters: [["key", "value"], ["filename", "Test file"]]
+}
+```
+
+> Note: To lock any of the above properties by using `disabledFiltersAndSearch` then you have to provide a value for the property to be locked at least empty value would be fine.
+
+### `disableFiltersAndSearch`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If `true` then the only provided `filters` & `search` objects will be used as filters & search and disable both the filters & search input in UI dis-allowing the user to change/un-select any of them at all keeping the selected/provided filters not disabled but no changes possible for them.
+
+> Note: if search query is empty it won't be disabled if you need to disable it with no text provide an empty string `''`.
+
+> Note: Enabling this option will dismiss applying the filters & search from the url queries.
+
+### `forceFilters`
+
+If `true` then the provided `filters` will always get applied with no possibility to remove from the UI, but the user still has the option to extend with more filters from the UI unless the provided filter accepts 1 value only.
+
+> Note: Enabling this option will dismiss applying the filters from the url queries.
+
+### `disableFileResolutionFallback`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+If `true` it will disable fallback request to load resolution info if not found in file details in grid/list layout.
+
+### `hideLeftSideBar`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Hide the folders tree sidebar and its toggle icon.
+
+### `defaultFieldKeyOfBulkEditPanel`
+
+<u>Type:</u> `string`.
+
+<u>Default:</u> `'tags'` fallbacks to `'title'`
+
+Assigns the default field of the bulk edit panel to be opened on showing the bulk edit panel as the focused/default field, it should be one of the general field keys (`tags`/`title`/`description`) or any field key -- lowered case -- of the shown file custom metadata fields (depends on the token).
+
+### `enableAIDescription`
+
+<u>Type:</u> `boolean`.
+
+<u>Default:</u> `false`
+
+Enables the generate description by AI in the description input of file window.
+
+## Events
+
+The explorer plugin 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:
+
+### `objects-removed`
+
+Emitted when objects (folders/labels/files) have been removed from the user's side.
+
+`params`:
+
+- `removedObjectsUuids`: An array of removed objects' uuids (for labels the sids will be the value).
+- `removedObjectsType`: `folders`/`labels`/`files`/`items` (files + folders).
+
+example
+
+```js
+scaleflexWidget.on("objects-removed", (removedObjectsUuids = [], objectsType) => {
+  console.log(
+    "Objects with the following Uuids have been removed:",
+    removedObjectsUuids,
+    objectsType
+  );
+});
+```
+
+### `folders-moved`
+
+Emitted when folder(s) are moved from path to another.
+
+`params`:
+
+- `movedFoldersUuids`: An array of folders uuids that are moved.
+- `newPath`: A string of the new path which the folders moved to.
+
+example
+
+```js
+scaleflexWidget.on('objects-removed', (movedFoldersUuids = [], newPath) => {
+  console.log(`Following folders uuids ${movedFoldersUuids.join(,)} are moved to this new path (${newPath}).`)
+})
+```
+
+<!-- Variables -->
+
+[npm-url]: https://www.npmjs.com/package/@scaleflex/widget-explorer
+[license-url]: https://opensource.org/licenses/MIT
+[sfx-url]: https://www.scaleflex.com/
+[version-url]: https://www.npmjs.com/package/@scaleflex/widget-explorer
+[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]: https://img.shields.io/npm/v/@scaleflex/widget-explorer?label=Version&style=for-the-badge&logo=npm
+[codeSandbox-image]: https://img.shields.io/badge/CodeSandbox-black?style=for-the-badge&logo=CodeSandbox