Make pattern previews templatable

[james-nash]

Summary

Fractal has a lovely feature called preview layouts, that give you per-pattern control over the markup that wraps your pattern when it is displayed with the pattern library.

Currently PL has _meta/00-head.mustache and _meta/01-foot.mustache that give you some control over the top and tail that will surround the pattern previews. However, there is no way to specify an alternative head & foot for certain patterns (as you can in Fractal).

I'd love to see this functionality added to a future version of Pattern Lab.

Use-cases

My use-cases for wanting this kind of functionality are as follows:

• Demonstrating contextual components. If you have components that change their appearance based on parent elements (for example, themable components as described in Contextual styling with custom properties). You could provide a custom preview template for such components that displays one instance of the component per theme, each wrapped in the necessary parent element to showcase how the component renders for that theme.
• Components that need some kind of trigger to become visible. For example, modal windows which typically are invisible until opened by some user action. You could provide a custom preview template with a "Show modal" button that can then make the modal appear.
• Components that look weird when taken out of context. Consider a card component. You'd probably not impose any kind of maximum width in the component's own CSS code. However, a single card is probably not designed to stretch to a desktop-sized screen width, because in real usage it would be placed into a grid and there would be several cards per row. Unfortunately, in PL, when you view a single card by itself, the preview width may be quite wide, thus making the card look excessively large. With a custom preview template you could wrap the card in a container with a sensible max-width to ensure it always displays at a sensible size.

There's probably other uses for this too, but those are a few I've encountered in my work a number of times.

Possible approach

We can already provide some meta data about patterns via the frontmatter in a pattern's markdown file - for example state and title. Perhaps this could be extended, and PL could add support for a preview property that takes the filename of a template which is then used to wrap the component.

For example, imagine a preview template like this: theme-preview.mustache:

<div class="theme-default">
    <h3>Default theme</h3>
    {{{ component }}}
</div>
<div class="theme-dark">
    <h3>Dark theme</h3>
    {{{ component }}}
</div>
<div class="theme-rainbow">
    <h3>Rainbow theme</h3>
    {{{ component }}}
</div>

(where, {{{ component }}} will be replaced with the pattern's rendered markup)

Then, imagine you've got a themable button component, whosebutton.md file might then look like this:

---
preview: theme-preview.mustache
---
This is a theme-aware button component...

Of course, there are some details to work out like: Do the preview templates need to be in a special folder, or do we just provide a relative path to them? Do they need to use the same pattern engine as your patterns or not? etc.

But, for now, I just wanted to get this idea written up to gather feedback and discussion

[mfranzke]

Probably it's a good chance to evaluate the usage and maybe some refactoring of https://www.npmjs.com/package/plugin-node-wrappable for this purpose.

[romerocs]

Any movement on this feature?