px-app-nav.html

<!--
Copyright (c) 2018, General Electric

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

<link rel="import" href="../polymer/polymer.html"/>
<link rel="import" href="../iron-resizable-behavior/iron-resizable-behavior.html"/>
<link rel="import" href="../px-app-helpers/px-app-asset/px-app-asset-behavior-graph.html"/>
<link rel="import" href="../px-app-helpers/px-app-asset/px-app-asset-behavior-selectable.html"/>

<link rel="import" href="px-app-nav-behavior-measure-text.html"/>
<link rel="import" href="px-app-nav-group.html"/>
<link rel="import" href="px-app-nav-subgroup.html"/>
<link rel="import" href="px-app-nav-item.html"/>
<link rel="import" href="px-app-nav-subitem.html"/>

<link rel="import" href="css/px-app-nav-styles.html">

<!--

`px-app-nav` is an app-level navigation element that allows users to change the
current view. The element is designed to work on desktop and mobile/touch
devices, supporting any viewport size. It has three distinct visual styles that
can be switched at any time to suit different app designs.

--------------------------------------------------------------------------------

### Navigation items: Structuring data and managing selection

The navigation accepts a list of items that will be converted into buttons for
the user to interact with. Each item should have at least a label that will
be displayed for the user to select and a unique ID that will be used to keep
track of which item is selected.

This data should be passed into the `items` attribute or property on the
`px-app-nav` element.

This is a simple navigation data example:


    [
      {
        "id" : "home",
        "label" : "Home",
        "icon" : "px-fea:home"
      },
      {
        "id" : "alert",
        "label" : "Alerts",
        "icon" : "px-fea:alerts"
      }
    ]


Top-level navigation items can optionally have child items. This is useful for
creating categories of related pages. If a top-level navigation item has any
children it cannot be selected directly - users can select its child items,
and the top-level "category" item will get the selected visual style.

This example shows a "Dashboards" category with a few different dashboard pages:


    [
      {
        "id" : "dash",
        "label" : "Dashboards",
        "icon" : "px-fea:dashboard",
        "children" : [
          {
            "id" : "plant-status",
            "label" : "Plant Status Updates"
          },
          {
            "id" : "output-info",
            "label" : "Daily Output Measurements"
          }
        ]
      }
    ]

All items (top-level items, top-level category items, and child items) should
have the following properties:

  - **id** {string} - unique string that identifies the item. Should only contain
  valid, URI-safe characters. Example: "home", "alerts1"
  - **label** {string} - short, human-readable text. The user will tap this text
  to select the item. Example: "Homepage", "View Alerts"

