upjs-rails 0.13.0 → 0.14.0

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

@@ -84,7 +84,6 @@ up.layout = (($) ->
   is called a second time, the previous animation will instantly jump to the
   last frame before the next animation is started.
 
-  @protected
   @function up.scroll
   @param {String|Element|jQuery} viewport
     The container element to scroll.
@@ -96,6 +95,7 @@ up.layout = (($) ->
     The timing function that controls the acceleration for the scrolling's animation.
   @return {Deferred}
     A promise that will be resolved when the scrolling ends.
+  @experimental
   ###
   scroll = (viewport, scrollTop, options) ->
     $viewport = $(viewport)
@@ -134,7 +134,9 @@ up.layout = (($) ->
 
   ###*
   @function up.layout.finishScrolling
-  @private
+  @param {String|Element|jQuery}
+    The element that might currently be scrolling.
+  @internal
   ###
   finishScrolling = (elementOrSelector) ->
     $(elementOrSelector).each ->
@@ -143,7 +145,7 @@ up.layout = (($) ->
 
   ###*
   @function up.layout.anchoredRight
-  @private
+  @internal
   ###
   anchoredRight = ->
     u.multiSelector(config.anchoredRight).select()
@@ -205,6 +207,7 @@ up.layout = (($) ->
     with the top edge of the viewport.
   @return {Deferred}
     A promise that will be resolved when the element is revealed.
+  @stable
   ###
   reveal = (elementOrSelector, options) ->
     u.debug('Revealing %o', elementOrSelector)
@@ -268,9 +271,9 @@ up.layout = (($) ->
 
   Throws an error if no viewport could be found.
 
-  @protected
   @function up.layout.viewportOf
   @param {String|Element|jQuery} selectorOrElement
+  @internal
   ###
   viewportOf = (selectorOrElement) ->
     $element = $(selectorOrElement)
@@ -282,10 +285,10 @@ up.layout = (($) ->
   Returns a jQuery collection of all the viewports contained within the
   given selector or element.
 
-  @protected
   @function up.layout.viewportsWithin
   @param {String|Element|jQuery} selectorOrElement
   @return jQuery
+  @internal
   ###
   viewportsWithin = (selectorOrElement) ->
     $element = $(selectorOrElement)
@@ -294,8 +297,8 @@ up.layout = (($) ->
   ###*
   Returns a jQuery collection of all the viewports on the screen.
 
-  @protected
   @function up.layout.viewports
+  @internal
   ###
   viewports = ->
     viewportSelector().select()
@@ -311,7 +314,7 @@ up.layout = (($) ->
 
   @function up.layout.scrollTops
   @return Object<String, Number>
-  @protected
+  @internal
   ###
   scrollTops = ->
     topsBySelector = {}
@@ -325,7 +328,7 @@ up.layout = (($) ->
 
   ###*
   @function up.layout.fixedChildren
-  @protected
+  @internal
   ###
   fixedChildren = (root = undefined) ->
     root ||= document.body
@@ -348,7 +351,7 @@ up.layout = (($) ->
   @function up.layout.saveScroll
   @param {String} [options.url]
   @param {Object<String, Number>} [options.tops]
-  @protected
+  @experimental
   ###
   saveScroll = (options = {}) ->
     url = u.option(options.url, up.history.url())
@@ -367,7 +370,7 @@ up.layout = (($) ->
   @param {jQuery} [options.around]
     If set, only restores viewports that are either an ancestor
     or descendant of the given element.
-  @protected
+  @experimental
   ###
   restoreScroll = (options = {}) ->
 
@@ -396,9 +399,10 @@ up.layout = (($) ->
     u.resolvedDeferred()
 
   ###*
-  @protected
   @function up.layout.revealOrRestoreScroll
-  @return {Deferred} A promise for when the revealing or scroll restauration ends
+  @return {Deferred}
+    A promise for when the revealing or scroll restauration ends
+  @internal
   ###
   revealOrRestoreScroll = (selectorOrElement, options) ->
     $element = $(selectorOrElement)
@@ -466,6 +470,7 @@ up.layout = (($) ->
       </div>
 
   @selector [up-viewport]
+  @stable
   ###
 
   ###*
@@ -480,6 +485,7 @@ up.layout = (($) ->
       <div class="top-nav" up-fixed="top">...</div>
 
   @selector [up-fixed=top]
+  @stable
   ###
 
   ###*
@@ -494,6 +500,7 @@ up.layout = (($) ->
       <div class="bottom-nav" up-fixed="bottom">...</div>
 
   @selector [up-fixed=bottom]
+  @stable
   ###
 
   up.on 'up:framework:reset', reset

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

@@ -102,6 +102,7 @@ up.link = (($) ->
     The selector to replace.
   @param {Object} options
     See options for [`up.replace`](/up.replace)
+  @stable
   ###
   visit = (url, options) ->
     options = u.options(options)
@@ -149,6 +150,10 @@ up.link = (($) ->
   @param {Object} [options.headers={}]
     An object of additional header key/value pairs to send along
     with the request.
+  @return {Promise}
+    A promise that will be resolved when the link destination
+    has been loaded and rendered.
+  @stable
   ###
   follow = (linkOrSelector, options) ->
     $link = $(linkOrSelector)
@@ -171,12 +176,12 @@ up.link = (($) ->
   Returns the HTTP method that should be used when following the given link.
 
   Looks at the link's `up-method` or `data-method` attribute.
-  Defaults to `get`.
+  Defaults to `"get"`.
 
-  @protected
   @function up.link.followMethod
   @param linkOrSelector
   @param options.method {String}
+  @internal
   ###
   followMethod = (linkOrSelector, options) ->
     $link = $(linkOrSelector)
@@ -245,6 +250,7 @@ up.link = (($) ->
     Whether to force the use of a cached response (`true`)
     or never use the cache (`false`)
     or make an educated guess (`undefined`).
+  @stable
   ###
   up.on 'click', 'a[up-target], [up-href][up-target]', (event, $link) ->
     if shouldProcessLinkEvent(event, $link)
@@ -273,6 +279,7 @@ up.link = (($) ->
   systems switch tabs on `mousedown` instead of `click`.
 
   @selector a[up-instant]
+  @stable
   ###
   up.on 'mousedown', 'a[up-instant], [up-href][up-instant]', (event, $link) ->
     if shouldProcessLinkEvent(event, $link)
@@ -281,7 +288,7 @@ up.link = (($) ->
 
   ###*
   @function up.link.childClicked
-  @private
+  @internal
   ###
   childClicked = (event, $link) ->
     $target = $(event.target)
@@ -295,10 +302,10 @@ up.link = (($) ->
   Makes sure that the given link is handled by Up.js.
 
   This is done by giving the link an `up-follow` attribute
-  if it doesn't already have it an `up-target` or `up-follow` attribute.
+  unless it already have it an `up-target` or `up-follow` attribute.
 
   @function up.link.makeFollowable
-  @protected
+  @internal
   ###
   makeFollowable = (link) ->
     $link = $(link)
@@ -313,8 +320,7 @@ up.link = (($) ->
 
       <a href="/users" up-follow>User list</a>
 
-  To only update a fragment instead of the entire page,
-  see [`up-target`](/up-target).
+  To only update a fragment instead of the entire page, see [`up-target`](/up-target).
 
   \#\#\#\# Turn any element into a link
 
@@ -333,6 +339,7 @@ up.link = (($) ->
   @param [up-restore-scroll='false']
     Whether to restore the scroll position of all viewports
     within the response.
+  @stable
   ###
   up.on 'click', 'a[up-follow], [up-href][up-follow]', (event, $link) ->
     if shouldProcessLinkEvent(event, $link)
@@ -360,6 +367,7 @@ up.link = (($) ->
   (`up-target`, `up-instant`, `up-preload`, etc.).
 
   @selector [up-expand]
+  @stable
   ###
   up.compiler '[up-expand]', ($area) ->
     link = $area.find('a, [up-href]').get(0)
@@ -392,6 +400,7 @@ up.link = (($) ->
       <a href="/users" up-target=".main" up-instant up-preload>User list</a>  
 
   @selector [up-dash]
+  @stable
   ###
   up.compiler '[up-dash]', ($element) ->
     target = u.castedAttr($element, 'up-dash')

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

@@ -119,6 +119,7 @@ up.modal = (($) ->
   @function up.modal.url
   @return {String}
     the source URL
+  @stable
   ###
   currentUrl = undefined
 
@@ -127,7 +128,7 @@ up.modal = (($) ->
 
   @function up.modal.coveredUrl
   @return {String}
-  @protected
+  @experimental
   ###
   coveredUrl = ->
     $modal = $('.up-modal')
@@ -238,7 +239,8 @@ up.modal = (($) ->
   @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 finished loading.
+    A promise that will be resolved when the popup has been loaded and rendered.
+  @stable
   ###
   follow = (linkOrSelector, options) ->
     options = u.options(options)
@@ -265,6 +267,9 @@ up.modal = (($) ->
     The extracted content will be placed into the dialog window.
   @param {Object} options
     See options for [previous `up.modal.open` variant](/up.modal.open).
+  @return {Promise}
+    A promise that will be resolved when the popup has been loaded and rendered.
+  @stable
   ###
   visit = (url, options) ->
     options = u.options(options)
@@ -272,12 +277,12 @@ up.modal = (($) ->
     open(options)
 
   ###*
-  @function up.modal.open
-  @private
+  @function open
+  @internal
   ###
   open = (options) ->
     options = u.options(options)
-    $link = u.option(options.$link, u.nullJquery())
+    $link = u.option(options.$link, u.nullJQuery())
     url = u.option(options.url, $link.attr('up-href'), $link.attr('href'))
     selector = u.option(options.target, $link.attr('up-modal'), 'body')
     width = u.option(options.width, $link.attr('up-width'), config.width)
@@ -314,12 +319,14 @@ up.modal = (($) ->
   @event up:modal:open
   @param event.preventDefault()
     Event listeners may call this method to prevent the modal from opening.
+  @stable
   ###
 
   ###*
   This event is [emitted](/up.emit) when a modal dialog has finished opening.
 
   @event up:modal:opened
+  @stable
   ###
 
   ###*
@@ -331,6 +338,7 @@ up.modal = (($) ->
   @function up.modal.close
   @param {Object} options
     See options for [`up.animate`](/up.animate)
+  @stable
   ###
   close = (options) ->
     $modal = $('.up-modal')
@@ -361,6 +369,7 @@ up.modal = (($) ->
   @event up:modal:close
   @param event.preventDefault()
     Event listeners may call this method to prevent the modal from closing.
+  @stable
   ###
 
   ###*
@@ -368,6 +377,7 @@ up.modal = (($) ->
   is done [closing](/up.modal.close).
 
   @event up:modal:closed
+  @stable
   ###
 
   autoclose = ->
@@ -381,7 +391,7 @@ up.modal = (($) ->
 
   @function up.modal.contains
   @param {String} elementOrSelector
-  @protected
+  @stable
   ###
   contains = (elementOrSelector) ->
     $element = $(elementOrSelector)
@@ -406,6 +416,7 @@ up.modal = (($) ->
   @param [up-height]
   @param [up-width]
   @param [up-history]
+  @stable
   ###
   up.on('click', 'a[up-modal]', (event, $link) ->
     event.preventDefault()
@@ -436,9 +447,16 @@ up.modal = (($) ->
 
   ###*
   When this element is clicked, closes a currently open dialog.
+
   Does nothing if no modal is currently open.
 
+  To make a link that closes the current modal, but follows to
+  a fallback destination if no modal is open:
+
+      <a href="/fallback" up-close>Okay</a>
+
   @selector [up-close]
+  @stable
   ###
   up.on('click', '[up-close]', (event, $element) ->
     if $element.closest('.up-modal').length

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

@@ -122,6 +122,7 @@ up.motion = (($) ->
     for a list of pre-defined timing functions.
   @return {Promise}
     A promise for the animation's end.
+  @stable
   ###
   animate = (elementOrSelector, animation, options) ->
     $element = $(elementOrSelector)
@@ -143,8 +144,8 @@ up.motion = (($) ->
   If `$element` is given, also inspects the element for animation-related
   attributes like `up-easing` or `up-duration`.
 
-  @protected
   @function up.motion.animateOptions
+  @internal
   ###
   animateOptions = (allOptions, $element = null) ->
     allOptions = u.options(allOptions)
@@ -227,6 +228,7 @@ up.motion = (($) ->
   
   @function up.motion.finish
   @param {Element|jQuery|String} elementOrSelector
+  @stable
   ###
   finish = (elementOrSelector) ->
     $(elementOrSelector).each ->
@@ -306,6 +308,7 @@ up.motion = (($) ->
     Whether to reveal the new element by scrolling its parent viewport.
   @return {Promise}
     A promise for the transition's end.
+  @stable
   ###  
   morph = (source, target, transitionOrName, options) ->
 
@@ -347,7 +350,7 @@ up.motion = (($) ->
   We use this to skip morphing for old browsers, or when the developer
   decides to only animate the new element (i.e. no real ghosting or transition)   .
 
-  @private
+  @internal
   ###
   skipMorph = ($old, $new, options) ->
     # Simply hide the old element, which would be the side effect of withGhosts(...) below.
@@ -357,7 +360,7 @@ up.motion = (($) ->
     up.layout.revealOrRestoreScroll($new, options)
 
   ###*
-  @private
+  @internal
   ###
   prependCopy = ($element, $viewport) ->
     elementDims = u.measure($element, relative: true, inner: true)
@@ -437,6 +440,7 @@ up.motion = (($) ->
   @function up.transition
   @param {String} name
   @param {Function} transition
+  @stable
   ###
   transition = (name, transition) ->
     transitions[name] = transition
@@ -470,6 +474,7 @@ up.motion = (($) ->
   @function up.animation
   @param {String} name
   @param {Function} animation
+  @stable
   ###
   animation = (name, animation) ->
     animations[name] = animation
@@ -488,6 +493,7 @@ up.motion = (($) ->
   @function up.motion.when
   @param promises...
   @return A new promise.
+  @experimental
   ###
   resolvableWhen = u.resolvableWhen
 
@@ -498,6 +504,7 @@ up.motion = (($) ->
   @function up.motion.none
   @return {Promise}
     A resolved promise
+  @stable
   ###
   none = u.resolvedDeferred
 

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

@@ -126,6 +126,7 @@ up.navigation = (($) ->
       <a href="/foo" up-follow up-current>Foo</a>
 
   @selector [up-active]
+  @stable
   ###
   sectionClicked = ($section) ->
     unmarkActive()
@@ -188,6 +189,7 @@ up.navigation = (($) ->
       <a href="/reports" up-alias="/reports/*">Reports</a>
 
   @selector [up-current]
+  @stable
   ###
   up.on 'up:fragment:inserted', ->
     # If a new fragment is inserted, it's likely to be the result

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

@@ -56,6 +56,7 @@ up.popup = (($) ->
   @function up.popup.url
   @return {String}
     the source URL
+  @stable
   ###
   currentUrl = undefined
 
@@ -64,7 +65,7 @@ up.popup = (($) ->
 
   @function up.popup.coveredUrl
   @return {String}
-  @protected
+  @experimental
   ###
   coveredUrl = ->
     $popup = $('.up-popup')
@@ -183,6 +184,9 @@ up.popup = (($) ->
     If set to `true`, the popup remains
     open even if the page changes in the background.
   @param {Object} [options.history=false]
+  @return {Promise}
+    A promise that will be resolved when the popup has been loaded and rendered.
+  @stable
   ###
   attach = (linkOrSelector, options) ->
     $link = $(linkOrSelector)
@@ -211,6 +215,7 @@ up.popup = (($) ->
   @function up.popup.close
   @param {Object} options
     See options for [`up.animate`](/up.animate).
+  @stable
   ###
   close = (options) ->
     $popup = $('.up-popup')
@@ -236,7 +241,7 @@ up.popup = (($) ->
 
   @methods up.popup.contains
   @param {String} elementOrSelector
-  @protected
+  @stable
   ###
   contains = (elementOrSelector) ->
     $element = $(elementOrSelector)
@@ -256,6 +261,7 @@ up.popup = (($) ->
   @selector a[up-popup]
   @param [up-sticky]
   @param [up-position]
+  @stable
   ###
   up.on('click', 'a[up-popup]', (event, $link) ->
     event.preventDefault()
@@ -289,6 +295,7 @@ up.popup = (($) ->
   a currently open popup is closed. 
   
   @selector [up-close]
+  @stable
   ###
   up.on('click', '[up-close]', (event, $element) ->
     if $element.closest('.up-popup').length

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

@@ -100,8 +100,15 @@ up.proxy = (($) ->
 
 
   ###*
-  @protected
+  Returns a cached response for the given request.
+
+  Returns `undefined` if the given request is not currently cached.
+
   @function up.proxy.get
+  @return {Promise}
+    A promise for the response that is API-compatible with the
+    promise returned by [`jQuery.ajax`](http://api.jquery.com/jquery.ajax/).
+  @experimental
   ###
   get = (request) ->
     request = normalizeRequest(request)
@@ -117,21 +124,41 @@ up.proxy = (($) ->
         return response
 
   ###*
-  @protected
+  Manually stores a promise for the response to the given request.
+
   @function up.proxy.set
+  @param {String} request.url
+  @param {String} [request.method='GET']
+  @param {String} [request.selector='body']
+  @param {Promise} response
+    A promise for the response that is API-compatible with the
+    promise returned by [`jQuery.ajax`](http://api.jquery.com/jquery.ajax/).
+  @experimental
   ###
   set = cache.set
 
   ###*
-  @protected
+  Manually removes the given request from the cache.
+
+  You can also [configure](/up.proxy.config) when the proxy
+  automatically removes cache entries.
+
   @function up.proxy.remove
+  @param {String} request.url
+  @param {String} [request.method='GET']
+  @param {String} [request.selector='body']
+  @experimental
   ###
   remove = cache.remove
 
   ###*
   Removes all cache entries.
 
+  Up.js also automatically clears the cache whenever it processes
+  a request with a non-GET HTTP method.
+
   @function up.proxy.clear
+  @stable
   ###
   clear = cache.clear
 
@@ -181,13 +208,17 @@ up.proxy = (($) ->
   @function up.proxy.ajax
   @param {String} request.url
   @param {String} [request.method='GET']
-  @param {String} [request.selector]
+  @param {String} [request.selector='body']
   @param {Boolean} [request.cache]
     Whether to use a cached response, if available.
     If set to `false` a network connection will always be attempted.
   @param {Object} [request.headers={}]
     An object of additional header key/value pairs to send along
     with the request.
+  @return
+    A promise for the response that is API-compatible with the
+    promise returned by [`jQuery.ajax`](http://api.jquery.com/jquery.ajax/).
+  @stable
   ###
   ajax = (options) ->
 
@@ -239,7 +270,9 @@ up.proxy = (($) ->
   used to busy, but is now idle.
 
   @function up.proxy.idle
-  @return {Boolean} Whether the proxy is idle
+  @return {Boolean}
+    Whether the proxy is idle
+  @experimental
   ###
   idle = ->
     pendingCount == 0
@@ -252,7 +285,9 @@ up.proxy = (($) ->
   used to be idle, but is now busy.
 
   @function up.proxy.busy
-  @return {Boolean} Whether the proxy is busy
+  @return {Boolean}
+    Whether the proxy is busy
+  @experimental
   ###
   busy = ->
     pendingCount > 0
@@ -288,6 +323,7 @@ up.proxy = (($) ->
   waiting, **no** additional `up:proxy:busy` events will be triggered.
 
   @event up:proxy:busy
+  @stable
   ###
 
   loadEnded = ->
@@ -301,6 +337,7 @@ up.proxy = (($) ->
   have [taken long to finish](/up:proxy:busy), but have finished now.
 
   @event up:proxy:idle
+  @stable
   ###
 
   load = (request) ->
@@ -315,10 +352,10 @@ up.proxy = (($) ->
   is starting to load.
 
   @event up:proxy:load
-  @protected
   @param event.url
   @param event.method
   @param event.selector
+  @experimental
   ###
 
   ###*
@@ -326,10 +363,10 @@ up.proxy = (($) ->
   has been received.
 
   @event up:proxy:received
-  @protected
   @param event.url
   @param event.method
   @param event.selector
+  @experimental
   ###
 
   isIdempotent = (request) ->
@@ -350,12 +387,12 @@ up.proxy = (($) ->
     preloadDelayTimer = setTimeout(block, delay)
 
   ###*
-  @protected
   @function up.proxy.preload
   @param {String|Element|jQuery}
     The element whose destination should be preloaded.
   @return
     A promise that will be resolved when the request was loaded and cached
+  @stable
   ###
   preload = (linkOrSelector, options) ->
     $link = $(linkOrSelector)
@@ -382,6 +419,7 @@ up.proxy = (($) ->
     The number of milliseconds to wait between hovering
     and preloading. Increasing this will lower the load in your server,
     but will also make the interaction feel less instant.
+  @stable
   ###
   up.on 'mouseover mousedown touchstart', '[up-preload]', (event, $element) ->
     # Don't do anything if we are hovering over the child