Merge pull request #1775 from hypothesis/refactor-highlights-styles

Highlight a11y (1/2) - Rename highlights CSS styles and move to separate module

src/annotator/guest.coffee

@@ -22,16 +22,23 @@ animationPromise = (fn) ->
       catch error
         reject(error)
 
+# A selector which matches elements added to the DOM by Hypothesis (eg. for
+# highlights and annotation UI).
+#
+# We can simplify this once all classes are converted from an "annotator-"
+# prefix to a "hypothesis-" prefix.
+IGNORE_SELECTOR = '[class^="annotator-"],[class^="hypothesis-"]'
+
 module.exports = class Guest extends Delegator
-  SHOW_HIGHLIGHTS_CLASS = 'annotator-highlights-always-on'
+  SHOW_HIGHLIGHTS_CLASS = 'hypothesis-highlights-always-on'
 
   # Events to be bound on Delegator#element.
   events:
-    ".annotator-hl click":               "onHighlightClick"
-    ".annotator-hl mouseover":           "onHighlightMouseover"
-    ".annotator-hl mouseout":            "onHighlightMouseout"
-    "click":                             "onElementClick"
-    "touchstart":                        "onElementTouchStart"
+    ".hypothesis-highlight click":      "onHighlightClick"
+    ".hypothesis-highlight mouseover":  "onHighlightMouseover"
+    ".hypothesis-highlight mouseout":   "onHighlightMouseout"
+    "click":                            "onElementClick"
+    "touchstart":                       "onElementTouchStart"
 
   options:
     Document: {}
@@ -153,7 +160,7 @@ module.exports = class Guest extends Delegator
     crossframe.on 'focusAnnotations', (tags=[]) =>
       for anchor in @anchors when anchor.highlights?
         toggle = anchor.annotation.$tag in tags
-        $(anchor.highlights).toggleClass('annotator-hl-focused', toggle)
+        $(anchor.highlights).toggleClass('hypothesis-highlight-focused', toggle)
 
     crossframe.on 'scrollToAnnotation', (tag) =>
       for anchor in @anchors when anchor.highlights?
@@ -181,7 +188,7 @@ module.exports = class Guest extends Delegator
     this.selections.unsubscribe()
     @adder.remove()
 
-    @element.find('.annotator-hl').each ->
+    @element.find('.hypothesis-highlight').each ->
       $(this).contents().insertBefore(this)
       $(this).remove()
 
@@ -228,7 +235,7 @@ module.exports = class Guest extends Delegator
       # Find a target using the anchoring module.
       options = {
         cache: self.anchoringCache
-        ignoreSelector: '[class^="annotator-"]'
+        ignoreSelector: IGNORE_SELECTOR
       }
       return self.anchoring.anchor(root, target.selector, options)
       .then((range) -> {annotation, target, range})
@@ -326,7 +333,7 @@ module.exports = class Guest extends Delegator
     getSelectors = (range) ->
       options = {
         cache: self.anchoringCache
-        ignoreSelector: '[class^="annotator-"]'
+        ignoreSelector: IGNORE_SELECTOR
       }
       # Returns an array of selectors for the passed range.
       return self.anchoring.describe(root, range, options)

src/annotator/highlighter.js

@@ -5,10 +5,10 @@ import $ from 'jquery';
  * element of the specified class and returns the highlight Elements.
  *
  * @param {NormalizedRange} normedRange - Range to be highlighted.
- * @param {string} cssClass - A CSS class to use for the highlight (default: 'annotator-hl')
+ * @param {string} cssClass - A CSS class to use for the highlight
  * @return {HTMLElement[]} - Elements wrapping text in `normedRange` to add a highlight effect
  */
