unpoly-rails 0.32.0 → 0.33.0

data/lib/assets/javascripts/unpoly/dom/extract_cascade.coffee

@@ -0,0 +1,73 @@
+u = up.util
+
+class up.dom.ExtractCascade
+
+  constructor: (selector, options) ->
+    @options = u.options(options, humanizedTarget: 'selector', layer: 'auto')
+    @candidates = @buildCandidates(selector)
+    @plans = u.map @candidates, (candidate, i) =>
+      planOptions = u.copy(@options)
+      if i > 0
+        # If we're using a fallback (any candidate that's not the first),
+        # the original transition might no longer be appropriate.
+        planOptions.transition = up.dom.config.fallbackTransition
+      new up.dom.ExtractPlan(candidate, planOptions)
+
+  buildCandidates: (selector) ->
+    candidates = [selector, @options.fallback, up.dom.config.fallbacks]
+    candidates = u.flatten(candidates)
+    # Remove undefined, null and false from the list
+    candidates = u.select candidates, u.isTruthy
+    if @options.fallback == false || @options.provideTarget
+      # Use the first defined candidate, but not `selector` since that
+      # might be an undefined options.failTarget
+      candidates = [candidates[0]]
+    candidates
+
+  oldPlan: =>
+    @detectPlan('oldExists')
+
+  newPlan: =>
+    @detectPlan('newExists')
+
+  matchingPlan: =>
+    @detectPlan('matchExists')
+
+  detectPlan: (checker) =>
+    u.detect @plans, (plan) -> plan[checker]()
+
+  bestPreflightSelector: =>
+    if @options.provideTarget
+      # We know that the target will be created right before swapping,
+      # so just assume the first plan will work.
+      @plans[0].selector
+    else if plan = @oldPlan()
+      plan.selector
+    else
+      @oldPlanNotFound()
+
+  bestMatchingSteps: =>
+    if plan = @matchingPlan()
+      plan.steps
+    else
+      @matchingPlanNotFound()
+
+  matchingPlanNotFound: =>
+    # The job of this method is to simply throw an error.
+    # However, we will investigate the reasons for the failure
+    # so we can provide a more helpful error message.
+    if @newPlan()
+      @oldPlanNotFound()
+    else
+      if @oldPlan()
+        message = "Could not find #{@options.humanizedTarget} in response"
+      else
+        message = "Could not match #{@options.humanizedTarget} in current page and response"
+      if @response && @options.inspectResponse
+        inspectAction = { label: 'Open response', callback: @options.inspectResponse }
+      up.fail(["#{message} (tried %o)", @candidates], action: inspectAction)
+
+  oldPlanNotFound: =>
+    layerProse = @options.layer
+    layerProse = 'page, modal or popup' if layerProse == 'auto'
+    up.fail("Could not find #{@options.humanizedTarget} in current #{layerProse} (tried %o)", @candidates)

data/lib/assets/javascripts/unpoly/dom/extract_plan.coffee

@@ -0,0 +1,65 @@
+u = up.util
+
+class up.dom.ExtractPlan
+
+  constructor: (selector, options) ->
+    @origin = options.origin
+    @selector = up.dom.resolveSelector(selector, options.origin)
+    @transition = options.transition || options.animation || 'none'
+    @response = options.response
+    @steps = @parseSteps()
+
+  findOld: =>
+    u.each @steps, (step) ->
+      step.$old = up.dom.first(step.selector, @options)
+
+  findNew: =>
+    u.each @steps, (step) =>
+      step.$new = @response.first(step.selector)
+
+  oldExists: =>
+    @findOld()
+    u.all @steps, (step) -> step.$old
+
+  newExists: =>
+    @findNew()
+    u.all @steps, (step) -> step.$new
+
+  matchExists: =>
+    @oldExists() && @newExists()
+
+  ###*
+  Example:
+
+      parseSelector('foo, bar:before', transition: 'cross-fade')
+
+      [
+        { selector: 'foo', pseudoClass: undefined, transition: 'cross-fade' },
+        { selector: 'bar', pseudoClass: 'before', transition: 'cross-fade' }
+      ]
+  ###
+  parseSteps: =>
+    if u.isString(@transition)
+      transitions = @transition.split(comma)
+    else
+      transitions = [@transition]
+
+    comma = /\ *,\ */
+
+    disjunction = @selector.split(comma)
+
+    u.map disjunction, (literal, i) ->
+      literalParts = literal.match(/^(.+?)(?:\:(before|after))?$/)
+      literalParts or up.fail('Could not parse selector literal "%s"', literal)
+      selector = literalParts[1]
+      if selector == 'html'
+        # If someone really asked us to replace the <html> root, the best
+        # we can do is replace the <body>.
+        selector = 'body'
+
+      pseudoClass = literalParts[2]
+      transition = transitions[i] || u.last(transitions)
+
+      selector: selector
+      pseudoClass: pseudoClass
+      transition: transition

