@samuelbradshaw/highlight-helper-js 0.9.0 → 0.10.0

package/README.md

@@ -91,20 +91,20 @@ You can also install it using [npm](https://www.npmjs.com/package/@samuelbradsha
 - **removeHighlights(highlightIds)** – Remove the specified highlights. If `highlightIds` isn’t provided, all highlights will be removed.
 - **getActiveHighlightId()** – Get the ID of the currently-active highlight (if there is one).
 - **getHighlightInfo(highlightIds, paragraphId)** – Get highlight information for an array of highlight IDs. If no highlight IDs are passed, information for all relevant highlights will be returned. If `paragraphId` is provided, only highlights that start in the specified paragraph will be returned. Highlights will be sorted based on their position on the page.
-- **setOption(key, value)** – Change one of the initialized options. Available options are described below.
+- **setOptions(optionsToUpdate)** – Change one or more options. `optionsToUpdate` is an object with one or more of the option keys described below.
 - **getOptions()** – Get the initialized options, including defaults for any options that weren’t explicitly set.
 - **removeHighlighter()** – Removes the current Highlighter instance and all of its highlights from the page. If a new Highlighter instance is created with the same container (as defined by the `containerSelector` option), the previous instance for that container will be removed automatically (there can be multiple Highlighter instances on a page, but each one needs to have a different container).
 
 
 ### <a name="options"></a>Options
 
-Options can be provided when HighlightHelper.js is initialized. They can also be set on demand using `setOption(key, value)` (described above). All of these settings are optional. If not specified, the default value for each option will be used.
+Options can be provided when HighlightHelper.js is initialized. They can be updated after initialization using `setOptions()`.
 
 - **containerSelector** – CSS selector for the section of the page that should be annotatable. Default: `body`.
 - **paragraphSelector** – CSS selector for the paragraphs (or other block elements) on the page that should be annotatable. Each paragraph is expected to have an ID attribute in the HTML, which is used to keep track of where a highlight starts and ends. Default: `h1[id], h2[id], h3[id], h4[id], h5[id], h6[id], p[id], ol[id], ul[id], dl[id], tr[id]`.
 - **colors** – Object that describes available highlight colors. Keys are color names, and values are [CSS color values](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). Default: red, orange, yellow, green, blue (see full default values at the bottom of highlight-helper.js).
 - **styles** – Object that describes available highlight styles. Keys are style names, and there are four properties for each style: `css`, `svg`, `css-active` (optional), and `svg-active` (optional). `css` is a CSS string used for styling highlights in `highlight-api` and `mark-elements` drawing modes, as well as for read-only highlights. `svg` is an SVG string (one or more SVG shapes) to represent the highlight in `svg` drawing mode. `css-active` and `svg-active` are alternative styles to be used when a highlight is active. The CSS custom property `var(--hh-color)` can be used to reference the highlight color value. For SVG highlights, the following variables (if present) will be replaced with relevant values from the highlight’s DOMRect: `{x}`, `{y}`, `{width}`, `{height}`, `{top}`, `{bottom}`, `{left}`, `{right}`. Default: fill, single-underline, double-underline, colored-text, redacted (see full default values at the bottom of highlight-helper.js).
-- **wrappers** – Object that describes available highlight wrappers. Keys are wrapper names, and values are objects with two optional properties: `start` (HTML string to be inserted at the beginning of the highlight), and `end` (HTML string to be inserted at the end of the highlight). Only read-only highlights support wrappers. `var(--hh-color)` can be used to reference the highlight color value. Variables surrounded by curly brackets will be replaced with variables stored in the `wrapperVariables` attribute of the highlight, if applicable. See default values at the bottom of highlight-helper.js.
+- **wrappers** – Object that describes available highlight wrappers. Keys are wrapper names, and values are objects with two optional properties: `start` (HTML string to be inserted at the beginning of the highlight), and `end` (HTML string to be inserted at the end of the highlight). `var(--hh-color)` can be used to reference the highlight color value. Variables surrounded by curly brackets will be replaced with variables stored in the `wrapperVariables` attribute of the highlight, if applicable. See default values at the bottom of highlight-helper.js.
 - **selectionHandles** – Object that describes custom selection handles that a user can drag to resize a selection or highlight. Because most touch devices have built-in selection handles, custom selection handles will only show when using a mouse or trackpad. There are two properties: `left` (HTML string to be used for the left selection handle) and `right` (HTML string to be used for the right selection handle). `var(--hh-color)` can be used to reference the highlight color value. See default values at the bottom of highlight-helper.js.
 - **rememberStyle** – Whether the most recent color, style, and wrapper should be remembered and used by default the next time the user creates a highlight. Boolean. Default: `true`.
 - **snapToWord** – Whether highlights should snap to the nearest word boundary. Spaces and dashes are considered word boundaries (this option may not work correctly in all languages). Boolean. Default: `false`.
@@ -129,11 +129,11 @@ HighlightHelper.js sends [custom events](https://developer.mozilla.org/en-US/doc
 - **hh:highlightcreate** – Sent when a new highlight is created. Includes information about the highlight.
 - **hh:highlightupdate** – Sent when the highlight changes. Includes information about the highlight, and a list of the attributes that changed.
 - **hh:highlightremove** – Sent when a highlight is removed. Includes the ID of the removed highlight.
-- **hh:tap** – Sent when a user taps in the annotatable container (potentially trying to activate a highlight or link). This will only be sent if there isn’t currently an active highlight. Includes the location of the tap, the highlight(s) that were tapped, and the hyperlink(s) that were tapped, if any.
+- **hh:tap** – Sent when a user taps in the annotatable container (potentially trying to tap a highlight, wrapper, or link). This will only be sent if there isn’t currently an active highlight. Includes the location of the tap, and the highlight, wrapper, or hyperlink that was tapped, if any.
 - **hh:selectionupdate** – Sent when the selection color or style changes. Can be used to update custom selection UI, such as the color of selection handles. Includes the key of the color and style.
 - **hh:highlightactivate** – Sent when a highlight is activated. Includes information about the activated highlight.
 - **hh:highlightdeactivate** – Sent when a highlight is deactivated. Includes the ID of the deactivated highlight.
-- **hh:ambiguousaction** – Sent when a user taps on overlapping highlights or an overlapping highlight and link. Includes the location of the tap, the highlight(s) that were tapped, and the hyperlink(s) that were tapped. This event will not be sent if `autoTapToActivate` is set to `false`.
+- **hh:ambiguousaction** – Sent when a user taps on overlapping highlights, wrappers, and/or links. Includes the location of the tap, and the highlight(s), wrapper(s), and hyperlink(s) that were tapped. This event will not be sent if `autoTapToActivate` is set to `false`.
 - **selectionchange** – This is a [standard JavaScript event](https://developer.mozilla.org/en-US/docs/Web/API/Document/selectionchange_event) (not specific to HighlightHelper.js), but it’s worth mentioning here because it can be useful for adding custom selection UI around the selected text (such as a floating annotation menu). When this sends, you can call `window.getSelection()` to get the current [Selection object](https://developer.mozilla.org/en-US/docs/Web/API/Selection).
 
 

package/demo.html

@@ -19,19 +19,19 @@
         --gray-90: hsl(0, 0%, 30%);
         --gray-50: hsl(0, 0%, 70%);
       }}
-      
+
       body {
         background-color: var(--page-bg);
         color: var(--text-color);
         line-height: 1.4;
       }
-      img { width: 120px; float: right; }
+      main { margin-right: 2em; }
       a { color: var(--gray-50); }
       button {
         cursor: pointer;
         user-select: none;
       }
-      
+
       #annotation-menu {
         font-family: "Helvetica", sans-serif;
         font-size: 0.8em;
@@ -54,7 +54,10 @@
           button[name="hh-color"][value="yellow"] { background-color: hsl(50, 98%, 61%); }
           button[name="hh-color"][value="green"] { background-color: hsl(75, 70%, 49%); }
           button[name="hh-color"][value="blue"] { background-color: hsl(182, 86%, 47%); }
-          button[name="hh-style"], button[name="hh-wrapper"] { color: inherit; border: 2px solid var(--gray-50); }
+          button[name="hh-style"], button[name="hh-wrapper"] {
+            position: relative;
+            color: inherit; border: 2px solid var(--gray-50);
+          }
           button[name="hh-remove"] { background-color: var(--gray-50); color: var(--page-bg); }
           .highlight-placeholder {
             background-color: var(--gray-90);
@@ -68,10 +71,25 @@
         font-size: smaller;
         line-height: 0.5em;
         &::before {
-          content: attr(data-marker) / attr(data-accessibility-label);
+          content: attr(data-content) / attr(data-accessibility-label);
+        }
+      }
+      .note-container {
+        display: inline-block;
+        visibility: visible;
+        font-style: normal;
+        height: 1em;
+      }
+      .note {
+        position: absolute;
+        right: 0.5rem;
+        font-size: 1.2rem;
+        margin-top: -0.2rem;
+        &::before {
+          content: attr(data-content) / attr(data-accessibility-label);
         }
       }
-      
+
       #disambiguation-panel {
         color: inherit;
         background-color: inherit;
@@ -106,13 +124,12 @@
   <body>
     <main>
       <h1 id="title1">HighlightHelper.js Demo</h1>
-      <img src="https://upload.wikimedia.org/wikipedia/commons/d/db/CMYK-color_model.png">
       <p id="p1"><b>HighlightHelper.js</b> enables highlighting or underlining text in an HTML page. Highlights are drawn via <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/SVG">SVG shapes</a>, the <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API">Custom Highlight API</a>, or <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/mark">HTML mark elements</a>. Highlights can be drawn across multiple paragraphs or <b>inline <i>style</i></b> elements—they can even overlap!</p>
       <p id="p2">Select text, then choose a color and style. Tap away when you’re done. Tap to activate it again for editing. Secondary elements like images (right) and Japanese ruby/furigana (below) are highlighted around.</p>
       <p id="p3">わたしニーファイは<ruby><rb>善</rb><rt>よ</rt></ruby>い<ruby><rb>両</rb><rt>りょう</rt></ruby><ruby><rb>親</rb><rt>しん</rt></ruby>から<ruby><rb>生</rb><rt>う</rt></ruby>まれたので，<ruby><rb>父</rb><rt>ちち</rt></ruby>が<ruby><rb>学</rb><rt>まな</rt></ruby>んだすべてのことの<ruby><rb>中</rb><rt>なか</rt></ruby>から<ruby><rb>幾</rb><rt>いく</rt></ruby>らかの<ruby><rb>教</rb><rt>おし</rt></ruby>えを<ruby><rb>受</rb><rt>う</rt></ruby>けた。</p>
       <p id="p4" style="direction: rtl;">فِي الْبَدْءِ خَلَقَ اللهُ السَّمَاوَاتِ وَالأَرْضَ. وَكَانَتِ الأَرْضُ خَرِبَةً وَخَالِيَةً، وَعَلَى وَجْهِ الْغَمْرِ ظُلْمَةٌ، وَرُوحُ اللهِ يَرِفُّ عَلَى وَجْهِ الْمِيَاهِ. وَقَالَ اللهُ: «لِيَكُنْ نُورٌ»، فَكَانَ نُورٌ.</p>
     </main>
-    
+
     <hr>
     <aside id="annotation-menu">
       <div class="buttons-area">
@@ -127,9 +144,10 @@
         <button name="hh-style" value="colored-text"> Colored text</button>
         <button name="hh-style" value="redacted"> Redacted</button>
         <button name="hh-remove">Remove</button>
-        <div></div>
-        <!--button name="hh-wrapper" value="none" title="No wrapper"><span class="highlight-placeholder">…</span></button>
-        <button name="hh-wrapper" value="footnote" title="Footnote"><span class="footnote-marker" data-marker="a" data-accessibility-label="Footnote"></span><span class="highlight-placeholder">…</span></button-->
+        <button name="hh-wrapper" value="none" title="No wrapper"><span class="highlight-placeholder">…</span></button>
+        <button name="hh-wrapper" value="footnote" title="Footnote"><span class="footnote-marker" data-content="a" data-accessibility-label="Footnote [a]"></span><span class="highlight-placeholder">…</span></button>
+        <button name="hh-wrapper" value="margin-note" title="Margin note"><span class="note-container"><span class="note" data-content="🙂" data-accessibility-label="Smile emoji"></span></span><span class="highlight-placeholder">…</span></button>
+        <button name="hh-wrapper" value="margin-note" title="Margin note"><span class="note-container"><span class="note" data-content="✅" data-accessibility-label="Checkmark emoji"></span></span><span class="highlight-placeholder">…</span></button>
       </div>
       <p>
         <label><input type="checkbox" id="hh-remember-style" checked> Remember most recent color and style</label><br>
@@ -167,7 +185,7 @@
     <p>
       ← <a href="https://github.com/samuelbradshaw/highlight-helper-js">Back to GitHub</a>
     </p>
-    
+
     <!-- Link to the HighlightHelper.js JavaScript file -->
     <script src="highlight-helper.js"></script>
     <script>
@@ -181,15 +199,15 @@
         },
         {
           highlightId: 'hh-1729991847300',
-          color: 'blue', style: 'fill',
+          color: 'blue', style: 'fill', wrapper: 'margin-note',
+          wrapperVariables: { content: '🙂', accessibilityLabel: 'Smile emoji', },
           startParagraphId: 'p2', startParagraphOffset: 27,
           endParagraphId: 'p2', endParagraphOffset: 42,
         },
         {
           highlightId: 'hh-1729991847468',
-          color: 'red', style: 'colored-text', wrapper: 'footnote',
-          wrapperVariables: { marker: 'a', accessibilityLabel: 'Footnote 1a', },
-          readOnly: true,
+          color: 'red', style: 'single-underline', wrapper: 'footnote',
+          wrapperVariables: { content: 'a', accessibilityLabel: 'Footnote [a]', },
           startParagraphId: 'p2', startParagraphOffset: 119,
           endParagraphId: 'p2', endParagraphOffset: 127,
         },
