feat: Added highlight container

src/components/common/definitions/defineAllComponents.ts

@@ -30,6 +30,7 @@ import IgcDropdownGroupComponent from '../../dropdown/dropdown-group.js';
 import IgcDropdownHeaderComponent from '../../dropdown/dropdown-header.js';
 import IgcDropdownItemComponent from '../../dropdown/dropdown-item.js';
 import IgcExpansionPanelComponent from '../../expansion-panel/expansion-panel.js';
+import IgcHighlightComponent from '../../highlight/highlight.js';
 import IgcIconComponent from '../../icon/icon.js';
 import IgcInputComponent from '../../input/input.js';
 import IgcListComponent from '../../list/list.js';
@@ -105,6 +106,7 @@ const allComponents: IgniteComponent[] = [
   IgcDividerComponent,
   IgcSwitchComponent,
   IgcExpansionPanelComponent,
+  IgcHighlightComponent,
   IgcIconComponent,
   IgcInputComponent,
   IgcListHeaderComponent,

src/components/common/util.ts

@@ -368,7 +368,7 @@ export function roundByDPR(value: number): number {
 }
 
 export function scrollIntoView(
-  element?: HTMLElement,
+  element?: HTMLElement | null,
   config?: ScrollIntoViewOptions
 ): void {
   if (!element) {
@@ -505,6 +505,19 @@ export function equal<T>(a: unknown, b: T, visited = new WeakSet()): boolean {
   return false;
 }
 
+/**
+ *  Escapes any potential regex syntax characters in a string, and returns a new string
+ *  that can be safely used as a literal pattern for the `RegExp()` constructor.
+ *
+ *  @remarks
+ *  Substitute with `RegExp.escape` once it has enough support:
+ *
+ * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/escape#browser_compatibility
+ */
+export function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
 /** Required utility type for specific props */
 export type RequiredProps<T, K extends keyof T> = T & {
   [P in K]-?: T[P];

src/components/highlight/highlight.spec.ts

@@ -0,0 +1,137 @@
+import { elementUpdated, expect, fixture, html } from '@open-wc/testing';
+
+import { defineComponents } from '../common/definitions/defineComponents.js';
+import IgcHighlightComponent from './highlight.js';
+
+describe('Highlight', () => {
+  before(() => defineComponents(IgcHighlightComponent));
+
+  let highlight: IgcHighlightComponent;
+
+  function createHighlightWithInitialMatch() {
+    return html`<igc-highlight search-text="lorem">
+      Lorem ipsum dolor sit amet consectetur adipisicing elit. Sapiente in
+      recusandae aliquam placeat! Saepe hic reiciendis quae, dolorum totam ab
+      mollitia, tempora excepturi blanditiis repellat dolore nemo cumque illum
+      quas.
+    </igc-highlight>`;
+  }
+
+  function createHighlight() {
+    return html`<igc-highlight>
+      Lorem ipsum dolor sit amet consectetur adipisicing elit. Sapiente in
+      recusandae aliquam placeat! Saepe hic reiciendis quae, dolorum totam ab
+      mollitia, tempora excepturi blanditiis repellat dolore nemo cumque illum
+      quas.
+    </igc-highlight>`;
+  }
+
+  describe('Initial render', () => {
+    beforeEach(async () => {
+      highlight = await fixture(createHighlightWithInitialMatch());
+    });
+
+    it('is correctly matched', async () => {
+      expect(highlight.size).to.equal(1);
+    });
+  });
+
+  describe('DOM', () => {
+    beforeEach(async () => {
+      highlight = await fixture(createHighlight());
+    });
+
+    it('is defined', async () => {
+      expect(highlight).to.not.be.undefined;
+    });
+
+    it('is accessible', async () => {
+      await expect(highlight).shadowDom.to.be.accessible();
+      await expect(highlight).lightDom.to.be.accessible();
+    });
+  });
+
+  describe('API', () => {
+    beforeEach(async () => {
+      highlight = await fixture(createHighlight());
+    });
+
+    it('matches on changing `search` value', async () => {
+      expect(highlight.size).to.equal(0);
+
+      highlight.searchText = 'lorem';
+      await elementUpdated(highlight);
+
+      expect(highlight.size).to.equal(1);
+
+      highlight.searchText = '';
+      await elementUpdated(highlight);
+
+      expect(highlight.size).to.equal(0);
+    });
+
+    it('matches with case sensitivity', async () => {
+      highlight.caseSensitive = true;
+      highlight.searchText = 'lorem';
+      await elementUpdated(highlight);
+
+      expect(highlight.size).to.equal(0);
+
+      highlight.searchText = 'Lorem';
+      await elementUpdated(highlight);
+
+      expect(highlight.size).to.equal(1);
+    });
+
+    it('moves to the next match when `next()` is invoked', async () => {
+      highlight.searchText = 'e';
+      await elementUpdated(highlight);
+
+      expect(highlight.size).greaterThan(0);
+      expect(highlight.current).to.equal(0);
+
+      highlight.next();
+      expect(highlight.current).to.equal(1);
+    });
+
+    it('moves to the previous when `previous()` is invoked', async () => {
+      highlight.searchText = 'e';
+      await elementUpdated(highlight);
+
+      expect(highlight.size).greaterThan(0);
+      expect(highlight.current).to.equal(0);
+
+      // Wrap around to the last one
+      highlight.previous();
+      expect(highlight.current).to.equal(highlight.size - 1);
+    });
+
+    it('setActive called', async () => {
+      highlight.searchText = 'e';
+      await elementUpdated(highlight);
+
+      highlight.setActive(15);
+      expect(highlight.current).to.equal(15);
+    });
+
+    it('refresh called', async () => {
+      highlight.searchText = 'lorem';
+      await elementUpdated(highlight);
+
+      expect(highlight.size).to.equal(1);
+
+      const node = document.createElement('div');
+      node.textContent = 'Lorem '.repeat(9);
+
+      highlight.append(node);
+      highlight.search();
+
+      expect(highlight.size).to.equal(10);
+
+      node.remove();
+      highlight.search();
+
+      expect(highlight.size).to.equal(1);
+    });
+  });
+});

src/components/highlight/highlight.ts

@@ -0,0 +1,212 @@
+import { html, LitElement } from 'lit';
+import { property } from 'lit/decorators.js';
+import { addThemingController } from '../../theming/theming-controller.js';
+import { registerComponent } from '../common/definitions/register.js';
+import {
+  createHighlightController,
+  type HighlightNavigation,
+} from './service.js';
+import { styles as shared } from './themes/shared/highlight.common.css.js';
+import { all } from './themes/themes.js';
+
+/**
+ * The highlight component provides efficient searching and highlighting of text
+ * projected into it via its default slot. It uses the native CSS Custom Highlight API
+ * to apply highlight styles to matched text nodes without modifying the DOM.
+ *
+ * The component supports case-sensitive matching, programmatic navigation between
+ * matches, and automatic scroll-into-view of the active match.
+ *
+ * @element igc-highlight
+ *
+ * @slot - The default slot. Place the text content you want to search and highlight here.
+ *
+ * @cssproperty --foreground - The text color for a highlighted text node.
+ * @cssproperty --background - The background color for a highlighted text node.
+ * @cssproperty --foreground-active - The text color for the active highlighted text node.
+ * @cssproperty --background-active - The background color for the active highlighted text node.
+ *
+ * @example
+ * Basic usage — wrap your text and set the `search-text` attribute:
+ * ```html
+ * <igc-highlight search-text="world">
+ *   <p>Hello, world! The world is a wonderful place.</p>
+ * </igc-highlight>
+ * ```
+ *
+ * @example
+ * Case-sensitive search:
+ * ```html
+ * <igc-highlight search-text="Hello" case-sensitive>
+ *   <p>Hello hello HELLO — only the first one matches.</p>
+ * </igc-highlight>
+ * ```
+ *
+ * @example
+ * Navigating between matches programmatically:
+ * ```typescript
+ * const highlight = document.querySelector('igc-highlight');
+ *
+ * highlight.searchText = 'world';
+ * console.log(highlight.size);    // total number of matches
+ * console.log(highlight.current); // index of the active match (0-based)
+ *
+ * highlight.next();               // move to the next match
+ * highlight.previous();           // move to the previous match
+ * highlight.setActive(2);         // jump to a specific match by index
+ * ```
+ *
+ * @example
+ * Prevent scroll-into-view when navigating:
+ * ```typescript
+ * const highlight = document.querySelector('igc-highlight');
+ * highlight.next({ preventScroll: true });
+ * ```
+ *
+ * @example
+ * Re-run search after dynamic content changes (e.g. lazy-loaded text):
+ * ```typescript
+ * const highlight = document.querySelector('igc-highlight');
+ * // After slotted content has been updated:
+ * highlight.search();
+ * ```
+ */
+export default class IgcHighlightComponent extends LitElement {
+  public static readonly tagName = 'igc-highlight';
+  public static override styles = [shared];
+
+  /* blazorSuppress */
+  public static register(): void {
+    registerComponent(IgcHighlightComponent);
+  }
+
+  //#region Internal properties and state
+
+  private readonly _service = createHighlightController(this);
+
+  private _caseSensitive = false;
+  private _searchText = '';
+
+  //#endregion
+
+  //#region Public properties and attributes
+
+  /**
+   * Whether to match the searched text with case sensitivity in mind.
+   * When `true`, only exact-case occurrences of `searchText` are highlighted.
+   *
+   * @attr case-sensitive
+   * @default false
+   */
+  @property({ type: Boolean, reflect: true, attribute: 'case-sensitive' })
+  public set caseSensitive(value: boolean) {
+    this._caseSensitive = value;
+    this.search();
+  }
+
+  public get caseSensitive(): boolean {
+    return this._caseSensitive;
+  }
+
+  /**
+   * The string to search and highlight in the DOM content of the component.
+   * Setting this property triggers a new search automatically.
+   * An empty string clears all highlights.
+   *
+   * @attr search-text
+   */
+  @property({ attribute: 'search-text' })
+  public set searchText(value: string) {
+    this._searchText = value;
+    this.search();
+  }
+
+  public get searchText(): string {
+    return this._searchText;
+  }
+
+  /** The total number of matches found for the current `searchText`. Returns `0` when there are no matches or `searchText` is empty. */
+  public get size(): number {
+    return this._service.size;
+  }
+
+  /** The zero-based index of the currently active (focused) match. Returns `0` when there are no matches. */
+  public get current(): number {
+    return this._service.current;
+  }
+
+  //#endregion
+
+  constructor() {
+    super();
+
+    addThemingController(this, all, {
+      themeChange: this._addStylesheet,
+    });
+  }
+
+  //#region Internal methods
+
+  private _addStylesheet(): void {
+    this._service.attachStylesheet();
+  }
+
+  //#endregion
+
+  //#region Public methods
+
+  /**
+   * Moves the active highlight to the next match.
+   * Wraps around to the first match after the last one.
+   *
+   * @param options - Optional navigation options (e.g. `preventScroll`).
+   */
+  public next(options?: HighlightNavigation): void {
+    this._service.next(options);
+  }
+
+  /**
+   * Moves the active highlight to the previous match.
+   * Wraps around to the last match when going back from the first one.
+   *
+   * @param options - Optional navigation options (e.g. `preventScroll`).
+   */
+  public previous(options?: HighlightNavigation): void {
+    this._service.previous(options);
+  }
+
+  /**
+   * Moves the active highlight to the match at the specified zero-based index.
+   *
+   * @param index - The zero-based index of the match to activate.
+   * @param options - Optional navigation options (e.g. `preventScroll`).
+   */
+  public setActive(index: number, options?: HighlightNavigation): void {
+    this._service.setActive(index, options);
+  }
+
+  /**
+   * Re-runs the highlight search based on the current `searchText` and `caseSensitive` values.
+   *
+   * Call this method after the slotted content changes dynamically (e.g. after lazy loading
+   * or programmatic DOM mutations) to ensure all matches are up to date.
+   */
+  public search(): void {
+    if (this.hasUpdated) {
+      this._service.clear();
+      this._service.find(this.searchText);
+    }
+  }
+
+  //#endregion
+
+  protected override render() {
+    return html`<slot></slot>`;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'igc-highlight': IgcHighlightComponent;
+  }
+}