px-sass-doc-viewer.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-element.html"/>
<link rel="import" href="../polymer/lib/elements/dom-if.html"/>
<link rel="import" href="../polymer/lib/elements/dom-repeat.html"/>
<link rel="import" href="../polymer/lib/utils/flattened-nodes-observer.html"/>
<link rel="import" href="../marked-element/marked-element.html"/>
<link rel="import" href="../prism-element/prism-highlighter.html"/>
<link rel="import" href="../prism-element/prism-theme-default.html"/>
<link rel="import" href="prism-extended-theme.html"/>
<link rel="import" href="../iron-ajax/iron-ajax.html"/>
<link rel="import" href="../iron-collapse/iron-collapse.html"/>
<link rel="import" href="../px-clipboard/px-clipboard.html"/>
<link rel="import" href="../px-icon-set/px-icon-set-utility.html"/>
<link rel="import" href="../px-icon-set/px-icon.html"/>
<link rel="import" href="css/px-sass-doc-viewer-styles.html"/>
<link rel="import" href="css/px-demo-styles.html"/>

<!--
Element providing documentation for a requested Predix UI Sass component (design library).

##### Usage

      <px-sass-doc-viewer
        library-name="px-toggle-design"
        layer="objects"
        inuit-flags='["$inuit-enable-toggle--small","$inuit-enable-toggle--large","$inuit-enable-toggle--huge"]'
        style-variables='["$inuit-toggle-color","$inuit-toggle-background","$inuit-toggle-border","$inuit-toggle-switch","$inuit-toggle-switch-border","$inuit-toggle-switch-shadow","$inuit-toggle-background--on","$inuit-toggle-border--on"]'
        dependencies='["https://github.com/PredixDev/px-colors-design","https://github.com/PredixDev/px-defaults-design","https://github.com/PredixDev/px-helpers-design"]'>
      </px-sass-doc-viewer>

@element px-sass-doc-viewer
@blurb Element providing documentation for a requested Predix UI Sass component (design library).
-->

