README.md

A set of opinionated web-components for building efficient and scalable financial applications

Packages

ACTIONS

Name	Package	Version	Links
Button	@finastra/button
Button Toggle Group	@finastra/button-toggle-group
Icon Button	@finastra/icon-button
FAB	@finastra/fab
Menu Trigger	@finastra/menu-trigger

FORMS

Name	Package	Version	Links
Autocomplete	@finastra/autocomplete
Checkbox	@finastra/checkbox
Chip	@finastra/chip
Circular Progress	@finastra/circular-progress
Divider	@finastra/divider
Formfield	@finastra/formfield
Launchpad	@finastra/launchpad
Linear Progress	@finastra/linear-progress
Logo	@finastra/logo
Menu Trigger	@finastra/menu-trigger
Textarea	@finastra/textarea
Radio	@finastra/radio
Search Input	@finastra/search-input
Select	@finastra/select
Slider	@finastra/slider
Stepper	@finastra/stepper
Switch	@finastra/switch
Textarea	@finastra/textarea
TextField	@finastra/textfield
Wizard	@finastra/wizard

GRAPHIC ELEMENTS

Name	Package	Version	Links
Avatar	@finastra/avatar
Badge	@finastra/badge
Icon	@finastra/icon
Logo	@finastra/logo

NAVIGATION

| Name | Package | Version | Links | | ------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | --- | | App Bar | @finastra/app-bar | | | | Bottom App Bar | @finastra/bottom-app-bar | N/A | TBD | | Breadcrumb | @finastra/breadcrumb | | | | Global Search | @finastra/global-search | | | | | Guided Tour | @finastra/guided-tour | | | | | Icon bar | @finastra/icon-bar | | | | Launchpad | @finastra/launchpad | | | | Sidenav | @finastra/sidenav | | | | | Tabs | @finastra/tabs | | | | User Profile | @finastra/user-profile | | |

DATA DISPLAY

Name	Package	Version	Links
Account Card	@finastra/account-card
App Card	@finastra/app-card
Brand Card	@finastra/brand-card
Card	@finastra/card
Charts	@finastra/charts
Chip	@finastra/chip
Circular Progress	@finastra/circular-progress
Data Table	@finastra/data-table
Divider	@finastra/divider
Expansion Panel	@finastra/expansion-panel
Linear Progress	@finastra/linear-progress
List	@finastra/list

POPOVER

Name	Package	Version	Links
Alert Message	@finastra/alert-message
Banner	@finastra/banner	N/A	TBD
Dialog	@finastra/dialog

Developer guide

Getting your environment set up

1. Make sure you have node@16.x.x and npm@8.x.x installed.
2. Fork Finastra Design System repo on Github.
3. Clone your fork to your machine with git clone
4. From the root of the project, run npm install to install the dependencies.

Alternatively, you can use Gitpod to code in your browser !

Web component development

Build

First run the following commands to build all components

npm run build:storybook

Note that you need to build the storybook only the first time you clone the repository or if you have modified any file inside the .storybook folder.

Local developement

• Local Dev Server (it also start the watch mode)

npm run wc:serve

• Storybook (for the documentation and demo)

npm run storybook:watch

You can also see the storybook in the browser ➡️ Go to Storybook

For local developement, we recommend using build in watch mode:

• Watch mode

npm run watch

Running tests

npm run test

Or in watch mode

npm run test:watch

in watch mode you can focus on a specific test by pressing f

Generating new web components

npm run generate:component MY_COMPONENT_NAME

To see a demo of the generated web component, run the commands mentioned in the #Web Component Development section.

💡 Compliance check for new web-component

We recommand using the generator to start a new web-component. To be compliant for contribution your web-component must have story and a test file.

Documenting your Web Component

The only source of truth of your wc documentation should be JSDoc alongside your component's code.

This JSDoc can be extracted (via wca), and injected in both Storybook and your README, so that you don't have to write the same thing 3 times.

Documentation in README.md

During release, JSDoc is extracted for every web component, and injected into each README.md file of said web component in a neat table format. You can inject the content to test how it will render prior to pushing your content, via npm run wca:md.

The script will look for the following delimiter to inject the content of documentation between them:

<!-- DOC -->
<!-- /DOC -->

