docs-json-parameters-table.html

<!--
@license
Copyright 2016 The Advanced REST client authors
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-collapse/iron-collapse.html">
<link rel="import" href="../paper-dropdown-menu/paper-dropdown-menu.html">
<link rel="import" href="../paper-listbox/paper-listbox.html">
<link rel="import" href="../paper-item/paper-item.html">
<link rel="import" href="docs-parameters-behavior.html">
<link rel="import" href="docs-parameters-table-shared-styles.html">
<link rel="import" href="docs-json-structure-view.html">
<link rel="import" href="raml-type-property-description.html">
<!--
`<docs-json-parameters-table>` displays a documentation view for JSON structured body.

### Example
```
<docs-json-parameters-table
  type="[[ramlJsonType]]"></docs-json-parameters-table>
```

### Styling
`<docs-json-parameters-table>` provides the following custom properties
and mixins for styling:

Custom property | Description | Default
----------------|-------------|----------
`--docs-parameters-table` | Mixin applied to all parameter table elements | `{}`
`--docs-parameters-url-table` | Mixin applied to this elements | `{}`
`--params-table-header-background-color` | Background color of table header | `#00A1DF`
`--params-table-header-color` | Font color of table header | `rgba(255, 255, 255, 0.87)`
`--params-table-subheader-background-color` | Background color of table subheader | `rgba(0, 161, 223, 0.24)`
`--params-table-subheader-color` | Font color of table subheader | `rgba(0, 0, 0, 0.87)`
`--params-table-row-border-color` | Border color of table rows | `rgba(0, 161, 223, 1)`
`--params-table-row-subproperty-border-color` | Border color of table row which is a description of child property. | `rgba(0, 161, 223, 0.24)`
`--params-table-row-background-color` | Background color of table's each row |  `#fff`
`--params-table-row-color` | Font color of table's each row |  `#fff`
`--docs-parameters-table-cell` | Mixin applied to each cell | `{}`
`--docs-parameters-table-meta` | Mixin applied to property's metadata (example, pattern, etc) | `{}`
`--params-table-subproperty-prefix-color` | Color of the parent property name in the subproperty list | `rgba(0, 0, 0, 0.54)`

