Allow dynamically loaded example files

Dockerfile

@@ -13,6 +13,7 @@ RUN rm -r /usr/share/nginx/html && rm /etc/nginx/conf.d/default.conf
 COPY --from=builder /frontend-shared/build /usr/share/nginx/html
 COPY ./templates/index.html /usr/share/nginx/html/index.html
 COPY ./images /usr/share/nginx/html/images
+COPY ./src/pattern-library/examples /usr/share/nginx/html/examples
 COPY conf/nginx.conf /etc/nginx/conf.d/default.conf
 
 EXPOSE 5001

README.md

@@ -49,3 +49,4 @@ import { Link } from '@hypothesis/frontend-shared';
 
 - [Development guide](docs/developing.md)
 - [Release guide](docs/releases.md)
+- [Adding examples](docs/examples.md)

docs/examples.md

@@ -0,0 +1,28 @@
+# Adding code examples
+
+Component library documentations frequently need to add interactive examples next to code snippets showcasing how you would get to build that.
+
+Manually writing those code snippets has some issues: they are not covered by your type checking and linting tasks, and they can accidentally get outdated.
+
+The web-based documentation included with this library allows to create example files which are both used as regular modules that can be imported for interactive examples, but also read as plain text to generate their corresponding code snippet.
+
+These files are checked as any other source files, and the code snippet will always be in sync with the interactive example.
+
+## Using example files
+
+When you want to create a code example, add a file with the name of your choice inside `src/pattern-library/examples` directory.
+
+You can then reference this file from the web-based pattern library, passing the `exampleFile` prop to the `<Library.Demo />` component.
+
+```tsx
+<Library.Demo exampleFile="some-example-file-name" />
+```
+
+## Considerations
+
+There are some considerations and limitations when working with example files.
+
+- They all need to have the `tsx` extension.
+- Nested directories are not supported, so it's a good idea to add contextual prefixes to example files. For example, all files related with `SelectNext` can be prefixed with `select-next` to make sure they are all grouped together.
+- Example files need to have a preact component as their default export.
+- When generating the source code snippet, import statements are stripped out.

package.json

@@ -14,6 +14,7 @@
     "@hypothesis/frontend-testing": "^1.2.2",
     "@rollup/plugin-babel": "^6.0.0",
     "@rollup/plugin-commonjs": "^25.0.0",
+    "@rollup/plugin-dynamic-import-vars": "^2.1.2",
     "@rollup/plugin-node-resolve": "^15.0.0",
     "@rollup/plugin-virtual": "^3.0.0",
     "@trivago/prettier-plugin-sort-imports": "^4.1.1",

rollup.config.js

@@ -1,5 +1,6 @@
 import { babel } from '@rollup/plugin-babel';
 import commonjs from '@rollup/plugin-commonjs';
+import dynamicImportVars from '@rollup/plugin-dynamic-import-vars';
 import { nodeResolve } from '@rollup/plugin-node-resolve';
 import { string } from 'rollup-plugin-string';
 
@@ -27,6 +28,7 @@ function bundleConfig(name, entryFile) {
         exclude: 'node_modules/**',
         extensions: ['.js', '.ts', '.tsx'],
       }),
