Refactor selection change detection to use observables

In preparation for some more complex handling of document events in
order to show the adder when the selection changes on mobile, refactor
the processing of events to use observables.

The zen-observable package is used as a lightweight implementation of
the proposed ES2017
[Observable](https://github.com/zenparsing/es-observable) API.

h/static/scripts/annotator/guest.coffee

@@ -9,6 +9,7 @@ $ = Annotator.$
 adder = require('./adder')
 highlighter = require('./highlighter')
 rangeUtil = require('./range-util')
+selections = require('./selections')
 
 animationPromise = (fn) ->
   return new Promise (resolve, reject) ->
@@ -47,7 +48,15 @@ module.exports = class Guest extends Annotator
   constructor: (element, options) ->
     super
 
+    self = this
     this.adderCtrl = new adder.Adder(@adder[0])
+    this.selections = selections(document).subscribe
+      next: (range) ->
+        if range
+          self._onSelection(range)
+        else
+          self._onClearSelection()
+
     this.anchors = []
 
     cfOptions =
@@ -133,6 +142,7 @@ module.exports = class Guest extends Annotator
   destroy: ->
     $('#annotator-dynamic-style').remove()
 
+    this.selections.unsubscribe()
     @adder.remove()
 
     @element.find('.annotator-hl').each ->
@@ -332,33 +342,21 @@ module.exports = class Guest extends Annotator
     tags = (a.$$tag for a in annotations)
     @crossframe?.call('focusAnnotations', tags)
 
-  onSuccessfulSelection: (event, immediate) ->
-    unless event?
-      throw "Called onSuccessfulSelection without an event!"
-    unless event.ranges?
-      throw "Called onSuccessulSelection with an event with missing ranges!"
-
-    @selectedRanges = event.ranges
+  _onSelection: (range) ->
+    @selectedRanges = [range]
 
     Annotator.$('.annotator-toolbar .h-icon-note')
       .attr('title', 'New Annotation')
       .removeClass('h-icon-note')
       .addClass('h-icon-annotate');
 
-    # Do we want immediate annotation?
-    if immediate
-      # Create an annotation
-      @onAdderClick event
-    else
-      # Show the adder button
-      selection = Annotator.Util.getGlobal().getSelection()
-      isBackwards = rangeUtil.isSelectionBackwards(selection)
-      focusRect = rangeUtil.selectionFocusRect(selection)
-      {left, top, arrowDirection} = this.adderCtrl.target(focusRect, isBackwards)
-      this.adderCtrl.showAt(left, top, arrowDirection)
-    true
-
-  onFailedSelection: (event) ->
+    selection = Annotator.Util.getGlobal().getSelection()
+    isBackwards = rangeUtil.isSelectionBackwards(selection)
+    focusRect = rangeUtil.selectionFocusRect(selection)
+    {left, top, arrowDirection} = this.adderCtrl.target(focusRect, isBackwards)
+    this.adderCtrl.showAt(left, top, arrowDirection)
+
+  _onClearSelection: () ->
     this.adderCtrl.hide()
     @selectedRanges = []
 

h/static/scripts/annotator/main.js

@@ -24,9 +24,6 @@ Annotator.Plugin.Toolbar = require('./plugin/toolbar');
 Annotator.Plugin.PDF = require('./plugin/pdf');
 require('../vendor/annotator.document');  // Does not export the plugin :(
 
-// Selection plugins
-Annotator.Plugin.TextSelection = require('./plugin/textselection');
-
 // Cross-frame communication
 Annotator.Plugin.CrossFrame = require('./plugin/cross-frame');
 Annotator.Plugin.CrossFrame.AnnotationSync = require('../annotation-sync');

h/static/scripts/annotator/plugin/textselection.coffee

-Annotator = require('annotator')
-$ = Annotator.$
-
-
-# This plugin implements the UI code for creating text annotations
-module.exports = class TextSelection extends Annotator.Plugin
-
-  pluginInit: ->
-    # Register the event handlers required for creating a selection
-    $(document).bind({
-      "touchend": @checkForEndSelection
-      "mouseup": @checkForEndSelection
-      "ready": @checkForEndSelection
-    })
-
-    null
-
-  destroy: ->
-    $(document).unbind({
-      "touchend": @checkForEndSelection
-      "mouseup": @checkForEndSelection
-      "ready": @checkForEndSelection
-    })
-    super
-
-  # This is called when the mouse is released.
-  # Checks to see if a selection  been made on mouseup and if so,
-  # calls Annotator's onSuccessfulSelection method.
-  #
-  # event - The event triggered this. Usually it's a mouseup Event,
-  #         but that's not necessary.
-  #
-  # Returns nothing.
-  checkForEndSelection: (event = {}) =>
-    callback = ->
-      # Get the currently selected ranges.
-      selection = Annotator.Util.getGlobal().getSelection()
-      ranges = for i in [0...selection.rangeCount]
-        r = selection.getRangeAt(0)
-        if r.collapsed then continue else r
-
-      if ranges.length
-        event.ranges = ranges
-        @annotator.onSuccessfulSelection event
-      else
-        @annotator.onFailedSelection event
-
-    # Run callback after the current event loop tick
-    # so that the mouseup event can update the document selection.
-    setTimeout callback, 0

h/static/scripts/annotator/selections.js

+'use strict';
+
+var Observable = require('zen-observable');
+
+/**
+ * Returns an observable of events emitted by `src`.
+ *
+ * @param {EventTarget} src - The event source.
+ * @param {Array<string>} eventNames - List of events to subscribe to
+ */
+function listen(src, eventNames) {
+  return new Observable(function (observer) {
+    var onNext = function (event) {
+      observer.next(event);
+    };
+
+    eventNames.forEach(function (event) {
+      src.addEventListener(event, onNext);
+    });
+
+    return function () {
+      eventNames.forEach(function (event) {
+        src.removeEventListener(event, onNext);
+      });
+    };
+  });
+}
+
+/**
+ * Returns an observable of `DOMRange` for the selection in the given
+ * @p document.
+ *
+ * @return Observable<DOMRange|null>
+ */
+function selections(document, setTimeout, clearTimeout) {
+  setTimeout = setTimeout || window.setTimeout;
+  clearTimeout = clearTimeout || window.clearTimeout;
+
+  var events = listen(document, ['ready', 'mouseup']);
+  return new Observable(function (obs) {
+    function emitRange() {
+      var selection = document.getSelection();
+      if (!selection.rangeCount || selection.getRangeAt(0).collapsed) {
+        obs.next(null);
+      } else {
+        obs.next(selection.getRangeAt(0));
+      }
+    }
+
+    var timeout;
+    var sub = events.subscribe({
+      next: function () {
+        // Add a delay before checking the state of the selection because
+        // the selection is not updated immediately after a 'mouseup' event
+        // but only on the next tick of the event loop.
+        timeout = setTimeout(emitRange, 0);
+      },
+    });
+
+    return function () {
+      clearTimeout(timeout);
+      sub.unsubscribe();
+    };
+  });
+}
+
+module.exports = selections;

h/static/scripts/annotator/test/selections-test.js

+'use strict';
+
+var unroll = require('../../test/util').unroll;
+
+var selections = require('../selections');
+
+function FakeDocument() {
+  var listeners = {};
+
+  return {
+    getSelection: function () {
+      return this.selection;
+    },
+
+    addEventListener: function (name, listener) {
+      listeners[name] = (listeners[name] || []).concat(listener);
+    },
+
+    removeEventListener: function (name, listener) {
+      listeners[name] = listeners[name].filter(function (lis) {
+        return lis !== listener;
+      });
+    },
+
+    dispatchEvent: function (event) {
+      listeners[event.type].forEach(function (fn) { fn(event); });
+    },
+  };
+}
+
+describe('selections', function () {
+  var fakeDocument;
+  var rangeSub;
+  var onSelectionChanged;
+
+  beforeEach(function () {
+    fakeDocument = new FakeDocument();
+    onSelectionChanged = sinon.stub();
+
+    var fakeSetTimeout = function (fn) { fn(); };
+    var fakeClearTimeout = function () {};
+
+    var ranges = selections(fakeDocument, fakeSetTimeout, fakeClearTimeout);
+    rangeSub = ranges.subscribe({next: onSelectionChanged});
+  });
+
+  afterEach(function () {
+    rangeSub.unsubscribe();
+  });
+
+  unroll('emits the selected range when #event occurs', function (testCase) {
+    var range = {};
+    fakeDocument.selection = {
+      rangeCount: 1,
+      getRangeAt: function (index) {
+        return index === 0 ? range : null;
+      },
+    };
+    fakeDocument.dispatchEvent({type: testCase.event});
+    assert.calledWith(onSelectionChanged, range);
+  }, [{event: 'mouseup'}, {event: 'ready'}]);
+});

package.json

@@ -67,7 +67,8 @@
     "unorm": "^1.3.3",
     "vinyl": "^1.1.1",
     "watchify": "^3.7.0",
-    "whatwg-fetch": "^0.10.1"
+    "whatwg-fetch": "^0.10.1",
+    "zen-observable": "^0.2.1"
   },
   "devDependencies": {
     "chai": "^3.5.0",