Implement pattern state lowest common denominator

closes #203

Author: bmuenzenmeyer

README.md

@@ -148,12 +148,26 @@ You can set the state of a pattern by including it in `patternlab-config.json` t
 Pattern states should be lowercase and use hyphens where spaces are present.
 ```
 "patternStates": {
-	"colors" : "inprogress",
-	"fonts" : "inreview",
-	"three-up" : "complete"
+	"atoms-colors" : "complete",
+	"molecules-primary-nav" : "inreview",
+	"organisms-header" : "inprogress"
 }
 ```
 
+Note that patterns inherit the lowest common denominator pattern state of their lineage.
+Consider:
+```
+"patternStates": {
+  "molecules-single-comment" : "complete",
+  "organisms-sticky-comment" : "inreview",
+  "templates-article" : "complete"
+}
+```
+In this case, two things are of note:
+
+* templates-article will display inreview since it inherits `organisms-sticky-comment`
+* pages-article will not display any pattern state, as it does not define one
+
 ##### Pattern Export
 `patternlab-config.json` also has two properties that work together to export completed patterns for use in a production environment. Provide an array of keys and an output directory. Pattern Lab doesn't ship with any pattern export keys, but the default directory is `"./pattern_exports/"` created inside the install directory.
 

core/lib/lineage_hunter.js

@@ -12,9 +12,10 @@
 
 var lineage_hunter = function () {
 
+  var pa = require('./pattern_assembler');
+
   function findlineage(pattern, patternlab) {
 
-    var pa = require('./pattern_assembler');
     var pattern_assembler = new pa();
 
     //find the {{> template-name }} within patterns
@@ -50,7 +51,11 @@ var lineage_hunter = function () {
             "lineagePattern": ancestorPattern.key,
             "lineagePath": "../../patterns/" + ancestorPattern.patternLink
           };
-          pattern.lineage.push(JSON.stringify(l));
+          if (ancestorPattern.patternState) {
+            l.lineageState = ancestorPattern.patternState;
+          }
+
+          pattern.lineage.push(l);
 
           //also, add the lineageR entry if it doesn't exist
           if (ancestorPattern.lineageRIndex.indexOf(pattern.key) === -1) {
@@ -61,16 +66,90 @@ var lineage_hunter = function () {
               "lineagePattern": pattern.key,
               "lineagePath": "../../patterns/" + pattern.patternLink
             };
-            ancestorPattern.lineageR.push(JSON.stringify(lr));
+            if (pattern.patternState) {
+              lr.lineageState = pattern.patternState;
+            }
+
+            ancestorPattern.lineageR.push(lr);
           }
         }
       });
     }
   }
 
+  function setPatternState(direction, pattern, targetPattern) {
+    // if the request came from the past, apply target pattern state to current pattern lineage
+    if (direction === 'fromPast') {
+      for (var i = 0; i < pattern.lineageIndex.length; i++) {
+        if (pattern.lineageIndex[i] === targetPattern.key) {
+          pattern.lineage[i].lineageState = targetPattern.patternState;
+        }
+      }
+    } else {
+      //the request came from the future, apply target pattern state to current pattern reverse lineage
+      for (var i = 0; i < pattern.lineageRIndex.length; i++) {
+        if (pattern.lineageRIndex[i] === targetPattern.key) {
+          pattern.lineageR[i].lineageState = targetPattern.patternState;
+        }
+      }
+    }
+  }
+
+
+  function cascadePatternStates(patternlab) {
+
+    var pattern_assembler = new pa();
+
+    for (var i = 0; i < patternlab.patterns.length; i++) {
+      var pattern = patternlab.patterns[i];
+
+      //for each pattern with a defined state
+      if (pattern.patternState) {
+
+        if (pattern.lineageIndex && pattern.lineageIndex.length > 0) {
+
+          //find all lineage - patterns being consumed by this one
+          for (var h = 0; h < pattern.lineageIndex.length; h++) {
+            var lineagePattern = pattern_assembler.get_pattern_by_key(pattern.lineageIndex[h], patternlab);
+            setPatternState('fromFuture', lineagePattern, pattern);
+          }
+        }
+
+        if (pattern.lineageRIndex && pattern.lineageRIndex.length > 0) {
+
+          //find all reverse lineage - that is, patterns consuming this one
+          for (var j = 0; j < pattern.lineageRIndex.length; j++) {
+
+            var lineageRPattern = pattern_assembler.get_pattern_by_key(pattern.lineageRIndex[j], patternlab);
+
+            //only set patternState if pattern.patternState "is less than" the lineageRPattern.patternstate
+            //this makes patternlab apply the lowest common ancestor denominator
+            if (patternlab.config.patternStateCascade.indexOf(pattern.patternState)
+              < patternlab.config.patternStateCascade.indexOf(lineageRPattern.patternState)) {
+
+              if (patternlab.config.debug) {
+                console.log('Found a lower common denominator pattern state: ' + pattern.patternState + ' on ' + pattern.key + '. Setting reverse lineage pattern ' + lineageRPattern.key + ' from ' + lineageRPattern.patternState);
+              }
+
+              lineageRPattern.patternState = pattern.patternState;
+
+              //take this opportunity to overwrite the lineageRPattern's lineage state too
+              setPatternState('fromPast', lineageRPattern, pattern);
+            } else {
+              setPatternState('fromPast', pattern, lineageRPattern);
+            }
+          }
+        }
+      }
+    }
+  }
+
   return {
     find_lineage: function (pattern, patternlab) {
       findlineage(pattern, patternlab);
+    },
+    cascade_pattern_states : function (patternlab) {
+      cascadePatternStates(patternlab);
     }
   };
 

