@bigbinary/neeto-fields-frontend 1.0.2 → 1.0.3

package/README.md

@@ -1,10 +1,53 @@
 # neeto-fields-nano
 
-[![Build Status](https://bigbinary.semaphoreci.com/badges/neeto-fields-engine/branches/master.svg?style=shields&key=09ec7715-3c13-437f-bc63-bb100c38c1bc)](https://bigbinary.semaphoreci.com/projects/neeto-fields-engine)
-
 **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)
+- Frontend package exports
+  - [Components](#components)
+    - [FieldsDashBoard](#1-fieldsdashboard)
+    - [AddField](#2-addfield)
+    - [FieldValuesContainer](#3-fieldvaluescontainer)
+    - [FieldInputs](#4-fieldinputs)
+  - [Functions](#functions)
+    - [mergeInitialValues](#1-neetofieldsutilsmergeinitialvalues)
+    - [transformValues](#2-neetofieldsutilstransformvalues)
+  - [Hooks](#hooks)
+    - [useFetchFields](#1-usefetchfields)
+- [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`, `text_area`, `person`, `checkbox`, `regex`,
+  `integer`, `decimal`, `datetime`.
+
 # Installation instructions
 
 ## Engine installation
@@ -89,6 +132,345 @@ Install the latest `neetoFields nano` package using the below command:
 yarn add @bigbinary/neeto-fields-frontend
 ```
 
+The frontend package exports 4 components, 2 utility functions and a hook.
+
+## Components
+
+### 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
+custom-field related operations. It functions without requiring any props by
+default, but you can customize its behavior by passing optional 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
+   format) for the dashboard table. This function gets the `onDeleteClick`,
+   `onEditClick` callbacks and `defaultColumns` as arguments.
+3. `showOwnersInMenu`: Accepts a boolean value. When set to `true`, the fields
+   are displayed in categorized form (side menu) based on owners. By default,
+   fields are categorized based on the resourceType.
+4. `resourceType`: Explicitly specifies the `resource_type` of the fields to be
+   shown in the dashboard table. This prop is expected when `showOwnersInMenu`
+   is set to `true`.
+5. `allowedKinds`:Specifies the list of field kinds allowed to be created.
+6. `paneProps`: Props to be passed to the Add/Edit pane. It accepts `children`
+   to be rendered inside the pane and `validations` for the formik input fields
+   in the `children`. `validations` must be provided as a map with the field
+   name as key and the corresponding yup validation schema as the value.
+7. `showStateFilter`: Boolean value which specifies whether to show or hide
+   state filters.
+8. `fieldStatesTaxonomy`: Specifies the names to be rendered for `active` and
+   `inactive` states.
+9. `breadcrumbs`: Specifies the breadcrumbs to be displayed on the dashboard
+   page.
+
+#### Usage:
+
+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,
+    },
+  }}
+  breadcrumbs={[
+    {
+      link: "/",
+      text: "Home",
+    },
+    {
+      link: "/",
+      text: "Settings",
+    },
+  ]}
+/>;
+```
+
+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,
+    },
+  }}
+  breadcrumbs={[
+    {
+      link: "/",
+      text: "Home",
+    },
+    {
+      link: "/",
+      text: "Settings",
+    },
+  ]}
+/>;
+```
+
+## 2. `AddField`
+
+<div align="center">
+  <img src="https://s11.gifyu.com/images/SWngt.gif" alt="AddField component gif" width="700"/>
+</div>
+
+The `AddField` component consists of a button and a pane that opens when the
+button is clicked.
+
+#### Props:
+
+1. `resourceType`: Specifies the resource_type of the field to be created via
+   the pane.
+2. `allowedKinds`: Specifies the list of field kinds allowed to be created.
+3. `children`: Children components for the pane.
+4. `additionalValidations`: Validations for the formik fields in `children`.
+
+#### Usage:
+
+```jsx
+import { AddField } from "@biginary/neeto-fields-frontend";
+
+<AddField
+  allowedKinds={["text", "number"]}
+  resourceType="users"
+  additionalValidations={{
+    hostSpecificInputName: validationSchema,
+  }}
+>
+  <HostSpecificInputFields />
+</AddField>;
+```
+
+## 3. `FieldValuesContainer`
+
+<div align="center">
+  <img src="https://i.ibb.co/K6Gz0FF/Neeto-Fields-Nano-2023-07-13-19-57-27.png" alt="FieldValuesContainer Image" width="500"/>
+</div>
+
+The `FieldValuesContainer` component handles field values associated with a
+specific resource.
+
+#### Props:
+
+1. `resourceType`: The type of resource.
+2. `fieldValues`: Field values associated with the resource obtained from the
+   response.
+3. `resourceId`: The ID of the resource.
+4. `ownerId`:The ID of the owner. This prop is required only if the owner is not
+   an organization.
+5. `queryKeysToBeInvalidatedOnSuccess`: An array of queryKeys that should be
+   invalidated when changing the field value.
+6. `customComponents`: If the host application has any extra `kind` other than
+   the supported ones, you can specify the component to be displayed
+   corresponding to that kind using this prop. It takes the `kind` name as the
+   key and the component rendering callback function as the value. The callback
+   function can expect the `field` object as argument.
+7. `className`: Class names for styling.
+
+#### Usage:
+
+Say the resource over here is a user.
+
+```jsx
+import { FieldValuesContainer } from "@bigbinary/neeto-fields-frontend";
+
+<FieldValuesContainer
+  fieldValues={user.fieldValues} // We expect the user response from host's backend to send associated field_values with it.
+  queryKeysToBeInvalidatedOnSuccess={["users"]}
+  resourceId={user?.id}
+  resourceType="users"
+  customComponents={{
+    hostSpecificKindName: field => <HostSpecificInputFields />,
+  }}
+/>;
+```
+
+### 4. `FieldInputs`
+
+<div align="center">
+  <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:
+
+#### Props:
+
+1. `fields`: An array of all the fetched fields.
+2. `customComponents`: If the host application has any extra kind other than the
+   supported ones, you can specify the component to be displayed corresponding
+   to that kind using this prop. It takes the kind name as the key and the
+   component rendering callback function as the value. The callback function can
+   expect the `field` object.
+
+> :memo: **_Note:_**
+>
+> To initialize the values for this formik fields, you need to use
+> [`mergeInitialValues`](#1-mergeinitialvaluesinitialvalues-fields) 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.
+
+#### Usage:
+
+```jsx
+import {
+  FieldInputs,
+  useFetchFields,
+  neetoFieldsUtils,
+} from "@bigbinary/neeto-fields-frontend";
+
+const HostForm = () => {
+  const {
+    data: { fields },
+  } = useFetchFields({
+    resourceType: "users",
+  });
+
+  const initialValues = neetoFieldsUtils.mergeInitialValues({
+    initialValues: INITIAL_VALUES,
+    fields,
+  });
+  return (
+    <Form
+      formikProps={{
+        initialValues,
+        validationSchema: VALIDATION_SCHEMA,
+        onSubmit: values =>
+          onSubmit(neetoFieldsUtils.transformValues({ values, fields })),
+        enableReinitialize: true,
+      }}
+    >
+      {/* Other host specific input fields */}
+
+      <FieldInputs fields={fields} />
+
+      <Button type="submit" label="Submit" />
+    </Form>
+  );
+};
+```
+
+## Functions
+
+The package exports the `neetoFieldsUtils`, which contains two utility
+functions.
+
+### 1. `neetoFieldsUtils.mergeInitialValues`
+
+This function builds the initial values for the Formik form that wraps the
+`<FieldInputs />` component.
+
+#### Arguments:
+
+- `initialValues`: The initial value object without considering
+  `<FieldInputs />`
+- `fields`: An array of all the fetched fields.
+
+#### Usage:
+
+```jsx
+import { useFetchFields } from "@bigbinary/neeto-fields-frontend";
+
+const {
+  data: { fields },
+} = useFetchFields({ resourceType: "users" });
+
+const initialValues = neetoFieldsUtils.mergeInitialValues({
+  initialValues: FORMIK_INITIAL_VALUES,
+  fields,
+});
+```
+
+### 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:
+
+- `values`: The Formik form values.
+
+#### Usage:
+
+```jsx
+import { useFetchFields } from "@bigbinary/neeto-fields-frontend";
+
+const {
+  data: { fields },
+} = useFetchFields({ resourceType: "users" });
+
+<Form
+  formikProps={{
+    initialValues,
+    validationSchema: VALIDATION_SCHEMA,
+    onSubmit: values =>
+      onSubmit(neetoFieldsUtils.transformValues({ values, fields })),
+    enableReinitialize: true,
+  }}
+>
+  {/* Form's children */}
+</Form>;
+```
+
+## Hooks
+
+#### 1. `useFetchFields`
+
+This is a React Query hook for fetching all the fields.
+
+#### 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.
+- `pageSize` The page size for fetching the fields.
+- `pageIndex`: The page index for fetching the fields.
+
+#### Usage:
+
+```jsx
+const {
+  data: { fields },
+} = useFetchFields({
+  resourceType: "users",
+  pageSize: 10,
+  pageIndex: 1,
+  ownerId: "ownerId",
+});
+```
+
 # Customizability
 
 ## Engine customizability