docs(Examples): allow to use TS in examples (#617)

* docs(Examples): allow to use TS in examples

* add jsdoc

* fix typo

* rename file

* add comment

* `createExample` to `createExampleSourceCode`

* rework with `path.relative()`

* remove JSON files on remove tsx

* create getRelativePathToSource function

Author: layershifter

.gitignore

@@ -12,6 +12,7 @@ docs/src/componentInfo
 docs/src/componentMenu.json
 docs/src/behaviorMenu.json
 docs/src/exampleMenus
+docs/src/exampleSources
 docs/dist/
 dll/
 node_modules/

build/babel/transform-star-import-plugin.ts

@@ -0,0 +1,36 @@
+import * as T from '@babel/types'
+import { BabelPlugin } from './types'
+
+/**
+ * Creates an default import:
+ * - import React from 'react'
+ */
+const createDefaultImportDeclaration = (
+  t: typeof T,
+  declaration: T.ImportDeclaration,
+  specifier: T.ImportNamespaceSpecifier,
+): T.ImportDeclaration =>
+  t.importDeclaration(
+    [t.importDefaultSpecifier(t.identifier(specifier.local.name))],
+    t.stringLiteral(declaration.source.value),
+  )
+
+/**
+ * A plugin for Babel that performs AST transform:
+ * - from: import * as _ from 'lodash'
+ * - to: import _ from 'lodash'
+ */
+const starImportToDefaultPlugin: BabelPlugin = ({ types: t }) => ({
+  visitor: {
+    ImportDeclaration: path => {
+      const { specifiers } = path.node
+      const specifier = specifiers[0]
+
+      if (specifiers.length === 1 && t.isImportNamespaceSpecifier(specifier)) {
+        path.replaceWith(createDefaultImportDeclaration(t, path.node, specifier))
+      }
+    },
+  },
+})
+
+export default starImportToDefaultPlugin

build/babel/types.ts

@@ -0,0 +1,22 @@
+import * as T from '@babel/types'
+import { NodePath } from '@babel/traverse'
+
+export type BabelPluginArguments = {
+  types: typeof T
+}
+
+type BabelPluginVisitorFunction<T> = (path: NodePath<T>) => void
+type BabelPluginVisitor<T> =
+  | BabelPluginVisitorFunction<T>
+  | {
+      exit: BabelPluginVisitorFunction<T>
+    }
+
+export type BabelPlugin = (
+  options: BabelPluginArguments,
+) => {
+  visitor: {
+    // This type is extendable, feel to add own visitor types.
+    ImportDeclaration: BabelPluginVisitor<T.ImportDeclaration>
+  }
+}

build/gulp/plugins/gulp-example-source.ts

@@ -0,0 +1,55 @@
+import * as Babel from '@babel/core'
+import * as gutil from 'gulp-util'
+import * as prettier from 'prettier'
+import * as through from 'through2'
+import * as Vinyl from 'vinyl'
+
+import * as prettierConfig from '../../../.prettierrc.json'
+import { ExampleSource } from '../../../docs/src/types'
+import transformStarImportPlugin from '../../babel/transform-star-import-plugin'
+import { getRelativePathToSourceFile } from './util'
+
+const pluginName = 'gulp-example-source'
+
+const createExampleSourceCode = (file: Vinyl): ExampleSource => {
+  const tsSource = file.contents.toString()
+
+  const transformResult = Babel.transform(tsSource, {
+    plugins: [transformStarImportPlugin],
+    presets: [['@babel/preset-typescript', { allExtensions: true, isTSX: true }]],
+    sourceType: 'module',
+  })
+  const jsSource = prettier.format(transformResult.code, {
+    ...prettierConfig,
+    parser: 'babylon',
+  })
+
+  return {
+    js: jsSource,
+    ts: tsSource,
+  }
+}
+
+export default () =>
+  through.obj((file: Vinyl, enc, cb) => {
+    if (file.isNull()) {
+      cb(null, file)
+      return
+    }
+
+    if (file.isStream()) {
+      cb(new gutil.PluginError(pluginName, 'Streaming is not supported'))
+      return
+    }
+
+    const sourcePath = getRelativePathToSourceFile(file.path)
+    const source = createExampleSourceCode(file)
+
+    cb(
+      null,
+      new Vinyl({
+        path: sourcePath,
+        contents: Buffer.from(JSON.stringify(source, null, 2)),
+      }),
+    )
+  })

build/gulp/plugins/util/getRelativePathToSourceFile.ts

@@ -0,0 +1,13 @@
+import * as path from 'path'
+import config from '../../../../config'
+
+const examplesPath = config.paths.docsSrc('examples', 'components')
+
+/**
+ * Generates a relative path to a source file, outputs:
+ * Chat/Types/ChatExample.shorthand.source.json
+ */
+const getRelativePathToSourceFile = (filePath: string): string =>
+  `${path.relative(examplesPath, filePath).replace(/\.tsx$/, '')}.source.json`
+
+export default getRelativePathToSourceFile

build/gulp/plugins/util/index.ts

@@ -1,5 +1,6 @@
 export * from './checksumUtils'
 export { default as getComponentInfo } from './getComponentInfo'
+export { default as getRelativePathToSourceFile } from './getRelativePathToSourceFile'
 export { default as parseDefaultValue } from './parseDefaultValue'
 export { default as parseDocblock } from './parseDocblock'
 export { default as parseDocSection } from './parseDocSection'

build/gulp/tasks/docs.ts

@@ -2,6 +2,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 fs from 'fs'
 import * as path from 'path'
 import * as rimraf from 'rimraf'
 import * as through2 from 'through2'
@@ -14,7 +15,9 @@ 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 gulpExampleSource from '../plugins/gulp-example-source'
 import gulpReactDocgen from '../plugins/gulp-react-docgen'
+import { getRelativePathToSourceFile } from '../plugins/util'
 
 const { paths } = config
 const g = require('gulp-load-plugins')()
@@ -46,13 +49,18 @@ task('clean:docs:example-menus', cb => {
   rimraf(paths.docsSrc('exampleMenus'), cb)
 })
 
+task('clean:docs:example-sources', cb => {
+  rimraf(paths.docsSrc('exampleSources'), cb)
+})
+
 task(
   'clean:docs',
   parallel(
     'clean:docs:component-menu',
     'clean:docs:component-menu-behaviors',
     'clean:docs:dist',
     'clean:docs:example-menus',
+    'clean:docs:example-sources',
   ),
 )
 
@@ -62,7 +70,8 @@ task(
 
 const componentsSrc = [`${paths.posix.src()}/components/*/[A-Z]*.tsx`, '!**/Slot.tsx']
 const behaviorSrc = [`${paths.posix.src()}/lib/accessibility/Behaviors/*/[a-z]*.ts`]
-const examplesSrc = `${paths.posix.docsSrc()}/examples/*/*/*/index.tsx`
+const examplesIndexSrc = `${paths.posix.docsSrc()}/examples/*/*/*/index.tsx`
+const examplesSrc = `${paths.posix.docsSrc()}/examples/*/*/*/!(*index|.knobs).tsx`
 const markdownSrc = [
   '.github/CONTRIBUTING.md',
   '.github/setup-local-development.md',
@@ -92,18 +101,25 @@ task('build:docs:component-menu-behaviors', () =>
 )
 
 task('build:docs:example-menu', () =>
-  src(examplesSrc, { since: lastRun('build:docs:example-menu') })
+  src(examplesIndexSrc, { since: lastRun('build:docs:example-menu') })
     .pipe(remember('example-menu')) // FIXME: with watch this unnecessarily processes index files for all examples
     .pipe(gulpExampleMenu())
     .pipe(dest(paths.docsSrc('exampleMenus'))),
 )
 
+task('build:docs:example-sources', () =>
+  src(examplesSrc, { since: lastRun('build:docs:example-sources') })
+    .pipe(gulpExampleSource())
+    .pipe(dest(paths.docsSrc('exampleSources'))),
+)
+
 task(
   'build:docs:json',
   parallel(
     series('build:docs:docgen', 'build:docs:component-menu'),
     'build:docs:component-menu-behaviors',
     'build:docs:example-menu',
+    'build:docs:example-sources',
   ),
 )
 
@@ -218,10 +234,21 @@ task('watch:docs', cb => {
   watch(componentsSrc, series('build:docs:docgen')).on('change', handleWatchChange)
 
   // rebuild example menus
-  watch(examplesSrc, series('build:docs:example-menu'))
+  watch(examplesIndexSrc, series('build:docs:example-menu'))
     .on('change', handleWatchChange)
     .on('unlink', path => handleWatchUnlink('example-menu', path))
 
+  watch(examplesSrc, series('build:docs:example-sources'))
+    .on('change', handleWatchChange)
+    .on('unlink', filePath => {
+      log(`File ${filePath} was deleted, running tasks...`)
+
+      const sourceFilename = getRelativePathToSourceFile(filePath)
+      const sourcePath = config.paths.docsSrc('exampleSources', sourceFilename)
+
+      fs.unlinkSync(sourcePath)
+    })
+
   watch(behaviorSrc, series('build:docs:component-menu-behaviors'))
     .on('change', handleWatchChange)
     .on('unlink', path => handleWatchUnlink('component-menu-behaviors', path))

docs/src/components/ComponentDoc/ComponentExample/SourceCodeManager.ts

@@ -84,7 +84,9 @@ class SourceCodeManager {
 
   private safeRequire = (path: string): string | undefined => {
     try {
-      return require(`!raw-loader!../../../examples/${path}`)
+      const filename = `${path.replace(/^components\//, '')}.source.json`
+
+      return require(`!docs/src/exampleSources/${filename}`).js
     } catch (e) {
       return undefined
     }

docs/src/examples/components/Ref/Types/RefExample.tsx

@@ -1,13 +1,17 @@
-import React from 'react'
+import * as React from 'react'
 import { Button, Grid, Ref, Segment } from '@stardust-ui/react'
 
-class RefExample extends React.Component {
+type RefExampleState = {
+  isMounted: boolean
+}
+
+class RefExample extends React.Component<{}, RefExampleState> {
   state = { isMounted: false }
 
   createdRef = React.createRef<HTMLButtonElement>()
   functionalRef = null
 
-  handleRef = node => (this.functionalRef = node)
+  handleRef = (node: HTMLButtonElement) => (this.functionalRef = node)
 
   componentDidMount() {
     this.setState({ isMounted: true })

docs/src/examples/components/Ref/Types/RefForwardingExample.tsx

@@ -1,13 +1,19 @@
-import React from 'react'
+import * as React from 'react'
 import { Grid, Ref, Segment } from '@stardust-ui/react'
 
-const ExampleButton = React.forwardRef<HTMLButtonElement>((props, ref) => (
-  <div>
-    <button {...props} ref={ref} />
-  </div>
-))
+type RefForwardingExampleState = {
+  isMounted: boolean
+}
+
+const ExampleButton = React.forwardRef<HTMLButtonElement, { children: React.ReactNode }>(
+  (props, ref) => (
+    <div>
+      <button {...props} ref={ref} />
+    </div>
+  ),
+)
 
-class RefForwardingExample extends React.Component {
+class RefForwardingExample extends React.Component<{}, RefForwardingExampleState> {
   forwardedRef = React.createRef<HTMLButtonElement>()
   state = { isMounted: false }