upjs-rails 0.1.0 → 0.2.0

data/lib/assets/javascripts/up/motion.js.coffee

@@ -1,19 +1,25 @@
 ###*
-Animation and transition effects.
+Animation and transitions
+=========================
+  
+TODO: Write some documentation.
   
 @class up.motion
 ###
 up.motion = (->
   
+  u = up.util
+  
   defaultOptions =
     duration: 300
+    delay: 0
     easing: 'ease'
 
   animations = {}
+  defaultAnimations = {}
   transitions = {}
-  
-  cssAnimate = up.util.cssAnimate
-  
+  defaultTransitions = {}
+
   ###*
   Animates an element.
   
@@ -33,52 +39,56 @@ up.motion = (->
   
   @method up.animate
   @param {Element|jQuery|String} elementOrSelector
-  @param {String|Function} animationOrName
+  @param {String|Function|Object} animation
   @param {Number} [options.duration]
   @param {String} [options.easing]
+  @param {Number} [options.delay]
   @return {Promise}
     A promise for the animation's end.
   ###
-  animate = (elementOrSelector, animationOrName, options) ->
+  animate = (elementOrSelector, animation, options) ->
     $element = $(elementOrSelector)
-    console.log("animating with", animationOrName)
-    options = up.util.options(options, defaultOptions)
-    anim = if up.util.isFunction(animationOrName)
-      animationOrName
+    options = u.options(options, defaultOptions)
+    if u.isFunction(animation)
+      assertIsPromise(
+        animation($element, options),
+        ["Animation did not return a Promise", animation]
+      )
+    else if u.isString(animation)
+      animate($element, findAnimation(animation), options)
+    else if u.isHash(animation)
+      u.cssAnimate($element, animation, options)
     else
-      animations[animationOrName] or up.util.error("Unknown animation", animationName)
-    assertIsPromise(
-      anim($element, options),
-      ["Animation did not return a Promise", animationOrName]
-    )
+      u.error("Unknown animation type", animation)
+      
+  findAnimation = (name) ->
+    animations[name] or u.error("Unknown animation", animation)
 
   withGhosts = ($old, $new, block) ->
     $oldGhost = null
     $newGhost = null
-    up.util.temporaryCss $new, display: 'none', ->
-      $oldGhost = up.util.prependGhost($old)
-    up.util.temporaryCss $old, display: 'none', ->
-      $newGhost = up.util.prependGhost($new)
+    u.temporaryCss $new, display: 'none', ->
+      $oldGhost = u.prependGhost($old).addClass('up-destroying')
+    u.temporaryCss $old, display: 'none', ->
+      $newGhost = u.prependGhost($new)
     # $old should take up space in the page flow until the transition ends
     $old.css(visibility: 'hidden')
-    newCssMemo = up.util.temporaryCss($new, display: 'none')
+    
+    newCssMemo = u.temporaryCss($new, display: 'none')
     promise = block($oldGhost, $newGhost)
     promise.then ->
       $oldGhost.remove()
       $newGhost.remove()
       # Now that the transition is over we show $new again.
-      # Since we expect $old to be removed in a heartblink,
+      # Since we expect $old to be removed in a heartbeat,
       # $new should take up space
       $old.css(display: 'none')
       newCssMemo()
       
   assertIsPromise = (object, messageParts) ->
-    up.util.isPromise(object) or up.util.error(messageParts...)
+    u.isPromise(object) or u.error(messageParts...)
     object
 
-
-    
-
   ###*
   Performs a transition between two elements.
   
@@ -103,14 +113,15 @@ up.motion = (->
   @param {Function|String} transitionOrName
   @param {Number} [options.duration]
   @param {String} [options.easing]
+  @param {Number} [options.delay]
   @return {Promise}
     A promise for the transition's end.
   ###  
   morph = (source, target, transitionOrName, options) ->
-    options = up.util.options(defaultOptions)
+    options = u.options(defaultOptions)
     $old = $(source)
     $new = $(target)
-    transition = up.util.presence(transitionOrName, up.util.isFunction) || transitions[transitionOrName]
+    transition = u.presence(transitionOrName, u.isFunction) || transitions[transitionOrName]
     if transition
       withGhosts $old, $new, ($oldGhost, $newGhost) ->
         assertIsPromise(
@@ -120,7 +131,7 @@ up.motion = (->
     else if animation = animations[transitionOrName]
       $old.hide()
       animate($new, animation, options)
-    else if up.util.isString(transitionOrName) && transitionOrName.indexOf('/') >= 0
+    else if u.isString(transitionOrName) && transitionOrName.indexOf('/') >= 0
       parts = transitionOrName.split('/')
       transition = ($old, $new, options) ->
         $.when(
@@ -129,7 +140,7 @@ up.motion = (->
         )
       morph($old, $new, transition, options)
     else
-      up.util.error("Unknown transition: #{transitionOrName}")
+      u.error("Unknown transition: #{transitionOrName}")
 
   ###*
   Defines a named transition.
@@ -150,6 +161,14 @@ up.motion = (->
   ###
   animation = (name, animation) ->
     animations[name] = animation
+    
+  snapshot = ->
+    defaultAnimations = u.copy(animations)
+    defaultTransitions = u.copy(transitions)
+    
+  reset = ->
+    animations = u.copy(defaultAnimations)
+    transitions = u.copy(defaultTransitions)
   
   ###*
   Returns a no-op animation or transition which has no visual effects
@@ -168,61 +187,61 @@ up.motion = (->
 
   animation('fade-in', ($ghost, options) ->
     $ghost.css(opacity: 0)
-    cssAnimate($ghost, { opacity: 1 }, options)
+    animate($ghost, { opacity: 1 }, options)
   )
   
   animation('fade-out', ($ghost, options) ->
     $ghost.css(opacity: 1)
-    cssAnimate($ghost, { opacity: 0 }, options)
+    animate($ghost, { opacity: 0 }, options)
   )
   
   animation('move-to-top', ($ghost, options) ->
     $ghost.css('margin-top': '0%')
-    cssAnimate($ghost, { 'margin-top': '-100%' }, options)
+    animate($ghost, { 'margin-top': '-100%' }, options)
   )
   
   animation('move-from-top', ($ghost, options) ->
     $ghost.css('margin-top': '-100%')
-    cssAnimate($ghost, { 'margin-top': '0%' }, options)
+    animate($ghost, { 'margin-top': '0%' }, options)
   )
     
   animation('move-to-bottom', ($ghost, options) ->
     $ghost.css('margin-top': '0%')
-    cssAnimate($ghost, { 'margin-top': '100%' }, options)
+    animate($ghost, { 'margin-top': '100%' }, options)
   )
   
   animation('move-from-bottom', ($ghost, options) ->
     $ghost.css('margin-top': '100%')
-    cssAnimate($ghost, { 'margin-top': '0%' }, options)
+    animate($ghost, { 'margin-top': '0%' }, options)
   )
   
   animation('move-to-left', ($ghost, options) ->
     $ghost.css('margin-left': '0%')
-    cssAnimate($ghost, { 'margin-left': '-100%' }, options)
+    animate($ghost, { 'margin-left': '-100%' }, options)
   )
   
   animation('move-from-left', ($ghost, options) ->
     $ghost.css('margin-left': '-100%')
-    cssAnimate($ghost, { 'margin-left': '0%' }, options)
+    animate($ghost, { 'margin-left': '0%' }, options)
   )
   
   animation('move-to-right', ($ghost, options) ->
     $ghost.css('margin-left': '0%')
-    cssAnimate($ghost, { 'margin-left': '100%' }, options)
+    animate($ghost, { 'margin-left': '100%' }, options)
   )
   
   animation('move-from-right', ($ghost, options) ->
     $ghost.css('margin-left': '100%')
-    cssAnimate($ghost, { 'margin-left': '0%' }, options)
+    animate($ghost, { 'margin-left': '0%' }, options)
   )
   
   animation('roll-down', ($ghost, options) ->
     fullHeight = $ghost.height()
-    styleMemo = up.util.temporaryCss($ghost,
+    styleMemo = u.temporaryCss($ghost,
       height: '0px'
       overflow: 'hidden'
     )
-    cssAnimate($ghost, { height: "#{fullHeight}px" }, options).then(styleMemo)
+    animate($ghost, { height: "#{fullHeight}px" }, options).then(styleMemo)
   )
   
   transition('none', none)
@@ -241,14 +260,14 @@ up.motion = (->
     )
   )
   
-  transition('move-top', ($old, $new, options) ->
+  transition('move-up', ($old, $new, options) ->
     $.when(
       animate($old, 'move-to-top', options),
       animate($new, 'move-from-bottom', options)
     )
   )
   
-  transition('move-bottom', ($old, $new, options) ->
+  transition('move-down', ($old, $new, options) ->
     $.when(
       animate($old, 'move-to-bottom', options),
       animate($new, 'move-from-top', options)
@@ -261,6 +280,9 @@ up.motion = (->
       animate($new, 'fade-in', options)
     )
   )
+
+  up.bus.on 'framework:ready', snapshot
+  up.bus.on 'framework:reset', reset
     
   morph: morph
   animate: animate

data/lib/assets/javascripts/up/navigation.js.coffee

@@ -1,15 +1,27 @@
 ###*
+Fast interaction feedback
+=========================
+  
 This module marks up link elements with classes indicating that
 they are currently loading (class `up-active`) or linking
 to the current location (class `up-current`).
-  
-The current location is either:
+
+This dramatically improves the perceived speed of your user interface
+by providing instant feedback for user interactions.
+
+The classes are added and removed automatically whenever
+a page fragment is added, changed or destroyed through Up.js.
+
+How Up.js computes the current location
+---------------------------------------
+
+From Up's point of view the "current" location is either:
   
 - the URL displayed in the browser window's location bar
-- the source URL of a currently opened {{#crossLink "up.modal"}}modal dialog{{/crossLink}} 
-- the source URL of a currently opened {{#crossLink "up.popup"}}popup overlay{{/crossLink}} 
-  
-@class up.navigation  
+- the source URL of a currently opened [modal dialog](/up.modal)
+- the source URL of a currently opened [popup overlay](/up.popup)
+
+@class up.navigation
 ###
 up.navigation = (->
 
@@ -19,7 +31,7 @@ up.navigation = (->
   SELECTOR_ACTIVE = ".#{CLASS_ACTIVE}"
 
   locationChanged = ->
-    windowLocation = up.util.normalizeUrl(location.href, search: false)
+    windowLocation = up.util.normalizeUrl(up.browser.url(), search: false)
     modalLocation = up.modal.source()
     popupLocation = up.popup.source()
     
@@ -48,15 +60,21 @@ up.navigation = (->
   up.on 'click', SELECTOR_SECTION, (event, $section) ->
     sectionClicked($section)
 
-  # If a new fragment is inserted, it's likely to be the result
-  # to the active action. So we can remove the active marker.
+  # When a fragment is ready it might either have brought a location change
+  # with it, or it might have opened a modal / popup which we consider
+  # to be secondary location sources (the primary being the browser's
+  # location bar.
   up.bus.on 'fragment:ready', ->
     unmarkActive()
+    # If a new fragment is inserted, it's likely to be the result
+    # to the active action. So we can remove the active marker.
     locationChanged()
 
-  # If the destroyed fragment is a modal or popup container
-  # this changes which URLs we consider currents.
   up.bus.on 'fragment:destroy', ($fragment) ->
+    # If the destroyed fragment is a modal or popup container
+    # this changes which URLs we consider currents.
+    # Also modals and popups restore their previous history
+    # once they close.
     if $fragment.is('.up-modal, .up-popup')
       locationChanged()
 

data/lib/assets/javascripts/up/popup.js.coffee

@@ -1,14 +1,30 @@
 ###*
-Pop-up overlays.
+Pop-up overlays
+===============
   
-For modal dialogs see {{#crossLink "up.modal"}}{{/crossLink}}.
+For modal dialogs see [up.modal](/up.modal).
   
-@class up.popup 
+@class up.popup
 ###
 up.popup = (->
+
+  u = up.util
+
+  config =
+    openAnimation: 'fade-in'
+    closeAnimation: 'fade-out'
+    origin: 'bottom-right'    
+
+  ###*
+  @method up.popup.defaults
+  @param {String} options.animation
+  @param {String} options.origin
+  ###
+  defaults = (options) ->
+    u.extend(config, options)
   
   position = ($link, $popup, origin) ->
-    linkBox = up.util.measure($link, full: true)
+    linkBox = u.measure($link, full: true)
     css = switch origin
       when "bottom-right"
         right: linkBox.right
@@ -23,16 +39,45 @@ up.popup = (->
         left: linkBox.left
         bottom: linkBox.top
       else
-        up.util.error("Unknown origin", origin)
-#    for key, value of css
-#      css[key] = Math.max(value, 0)
+        u.error("Unknown origin", origin)
+    $popup.attr('up-origin', origin)
     $popup.css(css)
+    ensureInViewport($popup)
+
+  ensureInViewport = ($popup) ->
+    box = u.measure($popup, full: true)
+    errorX = null
+    errorY = null
+    if box.right < 0
+      errorX = -box.right  # errorX is positive
+    if box.bottom < 0
+      errorY = -box.bottom # errorY is positive
+    if box.left < 0
+      errorX = box.left # errorX is negative
+    if box.top < 0
+      errorY = box.top # errorY is negative
+    if errorX
+      # We use parseInt to:
+      # 1) convert "50px" to 50
+      # 2) convert "auto" to NaN
+      if left = parseInt($popup.css('left'))
+        $popup.css('left', left - errorX)
+      else if right = parseInt($popup.css('right'))
+        $popup.css('right', right + errorX)
+    if errorY
+      if top = parseInt($popup.css('top'))
+        $popup.css('top', top - errorY)
+      else if bottom = parseInt($popup.css('bottom'))
+        $popup.css('bottom', bottom + errorY)
+    
     
   createHiddenPopup = ($link, selector, sticky) ->
-    $popup = up.util.$createElementFromSelector('.up-popup')
+    $popup = u.$createElementFromSelector('.up-popup')
     $popup.attr('up-sticky', '') if sticky
-    $content = up.util.$createElementFromSelector(selector)
-    $content.appendTo($popup)
+    $popup.attr('up-previous-url', up.browser.url())
+    $popup.attr('up-previous-title', document.title)
+    $placeholder = u.$createElementFromSelector(selector)
+    $placeholder.appendTo($popup)
     $popup.appendTo(document.body)
     $popup.hide()
     $popup
@@ -53,20 +98,17 @@ up.popup = (->
     If set to `true`, the popup remains
     open even if the page changes in the background.
   @param {Object} [options.history=false]
-  @example
-      <a href="/decks" up-popup=".deck_list">Switch deck</a>
-  @example
-      <a href="/settings" up-popup=".options" up-popup-sticky>Settings</a>  
   ###
-  open = (linkOrSelector, options = {}) ->
+  open = (linkOrSelector, options) ->
     $link = $(linkOrSelector)
 
-    url = up.util.presentAttr($link, 'href')
-    selector = options.target || $link.attr('up-popup') || 'body'
-    origin = options.origin || $link.attr('up-origin') || 'bottom-right'
-    animation = options.animation || $link.attr('up-animation') || 'roll-down'
-    sticky = options.sticky || $link.is('[up-sticky]')
-    history = options.history || false
+    options = u.options(options)
+    url = u.option($link.attr('href'))
+    selector = u.option(options.target, $link.attr('up-popup'), 'body')
+    origin = u.option(options.origin, $link.attr('up-origin'), config.origin)
+    animation = u.option(options.animation, $link.attr('up-animation'), config.openAnimation)
+    sticky = u.option(options.sticky, $link.is('[up-sticky]'))
+    history = u.option(options.history, $link.attr('up-history'), false)
 
     close()
     $popup = createHiddenPopup($link, selector, sticky)
@@ -75,7 +117,7 @@ up.popup = (->
     
     up.replace(selector, url,
       history: history
-      source: true
+      # source: true
       insert: -> updated($link, $popup, origin, animation) 
     )
     
@@ -98,27 +140,50 @@ up.popup = (->
   Does nothing if no popup is currently open.
   
   @method up.popup.close
-  @param options.animation {String}
+  @param {Object} options
+    See options for [`up.animate`](/up.motion#up.animate).
   ###
   close = (options) ->
-    options = up.util.options(options, animation: 'fade-out')
     $popup = $('.up-popup')
     if $popup.length
-      up.destroy($popup, animation: options.animation)
+      options = u.options(options,
+        animation: config.closeAnimation,
+        url: $popup.attr('up-previous-url'),
+        title: $popup.attr('up-previous-title')
+      )
+      up.destroy($popup, options)
     
   autoclose = ->
     unless $('.up-popup').is('[up-sticky]')
       close()
     
+  ###*
+  Opens the target of this link in a popup overlay:
+
+      <a href="/decks" up-modal=".deck_list">Switch deck</a>
 
-  up.on('click', '[up-popup]', (event, $link) ->
+  If the `up-sticky` attribute is set, the dialog does not auto-close
+  if a page fragment below the popup overlay updates:
+
+      <a href="/decks" up-popup=".deck_list">Switch deck</a>
+      <a href="/settings" up-popup=".options" up-sticky>Settings</a>
+
+  @method a[up-popup]
+  @ujs
+  @param up-target
+  @param [up-sticky]
+  @param [up-origin]
+  ###
+  up.on('click', 'a[up-popup]', (event, $link) ->
     event.preventDefault()
     if $link.is('.up-current')
       close()
     else
       open($link)
   )
-  
+
+  # Close the popup when someone clicks outside the popup
+  # (but not on a popup opener).
   up.on('click', 'body', (event, $body) ->
     $target = $(event.target)
     unless $target.closest('.up-popup').length || $target.closest('[up-popup]').length
@@ -131,13 +196,23 @@ up.popup = (->
   )
   
   # Close the pop-up overlay when the user presses ESC.
-  $(document).on('keydown', (event) ->
-    if event.keyCode == 27
+  up.magic.onEscape(-> close())
+
+  ###*
+  When an element with this attribute is clicked,
+  a currently open popup is closed. 
+  
+  @method [up-close]
+  @ujs
+  ###
+  up.on('click', '[up-close]', (event, $element) ->
+    if $element.closest('.up-popup')
       close()
   )
   
   open: open
   close: close
   source: source
+  defaults: defaults
   
 )()

data/lib/assets/javascripts/up/tooltip.js.coffee

@@ -0,0 +1,93 @@
+###*
+Tooltips
+========
+  
+TODO: Write some documentation.
+
+@class up.tooltip
+###
+up.tooltip = (->
+  
+  u = up.util
+
+  position = ($link, $tooltip, origin) ->
+    linkBox = u.measure($link)
+    tooltipBox = u.measure($tooltip)
+    css = switch origin
+      when "top"
+        left: linkBox.left + 0.5 * (linkBox.width - tooltipBox.width)
+        top: linkBox.top - tooltipBox.height
+      when "bottom"
+        left: linkBox.left + 0.5 * (linkBox.width - tooltipBox.width)
+        top: linkBox.top + linkBox.height
+      else
+        u.error("Unknown origin", origin)
+    $tooltip.attr('up-origin', origin)
+    $tooltip.css(css)
+
+  createElement = (html) ->
+    u.$createElementFromSelector('.up-tooltip')
+      .html(html)
+      .appendTo(document.body)
+
+  ###*
+  Opens a tooltip.
+  
+  @method up.tooltip.open
+  @param {Element|jQuery|String} elementOrSelector
+  @param {String} html
+  @param {String} [options.origin='top']
+  @param {String} [options.animation]
+  ###
+  open = (linkOrSelector, options = {}) ->
+    $link = $(linkOrSelector)
+    html = u.option(options.html, $link.attr('up-tooltip'))
+    origin = u.option(options.origin, $link.attr('up-origin'), 'top')
+    animation = u.option(options.animation, $link.attr('up-animation'), 'fade-in')
+    close()
+    $tooltip = createElement(html)
+    position($link, $tooltip, origin)
+    up.animate($tooltip, animation, options)
+
+  ###*
+  Closes a currently shown tooltip.
+  Does nothing if no tooltip is currently shown.
+  
+  @method up.tooltip.close
+  @param {Object} options
+    See options for See options for [`up.animate`](/up.motion#up.animate).
+  ###
+  close = (options) ->
+    $tooltip = $('.up-tooltip')
+    if $tooltip.length
+      options = u.options(options, animation: 'fade-out')
+      up.destroy($tooltip, options)
+
+
+  ###*
+  Displays a tooltip when hovering the mouse over this element:
+
+      <a href="/decks" up-tooltip="Show all decks">Decks</a>
+
+  @method [up-tooltip]
+  @ujs
+  ###
+  up.awaken('[up-tooltip]', ($link) ->
+    # Don't register these events on document since *every*
+    # mouse move interaction  bubbles up to the document. 
+    $link.on('mouseover', -> open($link))
+    $link.on('mouseout', -> close())
+  )
+
+  # Close the tooltip when someone clicks anywhere.
+  up.on('click', 'body', (event, $body) ->
+    close()
+  )
+
+  # Close the tooltip when the user presses ESC.
+  up.magic.onEscape(-> close())
+
+  open: open
+  close: close
+
+)()