dom-text-highlight 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# dom-text-highlight
+
+Fuzzy text matching and highlighting for DOM content using the CSS Custom Highlight API.
+
+## Install
+
+```sh
+npm install dom-text-highlight
+```
+
+## Basic Usage
+
+Import the default function and pass the text you want to find. The library finds the closest fuzzy match inside the target root and applies a `dom-highlight` CSS highlight.
+
+```js
+import DOMTextHighlight from 'dom-text-highlight'
+
+const article = document.querySelector('article')
+const range = DOMTextHighlight('custom highlight api', article)
+
+console.log(range.toString())
+```
+
+Add styles for the highlight name:
+
+```css
+::highlight(dom-highlight) {
+  background: #f6d85f;
+  color: #111;
+}
+```
+
+If no root is passed, the library searches `document.body`.
+
+```js
+DOMTextHighlight('some text on the page')
+```
+
+## Iframe Usage
+
+The package also exports `highlightInIframe`, which sends a highlight request from a parent page to a child iframe.
+
+```js
+import { highlightInIframe } from 'dom-text-highlight'
+
+const iframe = document.querySelector('iframe')
+
+iframe.addEventListener('load', () => {
+  highlightInIframe(iframe, 'text inside the iframe')
+})
+```
+
+The child iframe must load this module too. Importing it registers the message listener that handles `dom-highlight` messages.
+
+```html
+<script type="module">
+  import 'dom-text-highlight'
+</script>
+```
+
+You can pass a stricter `targetOrigin` as the third argument:
+
+```js
+highlightInIframe(iframe, 'text inside the iframe', 'https://example.com')
+```
+
+## API
+
+### `DOMTextHighlight(text, root)`
+
+Finds the best fuzzy match for `text` inside `root`, applies the `dom-highlight` custom highlight, and returns the created `Range`.
+
+- `text`: string to search for.
+- `root`: optional DOM node to search. Defaults to `document.body`.
+
+### `highlightInIframe(iframe, text, targetOrigin)`
+
+Posts a highlight request to an iframe.
+
+- `iframe`: target iframe element.
+- `text`: string to search for inside the iframe document.
+- `targetOrigin`: optional `postMessage` target origin. Defaults to `'*'`.
+
+## Browser Support
+
+This module requires the CSS Custom Highlight API, including `CSS.highlights` and `Highlight`. It throws an error when those APIs are unavailable.
+
+## Development
+
+Install dependencies:
+
+```sh
+npm install
+```
+
+Start the Vite test page:
+
+```sh
+npm run dev
+```
+
+Build the library:
+
+```sh
+npm run build
+```

package/dist/dom-text-highlight.js

@@ -0,0 +1,107 @@
+class w {
+  /**
+   * Calculates the Levenshtein distance for all substrings and returns their
+   * distance and insertion-deletion offset.
+   * 
+   * @param {string} needle The search string.
+   * @param {string} haystack The string to search.
+   * 
+   * @return {array} Array of all substring matches in pairs [distance, offset]
+   */
+  getEditDistances(t, o) {
+    var n = new Array(o.length + 1).fill([0, 0]);
+    for (let s = 0; s < t.length; s++) {
+      let r = [[s + 1, 0]];
+      for (let e = 0; e < o.length; e++) {
+        let i = t[s] != o[e], a = n[e + 1][0] + 1, h = r[e][0] + 1, g = n[e][0] + i, f = Math.min(a, Math.min(h, g)), c = [f, n[e][1]];
+        a === f ? c[1] = n[e + 1][1] - 1 : h === f && (c[1] = r[e][1] + 1), r.push(c);
+      }
+      n = r;
+    }
+    return n;
+  }
+  /**
+   * Search haystack for all instances of needle and returns an array of
+   * objects containing string position and levenshtein distance.
+   * 
+   * @param {string} needle The search string.
+   * @param {string} haystack The string to search.
+   * 
+   * @return {array} Array of best substring matches.
+   */
+  getMatches(t, o) {
+    let n = this.getEditDistances(t, o), s = [0], r = n[0][0];
+    for (let i = 1; i < n.length; i++) {
+      let a = n[i][0];
+      a < r ? (s = [i], r = a) : a == r && s.push(i);
+    }
+    let e = [];
+    for (let i of s) {
+      let a = n[i], h = {
+        distance: a[0],
+        start: i - t.length - a[1],
+        //simplification of startPos = endPos − (needleLength + insertions − deletions)
+        end: i
+      };
+      e.push(h);
+    }
+    return e;
+  }
+}
+function m(l, t) {
+  return new w().getMatches(l, t);
+}
+function p(l, t) {
+  const o = m(l, t);
+  let n;
+  for (const i of o)
+    (n === void 0 || i.distance < n.distance) && (n = i);
+  const s = Math.max(n.start, 0), r = Math.min(Math.max(n.end, s), t.length);
+  return { value: t.slice(s, r), start: s, end: r };
+}
+function x(l, t, o) {
+  const n = l.textContent ?? "";
+  if (!Number.isInteger(t) || !Number.isInteger(o) || t < 0 || t >= o || o > n.length)
+    throw new RangeError(
+      `Invalid range [${t}, ${o}) for text length ${n.length}`
+    );
+  const s = l.ownerDocument, r = s.createTreeWalker(
+    l,
+    s.defaultView.NodeFilter.SHOW_TEXT
+  );
+  let e = 0, i = null, a = 0, h = null, g = 0;
+  for (let c = r.nextNode(); c; c = r.nextNode()) {
+    const d = e + c.data.length;
+    if (i === null && t >= e && t < d && (i = c, a = t - e), h === null && o > e && o <= d && (h = c, g = o - e), i && h)
+      break;
+    e = d;
+  }
+  if (!i || !h)
+    throw new Error(
+      "Could not map offsets to the DOM. The DOM may have changed."
+    );
+  const f = s.createRange();
+  return f.setStart(i, a), f.setEnd(h, g), f;
+}
+const u = "dom-highlight";
+function M(l, t = document.body) {
+  const o = t.textContent ?? "", { start: n, end: s } = p(l, o), r = x(t, n, s), e = t.ownerDocument?.defaultView ?? window;
+  if (!e.CSS?.highlights || !e.Highlight)
+    throw new Error("This browser does not support the CSS Custom Highlight API.");
+  return e.CSS.highlights.set(u, new e.Highlight(r)), r;
+}
+function y(l, t, o = "*") {
+  if (!l?.contentWindow)
+    throw new TypeError("Expected an iframe with a contentWindow");
+  l.contentWindow.postMessage({
+    type: u,
+    text: t
+  }, o);
+}
+typeof window < "u" && window.addEventListener("message", (l) => {
+  l.data?.type !== u || typeof l.data.text != "string" || M(l.data.text, document.body);
+});
+export {
+  M as default,
+  y as highlightInIframe
+};

