DOM Find and Replace Utility

Common errors

• TypeError: findAndReplaceDOMText is not a function

  cause The `findAndReplaceDOMText` function was not correctly imported or the library script was not loaded into the page. This is common when mixing module types (e.g., trying to `require` a library designed for global script inclusion) or if the `npm install` command did not target the correct package (`heti-findandreplacedomtext`).
  fix If using npm/bundlers, ensure `import findAndReplaceDOMText from 'heti-findandreplacedomtext';` is at the top of your file. If using a script tag, verify the `<script>` tag pointing to `findAndReplaceDOMText.js` is correctly placed and loaded before its usage. Also verify the package name in `npm install` and `import` matches `heti-findandreplacedomtext`.

• Only the first occurrence of my search term is being replaced/wrapped.

  cause When using a regular expression for the `find` option, the global flag (`/g`) was omitted, causing `RegExp.prototype.exec` to only find the first match.
  fix Modify your `find` regular expression to include the global flag, e.g., change `/myword/` to `/myword/g`.

• The DOM structure appears corrupted or unexpectedly nested after replacement, especially with complex replacements.

  cause This can occur if the `replace` function is not carefully constructing new nodes, or if the `portionMode` is not suitable for the desired outcome, leading to incorrect node splitting or merging. It can also happen when the original DOM structure is heavily modified or normalized after the initial replacement, making reversion unpredictable.
  fix Review your `replace` function to ensure it consistently returns valid DOM nodes or strings. Consider adjusting the `portionMode` option (default is 'retain'). If you need to revert changes, save a clone of the original DOM subtree before modification, as the built-in `revert()` method may fail if the DOM is significantly altered elsewhere.

Warnings

• gotcha When using regular expressions for the `find` option, ensure the global flag (`/g`) is included if you intend to find and replace all occurrences. Without it, only the first match will be processed.
  Fix: Change `/pattern/` to `/pattern/g` for global search.
• gotcha The default `portionMode` is 'retain', which re-uses existing node boundaries. If you need the entire replacement to reside within the first-found match portion's node, set `portionMode: 'first'`. Most use cases benefit from the default 'retain' behavior.
  Fix: Set `portionMode: 'first'` in the options object if you desire a different behavior for node boundary handling during replacement.
• gotcha When using the `replace` option with a function, be cautious about injecting untrusted user-generated content directly into the DOM, as this can lead to Cross-Site Scripting (XSS) vulnerabilities. Always sanitize inputs.
  Fix: Sanitize any dynamic or user-provided input before using it within the `replace` function to create new DOM nodes or text content.
• gotcha Operating on very large or frequently changing DOM trees can lead to performance issues due to extensive DOM traversal and manipulation. Use `filterElements` and `forceContext` to narrow the scope if possible.
  Fix: Optimize by providing a `filterElements` function to ignore irrelevant parts of the DOM, or use `preset: 'prose'` to automatically exclude non-textual elements and limit contexts, improving performance on typical prose content.
• gotcha The package does not ship with TypeScript type definitions directly. While it can be used in TypeScript projects, you'll need to install `@types/findandreplacedomtext` for proper type checking and IDE assistance.
  Fix: Install the type definitions: `npm install --save-dev @types/findandreplacedomtext`.

Install

• npm install heti-findandreplacedomtext npm
• yarn add heti-findandreplacedomtext yarn
• pnpm add heti-findandreplacedomtext pnpm

Imports

• findAndReplaceDOMText
  wrong:

  const findAndReplaceDOMText = require('heti-findandreplacedomtext');

  correct:

  import findAndReplaceDOMText from 'heti-findandreplacedomtext';

  While older packages primarily use CommonJS, modern bundlers typically handle `import` for this library, but it may not be native ESM. For script tags, it exposes a global `findAndReplaceDOMText`.
• findAndReplaceDOMText (global)

  <!-- In HTML: --><script src="path/to/findAndReplaceDOMText.js"></script>
  <script>
    findAndReplaceDOMText(document.body, { find: /foo/, wrap: 'span' });
  </script>

  The library directly exposes the function globally when included as a script tag, which was common practice for client-side utilities. No explicit `export` is needed in this context.
• findAndReplaceDOMText (TypeScript)

  import findAndReplaceDOMText from 'heti-findandreplacedomtext';
  // Ensure @types/findandreplacedomtext is installed for type support
  // npm install --save-dev @types/findandreplacedomtext

  TypeScript users should install `@types/findandreplacedomtext` for type definitions, as the library itself is written in JavaScript and does not ship with built-in types.

Quickstart

Demonstrates wrapping text with `em` and `strong` tags, including across node boundaries, and replacing text with a custom element and uppercase transformation.

document.body.innerHTML = `
  <p id="t1">
    123 456 Hello
  </p>
  <p id="t2">
    123 456 Hell<span>o Goodbye</span>
  </p>
  <div id="t3">
    This is a test. Another test word.
  </div>
`;

import findAndReplaceDOMText from 'heti-findandreplacedomtext';

console.log('Original DOM content:');
console.log(document.body.innerHTML);

// Example 1: Basic wrap
findAndReplaceDOMText(document.getElementById('t1'), {
  find: /Hello/,
  wrap: 'em'
});

// Example 2: Wrap across multiple nodes
findAndReplaceDOMText(document.getElementById('t2'), {
  find: /Hello/,
  wrap: 'strong'
});

// Example 3: Replace text using a function
findAndReplaceDOMText(document.getElementById('t3'), {
  find: /test/g,
  replace: function(portion, match) {
    const span = document.createElement('span');
    span.style.color = 'blue';
    span.textContent = portion.text.toUpperCase();
    return span;
  }
});

console.log('\nModified DOM content:');
console.log(document.body.innerHTML);