docs(fix): reorganized usage guide for new users

.prettierrc.json

@@ -1,5 +1,6 @@
 {
   "$schema": "http://json.schemastore.org/prettierrc",
+  "arrowParens": "always",
   "jsxSingleQuote": true,
   "printWidth": 100,
   "tabWidth": 2,
@@ -18,6 +19,12 @@
       "options": {
         "semi": true
       }
+    },
+    {
+      "files": "docs/src/examples/**/*.js",
+      "options": {
+        "printWidth": 80
+      }
     }
   ]
 }

docs/src/components/CodeEditor/CodeEditor.js

@@ -96,7 +96,11 @@ const semanticUIReactCompleter = {
 }
 
 const CodeEditor = props => (
-  <Ace {...props} enableBasicAutocompletion={[semanticUIReactCompleter]} />
+  <Ace
+    {...props}
+    name={`docs-editor-${_.uniqueId()}`}
+    enableBasicAutocompletion={[semanticUIReactCompleter]}
+  />
 )
 
 export default CodeEditor

docs/src/components/CodeEditor/CodeEditorUniveral.js

@@ -19,11 +19,10 @@ const CodeEditor = isBrowser()
   : () => null
 
 function CodeEditorUniveral(props) {
-  const { id, mode, readOnly, value, ...rest } = props
+  const { mode, readOnly, value, ...rest } = props
 
   return (
     <CodeEditor
-      name={id}
       mode={mode}
       theme='tomorrow_night'
       width='100%'

docs/src/components/CodeSnippet/CodeSnippet.js

@@ -2,10 +2,9 @@ import React from 'react'
 import PropTypes from 'prop-types'
 
 import CodeEditor, { EDITOR_BACKGROUND_COLOR } from 'docs/src/components/CodeEditor'
-import { btoa } from 'docs/src/utils'
+import formatCode from '../../utils/formatCode'
 
 const containerStyle = {
-  marginBottom: '2rem',
   padding: '1rem',
   position: 'relative',
   background: EDITOR_BACKGROUND_COLOR,
@@ -24,28 +23,35 @@ const labelStyle = {
   zIndex: 100,
 }
 
-const CodeSnippet = ({ label, mode, value, ...rest }) => (
-  <div style={containerStyle}>
+const CodeSnippet = ({ fitted, label, mode, value, ...rest }) => (
+  <div style={{ ...containerStyle, margin: fitted ? 0 : '1rem 0' }}>
     <div style={labelStyle}>{label || mode}</div>
 
     <CodeEditor
-      id={btoa(value)}
       highlightActiveLine={false}
       highlightGutterLine={false}
       mode={mode}
       readOnly
       showGutter={false}
       showCursor={false}
-      value={value}
+      value={(mode === 'sh'
+        ? value.replace(/^/g, '$  ')
+        : formatCode(value, mode === 'html' ? 'html' : 'babylon')
+      ).trim()}
       {...rest}
     />
   </div>
 )
 
 CodeSnippet.propTypes = {
+  fitted: PropTypes.bool,
   label: PropTypes.string,
   mode: PropTypes.oneOf(['html', 'jsx', 'sh']).isRequired,
   value: PropTypes.string.isRequired,
 }
 
+CodeSnippet.defaultProps = {
+  mode: 'jsx',
+}
+
 export default CodeSnippet

docs/src/components/ComponentDoc/ComponentExample/ComponentExample.js

@@ -172,7 +172,9 @@ class ComponentExample extends PureComponent {
   }
 
   getKebabExamplePath = () => {
-    if (!this.kebabExamplePath) this.kebabExamplePath = _.kebabCase(this.props.examplePath)
+    if (!this.kebabExamplePath) {
+      this.kebabExamplePath = _.kebabCase(this.props.examplePath)
+    }
 
     return this.kebabExamplePath
   }
@@ -277,20 +279,14 @@ class ComponentExample extends PureComponent {
               <Grid.Column width={16} style={editorStyle}>
                 {showCode && (
                   <ComponentExampleRenderEditor
-                    editorId={`${this.getKebabExamplePath()}-jsx`}
                     githubEditHref={this.getGithubEditHref()}
                     originalValue={this.getOriginalSourceCode()}
                     value={sourceCode}
                     error={error}
                     onChange={this.handleChangeCode}
                   />
                 )}
-                {showHTML && (
-                  <ComponentExampleRenderHtml
-                    editorId={`${this.getKebabExamplePath()}-html`}
-                    value={htmlMarkup}
-                  />
-                )}
+                {showHTML && <ComponentExampleRenderHtml value={htmlMarkup} />}
               </Grid.Column>
             )}
             {isActive && !error && <CarbonAdNative inverted={this.isActiveState()} />}

docs/src/components/ComponentDoc/ComponentExample/ComponentExampleRenderEditor.js

@@ -33,7 +33,6 @@ class ComponentExampleRenderEditor extends PureComponent {
   state = {}
 
   static propTypes = {
-    editorId: PropTypes.string.isRequired,
     examplePath: PropTypes.string.isRequired,
     githubEditHref: PropTypes.string.isRequired,
     onChange: PropTypes.func.isRequired,
@@ -129,12 +128,12 @@ class ComponentExampleRenderEditor extends PureComponent {
   }
 
   render() {
-    const { editorId, error, onChange, value } = this.props
+    const { error, onChange, value } = this.props
 
     return (
       <div style={rootStyle}>
         {this.renderEditorMenu()}
-        <Editor id={editorId} value={value} onChange={onChange} />
+        <Editor value={value} onChange={onChange} />
         {error && (
           <Segment color='red' basic secondary inverted style={errorStyle}>
             {error}

docs/src/components/ComponentDoc/ComponentExample/ComponentExampleRenderHtml.js

@@ -3,7 +3,6 @@ import React, { PureComponent } from 'react'
 import { Divider } from 'semantic-ui-react'
 
 import Editor, { EDITOR_BACKGROUND_COLOR } from 'docs/src/components/CodeEditor'
-import formatCode from 'docs/src/utils/formatCode'
 
 const rootStyle = {
   padding: '1rem',
@@ -16,22 +15,21 @@ const dividerStyle = {
 
 export default class ComponentExampleRenderHtml extends PureComponent {
   static propTypes = {
-    editorId: PropTypes.string.isRequired,
     value: PropTypes.string.isRequired,
   }
 
   render() {
-    const { editorId, value } = this.props
+    const { value } = this.props
 
     // remove new line at eof after formatting for a tighter fit
-    const formattedCode = formatCode(value, 'html').replace(/\s+$/, '')
+    const formattedCode = value.trim()
 
     return (
       <div style={rootStyle}>
         <Divider fitted inverted horizontal style={dividerStyle}>
           HTML
         </Divider>
-        <Editor id={editorId} mode='html' value={formattedCode} readOnly />
+        <Editor mode='html' value={formattedCode} readOnly />
       </div>
     )
   }

docs/src/components/DocumentationPage/DocumentationPage.js

@@ -1,7 +1,7 @@
 import PropTypes from 'prop-types'
 import React from 'react'
 import { withRouteData, withSiteData } from 'react-static'
-import { Container } from 'semantic-ui-react'
+import { Container, Divider } from 'semantic-ui-react'
 
 import DocsLayout from 'docs/src/components/DocsLayout'
 import * as components from './components'
@@ -11,8 +11,10 @@ const DocumentationPage = ({ pageName, ...rest }) => {
 
   return (
     <DocsLayout additionalTitle={meta.title}>
-      <Container style={{ padding: 15 }}>
+      <Container text>
+        <Divider hidden />
         <MarkdownComponent {...rest} components={components} />
+        <Divider hidden section />
       </Container>
     </DocsLayout>
   )

docs/src/components/DocumentationPage/components.js

@@ -1,4 +1,3 @@
-import _ from 'lodash'
 import React from 'react'
 import { Link } from 'react-static'
 import { Header } from 'semantic-ui-react'
@@ -13,11 +12,10 @@ export const a = ({ children, href }) => <Link to={href}>{children}</Link>
 
 export const code = ({ className, children }) => {
   const mode = className.replace('language-', '')
-  const value = _.trim(children)
 
-  return <CodeSnippet mode={mode} value={value} />
+  return <CodeSnippet mode={mode} value={children} />
 }
 
-export const h1 = ({ children }) => <Header as='h1' content={children} />
+export const h1 = ({ children }) => <Header as='h1' content={children} textAlign='center' />
 
 export const h2 = ({ children }) => <Header as='h2' content={children} dividing />

docs/src/pages/Introduction.js

@@ -6,7 +6,7 @@ import { Container, Divider, Grid, Header, Icon, Label, List, Segment } from 'se
 import DocsLayout from 'docs/src/components/DocsLayout'
 import Editor from 'docs/src/components/CodeEditor'
 import Logo from 'docs/src/components/Logo/Logo'
-import { btoa, semanticUIDocsURL, repoURL } from 'docs/src/utils'
+import { semanticUIDocsURL, repoURL } from 'docs/src/utils'
 
 const AccordionJSX = `const panels = [{
   title: 'What is a dog?',
@@ -113,7 +113,7 @@ const Comparison = ({ jsx, html }) => (
         <Label color='grey' size='tiny' attached='top left'>
           JSX
         </Label>
-        <Editor id={btoa(jsx)} value={jsx} readOnly />
+        <Editor value={jsx} readOnly />
       </Grid.Column>
       <Grid.Column largeScreen='2' only='large screen' textAlign='center'>
         <Divider vertical>
@@ -124,7 +124,7 @@ const Comparison = ({ jsx, html }) => (
         <Label color='grey' size='tiny' attached='top right'>
           Rendered HTML
         </Label>
-        <Editor id={btoa(html)} mode='html' value={html} readOnly />
+        <Editor mode='html' value={html} readOnly />
       </Grid.Column>
     </Grid>
   </Segment>
@@ -168,8 +168,8 @@ const Introduction = ({ pkg }) => (
       </Segment>
 
       {/* ----------------------------------------
-        *  jQuery Free
-        * -------------------------------------- */}
+       *  jQuery Free
+       * -------------------------------------- */}
       <Segment basic padded>
         <Header as='h2' dividing>
           jQuery Free
@@ -186,8 +186,8 @@ const Introduction = ({ pkg }) => (
       </Segment>
 
       {/* ----------------------------------------
-        *  Declarative API
-        * -------------------------------------- */}
+       *  Declarative API
+       * -------------------------------------- */}
       <Segment basic padded>
         <Header as='h2' dividing>
           Declarative API
@@ -199,8 +199,8 @@ const Introduction = ({ pkg }) => (
       </Segment>
 
       {/* ----------------------------------------
-        *  Augmentation
-        * -------------------------------------- */}
+       *  Augmentation
+       * -------------------------------------- */}
       <Segment basic padded>
         <Header as='h2' dividing>
           Augmentation
@@ -221,8 +221,8 @@ const Introduction = ({ pkg }) => (
       </Segment>
 
       {/* ----------------------------------------
-        *  Shorthand Props
-        * -------------------------------------- */}
+       *  Shorthand Props
+       * -------------------------------------- */}
       <Segment basic padded>
         <Header as='h2' dividing>
           Shorthand Props
@@ -262,8 +262,8 @@ const Introduction = ({ pkg }) => (
       </Segment>
 
       {/* ----------------------------------------
-        *  Sub Components
-        * -------------------------------------- */}
+       *  Sub Components
+       * -------------------------------------- */}
       <Segment basic padded>
         <Header as='h2' dividing>
           Sub Components
@@ -276,8 +276,8 @@ const Introduction = ({ pkg }) => (
       </Segment>
 
       {/* ----------------------------------------
-        *  Auto Controlled State
-        * -------------------------------------- */}
+       *  Auto Controlled State
+       * -------------------------------------- */}
       <Segment basic padded>
         <Header as='h2' dividing>
           Auto Controlled State