extension/lib/scrollable-elements.coffee

   1 ###
   2 # Copyright Simon Lydell 2015, 2016.
   3 #
   4 # This file is part of VimFx.
   5 #
   6 # VimFx is free software: you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation, either version 3 of the License, or
   9 # (at your option) any later version.
  10 #
  11 # VimFx is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License
  17 # along with VimFx.  If not, see <http://www.gnu.org/licenses/>.
  18 ###
  19
  20 # This file contains an abstraction for keeping track of scrollable elements,
  21 # automatically keeping the largest scrollable element up-to-date. It stops
  22 # tracking elements that are removed from the DOM.
  23
  24 utils = require('./utils')
  25
  26 class ScrollableElements
  27   constructor: (@window) ->
  28     @elements = new Set()
  29     @largest = null
  30
  31   MINIMUM_SCROLL: 5
  32   MINIMUM_SCROLLABLE_ELEMENT_AREA: 25
  33
  34   # In quirks mode (when the page lacks a doctype), such as on Hackernews,
  35   # `<body>` is considered the root element rather than `<html>`. The 'overflow'
  36   # event is triggered for `<html>` though (_not_ `<body>`!). This method takes
  37   # care of returning the appropriate element, so we don’t need to think about
  38   # it anywhere else.
  39   quirks: (element) ->
  40     document = element.ownerDocument
  41     if element == document.documentElement and
  42        document.compatMode == 'BackCompat' and document.body?
  43       return document.body
  44     else
  45       return element
  46
  47   has: (element) -> @elements.has(@quirks(element))
  48
  49   add: (element) ->
  50     element = @quirks(element)
  51     @elements.add(element)
  52     @largest = element if @isLargest(element)
  53
  54   delete: (element) =>
  55     element = @quirks(element)
  56     @elements.delete(element)
  57     @updateLargest() if @largest == element
  58
  59   reject: (fn) ->
  60     @elements.forEach((element) => @elements.delete(element) if fn(element))
  61     @updateLargest()
  62
  63   isScrollable: (element) ->
  64     element = @quirks(element)
  65     return element.scrollTopMax  >= @MINIMUM_SCROLL or
  66            element.scrollLeftMax >= @MINIMUM_SCROLL
  67
  68   addChecked: (element) ->
  69     return unless computedStyle = @window.getComputedStyle(element)
  70     unless (computedStyle.getPropertyValue('overflow-y') == 'hidden' and
  71             computedStyle.getPropertyValue('overflow-x') == 'hidden') or
  72            # There’s no need to track elements so small that they don’t even fit
  73            # the scrollbars. For example, Gmail has lots of tiny overflowing
  74            # iframes. Filter those out.
  75            utils.area(element) < @MINIMUM_SCROLLABLE_ELEMENT_AREA or
  76            # On some pages, such as Google Groups, 'overflow' events may occur
  77            # for elements that aren’t even scrollable.
  78            not @isScrollable(element)
  79       @add(element)
  80
  81   deleteChecked: (element) ->
  82     # On some pages, such as Gmail, 'underflow' events may occur for elements
  83     # that are actually still scrollable! If so, keep the element.
  84     @delete(element) unless @isScrollable(element)
  85
  86   # It makes the most sense to consider the uppermost scrollable element the
  87   # largest. In other words, if a scrollable element contains another scrollable
  88   # element (or a frame containing one), the parent should be considered largest
  89   # even if the child has greater area.
  90   isLargest: (element) ->
  91     return true  unless @largest
  92     return true  if utils.containsDeep(element, @largest)
  93     return false if utils.containsDeep(@largest, element)
  94     return utils.area(element) > utils.area(@largest)
  95
  96   updateLargest: ->
  97     # Reset `@largest` and find a new largest scrollable element (if there are
  98     # any left).
  99     @largest = null
 100     @elements.forEach((element) => @largest = element if @isLargest(element))
 101
 102   # In theory, this method could return `@largest`. In reality, it is not that
 103   # simple. Elements may overflow when zooming in or out, but the
 104   # `.scrollHeight` of the element is not correctly updated when the 'overflow'
 105   # event occurs, making it possible for unscrollable elements to slip in. So
 106   # this method has to check whether the largest element really is scrollable,
 107   # and update it if needed. In the case where there is no largest element
 108   # (left), it _should_ mean that the page hasn’t got any scrollable elements,
 109   # and the whole page itself isn’t scrollable. However, we cannot be 100% sure
 110   # that nothing is scrollable (for example, if VimFx is updated in the middle
 111   # of a session). So in that case, instead of simply returning `null`, return
 112   # the entire page (the best bet). Not being able to scroll is very annoying.
 113   filterSuitableDefault: ->
 114     if @largest and @isScrollable(@largest)
 115       return @largest
 116     else
 117       @reject((element) => not @isScrollable(element))
 118       return @largest ? @quirks(@window.document.documentElement)
 119
 120 module.exports = ScrollableElements