extension/lib/markable-elements.coffee

   1 # This file contains functions for getting markable elements and related data.
   2
   3 utils = require('./utils')
   4 viewportUtils = require('./viewport')
   5
   6 isElementInstance = (el) -> Element.isInstance(el)
   7
   8 MIN_TEXTNODE_SIZE = 4
   9
  10 find = (window, filter, selector = '*') ->
  11   viewport = viewportUtils.getWindowViewport(window)
  12   wrappers = []
  13   getMarkableElements(window, viewport, wrappers, filter, selector)
  14   return wrappers
  15
  16 # `filter` is a function that is given every element in every frame of the page.
  17 # It should return wrapper objects for markable elements and a falsy value for
  18 # all other elements. All returned wrappers are added to `wrappers`. `wrappers`
  19 # is modified instead of using return values to avoid array concatenation for
  20 # each frame. It might sound expensive to go through _every_ element, but that’s
  21 # actually what other methods like using XPath or CSS selectors would need to do
  22 # anyway behind the scenes. However, it is possible to pass in a CSS selector,
  23 # which allows getting markable elements in several passes with different sets
  24 # of candidates.
  25 getMarkableElements = (
  26   window, viewport, wrappers, filter, selector, parents = []
  27 ) ->
  28   {document} = window
  29
  30   for element in getAllElements(document, selector)
  31     continue unless isElementInstance(element)
  32     # `getRects` is fast and filters out most elements, so run it first of all.
  33     rects = getRects(element, viewport)
  34     continue unless rects.insideViewport.length > 0
  35     continue unless wrapper = filter(
  36       element, (elementArg, tryRight = 1) ->
  37         return getElementShape(
  38           {window, viewport, parents, element: elementArg}, tryRight,
  39           if elementArg == element then rects else null
  40         )
  41     )
  42     wrappers.push(wrapper)
  43
  44   # Note: with fission's out-of-process iframes, accessing frameElement might
  45   # result in a SecurityError. In this case, squelch it and don't drill down.
  46   for frame in window.frames when (try frame.frameElement)
  47     continue unless result = viewportUtils.getFrameViewport(
  48       frame.frameElement, viewport
  49     )
  50     {viewport: frameViewport, offset} = result
  51     getMarkableElements(
  52       frame, frameViewport, wrappers, filter, selector,
  53       parents.concat({window, offset})
  54     )
  55
  56   return
  57
  58 findAllDOMs = (dom) ->
  59   return [dom].concat(
  60     Array.from(dom.querySelectorAll('*'))
  61       .filter((e) -> e.shadowRoot?)
  62       .map((e) -> findAllDOMs(e.shadowRoot))...
  63   )
  64
  65 getAllElements = (document, selector) ->
  66   return [].concat(
  67     findAllDOMs(document).map((d) ->
  68       Array.from(d.querySelectorAll(selector))
  69     )...
  70   )
  71
  72 getRects = (element, viewport) ->
  73   # `element.getClientRects()` returns a list of rectangles, usually just one,
  74   # which is identical to the one returned by `element.getBoundingClientRect()`.
  75   # However, if `element` is inline and line-wrapped, then it returns one
  76   # rectangle for each line, since each line may be of different length, for
  77   # example. That allows us to properly add hints to line-wrapped links.
  78   rects = element.getClientRects?() or []
  79   return {
  80     all: rects,
  81     insideViewport: Array.prototype.filter.call(
  82       rects,
  83       (rect) -> viewportUtils.isInsideViewport(rect, viewport)
  84     )
  85   }
  86
  87 # Returns the “shape” of an element:
  88 #
  89 # - `nonCoveredPoint`: The coordinates of the first point of the element that
  90 #   isn’t covered by another element (except children of the element). It also
  91 #   contains the offset needed to make those coordinates relative to the top
  92 #   frame, as well as the rectangle that the coordinates occur in. It is `null`
  93 #   if the element is outside `viewport` or entirely covered by other elements.
  94 # - `area`: The area of the part of the element that is inside the viewport.
  95 # - `width`: The width of the visible rect at `nonCoveredPoint`.
  96 # - `textOffset`: The distance between the left edge of the element and the left
  97 #   edge of its text vertically near `nonCoveredPoint`. Might be `null`. The
  98 #   calculation might stop early if `isBlock`.
  99 # - `isBlock`: `true` if the element is a block and has several lines of text
 100 #   (which is the case for “cards” with an image to the left and a title as well
 101 #   as some text to the right (where the entire “card” is a link)). This is used
 102 #   to place the the marker at the edge of the block.
 103 getElementShape = (elementData, tryRight, rects = null) ->
 104   {viewport, element} = elementData
 105   result =
 106     {nonCoveredPoint: null, area: 0, width: 0, textOffset: null, isBlock: false}
 107
 108   rects ?= getRects(element, viewport)
 109   totalArea = 0
 110   visibleRects = []
 111   for rect, index in rects.insideViewport
 112     visibleRect = viewportUtils.adjustRectToViewport(rect, viewport)
 113     continue if visibleRect.area == 0
 114     visibleRect.index = index
 115     totalArea += visibleRect.area
 116     visibleRects.push(visibleRect)
 117
 118   if visibleRects.length == 0
 119     if rects.all.length == 1 and totalArea == 0
 120       [rect] = rects.all
 121       if rect.width > 0 or rect.height > 0
 122         # If we get here, it means that everything inside `element` is floated
 123         # and/or absolutely positioned (and that `element` hasn’t been made to
 124         # “contain” the floats). For example, a link in a menu could contain a
 125         # span of text floated to the left and an icon floated to the right.
 126         # Those are still clickable. Therefore we return the shape of the first
 127         # visible child instead. At least in that example, that’s the best bet.
 128         for child in element.children
 129           childData = Object.assign({}, elementData, {element: child})
 130           shape = getElementShape(childData, tryRight)
 131           return shape if shape
 132     return result
 133
 134   result.area = totalArea
 135
 136   # Even if `element` has a visible rect, it might be covered by other elements.
 137   nonCoveredPoint = null
 138   nonCoveredPointRect = null
 139   for visibleRect in visibleRects
 140     nonCoveredPoint = getFirstNonCoveredPoint(
 141       elementData, visibleRect, tryRight
 142     )
 143     if nonCoveredPoint
 144       nonCoveredPointRect = visibleRect
 145       break
 146
 147   return result unless nonCoveredPoint
 148   result.nonCoveredPoint = nonCoveredPoint
 149
 150   result.width = nonCoveredPointRect.width
 151
 152   lefts = []
 153   smallestBottom = Infinity
 154   hasSingleRect = (rects.all.length == 1)
 155
 156   utils.walkTextNodes(element, (node) ->
 157     unless node.data.trim() == ''
 158       for quads in node.getBoxQuads()
 159         bounds = quads.getBounds()
 160         if bounds.width < MIN_TEXTNODE_SIZE or bounds.height < MIN_TEXTNODE_SIZE
 161           continue
 162
 163         if utils.overlaps(bounds, nonCoveredPointRect)
 164           lefts.push(bounds.left)
 165
 166         if hasSingleRect
 167           # The element is likely a block and has several lines of text; ignore
 168           # the `textOffset` (see the description of `textOffset` at the
 169           # beginning of the function).
 170           if bounds.top > smallestBottom
 171             result.isBlock = true
 172             return true
 173
 174           if bounds.bottom < smallestBottom
 175             smallestBottom = bounds.bottom
 176
 177     return false
 178   )
 179
 180   if lefts.length > 0
 181     result.textOffset =
 182       Math.round(Math.min(lefts...) - nonCoveredPointRect.left)
 183
 184   return result
 185
 186 getFirstNonCoveredPoint = (elementData, elementRect, tryRight) ->
 187   # Try the left-middle point, or immediately to the right of a covering element
 188   # at that point (when `tryRight == 1`). If both of those are covered the whole
 189   # element is considered to be covered. The reasoning is:
 190   #
 191   # - A marker should show up as near the left edge of its visible area as
 192   #   possible. Having it appear to the far right (for example) is confusing.
 193   # - We can’t try too many times because of performance.
 194   # - We used to try left-top first, but if the element has `border-radius`, the
 195   #   corners won’t belong to the element, so `document.elementFromPoint()` will
 196   #   return whatever is behind. One _could_ temporarily add a CSS class that
 197   #   removes `border-radius`, but that turned out to be too slow. Trying
 198   #   left-middle instead avoids the problem, and looks quite nice, actually.
 199   # - We used to try left-bottom as well, but that is so rare that it’s not
 200   #   worth it.
 201   #
 202   # It is safer to try points at least one pixel into the element from the
 203   # edges, hence the `+1`.
 204   {left, top, bottom, height} = elementRect
 205   return tryPoint(
 206     elementData, elementRect,
 207     left, +1, Math.round(top + height / 2), 0, tryRight
 208   )
 209
 210 # Tries a point `(x + dx, y + dy)`. Returns `(x, y)` (and the frame offset) if
 211 # the element passes the tests. Otherwise it tries to the right of whatever is
 212 # at `(x, y)`, `tryRight` times . If nothing succeeds, `false` is returned. `dx`
 213 # and `dy` are used to offset the wanted point `(x, y)` while trying.
 214 tryPoint = (elementData, elementRect, x, dx, y, dy, tryRight = 0) ->
 215   {window, viewport, parents, element} = elementData
 216   elementAtPoint = window.document.elementFromPoint(x + dx, y + dy)
 217   offset = {left: 0, top: 0}
 218   found = false
 219   firstLevel = true
 220
 221   # Ensure that `element`, or a child of `element` (anything inside an `<a>` is
 222   # clickable too), really is present at (x,y). Note that this is not 100%
 223   # bullet proof: Combinations of CSS can cause this check to fail, even though
 224   # `element` isn’t covered. We don’t try to temporarily reset such CSS because
 225   # of performance. (See further down for the special value `-1` of `tryRight`.)
 226   if contains(element, elementAtPoint) or tryRight == -1
 227     found = true
 228     # If we’re currently in a frame, there might be something on top of the
 229     # frame that covers `element`. Therefore we ensure that the frame really is
 230     # present at the point for each parent in `parents`.
 231     currentWindow = window
 232     for parent in parents by -1
 233       # If leaving the devtools container take the devtools zoom into account.
 234       if utils.isDevtoolsWindow(currentWindow)
 235         docShell = currentWindow
 236           .getInterface(Ci.nsIWebNavigation)
 237           .QueryInterface(Ci.nsIDocShell)
 238         if docShell
 239           devtoolsZoom = docShell.contentViewer.fullZoom
 240           offset.left *= devtoolsZoom
 241           offset.top  *= devtoolsZoom
 242           x  *= devtoolsZoom
 243           y  *= devtoolsZoom
 244           dx *= devtoolsZoom
 245           dy *= devtoolsZoom
 246
 247       offset.left += parent.offset.left
 248       offset.top  += parent.offset.top
 249       elementAtPoint = parent.window.document.elementFromPoint(
 250         offset.left + x + dx, offset.top + y + dy
 251       )
 252       firstLevel = false
 253       unless contains(currentWindow.frameElement, elementAtPoint)
 254         found = false
 255         break
 256       currentWindow = parent.window
 257
 258   return {x, y, offset} if found
 259
 260   return false if elementAtPoint == null or tryRight <= 0
 261   rect = elementAtPoint.getBoundingClientRect()
 262
 263   # `.getBoundingClientRect()` does not include pseudo-elements that are
 264   # absolutely positioned so that they go outside of the element (which is
 265   # common for `/###\`-looking tabs), but calling `.elementAtPoint()` on the
 266   # pseudo-element _does_ return the element. This means that the covering
 267   # element’s _rect_ won’t cover the element we’re looking for. If so, it’s
 268   # better to try again, forcing the element to be considered located at this
 269   # point. That’s what `-1` for the `tryRight` argument means. This is also used
 270   # in the 'complementary' pass, to include elements considered covered in
 271   # earlier passes (which might have been false positives).
 272   if firstLevel and rect.right <= x + offset.left
 273     return tryPoint(elementData, elementRect, x, dx, y, dy, -1)
 274
 275   # If `elementAtPoint` is a parent to `element`, it most likely means that
 276   # `element` is hidden some way. It can also mean that a pseudo-element of
 277   # `elementAtPoint` covers `element` partly. Therefore, try once at the most
 278   # likely point: The center of the part of the rect to the right of `x`.
 279   if elementRect.right > x and contains(elementAtPoint, element)
 280     return tryPoint(
 281       elementData, elementRect,
 282       (x + elementRect.right) / 2, 0, y, 0, 0
 283     )
 284
 285   newX = rect.right - offset.left + 1
 286   return false if newX > viewport.right or newX > elementRect.right
 287   return tryPoint(elementData, elementRect, newX, 0, y, 0, tryRight - 1)
 288
 289 # In XUL documents there are “anonymous” elements. These are never returned by
 290 # `document.elementFromPoint` but their closest non-anonymous parents are.
 291 # The same is true for Web Components (where their hosts are returned), with
 292 # the further caveat that they might be nested.
 293 # Note: getBindingParent() has been removed from fx72.
 294 normalize = (element) ->
 295   element = e while (e = element.ownerDocument.getBindingParent?(element))?
 296   element = e while (e = element.containingShadowRoot?.host)? # >=fx72
 297   element = element.parentNode while element.prefix?
 298   return element
 299
 300 # Returns whether `element` corresponds to `elementAtPoint`. This is only
 301 # complicated for browser elements in the web page content area.
 302 # `.elementAtPoint()` always returns `<tabbrowser#content>` then. The element
 303 # might be in another tab and thus invisible, but `<tabbrowser#content>` is the
 304 # same and visible in _all_ tabs, so we have to check that the element really
 305 # belongs to the current tab.
 306 contains = (element, elementAtPoint) ->
 307   return false unless elementAtPoint
 308   container = normalize(element)
 309   if elementAtPoint.localName == 'tabbrowser' and elementAtPoint.id == 'content'
 310     {gBrowser} = element.ownerGlobal.top
 311     tabpanel = gBrowser.getNotificationBox(gBrowser.selectedBrowser)
 312     return tabpanel.contains(element)
 313   else
 314     # Note that `a.contains(a)` is supposed to be true, but strangely aren’t for
 315     # `<menulist>`s in the Add-ons Manager, so do a direct comparison as well.
 316     return container == elementAtPoint or container.contains(elementAtPoint)
 317
 318 module.exports = {
 319   find
 320 }