# Version 2.0

A complete rebuild of the `ux-pattern-library`.

## Improvements

### Removed Gulp

- Pure JavaScript functions make the app easier to understand and write unit tests for (eventually).
- All commands are now NPM scripts (easy to find by looking at `package.json`).
- Removing Gulp means there's one fewer dependency to deal with.

### Improved file watching

- App can now respond when new files and directories are created, existing ones are deleted or renamed, etc. (so you don't have to restart the app as often).
- Source file watching has been decoupled from BrowserSync, so you can start the application server on it's own without having to fire up BrowserSync as well (you'll probably never do this, but from an architectural standpoint, there's a cleaner separation of concerns).
- Terminal output is nicer, cleaner and more useful.

### Handlebars compilation improvements

- Created a new `{{specimen}}` helper, which is more intuitive and eliminates the need to register two partials for each specimen (i.e. `{{> specimen-name }}` and `{{> specimen-name-snippet }}`).
- Removed hacky "metadata" code comments from specimens and pages.
- Removed a ton of hacky regex (trust me, things are better now).
- All Handlebars partials now require you to explicitly pass JSON objects to them, which makes things easier to understand and debug (no more mysterious, automatic inheritance).
- Eliminated a hack where one of the Handlebars templates had to be double-processed.

### Specimens

- Removed unnecessary `notes.html` files.
- Improved/formalized the way that 3rd-party CSS and JavaScript can be added to specimen pages (`external.yml` file instead of a "metadata" code comment).
- Added the ability to define multiple JSON data sources for a single specimen. Made it possible to generate these JSON objects via JavaScript (so we can use variables, loops, etc). Added ability to toggle between them in the UI via a select box, which causes the iframe to reload when the selection changes.
- Cleaned up iframe markup and code.
- Added new options and tools, including: "auto resize" checkbox, anchor links, contenteditable width and height fields, "fixed height" mode, "seamless" mode and "no resize" mode.
- Added the ability to include specimens inside layouts (i.e. tables, etc.) and iframes respect the width of their parent container. This will allow us to create more expressive pages.
- Made specimen toolbars sticky.
- Separated specimen JSON data from Handlebars templates, which now live inside the `patterns` directory, so they could potentially be pulled into external projects. It makes sense to bundle pattern markup with pattern CSS and JavaScript.

### Site

- Added the ability to add custom CSS and JavaScript to site pages, in the same way that it can be added to specimen pages (`script.js` and `style.scss` files).
- Added the ability to add 3rd-party CSS and JavaScript to site pages, in the same way that it can be added to specimen pages (`external.yml` file).
- Improved site layout: eliminated useless header and abandoned flexbox-based layout (thereby making it possible to implement specimen anchor links and sticky toolbars).
- Made the app capable of recognizing the difference between local development and production by setting an environment variable in the NPM script.
- Added the ability to omit pages from the menu in production by adding `hidden: true` to items in the `navigation.yml` file.
- Refactored and improved site JavaScript.

### Patterns

- Eliminated the "tgam" directory because it was unnecessary and made the app inflexible because it was hard-coded throughout the various Gulp tasks.

### General

- Simplified directory structure (no more `src` directory).
- Added the ability to have different `basePath`s in development and production (see `config.js`).
- Overall, compilation should now be faster (TODO: compare performance once all of the pages, specimens and patterns have been ported over).
- Removed the `tgam/whatever` alias for SCSS and JavaScript files, which makes things easier to understand (i.e. you now have to use relative paths like `require("../whatever");` and `@import "../whatever";` to import files from the `patterns` directory into your pages and specimens).
- Added a "prototype" page and specimen to document the various files and how to use them (see the `prototypes` directory). In the future we could create a CLI command that would duplicate the `prototypes/page` and `prototypes/specimen` directories and use them as starting points for a new pages and specimens.
- We're now using Express as the application server, which means that we could create routes that could process AJAX requests from the browser and make it more web app-like (potential future awesomeness).

## Future plans

- Write new media queries to make the static site usable on mobile devices.
- Add a `keywords` property to items in the `navigation.yml` file and add a "filter" text field to the sidebar. As the user types, navigation links hide or reveal based on whether or not their keywords match the search term.
- Port the "view specimen in CodePen" feature that JP created for his grid system over to this repo (won't be possible until the website goes public).
- Accessibility improvements.
- IE and Edge testing (is the CustomEvent polyfill loading where it needs to?).
- Add [SVGO](https://github.com/svg/svgo) to the project and create an automated SVG sprite-generation pipeline.
- Split the entire app into two separate NPM modules: the "core" and a "theme". The theme will depend on the core and will pass configuration data down into it. The theme will be able to override various Handlebars templates and CSS, which will enable users to customize the look of their static website. Core defaults will be used if they are not overridden by the theme (PatternEngine and PatternEngineTheme).
- Add the ability to flag specimens as "alpha" or "under construction".
- Add preset widths to specimen toolbar that set the iframe width on click (similiar to Chrome dev tools).
- Add an "initialHeight" option to specimen helpers (when used, autoHeight would become false, but checkbox would still be available)

## Known issues

- None currently.
