@bigbinary/neeto-folders-frontend 1.2.0 → 2.0.1

package/README.md

@@ -1,7 +1,7 @@
 # neeto-folders-nano
 
-The `neeto-folders-nano` acts as the source of truth for the new nano's structure,
-configs, data etc.
+The `neeto-folders-nano` acts as the source of truth for the new nano's
+structure, configs, data etc.
 
 ## Contents
 
@@ -37,13 +37,7 @@ configs, data etc.
    bundle install
    ```
 
-3. Add this line to your application's `config/routes.rb` file
-
-   ```ruby
-    mount NeetoFoldersEngine::Engine => "/neeto_folders_engine"
-   ```
-
-4. Add required migrations in the `db/migrate` folder. Run the following
+3. Add required migrations in the `db/migrate` folder. Run the following
    commands to copy the migrations from the engine to the host application.
 
    ```shell
@@ -53,23 +47,60 @@ configs, data etc.
 
 #### Usage
 
-1. Replace NeetoFoldersNano with your project name
+1. Define the folder model in your application by extending the
+   `NeetoFoldersEngine::Folder` base class. Below is the sample code in
+   NeetoRecord that defines a `RecordingFolder` model by extending the
+   `NeetoFoldersEngine::Folder` to manage recordings.
 
-   Create a `script.rb` file in the project root and paste the script from the
-   following file.
+   ```ruby
+   class RecordingFolder < NeetoFoldersEngine::Folder
+     has_many :recordings, -> { unscope(where: :deleted_at) }, foreign_key: :folder_id, dependent: :nullify
+   ```
 
-   [Replace project name script](./docs/engine/replace-project-name-script.md)
+   `NeetoFoldersEngine` also expects a instance method `items` to be defined in
+   the extended class. This enables the `NeetoFoldersEngine` to keep track of
+   the count of items in the folder. Below is a sample code from NeetoRecord.
 
-2. Run the file using the following command:
+   ```ruby
+   def items
+     recordings
+   end
+   ```
 
-   ```shell
-      ruby script.rb
+2. Include the `NeetoFoldersEngine::Folderable` in the model which should belong
+   to a folder. Order of include is important. Include `Folderable` after
+   `Deletable` from neeto-commons-backend to allow `Folderable` to override the
+   `soft_delete` method.
+
+   ```ruby
+   include NeetoFoldersEngine::Folderable
    ```
 
-Notes ⚠️
+3. `NeetoFoldersEngine` also exposes a controller class
+   `NeetoFoldersEngine::FoldersController` with `index`, `show`, `create`,
+   `update`, `destroy`, `bulk_update`, `bulk_destroy`, and `reorder` actions to
+   manage folders. The host application can extend this class to manage their
+   folders. Make sure the routes are properly configured to direct to these
+   actions.
 
-- Don't commit this file.
-- Project name should be given in PascalCase.
+   Similar to the `RecordingFolder < NeetoFoldersEngine::Folder`, the
+   `NeetoFoldersEngine::FoldersController` base controller expects a `folders`
+   method to be defined in the extended class that allows the controller to
+   target folder instances that belongs to a particular type. Given below is
+   sample definition in NeetoRecord which extracts recording folders that should
+   be managed by the extended controller.
+
+   ```ruby
+   class Api::V1::FoldersController < NeetoFoldersEngine::FoldersController
+
+     private
+
+       def folders
+         @_folders ||= @organization.recording_folders.includes(:recordings)
+       end
+     end
+
+   ```
 
 ### Frontend package
 
@@ -82,21 +113,255 @@ Notes ⚠️
    ```
 
 ### Instructions for development