package/dist/dom-text-highlight.umd.cjs

@@ -0,0 +1 @@
+(function(d,c){typeof exports=="object"&&typeof module<"u"?c(exports):typeof define=="function"&&define.amd?define(["exports"],c):(d=typeof globalThis<"u"?globalThis:d||self,c(d.DOMTextHighlight={}))})(this,(function(d){"use strict";class c{getEditDistances(t,o){var n=new Array(o.length+1).fill([0,0]);for(let s=0;s<t.length;s++){let r=[[s+1,0]];for(let e=0;e<o.length;e++){let i=t[s]!=o[e],h=n[e+1][0]+1,a=r[e][0]+1,g=n[e][0]+i,u=Math.min(h,Math.min(a,g)),f=[u,n[e][1]];h===u?f[1]=n[e+1][1]-1:a===u&&(f[1]=r[e][1]+1),r.push(f)}n=r}return n}getMatches(t,o){let n=this.getEditDistances(t,o),s=[0],r=n[0][0];for(let i=1;i<n.length;i++){let h=n[i][0];h<r?(s=[i],r=h):h==r&&s.push(i)}let e=[];for(let i of s){let h=n[i],a={distance:h[0],start:i-t.length-h[1],end:i};e.push(a)}return e}}function M(l,t){return new c().getMatches(l,t)}function x(l,t){const o=M(l,t);let n;for(const i of o)(n===void 0||i.distance<n.distance)&&(n=i);const s=Math.max(n.start,0),r=Math.min(Math.max(n.end,s),t.length);return{value:t.slice(s,r),start:s,end:r}}function y(l,t,o){const n=l.textContent??"";if(!Number.isInteger(t)||!Number.isInteger(o)||t<0||t>=o||o>n.length)throw new RangeError(`Invalid range [${t}, ${o}) for text length ${n.length}`);const s=l.ownerDocument,r=s.createTreeWalker(l,s.defaultView.NodeFilter.SHOW_TEXT);let e=0,i=null,h=0,a=null,g=0;for(let f=r.nextNode();f;f=r.nextNode()){const m=e+f.data.length;if(i===null&&t>=e&&t<m&&(i=f,h=t-e),a===null&&o>e&&o<=m&&(a=f,g=o-e),i&&a)break;e=m}if(!i||!a)throw new Error("Could not map offsets to the DOM. The DOM may have changed.");const u=s.createRange();return u.setStart(i,h),u.setEnd(a,g),u}const w="dom-highlight";function p(l,t=document.body){const o=t.textContent??"",{start:n,end:s}=x(l,o),r=y(t,n,s),e=t.ownerDocument?.defaultView??window;if(!e.CSS?.highlights||!e.Highlight)throw new Error("This browser does not support the CSS Custom Highlight API.");return e.CSS.highlights.set(w,new e.Highlight(r)),r}function b(l,t,o="*"){if(!l?.contentWindow)throw new TypeError("Expected an iframe with a contentWindow");l.contentWindow.postMessage({type:w,text:t},o)}typeof window<"u"&&window.addEventListener("message",l=>{l.data?.type!==w||typeof l.data.text!="string"||p(l.data.text,document.body)}),d.default=p,d.highlightInIframe=b,Object.defineProperties(d,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}})}));

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "dom-text-highlight",
+  "version": "1.0.0",
+  "description": "Fuzzy text matching and highlighting for DOM content.",
+  "type": "module",
+  "main": "./dist/dom-text-highlight.umd.cjs",
+  "module": "./dist/dom-text-highlight.js",
+  "exports": {
+    ".": {
+      "import": "./dist/dom-text-highlight.js",
+      "require": "./dist/dom-text-highlight.umd.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite --host 0.0.0.0",
+    "build": "vite build",
+    "preview": "vite preview --host 0.0.0.0"
+  },
+  "devDependencies": {
+    "vite": "^7.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/ol-c/dom-text-highlight.git"
+  },
+  "author": "Jason Ford",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/ol-c/dom-text-highlight/issues"
+  }
+}