text-highlight-js 1.0.0

package/dist/cjs/index.js

@@ -0,0 +1,368 @@
+"use strict";
+/**
+ * @fileoverview Enterprise-grade text highlighting utility
+ * Provides safe, performant text highlighting with HTML preservation
+ * @module TextHighlightHelper
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasMatch = exports.countMatches = exports.stripHtmlTags = exports.highlightHtmlContent = exports.highlightText = void 0;
+// ============================================================================
+// Constants
+// ============================================================================
+// const DEFAULT_HIGHLIGHT_CLASS = 'text-highlight';
+const MAX_SEARCH_TERMS = 50; // Prevent performance issues with too many terms
+const MAX_TEXT_LENGTH = 1000000; // 1MB text limit
+const MAX_SEARCH_TERM_LENGTH = 1000;
+// ============================================================================
+// Private Utilities
+// ============================================================================
+/**
+ * Validates and sanitizes input text
+ * @private
+ */
+const validateText = (text) => {
+    if (text === null || text === undefined) {
+        return "";
+    }
+    if (typeof text !== "string") {
+        console.warn("[TextHighlight] Invalid text type:", typeof text);
+        return "";
+    }
+    if (text.length > MAX_TEXT_LENGTH) {
+        console.warn(`[TextHighlight] Text exceeds maximum length (${MAX_TEXT_LENGTH}). Truncating.`);
+        return text.substring(0, MAX_TEXT_LENGTH);
+    }
+    return text;
+};
+/**
+ * Normalizes search terms to array and validates
+ * @private
+ */
+const normalizeSearchTerms = (searchTerm) => {
+    if (!searchTerm) {
+        return [];
+    }
+    const terms = Array.isArray(searchTerm) ? searchTerm : [searchTerm];
+    const validTerms = terms
+        .filter((term) => {
+        if (typeof term !== "string") {
+            console.warn("[TextHighlight] Invalid search term type:", typeof term);
+            return false;
+        }
+        if (term.length > MAX_SEARCH_TERM_LENGTH) {
+            console.warn(`[TextHighlight] Search term exceeds maximum length (${MAX_SEARCH_TERM_LENGTH})`);
+            return false;
+        }
+        return true;
+    })
+        .map((term) => term.trim())
+        .filter((term) => term.length > 0);
+    if (validTerms.length > MAX_SEARCH_TERMS) {
+        console.warn(`[TextHighlight] Too many search terms (${validTerms.length}). Using first ${MAX_SEARCH_TERMS}.`);
+        return validTerms.slice(0, MAX_SEARCH_TERMS);
+    }
+    return validTerms;
+};
+/**
+ * Escapes special regex characters in the search string
+ * @private
+ */
+const escapeRegExp = (text) => {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+};
+/**
+ * Creates a regex pattern from search terms
+ * @private
+ */
+const createSearchPattern = (terms, options = {}) => {
+    if (terms.length === 0) {
+        return null;
+    }
+    try {
+        const escapedTerms = [...terms]
+            .sort((a, b) => b.length - a.length)
+            .map(escapeRegExp);
+        const pattern = options.wholeWord
+            ? `\\b(${escapedTerms.join("|")})\\b`
+            : `(${escapedTerms.join("|")})`;
+        const flags = options.caseSensitive ? "g" : "gi";
+        return new RegExp(pattern, flags);
+    }
+    catch (error) {
+        console.error("[TextHighlight] Failed to create search pattern:", error);
+        return null;
+    }
+};
+/**
+ * Checks if a string matches any search term
+ * @private
+ */
+const matchesSearchTerm = (text, normalizedTermSet, caseSensitive = false) => {
+    const compareText = caseSensitive ? text : text.toLowerCase();
+    return normalizedTermSet.has(compareText);
+};
+/**
+ * Creates a highlight mark element (styled via CSS class)
+ * @private
+ */
+const createHighlightMark = (content, options = {}) => {
+    const mark = document.createElement("mark");
+    if (options.className) {
+        mark.className = options.className;
+    }
+    mark.textContent = content;
+    return mark;
+};
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Highlights search terms in plain text content
+ * Returns structured segments indicating which parts should be highlighted.
+ * This function is framework-agnostic and does not return JSX.
+ *
+ * @param text - The text to highlight
+ * @param searchTerm - Single search term or array of terms
+ * @param options - Highlighting configuration options
+ * @returns Array of segments with highlight metadata
+ *
+ * @example
+ * highlightText('Hello World', 'world')
+ * // → [{ text: 'Hello ', highlighted: false }, { text: 'World', highlighted: true }]
+ */
+const highlightText = (text, searchTerm, options = {}) => {
+    const validatedText = validateText(text);
+    if (!validatedText.trim()) {
+        return [{ text: validatedText, highlighted: false }];
+    }
+    const searchTerms = normalizeSearchTerms(searchTerm);
+    if (searchTerms.length === 0) {
+        return [{ text: validatedText, highlighted: false }];
+    }
+    const normalizedTermSet = new Set(options.caseSensitive
+        ? searchTerms
+        : searchTerms.map((t) => t.toLowerCase()));
+    const pattern = createSearchPattern(searchTerms, options);
+    if (!pattern) {
+        return [{ text: validatedText, highlighted: false }];
+    }
+    try {
+        const parts = validatedText.split(pattern);
+        let highlightCount = 0;
+        const maxHighlights = typeof options.maxHighlights === "number"
+            ? options.maxHighlights
+            : Infinity;
+        const segments = [];
+        parts.forEach((part) => {
+            if (!part) {
+                return;
+            }
+            const isMatch = matchesSearchTerm(part, normalizedTermSet, options.caseSensitive);
+            if (isMatch && highlightCount < maxHighlights) {
+                highlightCount++;
+                segments.push({ text: part, highlighted: true });
+            }
+            else {
+                segments.push({ text: part, highlighted: false });
+            }
+        });
+        return segments;
+    }
+    catch (error) {
+        console.error("[TextHighlight] Error highlighting text:", error);
+        return [{ text: validatedText, highlighted: false }];
+    }
+};
+exports.highlightText = highlightText;
+/**
+ * Highlights search terms in HTML content while preserving HTML structure
+ * Only highlights text nodes, leaving HTML tags and attributes intact
+ *
+ * @param htmlContent - HTML string to highlight
+ * @param searchTerm - Single search term or array of terms
+ * @param options - Highlighting configuration options
+ * @returns HTML string with highlighted text
+ *
+ * @example
+ * ```tsx
+ * highlightHtmlContent('<p>Hello World</p>', 'world')
+ * highlightHtmlContent('<div>React <br/> TypeScript</div>', ['react', 'script'])
+ * ```
+ */
+const highlightHtmlContent = (htmlContent, searchTerm, options = {}) => {
+    const validatedHtml = validateText(htmlContent);
+    if (!validatedHtml) {
+        return "";
+    }
+    if (typeof document === "undefined") {
+        console.warn("[TextHighlight] DOM not available (SSR mode)");
+        return validatedHtml;
+    }
+    const searchTerms = normalizeSearchTerms(searchTerm);
+    if (searchTerms.length === 0) {
+        return validatedHtml;
+    }
+    const normalizedTermSet = new Set(options.caseSensitive
+        ? searchTerms
+        : searchTerms.map((t) => t.toLowerCase()));
+    const pattern = createSearchPattern(searchTerms, options);
+    if (!pattern) {
+        return validatedHtml;
+    }
+    try {
+        // Create temporary DOM element to parse HTML safely
+        const tempDiv = document.createElement("div");
+        tempDiv.innerHTML = validatedHtml;
+        let highlightCount = 0;
+        const maxHighlights = typeof options.maxHighlights === "number"
+            ? options.maxHighlights
+            : Infinity;
+        /**
+         * Recursively highlights text nodes in DOM tree
+         * @private
+         */
+        const highlightTextNodes = (node) => {
+            var _a;
+            if (highlightCount >= maxHighlights) {
+                return;
+            }
+            if (node.nodeType === Node.TEXT_NODE) {
+                // Text node - apply highlighting
+                const textContent = node.textContent || "";
+                // Reset regex lastIndex for accurate testing
+                pattern.lastIndex = 0;
+                if (pattern.test(textContent)) {
+                    // Reset again for split operation
+                    pattern.lastIndex = 0;
+                    const fragment = document.createDocumentFragment();
+                    const parts = textContent.split(pattern);
+                    parts.forEach((part) => {
+                        if (!part) {
+                            return;
+                        }
+                        const isMatch = matchesSearchTerm(part, normalizedTermSet, options.caseSensitive);
+                        if (isMatch && highlightCount < maxHighlights) {
+                            highlightCount++;
+                            fragment.appendChild(createHighlightMark(part, options));
+                        }
+                        else {
+                            fragment.appendChild(document.createTextNode(part));
+                        }
+                    });
+                    // Replace original text node with highlighted fragment
+                    if (node.parentNode) {
+                        node.parentNode.replaceChild(fragment, node);
+                    }
+                }
+            }
+            else if (node.nodeType === Node.ELEMENT_NODE) {
+                // Element node - recursively process child nodes
+                // Skip script, style, and mark elements
+                const element = node;
+                const tagName = (_a = element.tagName) === null || _a === void 0 ? void 0 : _a.toLowerCase();
+                if (tagName === "script" || tagName === "style" || tagName === "mark") {
+                    return;
+                }
+                // Convert to array to avoid live collection issues during modification
+                const childNodes = Array.from(node.childNodes);
+                childNodes.forEach(highlightTextNodes);
+            }
+        };
+        highlightTextNodes(tempDiv);
+        return tempDiv.innerHTML;
+    }
+    catch (error) {
+        console.error("[TextHighlight] Error highlighting HTML content:", error);
+        return validatedHtml;
+    }
+};
+exports.highlightHtmlContent = highlightHtmlContent;
+/**
+ * Strips HTML tags from content to get plain text
+ * Useful for extracting searchable text from HTML
+ *
+ * @param html - HTML string to strip
+ * @returns Plain text content
+ *
+ * @example
+ * ```tsx
+ * stripHtmlTags('<p>Hello <strong>World</strong></p>') // Returns: "Hello World"
+ * ```
+ */
+const stripHtmlTags = (html) => {
+    const validatedHtml = validateText(html);
+    if (!validatedHtml) {
+        return "";
+    }
+    if (typeof document === "undefined") {
+        console.warn("[TextHighlight] DOM not available (SSR mode)");
+        return validatedHtml;
+    }
+    try {
+        const tempDiv = document.createElement("div");
+        tempDiv.innerHTML = validatedHtml;
+        return tempDiv.textContent || tempDiv.innerText || "";
+    }
+    catch (error) {
+        console.error("[TextHighlight] Error stripping HTML tags:", error);
+        return validatedHtml;
+    }
+};
+exports.stripHtmlTags = stripHtmlTags;
+/**
+ * Counts the number of matches for search terms in text
+ * Useful for displaying search result counts
+ *
+ * @param text - Text to search
+ * @param searchTerm - Single search term or array of terms
+ * @param options - Search configuration options
+ * @returns Number of matches found
+ *
+ * @example
+ * ```tsx
+ * countMatches('Hello World Hello', 'hello') // Returns: 2
+ * countMatches('React TypeScript', ['react', 'script']) // Returns: 2
+ * ```
+ */
+const countMatches = (text, searchTerm, options = {}) => {
+    const validatedText = validateText(text);
+    if (!validatedText) {
+        return 0;
+    }
+    const searchTerms = normalizeSearchTerms(searchTerm);
+    if (searchTerms.length === 0) {
+        return 0;
+    }
+    const pattern = createSearchPattern(searchTerms, options);
+    if (!pattern) {
+        return 0;
+    }
+    try {
+        const matches = validatedText.match(pattern);
+        return matches ? matches.length : 0;
+    }
+    catch (error) {
+        console.error("[TextHighlight] Error counting matches:", error);
+        return 0;
+    }
+};
+exports.countMatches = countMatches;
+/**
+ * Checks if text contains any of the search terms
+ *
+ * @param text - Text to search
+ * @param searchTerm - Single search term or array of terms
+ * @param options - Search configuration options
+ * @returns True if any match found
+ *
+ * @example
+ * ```tsx
+ * hasMatch('Hello World', 'world') // Returns: true
+ * hasMatch('React', ['angular', 'vue']) // Returns: false
+ * ```
+ */
+const hasMatch = (text, searchTerm, options = {}) => {
+    return countMatches(text, searchTerm, options) > 0;
+};
+exports.hasMatch = hasMatch;

