@plannotator/web-highlighter 0.8.0

package/src/painter/dom.ts

@@ -0,0 +1,345 @@
+import type HighlightRange from '@src/model/range';
+import type { SelectedNode, DomNode } from '@src/types';
+import { SplitType, SelectedNodeType } from '@src/types';
+import { hasClass, addClass as addElementClass, isHighlightWrapNode, removeAllClass } from '@src/util/dom';
+import {
+    ID_DIVISION,
+    getDefaultOptions,
+    CAMEL_DATASET_IDENTIFIER,
+    CAMEL_DATASET_IDENTIFIER_EXTRA,
+    DATASET_IDENTIFIER,
+    DATASET_SPLIT_TYPE,
+    DATASET_IDENTIFIER_EXTRA,
+} from '../util/const';
+import { unique } from '../util/tool';
+
+/**
+ * 支持的选择器类型
+ *  - class: .title, .main-nav
+ *  - id: #nav, #js-toggle-btn
+ *  - tag: div, p, span
+ */
+const isMatchSelector = ($node: HTMLElement, selector: string): boolean => {
+    if (!$node) {
+        return false;
+    }
+
+    if (/^\./.test(selector)) {
+        const className = selector.replace(/^\./, '');
+
+        return $node && hasClass($node, className);
+    } else if (/^#/.test(selector)) {
+        const id = selector.replace(/^#/, '');
+
+        return $node && $node.id === id;
+    }
+
+    const tagName = selector.toUpperCase();
+
+    return $node && $node.tagName === tagName;
+};
+
+/**
+ * If start node and end node is the same, don't need to tranvers the dom tree.
+ */
+const getNodesIfSameStartEnd = (
+    $startNode: Text,
+    startOffset: number,
+    endOffset: number,
+    exceptSelectors?: string[],
+) => {
+    let $element = $startNode as Node;
+
+    const isExcepted = ($e: HTMLElement) => exceptSelectors?.some(s => isMatchSelector($e, s));
+
+    while ($element) {
+        if ($element.nodeType === 1 && isExcepted($element as HTMLElement)) {
+            return [];
+        }
+
+        $element = $element.parentNode;
+    }
+
+    $startNode.splitText(startOffset);
+
+    const passedNode = $startNode.nextSibling as Text;
+
+    passedNode.splitText(endOffset - startOffset);
+
+    return [
+        {
+            $node: passedNode,
+            type: SelectedNodeType.text,
+            splitType: SplitType.both,
+        },
+    ];
+};
+
+/**
+ * get all the dom nodes between the start and end node
+ */
+export const getSelectedNodes = (
+    $root: Document | HTMLElement,
+    start: DomNode,
+    end: DomNode,
+    exceptSelectors: string[],
+): SelectedNode[] => {
+    const $startNode = start.$node;
+    const $endNode = end.$node;
+    const startOffset = start.offset;
+    const endOffset = end.offset;
+
+    // split current node when the start-node and end-node is the same
+    if ($startNode === $endNode && $startNode instanceof Text) {
+        return getNodesIfSameStartEnd($startNode, startOffset, endOffset, exceptSelectors);
+    }
+
+    const nodeStack: (ChildNode | Document | HTMLElement | Text)[] = [$root];
+    const selectedNodes: SelectedNode[] = [];
+
+    const isExcepted = ($e: HTMLElement) => exceptSelectors?.some(s => isMatchSelector($e, s));
+
+    let withinSelectedRange = false;
+    let curNode: Node = null;
+
+    while ((curNode = nodeStack.pop())) {
+        // do not traverse the excepted node
+        if (curNode.nodeType === 1 && isExcepted(curNode as HTMLElement)) {
+            continue;
+        }
+
+        const children = curNode.childNodes;
+
+        for (let i = children.length - 1; i >= 0; i--) {
+            nodeStack.push(children[i]);
+        }
+
+        // only collect text nodes
+        if (curNode === $startNode) {
+            if (curNode.nodeType === 3) {
+                (curNode as Text).splitText(startOffset);
+
+                const node = curNode.nextSibling as Text;
+
+                selectedNodes.push({
+                    $node: node,
+                    type: SelectedNodeType.text,
+                    splitType: SplitType.head,
+                });
+            }
+
+            // meet the start-node (begin to traverse)
+            withinSelectedRange = true;
+        } else if (curNode === $endNode) {
+            if (curNode.nodeType === 3) {
+                const node = curNode as Text;
+
+                node.splitText(endOffset);
+                selectedNodes.push({
+                    $node: node,
+                    type: SelectedNodeType.text,
+                    splitType: SplitType.tail,
+                });
+            }
+
+            // meet the end-node
+            break;
+        }
+        // handle text nodes between the range
+        else if (withinSelectedRange && curNode.nodeType === 3) {
+            selectedNodes.push({
+                $node: curNode as Text,
+                type: SelectedNodeType.text,
+                splitType: SplitType.none,
+            });
+        }
+    }
+
+    return selectedNodes;
+};
+
+const addClass = ($el: HTMLElement, className?: string[] | string): HTMLElement => {
+    let classNames = Array.isArray(className) ? className : [className];
+
+    classNames = classNames.length === 0 ? [getDefaultOptions().style.className] : classNames;
+    classNames.forEach(c => {
+        addElementClass($el, c);
+    });
+
+    return $el;
+};
+
+const isNodeEmpty = ($n: Node): boolean => !$n || !$n.textContent;
+
+/**
+ * Wrap a common wrapper.
+ */
+const wrapNewNode = (
+    selected: SelectedNode,
+    range: HighlightRange,
+    className: string[] | string,
+    wrapTag: string,
+): HTMLElement => {
+    const $wrap = document.createElement(wrapTag);
+
+    addClass($wrap, className);
+
+    $wrap.appendChild(selected.$node.cloneNode(false));
+    selected.$node.parentNode.replaceChild($wrap, selected.$node);
+
+    $wrap.setAttribute(`data-${DATASET_IDENTIFIER}`, range.id);
+    $wrap.setAttribute(`data-${DATASET_SPLIT_TYPE}`, selected.splitType);
+    $wrap.setAttribute(`data-${DATASET_IDENTIFIER_EXTRA}`, '');
+
+    return $wrap;
+};
+
+/**
+ * Split and wrapper each one.
+ */
+const wrapPartialNode = (
+    selected: SelectedNode,
+    range: HighlightRange,
+    className: string[] | string,
+    wrapTag: string,
+): HTMLElement => {
+    const $wrap: HTMLElement = document.createElement(wrapTag);
+
+    const $parent = selected.$node.parentNode as HTMLElement;
+    const $prev = selected.$node.previousSibling;
+    const $next = selected.$node.nextSibling;
+    const $fr = document.createDocumentFragment();
+    const parentId = $parent.dataset[CAMEL_DATASET_IDENTIFIER];
+    const parentExtraId = $parent.dataset[CAMEL_DATASET_IDENTIFIER_EXTRA];
+    const extraInfo = parentExtraId ? parentId + ID_DIVISION + parentExtraId : parentId;
+
+    $wrap.setAttribute(`data-${DATASET_IDENTIFIER}`, range.id);
+    $wrap.setAttribute(`data-${DATASET_IDENTIFIER_EXTRA}`, extraInfo);
+    $wrap.appendChild(selected.$node.cloneNode(false));
+
+    let headSplit = false;
+    let tailSplit = false;
+    let splitType: SplitType;
+
+    if ($prev) {
+        const $span = $parent.cloneNode(false);
+
+        $span.textContent = $prev.textContent;
+        $fr.appendChild($span);
+        headSplit = true;
+    }
+
+    const classNameList: string[] = [];
+
+    if (Array.isArray(className)) {
+        classNameList.push(...className);
+    } else {
+        classNameList.push(className);
+    }
+
+    addClass($wrap, unique(classNameList));
+    $fr.appendChild($wrap);
+
+    if ($next) {
+        const $span = $parent.cloneNode(false);
+
+        $span.textContent = $next.textContent;
+        $fr.appendChild($span);
+        tailSplit = true;
+    }
+
+    if (headSplit && tailSplit) {
+        splitType = SplitType.both;
+    } else if (headSplit) {
+        splitType = SplitType.head;
+    } else if (tailSplit) {
+        splitType = SplitType.tail;
+    } else {
+        splitType = SplitType.none;
+    }
+
+    $wrap.setAttribute(`data-${DATASET_SPLIT_TYPE}`, splitType);
+    $parent.parentNode.replaceChild($fr, $parent);
+
+    return $wrap;
+};
+
+/**
+ * Just update id info (no wrapper updated).
+ */
+const wrapOverlapNode = (selected: SelectedNode, range: HighlightRange, className: string[] | string): HTMLElement => {
+    const $parent = selected.$node.parentNode as HTMLElement;
+    const $wrap: HTMLElement = $parent;
+
+    removeAllClass($wrap);
+    addClass($wrap, className);
+
+    const dataset = $parent.dataset;
+    const formerId = dataset[CAMEL_DATASET_IDENTIFIER];
+
+    dataset[CAMEL_DATASET_IDENTIFIER] = range.id;
+    dataset[CAMEL_DATASET_IDENTIFIER_EXTRA] = dataset[CAMEL_DATASET_IDENTIFIER_EXTRA]
+        ? formerId + ID_DIVISION + dataset[CAMEL_DATASET_IDENTIFIER_EXTRA]
+        : formerId;
+
+    return $wrap;
+};
+
+/**
+ * wrap a dom node with highlight wrapper
+ *
+ * Because of supporting the highlight-overlapping,
+ * Highlighter can't just wrap all nodes in a simple way.
+ * There are three types:
+ *  - wrapping a whole new node (without any wrapper)
+ *  - wrapping part of the node
+ *  - wrapping the whole wrapped node
+ */
+export const wrapHighlight = (
+    selected: SelectedNode,
+    range: HighlightRange,
+    className: string[] | string,
+    wrapTag: string,
+): HTMLElement => {
+    const $parent = selected.$node.parentNode as HTMLElement;
+    const $prev = selected.$node.previousSibling;
+    const $next = selected.$node.nextSibling;
+
+    let $wrap: HTMLElement;
+
+    // text node, not in a highlight wrapper -> should be wrapped in a highlight wrapper
+    if (!isHighlightWrapNode($parent)) {
+        $wrap = wrapNewNode(selected, range, className, wrapTag);
+    }
+    // text node, in a highlight wrap -> should split the existing highlight wrapper
+    else if (isHighlightWrapNode($parent) && (!isNodeEmpty($prev) || !isNodeEmpty($next))) {
+        $wrap = wrapPartialNode(selected, range, className, wrapTag);
+    }
+    // completely overlap (with a highlight wrap) -> only add extra id info
+    else {
+        $wrap = wrapOverlapNode(selected, range, className);
+    }
+
+    return $wrap;
+};
+
+/**
+ * merge the adjacent text nodes
+ * .normalize() API has some bugs in IE11
+ */
+export const normalizeSiblingText = ($s: Node, isNext = true) => {
+    if (!$s || $s.nodeType !== 3) {
+        return;
+    }
+
+    const $sibling = isNext ? $s.nextSibling : $s.previousSibling;
+
+    if ($sibling.nodeType !== 3) {
+        return;
+    }
+
+    const text = $sibling.nodeValue;
+
+    $s.nodeValue = isNext ? $s.nodeValue + text : text + $s.nodeValue;
+    $sibling.parentNode.removeChild($sibling);
+};

package/src/painter/index.ts

@@ -0,0 +1,199 @@
+/**
+ * Painter object is designed for some painting work about higlighting,
+ * including rendering, cleaning...
+ * No need to instantiate repeatly. A Highlighter instance will bind a Painter instance.
+ */
+
+import type HighlightRange from '@src/model/range';
+import type { PainterOptions, HookMap } from '@src/types';
+import HighlightSource from '@src/model/source';
+import { wrapHighlight, getSelectedNodes, normalizeSiblingText } from '@src/painter/dom';
+import { getHighlightsByRoot, forEach, addClass, removeAllClass } from '@src/util/dom';
+import { ERROR } from '@src/types';
+import { initDefaultStylesheet } from '@src/painter/style';
+import {
+    ID_DIVISION,
+    eventEmitter,
+    DATASET_IDENTIFIER,
+    INTERNAL_ERROR_EVENT,
+    CAMEL_DATASET_IDENTIFIER,
+    CAMEL_DATASET_IDENTIFIER_EXTRA,
+} from '@src/util/const';
+
+export default class Painter {
+    options: PainterOptions;
+
+    $style: HTMLStyleElement;
+
+    styleId: string;
+
+    hooks: HookMap;
+
+    constructor(options: PainterOptions, hooks: HookMap) {
+        this.options = {
+            $root: options.$root,
+            wrapTag: options.wrapTag,
+            exceptSelectors: options.exceptSelectors,
+            className: options.className,
+        };
+        this.hooks = hooks;
+
+        initDefaultStylesheet();
+    }
+
+    /* =========================== render =========================== */
+    highlightRange(range: HighlightRange): HTMLElement[] {
+        if (!range.frozen) {
+            throw ERROR.HIGHLIGHT_RANGE_FROZEN;
+        }
+
+        const { $root, className, exceptSelectors } = this.options;
+        const hooks = this.hooks;
+
+        let $selectedNodes = getSelectedNodes($root, range.start, range.end, exceptSelectors);
+
+        if (!hooks.Render.SelectedNodes.isEmpty()) {
+            $selectedNodes = hooks.Render.SelectedNodes.call(range.id, $selectedNodes) || [];
+        }
+
+        return $selectedNodes.map(n => {
+            let $node = wrapHighlight(n, range, className, this.options.wrapTag);
+
+            if (!hooks.Render.WrapNode.isEmpty()) {
+                $node = hooks.Render.WrapNode.call(range.id, $node);
+            }
+
+            return $node;
+        });
+    }
+
+    highlightSource(sources: HighlightSource | HighlightSource[]): HighlightSource[] {
+        const list = Array.isArray(sources) ? sources : [sources];
+
+        const renderedSources: HighlightSource[] = [];
+
+        list.forEach(s => {
+            if (!(s instanceof HighlightSource)) {
+                eventEmitter.emit(INTERNAL_ERROR_EVENT, {
+                    type: ERROR.SOURCE_TYPE_ERROR,
+                });
+
+                return;
+            }
+
+            const range = s.deSerialize(this.options.$root, this.hooks);
+            const $nodes = this.highlightRange(range);
+
+            if ($nodes.length > 0) {
+                renderedSources.push(s);
+            } else {
+                eventEmitter.emit(INTERNAL_ERROR_EVENT, {
+                    type: ERROR.HIGHLIGHT_SOURCE_NONE_RENDER,
+                    detail: s,
+                });
+            }
+        });
+
+        return renderedSources;
+    }
+    /* ============================================================== */
+
+    /* =========================== clean =========================== */
+    // id: target id - highlight with this id should be clean
+    // if there is no highlight for this id, it will return false, vice versa
+    removeHighlight(id: string): boolean {
+        // whether extra ids contains the target id
+        const reg = new RegExp(`(${id}\\${ID_DIVISION}|\\${ID_DIVISION}?${id}$)`);
+
+        const hooks = this.hooks;
+        const wrapTag = this.options.wrapTag;
+        const $spans = document.querySelectorAll<HTMLElement>(`${wrapTag}[data-${DATASET_IDENTIFIER}]`);
+
+        // nodes to remove
+        const $toRemove: HTMLElement[] = [];
+        // nodes to update main id
+        const $idToUpdate: HTMLElement[] = [];
+        // nodes to update extra id
+        const $extraToUpdate: HTMLElement[] = [];
+
+        for (const $s of $spans) {
+            const spanId = $s.dataset[CAMEL_DATASET_IDENTIFIER];
+            const spanExtraIds = $s.dataset[CAMEL_DATASET_IDENTIFIER_EXTRA];
+
+            // main id is the target id and no extra ids --> to remove
+            if (spanId === id && !spanExtraIds) {
+                $toRemove.push($s);
+            }
+            // main id is the target id but there is some extra ids -> update main id & extra id
+            else if (spanId === id) {
+                $idToUpdate.push($s);
+            }
+            // main id isn't the target id but extra ids contains it -> just remove it from extra id
+            else if (spanId !== id && reg.test(spanExtraIds)) {
+                $extraToUpdate.push($s);
+            }
+        }
+
+        $toRemove.forEach($s => {
+            const $parent = $s.parentNode;
+            const $fr = document.createDocumentFragment();
+
+            forEach($s.childNodes, ($c: Node) => $fr.appendChild($c.cloneNode(false)));
+
+            const $prev = $s.previousSibling;
+            const $next = $s.nextSibling;
+
+            $parent.replaceChild($fr, $s);
+            // there are bugs in IE11, so use a more reliable function
+            normalizeSiblingText($prev, true);
+            normalizeSiblingText($next, false);
+            hooks.Remove.UpdateNodes.call(id, $s, 'remove');
+        });
+
+        $idToUpdate.forEach($s => {
+            const dataset = $s.dataset;
+            const ids = dataset[CAMEL_DATASET_IDENTIFIER_EXTRA].split(ID_DIVISION);
+            const newId = ids.shift();
+
+            // find overlapped wrapper associated with "extra id"
+            const $overlapSpan = document.querySelector<HTMLElement>(
+                `${wrapTag}[data-${DATASET_IDENTIFIER}="${newId}"]`,
+            );
+
+            if ($overlapSpan) {
+                // empty the current class list
+                removeAllClass($s);
+                // retain the class list of the overlapped wrapper which associated with "extra id"
+                addClass($s, [...$overlapSpan.classList]);
+            }
+
+            dataset[CAMEL_DATASET_IDENTIFIER] = newId;
+            dataset[CAMEL_DATASET_IDENTIFIER_EXTRA] = ids.join(ID_DIVISION);
+
+            hooks.Remove.UpdateNodes.call(id, $s, 'id-update');
+        });
+
+        $extraToUpdate.forEach($s => {
+            const extraIds = $s.dataset[CAMEL_DATASET_IDENTIFIER_EXTRA];
+
+            $s.dataset[CAMEL_DATASET_IDENTIFIER_EXTRA] = extraIds.replace(reg, '');
+            hooks.Remove.UpdateNodes.call(id, $s, 'extra-update');
+        });
+
+        return $toRemove.length + $idToUpdate.length + $extraToUpdate.length !== 0;
+    }
+
+    removeAllHighlight() {
+        const { wrapTag, $root } = this.options;
+        const $spans = getHighlightsByRoot($root, wrapTag);
+
+        $spans.forEach($s => {
+            const $parent = $s.parentNode;
+            const $fr = document.createDocumentFragment();
+
+            forEach($s.childNodes, ($c: Node) => $fr.appendChild($c.cloneNode(false)));
+            $parent.replaceChild($fr, $s);
+        });
+    }
+    /* ============================================================== */
+}

package/src/painter/style.ts

@@ -0,0 +1,21 @@
+/**
+ * inject styles
+ */
+import { STYLESHEET_ID, getStylesheet } from '@src/util/const';
+
+export const initDefaultStylesheet = () => {
+    const styleId = STYLESHEET_ID;
+
+    let $style: HTMLStyleElement = document.getElementById(styleId) as HTMLStyleElement;
+
+    if (!$style) {
+        const $cssNode = document.createTextNode(getStylesheet());
+
+        $style = document.createElement('style');
+        $style.id = styleId;
+        $style.appendChild($cssNode);
+        document.head.appendChild($style);
+    }
+
+    return $style;
+};

package/src/types/index.ts

@@ -0,0 +1,118 @@
+import type Hook from '@src/util/hook';
+
+export type RootElement = Document | HTMLElement;
+
+export interface HighlighterOptions {
+    $root?: RootElement;
+    exceptSelectors?: string[];
+    wrapTag?: string;
+    verbose?: boolean;
+    style?: {
+        className?: string[] | string;
+    };
+}
+
+export interface PainterOptions {
+    $root: RootElement;
+    wrapTag: string;
+    className: string[] | string;
+    exceptSelectors: string[];
+}
+
+export enum SplitType {
+    none = 'none',
+    head = 'head',
+    tail = 'tail',
+    both = 'both',
+}
+
+export enum ERROR {
+    DOM_TYPE_ERROR = '[DOM] Receive wrong node type.',
+    DOM_SELECTION_EMPTY = '[DOM] The selection contains no dom node, may be you except them.',
+    RANGE_INVALID = "[RANGE] Got invalid dom range, can't convert to a valid highlight range.",
+    RANGE_NODE_INVALID = "[RANGE] Start or end node isn't a text node, it may occur an error.",
+    DB_ID_DUPLICATE_ERROR = '[STORE] Unique id conflict.',
+    CACHE_SET_ERROR = "[CACHE] Cache.data can't be set manually, please use .save().",
+    SOURCE_TYPE_ERROR = "[SOURCE] Object isn't a highlight source instance.",
+    HIGHLIGHT_RANGE_FROZEN = '[HIGHLIGHT_RANGE] A highlight range must be frozen before render.',
+    HIGHLIGHT_SOURCE_RECREATE = '[HIGHLIGHT_SOURCE] Recreate highlights from sources error.',
+    // eslint-disable-next-line max-len
+    HIGHLIGHT_SOURCE_NONE_RENDER = "[HIGHLIGHT_SOURCE] This highlight source isn't rendered. May be the exception skips it or the dom structure has changed.",
+}
+
+export enum EventType {
+    CREATE = 'selection:create',
+    REMOVE = 'selection:remove',
+    MODIFY = 'selection:modify',
+    HOVER = 'selection:hover',
+    HOVER_OUT = 'selection:hover-out',
+    CLICK = 'selection:click',
+}
+
+export enum CreateFrom {
+    STORE = 'from-store',
+    INPUT = 'from-input',
+}
+
+export enum SelectedNodeType {
+    text = 'text',
+    span = 'span',
+}
+
+export interface SelectedNode {
+    $node: Node | Text;
+    type: SelectedNodeType;
+    splitType: SplitType;
+}
+
+export interface DomMeta {
+    parentTagName: string;
+    parentIndex: number;
+    textOffset: number;
+    extra?: unknown;
+}
+
+export interface DomNode {
+    $node: Node;
+    offset: number;
+}
+
+export interface HighlightPosition {
+    start: {
+        top: number;
+        left: number;
+    };
+    end: {
+        top: number;
+        left: number;
+    };
+}
+
+export interface HookMap {
+    Render: {
+        UUID: Hook<string>;
+        SelectedNodes: Hook<SelectedNode[]>;
+        WrapNode: Hook<HTMLElement>;
+    };
+    Serialize: {
+        Restore: Hook<DomNode[]>;
+        RecordInfo: Hook<string>;
+    };
+    Remove: {
+        UpdateNodes: Hook;
+    };
+}
+
+export enum UserInputEvent {
+    touchend = 'touchend',
+    mouseup = 'mouseup',
+    touchstart = 'touchstart',
+    click = 'click',
+    mouseover = 'mouseover',
+}
+
+export interface IInteraction {
+    PointerEnd: UserInputEvent;
+    PointerTap: UserInputEvent;
+    PointerOver: UserInputEvent;
+}

package/src/util/camel.ts

@@ -0,0 +1,6 @@
+/**
+ * convert dash-joined string to camel case
+ */
+
+export default (a: string): string =>
+    a.split('-').reduce((str, s, idx) => str + (idx === 0 ? s : s[0].toUpperCase() + s.slice(1)), '');