BREAKING-CHANGE: Deprecate underscore prefix (#1237)

* Deprecate underscore prefix * #1237: Update tests to use new "hidden" functionality * #1237: Add Documentation * #1237: Add deprecation warning * Update dev package sources * #1237 Update pattern doc locations * #1237 Update log warnings * Update documentation * add a possibility to disable deprecation warnings * Fix failing test by misssing config * Fix message text
pattern-lab · Jan 5, 2021 · 030a992 · 030a992
1 parent 92db31f
commit 030a992
Show file tree

Hide file tree

Showing 15 changed files with 217 additions and 73 deletions.
diff --git a/packages/core/src/lib/object_factory.js b/packages/core/src/lib/object_factory.js
@@ -2,12 +2,14 @@
 
 const _ = require('lodash');
 const path = require('path');
+const logger = require('./log');
 const patternEngines = require('./pattern_engines');
 
 // prefixMatcher is intended to match the leading maybe-underscore,
 // zero or more digits, and maybe-dash at the beginning of a pattern file name we can hack them
 // off and get at the good part.
 const prefixMatcher = /^_?(\d+-)?/;
+const prefixMatcherDeprecationCheckHidden = /^_.+/;
 
 /**
  * Pattern constructor / Pattern properties
@@ -51,6 +53,20 @@ const Pattern = function(
   this.subdir = pathObj.dir; // '00-atoms/00-global'
   this.fileExtension = pathObj.ext; // '.mustache'
 
+  if (
+    (prefixMatcherDeprecationCheckHidden.test(this.getDirLevel(0, info)) ||
+      prefixMatcherDeprecationCheckHidden.test(this.getDirLevel(1, info)) ||
+      prefixMatcherDeprecationCheckHidden.test(this.fileName)) &&
+    !info.isMetaPattern &&
+    patternlab &&
+    patternlab.config &&
+    !patternlab.config.disableDeprecationWarningForHiddenPatterns
+  ) {
+    logger.warning(
+      `${info.shortNotation}/${this.fileName} "Pattern", "Group" and "Subgroup" hiding by underscore prefix (_*) will be deprecated in the future.\n See https://patternlab.io/docs/hiding-patterns-in-the-navigation/`
+    );
+  }
+
   // TODO: Remove if when dropping ordering by prefix and keep else code
   if (info.patternHasOwnDir) {
     // Since there is still the requirement of having the numbers provided for sorting
@@ -301,6 +317,11 @@ Pattern.prototype = {
     info.dir = info.patternHasOwnDir ? pathObj.dir.split(path.sep).pop() : '';
     info.dirLevel = pathObj.dir.split(path.sep).filter(s => !!s).length;
 
+    // Only relevant for deprecation check and message
+    if (path.parse(pathObj.dir).base === '_meta') {
+      info.isMetaPattern = true;
+    }
+
     if (info.dirLevel === 0 || (info.dirLevel === 1 && info.patternHasOwnDir)) {
       // -> ./
       info.shortNotation = 'root';

diff --git a/packages/core/src/lib/pseudopattern_hunter.js b/packages/core/src/lib/pseudopattern_hunter.js
@@ -114,6 +114,7 @@ pseudopattern_hunter.prototype.find_pseudopatterns = function(
         },
         patternlab
       );
+      patternVariant.hidden = _.clone(currentPattern.hidden);
 
       changes_hunter.checkBuildState(patternVariant, patternlab);
       patternlab.graph.add(patternVariant);

diff --git a/packages/core/src/lib/readDocumentation.js b/packages/core/src/lib/readDocumentation.js
@@ -1,7 +1,8 @@
 'use strict';
 
-const path = require('path');
 const _ = require('lodash');
+const path = require('path');
+const fs = require('fs-extra');
 
 const ch = require('./changes_hunter');
 const logger = require('./log');
@@ -10,14 +11,15 @@ const mp = require('./markdown_parser');
 const changes_hunter = new ch();
 const markdown_parser = new mp();
 
-let fs = require('fs-extra'); //eslint-disable-line prefer-const
+const FILE_EXTENSION = '.md';
+const GROUP_DOC_PREFIX = '_';
 
 module.exports = function(pattern, patternlab) {
   try {
     const markdownFileName = path.resolve(
       patternlab.config.paths.source.patterns,
       pattern.subdir,
-      pattern.fileName + '.md'
+      pattern.fileName + FILE_EXTENSION
     );
     changes_hunter.checkLastModified(pattern, markdownFileName);
 
@@ -72,7 +74,74 @@ module.exports = function(pattern, patternlab) {
     // do nothing when file not found
     if (err.code !== 'ENOENT') {
       logger.warning(
-        `'there was an error setting pattern keys after markdown parsing of the companion file for pattern ${pattern.patternPartial}`
+        `There was an error setting pattern keys after markdown parsing of the companion file for pattern ${pattern.patternPartial}`
+      );
+      logger.warning(err);
+    }
+  }
+
+  // Read Documentation for Pattern-Group
+  // Use this approach, since pattern lab is a pattern driven software
+  try {
+    const markdownFileNameGroup = path.resolve(
+      patternlab.config.paths.source.patterns,
+      path.parse(pattern.subdir).dir,
+      GROUP_DOC_PREFIX + pattern.patternGroup + FILE_EXTENSION
+    );
+    const markdownFileContentsGroup = fs.readFileSync(
+      markdownFileNameGroup,
+      'utf8'
+    );
+    const markdownObjectGroup = markdown_parser.parse(
+      markdownFileContentsGroup
+    );
+
+    if (!_.isEmpty(markdownObjectGroup)) {
+      pattern.patternGroupData = markdownObjectGroup;
+    }
+  } catch (err) {
+    // do nothing when file not found
+    if (err.code !== 'ENOENT') {
+      logger.warning(
+        `There was an error setting pattern group data after markdown parsing for ${path.join(
+          patternlab.config.paths.source.patterns,
+          path.parse(pattern.subdir).dir,
+          GROUP_DOC_PREFIX + pattern.patternGroup + FILE_EXTENSION
+        )}`
+      );
+      logger.warning(err);
+    }
+  }
+
+  // Read Documentation for Pattern-Subgroup
+  try {
+    const markdownFileNameSubGroup = path.resolve(
+      patternlab.config.paths.source.patterns,
+      path.parse(pattern.subdir).dir,
+      path.parse(pattern.subdir).base,
+      GROUP_DOC_PREFIX + pattern.patternSubGroup + FILE_EXTENSION
+    );
+    const markdownFileContentsSubGroup = fs.readFileSync(
+      markdownFileNameSubGroup,
+      'utf8'
+    );
+    const markdownObjectSubGroup = markdown_parser.parse(
+      markdownFileContentsSubGroup
+    );
+
+    if (!_.isEmpty(markdownObjectSubGroup)) {
+      pattern.patternSubGroupData = markdownObjectSubGroup;
+    }
+  } catch (err) {
+    // do nothing when file not found
+    if (err.code !== 'ENOENT') {
+      logger.warning(
+        `There was an error setting pattern sub group data after markdown parsing for ${path.join(
+          patternlab.config.paths.source.patterns,
+          path.parse(pattern.subdir).dir,
+          path.parse(pattern.subdir).base,
+          GROUP_DOC_PREFIX + pattern.patternSubGroup + FILE_EXTENSION
+        )}`
       );
       logger.warning(err);
     }

diff --git a/packages/core/src/lib/ui_builder.js b/packages/core/src/lib/ui_builder.js
@@ -77,11 +77,14 @@ const ui_builder = function() {
       return true;
     }
 
-    // skip underscore-prefixed files
-    isOmitted = pattern.isPattern && pattern.fileName.charAt(0) === '_';
+    // skip marked as hidden patterns
+    isOmitted =
+      (pattern.isPattern && pattern.hidden) ||
+      // TODO: Remove next line when removing support & deprecation waring for underscore prefix hiding
+      (pattern.isPattern && pattern.fileName.charAt(0) === '_');
     if (isOmitted) {
       logger.info(
-        `Omitting ${pattern.patternPartial} from styleguide patterns because it has an underscore prefix.`
+        `Omitting ${pattern.patternPartial} from styleguide patterns because it is marked as hidden within it's documentation.`
       );
       return true;
     }
@@ -96,13 +99,16 @@ const ui_builder = function() {
       return true;
     }
 
-    // this pattern is contained with a directory prefixed with an underscore (a handy way to hide whole directories from the nav
+    // this pattern is contained with a directory documented as hidden (a handy way to hide whole directories from the nav
     isOmitted =
+      (pattern.patternGroupData && pattern.patternGroupData.hidden) ||
+      (pattern.patternSubGroupData && pattern.patternSubGroupData.hidden) ||
+      // TODO: Remove next two lines when removing support & deprecation waring for underscore prefix hiding
       pattern.relPath.charAt(0) === '_' ||
       pattern.relPath.indexOf(path.sep + '_') > -1;
     if (isOmitted) {
       logger.info(
-        `Omitting ${pattern.patternPartial} from styleguide patterns because its contained within an underscored directory.`
+        `Omitting ${pattern.patternPartial} from styleguide patterns because its contained within an hidden directory.`
       );
       return true;
     }

diff --git a/packages/core/test/ui_builder_tests.js b/packages/core/test/ui_builder_tests.js
@@ -72,7 +72,8 @@ tap.test(
   function(test) {
     //arrange
     var patternlab = createFakePatternLab({});
-    var pattern = new Pattern('00-test/_ignored-pattern.mustache');
+    var pattern = new Pattern('00-test/ignored-pattern.mustache');
+    pattern.hidden = true;
 
     //act
     var result = ui.isPatternExcluded(pattern, patternlab, uikit);
@@ -108,7 +109,7 @@ tap.test(
     var pattern = Pattern.createEmpty({
       relPath:
         path.sep +
-        '_hidden' +
+        'hidden' +
         path.sep +
         'patternsubtype' +
         path.sep +
@@ -118,6 +119,10 @@ tap.test(
       patternPartial: 'hidden-foo',
     });
 
+    pattern.patternGroupData = {
+      hidden: true,
+    };
+
     //act
     var result = ui.isPatternExcluded(pattern, patternlab, uikit);
 
@@ -134,12 +139,16 @@ tap.test(
     var patternlab = createFakePatternLab({});
     var pattern = Pattern.createEmpty({
       relPath:
-        'shown' + path.sep + '_patternsubtype' + path.sep + 'foo.mustache',
+        'shown' + path.sep + 'patternsubtype' + path.sep + 'foo.mustache',
       isPattern: true,
       fileName: 'foo.mustache',
       patternPartial: 'shown-foo',
     });
 
+    pattern.patternSubGroupData = {
+      hidden: true,
+    };
+
     //act
     var result = ui.isPatternExcluded(pattern, patternlab, uikit);
 

diff --git a/packages/development-edition-engine-handlebars/.gitignore b/packages/development-edition-engine-handlebars/.gitignore
@@ -7,3 +7,4 @@ Thumbs.db
 .idea/
 public
 dependencyGraph.json
+source/
diff --git a/packages/development-edition-engine-handlebars/patternlab-config.json b/packages/development-edition-engine-handlebars/patternlab-config.json
@@ -21,9 +21,18 @@
     "tools-docs": false
   },
   "ishViewportRange": {
-    "s": [240, 500],
-    "m": [500, 800],
-    "l": [800, 2600]
+    "s": [
+      240,
+      500
+    ],
+    "m": [
+      500,
+      800
+    ],
+    "l": [
+      800,
+      2600
+    ]
   },
   "logLevel": "info",
   "outputFileSuffixes": {
@@ -64,7 +73,11 @@
     }
   },
   "patternExtension": "hbs",
-  "patternStateCascade": ["inprogress", "inreview", "complete"],
+  "patternStateCascade": [
+    "inprogress",
+    "inreview",
+    "complete"
+  ],
   "patternExportAll": false,
   "patternExportDirectory": "pattern_exports",
   "patternExportPatternPartials": [],
@@ -103,7 +116,9 @@
       "enabled": true,
       "initialized": false,
       "options": {
-        "tabsToAdd": ["scss"]
+        "tabsToAdd": [
+          "scss"
+        ]
       }
     }
   }

diff --git a/packages/development-edition-engine-handlebars/source/_data/data.json b/packages/development-edition-engine-handlebars/source/_data/data.json
@@ -1,34 +1,14 @@
 {
-  "version": "2",
-  "swatches": [
-    {
-      "color": {
-        "hex": "#031636",
-        "cmyk": "94 59 0 79"
-      },
-      "label": "dark blue"
-    },
-    {
-      "color": {
-        "hex": "#0D80F0",
-        "cmyk": "95 47 0 6"
-      },
-      "label": "light blue"
-    },
-    {
-      "color": {
-        "hex": "#4c4c4c",
-        "cmyk": "0 0 0 70"
-      },
-      "label": "dark grey"
-    },
-    {
-      "color": {
-        "hex": "#b2b2b2",
-        "cmyk": "0 0 0 30"
-      },
-      "label": "light grey",
-      "inverted": true
-    }
-  ]
+	"company": {
+		"name": "Company Name",
+		"url": "http://company.com"
+	},
+	"page": {
+		"title": "This is the page title",
+		"description": "This is the page description"
+	},
+	"title": "Title ipsum dolor sit (39 characters)",
+	"description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
+	"url": "#",
+	"htmlText": "<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ipsam necessitatibus reprehenderit ipsum repellat quasi ratione sit possimus 🙂 eveniet, ea, ut mollitia repudiandae eligendi unde aperiam molestiae voluptatibus error. Dolorem, iure.</p><p>Lorem <strong>ipsum dolor sit amet</strong>, consectetur adipiscing elit. Integer fringilla sem a urna porttitor fringilla. Nulla eget justo felis. eget volutpat justo mattis nec. Sed a orci turpis. Aliquam aliquet placerat dui.</p><h2>This is a second-level heading</h2><p><a href='#'>Aliquam erat volutpat.</a> Mauris vulputate scelerisque feugiat. <em>Cras a erat a diam venenatis aliquam</em>. Sed tempus, purus ac pretium varius, risus orci sagittis purus, quis auctor libero magna nec magna. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Maecenas eros dolor.</p><ol> <li>Ordered list item</li><li>Another ordered list item</li><li>Yet another ordered list item</li></ol><h3>This is a third-level heading</h3><p>Aliquam ultrices cursus mauris, eget volutpat justo mattis nec. Sed a orci turpis. Aliquam aliquet placerat dui, consectetur tincidunt leo tristique et. Vivamus enim nisi, blandit a venenatis quis, convallis et arcu. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris libero sapien, placerat in sodales eu, tempor quis dui. Vivamus egestas faucibus pulvinar. Maecenas eget diam nunc. Phasellus at sem eros, ac suscipit neque. Phasellus sollicitudin libero a odio dignissim scelerisque. Aliquam purus nulla, tempor eget ullamcorper quis, rhoncus non dui.</p><h3><a href='#'>This is a linked heading</a></h3><ul> <li>Bulleted list item</li><li>Another bulleted list item</li><li>Yet bulleted list item</li><li>And here's yet another bulleted list item</li></ul><blockquote>This is a blockquote. Eget volutpat justo mattis nec. Sed a orci turpis. Aliquam aliquet placerat dui, consectetur tincidunt leo eget est blandit dignissim a eu ante. Morbi augue nulla <cite>Cite Source</cite></blockquote><h4>This is a fourth-level heading</h4><p>Cras at fringilla ipsum. Donec nec libero eget est blandit dignissim a eu ante. Morbi augue nulla, luctus eu sagittis vel, malesuada ut felis. Aliquam erat volutpat. Morbi malesuada augue ac massa hendrerit fermentum. Integer scelerisque lacus a dolor convallis lobortis. Curabitur mollis ante in massa ultricies dignissim.</p><h5>This is a fifth-level heading</h5><p>Cras at fringilla ipsum. Donec nec libero eget est blandit dignissim a eu ante. Morbi augue nulla, luctus eu sagittis vel.</p><h6>This is a sixth-level heading</h6> <p>Lorem ipsum dolor sit amet.</p>"
 }
diff --git a/packages/development-edition-engine-handlebars/source/_data/listitems.json b/packages/development-edition-engine-handlebars/source/_data/listitems.json
@@ -1,6 +1,3 @@
 {
-  "1": {},
-  "2": {},
-  "3": {},
-  "4": {}
+
 }
diff --git a/packages/development-edition-engine-handlebars/source/_meta/_00-head.mustache b/packages/development-edition-engine-handlebars/source/_meta/_00-head.mustache
@@ -1,17 +1,18 @@
 <!DOCTYPE html>
 <html class="{{ htmlClass }}">
-  <head>
-    <title>{{ title }}</title>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width" />
+	<head>
+		<title>{{ title }}</title>
+		<meta charset="UTF-8">
+		<meta name="viewport" content="width=device-width" />
 
-    <link rel="stylesheet" href="../../css/style.css?{{ cacheBuster }}" media="all" />
-    <link rel="stylesheet" href="../../css/pattern-scaffolding.css?{{ cacheBuster }}" media="all" />
+		<link rel="stylesheet" href="../../css/style.css?{{ cacheBuster }}" media="all" />
+		<link rel="stylesheet" href="../../css/pattern-scaffolding.css?{{ cacheBuster }}" media="all" />
 
-    <!-- Begin Pattern Lab (Required for Pattern Lab to run properly) -->
-    {{{ patternLabHead }}}
-    <!-- End Pattern Lab -->
+		<!--<Deject>-->
+		<!-- Begin Pattern Lab (Required for Pattern Lab to run properly) -->
+		{{{ patternLabHead }}}
+		<!-- End Pattern Lab -->
+		<!--</Deject>-->
 
-  </head>
-  <body class="{{ bodyClass }}">
-
+	</head>
+	<body class="{{ bodyClass }}">
diff --git a/packages/development-edition-engine-handlebars/source/_meta/_01-foot.mustache b/packages/development-edition-engine-handlebars/source/_meta/_01-foot.mustache
@@ -1,6 +1,9 @@
+	<script src="../../js/production.min.js"></script>
 
-<!--DO NOT REMOVE-->
-{{{ patternLabFoot }}}
+	<!--<Deject>-->
+	<!--DO NOT REMOVE-->
+	{{{ patternLabFoot }}}
+	<!--</Deject>-->
 
-</body>
+	</body>
 </html>