@bigbinary/neeto-fields-frontend 1.3.24 → 1.3.26

package/README.md

@@ -1,138 +1,104 @@
 # neeto-fields-nano
 
-**neeto-fields-nano** enables the management of dynamically added fields (often
-referred as custom fields) for the resources across neeto products.
-
-# Index
-
-- [General information](#general-information)
-- [Installation instructions](#installation-instructions)
-
-  - [Engine Installation](#engine-installation)
-  - [Frontend package Installation](#frontend-package-installation)
-  - [Dependency](#dependency)
-
-- [Frontend package exports](#frontend-package-exports)
-  - [Components](#components)
-    - [FieldsDashBoard](#1-fieldsdashboard)
-    - [FieldsPane](#2-fieldspane)
-    - [FieldValuesContainer](#3-fieldvaluescontainer)
-    - [FieldInputs](#4-fieldinputs)
-    - [InlineFieldValueInputProps](#5-inlinefieldvalueinput)
-  - [Functions](#functions)
-    - [mergeInitialValues](#1-neetofieldsutilsmergeinitialvalues)
-    - [transformValues](#2-neetofieldsutilstransformvalues)
-  - [Hooks](#hooks)
-    - [useFetchFields](#1-usefetchfields)
-    - [useShowFields](#2-useshowfield)
-    - [useCreateField](#3-usecreatefield)
-    - [useUpdateField](#4-useupdatefield)
-    - [useDestroyField](#5-usedestroyfield)
-- [Customizability](#customizability)
-  - [Engine customizability](#engine-customizability)
-- [Development instructions](#development-instructions)
-  - [Engine development](#engine-development)
-  - [Frontend package development](#frontend-package-development)
-
-# General information
-
-- This nano deals with fields and field values.
-
-- Field has a `name`, `kind`, `resource_type` and `owner`.
-
-- Field value has a `field` and `resource` item associated to it.
-
-- `resource_type` is the type of resource for which we are creating the field.
-  It is used for the categorized fetching and rendering of the fields. _eg:
-  users, tickets, deals, etc_
-
-- `owner` is basically scope of a field. It is whom to the field belongs. _eg:
-  Organization, Project, etc_
-
-- `kind` is the nature of the data meant as value for the field. All available
-  `kinds` are:
-
-  `text`, `number`, `monetary`, `single_option`, `multi_option`, `date`, `time`,
-  `date_range`, `time_range`, `textarea`, `person`, `checkbox`, `regex`,
-  `integer`, `decimal`, `datetime`.
-
-# Installation instructions
-
-## Engine installation
+The `neeto-fields-nano` enables the management of dynamically added fields
+(often referred to as custom fields) across neeto applications. The nano exports
+the `@bigbinary/neeto-fields-frontend` NPM package and `neeto-fields-engine`
+Rails engine for development.
+
+# Contents
+
+1. [Development with Host Application](#development-with-host-application)
+   - [Engine](#engine)
+     - [Installation](#installation)
+     - [customizability](#customizability)
+   - [Frontend package](#frontend-package)
+     - [Installation](#installation-1)
+     - [Instructions for development](#instructions-for-development)
+     - [Components](#components)
+       - [FieldsDashBoard](#1-fieldsdashboard)
+       - [FieldsPane](#2-fieldspane)
+       - [FieldValuesContainer](#3-fieldvaluescontainer)
+       - [FieldInputs](#4-fieldinputs)
+       - [InlineFieldValueInputProps](#5-inlinefieldvalueinput)
+       - [FieldDeleteAlert](#6-fielddeletealert)
+     - [Functions](#functions)
+       - [mergeInitialValues](#1-neetofieldsutilsmergeinitialvalues)
+       - [transformValues](#2-neetofieldsutilstransformvalues)
+     - [Hooks](#hooks)
+       - [useFetchFields](#1-usefetchfields)
+       - [useShowFields](#2-useshowfield)
+       - [useCreateField](#3-usecreatefield)
+       - [useUpdateField](#4-useupdatefield)
+       - [useDestroyField](#5-usedestroyfield)
+2. [Instructions for Publishing](#instructions-for-publishing)
+
+## Development with Host Application
+
+### Engine
+
+The engine is used to manage fields for any entity across neeto products.
+
+#### Installation
 
 1. Add this line to your application's Gemfile:
 
    ```ruby
-    source "NEETO_GEM_SERVER_URL" do
-      # ..existing gems
+   source "NEETO_GEM_SERVER_URL" do
+   # ..existing gems
 
-      gem 'neeto-fields-engine'
-    end
+     gem 'neeto-fields-engine'
+   end
    ```
 
 2. And then execute:
 
-   ```shell
+   ```ruby
    bundle install
    ```
 
-3. Add this line to your application's `config/routes.rb` file
+3. Add this line to your application's `config/routes.rb` file:
 
    ```ruby
-    mount NeetoFieldsEngine::Engine => "/neeto_fields_engine"
+   mount NeetoFieldsEngine::Engine => "/neeto_fields_engine"
    ```
 
-4. Add required migrations in the `db/migrate` folder. Run the following
-   commands to generate the migrations.
-
-```zsh
-rails g neeto_fields_engine:install
-```
+4. Run the following command to copy the migrations from the engine to the host
+   application:
 
-This will generate the migration to create the `neeto_fields_engine_fields`
-table (which holds the fields) and `neeto_fields_engine_field_values` table
-(which holds the value for the fields).
+   ```ruby
+   rails g neeto_fields_engine:install
+   ```
 
-5. Run the following command to create the tables.
+5. Add the migrations to the database:
 
-```zsh
-  rails db:migrate
-```
+   ```ruby
+   bundle exec rails db:migrate
+   ```
 
 6. Generate the required associations between models using the following
    command:
 
-```zsh
-rails g neeto_fields_engine:associations
-```
-
-This will prompt the user to enter 2 things:
-
-1. Name of Owner model.
-2. Names of Resource models.
+   ```ruby
+   rails g neeto_fields_engine:associations
+   ```
 
-- Owner: It is the ultimate owner of the fields being added. It can be
-  Organization, Project, etc depending on the business logic. _The field will
-  `belongs_to` Owner._
+   This will prompt the user to enter 2 things:
 
-- Resource: These are the models, to which we want the dynamic fields to be
-  attached with. This case be anything like Ticket, Deal, etc depending on the
-  business logic. _The field_value `belongs_to` each Resource._
+   1. Name of Owner model.
+   2. Names of Resource models.
 
-Once you enter the appropriate entries for the prompts asked. It will create an
-initializer file, which is required for the functioning of the engine.
+   Explore
+   [Owner & Resource Information](docs/engine/owner-resource-information.md) for
+   details.
 
-It will also add necessary associations to respective models, which were
-considered as Owner and Resources.
+#### Customizability
 
-> **_Note:_** _You might need to re-arrange the associations statements which
-> are normally inserted to top most lines of the file, to satisfy the Rails
-> standards._
+Refer [Engine customizability](docs/engine/customizability.md) to learn about
+customizing the engine's default behavior.
 
-Once you have completed these steps, you are ready to use the
-**neeto-fields-engine**.
+### Frontend package
 
-## Frontend package installation
+#### Installation
 
 Install the latest `neetoFields nano` package using the below command:
 
@@ -140,7 +106,7 @@ Install the latest `neetoFields nano` package using the below command:
 yarn add @bigbinary/neeto-fields-frontend
 ```
 
-## Dependency
+#### Dependency
 
 `neeto-fields-nano` has a peer dependency which is required to use the nano
 properly. Install the peer dependency using the below command:
@@ -149,23 +115,27 @@ properly. Install the peer dependency using the below command:
 yarn add uuid
 ```
 
-# Frontend package exports
+### Instructions for development
 
-The frontend package exports 4 components, 2 utility functions and a hook.
+Check the
+[Frontend package development guide](https://neeto-engineering.neetokb.com/p/a-d34cb4b0)
+for step-by-step instructions to develop the frontend package.
 
-## Components
+### Components
 
-### 1. `FieldsDashboard`
+#### 1. `FieldsDashboard`
 
 <div align="center">
   <img src="https://i.ibb.co/8NYn403/Screenshot-2023-07-13-20-04-54.png" alt="Dashboard image"/>
 </div>
 
-The FieldsDashboard component serves as a dashboard for managing all
+<br>
+
+The `FieldsDashboard` component serves as a dashboard for managing all
 custom-field related operations. It functions without requiring any props by
 default, but you can customize its behavior by passing optional props.
 
-#### Props:
+#### Props
 
 1. `rowData`: Represents the rowData for the table within the dashboard.
 2. `buildColumnData` : A function that builds the column data (in neetoUI table
@@ -197,12 +167,15 @@ default, but you can customize its behavior by passing optional props.
    `inactive` states.
 9. `breadcrumbs`: Specifies the breadcrumbs to be displayed on the dashboard
    page.
-10. `helpDocUrl`: Specify the URL to the help documentation about fields. This
+10. `helpDescription`: To set the description of the popover, this can be a
+    string or a custom component.
+11. `helpDocUrl`: Specify the URL to the help documentation about fields. This
     URL will be shown in the `NoData` screen.
-11. `nameAliases`: This property accepts alias names as key-value pairs to be
+12. `nameAliases`: This property accepts alias names as key-value pairs to be
     displayed for the names of resource types in header and menubar.
-12. `headerTitle`: Specify the header title explicitly. Default is 'fields'
-13. `resources`: For owner-based field categorization, provide an array of
+13. `headerTitle`: Specify the header title explicitly. Default is 'fields'. TIt
+    also specifies the title of `HelpPopover`.
+14. `resources`: For owner-based field categorization, provide an array of
     objects with `id` and `name` properties for each owner. For resource
     type-based categorization, use an array of objects with `label` and `value`
     properties representing each resource types.
@@ -211,89 +184,95 @@ default, but you can customize its behavior by passing optional props.
     > menu bar will fetch all resource types. For owner-based categorization, it
     > will fetch and list all owners in the organization.
 
-#### Usage:
-
-When Organization is the owner of the fields.
+#### Usage
 
-```jsx
-import { FieldsDashboard } from "@bigbinary/neeto-fields-frontend";
+1. When `Organization` is the owner of the fields.
+
+   ```jsx
+   import { FieldsDashboard } from "@bigbinary/neeto-fields-frontend";
+
+   <FieldsDashboard
+     allowedKinds={["text", "number"]}
+     buildColumnData={({ defaultColumns }) => [
+       ...defaultColumns,
+       {
+         dataIndex: "isSystem",
+         index: "isSystem",
+         title: t("titles.systemField"),
+         render: boolVal => (boolVal ? "Yes" : "No"),
+       },
+     ]}
+     fieldStatesTaxonomy={{ active: "Active", inactive: "Deactivated" }}
+     paneProps={{
+       children: <HostSpecificInputFields />,
+       validations: {
+         hostSpecificInputName: validationSchema,
+       },
+       initialValues: {
+         hostSpecificInputName: initialValue,
+       },
+     }}
+     breadcrumbs={[
+       {
+         link: "/",
+         text: "Home",
+       },
+       {
+         link: "/",
+         text: "Settings",
+       },
+     ]}
+   />;
+   ```
 
-<FieldsDashboard
-  allowedKinds={["text", "number"]}
-  buildColumnData={({ defaultColumns }) => [
-    ...defaultColumns,
-    {
-      dataIndex: "isSystem",
-      index: "isSystem",
-      title: t("titles.systemField"),
-      render: boolVal => (boolVal ? "Yes" : "No"),
-    },
-  ]}
-  fieldStatesTaxonomy={{ active: "Active", inactive: "Deactivated" }}
-  paneProps={{
-    children: <HostSpecificInputFields />,
-    validations: {
-      hostSpecificInputName: validationSchema,
-    },
-    initialValues: {
-      hostSpecificInputName: initialValue,
-    },
-  }}
-  breadcrumbs={[
-    {
-      link: "/",
-      text: "Home",
-    },
-    {
-      link: "/",
-      text: "Settings",
-    },
-  ]}
-/>;
-```
+   #### Usage in [neetoDesk](https://github.com/bigbinary/neeto-desk-web/blob/34068bb579335d3eb6041279f6f3f660099d7f1c/app/javascript/src/components/TicketFields/List/index.jsx#L119C8-L130C11)
+
+2. When `Organization` is not owner of the fields. Let's say the owner is
+   `Project`.
+
+   ```jsx
+   import { FieldsDashboard } from "@bigbinary/neeto-fields-frontend";
+
+   <FieldsDashboard
+     allowedKinds={["text", "number"]}
+     resourceType="tasks"
+     showOwnersInMenu
+     fieldStatesTaxonomy={{ active: "Active", inactive: "Deactivated" }}
+     paneProps={{
+       children: <HostSpecificInputFields />,
+       validations: {
+         hostSpecificInputName: validationSchema,
+       },
+       initialValues: {
+         hostSpecificInputName: initialValue,
+       },
+     }}
+     breadcrumbs={[
+       {
+         link: "/",
+         text: "Home",
+       },
+       {
+         link: "/",
+         text: "Settings",
+       },
+     ]}
+   />;
+   ```
 
-When Organization is not owner of the fields. Lets say the owner is Project.
+   #### Usage in [neetoForm](https://github.com/bigbinary/neeto-form-web/blob/1ae06a0f49f62b20ced313c1672fb336553b867c/app/javascript/src/components/Form/Settings/Fields.jsx#L35C7-L47C9)
 
-```jsx
-import { FieldsDashboard } from "@bigbinary/neeto-fields-frontend";
-
-<FieldsDashboard
-  allowedKinds={["text", "number"]}
-  ownerId={projectId}
-  resourceType="tasks"
-  showOwnersInMenu
-  fieldStatesTaxonomy={{ active: "Active", inactive: "Deactivated" }}
-  paneProps={{
-    children: <HostSpecificInputFields />,
-    validations: {
-      hostSpecificInputName: validationSchema,
-    },
-    initialValues: {
-      hostSpecificInputName: initialValue,
-    },
-  }}
-  breadcrumbs={[
-    {
-      link: "/",
-      text: "Home",
-    },
-    {
-      link: "/",
-      text: "Settings",
-    },
-  ]}
-/>;
-```
-
-## 2. `FieldsPane`
+#### 2. `FieldsPane`
 
 <div align="center">
   <img src="https://s11.gifyu.com/images/SWngt.gif" alt="AddField component gif" width="700"/>
 </div>
 
-This is the pane which handles the Add / Edit operations of the field.
+<br>
+
+The `FieldsPane` component handles the `Add / Edit` operations of the field.
 
-#### Props:
+#### Props
 
 1. `isOpen`: Boolean state which specifies the open/close state of the pane.
 2. `onClose`: The function to be executed on closing the pane.
@@ -311,7 +290,7 @@ This is the pane which handles the Add / Edit operations of the field.
 11. `onMutationSuccess`: The callback function which is triggered on the success
     of mutation functions( create, update & delete).
 
-#### Usage:
+#### Usage
 
 ```jsx
 import { FieldsPane } from "@biginary/neeto-fields-frontend";
@@ -338,10 +317,12 @@ const [fieldPaneOpen, setFieldPaneOpen] = useState(false);
   <img src="https://i.ibb.co/K6Gz0FF/Neeto-Fields-Nano-2023-07-13-19-57-27.png" alt="FieldValuesContainer Image" width="500"/>
 </div>
 
+<br>
+
 The `FieldValuesContainer` component handles field values associated with a
 specific resource.
 
-#### Props:
+#### Props
 
 1. `resourceType`: The type of resource.
 2. `fieldValues`: Field values associated with the resource obtained from the
@@ -378,9 +359,9 @@ specific resource.
     - `submitButtonLabel`
     - `cancelButtonLabel`
 
-#### Usage:
+#### Usage
 
-Say the resource over here is a user.
+Say the resource over here is a `user`.
 
 ```jsx
 import { FieldValuesContainer } from "@bigbinary/neeto-fields-frontend";
@@ -411,10 +392,11 @@ const queryClient = useQueryClient();
   <img src="https://i.ibb.co/9TmXnCx/Neeto-Fields-Nano-2023-07-14-00-38-03.png" alt="FieldInputs image" width="400"/>
 </div>
 
-The FieldInputs component render the input UI for the fetched fields. It accepts
-the following props:
+<br>
+
+The `FieldInputs` component render the input UI for the fetched fields.
 
-#### Props:
+#### Props
 
 1. `fields`: An array of all the fetched fields.
 2. `customComponents`: If the host application has any extra kind other than the
@@ -431,13 +413,13 @@ the following props:
 > :memo: **_Note:_**
 >
 > To initialize the values for this formik fields, you need to use
-> [`mergeInitialValues`](#1-mergeinitialvaluesinitialvalues-fields) function.
+> [`mergeInitialValues`](#1-neetofieldsutilsmergeinitialvalues) function.
 >
 > To submit the values from this formik form, you need to use
-> [`transformValues`](#2-transformvaluesvalues) function to capture the right
-> data from neeto-fields.
+> [`transformValues`](#2-neetofieldsutilstransformvalues) function to capture
+> the right data from neeto-fields.
 
-#### Usage:
+#### Usage
 
 ```jsx
 import {
@@ -481,10 +463,9 @@ const HostForm = () => {
 
 ### 5. `InlineFieldValueInput`
 
-The InlineFieldValueInput component render the field value input UI. It accepts
-the following props:
+The `InlineFieldValueInput` component render the field value input UI.
 
-#### Props:
+#### Props
 
 1. `fields`: An array of all the fetched fields.
 2. `fieldValues`: Field values associated with the resource.
@@ -495,7 +476,7 @@ the following props:
 7. `onMutationSuccess`: The callback function which is triggered on the success
    of mutation functions of field value.
 
-#### Usage:
+#### Usage
 
 Usually this is used as a component for inline editing of field values in
 tables. The example shows one such usage of building the `columnData` for table
@@ -526,19 +507,22 @@ const buildColumnDataForFields = (fields, onFieldValueUpdateSuccess) =>
   <img src="https://github.com/bigbinary/neeto-fields-nano/assets/35305344/6518b206-58f3-4375-bc68-7134ad68c168" alt="Field delete alert" width="500"/>
 </div>
 
-The `FieldDeleteAlert` component handles delete operation on fields. It accepts the following props:
+The `FieldDeleteAlert` component handles delete operation on fields. It accepts
+the following props:
 
-#### Props:
+#### Props
 
 1. `selectedField`: The field that needs to be deleted.
 2. `ownerId`: The ID of the owner in case the owner is not an organization.
 3. `resourceTypeName`: The type of resource.
 4. `isDeleteAlertOpen`: Boolean state which specifies whether the alert is open.
 5. `isDeleting`: Boolean state indicating whether the field is being deleted.
-6. `handleDelete`: The callback function responsible for deleting the specified field.
-7. `handleAlertClose`: The callback function to be executed on closing the alert.
+6. `handleDelete`: The callback function responsible for deleting the specified
+   field.
+7. `handleAlertClose`: The callback function to be executed on closing the
+   alert.
 
-#### Usage:
+#### Usage
 
 ```jsx
 import { FieldDeleteAlert } from "@biginary/neeto-fields-frontend";
@@ -561,18 +545,18 @@ const [isDeleteAlertOpen, setIsDeleteAlertOpen] = useState(false);
 The package exports the `neetoFieldsUtils`, which contains two utility
 functions.
 
-### 1. `neetoFieldsUtils.mergeInitialValues`
+#### 1. `neetoFieldsUtils.mergeInitialValues`
 
 This function builds the initial values for the Formik form that wraps the
 `<FieldInputs />` component.
 
-#### Arguments:
+#### Arguments
 
 - `initialValues`: The initial value object without considering
   `<FieldInputs />`
 - `fields`: An array of all the fetched fields.
 
-#### Usage:
+#### Usage
 
 ```jsx
 import { useFetchFields } from "@bigbinary/neeto-fields-frontend";
@@ -587,17 +571,17 @@ const initialValues = neetoFieldsUtils.mergeInitialValues({
 });
 ```
 
-### 2. `neetoFieldsUtils.transformValues`
+#### 2. `neetoFieldsUtils.transformValues`
 
 This function transforms the Formik form values and builds the `values` object
 including the data from `<FieldInputs />`. This transformed object can be passed
 to the `onSubmit` function of the Formik form.
 
-#### Arguments:
+#### Arguments
 
 - `values`: The Formik form values.
 
-#### Usage:
+#### Usage
 
 ```jsx
 import { useFetchFields } from "@bigbinary/neeto-fields-frontend";
@@ -619,18 +603,18 @@ const {
 </Form>;
 ```
 
-## Hooks
+### Hooks
 
 #### 1. `useFetchFields`
 
 This is a React Query hook for fetching all the fields.
 
-#### Arguments:
+#### Arguments
 
 - `resourceType`: The resource_type of the fields to be fetched.
 - `ownerId`: The ID of the owner in case the owner is not an organization.
 
-#### Usage:
+#### Usage
 
 ```jsx
 const {
@@ -645,7 +629,7 @@ const {
 
 This is a React Query hook for fetching details of a field.
 
-#### Argument
+#### Arguments
 
 - `fieldId`: The ID of field for fetching details.
 - `ownerId`: The ID of the owner in case the owner is not an organization.
@@ -700,77 +684,20 @@ delete({ fieldId })
 _Pass the `ownerId` too with the payload in case the owner is not an
 organization._
 
-# Customizability
-
-## Engine customizability
-
-In order to customize the engine's default behavior, we have several ways.
-
-- For improving the customizability, we've made every actions' duties into
-  separate services, which can be overridden from the host apps as and when
-  required.
-- If you wish to perform anything before or after the core logic of an action,
-  we have provision to do it as a **single transaction**.
-- Every action has `before_{action}_process` method invoked before the core
-  action logic and `after_{action}_process` method invoked after the core action
-  logic.
-- These methods can be overridden by defining them in the concern
-  `NeetoFieldsEngine::Fields::Customizable` or
-  `NeetoFieldsEngine::FieldValues::Customizable` depending on the context.
-
-> _Eg: If you want to do something before the update action of
-> `FieldsController`, then define it in `before_update_process` method inside
-> the `NeetoFieldsEngine::Fields::Customizable` concern._
-
-# Development instructions
-
-## Engine development
-
-1. Add this line to your application's Gemfile (replace the path to the local
-   copy of neeto-fields-engine):
-
-   ```ruby
-   gem 'neeto-fields-engine', path: '../neeto-fields-engine'
-   ```
-
-2. And then execute:
-
-   ```shell
-   bundle install
-   ```
-
-3. Refer [engine installation](#engine-installation) steps 3 and onwards.
-
-## Frontend package development
-
-The usage of `yalc` is explained in this video:
-https://www.youtube.com/watch?v=QBiYGP0Rhe0
-
-1.  See the changes in the host app by executing the following command \
-     <br/> Use this command if releasing a package for the first time.
-
-    ```shell
-    yarn build && yalc publish
-    ```
-
-    Use this command to see changes after the initial publish.
-
-    ```shell
-    yarn release
-    ```
-### 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.
-
-### Setup dummy host app
-
-Setup
-[Instructions](https://github.com/bigbinary/neeto-engineering/tree/main/Local-Development-Setup).
-
-Visit http://spinkart.lvh.me:9100 and login with email `oliver@example.com` and
-password `welcome`.
+## Instructions for Publishing
 
-### Additional instructions
+Consult the
+[building and releasing packages](https://neeto-engineering.neetokb.com/articles/building-and-releasing-packages)
+guide for details on how to publish.
 
-- Run `yarn build` to bundle the app.
+## Integrations
 
-### [Read about building and releasing](docs/building-and-releasing.md)
+| Projects     |     Integrated     |
+| ------------ | :----------------: |
+| neetoForm    | :white_check_mark: |
+| neetoDesk    | :white_check_mark: |
+| neetoPlanner | :white_check_mark: |
+| neetoCrm     | :white_check_mark: |
+| neetoChat    | :white_check_mark: |
+| neetoCal     | :white_check_mark: |
+| neetoTestify | :white_check_mark: |