# Navigation Tiers
![](http://img.badgesize.io/procore/particles/master/navigation-tiers/index.js)
![](http://img.badgesize.io/procore/particles/master/navigation-tiers/index.js?compression=gzip)
![](https://badge.fury.io/js/%40particles%2Fnavigation-tiers.svg)

Component is mounted with an initial data array for a single page. A page is a unique path of breadcrumbs/ids. The component stores each page in state to achieve the least amount of requests as possible. To navigate pages, an `onDrilldown` prop is required for getting the next page. This prop is returned back to you with an item of your data to determine how to render it. Optionally, you can provide a few more props for starting on tier N rather than the root.

# Example
![navigation-tiers](https://user-images.githubusercontent.com/8366399/34239375-d47c7158-e5bb-11e7-9ced-86337f059beb.gif)
## API

```
import Nav from '@particles/navigation-tiers'

<Nav.Tiers initialData root>
  <Nav.Tier id label onSelect onDrilldown itemSearch>
  {
    (data, onDrilldown) => (
      <div>
        {data.someKey}
        <span onClick={onDrilldown}>Next</span>
      </div>
    )
  }
  </Nav.Tier>
  <Nav.Tier id label onSelect itemSearch>
  {
    (data) => (
      <div>
        {data.displayKey} - {data.otherKey}
      </div>
    )
  }
  </Nav.Tier>
</Nav.Tiers>
```

### Required for starting on N
- `Tiers.props.initialPath`
- `Tiers.props.initialDisplay`
- `Tier.props.onGet`

### `Tiers` props
#### `clipResultsAt : Number`
The upper limit of items to render in a list to improve performance.

#### `initialData : Array`
The initial page data for the component's mount.

#### `initialDisplay : Array`
The initial breadcrumb display for when starting on a tier other than the root page.

#### `initialPath : Array`
The initial ids for path identification when starting on a tier other than the root page.

#### `root : String`
The display name for the first breadcrumb.

#### `i18n.errorTitle : String`

#### `i18n.errorMessage : String`
Default error message for all errors. Replaced with error callback value if present.

#### `i18n.noSearchResults : String`

#### `id : String`
The first element's `id` attribute

#### `onOpen : Function`
When the dropdown is opened.

#### `style : Object`
Style object for the first node. Usage of the `stylesheets` prop is recommended instead.

#### `stylesheets : Array`
Imported stylesheets for composition.

#### `tiggerZone: Any`
The content for the click zone to open/close the dropdown.

#### `searchOnKeyDown: Boolean`
Enables search on initial key down without having to click on dropdown trigger.

### `Tier` props
#### `clippedResultsMessage : Function(limit : Number) return String`
The message to display when a list is too large and the information is clipped. Provides the upper limit of items supplied from `Tiers.prop.clipResultsAt`.

#### `id : String`
The key with unique values across the data for the tier.

#### `label : String`
The key for the display name of the breadcrumb.

#### `onSelect : Function(option : Object)`
Function for when a tier's option is selected. Either via click or enter key pressed.

#### `onDrilldown : Function(option : Object, successCallback : Function(data : Array), errorCallback : Function(message : String))`
Function for when the next tier is requested. Provides which option is 'selected' and a callback to return the data.

#### `onGet : Function(id : Any, successCallback : Function(data : Array), errorCallback : Function(message : String))`
Used when not starting at the root. Function for when this tier is requested via the breadcrumb. `id` comes from the `initialPath` you provided for the breadcrumb.

#### `onHrefPrint : Function(option : Object) return String`
When items are desired to be anchors with hrefs.

#### `itemSearch : Function(term : String, option: Object) return Boolean`
The current search term and an option. Determine if this option should be included in the list. Return `true` to include the item, `false` to reject it.

#### `placeholder : String`
Search input placeholder.

#### `children : Function(option : Object, onDrilldown : Function) return Element`
Provides a function that will have an option of the current tier. Determine how this tier renders an option. Decorates the supplied onDrilldown function to attach to an element.


## Change Log

### 0.10.0
- core-react@^5.1.0

### 0.9.0
- add `Tiers.props.searchOnKeyDown`

### 0.8.3
- core-react@^4.8.1 (versions 4.6.x - 4.8.0 contain a bug with Input.props.inputRef)

### 0.8.2
- `Nav.Tiers.props.onOpen` prop when dropdown is clicked and opened
- `Tier.props.onSelect` called even if `Tier.props.onHrefPrint` exists

### 0.8.1
- dominate anchor style leaks

### 0.8.0
- add `Tier.props.onHrefPrint` to allow opening of items in a new tab via right click

### 0.7.2
- add qatags for the navigation dropdown

### 0.7.1
- fix component breaking when closing the dropdown when search results were empty

### 0.7.0
- add `scoped-scroll` particle
- reset search and highlight index on close
- bump `core-react` to version with css-modules having the css included
- remove FontAwesome in favor of `core-icons`
- UI updates

### 0.6.1
- add tests

### 0.6.0
- update core-react package, core-icons replaces fontawesome
- loading spinner overlays on content
- add error callback to onDrilldown and onGet props

### 0.5.0
- limit search results list length to improve performance
- fix clear button position from global button tag css targeting
- active breadcrumb style

### 0.4.0
- BREAKING CHANGE - rename `Tiers.props.data` to `Tiers.props.initialData` to show intention of mounting with this data
- add `Tiers.props.initialPath` and `Tiers.props.initialDisplay` for starting on nth tier
- add `Tier.onGet` for fetching a tier's data via a breadcrumb when not starting at the root
- split sandbox into two examples

### 0.3.1
- move when to call scroll function on events rather than component update. fix issue of hover event forcing scroll
- preventDefault for arrow keys to keep cursor in same location when scrolling up

### 0.3.0
- add scroll function for when navigating the list with up/down arrow keys
- fix bad prop type

### 0.2.0
- search icon changes to clear icon when value present
- add z-index of 1 to absolute container
- misc style updates

### 0.1.0, 0.1.1
- supports starting from first tier
- supports single list per tier
- provides callback for getting next page
- have to define number of tiers upfront, as children