-Check the [Frontend package development guide](https://neeto-engineering.neetokb.com/p/a-d34cb4b0) for step-by-step instructions to develop the frontend package.
+
+Check the
+[Frontend package development guide](https://neeto-engineering.neetokb.com/p/a-d34cb4b0)
+for step-by-step instructions to develop the frontend package.
 
 #### Usage
 
-1. Import `WelcomeScreen` component from "@bigbinary/neeto-folders-frontend"
+`neeto-folders-frontend` exports a set of components, hooks, utils and constants
+to be integrated in the host application.
+
+Most of the above exports accepts a configuration object with certain
+properties. Given below is the structure of default `config` object. You can
+pass your own config object as argument or props to customize behaviors that
+suits the host product. Define this constant in a constant file and customize
+certain properties such as params as necessary.
+
+```js
+{
 
-   ```javascript
-   import React from "react";
+  type: "FOLDER", // A unique type key for query keys.
+  maxDepth: 2, // Maximum allowed depth for folder tree
+  folderPath: "/folders/:folderId", // Path for handling URL redirections and params matching.
+  invalidationKeys: [], // For invalidation purposes. Keys in this array will be invalidated along with folders.
+  reorderMode: "rearrange", // If reorder pane should mount in positional `reorder` mode or simple `rearrange` mode.
+// Taxonomy
+  labels: {
+    folder: t("common.folder"),
+    folders: t("common.folders"),
+    items: t("common.items"),
+    items: t("common.items"),
+  }
+  params: {}, // Params to be passed to APIs along with other params. Can be used for sorting and similar.
+  api: { // Folder CRUD methods.
+    fetch: noop,
+    get: noop,
+    create: noop,
+    update: noop,
+    destroy: noop,
+    bulkUpdate: noop,
+    bulkDestroy: noop,
+  }
+}
+```
 
-   import { WelcomeScreen } from "@bigbinary/neeto-folders-frontend";
+#### Components
 
-   const App = () => <WelcomeScreen />;
+```js
+import * as components from "@bigbinary/neeto-folders-frontend/components";
+```
 
-   export default App;
-   ```
+1.  `FoldersContext`: This component renders all alerts and panes related to
+    folders. Make sure this component is included in some part of your
+    application.
+
+    ###### Props:
+
+    - `config`: A config object to customize the folders behavior.
+
+    Sample usage:
+
+    ```jsx
+    import { FoldersContext } from "@bigbinary/neeto-folders-frontend/components";
+    // ....
+    <FoldersContext config={foldersConfig}>
+      <ApplicationComponent>
+    </FoldersContext>
+    ```
+
+2.  `FoldersTree`: This component renders the folders in tree a tree structure.
+
+    ###### Props:
+
+    - `config`: A config object to customize the folders behavior.
+
+    Sample usage:
+
+    ```jsx
+    import { FoldersTree } from "@bigbinary/neeto-folders-frontend/components";
+    // ....
+    <FoldersTree config={foldersConfig} />;
+    ```
+
+3.  `FoldersList`: Component renders list of folders. If no folder is
+    selected/active, renders list of root folders. If inside a selected folder,
+    renders list of sub-folders. The active folder is identified based on the
+    param in the URL that matches the `folderPath` in the `config` object.
+
+    ###### Props:
+
+    - `config`: A config object to customize the folders behavior.
+
+    - `selection`: An array of folder ids indicating id of selected folders for
+      bulk selection.
+
+    - `onSelect`: Callback triggered when checkbox is selected for a folder item
+      for bulk selection.
+
+    Sample usage:
+
+    ```jsx
+    import { FoldersList } from "@bigbinary/neeto-folders-frontend/components";
+    // ....
+    <FoldersList
+      config={foldersConfig}
+      onSelect={onSelectFolder}
+      selection={folderSelection}
+    />;
+    ```
+
+4.  `MoveToFoldersPane`: This component can be used in host applications to move
+    items to a folder. Component renders current list of folders in pane with
+    radio buttons and invokes callbacks for folder selections.
+
+    ###### Props:
+
+    - `isOpen`: Boolean value that controls pane visibility.
+
+    - `item`: An item object that is to be moved to the folder.
+
+    - `config`: A config object to customize the folders behavior.
+
+    - `submitButtonProps`: Pane "Submit" button overrides.
+
+    - `cancelButtonProps`: Pane "Cancel" button overrides.
+
+    - `removeButtonProps`: Pane "Remove from folder" button overrides. Note that
+      the button will be hidden unless the `onRemove` prop is supplied.
+
+    - `onSubmit(folderId)`: Callback invoked with id of selected folder on
+      submit.
+
+    - `onClose()`: Callback invoked when the pane is closed.
+
+    - `onRemove()`: Callback invoked when the Remove from folder button is
+      pressed. Note that the button will be hidden unless this prop is supplied.
+
+    - `onSelect`: Callback triggered when checkbox is selected for a folder item
+      for bulk selection.
+
+    Sample usage:
+
+    ```jsx
+    import { MoveToFoldersPane } from "@bigbinary/neeto-folders-frontend/components";
+    // ....
+    <MoveToFoldersPane
+      item={itemToMove}
+      onSelect={onSelectFolder}
+      selection={folderSelection}
+    />;
+    ```
+
+#### Hooks
+
+```js
+import * as hooks from "@bigbinary/neeto-folders-frontend/hooks";
+```
+
+1. `useFolders(config)`: Hook that return the data for all folders in tree
+   structure.
+
+   ###### Arguments:
+
+   - `config`: A config object to customize the folders behavior.
+
+   ###### Returns:
+
+   - `isLoading`: `true` when data is being fetched for active folder. `false`
+     otherwise.
+
+   - `folders`: Data of all folders of given type in tree structure.
+
+2. `useFolder(config)`: Hook that return the data related to current active
+   folder based on URL param.
+
+   ###### Arguments:
+
+   - `config`: A config object to customize the folders behavior.
+
+   ###### Returns:
+
+   - `isLoading`: `true` when data is being fetched for active folder. `false`
+     otherwise.
+
+   - `folderId`: SID of the current active folder based on URL param.
+
+   - `folder`: Data of the current folder if exists.
+
+3. `useFolderActions(config)`: Hook that return a set of callbacks to trigger
+   actions from host application.
+
+   ###### Arguments:
+
+   - `config`: A config object to customize the folders behavior.
+
+   ###### Returns:
+
+   - `isPending`: `true` when action is in progress. `false` otherwise.
+
+   - `onAdd()`: Initiates the folder create action.
+
+   - `onEdit(folder)`: Initiates the folder edit action. Accepts `folder` data
+     as argument.
+
+   - `onMove(folder)`: Initiates the folder edit action. Accepts `folder` data
+     as argument.
+
+   - `onDelete(folder)`: Initiates the folders delete action. Accepts `folder`
+     data as argument.
+
+   - `onReorder()`: Initiates the reorder folder action. Opens the "Reorder"
+     pane.
+
+#### Utils
+
+```js
+import * as utils from "@bigbinary/neeto-folders-frontend/utils";
+```
+
+1. pathToFolder(folders, folderId):
+
+   ###### Arguments:
+
+   - `folders`: Folders data in tree structure, returned by the `useFolders`
+     hook.
+
+   - `folderId`: Target folder id.
+
+   Returns an flattened array of folders from root folder to current folder with
+   id `folderId`. Useful for showing breadcrumbs and similar.
+
+#### Constants
+
+```js
+import * as constants from "@bigbinary/neeto-folders-frontend/constants";
+```
+
+1. `QUERY_KEYS`: Use query keys to target React Query actions such as
+   invalidations.
+
+   - `[QUERY_KEYS.FOLDERS]`: Targets every query related to folders.
+
+   - `[QUERY_KEYS.FOLDERS, config.folderType]`: Targets every query related to
+     folders of particular type.
+
+   - `[QUERY_KEYS.FOLDERS, config.folderType, QUERY_KEYS.LIST]`: Targets folders
+     list.
+
+   - `[QUERY_KEYS.FOLDERS, config.folderType, QUERY_KEYS.DETAILS, folderId]`:
+     Target folder details of a folder with id `folderId`
 
 ## Instructions for Publishing
 

package/app/javascript/src/translations/en.json

@@ -5,32 +5,40 @@
     "edit": "Edit",
     "move": "Move",
     "save": "Save",
+    "name": "Name",
+    "folder": "Folder",
+    "folders": "Folders",
+    "item": "Item",
     "items": "Items"
   },
