@bigbinary/neeto-filters-frontend 1.4.1 → 2.0.0

package/CHANGELOG.md

@@ -22,7 +22,11 @@ Prefix the change with one of these keywords:
 - *Fixed*: for any bug fixes.
 - *Security*: in case of vulnerabilities.
 
-## [Unreleased](https://github.com/bigbinary/neeto-filters-frontend/compare/b77f80ed12e31627aa786452b20b86925309dfc3...HEAD)
+## [Unreleased](https://github.com/bigbinary/neeto-filters-frontend/compare/38783bf03081bc51ec623032d7c4fec0e15b632d...HEAD)
+
+## [2.0.0](https://github.com/bigbinary/neeto-filters-frontend/compare/b77f80ed12e31627aa786452b20b86925309dfc3...38783bf03081bc51ec623032d7c4fec0e15b632d) - 2022-11-10
+
+- Added: a new UI for handling filters. It consists of the `Filters` component for selecting the filters and the `Bar` component for displaying them.
 
 ## [1.4.1](https://github.com/bigbinary/neeto-filters-frontend/compare/c0b99b4212b89b4b02e7f6d1a3c5e4b2d23b45bf...b77f80ed12e31627aa786452b20b86925309dfc3) - 2022-10-11
 

package/README.md

@@ -2,17 +2,9 @@
 
 neetoFilters is the library that manages filters across neeto products.
 
-## Integrations
-
-| Project        | Routes                                        |
-| -------------- | --------------------------------------------- |
-| neeto-chat-web | /admin/contacts                               |
-| neeto-crm-web  | /deals, /contacts, /companies, /tasks, /mails |
-| neeto-cal-web  | /meetings, /scheduled-meetings                |
-
 ## Installation
 
-```zsh
+```bash
 yarn add @bigbinary/neeto-filters-frontend
 ```
 
@@ -20,228 +12,75 @@ yarn add @bigbinary/neeto-filters-frontend
 functioning of the package. Install all the peer dependencies using the below
 command:
 
-```zsh
+```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
 
-### 1. NeetoFilters Component
-
-```jsx
-import React from "react";
-
-import Filters from "@bigbinary/neeto-filters-frontend";
-
-import segmentsApi from "apis/segments";
-
-const FilterComponent = ({ segment, loadTableContent }) => {
-  const columns = [
-    {
-      node: "email",
-      label: "Email Address",
-      type: "text",
-    },
-    {
-      node: "ticket",
-      label: "Tickets",
-      type: "number",
-    },
-    {
-      node: "timezone",
-      label: "Timezone",
-      type: "timezone",
-      inputType: "text"
-      filters: ["is", "is_not", "greater_than", "less_than", "has_any_value", "is_unknown"],
-    }
-  ];
-
-  const handleChange = payload => {
-    loadTableContent(payload);
-  };
-
-  return (
-    <Filters
-      columns={columns}
-      segment={segment}
-      onChange={handleChange}
-    />
-  );
-};
-
-export default FilterComponent;
-```
-
-The types that are available by default are `text`, `number`, `date`, `time`,
-`datetime`, `date_range`, `time_range`, `single_option`, and `multi_option`. For
-adding types other than the default types, you can pass the `filters` prop along
-with the available logical filters as an array. You can change the input type
-for the filter by passing the `inputType` prop. By default the input type is
-`text`.
-
-This is an example payload for the `handleChange` method. This will be passed on
-to the `NeetoFilters::FilterService` in the `neeto_filters` gem.
-
-```json
-{
-  "segment": {
-    "id": "<uuid>",
-    "name": "Backlog",
-    "filters": [
-      {
-        "conditions": [
-          {
-            "node": "email",
-            "label": "Email Address",
-            "type": "text",
-            "rule": "contains",
-            "value": "bigbinary",
-            "conditionsJoinType": "and"
-          },
-          {
-            "node": "session",
-            "label": "Sessions",
-            "type": "number",
-            "rule": "greater_than",
-            "value": "10",
-            "conditionsJoinType": "and"
-          }
-        ],
-        "groupJoinType": "or"
-      },
-      {
-        "conditions": [
-          {
-            "node": "ticket",
-            "label": "Tickets",
-            "type": "number",
-            "rule": "greater_than",
-            "value": "5",
-            "conditionsJoinType": "and"
-          }
-        ],
-        "groupJoinType": "and"
-      }
-    ]
-  }
-}
+> The documentation for dropdown-type filters UI has been moved to https://github.com/bigbinary/neeto-filters-frontend/blob/main/src/components/DropdownFilter/README.md
+
+### 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 that needs to be represented in the filters pane.
+4. **onChange**: To specify the function that is triggered whenever a filter is applied or cleared.
+5. **buttonProps**: To specify the props to be passed to the button component.
+6. **paneProps**: To specify the props to be passed to the pane component.
+7. **isSearchable**: To specify whether the Select input is searchable.
+
+Here is an example for the `columns` prop:
+```js
+export const SAMPLE_FILTER_COLUMNS = [
+  {
+    key: "name",
+    node: "first_name,last_name",
+    label: "Name",
+    type: "single_option",
+    values: ["Oliver Smith", "Eve Smith"],
+  },
+  {
+    key: "email",
+    node: "email",
+    label: "Email",
+    type: "multi_option",
+    values: ["oliver@example.com", "eve@example.com"],
+  },
+  {
+    key: "created_at",
+    node: "created_at",
+    label: "Created At",
+    type: "date",
+  },
+];
 ```
 
