@internetarchive/bookreader 5.0.0-111 → 5.0.0-113

package/src/util/TextSelectionManager.js

@@ -1,8 +1,12 @@
 // @ts-check
 import { SelectionObserver } from "../BookReader/utils/SelectionObserver.js";
 import { html, LitElement } from 'lit';
-import { customElement } from 'lit/decorators.js';
+import { customElement, property, query } from 'lit/decorators.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
 import '@internetarchive/icon-share';
+import '@internetarchive/icon-edit-pencil/icon-edit-pencil.js';
+
+const BR_HIGHLIGHTS_LOCAL_STORAGE_KEY = "BRhighlightStorage";
 
 export class TextSelectionManager {
   options = {
@@ -12,8 +16,10 @@ export class TextSelectionManager {
 
   /** @type {BRSelectMenu} */
   selectMenu;
-  /** @type {boolean} */
-  selectionMenuEnabled = false;
+
+  get selectMenuEnabled() {
+    return this.br.plugins.experiments?.isEnabled('copyLinkToHighlight') || this.br.plugins.experiments?.isEnabled('annotateHighlight');
+  }
 
   /**
    * @param {string} layer Selector for the text layer to manage
@@ -46,21 +52,21 @@ export class TextSelectionManager {
         // Set a class on the page to avoid hiding it when zooming/etc
         this.br.refs.$br.find('.BRpagecontainer--hasSelection').removeClass('BRpagecontainer--hasSelection');
         $(window.getSelection().anchorNode).closest('.BRpagecontainer').addClass('BRpagecontainer--hasSelection');
-        this.selectMenu.showMenu();
+        this.showSelectMenu();
 
       }
 
-      if (selectEvent == 'focusChanged') {
+      if (selectEvent == 'changed') {
         // hide the button as user changes their selection
         if (this.mouseIsDown) {
-          this.selectMenu.hideMenu();
-        } else if (window.getSelection().toString()) {
-          this.selectMenu.showMenu();
+          this.hideSelectMenu();
+        } else if (window.getSelection()?.toString()) {
+          this.showSelectMenu();
         }
       }
 
       if (selectEvent == 'cleared') {
-        this.selectMenu.hideMenu();
+        this.hideSelectMenu();
       }
     }).attach();
   }
@@ -68,9 +74,7 @@ export class TextSelectionManager {
   // Need attach + detach methods to toggle w/ Translation plugin
   attach() {
     this.selectionObserver.attach();
-    if (this.selectionMenuEnabled) {
-      this.renderSelectionMenu();
-    }
+
     if (this.br.protected) {
       document.addEventListener('selectionchange', this._limitSelection);
       // Prevent right clicking when selected text
@@ -96,12 +100,8 @@ export class TextSelectionManager {
     }
   }
 
-  renderSelectionMenu() {
-    if (document.querySelector('.br-select-menu__option')) return;
-    document.body.append(this.selectMenu);
-  }
   /**
-   * @param {'started' | 'cleared' | 'focusChanged'} type
+   * @param {'started' | 'cleared' | 'changed'} type
    * @param {HTMLElement} target
    */
   _onSelectionChange = (type, target) => {
@@ -109,7 +109,7 @@ export class TextSelectionManager {
       this.textSelectingMode(target);
     } else if (type === 'cleared') {
       this.defaultMode(target);
-    } else if (type === 'focusChanged') {
+    } else if (type === 'changed') {
       // do nothing, just wait for the mouseup to trigger the styling change
     } else {
       throw new Error(`Unknown type ${type}`);
@@ -162,7 +162,7 @@ export class TextSelectionManager {
     // blocking selection
     $(textLayer).on("mousedown.textSelectPluginHandler", (event) => {
       this.mouseIsDown = true;
-      this.selectMenu.hideMenu();
+      this.hideSelectMenu();
       if ($(event.target).is(this.selectionElement.join(", "))) {
         event.stopPropagation();
       }
@@ -170,7 +170,7 @@ export class TextSelectionManager {
 
     $(textLayer).on("mouseup.textSelectPluginHandler", (event) => {
       this.mouseIsDown = false;
-      this.selectMenu.hideMenu();
+      this.hideSelectMenu();
       textLayer.style.pointerEvents = "none";
       if (skipNextMouseup) {
         skipNextMouseup = false;
@@ -196,7 +196,7 @@ export class TextSelectionManager {
       if (event.which != 1) return;
       this.mouseIsDown = true;
       event.stopPropagation();
-      this.selectMenu.hideMenu();
+      this.hideSelectMenu();
     });
 
     // Prevent page flip on click
@@ -204,10 +204,27 @@ export class TextSelectionManager {
       this.mouseIsDown = false;
       if (event.which != 1) return;
       event.stopPropagation();
-      this.selectMenu.showMenu();
+      this.showSelectMenu();
     });
   }
 
+  showSelectMenu() {
+    if (!this.selectMenuEnabled) return;
+
+    this.selectMenu.copyLinkToHighlightEnabled = this.br.plugins.experiments.isEnabled('copyLinkToHighlight');
+    this.selectMenu.highlightAnnotationEnabled = this.br.plugins.experiments.isEnabled('annotateHighlight');
+
+    if (!this.selectMenu.isConnected) {
+      document.body.append(this.selectMenu);
+    }
+
+    this.selectMenu.show();
+  }
+
+  hideSelectMenu() {
+    this.selectMenu.hide();
+  }
+
   _limitSelection = () => {
     const selection = window.getSelection();
     if (!selection.rangeCount) return;
@@ -246,98 +263,6 @@ export class TextSelectionManager {
   };
 }
 
-/**
- * Builds a TextFragment string from a given text selection.
- * Note does not include the fragment directive `:~:` or # symbol
- * See https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Fragment/Text_fragments
- * @param {Selection} selection currently selected text, eg `document.getSelection()`
- * @param {HTMLElement[]} contextElements elements providing context for the selection
- * @returns {string}
- */
-export function createTextFragmentUrlParam(selection, contextElements) {
-  // TODO: Can import something that handles this more gracefully? see -
-  // https://web.dev/articles/text-fragments#:~:text=In%20its%20simplest%20form%2C%20the%20syntax%20of,percent%2Dencoded%20text%20I%20want%20to%20link%20to.
-
-  // :~:text=[prefix-,]textStart[,textEnd][,-suffix]
-  const highlightedText = selection.toString().replace(/[\s]+/g, " ").trim().split(" ");
-  const direction = selection.direction;
-  const startNode = direction == 'backward' ? selection.focusNode : selection.anchorNode;
-  const endNode = direction == 'backward' ? selection.anchorNode : selection.focusNode;
-  // If text selection begins or ends with a space, we look for the next eligible word to serve as the start or end word
-  const startWord = startNode.textContent.replace(/[\s]+/g, "") ? startNode.textContent : highlightedText[0];
-  const endWord = endNode.textContent.replace(/[\s]+/g, "") ? endNode.textContent : highlightedText[highlightedText.length - 1];
-
-  const textStartRe = RegExp.escape(startWord);
-  const textEndRe = RegExp.escape(endWord);
-
-  // 's' regex modifier ensures the `.` also captures newline characters
-  // Need to use lookahead/lookbehind assertions to allow for overlapping quotes (i.e. multiple "Holmes" on the same page)
-  const startPhraseMatchRe = new RegExp(String.raw`(?<=(${textStartRe}).*?)(${textEndRe})`, "gis");
-  const endPhraseMatchRe = new RegExp(String.raw`(${textStartRe})(?=.*?(${textEndRe}))`, "gis");
-
-  // Duplicated spaces in pageLayer.textContent for some reason
-  const selectionContext = contextElements
-    .map((el) => el.textContent)
-    .join(' ')
-    .replace(/\s+/g, " ");
-  const startPhraseFoundMatches = selectionContext.matchAll(startPhraseMatchRe).toArray();
-  const endPhraseFoundMatches = selectionContext.matchAll(endPhraseMatchRe).toArray();
-  if (startPhraseFoundMatches.length == 1 && endPhraseFoundMatches.length == 1) {
-    // If `startWord...endWord` quote is unambiguous and only occurs once, no prefix-/-suffix is needed for the URL param
-    return `text=${encodeURIComponent(startWord)},${encodeURIComponent(endWord)}`;
-  }
-
-  // Need to add some additional context to `startWord...endWord` by including surrounding words before and after the keywords
-  const preStartRange = document.createRange();
-  preStartRange.setStart(contextElements[0].firstElementChild, 0);
-  preStartRange.setEnd(startNode, 0);
-
-  const postEndRange = document.createRange();
-  postEndRange.setStart(endNode, endNode.textContent.length);
-  const lastWordOfPageEl = getLastMostElement(contextElements[contextElements.length - 1]);
-  postEndRange.setEnd(lastWordOfPageEl, Math.max(0, lastWordOfPageEl.textContent.length - 1));
-
-  // prefixes/suffixes cannot contain paragraph breaks, words that are from more than one line break away should not be included
-  const prefix = getLastWords(3, preStartRange.toString())
-    .replace(/[ ]+/g, " ")
-    .trim()
-    .replace(/^[^\n]*\n/gm, "");
-  const suffix = getFirstWords(3, postEndRange.toString())
-    .replace(/[ ]+/g, " ")
-    .trim()
-    .replace(/\n[^\n]*$/gm, "");
-
-  // Partially selected words need to be captured completely
-  // Guarantee that all whitespace is replaced with just one space and that the first/last word of the highlight is not a space
-  const fullHighlight = selection.toString().replace(/\s+/g, " ").trim().split(/\s/g);
-  // Capture start/end words that may be partially highlighted
-  if (startNode.textContent.trim().length != 0) {
-    if (!startNode.textContent.includes(fullHighlight[0])) {
-      fullHighlight.unshift(startNode.textContent);
-    } else {
-      fullHighlight[0] = startNode.textContent;
-    }
-  }
-  if (endNode.textContent.trim().length != 0) {
-    if (!endNode.textContent.includes(fullHighlight[fullHighlight.length - 1])) {
-      fullHighlight.push(endNode.textContent);
-    }
-    fullHighlight[fullHighlight.length - 1] = endNode.textContent;
-  }
-
-  let quote = [fullHighlight.join(" ")];
-  if (fullHighlight.length > 6) {
-    quote = [fullHighlight.slice(0, 3).join(" "), fullHighlight.slice(-3).join(" ")];
-  }
-
-  const textFragmentArr = [];
-  if (prefix) textFragmentArr.push(`${prefix}-`);
-  textFragmentArr.push(...quote);
-  if (suffix) textFragmentArr.push(`-${suffix}`);
-
-  return `text=${textFragmentArr.map(encodeURIComponent).join(',')}`;
-}
-
 /**
  * @template T
  * Get the i-th element of an iterable
@@ -413,11 +338,133 @@ export function* walkBetweenNodes(start, end) {
   yield* walk(start);
 }
 
+@customElement('br-menu-option')
+export class BRSelectMenuOption extends LitElement {
+  @property({type: String})
+  icon = '';
+
+  @property({type: String})
+  label = '';
+
+  /** @type {string | null} */
+  temporaryText = null;
+
+  @property({type: Number, attribute: 'temporary-text-duration'})
+  temporaryTextDuration = 1200;
+
+  @property({type: String, attribute: 'aria-label'})
+  ariaLabel = '';
+
+  @property({type: Boolean, attribute: 'live-label'})
+  liveLabel = false;
+
+  @property({type: Boolean})
+  temporaryTextVisible = false;
+
+  /** @type {number | null} */
+  temporaryTextTimeoutId = null;
+
+  /** @override */
+  createRenderRoot() {
+    // Keep styles from existing stylesheet by opting out of shadow DOM
+    return this;
+  }
+
+  /** @override */
+  disconnectedCallback() {
+    if (this.temporaryTextTimeoutId != null) {
+      window.clearTimeout(this.temporaryTextTimeoutId);
+      this.temporaryTextTimeoutId = null;
+    }
+    super.disconnectedCallback();
+  }
+
+  /**
+   * @param {string} text
+   */
+  showTemporaryText(text) {
+    if (!text?.trim()) return;
+
+    this.temporaryText = text;
+
+    this.temporaryTextVisible = true;
+    if (this.temporaryTextTimeoutId != null) {
+      window.clearTimeout(this.temporaryTextTimeoutId);
+    }
+    this.temporaryTextTimeoutId = window.setTimeout(() => {
+      this.temporaryTextVisible = false;
+      this.temporaryText = null;
+      this.temporaryTextTimeoutId = null;
+    }, this.temporaryTextDuration);
+  }
+
+  renderIcon() {
+    if (this.icon === 'share') {
+      return html`<ia-icon-share class="br-select-menu__icon" aria-hidden="true"></ia-icon-share>`;
+    }
+    if (this.icon === 'edit-pencil') {
+      return html`<ia-icon-edit-pencil class="br-select-menu__icon" aria-hidden="true"></ia-icon-edit-pencil>`;
+    }
+    return '';
+  }
+
+  render() {
+    const baseLabel = this.label ?? '';
+    const hasTemporaryText = !!this.temporaryText;
+    const temporaryLabel = hasTemporaryText ? this.temporaryText : baseLabel;
+    const showTemporaryLabel = hasTemporaryText && this.temporaryTextVisible;
+    const visibleLabel = showTemporaryLabel ? temporaryLabel : baseLabel;
+    const providedAriaLabel = this.ariaLabel?.trim();
+    const accessibleLabel = providedAriaLabel && providedAriaLabel !== visibleLabel.trim() ? providedAriaLabel : undefined;
+    const sizingLabel = baseLabel.length >= temporaryLabel.length ? baseLabel : temporaryLabel;
+
+    return html`
+      <button
+        type="button"
+        class="br-select-menu__option"
+        role="menuitem"
+        aria-label=${ifDefined(accessibleLabel)}
+      >
+        ${this.renderIcon()}
+        ${hasTemporaryText ? html`
+          <span class="br-select-menu__label-wrap" style="display: inline-flex; position: relative; align-items: center;">
+            <span
+              class="br-select-menu__label"
+              style="visibility: hidden;"
+              aria-hidden="true"
+            >${sizingLabel}</span>
+            <span
+              class="br-select-menu__label"
+              style="position: absolute; inset: 0; display: inline-flex; align-items: center;"
+              aria-live=${this.liveLabel ? 'polite' : 'off'}
+            >${showTemporaryLabel ? temporaryLabel : baseLabel}</span>
+          </span>
+        ` : html`
+          <span class="br-select-menu__label" aria-live=${this.liveLabel ? 'polite' : 'off'}>${baseLabel}</span>
+        `}
+      </button>
+    `;
+  }
+}
+
 @customElement('br-select-menu')
 class BRSelectMenu extends LitElement {
   /** @type {import('../BookReader.js').default} */
   br;
 
+  /** @type {BRSelectMenuOption | null} */
+  @query('#copy-link-option')
+  copyLinkOption;
+
+  @property({type: Boolean})
+  copyLinkToHighlightEnabled = true;
+
+  @property({type: Boolean})
+  highlightAnnotationEnabled = true;
+
+  /**
+   * @param {import('../BookReader.js').default} br
+   */
   constructor(br) {
     super();
     this.br = br;
@@ -429,46 +476,225 @@ class BRSelectMenu extends LitElement {
     return this;
   }
 
+  /** @override */
+  connectedCallback() {
+    super.connectedCallback();
+    this.setAttribute('role', 'menu');
+    this.setAttribute('aria-label', 'Text selection actions');
+    this.setAttribute('aria-orientation', 'vertical');
+  }
+
+  renderCopyLinkToHighlightOption() {
+    return html`
+      <br-menu-option
+        id="copy-link-option"
+        @click=${this.handleCopyLinkToHighlight}
+        icon="share"
+        label="Copy Link to Highlight"
+        live-label
+      ></br-menu-option>
+    `;
+  }
+
+  renderRemoveOption() {
+    return html`
+      <br-menu-option
+        @click=${this.handleDeleteHighlight}
+        icon="share"
+        label="Delete Highlight and Annotation"
+      ></br-menu-option>
+    `;
+  }
+
+  renderAddAnnotationOption() {
+    return html`
+      <br-menu-option
+        @click=${this.handleAddAnnotation}
+        icon="edit-pencil"
+        label="Annotate"
+      ></br-menu-option>
+    `;
+  }
+
+  renderHighlightOption() {
+    return html`
+      <br-menu-option
+        @click=${this.handleHighlightSave}
+        icon="edit-pencil"
+        label="Highlight Selection"
+      ></br-menu-option>
+    `;
+  }
+  renderLocalStorageOptions() {
+    return html`
+      <br-menu-option
+        @click=${this.renderSavedHighlights}
+        icon="share"
+        label="Load Highlights"
+      ></br-menu-option>
+      <br-menu-option
+        @click=${() => {window.localStorage.removeItem(BR_HIGHLIGHTS_LOCAL_STORAGE_KEY);}}
+        icon="share"
+        label="Remove Stored Highlights"
+      ></br-menu-option>`;
+  }
+
   render() {
+    // TODO change the second button to use a different icon
     return html`
-      <button @click=${this.handleCopyLinkToHighlight} class="br-select-menu__option">
-        <ia-icon-share class="br-select-menu__icon" aria-hidden="true"></ia-icon-share>
-        <span class="br-select-menu__label">Copy Link to Highlight</span>
-      </button>
+      ${this.copyLinkToHighlightEnabled ? this.renderCopyLinkToHighlightOption() : ''}
+      ${this.highlightAnnotationEnabled && !this.nodesForRemoval ? this.renderHighlightOption() : ''}
+      ${this.highlightAnnotationEnabled ? this.renderLocalStorageOptions() : ''}
+      ${this.nodesForRemoval ? this.renderRemoveOption() : ''}
     `;
   }
 
   /**
    * @param {MouseEvent} e
    */
-  handleCopyLinkToHighlight(e) {
+  async handleCopyLinkToHighlight(e) {
     e.preventDefault();
-
     const currentParams = this.br.readQueryString();
     const currentSelection = window.getSelection();
-    /** @type {HTMLElement} */
-    const textLayer = currentSelection.anchorNode.parentElement.closest('.BRtextLayer');
-    const textFragmentUrlParam = createTextFragmentUrlParam(currentSelection, Array.from(document.querySelectorAll('.BRpage-visible')));
+    const textFragment = BookReaderTextFragment.fromSelection(currentSelection, this.br.$('.BRpage-visible').toArray());
 
     // Note: Have to do a param construction to avoid url-encoding of commas in the text fragment param
     let linkToHighlightParams = currentParams;
     if (currentParams.includes('text=')) {
-      linkToHighlightParams = currentParams.replace(/(text=)[\w\W\d%]+/, textFragmentUrlParam);
+      linkToHighlightParams = currentParams.replace(/(text=)[\w\W\d%]+/, `text=${textFragment.toUrlString()}`);
     } else {
       const sep = linkToHighlightParams ? '&' : '?';
-      linkToHighlightParams += `${sep}${textFragmentUrlParam}`;
+      linkToHighlightParams += `${sep}text=${textFragment.toUrlString()}`;
     }
-
     const currentUrl = window.location;
-    // TODO - updateResumeValue + getCookiePath in plugin.resume.js overrides the adjustedUrlPageNumPath, check how to workaround this
-    // TODO - won't work with hash mode
-    const adjustedUrlPageNumPath = currentUrl.pathname.toString().replace(/(?<=\/page\/)\d+(?=\/)/, textLayer.parentElement.getAttribute('data-page-num'));
+    const pageNum = textFragment.pageNumber || `n${textFragment.pageIndex}`;
+    const adjustedUrlPageNumPath = currentUrl.pathname.replace(/((?:^|[#/])page)\/[^/]+/, `$1/${pageNum}`);
+    const hash = currentUrl.hash ? currentUrl.hash.replace(/((?:^|[#/])page)\/[^/]+/, `$1/${pageNum}`) : '';
+    const linkToHighlight = `${currentUrl.origin}${adjustedUrlPageNumPath}${linkToHighlightParams}${hash}`;
+
+    await navigator.clipboard.writeText(linkToHighlight);
+    this.copyLinkOption?.showTemporaryText('Copied!');
+  }
+
+  /**
+   * Returns the closest BRtextLayer element on the page that contains the target node
+   * @param {Node} node
+   * @returns {HTMLElement | null}
+   */
+  getNodeTextLayer(node) {
+    if (!node) return;
+    const element = 'closest' in node ? node : node.parentElement;
+    return element?.closest('.BRtextLayer') ?? null;
+  }
+
+  /**
+   * Retrieves the current selected text on the page and serializes the quote contents + context
+   * The selection is also changed in the DOM to highlight the words
+   */
+  handleHighlightSave() {
+    const currentSelection = window.getSelection();
+    const start = currentSelection.direction === 'backward' ? currentSelection.focusNode.parentElement : currentSelection.anchorNode.parentElement;
+    const textLayer = this.getNodeTextLayer(start);
+    const highlight = BookReaderTextFragment.fromSelection(currentSelection, [textLayer.parentElement]);
+    highlight.uuid = `id-${crypto.randomUUID().split("-")[4]}`;
+    const highlights = this.loadHighlightsFromLocalStorage();
+    highlights.push(highlight);
+    this.saveToLocalStorage(highlights);
+    this.renderSavedHighlights();
+  }
+
+  handleAddAnnotation(e) {
+    // TODO
+  }
+
+  handleDeleteHighlight() {
+    if (this.nodesForRemoval) {
+      const uuid = retrieveUUID(this.nodesForRemoval[0]);
+      for (const ele of this.nodesForRemoval) {
+        const tempText = ele.textContent;
+        const parent = ele.parentElement;
+        if (parent.classList.contains('BRwordElement') || parent.classList.contains('BRspace')) {
+          ele.remove();
+          parent.textContent = tempText;
+        } else {
+          console.log("This element did not match removal criteria:", parent, ele);
+        }
+      }
+      this.deleteHighlight(uuid);
+      this.clearNodesForRemoval();
+    } else {
+      console.log("there is nothing to remove");
+    }
+  }
+
+  /**
+   * @param {string} uuid
+   */
+  deleteHighlight(uuid) {
+    const highlights = this.loadHighlightsFromLocalStorage();
+    for (let idx = 0; idx < highlights.length; idx++) {
+      if (highlights[idx].uuid === uuid) {
+        highlights.splice(idx, 1);
+        this.saveToLocalStorage(highlights);
+        return;
+      }
+    }
+  }
+
+  /**
+   * Saves all the highlights in an array to localStorage
+   * @param {BookReaderSavedHighlight[]} highlights
+   */
+  saveToLocalStorage(highlights) {
+    window.localStorage.setItem(BR_HIGHLIGHTS_LOCAL_STORAGE_KEY, JSON.stringify(highlights.map(hl => hl.toJSON())));
+  }
+
+  /**
+   * @returns {BookReaderSavedHighlight[]}
+   */
+  loadHighlightsFromLocalStorage() {
+    return JSON.parse(window.localStorage.getItem(BR_HIGHLIGHTS_LOCAL_STORAGE_KEY) || "[]")
+      .map(item => BookReaderTextFragment.fromJSON(item));
+  }
+
+  renderSavedHighlights() {
+    for (const hl of this.loadHighlightsFromLocalStorage()) {
+      const textLayer = /** @type {HTMLElement} */ (this.br.$(`.pagediv${hl.pageIndex} .BRtextLayer`)[0]);
+      if (!textLayer) continue;
+      renderHighlight(textLayer, hl);
+      // Attach click behaviour here? Only need one handler per text layer
+      $(textLayer)
+        .off('mouseup.BRHighlightClick')
+        .on('mouseup.BRHighlightClick', (e) => {
+          if (!e.target.classList.contains("BRhighlight")) return;
+          e.stopPropagation();
+          this.handleHighlightClick(e.target);
+        });
+    }
+  }
+
+  /**
+   * @param {HTMLElement} target
+   */
+  handleHighlightClick(target) {
+    const textLayer = this.getNodeTextLayer(target);
+    const identifier = retrieveUUID(target);
+    const selectedQuoteNodes = textLayer.querySelectorAll(`.${identifier}`);
+
+    const firstNode = selectedQuoteNodes[0];
+    const lastNode = selectedQuoteNodes[selectedQuoteNodes.length - 1];
 
-    const linkToHighlight = `${currentUrl.origin}${adjustedUrlPageNumPath}${linkToHighlightParams}${currentUrl?.hash || ''}`;
-    navigator.clipboard.writeText(linkToHighlight);
+    const highlightRange = document.createRange();
+    highlightRange.setStart(firstNode, 0);
+    highlightRange.setEnd(lastNode, 1);
+
+    const currentSelection = window.getSelection();
+    currentSelection.removeAllRanges();
+    currentSelection.addRange(highlightRange);
+    this.show();
   }
 
-  showMenu() {
+  show() {
     if (this.br.plugins.translate?.userToggleTranslate) return;
     const currentSelection = window.getSelection();
     const start = currentSelection.anchorNode.parentElement;
@@ -488,12 +714,22 @@ class BRSelectMenu extends LitElement {
     this.style.zIndex = '1';
     this.style.position = 'absolute';
     this.style.display = 'block';
+    this.clearNodesForRemoval();
   }
 
-  hideMenu = () => {
+  hide = () => {
     this.style.display = 'none';
+    this.clearNodesForRemoval();
     return;
   }
+
+  /**
+   * Remove temporary storage for the currently selected highlight and updates selection menu options
+   */
+  clearNodesForRemoval = () => {
+    this.nodesForRemoval = null;
+    this.requestUpdate();
+  }
 }
 
 /**
@@ -521,12 +757,473 @@ export function getLastWords(numWords, text) {
 }
 
 /**
- * @param {HTMLElement | Element} parent
+ * @param {Node} parent
  * @returns {Node}
  */
-export function getLastMostElement(parent) {
-  while (parent.lastElementChild) {
-    parent = parent.lastElementChild;
+export function getFirstMostNode(parent) {
+  while (parent.firstChild) {
+    parent = parent.firstChild;
   }
   return parent;
 }
+
+/**
+ * @param {Node} parent
+ * @returns {Node}
+ */
+export function getLastMostNode(parent) {
+  while (parent.lastChild) {
+    parent = parent.lastChild;
+  }
+  return parent;
+}
+
+/**
+ * Strips the whitespace to normalize text
+ * @param {String} string
+ * @returns
+ */
+function replaceWhitespace(string) {
+  return string.replace(/\s+/g, " ");
+}
+
+/**
+ * Checks if quote matches the text content and existing range, then identifies the start and end nodes that contain the quote string.
+ * @param {String} quote - The text to find
+ * @param {Range} range - the range to search in
+ * @param {Node[]} textNodes - visible text nodes within the range
+ * @returns {Range | undefined} Range that encompasses the quote, or undefined if no match is found
+ *
+ * Lightly adapted from
+ * https://github.com/GoogleChromeLabs/text-fragments-polyfill/blob/abc6ed408b3f20e91d9cbda9977748459f5e3877/src/text-fragment-utils.js#L765
+ */
+export function findRangeForQuote(quote, range, textNodes) {
+  const startOffset = textNodes[0] === range.startContainer ?
+    range.startOffset :
+    0;
+  const normalizedWholePageString = replaceWhitespace(range.toString());
+  const normalizedQuote = replaceWhitespace(quote);
+  let searchStart = 0;
+  let start;
+  let end;
+  while (searchStart < normalizedWholePageString.length) {
+    const matchedIndex = normalizedWholePageString.indexOf(normalizedQuote, searchStart);
+    if (matchedIndex === -1) return undefined;
+    const normalizedStartOffset = replaceWhitespace(textNodes[0].textContent.slice(0, startOffset)).length;
+    start = getBoundaryPointAtIndex(
+      normalizedStartOffset + matchedIndex,
+      textNodes, false);
+    end = getBoundaryPointAtIndex(
+      normalizedStartOffset + matchedIndex + normalizedQuote.length,
+      textNodes, true);
+    if (start != null && end != null) {
+      const foundRange = new Range();
+      foundRange.setStart(start.node, 0);
+      foundRange.setEnd(end.node, 1);
+      return foundRange;
+    }
+    searchStart = matchedIndex + 1;
+  }
+  return undefined;
+}
+
+
+/**
+ * Uses the index that matches the quote string and normalizes the string contents to find the correct node
+ * @param {Number} index
+ * @param {Node[]} nodes
+ * @param {boolean} isEnd
+ */
+export function getBoundaryPointAtIndex(index, nodes, isEnd) {
+  let counted = 0;
+  let normalizedData;
+  for (let i = 0; i < nodes.length; i++) {
+    const node = nodes[i];
+    if (node.className === 'BRlineElement') {
+      // Treat the lineElement as a space for now, will check if the previous node was hyphenated or another lineElement later
+      normalizedData = ' ';
+    } else {
+      if (!normalizedData) normalizedData = replaceWhitespace(node.textContent);
+    }
+    let nodeEnd = counted + normalizedData.length;
+    if (isEnd) nodeEnd += 1;
+    if (nodeEnd > index) {
+      const normalizedOffset = index - counted;
+      let denormalizedOffset = Math.min(index - counted, node.textContent.length);
+
+      const targetSubstring = isEnd ?
+        normalizedData.substring(0, normalizedOffset) :
+        normalizedData.substring(normalizedOffset);
+
+      let candidateSubstring = isEnd ?
+        replaceWhitespace(node.textContent.substring(0, normalizedOffset)) :
+        replaceWhitespace(node.textContent.substring(normalizedOffset));
+
+      const direction = (isEnd ? -1 : 1) * (targetSubstring.length > candidateSubstring.length ? -1 : 1);
+      while (denormalizedOffset >= 0 &&
+               denormalizedOffset <= node.textContent.length) {
+        if (candidateSubstring.length === targetSubstring.length) {
+          return {node : node, offset: denormalizedOffset};
+        }
+        denormalizedOffset += direction;
+
+        candidateSubstring = isEnd ?
+          node.textContent.substring(0, denormalizedOffset) :
+          node.textContent.substring(denormalizedOffset);
+      }
+    }
+    counted += normalizedData.length;
+
+    if (i + 1 < nodes.length) {
+      const nextNormalizedData = replaceWhitespace(nodes[i + 1].textContent);
+      // Hyphenated words prove to be an issue since spaces are being inserted between BRlineElements
+      // 1st case explicitly check the node class to prevent double counted spaces
+      // 2nd case can happen from node traversal when loading from localStorage
+      if (nodes[i - 1]?.classList.contains("BRwordElement--hyphen") && node.className === 'BRlineElement') {
+        counted -= 1;
+      } else if (nodes[i - 1]?.className === 'BRlineElement' && node.className === 'BRlineElement') {
+        counted -= 1;
+      }
+      normalizedData = nextNormalizedData;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Takes a text quote object and a container element, and wraps the quote
+ * within the container element in a span to apply highlight-like styling
+ *
+ * Iterate through the range and determine the "start" and "end" nodes
+ * Example of how this is done via polyfill
+ * https://github.com/GoogleChromeLabs/text-fragments-polyfill/blob/main/src/text-fragment-utils.js#L743
+ *
+ * @param {HTMLElement} textLayer
+ * @param {BookReaderTextFragment} quote
+ * @param {string | null} cssClassName optional css class to add to the highlight span element
+ */
+export function renderHighlight(textLayer, quote, cssClassName = null) {
+  // Create a range that encompasses the entire text content
+  const firstPageNode = getFirstMostNode(textLayer);
+  const lastPageNode = getLastMostNode(textLayer);
+  const wholePageRange = new Range();
+  wholePageRange.setStart(firstPageNode, 0);
+  wholePageRange.setEnd(lastPageNode, lastPageNode.textContent.length);
+
+  // Convert the whole page range into a normalized string, get the index of where the stored string matches the quote
+  const convertedString = replaceWhitespace(wholePageRange.toString());
+  const convertedQuote = replaceWhitespace(quote.quote);
+  const foundStringIndex = convertedString.indexOf(convertedQuote);
+  if (foundStringIndex == -1) {
+    console.warn("Could not find quote in page:", quote.quote);
+    return;
+  }
+  const fullContext = [quote.prefix, quote.quote, quote.suffix].join(" ");
+  const convertedFullContext = replaceWhitespace(fullContext);
+
+  // Retrieve the text nodes and relevant whitespace elements
+  // Need to keep the BRlineElement nodes in between to keep the index count consistent, remove first BRlineElement since text starts from the first real text node
+  const pageWordNodes = Array.from(textLayer.querySelectorAll('.BRwordElement, .BRspace, br, .BRlineElement'));
+  pageWordNodes.splice(0, 1);
+  const broadRange = findRangeForQuote(convertedFullContext, wholePageRange, pageWordNodes);
+  if (!broadRange) {
+    console.warn("Could not find quote with context in page, falling back to finding quote without context:", quote.quote);
+    return;
+  }
+
+  const broadRangeWordNodes = [];
+  for (const el of walkBetweenNodes(broadRange?.startContainer, broadRange?.endContainer)) {
+    if (el.classList?.contains('BRwordElement') || el.classList?.contains('BRspace') || el.classList?.contains('BRlineElement')) {
+      broadRangeWordNodes.push(el);
+    }
+  }
+
+  // At which point the quote should now be unambiguous!
+  const exactRange = findRangeForQuote(quote.quote, broadRange, broadRangeWordNodes);
+  if (!exactRange) {
+    throw new Error("Could not find quote in page");
+  }
+  const startTextNode = getFirstMostNode(exactRange.startContainer);
+  const endTextNode = getFirstMostNode(exactRange.endContainer);
+
+  // markRange requires the range to start and end within text nodes
+  const exactRangeTextNodes = new Range();
+  exactRangeTextNodes.setStart(startTextNode, 0);
+  exactRangeTextNodes.setEnd(endTextNode, endTextNode.textContent.length);
+
+  // Don't mark if already marked
+  if (startTextNode.parentElement.classList.contains("BRhighlight") ||
+      endTextNode.parentElement.classList.contains("BRhighlight")) {
+    return;
+  }
+
+  markRange(exactRangeTextNodes, () => {
+    const mark = document.createElement("mark");
+    mark.classList.add("BRhighlight");
+    if (cssClassName) mark.classList.add(cssClassName);
+    if (quote.uuid) mark.classList.add(quote.uuid);
+    return mark;
+  });
+}
+
+/**
+ * Given a Range, wraps its text contents in one or more <mark> elements.
+ * <mark> elements can't cross block boundaries, so this function walks the
+ * tree to find all the relevant text nodes and wraps them.
+ * @param {Range} range - the range to mark. Must start and end inside of
+ *     text nodes.
+ * @param {function(): Element} createWrappingElement - a function that creates
+ *    the element to wrap text nodes in. This is called once per text node.
+ * @return {Element[]} The <mark> nodes that were created.
+ *
+ * Lightly adapted from https://github.com/GoogleChromeLabs/text-fragments-polyfill/blob/abc6ed408b3f20e91d9cbda9977748459f5e3877/src/text-fragment-utils.js#L456
+ */
+function markRange(
+  range,
+  createWrappingElement = () => document.createElement("mark"),
+) {
+  if (range.startContainer.nodeType != Node.TEXT_NODE ||
+      range.endContainer.nodeType != Node.TEXT_NODE)
+    return [];
+
+  // If the range is entirely within a single node, just surround it.
+  if (range.startContainer === range.endContainer) {
+    const trivialMark = createWrappingElement();
+    range.surroundContents(trivialMark);
+    return [trivialMark];
+  }
+
+  // Start node -- special case
+  const startNode = range.startContainer;
+  const startNodeSubrange = range.cloneRange();
+  startNodeSubrange.setEndAfter(startNode);
+
+  // End node -- special case
+  const endNode = range.endContainer;
+  const endNodeSubrange = range.cloneRange();
+  endNodeSubrange.setStartBefore(endNode);
+
+  // In between nodes
+  const marks = [];
+  range.setStartAfter(startNode);
+  range.setEndBefore(endNode);
+  const walker = document.createTreeWalker(
+    range.commonAncestorContainer,
+    NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT,
+    {
+      acceptNode: function(node) {
+        if (!range.intersectsNode(node)) return NodeFilter.FILTER_REJECT;
+
+        if (node.nodeType === Node.TEXT_NODE)
+          return NodeFilter.FILTER_ACCEPT;
+        return NodeFilter.FILTER_SKIP;
+      },
+    },
+  );
+  let node = walker.nextNode();
+  while (node) {
+    if (node.nodeType === Node.TEXT_NODE) {
+      const mark = createWrappingElement();
+      node.parentNode.insertBefore(mark, node);
+      mark.appendChild(node);
+      marks.push(mark);
+    }
+    node = walker.nextNode();
+  }
+
+  const startMark = createWrappingElement();
+  startNodeSubrange.surroundContents(startMark);
+  const endMark = createWrappingElement();
+  endNodeSubrange.surroundContents(endMark);
+
+  return [startMark, ...marks, endMark];
+}
+
+/**
+ * Get UUID assigned to the highlight element from class list
+ * @param {HTMLElement} ele
+ * @returns
+ */
+function retrieveUUID(ele) {
+  if (!ele) return null;
+  const findUUID = Array.from(ele?.classList).filter((name) => {
+    if (name.slice(0, 2).includes('id')) {
+      return name;
+    }
+  });
+  if (findUUID.length) {
+    return findUUID[0];
+  }
+  return null;
+}
+
+/**
+ * An extension of the fields defined by the browser-native TextFragment;
+ * See https://developer.mozilla.org/en-US/docs/Web/URI/Reference/Fragment/Text_fragments
+ *
+ * Text fragment string format: `pageNumber:prefix-,quote,-suffix`
+ * Note the ':' and ',' separators must not be encoded, but
+ * the pageNumber, prefix, quote, and suffix text can be encoded.
+ */
+export class BookReaderTextFragment {
+  /**
+   * @param {object} params
+   * @param {string | null}params.prefix
+   * @param {string} params.quote
+   * @param {string | null} params.suffix
+   * @param {string | null} params.pageNumber Page number; e.g. asserted page number or the n-prefixed page index
+   * @param {number} params.pageIndex Page index; e.g. zero-based index of the page
+   * @param {string | null} [params.uuid] UUID for the text fragment if it has one
+   */
+  constructor({ prefix, quote, suffix, pageNumber, pageIndex, uuid }) {
+    /** @type {string|null} */
+    this.prefix = prefix;
+    /** @type {string} */
+    this.quote = quote;
+    /** @type {string|null} */
+    this.suffix = suffix;
+    /** @type {string|null} Page number; e.g. asserted page number or the n-prefixed page index */
+    this.pageNumber = pageNumber;
+    /** @type {number} Page index; e.g. zero-based index of the page */
+    this.pageIndex = pageIndex;
+    /** @type {string | null} UUID for the text fragment if it has one */
+    this.uuid = uuid ?? null;
+  }
+
+  /**
+   * Parse a text fragment from its string value (the part after `text=`).
+   * Expected format: `pageNumber:prefix-,quote,-suffix`
+   * @param {string} str
+   * @param {import('@/src/BookReader/BookModel.js').BookModel} book
+   * @param {number} fallbackPageIndex A fallback page index to use if the text
+   * fragment does not specify a page number or page index.
+   * @returns {BookReaderTextFragment}
+   */
+  static fromString(str, book, fallbackPageIndex) {
+    // Basically matches:
+    // (stuff):(stuff)-,(stuff),-(stuff)
+    const match = str.match(/^(?:(.*?):)?(?:(.*?)-,)?(.*?)(?:,-(.*))?$/);
+    if (!match) {
+      throw new Error(`Invalid text fragment format: ${str}`);
+    }
+    const pageNumber = match[1] ? decodeURIComponent(match[1]) : null;
+    const prefix = match[2] ? decodeURIComponent(match[2]) : null;
+    const quote = decodeURIComponent(match[3]);
+    const suffix = match[4] ? decodeURIComponent(match[4]) : null;
+    const pageIndex = pageNumber ? book.getPageIndex(pageNumber) : fallbackPageIndex;
+    if (typeof pageIndex !== 'number') {
+      throw new Error(`Could not determine page index for text fragment with page number ${pageNumber}`);
+    }
+
+    return new BookReaderTextFragment({ prefix, quote, suffix, pageNumber, pageIndex });
+  }
+
+  /**
+   * Extract and parse a text fragment from a URL string containing a `text=` parameter.
+   * @param {string} urlString
+   * @param {import('@/src/BookReader/BookModel.js').BookModel} book
+   * @param {number} fallbackPageIndex A fallback page index to use if the text
+   * fragment does not specify a page number or page index.
+   * @returns {BookReaderTextFragment|null}
+   */
+  static fromUrl(urlString, book, fallbackPageIndex) {
+    // Can't parse with eg new URLSearchParams since the text fragment format includes unencoded
+    // commas and colons, so need to do a regex match to extract the text fragment string
+    const textMatch = urlString.match(/[&?#]?text=([^&]*)/);
+    if (!textMatch) return null;
+    return BookReaderTextFragment.fromString(textMatch[1], book, fallbackPageIndex);
+  }
+
+  /**
+   * Outputs a url-safe string serialization of the text fragment, that's a variation of the standard
+   * browser TextFragment format to include page information: `pageNumber:prefix-,quote,-suffix`
+    * Note the ':' and ',' separators must not and are not encoded, but
+    * the pageNumber, prefix, quote, and suffix text are encoded.
+   * @returns {string}
+   */
+  toUrlString() {
+    // First the page number or index
+    let str = this.pageNumber ? `${encodeURIComponent(this.pageNumber)}:` : `n${this.pageIndex}:`;
+
+    if (this.prefix) {
+      str += `${encodeURIComponent(this.prefix)}-,`;
+    }
+    str += encodeURIComponent(this.quote);
+    if (this.suffix) {
+      str += `,-${encodeURIComponent(this.suffix)}`;
+    }
+    return str;
+  }
+
+  toJSON() {
+    return {
+      prefix: this.prefix,
+      quote: this.quote,
+      suffix: this.suffix,
+      pageNumber: this.pageNumber,
+      pageIndex: this.pageIndex,
+      uuid: this.uuid,
+    };
+  }
+
+  /**
+   * Create a BookReaderTextFragment instance from a JSON object.
+   * @param {object} json
+   * @returns {BookReaderTextFragment}
+   */
+  static fromJSON(json) {
+    return new BookReaderTextFragment(json);
+  }
+
+  /**
+   * Builds a TextFragment string from a given text selection.
+   * @param {Selection} selection currently selected text, eg `document.getSelection()`
+   * @param {HTMLElement[]} contextElements elements providing context for the selection
+   * @returns {BookReaderTextFragment}
+   */
+  static fromSelection(selection, contextElements) {
+    const range = selection.getRangeAt(0);
+
+    // Partially selected words need to be captured completely
+    const fullQuoteRange = new Range();
+    const startTextNode = getLastMostNode(range.startContainer);
+    const endTextNode = getFirstMostNode(range.endContainer);
+    fullQuoteRange.setStart(startTextNode, 0);
+    fullQuoteRange.setEnd(endTextNode, range.endOffset == 0 ? 0 : (endTextNode.textContent?.length ?? 0));
+
+    const preStartRange = document.createRange();
+    preStartRange.setStart(getFirstMostNode(contextElements[0]), 0);
+    preStartRange.setEnd(startTextNode, 0);
+
+    const postEndRange = document.createRange();
+    postEndRange.setStart(endTextNode, fullQuoteRange.endOffset);
+    const lastWordOfPageEl = getLastMostNode(contextElements[contextElements.length - 1]);
+    postEndRange.setEnd(lastWordOfPageEl, Math.max(0, lastWordOfPageEl.textContent.length - 1));
+
+    // prefixes/suffixes cannot contain paragraph breaks, words that are from more than one line break away should not be included
+    const prefix = getLastWords(3, preStartRange.toString())
+      .replace(/[ ]+/g, " ")
+      .trim()
+      .replace(/^[^\n]*\n/gm, "");
+    const suffix = getFirstWords(3, postEndRange.toString())
+      .replace(/[ ]+/g, " ")
+      .trim()
+      .replace(/\n[^\n]*$/gm, "");
+
+    // Guarantee that all whitespace is replaced with just one space and that the first/last word of the highlight is not a space
+    const quote = fullQuoteRange.toString().replace(/\s+/g, " ").trim();
+    const pageContainerEl = startTextNode.parentElement.closest(".BRpagecontainer");
+
+    return new BookReaderTextFragment({
+      quote,
+      prefix,
+      suffix,
+      pageNumber: pageContainerEl.getAttribute("data-page-num"),
+      pageIndex: parseFloat(pageContainerEl.getAttribute("data-index")),
+    });
+  }
+}
+
+/**
+ * @typedef {BookReaderTextFragment & { uuid: string }} BookReaderSavedHighlight
+ */