Using the UI in the Main ReadMe App
===

It's painful to implement React components a la cart across an old Angular app. To simplify this, we (by which I one hundred percent mean Sean) developed [the slick new **`ui()`** directive](https://github.com/readmeio/readme/blob/master/public/js/directives/ui.js). 

### Linked Local Development

```bash
cd ~/Repos/readme
npm link ~/Repos/ui               # Link your local UI repo here
cd ~/Repos/readme/packages/shared # and in any subpackages!
npm link ~/Repos/ui

cd ~/Repos/ui
npm run linkup -- "~/Repos/readme" # quick util to link some external deps up to their local readme counterparts!
npm run watch

cd ~/Repos/readme
npm run start
```

Afterwards, you can run `npm ls @readme/ui` in your ReadMe repo to check that UI and ReadMe linked properly. You should expect to see UNMET DEPENDENCY both at the readme and @readme/shared levels (see example below).

```bash
readme.io@3.11.2 ~/Repos/readme
├─┬ @readme/shared@0.0.0 -> ~/Repos/readme/packages/shared
│ └── UNMET DEPENDENCY @readme/ui@1.7.3 
└── UNMET DEPENDENCY @readme/ui@1.7.0 
npm ERR! missing: @readme/ui@1.7.0, required by readme.io@3.11.2
npm ERR! missing: @readme/ui@1.7.3, required by @readme/shared@0.0.0
```

> **Note**: after linking the UI, the ReadMe build may hang on initial compile. To "fix" this, just comment out [the stylesheet import, **here**](https://github.com/readmeio/readme/blob/master/public/js/directives/ui.js#L6), and restart ReadMe. Allow the app to compile fully before uncommenting the SCSS import... Everything should work just fine now!

### Using the Directive

Using a UI elements is as simple as setting the directive's `[is]` attribute:

```pug
ui(is="Button")
```

#### Props

You can pass data to the React component using the `[props]` attribute, including Angular `$scope` variables and complex JSON:

```pug
ui(is="Button" props=[
  {text: "Hello World"},
  {scopeDataVar: scopeDataVar}
])
```

> We're still mulling over the best syntax for passing props from the directive to React! Have opinions? [Get involved](https://github.com/readmeio/readme/pull/2253#discussion_r378449420).

In certain templates you may have to `JSON.stringify` the array before passing it to the props attribute. (This happens because we're using Angular *and* Express to render templates, but they each parse scope data slightly differently!)

#### Callbacks

Using the directives `[callback]` attribute in concert with our `nativeDispatch.js` utility method allows you to bubble an event up from a React component in to a scoped Angular method:

```pug
ui(is="MetricsDateRange" callback="changeTimeRange")
```

Internally, the `MetricsDateRange` uses the native dispatcher to trigger a custom `react` event. The directive then listens for this event and executes the appropriate callback method from the parent scope.