Add `TextQuoteAnchor.toPositionAnchor` method

This method used to exist in the `dom-anchor-text-quote` library but got
lost when the class was moved to a wrapper in `types.coffee` after the
upgrade to dom-anchor-text-quote v3.x.

This method is used by PDF anchoring and its absence caused quote
anchoring to throw an exception. The majority of PDF annotations still
continued to anchor because the position anchor still worked.

This commit also adds some basic documentation to the `types` module and
some basic API tests.

src/annotator/anchoring/test/types-test.js

+'use strict';
+
+var types = require('../types');
+
+var TextQuoteAnchor = types.TextQuoteAnchor;
+var TextPositionAnchor = types.TextPositionAnchor;
+
+// These are primarily basic API tests for the anchoring classes. Tests for
+// anchoring a variety of HTML and PDF content exist in `html-test` and
+// `pdf-test`.
+describe('Anchoring classes', function () {
+  var container;
+
+  before(function () {
+    container = document.createElement('div');
+    container.innerHTML = [
+      'Four score and seven years ago our fathers brought forth on this continent,',
+      'a new nation, conceived in Liberty, and dedicated to the proposition that',
+      'all men are created equal.',
+    ].join(' ');
+    document.body.appendChild(container);
+  });
+
+  after(function () {
+    container.remove();
+  });
+
+  describe('TextQuoteAnchor', function () {
+    describe('#toRange', function () {
+      it('returns a valid DOM Range', function () {
+        var quoteAnchor = new TextQuoteAnchor(container, 'Liberty');
+        var range = quoteAnchor.toRange();
+        assert.instanceOf(range, Range);
+        assert.equal(range.toString(), 'Liberty');
+      });
+
+      it('throws if the quote is not found', function () {
+        var quoteAnchor = new TextQuoteAnchor(container, 'five score and nine years ago');
+        assert.throws(function () {
+          quoteAnchor.toRange();
+        });
+      });
+    });
+
+    describe('#toPositionAnchor', function () {
+      it('returns a TextPositionAnchor', function () {
+        var quoteAnchor = new TextQuoteAnchor(container, 'Liberty');
+        var pos = quoteAnchor.toPositionAnchor();
+        assert.instanceOf(pos, TextPositionAnchor);
+      });
+
+      it('throws if the quote is not found', function () {
+        var quoteAnchor = new TextQuoteAnchor(container, 'some are more equal than others');
+        assert.throws(function () {
+          quoteAnchor.toPositionAnchor();
+        });
+      });
+    });
+  });
+});

src/annotator/anchoring/types.coffee

+# This module exports a set of classes for converting between DOM `Range`
+# objects and different types of selector. It is mostly a thin wrapper around a
+# set of anchoring libraries. It serves two main purposes:
+#
+#  1. Providing a consistent interface across different types of anchor.
+#  2. Insulating the rest of the code from API changes in the underyling anchoring
+#     libraries.
+
 domAnchorTextPosition = require('dom-anchor-text-position')
 domAnchorTextQuote = require('dom-anchor-text-quote')
 
@@ -106,6 +114,12 @@ class TextQuoteAnchor
       throw new Error('Quote not found')
     range
 
+  toPositionAnchor: (options = {}) ->
+    anchor = domAnchorTextQuote.toTextPosition(@root, this.toSelector(), options)
+    if anchor == null
+      throw new Error('Quote not found')
+    new TextPositionAnchor(@root, anchor.start, anchor.end)
+
 
 exports.RangeAnchor = RangeAnchor
 exports.FragmentAnchor = require('dom-anchor-fragment')