-### Handling combination of two columns
-
-- Some columns like `name` are actually combination of two columns `first_name`
-  and `last_name`. For this example, the node must be provided as
-  `"first_name,last_name"`. Here, both the nodes are separated by comma. On the
-  Rails side, they will be separated by space by default.
-- Note that this feature will not be supported for `date_range` and `time_range`
-  types.
+### 2. Bar component
 
-## Props
+#### Props
 
-1. **columns**: An array of objects that define the columns in which the filters
-   need to be applied. It requires the following the following keys (The columns
-   marked with \* are required):
+1. **columns**: The list of columns that needs to be represented in the filters pane.
+2. **onChange**: To specify the function that is triggered whenever a filter is applied or cleared.
+3. **setIsPaneOpen**: To trigger the isOpen state.
 
-- **node\***: The name of the column in the entity table.
-- **label\***: The label of the column that needs to be displayed in the
-  `Filters` component.
-- **type\***: The type of the column. It can be one of the following:
-  - `text`: A text input.
-  - `number`: A number input.
-  - `date`: A date input.
-  - `time`: A time input.
-  - `single_option`: A single option select input.
-  - `multi_option`: A multi option select input.
-  - `boolean`: Radio buttons.
-- **inputType**: If a new data type not in the above list needs to be added, you
-  can pass the `inputType` prop along with the `type` prop. It can take the
-  following values:
-  - `text`: A text input.
-  - `number`: A number input.
-  - `date`: A date input.
-  - `time`: A time input.
-  - `single_option`: A single option select input.
-  - `multi_option`: A multi option select input.
-  - `radio`: Radio buttons.
-- **filters**: If a new data type not in the above list is added, you need to
-  pass an array of strings that define the available logical filters for the
-  column.
-- **hidden**: If a column need not be shown in the dropdown, but should be
-  filterable via the URL, pass a truthy value to the `hidden` prop.
-- **model**: While dealing with associated types, it is mandatory to pass the
-  class name of the model of the associated column.
+All these props must be same as that passed to the `Filters` component.
 
-2. **onChange**: A function that is called when the user updates the filters. It
-   takes the segment as an argument.
-3. **hideActionButtons**: A boolean that determines whether the action buttons
-   (submit and delete) are hidden or not. It is set to `true` by default.
-4. **submitButtonProps**: An object that defines the additional props for the
-   submit button.
-5. **deleteButtonProps**: An object that defines the additional props for the
-   delete button.
-6. **segmentsEnabled**: By default, neetoFilters calls the segments API to fetch
-   all the stored segments. If neetoFilters is used without saving filters as
-   segments, set the `segmentsEnabled` prop as `false`.
+### 3. buildFiltersFromURL function
 
-### 2. SegmentMenu Component
+- This function takes the list of all filter columns as argument.
+- It builds the filter payload from the URL search params. This function should be called for initizing the `filters` state.
 
-```jsx
-<MenuBar showMenu={isMenuBarOpen} title="Neeto Filters">
-  <SegmentMenu entity="User" />
-</MenuBar>
+```js
+const [filters, setFilters] = useState(() => buildFiltersFromURL(SAMPLE_FILTER_COLUMNS));
 ```
 
-- The `SegmentMenu` component renders the list of all segments on the `MenuBar`.
-  It provides the functionality of searching and managing the segments.
-- It must only be used within the `MenuBar` component.
-- It expects only one prop: `entity`. It is the name of the model on which the
-  segments are defined on.
-
-### 3. Controlling the filters programatically
-
-- Filters can be programatically modified by updating the `neeto-filters` search
-  param in the URL.
-- For the example payload given above, the URL will be translated to:
-  ```
-  https://<base-url>/?neeto-filters=email-contains-bigbinary-text-and-session-greater_than-10-number-gor-ticket-greater_than-5-number
-  ```
-- The search param can be programatically built using the `encodeFilters` method
-  exported by the package. It accepts the `filters` are argument and returns the
-  search param associated with it.
-- Here is a sample usage:
-
-  ```js
-  const handleUpdateUrl = filters => {
-    const searchParams = new URLSearchParams(window.location.search);
-
-    if (searchParams.get("segmentId")) return;
-
-    isEmpty(filters)
-      ? searchParams.delete("neeto-filters")
-      : searchParams.set("neeto-filters", encodeFilters(filters));
-
-    history.push({ search: searchParams.toString() });
-  };
-  ```
-
-- Similarly, there is a `decodeFilters` method which can be used to decode the
-  URL and obtain the corresponding filters.
-
-### 4. Handling inverse polymorphic relations
-
-- Let's say there is a polymorphic relationship between `bookings` and
-  `transactions` where the relation is defined inside the `bookings` table as
-  `has_one :payment, as: :payable`.
-- If we need to filter all `payments` from the `bookings` table, it can be done
-  in the normal way by setting the node as "booking.payment.column_name". If we
-  need to access it the other way round, the node should be set as
-  "bookings:payable.column_name".
-
 ## Development
 
 Install all the dependencies by executing the following command
 
-```zsh
+```bash
 yarn install
 ```
 
@@ -251,7 +90,7 @@ In order to run the application you need to run the Rails server of the
 neetoFilters 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.
 
-```zsh
+```bash
 git clone https://github.com/bigbinary/neeto-filters-engine.git
 ./test/dummy/bin/setup
 rails server