Repository setup and initial implementation

Author: simonbrunel

.gitignore

@@ -0,0 +1,3 @@
+/dist
+/node_modules
+.DS_Store

LICENSE.md

@@ -0,0 +1,9 @@
+**The MIT License (MIT)**
+
+Copyright (c) 2016 Simon Brunel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,45 @@
+# Chart.Deferred.js
+
+A [Chart.js](http://www.chartjs.org/) plugin to defer the initial chart update until the user scrolls and the canvas appears inside the viewport. The main intent of Chart.Deferred.js is to trigger the initial chart animations when the user is likely to see them.
+
+Requires Chart.js **2.1.5** or later.
+
+## Configuration
+
+To configure this plugin, you can simply add the following entries to your chart options:
+
+| Name | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `deferred` | `Object/Boolean` | `true` | The deferred options (see `deferred.*` options). Also accepts a boolean, in which case if `true`, the chart will be deferred using the default options, else if `false`, the chart will not be deferred.
+| `deferred.enabled` | `Boolean` | `true` | `true` to enable this plugin, else `false` to disable it for the associated chart.
+| `deferred.xOffset` | `Number/String` | `0` | Number of pixels (or percent of the canvas width) from which the chart is considered inside the viewport.
+| `deferred.yOffset` | `Number/String` | `0` | Number of pixels (or percent of the canvas height) from which the chart is considered inside the viewport.
+| `deferred.delay` | `Number` | `0` | Number of milliseconds to delay the loading after the chart is considered inside the viewport.
+
+For example:
+
+```
+{
+    deferred: {           // enabled by default
+        xOffset: 150,     // defer until 150px of the canvas width are inside the viewport
+        yOffset: '50%',   // defer until 50% of the canvas height are inside the viewport
+        delay: 500        // delay of 500 ms after the canvas is considered inside the viewport
+    }
+}
+```
+
+Note that default options will defer the chart loading until the first line of pixels of the canvas appears in the viewport.
+
+## Development
+
+The following commands are available from the repository root (requires [Node.js](https://nodejs.org/))
+
+```shell
+> npm install           // initialize node dependencies
+> gulp build            // build dist files
+> gulp build --watch    // build and watch for changes
+```
+
+## License
+
+Chart.Deferred.js is available under the [MIT license](LICENSE.md).

gulpfile.js

@@ -0,0 +1,54 @@
+var argv = require('yargs').argv
+var gulp = require('gulp');
+var insert = require('gulp-insert');
+var rename = require('gulp-rename');
+var replace = require('gulp-replace');
+var streamify = require('gulp-streamify');
+var uglify = require('gulp-uglify');
+var gutil = require('gulp-util');
+var path = require('path');
+var package = require('./package.json');
+
+var srcDir = './src/';
+var outDir = './dist/';
+
+var header = "/*!\n\
+ * Chart.Deferred.js\n\
+ * http://chartjs.org/\n\
+ * Version: {{ version }}\n\
+ *\n\
+ * Copyright 2016 Simon Brunel\n\
+ * Released under the MIT license\n\
+ * https://github.com/chartjs/Chart.Deferred.js/blob/master/LICENSE.md\n\
+ */\n";
+
+gulp.task('build', buildTask);
+gulp.task('default', buildTask);
+
+function watch(glob, task) {
+    gutil.log('Waiting for changes...');
+    return gulp.watch(glob, function(e) {
+      gutil.log('Changes detected for', path.relative('.', e.path), '(' + e.type + ')');
+      task();
+      gutil.log('Waiting for changes...');
+    });
+}
+
+function buildTask() {
+  var task = function() {
+    return gulp.src(srcDir + 'chart.deferred.js')
+      .pipe(rename('Chart.Deferred.js'))
+      .pipe(insert.prepend(header))
+      .pipe(streamify(replace('{{ version }}', package.version)))
+      .pipe(gulp.dest(outDir))
+      .pipe(rename('Chart.Deferred.min.js'))
+      .pipe(streamify(uglify({ preserveComments: 'license' })))
+      .pipe(gulp.dest(outDir));
+  };
+
+  if (argv.watch) {
+    return task(), watch(srcDir + '**/*.js', task);
+  } else {
+    return task();
+  }
+}

package.json

@@ -0,0 +1,23 @@
+{
+  "name": "chart.deferred.js",
+  "homepage": "http://www.chartjs.org",
+  "description": "Chart.js plugin to defer initial animation.",
+  "version": "0.1.0",
+  "license": "MIT",
+  "main": "src/plugin.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chartjs/Chart.Deferred.js.git"
+  },
+  "devDependencies": {
+    "gulp": "^3.9.1",
+    "gulp-insert": "^0.5.0",
+    "gulp-replace": "^0.5.4",
+    "gulp-rename": "^1.2.2",
+    "gulp-streamify": "^1.0.2",
+    "gulp-uglify": "^1.5.3",
+    "gulp-util": "^3.0.7",
+    "path": "^0.12.7",
+    "yargs": "^4.7.1"
+  }
+}

src/chart.deferred.js

@@ -0,0 +1,132 @@
+/*global window: false */
+"use strict";
+
+(function() {
+
+	var Chart = window.Chart;
+	var helpers = Chart.helpers;
+
+	/**
+	 * Plugin based on discussion from Chart.js issue #2745.
+	 * @see https://github.com/chartjs/Chart.js/issues/2745
+	 */
+	Chart.Deferred = Chart.Deferred || {};
+	Chart.Deferred.defaults = {
+		enabled: true,
+		xOffset: 0,
+		yOffset: 0,
+		delay: 0
+	};
+
+	// DOM implementation
+	// @todo move it in Chart.js: src/core/core.platform.js
+	Chart.platform = helpers.extend(Chart.platform || {}, {
+		defer: function(fn, delay, scope) {
+			window.setTimeout(function() {
+				fn.call(scope)
+			}, delay);
+		}
+	});
+
+	var deferred_instances = [];
+
+	function computeOffset(value, base) {
+		var number = parseInt(value, 10);
+		if (isNaN(number)) {
+			return 0;
+		} else if (typeof value === 'string' && value.indexOf('%') !== -1) {
+			return number / 100 * base;
+		} else {
+			return number;
+		}
+	}
+
+	function chartInViewport(instance) {
+		var canvas = instance.chart.canvas;
+		var model = instance._deferred_model;
+		var rect = canvas.getBoundingClientRect();
+		var dy = computeOffset(model.yOffset || 0, rect.height);
+		var dx = computeOffset(model.xOffset || 0, rect.width);
+
+		return rect.right - dx >= 0
+			&& rect.bottom - dy >= 0
+			&& rect.left + dx <= window.innerWidth
+			&& rect.top + dy <= window.innerHeight;
+	}
+
+	helpers.addEvent(window, 'scroll', function() {
+		var instances = deferred_instances.slice(0);
+		var ilen = instances.length;
+		var instance, i;
+
+		for (i=0; i<ilen; ++i) {
+			instance = instances[i];
+			if (chartInViewport(instance)) {
+				instance.update();
+			}
+		}
+	});
+
+	function buildDeferredModel(instance) {
+		var defaults = Chart.Deferred.defaults;
+		var options = instance.options.deferred;
+		var getValue = helpers.getValueOrDefault;
+
+		if (options === undefined) {
+			options = {};
+		} else if (typeof options === 'boolean') {
+			// accepting { options: { deferred: true } }
+			options = { enabled: options };
+		}
+
+		return {
+			enabled: getValue(options.enabled, defaults.enabled),
+			xOffset: getValue(options.xOffset, defaults.xOffset),
+			yOffset: getValue(options.yOffset, defaults.yOffset),
+			delay: getValue(options.delay, defaults.delay),
+			delayed: false,
+			loaded: false
+		};
+	}
+
+	Chart.plugins.register({
+		beforeInit: function(instance) {
+			instance._deferred_model = buildDeferredModel(instance);
+			deferred_instances.push(instance);
+		},
+
+		beforeDatasetsUpdate: function(instance) {
+			var model = instance._deferred_model;
+			var index;
+
+			if (!model.loaded) {
+				if (model.enabled && !chartInViewport(instance)) {
+					// cancel the datasets update
+					return false;
+				}
+
+				// avoid extra scroll update by removing the chart from the lazy instances.
+				index = deferred_instances.indexOf(instance);
+				deferred_instances.splice(index, 1);
+				model.loaded = true;
+
+				if (model.delay > 0) {
+					model.delayed = true;
+					Chart.platform.defer(function() {
+						model.delayed = false;
+						instance.update();
+					}, model.delay);
+
+					return false;
+				}
+			}
+
+			if (model.delayed) {
+				// in case of delayed update, ensure to block external requests, such
+				// as interacting with the legend label, or direct calls to update()
+				return false;
+			}
+		}
+	});
+
+})();