The following optional properties can be defined for top-level items only:

  - **icon** {string} - valid [px-icon-set](https://www.predix-ui.com/#/modules/px-icon-set/)
  icon placed next to the text label for the item. Use an icon from the `px-fea`
  for the best sizing and visual styling. If the icon you need is not available in
  the `px-fea` icon set, you may use an icon from the `px-nav` icon set, but only
  do so if absolutely necessary.
  - **children** {array} - child items that will be placed in a dropdown under
  their parent top-level item. Each child item should have an `id` and `label`.
  If the child item has an `icon` property, it will be ignored.

Example top-level item without children:


    {
      "id" : "page-id",
      "label" : "Page Title",
      "icon" : "px-fea:templates"
    }


Example top-level item with child items:


    {
      "id" : "category-id",
      "label" : "Category Title",
      "icon" : "px-fea:microservice",
      "children" : [
        {
          "id" : "child-item-1",
          "label" : "First Child Title"
        },
        {
          "id" : "child-item-2",
          "label" : "Second Child Title"
        }
      ]
    }


Additional data not used by `px-app-nav` can also be included in each item's
object. This is a useful way to store metadata about app pages that will be used
at run-time when a new nav item is selected. Example:


    {
      "id" : "all-cases",
      "label" : "Cases",
      "metadata" : {
        "openCases" : "12",
        "closedCases" : "82"
      }
    }

The navigation will not mutate any of its items properties, making it easy to
share any item metadata with other app components.

#### Responding to item selection

When the user taps on a navigation item it will be marked as selected. The app
containing the `px-app-nav` element should respond to the new selected item and
update its view.

There are two ways for an app to listen for user selection:

- **By reference:** The element's `selected` property will be updated when a new
item is selected. The `selected` property will notify a reference to the object
that describes the item in the `items` array.

- **By route:** The element's `selectedRoute` property will notify an array of
strings that trace the path from the root of the `items` graph to the selected
item. This is useful for binding the navigation state to the app's URL path.
(See the [px-app-route](https://www.predix-ui.com/#/elements/px-app-helpers/px-app-route)
module for a guide to binding the navigation state to the URL.)

For example, given the following simplified navigation `items` list:

    [
      {
        "id" : "dash",
        "label" : "Dashboards",
        "children" : [
          {
            "id" : "info-dash",
            "label" : "Info Dashboard"
          }
        ]
      }
    ]

When the user selects the "Info Dashboard", the `selectedRoute` will be set to
`["dash", "info-fash"]`.

#### Selecting an item programmatically

Sometimes it is useful for an app to automatically change the active page
(e.g. opening the home page when the app is first loaded, or opening a dashboard
when the user clicks on an alert message). The `selected` and `selectedRoute`
properties can be used to set the selected navigation item state in the same
way they are used to read the selected navigation item state.

The simplest way to do this is through `selectedRoute`:


    <px-app-nav
        items='[
          { "label" : "Home",   "id" : "home",   "icon" : "px-fea:home" },
          { "label" : "Alerts", "id" : "alerts", "icon" : "px-fea:alerts" },
          { "label" : "Assets", "id" : "assets", "icon" : "px-fea:asset", children: [
            { "label" : "Asset #1", "id" : "a1" },
            { "label" : "Asset #2", "id" : "a2" }
          ] }
        ]'
        selected-route='["assets", "a1"]'>
    </px-app-nav>


Items can also be selected by reference using the `selected` property. Selecting
this way requires a bit of JavaScript; the navigation does a simple reference
equality check (`item1 === item2`) to find the item in the graph and select it.
Passing an item with the same properties as one of the `items` objects will
not select it.


    <px-app-nav id="nav"></px-app-nav>
    <script>
      var nav = document.getElementById('nav');
      var navItems = [
        { "id" : "home", "label" : "Home" }
      ];
      nav.items = navItems;
      nav.selected = navItems[0];
    </script>


Data-binding can also be used to accomplish the same thing without manually
finding the `px-app-nav` element in the DOM.

### Binding to the URL path (routing)

The `px-app-nav` element is designed to easily bind its state to the URL path.
When the user selects an item, its `selectedRoute` can be encoded and used to
set the URL path. The user can then bookmark the page or share the URL to link
to a specific view. When the user loads a page with a URL path defined, that
path can be decoded and used to select the right navigation item (and show a
page).

For a ready-to-go solution for binding `px-app-nav` to the URL path, see the
[px-app-route](https://www.predix-ui.com/#/elements/px-app-helpers/px-app-route) component.
This component works best in applications built using Polymer as a data-binding
framework, but also exposes methods to help convert the navigation's
`selectedRoute` to and from a path string for use in other framework routers.

Alternatively, listen for update events from the `selected` and/or `selectedRoute`
properties in your app and send the values to the framework router of your
choice, or implement your own routing system from scratch.

--------------------------------------------------------------------------------


### Navigation styles

Two of the navigation styles, horizontal and vertical, should only be used on
desktop screens. The collapsed navigation style should be used on mobile/touch
devices and can also be used for desktop devices.


#### 1. Horizontal navigation

The horizontal navigation style is a persistent bar fixed to the top of the viewport.
Navigation items are displayed in a row. If the window is too narrow to fit all
the items, any overflowed items are placed into an overflow dropdown. If only
one navigation item fits in the window, the navigation will automatically
switch to collapse style (see description below).

This is the default style. It doesn't require any additional configuration to
enable beyond putting the `px-app-nav` element tag on the app page. The following
example shows how to configure px-app-nav in the horizontal style:


    <px-app-nav
        items='[
          { "label" : "Home",   "id" : "home",   "icon" : "px-fea:home" },
          { "label" : "Alerts", "id" : "alerts", "icon" : "px-fea:alerts" },
          { "label" : "Assets", "id" : "assets", "icon" : "px-fea:asset", children: [
            { "label" : "Asset #1", "id" : "a1" },
            { "label" : "Asset #2", "id" : "a2" }
          ] }
        ]'
        selected-route='["assets","a1"]'>
    </px-app-nav>

#### Positioning a horizontal app-nav in an app:

The horizontal style `px-app-nav` element should be fixed at the top of your app
with app content configured to scroll beneath it. The app must position the
`px-app-nav` element using CSS to fix it to the top of the view. By default, the
element is `position: relative` and `display: block`, causing it to fill its
parent container's width but scroll out of the view as the user scrolls down
the page.

The following example fixes the element to the top of the view so content
can scroll beneath it:


    <style>
      px-app-nav {
        position: fixed;
        top: 0;
        left: 0;
      }
    </style>
    <px-app-nav items="..."></px-app-nav>

Using position fixed will cause the `px-app-nav` element to cover other HTML
elements at the top of your page. Offset your content (e.g. by setting
`margin-top: 80px` on your content container) to ensure the navigation does not
cover other app elements unintentionally.

--------------------------------------------------------------------------------

#### 2. Collapsed navigation

The collapsed navigation style is also a persistent bar fixed to the top of the
viewport. The navigation items are displayed in a dropdown menu that the user
can open by clicking or tapping on the open button; and closed by selecting
a navigation item or clicking or tapping anywhere else in the viewport.

If no item is selected, the collapsed navigation will show an empty outline
for the dropdown trigger button. If an item is selected that item's label and
icon will be shown in the dropdown trigger button.

This style can be enabled in a few different ways:

- **Force collapse:** Setting the `collapseAll` property to true or enabling the
`collapse-all` attribute on the `px-app-nav` element will force the navigation
to use the collapsed style at all times. Example:


    <px-app-nav items="..." collapse-all></px-app-nav>


- **Dynamic collapse:** The `collapseAt` property can be used to dynamically
collapse and un-collapse the navigation when the viewport size changes. If the
size of the `px-app-nav` element's container becomes smaller than the `collapseAt`
value, it is collapsed. If the element's container becomes larger than the
`collapseAt` value, it is un-collapsed.


    <px-app-nav items="..." collapse-at="420"></px-app-nav>


The `collapseAt` property should be a number that will be converted into pixels.

When the navigation is automatically collapsed or un-collapsed, the read-only
`collapsed` property will be updated. Watch that property to figure out the
state of the navigation.

- **Auto-collapse:** When the default horizontal style is in use and only 1 item
fits in the space available to the `px-app-nav` element, the navigation will be
automatically collapsed.

#### Positioning a collapsed app-nav in an app:

Follow the sticking instructions in the Horizontal style section above to
correctly position the `px-app-nav` element on the page in collapsed style.

--------------------------------------------------------------------------------

#### 3. Vertical navigation

The vertical navigation style is fixed to the left or right side of the browser.
When the navigation is not being interacted with it displays as a narrow strip
showing only the navigation item icons. When the user hovers over the vertical
navigation, the bar animates open and allows the user to click/tap to select
a new item. Example:


    <px-app-nav items="..." vertical></px-app-nav>

The vertical navigation can be opened in a few ways:

- **Auto open:** When the default vertical style is in use the navigation will automatically
open on hover over the `px-app-nav` element.

- **Force open:** Setting the `verticalOpenedAt` property to 0 on the `px-app-nav` 
element will force the navigation to use the opened style at all times. Example:


    <px-app-nav items="..." vertical-opened=at="0"></px-app-nav>


- **Dynamic open:** The `verticalOpenedAt` property can be used to dynamically open 
the navigation when the viewport size changes. If the size of the `px-app-nav` element's 
parent container becomes larger than the value of `verticalOpenedAt`, it is opened.
For example, if `verticalOpenedAt` is 600, the navigation will open if the containers
width exceeds 600px and close if below 600px.


    <px-app-nav items="..." vertical-opened-at="600"></px-app-nav>


The `verticalOpenedAt` property should be a number that will be converted into pixels.

When the navigation is dynamically opened, the `verticalOpened` property will be updated. 
Watch that property to figure out the state of the navigation.


#### Positioning a vertical app-nav  in an app:

The vertical style defaults to CSS styles `position: absolute; left: 0; top: 0;`
to stick to the left side of the screen. This causes the navigation element to
fill the first `position: relative` item above it in the DOM. Override these
values to position it in whatever way your app requires:


      <style>
        px-app-nav {
          position: fixed;
          right: 0;
          top: 0;
        }
      </style>
      <px-app-nav items="..."></px-app-nav>

--------------------------------------------------------------------------------


### Styling

The following custom properties are available for styling:

Custom property | Description
----------------|-------------
`--px-app-nav-background-color`                                         | The background color of the app nav bar
`--px-app-nav-item-background-color--collapsed`                         | The background color for a collapsed app nav
`--px-app-nav-item-background-color--empty`                             | The background color for an empty app nav
`--px-app-nav-item-background-color--hover`                             | The hover state color for an app nav item
`--px-app-nav-item-background-color--pressed`                           | The pressed state color for an app nav item
`--px-app-nav-item-background-color--selected`                          | The background color for a selected app nav item
`--px-app-nav-item-background-color`                                    | The background color for an unselected app nav item
`--px-app-nav-item-icon-color--collapsed`                               | The color of the icon in a collapsed app nav
`--px-app-nav-item-icon-color--hover`                                   | The hover state color for an icon
`--px-app-nav-item-icon-color--pressed`                                 | The pressed state color for an icon
`--px-app-nav-item-icon-color--selected`                                | The  color for the icon in a selected item
`--px-app-nav-item-icon-color`                                          | The normal, unselected color for an icon
`--px-app-nav-item-stripe-color--selected`                              | The stripe accent color on the top or side of a selected item
`--px-app-nav-item-text-color--collapsed`                               | The text color in a collapsed state
`--px-app-nav-item-text-color--hover`                                   | The text color in a hover state
`--px-app-nav-item-text-color--pressed`                                 | The text color in a pressed state
`--px-app-nav-item-text-color--selected`                                | The text color for a selected item
`--px-app-nav-item-text-color`                                          | The normal, unselected text color
`--px-app-nav-subitem-background-color--hover`                          | The hover state background color for the dropdown submenu
`--px-app-nav-subitem-background-color--selected`                       | The  background color for a selected item in the dropdown submenu
`--px-app-nav-subitem-background-color`                                 | The background color for the dropdown submenu
`--px-app-nav-subitem-text-color--collapsed`                            | The collapsed state text color for a submenu item
`--px-app-nav-subitem-text-color--hover`                                | The hover state text color for a submenu item
`--px-app-nav-subitem-text-color--selected`                             | The text color for a selected submenu item
`--px-app-nav-subitem-text-color`                                       | The normal, unselected text color for a submenu item
`--px-app-nav-subitem-background-color--collapsed`                      | The background color for the dropdown submenu in a collapsed state
`--px-app-nav-subitem-background-color--collapsed-hover`                | The hover state background color for the dropdown submenu in a collapsed state
`--px-app-nav-subitem-text-color--parent-collapsed-selected`            | The background color for the selected dropdown submenu in a collapsed state
`--px-app-nav-subitem-background-color--parent-collapsed-selected`      | The background color for the parent item of a selected submenu item in a collapsed state
`--px-app-nav-subitem-accent-color--parent-collapsed-selected`          | The strip accent color for the parent item of a selected submenu item in a collapsed state
`--px-app-nav-subitem-background-color--parent-collapsed-hover`         | The background color for the parent of a hovered submenu item in a collapsed state
`--px-app-nav-subitem-background-color--parent-collapsed-selected`      | The background color for the parent of a selected submenu item in a collapsed state
`--px-app-nav-subitem-text-color--parent-collapsed-selected`            | The text color for the parent of a hovered submenu item in a collapsed state
`--px-app-nav-subitem-text-color--parent-collapsed-not-selected`        | The text color for the parent of an open, unselected submenu item in a collapsed state
`--px-app-nav-subitem-background-color--parent-collapsed-not-selected`  | The background color for the parent of an open, unselected submenu item in a collapsed state


@element px-app-nav
@blurb A navigation component that allows the user to browse app pages and content
@homepage index.html
@demo index.html
-->
<dom-module id="px-app-nav">
  <template>
    <style include="px-app-nav-styles"></style>

    <section class="app-nav" id="container">
      <section class="app-nav__items" id="items">
        <!-- STATE: Horizontal or menu nav, any visible items -->
        <template is="dom-if" if="[[!vertical]]">
          <template is="dom-repeat" items="{{items}}" filter="_isItemVisible" id="visible">
            <!-- Stamp groups, which hold children -->
            <template is="dom-if" if="{{_isItemParent(item, keys.children)]]">
              <px-app-nav-group label="[[_getItemProp(item, keys.label)]]" icon="[[_getItemProp(item, keys.icon)]]" selected$="[[_isItemSelected(item, selectedMeta.parent)]]" collapsed$="[[vertical]]">
                <template is="dom-repeat" items="[[_getItemProp(item, keys.children)]]" as="subitem">
                  <px-app-nav-subitem item="[[subitem]]"
                                      label="[[_getItemProp(subitem, keys.label)]]"
                                      href="[[_getItemProp(item, keys.href)]]"
                                      window-name="[[_getItemProp(item, keys.window)]]"
                                      selected$="[[_isItemSelected(subitem, selectedMeta.item)]]">
                  </px-app-nav-subitem>
                </template>
              </px-app-nav-group>
            </template>

            <!-- Stamp plain old items, which hold children -->
            <template is="dom-if" if="[[_isItemNotParent(item, keys.children)}}">
              <px-app-nav-item item="[[item]]"
                               label="[[_getItemProp(item, keys.label)]]"
                               icon="[[_getItemProp(item, keys.icon)]]"
                               href="[[_getItemProp(item, keys.href)]]"
                               window-name="[[_getItemProp(item, keys.window)]]"
                               selected$="[[_isItemSelected(item, selectedMeta.item)]]">
              </px-app-nav-item>
            </template>
          </template>
        </template>

        <!-- STATE: Items overflowed or collapsed -->
        <template is="dom-if" if="[[anyOverflowed]]">
          <px-app-nav-group
              id="overflowedGroup"
              cancel-select
              fixed-width="[[_getDropdownWidth(allCollapsed, anyOverflowed)]]"
              label="[[_getDropdownLabel(selectedMeta.item, selectedMeta.parent, keys.label, collapseWithIcon, allCollapsed)]]"
              icon="[[_getDropdownIcon(selectedMeta.item, selectedMeta.parent, keys.icon, collapseWithIcon, allCollapsed, anyOverflowed, collapseOpened)]]"
              selected$="[[_isSelectedOverflowed(selectedMeta.item, selectedMeta.parent, overflowedItems)]]"
              hide-dropdown-icon="[[_isCollapsedCaratHidden(allCollapsed, collapseWithIcon)]]"
              no-highlight="[[allCollapsed]]"
              empty-icon="[[_isCollapsedDropdownEmpty(selectedMeta.item, allCollapsed, collapseWithIcon)]]"
              empty-label="[[_isCollapsedDropdownEmpty(selectedMeta.item, allCollapsed, collapseWithIcon)]]"
              fit-into="[[fitInto]]"
              opened="{{collapseOpened}}">
            <!-- Second item stamp: overflowed/collapsed items -->
            <template is="dom-repeat" items="[[items]]" filter="_isItemOverflowed" id="overflowed">
              <!-- Stamp groups, which hold children -->
              <template is="dom-if" if="[[_isItemParent(item, keys.children)]]">
                <px-app-nav-subgroup label="[[_getItemProp(item, keys.label)]]" icon="[[_getItemProp(item, keys.icon)]]" selected$="[[_isItemSelected(item, selectedMeta.parent)]]" overflowed$="[[someOverflowed]]" collapsed$="[[allCollapsed]]" opened$="[[_isOpened(item)]]">
                  <template is="dom-repeat" items="[[_getItemProp(item, keys.children)]]" as="subitem">
                    <px-app-nav-subitem item="[[subitem]]"
                                        label="[[_getItemProp(subitem, keys.label)]]"
                                        href="[[_getItemProp(subitem, keys.href)]]"
                                        window-name="[[_getItemProp(subitem, keys.window)]]"
                                        selected$="[[_isItemSelected(subitem, selectedMeta.item)]]"
                                        parent-selected$="[[_isItemSelected(item, selectedMeta.parent)]]"
                                        collapsed$="[[allCollapsed]]">
                    </px-app-nav-item>
                  </template>
                </px-app-nav-subgroup>
              </template>

              <!-- Stamp plain old items, which hold children -->
              <template is="dom-if" if="[[_isItemNotParent(item, keys.children)]]">
                <px-app-nav-item item="[[item]]"
                                 label="[[_getItemProp(item, keys.label)]]"
                                 icon="[[_getItemProp(item, keys.icon)]]"
                                 href="[[_getItemProp(item, keys.href)]]"
                                 window-name="[[_getItemProp(item, keys.window)]]"
                                 selected$="[[_isItemSelected(item, selectedMeta.item)]]"
                                 overflowed$="[[someOverflowed]]"
                                 collapsed$="[[allCollapsed]]">
                </px-app-nav-item>
              </template>
            </template>
          </px-app-nav-group>
        </template>

        <!-- STATE: Vertical nav -->
        <template is="dom-if" if="[[vertical]]">
          <!-- Second item stamp: overflowed/collapsed items -->
          <template is="dom-repeat" items="[[items]]" id="vertical">
            <!-- Stamp groups, which hold children -->
            <template is="dom-if" if="[[_isItemParent(item, keys.children)]]">
              <px-app-nav-subgroup label="[[_getItemProp(item, keys.label)]]" icon="[[_getItemProp(item, keys.icon)]]" selected$="[[_isItemSelected(item, selectedMeta.parent)]]" collapsed only-show-icon="[[!verticalOpened]]" empty-icon="[[_isIconEmpty(item, keys.icon)]]" opened$="[[_isOpened(item)]]" item="[[item]]">
                <template is="dom-repeat" items="[[_getItemProp(item, keys.children)]]" as="subitem">
                  <px-app-nav-subitem item="[[subitem]]"
                                      label="[[_getItemProp(subitem, keys.label)]]"
                                      href="[[_getItemProp(subitem, keys.href)]]"
                                      window-name="[[_getItemProp(subitem, keys.window)]]"
                                      selected$="[[_isItemSelected(subitem, selectedMeta.item)]]"
                                      parent-selected$="[[_isItemSelected(item, selectedMeta.parent)]]"
                                      collapsed></px-app-nav-item>
                </template>
              </px-app-nav-subgroup>
            </template>

            <!-- Stamp plain old items, which hold children -->
            <template is="dom-if" if="[[_isItemNotParent(item, keys.children)]]">
              <px-app-nav-item item="[[item]]"
                               label="[[_getItemProp(item, keys.label)]]"
                               icon="[[_getItemProp(item, keys.icon)]]"
                               href="[[_getItemProp(item, keys.href)]]"
                               window-name="[[_getItemProp(item, keys.window)]]"
                               selected$="[[_isItemSelected(item, selectedMeta.item)]]"
                               collapsed
                               only-show-icon$="[[!verticalOpened]]"
                               empty-icon="[[_isIconEmpty(item, keys.icon)]]">
              </px-app-nav-item>
            </template>
          </template>
        </template>
      </section>

      <section class="app-nav__actions" id="actions">
        <slot id="actionsvisible" name="actions"></slot>
      </section>
    </section>

  </template>
</dom-module>

<script src="px-app-nav.es6.js"></script>