prepared for releasing v2.2.0

angezid · Sep 12, 2023 · 9140474 · 9140474
1 parent 43d0a89
commit 9140474
Show file tree

Hide file tree

Showing 32 changed files with 378 additions and 188 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,7 @@
 * Added ability to mark line ranges (`markRanges()` API with `markLines` option).
 * Fixed handling `br` element in `getTextNodesAcross()` method.
 * Fixed negative value of the start index in `wrapRangeAcross()` method with `wrapAllRanges` option, which can occur in some cases.
-* Improvement that allows usage of RegExp conditional capturing groups with  `ignoreGroups` and `acrossElements` options in `markRegExp()` API.
+* An improvement that allows usage of RegExp conditional capturing groups with  `ignoreGroups` option in `markRegExp()` API.
 
 ### 2.1.2
 
@@ -18,7 +18,7 @@
 
 ### 2.1.0
 
-* Fixed bug related using a wildcards character `*` with `wildcards : 'withSpaces'`, `acrossElements` , and `blockElementBoundary` options.
+* Fixed bug related using a wildcards character `*` with `wildcards : 'withSpaces'`, `acrossElements` , and `blockElementsBoundary` options.
 * Added supports for virtual DOM environments such as JSDOM. Thanks to [Tyler Nickerson](https://github.com/Nickersoft) for the contribution.
 
 ### 2.0.0
@@ -37,7 +37,7 @@
 
 ### 1.1.2
 
-* Fixed bug related using a wildcards character `*` with `wildcards : 'withSpaces'`, `acrossElements` , and `blockElementBoundary` options.
+* Fixed bug related using a wildcards character `*` with `wildcards : 'withSpaces'`, `acrossElements` , and `blockElementsBoundary` options.
 * Fixed types path in package.json.
 
 ### 1.1.1

diff --git a/README.md b/README.md
@@ -2,25 +2,41 @@
 
 [![npm](https://img.shields.io/npm/v/advanced-mark.js)](https://www.npmjs.com/package/advanced-mark.js)
 
-#### Highlight words, terms, or text on a browser page using JavaScript.
+### A fast JavaScript library to highlight words, terms, or text on a browser page. It also supports virtual DOMs.
 
-This library from v2.0.0 doesn't guaranty backward compatibility with `mark.js` v9.0.0 and npm package v8.11.1.
+This library from v2.0.0 doesn't guaranty backward compatibility with *mark.js* v9.0.0 and npm package v8.11.1.
+
+What is done:
+* rewritten across elements pipeline for performance reason and additional features
+* rewritten domiterator class to handle iframes and shadow DOMs
+* `filter`, `each`, and `done` callbacks additional parameters expose useful data that can 'deprive' you from 'happy hacking'
+
+Added options:
+* `combinePatterns` - boosts performance of `mark()` method when highlighting an array of terms
+* `cacheTextNodes` - improves performance of `mark()` method when highlighting an array of terms
+* `separateGroups` - allows highlighting RegExp capturing groups instead of the whole match
+* `wrapAllRanges` - allows highlighting nesting/overlapping ranges and RegExp capturing groups
+* `markLines` - allows highlighting ranges of lines
+* `blockElementsBoundary` - limits matches within HTML block elements
+* `shadowDOM` - allows highlighting inside shadow DOM
+
+And a lot of other fixings, improvements ...
 
 [Playground](https://angezid.github.io/advanced-mark.js/playground) and
 [Documentation](https://angezid.github.io/advanced-mark.js/doc-v2) for `advanced-mark.js` v2.
 
-Also may be useful to read [Documentation](https://markjs.io/). Note that this doc is for old `mark.js`.
+Also may be useful to read [Documentation](https://markjs.io/). Note that this doc is for old *mark.js*.
 
 ## Modules changes
-* \*. es6.\*.js now are real ES6 modules. They are actually UMD modules in `mark.js` v9.0.0 and npm package v8.11.1.
+* \*. es6.\*.js now are real ES6 modules. They are actually UMD modules in *mark.js*.
 
 ``` js
 import Mark from './mark.es6.js';
 // import Mark from './jquery.mark.es6.js';
 ```
 
-Added `node.jquery.mark.es6.js` module, which is intended to use on Node.js and contains necessary `import $ from 'jquery';` declaration.  
-The modules `jquery.mark.es6.js` and `jquery.mark.es6. min.js` can be used directly in browsers (global $).
+Added `node.jquery.mark.es6.js` module, which is intended to use on Node.js and contains necessary `import $ from 'jquery'` declaration.  
+The modules `jquery.mark.es6.js` and `jquery.mark.es6. min.js` can be used directly in browsers (global $ or import $).
 
 ## Virtual DOMs
 See [JSDOM test](jsdom-tests/test.js).
diff --git a/dist/jquery.mark.es6.js b/dist/jquery.mark.es6.js
@@ -1088,12 +1088,14 @@ class Mark {
         while ((match = regex.exec(node.textContent)) !== null && (str = match[index]) !== '') {
           filterInfo.match = match;
           filterInfo.offset = info.start;
-          if ( !filterCb(node, str, filterInfo)) {
+          if ( !filterCb(node, str, filterInfo) || !str) {
             continue;
           }
           let i = 0, start = match.index;
           while (++i < index) {
-            start += match[i].length;
+            if (match[i]) {
+              start += match[i].length;
+            }
           }
           const end = start + str.length;
           if (this.opt.cacheTextNodes) {
@@ -1138,14 +1140,13 @@ class Mark {
         filterInfo.match = match;
         matchStart = true;
         let i = 0,
-          start = match.index,
-          len = str ? str.length : 0;
+          start = match.index;
         while (++i < index) {
           if (match[i]) {
             start += match[i].length;
           }
         }
-        this.wrapRangeAcross(dict, start, start + len, obj => {
+        this.wrapRangeAcross(dict, start, start + (str ? str.length : 0), obj => {
           filterInfo.matchStart = matchStart;
           filterInfo.offset = obj.startOffset;
           matchStart = false;

diff --git a/dist/jquery.mark.es6.min.js b/dist/jquery.mark.es6.min.js
diff --git a/dist/jquery.mark.js b/dist/jquery.mark.js
@@ -1448,13 +1448,15 @@
             while ((match = regex.exec(node.textContent)) !== null && (str = match[index]) !== '') {
               filterInfo.match = match;
               filterInfo.offset = info.start;
-              if (!filterCb(node, str, filterInfo)) {
+              if (!filterCb(node, str, filterInfo) || !str) {
                 continue;
               }
               var i = 0,
                 start = match.index;
               while (++i < index) {
-                start += match[i].length;
+                if (match[i]) {
+                  start += match[i].length;
+                }
               }
               var end = start + str.length;
               if (_this9.opt.cacheTextNodes) {
@@ -1509,14 +1511,13 @@
             filterInfo.match = match;
             matchStart = true;
             var i = 0,
-              start = match.index,
-              len = str ? str.length : 0;
+              start = match.index;
             while (++i < index) {
               if (match[i]) {
                 start += match[i].length;
               }
             }
-            _this10.wrapRangeAcross(dict, start, start + len, function (obj) {
+            _this10.wrapRangeAcross(dict, start, start + (str ? str.length : 0), function (obj) {
               filterInfo.matchStart = matchStart;
               filterInfo.offset = obj.startOffset;
               matchStart = false;

diff --git a/dist/jquery.mark.min.js b/dist/jquery.mark.min.js
diff --git a/dist/mark.es6.js b/dist/mark.es6.js
@@ -1088,12 +1088,14 @@ class Mark$1 {
         while ((match = regex.exec(node.textContent)) !== null && (str = match[index]) !== '') {
           filterInfo.match = match;
           filterInfo.offset = info.start;
-          if ( !filterCb(node, str, filterInfo)) {
+          if ( !filterCb(node, str, filterInfo) || !str) {
             continue;
           }
           let i = 0, start = match.index;
           while (++i < index) {
-            start += match[i].length;
+            if (match[i]) {
+              start += match[i].length;
+            }
           }
           const end = start + str.length;
           if (this.opt.cacheTextNodes) {
@@ -1138,14 +1140,13 @@ class Mark$1 {
         filterInfo.match = match;
         matchStart = true;
         let i = 0,
-          start = match.index,
-          len = str ? str.length : 0;
+          start = match.index;
         while (++i < index) {
           if (match[i]) {
             start += match[i].length;
           }
         }
-        this.wrapRangeAcross(dict, start, start + len, obj => {
+        this.wrapRangeAcross(dict, start, start + (str ? str.length : 0), obj => {
           filterInfo.matchStart = matchStart;
           filterInfo.offset = obj.startOffset;
           matchStart = false;

diff --git a/dist/mark.es6.min.js b/dist/mark.es6.min.js
diff --git a/dist/mark.js b/dist/mark.js
@@ -1444,13 +1444,15 @@
             while ((match = regex.exec(node.textContent)) !== null && (str = match[index]) !== '') {
               filterInfo.match = match;
               filterInfo.offset = info.start;
-              if (!filterCb(node, str, filterInfo)) {
+              if (!filterCb(node, str, filterInfo) || !str) {
                 continue;
               }
               var i = 0,
                 start = match.index;
               while (++i < index) {
-                start += match[i].length;
+                if (match[i]) {
+                  start += match[i].length;
+                }
               }
               var end = start + str.length;
               if (_this9.opt.cacheTextNodes) {
@@ -1505,14 +1507,13 @@
             filterInfo.match = match;
             matchStart = true;
             var i = 0,
-              start = match.index,
-              len = str ? str.length : 0;
+              start = match.index;
             while (++i < index) {
               if (match[i]) {
                 start += match[i].length;
               }
             }
-            _this10.wrapRangeAcross(dict, start, start + len, function (obj) {
+            _this10.wrapRangeAcross(dict, start, start + (str ? str.length : 0), function (obj) {
               filterInfo.matchStart = matchStart;
               filterInfo.offset = obj.startOffset;
               matchStart = false;

diff --git a/dist/mark.min.js b/dist/mark.min.js
diff --git a/dist/node.jquery.mark.es6.js b/dist/node.jquery.mark.es6.js
@@ -1089,12 +1089,14 @@ class Mark {
         while ((match = regex.exec(node.textContent)) !== null && (str = match[index]) !== '') {
           filterInfo.match = match;
           filterInfo.offset = info.start;
-          if ( !filterCb(node, str, filterInfo)) {
+          if ( !filterCb(node, str, filterInfo) || !str) {
             continue;
           }
           let i = 0, start = match.index;
           while (++i < index) {
-            start += match[i].length;
+            if (match[i]) {
+              start += match[i].length;
+            }
           }
           const end = start + str.length;
           if (this.opt.cacheTextNodes) {
@@ -1139,14 +1141,13 @@ class Mark {
         filterInfo.match = match;
         matchStart = true;
         let i = 0,
-          start = match.index,
-          len = str ? str.length : 0;
+          start = match.index;
         while (++i < index) {
           if (match[i]) {
             start += match[i].length;
           }
         }
-        this.wrapRangeAcross(dict, start, start + len, obj => {
+        this.wrapRangeAcross(dict, start, start + (str ? str.length : 0), obj => {
           filterInfo.matchStart = matchStart;
           filterInfo.offset = obj.startOffset;
           matchStart = false;

diff --git a/doc/TypeScript-types.md b/doc/TypeScript-types.md
@@ -1,40 +1,29 @@
 
 ## TypeScript types
 
-**See [Documentation](https://angezid.github.io/advanced-mark.js/doc-v1) for advanced-mark.js v1 on GitHub Pages.**
-
-
 The following TypeScript declaration files are added to `dist` folder:  
-jquery.mark.d.ts  
-jquery.mark.es6.d.ts  
-jquery.mark.umd.d.ts  
-mark.d.ts  
-mark.es6.d.ts  
-mark.umd.d.ts  
-regexpcreator.d.ts  
-regexpcreator.es6.d.ts  
-regexpcreator.umd.d.ts  
+* mark.d.ts  
+* mark.es6.d.ts  
+* jquery.mark.d.ts  
+* jquery.mark.es6.d.ts  
+* regexpcreator.d.ts  
+* regexpcreator.es6.d.ts
 
-### Simple example
-``` js
-import Mark from 'advanced-mark.js/dist/mark.js';
-
-new Mark(document.querySelector("article")).mark(['lorem','ipsum'], {});
-```
+**Note:** the default imported library is ES6 module -`mark.es6.js`, to import others you need to specify the full path,  
+e.g. `import 'advanced-mark.js/dist/jquery.mark.js';`.
 
-### jQuery example 
+#### JavaScript example
 ``` js
-import "jquery/dist/jquery.js";
-import Mark from 'advanced-mark.js/dist/jquery.mark.js';
+// imported 'mark.es6.js' library
+import Mark from 'advanced-mark.js';
 
-$("article").mark(['lorem','ipsum'], {});
+new Mark(document.querySelector("article")).mark('lorem ipsum', {});
 ```
 
-### RegExpCreator example
+#### jQuery example 
 ``` js
-import regCreator from 'advanced-mark.js/dist/regexpcreator.js';
+import $ from 'jquery';
+import 'advanced-mark.js/dist/jquery.mark.js';
 
-console.log('Using create method ', new regCreator().create('lorem', true));
-console.log('Using createDiacritics method ', new regCreator().createDiacritics('lorem'));
-console.log('Using createCombinePattern method ', new regCreator().createCombinePattern(['lorem', 'ipsum'], true));
+$("article").mark('lorem ipsum', {});
 ```
diff --git a/doc/elements-boundaries.md b/doc/elements-boundaries.md
@@ -20,7 +20,7 @@ If the custom `tagNames` are defined:
 * they can be the only elements that have boundaries
 * they can be added to the default block elements
 
-The `blockElementsBoundary` option makes sense only when highlighting phrases or RegExp separate groups.
+The `blockElementsBoundary` option makes sense only when highlighting phrases or RegExp separate groups, or using a wildcards character `*` with `wildcards : 'withSpaces'` option.
 
 * `blockElementsBoundary` {boolean|object} - Option: (default is `undefined`)
   * `tagNames` {string[]} - The string or array of tag name. (default is `undefined`)

diff --git a/doc/mark-method.md b/doc/mark-method.md
@@ -4,7 +4,6 @@
 **See [Documentation](https://angezid.github.io/advanced-mark.js/doc-v1) for advanced-mark.js v1 on GitHub Pages.**
 
 
-
 ### Syntax
 ``` js
 // javascript
@@ -31,27 +30,32 @@ $(context).mark(search[, options]);
       * `value`: 'exactly' or 'complementary'
       * `limiters`: an array of custom word boundary characters, e.g. `{ value : "exactly", limiters : ",.;:?!'\"".split() }`
 
-  * `wildcards` {string} - Two characters `?` and `*` used as wildcards (default is `disabled`):
+  * `wildcards` {string} - Two characters `?` and `*` used as wildcards unless thay are escaped (default is `disabled`):
     * `disabled`: The characters `?` and `*` match itself
     * `enabled`:
       * The character `?` match any non-white-space character zero or one time.
       * The character `*` match any non-white-space character zero or more time.
     * `withSpaces`:
       * The character `?` match any character zero or one time.
       * The character `*` match any character zero or more time, but as few times as possible.
-        
+
   * `ignoreJoiners` {boolean} - Whether to find matches that contain soft hyphen, zero width space, zero width non-joiner and zero width joiner (default is `false`)
   * `ignorePunctuation` {string[]} - An array of punctuation characters (default is `[]`)
   * `synonyms` {object} - An object with synonyms  (default is `{}`):
     e.g. `{ 'one': '1' }` - '1' is synonym for 'one' and vice versa. Value can be an array `{ 'be': ['am', 'is', 'are'] }`.
-    
+
   * `acrossElements` {boolean} - Whether to search for matches across elements (default is `false`)
   * `combinePatterns` {number|boolean} - Combine a specified number of individual term patterns into one (default is `10`)
     See [Performance](performance.md#ways-to-boost-performance) for more details.
   * `cacheTextNodes` {boolean} - Caching information to improve performance (default is `undefined`)
     See [Performance](performance.md#ways-to-boost-performance) for more details.
   * `blockElementsBoundary` {boolean|object} - Whether to limit matches within default HTML block elements and/or custom elements (default is `undefined`)  AE
     See [Elements boundaries](elements-boundaries.md) for more details.
+    * `tagNames` {string[]} - An array of custom HTML tag names
+    * `extend` {boolean} - `true` extends default boundary elements by the custom elements
+      otherwise only the custom elements do have boundaries
+    * `char` {string} - A custom boundary character. The default is `\x01`.
+
   * `shadowDOM` {boolean} - Whether to mark inside shadow DOMs (default is `undefined`)
     See [Highlighting in shadow DOM](shadow-dom.md) for more details.
   * `iframes` {boolean} - Whether to mark inside iframes (default is `false`)
@@ -86,7 +90,7 @@ $(context).mark(search[, options]);
 
   * `noMatch : (term) => {}` {function} - A callback that is called when a term has no match at all (default is )
     * `term` {string|string[]} - The not found term(s); the parameter is array when `combinePatterns` option is used
-  
+
 ### Available properties of the `filterInfo` object depending on options
 
 |            options               |    match   |   matchStart   |  execution  | offset |
@@ -150,5 +154,4 @@ jQuery:
 <pre><code class='lang-javascript'>$('selector').mark('test', options);</code></pre>
 </details>
 
-* AE across elements
-
+* AE - only available when `acrossElements` option is set to `true`