feat(docs): adding 'behaviors' section to menu (#119)

* editing,adding behaviours and adding acc. description for components

* removing divider role as it was not correctly implemented

* returning back divider file, which deleted by mistake

* adding tests

* adding test, modify tests, change format of description

* another changes in descriptions

* draft adding acc behaviours to sidebar menu

* first raw version of behaviours in menu

* adding parsing, UI improvement

* adding link to component

* another polish, moving comments, adding extract-comment package

* removing not used commented code

* adding comments to particular behavior files

* adding another doc for particular behaviors

* cleaning PR

* toggleButton Behavior updated coresponding master

* removing type from constants, taking from JSON or changed to hardcoded string

* improving showing behaviors in menu

* removing behavior description changes, it will be moved to new PR

* removing description changes in component, it will be moved to new PR

* removing changes in componentDocTag, it will go in next PR

* removing unused imports

* changes after review

* fix after PR

* - add behaviors menu to gulp watch

* adding changelog

* another fixes after json file was renamed

Author: kolaps33

.gitignore

@@ -10,6 +10,7 @@ coverage/
 dist/
 docs/src/componentInfo
 docs/src/componentMenu.json
+docs/src/behaviorMenu.json
 docs/src/exampleMenus
 docs/dist/
 dll/

CHANGELOG.md

@@ -22,6 +22,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Features
 - Add `state` to `props` in component styling functions @Bugaa92 ([#173](https://github.com/stardust-ui/react/pull/173))
+- Adding 'behaviors' section to the menu, under the components @kolaps33 ([#119] (https://github.com/stardust-ui/react/pull/119)
 
 <!--------------------------------[ v0.5.0 ]------------------------------- -->
 ## [v0.5.0](https://github.com/stardust-ui/react/tree/v0.5.0) (2018-08-30)

build/gulp/plugins/gulp-component-menu-behaviors.ts

@@ -0,0 +1,98 @@
+import * as gutil from 'gulp-util'
+import * as path from 'path'
+import * as through2 from 'through2'
+import * as Vinyl from 'vinyl'
+import * as _ from 'lodash'
+import * as fs from 'fs'
+
+const pluginName = 'gulp-component-menu-behaviors'
+const extract = require('extract-comments')
+const doctrine = require('doctrine')
+
+type BehaviorMenuItem = {
+  displayName: string
+  type: string
+  variations: {
+    name: string
+    text: string
+  }
+}
+
+export default () => {
+  const result: BehaviorMenuItem[] = []
+  function bufferContents(file, enc, cb) {
+    if (file.isNull()) {
+      cb(null, file)
+      return
+    }
+
+    if (file.isStream()) {
+      cb(new gutil.PluginError(pluginName, 'Streaming is not supported'))
+      return
+    }
+
+    try {
+      const absPath = path.resolve(process.cwd(), file.path)
+      const dir = path.dirname(absPath)
+      const componentType = _.lowerFirst(path.basename(path.dirname(dir)).replace(/s$/, ''))
+      const behaviorVariantName = file.basename
+      const behaviorName = path.basename(dir)
+
+      let description
+      const fileContent = fs.readFileSync(file.path).toString()
+      const blockComments = extract(fileContent).filter(comment => comment.type === 'BlockComment') // filtering only block comments
+      const emptyDescriptionText = 'Behavior file has no description.'
+
+      // getting object that describes '@description' part of the comment's text
+      if (!_.isEmpty(blockComments)) {
+        const commentTokens = doctrine.parse(blockComments[0].raw, { unwrap: true }).tags
+        const descriptionToken = commentTokens.find(token => token.title === 'description')
+        description = descriptionToken ? descriptionToken.description : emptyDescriptionText
+      } else {
+        description = emptyDescriptionText
+      }
+
+      result.push({
+        displayName: behaviorName,
+        type: componentType,
+        variations: {
+          name: behaviorVariantName,
+          text: description,
+        },
+      })
+      cb()
+    } catch (err) {
+      const pluginError = new gutil.PluginError(pluginName, err)
+      const relativePath = path.relative(process.cwd(), file.path)
+      pluginError.message = [
+        gutil.colors.magenta(`Error in file: ${relativePath}`),
+        gutil.colors.red(err.message),
+        gutil.colors.gray(err.stack),
+      ].join('\n\n')
+      this.emit('error', pluginError)
+    }
+  }
+
+  function getParsedResults() {
+    return _(result)
+      .groupBy('displayName')
+      .map((behaviors, displayName) => ({
+        displayName,
+        type: behaviors[0].type,
+        variations: _.map(behaviors, 'variations'),
+      }))
+      .value()
+  }
+
+  function endStream(cb) {
+    const file = new Vinyl({
+      path: './behaviorMenu.json',
+      contents: Buffer.from(JSON.stringify(getParsedResults(), null, 2)),
+    })
+
+    this.push(file)
+    cb()
+  }
+
+  return through2.obj(bufferContents, endStream)
+}

build/gulp/tasks/docs.ts

@@ -1,6 +1,7 @@
 import * as historyApiFallback from 'connect-history-api-fallback'
 import * as express from 'express'
 import { task, src, dest, lastRun, parallel, series, watch } from 'gulp'
+import * as remember from 'gulp-remember'
 import * as path from 'path'
 import * as rimraf from 'rimraf'
 import * as through2 from 'through2'
@@ -11,14 +12,15 @@ import * as WebpackHotMiddleware from 'webpack-hot-middleware'
 import sh from '../sh'
 import config from '../../../config'
 import gulpComponentMenu from '../plugins/gulp-component-menu'
+import gulpComponentMenuBehaviors from '../plugins/gulp-component-menu-behaviors'
 import gulpExampleMenu from '../plugins/gulp-example-menu'
 import gulpReactDocgen from '../plugins/gulp-react-docgen'
 
 const { paths } = config
 const g = require('gulp-load-plugins')()
 const { colors, log, PluginError } = g.util
 
-const handleWatchChange = e => log(`File ${e.path} was ${e.type}, running tasks...`)
+const handleWatchChange = (path, stats) => log(`File ${path} was changed, running tasks...`)
 
 // ----------------------------------------
 // Clean
@@ -32,6 +34,10 @@ task('clean:docs:component-menu', cb => {
   rimraf(paths.docsSrc('componentMenu.json'), cb)
 })
 
+task('clean:docs:component-menu-behaviors', cb => {
+  rimraf(paths.docsSrc('behaviorMenu.json'), cb)
+})
+
 task('clean:docs:dist', cb => {
   rimraf(paths.docsDist(), cb)
 })
@@ -45,6 +51,7 @@ task(
   parallel(
     'clean:docs:component-info',
     'clean:docs:component-menu',
+    'clean:docs:component-menu-behaviors',
     'clean:docs:dist',
     'clean:docs:example-menus',
   ),
@@ -55,6 +62,7 @@ task(
 // ----------------------------------------
 
 const componentsSrc = [`${config.paths.src()}/components/*/[A-Z]*.tsx`]
+const behaviorSrc = [`${config.paths.src()}/lib/accessibility/Behaviors/*/[A-Z]*.ts`]
 const examplesSrc = `${paths.docsSrc()}/examples/*/*/*/index.tsx`
 const markdownSrc = ['.github/CONTRIBUTING.md', 'specifications/*.md']
 
@@ -70,6 +78,13 @@ task('build:docs:component-menu', () =>
     .pipe(dest(paths.docsSrc())),
 )
 
+task('build:docs:component-menu-behaviors', () =>
+  src(behaviorSrc, { since: lastRun('build:docs:component-menu-behaviors') })
+    .pipe(remember('component-menu-behaviors'))
+    .pipe(gulpComponentMenuBehaviors())
+    .pipe(dest(paths.docsSrc())),
+)
+
 task('build:docs:example-menu', () =>
   src(examplesSrc, { since: lastRun('build:docs:example-menu') })
     .pipe(gulpExampleMenu())
@@ -78,7 +93,12 @@ task('build:docs:example-menu', () =>
 
 task(
   'build:docs:json',
-  parallel('build:docs:docgen', 'build:docs:component-menu', 'build:docs:example-menu'),
+  parallel(
+    'build:docs:docgen',
+    'build:docs:component-menu',
+    'build:docs:component-menu-behaviors',
+    'build:docs:example-menu',
+  ),
 )
 
 task('build:docs:html', () => src(paths.docsSrc('404.html')).pipe(dest(paths.docsDist())))
@@ -193,6 +213,13 @@ task('watch:docs', cb => {
   // rebuild example menus
   watch(examplesSrc, series('build:docs:example-menu')).on('change', handleWatchChange)
 
+  watch(behaviorSrc, series('build:docs:component-menu-behaviors'))
+    .on('change', handleWatchChange)
+    .on('unlink', path => {
+      log(`File ${path} was deleted, running tasks...`)
+      remember.forget('component-menu-behaviors', path)
+    })
+
   // rebuild images
   watch(`${config.paths.src()}/**/*.{png,jpg,gif}`, series('build:docs:images')).on(
     'change',

docs/src/components/DocsBehaviorRoot.tsx

@@ -0,0 +1,72 @@
+import * as _ from 'lodash'
+import PropTypes from 'prop-types'
+import * as React from 'react'
+const behaviorMenuItems = require('docs/src/behaviorMenu')
+import { Grid } from 'semantic-ui-react'
+import ComponentExampleTitle from './ComponentDoc/ComponentExample/ComponentExampleTitle'
+class DocsBehaviorRoot extends React.Component<any, any> {
+  static propTypes = {
+    children: PropTypes.node,
+    match: PropTypes.shape({
+      params: PropTypes.shape({
+        name: PropTypes.string.isRequired,
+      }),
+    }),
+  }
+
+  baseName(fileName: string) {
+    const divided = _.startCase(fileName.replace('ts', ''))
+    return _.upperFirst(_.lowerCase(divided))
+  }
+
+  render() {
+    const exampleStyle: React.CSSProperties = {
+      position: 'relative',
+      transition: 'box-shadow 200ms, background 200ms',
+      background: '#fff',
+      boxShadow: '0 1px 2px #ccc',
+      margin: '10px',
+    }
+
+    const commentBox: React.CSSProperties = {
+      padding: 5,
+    }
+    const { match } = this.props
+    return (
+      <div style={commentBox}>
+        {behaviorMenuItems
+          .find(behavior => behavior.displayName === _.capitalize(match.params.name))
+          .variations.map((variation, keyValue) => (
+            <Grid key={keyValue} className="docs-example" style={exampleStyle}>
+              <Grid.Column width={16} style={{ borderBottom: '1px solid #ddd' }}>
+                <div style={{ display: 'flex' }}>
+                  <div style={{ flex: '1' }}>
+                    <ComponentExampleTitle
+                      id={_.kebabCase(variation.name)}
+                      title={this.baseName(variation.name)}
+                      description={`Behavior name: ${variation.name.replace('.ts', '')}`}
+                    />
+                  </div>
+                  <div style={{ flex: '0 0 auto' }} />
+                </div>
+              </Grid.Column>
+              <div style={{ paddingTop: '1rem', paddingBottom: '1rem' }}>
+                <span> Description: </span>
+                <br />
+                {variation.text.split('\n').map((splittedText, keyValue) => {
+                  return (
+                    <span key={keyValue}>
+                      {splittedText}
+                      <br />
+                    </span>
+                  )
+                })}
+              </div>
+            </Grid>
+          ))}
+      </div>
+    )
+  }
+}
+
+export default DocsBehaviorRoot

docs/src/components/DocsRoot.tsx

@@ -5,6 +5,7 @@ import * as React from 'react'
 import ComponentDoc from '../components/ComponentDoc'
 import PageNotFound from '../views/PageNotFound'
 import componentInfoContext from '../utils/componentInfoContext'
+import DocsBehaviorRoot from './DocsBehaviorRoot'
 
 class DocsRoot extends React.Component<any, any> {
   static propTypes = {
@@ -22,6 +23,9 @@ class DocsRoot extends React.Component<any, any> {
   render() {
     const { match } = this.props
     const displayName = _.startCase(match.params.name).replace(/ /g, '')
+    if (match.params.type === 'behaviors') {
+      return <DocsBehaviorRoot {...this.props} />
+    }
     const info = componentInfoContext.byDisplayName[displayName]
 
     if (info) return <ComponentDoc info={info} />

docs/src/components/Sidebar/Sidebar.tsx

@@ -12,10 +12,10 @@ import { getComponentPathname, typeOrder, repoURL } from 'docs/src/utils'
 
 const pkg = require('../../../../package.json')
 const componentMenu = require('docs/src/componentMenu')
+const behaviorMenu = require('docs/src/behaviorMenu')
 
 const selectedItemLabelStyle: any = { color: '#35bdb2', float: 'right' }
 const selectedItemLabel = <span style={selectedItemLabelStyle}>Press Enter</span>
-
 type ComponentMenuItem = { displayName: string; type: string }
 
 class Sidebar extends React.Component<any, any> {
@@ -111,7 +111,7 @@ class Sidebar extends React.Component<any, any> {
           activeClassName="active"
         />
       )),
-    )(componentMenu)
+    )([...componentMenu, ...behaviorMenu])
 
     return (
       <Menu.Item key={nextType}>

docs/src/utils/constants.ts

@@ -1,2 +1,2 @@
 export const repoURL = 'https://github.com/stardust-ui/react'
-export const typeOrder = ['component']
+export const typeOrder = ['component', 'behavior']

package.json

@@ -107,13 +107,15 @@
     "enzyme": "^3.1.0",
     "enzyme-adapter-react-16": "^1.0.1",
     "express": "^4.15.4",
+    "extract-comments": "^1.0.0",
     "fbjs": "^0.8.17",
     "gh-pages": "^1.0.0",
     "glob": "^7.1.2",
     "gulp": "^4.0.0",
     "gulp-debug": "^4.0.0",
     "gulp-load-plugins": "^1.5.0",
     "gulp-plumber": "^1.2.0",
+    "gulp-remember": "^1.0.1",
     "gulp-rename": "^1.3.0",
     "gulp-replace": "^1.0.0",
     "gulp-transform": "^3.0.5",