Proposal: the road to fully consumable Pattern Libraries in PL (v3.0 - v4.0)

[geoffp]

The road to fully consumable Pattern Libraries in PL (v3.0 - v4.0)

Definitions:

• I'll refer to the process of one pattern or component using another as "composition", "includes" or "inclusion". This is what Mustache and Handlebars call "partials".
• For the sake of clarity, "template engine" means the templating engine on its own, and "pattern engine" means the Pattern Lab engine that lets us write using a certain template engine.
• "Addressing" means the way patterns refer to each other.

And to be clear, I'm talking here about a pattern library being publishable via NPM (or similar) and fully, directly consumable by a site or application without a nasty copy step or transform.

So, okay. Why is this hard currently?

It's hard because the default experience Pattern Lab is limiting. It promises ease of authoring at the cost of lock-in. It allows templates (or components, I suppose!) to include each other with names and syntaxes that aren't supported directly by the templating systems themselves {{> atoms-button}}. It encourages the injection of data into templates through non-standard means, via Pattern Parameters and Style Modifiers {{> atoms-button:ds-btn--isDisabled("text": "Save") }}. Four observations:

1. We couldn't have possibly forseen the rise of component based systems when these Pattern Lab features were added.
2. This is what makes templates non-consumable outside Pattern Lab! Essentially, it makes Pattern Lab a requirement for any composition of templates. No es bueno.
3. The only reason we work this way is to fix the shortcomings of Mustache, which currently happens to be our default.
4. Each templating system has its own ideas about how to load up patterns and put them in a namespace. Some require users to register and name templates manually before use (Mustache, Handlebars), some require templates to load each other up with "physical" path names as es2015+ imports (React, Vue, etc.), some can't do this on their own at all (Underscore) and others combine both approaches with custom loader classes/functions (Twig, Nunjucks).

How would we fix this?

I think this all leads to the following conclusion: for patterns and components in a PL library to be directly consumable, Pattern Lab must
Be fully and forever out of the business of extending template engines' syntax
Allow each templating system to do its own pattern registration and addressing.

But what's the plan?

Here's how I think we can pull this off:

1. Support only templating systems that can accept parameters, allowing us to deprecate and then drop support for Pattern Parameters and Style Modifiers. They will still exist as concepts employed by templating systems that cut the mustard, and we can document and demonstrate their use
2. That means that we drop Mustache as the default in favor of Handlebars, since it does parameters and Mustache doesn't. We no longer have to code and maintain this magic.
   a. I think it's worth calling out that ~all Mustache is valid Handlebars_. Which should ease the transition for teams (that haven't come to rely too heavily on Pattern Parameters and StyleModifiers)
3. For Handlebars, Twig, Nunjucks and similar, we can still support PL-style shorthand and long-form template naming, but the pattern engine must provide, and a consumable pattern library must export (via index.js or whatever), the registration function or class the pattern engine uses to implement our naming convention(s), so consuming apps can use the exact same one to register / load the patterns. For those that also support relative path addressing, we must not impede their use.
4. For React / Vue / es2015+ module-based components, we do nothing with pattern naming: those things will include each other with solid relative paths, and we must not attempt to force them into the mold of Pattern Lab's template naming. So for these, we don't support traditional "template naming". And that's okay.
5. For template engines that support a precompile or build step, we must not impede consuming apps from implementing one. I think it's out of scope (at least for now) for us to provide one for each engine.

So... what's next?

1. Stabilize, release, and mature Pattern Lab Node v3.0. We're almost there and will be soon ready to start cutting Beta releases! This will include a bunch of testing and documentation of new areas of the Pattern Lab Node ecosystem, including UIKits and the CLI.
2. As part of the Beta, we announce deprecation of Mustache / Pattern Parameters / StyleModifiers. It will all still work, and will for the duration of the 3.X lifecycle, but we will actively discourage their use in favor of more powerful / future options.
3. Monorepo + this proposed 4.X track should move us closer to Pattern Lab unification. A clearer template language posture should free us of limitations holding engine-twig back
4. Start working on starterkit-handlebars-demo as the new de-facto beginner's demo of Pattern Lab capabilities
5. Investigate further updates to our documentation site to further hammer home this message

[stale]

It's hard to keep track of everything. This issue has been automatically marked as stale because it has not had recent activity, neither from the team nor the community. It will be closed if no further activity occurs. Please consider adding additional info, volunteering to contribute a fix for this issue, or making a further case that this is important to you, the team, and the project as a whole. Thanks!

[stale]

Issue closed after going stale. It can be re-opened if still relevant.

[bmuenzenmeyer]

re-opening this issue - it serves as an important guidepost for post v3 work