emerald-ui

Emerald React UI Framework

Usage no npm install needed!

<script type="module">
  import emeraldUi from 'https://cdn.skypack.dev/emerald-ui';
</script>

README

emerald-ui

coverage build status npm version downloads npm peer dependency version

collaborators license storybook

emerald-ui is a component library that works with React and will help you build web pages faster more efficiently. It follows the Emerald Visual Language but can be adjusted with your own theme.

                    .------------------------.
                    |    Thanks for using    |
     _         _    |       EMERALD UI       |
^~^~/o\_______/ \   /------------------------'
         _______/  /
        |_____
__  __________\
  | |_
  |___\

Check out live examples in Storybook or go to the docs

Installation

Notes:

  1. Emerald UI has one peer dependency: react. You must have it installed in order for Emerald-UI to work completely.

  2. Material Icons are used by components like Icon. You must import them, e.g. in your head tag: <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">

Run npm i emerald-ui

To import the styles to your app:

import 'emerald-ui/lib/styles.css';

Append tm, ceb or ec to apply the respective theme:

import 'emerald-ui/lib/styles-tm.css';

Note: By importing styles.css the ec theme will be applied.

To import components with a single import:

import { ComponentName1, ComponentName2 } from 'emerald-ui';

To import individual components:

import ComponentName from 'emerald-ui/lib/ComponentName';

For more help on how to use the components you can go to the docs

For developers and collaborators

Installation

After cloning the repo, run npm i to install all the dependencies.

Note: In order to test the StripeForm component you need to install ngrok and add a tunnel to enable https:

Go to where the ngrok executable is and type

./ngrok http 6006

Now go to the URL that appears in the second Forwarding line.

Usage tips

For testing the components visually we use Storybook. There you can see the components in action. For the optimal development performance we recommend running npm start in a Terminal tab and npm t in another. This way we activate the storybook server and the tests runner, so when a change is made you can get Storybook reloaded and see in real time whether the tests are green.

  • npm start will run Storybook.
  • npm t will run the tests with a watch and coverage features. The coverage results can be seen directly in the console or in an HTML file that gets generated.
  • npm run build will build the JS and CSS files, run the linter and will copy the svg and images to the lib folder. It will also compile the code so it can be used in a browser via the CDN.

Visual regression testing

To do visual regression testing we're using Loki. For the moment it only supports running commands with yarn so make sure you have yarn installed on your machine. Also, to speed up the diffing process we're using GraphicsMagick which you must install as well.

The workflow is the following:

  1. Start the Storybook server by running npm start.
  2. Run npm run visual-tests:update to create or update your set of references. This command will take screenshots of each story and save them in a folder titled references in the .loki folder.
  3. Do some changes to your components.
  4. Test changes against references by running npm run visual-tests:test. This command will take new screenshots and save the ones with differences in the difference folder.
  5. Review the screenshots in the difference folder.
  6. If the differences in styles were the ones you expected, run npm run visual-tests:approve. If not, go back to step 3.

Architecture

Collaboration

Be sure to run npm run build and npm t to check that everything is green, which is that no tests are broken as well as the linter, before commiting and pushing changes to master. Under no circumstances should a broken build exist in the repo.

Storybook is a crucial part of Emerald-UI since it allows us to make sure that what we did is working as expected and it serves as a demo for our users. Because of this, every pull request that adds a new feature to Emerald-UI must contain the respective story in Storybook.

Apart from the story, the pull request must include the tests and the test coverage must be the same as it was before the changes were applied.

Roadmap

This is the development roadmap for Emerald-UI. We hope you walk with us down that road and help us make Emerald-UI the best it cab be!

  • Emerald-UI is the components library you know and love.
  • Project Helium is the complete removal of React Bootstrap and Bootstrap as dependencies.
  • Conquest is the upgrade of all the teams in CL to the latest version of Emerald-UI.
  • React Hooks is the implementation of React Hooks in all the components. This helps in reducing complexity and file sizes.
  • Open Source is the open sourcing of Emerald-UI so it can be used and developed by everyone.
  • Web components is the implementation of Custom Elements in all components so they can be used with any framework or no framework at all