paper-stepper.html

<link rel="import" href="../iron-flex-layout/iron-flex-layout.html">
<link rel="import" href="../iron-selector/iron-selectable.html">
<link rel="import" href="../iron-menu-behavior/iron-menu-behavior.html">
<link rel="import" href="../neon-animation/neon-animation-runner-behavior.html">
<link rel="import" href="../paper-button/paper-button.html">
<link rel="import" href="../paper-styles/default-theme.html">
<link rel="import" href="../paper-styles/shadow.html">
<link rel="import" href="../iron-collapse/iron-collapse.html">
<link rel="import" href="../iron-resizable-behavior/iron-resizable-behavior.html">
<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="animations/fade-in-slide-from-right-animation.html">
<link rel="import" href="animations/fade-out-slide-right-animation.html">
<link rel="import" href="animations/fade-in-slide-from-left-animation.html">
<link rel="import" href="animations/fade-out-slide-left-animation.html">
<link rel="import" href="paper-step.html">

<!--
Missing Doc


## Styling

The default color values respect the material specifications. For basic configuration, just defines the `--primary-color` for your app.

The stepper has a complexe interface so many custom properties are available, use them this way :

```html
<style is="custom-style">

  paper-stepper {
    --paper-stepper-custom-property: value;
  }

  paper-step {
    --paper-step-custom-property: value;
  }

</style>

<paper-stepper>
  <paper-step></paper-step>
  <paper-step></paper-step>
</paper-stepper>
```

Note, for sizing the stepper and steps depending on the layout, use the following instead of setting 'height' and 'max-height' :
- `--paper-stepper-horizontal-opened-height`
- `--paper-stepper-vertical-max-height`
- `--paper-vertical-step-max-height`

### Stepper

Custom property | Description | Default
------|-------------|----------
`--paper-stepper-horizontal-opened-height` | The horizontal opened stepper height | 450px
`--paper-stepper-horizontal-opening-transition-duration`| The horizontal stepper opening transition duration (ms) | 500
`--paper-stepper-vertical-max-height`| The vertical stepper max height so it has a scrollable area | undefined

### Step

Custom property | Description | Default
------|-------------|----------
`--paper-step-connector-line-background` | The connector lines background color. | `--divider-color`
`--paper-step-label-hover-background` | The steps label background when hovered. | rgba(0,0,0,0.04)
`--paper-step-ink-color` | The steps ripple effect ink color. | `--divider-color`

### Step text label

Custom property | Description | Default
------|-------------|----------
`--paper-step-disabled-label-text-color` | The no-selectable steps label text color. | `--paper-grey-400`
`--paper-step-selectable-label-text-color` | The selectable steps label text color. | `--paper-grey-600`
`--paper-step-opened-label-text-color` | The opened steps label text color. | `--light-theme-text-color`
`--paper-step-label-text-font-size` | The steps label text font size. | 14px
`--paper-step-label-optional-text-font-size` | The steps label optional text font size. | 12px

### Step badge

Custom property | Description | Default
------|-------------|----------
`--paper-step-badge-background` | The badge background. | `--paper-grey-300`
`--paper-step-badge-color` | The badge color. | `--dark-theme-text-color`
`--paper-step-badge-icon-width` | The badge icon width. | 16px
`--paper-step-badge-icon-height` | The badge icon height. | 16px
`--paper-step-opened-badge-background` | The opened steps badge background. | `--primary-color`
`--paper-step-saved-badge-background` | The saved steps badge background. | `--primary-color`
`--paper-step-selectable-hovered-badge-background` | The no-opened no-saved selectable steps badge background. | `--paper-grey-500`

### Vertical step

Custom property | Description | Default
------|-------------|----------
`--paper-vertical-step-continue-button-background` | The continue button background. | `--primary-color`
`--paper-vertical-step-continue-button-color` | The continue button background. | `--dark-theme-text-color`
`--paper-vertical-step-max-height` | The unrolled step content max-height. | 400px
`--paper-vertical-step-transition-duration` | The step opening transition duration | 500ms


