feat(v2): Add playgroundPosition config for live codeblock

packages/docusaurus-theme-live-codeblock/package.json

@@ -16,6 +16,7 @@
     "@docusaurus/core": "2.0.0-alpha.70",
     "@philpl/buble": "^0.19.7",
     "clsx": "^1.1.1",
+    "joi": "^17.4.0",
     "parse-numeric-range": "^1.2.0",
     "prism-react-renderer": "^1.1.1",
     "react-live": "^2.2.3"

packages/docusaurus-theme-live-codeblock/src/__tests__/validateThemeConfig.test.js

@@ -0,0 +1,71 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const {validateThemeConfig, DEFAULT_CONFIG} = require('../validateThemeConfig');
+
+function testValidateThemeConfig(themeConfig) {
+  function validate(schema, cfg) {
+    const {value, error} = schema.validate(cfg, {
+      convert: false,
+    });
+    if (error) {
+      throw error;
+    }
+    return value;
+  }
+
+  return validateThemeConfig({validate, themeConfig});
+}
+
+describe('validateThemeConfig', () => {
+  test('minimal config', () => {
+    const liveCodeblock = {
+      showResultBeforeEditor: true,
+    };
+    expect(testValidateThemeConfig({liveCodeblock})).toEqual({
+      liveCodeblock: {
+        ...DEFAULT_CONFIG,
+        ...liveCodeblock,
+      },
+    });
+  });
+
+  test('undefined config 1', () => {
+    const liveCodeblock = undefined;
+    expect(testValidateThemeConfig({liveCodeblock})).toEqual({
+      liveCodeblock: {
+        ...DEFAULT_CONFIG,
+      },
+    });
+  });
+
+  test('unexist config', () => {
+    expect(testValidateThemeConfig({})).toEqual({
+      liveCodeblock: {
+        ...DEFAULT_CONFIG,
+      },
+    });
+  });
+
+  test('empty config', () => {
+    const liveCodeblock = {};
+    expect(testValidateThemeConfig({liveCodeblock})).toEqual({
+      liveCodeblock: {
+        ...DEFAULT_CONFIG,
+      },
+    });
+  });
+
+  test('showResultBeforeEditor not a boolean', () => {
+    const liveCodeblock = {showResultBeforeEditor: 'invalid'};
+    expect(() =>
+      testValidateThemeConfig({liveCodeblock}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"liveCodeblock.showResultBeforeEditor\\" must be a boolean"`,
+    );
+  });
+});

packages/docusaurus-theme-live-codeblock/src/index.js

@@ -6,8 +6,9 @@
  */
 
 const path = require('path');
+const {validateThemeConfig} = require('./validateThemeConfig');
 
-module.exports = function () {
+function theme() {
   return {
     name: 'docusaurus-theme-live-codeblock',
 
@@ -25,4 +26,8 @@ module.exports = function () {
       };
     },
   };
-};
+}
+
+module.exports = theme;
+
+theme.validateThemeConfig = validateThemeConfig;

packages/docusaurus-theme-live-codeblock/src/theme/Playground/index.js

@@ -9,43 +9,72 @@ import * as React from 'react';
 import {LiveProvider, LiveEditor, LiveError, LivePreview} from 'react-live';
 import clsx from 'clsx';
 import Translate from '@docusaurus/Translate';
