unpoly-rails 0.57.0 → 0.60.0

data/lib/assets/javascripts/unpoly/motion.coffee.erb

@@ -29,18 +29,19 @@ and [predefined animations](/up.animate#named-animations).
 You can define custom animations using [`up.transition()`](/up.transition) and
 [`up.animation()`](/up.animation).
 
-@class up.motion
+@module up.motion
 ###
-up.motion = (($) ->
+up.motion = do ->
   
   u = up.util
+  e = up.element
 
   namedAnimations = {}
   defaultNamedAnimations = {}
   namedTransitions = {}
   defaultNamedTransitions = {}
 
-  motionTracker = new up.MotionTracker('motion')
+  motionController = new up.MotionController('motion')
 
   ###**
   Sets default options for animations and transitions.
@@ -65,14 +66,14 @@ up.motion = (($) ->
     that do not support [CSS transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions).
   @stable
   ###
-  config = u.config
+  config = new up.Config
     duration: 300
     delay: 0
     easing: 'ease'
     enabled: true
 
   reset = ->
-    motionTracker.reset()
+    motionController.reset()
     namedAnimations = u.copy(defaultNamedAnimations)
     namedTransitions = u.copy(defaultNamedTransitions)
     config.reset()
@@ -94,7 +95,7 @@ up.motion = (($) ->
 
   \#\#\# Example
 
-      up.animate('.warning', 'fade-in');
+      up.animate('.warning', 'fade-in')
 
   You can pass additional options:
 
@@ -102,7 +103,7 @@ up.motion = (($) ->
         delay: 1000,
         duration: 250,
         easing: 'linear'
-      });
+      })
 
   \#\#\# Named animations
 
@@ -127,9 +128,11 @@ up.motion = (($) ->
   By passing an object instead of an animation name, you can animate
   the CSS properties of the given element:
 
-      var $warning = $('.warning');
-      $warning.css({ opacity: 0 });
-      up.animate($warning, { opacity: 1 });
+      var warning = document.querySelector('.warning')
+      warning.style.opacity = 0
+      up.animate(warning, { opacity: 1 })
+
+  CSS properties must be given in `kebab-case`, not `camelCase`.
 
   \#\#\# Multiple animations on the same element
 
@@ -142,12 +145,12 @@ up.motion = (($) ->
   @function up.animate
   @param {Element|jQuery|string} elementOrSelector
     The element to animate.
-  @param {string|Function|Object} animation
+  @param {string|Function(element, options): Promise|Object} animation
     Can either be:
 
     - The animation's name
     - A function performing the animation
-    - An object of CSS attributes describing the last frame of the animation
+    - An object of CSS attributes describing the last frame of the animation (using kebeb-case property names)
   @param {number} [options.duration=300]
     The duration of the animation, in milliseconds.
   @param {number} [options.delay=0]
@@ -162,27 +165,27 @@ up.motion = (($) ->
   @stable
   ###
   animate = (elementOrSelector, animation, options) ->
-    $element = $(elementOrSelector)
+    element = e.get(elementOrSelector)
     options = animateOptions(options)
 
     animationFn = findAnimationFn(animation)
-    willRun = willAnimate($element, animation, options)
+    willRun = willAnimate(element, animation, options)
 
     if willRun
-      runNow = -> animationFn($element, options)
-      motionTracker.claim($element, runNow, options)
+      runNow = -> animationFn(element, options)
+      motionController.startFunction(element, runNow, options)
     else
-      skipAnimate($element, animation)
+      skipAnimate(element, animation)
 
-  willAnimate = ($elements, animationOrTransition, options) ->
+  willAnimate = (element, animationOrTransition, options) ->
     options = animateOptions(options)
-    isEnabled() && !isNone(animationOrTransition) && options.duration > 0 && !u.isSingletonElement($elements)
+    isEnabled() && !isNone(animationOrTransition) && options.duration > 0 && !e.isSingleton(element)
 
-  skipAnimate = ($element, animation) ->
+  skipAnimate = (element, animation) ->
     if u.isOptions(animation)
       # If we are given the final animation frame as an object of CSS properties,
       # the best we can do is to set the final frame without animation.
-      u.writeInlineStyle($element, animation)
+      e.setStyle(element, animation)
     # Signal that the animation is already done.
     Promise.resolve()
 
@@ -192,7 +195,7 @@ up.motion = (($) ->
   Animates the given element's CSS properties using CSS transitions.
 
   Does not track the animation, nor does it finishes existing animations
-  (use `up.motion.animate()` for that). It does, however, listen to the motionTracker's
+  (use `up.motion.animate()` for that). It does, however, listen to the motionController's
   finish event.
 
   @function animateNow
@@ -212,28 +215,32 @@ up.motion = (($) ->
     A promise that fulfills when the animation ends.
   @internal
   ###
-  animateNow = ($element, lastFrame, options) ->
-    options = u.merge(options, finishEvent: motionTracker.finishEvent)
-    cssTransition = new up.CssTransition($element, lastFrame, options)
+  animateNow = (element, lastFrame, options) ->
+    options = u.merge(options, finishEvent: motionController.finishEvent)
+    cssTransition = new up.CssTransition(element, lastFrame, options)
     return cssTransition.start()
 
   ###**
   Extracts animation-related options from the given options hash.
-  If `$element` is given, also inspects the element for animation-related
+  If `element` is given, also inspects the element for animation-related
   attributes like `up-easing` or `up-duration`.
 
+  @param {Object} userOptions
+  @param {Element|jQuery} [element]
+  @param {Object} [moduleDefaults]
   @function up.motion.animateOptions
   @internal
   ###
   animateOptions = (args...) ->
-    userOptions = args.shift() || {}
-    $element = if u.isJQuery(args[0]) then args.shift() else u.nullJQuery()
-    moduleDefaults = if u.isObject(args[0]) then args.shift() else {}
+    userOptions = args.shift() ? {}
+    moduleDefaults = u.extractOptions(args)
+    element = args.pop() || e.none()
+
     consolidatedOptions = {}
-    consolidatedOptions.easing = u.option(userOptions.easing, u.presentAttr($element, 'up-easing'), moduleDefaults.easing, config.easing)
-    consolidatedOptions.duration = Number(u.option(userOptions.duration, u.presentAttr($element, 'up-duration'), moduleDefaults.duration, config.duration))
-    consolidatedOptions.delay = Number(u.option(userOptions.delay, u.presentAttr($element, 'up-delay'), moduleDefaults.delay, config.delay))
-    consolidatedOptions.trackMotion = userOptions.trackMotion # required by up.MotionTracker
+    consolidatedOptions.easing = userOptions.easing ? element.getAttribute('up-easing') ? moduleDefaults.easing ? config.easing
+    consolidatedOptions.duration = userOptions.duration ? e.numberAttr(element, 'up-duration') ? moduleDefaults.duration ? config.duration
+    consolidatedOptions.delay = userOptions.delay ? e.numberAttr(element, 'up-delay') ? moduleDefaults.delay ? config.delay
+    consolidatedOptions.trackMotion = userOptions.trackMotion # required by up.MotionController
     consolidatedOptions
       
   findNamedAnimation = (name) ->
@@ -247,6 +254,9 @@ up.motion = (($) ->
   are completed.
 
   Animations are completed by jumping to the last animation frame instantly.
+  Promises returned by animation and transition functions instantly settle.
+
+  Emits the `up:motion:finish` event that is already handled by `up.animate()`.
 
   Does nothing if there are no animation to complete.
   
@@ -257,7 +267,21 @@ up.motion = (($) ->
   @stable
   ###
   finish = (elementOrSelector) ->
-    motionTracker.finish(elementOrSelector)
+    motionController.finish(elementOrSelector)
+
+  ###**
+  This event is emitted on an [animating](/up.animating) element by `up.motion.finish()` to
+  request the animation to instantly finish and skip to the last frame.
+
+  Promises returned by completed animation functions are expected to settle.
+
+  Animations started by `up.animate()` already handle this event.
+
+  @event up:motion:finish
+  @param {Element} event.target
+    The animating element.
+  @experimental
+  ###
 
   ###**
   Performs an animated transition between the `source` and `target` elements.
@@ -311,7 +335,7 @@ up.motion = (($) ->
   @function up.morph
   @param {Element|jQuery|string} source
   @param {Element|jQuery|string} target
-  @param {Function|string} transitionOrName
+  @param {Function(oldElement, newElement)|string} transition
   @param {number} [options.duration=300]
     The duration of the animation, in milliseconds.
   @param {number} [options.delay=0]
@@ -325,18 +349,17 @@ up.motion = (($) ->
     Whether to reveal the new element by scrolling its parent viewport.
   @return {Promise}
     A promise that fulfills when the transition ends.
-  @experimental
+  @stable
   ###  
-  morph = (source, target, transitionObject, options) ->
+  morph = (oldElement, newElement, transitionObject, options) ->
     options = u.options(options)
-    options = u.assign(options, animateOptions(options))
+    u.assign(options, animateOptions(options))
 
-    $old = $(source)
-    $new = $(target)
-    $both = $old.add($new)
+    oldElement = e.get(oldElement)
+    newElement = e.get(newElement)
 
     transitionFn = findTransitionFn(transitionObject)
-    willMorph = willAnimate($old, transitionFn, options)
+    willMorph = willAnimate(oldElement, transitionFn, options)
 
     # Remove callbacks from our options hash in case transitionFn calls morph() recursively.
     # If we passed on these callbacks, we might call destructors, events, etc. multiple times.
@@ -348,55 +371,54 @@ up.motion = (($) ->
     beforeStart()
 
     scrollNew = ->
-      # Don't animate the scrolling. The { duration } option was meant for the transition.
-      scrollOptions = u.merge(options, duration: 0)
-      # Scroll $new into position before we start the enter animation.
-      up.layout.scrollAfterInsertFragment($new, scrollOptions)
+      # Don't animate the scrolling.
+      scrollOptions = u.merge(options, behavior: 'instant')
+      # Scroll newElement into position before we start the enter animation.
+      up.viewport.scrollAfterInsertFragment(newElement, scrollOptions)
 
     if willMorph
-      if motionTracker.isActive($old) && options.trackMotion is false
-        return transitionFn($old, $new, options)
+      if motionController.isActive(oldElement) && options.trackMotion is false
+        return transitionFn(oldElement, newElement, options)
 
-      up.puts 'Morphing %o to %o with transition %o', $old.get(0), $new.get(0), transitionObject
+      up.puts 'Morphing %o to %o with transition %o', oldElement, newElement, transitionObject
 
-      $viewport = up.layout.viewportOf($old)
-      scrollTopBeforeReveal = $viewport.scrollTop()
+      viewport = up.viewport.closest(oldElement)
+      scrollTopBeforeReveal = viewport.scrollTop
 
-      oldRemote = up.layout.absolutize $old,
+      oldRemote = up.viewport.absolutize oldElement,
         # Because the insertion will shift elements visually, we must delay insertion
         # until absolutize() has measured the bounding box of the old element.
         afterMeasure: ->
-          $new.insertBefore($old)
+          e.insertBefore(oldElement, newElement)
           afterInsert()
 
       trackable = ->
-        # Scroll $new into position before we start the enter animation.
+        # Scroll newElement into position before we start the enter animation.
         promise = scrollNew()
 
         promise = promise.then ->
-          # Since we have scrolled the viewport (containing both $old and $new),
+          # Since we have scrolled the viewport (containing both oldElement and newElement),
           # we must shift the old copy so it looks like it it is still sitting
           # in the same position.
-          scrollTopAfterReveal = $viewport.scrollTop()
-          oldRemote.moveTop(scrollTopAfterReveal - scrollTopBeforeReveal)
+          scrollTopAfterReveal = viewport.scrollTop
+          oldRemote.moveBounds(0, scrollTopAfterReveal - scrollTopBeforeReveal)
 
-          transitionFn($old, $new, options)
+          transitionFn(oldElement, newElement, options)
 
         promise = promise.then ->
           beforeDetach()
-          $old.detach()
-          oldRemote.$bounds.remove()
+          e.remove(oldRemote.bounds)
           afterDetach()
 
         return promise
 
-      motionTracker.claim($both, trackable, options)
+      motionController.startFunction([oldElement, newElement], trackable, options)
 
     else
       beforeDetach()
       # Swapping the elements directly with replaceWith() will cause
       # jQuery to remove all data attributes, which we use to store destructors
-      swapElementsDirectly($old, $new)
+      swapElementsDirectly(oldElement, newElement)
       afterInsert()
       afterDetach()
       promise = scrollNew()
@@ -425,10 +447,10 @@ up.motion = (($) ->
     else
       oldAnimationFn = findAnimationFn(oldAnimation) || u.asyncNoop
       newAnimationFn = findAnimationFn(newAnimation) || u.asyncNoop
-      ($old, $new, options) ->
+      (oldElement, newElement, options) ->
         Promise.all([
-          oldAnimationFn($old, options),
-          newAnimationFn($new, options)
+          oldAnimationFn(oldElement, options),
+          newAnimationFn(newElement, options)
         ])
 
   findAnimationFn = (object) ->
@@ -439,25 +461,26 @@ up.motion = (($) ->
     else if u.isString(object)
       findNamedAnimation(object)
     else if u.isOptions(object)
-      ($element, options) -> animateNow($element, object, options)
+      (element, options) -> animateNow(element, object, options)
     else
       up.fail('Unknown animation %o', object)
 
-  swapElementsDirectly = ($old, $new) ->
-    # jQuery will actually let us .insertBefore the new <body> tag,
-    # but that's probably bad Karma.
-     $old.replaceWith($new)
+  # Have a separate function so we can mock it in specs.
+  swapElementsDirectly = (oldElement, newElement) ->
+     e.replace(oldElement, newElement)
 
   ###**
-  Defines a named transition.
+  Defines a named transition that [morphs](/up.element) from one element to another.
+
+  \#\#\# Example
 
   Here is the definition of the pre-defined `cross-fade` animation:
 
-      up.transition('cross-fade', ($old, $new, options) ->
-        up.motion.when(
-          up.animate($old, 'fade-out', options),
-          up.animate($new, 'fade-in', options)
-        )
+      up.transition('cross-fade', (oldElement, newElement, options) ->
+        Promise.all([
+          up.animate(oldElement, 'fade-out', options),
+          up.animate(newElement, 'fade-in', options)
+        ])
       )
 
   It is recommended that your transitions use [`up.animate()`](/up.animate),
@@ -466,11 +489,11 @@ up.motion = (($) ->
   If you choose to *not* use `up.animate()` and roll your own
   logic instead, your code must honor the following contract:
 
-  1. It must honor the options `{ delay, duration, easing }` if given
+  1. It must honor the options `{ delay, duration, easing }` if given.
   2. It must *not* remove any of the given elements from the DOM.
-  3. It returns a promise that is fulfilled when the transition has ended
+  3. It returns a promise that is fulfilled when the transition has ended.
   4. If during the animation an event `up:motion:finish` is emitted on
-     the given element, the transition instantly jumps to the last frame
+     either element, the transition instantly jumps to the last frame
      and resolves the returned promise.
 
   Calling [`up.animate()`](/up.animate) with an object argument
@@ -478,7 +501,7 @@ up.motion = (($) ->
 
   @function up.transition
   @param {string} name
-  @param {Function} transition
+  @param {Function(oldElement, newElement, options): Promise|Array} transition
   @stable
   ###
   registerTransition = (name, transition) ->
@@ -489,9 +512,9 @@ up.motion = (($) ->
 
   Here is the definition of the pre-defined `fade-in` animation:
 
-      up.animation('fade-in', function($element, options) {
-        $element.css(opacity: 0);
-        up.animate($element, { opacity: 1 }, options);
+      up.animation('fade-in', function(element, options) {
+        element.style.opacity = 0
+        up.animate(element, { opacity: 1 }, options)
       })
 
   It is recommended that your definitions always end by calling
@@ -513,7 +536,7 @@ up.motion = (($) ->
 
   @function up.animation
   @param {string} name
-  @param {Function} animation
+  @param {Function(element, options): Promise} animation
   @stable
   ###
   registerAnimation = (name, animation) ->
@@ -534,86 +557,86 @@ up.motion = (($) ->
     # false, undefined, '', null and the string "none" are all ways to skip animations
     !animationOrTransition || animationOrTransition == 'none' || u.isBlank(animationOrTransition)
 
-  registerAnimation('fade-in', ($element, options) ->
-    u.writeInlineStyle($element, opacity: 0)
-    animateNow($element, { opacity: 1 }, options)
+  registerAnimation('fade-in', (element, options) ->
+    e.setStyle(element, opacity: 0)
+    animateNow(element, { opacity: 1 }, options)
   )
 
-  registerAnimation('fade-out', ($element, options) ->
-    u.writeInlineStyle($element, opacity: 1)
-    animateNow($element, { opacity: 0 }, options)
+  registerAnimation('fade-out', (element, options) ->
+    e.setStyle(element, opacity: 1)
+    animateNow(element, { opacity: 0 }, options)
   )
 
   translateCss = (x, y) ->
     { transform: "translate(#{x}px, #{y}px)" }
 
-  registerAnimation('move-to-top', ($element, options) ->
-    u.writeInlineStyle($element, translateCss(0, 0))
-    box = u.measure($element)
+  registerAnimation('move-to-top', (element, options) ->
+    e.setStyle(element, translateCss(0, 0))
+    box = element.getBoundingClientRect()
     travelDistance = box.top + box.height
-    animateNow($element, translateCss(0, -travelDistance), options)
+    animateNow(element, translateCss(0, -travelDistance), options)
   )
 
-  registerAnimation('move-from-top', ($element, options) ->
-    u.writeInlineStyle($element, translateCss(0, 0))
-    box = u.measure($element)
+  registerAnimation('move-from-top', (element, options) ->
+    e.setStyle(element, translateCss(0, 0))
+    box = element.getBoundingClientRect()
     travelDistance = box.top + box.height
-    u.writeInlineStyle($element, translateCss(0, -travelDistance))
-    animateNow($element, translateCss(0, 0), options)
+    e.setStyle(element, translateCss(0, -travelDistance))
+    animateNow(element, translateCss(0, 0), options)
   )
 
-  registerAnimation('move-to-bottom', ($element, options) ->
-    u.writeInlineStyle($element, translateCss(0, 0))
-    box = u.measure($element)
-    travelDistance = u.clientSize().height - box.top
-    animateNow($element, translateCss(0, travelDistance), options)
+  registerAnimation('move-to-bottom', (element, options) ->
+    e.setStyle(element, translateCss(0, 0))
+    box = element.getBoundingClientRect()
+    travelDistance = e.root().clientHeight - box.top
+    animateNow(element, translateCss(0, travelDistance), options)
   )
 
-  registerAnimation('move-from-bottom', ($element, options) ->
-    u.writeInlineStyle($element, translateCss(0, 0))
-    box = u.measure($element)
-    travelDistance = u.clientSize().height - box.top
-    u.writeInlineStyle($element, translateCss(0, travelDistance))
-    animateNow($element, translateCss(0, 0), options)
+  registerAnimation('move-from-bottom', (element, options) ->
+    e.setStyle(element, translateCss(0, 0))
+    box = element.getBoundingClientRect()
+    travelDistance = up.viewport.rootHeight() - box.top
+    e.setStyle(element, translateCss(0, travelDistance))
+    animateNow(element, translateCss(0, 0), options)
   )
 
-  registerAnimation('move-to-left', ($element, options) ->
-    u.writeInlineStyle($element, translateCss(0, 0))
-    box = u.measure($element)
+  registerAnimation('move-to-left', (element, options) ->
+    e.setStyle(element, translateCss(0, 0))
+    box = element.getBoundingClientRect()
     travelDistance = box.left + box.width
-    animateNow($element, translateCss(-travelDistance, 0), options)
+    animateNow(element, translateCss(-travelDistance, 0), options)
   )
 
-  registerAnimation('move-from-left', ($element, options) ->
-    u.writeInlineStyle($element, translateCss(0, 0))
-    box = u.measure($element)
+  registerAnimation('move-from-left', (element, options) ->
+    e.setStyle(element, translateCss(0, 0))
+    box = element.getBoundingClientRect()
     travelDistance = box.left + box.width
-    u.writeInlineStyle($element, translateCss(-travelDistance, 0))
-    animateNow($element, translateCss(0, 0), options)
+    e.setStyle(element, translateCss(-travelDistance, 0))
+    animateNow(element, translateCss(0, 0), options)
   )
 
-  registerAnimation('move-to-right', ($element, options) ->
-    u.writeInlineStyle($element, translateCss(0, 0))
-    box = u.measure($element)
-    travelDistance = u.clientSize().width - box.left
-    animateNow($element, translateCss(travelDistance, 0), options)
+  registerAnimation('move-to-right', (element, options) ->
+    e.setStyle(element, translateCss(0, 0))
+    box = element.getBoundingClientRect()
+    travelDistance = up.viewport.rootWidth() - box.left
+    animateNow(element, translateCss(travelDistance, 0), options)
   )
 
-  registerAnimation('move-from-right', ($element, options) ->
-    u.writeInlineStyle($element, translateCss(0, 0))
-    box = u.measure($element)
-    travelDistance = u.clientSize().width - box.left
-    u.writeInlineStyle($element, translateCss(travelDistance, 0))
-    animateNow($element, translateCss(0, 0), options)
+  registerAnimation('move-from-right', (element, options) ->
+    e.setStyle(element, translateCss(0, 0))
+    box = element.getBoundingClientRect()
+    travelDistance = up.viewport.rootWidth() - box.left
+    e.setStyle(element, translateCss(travelDistance, 0))
+    animateNow(element, translateCss(0, 0), options)
   )
 
-  registerAnimation('roll-down', ($element, options) ->
-    fullHeight = $element.height()
-    styleMemo = u.writeTemporaryStyle($element,
+  registerAnimation('roll-down', (element, options) ->
+    previousHeightStr = e.style(element, 'height')
+    styleMemo = e.setTemporaryStyle(element,
       height: '0px'
       overflow: 'hidden'
     )
-    deferred = animate($element, { height: "#{fullHeight}px" }, options)
+    deferred = animate(element, { height: previousHeightStr }, options)
     deferred.then(styleMemo)
     deferred
   )
@@ -631,17 +654,14 @@ up.motion = (($) ->
   morph: morph
   animate: animate
   animateOptions: animateOptions
-  willAnimate: willAnimate
   finish: finish
-  finishCount: -> motionTracker.finishCount
+  finishCount: -> motionController.finishCount
   transition: registerTransition
   animation: registerAnimation
   config: config
   isEnabled: isEnabled
   isNone: isNone
 
-)(jQuery)
-
 up.transition = up.motion.transition
 up.animation = up.motion.animation
 up.morph = up.motion.morph