@element paper-stepper
@demo demo/index.html
@hero hero.svg
-->
<dom-module id="paper-stepper">
  <template>
    <style>
      :host {
        display: block;
        box-sizing: border-box;
        @apply(--layout-vertical);
        @apply(--shadow-elevation-2dp);
        background: white;
        border-radius: 1px;
      }
      #verticalResponsiveWidth {
        width: var(--paper-stepper-vertical-responsive-width, 0px);
        visibility: hidden;
      }

      /* Horizontal layout styles */

      :host([vertical]) {
        padding: 4px 0;
        @apply(--layout-scroll);
        max-height: var(--paper-stepper-vertical-max-height);
      }
      :host(:not([vertical])) {
        position: relative;
        /* Note: this variable is updated by the stepper itself, don't use it on user side */
        height: var(--label-wrapper-height);
        max-height: var(--label-wrapper-height);
        transition: max-height var(--paper-stepper-horizontal-opening-transition-duration, 300ms), box-shadow 0.28s cubic-bezier(0.4, 0, 0.2, 1);
      }
      :host(:not([vertical]):not([opened]):not(.collapsing)) {
        @apply(--shadow-none);
      }
      :host(:not([vertical])[opened]) {
        max-height: var(--paper-stepper-horizontal-opened-height, 450px);
      }
      :host(:not([vertical])[opened]), :host(:not([vertical]).collapsing) {
        height: var(--paper-stepper-horizontal-opened-height, 450px);
      }
      :host(:not([vertical])) #content-wrapper {
        @apply(--shadow-elevation-2dp);
        @apply(--layout-horizontal);
        @apply(--layout-flex-none);
        @apply(--layout-justified);
        background: var(--paper-stepper-horizontal-label-wrapper-background, --primary-background-color);
        border-radius: 1px;
        overflow: hidden;
      }
      .flex {
        @apply(--layout-flex);
      }
      #buttonsWrapper {
        @apply(--layout-horizontal);
        margin: 0 24px 24px 24px;
        overflow: hidden;
      }
      #continueButton:not([disabled]) {
        color: var(--primary-color);
      }
      paper-button[disabled] {
        background-color: transparent;
      }
      [hidden] {
        display: none;
      }
      :host(:not[vertical]) #content-wrapper:not(:hover) ::content paper-step[opened] {
        overflow: visible;
      }
    </style>
    
    <!-- Hidden block with width equals to the responsive threshold -->
    <div id="verticalResponsiveWidth"></div>
    
    <!-- This wrapper contains the horizontal stepper header or the full vertical stepper -->
    <div id="content-wrapper">
      <content select="[[selectable]]"></content>
    </div>

    <!-- Slideshow and buttons area for horizontal layout -->
    <template is="dom-if" if="[[!vertical]]">
      <div class="flex"></div>
      <div id="buttonsWrapper">
        <paper-button hidden$="[[!hasBackButton]]" disabled=[[!_hasBackStep]] on-tap="back">[[backText]]</paper-button>
        <span class="flex"></span>
        <paper-button hidden$="[[!hasSkipButton]]" disabled="[[!_canSkip]]" on-tap="progress">[[skipText]]</paper-button>
        <paper-button id="continueButton" on-tap="continue">{{_choosePrimaryButtonText(_attrForSelectedStepPrimaryButtonText, finishText, continueText, updateText)}}</paper-button>
      </div>
    </template>

  </template>

  <script>
    'use strict';
    Polymer({

      is: 'paper-stepper',

      behaviors: [
        Polymer.IronMenuBehavior,
        Polymer.NeonAnimationRunnerBehavior,
        Polymer.IronResizableBehavior
      ],

      /**
       * Fired when the stepper progress.
       *
       * @event paper-stepper-progressed
       */
      /**
       * Fired when all the steps are saved.
       *
       * @event paper-stepper-completed
       */
      properties: {
        opened: {
          type: Boolean,
          computed: '_computeOpened(_selectedIndex)',
          observer: '_openedChanged',
          notify: true,
          reflectToAttribute: true
        },
        alternativeLabel: {
          type: Boolean,
          value: false
        },
        vertical: {
          type: Boolean,
          value: false,
          notify: true,
          reflectToAttribute: true
        },
        backText: {
          type: String,
          value: 'BACK'
        },
        finishText: {
          type: String,
          value: 'FINISH'
        },
        continueText: {
          type: String,
          value: 'CONTINUE'
        },
        skipText: {
          type: String,
          value: 'SKIP'
        },
        optionalText: {
          type: String,
          value: 'Optional'
        },
        updateText: {
          type: String,
          value: 'UPDATE'
        },
        linear: {
          type: Boolean,
          value: false
        },
        completed: {
          type: Boolean,
          value: false,
          notify: true,
          computed: '_computeCompleted(stepNumber, savedStepNumber)'
        },
        hasSkipButton: {
          type: Boolean,
          value: false
        },
        hasBackButton: {
          type: Boolean,
          value: false
        },
        stepNumber: {
          type: Number,
          notify: true,
          computed: '_computeStepNumber(items.length)'
        },
        savedStepNumber: {
          type: Number,
          notify: true,
          readOnly: true
        },
        selectedAttribute: {
          value: 'opened',
          readOnly: true
        },
        /**
         * Note: if you decide to change this attribute, take care to only include `<paper-step>` elements in your `<paper-stepper>`
         */
        selectable: {
          value: 'paper-step'
        },
        /**
         * Multi mode is not allowed for now in paper-stepper.
         */
        mutli: {
          value: false,
          readOnly: true
        },
        responsiveCheckFrequence: {
          type: Number,
          value: 200
        },
        animateInitialSelection: {
          type: Boolean,
          value: false
        },
        horizontalHigherEntryAnimation: {
          type: String,
          value: 'fade-in-slide-from-right-animation'
        },
        horizontalHigherExitAnimation: {
          type: String,
          value: 'fade-out-slide-right-animation'
        },
        horizontalLowerEntryAnimation: {
          type: String,
          value: 'fade-in-slide-from-left-animation'
        },
        horizontalLowerExitAnimation: {
          type: String,
          value: 'fade-out-slide-left-animation'
        },
        _skipStepIndex: {
          type: Number,
          computed: '_compute_skipStepIndex(_selectedIndex)'
        },
        _canSkip: {
          type: Boolean,
          notify: true,
          computed: '_isntNull(_skipStepIndex)'
        },
        _backStepIndex: {
          type: Number,
          computed: '_compute_backStepIndex(_selectedIndex)'
        },
        _hasBackStep: {
          type: Boolean,
          computed: '_isntNull(_backStepIndex)'
        },
        _selectedIndex: {
          type: Number,
          observer: '_selectedIndexChanged',
          readOnly: true,
          value: -1
        },
        _attrForSelectedStepPrimaryButtonText: {
          type: String,
          computed: '_compute__attrForSelectedStepPrimaryButtonText(_selectedIndex, stepNumber)'
        }
      },

      _previousAnimatedStep: null,

      _previousSelected: null,

      keyBindings: {
        'left': '_onLeftKey',
        'right': '_onRightKey'
      },

      listeners: {
        'iron-items-changed': '_initializeSteps',
        'paper-step-saved': '_stepSaved',
        'transitionend': '_transitionEnd',
        'step-horizontal-label-resize': '_updateStepperClosedMaxHeight',
        'iron-resize': '_resizeHandler',
        'neon-animation-finish': '_onNeonAnimationFinish'
      },

      observers: [
        '_forwardCanSkip(_canSkip, selectedItem)',
        '_forwardHasBackStep(_hasBackStep, selectedItem)',
        '_forwardVertical(vertical)',
        '_forwardAlternativeLabel(alternativeLabel)',
        '_forwardStepperData(linear, backText, optionalText, finishText, continueText, skipText, updateText, hasSkipButton, hasBackButton)'
      ],

      attached: function() {
        this._responsiveCheck();
      },

      /**
       * Missing Doc
       */
      back: function() {
        this.selectIndex(this._backStepIndex);
      },

      /**
       * @return {Boolean} Try to continue the current step (if no step opened, use the first one).
       */
      continue: function() {
        if (this.selectedItem) {
          if (this.selectedItem.save()) {
            this.progress();
          }
        }
      },

      /**
       * Loops around the steps from the current (if no step opened, from the first one)
       * in order to open the next selectable unsaved step. Returns true if a step has been opened.
       */
      progress: function() {
        if (!this.stepNumber) {
          return false;
        }
        if (this.completed) {
          this.selected = null;
          return true;
        }
        for (var i = (this._selectedIndex+1)%this.stepNumber; i != this._selectedIndex; i = (i+1)%this.stepNumber) {
          if (this.items[i].selectable && !this.items[i].saved) {
            this.selectIndex(i);
            this.fire('paper-stepper-progressed');
            return true;
          }
        }
        return false;
      },

      /* Deselect and set the steps as unsaved*/
      reset: function() {
        this._setSavedStepNumber(0);
        this.selected = null;
        if (!this.items.length) {
          return;
        }
        this.items.map(function(step) {
          step._setSaved(false);
          step._set_previousSaved(false);
        });
        this.items[0]._set_previousSaved(true);
      },

      get _isRTL() {
        return window.getComputedStyle(this)['direction'] === 'rtl';
      },

      _onLeftKey: function(event) {
        if (this._isRTL) {
          this._focusNext();
        } else {
          this._focusPrevious();
        }
        event.detail.keyboardEvent.preventDefault();
      },
      
      _onRightKey: function(event) {
        if (this._isRTL) {
          this._focusPrevious();
        } else {
          this._focusNext();
        }
        event.detail.keyboardEvent.preventDefault();
      },

      /**
       * Work around: Override the method from IronSelectableBehavior to only allow the selection of selectable step. https://github.com/PolymerElements/iron-selector/issues/99
       */
      _selectSelected: function(selected) {
        var item = this._valueToItem(this.selected);
        if (item) {
          var selectable = item.selectable;
          if (selectable == undefined) {
            // if selectable isn't define it means the step is not yet ready for selection
            // and this method will be recalled by the initialization method.
            return;
          } else if (!selectable) {
            //reset previous selected if non null and selectable or deselect
            if (this._previousSelected && this._previousSelected.selectable) {
              this.selected = this._valueForItem(this.previousSelected);
            } else {
              this.selected = null;
            }
            this._previousSelected = null;
            return;
          }
        }
        this._selection.select(item);
        this._previousSelected = item;
        this._set_selectedIndex(this.indexOf(item));
        // Check for items, since this array is populated only when attached
        // Since Number(0) is falsy, explicitly check for undefined
        if (this.fallbackSelection && this.items.length && (this._selection.get() === undefined)) {
          this.selected = this.fallbackSelection;
        }
      },

      _updateStepperClosedMaxHeight: function() {
        this.debounce('updateStepperClosedMaxHeight', function() {
          this.customStyle['--label-wrapper-height'] = this.$$('#content-wrapper').clientHeight + 'px';
          this.updateStyles('--label-wrapper-height');
        });
      },

      _openedChanged: function(newValue, oldValue) {
        if (!this.vertical && oldValue != undefined) {
          this.toggleClass('collapsing', true);
        }
      },

      _transitionEnd: function(e) {
        // check to ignore event fired by paper-ripple
        if (e.propertyName == 'max-height') {
          this.toggleClass('collapsing', false);
        }
      },

      _computeOpened: function(_selectedIndex) {
        return _selectedIndex >= 0;
      },

      _stepSaved: function(e) {
        var previousStep = this.items[this.indexOf(e.target)+1];
        if (previousStep) {
          previousStep._set_previousSaved(true);
        }
        this._setSavedStepNumber(this.savedStepNumber+1);
      },

      _forwardVertical: function(vertical) {
        if (this.stepNumber) {
          this.items.map(function(step) {
            step._setVertical(vertical);
          });
        }
        this.setAttribute('role', vertical ? 'menu': 'menubar');
      },

      _forwardStepperData: function(linear, backText, optionalText, finishText, continueText, skipText, updateText, hasSkipButton, hasBackButton) {
        if (this.stepNumber) {
          this.items.map(function(step) {
            step._set_stepperData({
              linear: linear,
              backText: backText,
              optionalText: optionalText,
              finishText: finishText,
              continueText: continueText,
              skipText: skipText,
              updateText: updateText,
              hasSkipButton: hasSkipButton,
              hasBackButton: hasBackButton,
              stepNumber: this.stepNumber
            });
          }.bind(this));
        }
      },

      _forwardAlternativeLabel: function(alternativeLabel) {
        if (this.stepNumber) {
          this.items.map(function(step) {
            step._set_alternativeLabel(alternativeLabel);
          });
        }
      },

      _computeStepNumber: function(length) {
        return length;
      },

      _selectedIndexChanged: function(newValue, oldValue) {
        if (!this.vertical && newValue >=0 && oldValue >= 0) {
          var oldStep = this.items[oldValue], newStep = this.items[newValue];
          if (newStep.classList.contains('neon-animating')) {
            this.cancelAnimation();
          }
          if (this._previousAnimatedStep && this._previousAnimatedStep.classList.contains('neon-animating')) {
            this.cancelAnimation();
            this.toggleClass('neon-animating', false, this._previousAnimatedStep);
          }
          var forward = newValue - oldValue > 0;

          this.animationConfig = {
            'new-step-entry': {
              animatable: newStep,
              type: forward ?
                newStep.horizontalHigherEntryAnimation && 'higher-step-entry' :
                newStep.horizontalLowerEntryAnimation && 'lower-step-entry'
            },
            'old-step-exit': {
              animatable: oldStep,
              type: forward ?
                oldStep.horizontalLowerExitAnimation && 'lower-step-exit' :
                oldStep.horizontalHigherExitAnimation && 'higher-step-exit'
            }
          };
          if (this.animationConfig['new-step-entry'].type) {
            this.playAnimation('new-step-entry', {step: newStep});
            this.toggleClass('neon-animating', true, newStep);
          }
          if (this.animationConfig['old-step-exit'].type) {
            this.playAnimation('old-step-exit', {step: oldStep});
            this.toggleClass('neon-animating', true, oldStep);
          }

          this._previousAnimatedStep = oldStep;
        }
      },

      _onNeonAnimationFinish: function(event) {
        var step = event.detail.step;
        if (step) {
          this.toggleClass('neon-animating', false, step);
        }
      },

      _forwardCanSkip: function(_canSkip, selectedItem) {
        selectedItem._set_canSkip(_canSkip);
      },

      _forwardHasBackStep: function(_hasBackStep, selectedItem) {
        selectedItem._set_hasBackStep(_hasBackStep);
      },

      _compute__attrForSelectedStepPrimaryButtonText: function(selectedIndex) {
        /* TODO: compute from selectedItem when https://github.com/PolymerElements/iron-selector/issues/118 is fixed*/
        if (selectedIndex < 0) {
          return null;
        }
        var _attrForPrimaryButtonText = this.selectedItem.saved ? 'updateText' :
          ( (this.stepNumber - this.savedStepNumber) == 1 ? 'finishText' : 'continueText' );
        this.selectedItem._set_attrForPrimaryButtonText(_attrForPrimaryButtonText);
        return _attrForPrimaryButtonText;
      },

      _initializeSteps: function() {
        var savedStepNumber = 0;
        var data = {
          linear: this.linear,
          backText: this.backText,
          optionalText: this.optionalText,
          finishText: this.finishText,
          continueText: this.continueText,
          skipText: this.skipText,
          updateText: this.updateText,
          hasSkipButton: this.hasSkipButton,
          hasBackButton: this.hasBackButton,
          stepNumber: this.stepNumber
        };
        this.items.map(function(step, i) {
          if (this.horizontalHigherEntryAnimation && !step.horizontalHigherEntryAnimation) {
            step.horizontalHigherEntryAnimation = this.horizontalHigherEntryAnimation;
          }
          if (this.horizontalHigherExitAnimation && !step.horizontalHigherExitAnimation) {
            step.horizontalHigherExitAnimation = this.horizontalHigherExitAnimation;
          }
          if (this.horizontalLowerEntryAnimation && !step.horizontalLowerEntryAnimation) {
            step.horizontalLowerEntryAnimation = this.horizontalLowerEntryAnimation;
          }
          if (this.horizontalLowerExitAnimation && !step.horizontalLowerExitAnimation) {
            step.horizontalLowerExitAnimation = this.horizontalLowerExitAnimation;
          }
          step._setIndex(i + 1);
          step._set_stepper(this);
          step._setVertical(this.vertical);
          step._set_alternativeLabel(this.alternativeLabel);
          step._set_stepperData(data);
          // true for index 0
          step._set_previousSaved(!i);
          if (step.saved) {
            savedStepNumber++;
          }
        }.bind(this));
         
        this._setSavedStepNumber(savedStepNumber);
        // method from IronSelectableBehavior
        this._updateSelected();
      },

      _compute_skipStepIndex: function(_selectedIndex) {
        if (_selectedIndex >= 0 && !this.completed) {
          for (var i=(_selectedIndex+1)%this.stepNumber; i!=_selectedIndex; i=(i+1)%this.stepNumber) {
            if (this.items[i].selectable && !this.items[i].saved) {
              return i;
            }
          }
        }
        return null;
      },

      _compute_backStepIndex: function(_selectedIndex) {
        if (_selectedIndex >= 0) {
          for (var i=_selectedIndex - 1; i >= 0; i--) {
            if (this.items[i].selectable) {
              return i;
            }
          }
        }
        return null
      },

      _isntNull: function(n) {
        return n != null;
      },

      _computeCompleted: function(savedStepNumber, stepNumber) {
        var completed = stepNumber == savedStepNumber;
        if (completed) {
          this.fire('paper-stepper-completed');
          return true;
        }
        return false;
      },

      _choosePrimaryButtonText: function(_attrForSelectedStepPrimaryButtonText) {
        return this[_attrForSelectedStepPrimaryButtonText];
      },

      _resizeHandler: function() {
        this.debounce('paper-stepper-responsive-check', function() {
          this._responsiveCheck();
        }, this.responsiveCheckFrequence);
      },

      _responsiveCheck: function() {
        var verticalResponsiveWidth = this.$.verticalResponsiveWidth.clientWidth;
        if (verticalResponsiveWidth) {
          this.vertical = !(this.clientWidth > verticalResponsiveWidth);
        }
      }

    });

  </script>
</dom-module>