Make highlightRange accept Node, rename to highlightText
Fixes issue #111 <https://github.com/apache/incubator-annotator/issues/111>
diff --git a/packages/dom/src/highlight-range.ts b/packages/dom/src/highlight-text.ts
similarity index 89%
rename from packages/dom/src/highlight-range.ts
rename to packages/dom/src/highlight-text.ts
index 93ff390..5f8b4f3 100644
--- a/packages/dom/src/highlight-range.ts
+++ b/packages/dom/src/highlight-text.ts
@@ -19,12 +19,14 @@
*/
import { ownerDocument } from './owner-document';
+import { toRange } from './to-range';
/**
- * Wrap each text node in a given DOM Range with a `<mark>` or other element.
+ * Wrap each text node in a given Node or Range with a `<mark>` or other
+ * element.
*
- * If the Range start and/or ends within a Text node, that node will be split
- * in order to only wrap the contained part in the mark 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
@@ -32,22 +34,22 @@
* consider running `range.commonAncestorContainer.normalize()` afterwards to
* join all adjacent text nodes.
*
- * @param range - A DOM Range object. 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 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
+ * wrapper elements, e.g. its `class`.
* @returns A function that removes the created highlight.
*
* @public
*/
-export function highlightRange(
- range: Range,
+export function highlightText(
+ target: Node | Range,
tagName = 'mark',
attributes: Record<string, string> = {},
): () => void {
// First put all nodes in an array (splits start and end nodes if needed)
- const nodes = textNodesInRange(range);
+ const nodes = textNodesInRange(toRange(target));
// Highlight each node
const highlightElements: HTMLElement[] = [];
diff --git a/packages/dom/src/index.ts b/packages/dom/src/index.ts
index cd7d2ea..f687579 100644
--- a/packages/dom/src/index.ts
+++ b/packages/dom/src/index.ts
@@ -22,4 +22,4 @@
export * from './range';
export * from './text-quote';
export * from './text-position';
-export * from './highlight-range';
+export * from './highlight-text';
diff --git a/packages/dom/test/highlight-range/highlight-range.test.ts b/packages/dom/test/highlight-range/highlight-range.test.ts
index dae8212..b194419 100644
--- a/packages/dom/test/highlight-range/highlight-range.test.ts
+++ b/packages/dom/test/highlight-range/highlight-range.test.ts
@@ -19,7 +19,7 @@
*/
import { assert } from 'chai';
-import { highlightRange } from '../../src/highlight-range';
+import { highlightText } from '../../src/highlight-text';
import type { RangeInfo } from '../utils';
import { hydrateRange, evaluateXPath } from '../utils';
@@ -105,7 +105,7 @@
},
};
-describe('highlightRange', () => {
+describe('highlightText', () => {
for (const [
name,
{ inputHtml, range, tagName, attributes, expectedHtml },
@@ -113,8 +113,8 @@
it(`works for case: ${name}`, () => {
const doc = domParser.parseFromString(inputHtml, 'text/html');
- // Invoke highlightRange for the specified Range, and check the result.
- const removeHighlights = highlightRange(
+ // Invoke highlightText for the specified Range, and check the result.
+ const removeHighlights = highlightText(
hydrateRange(range, doc),
tagName,
attributes,
@@ -138,7 +138,7 @@
range.setStart(evaluateXPath(doc, '//b/text()[1]'), 12); // before 'dolor am'
range.setEnd(evaluateXPath(doc, '//b/text()[2]'), 20 - 15); // after 'dolor am'
- const removeHighlights = highlightRange(range);
+ const removeHighlights = highlightText(range);
const expectedHtml =
'<b>lorem ipsum <mark>dol</mark><mark>or am</mark>et yada yada</b>';
assert.equal(doc.body.innerHTML, expectedHtml);
@@ -159,7 +159,7 @@
range.setStart(evaluateXPath(doc, '//b/text()[1]'), 12); // before 'dolor am'
range.setEnd(evaluateXPath(doc, '//b/text()[3]'), 20 - 15); // after 'dolor am'
- const removeHighlights = highlightRange(range);
+ const removeHighlights = highlightText(range);
const expectedHtml =
'<b>lorem ipsum <mark>dol</mark><mark></mark><mark>or am</mark>et yada yada</b>';
assert.equal(doc.body.innerHTML, expectedHtml);
@@ -175,7 +175,7 @@
const range = doc.createRange();
range.selectNode(evaluateXPath(doc, '//img'));
- const removeHighlights = highlightRange(range);
+ const removeHighlights = highlightText(range);
assert.equal(doc.body.innerHTML, inputHtml);
removeHighlights();
@@ -187,8 +187,8 @@
const { range: range2, expectedHtml } = testCases['overlapping highlight'];
const doc = domParser.parseFromString(inputHtml, 'text/html');
- const removeHighlights1 = highlightRange(hydrateRange(range, doc));
- const removeHighlights2 = highlightRange(
+ const removeHighlights1 = highlightText(hydrateRange(range, doc));
+ const removeHighlights2 = highlightText(
hydrateRange(range2, doc),
'mark2',
);
@@ -204,8 +204,8 @@
const { range: range2, expectedHtml } = testCases['overlapping highlight'];
const doc = domParser.parseFromString(inputHtml, 'text/html');
- const removeHighlights1 = highlightRange(hydrateRange(range, doc));
- const removeHighlights2 = highlightRange(
+ const removeHighlights1 = highlightText(hydrateRange(range, doc));
+ const removeHighlights2 = highlightText(
hydrateRange(range2, doc),
'mark2',
);
diff --git a/web/index.js b/web/index.js
index abb9a8b..5ca1445 100644
--- a/web/index.js
+++ b/web/index.js
@@ -26,7 +26,7 @@
describeTextQuote,
createTextPositionSelectorMatcher,
describeTextPosition,
- highlightRange,
+ highlightText,
} from '@apache-annotator/dom';
import { makeRefinable } from '@apache-annotator/selector';
@@ -119,7 +119,7 @@
}
for (const range of ranges) {
- const removeHighlight = highlightRange(range);
+ const removeHighlight = highlightText(range);
moduleState.cleanupFunctions.push(removeHighlight);
}
