@plannotator/web-highlighter 0.8.0

package/src/index.ts

@@ -0,0 +1,285 @@
+import type { DomNode, DomMeta, HookMap, HighlighterOptions } from '@src/types';
+import EventEmitter from '@src/util/event.emitter';
+import HighlightRange from '@src/model/range';
+import { getTextFromRange } from '@src/model/range/selection';
+import HighlightSource from '@src/model/source';
+import uuid from '@src/util/uuid';
+import Hook from '@src/util/hook';
+import getInteraction from '@src/util/interaction';
+import Cache from '@src/data/cache';
+import Painter from '@src/painter';
+import { eventEmitter, getDefaultOptions, INTERNAL_ERROR_EVENT } from '@src/util/const';
+import { ERROR, EventType, CreateFrom } from '@src/types';
+import {
+    addClass,
+    removeClass,
+    isHighlightWrapNode,
+    getHighlightById,
+    getExtraHighlightId,
+    getHighlightsByRoot,
+    getHighlightId,
+    addEventListener,
+    removeEventListener,
+} from '@src/util/dom';
+
+interface EventHandlerMap {
+    [key: string]: (...args: any[]) => void;
+    [EventType.CLICK]: (data: { id: string }, h: Highlighter, e: MouseEvent | TouchEvent) => void;
+    [EventType.HOVER]: (data: { id: string }, h: Highlighter, e: MouseEvent | TouchEvent) => void;
+    [EventType.HOVER_OUT]: (data: { id: string }, h: Highlighter, e: MouseEvent | TouchEvent) => void;
+    [EventType.CREATE]: (data: { sources: HighlightSource[]; type: CreateFrom }, h: Highlighter) => void;
+    [EventType.REMOVE]: (data: { ids: string[] }, h: Highlighter) => void;
+}
+
+export default class Highlighter extends EventEmitter<EventHandlerMap> {
+    static event = EventType;
+
+    static isHighlightWrapNode = isHighlightWrapNode;
+
+    hooks: HookMap;
+
+    painter: Painter;
+
+    cache: Cache;
+
+    private _hoverId: string;
+
+    private options: HighlighterOptions;
+
+    private readonly event = getInteraction();
+
+    constructor(options?: HighlighterOptions) {
+        super();
+        this.options = getDefaultOptions();
+        // initialize hooks
+        this.hooks = this._getHooks();
+        this.setOption(options);
+        // initialize cache
+        this.cache = new Cache();
+
+        const $root = this.options.$root;
+
+        // initialize event listener
+        addEventListener($root, this.event.PointerOver, this._handleHighlightHover);
+        // initialize event listener
+        addEventListener($root, this.event.PointerTap, this._handleHighlightClick);
+        eventEmitter.on(INTERNAL_ERROR_EVENT, this._handleError);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    static isHighlightSource = (d: any) => !!d.__isHighlightSource;
+
+    run = () => addEventListener(this.options.$root, this.event.PointerEnd, this._handleSelection);
+
+    stop = () => {
+        removeEventListener(this.options.$root, this.event.PointerEnd, this._handleSelection);
+    };
+
+    addClass = (className: string, id?: string) => {
+        this.getDoms(id).forEach($n => {
+            addClass($n, className);
+        });
+    };
+
+    removeClass = (className: string, id?: string) => {
+        this.getDoms(id).forEach($n => {
+            removeClass($n, className);
+        });
+    };
+
+    getIdByDom = ($node: HTMLElement): string => getHighlightId($node, this.options.$root);
+
+    getExtraIdByDom = ($node: HTMLElement): string[] => getExtraHighlightId($node, this.options.$root);
+
+    getDoms = (id?: string): HTMLElement[] =>
+        id
+            ? getHighlightById(this.options.$root, id, this.options.wrapTag)
+            : getHighlightsByRoot(this.options.$root, this.options.wrapTag);
+
+    dispose = () => {
+        const $root = this.options.$root;
+
+        removeEventListener($root, this.event.PointerOver, this._handleHighlightHover);
+        removeEventListener($root, this.event.PointerEnd, this._handleSelection);
+        removeEventListener($root, this.event.PointerTap, this._handleHighlightClick);
+        this.removeAll();
+    };
+
+    setOption = (options?: HighlighterOptions) => {
+        this.options = {
+            ...this.options,
+            ...options,
+        };
+        this.painter = new Painter(
+            {
+                $root: this.options.$root,
+                wrapTag: this.options.wrapTag,
+                className: this.options.style.className,
+                exceptSelectors: this.options.exceptSelectors,
+            },
+            this.hooks,
+        );
+    };
+
+    fromRange = (range: Range): HighlightSource => {
+        const start: DomNode = {
+            $node: range.startContainer,
+            offset: range.startOffset,
+        };
+        const end: DomNode = {
+            $node: range.endContainer,
+            offset: range.endOffset,
+        };
+
+        // Use getTextFromRange for proper newline handling between block elements
+        const text = getTextFromRange(range);
+        let id = this.hooks.Render.UUID.call(start, end, text);
+
+        id = typeof id !== 'undefined' && id !== null ? id : uuid();
+
+        const hRange = new HighlightRange(start, end, text, id);
+
+        if (!hRange) {
+            eventEmitter.emit(INTERNAL_ERROR_EVENT, {
+                type: ERROR.RANGE_INVALID,
+            });
+
+            return null;
+        }
+
+        return this._highlightFromHRange(hRange);
+    };
+
+    fromStore = (start: DomMeta, end: DomMeta, text: string, id: string, extra?: unknown): HighlightSource => {
+        const hs = new HighlightSource(start, end, text, id, extra);
+
+        try {
+            this._highlightFromHSource(hs);
+
+            return hs;
+        } catch (err: unknown) {
+            eventEmitter.emit(INTERNAL_ERROR_EVENT, {
+                type: ERROR.HIGHLIGHT_SOURCE_RECREATE,
+                error: err,
+                detail: hs,
+            });
+
+            return null;
+        }
+    };
+
+    remove(id: string) {
+        if (!id) {
+            return;
+        }
+
+        const doseExist = this.painter.removeHighlight(id);
+
+        this.cache.remove(id);
+
+        // only emit REMOVE event when highlight exist
+        if (doseExist) {
+            this.emit(EventType.REMOVE, { ids: [id] }, this);
+        }
+    }
+
+    removeAll() {
+        this.painter.removeAllHighlight();
+
+        const ids = this.cache.removeAll();
+
+        this.emit(EventType.REMOVE, { ids }, this);
+    }
+
+    private readonly _getHooks = (): HookMap => ({
+        Render: {
+            UUID: new Hook('Render.UUID'),
+            SelectedNodes: new Hook('Render.SelectedNodes'),
+            WrapNode: new Hook('Render.WrapNode'),
+        },
+        Serialize: {
+            Restore: new Hook('Serialize.Restore'),
+            RecordInfo: new Hook('Serialize.RecordInfo'),
+        },
+        Remove: {
+            UpdateNodes: new Hook('Remove.UpdateNodes'),
+        },
+    });
+
+    private readonly _highlightFromHRange = (range: HighlightRange): HighlightSource => {
+        const source: HighlightSource = range.serialize(this.options.$root, this.hooks);
+        const $wraps = this.painter.highlightRange(range);
+
+        if ($wraps.length === 0) {
+            eventEmitter.emit(INTERNAL_ERROR_EVENT, {
+                type: ERROR.DOM_SELECTION_EMPTY,
+            });
+
+            return null;
+        }
+
+        this.cache.save(source);
+        this.emit(EventType.CREATE, { sources: [source], type: CreateFrom.INPUT }, this);
+
+        return source;
+    };
+
+    private _highlightFromHSource(sources: HighlightSource | HighlightSource[] = []) {
+        const renderedSources: HighlightSource[] = this.painter.highlightSource(sources);
+
+        this.emit(EventType.CREATE, { sources: renderedSources, type: CreateFrom.STORE }, this);
+        this.cache.save(sources);
+    }
+
+    private readonly _handleSelection = () => {
+        const range = HighlightRange.fromSelection(this.hooks.Render.UUID);
+
+        if (range) {
+            this._highlightFromHRange(range);
+            HighlightRange.removeDomRange();
+        }
+    };
+
+    private readonly _handleHighlightHover = (e: MouseEvent | TouchEvent) => {
+        const $target = e.target as HTMLElement;
+
+        if (!isHighlightWrapNode($target)) {
+            this._hoverId && this.emit(EventType.HOVER_OUT, { id: this._hoverId }, this, e);
+            this._hoverId = null;
+
+            return;
+        }
+
+        const id = getHighlightId($target, this.options.$root);
+
+        // prevent trigger in the same highlight range
+        if (this._hoverId === id) {
+            return;
+        }
+
+        // hover another highlight range, need to trigger previous highlight hover out event
+        if (this._hoverId) {
+            this.emit(EventType.HOVER_OUT, { id: this._hoverId }, this, e);
+        }
+
+        this._hoverId = id;
+        this.emit(EventType.HOVER, { id: this._hoverId }, this, e);
+    };
+
+    private readonly _handleError = (type: { type: ERROR; detail?: HighlightSource; error?: any }) => {
+        if (this.options.verbose) {
+            // eslint-disable-next-line no-console
+            console.warn(type);
+        }
+    };
+
+    private readonly _handleHighlightClick = (e: MouseEvent | TouchEvent) => {
+        const $target = e.target as HTMLElement;
+
+        if (isHighlightWrapNode($target)) {
+            const id = getHighlightId($target, this.options.$root);
+
+            this.emit(EventType.CLICK, { id }, this, e);
+        }
+    };
+}

package/src/model/range/dom.ts

@@ -0,0 +1,94 @@
+/**
+ * some dom operations about HighlightRange
+ */
+
+import type { DomMeta, DomNode } from '@src/types';
+import { CAMEL_DATASET_IDENTIFIER, ROOT_IDX, UNKNOWN_IDX } from '@src/util/const';
+
+const countGlobalNodeIndex = ($node: Node, $root: Document | HTMLElement): number => {
+    const tagName = ($node as HTMLElement).tagName;
+    const $list = $root.getElementsByTagName(tagName);
+
+    for (let i = 0; i < $list.length; i++) {
+        if ($node === $list[i]) {
+            return i;
+        }
+    }
+
+    return UNKNOWN_IDX;
+};
+
+/**
+ * text total length in all predecessors (text nodes) in the root node
+ * (without offset in current node)
+ */
+const getTextPreOffset = ($root: Node, $text: Node): number => {
+    const nodeStack: Node[] = [$root];
+
+    let $curNode: Node = null;
+    let offset = 0;
+
+    while (($curNode = nodeStack.pop())) {
+        const children = $curNode.childNodes;
+
+        for (let i = children.length - 1; i >= 0; i--) {
+            nodeStack.push(children[i]);
+        }
+
+        if ($curNode.nodeType === 3 && $curNode !== $text) {
+            offset += $curNode.textContent.length;
+        } else if ($curNode.nodeType === 3) {
+            break;
+        }
+    }
+
+    return offset;
+};
+
+/**
+ * find the original dom parent node (none highlight dom)
+ */
+const getOriginParent = ($node: HTMLElement | Text): HTMLElement => {
+    if ($node instanceof HTMLElement && (!$node.dataset || !$node.dataset[CAMEL_DATASET_IDENTIFIER])) {
+        return $node;
+    }
+
+    let $originParent = $node.parentNode as HTMLElement;
+
+    while ($originParent?.dataset[CAMEL_DATASET_IDENTIFIER]) {
+        $originParent = $originParent.parentNode as HTMLElement;
+    }
+
+    return $originParent;
+};
+
+export const getDomMeta = ($node: HTMLElement | Text, offset: number, $root: Document | HTMLElement): DomMeta => {
+    const $originParent = getOriginParent($node);
+    const index = $originParent === $root ? ROOT_IDX : countGlobalNodeIndex($originParent, $root);
+    const preNodeOffset = getTextPreOffset($originParent, $node);
+    const tagName = $originParent.tagName;
+
+    return {
+        parentTagName: tagName,
+        parentIndex: index,
+        textOffset: preNodeOffset + offset,
+    };
+};
+
+export const formatDomNode = (n: DomNode): DomNode => {
+    if (
+        // Text
+        n.$node.nodeType === 3 ||
+        // CDATASection
+        n.$node.nodeType === 4 ||
+        // Comment
+        n.$node.nodeType === 8
+    ) {
+        return n;
+    }
+
+    return {
+        $node: n.$node.childNodes[n.offset],
+        offset: 0,
+    };
+};

package/src/model/range/index.ts

@@ -0,0 +1,88 @@
+/**
+ * the HighlightRange Class（HRange）
+ * It's a special object called HRange in Highlighter,
+ * represents for a piece of chosen dom
+ */
+
+import type { DomNode, HookMap } from '@src/types';
+import type Hook from '@src/util/hook';
+import HighlightSource from '@src/model/source/index';
+import { ERROR } from '@src/types';
+import { getDomRange, removeSelection } from '@src/model/range/selection';
+import uuid from '@src/util/uuid';
+import { getDomMeta, formatDomNode } from '@src/model/range/dom';
+import { eventEmitter, INTERNAL_ERROR_EVENT } from '@src/util/const';
+
+class HighlightRange {
+    static removeDomRange = removeSelection;
+
+    start: DomNode;
+
+    end: DomNode;
+
+    text: string;
+
+    id: string;
+
+    frozen: boolean;
+
+    constructor(start: DomNode, end: DomNode, text: string, id: string, frozen = false) {
+        if (start.$node.nodeType !== 3 || end.$node.nodeType !== 3) {
+            eventEmitter.emit(INTERNAL_ERROR_EVENT, {
+                type: ERROR.RANGE_NODE_INVALID,
+            });
+        }
+
+        this.start = formatDomNode(start);
+        this.end = formatDomNode(end);
+        this.text = text;
+        this.frozen = frozen;
+        this.id = id;
+    }
+
+    static fromSelection(idHook: Hook<string>) {
+        const range = getDomRange();
+
+        if (!range) {
+            return null;
+        }
+
+        const start: DomNode = {
+            $node: range.startContainer,
+            offset: range.startOffset,
+        };
+        const end: DomNode = {
+            $node: range.endContainer,
+            offset: range.endOffset,
+        };
+
+        // Use Selection.toString() for proper newline handling between block elements
+        // Range.toString() includes HTML source whitespace, Selection.toString() gives clean output
+        const selection = window.getSelection();
+        const text = selection?.toString() || range.toString();
+        let id = idHook.call(start, end, text);
+
+        id = typeof id !== 'undefined' && id !== null ? id : uuid();
+
+        return new HighlightRange(start, end, text, id);
+    }
+
+    // serialize the HRange instance
+    // so that you can save the returned object (e.g. use JSON.stringify on it and send to backend)
+    serialize($root: Document | HTMLElement, hooks: HookMap): HighlightSource {
+        const startMeta = getDomMeta(this.start.$node as Text, this.start.offset, $root);
+        const endMeta = getDomMeta(this.end.$node as Text, this.end.offset, $root);
+
+        let extra;
+
+        if (!hooks.Serialize.RecordInfo.isEmpty()) {
+            extra = hooks.Serialize.RecordInfo.call(this.start, this.end, $root);
+        }
+
+        this.frozen = true;
+
+        return new HighlightSource(startMeta, endMeta, this.text, this.id, extra);
+    }
+}
+
+export default HighlightRange;

package/src/model/range/selection.ts

@@ -0,0 +1,55 @@
+/**
+ * Something about the Selection/Range API in browsers.
+ * If you want to use Highlighter in some old browsers, you may use a polyfill.
+ * https://caniuse.com/#search=selection
+ */
+
+export const getDomRange = (): Range => {
+    const selection = window.getSelection();
+
+    if (selection.isCollapsed) {
+        // eslint-disable-next-line no-console
+        console.debug('no text selected');
+
+        return null;
+    }
+
+    return selection.getRangeAt(0);
+};
+
+export const removeSelection = (): void => {
+    window.getSelection().removeAllRanges();
+};
+
+/**
+ * Get text from a Range with proper newline handling for block elements.
+ * Uses innerText on a cloned fragment to get clean output matching Selection.toString().
+ * Range.toString() includes HTML source whitespace, this method gives user-expected output.
+ * Falls back to range.toString() in environments where innerText isn't available (e.g. jsdom).
+ */
+export const getTextFromRange = (range: Range): string => {
+    // Try innerText approach for proper newline handling in real browsers
+    try {
+        const fragment = range.cloneContents();
+        const temp = document.createElement('div');
+
+        // Position off-screen but keep visible - innerText returns empty for hidden elements!
+        temp.style.cssText = 'position:absolute;left:-9999px;top:-9999px;';
+        document.body.appendChild(temp);
+        temp.appendChild(fragment);
+
+        const text = temp.innerText;
+
+        temp.remove();
+
+        // innerText may be undefined in jsdom, or empty if something went wrong
+        if (text) {
+            return text;
+        }
+    } catch (e: unknown) {
+        // Fall through to fallback
+    }
+
+    // Fallback to range.toString() (loses proper newline handling but works everywhere)
+    return range.toString();
+};

package/src/model/source/dom.ts

@@ -0,0 +1,66 @@
+import type { DomNode } from '@src//types';
+import type HighlightSource from '@src/model/source/index';
+import { ROOT_IDX } from '@src/util/const';
+
+/**
+ * Because of supporting highlighting a same area (range overlapping),
+ * Highlighter will calculate which text-node and how much offset it actually be,
+ * based on the origin website dom node and the text offset.
+ *
+ * @param {Node} $parent element node in the origin website dom tree
+ * @param {number} offset text offset in the origin website dom tree
+ * @return {DomNode} DOM a dom info object
+ */
+export const getTextChildByOffset = ($parent: Node, offset: number): DomNode => {
+    const nodeStack: Node[] = [$parent];
+
+    let $curNode: Node = null;
+    let curOffset = 0;
+    let startOffset = 0;
+
+    while (($curNode = nodeStack.pop())) {
+        const children = $curNode.childNodes;
+
+        for (let i = children.length - 1; i >= 0; i--) {
+            nodeStack.push(children[i]);
+        }
+
+        if ($curNode.nodeType === 3) {
+            startOffset = offset - curOffset;
+            curOffset += $curNode.textContent.length;
+
+            if (curOffset >= offset) {
+                break;
+            }
+        }
+    }
+
+    if (!$curNode) {
+        $curNode = $parent;
+    }
+
+    return {
+        $node: $curNode,
+        offset: startOffset,
+    };
+};
+
+/**
+ * get start and end parent element from meta info
+ *
+ * @param {HighlightSource} hs
+ * @param {HTMLElement | Document} $root root element, default document
+ * @return {Object}
+ */
+export const queryElementNode = (hs: HighlightSource, $root: Document | HTMLElement): { start: Node; end: Node } => {
+    const start =
+        hs.startMeta.parentIndex === ROOT_IDX
+            ? $root
+            : $root.getElementsByTagName(hs.startMeta.parentTagName)[hs.startMeta.parentIndex];
+    const end =
+        hs.endMeta.parentIndex === ROOT_IDX
+            ? $root
+            : $root.getElementsByTagName(hs.endMeta.parentTagName)[hs.endMeta.parentIndex];
+
+    return { start, end };
+};

package/src/model/source/index.ts

@@ -0,0 +1,54 @@
+/**
+ * HighlightSource Class (HSource)
+ * This Object can be deSerialized to HRange.
+ * Also it has the ability for persistence.
+ */
+
+import type { DomMeta, HookMap, DomNode } from '@src/types';
+import HighlightRange from '@src/model/range/index';
+import { queryElementNode, getTextChildByOffset } from '@src/model/source/dom';
+
+class HighlightSource {
+    startMeta: DomMeta;
+
+    endMeta: DomMeta;
+
+    text: string;
+
+    id: string;
+
+    extra?: unknown;
+
+    __isHighlightSource: unknown;
+
+    constructor(startMeta: DomMeta, endMeta: DomMeta, text: string, id: string, extra?: unknown) {
+        this.startMeta = startMeta;
+        this.endMeta = endMeta;
+        this.text = text;
+        this.id = id;
+        this.__isHighlightSource = {};
+
+        if (extra) {
+            this.extra = extra;
+        }
+    }
+
+    deSerialize($root: Document | HTMLElement, hooks: HookMap): HighlightRange {
+        const { start, end } = queryElementNode(this, $root);
+        let startInfo = getTextChildByOffset(start, this.startMeta.textOffset);
+        let endInfo = getTextChildByOffset(end, this.endMeta.textOffset);
+
+        if (!hooks.Serialize.Restore.isEmpty()) {
+            const res: DomNode[] = hooks.Serialize.Restore.call(this, startInfo, endInfo) || [];
+
+            startInfo = res[0] || startInfo;
+            endInfo = res[1] || endInfo;
+        }
+
+        const range = new HighlightRange(startInfo, endInfo, this.text, this.id, true);
+
+        return range;
+    }
+}
+
+export default HighlightSource;