unpoly-rails 0.53.0 → 0.53.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 6df6e7fea86df29cccc4752d549cd7083be2341f
-  data.tar.gz: a7375db94c1351ed6d5f46ef9ee856898fe1b5b7
+SHA256:
+  metadata.gz: f2684c206748c31c831f0891eafffb27bfaab7f995bec6fe97add98989f2cdac
+  data.tar.gz: 37a9f61758d26c768b7b84f17b42df9029105555e3216e74b34b8749d71ca897
 SHA512:
-  metadata.gz: 5ee1ee46c9d12ad6c40252fa31b8d877f5f32f85d3df461da82c02f7479d81f2a58d104bd3998aa478ace1215762d9be1c7e8d12e341be26aaeeb69ca399a239
-  data.tar.gz: 4e835e9180d7b051bb9ec126b760fc7766711ae2bca4993cc0f9fe04785e8c53a039c3ae4aed850a44bf2165b1d4adbe64b19c2ee383b8c897fccd8607114602
+  metadata.gz: 6ce730da5923ec604996a319f66dbc1d5fe4f86fa7c0287794ace4f0639941bf7f12736e6b76080ed9053eef7e3fdfbd068c8f4886b44892ecd3a75f6875d161
+  data.tar.gz: a6067a09b1c9234e1a1bdcff034e25881da221ba96c81dbfccf2ed1ee2807ceb60c607d4582b59449ffd2866bd81af89a962791682eaea8a6d54a8750f7c366c

data/CHANGELOG.md