@element docs-json-parameters-table
@demo demo/docs-body-parameters-table.html
-->
<dom-module id="docs-json-parameters-table">
  <template>
    <style include="docs-parameters-table-shared-styles"></style>
    <style>
    .parent-prefix {
      color: var(--params-table-subproperty-prefix-color, rgba(0, 0, 0, 0.54));
    }

    .parent-prefix::after {
      content: '.';
    }

    paper-listbox paper-item {
      cursor: pointer;
    }

    .params-table {
      display: table;
    }

    .tr {
      display: table-row;
    }
    </style>
    <iron-collapse opened="[[structureDisplayOpened]]">
      <docs-json-structure-view type="[[type]]" has-type="[[hasType]]"></docs-json-structure-view>
    </iron-collapse>

    <template is="dom-if" if="[[renderTable]]">
      <div class="params-table">
        <div class="thead params-table-header">
          <section class="tr">
            <span class="th">Parameter</span>
            <span class="th">Description</span>
          </section>
        </div>
        <h5 class="narrow-title">Properties</h5>
        <div class="tbody">
          <template is="dom-repeat" items="[[model]]">
            <template is="dom-if" if="[[item.isArrayHeader]]">
              <section class="tr">
                <div class="td param-type subheader">Array of [[item.type]] items</div>
                <div class="td param-type subheader subheader-empty-cell"></div>
              </section>
            </template>
            <template is="dom-if" if="[[item.isUnionSelector]]">
              <section class="tr">
                <div class="td param-name">
                  <paper-dropdown-menu label="Union variant">
                    <paper-listbox class="dropdown-content" selected="{{selectedUnion}}" data-action="toggle-type">
                      <template is="dom-repeat" items="[[item.options]]" as="union">
                        <paper-item data-type$="[[union.index]]">[[union.label]]</paper-item>
                      </template>
                    </paper-listbox>
                  </paper-dropdown-menu>
                </div>
                <div class="td param-desc"></div>
              </section>
            </template>
            <template is="dom-if" if="[[item.isProperyItem]]">
              <section class="tr" data-parent$="[[item.dataParent]]" hidden$="[[item.isHidden]]" subproperty$="[[item.isSubproperty]]" has-children$="[[item.hasChildren]]">
                <div class="td param-name">
                  <div class="name" child$="[[item.isSubproperty]]">
                    <template is="dom-if" if="[[item.withParent]]">
                      <span class="parent-prefix">[[item.parentDisplayValue]]</span>
                      <span>[[item.nameDisplayValue]]</span>
                    </template>
                    <template is="dom-if" if="[[!item.withParent]]">[[item.nameDisplayValue]]</template>
                  </div>
                  <span class="type-label">[[item.typeDisplay]]</span>
                  <template is="dom-if" if="[[item.required]]">
                    <span class="required-label">Required</span>
                  </template>
                  <template is="dom-if" if="[[item.hasEnum]]">
                    <span class="enum-label">Enum</span>
                  </template>
                </div>
                <div class="td param-desc">
                  <raml-type-property-description item="[[item]]" narrow="[[narrow]]"></raml-type-property-description>
                </div>
              </section>
            </template>
          </template>
        </div>
      </div>
    </template>
  </template>
  <script>
  (function() {
  Polymer({
    is: 'docs-json-parameters-table',

    behaviors: [RamlBehaviors.DocsParametersBehavior],

    properties: {
      /**
       * A RAML's type definition for the body payload.
       */
      type: Object,
      // True if `type` is set
      hasType: {
        type: Boolean,
        computed: '_computeHasType(type.*)',
        value: false,
        notify: true
      },
      // Computed value, will be set to `true` if current type contains a
      // schema definition.
      isSchema: {
        type: Boolean,
        computed: '_computeIsSchema(type)'
      },
      // If true then the schema / sxamples section is displayed.
      structureDisplayOpened: {
        type: Boolean,
        value: true
      },

      // If true then the narrow layout is applied.
      narrow: {
        type: Boolean,
        reflectToAttribute: true
      },
      /**
       * Generated data model for the view.
       */
      model: Array,
      /**
       * Selected union type if the object is a type of union.
       */
      selectedUnion: {
        type: Number,
        value: 0
      },
      /**
       * Computed property, true when the table can be rendered
       */
      renderTable: {
        type: Boolean,
        readOnly: true
      }
    },

    observers: [
      '_generateModel(hasType, type.*)',
      '_selectedUnionChanged(selectedUnion, model)',
      '_updateUiVariables(hasType, isSchema)'
    ],

    /**
     * Compytes main flow variables that controll what is visible.
     */
    _updateUiVariables: function(hasType, isSchema) {
      this._setRenderTable(!isSchema && hasType);
    },

    _computeHasType: function(record) {
      if (!record.base) {
        return false;
      }
      var object = record.base;
      if (object.schema) {
        return !!object.schemaContent;
      }
      switch (object.type) {
        case 'array':
          return !!object.items;
        case 'union':
          return !!(object.anyOf && object.anyOf.length);
        case 'json':
          return !!(object.content);
        default:
          var props = object.properties;
          return !!(props && Object.keys(props).length);
      }
    },
    // Computes `isSchema` value for given type.
    _computeIsSchema: function(object) {
      if (!object) {
        return false;
      }
      if (object.schema) {
        return true;
      }
      if (object.type === 'json') {
        return true;
      }
      return false;
    },
    /**
     * Generates a model for the view.
     * Called automatically when `hasType` or `type` change.
     */
    _generateModel: function(hasType, record) {
      var type = record && record.base;
      if (!hasType || !type) {
        return;
      }
      this.debounce('body-params-table-render', function() {
        var model = this.__computeModel(type, undefined, []);
        this.set('model', model);
      }.bind(this), 100);
    },
    /**
     * Computes a model for each item in the type.
     * Creates a flat sctructure of a table. Each element is a row element.
     * This recursively walking through objects properties and creates display
     * structure.
     *
     * @param {any} object Currenlty iterated object
     * @param {?Object} opts Additional options for current item.
     * @param {?Object} model An array where results are appended.
     */
    __computeModel: function(object, opts, model) {
      if (!object) {
        return;
      }
      model = model || [];
      opts = opts || {};

      var i;
      var len;
      var property;
      var options;
      var list;
      var modelItem;
      if (this.baseTypes.indexOf(object.type) !== -1 &&
        object.type !== 'object' && object.type !== 'array') {
        modelItem = this.__createModelForItem(object, opts);
        model.push(modelItem);
        return model;
      }

      if (object.properties && object.properties.length) {
        for (i = 0, len = object.properties.length; i < len; i++) {
          property = object.properties[i];
          if (property.type === 'union') {
            if (property.anyOf.length) {
              this._processUnionProperty(property, model, opts);
            }
            continue;
          }
          list = this.__handleModelProperty(property, opts);
          if (list) {
            model = model.concat(list);
          }
        }
      }

      if (object.items && object.items.properties && object.items.properties.length) {
        var isEmptyTable = (model.length === 0 && (!opts || !opts.parent));
        if (isEmptyTable) {
          modelItem = this.__createModelForArrayHeader(object, opts);
          model.push(modelItem);
          // Forces children to render a parent as "item."
          var currentCopy = Object.assign({}, object);
          currentCopy.displayName = 'item';
          options = Object.assign({}, opts, {
            parent: currentCopy
          });
        } else {
          modelItem = this.__createModelForItem(object, opts);
          model.push(modelItem);
          options = Object.assign({}, opts, {
            parent: object
          });
        }
        for (i = 0, len = object.items.properties.length; i < len; i++) {
          property = object.items.properties[i];
          list = this.__handleModelProperty(property, options);
          if (list) {
            model = model.concat(list);
          }
        }
      }
      if (object.type === 'union') {
        if (!object.anyOf.length) {
          return model;
        }
        this._processUnionProperty(object, model, opts);
      }
      return model;
    },

    _processUnionProperty: function(object, model, opts) {
      if (!object.anyOf.length) {
        return;
      }
      opts = opts || {};
      var modelItem = this.__createModelForUnion(object.anyOf);
      model.push(modelItem);
      for (var i = 0, len = object.anyOf.length; i < len; i++) {
        for (var j = 0, pLen = object.anyOf[i].properties.length; j < pLen; j++) {
          var property = object.anyOf[i].properties[j];
          var options = {
            inUnion: true,
            parent: opts.parent || object,
            variantIndex: i,
            childIndex: j
          };
          var list = this.__handleModelProperty(property, options);
          if (list && list.length) {
            for (var k = 0, kLen = list.length; k < kLen; k++) {
              model.push(list[k]);
            }
          }
        }
      }
    },

    /**
     * Creates a model for object / array / union property.
     *
     * @param {Object} property A property to evaluate.
     * @param {?Object} opts Item's options.
     * @return {Array} List of generated model items.
     */
    __handleModelProperty: function(property, opts) {
      opts = opts || {};
      var model = [];

      var hasChildren = false;
      if (property.properties || property.items || (property.items && typeof property.items !== 'string') || property.anyOf) {
        hasChildren = true;
      }
      var options;
      var modelItem = this.__createModelForItem(property, opts);
      model.push(modelItem);

      if (hasChildren) {
        var list;
        var children = property.properties || property.items || (property.items && property.items.properties) || property.anyOf;
        var childrenType = typeof children;
        if (!children.type && childrenType !== 'string') {
          children = this.readProperties(children);
        }
        if (children instanceof Array) {
          for (var j = 0, cLen = children.length; j < cLen; j++) {
            options = Object.assign({}, opts, {
              parent: property,
              hasChildren: hasChildren
            });
            list = this.__computeModel(children[j], options);
            if (list) {
              model = model.concat(list);
            }
          }
        } else if (typeof children === 'string') {
          modelItem.typeDisplay = 'Array[' + children + ']';
        } else {
          if (children.type === 'any' && !children.enum) {
            return model;
          }
          if (children.name !== (property.name || property.key)) {
            options = Object.assign({}, opts, {
              parent: property,
              hasChildren: hasChildren
            });
            list = this.__computeModel(children, options);
            if (list) {
              model = model.concat(list);
            }
          }
        }
      }
      return model;
    },
    /**
     * Creates a model for a regular property item.
     */
    __createModelForItem: function(item, opts) {
      opts = opts || {};
      if (typeof item === 'string') {
        return;
      }
      item = Object.assign({}, item);
      if (opts.hasChildren) {
        item.hasChildren = true;
      } else {
        item.hasChildren = false;
      }
      var fillParentInfo = true;
      if (opts.inUnion) {
        item.dataParent = opts.variantIndex;
        item.isHidden = true;
        if (opts.parent.anyOf) { //[opts.variantIndex].properties[opts.childIndex] === item
          item.nameDisplayValue = item.name || item.key || item.displayName;
          item.withParent = false;
          fillParentInfo = false;
        }
      }
      if (opts.parent) {
        if (fillParentInfo) {
          item.isSubproperty = true;
          item.nameDisplayValue = item.name || item.key || item.displayName;
          item.parentDisplayValue = opts.parent.displayName || opts.parent.name || opts.parent.key;
          item.withParent = true;
        }
      } else {
        item.nameDisplayValue = item.name || item.key || item.displayName;
        item.withParent = false;
      }
      if (item.type === 'array') {
        item.typeDisplay = 'Array';
      } else if (item.type === 'any' && item.enum) {
        item.typeDisplay = 'Enum';
      } else {
        item.typeDisplay = item.type;
      }

      item.hasDisplaName = this._hasDisplayName(item);
      item.hasExamples = this._hasExamples(item);
      if (item.hasExamples) {
        item.example = this._getExamples(item);
      }
      item.hasMinimum = this._hasMinimum(item);
      if (item.hasMinimum) {
        item.minimum = this._getMinimum(item);
      }
      item.hasMaximum = this._hasMaximum(item);
      if (item.hasMaximum) {
        item.maximum = this._getMaximum(item);
      }
      item.hasEnum = this.hasValue(item.enum);
      if (item.hasEnum) {
        item.enum = this._computeEnumValue(item.enum);
      }
      item.hasAnnotations = this.hasValue(item.annotations);
      item.isArrayHeader = false;
      item.isProperyItem = true;
      item.isUnionSelector = false;
      return item;
    },
    /**
     * Creates a model item for an array resource which have first element
     * described as an array.
     */
    __createModelForArrayHeader: function(item) {
      var type;
      if (typeof item.items === 'string') {
        type = item.items;
      }
      if (!type) {
        type = item.items.name || item.items.type || 'any';
      }
      return {
        isArrayHeader: true,
        isProperyItem: false,
        isUnionSelector: false,
        type: type
      };
    },

    __createModelForUnion: function(anyOf) {
      if (!anyOf) {
        console.warn('Trying to invoke row for union but number is not set');
        return [];
      }
      var options = [];
      for (var i = 0, len = anyOf.length; i < len; i++) {
        var item = anyOf[i];
        var label;
        if (item.displayName) {
          label = item.displayName;
        } else {
          label = 'Variant ' + (i + 1);
        }
        options.push({
          index: i,
          label: label
        });
      }
      return {
        isArrayHeader: false,
        isProperyItem: false,
        isUnionSelector: true,
        options: options
      };
    },

    _selectedUnionChanged: function(selectedUnion, model) {
      if (!model || selectedUnion === undefined) {
        return;
      }
      model.forEach(function(item, i) {
        if (!item.isProperyItem || item.dataParent === undefined) {
          return;
        }
        if (item.dataParent === selectedUnion) {
          if (model[i].isHidden) {
            this.set(['model', i, 'isHidden'], false);
          }
        } else {
          if (!model[i].isHidden) {
            this.set(['model', i, 'isHidden'], true);
          }
        }
      }, this);
    }
  });
  })();
  </script>
</dom-module>