@bigbinary/neeto-folders-frontend 1.1.6 → 1.1.7

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.
+
+   ```ruby
+   class RecordingFolder < NeetoFoldersEngine::Folder
+     has_many :recordings, -> { unscope(where: :deleted_at) }, foreign_key: :folder_id, dependent: :nullify
+   ```
 
-   Create a `script.rb` file in the project root and paste the script from the
-   following file.
+   `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.
 
-   [Replace project name script](./docs/engine/replace-project-name-script.md)
+   ```ruby
+   def items
+     recordings
+   end
+   ```
 
-2. Run the file using the following command:
+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.
 
-   ```shell
-      ruby script.rb
+   ```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,248 @@ 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.
 
-   ```javascript
-   import React from "react";
+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.
 
-   import { WelcomeScreen } from "@bigbinary/neeto-folders-frontend";
+```js
+{
 
-   const App = () => <WelcomeScreen />;
+  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.
+  itemLabel: t("common.items"), // For displaying the item label in counts
+  itemKeys: [], // For invalidation purposes. Keys in this array will be invalidated along with folders.
+  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,
+  }
+}
+```
 
-   export default App;
-   ```
+#### Components
+
+```js
+import * as components from "@bigbinary/neeto-folders-frontend/components";
+```
+
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigbinary/neeto-folders-frontend",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "A repo acts as the source of truth for the new nano's structure, configs, data etc.",
   "license": "UNLICENSED",
   "homepage": "https://github.com/bigbinary/neeto-folders-nano",

package/types.d.ts

@@ -1,3 +1,83 @@
 import React from "react";
 
-export const WelcomeScreen = React.FC<{}>;
+type ApiMethod = () => Promise<any>;
+
+interface Config {
+  type: string;
+  maxDepth: number;
+  folderPath: string;
+  itemLabel: string;
+  itemKeys: string[];
+  params: { [key: string]: any };
+  api: {
+    fetch: ApiMethod;
+    get: ApiMethod;
+    create: ApiMethod;
+    update: ApiMethod;
+    destroy: ApiMethod;
+    bulkUpdate: ApiMethod;
+    bulkDestroy: ApiMethod;
+  };
+}
+
+interface Folder {
+  name: string;
+  sid: string;
+  type: string;
+  item_count: number;
+  [key: string]: any;
+}
+
+interface QueryKeys {
+  FOLDERS: string;
+  LIST: string;
+  DETAILS: string;
+}
+
+export const QUERY_KEYS: QueryKeys;
+
+export const FoldersList: React.FC<{
+  config: Config;
+  selection: string[];
+  onSelect: (folderId: string) => void;
+}>;
+
+export const FoldersTree: React.FC<{
+  config: Config;
+}>;
+
+export const MoveToFolderPane: React.FC<{
+  isOpen: boolean;
+  config: Config;
+  item: Folder | any;
+  submitButtonProps: object;
+  cancelButtonProps: object;
+  removeButtonProps: object;
+  onSubmit: (folderId: string) => void;
+  onClose: () => void;
+  onRemove: () => void;
+}>;
+
+export const FoldersContext: React.FC<{
+  config: Config;
+  children: React.ReactNode;
+}>;
+
+export const useFolder: (config: Config) => {
+  isLoading: boolean;
+  folderId: string;
+  folder: Folder | null;
+};
+
+export const useFolders: (config: Config) => {
+  isLoading: boolean;
+  folders: Folder[];
+};
+
+export const useFolderActions: (config: Config) => {
+  onEdit: (item: Folder) => void;
+  onMove: (item: Folder) => void;
+  onDelete: (item: Folder) => void;
+};
+
+export const pathToFolder: (folders: Folder[], folderId: string) => string;