LG-3757: Create bundler-ready module entrypoint (#165)

* LG-3757: Create bundler-ready module entrypoint

**Why**: As a developer using the login.gov Design System, I expect that I can use identity-style-guide as a proper NPM package, so that I can deduplicate shared dependencies (see LG-3716) and take advantage of dead code elimination to reduce bundle size by omitting unused components.

* Rename auto to main in dist build

**Why**: Preserve backward-compatibility while renaming source to reflect auto setup behavior

* Build package in main build task

**Why**: Easier integration into existing CI setup, more consistent build artifacts

* Define build-package as dependency of lint task

**Why**: Lint includes import validation. Since there are internal references to built package, must be prebuilt for lint.

* Use export ns syntax for entrypoint exports

See: #165 (comment)

* Build package before NPM lint script

**Why**: Changes in #167 bypass Make for running lint, but in any case, the package needs to be built.

* Add additional USWDS 2.9.0 components for export

.gitignore

@@ -1,4 +1,5 @@
 /dist
+/build
 /node_modules
 /tmp
 .DS_Store

CHANGELOG.md

@@ -14,6 +14,10 @@
     - Graphic list should use `h2` as a heading element instead of `h3`.
 - "Official government website" banner text has been updated. Refer to [USWDS guidance](https://designsystem.digital.gov/components/banner/) for updated markup.
 
+### New Features
+
+- The published NPM package can now be imported into a project. Bundlers that support dead-code elimination (Webpack, etc.) can automatically remove unused code to optimize bundle size. See [Usage guide](https://design.login.gov/usage/) for more information. Existing usage of JavaScript code from `dist/assets/` is unaffected by these changes.
+
 ### Bug Fixes
 
 - Fixed support for multiple dropdown buttons on a page.

Makefile

@@ -1,6 +1,7 @@
 MAKEFLAGS += --jobs=6
 TMP_DIR = ./tmp
 OUTPUT_DIR = ./dist
+PACKAGE_DIR = ./build
 
 # Federalist builds overwrite the output directory.
 ifdef SITE_PREFIX
@@ -33,17 +34,20 @@ validate-package-lock: package.json package-lock.json
 
 validate-lockfiles: validate-gemfile-lock validate-package-lock
 
-lint:
+lint: build-package
 	./node_modules/.bin/gulp lint
 	make validate-lockfiles
 
-build: build-docs build-assets
+build: build-docs build-assets build-package
 
 build-docs:
 	JEKYLL_ENV=production bundle exec jekyll build
 
 build-assets: build-sass-and-js build-fonts build-images copy-scss
 
+build-package:
+	./node_modules/.bin/gulp build-package
+
 build-sass-and-js:
 	NODE_ENV=production \
 	DISABLE_NOTIFIER=true \
@@ -76,3 +80,4 @@ test-runner-jest:
 clean:
 	rm -rf $(OUTPUT_DIR)
 	rm -rf $(TMP_DIR)
+	rm -rf $(PACKAGE_DIR)

docs/usage.md

@@ -96,3 +96,26 @@ $image-path: 'img';
 
 @import 'identity-style-guide/dist/assets/scss/styles';
 ```
+
+### Use as a JavaScript package
+
+If you're already using a JavaScript bundler in your project, you can import specific component implementations from the `identity-style-guide` package. Most modern bundlers that support dead-code elimination will automatically optimize the bundle size to include only the code necessary in your project.
+
+```js
+import { accordion } from 'identity-style-guide';
+
+accordion.on();
+```
+
+Note that unlike the pre-built JavaScript assets found in the `dist/assets` directory, importing the package from NPM will not automatically initialize the components on the page or include polyfills necessary to support older browsers. You will have to call the `on()` method for each component you import.
+
+If you need support for older browsers in your project, it's suggested you import polyfills shipped with the `uswds` package and import it before any components:
+
+```
+npm install uswds
+```
+
+```js
+import 'uswds/src/js/polyfills';
+import { accordion } from 'identity-style-guide';
+```

gulpfile.js

@@ -13,6 +13,7 @@ const gulpStylelint = require('gulp-stylelint');
 const sourcemaps = require('gulp-sourcemaps');
 const uswds = require('uswds-gulp/config/uswds');
 const browserify = require('browserify');
+const babel = require('gulp-babel');
 const source = require('vinyl-source-stream');
 const buffer = require('vinyl-buffer');
 const uglify = require('gulp-uglify');
@@ -22,8 +23,10 @@ const pkg = require('./package.json');
 
 const PROJECT_SASS_SRC = './src/scss';
 const PROJECT_JS_SRC = './src/js';
-const PROJECT_JS_MAIN = 'main.js';
+const PROJECT_JS_AUTO = 'auto.js';
+const PROJECT_JS_AUTO_OUT = 'main.js';
 const OUTPUT_DIR = process.env.OUTPUT_DIR || './dist';
+const PACKAGE_DEST = 'build';
 const JS_DEST = `${OUTPUT_DIR}/assets/js`;
 const CSS_DEST = `${OUTPUT_DIR}/assets/css`;
 const SCSS_DEST = `${OUTPUT_DIR}/assets/scss`;
@@ -58,13 +61,28 @@ gulp.task('lint-js', () =>
     .pipe(eslint.failAfterError()),
 );
 
+gulp.task('build-package-cjs', () =>
+  gulp
+    .src(`${PROJECT_JS_SRC}/**/*.js`)
+    .pipe(babel({ presets: [['@babel/preset-env', { modules: 'cjs' }]] }))
+    .pipe(gulp.dest(`${PACKAGE_DEST}/cjs`)),
+);
+
+gulp.task('build-package-esm', () =>
+  gulp
+    .src(`${PROJECT_JS_SRC}/**/*.js`)
+    .pipe(babel({ presets: [['@babel/preset-env', { modules: false }]] }))
+    .pipe(gulp.dest(`${PACKAGE_DEST}/esm`)),
+);
+
 gulp.task('build-js', () => {
-  const stream = browserify({ entries: `${PROJECT_JS_SRC}/${PROJECT_JS_MAIN}`, debug: true })
+  const stream = browserify({ entries: `${PROJECT_JS_SRC}/${PROJECT_JS_AUTO}`, debug: true })
     .transform('babelify', { global: true, presets: ['@babel/preset-env'] })
     .bundle()
     .on('error', notificationOptions.handler)
-    .pipe(source(PROJECT_JS_MAIN))
+    .pipe(source(PROJECT_JS_AUTO))
     .pipe(buffer())
+    .pipe(rename(PROJECT_JS_AUTO_OUT))
     .pipe(gulp.dest(JS_DEST))
     .pipe(notify(notificationOptions.success));
 
@@ -150,6 +168,8 @@ gulp.task('lint', gulp.parallel('lint-js', 'lint-sass'));
 
 gulp.task('build', gulp.parallel('build-js', 'build-sass'));
 
+gulp.task('build-package', gulp.parallel('build-package-cjs', 'build-package-esm'));
+
 gulp.task(
   'watch',
   gulp.parallel(gulp.series('build-js', 'watch-js'), gulp.series('build-sass', 'watch-sass')),