Festicket React-UI-Components

react-ui-components is a collection of reusable components that are not specific to any particular Festicket UI. See the master branch Storybook Demo on Netlify. (This is automatically deployed with a GitHub webhook).

If you are creating a component that would be of no use to any website other than Festicket, it probably belongs in react-app-components instead.

Usage

To reduce bundle size in consuming projects, import components via their full path in the dist folder. For example:

import PrimaryButton from '@festicket/react-ui-components/dist/components/buttons/PrimaryButton';

Don't import components the following way as this will increase bundle size since this type of import causes all of react-ui-components to be imported at this point.

import { PrimaryButton } from '@festicket/react-ui-components'; // Don't do this

SVGs

React SVG Components can be found in dist/components/svgs/generated/.

In order to achieve a consistent style, only use these SVG components with the options provided. Never apply custom styling to them. The possible options for each SVG component can be seen in the Storybook for this project.

Contributing

Precommit Checks

We use Husky and lint-staged to run precommit checks on files staged for commit. This includes es-lint and flow validation.

Making Commits

Commit messages are generated using Commitizen and then verified using Commitlint.

It is important that all commits have the same format because these commits are then read by semantic-release and are used to decide the version number and release notes of any new release.

The format that we use is a customized version of (Conventional Commits)[https://www.conventionalcommits.org/] and uses the following format:

<type>: <description>

where type can be any of the following:

| Type | Description | | -------- | ------------------------------------------------ | | feat | A new feature | | fix | A bug fix | | docs | Documentation only changes | | refactor | Changes that neither fix a bug nor add a feature | | perf | Changes that improve performance | | test | Adding missing tests | | chore | Changes to the build process or auxiliary tools | | revert | Revert to a commit | | WIP | Work in progress |

When running git commit commitizen will be run in place of your default text editor and will ask you a number of questions in order to generate a valid commit message.

NOTE: you can run git commit --no-edit instead to skip the final step where the commit message you have created in commitizen is opened in your text editor.

The most important types are feat and fix, they are the only ones that will trigger a release and they are used to decide a version number and generate release notes. You will also have the opportunity with feat or fix commits to say whether your commit is a breaking change or not. A breaking change is any change that can cause dependent packages to break if they upgrade.

The basic format of a (semantic version)[https://semver.org/] number is MAJOR.MINOR.PATCH. When a release is done, the commit with the highest importance takes precedence when deciding the version number. So if a release solely consists of fixes, only the patch version will be bumped. If a feature is included then the minor version is bumped instead, and if any of the feat or fix commits include a breaking change then the major is bumped.

Deploy Previews

Each pull request on GitHub has its Storybook build deployed to a Deploy Preview url on Netlify. This will get automatically linked to in the GitHub pull request, and on the Jira ticket.

Visual Regression Checks

We use Percy for visual testing of components. Before a branch can be merged into master, the implementer must check the Percy link at the bottom of the PR conversation tab on GitHub, and approve any visual diffs between the current branch and master. If adding a new component there will always be visual diffs, but changing components can also cause unexpected changes to other components that rely on the changed one.

Triggering a New Release

We use Semantic Release to automate releases of this project. Semantic Release will trigger new releases based on commit message formats that it recognises.

A new release will happen when a branch is merged into master, provided at least one of the following conditions is met:

• A commit message with type fix will trigger a patch release (1.0.0 -> 1.0.1).
  • eg fix: stop component breaking
• A commit message with type feat will trigger a feature release (1.0.0 -> 1.1.0).
  • eg feat: add Header component
• A commit message with BREAKING CHANGE in the message body will trigger a breaking release (1.0.0 -> 2.0.0).
  • eg

docs: this part is irrelevant for triggering a breaking release

The import part is having BREAKING CHANGE in the body.

A new release will NOT happen if only commits of type refactor are included in the pull request.

If a branch contains commit messages that would trigger multiple release types, the most 'breaking' release type will be applied.

After a branch is merged into master, master will be rebuilt on Semaphore.

If the build of master is successful on Semaphore and contains a release commit, a server deploy will take place on Semaphore that will publish the latest version to NPM with the correct version.

Adding new SVGs

SVG Components are dynamically generated in the repo. Please read all the following information before attempting to add a new SVG to the project.

Important

• After images are generated, update transformer.js file, in order for images to be imported using @festicket/react-ui-componens path alias
• When getting new SVGs from the design team, make sure they are exported from Adobe Illustrator with the CSS setting CSS attributes and NOT CSS element. There is a bug with svgr/svgo that means some colours in the SVG may get lost when the converted SVG uses a CSS element.
• The source SVG files should specify a height and width attribute on the SVG element in the source code. You will need to manually add this to the source SVG if it doesn't have them. If they don't have this, they will end up with width: 100% in IE11. // http://nicolasgallagher.com/canvas-fix-svg-scaling-in-internet-explorer/

New SVGs are added by placing an SVG source file inside a folder in /svgs/. Each type of folder generates SVGs with different variation - based on the template that is configured for that folder in scripts/svgr.sh

Running npm run svgr will take all the SVGs from the source svg folders in /svgs and use svgr to generate React components from them. These will be placed in src/components/svgs/generated/.

If you make changes to an existing SVG, you must make the changes to the source SVG, as any changes to the files in src/components/svgs/generated/ will be overwritten the next time npm run svgr is run.

Animations

We use framer-motion (docs) for animations in ui-components. Have a good look around the docs before you read any more.

Animation timings

Where possible, trust the library's in-built timings. They are tried and tested and allow for lightning-quick setup of animations. If design decide that we really do need something custom, take a look at the transitions docs.