Falcon | Falcon UI

Table of contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Installation
   • Linking
3. Guidelines
4. Adding a component
5. Using the package in a project
6. Rendering values from the context data
7. Testing

About The Project

The Falcon UI project is the place where components that are shared between the Falcon projects can be developed.

Getting started

To run the Falcon UI project on your local machine, follow these simple steps.

Prerequisites

1. Git
2. Node
3. NPM
4. VS Code (preferred because of jsdocs usage. Read the developer guide in the frontend docs project for more)

Installation

1. Clone the repo

   git clone [email protected]:digitalinsuranceio/falcon/falcon-ui.git

2. Navigate to the repository folder

   cd falcon-ui

3. Install the required packages

   npm install

Linking

To use this project in another project locally follow the steps below:

1. In the Falcon UI project folder: build and watch the project

   npm run build:watch

2. In the Falcon UI project folder: link the project

   npm link

3. In the target project folder: link the falcon-ui library:

   npm link @digitalinsurance/falcon-ui

Guidelines

• Everything that is an input/form component should have a name that ends in 'Input'.
• Everything that is an input/form component should allow for validation messages.
• Everything that is an input/form component should have a label (this can be hidden by default).
• Translations are not handled in this project, intl is not used. The components in this project expect already translated labels to be passed to the components.
• A new component should be added to the components folder in its own folder. If you component is named MyComponent you should add a file named MyComponent.jsx in the src/components/MyComponent folder.
• All components should be exported from the src/index.js file as a named export.
• All components should have a snapshot test and unit tests for any functionality.
• All utility functions should also be tested.

Adding a component

The components in this project are used as Chakra UI components. We use their API to build the components. Please read this page carefully: https://chakra-ui.com/docs/theming/component-style.

When adding a new component please use the following folder structure:

| File/folder name | Description | | --- | --- | | parts | Folder where you put individual parts of your component in | | Component.jsx | The main component file | | theme.js | The theme file |

For an example of this please refer to the ShowData component. Any other files specific to this component can be added in the component folder itself, on the same level as the theme.js file. Make sure to add the theme for your component to the src/theme/index.js file and to export your component in the src/index.js file.

Extending a component

When extending a Chakra component, for example the Select component, prefix the Chakra component with Chakra when importing it:

import { Select as ChakraSelect } from '@chakra-ui/react';

This pattern can also be followed for other packages. Prefix the import with the package name and then extend it in the code:

import { Link as ReactRouterDomLink } from 'react-router-dom';

Using the package in a project

1. Install the package as a dependency

   npm install @digitalinsurance/falcon-ui

2. Import the Falcon UI theme

   import { falconUITheme } from '@digitalinsurance/falcon-ui';

3. Merge the theme with your projects theme and pass it to the ChakraProvider

   // We use lodash/merge here to merge the different theme adjustments
   <ChakraProvider theme={extendTheme(merge(theme, falconUITheme /* other theme adjustments */))}>
     {children}
   </ChakraProvider>

4. Now you can use the components from Falcon UI in your project.

Rendering values from the context data

Some components in Falcon UI are capable of rendering data coming from the context data. You can pass a string as children that contains the following template string: $< first_name > where first_name is the key of the value from the context data you want to render.

To enable this you have to wrap the component with the ContextDataProvider from Falcon UI and pass the data you want to expose to it. Follow the steps below to enable this:

1. Import the ContextDataProvider

   import { ContextDataProvider } from '@digitalinsurance/falcon-ui';

2. Render the ContextDataProvider around the Falcon UI component you want to use the data in

   /**
    * The data can be anything, for example the values from the form using the methods.getValues()
    * function from react-hook-form in a useEffect hook
    */
   <ContextDataProvider data={/* pass your data object here */}>
     {children}
   </ContextDataProvider>

3. Now you can use the templating format in a component, for example the ShowData component

   <ShowData
     label="The first_name value from the contextData"
     value="Hello $< first_name >, welcome!"
   />

Testing

For detailed testing explanation please refer to the frontend docs project on GitLab.