morpheus: A JavaScript repository from cjc

_  _ ____ ____ ___  _  _ ____ _  _ ____
|\/| |  | |__/ |__] |__| |___ |  | [__
|  | |__| |  \ |    |  | |___ |__| ___]

A Brilliant Animator.

Morpheus lets you "tween anything" in parallel on multiple elements; from colors to integers of any unit (px, em, %, etc), with easing transitions and bezier curves -- all in a single high-performant loop utilizing the CPU-friendly requestAnimationFrame standard.

It looks like this:

morpheus(elements, {
  // CSS
  left: -50,
  top: 100,
  width: '+=50',
  height: '-=50px',
  fontSize: '30px',
  color: '#f00',
  "background-color": '#f00',

  // API
  duration: 500,
  easing: easings.easeOut,
  bezier: [[100, 200], [200, 100]],
  complete: function () {
    console.log('done');
  }
})

General Tweening

morpheus.tween(1000,
  function (position) {
    // do stuff with position...
    // like for example, use bezier curve points :)
    var xy = morpheus.bezier([[startX, startY], <[n control points]>, [endX, endY]], position)
  },
  function () {
    console.log('done');
  },
  easings.bounce,
  100, // start
  300 // end
)

API

/**
  * morpheus:
  * @param element(s): HTMLElement(s)
  * @param options: mixed bag between CSS Style properties & animation options
  *  - {n} CSS properties|values
  *     - value can be strings, integers,
  *     - or callback function that receives element to be animated. method must return value to be tweened
  *     - relative animations start with += or -= followed by integer
  *  - duration: time in ms - defaults to 1000(ms)
  *  - easing: a transition method - defaults to an 'easeOut' algorithm
  *  - complete: a callback method for when all elements have finished
  *  - bezier: array of arrays containing x|y coordinates that define the bezier points. defaults to none
  *     - this may also be a function that receives element to be animated. it must return a value
  */

See the live examples

Language LTR - RTL support

For those who run web services that support languages spanning from LTR to RTL, you can use the drop-in plugin filed called rtltr.js found in the src directory which will automatically mirror all animations without having to change your implementation. It's pretty rad.

Browser support

Grade A & C Browsers according to Yahoo's Graded Browser Support

Ender integration

Got Ender? No? Get it.

$ npm install ender -g

Add Morpheus to your existing Ender build

$ ender add morpheus

Write code like a boss:

$('#content .boosh').animate({
  left: 911,
  complete: function () {
    console.log('boosh');
  }
});

Usage Notes

Color

If you're serious about *color animation*, there's a few precautions you'll need to take ahead of time. In order to morph *from* one color to another, you need to make sure the elements you're animating *have an inherited color style* to start with. Furthermore, those styles need to be represented in rgb, or hex, and not a named color (like red, or orange) -- that is unless you want to write code to map the [color conversion](http://www.w3schools.com/css/css_colornames.asp) yourself.

Therefore, at minimum, you need to set a color before animating.

element.style.color = '#ff0';
morpheus(element, {
  color: '#000'
})

With Bonzo installed in Ender.

$('div.things').css('color', '#ff0').animate({
  color: '#000'
})

Units

If you're considering animating by a CSS unit of measurement like em, pt, or %, like-wise to color animation, you must set the size ahead of time before animating:

$('div.intro')
  .css({
    fontSize: '2em',
    width: '50%'
  })
  .animate({
    fontSize: '+=1.5em',
    width: '100%'
  })

Transforms

Transforms can be animated in browsers that support them (IE9, FF, Chrome, Safari, Opera). morpheus.transform provides a shortcut to the correct style property for the browser (webkitTransform, MozTransform, etc). Like animating on units or color, you must set the property ahead of time before animating:

element.style[morpheus.transform] = 'rotate(30deg) scale(1)';
morpheus(element, {
  transform: 'rotate(0deg) scale(+=3)'
});

Morpheus (c) Dustin Diaz 2011 - License MIT

Happy Morphing!

cjc/morpheus