Ninja Power Manifesto

    bkn-ui
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0-beta.44 • Public • Published

    bkn-ui

    It's a set of React components based on Bootstrap 4 and Google's Material Design, using Reactstrap and react-mdc-web libraries respectively.

    It also includes custom styles using SASS.

    Table of Contents

    Installation

    npm install -S -E bkn-ui

    Or using yarn.

    yarn add -E bkn-ui

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

    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 section in their website for more details.

    Styles

    Material Design

    bkn-ui was designed with the Roboto font and Material Design Icons in mind. So be sure to include them in your HTML file, in <head> tag:

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

    @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 and 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:

    Basic elements

    Let's start by <Layout> component.

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

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

    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.

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

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

    // LayoutExample.tsx
     
    import './LayoutExample.scss';

    Note: see Theming 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.

    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.

    // LayoutExample.scss
     
    // code omitted for brevity
     
    @import "node_modules/bkn-ui/scss/components/welcome";

    That's it! Now go see Components section.

    API Reference

    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.

    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.

    13. Be happy. =]

    Install

    npm i bkn-ui

    DownloadsWeekly Downloads

    3

    Version

    2.0.0-beta.44

    License

    MIT

    Unpacked Size

    281 kB

    Total Files

    302

    Last publish

    Collaborators

    • jpbeakyn
    • nelsoneldoro
    • juanpujol
    • abraaoalves
    • falcaoaugustos
    • brunolazarus
    • hileomsi
    • murilopaixao