npm package: @office365rackspace/helix-ui-react
Description: Helix UI React is an implementation of the Helix UI webcomponents library for React.
Author: Michael Mangialardi
Latest version: 1.0.2-alpha.0

[![forthebadge](https://img.shields.io/badge/Made%20With-React-blue?style=for-the-badge&logo=react&labelColor=202020&color=62DAFB)](https://reactjs.org/)

# Helix UI React

<p align="center">
  <img src="https://media.github.rackspace.com/user/8179/files/eaa9a280-1c18-11ea-9030-c8bbc6454521">
</p>

Helix UI React is an implementation of the [Helix UI Webcomponents Library](https://github.com/HelixDesignSystem/helix-ui/) for React.

## Who Uses Helix UI React

* [Office 365 at Rackspace Control Panel](https://github.rackspace.com/Microsoft-Services/Office365.ControlPanel)

## How It Works

1. Helix UI React wraps Helix UI webcomponents and aims to keep an API that follows closely to the [Helix UI documentation](https://helixdesignsystem.github.io/helix-ui/components).
2. Internally, Helix UI React uses TypeScript which allows us to get the benefits of IntelliSense, as well as the ability to further reason about our code.


## Usage

1. Configure Helix UI Webcomponents:
There is a guide for [Getting Started](https://helixdesignsystem.github.io/helix-ui/guides/getting-started/). However, there's some level of work that is ambigious.

After installing `helix-ui` and `@webcomponents/webcomponentsjs`, you will need to manually add the appropriate css file and scripts to the HTML file where your React component is hosted.

Since this is not yet avaible to be done using Webpack, the files must be copied out of `node_modules` and moved to a public folder (where your HTML lives).

To do this, you can use [vendor-copy](https://www.npmjs.com/package/vendor-copy).

You can add the configuration in the `package.json` file, specifying the files you want to move out of `node_modules` and into a public folder. Here's what our configuration looks like:

```javascript
"vendorCopy": [
  {
    "from": "node_modules/@webcomponents/webcomponentsjs/custom-elements-es5-adapter.js",
    "to": "vendor/custom-elements-es5-adapter.js"
  },
  {
    "from": "node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js",
    "to": "vendor/webcomponents-loader.js"
  },
  {
    "from": "node_modules/helix-ui/dist/styles/helix-ui.min.css",
    "to": "vendor/helix-ui.min.css"
  },
  {
    "from": "node_modules/helix-ui/dist/scripts/helix-ui.browser.min.js",
    "to": "vendor/helix-ui.browser.min.js"
  }
]
```
You will likely just have to change the `to`s of this configuration to fit your needs. For example, if the folder serving your application (again, where the folder where your HTML file that hosts the React application is living) is called `public`, it would look `vendor/` would become `public/vendor/...` for every `to`.

The actually copying of these files can occur in the `postinstall` npm script also in your `package.json`:

```javascript
"postinstall": "vendor-copy"
```
In theory, these files need to be copied only when the `@webcomponents/webcomponentsjs` and `helix-ui` packages are updated (respectively). However, this script will always copy the files over after a fresh `npm install` (don't worry it doesn't take long).

Then, you would update the `head` of the HTML with the following (we included comments for clarification):

```html
<!-- DO NOT BUNDLE: HelixUI Styles -->
<link rel="stylesheet" href="/vendor/helix-ui.min.css" />
<!-- DO NOT COMPILE: Converts ES5 custom element constructor functions to ES6 classes -->
<script src="/vendor/custom-elements-es5-adapter.js"></script>
<!-- DO NOT COMPILE: Appends polyfills to <head> if needed by user's browser. -->
<script src="/vendor/webcomponents-loader.js"></script>
```

Finally, you have to add the `helix-ui.min.js` script to the `body`:

```html
<!--
    DO NOT BUNDLE: ES5-compiled assets specifically for use in the browser.
    Provides additional polyfills and automatically initializes HelixUI.
-->
<script src="/vendor/helix-ui.browser.min.js"></script>
```

You should now be set to use webcomponents and the Helix UI webcomponents in your application directly. If you are using TypeScript (as we are internally), you need to [declare each webcomponent as we have done here](https://github.rackspace.com/somi5630/helix-ui-react/blob/master/packages/helix-ui-lib/src/index.ts).

2. Install this package:

```bash
npm i @office365rackspace/helix-ui-react
```

3. Use any of our components:

```javascript
import { Alert } from '@office365rackspace/helix-ui-react';

<Alert cta="call to action" onSubmit={() => alert('submitted')} type={type}>
  Some Alert Message
</Alert>
```
We do not have documentation for the API of our components at the moment, but you can see the interfaces in our source code:

```javascript
export interface IAlertProps {
  children: React.ReactNode;
  cta: string;
  onSubmit: () => void;
  type: 'info' | 'warning' | 'error' | 'success';
}
```
[See all components](https://github.rackspace.com/somi5630/helix-ui-react/tree/master/packages/helix-ui-lib/src/components)

## Contributing
1. Install yarn
```bash
npm i -g yarn
```

2. Install packages
```bash
yarn install
```

3. Run Storybook

[Storybook](https://storybook.js.org/) is an open source tool for developing UI components in isolation for React, Vue, and Angular. In a word, it allows us to easily have a running site to demo all of our components in all other there various states.

<img width="906" alt="Screen Shot 2019-12-11 at 4 06 40 PM" src="https://media.github.rackspace.com/user/8179/files/87c40580-1c30-11ea-89d9-8b6f753e8d9e">

To run story, execute the following:

```bash
npm run story
```
The script should automatically open Storybook in your browser, but you can always navigate to http://localhost:9001/?path=/story

4. Enable TSLint plugin for your editor of choice

5. Develop a component

6. Create a story (demo) for that component in a `index.story.jsx` file adjacent to the `index.tsx` under the directory of your component (i.e. `alert`)

7. Put together a [PR](https://github.rackspace.com/somi5630/helix-ui-react/pull/14) for that component and request one of the contributers below to review

## Contributers
Mike Mangialardi ~ mike.mangialardi@rackspace.com

Elena Jdanova ~ elena.jdanova@rackspace.com

Somit Kumar ~ somit.kumar@rackspace.com