-
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import styles from './styles.module.css';
 
 export default function Playground({children, theme, transformCode, ...props}) {
+  const {
+    siteConfig: {
+      themeConfig: {liveCodeblock: {showResultBeforeEditor} = {}},
+    } = {},
+  } = useDocusaurusContext();
+
   return (
     <LiveProvider
       code={children.replace(/\n$/, '')}
       transformCode={transformCode || ((code) => `${code};`)}
       theme={theme}
       {...props}>
-      <div
-        className={clsx(
-          styles.playgroundHeader,
-          styles.playgroundEditorHeader,
-        )}>
-        <Translate
-          id="theme.Playground.liveEditor"
-          description="The live editor label of the live codeblocks">
-          Live Editor
-        </Translate>
-      </div>
-      <LiveEditor className={styles.playgroundEditor} />
-      <div
-        className={clsx(
-          styles.playgroundHeader,
-          styles.playgroundPreviewHeader,
-        )}>
-        <Translate
-          id="theme.Playground.result"
-          description="The result label of the live codeblocks">
-          Result
-        </Translate>
-      </div>
+      {showResultBeforeEditor ? (
+        <>
+          <ResultWithHeader />
+          <EditorWithHeader />
+        </>
+      ) : (
+        <>
+          <EditorWithHeader />
+          <ResultWithHeader />
+        </>
+      )}
+    </LiveProvider>
+  );
+}
+
+function ResultWithHeader() {
+  return (
+    <>
+      <Header
+        translateId="theme.Playground.result"
+        description="The result label of the live codeblocks"
+        text="Result"
+      />
       <div className={styles.playgroundPreview}>
         <LivePreview />
         <LiveError />
       </div>
-    </LiveProvider>
+    </>
+  );
+}
+
+function EditorWithHeader() {
+  return (
+    <>
+      <Header
+        translateId="theme.Playground.liveEditor"
+        description="The live editor label of the live codeblocks"
+        text="Live Editor"
+      />
+      <LiveEditor className={styles.playgroundEditor} />
+    </>
+  );
+}
+
+function Header({translateId, description, text}) {
+  return (
+    <div className={clsx(styles.playgroundHeader)}>
+      <Translate id={translateId} description={description}>
+        {text}
+      </Translate>
+    </div>
   );
 }

packages/docusaurus-theme-live-codeblock/src/theme/Playground/styles.module.css

@@ -10,18 +10,15 @@
   padding: 0.75rem;
   text-transform: uppercase;
   font-weight: bold;
+  background: var(--ifm-color-emphasis-200);
+  color: var(--ifm-color-content);
 }
 
-.playgroundEditorHeader {
+.playgroundHeader:first-of-type {
   background: var(--ifm-color-emphasis-600);
   color: var(--ifm-color-content-inverse);
 }
 
-.playgroundPreviewHeader {
-  background: var(--ifm-color-emphasis-200);
-  color: var(--ifm-color-content);
-}
-
 .playgroundEditor {
   font-family: var(--ifm-font-family-monospace) !important;
   /*rtl:ignore*/

packages/docusaurus-theme-live-codeblock/src/validateThemeConfig.js

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const Joi = require('joi');
+
+const DEFAULT_CONFIG = {
+  showResultBeforeEditor: false,
+};
+exports.DEFAULT_CONFIG = DEFAULT_CONFIG;
+
+const Schema = Joi.object({
+  liveCodeblock: Joi.object({
+    showResultBeforeEditor: Joi.boolean().default(
+      DEFAULT_CONFIG.showResultBeforeEditor,
+    ),
+  })
+    .label('themeConfig.liveCodeblock')
+    .default(DEFAULT_CONFIG),
+});
+exports.Schema = Schema;
+
+exports.validateThemeConfig = function ({validate, themeConfig}) {
+  return validate(Schema, themeConfig);
+};

website/docs/guides/markdown-features/markdown-features-code-blocks.mdx

@@ -292,6 +292,8 @@ function Clock(props) {
 }
 ```
 
+### Imports
+
 :::caution react-live and imports
 
 It is not possible to import components directly from the react-live code editor, you have to define available imports upfront.
@@ -343,6 +345,25 @@ function MyPlayground(props) {
 }
 ```
 
+### Configuration
+
+You can also configurate `@docusaurus/theme-live-codeblock` plugin with the following parameters:
+
+```jsx title="docusaurus.config.js"
+module.exports = {
+  // ...
+  themeConfig: {
+    // ...
+    // highlight-start
+    liveCodeblock: {
+      // Optional
+      showResultBeforeEditor: false,
+    },
+    // highlight-end
+  },
+};
+```
+
 ## Multi-language support code blocks
 
 With MDX, you can easily create interactive components within your documentation, for example, to display code in multiple programming languages and switching between them using a tabs component.