<dom-module id="px-sass-doc-viewer">
  <template>
    <style include="prism-theme-default"></style>
    <style include="px-sass-doc-viewer-styles"></style>
    <style include="px-demo-styles"></style>
    <style>
      .arrow--small {
        --iron-icon-height: 16px;
        --iron-icon-width: 16px;
      }
      .arrow--inactive {
        transform: rotate(-90deg);
      }
    </style>

    <prism-highlighter></prism-highlighter>
    <iron-ajax
        auto
        url="[[_getSassdocPath(importPath, sassdocPath, libraryName)]]"
        handle-as="json"
        last-response="{{_sassdocJson}}">
    </iron-ajax>

    <div class="demo-background--api">
      <div class="flex flex--col demo-layout--center u-pt++ u-pb++" >
        <div style="display:none" id="incomingMarkdown">
          <!-- Previously: <content select="[data-slot=intro]" ...> -->
          <slot name="intro"></slot>
          <!-- Previously: <content select="[data-slot=usage]" ...> -->
          <slot name="usage"></slot>
        </div>

        <div class="demo-background--api">
          <div class="flex flex--col api">

            <section>
              <slot name="intro-raw"></slot>
            </section>

            <template is="dom-if" if="[[_has(_introMarkdown)]]">
              <section>
                <marked-element markdown="[[_introMarkdown]]">
                  <div slot="markdown-html" class="markdown-html"></div>
                </marked-element>
              </section>
            </template>

            <!-- 1. INSTALLATION INSTRUCTIONS -->
            <section>
              <div class="delta u-mt++ u-mb">Install the module</div>
              <p>To use the {{baseName}} module, you need to install it in your project using Bower. Run this task on the command line from inside your project folder:</p>

              <px-clipboard copy-from="#install">
                <marked-element markdown="[[_getInstallCodeMarkdown(libraryName)]]">
                  <div slot="markdown-html" class="markdown-html" id="install"></div>
                </marked-element>
              </px-clipboard>
            </section>
            <!-- 1. END INSTALLATION INSTRUCTIONS -->

            <!-- 2. IMPORT SASS INSTRUCTIONS -->
            <template is="dom-if" if="[[!hideImportSass]]">
              <section>
                <div class="delta u-mt++ u-mb">Import it in your Sass</div>
                <p>The [[baseName]] module won't do anything until you import and configure it in your project Sass file. Follow these steps to import it:</p>

                <!-- 2.1 ENABLE FLAGS -->
                <h4 class="epsilon u-pt-">1. Enable Flags</h4>
                <template is="dom-if" if="[[_hasAnyFlags(inuitFlags, _sassdocInuitFlags)]]">
                  <p>You can turn on flags to generate additional styles defined in the [[baseName]] module. To generate new styles, set any of these flags to true above the module's <code class="code code--inline">@import</code> statement in your project Sass file:</p>
                </template>
                <template is="dom-if" if="[[!_hasAnyFlags(inuitFlags, _sassdocInuitFlags)]]">
                  <p>No flags to set</p>
                </template>

              <!-- If an array of inuit flags were passed in directly, parse and display here -->
              <template is="dom-if" if="[[_has(inuitFlags)]]">
                <px-clipboard copy-from="#enable">
                  <figure class="code u-mr-">
                    <code id="install">
                      <template is="dom-repeat" items="{{inuitFlags}}">
                        [[item]] : true;<br/>
                      </template>
                    </code>
                  </figure>
                </px-clipboard>
              </template>

              <!-- If an array of inuit flags were generated from Sassdoc, parse and display here -->
              <template is="dom-if" if="[[_has(_sassdocInuitFlags)]]">
                <ul class="list-ui list-ui--small u-mv+">
                  <template is="dom-repeat" items="{{_sassdocInuitFlags}}">
                    <li class="list-ui__item">
                      <span class="actionable">
                        <px-icon class$="arrow--small clickable [[_getFlagArrowClassName(item, _openedFlags)]]" icon="px-utl:chevron" data-toggle="{{item.context.name}}" on-tap="_toggleFlag"></px-icon>
                        <span on-tap="_toggleFlag" data-toggle="{{item.context.name}}" class="clickable">${{item.context.name}}</span>
                      </span>
                      <iron-collapse id="{{item.context.name}}-container" no-animation opened="[[_isFlagOpened(item, _openedFlags)]]">
                        <div class="sass-variable-details">
                          <p class="u-mt">{{item.description}}</p>
                          <p>
                            <small class="caps muted weight--light">Type: {{item.type}}</small>
                            <br /><small class="caps muted weight--light">Default Value: {{item.context.value}}</small>
                          </p>
                          <px-clipboard copy-from="#{{item.context.name}}-code">
                            <figure class="code u-mr-">
                              <code id="{{item.context.name}}-code">
                                ${{item.context.name}} : true;<br />
                                {{_importCode}}
                              </code>
                            </figure>
                          </px-clipboard>
                        </div>
                      </iron-collapse>
                    </li>
                  </template>
                </ul>
              </template>
              <!-- END 2.1 ENABLE FLAGS -->

              <!-- 2.3 IMPORT SASS -->
              <h4 class="epsilon u-pt-">2. Import Sass File</h4>
              <p>Import the module by placing this code into the <strong>{{layer}}</strong> layer of your project Sass file: <a href="https://github.com/PredixDev/px-getting-started#import-order" class="actionable actionable--action" target="_blank"><px-icon icon="px-utl:help" class="u-mh--" style="width:1rem"></px-icon>What's this?</a></p>

              <px-clipboard copy-from="#import2">
                <marked-element markdown="[[_toScssMarkdown(_importCode)]]">
                  <div slot="markdown-html" class="markdown-html" id="import2"></div>
                </marked-element>
              </px-clipboard>
            <!-- END 2.3 IMPORT SASS -->

            </section>
          </template>
          <!-- END 2. IMPORT SASS INSTRUCTIONS -->

          <!-- 3. USAGE -->
          <template is="dom-if" if="[[_has(_usageMarkdown)]]">
            <section>
              <div class="delta u-mt++ u-mb">Use it in your project</div>

              <marked-element markdown="[[_usageMarkdown]]">
                <div slot="markdown-html" class="markdown-html"></div>
              </marked-element>
            </section>
          </template>
          <!-- END 3. USAGE -->


          <!-- 4. CUSTOMIZE MODULE -->
          <section class="u-mb">
            <div class="delta u-mt++ u-mb">Customize Styles</div>
            <template is="dom-if" if="[[!_has(_sassdocStyleVariables)]]">
              <p>No customizable variables.</p>
            </template>
            <template is="dom-if" if="[[_has(_sassdocStyleVariables)]]">
              <p>You can change style variables to customize the design of the {{baseName}} module. To change styles directly in Sass,
                 set any of the Sass variables below to a new value <strong>above</strong> the module's <code class="code code--inline">@import</code>
                 statement in your project's Sass file. To change the style in your application's CSS, use the CSS variables instead.
                 Note that if you have set both a CSS and a Sass variable for the same attribute, the CSS variable will take precedence over the Sass variable. </p>
              <table class="table">
                <tr>
                  <th>Sass Variable</th>
                  <th>CSS Variable</th>
                  <th>Description</th>
                </tr>
                <template is="dom-repeat" items="{{_sassdocStyleVariables}}">
                  <tr>
                    <td>$[[item.context.name]]</td>
                    <td>{{item.todo}}</td>
                    <td>{{item.description}}</td>
                  </tr>
                </template>
              </table>
            </template>
          </section>
          <!-- END 4. CUSTOMIZE MODULE -->

          <!-- 5. DEPENDENCIES -->
          <section class="u-mb++">
            <div class="delta u-mt++ u-mb">Dependencies</div>
            <template is="dom-if" if="[[_has(dependencies)]]">
              <p>This module depends on the following modules (automatically included with Bower install):
                <ul class="list-bare">
                  <template is="dom-repeat" items="{{dependencies}}">
                    <li><a class="actionable" href="{{item}}" target="_blank">{{item}}</a></li>
                  </template>
                </ul>
              </p>
            </template>
            <template is="dom-if" if="[[!_has(dependencies)]]">
              <p>This module doesn't have any dependencies.</p>
            </template>
          </section>
          <!-- END 5. DEPENDENCIES -->
          </div>
        </div>
      </div>
    </div>
  </template>
