npm package: @outfront/ui-legacy
Description: A set of React components from Beakyn Company.
Author: Beakyn
Latest version: 2.0.0-beta.46

# bkn-ui

It's a set of [React](http://facebook.github.io/react/) components based on [Bootstrap 4](https://v4-alpha.getbootstrap.com/) and [Google's Material Design](https://material.io/), using [Reactstrap](https://github.com/reactstrap/reactstrap) and [react-mdc-web](https://github.com/kradio3/react-mdc-web) libraries respectively.

It also includes custom styles using [SASS](http://sass-lang.com/).

## Table of Contents

- [Installation](#installation)
- [Styles](#styles)
- [Getting Started](#getting-started)
- [API Reference](#api-reference)
- [Contributing](#contributing)

## Installation

```sh
npm install -S -E bkn-ui
```

Or using _yarn_.

```sh
yarn add -E bkn-ui
```

It has some peer dependencies, so if you not installed them, you have to.

```sh
yarn add -E bootstrap@4.0.0-alpha.6 react react-mdc-web reactstrap
```

**Note:** _reactstrap has some peer dependencies as well. See more details in_ [Dependencies](https://github.com/reactstrap/reactstrap#dependencies) _section in their website for more details._

## Styles

### Material Design

**bkn-ui** was designed with the
[Roboto](http://www.google.com/fonts/specimen/Roboto) font and
[Material Design Icons](https://material.io/icons/) in mind.
So be sure to include them in your HTML file, in `<head>` tag:

```html
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500" />
<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />
```

### Bootstrap

All Bootstrap styles are located in SASS files. For example, if you want to import styles for `<Layout>` component:

```sass
@import "node_modules/bkn-ui/scss/theme/base";
@import "node_modules/bkn-ui/scss/components/layout";
```

For more details on how to import the correct styles for any components, see [Theming](https://github.com/Beakyn/bkn-ui/wiki/3.-Theming) and [Components](https://github.com/Beakyn/bkn-ui/wiki/1.-Components) wiki pages.

## Getting Started

We are about to see how to implement an application layout that will be composed by a _Drawer_, a _Main Nav_, a _User dropdown menu_ and an _Welcome_ message.

This is the end result:

<p align="center"><img src="/screenshots/bkn-ui-getting-started-demo.gif"></p>

### Basic elements

Let's start by `<Layout>` component.

```jsx
// LayoutExample.tsx

import * as React from 'react';
import {SFC} from 'react';
import {Layout} from 'bkn-ui';

const LayoutExample: SFC<{}> = () => (
  <Layout
    drawerHeaderTitle="App Name"
    mainNavTitle="App Name"
  />   
);

LayoutExample.displayName = 'LayoutExample';
```

This will render a `<MainNav>` component on top (like an application bar) and a `<Drawer>` on the left. A button that toggles the `<Drawer>` will be rendered by default on `<MainNav>` in left side and on top of `<Drawer>` as well.

On `<Layout>` we added two props. `drawerHeaderTitle` prop will render _App Name_ text on top of `<Drawer>`. `mainNavTitle` prop will render same text in left side of `<MainNav>`.

### Drawer content

Our `<Drawer>` doesn't have any content besides a title. Let's add some content.

```jsx
import {Nav, NavItem, NavLink} from 'reactstrap';

const drawerContent = (
  <Nav vertical>
    <NavItem>
      <NavLink
        className="toggle-drawer active"
        href="#"
      >
        Link 1
      </NavLink>
    </NavItem>

    <NavItem>
      <NavLink
        className="toggle-drawer"
        href="#"
      >
        Link 2
      </NavLink>
    </NavItem>
  </Nav>
);

// code omitted for brevity

const LayoutExample: SFC<{}> = () => (
  <Layout
    drawerContent={drawerContent}
    drawerHeaderTitle="App Name"
    mainNavTitle="App Name"
  />   
);
```

As you can see, there's an `import` statement from _reactstrap_, instead of _bkn-ui_. This is because _reactstrap_ is a peer dependency in _bkn-ui_ and a lot of _reactstrap_ components wasn't cutomized by _bkn-ui_. See [_reactstrap_ components](https://reactstrap.github.io/components/alerts/) for more details.

Also a `drawerContent` prop was added to `<Layout>`, holding the drawer content.

### User menu

Now, let's add a user menu in the right side of `<MainNav>`.

```jsx
import {UserMenu, UserMenuImage} from 'bkn-ui';

const userMenuImage = (
  <UserMenuImage
    imageUrl="https://s.gravatar.com/avatar/00000000000000000000000000000000?s=480&r=pg"
    userName="John Doe"
  />
);

const userMenu = (
  <UserMenu userImage={userMenuImage}>
    <div>
      <div className="d-block">
        <strong>John Doe</strong>
      </div>
      <div className="d-block">johndoe@beakyn.com</div>
      <div className="d-block">
        <a className="dropdown-menu-link" href="#">Logout</a>
      </div>
      <div className="dropdown-divider" />
      <div className="d-block">
        <small>v1.0.0</small>
      </div>
    </div>
  </UserMenu>
);

// code omitted for brevity

const LayoutExample: SFC<{}> = () => (
  <Layout
    drawerContent={drawerContent}
    drawerHeaderTitle="App Name"
    mainNavElementRight={userMenu}
    mainNavTitle="App Name"
  />   
);
```

`<UserMenu>` renders a dropdown menu. We just add some content to it, as well as an image using `<UserMenuImage>` component.

Then we passed this to `<Layout>` via `mainNavElementRight` prop.

### Welcome message

We don't have anything in our layout body. Let's add an welcome message using `<Welcome>` component.

```jsx
import {Welcome} from 'bkn-ui';

// code omitted for brevity

const LayoutExample: SFC<{}> = () => (
  <Layout
    drawerContent={drawerContent}
    drawerHeaderTitle="App Name"
    mainNavElementRight={userMenu}
    mainNavTitle="App Name"
  >   
    <Welcome userName="John Doe">
      This is the Welcome component.
    </Welcome>
  </Layout>
);
```

So, we just include `<Welcome>` component as a child of `<Layout>`. Then we passed some content to it.

### Beautifying

Okay, let's beautify our UI.

First, we create a `LayoutExample.scss` file and import the base theme and styles for the components we are using (_layout_ and _welcome_).

```sass
// LayoutExample.scss

@import "node_modules/bkn-ui/scss/theme/base";
@import "node_modules/bkn-ui/scss/components/layout";
@import "node_modules/bkn-ui/scss/components/welcome";
```

Then we simply import that style file in our typescript file.

```jsx
// LayoutExample.tsx

import './LayoutExample.scss';
```

**Note:** _see_ [Theming](#api-reference) _section for more details._

Ok, but if you see the result, you'll see that welcome message has not a good spacing with main nav. Let's fix that in next section.

### Layout body

To fix spacing between `<MainNav>` and `<Welcome>` we going to use the `<Page>` and `<PageBody>` components. They work as a `<Layout>` body adding spacing and a custom scrollbar to the content.

```jsx
import {Page, PageBody} from 'bkn-ui';

// code omitted for brevity

const LayoutExample: SFC<Props> = ({appName}) => (
  <Layout
    drawerContent={drawerContent}
    drawerHeaderTitle={appName}
    mainNavElementRight={userMenu}
    mainNavTitle={appName}
  >   
    <Page>
      <PageBody>
        <Welcome userName="John Doe">
          This is the Welcome component.
        </Welcome>
      </PageBody>
    </Page>
  </Layout>
);
```

Also we need to add styles for `<Welcome>` in our SASS file.

```sass
// LayoutExample.scss

// code omitted for brevity

@import "node_modules/bkn-ui/scss/components/welcome";
```

That's it! Now go see [Components](#api-reference) section.

## API Reference

- [Components](https://github.com/Beakyn/bkn-ui/wiki/1.-Components)
- [Models](https://github.com/Beakyn/bkn-ui/wiki/2.-Models)
- [Theming](https://github.com/Beakyn/bkn-ui/wiki/3.-Theming)

## Contributing

1. Create an issue describing clearly the new feature or problem.
2. Create a branch with issue name.
3. Improve/Fix it.
4. Generate bundle and types by running:

    `npm run build`

5. Bump version in package.json based on [SemVer](http://semver.org/).
6. Create a PR and inform what issue is closed. For example: 

    `Closes #1`

7. Approve and merge PR.
8. Delete branch.
9. Publish to npm:

    `npm publish`

10. Create a tag for current version. For example:

    `git tag 1.0.0`

11. Push tag to Github.

    `git push --tags`

12. Write change log in tag body based on merged PRs. Example [here](https://github.com/Beakyn/bkn-form/releases/tag/1.1.4).
13. Be happy. =]