data/lib/assets/javascripts/unpoly/{flow.js.coffee → dom.coffee}

@@ -2,30 +2,38 @@
 Fragment update API
 ===================
   
-This module contains Unpoly's core functions to [change](/up.replace) or
-[destroy](/up.destroy) page fragments via JavaScript.
+This module exposes a low-level Javascript API to [change](/up.replace) or
+[destroy](/up.destroy) page fragments.
 
-Other Unpoly modules (like [`up.link`](/up.link) or [`up.modal`](/up.modal))
-build upon this module to offer higher level API functions.
-  
-@class up.flow
+Most of Unpoly's functionality (like [fragment links](/up.link) or [modals](/up.modal))
+is built from these functions. You can use them to extend Unpoly from your
+[custom Javascript](/up.syntax).
+
+@class up.dom
 ###
-up.flow = (($) ->
+up.dom = (($) ->
   
   u = up.util
 
   ###*
   Configures defaults for fragment insertion.
 
-  @property up.flow.config
+  @property up.dom.config
   @param {Boolean} [options.runInlineScripts=true]
     Whether inline `<script>` tags inside inserted HTML fragments will be executed.
   @param {Boolean} [options.runLinkedScripts=false]
     Whether `<script src='...'>` tags inside inserted HTML fragments will fetch and execute
     the linked JavaScript file.
+  @param {String} [options.fallbacks=['body']]
+    When a fragment updates cannot find the requested element, Unpoly will try this list of alternative selectors.
+    The first selector that matches an element in the current page (or response) will be used.
+  @param {String} [options.fallbackTransition='none']
+    The transition to use when using a fallback target.
   @stable
   ###
   config = u.config
+    fallbacks: ['body']
+    fallbackTransition: 'none'
     runInlineScripts: true
     runLinkedScripts: false
 
@@ -40,7 +48,7 @@ up.flow = (($) ->
   ###*
   Returns the URL the given element was retrieved from.
 
-  @method up.flow.source
+  @method up.dom.source
   @param {String|Element|jQuery} selectorOrElement
   @experimental
   ###
@@ -52,7 +60,7 @@ up.flow = (($) ->
   Resolves the given selector (which might contain `&` references)
   to an absolute selector.
 
-  @function up.flow.resolveSelector
+  @function up.dom.resolveSelector
   @param {String|Element|jQuery} selectorOrElement
   @param {String|Element|jQuery} origin
     The element that this selector resolution is relative to.
@@ -63,11 +71,11 @@ up.flow = (($) ->
     if u.isString(selectorOrElement)
       selector = selectorOrElement
       if u.contains(selector, '&')
-        if origin
+        if u.isPresent(origin) # isPresent returns false for empty jQuery collection
           originSelector = u.selectorForElement(origin)
           selector = selector.replace(/\&/, originSelector)
         else
-          up.fail("Found origin reference (%s) in selector %s, but options.origin is missing", '&', selector)
+          up.fail("Found origin reference (%s) in selector %s, but no origin was given", '&', selector)
     else
       selector = u.selectorForElement(selectorOrElement)
     selector
@@ -157,6 +165,8 @@ up.flow = (($) ->
     The URL to fetch from the server.
   @param {String} [options.failTarget='body']
     The CSS selector to update if the server sends a non-200 status code.
+  @param {String} [options.fallback]
+    The selector to update when the original target was not found in the page.
   @param {String} [options.title]
     The document title after the replacement.
 
@@ -206,22 +216,31 @@ up.flow = (($) ->
     same layer as the element that triggered the replacement (see `options.origin`).
     If that element is not known, or no match was found in that layer,
     Unpoly will search in other layers, starting from the topmost layer.
+
   @return {Promise}
     A promise that will be resolved when the page has been updated.
   @stable
   ###
   replace = (selectorOrElement, url, options) ->
-    up.puts "Replacing %s from %s (%o)", selectorOrElement, url, options
     options = u.options(options)
-    target = resolveSelector(selectorOrElement, options.origin)
-    failTarget = u.option(options.failTarget, 'body')
-    failTarget = resolveSelector(failTarget, options.origin)
 
     if !up.browser.canPushState() && options.history != false
       unless options.preload
         up.browser.loadPage(url, u.only(options, 'method', 'data'))
       return u.unresolvablePromise()
 
+    options.inspectResponse = -> up.browser.loadPage(url, u.only(options, 'method', 'data'))
+
+    successOptions = u.merge options,
+      humanizedTarget: 'target'
+
+    failureOptions = u.merge options,
+      humanizedTarget: 'failure target'
+      provideTarget: undefined # don't provide a target if we're targeting the failTarget
+
+    target = bestPreflightSelector(selectorOrElement, successOptions)
+    failTarget = bestPreflightSelector(options.failTarget, failureOptions)
+
     request =
       url: url
       method: options.method
@@ -231,19 +250,21 @@ up.flow = (($) ->
       cache: options.cache
       preload: options.preload
       headers: options.headers
-      
-    options.inspectResponse = -> up.browser.loadPage(url, u.only(options, 'method', 'data'))
-
-    promise = up.ajax(request)
+      timeout: options.timeout
 
     onSuccess = (html, textStatus, xhr) ->
-      processResponse(true, target, url, request, xhr, options)
+      processResponse(true, target, url, request, xhr, successOptions)
 
     onFailure = (xhr, textStatus, errorThrown) ->
-      processResponse(false, failTarget, url, request, xhr, options)
+      rejection = -> u.rejectedPromise(xhr, textStatus, errorThrown)
+      if xhr.responseText
+        promise = processResponse(false, failTarget, url, request, xhr, failureOptions)
+        promise.then(rejection, rejection)
+      else
+        rejection()
 
+    promise = up.ajax(request)
     promise = promise.then(onSuccess, onFailure)
-
     promise
 
   ###*
@@ -286,7 +307,8 @@ up.flow = (($) ->
         options.source  = 'keep'
         options.history = false
 
-    options.title = u.titleFromXhr(xhr) if shouldExtractTitle(options)
+    if shouldExtractTitle(options) && titleFromXhr = u.titleFromXhr(xhr)
+      options.title = titleFromXhr
 
     if options.preload
       u.resolvedPromise()
@@ -328,7 +350,7 @@ up.flow = (($) ->
   @param {String|Element|jQuery} selectorOrElement
   @param {String} html
   @param {Object} [options]
-    See options for [`up.replace`](/up.replace).
+    See options for [`up.replace()`](/up.replace).
   @return {Promise}
     A promise that will be resolved then the selector was updated
     and all animation has finished.
@@ -336,49 +358,42 @@ up.flow = (($) ->
   ###
   extract = (selectorOrElement, html, options) ->
     up.log.group 'Extracting %s from %d bytes of HTML', selectorOrElement, html?.length, ->
-      options = u.options(options,
+      options = u.options options,
         historyMethod: 'push'
         requireMatch: true
         keep: true
         layer: 'auto'
-      )
-
-      selector = resolveSelector(selectorOrElement, options.origin)
-      response = parseResponse(html, options)
-      options.title = response.title() if shouldExtractTitle(options)
 
       up.layout.saveScroll() unless options.saveScroll == false
 
-      promise = u.resolvedPromise()
-      promise = promise.then(options.beforeSwap) if options.beforeSwap
-      promise = promise.then -> updateHistory(options)
-      promise = promise.then ->
-        swapPromises = []
-        for step in parseImplantSteps(selector, options)
-          up.log.group 'Updating %s', step.selector, ->
-            $old = findOldFragment(step.selector, options)
-            $new = response.first(step.selector)
-            if $old && $new
-              filterScripts($new, options)
-              swapPromise = swapElements($old, $new, step.pseudoClass, step.transition, options)
-              swapPromises.push(swapPromise)
-              options.reveal = false
-        # Delay all further links in the promise chain until all fragments have been swapped
-        return $.when(swapPromises...)
-      promise = promise.then(options.afterSwap) if options.afterSwap
-      promise
-
-  findOldFragment = (selector, options) ->
-    first(selector, options) || oldFragmentNotFound(selector, options)
-
-  oldFragmentNotFound = (selector, options) ->
-    if options.requireMatch
-      layerProse = options.layer
-      layerProse = 'page, modal or popup' if layerProse == 'auto'
-      message = "Could not find selector %s in the current #{layerProse}"
-      if message[0] == '#'
-        message += ' (avoid using IDs)'
-      up.fail(message, selector)
+      # Allow callers to create the targeted element right before we swap.
+      options.provideTarget?()
+      response = parseResponse(html)
+      implantSteps = bestMatchingSteps(selectorOrElement, response, options)
+
+      if shouldExtractTitle(options) && responseTitle = response.title()
+        options.title = responseTitle
+      updateHistoryAndTitle(options)
+
+      swapPromises = []
+      for step in implantSteps
+        up.log.group 'Updating %s', step.selector, ->
+          filterScripts(step.$new, options)
+          swapPromise = swapElements(step.$old, step.$new, step.pseudoClass, step.transition, options)
+          swapPromises.push(swapPromise)
+          options.reveal = false # only reveal the first selector atom in the union
+
+      # Delay all further links in the promise chain until all fragments have been swapped
+      $.when(swapPromises...)
+
+  bestPreflightSelector = (selector, options) ->
+    cascade = new up.dom.ExtractCascade(selector, options)
+    cascade.bestPreflightSelector()
+
+  bestMatchingSteps = (selector, response, options) ->
+    options = u.merge(options, response: response)
+    cascade = new up.dom.ExtractCascade(selector, options)
+    cascade.bestMatchingSteps()
 
   filterScripts = ($element, options) ->
     runInlineScripts = u.option(options.runInlineScripts, config.runInlineScripts)
@@ -391,7 +406,7 @@ up.flow = (($) ->
       unless (isLinked && runLinkedScripts) || (isInline && runInlineScripts)
         $script.remove()
 
-  parseResponse = (html, options) ->
+  parseResponse = (html) ->
     # jQuery cannot construct transient elements that contain <html> or <body> tags
     htmlElement = u.createElementFromHtml(html)
     title: -> htmlElement.querySelector("title")?.textContent
@@ -403,16 +418,11 @@ up.flow = (($) ->
       # It returns an array of DOM elements, NOT a jQuery collection.
       if child = $.find(selector, htmlElement)[0]
         $(child)
-      else if options.requireMatch
-        inspectAction = { label: 'Open response', callback: options.inspectResponse }
-        up.fail(["Could not find selector %s in response %o", selector, html], action: inspectAction)
 
-  updateHistory = (options) ->
+  updateHistoryAndTitle = (options) ->
     options = u.options(options, historyMethod: 'push')
-    if options.history
-      up.history[options.historyMethod](options.history)
-    if options.title
-      document.title = options.title
+    up.history[options.historyMethod](options.history) if options.history
+    document.title = options.title if u.isString(options.title)
 
   swapElements = ($old, $new, pseudoClass, transition, options) ->
     transition ||= 'none'
@@ -460,13 +470,11 @@ up.flow = (($) ->
         options.keepPlans = transferKeepableElements($old, $new, options)
 
         if $old.is('body')
-          # We would prefer to delay cleaning until the destroy transition ends, but a
-          # swap of <body> cannot be animated. Also the replaceWith call below will clean the
-          # destroyer's data property from $old, making the up.syntax.clean call in `destroy` blow up.
-          up.syntax.clean($old)
           # jQuery will actually let us .insertBefore the new <body> tag,
           # but that's probably bad Karma.
-          $old.replaceWith($new)
+          swapBody($old, $new)
+          # We cannot morph the <body> tag
+          transition = false
         else
           # Don't insert the new element after the old element. For some reason
           # this will make the browser scroll to the bottom of the new element.
@@ -491,6 +499,10 @@ up.flow = (($) ->
 
     promise
 
+  # This is a separate method so we can mock it in specs
+  swapBody = ($oldBody, $newBody) ->
+    $oldBody.replaceWith($newBody)
+
   transferKeepableElements = ($old, $new, options) ->
     keepPlans = []
     if options.keep
@@ -619,35 +631,12 @@ up.flow = (($) ->
   @stable
   ###
 
-  parseImplantSteps = (selector, options) ->
-    transitionArg = options.transition || options.animation || 'none'
-    comma = /\ *,\ */
-    disjunction = selector.split(comma)
-    if u.isString(transitions)
-      transitions = transitionArg.split(comma)
-    else
-      transitions = [transitionArg]
-    for selectorAtom, i in disjunction
-      # Splitting the atom
-      selectorParts = selectorAtom.match(/^(.+?)(?:\:(before|after))?$/)
-      selectorParts or up.fail('Could not parse selector atom "%s"', selectorAtom)
-      selector = selectorParts[1]
-      if selector == 'html'
-        # If someone really asked us to replace the <html> root, the best
-        # we can do is replace the <body>.
-        selector = 'body'
-      pseudoClass = selectorParts[2]
-      transition = transitions[i] || u.last(transitions)
-      selector: selector
-      pseudoClass: pseudoClass
-      transition: transition
-
   ###*
   Compiles a page fragment that has been inserted into the DOM
   by external code.
 
   **As long as you manipulate the DOM using Unpoly, you will never
-  need to call this method.** You only need to use `up.hello` if the
+  need to call this method.** You only need to use `up.hello()` if the
   DOM is manipulated without Unpoly' involvement, e.g. by setting
   the `innerHTML` property or calling jQuery methods like
   `html`, `insertAfter` or `appendTo`:
@@ -731,7 +720,11 @@ up.flow = (($) ->
   @param {String} options.layer
     The name of the layer in which to find the element. Valid values are
     `auto`, `page`, `modal` and `popup`.
-  @param {}
+  @param {String|Element|jQuery} [options.origin]
+    An second element or selector that can be referenced as `&` in the first selector:
+
+        $input = $('input.email');
+        up.first('.field:has(&)', $input); // returns the .field containing $input
   @return {jQuery|Undefined}
     The first element that is neither a ghost or being destroyed,
     or `undefined` if no such element was given.
@@ -739,10 +732,11 @@ up.flow = (($) ->
   ###
   first = (selectorOrElement, options) ->
     options = u.options(options, layer: 'auto')
+    resolved = resolveSelector(selectorOrElement, options.origin)
     if options.layer == 'auto'
-      firstInPriority(selectorOrElement, options.origin)
+      firstInPriority(resolved, options.origin)
     else
-      firstInLayer(selectorOrElement, options.layer)
+      firstInLayer(resolved, options.layer)
 
   firstInPriority = (selectorOrElement, origin) ->
     layers = ['popup', 'modal', 'page']
@@ -781,7 +775,7 @@ up.flow = (($) ->
   ###*
   Destroys the given element or selector.
 
-  Takes care that all [`up.compiler`](/up.compiler) destructors, if any, are called.
+  Takes care that all [`up.compiler()`](/up.compiler) destructors, if any, are called.
 
   The element is removed from the DOM.
   Note that if you choose to animate the element removal using `options.animate`,
@@ -798,11 +792,11 @@ up.flow = (($) ->
   @param {String|Function} [options.animation='none']
     The animation to use before the element is removed from the DOM.
   @param {Number} [options.duration]
-    The duration of the animation. See [`up.animate`](/up.animate).
+    The duration of the animation. See [`up.animate()`](/up.animate).
   @param {Number} [options.delay]
-    The delay before the animation starts. See [`up.animate`](/up.animate).
+    The delay before the animation starts. See [`up.animate()`](/up.animate).
   @param {String} [options.easing]
-    The timing function that controls the animation's acceleration. [`up.animate`](/up.animate).
+    The timing function that controls the animation's acceleration. [`up.animate()`](/up.animate).
   @return {Deferred}
     A promise that will be resolved once the element has been removed from the DOM.
   @stable
@@ -822,7 +816,7 @@ up.flow = (($) ->
       # If e.g. a modal or popup asks us to restore a URL, do this
       # before emitting `fragment:destroy`. This way up.navigate sees the
       # new URL and can assign/remove .up-current classes accordingly.
-      updateHistory(options)
+      updateHistoryAndTitle(options)
 
       animationDeferred = u.presence(options.animation, u.isDeferred) ||
         up.motion.animate($element, options.animation, animateOptions)
@@ -882,7 +876,7 @@ up.flow = (($) ->
   @function up.reload
   @param {String|Element|jQuery} selectorOrElement
   @param {Object} [options]
-    See options for [`up.replace`](/up.replace)
+    See options for [`up.replace()`](/up.replace)
   @param {String} [options.url]
     The URL from which to reload the fragment.
     This defaults to the URL from which the fragment was originally loaded.
@@ -913,10 +907,11 @@ up.flow = (($) ->
 
 )(jQuery)
 
-up.replace = up.flow.replace
-up.extract = up.flow.extract
-up.reload = up.flow.reload
-up.destroy = up.flow.destroy
-up.first = up.flow.first
-up.hello = up.flow.hello
+up.replace = up.dom.replace
+up.extract = up.dom.extract
+up.reload = up.dom.reload
+up.destroy = up.dom.destroy
+up.first = up.dom.first
+up.hello = up.dom.hello
 
+up.renamedModule 'flow', 'dom'

data/lib/assets/javascripts/unpoly/{navigation.js.coffee → feedback.coffee}

@@ -33,16 +33,16 @@ Once the response is received the URL will change to `/bar` and the `up-active`
     <a href="/bar" up-follow class="up-current">Bar</a>
 
 
-@class up.navigation
+@class up.feedback
 ###
-up.navigation = (($) ->
+up.feedback = (($) ->
 
   u = up.util
 
   ###*
   Sets default options for this module.
 
-  @property up.navigation.config
+  @property up.feedback.config
   @param {Number} [config.currentClasses]
     An array of classes to set on [links that point the current location](/up-current).
   @stable
@@ -144,9 +144,9 @@ up.navigation = (($) ->
 
       var $button = $('button');
       $button.on('click', function() {
-        up.navigation.start($button);
+        up.feedback.start($button);
         up.ajax(...).always(function() {
-          up.navigation.stop($button);
+          up.feedback.stop($button);
         });
       });
 
@@ -154,18 +154,18 @@ up.navigation = (($) ->
 
       var $button = $('button');
       $button.on('click', function() {
-        up.navigation.start($button, function() {
+        up.feedback.start($button, function() {
           up.ajax(...);
         });
       });
 
-  @method up.navigation.start
+  @method up.feedback.start
   @param {Element|jQuery|String} elementOrSelector
     The element to mark as active
   @param {Function} [action]
     An optional function to run while the element is marked as loading.
     The function must return a promise.
-    Once the promise resolves, the element will be [marked as no longer loading](/up.navigation.stop).
+    Once the promise resolves, the element will be [marked as no longer loading](/up.feedback.stop).
   @internal
   ###
   start = (elementOrSelector, action) ->
@@ -213,14 +213,13 @@ up.navigation = (($) ->
   This happens automatically when network requests initiated by the Unpoly API have completed.
   Use this function if you make custom network calls from your own JavaScript code.
 
-  @function up.navigation.stop
+  @function up.feedback.stop
   @param {jQuery} event.$element
     The link or form that has finished loading.
   @internal
   ###
   stop = (elementOrSelector) ->
     $element = findActionableArea(elementOrSelector)
-    up.emit('up:navigated', $element: $element, message: false)
     $element.removeClass(CLASS_ACTIVE)
 
   ###*
@@ -286,8 +285,9 @@ up.navigation = (($) ->
   up.on 'up:framework:reset', reset
 
   config: config
-  defaults: -> up.fail('up.navigation.defaults(...) no longer exists. Set values on he up.navigation.config property instead.')
   start: start
   stop: stop
 
 )(jQuery)
+
+up.renamedModule 'navigation', 'feedback'