Skip to content

Commit 030a992

Browse files
JosefBredereckJosefBredereck
authored
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
1 parent 92db31f commit 030a992

File tree

15 files changed

+217
-73
lines changed

15 files changed

+217
-73
lines changed

‎packages/core/src/lib/object_factory.js

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,14 @@
22

33
const _ = require('lodash');
44
const path = require('path');
5+
const logger = require('./log');
56
const patternEngines = require('./pattern_engines');
67

78
// prefixMatcher is intended to match the leading maybe-underscore,
89
// zero or more digits, and maybe-dash at the beginning of a pattern file name we can hack them
910
// off and get at the good part.
1011
const prefixMatcher = /^_?(\d+-)?/;
12+
const prefixMatcherDeprecationCheckHidden = /^_.+/;
1113

1214
/**
1315
* Pattern constructor / Pattern properties
@@ -51,6 +53,20 @@ const Pattern = function(
5153
this.subdir = pathObj.dir; // '00-atoms/00-global'
5254
this.fileExtension = pathObj.ext; // '.mustache'
5355

56+
if (
57+
(prefixMatcherDeprecationCheckHidden.test(this.getDirLevel(0, info)) ||
58+
prefixMatcherDeprecationCheckHidden.test(this.getDirLevel(1, info)) ||
59+
prefixMatcherDeprecationCheckHidden.test(this.fileName)) &&
60+
!info.isMetaPattern &&
61+
patternlab &&
62+
patternlab.config &&
63+
!patternlab.config.disableDeprecationWarningForHiddenPatterns
64+
) {
65+
logger.warning(
66+
`${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/`
67+
);
68+
}
69+
5470
// TODO: Remove if when dropping ordering by prefix and keep else code
5571
if (info.patternHasOwnDir) {
5672
// Since there is still the requirement of having the numbers provided for sorting
@@ -301,6 +317,11 @@ Pattern.prototype = {
301317
info.dir = info.patternHasOwnDir ? pathObj.dir.split(path.sep).pop() : '';
302318
info.dirLevel = pathObj.dir.split(path.sep).filter(s => !!s).length;
303319

320+
// Only relevant for deprecation check and message
321+
if (path.parse(pathObj.dir).base === '_meta') {
322+
info.isMetaPattern = true;
323+
}
324+
304325
if (info.dirLevel === 0 || (info.dirLevel === 1 && info.patternHasOwnDir)) {
305326
// -> ./
306327
info.shortNotation = 'root';

‎packages/core/src/lib/pseudopattern_hunter.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,7 @@ pseudopattern_hunter.prototype.find_pseudopatterns = function(
114114
},
115115
patternlab
116116
);
117+
patternVariant.hidden = _.clone(currentPattern.hidden);
117118

118119
changes_hunter.checkBuildState(patternVariant, patternlab);
119120
patternlab.graph.add(patternVariant);

‎packages/core/src/lib/readDocumentation.js

Lines changed: 73 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
'use strict';
22

3-
const path = require('path');
43
const _ = require('lodash');
4+
const path = require('path');
5+
const fs = require('fs-extra');
56

67
const ch = require('./changes_hunter');
78
const logger = require('./log');
@@ -10,14 +11,15 @@ const mp = require('./markdown_parser');
1011
const changes_hunter = new ch();
1112
const markdown_parser = new mp();
1213

13-
let fs = require('fs-extra'); //eslint-disable-line prefer-const
14+
const FILE_EXTENSION = '.md';
15+
const GROUP_DOC_PREFIX = '_';
1416

1517
module.exports = function(pattern, patternlab) {
1618
try {
1719
const markdownFileName = path.resolve(
1820
patternlab.config.paths.source.patterns,
1921
pattern.subdir,
20-
pattern.fileName + '.md'
22+
pattern.fileName + FILE_EXTENSION
2123
);
2224
changes_hunter.checkLastModified(pattern, markdownFileName);
2325

@@ -72,7 +74,74 @@ module.exports = function(pattern, patternlab) {
7274
// do nothing when file not found
7375
if (err.code !== 'ENOENT') {
7476
logger.warning(
75-
`'there was an error setting pattern keys after markdown parsing of the companion file for pattern ${pattern.patternPartial}`
77+
`There was an error setting pattern keys after markdown parsing of the companion file for pattern ${pattern.patternPartial}`
78+
);
79+
logger.warning(err);
80+
}
81+
}
82+
83+
// Read Documentation for Pattern-Group
84+
// Use this approach, since pattern lab is a pattern driven software
85+
try {
86+
const markdownFileNameGroup = path.resolve(
87+
patternlab.config.paths.source.patterns,
88+
path.parse(pattern.subdir).dir,
89+
GROUP_DOC_PREFIX + pattern.patternGroup + FILE_EXTENSION
90+
);
91+
const markdownFileContentsGroup = fs.readFileSync(
92+
markdownFileNameGroup,
93+
'utf8'
94+
);
95+
const markdownObjectGroup = markdown_parser.parse(
96+
markdownFileContentsGroup
97+
);
98+
99+
if (!_.isEmpty(markdownObjectGroup)) {
100+
pattern.patternGroupData = markdownObjectGroup;
101+
}
102+
} catch (err) {
103+
// do nothing when file not found
104+
if (err.code !== 'ENOENT') {
105+
logger.warning(
106+
`There was an error setting pattern group data after markdown parsing for ${path.join(
107+
patternlab.config.paths.source.patterns,
108+
path.parse(pattern.subdir).dir,
109+
GROUP_DOC_PREFIX + pattern.patternGroup + FILE_EXTENSION
110+
)}`
111+
);
112+
logger.warning(err);
113+
}
114+
}
115+
116+
// Read Documentation for Pattern-Subgroup
117+
try {
118+
const markdownFileNameSubGroup = path.resolve(
119+
patternlab.config.paths.source.patterns,
120+
path.parse(pattern.subdir).dir,
121+
path.parse(pattern.subdir).base,
122+
GROUP_DOC_PREFIX + pattern.patternSubGroup + FILE_EXTENSION
123+
);
124+
const markdownFileContentsSubGroup = fs.readFileSync(
125+
markdownFileNameSubGroup,
126+
'utf8'
127+
);
128+
const markdownObjectSubGroup = markdown_parser.parse(
129+
markdownFileContentsSubGroup
130+
);
131+
132+
if (!_.isEmpty(markdownObjectSubGroup)) {
133+
pattern.patternSubGroupData = markdownObjectSubGroup;
134+
}
135+
} catch (err) {
136+
// do nothing when file not found
137+
if (err.code !== 'ENOENT') {
138+
logger.warning(
139+
`There was an error setting pattern sub group data after markdown parsing for ${path.join(
140+
patternlab.config.paths.source.patterns,
141+
path.parse(pattern.subdir).dir,
142+
path.parse(pattern.subdir).base,
143+
GROUP_DOC_PREFIX + pattern.patternSubGroup + FILE_EXTENSION
144+
)}`
76145
);
77146
logger.warning(err);
78147
}

‎packages/core/src/lib/ui_builder.js

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -77,11 +77,14 @@ const ui_builder = function() {
7777
return true;
7878
}
7979

80-
// skip underscore-prefixed files
81-
isOmitted = pattern.isPattern && pattern.fileName.charAt(0) === '_';
80+
// skip marked as hidden patterns
81+
isOmitted =
82+
(pattern.isPattern && pattern.hidden) ||
83+
// TODO: Remove next line when removing support & deprecation waring for underscore prefix hiding
84+
(pattern.isPattern && pattern.fileName.charAt(0) === '_');
8285
if (isOmitted) {
8386
logger.info(
84-
`Omitting ${pattern.patternPartial} from styleguide patterns because it has an underscore prefix.`
87+
`Omitting ${pattern.patternPartial} from styleguide patterns because it is marked as hidden within it's documentation.`
8588
);
8689
return true;
8790
}
@@ -96,13 +99,16 @@ const ui_builder = function() {
9699
return true;
97100
}
98101

99-
// this pattern is contained with a directory prefixed with an underscore (a handy way to hide whole directories from the nav
102+
// this pattern is contained with a directory documented as hidden (a handy way to hide whole directories from the nav
100103
isOmitted =
104+
(pattern.patternGroupData && pattern.patternGroupData.hidden) ||
105+
(pattern.patternSubGroupData && pattern.patternSubGroupData.hidden) ||
106+
// TODO: Remove next two lines when removing support & deprecation waring for underscore prefix hiding
101107
pattern.relPath.charAt(0) === '_' ||
102108
pattern.relPath.indexOf(path.sep + '_') > -1;
103109
if (isOmitted) {
104110
logger.info(
105-
`Omitting ${pattern.patternPartial} from styleguide patterns because its contained within an underscored directory.`
111+
`Omitting ${pattern.patternPartial} from styleguide patterns because its contained within an hidden directory.`
106112
);
107113
return true;
108114
}

‎packages/core/test/ui_builder_tests.js

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,8 @@ tap.test(
7272
function(test) {
7373
//arrange
7474
var patternlab = createFakePatternLab({});
75-
var pattern = new Pattern('00-test/_ignored-pattern.mustache');
75+
var pattern = new Pattern('00-test/ignored-pattern.mustache');
76+
pattern.hidden = true;
7677

7778
//act
7879
var result = ui.isPatternExcluded(pattern, patternlab, uikit);
@@ -108,7 +109,7 @@ tap.test(
108109
var pattern = Pattern.createEmpty({
109110
relPath:
110111
path.sep +
111-
'_hidden' +
112+
'hidden' +
112113
path.sep +
113114
'patternsubtype' +
114115
path.sep +
@@ -118,6 +119,10 @@ tap.test(
118119
patternPartial: 'hidden-foo',
119120
});
120121

122+
pattern.patternGroupData = {
123+
hidden: true,
124+
};
125+
121126
//act
122127
var result = ui.isPatternExcluded(pattern, patternlab, uikit);
123128

@@ -134,12 +139,16 @@ tap.test(
134139
var patternlab = createFakePatternLab({});
135140
var pattern = Pattern.createEmpty({
136141
relPath:
137-
'shown' + path.sep + '_patternsubtype' + path.sep + 'foo.mustache',
142+
'shown' + path.sep + 'patternsubtype' + path.sep + 'foo.mustache',
138143
isPattern: true,
139144
fileName: 'foo.mustache',
140145
patternPartial: 'shown-foo',
141146
});
142147

148+
pattern.patternSubGroupData = {
149+
hidden: true,
150+
};
151+
143152
//act
144153
var result = ui.isPatternExcluded(pattern, patternlab, uikit);
145154

‎packages/development-edition-engine-handlebars/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,4 @@ Thumbs.db
77
.idea/
88
public
99
dependencyGraph.json
10+
source/

‎packages/development-edition-engine-handlebars/patternlab-config.json

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,9 +21,18 @@
2121
"tools-docs": false
2222
},
2323
"ishViewportRange": {
24-
"s": [240, 500],
25-
"m": [500, 800],
26-
"l": [800, 2600]
24+
"s": [
25+
240,
26+
500
27+
],
28+
"m": [
29+
500,
30+
800
31+
],
32+
"l": [
33+
800,
34+
2600
35+
]
2736
},
2837
"logLevel": "info",
2938
"outputFileSuffixes": {
@@ -64,7 +73,11 @@
6473
}
6574
},
6675
"patternExtension": "hbs",
67-
"patternStateCascade": ["inprogress", "inreview", "complete"],
76+
"patternStateCascade": [
77+
"inprogress",
78+
"inreview",
79+
"complete"
80+
],
6881
"patternExportAll": false,
6982
"patternExportDirectory": "pattern_exports",
7083
"patternExportPatternPartials": [],
@@ -103,7 +116,9 @@
103116
"enabled": true,
104117
"initialized": false,
105118
"options": {
106-
"tabsToAdd": ["scss"]
119+
"tabsToAdd": [
120+
"scss"
121+
]
107122
}
108123
}
109124
}

‎packages/development-edition-engine-handlebars/source/_data/data.json

Lines changed: 12 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,14 @@
11
{
2-
"version": "2",
3-
"swatches": [
4-
{
5-
"color": {
6-
"hex": "#031636",
7-
"cmyk": "94 59 0 79"
8-
},
9-
"label": "dark blue"
10-
},
11-
{
12-
"color": {
13-
"hex": "#0D80F0",
14-
"cmyk": "95 47 0 6"
15-
},
16-
"label": "light blue"
17-
},
18-
{
19-
"color": {
20-
"hex": "#4c4c4c",
21-
"cmyk": "0 0 0 70"
22-
},
23-
"label": "dark grey"
24-
},
25-
{
26-
"color": {
27-
"hex": "#b2b2b2",
28-
"cmyk": "0 0 0 30"
29-
},
30-
"label": "light grey",
31-
"inverted": true
32-
}
33-
]
2+
"company": {
3+
"name": "Company Name",
4+
"url": "http://company.com"
5+
},
6+
"page": {
7+
"title": "This is the page title",
8+
"description": "This is the page description"
9+
},
10+
"title": "Title ipsum dolor sit (39 characters)",
11+
"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.",
12+
"url": "#",
13+
"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>"
3414
}

‎packages/development-edition-engine-handlebars/source/_data/listitems.json

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,3 @@
11
{
2-
"1": {},
3-
"2": {},
4-
"3": {},
5-
"4": {}
2+
63
}

‎packages/development-edition-engine-handlebars/source/_meta/_00-head.mustache

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,18 @@
11
<!DOCTYPE html>
22
<html class="{{ htmlClass }}">
3-
<head>
4-
<title>{{ title }}</title>
5-
<meta charset="UTF-8">
6-
<meta name="viewport" content="width=device-width" />
3+
<head>
4+
<title>{{ title }}</title>
5+
<meta charset="UTF-8">
6+
<meta name="viewport" content="width=device-width" />
77

8-
<link rel="stylesheet" href="../../css/style.css?{{ cacheBuster }}" media="all" />
9-
<link rel="stylesheet" href="../../css/pattern-scaffolding.css?{{ cacheBuster }}" media="all" />
8+
<link rel="stylesheet" href="../../css/style.css?{{ cacheBuster }}" media="all" />
9+
<link rel="stylesheet" href="../../css/pattern-scaffolding.css?{{ cacheBuster }}" media="all" />
1010

11-
<!-- Begin Pattern Lab (Required for Pattern Lab to run properly) -->
12-
{{{ patternLabHead }}}
13-
<!-- End Pattern Lab -->
11+
<!--<Deject>-->
12+
<!-- Begin Pattern Lab (Required for Pattern Lab to run properly) -->
13+
{{{ patternLabHead }}}
14+
<!-- End Pattern Lab -->
15+
<!--</Deject>-->
1416

15-
</head>
16-
<body class="{{ bodyClass }}">
17-
17+
</head>
18+
<body class="{{ bodyClass }}">

0 commit comments

Comments
 (0)