README

Helix UI React

Helix UI React is an implementation of the Helix UI Webcomponents Library for React.

Who Uses Helix UI React

Office 365 at Rackspace Control Panel

How It Works

Helix UI React wraps Helix UI webcomponents and aims to keep an API that follows closely to the Helix UI documentation.
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

Configure Helix UI Webcomponents: There is a guide for 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.

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:

"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 tos 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:

"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):

<!-- 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:

<!--
    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.

Install this package:

npm i @office365rackspace/helix-ui-react

Use any of our components:

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:

export interface IAlertProps {
  children: React.ReactNode;
  cta: string;
  onSubmit: () => void;
  type: 'info' | 'warning' | 'error' | 'success';
}

See all components

Contributing

Install yarn

npm i -g yarn

Install packages

yarn install

Run Storybook

Storybook 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.

To run story, execute the following:

npm run story

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

Enable TSLint plugin for your editor of choice
Develop a component
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)
Put together a PR 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

Usage no npm install needed!