unpoly-rails 0.62.1 → 2.0.0.pre.rc2

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

@@ -1,1075 +0,0 @@
-###**
-Forms
-=====
-  
-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.
-
-@module up.form
-###
-up.form = do ->
-  
-  u = up.util
-  e = up.element
-
-  ###**
-  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
-    will be updated with the validation messages from the server.
-
-    By default this looks for a `<fieldset>`, `<label>` or `<form>`
-    around the validating input field.
-  @param {string} [config.fields]
-    An array of CSS selectors that represent form fields, such as `input` or `select`.
-  @param {string} [config.submitButtons]
-    An array of CSS selectors that represent submit buttons, such as `input[type=submit]`.
-  @stable
-  ###
-  config = new up.Config
-    validateTargets: ['[up-fieldset]:has(&)', 'fieldset:has(&)', 'label:has(&)', 'form:has(&)']
-    fields: ['select', 'input:not([type=submit]):not([type=image])', 'button[type]:not([type=submit])', 'textarea'],
-    submitButtons: ['input[type=submit]', 'input[type=image]', 'button[type=submit]', 'button:not([type])']
-    observeDelay: 0
-
-  reset = ->
-    config.reset()
-
-  ###**
-  @function up.form.fieldSelector
-  @internal
-  ###
-  fieldSelector = (suffix = '') ->
-    config.fields.map((field) -> field + suffix).join(',')
-
-  ###**
-  Returns a list of form fields within the given element.
-
-  You can configure what Unpoly considers a form field by adding CSS selectors to the
-  [`up.form.config.fields`](/up.form.config#config.fields) array.
-
-  If the given element is itself a form field, a list of that given element is returned.
-
-  @function up.form.fields
-  @param {Element|jQuery} root
-    The element to scan for contained form fields.
-
-    If the element is itself a form field, a list of that element is returned.
-  @return {NodeList<Element>|Array<Element>}
-  @experimental
-  ###
-  findFields = (root) ->
-    root = e.get(root)
-    fields = e.subtree(root, fieldSelector())
-    if e.matches(root, 'form[id]')
-      outsideFieldSelector = fieldSelector(e.attributeSelector('form', root.id))
-      outsideFields = e.all(outsideFieldSelector)
-      fields.push(outsideFields...)
-      fields = u.uniq(fields)
-    fields
-
-#  findFields = (rootOrRoots) ->
-#    rootOrRoots = e.list(rootOrRoots)
-#    u.flatMap rootOrRoots, (root) -> e.subtree(root, fieldSelector())
-
-  ###***
-  @function up.form.submissionFields
-  @internal
-  ###
-  findSubmissionFields = (root) ->
-    fields = findFields(root)
-    if button = submittingButton(root)
-      fields = u.toArray(fields)
-      fields.push(button)
-    fields
-
-  ###**
-  @function up.form.submittingButton
-  @internal
-  ###
-  submittingButton = (form) ->
-    selector = submitButtonSelector()
-    focusedElement = document.activeElement
-    if focusedElement && e.matches(focusedElement, selector) && form.contains(focusedElement)
-      return focusedElement
-    else
-      # If no button is focused, we assume the first button in the form.
-      return e.first(form, selector)
-
-  ###**
-  @function up.form.submitButtonSelector
-  @internal
-  ###
-  submitButtonSelector = ->
-    config.submitButtons.join(',')
-
-  ###**
-  Submits a form via AJAX and updates a page fragment with the response.
-
-      up.submit('form.new-user', { target: '.main' })
-  
-  Instead of loading a new page, the form is submitted via AJAX.
-  The response is parsed for a CSS selector and the matching elements will
-  replace corresponding elements on the current page.
-
-  The unobtrusive variant of this is the [`form[up-target]`](/form-up-target) selector.
-  See the documentation for [`form[up-target]`](/form-up-target) for more
-  information on how AJAX form submissions work in Unpoly.
-
-  Emits the event [`up:form:submit`](/up:form:submit).
-
-  @function up.submit
-  @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]
-    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']
-    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]
-    The CSS selector to update when the form submission succeeds (server responds with status 200).
-    Defaults to the form's `up-target` attribute.
-
-    Inside the CSS selector you may refer to the form as `&` ([like in Sass](https://sass-lang.com/documentation/file.SASS_REFERENCE.html#parent-selector)).
-  @param {string} [options.failTarget]
-    The CSS 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.
-
-    Inside the CSS selector you may refer to the form as `&` ([like in Sass](https://sass-lang.com/documentation/file.SASS_REFERENCE.html#parent-selector)).
-  @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]
-    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']
-    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']
-    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]
-    The duration of the transition. See [`up.morph()`](/up.morph).
-  @param {number} [options.delay]
-    The delay before the transition starts. See [`up.morph()`](/up.morph).
-  @param {string} [options.easing]
-    The timing function that controls the transition's acceleration. [`up.morph()`](/up.morph).
-  @param {Element|string} [options.reveal=true]
-    Whether to reveal the target fragment after it was replaced.
-
-    You can also pass a CSS selector for the element to reveal.
-  @param {boolean|string} [options.failReveal=true]
-    Whether to [reveal](/up.reveal) the target fragment when the server responds with an error.
-
-    You can also pass a CSS selector for the element to reveal.
-  @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]
-    Whether to force the use of a cached response (`true`)
-    or never use the cache (`false`)
-    or make an educated guess (`undefined`).
-
-    By default only responses to `GET` requests are cached
-    for a few minutes.
-  @param {Object} [options.headers={}]
-    An object of additional header key/value pairs to send along
-    with the request.
-  @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']
-    The name of the layer that ought to be updated if the server sends a non-200 status code.
-  @param {Object|FormData|string|Array|up.Params} [options.params]
-    Extra form [parameters](/up.Params) that will be submitted in addition to
-    the parameters from the form.
-  @return {Promise}
-    A promise for the successful form submission.
-  @stable
-  ###
-  submit = (formOrSelector, options) ->
-    options = u.options(options)
-
-    form = e.get(formOrSelector)
-    form = e.closest(form, 'form')
-
-    target = options.target ? form.getAttribute('up-target') ? 'body'
-    options.failTarget ?= form.getAttribute('up-fail-target') ? e.toSelector(form)
-    options.reveal ?= e.booleanOrStringAttr(form, 'up-reveal') ? true
-    options.failReveal ?= e.booleanOrStringAttr(form, 'up-fail-reveal') ? true
-    options.fallback ?= form.getAttribute('up-fallback')
-    options.history ?= e.booleanOrStringAttr(form, 'up-history') ? true
-    options.transition ?= e.booleanOrStringAttr(form, 'up-transition')
-    options.failTransition ?= e.booleanOrStringAttr(form, 'up-fail-transition')
-    options.method ?= u.normalizeMethod(form.getAttribute('up-method') ? form.getAttribute('data-method') ? form.getAttribute('method') ? 'post')
-    options.cache ?= e.booleanAttr(form, 'up-cache')
-    options.restoreScroll ?= e.booleanAttr(form, 'up-restore-scroll') # the option supports an object value, but not the attr
-    options.origin ?= form
-    options.layer ?= form.getAttribute('up-layer')
-    options.failLayer ?= form.getAttribute('up-fail-layer')
-
-    # Take params from form, but allow to pass additional params as { params }
-    options.params = up.Params.fromForm(form).addAll(options.params)
-
-    options = u.merge(options, up.motion.animateOptions(options, form))
-
-    if options.validate
-      options.headers ||= {}
-      options.transition = false
-      options.failTransition = false
-      options.headers[up.protocol.config.validateHeader] = options.validate
-
-    url = options.url ? form.getAttribute('action') ? up.browser.url()
-
-    if options.method == 'GET'
-      # Only for GET forms, browsers discard all query params from the form's [action] URL.
-      # The URLs search part will be replaced with the serialized form data.
-      # See design/query-params-in-form-actions/cases.html for
-      # a demo of vanilla browser behavior.
-      url = up.Params.stripURL(url)
-
-    up.event.whenEmitted('up:form:submit', log: 'Submitting form', target: form).then ->
-      up.feedback.start(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.submit()
-        return u.unresolvablePromise()
-
-      promise = up.replace(target, url, options)
-      u.always promise, -> up.feedback.stop(form)
-      promise
-
-  ###**
-  This event is [emitted](/up.emit) when a form is [submitted](/up.submit) through Unpoly.
-
-  The event is emitted on the`<form>` element.
-
-  @event up:form:submit
-  @param {Element} event.target
-    The `<form>` element that will be submitted.
-  @param event.preventDefault()
-    Event listeners may call this method to prevent the form from being submitted.
-  @stable
-  ###
-
-  ###**
-  Observes form fields and runs a callback when a value changes.
-
-  This is useful for observing text fields while the user is typing.
-
-  The unobtrusive variant of this is the [`[up-observe]`](/up-observe) attribute.
-
-  \#\#\# Example
-
-  The following would print to the console whenever an input field changes:
-
-      up.observe('input.query', function(value) {
-        console.log('Query is now %o', value)
-      })
-
-  Instead of a single form field, you can also pass multiple fields,
-  a `<form>` or any container that contains form fields.
-  The callback will be run if any of the given fields change:
-
-      up.observe('form', function(value, name) {
-        console.log('The value of %o is now %o', name, value)
-      })
-
-  You may also pass the `{ batch: true }` option to receive all
-  changes since the last callback in a single object:
-
-      up.observe('form', { batch: true }, function(diff) {
-        console.log('Observed one or more changes: %o', diff)
-      })
-
-  @function up.observe
-  @param {string|Element|Array<Element>|jQuery} elements
-    The form fields that will 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 {boolean} [options.batch=false]
-    If set to `true`, the `onChange` callback will receive multiple
-    detected changes in a single diff object as its argument.
-  @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, name): string} onChange
-    The callback to run when the field's value changes.
-
-    If given as a function, it receives two arguments (`value`, `name`).
-    `value` is a string with the new attribute value and `string` is the name
-    of the form field that changed.
-
-    If given as a string, it will be evaled as JavaScript code in a context where
-    (`value`, `name`) are set.
-  @return {Function()}
-    A destructor function that removes the observe watch when called.
-  @stable
-  ###
-  observe = (elements, args...) ->
-    elements = e.list(elements)
-    fields = u.flatMap(elements, findFields)
-    callback = u.extractCallback(args) ? observeCallbackFromElement(elements[0]) ? up.fail('up.observe: No change callback given')
-    options = u.extractOptions(args)
-    options.delay = options.delay ? e.numberAttr(elements[0], 'up-delay') ? config.observeDelay
-    observer = new up.FieldObserver(fields, options, callback)
-    observer.start()
-    return observer.stop
-
-  observeCallbackFromElement = (element) ->
-    if rawCallback = element.getAttribute('up-observe')
-      new Function('value', 'name', rawCallback)
-
-  ###**
-  [Observes](/up.observe) a field or form and submits the form when a value changes.
-
-  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`](/form-up-autosubmit) attribute.
-
-  @function up.autosubmit
-  @param {string|Element|jQuery} selectorOrElement
-    The field or form 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) ->
-    observe(selectorOrElement, options, -> submit(selectorOrElement))
-
-  findValidateTarget = (field, options) ->
-    option = options.target ? field.getAttribute('up-validate')
-    option ||= u.findResult config.validateTargets, (defaultTarget) ->
-      resolvedDefault = e.resolveSelector(defaultTarget, options.origin)
-      if e.first(resolvedDefault)
-        # We want to return the selector, *not* the element. If we returned the element
-        # and derive a selector from that, any :has() expression would be lost.
-        return resolvedDefault
-
-    unless option
-      up.fail('Could not find validation target for %o (tried defaults %o)', field, config.validateTargets)
-
-    # resolveSelector() also creates a selector string if given an element
-    return e.resolveSelector(option, options.origin)
-
-  ###**
-  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 [`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
-
-      up.validate('input[name=email]', { target: '.email-errors' })
-
-  @function up.validate
-  @param {string|Element|jQuery} fieldOrSelector
-
-  @param {string|Element|jQuery} [options.target]
-  @return {Promise}
-    A promise that is fulfilled when the server-side
-    validation is received and the form was updated.
-  @stable
-  ###
-  validate = (fieldOrSelector, options) ->
-    field = e.get(fieldOrSelector)
-    options = u.options(options)
-    options.origin = field
-    options.target = findValidateTarget(field, options)
-    options.failTarget = options.target
-    options.reveal ?= e.booleanOrStringAttr(field, 'up-reveal') ? false
-    options.history = false
-    # Make sure the X-Up-Validate header is present, so the server-side
-    # knows that it should not persist the form submission
-    options.validate = field.getAttribute('name') || ':none'
-    options = u.merge(options, up.motion.animateOptions(options, field))
-    promise = up.submit(field, options)
-    promise
-
-  switcherValues = (field) ->
-    value = undefined
-    meta = undefined
-
-    if e.matches(field, 'input[type=checkbox]')
-      if field.checked
-        value = field.value
-        meta = ':checked'
-      else
-        meta = ':unchecked'
-    else if e.matches(field, 'input[type=radio]')
-      form = closestContainer(field)
-      groupName = field.getAttribute('name')
-      checkedButton = form.querySelector("input[type=radio]#{e.attributeSelector('name', groupName)}:checked")
-      if checkedButton
-        meta = ':checked'
-        value = checkedButton.value
-      else
-        meta = ':unchecked'
-    else
-      value = field.value
-
-    values = []
-    if u.isPresent(value)
-      values.push(value)
-      values.push(':present')
-    else
-      values.push(':blank')
-    if u.isPresent(meta)
-      values.push(meta)
-    values
-
-  ###**
-  Shows or hides a target selector depending on the value.
-
-  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 {Element} switcher
-  @param {string} [options.target]
-    The target selectors to switch.
-    Defaults to an `[up-switch]` attribute on the given field.
-  @internal
-  ###
-  switchTargets = (switcher, options = {}) ->
-    targetSelector = options.target ? switcher.getAttribute('up-switch')
-    form = closestContainer(switcher)
-    u.isPresent(targetSelector) or up.fail("No switch target given for %o", switcher)
-    fieldValues = switcherValues(switcher)
-
-    u.each e.all(form, targetSelector), (target) ->
-      switchTarget(target, fieldValues)
-
-  ###**
-  @internal
-  ###
-  switchTarget = (target, fieldValues) ->
-    fieldValues ||= switcherValues(findSwitcherForTarget(target))
-
-    if hideValues = target.getAttribute('up-hide-for')
-      hideValues = u.splitValues(hideValues)
-      show = u.intersect(fieldValues, hideValues).length == 0
-    else
-      if showValues = target.getAttribute('up-show-for')
-        showValues = u.splitValues(showValues)
-      else
-        # If the target has neither up-show-for or up-hide-for attributes,
-        # assume the user wants the target to be visible whenever anything
-        # is checked or entered.
-        showValues = [':present', ':checked']
-      show = u.intersect(fieldValues, showValues).length > 0
-
-    e.toggle(target, show)
-    target.classList.add('up-switched')
-
-  ###**
-  @internal
-  ###
-  findSwitcherForTarget = (target) ->
-    form = closestContainer(target)
-    switchers = e.all(form, '[up-switch]')
-    switcher = u.find switchers, (switcher) ->
-      targetSelector = switcher.getAttribute('up-switch')
-      e.matches(target, targetSelector)
-    return switcher or u.fail('Could not find [up-switch] field for %o', target)
-
-  closestContainer = (element) ->
-    e.closest(element, 'form, body')
-
-  ###**
-  Forms with an `up-target` attribute are [submitted via AJAX](/up.submit)
-  instead of triggering a full page reload.
-
-      <form method="post" action="/users" up-target=".main">
-        ...
-      </form>
-
-  The server response is searched for the selector given in `up-target`.
-  The selector content is then [replaced](/up.replace) in the current page.
-
-  The programmatic variant of this is the [`up.submit()`](/up.submit) function.
-
-  \#\#\# Failed submission
-
-  When the server was unable to save the form due to invalid params,
-  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,
-  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).
-
-  In Ruby on Rails, you can pass a
-  [`:status` option to `render`](http://guides.rubyonrails.org/layouts_and_rendering.html#the-status-option)
-  for this:
-
-      class UsersController < ApplicationController
-
-        def create
-          user_params = params[:user].permit(:email, :password)
-          @user = User.new(user_params)
-          if @user.save?
-            sign_in @user
-          else
-            render 'form', status: :bad_request
-          end
-        end
-
-      end
-
-  Note that you can also use
-  [`input[up-validate]`](/input-up-validate) to perform server-side
-  validations while the user is completing fields.
-
-  \#\#\# Redirects
-
-  Unpoly requires an additional response header to detect redirects,
-  which are otherwise undetectable for an AJAX client.
-
-  After the form's action performs a redirect, the next response should echo
-  the new request's URL as a response header `X-Up-Location`.
-
-  If you are using Unpoly via the `unpoly-rails` gem, these headers
-  are set automatically for every request.
-
-  \#\#\# Giving feedback while the form is processing
-
-  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)
-  by [listening](/up.on) to the [`up:proxy:slow`](/up:proxy:slow)
-  and [`up:proxy:recover`](/up:proxy:recover) events.
-
-  @selector form[up-target]
-  @param {string} up-target
-    The CSS selector to [replace](/up.replace) if the form submission is successful (200 status code).
-
-    Inside the CSS selector you may refer to this form as `&` ([like in Sass](https://sass-lang.com/documentation/file.SASS_REFERENCE.html#parent-selector)).
-  @param {string} [up-fail-target]
-    The CSS selector to [replace](/up.replace) if the form submission is not successful (non-200 status code).
-
-    Inside the CSS selector you may refer to this form as `&` ([like in Sass](https://sass-lang.com/documentation/file.SASS_REFERENCE.html#parent-selector)).
-
-    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 an error.
-  @param {string} [up-transition]
-    The animation to use when the form is replaced after a successful submission.
-  @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.
-
-    By default the form's target URL is used. If the form redirects to another URL,
-    the redirect target will be used.
-
-    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]
-    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']
-    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']
-    The name of the layer that ought to be updated if the server sends a
-    non-200 status code.
-  @param {string} [up-reveal='true']
-    Whether to reveal the target element after it was replaced.
-
-    You can also pass a CSS selector for the element to reveal.
-    Inside the CSS selector you may refer to the form as `&` ([like in Sass](https://sass-lang.com/documentation/file.SASS_REFERENCE.html#parent-selector)).
-  @param {string} [up-fail-reveal='true']
-    Whether to reveal the target element when the server responds with an error.
-
-    You can also pass a CSS selector for the element to reveal. You may use this, for example,
-    to reveal the first validation error message:
-
-        <form up-target=".content" up-fail-reveal=".error">
-          ...
-        </form>
-
-    Inside the CSS selector you may refer to the form as `&` ([like in Sass](https://sass-lang.com/documentation/file.SASS_REFERENCE.html#parent-selector)).
-  @param {string} [up-restore-scroll='false']
-    Whether to restore previously known scroll position of all viewports
-    within the target selector.
-  @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`).
-
-    By default only responses to `GET` requests are cached for a few minutes.
-  @stable
-  ###
-  up.on 'submit', 'form[up-target]', (event, form) ->
-    up.event.consumeAction(event)
-    u.muteRejection submit(form)
-
-  ###**
-  When a form field with this attribute is changed, the form is validated on the server
-  and is updated with validation messages.
-
-  To validate the form, Unpoly will submit the form with an additional `X-Up-Validate` HTTP header.
-  When 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 programmatic variant of this is the [`up.validate()`](/up.validate) function.
-
-  \#\#\# Example
-
-  Let's look at a standard registration form that asks for an e-mail and password:
-
-      <form action="/users">
-
-        <label>
-          E-mail: <input type="text" name="email" />
-        </label>
-
-        <label>
-          Password: <input type="password" name="password" />
-        </label>
-
-        <button type="submit">Register</button>
-
-      </form>
-
-  When the user changes the `email` field, we want to validate that
-  the e-mail address is valid and still available. Also we want to
-  change the `password` field for the minimum required password length.
-  We can do this by giving both fields an `up-validate` attribute:
-
-      <form action="/users">
-
-        <label>
-          E-mail: <input type="text" name="email" up-validate />
-        </label>
-
-        <label>
-          Password: <input type="password" name="password" up-validate />
-        </label>
-
-        <button type="submit">Register</button>
-
-      </form>
-
-  Whenever a field with `up-validate` changes, the form is POSTed to
-  `/users` with an additional `X-Up-Validate` HTTP header.
-  When 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.
-
-  In Ruby on Rails the processing action should behave like this:
-
-      class UsersController < ApplicationController
-
-        # This action handles POST /users
-        def create
-          user_params = params[:user].permit(:email, :password)
-          @user = User.new(user_params)
-          if request.headers['X-Up-Validate']
-            @user.valid?  # run validations, but don't save to the database
-            render 'form' # render form with error messages
-          elsif @user.save?
-            sign_in @user
-          else
-            render 'form', status: :bad_request
-          end
-        end
-
-      end
-
-  Note that if you're using the `unpoly-rails` gem you can simply say `up.validate?`
-  instead of manually checking for `request.headers['X-Up-Validate']`.
-
-  The server now renders an updated copy of the form with eventual validation errors:
-
-      <form action="/users">
-
-        <label class="has-error">
-          E-mail: <input type="text" name="email" value="foo@bar.com" />
-          Has already been taken!
-        </label>
-
-        <button type="submit">Register</button>
-
-      </form>
-
-  The `<label>` around the e-mail field is now updated to have the `has-error`
-  class and display the validation message.
-
-  \#\#\# How validation results are displayed
-
-  Although the server will usually respond to a validation with a complete,
-  fresh copy of the form, Unpoly will by default not update the entire form.
-  This is done in order to preserve volatile state such as the scroll position
-  of `<textarea>` elements.
-
-  By default Unpoly looks for a `<fieldset>`, `<label>` or `<form>`
-  around the validating input field, or any element with an
-  `up-fieldset` attribute.
-  With the Bootstrap bindings, Unpoly will also look
-  for a container with the `form-group` class.
-
-  You can change this default behavior by setting [`up.form.config.validateTargets`](/up.form.config#config.validateTargets):
-
-      // Always update the entire form containing the current field ("&")
-      up.form.config.validateTargets = ['form &']
-
-  You can also individually override what to update by setting the `up-validate`
-  attribute to a CSS selector:
-
-      <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
-  when one fields depends on the value of another field.
-
-  Let's say you have a form with one `<select>` to pick a department (sales, engineering, ...)
-  and another `<select>` to pick an employeee from the selected department:
-
-      <form action="/contracts">
-        <select name="department">...</select> <!-- options for all departments -->
-        <select name="employeed">...</select> <!-- options for employees of selected department -->
-      </form>
-
-  The list of employees needs to be updated as the appartment changes:
-
-      <form action="/contracts">
-        <select name="department" up-validate="[name=employee]">...</select>
-        <select name="employee">...</select>
-      </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 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.
-  @stable
-  ###
-
-  ###**
-  Performs [server-side validation](/input-up-validate) when any fieldset within this form changes.
-
-  You can configure what Unpoly considers a fieldset by adding CSS selectors to the
-  [`up.form.config.validateTargets`](/up.form.config#config.validateTargets) array.
-
-  @selector form[up-validate]
-  @stable
-  ###
-  up.on 'change', '[up-validate]', (event) ->
-    field = findFields(event.target)[0]
-    u.muteRejection validate(field)
-
-  ###**
-  Show or hide elements when a `<select>` or `<input>` has a given value.
-
-  \#\#\# Example: Select options
-
-  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>
-        <option value="advanced">Advanced parts</option>
-        <option value="very-advanced">Very advanced parts</option>
-      </select>
-
-  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
-      </div>
-
-      <div class="target" up-hide-for="basic">
-        hidden for advancedness = basic
-      </div>
-
-      <div class="target" up-show-for="advanced very-advanced">
-        shown for advancedness = advanced or very-advanced
-      </div>
-
-  \#\#\# Example: Text field
-
-  The controlling `<input>` gets an `up-switch` attribute with a selector for the elements to show or hide:
-
-      <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="user" up-switch=".target">
-
-      <div class="target" up-show-for=":blank">
-        please enter a username
-      </div>
-
-  \#\#\# Example: Checkbox
-
-  For checkboxes you can match against the pseudo-values `:checked` or `:unchecked`:
-
-      <input type="checkbox" name="flag" up-switch=".target">
-
-      <div class="target" up-show-for=":checked">
-        only shown when checkbox is checked
-      </div>
-
-      <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:
-
-      <input type="checkbox" name="flag" value="active" up-switch=".target">
-
-      <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
-  ###
-
-  ###**
-  Only shows this element if an input field with [`[up-switch]`](/input-up-switch) has one of the given values.
-
-  See [`input[up-switch]`](/input-up-switch) for more documentation and examples.
-
-  @selector [up-show-for]
-  @param {string} [up-show-for]
-    A space-separated list of input values for which this element should be shown.
-  @stable
-  ###
-
-  ###**
-  Hides this element if an input field with [`[up-switch]`](/input-up-switch) has one of the given values.
-
-  See [`input[up-switch]`](/input-up-switch) for more documentation and examples.
-
-  @selector [up-hide-for]
-  @param {string} [up-hide-for]
-    A space-separated list of input values for which this element should be hidden.
-  @stable
-  ###
-  up.compiler '[up-switch]', (switcher) ->
-    switchTargets(switcher)
-
-  up.on 'change', '[up-switch]', (event, switcher) ->
-    switchTargets(switcher)
-
-  up.compiler '[up-show-for]:not(.up-switched), [up-hide-for]:not(.up-switched)', (element) ->
-    switchTarget(element)
-
-  ###**
-  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.
-
-  \#\#\# Example
-
-  The following would run a global `showSuggestions(value)` function
-  whenever the `<input>` changes:
-
-      <input name="query" up-observe="showSuggestions(value)">
-
-  \#\#\# 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 |
-
-  \#\#\# Observing radio buttons
-
-  Multiple radio buttons with the same `[name]` (a radio button group)
-  produce a single value for the form.
-
-  To observe radio buttons group, use the `[up-observe]` attribute on an
-  element that contains all radio button elements with a given name:
-
-      <div up-observe="formatSelected(value)">
-        <input type="radio" name="format" value="html"> HTML format
-        <input type="radio" name="format" value="pdf"> PDF format
-        <input type="radio" name="format" value="txt"> Text format
-      </div>
-
-  @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)">
-        <input name="foo">
-        <input name="bar">
-      </form>
-
-  \#\#\# 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 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)
-
-  ###**
-  Submits this field's form when this field changes its values.
-
-  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 automatically submit the form when the query is changed:
-
-      <form method="GET" action="/search">
-        <input type="search" name="query" up-autosubmit>
-        <input type="checkbox" name="archive"> Include archive
-      </form>
-
-  \#\#\# Auto-submitting radio buttons
-
-  Multiple radio buttons with the same `[name]` (a radio button group)
-  produce a single value for the form.
-
-  To auto-submit radio buttons group, use the `[up-submit]` attribute on an
-  element that contains all radio button elements with a given name:
-
-      <div up-autosubmit>
-        <input type="radio" name="format" value="html"> HTML format
-        <input type="radio" name="format" value="pdf"> PDF format
-        <input type="radio" name="format" value="txt"> Text format
-      </div>
-
-  @selector input[up-autosubmit]
-  @param {string} up-delay
-    The number of miliseconds to wait after a change before the form is submitted.
-  @stable
-  ###
-
-  ###**
-  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 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)
-
-  up.compiler '[autofocus]', { batch: true }, (inputs) -> u.last(inputs).focus()
-
-  up.on 'up:framework:reset', reset
-
-  <% if ENV['JS_KNIFE'] %>knife: eval(Knife.point)<% end %>
-  config: config
-  submit: submit
-  observe: observe
-  validate: validate
-  autosubmit: autosubmit
-  fieldSelector: fieldSelector
-  fields: findFields
-  submissionFields: findSubmissionFields
-
-up.submit = up.form.submit
-up.observe = up.form.observe
-up.autosubmit = up.form.autosubmit
-up.validate = up.form.validate