VA-277: Add component library structure and docs

docroot/themes/custom/vagov/README.md

@@ -1,9 +1,16 @@
-# USWDS Subtheme
+# VAGov Custom Theme
+## A subtheme of [USWDS](https://www.drupal.org/project/uswds)
 
-## Installation
+### Dependencies
+1. [USWDS](https://github.com/uswds/uswds)
+2. [Components module for Drupal 8](https://www.drupal.org/project/components) - to create a project namespace to use for a UI component libary. 
+That component namespace is defined in *vagov.info.yml*.
 
-1. Copy this folder ("my_subtheme") out into the desired location for your subtheme (eg, themes/custom/my_subtheme).
-2. Rename the folder to the name of your theme (eg, my_renamed_theme).
-3. Rename the my_subtheme.info.yml.rename-me file to name-of-your-theme.info.yml (eg, my_renamed_theme.info.yml).
-4. Tweak that .info.yml file as needed, noting the instructions there for Sass workflow, if that is desired.
-5. Enable this theme in the usual way (eg, drush en my_renamed_subtheme).
+    __Current component namespace:__ *uiComponents*
+
+3. Gulp
+
+
+### Docs
+1. For project code conventions (CSS naming standards & more) see docs/CodeConventions.md
+2. For information about Gulp configuration and tasks you can run in this project see docs/GulpConfiguration.md

docroot/themes/custom/vagov/assets/js/src/_example.js

@@ -0,0 +1,8 @@
+
+(function ($, Drupal) {
+    Drupal.behaviors.exampleBehavior = {
+        attach:function (context, settings) {
+            console.log('test from example behavior');
+        }
+    };
+})(jQuery, Drupal);

docroot/themes/custom/vagov/docs/CodeConventions.md

@@ -0,0 +1,24 @@
+# Code Conventions
+### CSS class naming convention
+Learn more: https://design.cms.gov/guidelines/code-conventions/
+
+```
+.namespace-prefix-BEM--SYNTAX
+```
+
+```
+.vagov-c-breadcrumb--container
+```
+
+* CSS name space: *vagov*
+
+* Prefixes
+  * ```l- ``` layout style ex: *.vagov-l-container*
+  * ```c-``` component style ex: *.vagov-c-button*
+  * ```u-``` utility ex: *.vagov-u-color--primary*
+  * ```js-``` javascript hook *.vagov-js-expand*
+
+* [BEM SYNTAX](http://getbem.com/introduction/)
+  * Block - a standalone component that is meaningful on it's own. e.g. a button
+  * Element - a part of a component that has no standalone meaning and is tied to the component e.g. button text
+  * Modifier - a flag on a component or element used to change it's appearance or behavior.

docroot/themes/custom/vagov/docs/GulpConfiguration.md

@@ -0,0 +1,16 @@
+# Gulp Configuration & Tasks
+## Gulp Plugins
+1. gulp-sass: sass compiling
+2. gulp-livereload: automatically reload the browser upon making a change to styles or javascript during local dev
+3. gulp-autoprefixer: automatically add necessary browser prefixes while compiling sass
+4. gulp-sourcemaps: create inline sourcemaps
+5. gulp-concat: concatenate javascript files
+6. gulp-babel: convert ECMAScript 2015+ code into backwards compatible javascript.
+7. gulp-uglify: minify javascript
+
+
+## Gulp Tasks
+1. ``` sass ``` compile sass into css, add necessary browser prefixes, compress, and save in assets/css 
+2. ``` watch ``` watch project directory for changes to theme files (sass, js, and twig files) and reloads browser to display changes
+3. ``` scripts ``` compile, concatenate, and minify javascript 
+4. ``` clearcache ``` clear drupal cache

docroot/themes/custom/vagov/gulpfile.js

@@ -1,9 +1,19 @@
+'use strict';
+
 var gulp = require('gulp'),
-  livereload = require('gulp-livereload'),
-  sass = require('gulp-sass'),
-  autoprefixer = require('gulp-autoprefixer'),
-  sourcemaps = require('gulp-sourcemaps');
+    livereload = require('gulp-livereload'),
+    sass = require('gulp-sass'),
+    autoprefixer = require('gulp-autoprefixer'),
+    sourcemaps = require('gulp-sourcemaps'),
+    concat = require('gulp-concat'),
+    uglify = require('gulp-uglify'),
+    cp = require('child_process'),
+    babel = require('gulp-babel');
 
+/**
+ * @task sass
+ * Compile and compress files from scss, add browser prefixes, create a source map, and save in assets folder.
+ */
 gulp.task('sass', function () {
   gulp.src('assets/scss/**/*.scss')
     .pipe(sourcemaps.init())
@@ -13,13 +23,48 @@ gulp.task('sass', function () {
     .pipe(gulp.dest('assets/css/'));
 });
 
+/**
+ * @task scripts
+ * Compile files from js, concatenate, create a source map, and save in assets folder.
+ */
+gulp.task('scripts', function() {
+    return gulp.src(['assets/js/src/**/*.js'])
+        .pipe(sourcemaps.init())
+        .pipe(babel({
+            presets: ['@babel/env']
+        }))
+        .pipe(concat('script.min.js'))
+        .pipe(uglify())
+        .pipe(sourcemaps.write('./'))
+        .pipe(gulp.dest('assets/js'));
+});
+
+/**
+ * @task clearcache
+ * Clear all drupal caches
+ */
+gulp.task('clearcache', function(done) {
+    return cp.spawn('lando', ['drush'], ['cache-rebuild'], {stdio: 'inherit'})
+        .on('close', done);
+});
+
+/**
+ * @task watch
+ * Watch scss, JS, and twig files for changes & recompile
+ * Reload browser with livereload to show changes
+ */
 gulp.task('watch', function () {
   livereload.listen();
 
   gulp.watch('assets/scss/**/*.scss', ['sass']);
-  gulp.watch(['assets/css/uswds.css', './**/*.html.twig', './js/*.js'], function (files) {
-    livereload.changed(files)
+  gulp.watch('assets/js/src/**/*.js', ['scripts']);
+  gulp.watch(['assets/css/uswds.css', './**/*.html.twig', 'assets/js/dist/*.js'], function (files) {
+    livereload.changed(files);
   });
 });
 
-gulp.task('default', ['sass', 'watch']);
+/**
+ * Default task, running just `gulp` will
+ * compile & autoprefix Sass & concatenate JS files, launch livereload, watch files.
+ */
+gulp.task('default', ['sass', 'scripts', 'watch']);