RubyGems - unpoly-rails - Versions diffs - 0.57.0 → 0.60.0 - Mend

unpoly-rails 0.57.0 → 0.60.0

Potentially problematic release.

This version of unpoly-rails might be problematic. Click here for more details.

Files changed (186) hide show

data/lib/assets/javascripts/unpoly/framework.coffee ADDED

@@ -0,0 +1,67 @@
+###**
+@module up.framework
+###
+up.framework = do ->
+  u = up.util
+  isBooting = true
+  ###**
+  Resets Unpoly to the state when it was booted.
+  All custom event handlers, animations, etc. that have been registered
+  will be discarded.
+  Emits event [`up:framework:reset`](/up:framework:reset).
+  @function up.framework.reset
+  @internal
+  ###
+  emitReset = ->
+    up.emit('up:framework:reset', log: 'Resetting framework')
+  ###**
+  This event is [emitted](/up.emit) when Unpoly is [reset](/up.framework.reset) during unit tests.
+  @event up:framework:reset
+  @internal
+  ###
+  ###**
+  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 = ->
+    if up.browser.isSupported()
+      # This is called synchronously after all Unpoly modules have been parsed
+      # and executed. User code hasn't been executed yet. Use this moment to
+      # tell everyone to snapshot
+      up.emit('up:framework:booted', log: 'Framework booted')
+      isBooting = false
+      # From here on, all event handlers (both Unpoly's and user code) should be able
+      # to work with the DOM, so wait for the DOM to be ready.
+      up.event.onReady ->
+        # In case the DOM was already ready when up.event.boot() was called, we still
+        # haven't executed user-provided code. So we wait one more frame until
+        # user-provided compilers, event handlers, etc. have been registered.
+        # This also gives async user-code a chance to run in the next microtask.
+        u.task ->
+          # At this point all user-code has been called.
+          # The following event will cause Unpoly to compile the <body>.
+          up.emit('up:app:boot', log: 'Booting user application')
+          up.emit('up:app:booted', log: 'User application booted')
+    else
+      console.log?("Unpoly doesn't support this browser. Framework was not booted.")
+  reset: emitReset
+  boot: boot
+  isBooting: -> isBooting

data/lib/assets/javascripts/unpoly/history.coffee CHANGED

@@ -6,11 +6,12 @@ In an Unpoly app, every page has an URL.
 [Fragment updates](/up.link) automatically update the URL.
-@class up.history
+@module up.history
 ###
