unpoly-rails 0.37.0 → 0.50.0

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

@@ -5,7 +5,7 @@ Modal dialogs
 Instead of [linking to a page fragment](/up.link), you can choose to show a fragment
 in a modal dialog. The existing page will remain open in the background.
 
-To open a modal, add an [`up-modal`](/up-modal) attribute to a link:
+To open a modal, add an [`up-modal`](/a-up-modal) attribute to a link:
 
     <a href="/blogs" up-modal=".blog-list">Switch blog</a>
 
@@ -21,7 +21,7 @@ By default the dialog automatically closes
 This is useful to have the dialog interact with the page that
 opened it, e.g. by updating parts of a larger form.
 
-To disable this behavior, give the opening link an [`up-sticky`](/up-modal#up-sticky) attribute:
+To disable this behavior, give the opening link an [`up-sticky`](/a-up-modal#up-sticky) attribute:
 
 
 \#\#\# Customizing the dialog design
@@ -64,24 +64,24 @@ up.modal = (($) ->
   Sets default options for future modals.
 
   @property up.modal.config
-  @param {String} [config.history=true]
+  @param {string} [config.history=true]
     Whether opening a modal will add a browser history entry.
-  @param {Number} [config.width]
+  @param {number} [config.width]
     The width of the dialog as a CSS value like `'400px'` or `'50%'`.
 
     Defaults to `undefined`, meaning that the dialog will grow to fit its contents
     until it reaches `config.maxWidth`. Leaving this as `undefined` will
     also allow you to control the width using CSS on `.up-modal-dialog´.
-  @param {Number} [config.maxWidth]
+  @param {number} [config.maxWidth]
     The width of the dialog as a CSS value like `'400px'` or `50%`.
     You can set this to `undefined` to make the dialog fit its contents.
     Be aware however, that e.g. Bootstrap stretches input elements
     to `width: 100%`, meaning the dialog will also stretch to the full
     width of the screen.
-  @param {Number} [config.height='auto']
+  @param {number} [config.height='auto']
     The height of the dialog in pixels.
     Defaults to `undefined`, meaning that the dialog will grow to fit its contents.
-  @param {String|Function(config)} [config.template]
+  @param {string|Function(config)} [config.template]
     A string containing the HTML structure of the modal.
     You can supply an alternative template string, but make sure that it
     defines tag with the classes `up-modal`, `up-modal-dialog` and  `up-modal-content`.
@@ -89,34 +89,34 @@ up.modal = (($) ->
     You can also supply a function that returns a HTML string.
     The function will be called with the modal options (merged from these defaults
     and any per-open overrides) whenever a modal opens.
-  @param {String} [config.closeLabel='×']
+  @param {string} [config.closeLabel='×']
     The label of the button that closes the dialog.
-  @param {Boolean} [config.closable=true]
+  @param {boolean} [config.closable=true]
     When `true`, the modal will render a close icon and close when the user
     clicks on the backdrop or presses Escape.
 
     When `false`, you need to either supply an element with `[up-close]` or
     close the modal manually with `up.modal.close()`.
-  @param {String} [config.openAnimation='fade-in']
+  @param {string} [config.openAnimation='fade-in']
     The animation used to open the viewport around the dialog.
-  @param {String} [config.closeAnimation='fade-out']
+  @param {string} [config.closeAnimation='fade-out']
     The animation used to close the viewport the dialog.
-  @param {String} [config.backdropOpenAnimation='fade-in']
+  @param {string} [config.backdropOpenAnimation='fade-in']
     The animation used to open the backdrop that dims the page below the dialog.
-  @param {String} [config.backdropCloseAnimation='fade-out']
+  @param {string} [config.backdropCloseAnimation='fade-out']
     The animation used to close the backdrop that dims the page below the dialog.
-  @param {Number} [config.openDuration]
+  @param {number} [config.openDuration]
     The duration of the open animation (in milliseconds).
-  @param {Number} [config.closeDuration]
+  @param {number} [config.closeDuration]
     The duration of the close animation (in milliseconds).
-  @param {String} [config.openEasing]
+  @param {string} [config.openEasing]
     The timing function controlling the acceleration of the opening animation.
-  @param {String} [config.closeEasing]
+  @param {string} [config.closeEasing]
     The timing function controlling the acceleration of the closing animation.
-  @param {Boolean} [options.sticky=false]
+  @param {boolean} [options.sticky=false]
     If set to `true`, the modal remains
     open even it changes the page in the background.
-  @param {String} [options.flavor='default']
+  @param {string} [options.flavor='default']
     The default [flavor](/up.modal.flavors).
   @stable
   ###
@@ -156,7 +156,7 @@ up.modal = (($) ->
 
   \#\#\# Example
 
-  Unpoly's [`[up-drawer]`](/up-drawer) is implemented as a modal flavor:
+  Unpoly's [`[up-drawer]`](/a-up-drawer) is implemented as a modal flavor:
 
       up.modal.flavors.drawer = {
         openAnimation: 'move-from-right',
@@ -197,7 +197,7 @@ up.modal = (($) ->
   or `undefined` if no modal is currently open.
 
   @function up.modal.url
-  @return {String}
+  @return {string}
     the source URL
   @stable
   ###
@@ -206,7 +206,7 @@ up.modal = (($) ->
   Returns the URL of the page behind the modal overlay.
 
   @function up.modal.coveredUrl
-  @return {String}
+  @return {string}
   @experimental
   ###
   
@@ -297,7 +297,7 @@ up.modal = (($) ->
   This also returns `true` if the modal is in an opening or closing animation.
 
   @function up.modal.isOpen
-  @return {Boolean}
+  @return {boolean}
   @stable
   ###
   isOpen = ->
@@ -314,42 +314,42 @@ up.modal = (($) ->
   Emits events [`up:modal:open`](/up:modal:open) and [`up:modal:opened`](/up:modal:opened).
 
   @function up.modal.follow
-  @param {Element|jQuery|String} linkOrSelector
+  @param {Element|jQuery|string} linkOrSelector
     The link to follow.
-  @param {String} [options.target]
+  @param {string} [options.target]
     The selector to extract from the response and open in a modal dialog.
-  @param {Number} [options.width]
+  @param {number} [options.width]
     The width of the dialog in pixels.
     By [default](/up.modal.config) the dialog will grow to fit its contents.
-  @param {Number} [options.height]
+  @param {number} [options.height]
     The width of the dialog in pixels.
     By [default](/up.modal.config) the dialog will grow to fit its contents.
-  @param {Boolean} [options.sticky=false]
+  @param {boolean} [options.sticky=false]
     If set to `true`, the modal remains
     open even it changes the page in the background.
-  @param {Boolean} [config.closable=true]
+  @param {boolean} [config.closable=true]
     When `true`, the modal will render a close icon and close when the user
     clicks on the backdrop or presses Escape.
 
     When `false`, you need to either supply an element with `[up-close]` or
     close the modal manually with `up.modal.close()`.
-  @param {String} [options.confirm]
+  @param {string} [options.confirm]
     A message that will be displayed in a cancelable confirmation dialog
     before the modal is being opened.
-  @param {String} [options.method="GET"]
+  @param {string} [options.method="GET"]
     Override the request method.
-  @param {Object} [options.history=true]
+  @param {boolean} [options.history=true]
     Whether to add a browser history entry for the modal's source URL.
-  @param {String} [options.animation]
+  @param {string} [options.animation]
     The animation to use when opening the modal.
-  @param {Number} [options.duration]
+  @param {number} [options.duration]
     The duration of the animation. See [`up.animate()`](/up.animate).
-  @param {Number} [options.delay]
+  @param {number} [options.delay]
     The delay before the animation starts. See [`up.animate()`](/up.animate).
-  @param {String} [options.easing]
+  @param {string} [options.easing]
     The timing function that controls the animation's acceleration. [`up.animate()`](/up.animate).
   @return {Promise}
-    A promise that will be resolved when the modal has been loaded and
+    A promise that will be fulfilled when the modal has been loaded and
     the opening animation has completed.
   @stable
   ###
@@ -358,6 +358,14 @@ up.modal = (($) ->
     options.$link = $(linkOrSelector)
     openAsap(options)
 
+  preloadNow = ($link, options) ->
+    options = u.options(options)
+    options.$link = $link
+    options.preload = true
+    # Use openNow() and not openAsap() so (1) we don't close a currently open modal
+    # and (2) our pending AJAX request does not prevent other modals from opening
+    openNow(options)
+
   ###*
   Opens a modal for the given URL.
 
@@ -371,15 +379,15 @@ up.modal = (($) ->
   Emits events [`up:modal:open`](/up:modal:open) and [`up:modal:opened`](/up:modal:opened).
 
   @function up.modal.visit
-  @param {String} url
+  @param {string} url
     The URL to load.
-  @param {String} options.target
+  @param {string} options.target
     The CSS selector to extract from the response.
     The extracted content will be placed into the dialog window.
   @param {Object} options
     See options for [`up.modal.follow()`](/up.modal.follow).
   @return {Promise}
-    A promise that will be resolved when the modal has been loaded and the opening
+    A promise that will be fulfilled when the modal has been loaded and the opening
     animation has completed.
   @stable
   ###
@@ -404,14 +412,14 @@ up.modal = (($) ->
   Emits events [`up:modal:open`](/up:modal:open) and [`up:modal:opened`](/up:modal:opened).
 
   @function up.modal.extract
-  @param {String} selector
+  @param {string} selector
     The CSS selector to extract from the HTML.
-  @param {String} html
+  @param {string} html
     The HTML containing the modal content.
   @param {Object} options
     See options for [`up.modal.follow()`](/up.modal.follow).
   @return {Promise}
-    A promise that will be resolved when the modal has been opened and the opening
+    A promise that will be fulfilled when the modal has been opened and the opening
     animation has completed.
   @stable
   ###
@@ -423,12 +431,7 @@ up.modal = (($) ->
     openAsap(options)
 
   openAsap = (options) ->
-    curriedOpenNow = -> openNow(options)
-    if isOpen()
-      chain.asap(closeNow, curriedOpenNow)
-    else
-      chain.asap(curriedOpenNow)
-    chain.promise()
+    chain.asap closeNow, (-> openNow(options))
 
   openNow = (options) ->
     options = u.options(options)
@@ -451,6 +454,7 @@ up.modal = (($) ->
     options.confirm = u.option(options.confirm, $link.attr('up-confirm'))
     options.method = up.link.followMethod($link, options)
     options.layer = 'modal'
+    options.failTarget = u.option(options.failTarget, $link.attr('up-fail-target'))
     options.failLayer = u.option(options.failLayer, $link.attr('up-fail-layer'), 'auto')
     animateOptions = up.motion.animateOptions(options, $link, duration: flavorDefault('openDuration', options.flavor), easing: flavorDefault('openEasing', options.flavor))
 
@@ -460,6 +464,13 @@ up.modal = (($) ->
     options.history = u.option(options.history, u.castedAttr($link, 'up-history'), flavorDefault('history', options.flavor))
     options.history = false unless up.browser.canPushState()
 
+    # This will prevent up.replace() from looking for fallbacks, since
+    # it knows the target will always exist.
+    options.provideTarget = -> createHiddenFrame(target, options)
+
+    if options.preload
+      return up.replace(target, url, options)
+
     up.browser.whenConfirmed(options).then ->
       up.bus.whenEmitted('up:modal:open', url: url, message: 'Opening modal').then ->
         state.phase = 'opening'
@@ -470,7 +481,6 @@ up.modal = (($) ->
         if options.history
           state.coveredUrl = up.browser.url()
           state.coveredTitle = document.title
-        options.provideTarget = -> createHiddenFrame(target, options)
         extractOptions = u.merge(options, animation: false)
         if html
           promise = up.extract(target, html, extractOptions)
@@ -512,20 +522,19 @@ up.modal = (($) ->
   @param {Object} options
     See options for [`up.animate()`](/up.animate)
   @return {Promise}
-    A promise that will be resolved once the modal's close
+    A promise that will be fulfilled once the modal's close
     animation has finished.
   @stable
   ###
   closeAsap = (options) ->
-    if isOpen()
-      chain.asap -> closeNow(options)
-    chain.promise()
+    chain.asap -> closeNow(options)
 
   closeNow = (options) ->
-    unless isOpen() # this can happen when a request fails and the chain proceeds to the next task
-      return u.resolvedPromise()
-
     options = u.options(options)
+
+    unless isOpen()
+      return Promise.resolve()
+
     viewportCloseAnimation = u.option(options.animation, flavorDefault('closeAnimation'))
     viewportCloseAnimation = u.evalOption(viewportCloseAnimation, position: state.position)
     backdropCloseAnimation = u.option(options.backdropAnimation, flavorDefault('backdropCloseAnimation'))
@@ -546,6 +555,7 @@ up.modal = (($) ->
       state.url = null
       state.coveredUrl = null
       state.coveredTitle = null
+
       promise = animate(viewportCloseAnimation, backdropCloseAnimation, animateOptions)
 
       promise = promise.then ->
@@ -569,13 +579,13 @@ up.modal = (($) ->
   animate = (viewportAnimation, backdropAnimation, animateOptions) ->
     # If we're not animating the dialog, don't animate the backdrop either
     if up.motion.isNone(viewportAnimation)
-      u.resolvedPromise()
+      Promise.resolve()
     else
       markAsAnimating()
-      promise = $.when(
+      promise = Promise.all([
         up.animate(state.$modal.find('.up-modal-viewport'), viewportAnimation, animateOptions),
         up.animate(state.$modal.find('.up-modal-backdrop'), backdropAnimation, animateOptions)
-      )
+      ])
       promise = promise.then -> markAsAnimating(false)
       promise
 
@@ -607,9 +617,9 @@ up.modal = (($) ->
   within the current modal.
 
   @function up.modal.contains
-  @param {String} elementOrSelector
+  @param {string} elementOrSelector
     The element to test
-  @return {Boolean}
+  @return {boolean}
   @stable
   ###
   contains = (elementOrSelector) ->
@@ -617,7 +627,7 @@ up.modal = (($) ->
     $element.closest('.up-modal').length > 0
 
   flavor = (name, overrideConfig = {}) ->
-    up.log.warn 'The up.modal.flavor function is deprecated. Use the up.modal.flavors property instead.'
+    up.log.warn 'up.modal.flavor() is deprecated. Use the up.modal.flavors property instead.'
     u.assign(flavorOverrides(name), overrideConfig)
 
   ###*
@@ -655,34 +665,34 @@ up.modal = (($) ->
   and place the matching `.blog-list` tag will be placed in
   a modal dialog.
 
-  @selector [up-modal]
-  @param {String} up-modal
+  @selector a[up-modal]
+  @param {string} up-modal
     The CSS selector that will be extracted from the response and displayed in a modal dialog.
-  @param {String} [up-confirm]
+  @param {string} [up-confirm]
     A message that will be displayed in a cancelable confirmation dialog
     before the modal is opened.
-  @param {String} [up-method='GET']
+  @param {string} [up-method='GET']
     Override the request method.
-  @param {String} [up-sticky]
+  @param {string} [up-sticky]
     If set to `"true"`, the modal remains
     open even if the page changes in the background.
-  @param {Boolean} [up-closable]
+  @param {boolean} [up-closable]
     When `true`, the modal will render a close icon and close when the user
     clicks on the backdrop or presses Escape.
 
     When `false`, you need to either supply an element with `[up-close]` or
     close the modal manually with `up.modal.close()`.
-  @param {String} [up-animation]
+  @param {string} [up-animation]
     The animation to use when opening the viewport containing the dialog.
-  @param {String} [up-backdrop-animation]
+  @param {string} [up-backdrop-animation]
     The animation to use when opening the backdrop that dims the page below the dialog.
-  @param {String} [up-height]
+  @param {string} [up-height]
     The width of the dialog in pixels.
     By [default](/up.modal.config) the dialog will grow to fit its contents.
-  @param {String} [up-width]
+  @param {string} [up-width]
     The width of the dialog in pixels.
     By [default](/up.modal.config) the dialog will grow to fit its contents.
-  @param {String} [up-history]
+  @param {string} [up-history]
     Whether to push an entry to the browser history for the modal's source URL.
 
     Set this to `'false'` to prevent the URL bar from being updated.
@@ -690,8 +700,10 @@ up.modal = (($) ->
 
   @stable
   ###
-  up.link.onAction '[up-modal]', ($link) ->
-    followAsap($link)
+  up.link.addFollowVariant '[up-modal]',
+    # Don't just pass the `follow` function reference so we can stub it in tests
+    follow: ($link, options) -> followAsap($link, options)
+    preload: ($link, options) -> preloadNow($link, options)
 
   # Close the modal when someone clicks outside the dialog (but not on a modal opener).
   # Note that we cannot listen to clicks on .up-modal-backdrop, which is a sister element
@@ -755,10 +767,10 @@ up.modal = (($) ->
   and place the matching `.blog-list` tag will be placed in
   a modal drawer.
 
-  @selector [up-drawer]
-  @param {String} up-drawer
+  @selector a[up-drawer]
+  @param {string} up-drawer
     The CSS selector to extract from the response and open in the drawer.
-  @param {String} [up-position='auto']
+  @param {string} [up-position='auto']
     The side from which the drawer slides in.
 
     Valid values are `'left'`, `'right'` and `'auto'`. If set to `'auto'`, the
@@ -766,7 +778,7 @@ up.modal = (($) ->
     Otherwise it will slide in from the right.
   @stable
   ###
-  up.macro '[up-drawer]', ($link) ->
+  up.macro 'a[up-drawer], [up-href][up-drawer]', ($link) ->
     target = $link.attr('up-drawer')
     $link.attr
       'up-modal': target
@@ -779,7 +791,7 @@ up.modal = (($) ->
   @param {Object} config
     Default options for future drawers.
 
-    See [`up.modal.config`] for available options.
+    See [`up.modal.config`](/up.modal.config) for available options.
   @experimental
   ###
   flavors.drawer =