Merge pull request #44 from alienzhou/feat/deserialize-hook

Feat/deserialize hook

Author: alienzhou

README.md

@@ -266,6 +266,10 @@ If the `id` is not passed, it will return all the areas' wrap nodes.
 
 If you have a wrap node, it can return the unique highlight id for you.
 
+#### `highlighter.getExtraIdByDom(node)`
+
+If you have a wrap node, it can return the extra unique highlight id for you.
+
 ### 4. Event Listener
 
 web-highlighter use listeners to handle the events.

README.zh_CN.md

@@ -261,7 +261,11 @@ if (selection.isCollapsed) {
 
 ####  6.3.11. <a name='highlighter.getIdByDomnode'></a>`highlighter.getIdByDom(node)`
 
-传入一个包裹节点，返回该节点对应的高亮区域去的唯一 ID。
+传入一个包裹节点，返回该节点对应的高亮区域的唯一 ID。
+
+####  6.3.11. <a name='highlighter.getExtraIdByDomnode'></a>`highlighter.getExtraIdByDom(node)`
+
+传入一个包裹节点，返回该节点对应的高亮区域的额外 ID。
 
 ###  6.4. <a name='EventListener'></a>`Event Listener`
 

docs/ADVANCE.md

@@ -34,7 +34,7 @@ highlighter.hooks.Render.UUID.tap(function (start, end, text) {
 
 Hook into the process of generating a unique id.
 
-**arguements:**
+**arguments:**
 
 - start: DOM info of the start node
 - end: DOM info of the end node
@@ -48,7 +48,7 @@ Hook into the process of generating a unique id.
 
 Process all the text nodes in the highlighted area and return a new list by using this hook.
 
-**arguements:**
+**arguments:**
 
 - id: id of the highlighted area
 - selectedNodes: all the text nodes in the highlighted area
@@ -61,7 +61,7 @@ Process all the text nodes in the highlighted area and return a new list by usin
 
 Process the wrapping elements.
 
-**arguements:**
+**arguments:**
 
 - id: id of the highlighted area
 - node: the wrapping elements
@@ -70,11 +70,23 @@ Process the wrapping elements.
 
 - the wrapping elements
 
+### `Serialize.Restore`
+
+Customize your own restoring method. When you tap this hook, the `HighlightSource` instance will use the function you pass to calculate the start and end nodes' info.
+
+**arguments:**
+
+- hs: the current `HighlightSource` instance
+
+**return value needed:**
+
+- an array: the first element is the start info and the second is the end
+
 ### `Serialize.RecordInfo`
 
 Add or modify some extra info when serialize the `HighlightRange` object.
 
-**arguements:**
+**arguments:**
 
 - start: meta info of the start node
 - end: meta info of the end node
@@ -88,7 +100,7 @@ Add or modify some extra info when serialize the `HighlightRange` object.
 
 Process the affected wrapping elements when remove highlighted areas.
 
-**arguements:**
+**arguments:**
 
 - id: id of the highlighted area
 - nodes: the affected wrapping elements

docs/ADVANCE.zh_CN.md

@@ -70,6 +70,18 @@ highlighter.hooks.Render.UUID.tap(function (start, end, text) {
 
 - 高亮包裹的节点
 
+### `Serialize.Restore`
+
+自定义你的还原（反序列化）方法。当你使用这个钩子时，`HighlightSource` 实例会调用你注册的方法来计算高亮选区的首尾节点信息。
+
+**参数:**
+
+- hs: 当前的 `HighlightSource` 实例
+
+**所需的返回值:**
+
+- 一个数组对象: 数组的第一个元素是选区开始的节点信息，第二个元素是结束的节点信息
+
 ### `Serialize.RecordInfo`
 
 为选区序列化时的持久化数据生成额外信息

docs/img/create-flow.jpg

@@ -86,15 +86,25 @@ highlighter
  * attach hooks
  */
 highlighter.hooks.Render.SelectedNodes.tap(
-    (id, selectedNodes)  => selectedNodes.filter(n => n.$node.textContent)
+    (id, selectedNodes) => selectedNodes.filter(n => n.$node.textContent)
 );
 
+highlighter.hooks.Serialize.Restore.tap(
+    source =>  log('Serialize.Restore hook -', source)
+);
+
+highlighter.hooks.Serialize.RecordInfo.tap(() => {
+    const extraInfo = Math.random().toFixed(4);
+    log('Serialize.RecordInfo hook -', extraInfo)
+    return extraInfo;
+});
+
 /**
  * retrieve from local store
  */
 const storeInfos =  store.getAll();
 storeInfos.forEach(
-    ({hs}) => highlighter.fromStore(hs.startMeta, hs.endMeta, hs.text, hs.id)
+    ({hs}) => highlighter.fromStore(hs.startMeta, hs.endMeta, hs.text, hs.id, hs.extra)
 );
 
 let autoStatus;

docs/img/create-flow.zh_CN.jpg

@@ -47,21 +47,6 @@ class LocalStore {
         this.jsonToStore(stores);
     }
 
-    get(id) {
-        const list = this.storeToJson()
-            .filter(store => store.hs.id === id)
-            .map(store => ({
-                hs: new HighlightSource(
-                    store.hs.startMeta,
-                    store.hs.endMeta,
-                    store.hs.text,
-                    store.hs.id
-                ),
-                info: store.info
-            }));
-        return list[0];
-    }
-
     remove(id) {
         const stores = this.storeToJson();
         let index = null;

docs/img/remove-flow.jpg

@@ -1,6 +1,6 @@
 {
   "name": "web-highlighter",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "✨A no-runtime dependency lib for text highlighting & persistence on any website ✨🖍️",
   "main": "dist/web-highlighter.min.js",
   "browser": "dist/web-highlighter.min.js",
@@ -17,6 +17,11 @@
     "build": "export target=dist && node script/build.js",
     "prepublishOnly": "npm run build"
   },
+  "husky": {
+    "hooks": {
+      "pre-commit": "npm run test"
+    }
+  },
   "homepage": "https://alienzhou.github.io/web-highlighter",
   "repository": {
     "type": "git",
@@ -49,6 +54,7 @@
     "fs-extra": "^7.0.1",
     "html-webpack-plugin": "^3.2.0",
     "http-server": "^0.11.1",
+    "husky": "^4.2.5",
     "jsdom": "^16.2.2",
     "jsdom-global": "^3.0.2",
     "mocha": "^7.1.2",

docs/img/remove-flow.zh_CN.jpg

@@ -26,6 +26,7 @@ import {
     removeClass,
     isHighlightWrapNode,
     getHighlightById,
+    getExtraHighlightId,
     getHighlightsByRoot,
     getHighlightId,
     addEventListener,
@@ -65,6 +66,7 @@ export default class Highlighter extends EventEmitter {
             WrapNode: new Hook('Render.WrapNode')
         },
         Serialize: {
+            Restore: new Hook('Serialize.Restore'),
             RecordInfo: new Hook('Serialize.RecordInfo')
         },
         Remove: {
@@ -143,6 +145,7 @@ export default class Highlighter extends EventEmitter {
     removeClass = (className: string, id?: string) => this.getDoms(id).forEach($n => removeClass($n, className));
 
     getIdByDom = ($node: HTMLElement): string => getHighlightId($node);
+    getExtraIdByDom = ($node: HTMLElement): string[] => getExtraHighlightId($node);
     getDoms = (id?: string): Array<HTMLElement> => id
         ? getHighlightById(this.options.$root, id, this.options.wrapTag)
         : getHighlightsByRoot(this.options.$root, this.options.wrapTag);
@@ -191,9 +194,9 @@ export default class Highlighter extends EventEmitter {
         return this._highlightFromHRange(hRange);
     }
 
-    fromStore = (start: DomMeta, end: DomMeta, text, id): HighlightSource => {
+    fromStore = (start: DomMeta, end: DomMeta, text: string, id: string, extra?: unknown): HighlightSource => {
         try {
-            const hs = new HighlightSource(start, end, text, id);
+            const hs = new HighlightSource(start, end, text, id, extra);
             this._highlightFromHSource(hs);
             return hs;
         }

example/index.js

@@ -4,7 +4,7 @@
  * Also it has the ability for persistence.
  */
 
-import {DomMeta} from '../../types';
+import {DomMeta, HookMap, DomNode} from '../../types';
 import HighlightRange from '../range/index';
 import {queryElementNode, getTextChildByOffset} from './dom';
 
@@ -13,15 +13,15 @@ class HighlightSource {
     endMeta: DomMeta;
     text: string;
     id: string;
-    extra?: any;
-    __isHighlightSource: any;
+    extra?: unknown;
+    __isHighlightSource: unknown;
 
     constructor(
         startMeta: DomMeta,
         endMeta: DomMeta,
         text: string,
         id: string,
-        extra?: any
+        extra?: unknown
     ) {
         this.startMeta = startMeta;
         this.endMeta = endMeta;
@@ -33,10 +33,16 @@ class HighlightSource {
         }
     }
 
-    deSerialize($root: HTMLElement | Document): HighlightRange {
+    deSerialize($root: HTMLElement | Document, hooks: HookMap): HighlightRange {
         const {start, end} = queryElementNode(this, $root);
-        const startInfo = getTextChildByOffset(start, this.startMeta.textOffset);
-        const endInfo = getTextChildByOffset(end, this.endMeta.textOffset);
+        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,

example/local.store.js

@@ -73,7 +73,7 @@ export default class Painter {
                 });
                 return;
             }
-            const range = s.deSerialize(this.options.$root);
+            const range = s.deSerialize(this.options.$root, this.hooks);
             const $nodes = this.highlightRange(range);
             if ($nodes.length > 0) {
                 renderedSources.push(s);

package.json

@@ -69,7 +69,7 @@ export interface DomMeta {
     parentTagName: string;
     parentIndex: number;
     textOffset: number;
-    extra?: any;
+    extra?: unknown;
 }
 
 export interface DomNode {
@@ -95,6 +95,7 @@ export type HookMap = {
         WrapNode: Hook;
     };
     Serialize: {
+        Restore: Hook;
         RecordInfo: Hook;
     };
     Remove: {

src/index.ts

@@ -27,6 +27,17 @@ export const getHighlightId = ($node: HTMLElement): string => {
     return '';
 };
 
+/**
+ * get extra highlight id by wrapping node
+ */
+export const getExtraHighlightId = ($node: HTMLElement): string[] => {
+    if (isHighlightWrapNode($node)) {
+        const extraId = $node.dataset[CAMEL_DATASET_IDENTIFIER_EXTRA];
+        return extraId.split(ID_DIVISION).filter(i => i);
+    }
+    return [];
+};
+
 /**
  * get all highlight wrapping nodes nodes from a root node
  */

src/model/source/index.ts

@@ -3,7 +3,7 @@
  * modify from mitt
 */
 
-type EventHandler = (event?: any) => void;
+type EventHandler = (event?: unknown) => void;
 type EventHandlerList = Array<EventHandler>;
 type HandlersMap = {[propName: string]: EventHandlerList};
 

src/painter/index.ts

@@ -11,9 +11,19 @@ class Hook {
         this.name = name;
     }
 
-    tap(cb: Function) {
-        this.ops.push(cb);
-        return this;
+    tap(cb: Function): Function {
+        if (this.ops.indexOf(cb) < 0) {
+            this.ops.push(cb);
+        }
+        return () => this.remove(cb);
+    }
+
+    remove(cb: Function): void {
+        const idx = this.ops.indexOf(cb);
+        if (idx < 0) {
+            return;
+        }
+        this.ops.splice(idx, 1);
     }
 
     isEmpty(): boolean {

src/types/index.ts

@@ -412,6 +412,29 @@ describe('Highlighter API', function () {
         });
     });
 
+    describe('#getExtraIdByDom', () => {
+        beforeEach(() => {
+            highlighter.removeAll();
+            sources.forEach(s => highlighter.fromStore(s.startMeta, s.endMeta, s.text, s.id));
+        });
+
+        it('should return the correct id', () => {
+            const id = sources[0].id;
+            const dom = highlighter.getDoms(id)[2];
+            const ids = highlighter.getExtraIdByDom(dom);
+            expect(ids.sort()).to.deep.equal([sources[0].id, sources[1].id].sort());
+        });
+
+        it('should return empty array when there is no extra id', () => {
+            const dom = highlighter.getDoms(sources[0].id)[0];
+            expect(highlighter.getExtraIdByDom(dom)).to.deep.equal([]);
+        });
+
+        it('should return empty array when the dom is not a wrapper', () => {
+            expect(highlighter.getExtraIdByDom(document.querySelector('img'))).to.deep.equal([]);
+        });
+    });
+
     afterEach(() => {
         cleanup();
     });