@bigbinary/neeto-filters-frontend 2.13.1 → 2.14.0

package/README.md

@@ -1,4 +1,3 @@
-
 # @bigbinary/neeto-filters-frontend
 
 neetoFilters is the library that manages filters across neeto products.
@@ -12,49 +11,65 @@ yarn add @bigbinary/neeto-filters-frontend
 **neetoFilters** has a few peer dependencies that are required for the proper
 functioning of the package. Install all the peer dependencies using the below
 command:
+
 ```bash
 yarn add @bigbinary/neetoui @bigbinary/neeto-icons axios@0.27.2 classnames@2.3.1 dayjs@1.11.1 formik@2.2.0 ramda@0.28.0 react-router-dom@5.3.0 react-router-nav-prompt@0.4.1 react-toastify@9.0.1 yup@0.32.11
 ```
+
 ## Usage
 
-neeto-filters-frontend exports 2 components (`Filters` & `Bar`) and 2 functions (`buildFiltersFromURL()` & `buildSelectorsFromURL()`).
+neeto-filters-frontend exports 2 components (`Filters` & `Bar`) and 2 functions
+(`buildFiltersFromURL()` & `buildSelectorsFromURL()`).
+
 ### 1. `Filters` component
 
 #### Props
 
 1.  **isOpen**: To specify whether the Pane component is open or not.
 2.  **setIsOpen**: To trigger the isOpen state.
-3.  **columns**: The list of columns/fields that needs to be represented in the filters pane.
-4.  **onChange**: To specify the callback function that is triggered whenever a filter is applied or cleared. This function will get the  updated filters as argument.
-5. **onSelectorsChange**: To specify the callback function that is triggered whenever a selector value is changed. This function will get the updated selectors as argument.
+3.  **columns**: The list of columns/fields that needs to be represented in the
+    filters pane.
+4.  **onChange**: To specify the callback function that is triggered whenever a
+    filter is applied or cleared. This function will get the updated filters as
+    argument.
+5.  **onSelectorsChange**: To specify the callback function that is triggered
+    whenever a selector value is changed. This function will get the updated
+    selectors as argument.
 6.  **buttonProps**: To specify the props to be passed to the button component.
 7.  **paneProps**: To specify the props to be passed to the pane component.
-8.  **isSearchable**: To specify whether you need a search bar in filters pane to search through filter fields.
+8.  **isSearchable**: To specify whether you need a search bar in filters pane
+    to search through filter fields.
 9.  **className**: To specify classes to the Filters component.
 10. **keyword**: To specify the props related to searching.
-11. **childrenKeys** The list of keys which has to be cleared from url during clear filters operation.
-12. **children**: To specify the custom components specific to the host application.
-13. **size**: To specify the width of the filters pane. It accepts "xsmall" (default), "small", and "large" as value.
+11. **childrenKeys** The list of keys which has to be cleared from url during
+    clear filters operation.
+12. **children**: To specify the custom components specific to the host
+    application.
+13. **size**: To specify the width of the filters pane. It accepts "xsmall"
+    (default), "small", and "large" as value.
 
 Here is an example of `keyword` prop:
+
 ```js
 const [searchTerm, setSearchTerm] = useState("");
 const searchKeywordProps = {
   key: "keyword",
-	node: "name",
-	value: searchTerm.trim(),
-	setValue: setSearchTerm,
-}
+  node: "name",
+  value: searchTerm.trim(),
+  setValue: setSearchTerm,
+};
 ```
+
 This `searchKeywordProps` can be passed as the value to `keyword` prop.
 
-> :memo: **Note:**
-If you wish to conduct a search for the keyword among multiple columns spanning different tables in the DB, then you should pass the name of the models corresponding to the tables  as value of `models` prop.
+> :memo: **Note:** If you wish to conduct a search for the keyword among
+> multiple columns spanning different tables in the DB, then you should pass the
+> name of the models corresponding to the tables as value of `models` prop.
 >
 > Example:
 >
-> If you are querying the user records and searching the keyword among users' name and users' organization name, then
-node will be like:
+> If you are querying the user records and searching the keyword among users'
+> name and users' organization name, then node will be like:
 >
 > `node = "first_name,last_name,organization.name"`
 >
