jquery.keyframeanimation.js

;(function($, window, undefined) {
	

	$.fn.keyframeAnimation = function(propertyOrSettings/* [, ...] */) {
		if($.fn.keyframeAnimation[propertyOrSettings]) {
			var property = $.fn.keyframeAnimation[propertyOrSettings];

			if(property.apply) {
				return property.apply(this, Array.prototype.slice.call(arguments, 1));
			} else {
				return property;
			}
		} else {
			return $.fn.keyframeAnimation.initialize.apply(this, arguments);
		}
	};
	
	
	$.fn.keyframeAnimation.version = '0.3.5';
	
	

	$.fn.keyframeAnimation.initialize = function(settings) {

		var defaultSettings = {
			keyframes: {},
			delays: [],
			animationDuration: 0,
			animationIterationCount: 1,
			animationTimingFunction: 'ease'
		};
		settings = $.extend({}, defaultSettings, settings);
		
		var elements = this;
		

		if(elements.data('keyframeAnimation') === undefined) {
			elements.data('keyframeAnimation', {});
		}
		

		var orderedKeyframePercentages = (Object.keys ?
			Object.keys(settings.keyframes) :
			$.map(settings.keyframes, function(styles, percentage) { return percentage; })
		).sort();
		
		var currentIteration = 0;

		var iterateAnimation = function() {
			currentIteration++;
			

			if(settings.animationIterationCount === 'infinite' || currentIteration <= settings.animationIterationCount) {
				elements.data('keyframeAnimation').timeouts = [];
				

				elements.each(animateElement);
				elements.data('keyframeAnimation').timeouts.push(window.setTimeout(iterateAnimation, settings.animationDuration));
			} else {

				delete elements.data('keyframeAnimation').timeouts;
			}
		};
		

		var animateElement = function(elementIndex, element) {
			var elementDelay = settings.delays[elementIndex] || 0;
			

			$.each(orderedKeyframePercentages, function(keyframeIndex, percentage) {
				var styles = settings.keyframes[percentage];
				

				/* TODO: Move this out of the loop so it only needs to be 
				   computed once (or memoize). */
				var percentageBetweenKeyframes, keyframeOffset;
				if(percentage != 0) {

					percentageBetweenKeyframes = (percentage - orderedKeyframePercentages[keyframeIndex - 1]);
					

					keyframeOffset = settings.animationDuration * orderedKeyframePercentages[keyframeIndex - 1];
				} else {

					percentageBetweenKeyframes = 0;
					keyframeOffset = 0;
				}
				

				var interpolationDuration = settings.animationDuration * percentageBetweenKeyframes;
				

				elements.data('keyframeAnimation').timeouts.push(window.setTimeout(function() {

					/* FIXME? Will calling `.stop()` thwart attempts to 
					   resolve the "skipped styles" bug? (Since the 
					   solution to that will probably need multiple 
					   simultaneous animations.) Maybe there should be 
					   one queue per keyframe? */
					$(element).stop('keyframeAnimation', false, true).animate(styles, {
						duration: interpolationDuration, 
						queue: 'keyframeAnimation',
						easing: getEasingFunction(settings.animationTimingFunction)
					}).dequeue('keyframeAnimation');
				}, keyframeOffset + elementDelay));
			});
		};
		

		iterateAnimation();
		

		return this;
	};
	
	

	$.fn.keyframeAnimation.abort = function() {
		if(this.data('keyframeAnimation').timeouts) {
			$.each(this.data('keyframeAnimation').timeouts, function(index, timeoutID) {
				window.clearTimeout(timeoutID);
			});
			delete this.data('keyframeAnimation').timeouts;
		}
		

		return this;
	};
	
	

	var cubicBezierTimingFunctionPoints = {
		ease: [
			{ x: 0.25, y: 0.1 },
			{ x: 0.25, y: 1 }
		],
		linear: [
			{ x: 0, y: 0 },
			{ x: 1, y: 1 }
		],
		easeIn: [
			{ x: 0.42, y: 0 },
			{ x: 1, y: 1 }
		],
		easeOut: [
			{ x: 0, y: 0 },
			{ x: 0.58, y: 1 }
		],
		easeInOut: [
			{ x: 0.42, y: 0 },
			{ x: 0.58, y: 1 }
		]
	};
	
	

	/* FIXME? Is the extra complexity of creating these on-the-fly worth the 
	   small performance savings and the smaller `$.easing` namespace 
	   footprint? Since `$.easing` is externally-visible, will it be 
	   confusing to not always have all css* easing functions present? 
	   Something like this would definitely still be necessary for custom 
	   timing functions (e.g. 'cubic-bezier(x1, y1, x2, y2)'). */
	var getEasingFunction = function(timingFunctionName) {

		var easingName = 'css' + timingFunctionName.charAt(0).toUpperCase() + timingFunctionName.slice(1);
		
		if($.easing[easingName] === undefined) {

			var points = cubicBezierTimingFunctionPoints[timingFunctionName];
			$.easing[easingName] = function(percentComplete, millisecondsSince, startValue, endValue, totalDuration) {
				var totalDurationSeconds = totalDuration / 1000;
				return cubicBezierAtTime(percentComplete, points[0].x, points[0].y, points[1].x, points[1].y, totalDurationSeconds);
			};
		}
		
		return easingName;
	};
	
	

	/* TODO: more descriptive variable names. */
	var cubicBezierAtTime = function(t, p1x, p1y, p2x, p2y, duration) {

		var cx = 3 * p1x;
		var bx = 3 * (p2x - p1x) - cx;
		var ax = 1 - cx - bx;
		var cy = 3 * p1y;
		var by = 3 * (p2y - p1y) - cy;
		var ay = 1 - cy - by;
		

		var sampleCurveX = function(t) {
			return ((ax * t + bx) * t + cx) * t;
		};
		var sampleCurveY = function(t) {
			return ((ay * t + by) * t + cy) * t;
		};
		var sampleCurveDerivativeX = function(t) {
			return (3 * ax * t + 2 * bx) * t + cx;
		};
		

		var solveCurveX = function(x, epsilon) {
			var t0, t1, t2, x2, d2, i;
			

			for(t2 = x, i = 0; i < 8; i++) {
				x2 = sampleCurveX(t2) - x;
				if(Math.abs(x2) < epsilon) {
					return t2;
				}
				d2 = sampleCurveDerivativeX(t2);
				if(Math.abs(d2) < 1e-6) {
					break;
				}
				t2 = t2 - x2 / d2;
			}
			

			t0 = 0;
			t1 = 1;
			t2 = x;
			if(t2 < t0) {
				return t0;
			}
			if(t2 > t1) {
				return t1;
			}
			while(t0 < t1) {
				x2 = sampleCurveX(t2);
				if(Math.abs(x2 - x) < epsilon) {
					return t2;
				}
				if(x > x2) {
					t0 = t2;
				} else {
					t1 = t2;
				}
				t2 = (t1 - t0) * 0.5 + t0;
			}
			return t2; // Failure. /* FIXME: What does this imply? */
		};
		

		var epsilon = 1 / (200 * duration);
		

		return sampleCurveY(solveCurveX(t, epsilon));
	};
	
}(jQuery, window));