Merge develop into master

Author: nicoespeon

CONTRIBUTING.md

@@ -7,27 +7,41 @@ Glad to hear you'd like to help us improving the library. Here's the how-to!
 
 Sounds nice! Please proceed as following:
 
-1. **Search for existing issues.** Sometimes, other folks may have reported the same issue and it'd be nice not to duplicate them.
-2. If possible, please **create an isolated and reproducible test case.** Make use of [jsFiddle](jsfiddle.net) - for instance - to share your isolated test cases. We won't hold it against you for feature requests, but a live [POC](http://en.wikipedia.org/wiki/Proof_of_concept) is sometimes easier to catch.
-3. **Share as much information as possible.** Include browser and version, version of gitgraph.js, etc. where appropriate. That can help us to reproduce the bug, if so.
+1. **Search for existing issues.** Sometimes, other folks may have reported the
+   same issue and it'd be nice not to duplicate them.
+2. If possible, please **create an isolated and reproducible test case.** Make
+   use of [jsFiddle](jsfiddle.net) - for instance - to share your isolated test
+   cases. We won't hold it against you for feature requests, but a live [POC][]
+   is sometimes easier to catch.
+   [POC]: http://en.wikipedia.org/wiki/Proof_of_concept
+3. **Share as much information as possible.** Include browser and version,
+   version of gitgraph.js, etc. where appropriate. That can help us to reproduce
+   the bug, if so.
 
 ## Or wanna contribute to the code?
 
 Github's Pull Request is a fantastic tool to contribute to the code.
 
 Just keep in mind the following rules:
 
-- Change must be done in `src/` files, eventually `test/` or `examples/`, that's all.
+- Change must be done in `src/` files, eventually `test/` or `examples/`, that's
+  all.
 - You'd be nice not to pollute your pull request with unintended changes.
-- Pull requests should always be against the `develop` branch, never against `master` nor `gh-pages`.
+- Pull requests should always be against the `develop` branch, never against
+  `master` nor `gh-pages`.
 