</dom-module>

<script>
  class PxSassDocViewer extends Polymer.Element {
    static get is() { return 'px-sass-doc-viewer'; }

    static get properties() {
      return {
        /**
         * Name of the documented Sass module.
         */
        libraryName: {
          type: String,
          value: ''
        },

        /**
         * Inuit flags exposed by the Sass module. Optional — passing in
         * a Sassdoc JSON file will generate the inuit flags automatically.
         * Format as array of strings with the name of each flag.
         */
        inuitFlags: {
          type: Array,
          value: () => []
        },

        /**
         * ITCSS layer that this component belongs in.
         * Examples: generic, objects, trumps
         */
        layer: {
          type: String,
          value: ''
        },

        /**
         * Base name of the component in the file path.
         * Example: _objects.[baseName].scss
         */
        baseName: {
          type: String,
          value: ''
        },

        /**
         * Sass modules needed to use the one being documented. Format as array
         * of strings. Each entry should be the URL a dependant Sass module's
         * Github repo.
         *
         * Example:
         * ```
         * [https://github.com/PredixDev/px-colors-design"]
         * ```
         */
        dependencies: {
          type: Array,
          value: () => []
        },

        /**
         * A string of markdown-styled text passed in through the intro slot.
         * Automatically retrieved when the slot is distributed.
         */
        _introMarkdown: {
          type: String,
          value: ''
        },

        /**
         * A string of markdown-styled text passed in through the usage slot.
         * Automatically retrieved when the slot is distributed.
         */
        _usageMarkdown: {
          type: String,
          value: ''
        },

        /**
         * Computed string with the import statement for the Sass component.
         */
        _importCode: {
          type: String,
          value: '',
          computed: '_computeImportCode(libraryName, layer, baseName)'
        },

        /**
         * Path to a generated Sassdoc JSON file.
         */
        sassdocPath: {
          type: String,
          value: ''
        },

        /**
         * Raw Sassdoc JSON, automatically loaded by iron-ajax from `sassdocPath`.
         */
        _sassdocJson: {
          type: Array,
          value: () => []
        },

        /**
         * Style variables computed from the raw Sassdoc JSON.
         */
        _sassdocStyleVariables: {
          type: Array,
          value: () => [],
          computed: '_computeSassdocStyleVariables(_sassdocJson)'
        },

        /**
         * Inuit flags computed from the raw Sassdoc JSON.
         */
        _sassdocInuitFlags: {
          type: Array,
          value: () => [],
          computed: '_computeSassdocInuitFlags(_sassdocJson)'
        },

        /**
         * Set to true to hide the "Import in your Sass" instructions
         */
        hideImportSass: {
          type: Boolean,
          value: false
        },

        /**
         * Array of opened inuit flags. When the user taps on a flag name
         * it will be added to this list, triggering the flag's accordion
         * to open and arrow to rotate downward.
         */
        _openedFlags: {
          type: Array,
          value: () => []
        }
      };
    }

    connectedCallback() {
      super.connectedCallback();
      this._observer = new Polymer.FlattenedNodesObserver(this.$.incomingMarkdown, (info) => {
        this._processNewNodes(info.addedNodes);
      });
    }

    disconnectedCallback() {
      super.disconnectedCallback();
      this._observer.disconnect();
    }

    _processNewNodes(nodes) {
      let elements = nodes.filter(n => n.nodeType === Node.ELEMENT_NODE);
      elements.forEach(el => {
        if (el.slot && el.slot === 'intro') {
          this._introMarkdown = el.innerHTML;
        }
        if (el.slot && el.slot === 'usage') {
          let usageMarkup = el.innerHTML
            // Remove any instance of `class="style-scope *-demo"`
            .replace(/class\=\"style\-scope .*\-demo\"/g,'')
            // Strip `style-scope` and  `*-demo` from other `class` attributes
            .replace(/class\=\"(.*) style-scope .*\-demo\"/g,'class="$1"')
            // Strip the inserted class attribute and lightDOM content from the px-actionable-design demo
            .replace(/ class\=\"style-scope px-actionable-design-demo x-scope px-icon-1\"/g,'')
            .replace(/[\s]*<iron-icon.*[\s]*<\/iron-icon>[\s]*/g,'');
          this._usageMarkdown = el.innerHTML;
        }
      });
    }

    /**
     * Checks if `o` has length. `o` could be an Array, string, or any value
     * with a length property.
     */
    _has(o) {
      return o.length && o.length > 0;
    }

    /**
     * Checks to see if any inuit flags are defined (passed in through a property
     * or pulled from Sassdoc).
     */
    _hasAnyFlags(userDefinedFlags, sasdocDefinedFlags) {
      return (Array.isArray(userDefinedFlags) && userDefinedFlags.length) ||
        (Array.isArray(sasdocDefinedFlags) && sasdocDefinedFlags.length);
    }

    _computeSassdocInuitFlags(sassdoc) {
      if (Array.isArray(sassdoc)) {
        return sassdoc.filter(item =>
          item.group && item.group.length && item.group[0].indexOf('variables:flag') > -1
        );
      }
    }

    _computeSassdocStyleVariables(sassdoc) {
      if (Array.isArray(sassdoc)) {
        return sassdoc.filter(item =>
          item.group && item.group.length && item.group[0].indexOf('variables:style') > -1
        );
      }
    }

    _computeImportCode(library, layer, base) {
      if (typeof library === 'string' && typeof layer === 'string' && typeof base === 'string') {
        return `@import "${library}/_${layer}.${base}.scss";`
      }
    }

    _toScssMarkdown(code) {
      if (typeof code !== 'string') return;
      return '```scss\n' + code + '\n```';
    }

    _getInstallCodeMarkdown(libraryName) {
      return '```bash\n' + `bower install ${libraryName} --save-dev` + '\n```';
    }

    _getSassdocPath(importPath, sassdocPath, libraryName) {
      if (!importPath || !sassdocPath || !libraryName) return;
      let base = this.importPath.substr(0, this.importPath.indexOf('px-sass-doc'));
      return base + this.libraryName + '/' + sassdocPath;
    }

    _toggleFlag(evt) {
      let flag = evt.model.item;
      if (this._openedFlags.indexOf(flag) === -1) {
        this._openedFlags = this._openedFlags.concat([flag]);
      } else {
        this._openedFlags = this._openedFlags.filter(f => f !== flag);
      }
    }

    _isFlagOpened(flag, openedFlags) {
      if (!flag || !openedFlags) return false;
      return openedFlags.indexOf(flag) > -1;
    }

    _getFlagArrowClassName(flag, openedFlags) {
      return this._isFlagOpened(flag, openedFlags) ? '' : 'arrow--inactive';
    }
  }

  customElements.define('px-sass-doc-viewer', PxSassDocViewer);
</script>