-export function highlightRange(normedRange, cssClass = 'annotator-hl') {
+export function highlightRange(normedRange, cssClass = 'hypothesis-highlight') {
   const white = /^\s*$/;
 
   // A custom element name is used here rather than `<span>` to reduce the

src/annotator/plugin/bucket-bar.coffee

@@ -232,13 +232,13 @@ module.exports = class BucketBar extends Plugin
         bucket = @tabs.index(event.currentTarget)
         for anchor in @annotator.anchors
           toggle = anchor in @buckets[bucket]
-          $(anchor.highlights).toggleClass('annotator-hl-focused', toggle)
+          $(anchor.highlights).toggleClass('hypothesis-highlight-focused', toggle)
 
       # Gets rid of them after
       .on 'mouseout', (event) =>
         bucket = @tabs.index(event.currentTarget)
         for anchor in @buckets[bucket]
-          $(anchor.highlights).removeClass('annotator-hl-focused')
+          $(anchor.highlights).removeClass('hypothesis-highlight-focused')
 
       # Does one of a few things when a tab is clicked depending on type
       .on 'click', (event) =>

src/annotator/test/guest-test.coffee

@@ -218,18 +218,18 @@ describe 'Guest', ->
           {annotation: {$tag: 'tag2'}, highlights: highlight1.toArray()}
         ]
         emitGuestEvent('focusAnnotations', ['tag1'])
-        assert.isTrue(highlight0.hasClass('annotator-hl-focused'))
+        assert.isTrue(highlight0.hasClass('hypothesis-highlight-focused'))
 
       it 'unfocuses any annotations without a matching tag', ->
-        highlight0 = $('<span class="annotator-hl-focused"></span>')
-        highlight1 = $('<span class="annotator-hl-focused"></span>')
+        highlight0 = $('<span class="hypothesis-highlight-focused"></span>')
+        highlight1 = $('<span class="hypothesis-highlight-focused"></span>')
         guest = createGuest()
         guest.anchors = [
           {annotation: {$tag: 'tag1'}, highlights: highlight0.toArray()}
           {annotation: {$tag: 'tag2'}, highlights: highlight1.toArray()}
         ]
         emitGuestEvent('focusAnnotations', 'ctx', ['tag1'])
-        assert.isFalse(highlight1.hasClass('annotator-hl-focused'))
+        assert.isFalse(highlight1.hasClass('hypothesis-highlight-focused'))
 
     describe 'on "scrollToAnnotation" event', ->
 

src/annotator/test/highlighter-test.js

@@ -23,7 +23,7 @@ describe('annotator/highlighter', () => {
       assert.equal(result.length, 1);
       assert.strictEqual(el.childNodes[0], result[0]);
       assert.equal(result[0].nodeName, 'HYPOTHESIS-HIGHLIGHT');
-      assert.isTrue(result[0].classList.contains('annotator-hl'));
+      assert.isTrue(result[0].classList.contains('hypothesis-highlight'));
     });
 
     it('skips text nodes that are only white space', () => {

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

@@ -27,11 +27,11 @@ function annotateQuote(quote) {
  * @param {Element} container
  */
 function highlightedPhrases(container) {
-  return Array.from(container.querySelectorAll('.annotator-hl')).map(function(
-    el
-  ) {
-    return el.textContent;
-  });
+  return Array.from(container.querySelectorAll('.hypothesis-highlight')).map(
+    function(el) {
+      return el.textContent;
+    }
+  );
 }
 
 function simplifyWhitespace(quote) {

src/styles/annotator/annotator.scss

@@ -7,33 +7,10 @@
 
 @use './adder';
 @use './bucket-bar';
+@use './highlights';
 
 var.$base-font-size: 14px;
 
-//HIGHLIGHTS////////////////////////////////
-.annotator-highlights-always-on {
-  .annotator-hl {
-    background-color: var.$highlight-color;
-    cursor: pointer;
-  }
-
-  .annotator-hl .annotator-hl {
-    background-color: var.$highlight-color-second;
-  }
-
-  .annotator-hl .annotator-hl .annotator-hl {
-    background-color: var.$highlight-color-third;
-  }
-}
-
-.annotator-hl.annotator-hl-focused {
-  background-color: var.$highlight-color-focus !important;
-
-  .annotator-hl {
-    background-color: transparent !important;
-  }
-}
-
 // Sidebar
 .annotator-frame {
   // a CSS reset which attempts to prevent the host page's styles

src/styles/annotator/highlights.scss

+@use '../variables' as var;
+
+// `hypothesis-highlights-always-on` is a class that is toggled on the root
+// of the annotated document when highlights are enabled/disabled.
+.hypothesis-highlights-always-on {
+  .hypothesis-highlight {
+    background-color: var.$highlight-color;
+    cursor: pointer;
+  }
+
+  .hypothesis-highlight .hypothesis-highlight {
+    background-color: var.$highlight-color-second;
+  }
+
+  .hypothesis-highlight .hypothesis-highlight .hypothesis-highlight {
+    background-color: var.$highlight-color-third;
+  }
+}
+
+.hypothesis-highlight.hypothesis-highlight-focused {
+  background-color: var.$highlight-color-focus !important;
+
+  .hypothesis-highlight {
+    background-color: transparent !important;
+  }
+}