feat(storybook-utils): add MDXFileLoader to load and render non-JS files in MDX

Author: bashmish

.changeset/gentle-masks-film.md

@@ -0,0 +1,5 @@
+---
+'@web/storybook-utils': patch
+---
+
+add MDXFileLoader to load and render non-JS files in MDX

package-lock.json

@@ -72,6 +72,8 @@
     "@storybook/blocks": "^7.0.0",
     "@storybook/types": "^7.0.0",
     "@web/dev-server": "^0.4.0",
+    "@web/rollup-plugin-import-meta-assets": "^2.2.1",
+    "@web/storybook-utils": "^1.0.1",
     "storybook": "^7.0.0"
   }
 }

packages/storybook-framework-web-components/package.json

@@ -88,17 +88,23 @@ test.describe('all in one', () => {
       await sbPage.waitUntilLoaded();
 
       await expect(page).toHaveTitle(/^My page - Docs/);
-      await expect(sbPage.docParent().locator('h1')).toContainText('My page header');
+      await expect(sbPage.docParent().locator('h1').nth(0)).toContainText('My page header');
       await expect(
         sbPage.docParent().getByText('This is an MDX-based documentation page.'),
       ).toBeAttached();
-      await expect(sbPage.docParent().locator('h2')).toContainText('Story inside my page');
+      await expect(sbPage.docParent().locator('h2').nth(0)).toContainText('Story inside my page');
       await expect(
         sbPage.docParent().getByText('Below is a story rendered in MDX.'),
       ).toBeAttached();
       expect(await sbPage.docParent().locator('#root-inner').innerHTML()).toContain(
         '<div>My component works</div>',
       );
+      await expect(sbPage.docParent().locator('h2').nth(1)).toContainText('MDXFileLoader');
+      await expect(
+        sbPage.docParent().getByText('Below is a content loaded from a separate Markdown file.'),
+      ).toBeAttached();
+      await expect(sbPage.docParent().locator('h1').nth(1)).toContainText('My readme');
+      await expect(sbPage.docParent().getByText('My readme works.')).toBeAttached();
     });
 
     test('renders autodocs page', async ({ page }) => {

packages/storybook-framework-web-components/tests/all-in-one.spec.js

@@ -1,3 +1,5 @@
+import { importMetaAssets } from '@web/rollup-plugin-import-meta-assets';
+
 /** @type { import('../../../../index.d.ts').StorybookConfig } */
 const config = {
   stories: ['../stories/**/*.stories.js', '../stories/**/*.mdx'],
@@ -13,6 +15,7 @@ const config = {
   rollupFinal(config) {
     return {
       ...config,
+      plugins: [...config.plugins, importMetaAssets()],
       onLog(level, log, defaultHandler) {
         // we are only interested in warnings
         if (level !== 'warn') {

packages/storybook-framework-web-components/tests/fixtures/all-in-one/.storybook/main.js

@@ -0,0 +1,3 @@
+# My readme
+
+My readme works.

packages/storybook-framework-web-components/tests/fixtures/all-in-one/README.md

@@ -1,4 +1,5 @@
-import { Canvas, Meta } from '@storybook/blocks';
+import { Canvas, Markdown, Meta } from '@storybook/blocks';
+import { MDXFileLoader } from '@web/storybook-utils';
 
 import * as MyComponentStories from './my-component.stories.js';
 
@@ -13,3 +14,14 @@ This is an MDX-based documentation page.
 Below is a story rendered in MDX.
 
 <Canvas of={MyComponentStories.DefaultStory} />
+
+## MDXFileLoader
+
+Below is a content loaded from a separate Markdown file.
+
+<MDXFileLoader
+  url={new URL('../README.md', import.meta.url).href}
+  render={content => {
+    return <Markdown>{content}</Markdown>;
+  }}
+/>

packages/storybook-framework-web-components/tests/fixtures/all-in-one/stories/my-page.mdx

@@ -2,6 +2,35 @@
 
 Utilities for Storybook.
 
+## MDXFileLoader
+
+Loads a non-JS file content in MDX and allows to render it.
+
+This is needed for 2 reasons:
+
+- to workaround the limitation of MDX 2 where top-level await is not supported
+- to work in browsers where non-standard ESM imports (e.g. imports of text files, CSS and such) are not possible
+
+> In MDX 3 you can just [use the top-level await.](https://mdxjs.com/blog/v3/#await-in-mdx)
+
+### Use-case: render external Markdown file using Storybook `Markdown` block.
+
+Given a Storybook MDX file `docs/my-page.mdx` and a Markdown file `README.md` in the root, use the following MDX code:
+
+```mdx
+import { Markdown } from '@storybook/blocks';
+import { MDXFileLoader } from '@web/storybook-utils';
+
+<MDXFileLoader
+  url={new URL('../README.md', import.meta.url).href}
+  render={content => {
+    return <Markdown>{content}</Markdown>;
+  }}
+/>
+```
+
+> Make sure to use `@web/rollup-plugin-import-meta-assets` or another alternative to correctly bundle the assets resolved with the help of `import.meta.url`.
+
 ## createAddon
 
 Storybook addons are React components.

packages/storybook-utils/README.md

@@ -1 +1,2 @@
 export { createAddon } from './create-addon.js';
+export { MDXFileLoader } from './mdx-file-loader.js';

packages/storybook-utils/src/index.js

@@ -0,0 +1,17 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * @param {{ url: string, render: (content: string) => any }} props
+ */
+export const MDXFileLoader = ({ url, render }) => {
+  const [content, setContent] = useState('');
+  useEffect(() => {
+    fetch(url)
+      .then(res => res.text())
+      .then(text => setContent(text));
+  }, []);
+  if (!content) {
+    return 'Loading...';
+  }
+  return render(content);
+};