package/dist/esm/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Enterprise-grade text highlighting utility
+ * Provides safe, performant text highlighting with HTML preservation
+ * @module TextHighlightHelper
+ * @version 1.0.0
+ */
+/**
+ * Configuration options for text highlighting
+ */
+export interface HighlightOptions {
+    /** CSS class name for highlighted elements (style via your own CSS) */
+    className?: string;
+    /** Case-sensitive search */
+    caseSensitive?: boolean;
+    /** Match whole words only */
+    wholeWord?: boolean;
+    /** Maximum number of highlights to apply (for performance) */
+    maxHighlights?: number;
+}
+/**
+ * Search term type - can be string or array of strings
+ */
+export type SearchTerm = string | string[];
+/**
+ * Result segment for highlighted text.
+ * Framework-agnostic structure that callers can render in any UI library.
+ */
+export interface HighlightSegment {
+    text: string;
+    highlighted: boolean;
+}
+/**
+ * Highlights search terms in plain text content
+ * Returns structured segments indicating which parts should be highlighted.
+ * This function is framework-agnostic and does not return JSX.
+ *
+ * @param text - The text to highlight
+ * @param searchTerm - Single search term or array of terms
+ * @param options - Highlighting configuration options
+ * @returns Array of segments with highlight metadata
+ *
+ * @example
+ * highlightText('Hello World', 'world')
+ * // → [{ text: 'Hello ', highlighted: false }, { text: 'World', highlighted: true }]
+ */
+declare const highlightText: (text: string, searchTerm: SearchTerm, options?: HighlightOptions) => HighlightSegment[];
+/**
+ * Highlights search terms in HTML content while preserving HTML structure
+ * Only highlights text nodes, leaving HTML tags and attributes intact
+ *
+ * @param htmlContent - HTML string to highlight
+ * @param searchTerm - Single search term or array of terms
+ * @param options - Highlighting configuration options
+ * @returns HTML string with highlighted text
+ *
+ * @example
+ * ```tsx
+ * highlightHtmlContent('<p>Hello World</p>', 'world')
+ * highlightHtmlContent('<div>React <br/> TypeScript</div>', ['react', 'script'])
+ * ```
+ */
+declare const highlightHtmlContent: (htmlContent: string, searchTerm: SearchTerm, options?: HighlightOptions) => string;
+/**
+ * Strips HTML tags from content to get plain text
+ * Useful for extracting searchable text from HTML
+ *
+ * @param html - HTML string to strip
+ * @returns Plain text content
+ *
+ * @example
+ * ```tsx
+ * stripHtmlTags('<p>Hello <strong>World</strong></p>') // Returns: "Hello World"
+ * ```
+ */
+declare const stripHtmlTags: (html: string) => string;
+/**
+ * Counts the number of matches for search terms in text
+ * Useful for displaying search result counts
+ *
+ * @param text - Text to search
+ * @param searchTerm - Single search term or array of terms
+ * @param options - Search configuration options
+ * @returns Number of matches found
+ *
+ * @example
+ * ```tsx
+ * countMatches('Hello World Hello', 'hello') // Returns: 2
+ * countMatches('React TypeScript', ['react', 'script']) // Returns: 2
+ * ```
+ */
+declare const countMatches: (text: string, searchTerm: SearchTerm, options?: HighlightOptions) => number;
+/**
+ * Checks if text contains any of the search terms
+ *
+ * @param text - Text to search
+ * @param searchTerm - Single search term or array of terms
+ * @param options - Search configuration options
+ * @returns True if any match found
+ *
+ * @example
+ * ```tsx
+ * hasMatch('Hello World', 'world') // Returns: true
+ * hasMatch('React', ['angular', 'vue']) // Returns: false
+ * ```
+ */
+declare const hasMatch: (text: string, searchTerm: SearchTerm, options?: HighlightOptions) => boolean;
+export { highlightText, highlightHtmlContent, stripHtmlTags, countMatches, hasMatch, };
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgBH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;AAE3C;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;CACtB;AA0ID;;;;;;;;;;;;;GAaG;AACH,QAAA,MAAM,aAAa,GACjB,MAAM,MAAM,EACZ,YAAY,UAAU,EACtB,UAAS,gBAAqB,KAC7B,gBAAgB,EAyDlB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,QAAA,MAAM,oBAAoB,GACxB,aAAa,MAAM,EACnB,YAAY,UAAU,EACtB,UAAS,gBAAqB,KAC7B,MA6GF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,QAAA,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MAmBrC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,QAAA,MAAM,YAAY,GAChB,MAAM,MAAM,EACZ,YAAY,UAAU,EACtB,UAAS,gBAAqB,KAC7B,MAuBF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,QAAA,MAAM,QAAQ,GACZ,MAAM,MAAM,EACZ,YAAY,UAAU,EACtB,UAAS,gBAAqB,KAC7B,OAEF,CAAC;AAMF,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,aAAa,EACb,YAAY,EACZ,QAAQ,GACT,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,364 @@
+/**
+ * @fileoverview Enterprise-grade text highlighting utility
+ * Provides safe, performant text highlighting with HTML preservation
+ * @module TextHighlightHelper
+ * @version 1.0.0
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+// const DEFAULT_HIGHLIGHT_CLASS = 'text-highlight';
+const MAX_SEARCH_TERMS = 50; // Prevent performance issues with too many terms
+const MAX_TEXT_LENGTH = 1000000; // 1MB text limit
+const MAX_SEARCH_TERM_LENGTH = 1000;
+// ============================================================================
+// Private Utilities
+// ============================================================================
+/**
+ * Validates and sanitizes input text
+ * @private
+ */
+const validateText = (text) => {
+    if (text === null || text === undefined) {
+        return "";
+    }
+    if (typeof text !== "string") {
+        console.warn("[TextHighlight] Invalid text type:", typeof text);
+        return "";
+    }
+    if (text.length > MAX_TEXT_LENGTH) {
+        console.warn(`[TextHighlight] Text exceeds maximum length (${MAX_TEXT_LENGTH}). Truncating.`);
+        return text.substring(0, MAX_TEXT_LENGTH);
+    }
+    return text;
+};
+/**
+ * Normalizes search terms to array and validates
+ * @private
+ */
+const normalizeSearchTerms = (searchTerm) => {
+    if (!searchTerm) {
+        return [];
+    }
+    const terms = Array.isArray(searchTerm) ? searchTerm : [searchTerm];
+    const validTerms = terms
+        .filter((term) => {
+        if (typeof term !== "string") {
+            console.warn("[TextHighlight] Invalid search term type:", typeof term);
+            return false;
+        }
+        if (term.length > MAX_SEARCH_TERM_LENGTH) {
+            console.warn(`[TextHighlight] Search term exceeds maximum length (${MAX_SEARCH_TERM_LENGTH})`);
+            return false;
+        }
+        return true;
+    })
+        .map((term) => term.trim())
+        .filter((term) => term.length > 0);
+    if (validTerms.length > MAX_SEARCH_TERMS) {
+        console.warn(`[TextHighlight] Too many search terms (${validTerms.length}). Using first ${MAX_SEARCH_TERMS}.`);
+        return validTerms.slice(0, MAX_SEARCH_TERMS);
+    }
+    return validTerms;
+};
+/**
+ * Escapes special regex characters in the search string
+ * @private
+ */
+const escapeRegExp = (text) => {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+};
+/**
+ * Creates a regex pattern from search terms
+ * @private
+ */
+const createSearchPattern = (terms, options = {}) => {
+    if (terms.length === 0) {
+        return null;
+    }
+    try {
+        const escapedTerms = [...terms]
+            .sort((a, b) => b.length - a.length)
+            .map(escapeRegExp);
+        const pattern = options.wholeWord
+            ? `\\b(${escapedTerms.join("|")})\\b`
+            : `(${escapedTerms.join("|")})`;
+        const flags = options.caseSensitive ? "g" : "gi";
+        return new RegExp(pattern, flags);
+    }
+    catch (error) {
+        console.error("[TextHighlight] Failed to create search pattern:", error);
+        return null;
+    }
+};
+/**
+ * Checks if a string matches any search term
+ * @private
+ */
+const matchesSearchTerm = (text, normalizedTermSet, caseSensitive = false) => {
+    const compareText = caseSensitive ? text : text.toLowerCase();
+    return normalizedTermSet.has(compareText);
+};
+/**
+ * Creates a highlight mark element (styled via CSS class)
+ * @private
+ */
+const createHighlightMark = (content, options = {}) => {
+    const mark = document.createElement("mark");
+    if (options.className) {
+        mark.className = options.className;
+    }
+    mark.textContent = content;
+    return mark;
+};
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Highlights search terms in plain text content
+ * Returns structured segments indicating which parts should be highlighted.
+ * This function is framework-agnostic and does not return JSX.
+ *
+ * @param text - The text to highlight
+ * @param searchTerm - Single search term or array of terms
+ * @param options - Highlighting configuration options
+ * @returns Array of segments with highlight metadata
+ *
+ * @example
+ * highlightText('Hello World', 'world')
+ * // → [{ text: 'Hello ', highlighted: false }, { text: 'World', highlighted: true }]
+ */
+const highlightText = (text, searchTerm, options = {}) => {
+    const validatedText = validateText(text);
+    if (!validatedText.trim()) {
+        return [{ text: validatedText, highlighted: false }];
+    }
+    const searchTerms = normalizeSearchTerms(searchTerm);
+    if (searchTerms.length === 0) {
+        return [{ text: validatedText, highlighted: false }];
+    }
+    const normalizedTermSet = new Set(options.caseSensitive
+        ? searchTerms
+        : searchTerms.map((t) => t.toLowerCase()));
+    const pattern = createSearchPattern(searchTerms, options);
+    if (!pattern) {
+        return [{ text: validatedText, highlighted: false }];
+    }
+    try {
+        const parts = validatedText.split(pattern);
+        let highlightCount = 0;
+        const maxHighlights = typeof options.maxHighlights === "number"
+            ? options.maxHighlights
+            : Infinity;
+        const segments = [];
+        parts.forEach((part) => {
+            if (!part) {
+                return;
+            }
+            const isMatch = matchesSearchTerm(part, normalizedTermSet, options.caseSensitive);
+            if (isMatch && highlightCount < maxHighlights) {
+                highlightCount++;
+                segments.push({ text: part, highlighted: true });
+            }
+            else {
+                segments.push({ text: part, highlighted: false });
+            }
+        });
+        return segments;
+    }
+    catch (error) {
+        console.error("[TextHighlight] Error highlighting text:", error);
+        return [{ text: validatedText, highlighted: false }];
+    }
+};
+/**
+ * Highlights search terms in HTML content while preserving HTML structure
+ * Only highlights text nodes, leaving HTML tags and attributes intact
+ *
+ * @param htmlContent - HTML string to highlight
+ * @param searchTerm - Single search term or array of terms
+ * @param options - Highlighting configuration options
+ * @returns HTML string with highlighted text
+ *
+ * @example
+ * ```tsx
+ * highlightHtmlContent('<p>Hello World</p>', 'world')
+ * highlightHtmlContent('<div>React <br/> TypeScript</div>', ['react', 'script'])
+ * ```
+ */
+const highlightHtmlContent = (htmlContent, searchTerm, options = {}) => {
+    const validatedHtml = validateText(htmlContent);
+    if (!validatedHtml) {
+        return "";
+    }
+    if (typeof document === "undefined") {
+        console.warn("[TextHighlight] DOM not available (SSR mode)");
+        return validatedHtml;
+    }
+    const searchTerms = normalizeSearchTerms(searchTerm);
+    if (searchTerms.length === 0) {
+        return validatedHtml;
+    }
+    const normalizedTermSet = new Set(options.caseSensitive
+        ? searchTerms
+        : searchTerms.map((t) => t.toLowerCase()));
+    const pattern = createSearchPattern(searchTerms, options);
+    if (!pattern) {
+        return validatedHtml;
+    }
+    try {
+        // Create temporary DOM element to parse HTML safely
+        const tempDiv = document.createElement("div");
+        tempDiv.innerHTML = validatedHtml;
+        let highlightCount = 0;
+        const maxHighlights = typeof options.maxHighlights === "number"
+            ? options.maxHighlights
+            : Infinity;
+        /**
+         * Recursively highlights text nodes in DOM tree
+         * @private
+         */
+        const highlightTextNodes = (node) => {
+            var _a;
+            if (highlightCount >= maxHighlights) {
+                return;
+            }
+            if (node.nodeType === Node.TEXT_NODE) {
+                // Text node - apply highlighting
+                const textContent = node.textContent || "";
+                // Reset regex lastIndex for accurate testing
+                pattern.lastIndex = 0;
+                if (pattern.test(textContent)) {
+                    // Reset again for split operation
+                    pattern.lastIndex = 0;
+                    const fragment = document.createDocumentFragment();
+                    const parts = textContent.split(pattern);
+                    parts.forEach((part) => {
+                        if (!part) {
+                            return;
+                        }
+                        const isMatch = matchesSearchTerm(part, normalizedTermSet, options.caseSensitive);
+                        if (isMatch && highlightCount < maxHighlights) {
+                            highlightCount++;
+                            fragment.appendChild(createHighlightMark(part, options));
+                        }
+                        else {
+                            fragment.appendChild(document.createTextNode(part));
+                        }
+                    });
+                    // Replace original text node with highlighted fragment
+                    if (node.parentNode) {
+                        node.parentNode.replaceChild(fragment, node);
+                    }
+                }
+            }
+            else if (node.nodeType === Node.ELEMENT_NODE) {
+                // Element node - recursively process child nodes
+                // Skip script, style, and mark elements
+                const element = node;
+                const tagName = (_a = element.tagName) === null || _a === void 0 ? void 0 : _a.toLowerCase();
+                if (tagName === "script" || tagName === "style" || tagName === "mark") {
+                    return;
+                }
+                // Convert to array to avoid live collection issues during modification
+                const childNodes = Array.from(node.childNodes);
+                childNodes.forEach(highlightTextNodes);
+            }
+        };
+        highlightTextNodes(tempDiv);
+        return tempDiv.innerHTML;
+    }
+    catch (error) {
+        console.error("[TextHighlight] Error highlighting HTML content:", error);
+        return validatedHtml;
+    }
+};
+/**
+ * Strips HTML tags from content to get plain text
+ * Useful for extracting searchable text from HTML
+ *
+ * @param html - HTML string to strip
+ * @returns Plain text content
+ *
+ * @example
+ * ```tsx
+ * stripHtmlTags('<p>Hello <strong>World</strong></p>') // Returns: "Hello World"
+ * ```
+ */
+const stripHtmlTags = (html) => {
+    const validatedHtml = validateText(html);
+    if (!validatedHtml) {
+        return "";
+    }
+    if (typeof document === "undefined") {
+        console.warn("[TextHighlight] DOM not available (SSR mode)");
+        return validatedHtml;
+    }
+    try {
+        const tempDiv = document.createElement("div");
+        tempDiv.innerHTML = validatedHtml;
+        return tempDiv.textContent || tempDiv.innerText || "";
+    }
+    catch (error) {
+        console.error("[TextHighlight] Error stripping HTML tags:", error);
+        return validatedHtml;
+    }
+};
+/**
+ * Counts the number of matches for search terms in text
+ * Useful for displaying search result counts
+ *
+ * @param text - Text to search
+ * @param searchTerm - Single search term or array of terms
+ * @param options - Search configuration options
+ * @returns Number of matches found
+ *
+ * @example
+ * ```tsx
+ * countMatches('Hello World Hello', 'hello') // Returns: 2
+ * countMatches('React TypeScript', ['react', 'script']) // Returns: 2
+ * ```
+ */
+const countMatches = (text, searchTerm, options = {}) => {
+    const validatedText = validateText(text);
+    if (!validatedText) {
+        return 0;
+    }
+    const searchTerms = normalizeSearchTerms(searchTerm);
+    if (searchTerms.length === 0) {
+        return 0;
+    }
+    const pattern = createSearchPattern(searchTerms, options);
+    if (!pattern) {
+        return 0;
+    }
+    try {
+        const matches = validatedText.match(pattern);
+        return matches ? matches.length : 0;
+    }
+    catch (error) {
+        console.error("[TextHighlight] Error counting matches:", error);
+        return 0;
+    }
+};
+/**
+ * Checks if text contains any of the search terms
+ *
+ * @param text - Text to search
+ * @param searchTerm - Single search term or array of terms
+ * @param options - Search configuration options
+ * @returns True if any match found
+ *
+ * @example
+ * ```tsx
+ * hasMatch('Hello World', 'world') // Returns: true
+ * hasMatch('React', ['angular', 'vue']) // Returns: false
+ * ```
+ */
+const hasMatch = (text, searchTerm, options = {}) => {
+    return countMatches(text, searchTerm, options) > 0;
+};
+// ============================================================================
+// Exports
+// ============================================================================
+export { highlightText, highlightHtmlContent, stripHtmlTags, countMatches, hasMatch, };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "text-highlight-js",
+  "version": "1.0.0",
+  "description": "Lightweight text highlighting utility with ESM and CJS support",
+  "keywords": [
+    "text",
+    "highlight",
+    "search",
+    "html",
+    "utility"
+  ],
+  "license": "MIT",
+  "author": "Anuj Gupta",
+
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+
+  "sideEffects": false,
+
+  "files": [
+    "dist"
+  ],
+
+  "scripts": {
+    "clean": "rimraf dist",
+    "build:esm": "tsc",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build": "npm run clean && npm run build:esm && npm run build:cjs",
+    "prepublishOnly": "npm run build"
+  },
+
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "rimraf": "^5.0.5"
+  },
+
+  "engines": {
+    "node": ">=14"
+  }
+}