feat(docs): improve ux

docs/app/Components/ComponentDoc/ComponentExample/ComponentExample.js

@@ -9,10 +9,10 @@ import copyToClipboard from 'copy-to-clipboard'
 
 import {
   exampleContext,
-  repoURL,
-  scrollToAnchor,
   examplePathToHash,
   getFormattedHash,
+  repoURL,
+  scrollToAnchor,
 } from 'docs/app/utils'
 import { Divider, Grid, Menu, Visibility } from 'src'
 import Editor from 'docs/app/Components/Editor/Editor'
@@ -34,12 +34,6 @@ const babelConfig = {
   ],
 }
 
-const headerColumnStyle = {
-  // provide room for absolutely positions toggle code icons
-  minHeight: '4em',
-  paddingRight: '7em',
-}
-
 const childrenStyle = {
   paddingTop: 0,
   maxWidth: '50rem',
@@ -52,11 +46,17 @@ const errorStyle = {
   background: '#fff2f2',
 }
 
+const controlsWrapperStyle = {
+  minHeight: '3rem',
+}
+
 /**
  * Renders a `component` and the raw `code` that produced it.
  * Allows toggling the the raw `code` code block.
  */
 class ComponentExample extends PureComponent {
+  state = {}
+
   static contextTypes = {
     onPassed: PropTypes.func,
   }
@@ -74,20 +74,35 @@ class ComponentExample extends PureComponent {
 
   componentWillMount() {
     const { examplePath } = this.props
-    const sourceCode = this.getOriginalSourceCode()
-
     this.anchorName = examplePathToHash(examplePath)
 
     const exampleElement = this.renderOriginalExample()
-    const markup = renderToStaticMarkup(exampleElement)
 
     this.setState({
       exampleElement,
       handleMouseLeave: this.handleMouseLeave,
       handleMouseMove: this.handleMouseMove,
       showCode: this.isActiveHash(),
-      sourceCode,
-      markup,
+      sourceCode: this.getOriginalSourceCode(),
+      markup: renderToStaticMarkup(exampleElement),
+    })
+  }
+
+  componentWillReceiveProps(nextProps) {
+    // deactivate examples when switching from one to the next
+    if (
+      this.isActiveHash() &&
+      this.isActiveState() &&
+      this.props.location.hash !== nextProps.location.hash
+    ) {
+      this.clearActiveState()
+    }
+  }
+
+  clearActiveState = () => {
+    this.setState({
+      showCode: false,
+      showHTML: false,
     })
   }
 
@@ -116,10 +131,7 @@ class ComponentExample extends PureComponent {
 
     history.replace(location.pathname)
 
-    this.setState({
-      showCode: false,
-      showHTML: false,
-    })
+    this.clearActiveState()
   }
 
   handleDirectLinkClick = () => {
@@ -304,45 +316,19 @@ class ComponentExample extends PureComponent {
   }
 
   setGitHubHrefs = () => {
-    const { examplePath, location } = this.props
+    const { examplePath } = this.props
 
     if (this.ghEditHref && this.ghBugHref) return
 
     // get component name from file path:
     // elements/Button/Types/ButtonButtonExample
     const pathParts = examplePath.split(__PATH_SEP__)
-    const componentName = pathParts[1]
     const filename = pathParts[pathParts.length - 1]
 
     this.ghEditHref = [
       `${repoURL}/edit/master/docs/app/Examples/${examplePath}.js`,
       `?message=docs(${filename}): your description`,
     ].join('')
-
-    this.ghBugHref = [
-      `${repoURL}/issues/new?`,
-      _.map(
-        {
-          title: `fix(${componentName}): your description`,
-          body: [
-            '**Steps to Reproduce**',
-            '1. Do something',
-            '2. Do something else.',
-            '',
-            '**Expected**',
-            `The ${componentName} should do this`,
-            '',
-            '**Result**',
-            `The ${componentName} does not do this`,
-            '',
-            '**Testcase**',
-            `If the docs show the issue, use: ${location.href}`,
-            'Otherwise, fork this to get started: http://codepen.io/levithomason/pen/ZpBaJX',
-          ].join('\n'),
-        },
-        (val, key) => `${key}=${encodeURIComponent(val)}`,
-      ).join('&'),
-    ].join('')
   }
 
   renderJSXControls = () => {
@@ -376,14 +362,6 @@ class ComponentExample extends PureComponent {
             href={this.ghEditHref}
             target='_blank'
           />
-          <Menu.Item
-            active={!!error} // to show the color
-            color={color}
-            icon='bug'
-            content='Issue'
-            href={this.ghBugHref}
-            target='_blank'
-          />
         </Menu>
       </Divider>
     )
@@ -441,7 +419,7 @@ class ComponentExample extends PureComponent {
   }
 
   render() {
-    const { children, description, suiVersion, title } = this.props
+    const { children, description, location, suiVersion, title } = this.props
     const {
       handleMouseLeave,
       handleMouseMove,
@@ -453,9 +431,13 @@ class ComponentExample extends PureComponent {
 
     const isActive = this.isActiveHash() || this.isActiveState()
 
+    const isInFocus = !location.hash || (location.hash && (this.isActiveHash() || isHovering))
+
     const exampleStyle = {
       position: 'relative',
-      transition: 'box-shadow 200ms, background 200ms',
+      transition: 'box-shadow 200ms, background 200ms, opacity 200ms, filter 200ms',
+      opacity: isInFocus ? 1 : 0.4,
+      filter: isInFocus ? 'grayscale(0)' : 'grayscale(1)',
       ...(isActive
         ? {
           background: '#fff',
@@ -479,14 +461,14 @@ class ComponentExample extends PureComponent {
           style={exampleStyle}
         >
           <Grid.Row>
-            <Grid.Column style={headerColumnStyle} width={12}>
+            <Grid.Column width={12}>
               <ComponentExampleTitle
                 description={description}
                 title={title}
                 suiVersion={suiVersion}
               />
             </Grid.Column>
-            <Grid.Column textAlign='right' width={4}>
+            <Grid.Column textAlign='right' width={4} style={controlsWrapperStyle}>
               <ComponentControls
                 anchorName={this.anchorName}
                 onCopyLink={this.handleDirectLinkClick}
@@ -499,9 +481,11 @@ class ComponentExample extends PureComponent {
             </Grid.Column>
           </Grid.Row>
 
-          <Grid.Row columns={1}>
-            {children && <Grid.Column style={childrenStyle}>{children}</Grid.Column>}
-          </Grid.Row>
+          {children && (
+            <Grid.Row columns={1}>
+              <Grid.Column style={childrenStyle}>{children}</Grid.Column>
+            </Grid.Row>
+          )}
 
           <Grid.Row columns={1}>
             <Grid.Column className={`rendered-example ${this.getKebabExamplePath()}`}>

docs/app/Components/ComponentDoc/ComponentExample/ComponentExampleTitle.js

@@ -7,9 +7,6 @@ import { pure } from 'docs/app/HOC'
 const titleStyle = {
   margin: 0,
 }
-const descriptionStyle = {
-  maxWidth: '50rem',
-}
 
 const ComponentExampleTitle = ({ description, title, suiVersion }) => (
   <div>
@@ -27,7 +24,7 @@ const ComponentExampleTitle = ({ description, title, suiVersion }) => (
         )}
       </Header>
     )}
-    {description && <p style={descriptionStyle}>{description}</p>}
+    {description && <p>{description}</p>}
   </div>
 )
 

docs/app/utils/index.js

@@ -1,8 +1,8 @@
 export * from './constants'
 export exampleContext from './exampleContext'
+export examplePathToHash from './examplePathToHash'
 export getComponentGroup from './getComponentGroup'
 export getFormattedHash from './getFormattedHash'
 export getSeeItems from './getSeeItems'
-export scrollToAnchor from './scrollToAnchor'
-export examplePathToHash from './examplePathToHash'
 export parentComponents from './parentComponents'
+export scrollToAnchor from './scrollToAnchor'

docs/app/utils/scrollToAnchor.js

@@ -1,27 +1,30 @@
-const mathSign = Math.sign || function (x) {
-  const val = +x
+const mathSign =
+  Math.sign ||
+  function mathSign(x) {
+    const val = +x
 
-  if (val === 0 || isNaN(val)) return val
-  return val > 0 ? 1 : -1
-}
+    if (val === 0 || isNaN(val)) return val
+    return val > 0 ? 1 : -1
+  }
 
-const scrollToAnchor = (lastOffsetY) => {
+const scrollToAnchor = (lastOffsetY, lastAcceleration = 0.1) => {
   const anchor = location.hash && document.querySelector(location.hash)
   const offsetY = window.scrollY || window.pageYOffset
 
   // no scroll to target, stop
   if (!anchor) return
 
   const elementTop = Math.round(anchor.getBoundingClientRect().top)
-  const scrollStep = Math.ceil((Math.abs(elementTop / 8))) * mathSign(elementTop)
+  const scrollStep = Math.ceil(Math.abs(elementTop / 8)) * mathSign(elementTop)
+  const acceleration = Math.min(1, (lastAcceleration * 100) ** 1.1 / 100)
 
   // if our last step was not applied, stop
   // we've either hit the top, bottom, or arrived at the element
   if (lastOffsetY === offsetY) return
 
   // more scrolling to do!
-  scrollBy(0, scrollStep)
-  requestAnimationFrame(() => scrollToAnchor(offsetY))
+  scrollBy(0, scrollStep * acceleration)
+  requestAnimationFrame(() => scrollToAnchor(offsetY, acceleration))
 }
 
 export default scrollToAnchor

docs/src/examples/.eslintrc

@@ -0,0 +1,5 @@
+{
+  "rules": {
+    "react/prop-types": 0
+  }
+}