feat: Add support for simplified interactive demo syntax using code blocks

.yarn/patches/react-live-npm-4.1.7-7b41625faa.patch

@@ -0,0 +1,26 @@
+diff --git a/dist/index.js b/dist/index.js
+index 7bcfee33d9cfaa6c5f9d7da40335ec2551f932b6..4c29438cb94412d25aed193f9c86f20ccebb9009 100644
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -168,7 +168,7 @@ var import_sucrase = require("sucrase");
+ var defaultTransforms = ["jsx", "imports"];
+ function transform(opts = {}) {
+   const transforms = Array.isArray(opts.transforms) ? opts.transforms.filter(Boolean) : defaultTransforms;
+-  return (code) => (0, import_sucrase.transform)(code, { transforms }).code;
++  return (code) => (0, import_sucrase.transform)(code, { transforms, jsxPragma: 'jsx' }).code;
+ }
+
+ // src/utils/transpile/errorBoundary.tsx
+diff --git a/dist/index.mjs b/dist/index.mjs
+index 44a3fbed4fc0545b75235add7369a262e8ee5220..6cfad17b4ce81553bac1243b7421f5f75ade43fc 100644
+--- a/dist/index.mjs
++++ b/dist/index.mjs
+@@ -127,7 +127,7 @@ import { transform as _transform } from "sucrase";
+ var defaultTransforms = ["jsx", "imports"];
+ function transform(opts = {}) {
+   const transforms = Array.isArray(opts.transforms) ? opts.transforms.filter(Boolean) : defaultTransforms;
+-  return (code) => _transform(code, { transforms }).code;
++  return (code) => _transform(code, { transforms, jsxPragma: 'jsx' }).code;
+ }
+
+ // src/utils/transpile/errorBoundary.tsx

packages/docusaurus-theme/package.json

@@ -39,7 +39,7 @@
     "moment": "^2.30.1",
     "prism-react-renderer": "^2.3.1",
     "react-is": "^18.3.1",
