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/classes/tether.coffee ADDED

@@ -0,0 +1,105 @@
+u = up.util
+e = up.element
+class up.Tether
+  constructor: (options) ->
+    @anchor = options.anchor
+    [@position, @align] = options.position.split('-')
+    if @align
+      up.legacy.warn('The position value %o is deprecated. Use %o instead.', options.position, @describeConstraints())
+    else
+      @align = options.align
+    @alignAxis = if @position == 'top' || @position == 'bottom' then 'horizontal' else 'vertical'
+    @viewport = up.viewport.closest(@anchor)
+    # The document viewport is <html> on some browsers, and we cannot attach children to that.
+    @parent = if @viewport == e.root() then document.body else @viewport
+    # If the offsetParent is within the viewport (or is the viewport)
+    # we can simply absolutely position it and it will move as the viewport scrolls.
+    # If not however, we have no choice but to move it on every scroll event.
+    @syncOnScroll = !@viewport.contains(@anchor.offsetParent)
+    @root = e.affix(@parent, '.up-bounds')
+    @setBoundsOffset(0, 0)
+    @changeEventSubscription('on')
+  destroy: ->
+    e.remove(@root)
+    @changeEventSubscription('off')
+  changeEventSubscription: (fn) ->
+    up[fn](window, 'resize', @scheduleSync)
+    up[fn](@viewport, 'scroll', @scheduleSync) if @syncOnScroll
+  scheduleSync: =>
+    clearTimeout(@syncTimer)
+    @syncTimer = u.task(@sync)
+  sync: =>
+    rootBox = @root.getBoundingClientRect()
+    anchorBox = @anchor.getBoundingClientRect()
+    left = undefined
+    top = undefined
+    switch @alignAxis
+      when 'horizontal'
+        top = switch @position
+          when 'top'
+            anchorBox.top - rootBox.height
+          when 'bottom'
+            anchorBox.top + anchorBox.height
+        left = switch @align
+          when 'left'
+            # anchored to anchor's left, grows to the right
+            anchorBox.left
+          when 'center'
+            # anchored to anchor's horizontal center, grows equally to left/right
+            anchorBox.left + 0.5 * (anchorBox.width - rootBox.width)
+          when 'right'
+            # anchored to anchor's right, grows to the left
+            anchorBox.left + anchorBox.width - rootBox.width
+      when 'vertical'
+        top = switch @align
+          when 'top'
+            # anchored to the top, grows to the bottom
+            anchorBox.top
+          when 'center'
+            # anchored to anchor's vertical center, grows equally to left/right
+            anchorBox.top + 0.5 * (anchorBox.height - rootBox.height)
+          when 'bottom'
+            # anchored to the bottom, grows to the top
+            anchorBox.top + anchorBox.height - rootBox.height
+        left = switch @position
+          when 'left'
+            anchorBox.left - rootBox.width
+          when 'right'
+            anchorBox.left + anchorBox.width
+    if u.isDefined(left) || u.isDefined(top)
+      @moveTo(left, top)
+    else
+      up.fail('Invalid tether constraints: %o', @describeConstraints())
+  describeConstraints: ->
+    { @position, @align }
+  moveTo: (targetLeft, targetTop) ->
+    rootBox = @root.getBoundingClientRect()
+    @setBoundsOffset(
+      targetLeft - rootBox.left + @offsetLeft,
+      targetTop - rootBox.top + @offsetTop
+    )
+  setBoundsOffset: (left, top) ->
+    @offsetLeft = left
+    @offsetTop = top
+    e.setStyle(@root, { left, top })

data/lib/assets/javascripts/unpoly/classes/url_set.coffee CHANGED

@@ -8,20 +8,25 @@ class up.UrlSet
     @urls = u.compact(@urls)
   matches: (testUrl) =>
-    if testUrl.substr(-1) == '*'
-      @doesMatchPrefix(testUrl.slice(0, -1))
+    if testUrl.indexOf('*') >= 0
+      @doesMatchPattern(testUrl)
     else
       @doesMatchFully(testUrl)
   doesMatchFully: (testUrl) =>
     u.contains(@urls, testUrl)
-  doesMatchPrefix: (prefix) =>
-    u.detect @urls, (url) ->
-      url.indexOf(prefix) == 0
+  doesMatchPattern: (pattern) =>
+    placeholder = "__ASTERISK__"
+    pattern = pattern.replace(/\*/g, placeholder)
+    pattern = u.escapeRegexp(pattern)
+    pattern = pattern.replace(new RegExp(placeholder, 'g'), '.*?')
+    pattern = new RegExp('^' + pattern + '$')
+    u.find @urls, (url) -> pattern.test(url)
   matchesAny: (testUrls) =>
-    u.detect(testUrls, @matches)
+    u.find(testUrls, @matches)
-  isEqual: (otherSet) =>
+  "#{u.isEqual.key}": (otherSet) =>
     u.isEqual(@urls, otherSet?.urls)

data/lib/assets/javascripts/unpoly/element.coffee.erb ADDED

