Merge pull request #10 from CMSgov/staging

v1.0.0-alpha.2

CONTRIBUTING.md

@@ -1,3 +1,14 @@
+## Development process
+
+1. Branch off of `staging`: `git checkout -b username/branch-name`.
+1. Commit your changes
+1. Make a pull request against the `staging` branch and format your pull request description using the following format:
+  - **Added:** for new features or components.
+  - **Changed:** for changes in existing functionality or design.
+  - **Deprecated:** for once-stable features or components removed in upcoming releases.
+  - **Removed:** for deprecated features or components removed in this release.
+  - **Fixed:** for any bug fixes.
+
 ## Running locally
 
 ### Package management
@@ -6,7 +17,13 @@ This project uses [Yarn](https://yarnpkg.com/) for package management. Yarn help
 
 [**Install Yarn**](https://yarnpkg.com/docs/install), if you don't have it yet.
 
-#### Install dependencies
+#### Install build process dependencies
+
+```
+yarn install
+```
+
+#### Install package dependencies
 
 ```
 yarn bootstrap
@@ -18,10 +35,12 @@ _Note_: `yerna` will become obsolete once [Lerna](https://lernajs.io/) [is merge
 
 ### Scripts
 
-- `yarn run build` compiles everything and makes things production-ready
-- `yarn run prerelease` increments the package versions. By default it will do a patch version increment, however you can also do a minor or major increment by doing the following: `yarn run prerelease -- --type=minor`
-- `yarn run start` runs a Browsersync server for the documentation, and compiles a file when it changes.
-- `yarn test` runs all tests using [Jest](https://facebook.github.io/jest/).
+- `yarn run start` - You'll want to run this when you're developing components. It compiles Sass, transpiles JavaScript, and runs a local documentation instance where you can preview changes.
+- `yarn run build` - compile/transpile/uglify everything and makes things release-ready.
+- `yarn run bump` - increments package versions. Read "[Versioning](https://github.com/CMSgov/design-system/wiki/Versioning)" for more info.
+- `yarn run generate` - Generates the necessary files for a new core component
+- `yarn run g` - Alias for `yarn run generate`
+- `yarn test` - tests and lints the codebase.
 
 ### Coding guidelines
 

config/gulp/build.js

@@ -18,7 +18,6 @@ module.exports = (gulp) => {
     return runSequence(
       [
         'sass',
-        'javascript',
         'fonts'
       ],
       done

config/gulp/prerelease.js → config/gulp/bumpVersion.js

@@ -1,7 +1,7 @@
 /**
- * The `prerelease` task increments our package versions. It accepts a single
+ * The `bumpVersion` task increments our package versions. It accepts a single
  * argument: `--type` with a value of 'patch' (default), 'minor', and 'major'.
- * Example: `gulp prerelease --type=major` would bump 1.1.1 to 2.0.0
+ * Example: `gulp bumpVersion --type=major` would bump 1.1.1 to 2.0.0
  */
 const argv = require('yargs').argv;
 const bump = require('gulp-bump');
@@ -22,7 +22,7 @@ module.exports = (gulp) => {
   gulp.task('bumpVersion:core', () => bumpVersion('./packages/core'));
   gulp.task('bumpVersion:docs', () => bumpVersion('./packages/docs'));
 
-  gulp.task('prerelease', () => {
+  gulp.task('bumpVersion', () => {
     runSequence([
       'bumpVersion:core',
       'bumpVersion:docs',

config/gulp/common/react-docgen.js

@@ -2,6 +2,7 @@
  * Creates a Gulp-friendly implementation of react-docgen. Takes a stream
  * of React component files and returns a stream of JSON documentation files.
  */
+const dutil = require('../doc-util');
 const gUtil = require('gulp-util');
 const reactDocgen = require('react-docgen');
 const path = require('path');
@@ -15,18 +16,24 @@ function getPropertyName(nameAfter, filePath) {
 
 module.exports = function(options) {
   options = options || {};
+  let response = {};
 
   return through.obj((file, encoding, cb) => {
-    if (file.isNull()) return cb(null, file);
+    try {
+      if (file.isNull()) return cb(null, file);
 
-    let doc = reactDocgen.parse(file.contents);
-    // Reduce filesize by removing properties we don't need
-    delete doc.methods;
+      let doc = reactDocgen.parse(file.contents);
+      // Reduce filesize by removing properties we don't need
+      delete doc.methods;
 
-    // Assign the doc object to a unique property so we can
-    // merge the JSON files in another stream
-    let response = {};
-    response[getPropertyName(options.nameAfter, file.path)] = doc;
+      // Assign the doc object to a unique property so we can
+      // merge the JSON files in another stream
+      response[getPropertyName(options.nameAfter, file.path)] = doc;
+    } catch(e) {
+      dutil.logError('react-docgen', e);
+      dutil.logData('react-docgen', file.path);
+      response = {};
+    }
 
     file.contents = new Buffer(JSON.stringify(response));
     file.path = gUtil.replaceExtension(file.path, '.json');

config/gulp/docs.js

@@ -8,11 +8,13 @@ const dutil = require('./doc-util');
 const kss = require('kss');
 const merge = require('gulp-merge-json');
 const processKssSection = require('./kss/processSection');
+const nestKssSections = require('./kss/nestSections');
 const reactDocgen = require('./common/react-docgen');
 const runSequence = require('run-sequence');
 const source = require('vinyl-source-stream');
 
 module.exports = (gulp) => {
+  // Clear the fonts directory to ensure old fonts are pruned
   gulp.task('docs:clean-fonts', () => {
     return del('packages/docs/dist/fonts');
   });
@@ -22,12 +24,25 @@ module.exports = (gulp) => {
     .pipe(gulp.dest('packages/docs/dist'));
   });
 
+  // Clear the images directory to ensure old images are pruned
+  gulp.task('docs:clean-images', () => {
+    return del('packages/docs/dist/images');
+  });
+
+  // The docs use the design system's Sass files, which don't have the
+  // images inlined yet, so we need to be able to reference them by their URL
+  gulp.task('docs:copy-images', () => {
+    return gulp.src('packages/core/src/**/images/*')
+    .pipe(gulp.dest('packages/docs/dist'));
+  });
+
   gulp.task('docs:kss', () => {
-    return kss.traverse('packages/core/src/styles/')
+    return kss.traverse('packages/core/src/')
       .then(styleguide => {
         return styleguide.sections()
           .map(processKssSection);
       })
+      .then(nestKssSections)
       .then(sections => {
         const body = JSON.stringify(sections);
         const stream = source('sections.json');
@@ -37,10 +52,15 @@ module.exports = (gulp) => {
   });
 
   // Extract info from React component files for props documentation
-  gulp.task('docs:react-props', () => {
-    return gulp.src('packages/core/src/scripts/**/*.jsx')
+  gulp.task('docs:react', () => {
+    return gulp
+      .src([
+        'packages/core/src/components/**/*.jsx',
+        '!packages/core/src/components/**/*.test.jsx',
+        '!packages/core/src/components/**/*.example.jsx',
+      ])
       .pipe(reactDocgen({
-        nameAfter: 'packages/core/src/scripts/'
+        nameAfter: 'packages/'
       }))
       .pipe(merge({
         fileName: 'react-doc.json'
@@ -53,9 +73,12 @@ module.exports = (gulp) => {
 
     runSequence(
       'docs:clean-fonts',
+      'docs:clean-images',
       [
         'docs:kss',
+        'docs:react',
         'docs:copy-fonts',
+        'docs:copy-images',
         'webpack'
       ],
       done

config/gulp/index.js

@@ -13,10 +13,10 @@ module.exports = (gulp) => {
 
   [
     'build',
+    'bumpVersion',
     'docs',
     'fonts',
-    'javascript',
-    'prerelease',
+    'lint',
     'sass',
     'server',
     'watch',

config/gulp/kss/__tests__/nestSections.test.js

@@ -0,0 +1,42 @@
+const _ = require('lodash');
+const nestSections = require('../nestSections');
+
+const sections = [
+  {
+    reference: 'components',
+    sections: []
+  }, {
+    reference: 'components.buttons',
+    sections: []
+  }, {
+    reference: 'components.buttons.primary',
+    sections: []
+  }, {
+    reference: 'utilities',
+    sections: []
+  }, {
+    reference: 'utilities.colors',
+    sections: []
+  }, {
+    reference: 'home',
+    sections: []
+  }
+];
+
+describe('nestSections', () => {
+  it('nests children within parent section', () => {
+    return nestSections(sections)
+      .then(nestedSections => {
+        let components = _.find(nestedSections, {
+          reference: 'components'
+        });
+
+        expect(components.sections[0].reference)
+          .toEqual('components.buttons');
+        expect(components.sections[0].sections[0].reference)
+          .toEqual('components.buttons.primary');
+        expect(nestedSections.length)
+          .toEqual(3);
+      });
+  });
+});

config/gulp/kss/__tests__/processSection.test.js

@@ -0,0 +1,43 @@
+'use strict';
+const processSection = require('../processSection');
+
+describe('processSection', () => {
+  let section = reference => {
+    return {
+      toJSON: () => (
+        {
+          description: '<p>Hello world</p><p>@react-component</p><p>@hide-markup</p><p>@status prototype</p>',
+          markup: '<% var foo="bar" %><%= foo %>',
+          modifiers: [{
+            name: '.primary',
+            description: 'The primary action',
+            className: ''
+          }],
+          parameters: [],
+          reference: reference
+        }
+      )
+    };
+  };
+
+  let data;
+
+  beforeAll(() => {
+    data = processSection(section());
+  });
+
+  it('sets and replaces flags', () => {
+    expect(data.hasReactComponent).toEqual(true);
+    expect(data.hideMarkup).toEqual(true);
+    expect(data.status).toEqual('prototype');
+    expect(data.description).toEqual('<p>Hello world</p>');
+  });
+
+  it('renders EJS', () => {
+    expect(data.markup).toEqual('bar');
+  });
+
+  it('adds a sections property', () => {
+    expect(data.sections).toEqual(expect.any(Array));
+  });
+});

config/gulp/kss/nestSections.js

@@ -0,0 +1,41 @@
+const _ = require('lodash');
+
+/**
+ * Each KSS section has a reference property which we can use to determine
+ * which sections are parent sections vs. a child section. For example:
+ * "components.buttons" would belong in "components".
+ * @param  {Array} sections - KssSection
+ * @return {Promise<Array>}
+ */
+module.exports = (sections) => {
+  sections = sections
+    .concat([]) // don't mutate original array
+    .map(setParentReference)
+    .map((section, index) => {
+      if (section.parentReference) {
+        let parent = _.find(sections, {
+          reference: section.parentReference
+        });
+
+        if (parent) parent.sections.push(section);
+      }
+      return section;
+    })
+    .filter(section => !section.parentReference);
+
+  return Promise.resolve(sections);
+};
+
+// Goes up a reference level to find and set the parent reference
+// @example components.buttons.primary => components.buttons
+function setParentReference(section) {
+  const references = section.reference.split('.');
+  if (references.length > 1) {
+    references.pop();
+    section.parentReference = references.join('.');
+  } else {
+    section.parentReference = null;
+  }
+
+  return section;
+}