Turn highlightText into a class TextHighlight

packages/dom/src/index.ts

@@ -25,4 +25,4 @@ export * from './css.js';
 export * from './range/index.js';
 export * from './text-quote/index.js';
 export * from './text-position/index.js';
-export * from './highlight-text.js';
+export * from './text-highlight.js';

packages/dom/src/text-highlight.ts

@@ -0,0 +1,214 @@
+/**
+ * @license
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ *
+ * SPDX-FileCopyrightText: The Apache Software Foundation
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ownerDocument } from './owner-document.js';
+import { toRange } from './to-range.js';
+
+/**
+ * Wrap each text node in a given Node or Range with a `<mark>` or other
+ * element.
+ *
+ * If a Range is given that starts and/or ends within a Text node, that node
+ * will be split in order to only wrap the contained part in the mark element.
+ *
+ * The highlight can be removed again by calling the function that cleans up the
+ * wrapper elements. Note that this might not perfectly restore the DOM to its
+ * previous state: text nodes that were split are not merged again. One could
+ * consider running `range.commonAncestorContainer.normalize()` afterwards to
+ * join all adjacent text nodes.
+ *
+ * @deprecated
+ * Use TextHighlight instead:
+ *
+ *     highlight = new TextHighlight(…);
+ *     highlight.remove();
+ *
+ * @param target - The Node/Range containing the text. If it is a Range, note
+ * that as highlighting modifies the DOM, the Range may be unusable afterwards.
+ * @param tagName - The element used to wrap text nodes. Defaults to `'mark'`.
+ * @param attributes - An object defining any attributes to be set on the
+ * wrapper elements, e.g. its `class`.
+ * @returns A function that removes the created highlight.
+ *
+ * @public
+ */
+export function highlightText(
+  target: Node | Range,
+  tagName = 'mark',
+  attributes: Record<string, string> = {},
+): () => void {
+  const highlight = new TextHighlight(target, tagName, attributes);
+  return () => highlight.remove();
+}
+
+export class TextHighlight {
+  public readonly highlightElements: HTMLElement[] = [];
+
+  /**
+   * Wrap each text node in a given Node or Range with a `<mark>` or other
+   * element.
+   *
+   * If a Range is given that starts and/or ends within a Text node, that node
+   * will be split in order to only wrap the contained part in the mark element.
+   *
+   * @param target - The Node/Range containing the text. If it is a Range, note
+   * that as highlighting modifies the DOM, the Range may be unusable
+   * afterwards.
+   * @param element - The element used to wrap text nodes. Pass either a string
+   * with its tag name, or an Element to be cloned. Defaults to `'mark'`.
+   * @param attributes - An object defining any attributes to be set on the
+   * wrapper elements, e.g. its `class`. Not applicable if `element` is a
+   * function.
+   * @returns A {@link Highlight} object, that can be used to access the wrapper
+   * elements or to remove the highlight again.
+   *
+   * @public
+   */
+  constructor(
+    target: Node | Range,
+    element: string | HTMLElement = "mark",
+    attributes: Record<string, string> = {},
+  ) {
+    // First put all nodes in an array (splits start and end nodes if needed)
+    const nodes = this.textNodesInRange(toRange(target));
+
+    // Highlight each node
+    for (const node of nodes) {
+      const highlightElement = this.wrapNodeInHighlight(node, element, attributes);
+      this.highlightElements.push(highlightElement);
+    }
+  }
+
+  /**
+   * Remove each of the created highlightElements.
+   *
+   * It takes the wrapping (`<mark>`) elements out of the DOM tree, thus moving
+   * their child node(s) one level up.
+   */
+  public remove() {
+    for (const highlightElement of this.highlightElements) {
+      this.removeHighlightElement(highlightElement);
+    }
+  }
+
+  /**
+   * Return an array of the text nodes in the range. Split the start and end nodes if required.
+   */
+  private textNodesInRange(range: Range): Text[] {
+    // If the start or end node is a text node and only partly in the range, split it.
+    if (isTextNode(range.startContainer) && range.startOffset > 0) {
+      const endOffset = range.endOffset; // (this may get lost when the splitting the node)
+      const createdNode = range.startContainer.splitText(range.startOffset);
+      if (range.endContainer === range.startContainer) {
+        // If the end was in the same container, it will now be in the newly created node.
+        range.setEnd(createdNode, endOffset - range.startOffset);
+      }
+      range.setStart(createdNode, 0);
+    }
+    if (
+      isTextNode(range.endContainer) &&
+      range.endOffset < range.endContainer.length
+    ) {
+      range.endContainer.splitText(range.endOffset);
+    }
+
+    // Collect the text nodes.
+    const walker = ownerDocument(range).createTreeWalker(
+      range.commonAncestorContainer,
+      NodeFilter.SHOW_TEXT,
+      {
+        acceptNode: (node) =>
+          range.intersectsNode(node)
+            ? NodeFilter.FILTER_ACCEPT
+            : NodeFilter.FILTER_REJECT,
+      }
+    );
+    walker.currentNode = range.startContainer;
+
+    // // Optimise by skipping nodes that are explicitly outside the range.
+    // const NodeTypesWithCharacterOffset = [
+    //  Node.TEXT_NODE,
+    //  Node.PROCESSING_INSTRUCTION_NODE,
+    //  Node.COMMENT_NODE,
+    // ];
+    // if (!NodeTypesWithCharacterOffset.includes(range.startContainer.nodeType)) {
+    //   if (range.startOffset < range.startContainer.childNodes.length) {
+    //     walker.currentNode = range.startContainer.childNodes[range.startOffset];
+    //   } else {
+    //     walker.nextSibling(); // TODO verify this is correct.
+    //   }
+    // }
+
+    const nodes: Text[] = [];
+    if (isTextNode(walker.currentNode)) nodes.push(walker.currentNode);
+    while (walker.nextNode() && range.comparePoint(walker.currentNode, 0) !== 1)
+      nodes.push(walker.currentNode as Text);
+    return nodes;
+  }
+
+  /**
+   * Replace [node] with <tagName ...attributes>[node]</tagName>
+   */
+  private wrapNodeInHighlight(
+    node: ChildNode,
+    element: string | HTMLElement,
+    attributes: Record<string, string>
+  ): HTMLElement {
+    const document = node.ownerDocument as Document;
+    const highlightElement =
+      typeof element === "string"
+        ? document.createElement(element)
+        : (element.cloneNode() as typeof element);
+    Object.keys(attributes).forEach((key) => {
+      highlightElement.setAttribute(key, attributes[key]);
+    });
+    const tempRange = document.createRange();
+    tempRange.selectNode(node);
+    tempRange.surroundContents(highlightElement);
+    return highlightElement;
+  }
+
+  /**
+   * Remove a highlight element created with wrapNodeInHighlight.
+   */
+  private removeHighlightElement(highlightElement: HTMLElement) {
+    // If it has somehow been removed already, there is nothing to be done.
+    if (!highlightElement.parentNode) return;
+    if (highlightElement.childNodes.length === 1) {
+      highlightElement.replaceWith(highlightElement.firstChild as Node);
+    } else {
+      // If the highlight somehow contains multiple nodes now, move them all.
+      while (highlightElement.firstChild) {
+        highlightElement.parentNode.insertBefore(
+          highlightElement.firstChild,
+          highlightElement
+        );
+      }
+      highlightElement.remove();
+    }
+  }
+}
+
+function isTextNode(node: Node): node is Text {
+  return node.nodeType === Node.TEXT_NODE;
+}