core/lib/pattern_assembler.js

@@ -36,8 +36,8 @@ var pattern_assembler = function () {
   }
 
   function setState(pattern, patternlab) {
-    if (patternlab.config.patternStates && patternlab.config.patternStates[pattern.patternName]) {
-      pattern.patternState = patternlab.config.patternStates[pattern.patternName];
+    if (patternlab.config.patternStates && patternlab.config.patternStates[pattern.key]) {
+      pattern.patternState = patternlab.config.patternStates[pattern.key];
     } else {
       pattern.patternState = "";
     }

core/lib/patternlab.js

@@ -18,6 +18,7 @@ var patternlab_engine = function (config) {
     pa = require('./pattern_assembler'),
     mh = require('./media_hunter'),
     pe = require('./pattern_exporter'),
+    lh = require('./lineage_hunter'),
     he = require('html-entities').AllHtmlEntities,
     patternlab = {};
 
@@ -80,6 +81,7 @@ var patternlab_engine = function (config) {
     var pattern_assembler = new pa(),
       entity_encoder = new he(),
       pattern_exporter = new pe(),
+      lineage_hunter = new lh(),
       patterns_dir = paths.source.patterns;
 
     pattern_assembler.combine_listItems(patternlab);
@@ -154,6 +156,9 @@ var patternlab_engine = function (config) {
     //we need to do this before expanding patterns & partials into extendedTemplates, otherwise we could lose the data -> partial reference
     pattern_assembler.parse_data_links(patternlab);
 
+    //cascade any patternStates
+    lineage_hunter.cascade_pattern_states(patternlab);
+
     //delete the contents of config.patterns.public before writing
     if (deletePatternDir) {
       fs.emptyDirSync(paths.public.patterns);
@@ -172,6 +177,19 @@ var patternlab_engine = function (config) {
 
       pattern.header = head;
 
+      //json stringify lineage and lineageR
+      var lineageArray = [];
+      for (var i = 0; i < pattern.lineage.length; i++) {
+        lineageArray.push(JSON.stringify(pattern.lineage[i]));
+      }
+      pattern.lineage = lineageArray;
+
+      var lineageRArray = [];
+      for (var i = 0; i < pattern.lineageR.length; i++) {
+        lineageRArray.push(JSON.stringify(pattern.lineageR[i]));
+      }
+      pattern.lineageR = lineageRArray;
+
       //render the pattern, but first consolidate any data we may have
       var allData = JSON.parse(JSON.stringify(patternlab.data));
       allData = pattern_assembler.merge_data(allData, pattern.jsonFileData);

patternlab-config.json

@@ -49,8 +49,11 @@
     "tools-shortcuts": true,
     "tools-docs": true
   },
+  "patternStateCascade": ["inprogress", "inreview", "complete"],
   "patternStates": {
-    "homepage-emergency" : "inprogress"
+    "molecules-single-comment" : "complete",
+    "organisms-sticky-comment" : "inreview",
+    "templates-article" : "complete"
   },
   "patternExportKeys": [],
   "patternExportDirectory": "./pattern_exports/",