@bigbinary/neeto-rules-frontend 0.4.2 → 0.4.4

package/README.md

@@ -1,19 +1,582 @@
 # neeto-rules-nano
 
-This repo acts as the source of truth for the new nano's structure, configs,
-data etc.
+The `neeto-rules-nano` facilitates the management of automation rules within neeto applications. The nano exports `@bigbinary/neeto-rules-frontend` NPM package and `neeto-rules-engine` Rails engine.
 
-# Local Development Setup
+## Contents
 
-1. Setup
-   [Instructions](https://github.com/bigbinary/neeto-engineering/tree/main/Local-Development-Setup).
+1. [Development with Host Application](#development-with-host-application)
+    - [Engine](#engine)
+      - [Installation](#installation)
+    - [Frontend package](#frontend-package)
+      - [Installation](#installation-1)
+      - [Instructions for development](#instructions-for-development)
+      - [Components](#components)
+        - [NeetoRulesForm](#1-neetorulesform)
+        - [Field components for NeetoRulesForm](#2-field-components-for-neetorulesform)
+          - [InputField](#21-inputfield)
+          - [TextareaField](#22-textareafield)
+          - [SelectField](#23-selectfield)
+          - [MultiSelectField](#24-multiselectfield)
+          - [RadioField](#25-radiofield)
+          - [EventConditions](#26-eventconditions)
+          - [Conditions](#27-conditions)
+          - [Actions](#28-actions)
+          - [Custom action component](#29-custom-action-component)
+        - [RulePreview](#3-rulepreview)
+2. [Instructions for Publishing](#instructions-for-publishing)
 
-2. Run `yarn build` to bundle the app.
+## Development with Host Application
 
-3. Visit http://spinkart.lvh.me:9100 and login with email `oliver@example.com`
-   and password `welcome`.
+### Engine
 
-# Publish instructions
+The Engine is used to manage automation rules feature within neeto applications.
 
-1. [Engine and package installation](./docs/engine-and-package-installation.md)
-2. [Building and releasing](./docs/building-and-releasing.md)
+#### Installation
+
+1. Add this line to your application's Gemfile:
+
+    ```ruby
+    source "NEETO_GEM_SERVER_URL" do
+    # ..existing gems
+
+      gem "neeto-rules-engine"
+    end
+    ```
+
+2. And then execute:
+
+    ```ruby
+    bundle install
+    ```
+
+3. Add this line to your application's `config/routes.rb` file:
+
+    ```ruby
+    mount NeetoRulesEngine::Engine => "/neeto_rules"
+    ```
+
+4. Run the following command to copy the migrations from the engine to the host application:
+
+    ```ruby
+    rails g neeto_rules_engine:install
+    ```
+
+5. Add the migrations to the database:
+
+    ```ruby
+    bundle exec rails db:migrate
+    ```
+
+### Frontend package
+
+#### Installation
+
+Install the latest `neetoRules nano` package using the below command:
+
+```shell
+yarn add @bigbinary/neeto-rules-frontend
+```
+
+### 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.
+
+### Components
+
+#### 1. `NeetoRulesForm`
+
+<div align="center">
+  <img src="./docs/images/rules-form.png"/>
+</div>
+
+<br>
+
+The `NeetoRulesForm` component is used to create and edit automation rules.
+
+`NeetoRulesForm` accepts the following field types which is specified in the `initialProps` ([reference](https://github.com/bigbinary/neeto-desk-web/blob/c7ea475e0963cb4fa0831856c9545e1f697ca472/app/javascript/src/components/Automations/Form/constants.js#L43)):
+
+1. text
+2. long-text
+3. dropdown
+4. multi-select
+5. radio
+6. events
+7. condition
+8. actions
+
+#### Props
+
+- `data`: The initial props for the form.
+- `children`: The form fields.
+- `className`: To provide external classes to form.
+- `handleSubmit`: The function to handle the form submission.
+- `handleClose`: The function to handle the form close.
+
+#### Usage
+
+```jsx
+import { NeetoRulesForm } from "@bigbinary/neeto-rules-frontend";
+
+const { InputField, TextareaField, SelectField, Events, Card, Conditions, Actions } = NeetoRulesForm;
+
+<NeetoRulesForm data={initialProps}>
+  {({ formattedValues, values, ...formikBag }) => (
+    <>
+      <InputField name="name" data={initialProps} />
+      <TextareaField name="description" data={initialProps} />
+      <SelectField name="projectId" data={initialProps} />
+      <Events name="events" data={initialProps} performerName="performer" />
+      <Card title="Conditions">
+        <Conditions name="conditions" data={initialProps} />
+      </Card>
+      <Actions name="actions" data={initialProps} />
+    </>
+  )}
+</NeetoRulesForm>
+```
+
+#### References
+
+1. [neeto-cal-web](https://github.com/bigbinary/neeto-cal-web/blob/7ef6806ecc47e01d5cdb0252878e4dc442d12dd0/app/javascript/src/components/commons/MeetingsBuilder/Configure/AutomationRules/Form/index.jsx#L11)
+2. [neeto-desk-web](https://github.com/bigbinary/neeto-desk-web/blob/edc9bad9305d55c18a67de3931cbe2633fe3710f/app/javascript/src/components/Automations/Form/index.jsx#L188)
+3. [neeto-planner-web](https://github.com/bigbinary/neeto-planner-web/blob/73bb48e1721bb8ae3c71dbabe7b3b99c443a3f6e/app/javascript/src/components/Settings/Automations/Automation/Form/index.jsx#L39)
+
+<br>
+
+#### 2. Field components for `NeetoRulesForm`
+
+NeetoRulesForm provides field components to create the automation rules form.
+
+#### References
+
+1. [neeto-cal-web](https://github.com/bigbinary/neeto-cal-web/blob/7ef6806ecc47e01d5cdb0252878e4dc442d12dd0/app/javascript/src/components/commons/MeetingsBuilder/Configure/AutomationRules/Form/index.jsx#L8)
+2. [neeto-desk-web](https://github.com/bigbinary/neeto-desk-web/blob/edc9bad9305d55c18a67de3931cbe2633fe3710f/app/javascript/src/components/Macros/Form/FormContent.jsx#L8)
+3. [neeto-planner-web](https://github.com/bigbinary/neeto-planner-web/blob/73bb48e1721bb8ae3c71dbabe7b3b99c443a3f6e/app/javascript/src/components/Settings/Automations/Automation/Form/FormContent.jsx#L24)
+
+#### 2.1 `InputField`
+
+```jsx
+import { NeetoRulesForm } from "@bigbinary/neeto-rules-frontend";
+
+const { InputField } = NeetoRulesForm;
+
+const initialProps = {
+  ...otherProps,
+  firstName: {
+    label: "First Name",
+    type: "text",
+    value: "", // Default value.
+    componentProps: {
+      placeholder: "Enter name",
+    },
+  },
+};
+
+<InputField name="firstName" data={initialProps} />;
+```
+
+#### props
+
+1. `name`: Name of the field. The name should be same as that in the `initialProps`.
+2. `data`: The same `initialProps` that is passed to data prop in `NeetoRulesForm`.
+3. `label`: Label for the field.
+
+#### 2.2 `TextareaField`
+
+```jsx
+import { NeetoRulesForm } from "@bigbinary/neeto-rules-frontend";
+
+const { TextareaField } = NeetoRulesForm;
+
+const initialProps = {
+  ...otherProps,
+  description: {
+    label: "Description",
+    type: "long-text",
+    value: "", // Default value.
+  },
+};
+
+<TextareaField name="description" data={initialProps} />;
+```
+
+#### props
+
+1. `name`: Name of the field. The name should be same as that in the `initialProps`.
+2. `data`: The same `initialProps` that is passed as `data` prop in `NeetoRulesForm`.
+3. `label`: Label for the field.
+
+####  2.3 `SelectField`
+
+```jsx
+import { NeetoRulesForm } from "@bigbinary/neeto-rules-frontend";
+
+const { SelectField } = NeetoRulesForm;
+
+const initialProps = {
+  ...otherProps,
+  user: {
+    label: "Project",
+    type: "dropdown",
+    options: [{ label: "Oliver", value: "oliver" }],
+    value: "oliver", // Default selected option will be Oliver
+  },
+};
+
+<SelectField name="user" data={initialProps} />;
+```
+
+#### props
+
+1. `name`: Name of the field. The name should be same as that in the `initialProps`.
+2. `data`: The same `initialProps` that is passed to data prop in `NeetoRulesForm`.
+3. `label`: Label for the field.
+4. `options`: Options for the dropdown. The options should be an array of objects with `label` and `value` keys. `[{label, value}]`.
+5. `onChange`: Callback function that is called when the value of the dropdown changes. `(value, setValue) => void` `setValue` is to set the new value.
+
+#### 2.4 `MultiSelectField`
+
+```jsx
+import { NeetoRulesForm } from "@bigbinary/neeto-rules-frontend";
+
+const { MultiSelectField } = NeetoRulesForm;
+
+const initialProps = {
+  ...otherProps,
+  users: {
+    label: "Projects",
+    type: "multi-select",
+    options: [
+      { label: "Oliver", value: "oliver" },
+      { label: "John", value: "john" },
+    ],
+    value: ["oliver"], // Default selected option will be Oliver
+  },
+};
+
+<MultiSelectField name="users" data={initialProps} />;
+```
+
+#### props
+
+1. `name`: Name of the field. The name should be same as that in the `initialProps`.
+2. `data`: The same `initialProps` that is passed to data prop in `NeetoRulesForm`.
+3. `label`: Label for the field.
+4. `options`: Options for the dropdown. The options should be an array of objects with `label` and `value` keys. `[{label, value}]`.
+5. `onChange`: Callback function that is called when the value of the dropdown changes. `(value, setValue) => void` `setValue` is to set the new value.
+
+#### 2.5 `RadioField`
+
+```jsx
+import { NeetoRulesForm } from "@bigbinary/neeto-rules-frontend";
+
+const { RadioField } = NeetoRulesForm;
+
+const initialProps = {
+  ...otherProps,
+  performer: {
+    label: "Performer",
+    type: "radio",
+    value: "any", // Default selected value will be "any"
+    options: [
+      { label: "Admin", value: "admin" },
+      { label: "Any", value: "any" },
+    ],
+  },
+};
+
+<RadioField name="performer" data={initialProps} />;
+```
+
+#### props
+
+1. `name`: Name of the field. The name should be same as that in the `initialProps`.
+2. `data`: The same `initialProps` that is passed to data prop in `NeetoRulesForm`.
+3. `label`: Label for the field.
+4. `options`: Options for the radio buttons. The options should be an array of objects with `label` and `value` keys. `[{label, value}]`.
+
+#### 2.6 `EventConditions`
+
+![event-conditions](./docs/images/event-conditions.png)
+
+```jsx
+import { NeetoRulesForm } from "@bigbinary/neeto-rules-frontend";
+
+const { EventConditions } = NeetoRulesForm;
+
+const EVENT_OPTIONS = [
+  { label: "Ticket is created", value: "created" },
+  { label: "Ticket is updated", value: "updated" },
+  ...otherOptions,
+];
+
+const PERFORMER_OPTIONS = [
+  { label: "Any", value: "any" },
+  { label: "Member", value: "agent" },
+  ...otherOptions,
+];
+
+const CONDITION_OPTIONS = [
+  {
+    value: "status",
+    label: "Status",
+    type: "multi-select",
+    allowMatching: ["any_of", "none_of"],
+    dropdownOptions: [
+      { label: "Open", value: "open" },
+      { label: "Closed", value: "closed" },
+      { label: "On hold", value: "on_hold" },
+    ],
+  },
+  {
+    value: "name",
+    label: "Name",
+    allowMatching: ["is", "is_not"],
+    type: "text",
+  },
+  ...otherOptions,
+];
+
+const DEFAULT_CONDITION_VALUE = [
+  {
+    id: "1",
+    field: "status",
+    verb: "any_of",
+    metadata: { values: ["open", "closed"] },
+    joinType: "and_operator",
+  },
+  {
+    id: "2",
+    field: "name",
+    verb: "is",
+    metadata: { value: "Test" },
+    joinType: "and_operator",
+  },
+  ...otherConditionValues,
+];
+
+const initialProps = {
+  ...otherProps,
+  events: {
+    label: "Events",
+    type: "events",
+    value: [{ name: EVENT_OPTIONS[0].value }],
+    eventOptions: EVENT_OPTIONS,
+    defaultData: { name: "time_based", performer: "system" },
+  },
+  performer: {
+    label: "Performer",
+    type: "dropdown",
+    value: "any",
+    options: PERFORMER_OPTIONS,
+  },
+  conditions: {
+    label: "Conditions",
+    type: "condition",
+    conditionOptions: CONDITION_OPTIONS,
+    value: DEFAULT_CONDITION_VALUE,
+  },
+};
+
+<EventConditions
+  name="events"
+  data={initialProps}
+  performerName="performer"
+  conditionsName="conditions"
+/>;
+```
+
+#### props
+
+1. `name`: Name of the field. The name should be same as that in the `initialProps`.
+2. `data`: The same `initialProps` that is passed to data prop in NeetoRulesForm.
+3. `label`: Label for the field.
+4. `performerName`: Name of the performer field. The `performerName` should be same as that in the `initialProps`.
+5. `conditionsName`: Name of the conditions field. The `conditionsName` should be same as that in the `initialProps`.
+6. `onSelectEvent`: `(name, selectedOption) => void`. This method will trigger when we select an event option. The name is to refer the event in the formik context.
+
+Refer to the [EventCondition section](./docs/event-conditions.md) for more information.
+
+#### 2.7 `Conditions`
+
+```jsx
+import { NeetoRulesForm } from "@bigbinary/neeto-rules-frontend";
+
+const { Card, Conditions } = NeetoRulesForm;
+
+const initialProps = {
+  ...otherProps,
+  conditions: {
+    label: "Conditions",
+    type: "condition",
+    conditionOptions: [
+      {
+        value: "status",
+        label: "Status",
+        type: "dropdown", // Types : text, number, email, decimal, url, dropdown, multi-select, multi-select-create, date.
+        allowMatching: ["is", "is_not", "any_of", "none_of"],
+        dropdownOptions: [
+          { label: "Open", value: "open" },
+          { label: "Closed", value: "closed" },
+        ],
+        additionalData: {
+          any_of: "multi-select",
+          none_of: "multi-select",
+        },
+      },
+      {
+        value: "name",
+        label: "Name",
+        type: "text",
+        allowMatching: ["is", "is_not"],
+      },
+      {
+        value: "tags",
+        label: "Tags",
+        type: "multi-select-create",
+        allowMatching: ["contains_any_of", "contains_none_of"],
+      },
+    ],
+    value: [
+      {
+        id: "1",
+        field: "status",
+        verb: "is",
+        metadata: { value: "open" },
+        joinType: "and_operator",
+      },
+      {
+        id: "2",
+        field: "name",
+        verb: "is",
+        metadata: { value: "Test" },
+        joinType: "and_operator",
+      },
+      {
+        id: "3",
+        field: "tags",
+        verb: "contains_any_of",
+        metadata: { values: ["Test", "Open"] },
+        joinType: "and_operator",
+      },
+    ],
+  },
+};
+
+<Card title="Conditions">
+  <Conditions name="conditions" data={initialProps} />
+</Card>;
+```
+
+#### props
+
+1. `name`: Name of the field. The name should be same as that in the `initialProps`.
+2. `data`: The same `initialProps` that is passed to data prop in `NeetoRulesForm`.
+3. `label`: Label for the field.
+4. `onSelectCondition`: `(name, selectedOption) => void`. This method will trigger when we select a condition option. The name is to refer the condition in the formik context.
+5. `selectedConditionOptions`: `(selectedCondition)=> [{label, value}]`. To provide options for the selected condition if the type of selected condition is `dropdown`, `multi-select`, or `multi-select-create`.
+6. `isCallback`: To specify if there is a preview callback function for the conditions. (Boolean).
+7. `previewCallback`: `(conditions) => void`. This method will trigger when we click on the preview button. The conditions are the selected conditions in the formik context.
+
+#### 2.8 `Actions`
+
+![actions](./docs/images/action.png)
+
+```jsx
+import { NeetoRulesForm } from "@bigbinary/neeto-rules-frontend";
+
+const { Actions } = NeetoRulesForm;
+
+const initialProps = {
+  ...otherProps,
+  actions: {
+    label: "Actions",
+    type: "actions",
+    actionOptions: [
+      {
+        value: "add_tags",
+        label: "Add Tags",
+        type: "multiSelect", // Types : emailToIds, emailTo, email, dropdown, list, multiSelect, note, date, text, textarea, decimal, number, regex, longText
+        hideSeparator: true,
+        placeholder: "Select tags",
+        dropdownOptions: [
+          { label: "Open", value: "open" },
+          { label: "Close", value: "close" },
+          { label: "Hold", value: "hold" },
+        ],
+      },
+      {
+        value: "email_to",
+        label: "Email To",
+        type: "emailToIds",
+        separator: "as",
+        hideSubject: true, // Hide subject field if this prop is true
+      },
+      {
+        value: "send_sms",
+        label: "Send sms",
+        type: "longText",
+      },
+    ],
+    value: [
+      {
+        id: "1",
+        name: "email_to", // Specify the value of the selected action.
+        metadata: { emails: ["a@a.com"], subject: "test", body: "test" },
+      },
+      {
+        id: "2",
+        name: "add_tags",
+        metadata: { values: ["close"] },
+      },
+    ],
+  },
+};
+
+<Actions name="fieldName" data={initialProps} />;
+```
+
+#### props
+
+1. `name`: Name of the field. The name should be same as that in the `initialProps`.
+2. `data`: The same `initialProps` that is passed to data prop in `NeetoRulesForm`.
+3. `label`: Label for the field.
+4. `onSelectAction`: `(name, selectedOption) => void`. This method will trigger when we select an action option. The name is to refer the action in the formik context.
+5. `selectedActionOptions`: `(selectedAction)=> [{label, value}]`. To provide options for the selected action if the type of selected action is `dropdown` or `multi-select`.
+
+Refer to the [Actions section](./docs/actions.md) for more information.
+
+#### 2.9 Custom action component
+
+neetoRulesFrontend allows to pass custom action components from host application. Below is an example for customize task component which is being sent by neeto-crm in action options.
+
+```jsx
+ {
+    label: "Add task",
+    value: "add_task",
+    placeholder: "Task",
+    component: TaskComponent,
+    validation: TASK_VALIDATION,
+  },
+```
+
+#### 3. `RulePreview`
+
+The `RulePreview` component is used to preview the automation rule.
+
+![rule-preview](./docs/images/rule-preview.png)
+
+#### Props
+
+1. `ruleDetails`: The rule details to be previewed.
+2. `isLoading`: To specify if the preview is loading. (Boolean).
+3. `isOpen`: To specify if the preview is open. (Boolean).
+4. `onClose`: The callback function to call when the preview is closed. `() => void`.
+
+reference:
+
+1. [neeto-crm-web](https://github.com/bigbinary/neeto-crm-web/blob/b4c59181aec20d7519dd73b54b0695362ed4466f/app/javascript/src/components/Settings/Automations/index.jsx#L115)
+
+## Instructions for Publishing
+
+Consult the [building and releasing packages](https://neeto-engineering.neetokb.com/articles/building-and-releasing-packages) guide for details on how to publish.

package/app/javascript/src/translations/en.json

@@ -34,6 +34,7 @@
       "noEvents": "A rule without events will run hourly.",
       "addEvent": "Add Event",
       "noCondition": "No tickets matching specified conditions",
+      "noTicketFields": "No more conditions.",
       "subjectText": "Will be generated from the ticket's subject.",
       "note": "Note",
       "thisHappens": "this happens",