Generate source code previews

.storybook/preview.js

@@ -8,6 +8,7 @@ import tokens from '../src/compiled/tokens/js/tokens';
 import 'focus-visible';
 import '../src/index-with-dependencies.scss';
 import './preview.scss';
+import { makeTwigInclude } from '../src/make-twig-include';
 const breakpoints = tokens.size.breakpoint;
 
 // Extend the languages Storybook will highlight
@@ -67,6 +68,22 @@ export const parameters = {
     // https://github.com/storybookjs/storybook/blob/v6.0.21/addons/docs/docs/docspage.md#inline-stories-vs-iframe-stories
     inlineStories: true,
     prepareForInline: (storyFn) => htmlToReactParser.parse(storyFn()),
+    transformSource(src, storyContext) {
+      try {
+        const storyFunction = storyContext.getOriginal();
+        const rendered = storyFunction(storyContext.args);
+        // The twing/source-inputs-loader.js file makes it so that whenever twig templates are rendered,
+        // the arguments and input path are stored in the window.__twig_inputs__ variable.
+        // __twig_inputs__ is a map between the output HTML and and objects with the arguments and input paths
+        // Here, since we have the rendered HTML, we can look up what the arguments and path were
+        // that correspond to that output
+        const input = window.__twig_inputs__?.get(rendered);
+        if (!input) return src;
+        return makeTwigInclude(input.path, input.args);
+      } catch {
+        return src;
+      }
+    },
   },
   viewport: {
     viewports: {

CONTRIBUTING.md

@@ -73,3 +73,27 @@ This is generally not necessary, but in case you need to manually publish a vers
 You can run `npm publish --dry-run` to see everything that _would_ happen during publish, without actually publishing to the npm registry.
 
 Note the branch is `v-next` for now. When we we merge this branch to `master`, these instructions should be updated.
+
+## Overriding source code previews in Storybook
+
+For most stories, we are able to generate a twig source code snippet for Storybook to display automatically. When stories use `useEffect` or other hooks, the source code snippet cannot be generated automatically, so the JS that was passed to `<Story>` is shown instead (there may be other cases where this happens as well). In those cases, you can manually pass the source code to `<Story>`:
+
+```jsx
+import { makeTwigInclude } from '../../make-twig-include';
+<Story
+  name="Story Name"
+  parameters={{
+    docs: { source: { code: makeTwigInclude('asdf', { foo: 'bar' }) } },
+  }}
+>
+  {(args) => template(args)}
+</Story>;
+```
+
+This generates a source code snippet like this:
+
+```twig
+{% include 'asdf' with {
+  "foo": "bar"
+} only %}
+```

src/make-twig-include.js

@@ -0,0 +1,13 @@
+/**
+ * Generate a twig source string of an include with args, i.e.
+ * {% include '@cloudfour/components/button.twig' with { "type": "disabled" } only %}
+ * @param {string} path
+ * @param {any} args
+ */
+export const makeTwigInclude = (path, args) => {
+  const argsString =
+    Object.keys(args).length > 0
+      ? ` with ${JSON.stringify(args, null, 2)}`
+      : '';
+  return `{% include '${path}'${argsString} only %}`;
+};

twing/source-inputs-loader.js

@@ -0,0 +1,24 @@
+const { relative } = require('path');
+
+// This loader changes the functions that are generated by importing .twig files
+// It makes the functions attach the arguments and twig file path to a global __twig__inputs__ global
+// __twig__inputs__ is a map between the output HTML and and objects with the arguments and input paths
+// __twig__inputs__ is used in transformSource in .storybook/preview.js to generate the twig source code previews
+
+module.exports = function (source) {
+  // Change it from an absolute path to a path starting with @cloudfour/
+  const path = relative(this.rootContext, this.resourcePath).replace(
+    /^src\//,
+    '@cloudfour/'
+  );
+  return source.replace(
+    `return template.render(context)`,
+    `const rendered = template.render(context);
+     const inputs = window.__twig_inputs__ || (window.__twig_inputs__ = new Map());
+     inputs.set(
+       rendered,
+       { path: ${JSON.stringify(path)}, args: context }
+     );
+     return rendered;`
+  );
+};

twing/webpack-options.js

@@ -5,12 +5,18 @@ const twingVirtualEnvironmentPath = require.resolve(
 
 const twingLoader = {
   test: /\.twig$/,
-  use: {
-    loader: 'twing-loader',
-    options: {
-      environmentModulePath: twingEnvironmentNodePath,
+  use: [
+    // Webpack loaders run in reverse, so this top loader will run last
+    {
+      loader: require.resolve('./source-inputs-loader'),
     },
-  },
+    {
+      loader: 'twing-loader',
+      options: {
+        environmentModulePath: twingEnvironmentNodePath,
+      },
+    },
+  ],
 };
 
 const alias = {