@@ -0,0 +1,1126 @@
+#= require ./classes/selector
+###**
+DOM helpers
+===========
+The `up.element` module offers functions for DOM manipulation and traversal.
+It complements [native `Element` methods](https://www.w3schools.com/jsref/dom_obj_all.asp) and works across all [supported browsers](/up.browser).
+@module up.element
+###
+up.element = do ->
+  u = up.util
+  ###**
+  Returns a null-object that mostly behaves like an `Element`.
+  @function up.element.none()
+  @internal
+  ###
+  NONE = { getAttribute: -> undefined }
+  ###**
+  Matches all elements that have a descendant matching the given selector.
+  \#\#\# Example
+  `up.element.all('div:has(span)')`  matches all `<div>` elements with at least one `<span>` among its descendants:
+  ```html
+  <div>
+    <span>Will be matched</span>
+  </div>
+  <div>
+    Will NOT be matched
+  </div>
+  <div>
+    <span>Will be matched</span>
+  </div>
+  ```
+  \#\#\# Compatibility
+  `:has()` is supported by all Unpoly functions (like `up.element.all()`) and
+   selectors (like `a[up-target]`).
+  As a [level 4 CSS selector](https://drafts.csswg.org/selectors-4/#relational),
+  `:has()` [has yet to be implemented](https://caniuse.com/#feat=css-has)
+  in native browser functions like [`document.querySelectorAll()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/querySelectorAll).
+  You can also use [`:has()` in jQuery](https://api.jquery.com/has-selector/).
+  @selector :has()
+  @experimental
+  ###
+  parseSelector = (selector) ->
+    up.Selector.parse(selector)
+  ###**
+  Returns the first descendant element matching the given selector.
+  It is similar to [`element.querySelector()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector),
+  but also supports the [`:has()`](/has) selector.
+  @function up.element.first
+  @param {Element} [parent=document]
+    The parent element whose descendants to search.
+    If omitted, all elements in the `document` will be searched.
+  @param {string} selector
+    The CSS selector to match.
+  @return {Element|undefined|null}
+    The first element matching the selector.
+    Returns `null` or `undefined` if no element macthes.
+  @experimental
+  ###
+  first = (args...) ->
+    selector = args.pop()
+    parent = args[0] ? document
+    parseSelector(selector).descendant(parent)
+  ###**
+  Returns all descendant elements matching the given selector.
+  @function up.element.all
+  @param {Element} [parent=document]
+    The parent element whose descendants to search.
+    If omitted, all elements in the `document` will be searched.
+  @param {string} selector
+    The CSS selector to match.
+  @return {NodeList<Element>|Array<Element>}
+    A list of all elements matching the selector.
+    Returns an empty list if there are no matches.
+  @experimental
+  ###
+  all = (args...) ->
+    selector = args.pop()
+    parent = args[0] ? document
+    parseSelector(selector).descendants(parent)
+  ###**
+  Returns a list of the given parent's descendants matching the given selector.
+  The list will also include the parent element if it matches the selector itself.
+  @function up.element.subtree
+  @param {Element} parent
+    The parent element for the search.
+  @param {string} selector
+    The CSS selector to match.
+  @return {NodeList<Element>|Array<Element>}
+    A list of all matching elements.
+  @experimental
+  ###
+  subtree = (root, selector) ->
+    parseSelector(selector).subtree(root)
+  ###**
+  Returns the first element that matches the selector by testing the element itself
+  and traversing up through its ancestors in the DOM tree.
+  @function up.element.closest
+  @param {Element} element
+    The element on which to start the search.
+  @param {string}
+    The CSS selector to match.
+  @return {Element|null|undefined} element
+    The matching element.
+    Returns `null` or `undefined` if no element matches.
+  @experimental
+  ###
+  closest = (element, selector) ->
+    parseSelector(selector).closest(element)
+  ###**
+  Returns whether the given element matches the given CSS selector.
+  @function up.element.matches
+  @param {Element} element
+    The element to check.
+  @param {string} selector
+    The CSS selector to match.
+  @return {boolean}
+    Whether `element` matches `selector`.
+  @experimental
+  ###
+  matches = (element, selector) ->
+    parseSelector(selector).matches(element)
+  ###**
+  @function up.element.ancestor
+  @internal
+  ###
+  ancestor = (element, selector) ->
+    parseSelector(selector).ancestor(element)
+  ###**
+  Casts the given value to a native [Element](https://developer.mozilla.org/en-US/docs/Web/API/Element).
+  This is useful when working with jQuery values, or to allow callers to pass CSS selectors
+  instead of elements.
+  \#\#\# Casting rules
+  - If given an element, returns that element.
+  - If given a CSS selector string, returns the [first element matching](/up.element.first) that selector.
+  - If given a jQuery collection , returns the first element in the collection.
+    Throws an error if the collection contains more than one element.
+  - If given any other argument (`undefined`, `null`, `document`, `window`…), returns the argument unchanged.
+  @function up.element.get
+  @param {Element|jQuery|string} value
+    The value to cast.
+  @return {Element}
+    The obtained `Element`.
+  @experimental
+  ###
+  getOne = (value) ->
+    if u.isElement(value) # Return an element before we run any other expensive checks
+      value
+    else if u.isString(value)
+      first(value)
+    else if u.isJQuery(value)
+      if value.length > 1
+        up.fail('up.element.get(): Cannot cast multiple elements (%o) to a single element', value)
+      value[0]
+    else
+      # undefined, null, Window, Document, DocumentFragment, ...
+      value
+  ###**
+  Composes a list of elements from the given arguments.
+  \#\#\# Casting rules
+  - If given a string, returns the all elements matching that string.
+  - If given any other argument, returns the argument [wrapped as a list](/up.util.wrapList).
+  \#\#\# Example
+  ```javascript
+  $jquery = $('.jquery')                          // returns jQuery (2) [div.jquery, div.jquery]
+  nodeList = document.querySelectorAll('.node')   // returns NodeList (2) [div.node, div.node]
+  element = document.querySelector('.element')    // returns Element div.element
+  selector = '.selector'                          // returns String '.selector'
+  elements = up.element.list($jquery, nodeList, undefined, element, selector)
+  // returns [div.jquery, div.jquery, div.node, div.node, div.element, div.selector]
+  ```
+  @function up.element.list
+  @param {Array<jQuery|Element|Array<Element>|String|undefined|null>} ...args
+  @return {Array<Element>}
+  @internal
+  ###
+  getList = (args...) ->
+    u.flatMap args, valueToList
+  valueToList = (value) ->
+    if u.isString(value)
+      all(value)
+    else
+      u.wrapList(value)
+#  assertIsElement = (element) ->
+#    unless u.isElement(element)
+#      up.fail('Not an element: %o', element)
+  ###**
+  Removes the given element from the DOM tree.
+  If you don't need IE11 support you may also use the built-in
+  [`Element#remove()`](https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/remove) to the same effect.
+  @function up.element.remove
+  @param {Element} element
+    The element to remove.
+  @experimental
+  ###
+  remove = (element) ->
+    if element.remove
+      element.remove()
+    # IE does not support Element#remove()
+    else if parent = element.parentNode
+      parent.removeChild(element)
+  ###**
+  Hides the given element.
+  The element is hidden by setting an [inline style](https://www.codecademy.com/articles/html-inline-styles)
+  of `{ display: none }`.
+  Also see `up.element.show()`.
+  @function up.element.hide
+  @param {Element} element
+  @experimental
+  ###
+  hide = (element) ->
+    element.style.display = 'none'
+  ###**
+  Shows the given element.
+  Also see `up.element.hide()`.
+  \#\#\# Limitations
+  The element is shown by setting an [inline style](https://www.codecademy.com/articles/html-inline-styles)
+  of `{ display: '' }`.
+  You might have CSS rules causing the element to remain hidden after calling `up.element.show(element)`.
+  Unpoly will not handle such cases in order to keep this function performant. As a workaround, you may
+  manually set the `element.style.display` property. Also see discussion
+  in jQuery issues [#88](https://github.com/jquery/jquery.com/issues/88),
+  [#2057](https://github.com/jquery/jquery/issues/2057) and
+  [this WHATWG mailing list post](http://lists.w3.org/Archives/Public/public-whatwg-archive/2014Apr/0094.html).
+  @function up.element.show
+  @experimental
+  ###
+  show = (element) ->
+    element.style.display = ''
+  ###**
+  Display or hide the given element, depending on its current visibility.
+  @function up.element.toggle
+  @param {Element} element
+  @param {Boolean} [newVisible]
+    Pass `true` to show the element or `false` to hide it.
+    If omitted, the element will be hidden if shown and shown if hidden.
+  @experimental
+  ###
+  toggle = (element, newVisible) ->
+    newVisible ?= !isVisible(element)
+    if newVisible
+      show(element)
+    else
+      hide(element)
+#  trace = (fn) ->
+#    (args...) ->
+#      console.debug("Calling %o with %o", fn, args)
+#      fn(args...)
+  ###**
+  Adds or removes the given class from the given element.
+  If you don't need IE11 support you may also use the built-in
+  [`Element#classList.toggle(className)`](https://developer.mozilla.org/en-US/docs/Web/API/Element/classList) to the same effect.
+  @function up.element.toggleClass
+  @param {Element} element
+    The element for which to add or remove the class.
+  @param {String} className
+    A boolean value to determine whether the class should be added or removed.
+  @param {String} state
+    If omitted, the class will be added if missing and removed if present.
+  @experimental
+  ###
+  toggleClass = (element, klass, newPresent) ->
+    list = element.classList
+    newPresent ?= !list.contains(klass)
+    if newPresent
+      list.add(klass)
+    else
+      list.remove(klass)
+  ###**
+  Sets all key/values from the given object as attributes on the given element.
+  \#\#\# Example
+      up.element.setAttrs(element, { title: 'Tooltip', tabindex: 1 })
+  @function up.element.setAttrs
+  @param {Element} element
+    The element on which to set attributes.
+  @param {object} attributes
+    An object of attributes to set.
+  @experimental
+  ###
+  setAttrs = (element, attributes) ->
+    for key, value of attributes
+      element.setAttribute(key, value)
+  ###**
+  @function up.element.metaContent
+  @internal
+  ###
+  metaContent = (name) ->
+    selector = "meta" + attributeSelector('name', name)
+    first(selector)?.getAttribute('content')
+  ###**
+  @function up.element.insertBefore
+  @internal
+  ###
+  insertBefore = (existingElement, newElement) ->
+    existingElement.insertAdjacentElement('beforebegin', newElement)
+#  insertAfter = (existingElement, newElement) ->
+#    existingElement.insertAdjacentElement('afterend', newElement)
+  ###**
+  Replaces the given old element with the given new element.
+  The old element will be removed from the DOM tree.
+  If you don't need IE11 support you may also use the built-in
+  [`Element#replaceWith()`](https://developer.mozilla.org/en-US/docs/Web/API/ChildNode/replaceWith) to the same effect.
+  @function up.element.replace
+  @param {Element} oldElement
+  @param {Element} newElement
+  @experimental
+  ###
+  replace = (oldElement, newElement) ->
+    oldElement.parentElement.replaceChild(newElement, oldElement)
+  ###**
+  Creates an element matching the given CSS selector.
+  The created element will not yet be attached to the DOM tree.
+  Attach it with [`Element#appendChild()`](https://developer.mozilla.org/en-US/docs/Web/API/Node/appendChild)
+  or use `up.element.affix()` to create an attached element.
+  \#\#\# Examples
+  To create an element with a given tag name:
+      element = up.element.createFromSelector('span')
+      // element is <span></span>
+  To create an element with a given class:
+      element = up.element.createFromSelector('.klass')
+      // element is <div class="klass"></div>
+  To create an element with a given ID:
+      element = up.element.createFromSelector('#foo')
+      // element is <div id="foo"></div>
+  To create an element with a given boolean attribute:
+      element = up.element.createFromSelector('[attr]')
+      // element is <div attr></div>
+  To create an element with a given attribute value:
+      element = up.element.createFromSelector('[attr="value"]')
+      // element is <div attr="value"></div>
+  You may also pass an object of attribute names/values as a second argument:
+      element = up.element.createFromSelector('div', { attr: 'value' })
+      // element is <div attr="value"></div>
+  You may set the element's inner text by passing a `{ text }` option:
+      element = up.element.createFromSelector('div', { text: 'inner text' })
+      // element is <div>inner text</div>
+  You may set inline styles by passing an object of CSS properties as a second argument:
+      element = up.element.createFromSelector('div', { style: { color: 'red' }})
+      // element is <div style="color: red"></div>
+  @function up.element.createFromSelector
+  @param {string} selector
+    The CSS selector from which to create an element.
+  @param {Object} [attrs]
+    An object of attributes to set on the created element.
+  @param {Object} [attrs.text]
+    The [text content](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent) of the created element.
+  @param {Object} [attrs.style]
+    An object of CSS properties that will be set as the inline style
+    of the created element.
+  @return {Element}
+    The created element.
+  @experimental
+  ###
+  createFromSelector = (selector, attrs) ->
+    # Extract attribute values before we do anything else.
+    # Attribute values might contain spaces, and then we would incorrectly
+    # split depths at that space.
+    attrValues = []
+    selectorWithoutAttrValues = selector.replace /\[([\w-]+)(?:=(["'])?([^"'\]]*?)\2)?\]/g, (_match, attrName, _quote, attrValue) ->
+      attrValues.push(attrValue || '')
+      "[#{attrName}]"
+    depths = selectorWithoutAttrValues.split(/[ >]+/)
+    rootElement = undefined
+    depthElement = undefined
+    previousElement = undefined
+    for depthSelector in depths
+      tagName = undefined
+      depthSelector = depthSelector.replace /^[\w-]+/, (match) ->
+        tagName = match
+        ''
+      depthElement = document.createElement(tagName || 'div')
+      rootElement ||= depthElement
+      depthSelector = depthSelector.replace /\#([\w-]+)/, (_match, id) ->
+        depthElement.id = id
+        ''
+      depthSelector = depthSelector.replace /\.([\w-]+)/g, (_match, className) ->
+        depthElement.classList.add(className)
+        ''
+      # If we have stripped out attrValues at the beginning of the function,
+      # they have been replaced with the attribute name only (as "[name]").
+      if attrValues.length
+        depthSelector = depthSelector.replace /\[([\w-]+)\]/g, (_match, attrName) ->
+          depthElement.setAttribute(attrName, attrValues.shift())
+          ''
+      unless depthSelector == ''
+        throw new Error('Cannot parse selector: ' + selector)
+      previousElement?.appendChild(depthElement)
+      previousElement = depthElement
+    if attrs
+      if classValue = u.pluckKey(attrs, 'class')
+        for klass in u.wrapList(classValue)
+          rootElement.classList.add(klass)
+      if styleValue = u.pluckKey(attrs, 'style')
+        setInlineStyle(rootElement, styleValue)
+      if textValue = u.pluckKey(attrs, 'text')
+        rootElement.innerText = textValue
+      setAttrs(rootElement, attrs)
+    rootElement
+  ###**
+  Creates an element matching the given CSS selector and attaches it to the given parent element.
+  To create a detached element from a selector,
+  see `up.element.createFromSelector()`.
+  \#\#\# Example
+      element = up.element.affix(document.body, '.klass')
+      element.parentElement // returns document.body
+      element.className // returns 'klass'
+  @function up.element.affix
+  @params {Element} parent
+    The parent to which to attach the created element.
+  @params {string} selector
+    The CSS selector from which to create an element.
+  @params {Object} attrs
+    An object of attributes to set on the created element.
+  @param {Object} attrs.text
+    The [text content](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent) of the created element.
+  @param {Object} attrs.style
+    An object of CSS properties that will be set as the inline style
+    of the created element.
+  @return {Element}
+    The created element.
+  @experimental
+  ###
+  affix = (parent, selector, attributes) ->
+    element = createFromSelector(selector, attributes)
+    parent.appendChild(element)
+    element
+  ###**
+  Returns a CSS selector that matches the given element as good as possible.
+  To build the selector, the following element properties are used in decreasing
+  order of priority:
+  - The element's `[up-id]` attribute
+  - The element's `[id]` attribute
+  - The element's `[name]` attribute
+  - The element's `[class]` names
+  - The element's [`[aria-label]`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute) attribute
+  - The element's tag name
+  \#\#\# Example
+      element = document.createElement('span')
+      element.className = 'klass'
+      selector = up.element.toSelector(element) // returns '.klass'
+  @function up.element.toSelector
+  @param {string|Element|jQuery}
+    The element for which to create a selector.
+  @experimental
+  ###
+  toSelector = (element) ->
+    return element if u.isString(element)
+    # resolveSelector() might be called with jQuery collections
+    element = getOne(element)
+    selector = undefined
+    if isSingleton(element)
+      selector = elementTagName(element)
+    else if upId = element.getAttribute("up-id")
+      selector = attributeSelector('up-id', upId)
+    else if id = element.getAttribute("id")
+      if id.match(/^[a-z0-9\-_]+$/i)
+        selector = "##{id}"
+      else
+        selector = attributeSelector('id', id)
+    else if name = element.getAttribute("name")
+      selector = elementTagName(element) + attributeSelector('name', name)
+    else if classes = u.presence(nonUpClasses(element))
+      selector = ''
+      for klass in classes
+        selector += ".#{klass}"
+    else if ariaLabel = element.getAttribute("aria-label")
+      selector = attributeSelector('aria-label', ariaLabel)
+    else
+      selector = elementTagName(element)
+    return selector
+  ###**
+  Sets an unique identifier for this element.
+  This identifier is used by `up.element.toSelector()`
+  to create a CSS selector that matches this element precisely.
+  If the element already has other attributes that make a good identifier,
+  like a `[id]`, `[class]` or `[aria-label]`, it is not necessary to
+  set `[up-id]`.
+  \#\#\# Example
+  Take this element:
+      <a href="/">Homepage</a>
+  Unpoly cannot generate a good CSS selector for this element:
+      up.element.toSelector(element)
+      // returns 'a'
+  We can improve this by assigning an `[up-id]`:
+      <a href="/" up-id="link-to-home">Open user 4</a>
+  The attribute value is used to create a better selector:
+      up.element.toSelector(element)
+      // returns '[up-id="link-to-home"]'
+  @selector [up-id]
+  @param {string} up-id
+    A string that uniquely identifies this element.
+  @stable
+  ###
+  ###**
+  @function up.element.isSingleton
+  @internal
+  ###
+  isSingleton = (element) ->
+    matches(element, 'html, body, head, title')
+  elementTagName = (element) ->
+    element.tagName.toLowerCase()
+  ###**
+  @function up.element.attributeSelector
+  @internal
+  ###
+  attributeSelector = (attribute, value) ->
+    value = value.replace(/"/g, '\\"')
+    "[#{attribute}=\"#{value}\"]"
+  nonUpClasses = (element) ->
+    classString = element.className
+    classes = u.splitValues(classString)
+    u.reject classes, (klass) -> klass.match(/^up-/)
+  ###**
+  @function up.element.createDocumentFromHtml
+  @internal
+  ###
+  createDocumentFromHtml = (html) ->
+    # IE9 cannot set innerHTML on a <html> or <head> element.
+    parser = new DOMParser()
+    return parser.parseFromString(html, 'text/html')
+  ###**
+  Creates an element from the given HTML fragment.
+  \#\#\# Example
+    element = up.element.createFromHtml('<div class="foo"><span>text</span></div>')
+    element.className // returns 'foo'
+    element.children[0] // returns <span> element
+    element.children[0].textContent // returns 'text'
+  @function up.element.createFromHtml
+  @experimental
+  ###
+  createFromHtml = (html) ->
+    doc = createDocumentFromHtml(html)
+    return doc.body.children[0]
+  ###**
+  @function up.element.root
+  @internal
+  ###
+  getRoot = ->
+    document.documentElement
+  ###**
+  Forces the browser to paint the given element now.
+  @function up.element.paint
+  @internal
+  ###
+  paint = (element) ->
+    element.offsetHeight
+  ###**
+  @function up.element.concludeCssTransition
+  @internal
+  ###
+  concludeCssTransition = (element) ->
+    undo = setTemporaryStyle(element, transition: 'none')
+    # Browsers need to paint at least one frame without a transition to stop the
+    # animation. In theory we could just wait until the next paint, but in case
+    # someone will set another transition after us, let's force a repaint here.
+    paint(element)
+    return undo
+  ###**
+  Returns whether the given element has a CSS transition set.
+  @function up.element.hasCssTransition
+  @return {boolean}
+  @internal
+  ###
+  hasCssTransition = (elementOrStyleHash) ->
+    if u.isOptions(elementOrStyleHash)
+      styleHash = elementOrStyleHash
+    else
+      styleHash = computedStyle(elementOrStyleHash)
+    prop = styleHash.transitionProperty
+    duration = styleHash.transitionDuration
+    # The default transition for elements is actually "all 0s ease 0s"
+    # instead of "none", although that has the same effect as "none".
+    noTransition = (prop == 'none' || (prop == 'all' && duration == 0))
+    not noTransition
+  ###**
+  @function up.element.fixedToAbsolute
+  @internal
+  ###
+  fixedToAbsolute = (element) ->
+    elementRectAsFixed = element.getBoundingClientRect()
+    # Set the position to 'absolute' so it gains an offsetParent
+    element.style.position = 'absolute'
+    offsetParentRect = element.offsetParent.getBoundingClientRect()
+    setInlineStyle element,
+      left: elementRectAsFixed.left - computedStyleNumber(element, 'margin-left') - offsetParentRect.left
+      top: elementRectAsFixed.top - computedStyleNumber(element, 'margin-top') - offsetParentRect.top
+      right: ''
+      bottom: ''
+  ###**
+  On the given element, set attributes that are still missing.
+  @function up.element.setMissingAttrs
+  @internal
+  ###
+  setMissingAttrs = (element, attrs) ->
+    for key, value of attrs
+      if u.isMissing(element.getAttribute(key))
+        element.setAttribute(key, value)
+  ###**
+  @function up.element.unwrap
+  @internal
+  ###
+  unwrap = (wrapper) ->
+    parent = wrapper.parentNode;
+    wrappedNodes = u.toArray(wrapper.childNodes)
+    u.each wrappedNodes, (wrappedNode) ->
+      parent.insertBefore(wrappedNode, wrapper)
+    parent.removeChild(wrapper)
+#  ###**
+#  Returns the value of the given attribute on the given element, if the value is [present](/up.util.isPresent).
+#
+#  Returns `undefined` if the attribute is not set, or if it is set to an empty string.
+#
+#  @function up.element.presentAttr
+#  @param {Element} element
+#    The element from which to retrieve the attribute value.
+#  @param {String} attribute
+#    The attribute name.
+#  @return {string|undefined}
+#    The attribute value, if present.
+#  @experimental
+#  ###
+#  presentAttr = (element, attribute) ->
+#    value = element.getAttribute(attribute)
+#    u.presence(value)
+  ###**
+  Returns the value of the given attribute on the given element, cast as a boolean value.
+  If the attribute value cannot be cast to `true` or `false`, `undefined` is returned.
+  \#\#\# Casting rules
+  This function deviates from the
+  [HTML Standard for boolean attributes](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#boolean-attributes)
+  in order to allow `undefined` values. When an attribute is missing, Unpoly considers the value to be `undefined`
+  (where the standard would assume `false`).
+  Unpoly also allows `"true"` and `"false"` as attribute values.
+  The table below shows return values for `up.element.booleanAttr(element, 'foo')` given different elements:
+  | Element             | Return value |
+  |---------------------|--------------|
+  | `<div foo>`         | `true`       |
+  | `<div foo="foo">`   | `true`       |
+  | `<div foo="true">`  | `true`       |
+  | `<div foo="">`      | `true`       |
+  | `<div foo="false">` | `false`      |
+  | `<div>`             | `undefined`  |
+  | `<div foo="bar">`   | `undefined`  |
+  @function up.element.booleanAttr
+  @param {Element} element
+    The element from which to retrieve the attribute value.
+  @param {String} attribute
+    The attribute name.
+  @return {boolean|undefined}
+    The cast attribute value.
+  @experimental
+  ###
+  booleanAttr = (element, attribute, pass) ->
+    value = element.getAttribute(attribute)
+    switch value
+      when 'false'
+        false
+      when 'true', '', attribute
+        true
+      else
+        value if pass
+  ###**
+  Returns the given attribute value cast as boolean.
+  If the attribute value cannot be cast, returns the attribute value unchanged.
+  @internal
+  ###
+  booleanOrStringAttr = (element, attribute) ->
+    booleanAttr(element, attribute, true)
+  ###**
+  Returns the value of the given attribute on the given element, cast to a number.
+  If the attribute value cannot be cast to a number, `undefined` is returned.
+  @function up.element.numberAttr
+  @param {Element} element
+    The element from which to retrieve the attribute value.
+  @param {String} attribute
+    The attribute name.
+  @return {number|undefined}
+    The cast attribute value.
+  @experimental
+  ###
+  numberAttr = (element, attribute) ->
+    value = element.getAttribute(attribute)
+    if value?.match(/^[\d\.]+$/)
+      parseFloat(value)
+  ###**
+  Reads the given attribute from the element, parsed as [JSON](https://www.json.org/).
+  Returns `undefined` if the attribute value is [blank](/up.util.isBlank).
+  Throws a `SyntaxError` if the attribute value is an invalid JSON string.
+  @function up.element.jsonAttr
+  @param {Element} element
+    The element from which to retrieve the attribute value.
+  @param {String} attribute
+    The attribute name.
+  @return {Object|undefined}
+    The cast attribute value.
+  @experimental
+  ###
+  jsonAttr = (element, attribute) ->
+    # The document does not respond to #getAttribute()
+    if json = element.getAttribute?(attribute)?.trim()
+      JSON.parse(json)
+  ###**
+  Temporarily sets the inline CSS styles on the given element.
+  Returns a function that restores the original inline styles when called.
+  \#\#\# Example
+      element = document.querySelector('div')
+      unhide = up.element.setTemporaryStyle(element, { 'visibility': 'hidden' })
+      // do things while element is invisible
+      unhide()
+      // element is visible again
+  @function up.element.setTemporaryStyle
+  @param {Element} element
+    The element to style.
+  @param {Object} styles
+    An object of CSS property names and values.
+  @return {Function()}
+    A function that restores the original inline styles when called.
+  @internal
+  ###
+  setTemporaryStyle = (element, newStyles, block) ->
+    oldStyles = inlineStyle(element, Object.keys(newStyles))
+    setInlineStyle(element, newStyles)
+    return -> setInlineStyle(element, oldStyles)
+  ###**
+  Receives [computed CSS styles](https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle)
+  for the given element.
+  \#\#\# Examples
+  When requesting a single CSS property, its value will be returned as a string:
+      value = up.element.style(element, 'font-size')
+      // value is '16px'
+  When requesting multiple CSS properties, the function returns an object of property names and values:
+      value = up.element.style(element, ['font-size', 'margin-top'])
+      // value is { 'font-size': '16px', 'margin-top': '10px' }
+  @function up.element.style
+  @param {Element} element
+  @param {String|Array} propOrProps
+    One or more CSS property names in kebab-case or camelCase.
+  @return {string|object}
+  @experimental
+  ###
+  computedStyle = (element, props) ->
+    style = window.getComputedStyle(element)
+    extractFromStyleObject(style, props)
+  ###**
+  Receives a [computed CSS property value](https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle)
+  for the given element, casted as a number.
+  The value is casted by removing the property's [unit](https://www.w3schools.com/cssref/css_units.asp) (which is usually `px` for computed properties).
+  The result is then parsed as a floating point number.
+  Returns `undefined` if the property value is missing, or if it cannot
+  be parsed as a number.
+  \#\#\# Examples
+  When requesting a single CSS property, its value will be returned as a string:
+      value = up.element.style(element, 'font-size')
+      // value is '16px'
+      value = up.element.styleNumber(element, 'font-size')
+      // value is 16
+  @function up.element.styleNumber
+  @param {Element} element
+  @param {String} prop
+    A single property name in kebab-case or camelCase.
+  @return {number|undefined}
+  @experimental
+  ###
+  computedStyleNumber = (element, prop) ->
+    rawValue = computedStyle(element, prop)
+    if u.isGiven(rawValue)
+      parseFloat(rawValue)
+    else
+      undefined
+  ###**
+  Gets the given inline style(s) from the given element's `[style]` attribute.
+  @function up.element.inlineStyle
+  @param {Element} element
+  @param {String|Array} propOrProps
+    One or more CSS property names in kebab-case or camelCase.
+  @return {string|object}
+  @internal
+  ###
+  inlineStyle = (element, props) ->
+    style = element.style
+    extractFromStyleObject(style, props)
+  extractFromStyleObject = (style, keyOrKeys) ->
+    if u.isString(keyOrKeys)
+      style[keyOrKeys]
+    else # array
+      u.only(style, keyOrKeys...)
+  ###**
+  Sets the given CSS properties as inline styles on the given element.
+  @function up.element.setStyle
+  @param {Element} element
+  @param {Object} props
+    One or more CSS properties with kebab-case keys or camelCase keys.
+  @return {string|object}
+  @experimental
+  ###
+  setInlineStyle = (element, props) ->
+    style = element.style
+    for key, value of props
+      value = normalizeStyleValueForWrite(key, value)
+      style[key] = value
+  normalizeStyleValueForWrite = (key, value) ->
+    if u.isMissing(value)
+      value = ''
+    else if CSS_LENGTH_PROPS.has(key.toLowerCase().replace(/-/, ''))
+      value = cssLength(value)
+    value
+  CSS_LENGTH_PROPS = u.arrayToSet [
+    'top', 'right', 'bottom', 'left',
+    'padding', 'paddingtop', 'paddingright', 'paddingbottom', 'paddingleft',
+    'margin', 'margintop', 'marginright', 'marginbottom', 'marginleft',
+    'borderwidth', 'bordertopwidth', 'borderrightwidth', 'borderbottomwidth', 'borderleftwidth'
+    'width', 'height',
+    'maxwidth', 'maxheight',
+    'minwidth', 'minheight',
+  ]
+  ###**
+  Converts the given value to a CSS length value, adding a `px` unit if required.
+  @function cssLength
+  @internal
+  ###
+  cssLength = (obj) ->
+    if u.isNumber(obj) || (u.isString(obj) && /^\d+$/.test(obj))
+      obj.toString() + "px"
+    else
+      obj
+  ###**
+  Resolves the given CSS selector (which might contain `&` references)
+  to a full CSS selector without ampersands.
+  If passed an `Element` or `jQuery` element, returns a CSS selector string
+  for that element.
+  @function up.element.resolveSelector
+  @param {string|Element|jQuery} selectorOrElement
+  @param {string|Element|jQuery} origin
+    The element that this selector resolution is relative to.
+    That element's selector will be substituted for `&` ([like in Sass](https://sass-lang.com/documentation/file.SASS_REFERENCE.html#parent-selector)).
+  @return {string}
+  @internal
+  ###
+  resolveSelector = (selectorOrElement, origin) ->
+    if u.isString(selectorOrElement)
+      selector = selectorOrElement
+      if u.contains(selector, '&')
+        if u.isPresent(origin) # isPresent returns false for empty jQuery collection
+          originSelector = toSelector(origin)
+          selector = selector.replace(/\&/, originSelector)
+        else
+          up.fail("Found origin reference (%s) in selector %s, but no origin was given", '&', selector)
+    else
+      selector = toSelector(selectorOrElement)
+    selector
+  ###**
+  Returns whether the given element is currently visible.
+  An element is considered visible if it consumes space in the document.
+  Elements with `{ visibility: hidden }` or `{ opacity: 0 }` are considered visible, since they still consume space in the layout.
+  Elements not attached to the DOM are considered hidden.
+  @function up.element.isVisible
+  @param {Element} element
+    The element to check.
+  @experimental
+  ###
+  isVisible = (element) ->
+    # From https://github.com/jquery/jquery/blame/9cb162f6b62b6d4403060a0f0d2065d3ae96bbcc/src/css/hiddenVisibleSelectors.js#L12
+    !!(element.offsetWidth || element.offsetHeight || element.getClientRects().length)
+  <% if ENV['JS_KNIFE'] %>knife: eval(Knife.point)<% end %>
+  # also document :has()!
+  first: first # same as document.querySelector
+  all: all # same as document.querySelectorAll
+  subtree: subtree # practical
+  closest: closest # needed for IE11
+  matches: matches # needed for IE11
+  ancestor: ancestor # not practical. we use it to implement closest
+  get: getOne # practical for code that also works with jQuery
+  list: getList # practical for composing multiple collections, or wrapping.
+  remove: remove # needed for IE11
+  toggle: toggle # practical
+  toggleClass: toggleClass # practical
+  hide: hide # practical
+  show: show # practical
+  metaContent: metaContent # internal
+  replace: replace # needed for IE11
+  insertBefore: insertBefore # internal shortcut, people can use insertAdjacentElement and i don't want to support insertAfter when I don't need it.
+  createFromSelector: createFromSelector # practical for element creation.
+  setAttrs: setAttrs # practical
+  affix: affix # practical for element creation
+  toSelector: toSelector # practical
+  isSingleton: isSingleton # internal
+  attributeSelector: attributeSelector # internal
+  createDocumentFromHtml: createDocumentFromHtml # internal
+  createFromHtml: createFromHtml # practical for element creation
+  root: getRoot # internal
+  paint: paint # internal
+  concludeCssTransition: concludeCssTransition # internal
+  hasCssTransition: hasCssTransition # internal
+  fixedToAbsolute: fixedToAbsolute # internal
+  setMissingAttrs: setMissingAttrs # internal
+  unwrap: unwrap # practical for jQuery migration
+  # presentAttr: presentAttr # experimental
+  booleanAttr: booleanAttr # it's practical, but i cannot find a good name. people might expect it to cast to number, too. but i don't need that for my own code. maybe booleanAttr?
+  numberAttr: numberAttr # practical
+  jsonAttr: jsonAttr # practical
+  booleanOrStringAttr: booleanOrStringAttr
+  setTemporaryStyle: setTemporaryStyle # practical
+  style: computedStyle # practical.
+  styleNumber: computedStyleNumber # practical.
+  inlineStyle: inlineStyle # internal
+  setStyle: setInlineStyle # practical.
+  resolveSelector: resolveSelector # internal
+  none: -> NONE # internal
+  isVisible: isVisible # practical