+
   "createFolder": {
-    "parentInfo": "Leave the option empty to create folder at the root level",
-    "parentTitle": "Parent folder"
+    "parentInfo": "Leave the option empty to create {{ folder }} at the root level",
+    "parentTitle": "Parent {{ folder }}"
   },
   "deleteFolder": {
-    "info": "Are you sure you want to delete the folder <strong>{{name, anyCase}}</strong>?",
-    "title": "Delete folder"
+    "info": "Are you sure you want to delete the {{ folder }} <strong>{{name, anyCase}}</strong>?",
+    "title": "Delete {{ folder }}"
   },
   "folders": {
-    "title": "Folders",
-    "add": "Add new folder",
-    "edit": "Edit folder",
-    "name": "Folder name",
-    "subfolderCount_one": "{{count}} sub folder",
-    "subfolderCount_other": "{{count}} sub folders",
-    "noFolders": "No folders to show"
+    "title": "{{ folders }}",
+    "add": "Add new {{ folder }}",
+    "edit": "Edit {{ folder }}",
+    "name": "{{ folder }} name",
+    "subfolderCount": "{{count}} sub {{ folders }}",
+    "noFolders": "No {{ folder }} to show"
   },
   "moveToFolder": {
-    "depthExceeded": "Cannot move to this folder. Maximum {{maxDepth}} nested folders are allowed.",
-    "notAllowed": "You cannot move to this folder.",
-    "remove": "Remove from folder",
-    "title": "Move to folder"
+    "depthExceeded": "Cannot move to this {{ folder }}. Maximum {{maxDepth}} nested {{ folders }} are allowed.",
+    "notAllowed": "You cannot move to this {{ folder }}.",
+    "remove": "Remove from {{ folder }}",
+    "title": "Move to {{ folder }}"
   },
   "reorderFolder": {
-    "title": "Reorder folders"
+    "title": "Reorder {{ folders }}"
+  },
+
+  "errors": {
+    "blank": "{{entity}} cannot be blank"
   }
 }