fix(react-docs): Fix live mode toggling (patternfly#780)

* fix(react-docs): Fix live mode toggling * update readme and add liveScope prop
redallen · Oct 16, 2018 · f7cc358 · f7cc358
1 parent 9cc0092
commit f7cc358
Show file tree

Hide file tree

Showing 4 changed files with 107 additions and 13 deletions.
diff --git a/packages/patternfly-4/react-docs/README.md b/packages/patternfly-4/react-docs/README.md
@@ -23,3 +23,64 @@ To build the site.
 ```sh
 yarn build:site
 ```
+
+## Live examples
+### Disabling globally
+You can turn off the functionality to live edit the examples globally by settings GATSBY_LIVE_EXAMPLES to false, either by editing [.env.development](./.env.development) and [.env.production](./.env.production) or by setting it in the CLI prior to starting the docs:
+```sh
+GATSBY_LIVE_EXAMPLES=false yarn start:pf4
+```
+### Other example settings
+There are some special static fields you can specify in the example to change behavior:
+```sh
+// Sets the title for the example
+static title = 'Example title';
+
+// Sets the description for the example
+static description = 'Example description';
+
+// True by default, set to false to disable live editing for this example
+static live = false;
+
+// Pass imports into the liveScope object so it is available to the live editor.
+// By default, the live editor only knows about React.*, react-core components, react-icons, and the react-styles css function
+// If you have additional imports in your examples, they can be passed to the live editor scope like this:
+static liveScope = { spacingStyles };
+
+// Additional styles relevant to the example display can be added via a static field getContainerProps.
+// getContainerProps is an import to a .js file that has content such as:
+/*
+import { css, StyleSheet } from '@patternfly/react-styles';
+const styles = StyleSheet.create({
+  demoLayout: {
+    '& > .pf-c-alert': {
+      marginBottom: '0.5rem'
+    }
+  }
+});
+export default () => ({ className: css(styles.demoLayout) });
+*/
+static getContainerProps = getContainerProps;
+
+```
+In the examples *.docs.js file, you can specify these properties:
+```sh
+// Main title for the examples
+title: 'Alert',
+
+// Components to display in the props table
+components: {
+  Alert
+},
+
+// Enums that need to be evaluated for the props table
+enumValues: {
+  'Object.values(AlertVariant)': Object.values(AlertVariant)
+},
+
+// The examples
+examples: [SuccessExample, DangerExample, InfoExample, WarningExample],
+// True to show links instead of inline examples, also turns live editing off
+
+fullPageOnly: false
+```
diff --git a/packages/patternfly-4/react-docs/src/components/componentDocs/componentDocs.js b/packages/patternfly-4/react-docs/src/components/componentDocs/componentDocs.js
@@ -51,6 +51,7 @@ class ComponentDocs extends React.PureComponent {
                 images={images}
                 fullPageOnly={fullPageOnly}
                 live={ComponentExample.live}
+                liveScope={ComponentExample.liveScope}
                 name={componentDocs.displayName}
                 {...(ComponentExample.getContainerProps ? ComponentExample.getContainerProps() : {})}
               >

diff --git a/packages/patternfly-4/react-docs/src/components/example/example.js b/packages/patternfly-4/react-docs/src/components/example/example.js
@@ -17,7 +17,8 @@ const propTypes = {
   raw: PropTypes.string,
   path: PropTypes.string,
   images: PropTypes.array,
-  live: PropTypes.bool
+  live: PropTypes.bool,
+  liveScope: PropTypes.object
 };
 
 const defaultProps = {
@@ -29,7 +30,8 @@ const defaultProps = {
   raw: '',
   path: '',
   images: [],
-  live: true
+  live: true,
+  liveScope: {}
 };
 
 const GATSBY_LIVE_EXAMPLES = process.env.GATSBY_LIVE_EXAMPLES === 'true';
@@ -45,6 +47,7 @@ const Example = ({
   path: examplePath,
   images,
   live,
+  liveScope,
   ...props
 }) => {
   // Display full page link
@@ -73,16 +76,34 @@ const Example = ({
       </Section>
     );
   }
+
   return (
     <div>
       <Title size="lg">{title}</Title>
       {Boolean(description) && <p className={css(styles.description)}>{description}</p>}
-      {GATSBY_LIVE_EXAMPLES && live ? (
-        <LiveDemo raw={raw.trim()} path={examplePath} images={images} className={className} />
+      {GATSBY_LIVE_EXAMPLES ? (
+        <React.Fragment>
+          {!live && (
+            <div className={css(className, styles.example)} {...props}>
+              {children}
+            </div>
+          )}
+          <LiveDemo
+            raw={raw.trim()}
+            path={examplePath}
+            images={images}
+            className={className}
+            live={live}
+            liveScope={liveScope}
+          />
+        </React.Fragment>
       ) : (
-          <div className={css(className, styles.example)} {...props}>
-            {children}
-          </div>
+          <React.Fragment>
+            <div className={css(className, styles.example)} {...props}>
+              {children}
+            </div>
+            <LiveDemo raw={raw.trim()} path={examplePath} live={false} />
+          </React.Fragment>
         )}
     </div>
   );

diff --git a/packages/patternfly-4/react-docs/src/components/example/liveDemo.js b/packages/patternfly-4/react-docs/src/components/example/liveDemo.js
@@ -15,17 +15,19 @@ const propTypes = {
   raw: PropTypes.string.isRequired,
   path: PropTypes.string,
   images: PropTypes.array,
-  live: PropTypes.bool
+  live: PropTypes.bool,
+  liveScope: PropTypes.object
 };
 
 const defaultProps = {
   className: '',
   path: '',
   images: [],
-  live: true
+  live: true,
+  liveScope: {}
 };
 
-const scopePlayground = { React, ...CoreComponents, ...CoreIcons, css, styles };
+const scopePlayground = { React, ...CoreComponents, ...CoreIcons, css };
 
 const transformCode = code => {
   try {
@@ -35,7 +37,7 @@ const transformCode = code => {
     code = code.replace(/^\s*\/\/.*$/gm, '');
     code = code.replace(/extends Component/gm, 'extends React.Component');
     code = code.replace(/^\s*export.*$/gm, '');
-    code = code.replace(/^\s*static.*$/gm, '');
+    code = code.replace(/^\s*static(.|\s)*?;$/gm, '');
     const transformedCode = transform(code, {
       presets: ['react', 'stage-2']
     }).code;
@@ -72,14 +74,15 @@ class LiveDemo extends React.Component {
   };
 
   render() {
-    const { className, raw, images, live, path } = this.props;
+    const { className, raw, images, live, liveScope, path } = this.props;
     const { codeOpen, showCopyMessage } = this.state;
 
     const GITHUB_BASE = 'https://github.com/patternfly/patternfly-react/blob/master/packages/patternfly-4';
     const examplePath = `${GITHUB_BASE}${path.substr(5)}`;
 
     const scope = {
-      ...scopePlayground
+      ...scopePlayground,
+      ...liveScope
     };
     for (const image of images) {
       const searchIndex = raw.search(image.name);
@@ -126,6 +129,14 @@ class LiveDemo extends React.Component {
                 Copied to clipboard
               </CoreComponents.Text>
             </CoreComponents.TextContent>
+            {codeOpen &&
+              !live && (
+                <CoreComponents.TextContent className={css(styles.messageShow)}>
+                  <CoreComponents.Text component="pre" className={css(styles.messageText)}>
+                    Live edititing disabled
+                  </CoreComponents.Text>
+                </CoreComponents.TextContent>
+              )}
           </div>
           {codeOpen && <LiveEditor className={styles.code} ignoreTabKey contentEditable={live} />}
           {live && <LiveError />}