@@ -63,6 +78,7 @@ node will be like:
 > `model = "User,Organization"`
 
 Here is an example for the `columns` prop:
+
 ```js
 export  const  SAMPLE_FILTER_FIELDS = [
 	{
@@ -88,17 +104,25 @@ export  const  SAMPLE_FILTER_FIELDS = [
 	},
 ];
 ```
+
 - `key` : A unique identifier provided to each columns/field.
 - `group`: The label of the group, if the field is associated with a group.
 - `node`: The column in DB table corresponding to the field.
 - `label` The label to be shown just above the field in Pane.
-- `suffixComponent` The component to be shown at the end of the respective Block in filters Bar.
-- `preprocessor` The function to be used to preprocess the value before applying the filter.
+- `suffixComponent` The component to be shown at the end of the respective Block
+  in filters Bar.
+- `preprocessor` The function to be used to preprocess the value before applying
+  the filter.
 - `type`: The nature/type of the field needed in pane.
-	- The supported types are `text`, `number`, `decimal`, `date`, `single_date`, `time`, `single_time`, `single_option`, `multi_option` and `boolean`
-- `model`: If the node provided is **not** directly refering to the column within the table being queried for the filtered results, then we need to provide the **model** corresponding to the target table.
-	- For example: We are adding a filter field for querying on `users` table to list all users with address containing the a certain word. Say the addresses are stored in **another table `addresses`**.
-Then the node will be `address.line_1,line_2`. In such cases we need to pass this extra prop like `model: "Address"`.
+  - The supported types are `text`, `number`, `decimal`, `date`, `single_date`,
+    `time`, `single_time`, `single_option`, `multi_option` and `boolean`
+- `model`: If the node provided is **not** directly refering to the column
+  within the table being queried for the filtered results, then we need to
+  provide the **model** corresponding to the target table. - For example: We are
+  adding a filter field for querying on `users` table to list all users with
+  address containing the a certain word. Say the addresses are stored in
+  **another table `addresses`**. Then the node will be `address.line_1,line_2`.
+  In such cases we need to pass this extra prop like `model: "Address"`.
   - Then whole object for the field might look like this
     ```js
     {
@@ -109,123 +133,172 @@ Then the node will be `address.line_1,line_2`. In such cases we need to pass thi
       type: "text"
     }
     ```
-- `values`: The list of label-value pair to be shown in dropdown, if the `type` provided is `single_option` or `multi_option`.
-- `showRuleSelector` : Boolean value, which determines whether to show a rule selector above the `text` , `number` and `decimal` type fields. `false` by default.
-- `hidden`: Boolean value, which determines to show or hide field from filter pane. `false ` by default.
-- `defaultValue`: The default value that should appear as chosen one in the filter fields.
+- `values`: The list of label-value pair to be shown in dropdown, if the `type`
+  provided is `single_option` or `multi_option`.
+- `showRuleSelector` : Boolean value, which determines whether to show a rule
+  selector above the `text` , `number` and `decimal` type fields. `false` by
+  default.
+- `hidden`: Boolean value, which determines to show or hide field from filter
+  pane. `false ` by default.
+- `defaultValue`: The default value that should appear as chosen one in the
+  filter fields.
 - `defaultType`: The type of the input that should be used in the Filters pane.
-- `isClearable`: Boolean value which specifies whether the field can be cleared or not.
+- `isClearable`: Boolean value which specifies whether the field can be cleared
+  or not.
+
+- By `selectors` we mean the filter fields which doesn't have any relation
+  (`node`) to a DB >table column.
+- For example, consider a field in filter pane called `Group by`. We cannot
+  provide a `node` to associate it with a column in DB table. Still it can
+  provide an important value which can be used for the computation as if by
+  telling a means by which the records can be grouped after filtering.
+- Fields without a `node`, among the ones passed as value to the `column` prop
+  of `Filters` are >considered as selectors.
 
