syrup/README.md

A collection of common UI utilities and libraries leveraged by AI2.

# Syrup

Syrup is a collection of shared UI utilities and libraries leveraged by [AI2](http://github.com/allenai) when developing interfaces.

## Installation

Install via `npm`:

```shell
npm install syrup
```

## API

### syrup.gulp.tasks(gulp, configParameters, configKeys, paths)

```javascript
/**
 * Registers default gulp tasks.
 *
 * @param {object}  gulp                          The gulp library.
 * @param {object}  options                       Optional object definining configuration
 *                                                parameters.
 * @param {object}  options.compressJs            If true javascript will be minified. Defaults
 *                                                to true.
 * @param {object}  options.sourceMaps            Enables javascript source maps. Defaults to
 *                                                true.
 * @param {object}  options.compressCss           If true styles will be compressed. Defaults to
 *                                                true.
 * @param {string}  options.jsOut                 Sets the name of the javascript file produced
 *                                                by the javascript build step. Defaults to
 *                                                "app.js".
 * @param {object}  configParameters              Optional map of configuration keys. If set each
 *                                                key is searched for in the html contents of the
 *                                                application and replaced with the corresponding
 *                                                value.
 * @param {object}  paths                         Optional object defining paths relevant to the
 *                                                project. If not specified the defaults are used.
 * @param {string}  paths.base                    The base directory of your project where the
 *                                                gulpfile itself lives.  Defaults to
 *                                                process.cwd().
 * @param {string}  paths.src                     Path to the application's source files.
 * @param {string}  paths.html                    Path to the project's HTML files.
 * @param {string}  paths.jshint                  Path to javascript files which should be linted
 *                                                using jshint.
 * @param {string}  paths.js                      Path to javascript files to be bundled using
 *                                                browserify.
 * @param {string}  paths.less                    Path to the project's less files.
 * @param {string}  paths.assets                  Path to the project's assets.
 * @param {string}  paths.fonts                   Path to the project's fonts.
 * @param {string}  paths.build                   Path to the project's build directory where the
 *                                                final output should be placed.
 * @param {string}  paths.tmp                     Path where temporary files should be put.
 * @param {string}  paths.watch                   Path to the files which should be watched for
 *                                                changes while the griddle serve is running and
 *                                                trigger a rebuild as changes occur.
 * @param {string}  paths.unitTests               Path to the project's unit tests. These files
 *                                                are browserified to paths.tmp prior to execution
 * @param {string}  paths.unitTestConfig          Path to the project's karma configuration file.
 * @param {string}  paths.integrationTestConfig   Path to the project's pesto / protractor
 *                                                configuration file.
 * @returns {undefined}
 */
syrup.gulp.tasks(gulp, options, configParameters, paths)
```

The default paths are as follows.

```javascript
{
  base: process.cwd(),
  src: 'app',
  html: 'app/index.html',
  allLess: 'app/**/*.less',
  less: 'app/main.less',
  jshint: 'app/**/*.js',
  js: 'app/app.js',
  assets: 'app/assets/**/*',
  fonts: 'node_modules/syrup/fonts/**/*',
  build: 'build',
  watch: 'app',
  tmp: 'tmp',
  unitTests: 'app/**/*-test.js',
  unitTestConfig: 'unit-tests.conf.js',
  integrationTestConfig: 'integration-tests.conf.js',
  integrationTests: 'integration-tests/**/*-it.js'
}
```

See [Karma](http://karma-runner.github.io/) for more on writing, configuring and running unit tests.

See [Pesto](https://github.com/allenai/pesto) for more on writing, configuring and running integration tests.

### syrup.server.start(options)

```javascript
/**
 * Starts an express + griddle based HTTP server with the specified options.  The HTTP server
 * serves static files located in options.serve which are built dynamically using the gulpfile
 * located in options.base.   If options.watch is set to true, the project is rebuilt everytime
 * changes within options.base are detected.
 *
 * @param {object}  options                   Server options.
 * @param {object}  options.base              The base path to the project (where the gulpfile lives).
 * @param {string}  options.serve             The directory from which to serve static files.
 * @param {string}  [options.watch=undefined] Directory to watch for changes and trigger rebuilds
 *                                            as they occur.
 * @param {number}  [options.port=4000]       The port to listen on, defaults to 4000.
 *
 * @returns {Promise} A promise which is resolved once the server is started.
 */
```

A server can also be started using the gulp task, `start-server`:

```shell
gulp start-server
```

### syrup.server.stop()

```javascript
/**
 * Stops a server if there's one running.
 *
 * @returns {Promise} A promise which is resolved once the server is stopped.
 */
```

Example:

```javascript
var gulp = require('gulp');
var syrup = require('syrup');

syrup.gulp.tasks(gulp);
```

Now, from the command line run:

```
gulp build
```

## Default Styles

Example Use:

```css
@import '../../node_modules/syrup/less/syrup.less';
```

Included Stylesheets:

* `syrup/less/syrup.less`: A collection of less styles which include:
  * `syrup/less/colors.less`: Common colors.
  * `syrup/less/defaults.less`: Opinionated defaults.
  * `syrup/less/dimensions.less`: Variables related to standard site dimensions.
  * `syrup/less/functions.less`: Utility functions.
  * `syrup/less/icons.less`: Webfont icons.
  * `syrup/less/reset.less`: Browser style normalization.
  * `syrup/less/responsive.less`: Basic responsiveness for specified containers.
  * `syrup/less/text.less`: Typographic styles.

Colors:

The following colors are available upon including `colors.less`:

```less
/* ==========================================================================
   AI2 Brand Colors
   ========================================================================== */

@black: #202122;
@dark-blue: #286a8e;
@blue: #5ea5d9;
@gold: #fcb431;
@yellow: #fdea65;
@off-black: #3e4346;
@gray: #8c9296;
@light-blue: #bed2dd;
@light-gray: #e0e0e0;
@white: #fff;

@lighter-gray: lighten(@light-gray, 8%);
@lighter-blue: lighten(@light-blue, 12%);

@red: #a92020;
@green: #3fb62c;
@purple: #81288e;
@orange: #e26622;

@shadow: rgba(45,45,46,0.1);
@dark-shadow: rgba(45,45,46,0.2);
@translucent: rgba(255,255,255,.95);
```