@allica/ui-react

A suite of React components based on the Allica Design System, that enables teams within Allica Bank to build consistent user interfaces

Scope

It is important that the scope of this library is constrained to only those components and utilities that implement the small building blocks of the Allica Design System. These building blocks can be consumed by product applications in order to build application specific components and pages. Application specific components should not be added to this library.

Component designs (Figma)

Getting Started

Install in a project

The library is a private npm package, hosted on Azure. In order to install and use the library you must first set up access to Azure artifacts, usually with Personal Access Token, and then setup your project .npmrc (note this is different from the user .npmrc mentioned in the Azure artifacts setup)

Set up Personal Access Token (PAT)

Follow the steps here, under 'Project setup', making sure to follow the correct steps for your operating system.

Set up .npmrc

In the root of your project (same level as package.json), if not already created, create a .npmrc file

touch .npmrc

and add the following -

@allica:registry=https://pkgs.dev.azure.com/AllicaBankLtd/Allica_Web/_packaging/allica_web/npm/registry/

Install the package

To install the package, run -

npm i @allica/ui-react

Install peer dependencies

This component library relies on some packages that your application needs installed as dependencies. These packages do not come packaged automatically. To install the required peer dependencies, run -

npm i react@18 react-dom@18 @chakra-ui/react@2 @emotion/react@11 @emotion/styled@11 framer-motion@7

Optimize your bundle size

Given this library relies on Chakra UI and it's dependencies, its important to pay attention to the bundle size of your application after installing the above dependencies. Your application should look to use optimizations such as tree shaking, minification and compression as a minimum.

Storybook

The library contains a Storybook of all the available components. Currently storybook is only available locally. To view Storybook, run -

npm run storybook

Using the library in the project

Theming

Once you have the library installed in your application, you need to wrap your components with a ThemeProvider. This will apply the Allica 'theme' to the components consumed from this library, and also any further Chakra-UI components. You also need to import the fonts. You can do something like -

import { ThemeProvider } from '@allica/ui-react'
import '@allica/ui-react/dist/esm/fonts.css';
...
return (
    <ThemeProvider>
        <App />
    </ThemeProvider>
)

Now you can apply theme values to components, in order to get the predefined size / color / variant of component etc

e.g. for a Text component, with a size '02' and colour 'text-1' (as per design language)

import { Text } fron '@allica/ui-react';
...
return (
    <Text size={'02'} color={'text.1'}>Example</Text>
)

The various values that are used in the theme, such as colors, fonts, sizes, spacing and more, can be found here

Typescript support ( @allica/ui-react v2.7+)

In order for typescript to know about the available theme tokens, you can add the following script to your project, which will generate theme tokens based on the Allica theme -

"gen:theme-types": "npx chakra-cli tokens node_modules/@allica/ui-react/theme ",
"dependencies": "npm run gen:theme-types",

note - dependencies script is optional, but is a predefined npm script that will run when node_modules are updated, useful for automatically generating theme tokens

More on theming in Chakra-UI's docs

Contributing

Work items for new component designs, implementation and any bugs found in the component library should be tracked in Jira.

Component discovery

In order to define what is a viable component that should be placed in this library, there is a discovery process that needs to be followed to ensure we are only adding necessary, useful components, without creating duplicate components that solve for the same UX use case.

Process - TBD / Work in Progress

At least for now, all component requirements and ideas should be discussed with the Design team, creating Jira work items as necessary to account for design and engineering effort

Jira

TBC - Currently work is being tracked on the Allica Engineer board, but will probably move to the Design board

Workflow Guidelines

Directory structure

In order to ensure consistency across components in the library, each component, where possible, should be placed inside a new directory inside src/components, named as per the component name. The directory should have the following files added and completed in order to be treated as 'done' -

