unpoly-rails 0.37.0 → 0.50.0

data/lib/assets/javascripts/unpoly/form.coffee

@@ -2,7 +2,7 @@
 Forms
 =====
   
-Unpoly comes with functionality to [submit](/form-up-target) and [validate](/up-validate)
+Unpoly comes with functionality to [submit](/form-up-target) and [validate](/input-up-validate)
 forms without leaving the current page. This means you can replace page fragments,
 open dialogs with sub-forms, etc. all without losing form state.
 
@@ -16,7 +16,7 @@ up.form = (($) ->
   Sets default options for form submission and validation.
 
   @property up.form.config
-  @param {Number} [config.observeDelay=0]
+  @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.
@@ -28,7 +28,7 @@ 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=[':input']]
+  @param {string} [config.fields=[':input']]
     An array of CSS selectors that represent form fields, such as `input` or `select`.
   @stable
   ###
@@ -54,51 +54,51 @@ up.form = (($) ->
   information on how AJAX form submissions work in Unpoly.
 
   @function up.submit
-  @param {Element|jQuery|String} formOrSelector
+  @param {Element|jQuery|string} formOrSelector
     A reference or selector for the form to submit.
     If the argument points to an element that is not a form,
     Unpoly will search its ancestors for the closest form.
-  @param {String} [options.url]
+  @param {string} [options.url]
     The URL where to submit the form.
     Defaults to the form's `action` attribute, or to the current URL of the browser window.
-  @param {String} [options.method='post']
+  @param {string} [options.method='post']
     The HTTP method used for the form submission.
     Defaults to the form's `up-method`, `data-method` or `method` attribute, or to `'post'`
     if none of these attributes are given.
-  @param {String} [options.target]
+  @param {string} [options.target]
     The selector to update when the form submission succeeds (server responds with status 200).
     Defaults to the form's `up-target` attribute.
-  @param {String} [options.failTarget]
+  @param {string} [options.failTarget]
     The selector to update when the form submission fails (server responds with non-200 status).
     Defaults to the form's `up-fail-target` attribute, or to an auto-generated
     selector that matches the form itself.
-  @param {String} [options.fallback]
+  @param {string} [options.fallback]
     The selector to update when the original target was not found in the page.
     Defaults to the form's `up-fallback` attribute.
-  @param {Boolean|String} [options.history=true]
+  @param {boolean|string} [options.history=true]
     Successful form submissions will add a history entry and change the browser's
     location bar if the form either uses the `GET` method or the response redirected
     to another page (this requires the `unpoly-rails` gem).
     If you want to prevent history changes in any case, set this to `false`.
-    If you pass a `String`, it is used as the URL for the browser history.
-  @param {String} [options.transition='none']
+    If you pass a string, it is used as the URL for the browser history.
+  @param {string} [options.transition='none']
     The transition to use when a successful form submission updates the `options.target` selector.
     Defaults to the form's `up-transition` attribute, or to `'none'`.
-  @param {String} [options.failTransition='none']
+  @param {string} [options.failTransition='none']
     The transition to use when a failed form submission updates the `options.failTarget` selector.
     Defaults to the form's `up-fail-transition` attribute, or to `options.transition`, or to `'none'`.
-  @param {Number} [options.duration]
+  @param {number} [options.duration]
     The duration of the transition. See [`up.morph()`](/up.morph).
-  @param {Number} [options.delay]
+  @param {number} [options.delay]
     The delay before the transition starts. See [`up.morph()`](/up.morph).
-  @param {String} [options.easing]
+  @param {string} [options.easing]
     The timing function that controls the transition's acceleration. [`up.morph()`](/up.morph).
-  @param {Element|jQuery|String} [options.reveal]
+  @param {Element|jQuery|string} [options.reveal=true]
     Whether to reveal the target element within its viewport.
-  @param {Boolean} [options.restoreScroll]
+  @param {boolean} [options.restoreScroll]
     If set to `true`, this will attempt to [`restore scroll positions`](/up.restoreScroll)
     previously seen on the destination URL.
-  @param {Boolean} [options.cache]
+  @param {boolean} [options.cache]
     Whether to force the use of a cached response (`true`)
     or never use the cache (`false`)
     or make an educated guess (`undefined`).
@@ -108,19 +108,18 @@ up.form = (($) ->
   @param {Object} [options.headers={}]
     An object of additional header key/value pairs to send along
     with the request.
-  @param {String} [options.layer='auto']
+  @param {string} [options.layer='auto']
     The name of the layer that ought to be updated. Valid values are
     `auto`, `page`, `modal` and `popup`.
 
     If set to `auto` (default), Unpoly will try to find a match in the form's layer.
-  @param {String} [options.failLayer='auto']
+  @param {string} [options.failLayer='auto']
     The name of the layer that ought to be updated if the server sends a non-200 status code.
   @return {Promise}
     A promise for the successful form submission.
   @stable
   ###
   submit = (formOrSelector, options) ->
-    
     $form = $(formOrSelector).closest('form')
 
     options = u.options(options)
@@ -152,11 +151,12 @@ up.form = (($) ->
 
     # If we can't update the location URL, fall back to a vanilla form submission.
     unless up.browser.canPushState() || options.history == false
+      # Don't use up.browser.navigate(); It cannot deal with file inputs.
       $form.get(0).submit()
       return u.unresolvablePromise()
 
     promise = up.replace(target, url, options)
-    promise.always -> up.feedback.stop($form)
+    u.always promise, -> up.feedback.stop($form)
     promise
 
   ###*
@@ -212,16 +212,16 @@ up.form = (($) ->
       });
 
   @function up.observe
-  @param {Element|jQuery|String} selectorOrElement
+  @param {Element|jQuery|string} selectorOrElement
     The form fields that wiill be observed.
 
     You can pass one or more fields, a `<form>` or any container that contains form fields.
     The callback will be run if any of the given fields change.
-  @param {Number} [options.delay=up.form.config.observeDelay]
+  @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
+  @param {Function(value, $field)|string} onChange
     The callback to run 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
@@ -251,7 +251,7 @@ up.form = (($) ->
     delay = u.option(u.presentAttr($element, 'up-delay'), options.delay, config.observeDelay)
     delay = parseInt(delay)
 
-    $fields = u.multiSelector(config.fields).findWithSelf($element)
+    $fields = u.multiSelector(config.fields).selectInSubtree($element)
 
     destructors = u.map $fields, (field) ->
       observeField($(field), delay, callback)
@@ -259,49 +259,20 @@ up.form = (($) ->
     u.sequence(destructors...)
 
   observeField = ($field, delay, callback) ->
-    processedValue = u.submittedValue($field)
-    timer = undefined
-    lastCallbackDone = u.resolvedPromise()
-
-    runCallback = (value) ->
-      processedValue = value
-      callbackReturnValue = callback.apply($field.get(0), [value, $field])
-      if u.isPromise(callbackReturnValue)
-        lastCallbackDone = callbackReturnValue
-      else
-        lastCallbackDone = callbackReturnValue
-
-    check = ->
-      value = u.submittedValue($field)
-      # don't run the callback for the check during initialization
-      if processedValue != value
-        nextCallback = -> runCallback(value)
-        timer?.cancel()
-        timer = u.promiseTimer(delay)
-        # We wait until both the delay has passed and a previous callback is done executing
-        $.when(timer, lastCallbackDone).then(nextCallback)
-
-    # Although (depending on the browser) we only need/receive either input or change,
-    # we always bind to both events in case another script manually triggers it.
-    changeEvents = 'input change'
-
-    $field.on(changeEvents, check)
-
-    # return destructor
-    return ->
-      $field.off(changeEvents, check)
-      timer?.cancel()
+    observer = new up.FieldObserver($field, { delay, callback })
+    observer.start()
+    return observer.stop
 
   ###*
   [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)
+  Both the form and the changed field will be assigned a CSS class [`form-up-active`](/form-up-active)
   while the autosubmitted form is processing.
 
-  The unobtrusive variant of this is the [`up-autosubmit`](/up-autosubmit) attribute.
+  The unobtrusive variant of this is the [`up-autosubmit`](/form-up-autosubmit) attribute.
 
   @function up.autosubmit
-  @param {String|Element|jQuery} selectorOrElement
+  @param {string|Element|jQuery} selectorOrElement
     The field or form to observe.
   @param {Object} [options]
     See options for [`up.observe()`](/up.observe)
@@ -329,15 +300,14 @@ up.form = (($) ->
     target
 
   ###*
-  Performs a server-side validation of a form and update the form
-  with validation messages.
+  Performs a server-side validation of a form field.
 
   `up.validate()` submits the given field's form with an additional `X-Up-Validate`
   HTTP header. Upon seeing this header, the server is expected to validate (but not save)
   the form submission and render a new copy of the form with validation errors.
 
-  The unobtrusive variant of this is the [`[up-validate]`](/up-validate) selector.
-  See the documentation for [`[up-validate]`](/up-validate) for more information
+  The unobtrusive variant of this is the [`input[up-validate]`](/input-up-validate) selector.
+  See the documentation for [`input[up-validate]`](/input-up-validate) for more information
   on how server-side validation works in Unpoly.
 
   \#\#\# Example
@@ -345,11 +315,11 @@ up.form = (($) ->
       up.validate('input[name=email]', { target: '.email-errors' })
 
   @function up.validate
-  @param {String|Element|jQuery} fieldOrSelector
+  @param {string|Element|jQuery} fieldOrSelector
 
-  @param {String|Element|jQuery} [options.target]
+  @param {string|Element|jQuery} [options.target]
   @return {Promise}
-    A promise that is resolved when the server-side
+    A promise that is fulfilled when the server-side
     validation is received and the form was updated.
   @stable
   ###
@@ -399,15 +369,15 @@ up.form = (($) ->
   ###*
   Shows or hides a target selector depending on the value.
 
-  See [`[up-switch]`](/up-switch) for more documentation and examples.
+  See [`input[up-switch]`](/input-up-switch) for more documentation and examples.
 
   This function does not currently have a very useful API outside
   of our use for `up-switch`'s UJS behavior, that's why it's currently
   still marked `@internal`.
 
   @function up.form.switchTargets
-  @param {String|Element|jQuery} fieldOrSelector
-  @param {String} [options.target]
+  @param {string|Element|jQuery} fieldOrSelector
+  @param {string} [options.target]
     The target selectors to switch.
     Defaults to an `up-switch` attribute on the given field.
   @internal
@@ -474,7 +444,7 @@ up.form = (($) ->
   it will usually re-render an updated copy of the form with
   validation messages.
 
-  For Unpoly to be able to detect a failed form submission,,
+  For Unpoly to be able to detect a failed form submission,
   the form must be re-rendered with a non-200 HTTP status code.
   We recommend to use either 400 (bad request) or
   422 (unprocessable entity).
@@ -497,8 +467,8 @@ up.form = (($) ->
 
       end
 
-  Note that you can also use the
-  [`up-validate`](/up-validate) attribute to perform server-side
+  Note that you can also use
+  [`input[up-validate]`](/input-up-validate) to perform server-side
   validations while the user is completing fields.
 
   \#\#\# Redirects
@@ -514,7 +484,7 @@ up.form = (($) ->
 
   \#\#\# Giving feedback while the form is processing
 
-  The `<form>` element will be assigned a CSS class `up-active` while
+  The `<form>` element will be assigned a CSS class [`up-active`](/form.up-active) while
   the submission is loading.
 
   You can also [implement a spinner](/up.proxy/#spinners)
@@ -522,17 +492,17 @@ up.form = (($) ->
   and [`up:proxy:recover`](/up:proxy:recover) events.
 
   @selector form[up-target]
-  @param {String} up-target
+  @param {string} up-target
     The selector to [replace](/up.replace) if the form submission is successful (200 status code).
-  @param {String} [up-fail-target]
+  @param {string} [up-fail-target]
     The selector to [replace](/up.replace) if the form submission is not successful (non-200 status code).
     If omitted, Unpoly will replace the `<form>` tag itself, assuming that the
     server has echoed the form with validation errors.
   @param [up-fallback]
     The selector to replace if the server responds with a non-200 status code.
-  @param {String} [up-transition]
+  @param {string} [up-transition]
     The animation to use when the form is replaced after a successful submission.
-  @param {String} [up-fail-transition]
+  @param {string} [up-fail-transition]
     The animation to use when the form is replaced after a failed submission.
   @param [up-history]
     Whether to push a browser history entry after a successful form submission.
@@ -542,27 +512,27 @@ up.form = (($) ->
 
     Set this to `'false'` to prevent the URL bar from being updated.
     Set this to a URL string to update the history with the given URL.
-  @param {String} [up-method]
+  @param {string} [up-method]
     The HTTP method to be used to submit the form (`get`, `post`, `put`, `delete`, `patch`).
     Alternately you can use an attribute `data-method`
     ([Rails UJS](https://github.com/rails/jquery-ujs/wiki/Unobtrusive-scripting-support-for-jQuery))
     or `method` (vanilla HTML) for the same purpose.
-  @param {String} [up-layer='auto']
+  @param {string} [up-layer='auto']
     The name of the layer that ought to be updated. Valid values are
     `auto`, `page`, `modal` and `popup`.
 
     If set to `auto` (default), Unpoly will try to find a match in the form's layer.
     If no match was found in that layer,
     Unpoly will search in other layers, starting from the topmost layer.
-  @param {String} [up-fail-layer='auto']
+  @param {string} [up-fail-layer='auto']
     The name of the layer that ought to be updated if the server sends a
     non-200 status code.
-  @param {String} [up-reveal='true']
+  @param {string} [up-reveal='true']
     Whether to reveal the target element within its viewport before updating.
-  @param {String} [up-restore-scroll='false']
+  @param {string} [up-restore-scroll='false']
     Whether to restore previously known scroll position of all viewports
     within the target selector.
-  @param {String} [up-cache]
+  @param {string} [up-cache]
     Whether to force the use of a cached response (`true`)
     or never use the cache (`false`)
     or make an educated guess (`undefined`).
@@ -712,8 +682,8 @@ up.form = (($) ->
   In order to update the `department` field in addition to the `employee` field, you could say
   `up-validate="&, [name=employee]"`, or simply `up-validate="form"` to update the entire form.
 
-  @selector [up-validate]
-  @param {String} up-validate
+  @selector input[up-validate]
+  @param {string} up-validate
     The CSS selector to update with the server response.
 
     This defaults to a fieldset or form group around the validating field.
@@ -723,11 +693,11 @@ up.form = (($) ->
     validate($field)
 
   ###*
-  Show or hide part of a form if certain options are selected or boxes are checked.
+  Show or hide elements when a `<select>` or `<input>` has a given value.
 
-  \#\#\# Example
+  \#\#\# Example: Select options
 
-  The triggering input gets an `up-switch` attribute with a selector for the elements to show or hide:
+  The controlling form field gets an `up-switch` attribute with a selector for the elements to show or hide:
 
       <select name="advancedness" up-switch=".target">
         <option value="basic">Basic parts</option>
@@ -735,7 +705,8 @@ up.form = (($) ->
         <option value="very-advanced">Very advanced parts</option>
       </select>
 
-  The target elements get a space-separated list of select values for which they are shown or hidden:
+  The target elements can use [`[up-show-for]`](/up-show-for) and [`[up-hide-for]`](/up-hide-for)
+  attributes to indicate for which values they should be shown or hidden:
 
       <div class="target" up-show-for="basic">
         only shown for advancedness = basic
@@ -749,63 +720,66 @@ up.form = (($) ->
         shown for advancedness = advanced or very-advanced
       </div>
 
-  For checkboxes you can also use the pseudo-values `:checked` or `:unchecked` like so:
+  \#\#\# Example: Text field
 
-      <input type="checkbox" name="flag" up-switch=".target">
+  The controlling `<input>` gets an `up-switch` attribute with a selector for the elements to show or hide:
 
-      <div class="target" up-show-for=":checked">
-        only shown when checkbox is checked
+      <input type="text" name="user" up-switch=".target">
+
+      <div class="target" up-show-for="alice">
+        only shown for user alice
       </div>
 
   You can also use the pseudo-values `:blank` to match an empty input value,
   or `:present` to match a non-empty input value:
 
-      <input type="text" name="email" up-switch=".target">
+      <input type="text" name="user" up-switch=".target">
 
       <div class="target" up-show-for=":blank">
-        please enter an email address
+        please enter a username
       </div>
 
-  @selector [up-switch]
-  @stable
-  ###
+  \#\#\# Example: Checkbox
 
-  ###*
-  Show this element only if a form field has a given value.
+  For checkboxes you can match against the pseudo-values `:checked` or `:unchecked`:
 
-  See [`[up-switch]`](/up-switch) for more documentation and examples.
+      <input type="checkbox" name="flag" up-switch=".target">
 
-  @selector [up-show-for]
-  @param up-show-for
-    A space-separated list of values for which to show this element.
-  @stable
-  ###
+      <div class="target" up-show-for=":checked">
+        only shown when checkbox is checked
+      </div>
 
-  ###*
-  Hide this element if a form field has a given value.
+      <div class="target" up-show-for=":cunhecked">
+        only shown when checkbox is unchecked
+      </div>
+
+  Of course you can also match against the `value` property of the checkbox element:
 
-  See [`[up-switch]`](/up-switch) for more documentation and examples.
+      <input type="checkbox" name="flag" value="active" up-switch=".target">
 
-  @selector [up-hide-for]
-  @param up-hide-for
-    A space-separated list of values for which to hide this element.
+      <div class="target" up-show-for="active">
+        only shown when checkbox is checked
+      </div>
+
+  @selector input[up-switch]
+  @param {string} up-switch
+    A CSS selector for elements whose visibility depends on this field's value.
   @stable
   ###
-
-  up.on 'change', '[up-switch]', (event, $field) ->
+  up.compiler '[up-switch]', ($field) ->
     switchTargets($field)
 
-  up.compiler '[up-switch]', ($field) ->
+  up.on 'change', '[up-switch]', (event, $field) ->
     switchTargets($field)
 
   up.compiler '[up-show-for]:not(.up-switched), [up-hide-for]:not(.up-switched)', ($element) ->
     switchTarget($element)
 
-
   ###*
-  Observes this field or form and runs a callback when a value changes.
+  Observes this field and runs a callback when a value changes.
 
   This is useful for observing text fields while the user is typing.
+  If you want to submit the form after a change see [`input[up-autosubmit]`](/input-up-autosubmit).
 
   The programmatic variant of this is the [`up.observe()`](/up.observe) function.
 
@@ -818,7 +792,35 @@ up.form = (($) ->
         <input name="query" up-observe="showSuggestions(value)">
       </form>
 
-  The following would run a global `somethingChanged(value)` function
+  \#\#\# Callback context
+
+  The script given to `up-observe` runs with the following context:
+
+  | Name     | Type      | Description                           |
+  | -------- | --------- | ------------------------------------- |
+  | `value`  | `string`  | The current value of the field        |
+  | `this`   | `Element` | The form field                        |
+  | `$field` | `jQuery`  | The form field as a jQuery collection |
+
+  @selector input[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
+  ###
+
+  ###*
+  Observes this form and runs a callback when any field changes.
+
+  This is useful for observing text fields while the user is typing.
+  If you want to submit the form after a change see [`input[up-autosubmit]`](/input-up-autosubmit).
+
+  The programmatic variant of this is the [`up.observe()`](/up.observe) function.
+
+  \#\#\# Example
+
+  The would call a function `somethingChanged(value)`
   when any `<input>` within the `<form>` changes:
 
       <form up-observe="somethingChanged(value)">
@@ -832,47 +834,62 @@ up.form = (($) ->
 
   | Name     | Type      | Description                           |
   | -------- | --------- | ------------------------------------- |
-  | `value`  | `String`  | The current value of the field        |
+  | `value`  | `string`  | The current value of the field        |
   | `this`   | `Element` | The form field                        |
   | `$field` | `jQuery`  | The form field as a jQuery collection |
 
-  @selector [up-observe]
-  @param {String} up-observe
-    The code to run when the field's value changes.
-  @param {String} up-delay
+  @selector form[up-observe]
+  @param {string} up-observe
+    The code to run when any 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]', ($formOrField) -> observe($formOrField)
 
   ###*
-  [Observes](/up.observe) this field or form and submits the form when a value changes.
+  [Observes](/up.observe) this form field and submits the form when its value changes.
 
-  The form field will be assigned a CSS class [`up-active`](/up-active)
-  while the autosubmitted form is processing.
+  Both the form and the changed field will be assigned a CSS class [`up-active`](/form-up-active)
+  while the autosubmitted form is loading.
 
   The programmatic variant of this is the [`up.autosubmit()`](/up.autosubmit) function.
 
   \#\#\# Example
 
-  The following would submit the form when either query or checkbox was changed:
+  The following would automatically submit the form when the query is changed:
 
-      <form method="GET" action="/search" up-autosubmit>
-        <input type="search" name="query">
+      <form method="GET" action="/search">
+        <input type="search" name="query" up-autosubmit>
         <input type="checkbox" name="archive"> Include archive
       </form>
 
-  The following would submit the form only if the query was changed,
-  but not if the checkbox was changed:
+  @selector input[up-autosubmit]
+  @param {string} up-delay
+    The number of miliseconds to wait after a change before the form is submitted.
+  @stable
+  ###
 
-      <form method="GET" action="/search">
-        <input type="search" name="query" up-autosubmit>
+  ###*
+  [Observes](/up.observe) this form and submits the form when *any* field changes.
+
+  Both the form and the field will be assigned a CSS class [`up-active`](/form-up-active)
+  while the autosubmitted form is loading.
+
+  The programmatic variant of this is the [`up.autosubmit()`](/up.autosubmit) function.
+
+  \#\#\# Example
+
+  This will submit the form when either query or checkbox was changed:
+
+      <form method="GET" action="/search" up-autosubmit>
+        <input type="search" name="query">
         <input type="checkbox" name="archive"> Include archive
       </form>
 
-  @selector [up-autosubmit]
-  @param {String} up-delay
-    The number of miliseconds to wait after the change before the form is submitted.
+  @selector form[up-autosubmit]
+  @param {string} up-delay
+    The number of miliseconds to wait after a change before the form is submitted.
   @stable
   ###
   up.compiler '[up-autosubmit]', ($formOrField) -> autosubmit($formOrField)