+      dynamicImportVars(),
       nodeResolve({ extensions: ['.js', '.ts', '.tsx'] }),
       commonjs({ include: 'node_modules/**' }),
       string({

scripts/serve-pattern-library.js

@@ -11,6 +11,10 @@ export function servePatternLibrary(port = 4001) {
   app.use('/scripts', express.static(path.join(dirname, '../build/scripts')));
   app.use('/styles', express.static(path.join(dirname, '../build/styles')));
   app.use('/images', express.static(path.join(dirname, '../images')));
+  app.use(
+    '/examples',
+    express.static(path.join(dirname, '../src/pattern-library/examples')),
+  );
 
   // For any other path, serve the index.html file to allow client-side routing
   app.get('/:path?', (req, res) => {

src/pattern-library/components/Library.tsx

@@ -1,7 +1,7 @@
 import classnames from 'classnames';
 import { toChildArray, createContext } from 'preact';
 import type { ComponentChildren, JSX } from 'preact';
-import { useMemo, useState, useContext } from 'preact/hooks';
+import { useState, useContext, useEffect, useCallback } from 'preact/hooks';
 import { Link as RouteLink } from 'wouter-preact';
 
 import {
@@ -165,8 +165,28 @@ function Example({ children, title, ...htmlAttributes }: LibraryExampleProps) {
   );
 }
 
+function SimpleError({ message }: { message: string }) {
+  return (
+    <div className="w-full text-red-600 p-2 border rounded border-red-600">
+      {message}
+    </div>
+  );
+}
+
 export type LibraryDemoProps = {
-  children: ComponentChildren;
+  children?: ComponentChildren;
+
+  /**
+   * Example file to read and use as content (to be rendered with syntax
+   * highlighting).
+   * It should be relative to the `pattern-library/examples` dir, and include no
+   * file extension: `exampleFile="some-example"`.
+   *
+   * The file needs to have a default export, which will be used to render the
+   * interactive example
+   */
+  exampleFile?: string;
+
   /** Extra CSS classes for the demo content's immediate parent container */
   classes?: string | string[];
   /** Inline styles to apply to the demo container */
@@ -179,32 +199,66 @@ export type LibraryDemoProps = {
   withSource?: boolean;
 };
 
+function useDemoChildrenAndSource(
+  props: Pick<LibraryDemoProps, 'children' | 'exampleFile'>,
+) {
+  const [source, setSource] = useState<ComponentChildren>();
+  const [children, setChildren] = useState<ComponentChildren>();
+
+  useEffect(() => {
+    if (!props.exampleFile) {
+      setChildren(props.children);
+      setSource(
+        <div className="border w-full rounded-md bg-slate-7 text-color-text-inverted p-4">
+          <ul>
+            {toChildArray(props.children).map((child, idx) => {
+              return (
+                <li key={idx}>
+                  <code>
+                    <pre
+                      className="font-pre whitespace-pre-wrap break-words text-sm"
+                      dangerouslySetInnerHTML={{ __html: jsxToHTML(child) }}
+                    />
+                  </code>
+                </li>
+              );
+            })}
+          </ul>
+        </div>,
+      );
+    } else {
+      import(`../examples/${props.exampleFile}.tsx`)
+        .then(({ default: App }) => setChildren(<App />))
+        .catch(() =>
+          setChildren(
+            <SimpleError
+              message={`Failed loading ../examples/${props.exampleFile}.tsx module`}
+            />,
+          ),
+        );
+      setSource(<Code exampleFile={props.exampleFile} />);
+    }
+  }, [props.exampleFile, props.children]);
+
+  return { source, children };
+}
+
 /**
  * Render a "Demo", with optional source. This will render the children as
  * provided in a tabbed container. If `withSource` is `true`, the JSX source
  * of the children will be provided in a separate "Source" tab from the
  * rendered Demo content.
  */
 function Demo({
-  children,
   classes,
   withSource = false,
   style = {},
   title,
+  ...rest
 }: LibraryDemoProps) {
   const [visibleTab, setVisibleTab] = useState('demo');
-  const source = toChildArray(children).map((child, idx) => {
-    return (
-      <li key={idx}>
-        <code>
-          <pre
-            className="font-pre whitespace-pre-wrap break-words text-sm"
-            dangerouslySetInnerHTML={{ __html: jsxToHTML(child) }}
-          />
-        </code>
-      </li>
-    );
-  });
+  const { children, source } = useDemoChildrenAndSource(rest);
+
   return (
     <div className="my-8 p-2 space-y-1">
       <div className="flex items-center px-2">
@@ -255,11 +309,7 @@ function Demo({
             </div>
           </div>
         )}
-        {visibleTab === 'source' && (
-          <div className="border w-full rounded-md bg-slate-7 text-color-text-inverted p-4">
-            <ul>{source}</ul>
-          </div>
-        )}
+        {visibleTab === 'source' && source}
       </div>
     </div>
   );
@@ -332,48 +382,101 @@ function ChangelogItem({ status, children }: LibraryChangelogItemProps) {
   );
 }
 
+type CodeContentProps =
+  | {
+      /** Code content (to be rendered with syntax highlighting) */
+      content: ComponentChildren;
+    }
+  | {
+      /**
+       * Example file to read and use as content (to be rendered with syntax
+       * highlighting)
+       */
+      exampleFile: string;
+    };
+
 export type LibraryCodeProps = {
-  /** Code content (to be rendered with syntax highlighting) */
-  content: ComponentChildren;
   /** Controls relative code font size */
   size?: 'sm' | 'md';
   /** Caption (e.g. filename, description) of code block */
   title?: ComponentChildren;
-};
+} & CodeContentProps;
+
+function isCodeWithContent(
+  props: CodeContentProps,
+): props is { content: ComponentChildren } {
+  return 'content' in props;
+}
+
+function useCodeContent(
+  props: CodeContentProps,
+): [string | undefined, Error | undefined] {
+  const [codeMarkup, setCodeMarkup] = useState<string>();
+  const [error, setError] = useState<Error>();
+  const setJSXContent = useCallback(
+    (content: ComponentChildren) => setCodeMarkup(jsxToHTML(content)),
+    [],
+  );
+
+  useEffect(() => {
+    if (isCodeWithContent(props)) {
+      setJSXContent(props.content);
+    } else {
+      fetch(`/examples/${props.exampleFile}.tsx`)
+        .then(res => {
+          if (res.status >= 400) {
+            throw new Error(`Failed loading ${props.exampleFile} example file`);
+          }
+          return res.text();
+        })
+        .then(text =>
+          // Remove import statements and trim trailing empty lines
+          text.replace(/^import .*;\n/gm, '').replace(/^\s*\n*/, ''),
+        )
+        .then(setJSXContent)
+        .catch(setError);
+    }
+  }, [props, setJSXContent]);
+
+  return [codeMarkup, error];
+}
 
 /**
  * Render provided `content` as a "code block" example.
  *
  * Long code content will scroll if <Code /> is rendered inside a parent
  * element with constrained dimensions.
  */
-function Code({ content, size, title }: LibraryCodeProps) {
-  const codeMarkup = useMemo(() => jsxToHTML(content), [content]);
+function Code({ size, title, ...rest }: LibraryCodeProps) {
+  const [codeMarkup, error] = useCodeContent(rest);
 
   return (
     <figure className="space-y-2 min-h-0 h-full">
-      <ScrollContainer borderless>
-        <div
-          className={classnames(
-            'unstyled-text bg-slate-7 text-color-text-inverted p-4 rounded-md min-h-0 h-full',
-            { 'text-sm': size === 'sm' },
+      {codeMarkup && (
+        <ScrollContainer borderless>
+          <div
+            className={classnames(
+              'unstyled-text bg-slate-7 text-color-text-inverted p-4 rounded-md min-h-0 h-full',
+              { 'text-sm': size === 'sm' },
+            )}
+          >
+            <Scroll variant="flat">
+              <code className="text-color-text-inverted">
+                <pre
+                  className="whitespace-pre-wrap"
+                  dangerouslySetInnerHTML={{ __html: codeMarkup }}
+                />
+              </code>
+            </Scroll>
+          </div>
+          {title && (
+            <figcaption className="flex justify-end">
+              <span className="italic">{title}</span>
+            </figcaption>
           )}
-        >
-          <Scroll variant="flat">
-            <code className="text-color-text-inverted">
-              <pre
-                className="whitespace-pre-wrap"
-                dangerouslySetInnerHTML={{ __html: codeMarkup }}
-              />
-            </code>
-          </Scroll>
-        </div>
-        {title && (
-          <figcaption className="flex justify-end">
-            <span className="italic">{title}</span>
-          </figcaption>
-        )}
-      </ScrollContainer>
+        </ScrollContainer>
+      )}
+      {error && <SimpleError message={error.message} />}
     </figure>
   );
 }