@bigbinary/neeto-fields-frontend 1.3.23 → 1.3.24-beta

package/README.md

@@ -1,138 +1,97 @@
 # 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
+    ```ruby
     source "NEETO_GEM_SERVER_URL" do
-      # ..existing gems
+    # ..existing gems
 
       gem 'neeto-fields-engine'
     end
-   ```
+    ```
 
 2. And then execute:
 
-   ```shell
-   bundle install
-   ```
+    ```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
+    ```ruby
     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
-```
-
-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).
+    ```
 
-5. Run the following command to create the tables.
+4. Run the following command to copy the migrations from the engine to the host application:
 
-```zsh
-  rails db:migrate
-```
+    ```ruby
+    rails g neeto_fields_engine:install
+    ```
 
-6. Generate the required associations between models using the following
-   command:
+5. Add the migrations to the database:
 
-```zsh
-rails g neeto_fields_engine:associations
-```
+    ```ruby
+    bundle exec rails db:migrate
+    ```
 
-This will prompt the user to enter 2 things:
+6. Generate the required associations between models using the following command:
 
-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 +99,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 +108,25 @@ 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
@@ -211,89 +172,96 @@ 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:
+#### Usage
 
-When Organization is the owner of the fields.
+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",
+        },
+      ]}
+    />;
+    ```
 
-```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",
-    },
-  ]}
-/>;
-```
+    #### Usage in [neetoDesk](https://github.com/bigbinary/neeto-desk-web/blob/34068bb579335d3eb6041279f6f3f660099d7f1c/app/javascript/src/components/TicketFields/List/index.jsx#L119C8-L130C11)
 
-When Organization is not owner of the fields. Lets say the owner is Project.
 
-```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. 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",
+        },
+      ]}
+    />;
+    ```
+
+   #### Usage in [neetoForm](https://github.com/bigbinary/neeto-form-web/blob/1ae06a0f49f62b20ced313c1672fb336553b867c/app/javascript/src/components/Form/Settings/Fields.jsx#L35C7-L47C9)
+
 
-## 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>
 
-#### Props:
+The `FieldsPane` component handles the `Add / Edit` operations of the field.
+
+#### 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,26 +279,26 @@ 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";
+  ```jsx
+  import { FieldsPane } from "@biginary/neeto-fields-frontend";
 
-const [fieldPaneOpen, setFieldPaneOpen] = useState(false);
+  const [fieldPaneOpen, setFieldPaneOpen] = useState(false);
 
-<FieldsPane
-  isOpen={fieldPaneOpen}
-  allowedKinds={["text", "number"]}
-  resourceType="users"
-  additionalValidations={{
-    hostSpecificInputName: validationSchema,
-  }}
-  initialValues={{ hostSpecificInputName: initialValue }}
-  onClose={() => setFieldPaneOpen(false)}
->
-  <HostSpecificInputFields />
-</FieldsPane>;
-```
+  <FieldsPane
+    isOpen={fieldPaneOpen}
+    allowedKinds={["text", "number"]}
+    resourceType="users"
+    additionalValidations={{
+      hostSpecificInputName: validationSchema,
+    }}
+    initialValues={{ hostSpecificInputName: initialValue }}
+    onClose={() => setFieldPaneOpen(false)}
+  >
+    <HostSpecificInputFields />
+  </FieldsPane>;
+  ```
 
 ## 3. `FieldValuesContainer`
 
@@ -338,10 +306,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 +348,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 +381,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 +402,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
+> [`transformValues`](#2-neetofieldsutilstransformvalues) function to capture the right
 > data from neeto-fields.
 
-#### Usage:
+#### Usage
 
 ```jsx
 import {
@@ -481,10 +452,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 +465,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
@@ -528,7 +498,7 @@ const buildColumnDataForFields = (fields, onFieldValueUpdateSuccess) =>
 
 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.
@@ -538,7 +508,7 @@ The `FieldDeleteAlert` component handles delete operation on fields. It accepts
 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 +531,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 +557,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 +589,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 +615,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 +670,18 @@ 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: |