@@ -218,17 +236,18 @@
           endParagraphId: 'p4', endParagraphOffset: 207,
         },
       ];
-      
+
       // Initialize a Highlighter instance, then load highlights
       const highlighter = new Highlighter({
         containerSelector: 'main',
         paragraphSelector: 'main [id]',
         wrappers: {
-          'footnote': { start: '<span class="footnote-marker" data-marker="{marker}" data-accessibility-label="{accessibilityLabel}"></span>', end: '', },
+          'footnote': { start: '<span class="footnote-marker" data-content="{content}" data-accessibility-label="{accessibilityLabel}"></span>', end: '', },
+          'margin-note': { start: '<span class="note-container"><span class="note" data-content="{content}" data-accessibility-label="{accessibilityLabel}"></span></span>', end: '', },
         },
       });
       highlighter.loadHighlights(highlights);
-      
+
       // Call HighlightHelper.js methods when color, style, wrapper, or remove buttons on this demo page are tapped
       const colorButtons = document.getElementsByName('hh-color');
       for (const colorButton of colorButtons) {
@@ -240,7 +259,13 @@
       }
       const wrapperButtons = document.getElementsByName('hh-wrapper');
       for (const wrapperButton of wrapperButtons) {
-        wrapperButton.addEventListener('click', () => { highlighter.createOrUpdateHighlight({ wrapper: wrapperButton.value }); });
+        const contentSpan = wrapperButton.querySelector('[data-content]');
+        wrapperButton.addEventListener('click', () => {
+          highlighter.createOrUpdateHighlight({
+            wrapper: wrapperButton.value === 'none' ? null : wrapperButton.value,
+            wrapperVariables: { content: contentSpan?.dataset?.content ?? '', accessibilityLabel: contentSpan?.dataset?.accessibilityLabel ?? '', },
+          });
+        });
       }
       const removeButton = document.getElementsByName('hh-remove')[0];
       removeButton.addEventListener('click', () => { highlighter.removeHighlights([highlighter.getActiveHighlightId()]); });