-Once you send a Pull Request, your code will be check with [Travis CI](https://travis-ci.org/nicoespeon/gitgraph.js) to tell whether you break the build or not. The Travis test should pass before we accept any Pull Request.
+Once you send a Pull Request, your code will be checked with [Travis CI][] to
+tell whether you break the build or not. The Travis test should pass before we
+accept any Pull Request.
+[Travis CI]: https://travis-ci.org/nicoespeon/gitgraph.js
 
 ## Check about our coding standards
 
-Please follow our coding standards as best as you can to keep consistency over code.
+Please follow our coding standards as best as you can to keep consistency over
+code.
 
-The [.editorconfig](https://github.com/nicoespeon/gitgraph.js/blob/develop/.editorconfig) file should help you configure your IDE to do so.
+The [.editorconfig][] file should help you configure your IDE to do so.
+[.editorconfig]: https://github.com/nicoespeon/gitgraph.js/blob/develop/.editorconfig
 
 ### JS
 
@@ -40,10 +54,14 @@ The [.editorconfig](https://github.com/nicoespeon/gitgraph.js/blob/develop/.edit
 
 - Adhere to the (default) [CSScomb](http://csscomb.com/) property order
 - Multiple-line approach (one property and value per line)
-- Always a space after a property's colon (.e.g, `display: block;` and not `display:block;`)
+- Always a space after a property's colon (.e.g, `display: block;` and not
+  `display:block;`)
 - End all lines with a semi-colon
 - For multiple, comma-separated selectors, place each selector on its own line
-- Attribute selectors, like `input[type="text"]`, should always wrap the attribute's value in double quotes, for consistency and safety (see [this blog post on unquoted attribute values](http://mathiasbynens.be/notes/unquoted-attribute-values) that can lead to XSS attacks).
+- Attribute selectors, like `input[type="text"]`, should always wrap the
+  attribute's value in double quotes, for consistency and safety (see [this blog
+  post on unquoted attribute values][blog] that can lead to XSS attacks).
+  [blog]: http://mathiasbynens.be/notes/unquoted-attribute-values
 
 ### HTML
 
@@ -54,6 +72,8 @@ The [.editorconfig](https://github.com/nicoespeon/gitgraph.js/blob/develop/.edit
 
 ## License
 
-By contributing your code, you agree to license your contribution under the terms of [the MIT license](https://github.com/nicoespeon/gitgraph.js/blob/master/LICENSE.md).
+By contributing your code, you agree to license your contribution under the
+terms of the [MIT license][]
+[MIT license]: https://github.com/nicoespeon/gitgraph.js/blob/master/LICENSE.md
 
 [> What does that mean?](http://choosealicense.com/licenses/mit/)

README.md

@@ -13,59 +13,78 @@ You have different options to start with the library:
 
 - [Download the latest release](https://github.com/nicoespeon/gitgraph.js/releases/latest).
 - Clone the repo: `git clone git://github.com/nicoespeon/gitgraph.js.git`.
+- Install with [npm](https://www.npmjs.com): `npm install --save gitgraph.js`.
 - Install with [Bower](http://bower.io/): `bower install gitgraph.js`.
 - Use [the CDNjs hosted lib](https://cdnjs.com/libraries/gitgraph.js).
 
 Production files are available under the `build/` directory.
 
 ## Report a bug / Ask for a feature
 
-You found some nasty bug or have a cool feature request? [Just open a new issue](https://github.com/nicoespeon/gitgraph.js/issues).
+You found some nasty bug or have a cool feature request? [Just open a new
+issue](https://github.com/nicoespeon/gitgraph.js/issues).
 
-Please have a look at [the Issue Guidelines](https://github.com/necolas/issue-guidelines/blob/master/CONTRIBUTING.md) from [Nicolas Gallagher](https://github.com/necolas) before doing so.
+Please have a look at the [Issue Guidelines][] from [Nicolas Gallagher][] before
+doing so.
+[Issue Guidelines]: https://github.com/necolas/issue-guidelines/blob/master/CONTRIBUTING.md
+[Nicolas Gallagher]: https://github.com/necolas
 
 ## Documentation
 
 The JavaScript source code is documented with [JSDoc](http://usejsdoc.org/).
 
 ## Contributing
 
-Editor preferences are available in [the editor config](https://github.com/nicoespeon/gitgraph.js/blob/master/.editorconfig) for easy use in common text editors. Read more and download plugins at <http://editorconfig.org>.
+Editor preferences are available in for [the editor config][] easy use in common
+text editors. Read more and download plugins at <http://editorconfig.org>.
+[the editor config]: https://github.com/nicoespeon/gitgraph.js/blob/master/.editorconfig
 
-The project uses [Grunt](http://gruntjs.com) with convenient methods for our workflow. It's how we lint our code, run tests, generate documentation, etc. To use it, install the required dependencies as directed and then run the following Grunt commands.
+The project uses [Grunt](http://gruntjs.com) with convenient methods for our
+workflow. It's how we lint our code, run tests, generate documentation, etc. To
+use it, install the required dependencies as directed and then run the following
+Grunt commands.
 
 ### Install Grunt
 
 From the command line:
 
 - Install `grunt-cli` globally with `npm install -g grunt-cli`.
-- Install [the necessary local dependencies](https://github.com/nicoespeon/gitgraph.js/blob/master/.editorconfig) with `npm install`.
+- Install [the necessary local dependencies][] with `npm install`.
+[the necessary local dependencies]: https://github.com/nicoespeon/gitgraph.js/blob/master/package.json
 
-When completed, you'll be able to run the various Grunt commands provided from the command line.
+When completed, you'll be able to run the various Grunt commands provided from
+the command line.
 
 [> Need more information about how to get started with Grunt?](http://gruntjs.com/getting-started)
 
 ### Available Grunt commands
 
 #### test code - `grunt test`
 
-Check source code against [JSHint](http://www.jshint.com/) then runs unit tests with [Jasmine](http://pivotal.github.io/jasmine/).
+Check source code against [JSHint][] then runs unit tests with [Jasmine][].
+[JSHint]: http://www.jshint.com/
+[Jasmine]: https://jasmine.github.io/
 
 #### generate documentation - `grunt doc`
 
-Generate source code documentation into `dist/docs/` (not versioned) with [JSDoc](http://usejsdoc.org/).
+Generate source code documentation into `dist/docs/` (not versioned) with
+[JSDoc](http://usejsdoc.org/).
 
 #### compile a non-versioned release - `grunt dist`
 
-Clean `dist/` directory, lint code, output the minified release into `dist/gitgraph.min.js` and generate the documentation into `dist/docs/`.
+Clean `dist/` directory, lint code, output the minified release into
+`dist/gitgraph.min.js` and generate the documentation into `dist/docs/`.
 
 #### compile a new release - `grunt release`
 
-Lint code, output the source and minified releases into `build/` and generate the official documentation into `docs/`.
+Lint code, output the source and minified releases into `build/` and generate
+the official documentation into `docs/`.
 
 #### open a live reload server - `grunt server`
 
-For a better code experience, this grunt task opens a live server in your favorite browser. This server is automatically reloaded when you save a project file.
+For a better code experience, this grunt task opens a live server in your
+favorite browser. This server is automatically reloaded when you save a project
+file.
 
 Please note that `examples/index.html` is the default file for testing ;)
 
@@ -83,9 +102,11 @@ Releases will be numbered with the following format:
 
 And constructed with the following guidelines:
 
-- Breaking backward compatibility bumps the `<major>` (and resets the `<minor>` and `<patch>`)
-- New additions without breaking backward compatibility bumps the `<minor>` (and resets the `<patch>`)
-- Bug fixes and misc. changes bumps the `<patch>`
+- Breaking backward compatibility bumps the `<major>` (and resets the `<minor>`
+  and `<patch>`)
+- New additions without breaking backward compatibility bump the `<minor>` (and
+  reset the `<patch>`)
+- Bug fixes and misc. changes bump the `<patch>`
 
 ## Authors and contributors
 
@@ -95,6 +116,7 @@ And constructed with the following guidelines:
 
 ## Copyright and License
 
-Copyright (c) 2013 Nicolas CARLO and Fabien BERNARD under [the MIT license](https://github.com/nicoespeon/gitgraph.js/blob/master/LICENSE.md).
+Copyright (c) 2013 Nicolas CARLO and Fabien BERNARD under the [MIT license][]
+[MIT license]: https://github.com/nicoespeon/gitgraph.js/blob/master/LICENSE.md
 
 [> What does that mean?](http://choosealicense.com/licenses/mit/)

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "gitgraph.js",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "main": [ "./build/gitgraph.js", "./build/gitgraph.css" ],
   "ignore": [
     "**/.*"

build/gitgraph.js

@@ -1,5 +1,5 @@
 /* ==========================================================
- *                  GitGraph v1.4.0
+ *                  GitGraph v1.5.0
  *      https://github.com/nicoespeon/gitgraph.js
  * ==========================================================
  * Copyright (c) 2016 Nicolas CARLO (@nicoespeon) ٩(^‿^)۶
@@ -196,22 +196,32 @@
     this.commitOffsetY = options.initCommitOffsetY || 0;
 
     // Bindings
-    var mouseMoveOptions = {
+    this.mouseMoveOptions = {
       handleEvent: this.hover,
       gitgraph: this
     };
-    this.canvas.addEventListener( "mousemove", mouseMoveOptions, false );
+    this.canvas.addEventListener( "mousemove", this.mouseMoveOptions, false );
 
-    var mouseDownOptions = {
+    this.mouseDownOptions = {
       handleEvent: this.click,
       gitgraph: this
     };
-    this.canvas.addEventListener( "mousedown", mouseDownOptions, false );
+    this.canvas.addEventListener( "mousedown", this.mouseDownOptions, false );
 
     // Render on window resize
     window.onresize = this.render.bind( this );
   }
 
+  /**
+   * Disposing canvas event handlers
+   *
+   * @this GitGraph
+   **/
+  GitGraph.prototype.dispose = function () {
+    this.canvas.removeEventListener( "mousemove", this.mouseMoveOptions, false );
+    this.canvas.removeEventListener( "mousedown", this.mouseDownOptions, false );
+  };
+
   /**
    * Create new branch
    *
@@ -372,6 +382,14 @@
    * @callback commitCallback
    * @param {Commit} commit - A commit
    * @param {boolean} mouseOver - True, if the mouse is currently hovering over the commit
+   * @param {Event} event - The DOM event (e.g. a click event)
+   */
+
+  /**
+   * A formatter for commit
+   *
+   * @callback commitFormatter
+   * @param {Commit} commit - The commit to format
    */
 
   /**
@@ -403,7 +421,7 @@
       var distanceBetweenCommitCenterAndMouse = Math.sqrt( Math.pow( distanceX, 2 ) + Math.pow( distanceY, 2 ) );
       var isOverCommit = distanceBetweenCommitCenterAndMouse < this.template.commit.dot.size;
 
-      callbackFn( commit, isOverCommit );
+      callbackFn( commit, isOverCommit, event );
     }
   };
 
@@ -450,7 +468,7 @@
       _emitEvent( self.canvas, "commit:" + event, mouseEventOptions );
     }
 
-    self.applyCommits( event, function ( commit, isOverCommit ) {
+    self.applyCommits( event, function ( commit, isOverCommit, event ) {
       if ( isOverCommit ) {
         if ( !self.template.commit.message.display && self.template.commit.shouldDisplayTooltipsInCompactMode ) {
           showCommitTooltip( commit );
@@ -485,13 +503,13 @@
    * @this GitGraph
    **/
   GitGraph.prototype.click = function ( event ) {
-    this.gitgraph.applyCommits( event, function ( commit, isOverCommit ) {
+    this.gitgraph.applyCommits( event, function ( commit, isOverCommit, event ) {
       if ( !isOverCommit ) {
         return;
       }
 
       if ( commit.onClick !== null ) {
-        commit.onClick( commit, true );
+        commit.onClick( commit, true, event );
       }
     } );
   };
@@ -1220,7 +1238,7 @@
    * @param {Boolean} [options.commit.message.displayHash] - Commit message hash policy
    * @param {String} [options.commit.message.font = "normal 12pt Calibri"] - Commit message font
    * @param {Boolean} [options.commit.shouldDisplayTooltipsInCompactMode] - Tooltips policy
-   * @param {commitCallback} [options.commit.tooltipHTMLFormatter=true] - Formatter for the tooltip contents.
+   * @param {commitFormatter} [options.commit.tooltipHTMLFormatter=true] - Formatter for the tooltip contents.
    *
    * @this Template
    **/

build/gitgraph.min.js

@@ -324,7 +324,7 @@ <h6>Properties</h6>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line506">line 506</a>
+        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line524">line 524</a>
     </li></ul></dd>
 
 
@@ -465,7 +465,7 @@ <h5>Parameters:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line595">line 595</a>
+        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line613">line 613</a>
     </li></ul></dd>
 
 
@@ -566,7 +566,7 @@ <h5>This:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line870">line 870</a>
+        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line888">line 888</a>
     </li></ul></dd>
 
 
@@ -638,7 +638,7 @@ <h5>This:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line790">line 790</a>
+        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line808">line 808</a>
     </li></ul></dd>
 
 
@@ -833,7 +833,7 @@ <h6>Properties</h6>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line669">line 669</a>
+        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line687">line 687</a>
     </li></ul></dd>
 
 
@@ -912,7 +912,7 @@ <h5>This:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line799">line 799</a>
+        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line817">line 817</a>
     </li></ul></dd>
 
 
@@ -1092,7 +1092,7 @@ <h5>Parameters:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line813">line 813</a>
+        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line831">line 831</a>
     </li></ul></dd>
 
 
@@ -1187,7 +1187,7 @@ <h5>This:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line895">line 895</a>
+        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line913">line 913</a>
     </li></ul></dd>
 
 
@@ -1259,7 +1259,7 @@ <h5>This:</h5>
 
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line620">line 620</a>
+        <a href="gitgraph.js.html">gitgraph.js</a>, <a href="gitgraph.js.html#line638">line 638</a>
     </li></ul></dd>
 
 
@@ -1306,7 +1306,7 @@ <h2><a href="index.html">Index</a></h2><h3>Classes</h3><ul><li><a href="Branch.h
 <br clear="both">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.2.2</a> on Fri Sep 02 2016 21:24:48 GMT+0200 (CEST)
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.2.2</a> on Fri Dec 09 2016 08:47:33 GMT+0100 (CET)
 </footer>
 
 <script> prettyPrint(); </script>