-- By `selectors` we mean the filter fields which doesn't have any relation (`node`) to a DB >table column.
- - For example, consider a field in filter pane called `Group by`. We cannot provide a `node` to associate it with a column in DB table. Still it can provide an important value which can be used for  the computation as if by telling a means by which the records can be grouped after filtering.
-  - Fields without a `node`, among the ones passed as value to the `column` prop of `Filters` are >considered as selectors.
-  ```js
-  {
-    key:  "groupBy",
-    label:  "Group by",
-    type:  "single_option",
-    values: [
-      {
-        label: "Team",
-        value: "team"
-      },
-      {
-        label: "Location",
-        value: "location"
-      }
-    ],
+```js
+{
+  key:  "groupBy",
+  label:  "Group by",
+  type:  "single_option",
+  values: [
+    {
+      label: "Team",
+      value: "team"
+    },
+    {
+      label: "Location",
+      value: "location"
+    }
+  ],
 	}
-  ```
-  When user selects a value from this dropdown we get that value in the `selectors` state. This can be used for further computations outside the neeto-filters.
+```
 
+When user selects a value from this dropdown we get that value in the
+`selectors` state. This can be used for further computations outside the
+neeto-filters.
 
 ### 2. `Bar` component
 
 #### Props
 
-1.  **columns**: The list of columns/fields that needs to be represented in the filters pane.
-2.  **onChange**: To specify the callback function that is triggered whenever a filter is applied or cleared. This function will get the updated filters as argument.
+1.  **columns**: The list of columns/fields that needs to be represented in the
+    filters pane.
+2.  **onChange**: To specify the callback function that is triggered whenever a
+    filter is applied or cleared. This function will get the updated filters as
+    argument.
 3.  **setIsPaneOpen**: To trigger the isOpen state.
 4.  **className**: To specify classes to the Bar component.
-5. **keyword**: To specify the props related to searching.
-6. **onSelectorsChange**: To specify the callback function that is triggered whenever a selector value is changed. This function will get the updated selectors as argument.
-7. **childrenKeys** The list of keys which has to be cleared from url during clear filters operation.
-8. **entity**: The entity associated with the filters.
-
-All these props must be same as that passed to the `Filters` component.
-The option to save filters as segments will be enabled only when the entity prop is passed to the component.
+5.  **keyword**: To specify the props related to searching.
+6.  **onSelectorsChange**: To specify the callback function that is triggered
+    whenever a selector value is changed. This function will get the updated
+    selectors as argument.
+7.  **childrenKeys** The list of keys which has to be cleared from url during
+    clear filters operation.
+8.  **entity**: The entity associated with the filters.
+
+All these props must be same as that passed to the `Filters` component. The
+option to save filters as segments will be enabled only when the entity prop is
+passed to the component.
 
 ### 3. `Segments` component
 
 #### Props
 
-1.  **columns**: The list of columns/fields that needs to be represented in the filters pane.
+1.  **columns**: The list of columns/fields that needs to be represented in the
+    filters pane.
 2.  **entity**: The entity associated with the segments.
 3.  **setIsPaneOpen**: To trigger the isOpen state of the filters pane.
 
