Added @modifiers annotation (#32)

* Added config for alternative placeholder service

* Added the @modifiers annotation to atoms, molecules; and structures

* Check for null modifier annotations

* Fixed incorrect @return DOCBLOCK

assets/styles/atoms/typography.scss

@@ -3,6 +3,7 @@
 // Copyright (C) 2016 Michael Seibt
 //
 // With contributions from: -
+//  - Ryan Potter (www.ryanpotter.co.nz)
 //
 // This software may be modified and distributed under the terms
 // of the MIT license. See the LICENSE file for details.
@@ -51,6 +52,12 @@
   border-bottom: 1px dashed $color--light-gray;
 }
 
+.SG-h5 {
+  color: $color--dark-gray;
+  font-size: 14px;
+  margin: 1em 0;
+}
+
 /**
  * Generic paragraph style for medium to long blocks of text. This element
  * is using the @{lipsum} substitution to generate two blocks of text.

assets/views/common/components.pug

@@ -4,6 +4,7 @@
  * Copyright (C) 2016 Michael Seibt
  *
  * With contributions from: -
+ *  - Ryan Potter (www.ryanpotter.co.nz)
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
@@ -80,6 +81,22 @@ mixin component(component)
           div.SG-gr-12.SG-component__preview(class=meta.namespace)
             | !{component.markup}
 
+    -if (component.modifiers)
+      div.SG-row
+        div.SG-gr-12
+          h4.SG-h5 #{component.name} Modifiers
+          div.SG-row.SG-table
+            div.SG-gr-3
+              div.SG-table__head.SG-table__cell Modifier
+            div.SG-gr-9
+              div.SG-table__head.SG-table__cell Description
+          each val in component.modifiers
+            div.SG-row.SG-table
+              div.SG-gr-3
+                div.SG-table__cell= val.class
+              div.SG-gr-9
+                div.SG-table__cell= val.description || ''
+
     -if (component.markup)
       div.SG-row
         div.SG-gr-12.SG-nogutter

docs/src/views/annotation-reference.pug

@@ -47,10 +47,10 @@ block content
      * @section Style Mixins
      * @param $radius This could be single line ...
      * @param $color
-     *   Or multi-line, you decide!
+     *  Or multi-line, you decide!
      * @example
-     *   @include brc(3px);
-     *   @include brc(3px, $color--red);
+     *  @include brc(3px);
+     *  @include brc(3px, $color--red);
      */
     @mixin brc($radius, $color = '#333') {
       /* ... */
@@ -65,13 +65,15 @@ block content
     /**
      * @atom Button
      * @section Navigation > Buttons
+     * @modifiers
+     *  .button--alert an alert button
      * @markup
-     *   <button class="button">
-     *     A button
-     *   </button>
-     *   <button class="button button--alert">
-     *     An alert button
-     *   </button>
+     *  <button class="button">
+     *    A button
+     *  </button>
+     *  <button class="button button--alert">
+     *    An alert button
+     *  </button>
      */
     .button {
      /* ... */

docs/src/views/common/menu.pug

@@ -8,6 +8,7 @@ nav.menu.SG-toc
         li: a.SG-a(href="getting-started.html") Getting Started
         li: a.SG-a(href="annotation-reference.html") Annotation reference
         li: a.SG-a(href="substitutions-flags.html") Substitutions & Flags
+        li: a.SG-a(href="modifiers.html") Modifiers
         li: a.SG-a(href="vendored-elements.html") Vendored elements
 
         li.SG-toc__category Meta

docs/src/views/getting-started.pug

@@ -31,6 +31,8 @@ block content
      * @section Navigation > Buttons
      * @description
      *  Buttons for various purposes.
+     * @modifiers
+     *  .button--alert an alert button
      * @markup
      *   <button class="button">A button</button>
      *   <button class="button button--alert">

docs/src/views/modifiers.pug

@@ -0,0 +1,29 @@
+extends layouts/doc-page
+
+block title
+  | Modifiers
+
+block content
+  h1.SG-h1 Modifiers
+  p.SG-p.
+    For listing variations of blocks/elements @modifiers are available to use on certain elements.
+
+  p.SG-p.
+    For example, if you have modifiers for an element that you need to document, but don't necessarily want to display in the @markup.
+
+  code.code.language-nucleus(data-d-code-preview).
+    /**
+     *
+     *
+     * @atom Button
+     * @modifiers
+     *  .btn--primary for use in positive flows
+     *  .btn--secondary for use in alternative flows
+     * @markup
+     *  ...
+     */
+    .btn {
+      ...
+      &--primary { /* ... */ }
+      &--secondary { /* ... */ }
+    }

src/Crawler.js

@@ -3,6 +3,7 @@
  * Copyright (C) 2016 Michael Seibt
  *
  * With contributions from: -
+ *  - Ryan Potter (www.ryanpotter.co.nz)
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
@@ -17,7 +18,7 @@ var syntax = require('postcss-scss');
 var Crawler = {};
 
 /**
- * Reads the files content and returnes the parsed styleguide information.
+ * Reads the files content and returns the parsed styleguide information.
  *
  * @param  {string} file
  *         Filename

src/Transform.js

@@ -3,6 +3,7 @@
  * Copyright (C) 2016 Michael Seibt
  *
  * With contributions from: -
+ *  - Ryan Potter (www.ryanpotter.co.nz)
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
@@ -42,7 +43,7 @@ Transform.forView = function(styles) {
     var entity = this.createEntity(style);
 
     // If entity is empty, we cold not specify a type or
-    // validation failed during entity instanciation.
+    // validation failed during entity instantiation.
     if (!entity || (Object.keys(entity).length === 0)) {
       continue;
     }
@@ -98,7 +99,7 @@ Transform.getStyleType = function(style) {
 };
 
 /**
- * Returns wheather a style has a given annotation.
+ * Returns whether a style has a given annotation.
  *
  * @param  {string}  key
  * @param  {object}  style

src/entities/Atom.js

@@ -3,6 +3,7 @@
  * Copyright (C) 2016 Michael Seibt
  *
  * With contributions from: -
+ *  - Ryan Potter (www.ryanpotter.co.nz)
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
@@ -12,13 +13,13 @@
 
 var Entity = require('./Entity');
 
-var Atom = function(raw) {
+var Atom = function (raw) {
   // Call parent constructor
   Entity.call(this, raw);
 
   // Set atom-specific entity properties
-  this.type = "Atom";
-  this.fillable = ['atom', 'section', 'description', 'markup', 'deprecated'];
+  this.type     = "Atom";
+  this.fillable = ['atom', 'section', 'description', 'modifiers', 'markup', 'deprecated'];
 
   // Validate the raw input data for common mistakes
   if (!this.validate()) return {};
@@ -29,6 +30,7 @@ var Atom = function(raw) {
     type: 'atom',
     section: 'Atoms > ' + this.getSection(),
     description: raw.annotations.description,
+    modifiers: this.getModifiers(),
     markup: raw.annotations.markup,
     deprecated: raw.annotations.deprecated,
     location: 'atoms.html',

src/entities/Entity.js

@@ -3,6 +3,7 @@
  * Copyright (C) 2016 Michael Seibt
  *
  * With contributions from: -
+ *  - Ryan Potter (www.ryanpotter.co.nz)
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
@@ -26,7 +27,7 @@ var Entity = function(raw) {
 /**
  * Checks the incoming raw style data for common mistakes.
  *
- * @return {book}
+ * @return {bool}
  *         Returns true if the style is solid enough for further processing.
  */
 Entity.prototype.validate = function() {
@@ -94,7 +95,7 @@ Entity.prototype.getSection = function() {
 };
 
 /**
- * Returns the name of the element the entity referes to. This could be a
+ * Returns the name of the element the entity refers to. This could be a
  * selector, a property or a mixin.
  *
  * @return {string}
@@ -106,6 +107,48 @@ Entity.prototype.getDescriptor = function() {
     this.raw.element.params || 'unknown' : 'unknown';
 };
 
+/**
+ * Returns an array based on new lines for formatting.
+ *
+ * @returns {*}
+ */
+Entity.prototype.getModifiers = function () {
+  // Check for a modifier annotation.
+  if (typeof this.raw.annotations.modifiers !== 'undefined' && this.raw.annotations.modifiers !== null) {
+    const modifiers        = this.raw.annotations.modifiers;
+    const modifiersArray   = modifiers.split('\n');
+    let formattedModifiers = []; // the container array for final output.
+    /**
+     * Loop through the modifier annotation, and
+     * return the class names and descriptions as
+     * an array for formatting.
+     */
+    modifiersArray.map((value) => {
+      let modifier;
+      /**
+       * Check if the modifier has any white space
+       * (has a description). Return the appropriate object
+       * for formatting.
+       */
+      if (value.indexOf(' ') >= 0) {
+        modifier = {
+          class: value.substr(0, value.indexOf(' ')),
+          description: value.substr(value.indexOf(' ') + 1),
+        };
+      } else {
+        modifier = {
+          class: value,
+          description: null,
+        };
+      }
+      // Add to the output array.
+      formattedModifiers.push(modifier);
+    });
+    return formattedModifiers;
+  }
+  return null;
+};
+
 Entity.prototype.hash = function() {
   return hash.digest(this.raw.annotations);
 };

src/entities/Molecule.js

@@ -3,10 +3,12 @@
  * Copyright (C) 2016 Michael Seibt
  *
  * With contributions from: -
+ *  - Ryan Potter (www.ryanpotter.co.nz)
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
  */
+
 'use strict';
 
 var Entity = require('./Entity');
@@ -17,7 +19,7 @@ var Molecule = function(raw) {
 
   // Set molecule-specific entity properties
   this.type = "Molecule";
-  this.fillable = ['molecule', 'section', 'description', 'markup', 'deprecated'];
+  this.fillable = ['molecule', 'section', 'description', 'modifiers', 'markup', 'deprecated'];
 
   // Validate the raw input data for common mistakes
   if (!this.validate()) return {};
@@ -28,6 +30,7 @@ var Molecule = function(raw) {
     descriptor: raw.descriptor,
     section: 'Molecules > ' + this.getSection(),
     description: raw.annotations.description,
+    modifiers: this.getModifiers(),
     markup: raw.annotations.markup,
     deprecated: raw.annotations.deprecated,
     hash: this.hash(),

src/entities/Structure.js

@@ -3,6 +3,7 @@
  * Copyright (C) 2016 Michael Seibt
  *
  * With contributions from: -
+ *  - Ryan Potter (www.ryanpotter.co.nz)
  *
  * This software may be modified and distributed under the terms
  * of the MIT license. See the LICENSE file for details.
@@ -18,7 +19,7 @@ var Structure = function(raw) {
 
   // Set structure-specific entity properties
   this.type = "Structure";
-  this.fillable = ['structure', 'section', 'description', 'markup', 'flag', 'deprecated'];
+  this.fillable = ['structure', 'section', 'description', 'modifiers', 'markup', 'flag', 'deprecated'];
 
   // Validate the raw input data for common mistakes
   if (!this.validate()) return {};
@@ -29,6 +30,7 @@ var Structure = function(raw) {
     descriptor: raw.descriptor,
     section: 'Structures > ' + this.getSection(),
     description: raw.annotations.description,
+    modifiers: this.getModifiers(),
     markup: raw.annotations.markup,
     deprecated: raw.annotations.deprecated,
     flags: this.getFlags(),

test/Atom.test.js

@@ -41,6 +41,7 @@ describe('Atom', function() {
         location: 'atoms.html',
         section: 'Atoms > Other',
         description: 'A test description',
+        modifiers: null,
         markup: '...',
         deprecated: false
     });
@@ -69,6 +70,7 @@ describe('Atom', function() {
         location: 'atoms.html',
         section: 'Atoms > Other',
         description: 'A test description',
+        modifiers: null,
         markup: '...',
         deprecated: true
     });