Discussion and Vote: Pattern State Declaration, and other Pattern Metadata

[bmuenzenmeyer]

As a Pattern Lab Node user, I use a configuration json file to define pattern states. Am I compliant with the spec?

---

Pattern States in PL/Node use a key/value object defined in patternlab-config.json instead of the PHP filename approach, which uses filename suffixes.

Here's an example from the docs:

"patternStates": {
  "molecules-single-comment" : "complete",
  "organisms-sticky-comment" : "inreview",
  "templates-article" : "complete"
}

This was a conscious decision made at time of implementation, with the following benefits:

• reduce fatigue with yet more regexes
• I also thought it'd be simpler to change states in one place rather than have to rename files- an action, that, in my opinion, always feels costly from a UX perspective (just clicking through and editing) and results in a mess for version control systems.

This deviation would, however, make someone porting from PL/* to the other a bit more cumbersome. Though, pattern states might be low on their priority list when switching anyways.

What I am asking with this question is whether or not this deviation from PHP is in spec.

The timeline for this feature is dependent on the outcome of this issue, as spec compliance is a goal of PL/Node.

Tagging spec-question because I need input regarding compliance, and am not proposing a change to PHP's strategy.

This issue does not require a vote in my opinion, but we should perhaps open a process question to determine how questions like this are handled officially in the future. I'll wait to create one until after this issue shakes out.

---

JUNE 3RD EDIT

• parse status out of a pattern's .md Front Matter and map to a pattern's patternState proprerty
• parse order out of a pattern's .md Front Matter and use to override any file order prior to rendering
• parse hidden out of a pattern's .md Front Matter and use to hide pattern from all direct individual or subtype rendering similar to _underscoredPattern.mustache today. These patterns should still be include-able as partials
• parse excludeFromStyleguide (or a better name) out of a pattern's .md Front Matter and use to omit pattern from all rendering
• parse tags out of a pattern's .md Front Matter and ... ??? (available in a future search enhancement?)
• parse additional keys ouf of a pattern's .md Front Matter and display in {{patternDescAdditions}}

/cc @pattern-lab/voting-members

[bradfrost]

I like this. I'm thinking about version control with how pattern states are currently set up. If changing a state requires changing the file name, then it becomes harder to track and step through the history in a version control system. Am I right about that? I haven't actually used pattern states in projects. Just a thought.

[bmuenzenmeyer]

As far as I know, some version control systems can recognize the rename while others cannot, which would result in delete/add's and loss of history.

I am curious which method is preferred at scale, or if it matters, and both implementations could be considered in spec, the important part being the actual functionality, not the details.

I envision that's exactly why we are having these discussions 🎯

[dmolsen]

It's definitely not in spec. Sorry. In spec would mean someone could copy a set of files from one to the other and given the same input they'd get the same output.

That said, I'd be willing to deprecate the @status feature in favor of something like Fractal's statuses methodology which is part of their component configuration. While your points are valid I think an entirely separate file goes too far the other way as it's really indirect.

If we go the route of copying parts of "component configuration" (not all are applicable) someone should be able to set it in a pattern's .json, .yml, or .md file. The latter as part of the YAML front-matter.

Would this provide a happy medium between a fully separate config file and @status?

[bradfrost]

@dmolsen I totally dig having all that pattern-specific stuff as part of the Front Matter!

-----
title: Media Object
description: This is the description.
status: inprogress
------

Love it.

[dmolsen]

Well, description is just the markdown portion of the file and wouldn't come from the front-matter. But something like order could.

On Jun 1, 2016, at 3:23 PM, Brad Frost notifications@github.com wrote:

@dmolsen I totally dig having all that pattern-specific stuff as part of the Front Matter!

---

title: Media Object
description: This is the description.

status: inprogress

Love it.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.

[bmuenzenmeyer]

Would this provide a happy medium between a fully separate config file and @status?

I think putting status into the Front Matter makes a lot of sense. It would be easier than editing a filename and closer linked to the pattern it was declaring status for than tucked away inside a massive config file.

It also might make things like referenced starterkits easier to consume.

A separate discussion should be opened about whether to move order into this file too. I know that using order baked into the file name has just as many problems as status, (if not more!) and it only gets worse with scale.

So...

• create a vote issue to reference this discussion regarding status
• create a discussion or discussion & vote issue to discuss order

?

[dmolsen]

Too keep this somewhat clean let's just roll this into one discussion & vote issue. Here are the four I like from Fractal:

• status
• tags
• order
• hidden

In addition to that I could see an option that allows a pattern to be in the nav but not shown on a "view all" page.

Why don't you review the Fractal docs and see if anything else pops out for you. "Collections" is our subtype so maybe there are options there too.

[bmuenzenmeyer]

tags

Oooooo.... interesting. Imagine a search that is not only pattern name aware, but tag aware too. I like this a lot.

hidden

This would deprecate the _pattern.mustache approach then?

In addition to that I could see an option that allows a pattern to be in the nav but not shown on a "view all" page.

Yes that would be a nice place to do this! We do this in PL/Node today with a styleguideExcludes array that lists the patternPartials to skip when building the view-all pages. I think PL/PHP has the same?

Why don't you review the Fractal docs and see if anything else pops out for you. "Collections" is our subtype so maybe there are options there too.

Will do and report back

[bradfrost]

I like this. I'm also wondering if there's a way to do a freeform key-value pair thing that lets people extend this info? Thinking things like:

• Version (of a specific pattern i.e. 🔥 CAROUSEL 3.0 🔥
• People (i.e. Sarah Smith owns this pattern)
• Revision Date
• Other stuff

If the key matches something PL uses, it would behave accordingly, but if not it would dump it in the panel.

This is just a thought, but figured now would be the time to bring it up since we're talking about pattern info like this.

[dmolsen]

That's supposed to work in PL/PHP now but somehow I've borked that. That's what's supposed to go in {{# descAdditions }} or whatever that block is called in the base template. Good that you brought it up because it should get documented for spec. And fixed ;)

On Jun 2, 2016, at 7:32 PM, Brad Frost notifications@github.com wrote:

I like this. I'm also wondering if there's a way to do a freeform key-value pair thing that lets people extend this info? Thinking things like:

Version (of a specific pattern i.e. 🔥 CAROUSEL 3.0 🔥
People (i.e. Sarah Smith owns this pattern)
Revision Date
Other stuff
If the key matches something PL uses, it would behave accordingly, but if not it would dump it in the panel.

This is just a thought, but figured now would be the time to bring it up since we're talking about pattern info like this.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.

[bmuenzenmeyer]

@bradfrost - response

I'm also wondering if there's a way to do a freeform key-value pair thing that lets people extend this info?

neat idea. right now I am white-listing the parsing of frontmatter in PL/Node, but yes one could let anything that isn't an exact key match fall through to what Dave is alluding to. If that's intended behavior I will need to open an issue to do that.

@dmolsen - response

Why don't you review the Fractal docs and see if anything else pops out for you. "Collections" is our subtype so maybe there are options there too.

The ones you chose look good to me too. display is interesting to purposefully constrain an element that you know is typically to be seen in a small viewport, and say, is styled using flexbox, and looks odd when the iframe extends beyond the pattern's typical use. I think we have mechanisms to achieve the same effect however, like the ish controls or styleguide-specific.css
Don't know if it merits inclusion though.

Please also respond to #16 (comment) questions regarding hidden and the styleguideExclude option.

I'll attempt to summarize what we are voting on by editing the top-most comment.