@@ -248,7 +273,7 @@
       function respondToKeyPress(event) {
         if (event.key === 'Backspace') highlighter.removeHighlights([highlighter.getActiveHighlightId()]);
       }
-      
+
       // Call HighlightHelper.js methods when options are changed
       const rememberStyleCheckbox = document.getElementById('hh-remember-style');
       const snapToWordCheckbox = document.getElementById('hh-snap-to-word');
@@ -278,11 +303,11 @@
       selectionHandlesTextSelectionCheckbox.addEventListener('change', (event) => { highlighter.setOption('showCustomSelectionHandlesForTextSelection', event.currentTarget.checked); });
       const selectionHandlesOnTouchCheckbox = document.getElementById('hh-selection-handles-touch');
       selectionHandlesOnTouchCheckbox.addEventListener('change', (event) => { highlighter.setOption('showCustomSelectionHandlesOnTouch', event.currentTarget.checked); });
-      
+
       const container = document.querySelector(highlighter.getOptions().containerSelector);
       const snippetDiv = document.getElementById('snippet');
       const infoDiv = document.getElementById('highlight-info');
-      
+
       // Respond to highlight update and highlight activate event
       container.addEventListener('hh:highlightupdate', updateHighlightInfo);
       container.addEventListener('hh:highlightactivate', updateHighlightInfo);