• component file (e.g. button.tsx) - the React component and any component logic
• styles file (e.g. button.styles.ts) - any relevant internal styling for the component
• theme file (e.g. button.theme.ts) - component specific theme values
• test file (e.g. button.spec.tsx) - Unit tests using jest and @testing-library/react
• storybook file (e.g. button.stories.tsx) - stories of the components, showcasing the various states and variants of a component
• index file (e.g. index.ts) - A file that represents the public API for the component, ensuring only the intended components, functions etc get exported to the consumer.

e.g.

src
    /components
        /button
            button.tsx
            button.styles.ts
            button.theme.ts
            button.spec.tsx
            button.stories.tsx
            index.ts <!-- exports Button component
        index.ts <!-- exports all components

Component structure

Without being too prescriptive, but for some consistency, loosely follow a structure as below -

(button.tsx)

import { FC, PropsWithChildren } from 'react';

export const Button: FC<PropsWithChildren> = ({ children }) => {
    const handleClick = () => {...}

    return (
        <button onClick={handleClick}>{children}</button>
    )
}

(src/components/button/index.ts)

export { Button } from './button';

(src/components/index.ts)

export * from './button';

Note - there is no benefit in using export default, as all components will need to be named in order to be exposed to the consuming application, therefore it removes the need to alias an export like -

(src/components/button/index.ts) - (not recommended)

export { default as Button } from './button';

Testing

We are currently using jest and @testing-library/react for unit testing

Build

Before your components can be consumed by an application, you need to build the library. The build process output two formats - esm ECMAScript Modules and cjs CommonJS

esm is used by your consuming React application and ran in the browser.
cjs is used by your unit tests, until jest offers first class support for esm (still experimental)

To build the library, run -

npm run build

Testing / Running the library locally

In order to test out your new component, or changes to an existing component, you should do this before publishing the library. One way to accomplish this is to use npm link

Uninstall @allica/ui-react from your application

npm un @allica/ui-react

In a terminal for this component library, build the library (if not already built), and use npm link

npm run build
npm link

In your application terminal, link the library

npm link @allica/ui-react

!! IMPORTANT !!

When you are done testing, be sure to reinstall the real library -

npm i @allica/ui-react

Git Commit / Git Push

This library is following the conventional commits standard. This library will preinstall a git commitmsg hook via husky to ensure commit names follow this standard. It is important as the automatic version bumping mechanism (commit-and-tag-version) uses the conventional commit messages to determine the next version automatically. (major, minor, patch).

If working on multiple features / components, please commit each one separately so that each commit only contains a single feature, and the commit message accurately describes that single change.

an example bugfix commit in the terminal looks like -

$ git commit -m "fix(Button): fix button click handler
>
> refs: AB-123"

producing -

fix(Button): fix button click handler

refs: AB-123

Note, please use the name of the component/feature, in this case Button, as the scope in the commit message, as this gets used in the changelog generation. For adding JIRA ticket ids, please add them to the body of the commit description as shown.

Squashing commits

Please only squash commits so that a single commit contains a single feature. It is OK to have a pull request with multiple commits, where each commit represents a single feature. This is important for accurate changelog generation.

Raise a Pull Request

Once you have committed and push your changes, please raise a pull request.

Note

• it is common for a single pull request to have multiple commits where there has been multiple component updates
• we haven't yet bumped the version of the library yet, this comes next.

Create a Release

Once all the changes have been merged into the main branch that are targeting the next release, you can now generate a new changlelog and bump the version, ready for a Release Pull Request.

In a feature branch that has the latest from master (this can be the branch from the previous step), Run -

npm run release

this will -

• bump the version in the package.json and package-lock.json according to previous commit messages
• create a new git tag based on the new version
• add commit information to the CHANGELOG.md as release notes, since the last release.

Then push your changes, making sure to also push the new tag

git push --follow-tags

Now create another pull request

Publishing

Once the Release pull request has been approved and merged to the main branch, you can now publish to Azure Artifacts (our private NPM repo)

In the branch that contains your latest changes, you can run -

npm publish (Use pipeline, instead of this command from your machine)

Note, the prepublishOnly npm script will ensure your local machine has the correct release artifact built before it runs the npm publish command

Pipeline

Getting ready