fk-ui-common

It is a npm package, which will have all the common components of FPG Fintech. It can be used across all the FPG fintech UI products(fk-cp-fintech, insurance, advanz app).

Installation

// with npm
npm install fk-ui-common

// with yarn
yarn add fk-ui-common

Pre requisites

You must be using React version >= 16.9.0 and React DOM >= 16.9.0

Usage

fk-ui-common, provides the following functionalities:

• App wide State management for your screen data, and widget data
• Pure UI components such as SnackBar, or Accordian, or HTMLText
• Action handling such as page navigation, redirection, API call, bottom sheets, modal, etc via HandleAction HOC. You can directly or indirectly use this. For example StatefulButtonWidget, or ActionLink will use HandleAction internally to perform associated action.
• Components that might require bridge interaction such as HeaderWrapper component

If you want to make use of any functionality other than the pure UI components, then you must first initialise the UICommonSDK (erlier SDK, now renamed). This is needed to provide the API interaction functionality as well as bridge functionality to the fk-ui-common components that need it. For example, HandleAction requires both APIHandler and FKWebUIProvider implementations.:

import { UICommonSDK } from 'fk-ui-common';
import { APIHandler } from 'fk-ui-common';
//1. Provide implementation of APIHandler like So:
 class YourAPI extends APIHandler {
   ....
 }
//2. Provide the UI provider implementation
import {FKWebUIProvider} from 'fk-ui-common';
class YourUIProvider extends FKWebUIProvider {

}

//3. Configure the UICommonSDK object
import { UICommonSDK } from 'fk-ui-common';
 UICommonSDK.initialize(new YourAPI(), new YourUIProvider());

Seeing components in action

You can run the following command to see the storybook in action

npm run storybook

This should open a page that contains all stories, in your default browser. This should help to see the various widgets and components in action. You should see the storybook like this:

You can check the usage in the form of a code under the story pane as shown in the above figure. Ensure you have the Canvas selected at the top. You can see different use cases of a given component by exploring all the stories under that component. Therby you can learn how to use a given component in your own app.

In the next section we will discuss how to use some of the components in a React app.

App state management

The fk-ui-common does provide a powerful app state management functionality out of the box. It uses the modern context API to maintain the central state, and also enable the provider-subscriber pattern dictated by Context API to reflect state updates in the UI. This state management is geared towards apps that are going to be widget driven and is going to use the widgets provided by this framework.

You should ensure your root component is enclosed within the app context.

import { AppProvider } from 'fk-ui-common';

const App = () => {
  UICommonSDK.initialize(apiHandler, new FKWebUI());
  return (
    <React.Fragment>
      <Router>
        <AppProvider>
           <YourRootComponentHere/>
        </AppProvider>
      </Router>
    </React.Fragment>
  );
};

So any component down under your root can access the app state maintained by the AppContext by using the hook useAppState

AppContext mainly maintains the following states:

• Screen data, the page specification as an assortment of widget, also known as page response is parsed and stored using a utility method called setScreenData. You can access the screen data using screenData.
• Widget Data: Each page will also have something called WidgetData, which the data that user provided by interacting with the widgets in a given page. You can access it from the app state using widgetData, and set it using setWidgetData.
• screenName This is the name of the current page. You can set it if needed using setScreenName.
• modalSheetOpened Useful to check if a modal sheet is currently opened. You can set the same using setModalSheetOpened.
• enterKeyPressed A useful state in forms to initate an action when user presses enter button. You can set this using setEnterkeyPressed.
• updatePageData This will refresh the current page's content. For example, calling an API might return back you a response indicating that you need to refresh the current page's content. For an example usage, refer handleAction.tsx>handleResponse method.

You can refer the AppProvide component definition to understand the structure of the value of the provider here: src/components/App/AppProvider.tsx

Here is a typicall usage of useAppState hook inside a widget StatefulButtonWidget:

import useAppState from '../App/useAppState';
...

  const {
    screenName,
    widgetData,
    enterKeyFormId,
    setEnterKeyPressed
  } = useAppState();

...
  //Get the widget data for this page...
  let screenWidgetData = widgetData[screenName];

  //checks if any data present in optional form and checks for validation
  if (!disabled && screenWidgetData && fetchIds.length > 0) {
    fetchIds.forEach((key: string) => {
      if (
        screenWidgetData[key] &&
        screenWidgetData[key].hasValue &&
        !screenWidgetData[key].valid
      ) {
        disabled = true;
      }
    });
  }

Here is another example where a page builder in your app would parse widgets and set the screen data for each of the page:

 const { setScreenData, setScreenName, screenData } = useAppState();

  const getPageContent = () => {
    apiHandler
      .fetchPage(pageUri)
      .then((response: any) => {
        setScreenData(response, pageUri);
      })
      .catch(() => {
          getPageContent();
        });
      });
  };

Snackbar Component

This is another quite useful reusable component which you can use in your app with minimum setup requirements. First you will require to wrap your components where you want to use the snackbar, in a HOC called SnackBarProvider. A typical usage is illustrated here:

import { SnackBarProvider } from 'fk-ui-common';

//Wrap the components in which you want to use SnackBar
const App = () => {
  return (
    <React.Fragment>

          <SnackBarProvider>

            <MyComponentUsingSnackBar/>


          </SnackBarProvider>

    </React.Fragment>
  );
};

Inside your or its descendants, you can now use the snackBar, via a handly react hook:

import useSnackBar from 'fk-ui-common';

//inside the component
   const { addToast } = useSnackBar();

 addToast("Failed to get widgets!", {
            retry: getWidgets, //Method to be retried via the retry button in snackbar
            autoDismissTime: 3000 //milliseconds
          });

Component Driven Development

We’ll build our UI following a Component-Driven Development (CDD) methodology. It’s a process that builds UIs from the “bottom up” starting with components and ending with screens. CDD helps you scale the amount of complexity you’re faced with as you build out the UI.

We use StoryBook. We create components and stories inside component specific folder inside src/components folder. So if we develop a component by name 'Button', then we will have following important files inside the component folder:

• CSS styles: /src/components/Button/style.css
• TSX of component: /src/components/Button/Button.tsx
• Stories of the component: /src/components/Button/Button.stories.tsx

For a good introduction to Storybook, refer this.

Generating a new component for development

If you want to develop a component, you can automatically generate a folder by the name you choose, that will contain the necessary tsx, css, storybook, and associated type specification file generated together. To generate the component folder, run

npm run generate <component name>

So for example, you want to develop a component by name 'Box', you will need to run:

npm run generate Box

This will generate a folder containining following:

• index.ts The module exports will be in this, your component and its types are exported in this.
• Box.tsx The component you are developing. It will contain placeholder code, which you will modify as per your component requirement.
• Box.css The SASS style css. You can write SASS like nested css here. SASS variables and nesting is supported out of the box by the PostCSS toolchain.
• Box.stories.tsx - This will contain your stories for visually testing the component in isolation. Currently only the classic storiesOf syntax is supported.
• types.ts This file will contain typically the data type of the props that your component will receive.

Steps to publish the version:

1. Create an account in global npm registry : https://www.npmjs.com/

2. npm login: Comment the flipkart registry and un-comment the global registry entry in .npmrc, to get logged in to the global registry.

   Username: [npmjs created username] Password: [npmjs Password] Email: [flipkart email address].

If 2FA is enabled, there will be one more ask for 2FA OTP Authenticator(OTP) :[add from the Authenticator].

Once user is logged, it will show the registry, where the user is logged as.

3. npm publish, update the package.json, for the new changes and then run the command. If 2FA is enabled, there will be ask for the OTP, please add and proceed further.