-up.history = (($) ->
+up.history = do ->
   u = up.util
+  e = up.element
   ###**
   Configures behavior when the user goes back or forward in browser history.
@@ -24,7 +25,7 @@ up.history = (($) ->
     when the user goes back or forward in history.
   @stable
   ###
-  config = u.config
+  config = new up.Config
     enabled: true
     popTargets: ['body']
     restoreScroll: true
@@ -119,11 +120,11 @@ up.history = (($) ->
   push = (url, options) ->
     options = u.options(options, force: false)
     url = normalizeUrl(url)
-    if (options.force || !isCurrentUrl(url)) && up.bus.nobodyPrevents('up:history:push', url: url, message: "Adding history entry for #{url}")
+    if (options.force || !isCurrentUrl(url)) && up.event.nobodyPrevents('up:history:push', url: url, log: "Adding history entry for #{url}")
       if manipulate('pushState', url)
-        up.emit('up:history:pushed', url: url, message: "Advanced to location #{url}")
+        up.emit('up:history:pushed', url: url, log: "Advanced to location #{url}")
       else
-        up.emit('up:history:muted', url: url, message: "Did not advance to #{url} (history is unavailable)")
+        up.emit('up:history:muted', url: url, log: "Did not advance to #{url} (history is unavailable)")
   ###**
   This event is [emitted](/up.emit) before a new history entry is added.
@@ -162,27 +163,26 @@ up.history = (($) ->
       url = currentUrl()
       # We can't let people prevent this event, since `popstate` is also unpreventable.
-      up.emit('up:history:restore', url: url, message: "Restoring location #{url}")
+      up.emit('up:history:restore', url: url, log: "Restoring location #{url}")
       popSelector = config.popTargets.join(', ')
       replaced = up.replace popSelector, url,
         history: false,     # don't push a new state
         title: true,        # do extract the title from the response
         reveal: false,
-        transition: 'none',
         saveScroll: false   # since the URL was already changed by the browser, don't save scroll state
         restoreScroll: config.restoreScroll
         layer: 'page'       # Don't replace elements in a modal that might still be open
       replaced.then ->
         url = currentUrl()
-        up.emit('up:history:restored', url: url, message: "Restored location #{url}")
+        up.emit('up:history:restored', url: url, log: "Restored location #{url}")
     else
       up.puts 'Ignoring a state not pushed by Unpoly (%o)', state
   pop = (event) ->
     observeNewUrl(currentUrl())
-    up.layout.saveScroll(url: previousUrl)
-    state = event.originalEvent.state
+    up.viewport.saveScroll(url: previousUrl)
+    state = event.state
     restoreStateOnPop(state)
   ###**
@@ -207,19 +207,21 @@ up.history = (($) ->
   @experimental
   ###
-  if up.browser.canPushState()
-    register = ->
-      $(window).on "popstate", pop
-      replace(currentUrl(), force: true)
+  up.on 'up:app:boot', ->
+    if up.browser.canPushState()
+      register = ->
+        window.history.scrollRestoration = 'manual' if up.browser.canControlScrollRestoration()
+        window.addEventListener('popstate', pop)
+        replace(currentUrl(), force: true)
-    if jasmine?
-      # Can't delay this in tests.
-      register()
-    else
-      # Defeat an unnecessary popstate that some browsers trigger
-      # on pageload (Safari, Chrome < 34).
-      # We should check in 2023 if we can remove this.
-      setTimeout register, 100
+      if jasmine?
+        # Can't delay this in tests.
+        register()
+      else
+        # Defeat an unnecessary popstate that some browsers trigger
+        # on pageload (Safari, Chrome < 34).
+        # We should check in 2023 if we can remove this.
+        setTimeout(register, 100)
   ###**
   Changes the link's destination so it points to the previous URL.
@@ -246,13 +248,13 @@ up.history = (($) ->
   @selector a[up-back]
   @stable
   ###
-  up.macro 'a[up-back], [up-href][up-back]', ($link) ->
+  up.macro 'a[up-back], [up-href][up-back]', (link) ->
     if u.isPresent(previousUrl)
-      u.setMissingAttrs $link,
+      e.setMissingAttrs link,
         'up-href': previousUrl,
         'up-restore-scroll': ''
-      $link.removeAttr 'up-back'
-      up.link.makeFollowable($link)
+      link.removeAttribute('up-back')
+      up.link.makeFollowable(link)
   up.on 'up:framework:reset', reset
@@ -264,4 +266,3 @@ up.history = (($) ->
   previousUrl: -> previousUrl
   normalizeUrl: normalizeUrl
-)(jQuery)

data/lib/assets/javascripts/unpoly/legacy.coffee ADDED

@@ -0,0 +1,60 @@
+u = up.util
+up.legacy = do ->
+#  renamedProperty = (object, oldKey, newKey) ->
+#    warning = -> warn('Property { %s } has been renamed to { %s } (found in %o)', oldKey, newKey, object)
+#    Object.defineProperty object, oldKey,
+#      get: ->
+#        warning()
+#        @[newKey]
+#      set: (newValue) ->
+#        warning()
+#        @[newKey] = newValue
+#  removedProperty = (object, key) ->
+#    failure = -> up.fail('Deprecated: Property { %s } is no longer supported (found in %o)', key, object)
+#    Object.defineProperty object, key,
+#      get: failure
+#      set: failure
+  fixKey = (object, oldKey, newKey) ->
+    if oldKey of object
+      warn('Property { %s } has been renamed to { %s } (found in %o)', oldKey, newKey, object)
+      u.renameKey(object, oldKey, newKey)
+#  # Maps old event name to new event name
+#  renamedEvents = {}
+#
+#  renamedEvent = (oldName, newName) ->
+#    renamedEvents[oldName] = newName
+#
+#  fixEventName = (eventName) ->
+#    if newEventName = renamedEvents[eventName]
+#      warn("Event #{eventName} has been renamed to #{newEventName}")
+#      newEventName
+#    else
+#      eventName
+  renamedModule = (oldName, newName) ->
+    Object.defineProperty up, oldName, get: ->
+      warn("up.#{oldName} has been renamed to up.#{newName}")
+      up[newName]
+  warnedMessages = {}
+  warn = (message, args...) ->
+    message = "[DEPRECATION] #{message}"
+    message = up.log.sprintf(message, args...)
+    unless warnedMessages[message]
+      warnedMessages[message] = true
+      up.warn(message)
+  renamedModule: renamedModule
+#  renamedProperty: renamedProperty
+#  removedProperty: removedProperty
+#  renamedEvent: renamedEvent
+#  fixEventName: fixEventName
+  fixKey: fixKey
+  warn: warn

data/lib/assets/javascripts/unpoly/link.coffee.erb CHANGED

@@ -2,6 +2,10 @@
 Linking to fragments
 ====================
+The `up.link` module lets you build links that update fragments instead of entire pages.
+\#\#\# Motivation
 In a traditional web application, the entire page is destroyed and re-created when the
 user follows a link:
@@ -29,7 +33,7 @@ Pages also load much faster since the DOM, CSS and Javascript environments do no
 destroyed and recreated for every request.
-## Example
+\#\#\# Example
 Let's say we are rendering three pages with a tabbed navigation to switch between screens:
@@ -64,19 +68,21 @@ With these [`up-target`](/a-up-target) annotations Unpoly only updates the targe
 The JavaScript environment will persist and the user will not see a white flash while the
 new page is loading.
-@class up.link
+@module up.link
 ###
-up.link = (($) ->
+up.link = do ->
   u = up.util
+  e = up.element
   ###**
-  Visits the given URL without a full page load.
-  This is done by fetching `url` through an AJAX request
-  and [replacing](/up.replace) the current `<body>` element with the response's `<body>` element.
+  Fetches this given URL with JavaScript and [replaces](/up.replace) the
+  current `<body>` element with the response's `<body>` element.
-  For example, this would fetch the `/users` URL:
+  \#\#\# Example
+  This would replace the current page with the response for `/users`:
       up.visit('/users')
@@ -89,37 +95,34 @@ up.link = (($) ->
     See options for [`up.replace()`](/up.replace)
   @stable
   ###
-  visit = (url, options) ->
-    options = u.options(options)
-    selector = u.option(options.target, 'body')
+  visit = (url, options = {}) ->
+    selector = options.target ? 'body'
     up.replace(selector, url, options)
   ###**
-  Follows the given link via AJAX and [replaces](/up.replace) the current page
-  with HTML from the response.
+  Fetches the given link's `[href]` with JavaScript and [replaces](/up.replace) the current page with HTML from the response.
   By default the page's `<body>` element will be replaced.
-  If the link has an attribute like [`[up-target]`](/up-target)
-  or [`[up-modal]`](/a-up-modal), the corresponding UJS behavior will be activated
-  just as if the user had clicked on the link.
+  If the link has an attribute like `a[up-target]`
+  or `a[up-modal]`, the respective Unpoly behavior will be used.
-  Emits the event [`up:link:follow`](/up:link:follow).
+  Emits the event `up:link:follow`.
   \#\#\# Examples
-  Let's say you have a link with an [`a[up-target]`](/a-up-target) attribute:
+  Assume we have a link with an `a[up-target]` attribute:
       <a href="/users" up-target=".main">Users</a>
   Calling `up.follow()` with this link will replace the page's `.main` fragment
   as if the user had clicked on the link:
-      var $link = $('a:first');
-      up.follow($link);
+      var link = document.querSelector('a')
+      up.follow(link)
   @function up.follow
   @param {Element|jQuery|string} linkOrSelector
-    An element or selector which is either an `<a>` tag or any element with an `up-href` attribute.
+    An element or selector which is either an `<a>` tag or any element with an `[up-href]` attribute.
   @param {string} [options.target]
     The selector to replace.
@@ -143,9 +146,9 @@ up.link = (($) ->
   @stable
   ###
   follow = (linkOrSelector, options) ->
-    $link = $(linkOrSelector)
-    variant = followVariantForLink($link)
-    variant.followLink($link, options)
+    link = e.get(linkOrSelector)
+    variant = followVariantForLink(link)
+    variant.followLink(link, options)
   ###**
   This event is [emitted](/up.emit) when a link is [followed](/up.follow) through Unpoly.
@@ -153,7 +156,7 @@ up.link = (($) ->
   The event is emitted on the `<a>` element that is being followed.
   @event up:link:follow
-  @param {jQuery} event.$link
+  @param {Element} event.target
     The link element that will be followed.
   @param event.preventDefault()
     Event listeners may call this method to prevent the link from being followed.
@@ -164,36 +167,33 @@ up.link = (($) ->
   @function defaultFollow
   @internal
   ###
-  defaultFollow = (linkOrSelector, options) ->
-    $link = $(linkOrSelector)
+  defaultFollow = (link, options) ->
     options = u.options(options)
-    url = u.option(options.url, $link.attr('up-href'), $link.attr('href'))
-    target = u.option(options.target, $link.attr('up-target'))
-    options.failTarget = u.option(options.failTarget, $link.attr('up-fail-target'))
-    options.fallback = u.option(options.fallback, $link.attr('up-fallback'))
-    options.transition = u.option(options.transition, u.castedAttr($link, 'up-transition'), 'none')
-    options.failTransition = u.option(options.failTransition, u.castedAttr($link, 'up-fail-transition'), 'none')
-    options.history = u.option(options.history, u.castedAttr($link, 'up-history'))
-    options.reveal = u.option(options.reveal, u.castedAttr($link, 'up-reveal'), true)
-    options.failReveal = u.option(options.failReveal, u.castedAttr($link, 'up-fail-reveal'), true)
-    options.cache = u.option(options.cache, u.castedAttr($link, 'up-cache'))
-    options.restoreScroll = u.option(options.restoreScroll, u.castedAttr($link, 'up-restore-scroll'))
-    options.method = followMethod($link, options)
-    options.origin = u.option(options.origin, $link)
-    options.layer = u.option(options.layer, $link.attr('up-layer'), 'auto')
-    options.failLayer = u.option(options.failLayer, $link.attr('up-fail-layer'), 'auto')
-    options.confirm = u.option(options.confirm, $link.attr('up-confirm'))
-    options = u.merge(options, up.motion.animateOptions(options, $link))
+    url = options.url ? link.getAttribute('up-href') ? link.getAttribute('href')
+    target = options.target ? link.getAttribute('up-target')
+    options.failTarget ?= link.getAttribute('up-fail-target')
+    options.fallback ?= link.getAttribute('up-fallback')
+    options.transition ?= e.booleanOrStringAttr(link, 'up-transition')
+    options.failTransition ?= e.booleanOrStringAttr(link, 'up-fail-transition')
+    options.history ?= e.booleanOrStringAttr(link, 'up-history')
+    options.reveal ?= e.booleanOrStringAttr(link, 'up-reveal') ? true
+    options.failReveal ?= e.booleanOrStringAttr(link, 'up-fail-reveal') ? true
+    options.cache ?= e.booleanAttr(link, 'up-cache')
+    options.restoreScroll ?= e.booleanAttr(link, 'up-restore-scroll') # the option may contain an Object, but not the attr
+    options.method = followMethod(link, options)
+    options.origin ?= link
+    options.layer ?= link.getAttribute('up-layer')
+    options.failLayer ?= link.getAttribute('up-fail-layer')
+    options.confirm ?= link.getAttribute('up-confirm')
+    options = u.merge(options, up.motion.animateOptions(options, link))
     up.browser.whenConfirmed(options).then ->
       up.replace(target, url, options)
-  defaultPreload = ($link, options) ->
+  defaultPreload = (link, options) ->
     options = u.options(options)
     options.preload = true
-    defaultFollow($link, options)
+    defaultFollow(link, options)
   ###**
   Returns the HTTP method that should be used when following the given link.
@@ -202,14 +202,13 @@ up.link = (($) ->
   Defaults to `"get"`.
   @function up.link.followMethod
-  @param linkOrSelector
+  @param link
   @param options.method {string}
   @internal
   ###
-  followMethod = (linkOrSelector, options) ->
-    $link = $(linkOrSelector)
-    options = u.options(options)
-    u.option(options.method, $link.attr('up-method'), $link.attr('data-method'), 'get').toUpperCase()
+  followMethod = (link, options = {}) ->
+    rawMethod = options.method ? link.getAttribute('up-method') ? link.getAttribute('data-method') ? 'GET'
+    rawMethod.toUpperCase()
   ###**
   No-op that is called when we allow a browser's default action to go through,
@@ -233,8 +232,8 @@ up.link = (($) ->
   @function up.link.addFollowVariant
   @param {string} simplifiedSelector
     A selector without `a` or `[up-href]`, e.g. `[up-target]`
-  @param {Function(jQuery, Object)} options.follow
-  @param {Function(jQuery, Object)} options.preload
+  @param {Function(element, options)} options.follow
+  @param {Function(element, options)} options.preload
   @internal
   ###
   addFollowVariant = (simplifiedSelector, options) ->
@@ -244,40 +243,41 @@ up.link = (($) ->
     variant
   ###**
-  Returns whether the given link will be handled by Unpoly instead of making a full page load.
+  Returns whether the given link will be [followed](/up.follow) by Unpoly
+  instead of making a full page load.
-  A link will be handled by Unpoly if it has an attribute
-  like `up-target` or `up-modal`.
+  A link will be followed by Unpoly if it has an attribute
+  like `a[up-target]` or `a[up-modal]`.
   @function up.link.isFollowable
   @param {Element|jQuery|string} linkOrSelector
     The link to check.
   @experimental
   ###
-  isFollowable = (link) ->
-    !!followVariantForLink(link, default: false)
+  isFollowable = (linkOrSelector) ->
+    linkOrSelector = e.get(linkOrSelector)
+    !!followVariantForLink(linkOrSelector, default: false)
   ###**
   Returns the handler function that can be used to follow the given link.
   E.g. it wil return a handler calling `up.modal.follow` if the link is a `[up-modal]`,
   but a handler calling `up.link.follow` if the links is `[up-target]`.
-  @param {Element|jQuery|string}
-  @return {Function(jQuery)}
+  @param {Element} link
+  @return {Object}
   @internal
   ###
-  followVariantForLink = (linkOrSelector, options) ->
-    options = u.options(options)
-    $link = $(linkOrSelector)
-    variant = u.detect followVariants, (variant) -> variant.matchesLink($link)
+  followVariantForLink = (link, options = {}) ->
+    variant = u.find followVariants, (variant) -> variant.matchesLink(link)
     variant ||= DEFAULT_FOLLOW_VARIANT unless options.default is false
     variant
   ###**
-  Makes sure that the given link will be handled by Unpoly instead of making a full page load.
+  Makes sure that the given link will be [followed](/up.follow)
+  by Unpoly instead of making a full page load.
-  This is done by giving the link an `up-follow` attribute
-  unless it already have it an attribute like `up-target` or `up-modal`.
+  This is done by giving the link an `a[up-follow]` attribute
+  unless it already have it an attribute like `a[up-target]` or `a[up-modal]`.
   @function up.link.makeFollowable
   @param {Element|jQuery|string} linkOrSelector
@@ -285,21 +285,20 @@ up.link = (($) ->
   @experimental
   ###
   makeFollowable = (link) ->
-    $link = $(link)
-    unless isFollowable($link)
-      $link.attr('up-follow', '')
+    unless isFollowable(link)
+      link.setAttribute('up-follow', '')
-  shouldProcessEvent = (event, $link) ->
+  shouldProcessEvent = (event, link) ->
     target = event.target
     # We never handle events for the right mouse button, or when Shift/CTRL/Meta is pressed
     return false unless u.isUnmodifiedMouseEvent(event)
-    # If we actually targeted $link, save ourselves the expensive DOM traversal below
-    return true if target == $link.get(0)
+    # If we actually targeted `link`, save ourselves the expensive DOM traversal below
+    return true if target == link
     # If user clicked on a child link of $link, or in an <input> within an [up-expand][up-href]
     # we want those other elements handle the click.
-    $betterTarget = $(target).closest("a, [up-href], #{up.form.fieldSelector()}").not($link)
-    return false if $betterTarget.length
-    return true
+    betterTargetSelector = "a, [up-href], #{up.form.fieldSelector()}"
+    betterTarget = e.closest(target, betterTargetSelector)
+    return !betterTarget || betterTarget == link
   ###**
   Returns whether the given link has a [safe](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1)
@@ -309,20 +308,26 @@ up.link = (($) ->
   @experimental
   ###
   isSafe = (selectorOrLink, options) ->
-    $link = $(selectorOrLink)
-    method = followMethod($link, options)
+    method = followMethod(selectorOrLink, options)
     up.proxy.isSafeMethod(method)
   ###**
-  Follows this link via AJAX and replaces a CSS selector in the current page
-  with corresponding elements from a new page fetched from the server:
+  [Follows](/up.follow) this link with JavaScript and replaces a CSS selector
+  on the current page with a corresponding element from the response.
+  \#\#\# Example
+  This will update the fragment `<div class="main">` with the same element
+  fetched from `/posts/5`:
       <a href="/posts/5" up-target=".main">Read post</a>
   \#\#\# Updating multiple fragments
   You can update multiple fragments from a single request by separating
-  separators with a comma (like in CSS). E.g. if opening a post should
+  separators with a comma (like in CSS).
+  For instance, if opening a post should
   also update a bubble showing the number of unread posts, you might
   do this:
@@ -331,7 +336,7 @@ up.link = (($) ->
   \#\#\# Appending or prepending content
   By default Unpoly will replace the given selector with the same
-  selector from a freshly fetched page. Instead of replacing you
+  selector from the server response. Instead of replacing you
   can *append* the loaded content to the existing content by using the
   `:after` pseudo selector. In the same fashion, you can use `:before`
   to indicate that you would like the *prepend* the loaded content.
@@ -353,7 +358,7 @@ up.link = (($) ->
   \#\#\# Following elements that are no links
   You can also use `[up-target]` to turn an arbitrary element into a link.
-  In this case, put the link's destination into the `up-href` attribute:
+  In this case, put the link's destination into the `[up-href]` attribute:
       <button up-target=".main" up-href="/foo/bar">Go</button>
@@ -420,15 +425,14 @@ up.link = (($) ->
   ###
   DEFAULT_FOLLOW_VARIANT = addFollowVariant '[up-target], [up-follow]',
     # Don't just pass the `defaultFollow` function reference so we can stub it in tests
-    follow: ($link, options) -> defaultFollow($link, options)
-    preload: ($link, options) -> defaultPreload($link, options)
+    follow: (link, options) -> defaultFollow(link, options)
+    preload: (link, options) -> defaultPreload(link, options)
   ###**
-  If applied on a link, follows this link via AJAX and replaces the
+  Fetches this link's `[href]` with JavaScript and [replaces](/up.replace) the
   current `<body>` element with the response's `<body>` element.
-  To only update a fragment instead of the entire page, see
-  [`a[up-target]`](/a-up-target).
+  To only update a fragment instead of the entire `<body>`, see `a[up-target]`.
   \#\#\# Example
@@ -485,19 +489,19 @@ up.link = (($) ->
   AJAX request will be triggered right way, the interaction will
   appear faster.
-  Note that using `[up-instant]` will prevent a user from canceling a link
-  click by moving the mouse away from the interaction area. However, for
+  Note that using `[up-instant]` will prevent a user from canceling a
+  click by moving the mouse away from the link. However, for
   navigation actions this isn't needed. E.g. popular operation
   systems switch tabs on `mousedown` instead of `click`.
-  `up-instant` will also work for links that open [modals](/up.modal) or [popups](/up.popup).
+  `[up-instant]` will also work for links that open [modals](/up.modal) or [popups](/up.popup).
   @selector a[up-instant]
   @stable
   ###
   ###**
-  Marks up the current link to be followed *as fast as possible*.
+  [Follows](/up.follow) this link *as fast as possible*.
   This is done by:
@@ -505,20 +509,26 @@ up.link = (($) ->
   - [Preloading the link's destination URL](/a-up-preload)
   - [Triggering the link on `mousedown`](/a-up-instant) instead of on `click`
+  \#\#\# Example
   Use `up-dash` like this:
       <a href="/users" up-dash=".main">User list</a>
-  Note that this is shorthand for:
+  This is shorthand for:
       <a href="/users" up-target=".main" up-instant up-preload>User list</a>
   @selector a[up-dash]
+  @param {string} [up-dash='body']
+    The CSS selector to replace
+    Inside the CSS selector you may refer to this link as `&` ([like in Sass](https://sass-lang.com/documentation/file.SASS_REFERENCE.html#parent-selector)).
   @stable
   ###
-  up.macro '[up-dash]', ($element) ->
-    target = u.castedAttr($element, 'up-dash')
-    $element.removeAttr('up-dash')
+  up.macro '[up-dash]', (element) ->
+    target = e.booleanOrStringAttr(element, 'up-dash')
+    element.removeAttribute('up-dash')
     newAttrs = {
       'up-preload': '',
       'up-instant': ''
@@ -526,17 +536,19 @@ up.link = (($) ->
     if target is true
       # If it's literally `true` then we don't have a target selector.
       # Just follow the link by replacing `<body>`.
-      makeFollowable($element)
+      makeFollowable(element)
     else
       newAttrs['up-target'] = target
-    u.setMissingAttrs($element, newAttrs)
+    e.setMissingAttrs(element, newAttrs)
   ###**
-  Add an `[up-expand]` attribute to any element that contains a link
-  in order to enlarge the link's click area.
+  Add an `[up-expand]` attribute to any element to enlarge the click area of an
+  descendant link.
+  `[up-expand]` honors all the Unppoly attributes in expanded links, like
+  `a[up-target]`, `a[up-instant]` or `a[up-preload]`.
+  It also expands links that open [modals](/up.modal) or [popups](/up.popup).
-  `[up-expand]` honors all the UJS behavior in expanded links
-  ([`a[up-target]`](/a-up-target), [`a[up-instant]`](/a-up-instant), [`a[up-preload]`](/a-up-preload), etc.).
   \#\#\# Example
@@ -548,8 +560,6 @@ up.link = (($) ->
   In the example above, clicking anywhere within `.notification` element
   would [follow](/up.follow) the *Close* link.
-  `up-expand` also expands links that open [modals](/up.modal) or [popups](/up.popup).
   \#\#\# Elements with multiple contained links
   If a container contains more than one link, you can set the value of the
@@ -566,7 +576,7 @@ up.link = (($) ->
   `[up-expand]` has some limitations for advanced browser users:
   - Users won't be able to right-click the expanded area to open a context menu
-  - Users won't be able to CTRL+click the expanded area to open a new tab
+  - Users won't be able to `CTRL`+click the expanded area to open a new tab
   To overcome these limitations, consider nesting the entire clickable area in an actual `<a>` tag.
   [It's OK to put block elements inside an anchor tag](https://makandracards.com/makandra/43549-it-s-ok-to-put-block-elements-inside-an-a-tag).
@@ -575,24 +585,24 @@ up.link = (($) ->
   @param {string} [up-expand]
     A CSS selector that defines which containing link should be expanded.
-    If omitted, the first contained link will be expanded.
+    If omitted, the first link in this element will be expanded.
   @stable
   ###
-  up.macro '[up-expand]', ($area) ->
-    $childLinks = $area.find('a, [up-href]')
-    if selector = $area.attr('up-expand')
-      $childLinks = $childLinks.filter(selector)
-    if link = $childLinks.get(0)
+  up.macro '[up-expand]', (area) ->
+    selector = area.getAttribute('up-expand') || 'a, [up-href]'
+    childLinks = e.all(area, selector)
+    if childLink = childLinks[0]
       upAttributePattern = /^up-/
       newAttrs = {}
-      newAttrs['up-href'] = $(link).attr('href')
-      for attribute in link.attributes
+      newAttrs['up-href'] = childLink.getAttribute('href')
+      for attribute in childLink.attributes
         name = attribute.name
         if name.match(upAttributePattern)
           newAttrs[name] = attribute.value
-      u.setMissingAttrs($area, newAttrs)
-      $area.removeAttr('up-expand')
-      makeFollowable($area)
+      e.setMissingAttrs(area, newAttrs)
+      area.removeAttribute('up-expand')
+      makeFollowable(area)
   <% if ENV['JS_KNIFE'] %>knife: eval(Knife.point)<% end %>
   visit: visit
@@ -606,7 +616,5 @@ up.link = (($) ->
   followVariantForLink: followVariantForLink
   allowDefault: allowDefault
-)(jQuery)
 up.visit = up.link.visit
 up.follow = up.link.follow