diff --git a/packages/core/src/lib/object_factory.js b/packages/core/src/lib/object_factory.js index 01a324521..633edfa38 100644 --- 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 index 71c178177..22e46a790 100644 --- 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 index f2c4dd4ab..597acc5b7 100644 --- 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 index 6a95a2bca..719f37e31 100644 --- 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 index 00fd29ec0..21defffb2 100644 --- 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 index 0679bd2b5..30cb59412 100644 --- 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/ \ No newline at end of file diff --git a/packages/development-edition-engine-handlebars/patternlab-config.json b/packages/development-edition-engine-handlebars/patternlab-config.json index 36546fb07..be081a639 100644 --- 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 index 250376db0..9177a2289 100644 --- 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": "

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.

Lorem ipsum dolor sit amet, 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.

This is a second-level heading

Aliquam erat volutpat. Mauris vulputate scelerisque feugiat. Cras a erat a diam venenatis aliquam. 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.

  1. Ordered list item
  2. Another ordered list item
  3. Yet another ordered list item

This is a third-level heading

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.

This is a linked heading

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 Source

This is a fourth-level heading

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.

This is a fifth-level heading

Cras at fringilla ipsum. Donec nec libero eget est blandit dignissim a eu ante. Morbi augue nulla, luctus eu sagittis vel.

This is a sixth-level heading

Lorem ipsum dolor sit amet.

" } diff --git a/packages/development-edition-engine-handlebars/source/_data/listitems.json b/packages/development-edition-engine-handlebars/source/_data/listitems.json index c35d1076d..49d1a202f 100644 --- 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 index 45ce3bb7d..76899a54a 100644 --- 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 @@ - - {{ title }} - - + + {{ title }} + + - - + + - - {{{ patternLabHead }}} - + + + {{{ patternLabHead }}} + + - - - + + diff --git a/packages/development-edition-engine-handlebars/source/_meta/_01-foot.mustache b/packages/development-edition-engine-handlebars/source/_meta/_01-foot.mustache index 797d9418d..98d360860 100644 --- 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 @@ + - -{{{ patternLabFoot }}} + + + {{{ patternLabFoot }}} + - + diff --git a/packages/docs/src/docs/pattern-documenting.md b/packages/docs/src/docs/pattern-documenting.md index 8cdcdb465..2d0290e6d 100644 --- a/packages/docs/src/docs/pattern-documenting.md +++ b/packages/docs/src/docs/pattern-documenting.md @@ -22,6 +22,7 @@ Attributes overview: * The `title` attribute is used in Pattern Lab's navigation as well as in the styleguide views. Format: `string` * Pattern `tags` has to be an array, like `tags: [new, relaunch, dev]` * [Pattern `states`](/docs/using-pattern-states/) are defined like `state: incomplete` and [provide a simple visual indication](/docs/using-pattern-states/) +* The `hidden` property to [Hide Patterns in the Navigation](/docs/hiding-patterns-in-the-navigation/) Both `tags` and `states` could be used for [not including patterns in a UIKit specific build](/docs/editing-the-configuration-options/#heading-uikits). @@ -53,5 +54,5 @@ We'd name our documentation file: ## Adding More Attributes to the Front Matter -A future update of Pattern Lab will support more front matter attributes including: excludeFromStyleguide, order, hidden and links. +A future update of Pattern Lab will support more front matter attributes including: excludeFromStyleguide, order and links. It will also support adding custom attributes that could be utilized by plugins. For example, GitHub issues related to patterns. diff --git a/packages/docs/src/docs/pattern-hiding.md b/packages/docs/src/docs/pattern-hiding.md index 52ba3acae..80fe8b20e 100644 --- a/packages/docs/src/docs/pattern-hiding.md +++ b/packages/docs/src/docs/pattern-hiding.md @@ -9,14 +9,51 @@ eleventyNavigation: order: 170 --- -To remove a pattern from Pattern Lab's drop-down navigation and style guide add an underscore (`_`) to the beginning of the pattern name. For example, we may have a Google Map-based pattern that we don't need for a particular project. The path might look like: +Removing a pattern from Pattern Lab's drop-down navigation and style guide is accomplished by setting the `hidden` frontmatter key on any pattern's companion `.md` file. For example, we may have a Google Map-based pattern that we don't need for a particular project. The path might look like: molecules/media/map.mustache -To "hide" the pattern we add the underscore and re-generate our site: +We would create or edit a file in the same location, calling it `map.md`: - molecules/media/_map.mustache +``` +--- +hidden: true +--- +The map component... +``` + +## Hiding Pattern Groups + +The same concept applies to `pattern-groups`. For example, you have a `pattern-group` named `atoms`, and you create a companion `.md` file for that group under `_patters/atoms/_atoms.md`. In that case, the whole `pattern-group` and all its components will be hidden in the UI. The doc-file resolving works the following `{patternsRoot}/{pattern-group folder name}/_{pattern-group raw name without prefixes}.md` + +``` +--- +hidden: true +--- +# _atoms.md file +``` + +## Hiding Pattern Sub Groups + +The same concept applies to `pattern-sub-groups`. For example, you have a `pattern-sub-group` named `buttons` which is structured under `atoms`, and you create a companion `.md` file for that group under `_patters/atoms/buttons/_buttons.md`. In that case, the whole `pattern-sub-group` and all its components will be hidden in the UI. The doc-file resolving works the following `{patternsRoot}/{pattern-group folder name}/{pattern-sub-group folder name}/_{pattern-sub-group raw name without prefixes}.md` + +``` +--- +hidden: true +--- +# _buttons.md file +``` + +## Additional Information A hidden pattern can still be included in other patterns. -Not all PatternEngines support hiding patterns. +## Deactivate deprecation warning + +To deactivate the deprecation warning for hidden patterns, add + +``` +disableDeprecationWarningForHiddenPatterns: true +``` + +to the `patternlab-config.json` \ No newline at end of file diff --git a/packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/_colors.hbs b/packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/colors.hbs similarity index 100% rename from packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/_colors.hbs rename to packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/colors.hbs diff --git a/packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/colors.md b/packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/colors.md new file mode 100644 index 000000000..20ceb0395 --- /dev/null +++ b/packages/starterkit-handlebars-demo/dist/_patterns/00-atoms/01-global/colors.md @@ -0,0 +1,3 @@ +--- +hidden: true +--- \ No newline at end of file