# Comparison Components

[![Owners](https://img.shields.io/badge/Owner-Comparison%20Team-blue.svg?logo=slack&longCache=true&style=for-the-badge)](https://transferwise.slack.com/app_redirect?channel=comparison)


React components for Comparison.

* **Comparison Table:**<br>
Shows a comparison table of providers given a route and amount without showing any inputs.
* **Comparison:**<br>
Shows the comparison table with inputs provided for the route and amount.

The comparison components are currently used in three places:
- Homepage (as a React component)
- Transfer Flow (used as above)
- Comparison Pages (React component injected using the Universal Loader / Widget)

## Usage
### Web Widget / Universal Loader™

The easiest way to use `Comparison Components` within an application is by using the **Web Widget / Universal Loader™**. 
Please see the docs [here](https://github.com/transferwise/widgets/blob/master/README.md) for more details.

### NPM module

Alternatively, you can install this React widget as an npm module running:

```
npm install @transferwise/comparison-components
```

## Development
Written using React and built using Webpack.

Requires:
* NPM >= 5.10

To see and develop with the components locally run `npm run storybook`.
If you would like to run with some of the APIs stubbed, run with `npm run-script start-stubbed-api`

The demo page contains the two different components **Comparison** and **Table**, one underneath the other.

### Example:

```javascript
// example/index.js

import React from 'react';
import ReactDOM from 'react-dom';
import { Comparison } from '../src/';

const Root = () => {
  return (
    <div>
      <Comparison
        sourceCurrency="EUR"  // required
        targetCurrency="GBP"  // required
        sendAmount={5000} // required
        source="EUR"  // deprecated
        target="GBP"  // deprecated
        amount={5000} // deprecated
        providers={['transferwise', 'deutsche-bank', 'commerzbank']}
        sourceCountry="de"
        providerCountry="de"
        maxVisibleProviders={5}
        expandDisclaimer
        affiliateLink="http://transferwise.evyy.net/c/111111/22222/333"
      />
    </div>
  );
};

ReactDOM.render(<Root />, document.getElementById('root'));
```

- `lang`: `string` ISO 639-1. Default `en`
- `sourceCountry`: `string`  ISO 3166-1 alpha-2. Filter results by source country. i.e the origin country from where a user may want to send money from.
- `providerCountry`: `string`   ISO 3166-1 alpha-2. Filter by provider country. i.e the country which the provider belongs to (e.g Natwest - GB, ANZ - AU). This property is also useful for only showing national banks, rather than "global" providers (like Western Union, Moneygram etc)
- `maxVisibleProviders`: `number` by default shows 3 providers and the rest are hidden under [Show more providers]() link.
- `expandDisclaimer`: `boolean` will render the table with the disclaimer already opened and scrolls the element into the visible area of the browser window
- `affiliateLink`: `string` Affiliate tracking link.
- `trackEvent`: `func(eventName, trackingAttributes)` is called on user interaction with the table and other table based events (for example, user changes the send amount or views at least 50% of the table).
- `trackLeavePageEvent`: `func(eventName, trackingAttributes, callback)` is called on page exit events (for example, on click to CTA).

All attributes are valid for `<Comparison /> <ComparisonTable />` components

### Tasks

```
npm run storybook                - runs storybook on 9001
npm run-script start-stubbed-api - runs a hot reloading server on port 4040 using stubbed
npm test                         - runs `jest` for Comparison Table
npm run build-web                - compiles the standalone comparison widget
npm run build-npm                - compiles UMD and ES bundles for distribution on NPM 
```

Do not forget to update the version number in `package.json` when committing changes.

### Bundle analysis

The project has `webpack-bundle-analyzer` and `rollup-plugin-visualizer` set up to inspect the compiled bundle files. They can be accessed by setting the environment variable `ANALYZE` and running the build command as normal.

```bash
$ ANALYZE=true npm run build-web
# Note this will open several browser tabs, one for each bundle
$ ANALYZE=true npm run build-npm
```

![bundle analysis chart](./docs/readme-bundle-analysis.png)

### Creating a new component

To create a new Comparison Component that can be imported by others, the following changes are required:

- Create your component as the default export of `~/src/new-component`
- Create a `.stories.js` file in the folder to show the component in Storybook
- `~/src/index.js`: make the component a named export
- Translations:
  - `~/crowdin.yaml`: add an entry for the new component
- `~/rollup.config.js`: add a new `input`
- `~/webpack.config.npm.umd.js`: add a new `componentEntry()`
- `~/CODEOWNERS.md`: make comparison team and your team owners of the `~/src/new-component` folder
- Follow the normal versioning process, outlined in the PR template

## Translations
[How translations working in comparison components](./src/localisation/I18n.md)
