patternpack/readme.md

Build and Document Your Interface. Then Share the Code.

# PatternPack
PatternPack is designed to accelerate the creation of web application pattern libraries. When configured properly it will generate a static site pattern library. The [patternpack-example-library](https://github.com/patternpack/patternpack-example-library) demonstrates exactly how to do this and is a good place to learn how to use PatternPack.

## Getting Started
This plugin requires Grunt `~0.4.0`

If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

```shell
npm install patternpack --save-dev
```

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

```javascript
grunt.loadNpmTasks('patternpack');
```

A basic `gruntfile.js` for PatternPack should look like:

```javascript
module.exports = function (grunt) {
  grunt.initConfig({
    patternpack: {
      run: {},
      build: {},
      release: {}
    }
  });

  grunt.loadNpmTasks('patternpack');

  grunt.registerTask('default', ['patternpack:run']);
}
```

Running `grunt` with this will auto-generate all necessary files on initial run.

To learn more about PatternPack, check out the [Guides and Resources](https://github.com/patternpack/patternpack/blob/master/docs/docs.md). We also have a [Slack channel](http://slack.patternpack.org/) available.

## PatternPack Task
_Run this task with the `grunt patternpack` command._

Task options may be specified according to the grunt [Configuring tasks](http://gruntjs.com/configuring-tasks) guide. However the files and targets are not used at this time.

### Options

#### src
Type: `string`  
Default: `./src`

The path at which the patterns can be located. This is base path to all the pattern in the pattern library.

#### build
Type: `string`  
Default: `./html`

The path at which the patterns library will be generated. This is the base path where the working pattern library will be created, and can be reviewed during development.

#### release
Type: `string`  
Default: `./release`

The path at which the pattern library will published. This is the base path where the released pattern library assets can be found by consuming applications.

#### task
Type: `string`  
Default: `""`  
Allowed Values: `"", default, build, integrate, release, release-patch, release-minor, release-major`

The action that PatternPack will take when run.

> `""` `default`: builds the pattern library and runs a local webserver.
> `build`: builds the pattern library.
> `release`: alias for `release-patch`.
> `release-patch`: patch increment to the package version, then performs a release.
> `release-minor`: minor increment to the package version, then performs a release.
> `release-major`: major increment to the package version, then performs a release.

A release performs the following actions
* Increments the package version
* Copies the current build to the release location
* Commits the changes with the version number as the message

#### assets
Type: `string`  
Default: `./src/assets`

A folder to house any additional assets to be shared across projects (e.g., fonts, icons, images, etc.).

#### theme
Type: `string`  
Default: `patternpack-example-theme`

The name of the npm package (or the path) which contains the PatternPack theme. Custom themes can be npm modules or simply files that exist within a pattern library. By default PatternPack is configured to use the [patternpack-example-theme](https://github.com/patternpack/patternpack-example-library)

#### data
Type: `string`
Default: `./data`

Allows you to pass JSON or YML data files from this directory into your pages. By default, it would be exposed as `{{filename}}`. To learn more look at the [Assemble's documentation on supplying data to templates](http://assemble.io/docs/options-data.html).

#### logo
Type: `string`  
Default: `/theme-assets/images/logo.svg`

*Note: if you are using a custom `options.theme` value, this option is not necessary*

If you're using the default theme, you can pass in a custom logo to be used with your library. It should be the path to your logo file relative to the build directory (`./html/` if you didn't configure `options.build`). It's recommended to put the logo inside of the `./src/assets/images` directory, and then pass in a value of `/assets/images/yourLogo.png`.

The logo will be resized via CSS to a `max-height` of 30px.

#### css.preprocessor
Type: `string`  
Default: `sass`
Allowed Values: `sass, less, none, ""`

The type of css preprocessor to run.
> `sass`: runs the sass preprocessor on `assets/sass/options.css.fileName.scss`
> `less`: runs the less preprocessor on `assets/less/options.css.fileName.less`
> `""` `none`: does not run any css preprocessor

#### css.fileName
Type: `string`  
Default: `patterns`

The final CSS file you will create that will `import` all your patterns and any other CSS you write. You will manually create this file which will be automatically watched during development and have your configured CSS preprocessor and autoprefixer run on it. Do not add an extension to this file name.

It must live in your configured `assets` directory under a `sass` or `less` subdirectory (e.g., `src/assets/sass/patterns.scss`).

#### css.autoprefixer
Type: `array`  
Default: `browsers: ['last 2 versions']`

Pass in options to PostCSS Autoprefixer. See the [available options](https://github.com/postcss/autoprefixer#options).

#### publish.library
Type: `boolean`  
Default: `true`

Indicates whether a full pattern library will be generated.

#### publish.patterns
Type: `boolean`  
Default: `false`

Indicates whether standalone patterns will be generated.

_This option can be useful if you would like to integrate patterns directly into another application. For example when the patterns includes components or interations that are only available in the context of the application (such as AngularJS directives)._

#### patternStructure
Type: `Array`  
Default:
```javascript
[
  { "name": "Atoms", "path": "atoms" },
  { "name": "Molecules", "path": "molecules" },
  { "name": "Pages", "path": "pages" }
]
```

Specifies the hierarchy used to organize patterns. The default configuration represents the atomic design hierarch, but this can be overriden with any preferred structure.

>`name`: The friendly name that is displayed in the pattern library.
>`path`: The location at which the patterns can be found. This path is relative to the `src` path.

_The order of the items in the Array determines the order in which they will be displayed in the pattern library._

#### server
See the options in [`grunt-connect`](https://github.com/gruntjs/grunt-contrib-connect#options)

For example:

```javascript
  server: {
    port: 5555
  }
```

#### integrate
Type: `string`  
Default: none

Configures a directory where library builds will copy when running the `patternpack:integrate` command. Note that it is not recommended to configure this in your gruntfile when sharing across a team. Instead, use the `.patternpackrc` [method below](#user-specific-settings-override).

### Usage Examples

#### Basic usage
This is an example of the most minimal configuration possible for PatternPack. If the default conventions are followed, minimal grunt configuration is required.

```javascript
patternpack: {
  run: {},
  build: {},
  integrate: {},
  release: {},
  "release-patch": {},
  "release-minor": {},
  "release-major": {}
}
```

#### Custom task names
This example shows how task names can be customized. Configuring the the `task` option specifies what action PatternPack will take when the custom task is called.

```javascript
patternpack: {
  customDev: {
    task: 'default' // builds the application and runs the server
  },
  customBuild: {
    task: 'build' // builds the application
  },
  customRelease: {
    task: 'release' // releases the current build
  }
}
```

#### Custom file locations
This example demonstrates how to configure PatternPack to point to different file locations for the patterns, and then output the resulting pattern library to a custom location.

```javascript
patternpack: {
  options: {
    src: './path/to/patterns',
    build: './path/to/pattern-library',
    release: './path/to/release'
  }
}
```

#### Custom pattern structure
Using the `patternStructure` option, you are able to configure the categories you will put your patterns in. In this case `components`, `modules`, `templates` and `pages`.

```javascript
patternpack: {
  options: {
    patternStructure: [
      { "name": "Components", "path": "components" },
      { "name": "Modules", "path": "modules" },
      { "name": "Templates", "path": "tmpl" }
      { "name": "Pages", "path": "pages" }
    ]
  }
}
```

In this configuration PatternPack would look for patterns in:
```
src/
  components
  modules
  tmpl
  pages
```

Where src/ is configured in [`options.src`](#src).

#### User-specific settings override
An individual developer can override any option in the `patternpack` task by creating a `.patternpackrc` file. This is a JSON file that would mirror the contents of the `patternpack.options` portion of your task. It's recommended to add the `.patternpackrc` file to your `.gitignore`

For example, to override the server configuration, set up a `.patternpackrc` file:

```javascript
{
  "server": {
    "port": 1234
  }
}
```

Note that this file should be conforming JSON, so all strings should be wrapped in double quotes.

#### All available options
This example shows all options with their default options.

```javascript
{
  release: "./dist",
  build: "./html",
  src: "./src",
  assets: "./src/assets",
  css: {
    preprocessor: "sass",
    fileName: "project",
    autoprefixer: {
      browsers: ["last 2 versions"]
    }
  }
  integrate: "../patternpack-example-app/node_modules/patternpack-example-library",
  theme: "./node_modules/patternpack-example-theme",
  logo: "./theme-assets/images/logo.svg",
  publish: {
    library: true,
    patterns: false
  },
  patternStructure: [
    { name: "Atoms", path: "atoms" },
    { name: "Molecules", path: "molecules" },
    { name: "Pages", path: "pages" }
  ],
  server: {
    port: 1234
  }
}
```

### Modular Tasks
PatternPack makes some of its bundled functionality available in modular tasks. They are helpful if you are trying to add custom functionality to your pattern library.

These are available as a part of your `patternpack` task in your `gruntfile.js`:

```
patternpack: {
  options: {
    ...
  },
  build: {},
  "build-styles": {},
  "build-pages": {},
  integrate: {},
},
```

#### patternpack:build
This does a complete rebuild of your styles and website into your build directory (`/html/`). The only difference from this to `patternpack:run` is that no webserver/livereload is spun up.

1. Cleans your build directory
1. Builds your CSS (`patternpack:build-styles`)
  1. Globs the Sass/LESS in your component directories
  1. Builds all your Sass/LESS
  1. Runs Autoprefixer
  1. Copies your CSS to your build directory
1. Builds your site pages into your build directory (`patternpack:build-pages`)

#### patternpack:build-styles
This does a rebuild of your CSS into your build directory.

1. Globs the Sass/LESS in your component directories
1. Builds all your Sass/LESS
1. Runs Autoprefixer

#### patternpack:build-pages
This rebuilds your website pages into your build directory.

## PatternPack Workflow

### Pattern Library Development
When developing new patterns for a pattern library, PatternPack provides the `patternpack:default` and `patternpack:build` tasks to assist with the process. The `patternpack:default` task is primarily used for interactive development. It hosts a simple webserver for reviewing changes, and will automatically compile CSS and markdown into patterns as changes are made.

The `patternpack:build` task does not run the webserver or monitor for changes. It is best used for manual updates and inspection of the pattern library. It is also useful to call as part of a customized build process.

### Pattern Library Release
In order to release a new version of a pattern library you create with PatternPack, the following sequence of commands should be executed.

```shell
$ grunt patternpack:release
$ git push --follow-tags
```

`grunt patternpack:release` generates the pattern library, increments the version, copies the pattern library to the release location, commits the code and tags the git repo with the new version number. `git push --follow-tags` pushes the code changes to the origin and the newly added tag.

Once released your application should be able to reference the newly tagged version of the pattern library to utilize the new patterns.