@@ -300,6 +325,9 @@
         for (const annotatedParagraph of annotatedParagraphs) {
           const snippetParagraph = annotatedParagraph.cloneNode(true);
           snippetParagraph.id = `${snippetParagraph.id}_${event.detail.highlight.highlightId}`;
+          for (const wrapperEl of snippetParagraph.querySelectorAll('[data-highlight-id]')) {
+            wrapperEl.dataset.highlightId = wrapperEl.dataset.highlightId + '_snippet';
+          }
           snippetDiv.append(snippetParagraph);
         }
         const snippetHighlights = [
@@ -317,15 +345,23 @@
         });
         snippetHighlighter.loadHighlights(snippetHighlights);
       }
-      
+
       // Respond to highlight deactivate event
       container.addEventListener('hh:highlightdeactivate', clearHighlightInfo);
       function clearHighlightInfo(event) {
         snippetDiv.innerHTML = '';
         infoDiv.innerHTML = 'N/A';
       }
-      
-      // Respond to ambiguous action events (when a user taps on overlapping highlights, or an overlapping link and highlight)
+
+      // Respond to tap
+      container.addEventListener('hh:tap', respondToTap);
+      function respondToTap(event) {
+        if (event.detail.wrappers.length === 1) {
+          highlighter.activateHighlight(event.detail.wrappers[0].highlightInfo.highlightId);
+        }
+      }
+
+      // Respond to ambiguous action events (when a user taps on overlapping highlights, wrappers, and/or links)
       const disambiguationPanel = document.getElementById('disambiguation-panel');
       const disambiguationButtonsDiv = document.getElementById('disambiguation-buttons');
       const disambiguationCancelButton = document.getElementById('disambiguation-cancel');
