feat: integrate @hadl/patternlab-plugin-pattern-wrap into core (#1433)

* feat: integrate @hadl/patternlab-plugin-pattern-wrap into core

* test: pattern wrap classes reading from markdown and/or json

Refs: #1432

* docs: pattern wrap classes config and details documentation

Refs: #1432

Co-authored-by: Josef Bredreck <[email protected]>

packages/core/patternlab-config.json

@@ -97,5 +97,7 @@
       "excludedPatternStates": [],
       "excludedTags": []
     }
-  ]
+  ],
+  "patternWrapClassesEnable": false,
+  "patternWrapClassesKey": []
 }

packages/core/src/lib/compose.js

@@ -10,6 +10,7 @@ const render = require('./render');
 const uikitExcludePattern = require('./uikitExcludePattern');
 const pm = require('./plugin_manager');
 const dataMerger = require('./dataMerger');
+const patternWrapClassesChangePatternTemplate = require('./patternWrapClasses');
 const pluginManager = new pm();
 
 const Pattern = require('./object_factory').Pattern;
@@ -159,6 +160,7 @@ module.exports = async function (pattern, patternlab) {
           const headHTML = intermediateResults[0]; //headPromise
           pattern.patternPartialCode = intermediateResults[1]; //patternPartialPromise
           const footerPartial = intermediateResults[2]; //footerPartialPromise
+          patternWrapClassesChangePatternTemplate(patternlab, pattern);
 
           //finish up our footer data
           let allFooterData;

packages/core/src/lib/patternWrapClasses.js

@@ -0,0 +1,45 @@
+/**
+ * get the classes from pattern markdown and/or json
+ * @param {PatternLab} patternlab
+ * @param {Pattern} pattern
+ * @return {string}
+ */
+function getPatternWrapClasses(patternlab, pattern) {
+  const { patternWrapClassesEnable, patternWrapClassesKey } = patternlab.config;
+  if (
+    !patternWrapClassesEnable ||
+    !patternWrapClassesKey ||
+    patternWrapClassesKey.length === 0
+  ) {
+    return '';
+  }
+
+  const classes = [];
+  patternWrapClassesKey.forEach((key) => {
+    const { allMarkdown, jsonFileData } = pattern;
+
+    if (allMarkdown && allMarkdown[key]) {
+      classes.push(allMarkdown[key]);
+    }
+
+    if (jsonFileData && jsonFileData[key]) {
+      classes.push(jsonFileData[key]);
+    }
+  });
+
+  return classes.join(' ');
+}
+
+/**
+ * change pattern template and wrap with classes pattern wrapper
+ * @param {PatternLab} patternlab
+ * @param {Pattern} pattern
+ */
+function patternWrapClassesChangePatternTemplate(patternlab, pattern) {
+  const classes = getPatternWrapClasses(patternlab, pattern);
+  if (classes.length !== 0) {
+    pattern.patternPartialCode = `<div class="pl-pattern-wrapper-element ${classes}">${pattern.patternPartialCode}</div>`;
+  }
+}
+
+module.exports = patternWrapClassesChangePatternTemplate;

packages/core/test/files/_patterns/test/pattern-wrap-class-json.json

@@ -0,0 +1,3 @@
+{
+  "theme-class": "json-theme-class"
+}

packages/core/test/files/_patterns/test/pattern-wrap-class-json.mustache

@@ -0,0 +1 @@
+bar

packages/core/test/files/_patterns/test/pattern-wrap-class-markdown.md

@@ -0,0 +1,3 @@
+---
+theme-class: markdown-theme-class
+---

packages/core/test/files/_patterns/test/pattern-wrap-class-markdown.mustache

@@ -0,0 +1 @@
+bar

packages/core/test/patternWrapClasses_tests.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const path = require('path');
+const tap = require('tap');
+
+const loadPattern = require('../src/lib/loadPattern');
+const patternWrapClassesChangePatternTemplate = require('../src/lib/patternWrapClasses');
+const util = require('./util/test_utils.js');
+const patternEngines = require('../src/lib/pattern_engines');
+const config = require('./util/patternlab-config.json');
+
+patternEngines.loadAllEngines(config);
+
+const patterns_dir = `${__dirname}/files/_patterns`;
+
+tap.test('reading pattern wrap class from markdown', function (test) {
+  const patternlab = util.fakePatternLab(patterns_dir);
+  patternlab.config = {
+    ...patternlab.config,
+    patternWrapClassesEnable: true,
+    patternWrapClassesKey: ['theme-class'],
+  };
+
+  const patternPathMarkdown = path.join(
+    'test',
+    'pattern-wrap-class-markdown.mustache'
+  );
+  const patternMarkdown = loadPattern(patternPathMarkdown, patternlab);
+  patternWrapClassesChangePatternTemplate(patternlab, patternMarkdown);
+  const patternPartialMarkdown =
+    '<div class="pl-pattern-wrapper-element markdown-theme-class"></div>';
+
+  test.equal(patternMarkdown.patternPartialCode, patternPartialMarkdown);
+  test.end();
+});
+
+tap.test('reading pattern wrap class from json', function (test) {
+  const patternlab = util.fakePatternLab(patterns_dir);
+  patternlab.config = {
+    ...patternlab.config,
+    patternWrapClassesEnable: true,
+    patternWrapClassesKey: ['theme-class'],
+  };
+
+  const patternPathJson = path.join('test', 'pattern-wrap-class-json.mustache');
+  const patternJson = loadPattern(patternPathJson, patternlab);
+  patternWrapClassesChangePatternTemplate(patternlab, patternJson);
+  const patternPartialJson =
+    '<div class="pl-pattern-wrapper-element json-theme-class"></div>';
+
+  test.equal(patternJson.patternPartialCode, patternPartialJson);
+  test.end();
+});

packages/docs/src/docs/advanced-config-options.md

@@ -210,7 +210,7 @@ For example, to export the navigation, header, and footer, one might do:
 
 ## patternMergeVariantArrays
 
-Used to override the merge behavior of pattern variants. For more information see [The Pseudo-Pattern File Data](docs/using-pseudo-patterns/#heading-the-pseudo-pattern-file-data).
+Used to override the merge behavior of pattern variants. For more information see [The Pseudo-Pattern File Data](/docs/using-pseudo-patterns/#heading-the-pseudo-pattern-file-data).
 
 - `true` will merge arrays of the pattern and pseudo-pattern with [lodash merge](https://lodash.com/docs/4.17.15#merge)
 - `false` will override arrays from the pattern with pseudo-patterns arrays
@@ -221,6 +221,29 @@ Used to override the merge behavior of pattern variants. For more information se
 
 **default**: `true` | `undefined`
 
+## patternWrapClassesEnable
+
+Set to `true` to enable adding a wrapper div with css class(es) around a pattern.  
+For more information see [Pattern Wrap Classes](/docs/pattern-wrap-classes/).
+
+```javascript
+"patternWrapClassesEnable": false,
+```
+
+**default**: `false`
+
+## patternWrapClassesKey
+
+Configure your class keys for `"patternWrapClassesEnable": true`.  
+For more information see [Pattern Wrap Classes](/docs/pattern-wrap-classes/).
+
+
+```javascript
+"patternWrapClassesKey": ['theme-class'],
+```
+
+**default**: `[]`
+
 ## renderFlatPatternsOnViewAllPages
 
 Used to activate rendering flat patterns on view all pages and generate view all pages if only flat patterns are available

packages/docs/src/docs/advanced-pattern-wrap-classes.md

@@ -0,0 +1,105 @@
+---
+title: Pattern Wrap Classes
+tags:
+  - docs
+category: advanced
+eleventyNavigation:
+  title: Pattern Wrap Classes
+  key: advanced
+  order: 300
+sitemapPriority: '0.8'
+---
+
+This feature allows you to add a wrapper div with css class(es) around a pattern when shown in the single preview.
+If it gets included in another pattern, the wrapper is not added.
+
+This comes in handy if you, for example, use theming classes to visualize different backgrounds, colors etc.
+
+## Configuration
+
+Enable this feature with the configuration options 
+[patternWrapClassesEnable](/docs/editing-the-configuration-options/#heading-patternwrapclassesenable) and 
+[patternWrapClassesKey](/docs/editing-the-configuration-options/#heading-patternwrapclasseskey).
+
+## How does it work?
+
+Patternlab will look for any "data key" added to the `patternWrapClassesKey` array and adds that
+date to the wrapper element classes.
+
+Data key can be set inside the Markdown or JSON file of any pattern.
+
+### Example Config
+
+```json
+"patternWrapClassesKey": ["theme-class"]
+```
+
+## Use in Markdown
+
+Usage [Documenting Patterns](/docs/documenting-patterns/)
+
+### my-pattern.md
+```markdown
+---
+theme-class: my-theme-class
+---
+```
+
+### Result
+```html
+<div class="pl-pattern-wrapper-element my-theme-class">...markup of pattern...</div>
+```
+
+## Use in JSON
+
+Usage [Creating Pattern-specific Values](/docs/creating-pattern-specific-values/)
+
+### my-pattern.json
+```json
+{
+  "theme-class": "my-other-theme-class"
+}
+```
+
+### Result
+```html
+<div class="pl-pattern-wrapper-element my-other-theme-class">...markup of pattern...</div>
+```
+
+## Pseudo-Patterns
+
+This will work with pseudo-patterns too ([Using Pseudo-Patterns](/docs/using-pseudo-patterns/))
+
+### my-pattern~variant.json
+```json
+{
+  "theme-class": "my-variant-theme-class"
+}
+```
+
+### Result
+```html
+<div class="pl-pattern-wrapper-element my-variant-theme-class">...markup of pattern...</div>
+```
+
+## Multiple entries in "patternWrapClassesKey"
+
+Will result in multiple classes in the wrapper div.
+
+### Example Config
+```json
+"patternWrapClassesKey": ["theme-class", "other-class"]
+```
+
+### my-pattern.json
+```json
+{
+  "theme-class": "theme-class",
+  "other-class": "some-other-class"
+}
+```
+
+### Result
+```html
+<div class="pl-pattern-wrapper-element theme-class some-other-class">...markup of pattern...</div>
+```