@bigbinary/neeto-approvals-frontend 0.2.11 → 0.2.13

package/README.md

@@ -1,34 +1,92 @@
-# @bigbinary/neeto-approvals-frontend
+# neeto-approvals-nano
+The `neeto-approvals-nano` manages approvals within neeto applications. The nano exports the `@bigbinary/neeto-approvals-frontend` NPM package and `neeto-approvals-engine` Rails engine for development.
+
+# Contents
+1. [Development with Host Application](#development-with-host-application)
+    - [Engine](#engine)
+        - [Installation](#installation)
+        - [Usage](#usage)
+    - [Frontend package](#frontend-package)
+        - [Installation](#installation-1)
+        - [Components](#components)
+2. [Instructions for Publishing](#instructions-for-publishing)
+
+# Development with Host Application
+## Engine
+The engine is used to manage approval requests and approval templates for an organization.
+
+### Installation
+1. Add this line to your application's Gemfile:
+    ```ruby
+    source "NEETO_GEM_SERVER_URL" do
+       # ..existing gems
+
+       gem 'neeto-approvals-engine'
+    end
+    ```
+2. And then execute:
+    ```ruby
+    bundle install
+    ```
+3. Add this line to your application's `config/routes.rb` file:
+    ```ruby
+    mount NeetoApprovalsEngine::Engine => "/neeto_approvals_engine"
+    ```
+4. Run the following command to copy the migrations from the engine to the host application:
+    ```ruby
+    bundle exec rails neeto_approvals_engine:install:migrations
+    ```
+5. Add the migrations to the database:
+    ```ruby
+    bundle exec rails db:migrate
+    ```
 
-neetoApprovals is a library that manages approvals across neeto products.
+### Usage
 
-## Installation
+You can learn more about the setup and usage here:
+1. [Models](/docs/engine/models.md)
+2. [Controllers](/docs/engine/controllers.md)
+3. [Services](/docs/engine/services.md)
 
-1. **neetoApprovals** has a few peer dependencies that are required for the proper
-functioning of the package. Install all the peer dependencies using the below
-command:
+## Frontend package
+The package exports three components: `Approvals`, `Form`, and `Public`.
 
+### Installation
+1. `neeto-approvals-nano` has a few peer dependencies that are required for the proper functioning of the package. Install all the peer dependencies using the below command:
     ```zsh
     yarn add @bigbinary/neeto-icons@1.8.46 @bigbinary/neetoui@4.1.33 axios@1.2.1 classnames@2.3.2 formik@2.2.9 ramda@0.28.0 react-router-dom@5.3.3 react-toastify@8.2.0 react-query@3.39.2 yup@0.32.11
     ```
 
-2. Now install the latest **neetoApprovals** package using the below command:
-
+2. Now install the latest `neeto-approvals-nano` package using the below command:
     ```zsh
     yarn add @bigbinary/neeto-approvals-frontend
     ```
 
-## Usage
+### Components
+#### `Approvals` ([source code](https://github.com/bigbinary/neeto-approvals-nano/blob/13500c56e311a488fce886876781b8c26a0f0145/app/javascript/src/components/Approvals/index.jsx))
+This component manages approval requests, approval templates and history of approval requests. It consists of three tabs: `Pending`, `Templates`, and `History`
+1. `Pending` - Lists all pending approval requests.
+2. `Templates` - Lists all approval templates.
+3. `History` - Lists all approved, rejected, and cancelled approval requests.
+
+
+##### Props
+- `config`: Configuration object that includes specifications for paths, URLs, template placeholders and breadcrumbs. It also allows optional configurations for help articles.
+
+##### Configuration
+Refer to the [Approvals](/docs/frontend/approvals.md) section for detailed information on the available configurations for the `Approvals` component.
+
+##### Usage
 ```jsx
 import React from "react";
 
+import { Approvals } from "@bigbinary/neeto-approvals-frontend";
 import { routes } from "common/routes";
 import { BrowserRouter, Redirect, Route, Switch } from "react-router-dom";
 import { ToastContainer } from "react-toastify";
 
 import SideBar from "./Common/SideBar";
 
-import { Approvals } from "neetoapprovals";
 
 const Main = () => (
   <BrowserRouter>
@@ -39,40 +97,10 @@ const Main = () => (
           path={routes.approvals}
           render={() => (
             <Approvals
-              config={{
-                approvalsPath: routes.approvals,
-                templateUrl: "templatesUrl",
-                requestUrl: "requestsUrl",
-                templatePlaceholders: [
-                  {
-                    category: "ticket",
-                    label: "Ticket",
-                    variables: [
-                      { key: "id", label: "ticket.id" },
-                      { key: "number", label: "ticket.number" },
-                      { key: "subject", label: "ticket.subject" },
-                    ],
-                  },
-                  {
-                    category: "requester",
-                    label: "Customer",
-                    variables: [
-                      { key: "id", label: "customer.id" },
-                      { key: "name", label: "customer.name" },
-                      { key: "email", label: "customer.email" },
-                    ],
-                  },
-                ],
-                breadcrumbs: [
-                  { text: "Settings", link: routes.settings },
-                  { text: "General settings", link: routes.settings.general },
-                  { text: "Approvals" },
-                ],
-              }}
+              config={APPROVALS_CONFIG}
             />
           )}
         />
-        <Redirect to={routes.approvals} />
       </Switch>
     </div>
     <ToastContainer />
@@ -82,45 +110,73 @@ const Main = () => (
 export default Main;
 ```
 
-## Configurations
+#### `Form` ([source code](https://github.com/bigbinary/neeto-approvals-nano/blob/13500c56e311a488fce886876781b8c26a0f0145/app/javascript/src/components/Approvals/CreateRequestForm.jsx))
+This component handles creation and updation of approval templates.
+
+##### Props
+- `isLoading` - Boolean value to show the loading state in the submit button
+- `isOpen` - Boolean value to open the pane
+- `setIsPaneOpen` - Set it to false to close the pane
+- `requestableId` - ID of the entity to which we are associating requests. This is used to parse messages based on the entity's attributes in the engine.
+- `onSubmit` - Function which calls the API to submit approval request details such as request message, template title, approver ID and requestable ID.
 
-The configurations for the components present in this NPM package are given below. Click on them to read more:
+##### Usage
+```jsx
+import React from "react";
+import { Form } from "@bigbinary/neeto-approvals-frontend";
+
+const RequestApproval = () => {
+  const { mutate: createRequest, isLoading } = useCreateRequest();
+
+  const onSubmit = (request, template, onClose) => {
+    createRequest(
+      {
+        request: {
+          ...request,
+          title: template.name,
+          approverId: template.approverId,
+          requestableId: requestableId, // Specify the ID of the requestable associated entity
+        },
+      },
+      { onSuccess: onClose }
+    );
+  };
+
+  return (
+    <Form
+      isLoading={isLoading}
+      isOpen={isNewApprovalRequestPaneOpen}
+      setIsPaneOpen={setIsNewApprovalRequestPaneOpen}
+      requestableId={requestableId} // Specify the ID of the requestable associated entity
+      onSubmit={onSubmit}
+    />
+  );
+};
+
+export default RequestApproval;
+```
 
-1. [Approvals](./docs/approvals/README.md)
-2. [Form](./docs/form/README.md)
+#### `Public` ([source code](https://github.com/bigbinary/neeto-approvals-nano/blob/13500c56e311a488fce886876781b8c26a0f0145/app/javascript/src/components/Approvals/Public/index.jsx))
 
-## Development
+This component is used to show the approval request detail without any user login.
 
-1. Install all the dependencies by executing the following command
+##### Props
+No props need to be passed. However, ensure that the path of the page rendering the `Public` component contains the `id` param for the request ID.
 
-    ```zsh
-    yarn install
-    ```
+##### Usage
+```jsx
+import React from "react";
+import { Public } from "@bigbinary/neeto-approvals-frontend";
 
-2. See the changes in the example app by executing the following command:
+const PublicRequestApproval = () => {
+  return (
+    <Public />
+  );
+};
+
+export default PublicRequestApproval;
+```
 
-    ```zsh
-    yarn dev
-    ```
 
-# Building and releasing.
-
-The `@bigbinary/neeto-approvals-frontend` package gets published to NPM when we
-merge a PR with `patch`, `minor` or `major` label to the `main` branch. The
-`patch` label is used for bug fixes, `minor` label is used for new features and
-`major` label is used for breaking changes. You can checkout the
-`Create and publish releases` workflow in GitHub Actions to get a live update.
-
-In case if you missed to add the label, you can manually publish the package.
-For that first you need to create a PR to update the version number in the
-`package.json` file and merge it to the `main` branch. After merging the PR, you
-need to create a
-[new github release](https://github.com/bigbinary/neeto-approvals-frontend/releases/new)
-from main branch. Whenever a new release is created with a new version number,
-the github actions will automatically publish the built package to npm. You can
-checkout the `Publish to npm` workflow in GitHub Actions to get a live update.
-
-Please note that before publishing the package, you need to verify the
-functionality in some of the neeto web-apps locally using `yalc` package
-manager. The usage of yalc is explained in this video:
-https://youtu.be/QBiYGP0Rhe0
+# 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/{src → app/javascript/src}/translations/en.json

@@ -1,7 +1,7 @@
 {
   "neetoApprovals": {
     "alerts": {
-      "deleting_": "You are permanently deleting the {{what}} <strong>{{- name}}</strong>. This can't be undone."
+      "deleting_": "You are permanently deleting the {{what}} <strong>{{name, anyCase}}</strong>. This can't be undone."
     },
     "buttons": {
       "cancel": "Cancel",
@@ -30,9 +30,6 @@
       "name": "Name",
       "notFound_": "There are no {{what}} to show",
       "notFound": "Could not find the approval request.",
-      "visibility": "Visibility",
-      "variable": "Variable",
-      "variable_": "Variable {{number}}",
       "pendingApproval_one": "Pending approval",
       "pendingApproval_other": "Pending approvals",
       "title": "Title",
@@ -48,12 +45,12 @@
       "waitingFor": "Waiting for",
       "templateDetails": "Template details",
       "field": "Field",
-      "noDataHelpText": "Here is how you can use <a>{{entity}}.</a>"
+      "noDataHelpText": "Here is how you can use <a>{{entity, anyCase}}.</a>"
     },
     "validations": {
       "limitExceeded": "You have exceeded the limit of {{limit}} characters for the {{what}}.",
       "approver": "Please select a approver",
-      "required": "{{what}} is required",
+      "required": "{{what, anyCase}} is required",
       "variableName": "Name must be alphanumeric, may include underscore, must start with a letter and must not end with an underscore.",
       "pleaseEnter_": "Please enter {{what}}"
     },