-    "react-live": "^4.1.7"
+    "react-live": "patch:react-live@npm%3A4.1.7#~/.yarn/patches/react-live-npm-4.1.7-7b41625faa.patch"
   },
   "peerDependencies": {
     "react": "^18.0.0",

packages/docusaurus-theme/src/components/demo/context.ts

@@ -2,7 +2,15 @@ import { createContext, useContext } from 'react';
 import { DemoSourceMeta } from './demo';
 
 export interface DemoContextObject {
+  /**
+   * Array of all available sources for this demo instance
+   */
   sources: DemoSourceMeta[];
+
+  /**
+   * Add source to the list of available sources
+   * This should only be used internally when initializing the component!
+   */
   addSource(source: DemoSourceMeta): void;
 }
 

packages/docusaurus-theme/src/components/demo/demo.tsx

@@ -21,6 +21,7 @@ import { DemoSource } from './source';
 import { demoDefaultScope } from './scope';
 import { DemoActionsBar } from './actions_bar';
 import { demoCodeTransformer } from './code_transformer';
+import { DemoPreviewProps } from './preview/preview';
 
 export interface DemoSourceMeta {
   code: string;
@@ -40,6 +41,7 @@ export interface DemoProps extends PropsWithChildren {
    * The default scope exposes all React and EUI exports.
    */
   scope?: Record<string, unknown>;
+  previewPadding?: DemoPreviewProps['padding'];
 }
 
 const getDemoStyles = (euiTheme: UseEuiTheme) => ({
@@ -56,12 +58,13 @@ const getDemoStyles = (euiTheme: UseEuiTheme) => ({
 export const Demo = ({
   children,
   scope,
-  isSourceOpen: _isSourceOpen = true
+  isSourceOpen: _isSourceOpen = false,
+  previewPadding,
 }: DemoProps) => {
   const styles = useEuiMemoizedStyles(getDemoStyles);
   const [sources, setSources] = useState<DemoSourceMeta[]>([]);
   const [isSourceOpen, setIsSourceOpen] = useState<boolean>(_isSourceOpen);
-  const activeSource = sources[0];
+  const activeSource = sources[0] || null;
 
   // liveProviderKey restarts the demo to its initial state
   const [liveProviderKey, setLiveProviderKey] = useState<number>(0);
@@ -101,7 +104,7 @@ export const Demo = ({
           theme={prismThemes.dracula}
           scope={finalScope}
         >
-          <DemoPreview />
+          <DemoPreview padding={previewPadding} />
           <DemoActionsBar
             isSourceOpen={isSourceOpen}
             setSourceOpen={setIsSourceOpen}

packages/docusaurus-theme/src/components/demo/editor/editor.tsx

@@ -8,7 +8,7 @@
 
 import { LiveEditor, LiveError } from 'react-live';
 import { css } from '@emotion/react';
-import { useEuiMemoizedStyles, useEuiTheme } from '@elastic/eui';
+import { useEuiMemoizedStyles } from '@elastic/eui';
 
 const getEditorStyles = () => ({
   editor: css`

packages/docusaurus-theme/src/components/demo/preview/preview.tsx

@@ -3,11 +3,16 @@ import { LivePreview } from 'react-live';
 import BrowserOnly from '@docusaurus/BrowserOnly';
 import ErrorBoundary from '@docusaurus/ErrorBoundary';
 import { ErrorBoundaryErrorMessageFallback } from '@docusaurus/theme-common';
-import { UseEuiTheme, EuiFlexGroup, useEuiTheme } from '@elastic/eui';
+import { UseEuiTheme, useEuiTheme, EuiPaddingSize, euiPaddingSize } from '@elastic/eui';
+import { CSSProperties } from 'react';
+
+export interface DemoPreviewProps {
+  padding?: EuiPaddingSize;
+}
 
 const getPreviewStyles = (euiTheme: UseEuiTheme) => ({
   previewWrapper: css`
-    padding: ${euiTheme.euiTheme.size.l};
+    padding: var(--docs-demo-preview-padding);
     border-radius: var(--docs-demo-border-radius);
   `,
 });
@@ -21,16 +26,21 @@ const PreviewLoader = () => (
   <div>Loading...</div>
 );
 
-export const DemoPreview = () => {
+export const DemoPreview = ({ padding = 'l' }: DemoPreviewProps) => {
   const euiTheme = useEuiTheme();
   const styles = getPreviewStyles(euiTheme);
+  const paddingSize = euiPaddingSize(euiTheme, padding);
+
+  const style = {
+    '--docs-demo-preview-padding': paddingSize,
+  } as CSSProperties;
 
   return (
     <BrowserOnly fallback={<PreviewLoader />}>
       {() => (
         <>
           <ErrorBoundary fallback={(params: any) => <ErrorBoundaryErrorMessageFallback {...params} />}>
-            <div css={styles.previewWrapper}>
+            <div css={styles.previewWrapper} style={style}>
               <LivePreview />
             </div>
           </ErrorBoundary>

packages/docusaurus-theme/src/components/demo/scope.ts

@@ -1,5 +1,14 @@
 import React from 'react';
 import * as EUI from '@elastic/eui';
+import * as EmotionReact from '@emotion/react';
+
+/**
+ * A custom client-side require() alternative to inform users it's not available
+ * in our demo environment
+ */
+const clientSideRequire = () => {
+  throw new Error('require() is not accessible in the interactive demo environment! All EUI and React exports are available in the global scope for you to use without the need to import them.');
+}
 
 export const demoDefaultScope: Record<string, unknown> = {
   // React
@@ -8,4 +17,9 @@ export const demoDefaultScope: Record<string, unknown> = {
 
   // EUI exports
   ...EUI,
+
+  // Emotion
+  ...EmotionReact,
+
+  require: clientSideRequire,
 };

packages/docusaurus-theme/src/components/demo/source/get_source_from_children.ts

@@ -12,6 +12,11 @@ export interface SourceMeta {
  * Get source string from given children.
  */
 export const getSourceFromChildren = (children: ReactNode): string | null => {
+  // Direct (non-MDX) usage almost always passes a string
+  if (typeof children === 'string') {
+    return children;
+  }
+
   if (Children.count(children) !== 1 || !isElement(children)) {
     // This should never happen
     return null;

packages/docusaurus-theme/src/theme/CodeBlock/index.tsx

@@ -0,0 +1,44 @@
+import React, { isValidElement, type ReactNode } from 'react';
+import { EuiCodeBlock } from '@elastic/eui';
+import type { Props } from '@theme/CodeBlock';
+import { Demo } from '../../components/demo';
+
+/**
+ * Best attempt to make the children a plain string so it is copyable. If there
+ * are react elements, we will not be able to copy the content, and it will
+ * return `children` as-is; otherwise, it concatenates the string children
+ * together.
+ */
+function maybeStringifyChildren(children: ReactNode): ReactNode {
+  if (React.Children.toArray(children).some((el) => isValidElement(el))) {
+    return children;
+  }
+  // The children is now guaranteed to be one/more plain strings
+  return Array.isArray(children) ? children.join('') : (children as string);
+}
+
+export default function CodeBlock({
+  children: rawChildren,
+  metastring,
+  className,
+  ...props
+}: Props): JSX.Element {
+  const children = maybeStringifyChildren(rawChildren);
+  const language = className?.replace('language-', '') || undefined;
+
+  if (metastring?.startsWith('interactive')) {
+    return <Demo {...props}>{children}</Demo>;
+  }
+
+  return (
+    <EuiCodeBlock
+      {...props}
+      fontSize="m"
+      overflowHeight={450}
+      language={language}
+      isCopyable
+    >
+      {children}
+    </EuiCodeBlock>
+  );
+}

packages/docusaurus-theme/src/theme/MDXComponents/Code.tsx

@@ -1,13 +1,9 @@
 import React from 'react';
 import type CodeType from '@theme-init/MDXComponents/Code';
+import CodeBlock from '@theme/CodeBlock';
 import type { WrapperProps } from '@docusaurus/types';
 import { css } from '@emotion/react';
-import {
-  EuiCode,
-  EuiCodeBlock,
-  useEuiMemoizedStyles,
-  UseEuiTheme,
-} from '@elastic/eui';
+import { EuiCode, useEuiMemoizedStyles, UseEuiTheme } from '@elastic/eui';
 
 type Props = WrapperProps<typeof CodeType>;
 
@@ -33,15 +29,24 @@ const Code = ({ children, className, ...rest }: Props): JSX.Element => {
       )
     : false;
 
-  return isInlineCode ? (
-    <EuiCode {...rest} language={language} css={styles.code}>
-      {children}
-    </EuiCode>
-  ) : (
-    <EuiCodeBlock {...rest} fontSize="m" language={language}>
+  if (isInlineCode) {
+    return (
+      <EuiCode
+        {...rest}
+        className={className}
+        language={language}
+        css={styles.code}
+      >
+        {children}
+      </EuiCode>
+    );
+  }
+
+  return (
+    <CodeBlock className={className} {...rest}>
       {children}
-    </EuiCodeBlock>
-  );
+    </CodeBlock>
+  )
 };
 
 export default Code;

packages/docusaurus-theme/src/theme/theme.d.ts

@@ -118,6 +118,31 @@ declare module '@theme-original/EditThisPage' {
   export default function EditThisPage(props: Props): JSX.Element;
 }
 
+// original: https://github.com/facebook/docusaurus/blob/fa743c81defd24e22eae45c81bd79eb8ec2c4ef0/packages/docusaurus-theme-classic/src/theme-classic.d.ts#L364
+declare module '@theme/CodeBlock' {
+  import type { ReactNode } from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+    readonly className?: string;
+    readonly metastring?: string;
+    readonly title?: string;
+    readonly language?: string;
+    readonly showLineNumbers?: boolean;
+  }
+
+  export default function CodeBlock(props: Props): JSX.Element;
+}
+
+// original: https://github.com/facebook/docusaurus/blob/8b877d27d4b1bcd5c2ee13dde8332407a1c26447/packages/docusaurus-theme-classic/src/theme-classic.d.ts#L510
+declare module '@theme/MDXComponents/Code' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'code'> {}
+
+  export default function MDXCode(props: Props): JSX.Element;
+}
+
 // original: https://github.com/facebook/docusaurus/blob/fa743c81defd24e22eae45c81bd79eb8ec2c4ef0/packages/docusaurus-theme-classic/src/theme-classic.d.ts#L563
 declare module '@theme-original/DocSidebar' {
   import type { PropSidebarItem } from '@docusaurus/plugin-content-docs';