Improve source code previews in Storybook

[tylersticka]

By default, Storybook displays the JavaScript source for stories when you click the "show code" button on story previews in docs mode:

This is not particularly useful for this project, where most of the patterns are Twig templates. There's never a place where that code would be copied and pasted anywhere.

We recently updated Storybook to 6.x, which included a few improvements to the customization of source previews. Unfortunately these don't seem to be capable of full automation, but it would allow us to do something like this...

import { Story, Canvas, Meta } from '@storybook/addon-docs/blocks';
import template from './example/template.twig';
import templateSrc from '!!raw-loader!./example/template.twig;
// ...

<Canvas>
  <Story name="Example" parameters={{
    docs: { source: { code: templateSrc } }
  }}>
    {(args) => template(args)}
  </Story>
</Canvas>

This would get us a lot closer, but it does call into question our current way of keeping things DRY through demos. Consider these two examples, a default and a prose container:

Notice that the examples are the same, and aren't really indicative of how things would work in the wild. That's because the demos were written from the point of view of the maintainer keeping things DRY and not as a point of reference for the viewer. Does this mean rewriting all of the demos so far to keep them more relevant?

Alternatively, we could manually include an additional example for each pattern:

<Source
  language="twig"
  code={`{% embed '@cloudfour/objects/container/container.twig' %}
  {% block content %}
    Hello world
  {% endblock %}
{% endembed %}`}
></Source>

Which would display outside the story:

This would give us a lot more freedom, but is it too much extra work? And can we disable the normal "show code" buttons to reduce noise of the docs?

[tylersticka]

This has changed a bit since I made this issue.

You can now specify a docs.source.code parameter with a string, which I've done for the favicon documentation. Example:

<Canvas>
  <Story
    name="..."
    parameters={{
      docs: {
        source: {
          code: `CODE GOES HERE`,
        },
      },
    }}
  >...</Story>
</Canvas>

It's unclear if a string is the only option, or if it would be possible to use a function that could receive some of the story context and let us generate these snippets dynamically.

[tylersticka]

Okay, there's also a Docs parameter called transformSource that can apply changes dynamically: storybookjs/storybook#1843 (comment)

If I add the following to preview.js as part of the parameters.docs export:

    transformSource: (_src, storyContext) => {
      try {
        const result = storyContext.storyFn(storyContext);
        return result;
      } catch (e) {
        return null;
      }
    }

Then every story will get its HTML output as its source code:

But obviously that doesn't give us the Twig output, only the HTML. It may be a better idea to make some sort of helper function for generating code previews that could be passed along to transformSource at a story parameter level?

Anyway! Not sure exactly what's possible, just figured I'd share the outcomes of my research.