When working with multiple components, by default it will display the first found component inside the default delimiter. You can specify which component to output where by passing the tagName of your component as a parameter inside the delimiters:

<!-- DOC:fds-special-component -->
<!-- /DOC:fds-special-component -->

Some doc that won't get overriden

<!-- DOC:fds-special-component-2 -->
<!-- /DOC:fds-special-component-2 -->

Documentation in Storybook

While working with Storybook, this same JSDoc can be extracted and injected in storybook in order to facilitate writing stories, and avoiding duplication of content.

npm run wca is launched prior to executing npm run wc:storybook and will extract JSDoc in a JSON format, and transform it to storybook compatible exports. This extract will by default be created in your component's stories folder, under {name}.json; name being the name of your web component.

In your storybook story, you can import argTypes (props), cssprops (css custom properties), and actions (events) and provide them to your story config.

Example:

const README = require('../README.md');
import { AppBar } from '@finastra/app-bar';
import { Meta, Story } from '@storybook/web-components';
import { actions, argTypes, cssprops } from './sb-generated/fds-app-bar.json';
import { allSanitizers } from '../../../../scripts/markdown-sanitizers';

export default {
  title: 'NAVIGATION/App Bar',
  component: 'fds-app-bar',
  argTypes,
  args: {
    appName: 'Finastra'
  },
  parameters: {
    actions,
    docs: {
      description: { component: allSanitizers(README) }
    },
    cssprops
  }
} as Meta;

(this is a simplified example of a story, keep the content that was generated when using the wc generator)

If you're adding or modifying your JSDoc while storybook watcher is running, you either have to stop it and run it again, or regenerate extract of JSDoc via npm run wca in a separate terminal (Storybook watcher will see the changes and relaunch)

Adding local dependencies

Whenever you need to use a component inside another component, you'll need to add it as a dependency in its package.json file.

To accomplish this easily, we've added an add script in the root package.json.
It can be used like following:

npm run add -- submodule submoduleToAdd

Example

Say we want to use the @finastra/avatar component inside the @finastra/user-profile component.
We'd be running:

npm run add -- packages/fds-components-web/user-profile ./packages/fds-components-web/avatar

Version of the package will be automatically updated during release.

Use Web Components in React Application

If you already have an existing project, feel free to skip directly to the next step. Otherwise, run this command to get started with React:

npx create-react-app my-app

Install and configure polyfill

The Web Components polyfills are a suite of JavaScript libraries that implement Web Components APIs for browsers that don't have built-in support.

npm install --save @webcomponents/webcomponentsjs vendor-copy

On package.json add the following script:

"postinstall": "vendor-copy"

and the configuration to copy the required js files to public folder:

"vendorCopy": [
	{
		"from": "node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js",
		"to": "public/vendor/custom-elements-es5-adapter.js"
	},
	{
		"from": "node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js",
		"to": "public/vendor/webcomponents-bundle.js"
	}
]

After this step, the package.json should contain:

"scripts": {
	"start": "react-scripts start",
	"build": "react-scripts build",
	"test": "react-scripts test",
	"eject": "react-scripts eject",
	"postinstall": "vendor-copy"
},
"vendorCopy": [
	{
		"from": "node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js",
		"to": "public/vendor/custom-elements-es5-adapter.js"
	},
	{
		"from": "node_modules/@webcomponents/webcomponentsjs/webcomponents-bundle.js",
		"to": "public/vendor/webcomponents-bundle.js"
	}
]

On index.html, add the following scripts:

<script src="%PUBLIC_URL%/vendor/webcomponents-bundle.js"></script>
<script>
  if (!window.customElements) {
    document.write('<!--');
  }
</script>
<script src="%PUBLIC_URL%/vendor/custom-elements-es5-adapter.js"></script>
<!-- DO NOT REMOVE THIS COMMENT, WE NEED ITS CLOSING MARKER -->

Configuration for property 'web-component-name' does not exist on type 'JSX.IntrinsicElements'

In case of a React application that uses Typescript, there's a high chance to encounter the error related to JSX.IntrinsicElements, as React only knows about standard HTML Elements. One of the solutions is to declare the custom web-component as part of the JSX.IntrinsicElements like this:

declare global {
  namespace JSX {
    interface IntrinsicElements {
      'web-component-name': any;
    }
  }
}

Congrats! You're ready to integrate your first Web Component! 🎉