@@ -333,7 +369,11 @@
       container.addEventListener('hh:ambiguousaction', handleAmbiguousAction);
       function handleAmbiguousAction(event) {
         disambiguationButtonsDiv.innerHTML = '';
-        for (const highlight of event.detail.highlights) {
+        const highlightIds = new Set();
+        for (const highlight of event.detail.highlights) highlightIds.add(highlight.highlightId);
+        for (const wrapper of event.detail.wrappers) highlightIds.add(wrapper.highlightInfo.highlightId);
+        const highlights = highlighter.getHighlightInfo(highlightIds);
+        for (const highlight of highlights) {
           let buttonStyle = highlighter.getOptions().styles[highlight.style]['css']
           let buttonHtml = `
             <button data-color="${highlight.color}" onclick="disambiguationPanel.close();highlighter.activateHighlight('${highlight.highlightId}');">
@@ -354,7 +394,20 @@
         // TODO: Waiting 10 milliseconds before showing the disambiguation panel is a workaround for an issue in Android Chrome where a click event fires right after the pointerup event that triggered hh:ambiguousaction. If the click event happens to be at the same position as a button in the panel, the button will receive the click, dismissing the panel before the user sees it.
         setTimeout(function() { disambiguationPanel.showModal(); }, 10);
       }
-      
+
+      // Update margin note position when a highlight with a start wrapper is active
+      function updateMarginNotePosition(event) {
+        const activeHighlightId = highlighter.getActiveHighlightId();
+        if (!activeHighlightId) return;
+        const note = container.querySelector(`.hh-wrapper-start[data-highlight-id="${activeHighlightId}"] .note`);
+        if (!note) return;
+        const selection = getSelection();
+        const startRect = selection.type === 'Range' ? selection.getRangeAt(0).getBoundingClientRect() : null;
+        if (startRect) note.style.top = (startRect.top + window.scrollY - 1) + 'px';
+      }
+      container.addEventListener('hh:highlightactivate', updateMarginNotePosition);
+      document.addEventListener('selectionchange', updateMarginNotePosition);
+
       // Log events for debugging
       container.addEventListener('hh:highlightcreate', console.info)
       container.addEventListener('hh:highlightupdate', console.info)
@@ -365,16 +418,6 @@
       container.addEventListener('hh:selectionupdate', console.info)
       container.addEventListener('hh:ambiguousaction', console.info)
       container.addEventListener('hh:tap', console.info)
-      
-//       snippetDiv.addEventListener('hh:highlightcreate', console.warn)
-//       snippetDiv.addEventListener('hh:highlightupdate', console.warn)
-//       snippetDiv.addEventListener('hh:highlightremove', console.warn)
-//       snippetDiv.addEventListener('hh:highlightsload', console.warn)
-//       snippetDiv.addEventListener('hh:highlightactivate', console.warn)
-//       snippetDiv.addEventListener('hh:highlightdeactivate', console.warn)
-//       snippetDiv.addEventListener('hh:selectionupdate', console.warn)
-//       snippetDiv.addEventListener('hh:ambiguousaction', console.warn)
-//       snippetDiv.addEventListener('hh:tap', console.warn)
     </script>
   </body>
 </html>

package/highlight-helper.js

@@ -57,7 +57,7 @@ function Highlighter(options = _defaultOptions) {
 
   this._updateAppearanceStylesheet();
   this._updateSelectionUi('appearance');
-  this.setOption('selectionHandles', this._options.selectionHandles);
+  this.setOptions({ selectionHandles: this._options.selectionHandles });
 }
 
 Highlighter.prototype._initializeHighlighter = function (previousContainerSelector = null) {
@@ -112,11 +112,13 @@ Highlighter.prototype._initializeHighlighter = function (previousContainerSelect
   this._hyperlinkElements = this._annotatableContainer.getElementsByTagName('a');
   this._hyperlinksByPosition = {}
   for (let hyp = 0; hyp < this._hyperlinkElements.length; hyp++) {
+    const hyperlink = this._hyperlinkElements[hyp];
+    hyperlink.dataset.hhPosition = hyp;
     this._hyperlinksByPosition[hyp] = {
       'position': hyp,
-      'text': this._hyperlinkElements[hyp].innerHTML,
-      'url': this._hyperlinkElements[hyp].href,
-      'hyperlinkElement': this._hyperlinkElements[hyp],
+      'text': hyperlink.innerHTML,
+      'url': hyperlink.href,
+      'hyperlinkElement': hyperlink,
     }
   }
 
@@ -315,12 +317,12 @@ Highlighter.prototype._loadEventListeners = function () {
       this._tapResult.isLongPress = isLongPress;
       this._annotatableContainer.dispatchEvent(new CustomEvent('hh:tap', { detail: this._tapResult, }));
       if (options.autoTapToActivate && this._tapResult?.targetFound && !isLongPress) {
-        if (this._tapResult.highlights.length === 1 && this._tapResult.hyperlinks.length === 0) {
+        if (this._tapResult.targetCount > 1) {
+          return this._annotatableContainer.dispatchEvent(new CustomEvent('hh:ambiguousaction', { detail: this._tapResult, }));
+        } else if (this._tapResult.highlights.length === 1) {
           return this.activateHighlight(this._tapResult.highlights[0].highlightId);
-        } else if (this._tapResult.highlights.length === 0 && this._tapResult.hyperlinks.length === 1) {
+        } else if (this._tapResult.hyperlinks.length === 1) {
           return this.activateHyperlink(this._tapResult.hyperlinks[0].position);
-        } else if (this._tapResult.highlights.length + this._tapResult.hyperlinks.length > 1) {
-          return this._annotatableContainer.dispatchEvent(new CustomEvent('hh:ambiguousaction', { detail: this._tapResult, }));
         }
       }
     }
@@ -446,6 +448,34 @@ Highlighter.prototype.drawHighlights = function (highlightIds = Object.keys(this
     // Don't redraw a read-only highlight that's already drawn
     if (wasDrawnAsReadOnly) continue;
 
+    // Insert wrappers before drawing, so any layout shift from wrapper content is reflected in drawing positions
+    if (highlightInfo.wrapper && (options.wrappers[highlightInfo.wrapper]?.start || options.wrappers[highlightInfo.wrapper]?.end)) {
+      const addWrapper = (edge, range, htmlString) => {
+        htmlString = `<span class="hh-wrapper-${edge}" data-highlight-id="${highlightId}" data-color="${highlightInfo.color}" data-style="${highlightInfo.style}" data-hh-ignore="">${htmlString}</span>`
+        for (const key of Object.keys(highlightInfo.wrapperVariables)) {
+          htmlString = htmlString.replaceAll(`{${key}}`, highlightInfo.wrapperVariables[key]);
+        }
+        const template = document.createElement('template');
+        template.innerHTML = htmlString;
+        let htmlElement = template.content.firstChild;
+        range.insertNode(htmlElement);
+      }
+      const startRange = highlightInfo.rangeObj;
+      const endRange = document.createRange(); endRange.setStart(highlightInfo.rangeObj.endContainer, highlightInfo.rangeObj.endOffset);
+      const wrapperInfo = options.wrappers[highlightInfo.wrapper];
+      addWrapper('start', startRange, wrapperInfo.start);
+      addWrapper('end', endRange, wrapperInfo.end);
+      rangeParagraphs.forEach(p => { p.normalize(); });
+      range = this._getCorrectedRangeObj(highlightId);
+      if (!highlightInfo.readOnly && options.drawingMode === 'svg') {
+        const startWrapperEl = this._annotatableContainer.querySelector(`.hh-wrapper-start[data-highlight-id="${highlightId}"]`);
+        const endWrapperEl = this._annotatableContainer.querySelector(`.hh-wrapper-end[data-highlight-id="${highlightId}"]`);
+        range = document.createRange();
+        range.setStartAfter(startWrapperEl);
+        range.setEndBefore(endWrapperEl);
+      }
+    }
+
     // Draw highlights with mark elements
     if (highlightInfo.readOnly || options.drawingMode === 'mark-elements') {
       // Inject HTML <mark> elements
@@ -478,13 +508,13 @@ Highlighter.prototype.drawHighlights = function (highlightIds = Object.keys(this
         styledMark.appendChild(textNode);
         // Absorb adjacent elements without text into the mark element. This prevents unstyled gaps around CSS-rendered pseudoelement content (such as superscript footnote markers).
         let prev = styledMark.previousSibling;
-        while (prev && prev.nodeType === Node.ELEMENT_NODE && prev.textContent === '') {
+        while (prev && prev.nodeType === Node.ELEMENT_NODE && prev.textContent === '' && !prev.hasAttribute('data-hh-ignore')) {
           const toAbsorb = prev; prev = prev.previousSibling;
           styledMark.prepend(toAbsorb);
         }
         if (tn < relevantTextNodes.length - 1) {
           let next = styledMark.nextSibling;
-          while (next && next.nodeType === Node.ELEMENT_NODE && next.textContent === '') {
+          while (next && next.nodeType === Node.ELEMENT_NODE && next.textContent === '' && !next.hasAttribute('data-hh-ignore')) {
             const toAbsorb = next; next = next.nextSibling;
             styledMark.appendChild(toAbsorb);
           }
@@ -528,28 +558,6 @@ Highlighter.prototype.drawHighlights = function (highlightIds = Object.keys(this
       group.innerHTML = svgContent;
       this._svgBackground.appendChild(group);
     }
-
-    // Update wrapper (for read-only highlights only)
-    if (highlightInfo.readOnly) {
-      if (highlightInfo.wrapper && (options.wrappers[highlightInfo.wrapper]?.start || options.wrappers[highlightInfo.wrapper]?.end)) {
-        const addWrapper = (edge, range, htmlString) => {
-          htmlString = `<span class="hh-wrapper-${edge}" data-highlight-id="${highlightId}" data-color="${highlightInfo.color}" data-style="${highlightInfo.style}" data-hh-ignore="">${htmlString}</span>`
-          for (const key of Object.keys(highlightInfo.wrapperVariables)) {
-            htmlString = htmlString.replaceAll(`{${key}}`, highlightInfo.wrapperVariables[key]);
-          }
-          const template = document.createElement('template');
-          template.innerHTML = htmlString;
-          let htmlElement = template.content.firstChild;
-          range.insertNode(htmlElement);
-        }
-        const startRange = highlightInfo.rangeObj;
-        const endRange = document.createRange(); endRange.setStart(highlightInfo.rangeObj.endContainer, highlightInfo.rangeObj.endOffset);
-        const wrapperInfo = options.wrappers[highlightInfo.wrapper];
-        addWrapper('start', startRange, wrapperInfo.start);
-        addWrapper('end', endRange, wrapperInfo.end);
-        rangeParagraphs.forEach(p => { p.normalize(); });
-      }
-    }
   }
 
   // Show container
@@ -683,14 +691,23 @@ Highlighter.prototype.createOrUpdateHighlight = function (attributes = {}, trigg
     changes: appearanceChanges.concat(boundsChanges),
   }
 
+  const wrapperChanged = appearanceChanges.some(k => k.startsWith('wrapper'));
   if (triggeredByUserAction && !this._activeHighlightId) {
     this.activateHighlight(highlightId);
   } else if (this._activeHighlightId && highlightId === this._activeHighlightId && appearanceChanges.length > 0) {
     this._updateSelectionUi('appearance');
-  } else if (highlightId !== this._activeHighlightId) {
+  }
+  if (highlightId !== this._activeHighlightId || wrapperChanged) {
     this.drawHighlights([highlightId]);
   }
 
+  // Redraw highlights after the current highlight if needed
+  if (wrapperChanged && options.drawingMode === 'svg') {
+    const highlights = this.getHighlightInfo();
+    const changedIndex = highlights.findIndex(h => h.highlightId === highlightId);
+    this.drawHighlights(highlights.slice(changedIndex + 1).map(h => h.highlightId));
+  }
+
   if (isNewHighlight) {
     this._annotatableContainer.dispatchEvent(new CustomEvent('hh:highlightcreate', { detail: detail }));
   } else {
@@ -792,33 +809,47 @@ Highlighter.prototype.getHighlightInfo = function (highlightIds = Object.keys(th
   return filteredHighlights;
 }
 
-// Update one of the initialized options
-Highlighter.prototype.setOption = function (key, value) {
+// Update initialized options
+Highlighter.prototype.setOptions = function (optionsToUpdate) {
   const options = this._options;
-  options[key] = value ?? options[key];
-  if (key === 'drawingMode' || key === 'styles') {
-    this._updateAppearanceStylesheet();
-    if (supportsHighlightApi) CSS.highlights.clear();
-    this.drawHighlights();
-  } else if (key === 'colors') {
-    this._updateAppearanceStylesheet();
-  } else if (key === 'containerSelector') {
+  for (const key in optionsToUpdate) {
+    options[key] = optionsToUpdate[key] ?? options[key];
+  }
+  if ('containerSelector' in optionsToUpdate) {
     this.removeHighlighter();
     this._initializeHighlighter();
     this._loadStyles();
     this._loadEventListeners();
     this._updateAppearanceStylesheet();
     this._updateSelectionUi('appearance');
-    this.setOption('selectionHandles', options.selectionHandles);
-  } else if (key === 'paragraphSelector') {
-    this._initializeHighlighter();
-  } else if (key === 'selectionHandles') {
     for (const selectionHandle of this._selectionHandles) {
       selectionHandle.children[1].innerHTML = options.selectionHandles[selectionHandle.dataset.side] ?? '';
     }
+  } else {
+    if ('paragraphSelector' in optionsToUpdate) {
+      this._initializeHighlighter();
+    }
+    if ('drawingMode' in optionsToUpdate || 'styles' in optionsToUpdate || 'colors' in optionsToUpdate) {
+      this._updateAppearanceStylesheet();
+    }
+    if ('drawingMode' in optionsToUpdate || 'styles' in optionsToUpdate) {
+      if (supportsHighlightApi) CSS.highlights.clear();
+      this.drawHighlights();
+    }
+    if ('selectionHandles' in optionsToUpdate) {
+      for (const selectionHandle of this._selectionHandles) {
+        selectionHandle.children[1].innerHTML = options.selectionHandles[selectionHandle.dataset.side] ?? '';
+      }
+    }
   }
 }
 
+/** @deprecated Use setOptions({ key: value }) instead */
+Highlighter.prototype.setOption = function (key, value) {
+  console.warn('setOption() is deprecated. Use setOptions({ key: value }) instead.');
+  this.setOptions({ [key]: value });
+}
+
 // Get all of the initialized options
 Highlighter.prototype.getOptions = function () {
   return this._options;
@@ -839,41 +870,51 @@ Highlighter.prototype.removeHighlighter = function () {
 
 /********************** Private Methods **********************/
 
-// Check if the tap is in the range of an existing highlight or link
+// Check if the tap hits any highlights, wrappers, or links
 Highlighter.prototype._checkForTapTargets = function (pointerEvent) {
   if (!pointerEvent) return;
 
-  // Check for tapped highlights and hyperlinks
-  const tappedHighlights = [];
-  const tappedHyperlinks = [];
+  // Check for tapped highlights
+  const tappedHighlightIds = [];
   if (!pointerEvent.target.closest('[data-hh-ignore]')) {
     for (const highlightId of Object.keys(this._highlightsById)) {
       const highlightInfo = this._highlightsById[highlightId];
       const highlightRange = highlightInfo.rangeObj;
       for (const rangeRect of highlightRange.getClientRects()) {
         if (this._isPointInRect(pointerEvent.clientX, pointerEvent.clientY, rangeRect, 5)) {
-          tappedHighlights.push(highlightInfo);
+          tappedHighlightIds.push(highlightId);
           break;
         }
       }
     }
-    for (const hyperlinkInfo of Object.values(this._hyperlinksByPosition)) {
-      if (pointerEvent.target.closest('a') === hyperlinkInfo.hyperlinkElement) {
-        tappedHyperlinks.push(hyperlinkInfo);
-      }
-    }
   }
+  const tappedHighlights = this.getHighlightInfo(tappedHighlightIds);
 
-  // Sort highlights (hyperlinks should already be sorted)
-  const tappedHighlightIds = [];
-  for (const highlightInfo of tappedHighlights) tappedHighlightIds.push(highlightInfo.highlightId);
-  const sortedTappedHighlights = this.getHighlightInfo(tappedHighlightIds);
+  // Check for tapped wrappers and hyperlinks
+  const tappedWrappers = [];
+  const tappedHyperlinks = [];
+  const targetElements = document.elementsFromPoint(pointerEvent.clientX, pointerEvent.clientY);
+  for (const element of targetElements) {
+    const wrapper = element.closest('.hh-wrapper-start, .hh-wrapper-end');
+    if (wrapper) {
+      tappedWrappers.push({
+        position: wrapper.className.includes('hh-wrapper-start') ? 'start' : 'end',
+        highlightInfo: this._highlightsById[wrapper.dataset.highlightId],
+      });
+    } else if (element.matches('a') && element.dataset.hhPosition) {
+      const hyperlinkInfo = this._hyperlinksByPosition[element.dataset.hhPosition];
+      tappedHyperlinks.push(hyperlinkInfo);
+    }
+  }
 
+  const targetCount = tappedHighlights.length + tappedWrappers.length + tappedHyperlinks.length;
   return {
-    'targetFound': sortedTappedHighlights.length > 0 || tappedHyperlinks.length > 0,
+    'targetCount': targetCount,
+    'targetFound': targetCount > 0,
     'tapRange': this._getCaretFromCoordinates(pointerEvent.clientX, pointerEvent.clientY),
     'pointerEvent': pointerEvent,
-    'highlights': sortedTappedHighlights,
+    'highlights': tappedHighlights,
+    'wrappers': tappedWrappers,
     'hyperlinks': tappedHyperlinks,
   }
 }
@@ -958,6 +999,7 @@ Highlighter.prototype._updateSelectionUi = function (changeType = 'appearance')
   this._svgActiveOverlay.innerHTML = '';
   if (this._activeHighlightId && options.drawingMode === 'svg') {
     let range = this._getCorrectedRangeObj(this._activeHighlightId);
+    range = this._snapRangeToBoundaries(range);
     const rangeParagraphs = this._annotatableContainer.querySelectorAll(`#${highlightInfo.rangeParagraphIds.join(', #')}`);
     const clientRects = this._getMergedClientRects(range, rangeParagraphs);
     this._svgActiveOverlay.dataset.color = color;
@@ -981,7 +1023,7 @@ Highlighter.prototype._updateSelectionUi = function (changeType = 'appearance')
     if (this._activeHighlightId && options.drawingMode === 'svg') {
       this._selectionStylesheet.replaceSync(`
         ${options.containerSelector} g[data-highlight-id="${this._activeHighlightId}"][data-style] { display: none; }
-        ${options.containerSelector} .hh-wrapper-start[data-highlight-id="${this._activeHighlightId}"], .hh-wrapper-end[data-highlight-id="${this._activeHighlightId}"] { display: none; }
+        ${options.containerSelector} .hh-wrapper-start[data-highlight-id="${this._activeHighlightId}"], .hh-wrapper-end[data-highlight-id="${this._activeHighlightId}"] { visibility: hidden; }
         ${options.containerSelector} ::selection { background-color: transparent; }
       `);
     } else if (this._activeHighlightId) {
@@ -989,7 +1031,7 @@ Highlighter.prototype._updateSelectionUi = function (changeType = 'appearance')
       this._selectionStylesheet.replaceSync(`
         ${options.containerSelector} ::highlight(${highlightInfo.escapedHighlightId}) { all: unset; }
         ${options.containerSelector} mark[data-highlight-id="${this._activeHighlightId}"][data-style] { all: unset; }
-        ${options.containerSelector} .hh-wrapper-start[data-highlight-id="${this._activeHighlightId}"], .hh-wrapper-end[data-highlight-id="${this._activeHighlightId}"] { display: none; }
+        ${options.containerSelector} .hh-wrapper-start[data-highlight-id="${this._activeHighlightId}"], .hh-wrapper-end[data-highlight-id="${this._activeHighlightId}"] { visibility: hidden; }
         ${options.containerSelector} ::selection { --hh-color: ${colorString}; ${styleTemplate} }
         ${options.containerSelector} rt::selection, ${options.containerSelector} img::selection { background-color: transparent; }
       `);
@@ -1035,7 +1077,7 @@ Highlighter.prototype._updateSelectionUi = function (changeType = 'appearance')
           }
           if (selectionHandle.dataset.side !== side) {
             selectionHandle.dataset.side = side;
-            this.setOption('selectionHandles', options.selectionHandles);
+            this.setOptions({ selectionHandles: options.selectionHandles });
           }
         }
         this._setCustomSelectionHandleVisibility(true);
@@ -1076,6 +1118,17 @@ Highlighter.prototype._snapRangeToBoundaries = function (range, anchorNode = nul
     }
   }
 
+  // If the range starts at the end of a text node, move it to start at the beginning of the following text node. This prevents the range from jumping across the text node boundary and selecting an extra word.
+  if (startOffset === startNode.textContent.length) {
+    const walker = this._getTextNodeWalker(range.commonAncestorContainer);
+    walker.currentNode = startNode;
+    const nextTextNode = walker.nextNode();
+    if (nextTextNode) {
+      startNode = nextTextNode;
+      startOffset = 0;
+    }
+  }
+
   // Prevent the range from starting or ending in an invalid text node
   if (this._annotatableContainer.contains(range.commonAncestorContainer) && (this._shouldSkipTextNode(startNode) || this._shouldSkipTextNode(endNode))) {
     if (this._shouldSkipTextNode(startNode)) {
@@ -1095,17 +1148,6 @@ Highlighter.prototype._snapRangeToBoundaries = function (range, anchorNode = nul
 
   // Snap to the nearest word
   if (options.snapToWord) {
-    // If the range starts at the end of a text node, move it to start at the beginning of the following text node. This prevents the range from jumping across the text node boundary and selecting an extra word.
-    if (startOffset === startNode.textContent.length) {
-      const walker = this._getTextNodeWalker(range.commonAncestorContainer);
-      walker.currentNode = startNode;
-      const nextTextNode = walker.nextNode();
-      if (nextTextNode) {
-        startNode = nextTextNode;
-        startOffset = 0;
-      }
-    }
-
     // Trim whitespace and dashes at range start and end
     while (_reWhitespaceDash.test(startOffset < startNode.textContent.length && startNode.textContent[startOffset])) startOffset += 1;
     while (endOffset > 0 && _reWhitespaceDash.test(endNode.textContent[endOffset - 1])) endOffset -= 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samuelbradshaw/highlight-helper-js",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "JavaScript tool that enables highlighting or underlining text in an HTML page.",
   "type": "module",
   "main": "highlight-helper.mjs",