-The "columns" prop must be same as that passed to the `Filters` component.
-To set up the neeto-filters-engine with support for Segments, please follow the instructions provided in the installation [documentation](https://github.com/bigbinary/neeto-filters-engine#installation).
+The "columns" prop must be same as that passed to the `Filters` component. To
+set up the neeto-filters-engine with support for Segments, please follow the
+instructions provided in the installation
+[documentation](https://github.com/bigbinary/neeto-filters-engine#installation).
 
- ### 3. `buildFiltersFromURL` function
+### 3. `buildFiltersFromURL` function
 
 - This function takes a list as argument.
-- This list should contains all the filter columns/fields and the value passed to `keyword` prop of `Filters` and `Bar`.
-- It builds the filter payload from the URL search params. This function should be called for initializing the `filters` state.
+- This list should contains all the filter columns/fields and the value passed
+  to `keyword` prop of `Filters` and `Bar`.
+- It builds the filter payload from the URL search params. This function should
+  be called for initializing the `filters` state.
+
 ```js
-const [filters, setFilters] = useState(() =>  buildFiltersFromURL([...SAMPLE_FILTER_COLUMNS, searchKeywordProps]));
+const [filters, setFilters] = useState(() =>
+  buildFiltersFromURL([...SAMPLE_FILTER_COLUMNS, searchKeywordProps])
+);
 ```
 
 ### 4. `buildSelectorsFromURL` function
 
-- By `selectors` we mean the filter fields which doesn't have any relation (`node`) to a DB table column.
-  - For example, consider a field in filter pane called `Group by`. We cannot provide a `node` to associate it with a column in DB table. Still it can provide an important value which can be used for  the computation as if by telling a means by which the records can be grouped after filtering.
-  - Fields without a `node`, among the ones passed as value to the `column` prop of `Filters` are considered as selectors.
+- By `selectors` we mean the filter fields which doesn't have any relation
+  (`node`) to a DB table column.
+  - For example, consider a field in filter pane called `Group by`. We cannot
+    provide a `node` to associate it with a column in DB table. Still it can
+    provide an important value which can be used for the computation as if by
+    telling a means by which the records can be grouped after filtering.
+  - Fields without a `node`, among the ones passed as value to the `column` prop
+    of `Filters` are considered as selectors.
 - This function takes a list as argument.
 - This list should contains all the filter columns/fields.
-- It builds the selectors' value from the URL search params. This function should be called for initializing the `selectors` state.
-- `selectors` will be an object with keys same as provided in filter fields and selected value as its value.
+- It builds the selectors' value from the URL search params. This function
+  should be called for initializing the `selectors` state.
+- `selectors` will be an object with keys same as provided in filter fields and
+  selected value as its value.
+
 ```js
-const [selectors, setSelectors] = useState(() =>  buildSelectorsFromURL(FILTER_COLUMNS));
+const [selectors, setSelectors] = useState(() =>
+  buildSelectorsFromURL(FILTER_COLUMNS)
+);
 ```
 
 ### 5. `buildFilterColumnsFromFields` function
 
-The `buildFilterColumnsFromFields` function is used to generate an array of filter columns based on the provided fields (often referred as custom fields) and selected field names.
+The `buildFilterColumnsFromFields` function is used to generate an array of
+filter columns based on the provided fields (often referred as custom fields)
+and selected field names.
 
 #### Parameters
 
 - `fields` (array): An array of field objects representing the available fields.
-- `selectedFields` (array, optional): An array of strings representing the selected field names. Defaults to an empty array.
+- `selectedFields` (array, optional): An array of strings representing the
+  selected field names. Defaults to an empty array.
+- `showRuleSelector` (boolean, optional): A boolean value which specify whether
+  to show the rule selector for each filter or not. It is `false` by default.
 
 ```js
 const fields = [
   {
-    id: '1',
-    name: 'name',
-    kind: 'text',
+    id: "1",
+    name: "name",
+    kind: "text",
   },
   {
-    id: '2',
-    name: 'age',
-    kind: 'number',
+    id: "2",
+    name: "age",
+    kind: "number",
   },
   // Add more field objects as needed
 ];
 
-const selectedFields = ['name', 'age'];
+const selectedFields = ["name", "age"];
 
-const filterColumns = buildFilterColumnsFromFields(fields, selectedFields);
+const filterColumns = buildFilterColumnsFromFields({ fields, selectedFields });
 ```
 
 ## Development
 
 Install all the dependencies by executing the following command
+
 ```bash
 yarn install
 ```
-Start the development server using the `yarn start` command.
-In order to run the application you need to run the Rails server of the
-[neeto-filters-engine](https://github.com/bigbinary/neeto-filters-engine)'s dummy application as well. This is necessary to make sure that all the APIs and React Query hooks are working as per the requirement.
+
+Start the development server using the `yarn start` command. In order to run the
+application you need to run the Rails server of the
+[neeto-filters-engine](https://github.com/bigbinary/neeto-filters-engine)'s
+dummy application as well. This is necessary to make sure that all the APIs and
+React Query hooks are working as per the requirement.
+
 ```bash
 git clone https://github.com/bigbinary/neeto-filters-engine.git
 ./test/dummy/bin/setup