upjs-rails 0.14.1 → 0.15.0

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

@@ -16,6 +16,10 @@ up.form = (($) ->
   Sets default options for form submission and validation.
 
   @property up.form.config
+  @param {Number} [config.observeDelay=0]
+    The number of miliseconds to wait before [`up.observe`](/up.observe) runs the callback
+    after the input value changes. Use this to limit how often the callback
+    will be invoked for a fast typist.
   @param {Array} [config.validateTargets=['[up-fieldset]:has(&)', 'fieldset:has(&)', 'label:has(&)', 'form:has(&)']]
     An array of CSS selectors that are searched around a form field
     that wants to [validate](/up.validate). The first matching selector
@@ -24,10 +28,14 @@ up.form = (($) ->
     By default this looks for a `<fieldset>`, `<label>` or `<form>`
     around the validating input field, or any element with an
     `up-fieldset` attribute.
+  @param {String} [config.fields]
+    An array of CSS selectors that represent form fields, such as `input` or `select`.
   @stable
   ###
   config = u.config
     validateTargets: ['[up-fieldset]:has(&)', 'fieldset:has(&)', 'label:has(&)', 'form:has(&)']
+    fields: [':input']
+    observeDelay: 0
 
   reset = ->
     config.reset()
@@ -106,8 +114,11 @@ up.form = (($) ->
     $form = $(formOrSelector).closest('form')
 
     options = u.options(options)
-    successSelector = up.flow.resolveSelector(u.option(options.target, $form.attr('up-target'), 'body'), options)
-    failureSelector = up.flow.resolveSelector(u.option(options.failTarget, $form.attr('up-fail-target'), -> u.selectorForElement($form)), options)
+    successSelector = u.option(options.target, $form.attr('up-target'), 'body')
+    successSelector = up.flow.resolveSelector(successSelector, options)
+    failureSelector = u.option(options.failTarget, $form.attr('up-fail-target')) || u.selectorForElement($form)
+    failureSelector = up.flow.resolveSelector(failureSelector, options)
+
     historyOption = u.option(options.history, u.castedAttr($form, 'up-history'), true)
     successTransition = u.option(options.transition, u.castedAttr($form, 'up-transition'))
     failureTransition = u.option(options.failTransition, u.castedAttr($form, 'up-fail-transition'), successTransition)
@@ -174,7 +185,8 @@ up.form = (($) ->
         up.flow.implant(failureSelector, html, failureOptions)
 
   ###*
-  Observes a form field and runs a callback when its value changes.
+  Observes a field or form and runs a callback when a value changes.
+
   This is useful for observing text fields while the user is typing.
 
   The UJS variant of this is the [`up-observe`](/up-observe) attribute.
@@ -184,9 +196,9 @@ up.form = (($) ->
   The following would submit the form whenever the
   text field value changes:
 
-      up.observe('input[name=query]', { change: function(value, $input) {
+      up.observe('input[name=query]', function(value, $input) {
         up.submit($input)
-      } });
+      });
 
   \#\#\#\# Preventing concurrency
 
@@ -204,43 +216,56 @@ up.form = (($) ->
   load on your server, you can use a `delay` option to wait
   a few miliseconds before executing the callback:
 
-      up.observe('input', {
-        delay: 100,
-        change: function(value, $input) { up.submit($input) }
+      up.observe('input', { delay: 100 }, function(value, $input) {
+        up.submit($input)
       });
 
   @function up.observe
   @param {Element|jQuery|String} fieldOrSelector
-  @param {Function(value, $field)|String} options.change
+  @param {Number} [options.delay=up.form.config.observeDelay]
+    The number of miliseconds to wait before executing the callback
+    after the input value changes. Use this to limit how often the callback
+    will be invoked for a fast typist.
+  @param {Function(value, $field)|String} onChange
     The callback to execute when the field's value changes.
     If given as a function, it must take two arguments (`value`, `$field`).
     If given as a string, it will be evaled as Javascript code in a context where
     (`value`, `$field`) are set.
-  @param {Number} [options.delay=0]
-    The number of miliseconds to wait before executing the callback
-    after the input value changes. Use this to limit how often the callback
-    will be invoked for a fast typist.
+  @return {Function}
+    A destructor function that removes the observe watch when called.
   @stable
   ###
-  observe = (fieldOrSelector, options) ->
+  observe = (selectorOrElement, args...) ->
 
-    $field = $(fieldOrSelector)
+    options = {}
+    callbackArg = undefined
+    if args.length == 1
+      callbackArg = args[0]
+    if args.length > 1
+      options = u.options(args[0])
+      callbackArg = args[1]
+
+    $element = $(selectorOrElement)
     options = u.options(options)
-    delay = u.option($field.attr('up-delay'), options.delay, 0)
+    delay = u.option($element.attr('up-delay'), options.delay, config.observeDelay)
     delay = parseInt(delay)
 
-    knownValue = null
     callback = null
-    callbackTimer = null
 
-    if codeOnChange = $field.attr('up-observe')
-      callback = (value, $field) ->
-        eval(codeOnChange)
-    else if options.change
-      callback = options.change
+    if u.isGiven(options.change)
+      up.error('up.observe now takes the change callback as the last argument')
+
+    rawCallback = u.option(u.presentAttr($element, 'op-observe'), callbackArg)
+    if u.isString(rawCallback)
+      callback = (value, $field) -> eval(rawCallback)
     else
-      u.error('up.observe: No change callback given')
+      callback = rawCallback or u.error('up.observe: No change callback given')
+
+    if $element.is('form')
+      return observeForm($element, options, callback)
 
+    knownValue = null
+    callbackTimer = null
     callbackPromise = u.resolvedPromise()
 
     # This holds the next callback function, curried with `value` and `$field`.
@@ -256,14 +281,14 @@ up.form = (($) ->
         returnValue
 
     check = ->
-      value = $field.val()
+      value = $element.val()
       # don't run the callback for the check during initialization
       skipCallback = u.isNull(knownValue)
       if knownValue != value
         knownValue = value
         unless skipCallback
           clearTimer()
-          nextCallback = -> callback.apply($field.get(0), [value, $field])
+          nextCallback = -> callback.apply($element.get(0), [value, $element])
           callbackTimer = setTimeout(
             ->
               # Only run the callback once the previous callback's
@@ -288,15 +313,53 @@ up.form = (($) ->
       'input change'
     else
       # Actually we won't ever get `input` from the user in this browser,
-      # but we want to notice if another script  manually triggers `input`
+      # but we want to notice if another script manually triggers `input`
       # on the element.
       'input change keypress paste cut click propertychange'
-    $field.on changeEvents, check
+    $element.on(changeEvents, check)
 
     check()
 
     # return destructor
-    return clearTimer
+    return ->
+      $element.off(changeEvents, check)
+      clearTimer()
+
+  ###*
+  @function observeForm
+  @internal
+  ###
+  observeForm = ($form, options, callback) ->
+    $fields = u.multiSelector(config.fields).find($form)
+    destructors = u.map $fields, ($field) ->
+      observe($field, callback)
+    ->
+      destructor() for destructor in destructors
+
+  ###*
+  [Observes](/up.observe) a field or form and submits the form when a value changes.
+
+  The changed form field will be assigned a CSS class [`up-active`](/up-active)
+  while the autosubmitted form is processing.
+
+  The UJS variant of this is the [`up-autosubmit`](/up-autosubmit) attribute.
+
+  @function up.autosubmit
+  @param {String|Element|jQuery} selectorOrElement
+    The form field to observe.
+  @param {Object} [options]
+    See options for [`up.observe`](/up.observe)
+  @return {Function}
+    A destructor function that removes the observe watch when called.
+  @stable
+  ###
+  autosubmit = (selectorOrElement, options) ->
+    console.log("autosubmit %o", selectorOrElement)
+    observe(selectorOrElement, options, (value, $field) ->
+      $form = $field.closest('form')
+      $field.addClass('up-active')
+      submit($form).always -> $field.removeClass('up-active')
+    )
 
   resolveValidateTarget = ($field, options) ->
     target = u.option(options.target, $field.attr('up-validate'))
@@ -564,7 +627,6 @@ up.form = (($) ->
       <input type="text" name="email" up-validate=".email-errors">
       <span class="email-errors"></span>
 
-
   \#\#\#\# Updating dependent fields
 
   The `[up-validate]` behavior is also a great way to partially update a form
@@ -599,21 +661,23 @@ up.form = (($) ->
     validate($field)
 
   ###*
-  Observes this form field and runs the given script
-  when its value changes. This is useful for observing text fields
-  while the user is typing.
+  Observes this field or form and runs a callback when a value changes.
+
+  This is useful for observing text fields while the user is typing.
 
   The programmatic variant of this is the [`up.observe`](/up.observe) function.
 
   \#\#\#\# Example
 
-  For instance, the following would submit the form whenever the
-  text field value changes:
+  The following would run a global `showSuggestions(value)` function
+  whenever the `<input>` changes:
 
-      <form method="GET" action="/search">
-        <input type="query" up-observe="up.form.submit(this)">
+      <form>
+        <input type="query" up-observe="showSuggestions(value)">
       </form>
 
+  \#\#\#\# Callback context
+
   The script given to `up-observe` runs with the following context:
 
   | Name     | Type      | Description                           |
@@ -625,21 +689,39 @@ up.form = (($) ->
   @selector [up-observe]
   @param {String} up-observe
     The code to run when the field's value changes.
+  @param {String} up-delay
+    The number of miliseconds to wait after a change before the code is run.
   @stable
   ###
-  up.compiler '[up-observe]', ($field) ->
-    return observe($field)
+  up.compiler '[up-observe]', ($formOrField) -> observe($formOrField)
+
+  ###*
+  [Observes](/up.observe) this field or form and submits the form when a value changes.
 
-#  up.compiler '[up-autosubmit]', ($field) ->
-#    return observe($field, change: ->
-#      $form = $field.closest('form')
-#      $field.addClass('up-active')
-#      up.submit($form).always ->
-#        $field.removeClass('up-active')
-#    )
+  The form field will be assigned a CSS class [`up-active`](/up-active)
+  while the autosubmitted form is processing.
+
+  The programmatic variant of this is the [`up.autosubmit`](/up.autosubmit) function.
+
+  \#\#\#\# Example
+
+  The following would submit the form whenever the
+  text field value changes:
+
+      <form method="GET" action="/search" up-autosubmit>
+        <input type="query">
+      </form>
+
+  @selector [up-autosubmit]
+  @param {String} up-delay
+    The number of miliseconds to wait after the change before the form is submitted.
+  @stable
+  ###
+  up.compiler '[up-autosubmit]', ($formOrField) -> autosubmit($formOrField)
 
   up.on 'up:framework:reset', reset
 
+  knife: eval(Knife?.point)
   submit: submit
   observe: observe
   validate: validate
@@ -648,5 +730,5 @@ up.form = (($) ->
 
 up.submit = up.form.submit
 up.observe = up.form.observe
+up.autosubmit = up.form.autosubmit
 up.validate = up.form.validate
-

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

@@ -3,7 +3,8 @@ Modal dialogs
 =============
 
 Instead of [linking to a page fragment](/up.link), you can choose
-to show a fragment in a modal dialog.
+to show a fragment in a modal dialog. The existing page will remain
+open in the background and reappear once the modal is closed.
 
 To open a modal, add an [`up-modal` attribute](/a-up-modal) to a link,
 or call the Javascript functions [`up.modal.follow`](/up.modal.follow)
@@ -312,7 +313,7 @@ up.modal = (($) ->
     else
       # Although someone prevented the destruction, keep a uniform API for
       # callers by returning a Deferred that will never be resolved.
-      $.Deferred()
+      u.unresolvableDeferred()
 
   ###*
   This event is [emitted](/up.emit) when a modal dialog is starting to open.
@@ -340,6 +341,9 @@ up.modal = (($) ->
   @function up.modal.close
   @param {Object} options
     See options for [`up.animate`](/up.animate)
+  @return {Deferred}
+    A promise that will be resolved once the modal's close
+    animation has finished.
   @stable
   ###
   close = (options) ->
@@ -358,9 +362,10 @@ up.modal = (($) ->
           up.emit('up:modal:closed')
         deferred
       else
-        # Although someone prevented the destruction, keep a uniform API for
-        # callers by returning a Deferred that will never be resolved.
-        $.Deferred()
+        # Although someone prevented the destruction,
+        # keep a uniform API for callers by returning
+        # a Deferred that will never be resolved.
+        u.unresolvableDeferred()
     else
       u.resolvedDeferred()
 

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

@@ -2,7 +2,7 @@
 Animation
 =========
   
-Whenever you change a page fragment (through methods like
+Whenever you update a page fragment (through methods like
 [`up.replace`](/up.replace) or UJS attributes like [`up-target`](/up-target))
 you can animate the change.
 
@@ -26,7 +26,6 @@ and [transitions](/up.morph#named-animation).
 You can also easily [define your own animations](/up.animation)
 or [transitions](/up.transition) using Javascript or CSS.
 
-  
 @class up.motion
 ###
 up.motion = (($) ->
@@ -325,7 +324,7 @@ up.motion = (($) ->
     parsedOptions = u.only(options, 'reveal', 'restoreScroll', 'source')
     parsedOptions = u.extend(parsedOptions, animateOptions(options))
 
-    if up.browser.canCssAnimation()
+    if up.browser.canCssTransition()
       finish($old)
       finish($new)
 

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

@@ -1,8 +1,8 @@
 ###*
 Fast interaction feedback
 =========================
-  
-This module marks up link elements with classes indicating that
+
+Up.js automatically marks up link elements with classes indicating that
 they are currently loading (class `up-active`) or linking
 to the current location (class `up-current`).
 

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

@@ -3,14 +3,13 @@ Pop-up overlays
 ===============
 
 Instead of [linking to a page fragment](/up.link), you can choose
-to show a fragment in a popup overlay.
+to show a fragment in a popup overlay that rolls down from an anchoring element.
 
 To open a popup, add an [`up-popup` attribute](/a-up-popup) to a link,
 or call the Javascript function [`up.popup.attach`](/up.popup.attach).
 
 For modal dialogs see [up.modal](/up.modal) instead.
 
-
 \#\#\#\# Customizing the popup design
 
 Loading the Up.js stylesheet will give you a minimal popup design:
@@ -27,7 +26,6 @@ By default the popup uses the following DOM structure:
       ...
     </div>
 
-
 \#\#\#\# Closing behavior
 
 The popup closes when the user clicks anywhere outside the popup area.
@@ -42,7 +40,6 @@ To disable this behavior, give the opening link an `up-sticky` attribute:
 
     <a href="/settings" up-popup=".options" up-sticky>Settings</a>
 
-  
 @class up.popup
 ###
 up.popup = (($) ->
@@ -164,10 +161,14 @@ up.popup = (($) ->
   updated = ($link, $popup, position, animation, animateOptions) ->
     $popup.show()
     setPosition($link, $popup, position)
-    up.animate($popup, animation, animateOptions)
+    deferred = up.animate($popup, animation, animateOptions)
+    deferred.then -> up.emit('up:popup:opened')
+    deferred
     
   ###*
   Attaches a popup overlay to the given element or selector.
+
+  Emits events [`up:popup:open`](/up:popup:open) and [`up:popup:opened`](/up:popup:opened).
   
   @function up.popup.attach
   @param {Element|jQuery|String} elementOrSelector
@@ -202,35 +203,89 @@ up.popup = (($) ->
     animateOptions = up.motion.animateOptions(options, $link)
 
     close()
-    $popup = createHiddenPopup($link, selector, sticky)
-    
-    up.replace(selector, url,
-      history: history
-      insert: -> updated($link, $popup, position, animation, animateOptions)
-    )
-    
+
+    if up.bus.nobodyPrevents('up:popup:open', url: url)
+      $popup = createHiddenPopup($link, selector, sticky)
+
+      up.replace(selector, url,
+        history: history
+        insert: -> updated($link, $popup, position, animation, animateOptions)
+      )
+    else
+      # Although someone prevented the destruction, keep a uniform API for
+      # callers by returning a Deferred that will never be resolved.
+      u.unresolvableDeferred()
+
+  ###*
+  This event is [emitted](/up.emit) when a popup is starting to open.
+
+  @event up:popup:open
+  @param event.preventDefault()
+    Event listeners may call this method to prevent the popup from opening.
+  @stable
+  ###
+
+  ###*
+  This event is [emitted](/up.emit) when a popup has finished opening.
+
+  @event up:popup:opened
+  @stable
+  ###
+      
   ###*
   Closes a currently opened popup overlay.
+
   Does nothing if no popup is currently open.
-  
+
+  Emits events [`up:popup:close`](/up:popup:close) and [`up:popup:closed`](/up:popup:closed).
+
   @function up.popup.close
   @param {Object} options
     See options for [`up.animate`](/up.animate).
+  @return {Deferred}
+    A promise that will be resolved once the modal's close
+    animation has finished.
   @stable
   ###
   close = (options) ->
     $popup = $('.up-popup')
     if $popup.length
-      options = u.options(options,
-        animation: config.closeAnimation,
-        url: $popup.attr('up-covered-url'),
-        title: $popup.attr('up-covered-title')
-      )
-      currentUrl = undefined
-      up.destroy($popup, options)
+      if up.bus.nobodyPrevents('up:popup:close', $element: $popup)
+        options = u.options(options,
+          animation: config.closeAnimation,
+          url: $popup.attr('up-covered-url'),
+          title: $popup.attr('up-covered-title')
+        )
+        currentUrl = undefined
+        deferred = up.destroy($popup, options)
+        deferred.then -> up.emit('up:popup:closed')
+        deferred
+      else
+        # Although someone prevented the destruction,
+        # keep a uniform API for callers by returning
+        # a Deferred that will never be resolved.
+        u.unresolvableDeferred()
     else
-      u.resolvedPromise()
-    
+      u.resolvedDeferred()
+
+  ###*
+  This event is [emitted](/up.emit) when a popup dialog
+  is starting to [close](/up.popup.close).
+
+  @event up:popup:close
+  @param event.preventDefault()
+    Event listeners may call this method to prevent the popup from closing.
+  @stable
+  ###
+
+  ###*
+  This event is [emitted](/up.emit) when a popup dialog
+  is done [closing](/up.popup.close).
+
+  @event up:popup:closed
+  @stable
+  ###
+      
   autoclose = ->
     unless $('.up-popup').is('[up-sticky]')
       discardHistory()

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

@@ -99,7 +99,6 @@ up.proxy = (($) ->
     key: cacheKey
     log: 'up.proxy'
 
-
   ###*
   Returns a cached response for the given request.
 

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

@@ -304,6 +304,8 @@ up.syntax = (($) ->
 
   @function up.hello
   @param {String|Element|jQuery} selectorOrElement
+  @return {jQuery}
+    The compiled element
   @stable
   ###
   hello = (selectorOrElement) ->

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

@@ -667,8 +667,7 @@ up.util = (($) ->
 
   ###*
   Returns the first argument that is considered present.
-  If an argument is a function, it is called and the value is checked for presence.
-  
+
   This function is useful when you have multiple option sources and the value can be boolean.
   In that case you cannot change the sources with a `||` operator
   (since that doesn't short-circuit at `false`).
@@ -678,15 +677,7 @@ up.util = (($) ->
   @internal
   ###
   option = (args...) ->
-    # This behavior is subtly different from detect!
-    match = undefined
-    for arg in args
-      value = arg
-      value = value() if isFunction(value)
-      if isGiven(value)
-        match = value
-        break
-    match    
+    detect(args, isGiven)
 
   ###*
   Passes each element in the given array to the given function.
@@ -922,7 +913,7 @@ up.util = (($) ->
   ###
   cssAnimate = (elementOrSelector, lastFrame, opts) ->
     $element = $(elementOrSelector)
-    if up.browser.canCssAnimation()
+    if up.browser.canCssTransition()
       opts = options(opts, 
         duration: 300, 
         delay: 0, 
@@ -1149,6 +1140,16 @@ up.util = (($) ->
   resolvedPromise = ->
     resolvedDeferred().promise()
 
+  ###*
+  Returns a [Deferred object](https://api.jquery.com/category/deferred-object/) that will never be resolved.
+
+  @function up.util.unresolvableDeferred
+  @return {Deferred}
+  @experimental
+  ###
+  unresolvableDeferred = ->
+    $.Deferred()
+
   ###*
   Returns a promise that will never be resolved.
 
@@ -1156,7 +1157,7 @@ up.util = (($) ->
   @experimental
   ###
   unresolvablePromise = ->
-    $.Deferred().promise()
+    unresolvableDeferred().promise()
 
   ###*
   Returns an empty jQuery collection.
@@ -1518,6 +1519,7 @@ up.util = (($) ->
   clientSize: clientSize
   only: only
   trim: trim
+  unresolvableDeferred: unresolvableDeferred
   unresolvablePromise: unresolvablePromise
   resolvedPromise: resolvedPromise
   resolvedDeferred: resolvedDeferred

data/lib/upjs/rails/version.rb

@@ -4,6 +4,6 @@ module Upjs
     # The current version of the upjs-rails gem.
     # This version number is also used for releases of the Up.js
     # frontend code.
-    VERSION = '0.14.1'
+    VERSION = '0.15.0'
   end
 end

data/spec_app/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    upjs-rails (0.14.0)
+    upjs-rails (0.14.1)
       rails (>= 3)
 
 GEM

data/spec_app/spec/javascripts/up/bus_spec.js.coffee

@@ -76,19 +76,21 @@ describe 'up.bus', ->
 
         expect(emittedEvent.customField).toEqual('custom-value')
 
-      it 'triggers an event on an element given as .$element event property', ->
-        emittedEvent = undefined
-        emitted$Target = undefined
+      describe 'with .$element option', ->
 
-        $element = affix('.element').text('foo')
+        it 'triggers an event on the given element', ->
+          emittedEvent = undefined
+          $emittedTarget = undefined
 
-        up.on 'foo', (event, $target) ->
-          emittedEvent = event
-          emitted$Target = $target
+          $element = affix('.element').text('foo')
 
-        up.emit('foo', $element: $element)
+          up.on 'foo', (event, $target) ->
+            emittedEvent = event
+            $emittedTarget = $target
 
-        expect(emittedEvent).toBeDefined()
-        expect(emitted$Target).toEqual($element)
+          up.emit('foo', $element: $element)
+
+          expect(emittedEvent).toBeDefined()
+          expect($emittedTarget).toEqual($element)
 
-        expect(emittedEvent.$element).toEqual($element)
+          expect(emittedEvent.$element).toEqual($element)