@asphalt-react/appbar/README.md

Appbar

# Appbar

![npm](https://img.shields.io/npm/dt/@asphalt-react/appbar?style=flat-square)
[![npm version](https://badge.fury.io/js/@asphalt-react%2Fappbar.svg)](https://badge.fury.io/js/@asphalt-react%2Fappbar)

Appbar component is the main navigation bar for the whole application. Use this component at the root of your application as the top navigation bar. It contains a list of links that can either take the user to another page or to another section on the same page. Appbar is responsive and adapts to small, medium & large screens. You can also create a custom Appbar through a family of unit components exported by Appbar.

## Usage

```jsx
import { Appbar, Nav, NavItem, NavLink } from "@asphalt-react/appbar"

function App () {

  return (
    <Appbar>
      <Nav>
        <NavItem>
          <NavLink asProps={{ href: "/" }}>Home</NavLink>
        </NavItem>
        <NavItem>
          <NavLink asProps={{ href: "/Dashboard" }}>Dashboard</NavLink>
        </NavItem>
      </Nav>
    </Appbar>
  );
}

export default App;
```

## Anatomy

Appbar has 3 sections:

1. **Head**: Add items in the head section such as Logo using the `head` prop.
2. **Body**: Contains the list of items for navigation. This is the children.
3. **Tail**: Add items in the tail section such as user Avatar or logout button using the `tail` prop.

The styles required for the Appbar to stick to the top of the screen needs to be added while implementation.

## Navigation items

Appbar exports a family of unit components to create the nav items:

1. Nav
2. NavItem
3. NavLink
4. NavItemCaption
5. NavItemIcon
6. NavItemAction

Using these components, you can compose a variety of nav items.

## Screen size adaptability

Appbar adapts to smaller screens (below 600px). The Appbar renders at the top of its container with the head and tail section visible. The body section is hidden under a hamburger button that appears in the head section.

Activating the hamburger button shows the hidden sections in a container (or drawer) that covers the complete screen. The hamburger button is replaced by a cross button to close the drawer. Appbar also exposes a `close()` function that to close the drawer. It can be useful if you want to close the drawer on selecting a nav item. For example:

```jsx
import { Appbar, Nav, NavItem, NavLink } from "@asphalt-react/appbar"

function App () {
  const close = () => Appbar.close

  return (
    <Appbar>
      <Nav>
        <NavItem>
          <NavLink onClick={close} asProps={{ href: "example.com" }}>Dashboard</NavLink>
        </NavItem>
      </Nav>
    </Appbar>
  )
}
```

### Accessibility

1. Appbar accepts <kbd>Esc</kbd> to close the drawer.
2. Appbar also traps focus in the drawer. Press <kbd>Tab</kbd> or <kbd>Shift</kbd> + <kbd>Tab</kbd> to toggle through the focusable elements.

## Creating a custom Appbar

Appbar exports layout unit components using which you can create a custom implementation of Appbar:

1. BaseAppbar
2. AppbarHead
3. AppbarBody
4. AppbarTail
5. useAppbar

You would need to add the responsive styles as they are not screen responsive by default.
These layout components do not respond to different screen sizes. You can wrap them in containers with media queries for the custom Appbar to adapt to screen sizes. For example:

```
@media only screen and (max-width: 600px) {
  .container {
    /* some styles */
  }

  .content {
    /* some styles */
  }
}
```

```jsx
const CustomAppbar = () => {
  return (
    <div className="container">
      <BaseAppbar>
        <div className="content">
          <AppbarBody>
            // NavItems
          </AppbarBody>
        </div>
      </BaseAppbar>
    </div>
  )
}
```

## Hooks

Appbar exports a `useAppbar` hook to help you create custom functionality.

### useAppbar

React hook to implement the ability to open/close the Appbar in smaller screens. Use this hook when you are implementing your custom Appbar using the unit layout components. Let's look at the usage:

```jsx
import { Appbar, useAppbar } from "@asphalt-react/appbar"

const CustomAppbar = () => {
  const { visible, open, close } = useAppbar({ defaultOpen: true })

  return (
      <Appbar>
        <div className={visible ? "show" : "hide"}>
          {visible ? (
            <Button onClick={close}>close</Button>
          ) : (
            <Button onClick={open}>open</Button>
          )}
        </div>
      </Appbar>
  )
}

```

1. `visible`: A stateful boolean value to control the (open/close) state.
2. `open`: A function to open the Appbar.
3. `close`: A function to close the Appbar.

`useAppbar` accepts the `defaultVisible` prop as the argument.

[comment]: # "Appbar Props"

## Props

### children

React node to render in the Appbar content.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | N/A     |

### head

Content to display in the Appbar head.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | null    |

### tail

Content to display in the Appbar tail.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | null    |

### dismissLabel

"aria-label" for the button to close Appbar in smaller screens.

| type   | required | default                   |
| ------ | -------- | ------------------------- |
| string | false    | "close appbar navigation" |

### menuLabel

"aria-label" for the button to open Appbar in smaller screens.

| type   | required | default                  |
| ------ | -------- | ------------------------ |
| string | false    | "open appbar navigation" |

### defaultVisible

Appbar shows the body section in the initial state.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

# Nav

[comment]: # "Nav Props"

## Props

### children

React nodes to render in the Nav content.

| type | required | default |
| ---- | -------- | ------- |
| node | true     | N/A     |

# NavItem

Using NavItem component, links can be added to the Appbar. By default, it renders an `<a>` tag but you can pass your custom element or React component using `as` prop. All the props related to the link should be passed in `asProps` element.

[comment]: # "NavItem Props"

## Props

### children

Content for a nav item.

| type | required | default |
| ---- | -------- | ------- |
| node | true     | N/A     |

# NavItemCaption

[comment]: # "NavItemCaption Props"

## Props

### children

React node to render the caption of the nav item.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | N/A     |

# NavItemIcon

Icon for the NavItem. Accepts SVG.

[comment]: # "NavItemIcon Props"

## Props

### children

Icon to enhance the nav item's caption. Accepts SVG.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | N/A     |

# NavItemAction

Accepts elements for custom actions in a NavItem.

[comment]: # "NavItemAction Props"

## Props

### children

React node to render action elements for a nav item.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | N/A     |

### propagateEvent

Allow events to propagate to the parent element.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

# NavLink

Renders the link element for a NavItem.

[comment]: # "NavLink Props"

## Props

### children

React node to render link content.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | N/A     |

### as

Html element/React component to replace the default element. Using this prop, you can use your router's link element, such as "react-router-dom"'s Link element.

| type        | required | default |
| ----------- | -------- | ------- |
| elementType | false    | "a"     |

### asProps

Pass the props such as "href", "id" for the custom link element passed in `as` prop.

| type   | required | default |
| ------ | -------- | ------- |
| object | false    | {}      |

### active

Marks the nav link as active.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### prominent

An active style. Adds an indicator to accent the active nav link.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### highlight

A subtle active style. Highlights the surface of the nav item.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### icon

An icon only nav link.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | false   |

### bezel

Adds padding.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

# BaseAppbar

The base container unit component.

[comment]: # "BaseAppbar Props"

## Props

### children

Container for the BaseAppbar content.

| type | required | default |
| ---- | -------- | ------- |
| node | true     | N/A     |

### bezel

Adds padding.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

# AppbarHead

The unit component for rendering the head elements.

[comment]: # "AppbarHead Props"

## Props

### children

Container for the AppbarHead content.

| type | required | default |
| ---- | -------- | ------- |
| node | false    | N/A     |

### bezel

Adds padding.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |

# AppbarBody

The unit component to render the main content.

[comment]: # "AppbarBody Props"

## Props

### children

Container for the AppbarBody content.

| type | required | default |
| ---- | -------- | ------- |
| node | true     | N/A     |

# AppbarTail

React node to render content in the tail section.

[comment]: # "AppbarTail Props"

## Props

### children

Container for the AppbarTail content.

| type | required | default |
| ---- | -------- | ------- |
| node | true     | N/A     |

### bezel

Adds padding.

| type | required | default |
| ---- | -------- | ------- |
| bool | false    | true    |