@@ -6,9 +6,28 @@ Changes to this project will be documented in this file.
 This project mostly adheres to [Semantic Versioning](http://semver.org/).
 
 
+0.53.1
+------
+
+### General
+
+- Fix a bug where replacing the first element on the page (in DOM order) would shift the scroll position if animation is disabled.
+- Fix a bug where query params would be lost when Unpoly would fall back to a full page load.
+
+### Optional server protocol
+
+- The optional cookie the server can send to [signal the initial request method](/up.protocol#signaling-the-initial-request-method) will now be removed as soon as Unpoly has booted.
 
-Unreleased
-----------
+### Animations
+
+- Fix a bug where the animation `move-from-top` would finish instantly after animating with `move-to-top`.
+- Fix a bug where the animation `move-from-right` would finish instantly  after animating with `move-to-right`.
+- Fix a bug where the animation `move-from-bottom` would finish instantly after animating with `move-to-bottom`.
+- Fix a bug where the animation `move-from-left` wwould finish instantly  after animating with `move-to-left`.
+
+
+0.53.0
+------
 
 ### New module: Passive updates
 

data/dist/unpoly.js

@@ -5,7 +5,7 @@
 
 (function() {
   window.up = {
-    version: "0.53.0",
+    version: "0.53.1",
     renamedModule: function(oldName, newName) {
       return typeof Object.defineProperty === "function" ? Object.defineProperty(up, oldName, {
         get: function() {
@@ -2100,7 +2100,7 @@ that might save you from loading something like [Lodash](https://lodash.com/).
     @internal
      */
     rejectOnError = function(block) {
-      var error;
+      var error, error1;
       try {
         return block();
       } catch (error1) {
@@ -3271,6 +3271,7 @@ that might save you from loading something like [Lodash](https://lodash.com/).
 
     Request.prototype.navigate = function() {
       var $form, addField, csrfParam, csrfToken, formMethod;
+      this.transferSearchToData();
       $form = $('<form class="up-page-loader"></form>');
       addField = function(field) {
         return $('<input type="hidden">').attr(field).appendTo($form);
@@ -3515,379 +3516,70 @@ that might save you from loading something like [Lodash](https://lodash.com/).
 }).call(this);
 
 /**
-Server protocol
+Browser support
 ===============
 
-You rarely need to change server-side code
-in order to use Unpoly. There is no need to provide a JSON API, or add
-extra routes for AJAX requests. The server simply renders a series
-of full HTML pages, just like it would without Unpoly.
-
-That said, there is an **optional** protocol your server can use to
-exchange additional information when Unpoly is [updating fragments](/up.link).
-
-While the protocol can help you optimize performance and handle some
-edge cases, implementing it is **entirely optional**. For instance,
-`unpoly.com` itself is a static site that uses Unpoly on the frontend
-and doesn't even have a server component.
-
-## Existing implementations
-
-You should be able to implement the protocol in a very short time.
-There are existing implementations for various web frameworks:
-
-- [Ruby on Rails](/install/rails)
-- [Roda](https://github.com/adam12/roda-unpoly)
-- [Rack](https://github.com/adam12/rack-unpoly) (Sinatra, Padrino, Hanami, Cuba, ...)
-- [Phoenix](https://elixirforum.com/t/unpoly-a-framework-like-turbolinks/3614/15) (Elixir)
-
-
-## Protocol details
-
-\#\#\# Redirect detection for IE11
-
-On Internet Explorer 11, Unpoly cannot detect the final URL after a redirect.
-You can fix this edge case by delivering an additional HTTP header
-with the *last* response in a series of redirects:
-
-```http
-X-Up-Location: /current-url
-```
-
-The **simplest implementation** is to set these headers for every request.
-
-
-\#\#\# Optimizing responses
-
-When [updating a fragment](/up.link), Unpoly will send an
-additional HTTP header containing the CSS selector that is being replaced:
-
-```http
-X-Up-Target: .user-list
-```
-
-Server-side code is free to **optimize its response** by only returning HTML
-that matches the selector. For example, you might prefer to not render an
-expensive sidebar if the sidebar is not targeted.
-
-Unpoly will often update a different selector in case the request fails.
-This selector is also included as a HTTP header:
-
-```
-X-Up-Fail-Target: body
-```
-
-
-\#\#\# Pushing a document title to the client
-
-When [updating a fragment](/up.link), Unpoly will by default
-extract the `<title>` from the server response and update the document title accordingly.
-
-The server can also force Unpoly to set a document title by passing a HTTP header:
-
-```http
-X-Up-Title: My server-pushed title
-```
-
-This is useful when you [optimize your response](#optimizing-responses) and not render
-the application layout unless it is targeted. Since your optimized response
-no longer includes a `<title>`, you can instead use the HTTP header to pass the document title.
-
-
-\#\#\# Signaling failed form submissions
-
-When [submitting a form via AJAX](/form-up-target)
-Unpoly needs to know whether the form submission has failed (to update the form with
-validation errors) or succeeded (to update the `up-target` selector).
-
-For Unpoly to be able to detect a failed form submission, the response must be
-return a non-200 HTTP status code. We recommend to use either
-400 (bad request) or 422 (unprocessable entity).
-
-To do so in [Ruby on Rails](http://rubyonrails.org/), pass a [`:status` option to `render`](http://guides.rubyonrails.org/layouts_and_rendering.html#the-status-option):
-
-    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
-
-
-\#\#\# Detecting live form validations
-
-When [validating a form](/input-up-validate), Unpoly will
-send an additional HTTP header containing a CSS selector for the form that is
-being updated:
-
-```http
-X-Up-Validate: .user-form
-```
-
-When detecting a validation request, the server is expected to **validate (but not save)**
-the form submission and render a new copy of the form with validation errors.
-
-Below you will an example for a writing route that is aware of Unpoly's live form
-validations. The code is for [Ruby on Rails](http://rubyonrails.org/),
-but you can adapt it for other languages:
-
-    class UsersController < ApplicationController
-
-      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
-
-
-\#\#\# Signaling the initial request method
-
-If the initial page was loaded  with a non-`GET` HTTP method, Unpoly prefers to make a full
-page load when you try to update a fragment. Once the next page was loaded with a `GET` method,
-Unpoly will restore its standard behavior.
-
-This fixes two edge cases you might or might not care about:
-
-1. Unpoly replaces the initial page state so it can later restore it when the user
-   goes back to that initial URL. However, if the initial request was a POST,
-   Unpoly will wrongly assume that it can restore the state by reloading with GET.
-2. Some browsers have a bug where the initial request method is used for all
-   subsequently pushed states. That means if the user reloads the page on a later
-   GET state, the browser will wrongly attempt a POST request.
-   This issue affects Safari 9 and 10 (last tested in 2017-08).
-   Modern Firefoxes, Chromes and IE10+ don't have this behavior.
-
-In order to allow Unpoly to detect the HTTP method of the initial page load,
-the server must set a cookie:
-
-```http
-Set-Cookie: _up_method=POST
-```
+Unpoly supports all modern browsers.
 
-When Unpoly boots, it will look for this cookie and configure its behavior accordingly.
-The cookie is then deleted in order to not affect following requests.
+Chrome, Firefox, Edge, Safari
+: Full support
 
-The **simplest implementation** is to set this cookie for every request that is neither
-`GET` nor contains an [`X-Up-Target` header](/#optimizing-responses). For all other requests
-an existing cookie should be deleted.
+Internet Explorer 11
+: Full support with a `Promise` polyfill like [es6-promise](https://github.com/stefanpenner/es6-promise) (2.4 KB).
 
+Internet Explorer 10 or lower
+: Unpoly prevents itself from booting itself, leaving you with a classic server-side application.
 
-@class up.protocol
+@class up.browser
  */
 
 (function() {
-  up.protocol = (function($) {
-    var config, csrfParam, csrfToken, initialRequestMethod, locationFromXhr, methodFromXhr, reset, titleFromXhr, u;
-    u = up.util;
+  var slice = [].slice;
 
-    /**
-    @function up.protocol.locationFromXhr
-    @internal
-     */
-    locationFromXhr = function(xhr) {
-      return xhr.getResponseHeader(config.locationHeader) || xhr.responseURL;
-    };
+  up.browser = (function($) {
+    var CONSOLE_PLACEHOLDERS, canConsole, canCssTransition, canDOMParser, canFormData, canInputEvent, canPromise, canPushState, hash, isIE10OrWorse, isRecentJQuery, isSupported, navigate, polyfilledSessionStorage, popCookie, puts, sessionStorage, sprintf, sprintfWithFormattedArgs, stringifyArg, submitForm, u, url, whenConfirmed;
+    u = up.util;
 
     /**
-    @function up.protocol.titleFromXhr
+    @method up.browser.navigate
+    @param {string} url
+    @param {string} [options.method='get']
+    @param {Object|Array} [options.data]
     @internal
      */
-    titleFromXhr = function(xhr) {
-      return xhr.getResponseHeader(config.titleHeader);
+    navigate = function(url, options) {
+      var request;
+      if (options == null) {
+        options = {};
+      }
+      request = new up.Request(u.merge(options, {
+        url: url
+      }));
+      return request.navigate();
     };
 
     /**
-    @function up.protocol.methodFromXhr
-    @internal
+    For mocking in specs.
+    
+    @method submitForm
      */
-    methodFromXhr = function(xhr) {
-      var method;
-      if (method = xhr.getResponseHeader(config.methodHeader)) {
-        return u.normalizeMethod(method);
-      }
+    submitForm = function($form) {
+      return $form.submit();
     };
 
     /**
-    Server-side companion libraries like unpoly-rails set this cookie so we
-    have a way to detect the request method of the initial page load.
-    There is no JavaScript API for this.
+    A cross-browser way to interact with `console.log`, `console.error`, etc.
     
-    @function up.protocol.initialRequestMethod
-    @internal
-     */
-    initialRequestMethod = u.memoize(function() {
-      var methodFromServer;
-      methodFromServer = up.browser.popCookie(config.methodCookie);
-      return (methodFromServer || 'get').toLowerCase();
-    });
-
-    /**
-    Configures strings used in the optional [server protocol](/up.protocol).
-    
-    @property up.protocol.config
-    @param {String} [config.targetHeader='X-Up-Target']
-    @param {String} [config.failTargetHeader='X-Up-Fail-Target']
-    @param {String} [config.locationHeader='X-Up-Location']
-    @param {String} [config.titleHeader='X-Up-Title']
-    @param {String} [config.validateHeader='X-Up-Validate']
-    @param {String} [config.methodHeader='X-Up-Method']
-    @param {String} [config.methodCookie='_up_method']
-      The name of the optional cookie the server can send to
-      [signal the initial request method](/up.protocol#signaling-the-initial-request-method).
-    @param {String} [config.methodParam='_method']
-      The name of the POST parameter when [wrapping HTTP methods](/up.form.config#config.wrapMethods)
-      in a `POST` request.
-    @param {String} [config.csrfHeader='X-CSRF-Token']
-      The name of the HTTP header that will include the
-      [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Synchronizer_token_pattern)
-      for AJAX requests.
-    @param {String|Function} [config.csrfParam]
-      The `name` of the hidden `<input>` used for sending a
-      [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Synchronizer_token_pattern) when
-      submitting a default, non-AJAX form. For AJAX request the token is sent as an HTTP header instead.
-    
-      The parameter name can be configured as a string or as function that returns the parameter name.
-      If no name is set, no token will be sent.
-    
-      Defaults to the `content` attribute of a `<meta>` tag named `csrf-token`:
-    
-          <meta name="csrf-param" content="authenticity_token" />
-    
-    @param {String|Function} [config.csrfToken]
-      The [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Synchronizer_token_pattern)
-      to send for unsafe requests. The token will be sent as either a HTTP header (for AJAX requests)
-      or hidden form `<input>` (for default, non-AJAX form submissions).
-    
-      The token can either be configured as a string or as function that returns the token.
-      If no token is set, no token will be sent.
-    
-      Defaults to the `content` attribute of a `<meta>` tag named `csrf-token`:
-    
-          <meta name='csrf-token' content='secret12345'>
-    
-    @experimental
-     */
-    config = u.config({
-      targetHeader: 'X-Up-Target',
-      failTargetHeader: 'X-Up-Fail-Target',
-      locationHeader: 'X-Up-Location',
-      validateHeader: 'X-Up-Validate',
-      titleHeader: 'X-Up-Title',
-      methodHeader: 'X-Up-Method',
-      methodCookie: '_up_method',
-      methodParam: '_method',
-      csrfParam: function() {
-        return $('meta[name="csrf-param"]').attr('content');
-      },
-      csrfToken: function() {
-        return $('meta[name="csrf-token"]').attr('content');
-      },
-      csrfHeader: 'X-CSRF-Token'
-    });
-    csrfParam = function() {
-      return u.evalOption(config.csrfParam);
-    };
-    csrfToken = function() {
-      return u.evalOption(config.csrfToken);
-    };
-    reset = function() {
-      return config.reset();
-    };
-    return {
-      config: config,
-      reset: reset,
-      locationFromXhr: locationFromXhr,
-      titleFromXhr: titleFromXhr,
-      methodFromXhr: methodFromXhr,
-      csrfParam: csrfParam,
-      csrfToken: csrfToken,
-      initialRequestMethod: initialRequestMethod
-    };
-  })(jQuery);
-
-}).call(this);
-
-/**
-Browser support
-===============
-
-Unpoly supports all modern browsers.
-
-Chrome, Firefox, Edge, Safari
-: Full support
-
-Internet Explorer 11
-: Full support with a `Promise` polyfill like [es6-promise](https://github.com/stefanpenner/es6-promise) (2.4 KB).
-
-Internet Explorer 10 or lower
-: Unpoly prevents itself from booting itself, leaving you with a classic server-side application.
-
-@class up.browser
- */
-
-(function() {
-  var slice = [].slice;
-
-  up.browser = (function($) {
-    var CONSOLE_PLACEHOLDERS, canConsole, canCssTransition, canDOMParser, canFormData, canInputEvent, canPromise, canPushState, hash, isIE10OrWorse, isRecentJQuery, isSupported, navigate, polyfilledSessionStorage, popCookie, puts, sessionStorage, sprintf, sprintfWithFormattedArgs, stringifyArg, submitForm, u, url, whenConfirmed;
-    u = up.util;
-
-    /**
-    @method up.browser.navigate
-    @param {string} url
-    @param {string} [options.method='get']
-    @param {Object|Array} [options.data]
-    @internal
-     */
-    navigate = function(url, options) {
-      var request;
-      if (options == null) {
-        options = {};
-      }
-      request = new up.Request(u.merge(options, {
-        url: url
-      }));
-      return request.navigate();
-    };
-
-    /**
-    For mocking in specs.
-    
-    @method submitForm
-     */
-    submitForm = function($form) {
-      return $form.submit();
-    };
-
-    /**
-    A cross-browser way to interact with `console.log`, `console.error`, etc.
-    
-    This function falls back to `console.log` if the output stream is not implemented.
-    It also prints substitution strings (e.g. `console.log("From %o to %o", "a", "b")`)
-    as a single string if the browser console does not support substitution strings.
-    
-    \#\#\# Example
-    
-        up.browser.puts('log', 'Hi world');
-        up.browser.puts('error', 'There was an error in %o', obj);
-    
-    @function up.browser.puts
+    This function falls back to `console.log` if the output stream is not implemented.
+    It also prints substitution strings (e.g. `console.log("From %o to %o", "a", "b")`)
+    as a single string if the browser console does not support substitution strings.
+    
+    \#\#\# Example
+    
+        up.browser.puts('log', 'Hi world');
+        up.browser.puts('error', 'There was an error in %o', obj);
+    
+    @function up.browser.puts
     @internal
      */
     puts = function() {
@@ -4126,6 +3818,7 @@ Internet Explorer 10 or lower
     @internal
      */
     sessionStorage = u.memoize(function() {
+      var error;
       try {
         return window.sessionStorage;
       } catch (error) {
@@ -4566,180 +4259,490 @@ This improves jQuery's [`on`](http://api.jquery.com/on/) in multiple ways:
     };
 
     /**
-    Registers an event listener to be called when the user
-    presses the `Escape` key.
-    
-    @function up.bus.onEscape
-    @param {Function} listener
-      The listener function to register.
-    @return {Function}
-      A function that unbinds the event listeners when called.
-    @experimental
+    Registers an event listener to be called when the user
+    presses the `Escape` key.
+    
+    @function up.bus.onEscape
+    @param {Function} listener
+      The listener function to register.
+    @return {Function}
+      A function that unbinds the event listeners when called.
+    @experimental
+     */
+    onEscape = function(listener) {
+      return live('keydown', 'body', function(event) {
+        if (u.escapePressed(event)) {
+          return listener(event);
+        }
+      });
+    };
+
+    /**
+    Stops the given event from propagating and prevents the default action.
+    
+    @function up.bus.haltEvent
+    @internal
+     */
+    haltEvent = function(event) {
+      event.stopImmediatePropagation();
+      event.stopPropagation();
+      return event.preventDefault();
+    };
+
+    /**
+    @function up.bus.consumeAction
+    @internal
+     */
+    consumeAction = function(event) {
+      haltEvent(event);
+      if (event.type !== 'up:action:consumed') {
+        return emit('up:action:consumed', {
+          $element: $(event.target),
+          message: false
+        });
+      }
+    };
+
+    /**
+    Makes a snapshot of the currently registered event listeners,
+    to later be restored through [`up.bus.reset()`](/up.bus.reset).
+    
+    @internal
+     */
+    snapshot = function() {
+      var description, number, results;
+      results = [];
+      for (number in liveUpDescriptions) {
+        description = liveUpDescriptions[number];
+        results.push(description.isDefault = true);
+      }
+      return results;
+    };
+    resetBus = function() {
+      var description, doomedDescriptions, i, len, number, results;
+      doomedDescriptions = [];
+      for (number in liveUpDescriptions) {
+        description = liveUpDescriptions[number];
+        if (!description.isDefault) {
+          doomedDescriptions.push(description);
+        }
+      }
+      results = [];
+      for (i = 0, len = doomedDescriptions.length; i < len; i++) {
+        description = doomedDescriptions[i];
+        results.push(unbind.apply(null, description));
+      }
+      return results;
+    };
+
+    /**
+    Resets Unpoly to the state when it was booted.
+    All custom event handlers, animations, etc. that have been registered
+    will be discarded.
+    
+    This is an internal method for to enable unit testing.
+    Don't use this in production.
+    
+    Emits event [`up:framework:reset`](/up:framework:reset).
+    
+    @function up.reset
+    @experimental
+     */
+    emitReset = function() {
+      emit('up:framework:reset', {
+        message: 'Resetting framework'
+      });
+      return up.protocol.reset();
+    };
+
+    /**
+    This event is [emitted](/up.emit) when Unpoly is [reset](/up.reset) during unit tests.
+    
+    @event up:framework:reset
+    @experimental
+     */
+    renamedEvent = function(oldEvent, newEvent) {
+      return renamedEvents[oldEvent] = newEvent;
+    };
+
+    /**
+    Boots the Unpoly framework.
+    
+    **This is called automatically** by including the Unpoly JavaScript files.
+    
+    Unpoly will not boot if the current browser is [not supported](/up.browser.isSupported).
+    This leaves you with a classic server-side application on legacy browsers.
+    
+    @function up.boot
+    @internal
+     */
+    boot = function() {
+      if (up.browser.isSupported()) {
+        emit('up:framework:boot', {
+          message: 'Booting framework'
+        });
+        emit('up:framework:booted', {
+          message: 'Framework booted'
+        });
+        return u.nextFrame(function() {
+          return u.whenReady().then(function() {
+            emit('up:app:boot', {
+              message: 'Booting user application'
+            });
+            return emit('up:app:booted', {
+              message: 'User application booted'
+            });
+          });
+        });
+      } else {
+        return typeof console.log === "function" ? console.log("Unpoly doesn't support this browser. Framework was not booted.") : void 0;
+      }
+    };
+
+    /**
+    This event is [emitted](/up.emit) when Unpoly [starts to boot](/up.boot).
+    
+    @event up:framework:boot
+    @internal
+     */
+    live('up:framework:booted', snapshot);
+    live('up:framework:reset', resetBus);
+    return {
+      knife: eval(typeof Knife !== "undefined" && Knife !== null ? Knife.point : void 0),
+      on: live,
+      off: unbind,
+      emit: emit,
+      nobodyPrevents: nobodyPrevents,
+      whenEmitted: whenEmitted,
+      onEscape: onEscape,
+      emitReset: emitReset,
+      haltEvent: haltEvent,
+      consumeAction: consumeAction,
+      renamedEvent: renamedEvent,
+      boot: boot
+    };
+  })(jQuery);
+
+  up.on = up.bus.on;
+
+  up.off = up.bus.off;
+
+  up.emit = up.bus.emit;
+
+  up.reset = up.bus.emitReset;
+
+  up.boot = up.bus.boot;
+
+}).call(this);
+
+/**
+Server protocol
+===============
+
+You rarely need to change server-side code
+in order to use Unpoly. There is no need to provide a JSON API, or add
+extra routes for AJAX requests. The server simply renders a series
+of full HTML pages, just like it would without Unpoly.
+
+That said, there is an **optional** protocol your server can use to
+exchange additional information when Unpoly is [updating fragments](/up.link).
+
+While the protocol can help you optimize performance and handle some
+edge cases, implementing it is **entirely optional**. For instance,
+`unpoly.com` itself is a static site that uses Unpoly on the frontend
+and doesn't even have a server component.
+
+## Existing implementations
+
+You should be able to implement the protocol in a very short time.
+There are existing implementations for various web frameworks:
+
+- [Ruby on Rails](/install/rails)
+- [Roda](https://github.com/adam12/roda-unpoly)
+- [Rack](https://github.com/adam12/rack-unpoly) (Sinatra, Padrino, Hanami, Cuba, ...)
+- [Phoenix](https://elixirforum.com/t/unpoly-a-framework-like-turbolinks/3614/15) (Elixir)
+
+
+## Protocol details
+
+\#\#\# Redirect detection for IE11
+
+On Internet Explorer 11, Unpoly cannot detect the final URL after a redirect.
+You can fix this edge case by delivering an additional HTTP header
+with the *last* response in a series of redirects:
+
+```http
+X-Up-Location: /current-url
+```
+
+The **simplest implementation** is to set these headers for every request.
+
+
+\#\#\# Optimizing responses
+
+When [updating a fragment](/up.link), Unpoly will send an
+additional HTTP header containing the CSS selector that is being replaced:
+
+```http
+X-Up-Target: .user-list
+```
+
+Server-side code is free to **optimize its response** by only returning HTML
+that matches the selector. For example, you might prefer to not render an
+expensive sidebar if the sidebar is not targeted.
+
+Unpoly will often update a different selector in case the request fails.
+This selector is also included as a HTTP header:
+
+```
+X-Up-Fail-Target: body
+```
+
+
+\#\#\# Pushing a document title to the client
+
+When [updating a fragment](/up.link), Unpoly will by default
+extract the `<title>` from the server response and update the document title accordingly.
+
+The server can also force Unpoly to set a document title by passing a HTTP header:
+
+```http
+X-Up-Title: My server-pushed title
+```
+
+This is useful when you [optimize your response](#optimizing-responses) and not render
+the application layout unless it is targeted. Since your optimized response
+no longer includes a `<title>`, you can instead use the HTTP header to pass the document title.
+
+
+\#\#\# Signaling failed form submissions
+
+When [submitting a form via AJAX](/form-up-target)
+Unpoly needs to know whether the form submission has failed (to update the form with
+validation errors) or succeeded (to update the `up-target` selector).
+
+For Unpoly to be able to detect a failed form submission, the response must be
+return a non-200 HTTP status code. We recommend to use either
+400 (bad request) or 422 (unprocessable entity).
+
+To do so in [Ruby on Rails](http://rubyonrails.org/), pass a [`:status` option to `render`](http://guides.rubyonrails.org/layouts_and_rendering.html#the-status-option):
+
+    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
+
+
+\#\#\# Detecting live form validations
+
+When [validating a form](/input-up-validate), Unpoly will
+send an additional HTTP header containing a CSS selector for the form that is
+being updated:
+
+```http
+X-Up-Validate: .user-form
+```
+
+When detecting a validation request, the server is expected to **validate (but not save)**
+the form submission and render a new copy of the form with validation errors.
+
+Below you will an example for a writing route that is aware of Unpoly's live form
+validations. The code is for [Ruby on Rails](http://rubyonrails.org/),
+but you can adapt it for other languages:
+
+    class UsersController < ApplicationController
+
+      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
+
+
+\#\#\# Signaling the initial request method
+
+If the initial page was loaded  with a non-`GET` HTTP method, Unpoly prefers to make a full
+page load when you try to update a fragment. Once the next page was loaded with a `GET` method,
+Unpoly will restore its standard behavior.
+
+This fixes two edge cases you might or might not care about:
+
+1. Unpoly replaces the initial page state so it can later restore it when the user
+   goes back to that initial URL. However, if the initial request was a POST,
+   Unpoly will wrongly assume that it can restore the state by reloading with GET.
+2. Some browsers have a bug where the initial request method is used for all
+   subsequently pushed states. That means if the user reloads the page on a later
+   GET state, the browser will wrongly attempt a POST request.
+   This issue affects Safari 9 and 10 (last tested in 2017-08).
+   Modern Firefoxes, Chromes and IE10+ don't have this behavior.
+
+In order to allow Unpoly to detect the HTTP method of the initial page load,
+the server must set a cookie:
+
+```http
+Set-Cookie: _up_method=POST
+```
+
+When Unpoly boots, it will look for this cookie and configure its behavior accordingly.
+The cookie is then deleted in order to not affect following requests.
+
+The **simplest implementation** is to set this cookie for every request that is neither
+`GET` nor contains an [`X-Up-Target` header](/#optimizing-responses). For all other requests
+an existing cookie should be deleted.
+
+
+@class up.protocol
+ */
+
+(function() {
+  up.protocol = (function($) {
+    var config, csrfParam, csrfToken, initialRequestMethod, locationFromXhr, methodFromXhr, reset, titleFromXhr, u;
+    u = up.util;
+
+    /**
+    @function up.protocol.locationFromXhr
+    @internal
      */
-    onEscape = function(listener) {
-      return live('keydown', 'body', function(event) {
-        if (u.escapePressed(event)) {
-          return listener(event);
-        }
-      });
+    locationFromXhr = function(xhr) {
+      return xhr.getResponseHeader(config.locationHeader) || xhr.responseURL;
     };
 
     /**
-    Stops the given event from propagating and prevents the default action.
-    
-    @function up.bus.haltEvent
+    @function up.protocol.titleFromXhr
     @internal
      */
-    haltEvent = function(event) {
-      event.stopImmediatePropagation();
-      event.stopPropagation();
-      return event.preventDefault();
+    titleFromXhr = function(xhr) {
+      return xhr.getResponseHeader(config.titleHeader);
     };
 
     /**
-    @function up.bus.consumeAction
+    @function up.protocol.methodFromXhr
     @internal
      */
-    consumeAction = function(event) {
-      haltEvent(event);
-      if (event.type !== 'up:action:consumed') {
-        return emit('up:action:consumed', {
-          $element: $(event.target),
-          message: false
-        });
+    methodFromXhr = function(xhr) {
+      var method;
+      if (method = xhr.getResponseHeader(config.methodHeader)) {
+        return u.normalizeMethod(method);
       }
     };
 
     /**
-    Makes a snapshot of the currently registered event listeners,
-    to later be restored through [`up.bus.reset()`](/up.bus.reset).
+    Server-side companion libraries like unpoly-rails set this cookie so we
+    have a way to detect the request method of the initial page load.
+    There is no JavaScript API for this.
     
+    @function up.protocol.initialRequestMethod
     @internal
      */
-    snapshot = function() {
-      var description, number, results;
-      results = [];
-      for (number in liveUpDescriptions) {
-        description = liveUpDescriptions[number];
-        results.push(description.isDefault = true);
-      }
-      return results;
-    };
-    resetBus = function() {
-      var description, doomedDescriptions, i, len, number, results;
-      doomedDescriptions = [];
-      for (number in liveUpDescriptions) {
-        description = liveUpDescriptions[number];
-        if (!description.isDefault) {
-          doomedDescriptions.push(description);
-        }
-      }
-      results = [];
-      for (i = 0, len = doomedDescriptions.length; i < len; i++) {
-        description = doomedDescriptions[i];
-        results.push(unbind.apply(null, description));
-      }
-      return results;
-    };
+    initialRequestMethod = u.memoize(function() {
+      var methodFromServer;
+      methodFromServer = up.browser.popCookie(config.methodCookie);
+      return (methodFromServer || 'get').toLowerCase();
+    });
+    up.bus.on('up:framework:booted', initialRequestMethod);
 
     /**
-    Resets Unpoly to the state when it was booted.
-    All custom event handlers, animations, etc. that have been registered
-    will be discarded.
+    Configures strings used in the optional [server protocol](/up.protocol).
     
-    This is an internal method for to enable unit testing.
-    Don't use this in production.
+    @property up.protocol.config
+    @param {String} [config.targetHeader='X-Up-Target']
+    @param {String} [config.failTargetHeader='X-Up-Fail-Target']
+    @param {String} [config.locationHeader='X-Up-Location']
+    @param {String} [config.titleHeader='X-Up-Title']
+    @param {String} [config.validateHeader='X-Up-Validate']
+    @param {String} [config.methodHeader='X-Up-Method']
+    @param {String} [config.methodCookie='_up_method']
+      The name of the optional cookie the server can send to
+      [signal the initial request method](/up.protocol#signaling-the-initial-request-method).
+    @param {String} [config.methodParam='_method']
+      The name of the POST parameter when [wrapping HTTP methods](/up.form.config#config.wrapMethods)
+      in a `POST` request.
+    @param {String} [config.csrfHeader='X-CSRF-Token']
+      The name of the HTTP header that will include the
+      [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Synchronizer_token_pattern)
+      for AJAX requests.
+    @param {String|Function} [config.csrfParam]
+      The `name` of the hidden `<input>` used for sending a
+      [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Synchronizer_token_pattern) when
+      submitting a default, non-AJAX form. For AJAX request the token is sent as an HTTP header instead.
     
-    Emits event [`up:framework:reset`](/up:framework:reset).
+      The parameter name can be configured as a string or as function that returns the parameter name.
+      If no name is set, no token will be sent.
     
-    @function up.reset
-    @experimental
-     */
-    emitReset = function() {
-      emit('up:framework:reset', {
-        message: 'Resetting framework'
-      });
-      return up.protocol.reset();
-    };
-
-    /**
-    This event is [emitted](/up.emit) when Unpoly is [reset](/up.reset) during unit tests.
+      Defaults to the `content` attribute of a `<meta>` tag named `csrf-token`:
     
-    @event up:framework:reset
-    @experimental
-     */
-    renamedEvent = function(oldEvent, newEvent) {
-      return renamedEvents[oldEvent] = newEvent;
-    };
-
-    /**
-    Boots the Unpoly framework.
+          <meta name="csrf-param" content="authenticity_token" />
     
-    **This is called automatically** by including the Unpoly JavaScript files.
+    @param {String|Function} [config.csrfToken]
+      The [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Synchronizer_token_pattern)
+      to send for unsafe requests. The token will be sent as either a HTTP header (for AJAX requests)
+      or hidden form `<input>` (for default, non-AJAX form submissions).
     
-    Unpoly will not boot if the current browser is [not supported](/up.browser.isSupported).
-    This leaves you with a classic server-side application on legacy browsers.
+      The token can either be configured as a string or as function that returns the token.
+      If no token is set, no token will be sent.
     
-    @function up.boot
-    @internal
-     */
-    boot = function() {
-      if (up.browser.isSupported()) {
-        emit('up:framework:boot', {
-          message: 'Booting framework'
-        });
-        emit('up:framework:booted', {
-          message: 'Framework booted'
-        });
-        return u.nextFrame(function() {
-          return u.whenReady().then(function() {
-            emit('up:app:boot', {
-              message: 'Booting user application'
-            });
-            return emit('up:app:booted', {
-              message: 'User application booted'
-            });
-          });
-        });
-      } else {
-        return typeof console.log === "function" ? console.log("Unpoly doesn't support this browser. Framework was not booted.") : void 0;
-      }
-    };
-
-    /**
-    This event is [emitted](/up.emit) when Unpoly [starts to boot](/up.boot).
+      Defaults to the `content` attribute of a `<meta>` tag named `csrf-token`:
     
-    @event up:framework:boot
-    @internal
+          <meta name='csrf-token' content='secret12345'>
+    
+    @experimental
      */
-    live('up:framework:booted', snapshot);
-    live('up:framework:reset', resetBus);
+    config = u.config({
+      targetHeader: 'X-Up-Target',
+      failTargetHeader: 'X-Up-Fail-Target',
+      locationHeader: 'X-Up-Location',
+      validateHeader: 'X-Up-Validate',
+      titleHeader: 'X-Up-Title',
+      methodHeader: 'X-Up-Method',
+      methodCookie: '_up_method',
+      methodParam: '_method',
+      csrfParam: function() {
+        return $('meta[name="csrf-param"]').attr('content');
+      },
+      csrfToken: function() {
+        return $('meta[name="csrf-token"]').attr('content');
+      },
+      csrfHeader: 'X-CSRF-Token'
+    });
+    csrfParam = function() {
+      return u.evalOption(config.csrfParam);
+    };
+    csrfToken = function() {
+      return u.evalOption(config.csrfToken);
+    };
+    reset = function() {
+      return config.reset();
+    };
     return {
-      knife: eval(typeof Knife !== "undefined" && Knife !== null ? Knife.point : void 0),
-      on: live,
-      off: unbind,
-      emit: emit,
-      nobodyPrevents: nobodyPrevents,
-      whenEmitted: whenEmitted,
-      onEscape: onEscape,
-      emitReset: emitReset,
-      haltEvent: haltEvent,
-      consumeAction: consumeAction,
-      renamedEvent: renamedEvent,
-      boot: boot
+      config: config,
+      reset: reset,
+      locationFromXhr: locationFromXhr,
+      titleFromXhr: titleFromXhr,
+      methodFromXhr: methodFromXhr,
+      csrfParam: csrfParam,
+      csrfToken: csrfToken,
+      initialRequestMethod: initialRequestMethod
     };
   })(jQuery);
 
-  up.on = up.bus.on;
-
-  up.off = up.bus.off;
-
-  up.emit = up.bus.emit;
-
-  up.reset = up.bus.emitReset;
-
-  up.boot = up.bus.boot;
-
 }).call(this);
 
 /**
@@ -6628,7 +6631,7 @@ is built from these functions. You can use them to extend Unpoly from your
 
 (function() {
   up.dom = (function($) {
-    var autofocus, bestMatchingSteps, bestPreflightSelector, config, destroy, detectScriptFixes, emitFragmentInserted, emitFragmentKept, extract, findKeepPlan, first, firstInLayer, firstInPriority, fixScripts, hello, isRealElement, isSingletonElement, layerOf, matchesLayer, parseResponseDoc, processResponse, reload, replace, reset, resolveSelector, setSource, shouldExtractTitle, shouldLogDestruction, source, swapElements, swapSingletonElement, transferKeepableElements, u, updateHistoryAndTitle;
+    var autofocus, bestMatchingSteps, bestPreflightSelector, config, destroy, detectScriptFixes, emitFragmentInserted, emitFragmentKept, extract, findKeepPlan, first, firstInLayer, firstInPriority, fixScripts, hello, isRealElement, layerOf, matchesLayer, parseResponseDoc, processResponse, reload, replace, reset, resolveSelector, setSource, shouldExtractTitle, shouldLogDestruction, shouldSwapElementsDirectly, source, swapElements, swapElementsDirectly, transferKeepableElements, u, updateHistoryAndTitle;
     u = up.util;
 
     /**
@@ -6857,7 +6860,7 @@ is built from these functions. You can use them to extend Unpoly from your
     @stable
      */
     replace = function(selectorOrElement, url, options) {
-      var e, failureOptions, fullLoad, improvedFailTarget, improvedTarget, onFailure, onSuccess, promise, request, successOptions;
+      var e, error, failureOptions, fullLoad, improvedFailTarget, improvedTarget, onFailure, onSuccess, promise, request, successOptions;
       options = u.options(options);
       options.inspectResponse = fullLoad = function() {
         return up.browser.navigate(url, u.only(options, 'method', 'data'));
@@ -7153,8 +7156,8 @@ is built from these functions. You can use them to extend Unpoly from your
         options.keepPlans = transferKeepableElements($old, $new, options);
         clean = up.syntax.prepareClean($old);
         replacement = function() {
-          if (isSingletonElement($old)) {
-            swapSingletonElement($old, $new);
+          if (shouldSwapElementsDirectly($old, $new, transition, options)) {
+            swapElementsDirectly($old, $new);
             transition = false;
           } else {
             $new.insertBefore($old);
@@ -7174,10 +7177,12 @@ is built from these functions. You can use them to extend Unpoly from your
       }
       return promise;
     };
-    isSingletonElement = function($element) {
-      return $element.is('body');
+    shouldSwapElementsDirectly = function($old, $new, transition, options) {
+      var $both;
+      $both = $old.add($new);
+      return $old.is('body') || !up.motion.willAnimate($both, transition, options);
     };
-    swapSingletonElement = function($old, $new) {
+    swapElementsDirectly = function($old, $new) {
       return $old.replaceWith($new);
     };
     transferKeepableElements = function($old, $new, options) {
@@ -7843,6 +7848,7 @@ You can define custom animations using [`up.transition()`](/up.transition) and
       });
     };
     willAnimate = function($elements, animationOrTransition, options) {
+      options = animateOptions(options);
       return isEnabled() && !isNone(animationOrTransition) && options.duration > 0 && u.all($elements, u.isBodyDescendant);
     };
     skipAnimate = function($element, animation) {
@@ -8306,13 +8312,14 @@ You can define custom animations using [`up.transition()`](/up.transition) and
     };
     registerAnimation('move-to-top', function($ghost, options) {
       var box, travelDistance;
+      $ghost.css(translateCss(0, 0));
       box = u.measure($ghost);
       travelDistance = box.top + box.height;
-      $ghost.css(translateCss(0, 0));
       return animate($ghost, translateCss(0, -travelDistance), options);
     });
     registerAnimation('move-from-top', function($ghost, options) {
       var box, travelDistance;
+      $ghost.css(translateCss(0, 0));
       box = u.measure($ghost);
       travelDistance = box.top + box.height;
       $ghost.css(translateCss(0, -travelDistance));
@@ -8320,13 +8327,14 @@ You can define custom animations using [`up.transition()`](/up.transition) and
     });
     registerAnimation('move-to-bottom', function($ghost, options) {
       var box, travelDistance;
+      $ghost.css(translateCss(0, 0));
       box = u.measure($ghost);
       travelDistance = u.clientSize().height - box.top;
-      $ghost.css(translateCss(0, 0));
       return animate($ghost, translateCss(0, travelDistance), options);
     });
     registerAnimation('move-from-bottom', function($ghost, options) {
       var box, travelDistance;
+      $ghost.css(translateCss(0, 0));
       box = u.measure($ghost);
       travelDistance = u.clientSize().height - box.top;
       $ghost.css(translateCss(0, travelDistance));
@@ -8334,13 +8342,14 @@ You can define custom animations using [`up.transition()`](/up.transition) and
     });
     registerAnimation('move-to-left', function($ghost, options) {
       var box, travelDistance;
+      $ghost.css(translateCss(0, 0));
       box = u.measure($ghost);
       travelDistance = box.left + box.width;
-      $ghost.css(translateCss(0, 0));
       return animate($ghost, translateCss(-travelDistance, 0), options);
     });
     registerAnimation('move-from-left', function($ghost, options) {
       var box, travelDistance;
+      $ghost.css(translateCss(0, 0));
       box = u.measure($ghost);
       travelDistance = box.left + box.width;
       $ghost.css(translateCss(-travelDistance, 0));
@@ -8348,13 +8357,14 @@ You can define custom animations using [`up.transition()`](/up.transition) and
     });
     registerAnimation('move-to-right', function($ghost, options) {
       var box, travelDistance;
+      $ghost.css(translateCss(0, 0));
       box = u.measure($ghost);
       travelDistance = u.clientSize().width - box.left;
-      $ghost.css(translateCss(0, 0));
       return animate($ghost, translateCss(travelDistance, 0), options);
     });
     registerAnimation('move-from-right', function($ghost, options) {
       var box, travelDistance;
+      $ghost.css(translateCss(0, 0));
       box = u.measure($ghost);
       travelDistance = u.clientSize().width - box.left;
       $ghost.css(translateCss(travelDistance, 0));
@@ -8384,6 +8394,7 @@ You can define custom animations using [`up.transition()`](/up.transition) and
       morph: morph,
       animate: animate,
       animateOptions: animateOptions,
+      willAnimate: willAnimate,
       finish: finish,
       transition: registerTransition,
       animation: registerAnimation,