@coveo/quantic 3.39.0 → 3.40.0

package/force-app/main/default/lwc/quanticGeneratedAnswerContent/quanticGeneratedAnswerContent.js

@@ -1,6 +1,12 @@
+import {
+  registerComponentForInit,
+  initializeWithHeadless,
+  getHeadlessBundle,
+} from 'c/quanticHeadlessLoader';
 import {
   transformMarkdownToHtml,
   loadMarkdownDependencies,
+  LinkUtils,
 } from 'c/quanticUtils';
 import {LightningElement, api} from 'lwc';
 // @ts-ignore
@@ -8,6 +14,21 @@ import generatedMarkdownContentTemplate from './templates/generatedMarkdownConte
 // @ts-ignore
 import generatedTextContentTemplate from './templates/generatedTextContent.html';
 
+/** @typedef {import("coveo").SearchEngine} SearchEngine */
+/** @typedef {import("coveo").InsightEngine} InsightEngine */
+
+const INLINE_LINK_ICON = `
+  <svg
+    class="slds-icon answer-content__link-icon-svg"
+    aria-hidden="true"
+    focusable="false"
+    viewBox="0 0 52 52"
+  >
+    <path d="M48.5 2h-15c-.8 0-1.5.7-1.5 1.5v3c0 .8.7 1.5 1.5 1.5h6.4L22.1 25.8c-.6.6-.6 1.5 0 2.1l2.1 2.1c.6.6 1.5.6 2.1 0L44 12.3v6.2c0 .8.7 1.5 1.5 1.5h3c.8 0 1.5-.7 1.5-1.5v-15c0-.8-.7-1.5-1.5-1.5z"></path>
+    <path d="M38 28.5V46H8V16h17.5c.8 0 1.5-.7 1.5-1.5v-3c0-.8-.7-1.5-1.5-1.5H6c-2.2 0-4 1.8-4 4v34c0 2.2 1.8 4 4 4h34c2.2 0 4-1.8 4-4V28.5c0-.8-.7-1.5-1.5-1.5h-3c-.8 0-1.5.7-1.5 1.5z"></path>
+  </svg>
+`;
+
 /**
  * The `QuanticGeneratedAnswerContent` component displays the generated answer content.
  * @category Internal
@@ -16,6 +37,18 @@ import generatedTextContentTemplate from './templates/generatedTextContent.html'
  * <c-quantic-generated-answer-content answer-content-format={answerContentFormat} answer={answer} is-streaming={isStreaming}></c-quantic-generated-answer-content>
  */
 export default class QuanticGeneratedAnswerContent extends LightningElement {
+  /**
+   * The ID of the engine instance the component registers to.
+   * @api
+   * @type {string}
+   */
+  @api engineId;
+  /**
+   * The unique identifier of the generated answer.
+   * @api
+   * @type {string}
+   */
+  @api answerId;
   /**
    * If the answer is streaming, it will render a blinking cursor at the end of the answer.
    * @api
@@ -65,6 +98,32 @@ export default class QuanticGeneratedAnswerContent extends LightningElement {
   /** @type {'text/plain' | 'text/markdown'} */
   _answerContentFormat = 'text/plain';
   _markdownDependenciesLoaded = false;
+  /** @type {Array<function>} */
+  _inlineLinkBindings = [];
+  /** @type {AnyHeadless} */
+  headless;
+  /** @type {SearchEngine | InsightEngine} */
+  engine;
+
+  connectedCallback() {
+    registerComponentForInit(this, this.engineId);
+  }
+
+  renderedCallback() {
+    initializeWithHeadless(this, this.engineId, this.initialize);
+  }
+
+  /**
+   * @param {SearchEngine | InsightEngine} engine
+   */
+  initialize = (engine) => {
+    this.headless = getHeadlessBundle(this.engineId);
+    this.engine = engine;
+  };
+
+  disconnectedCallback() {
+    this.cleanUpInlineLinkBindings();
+  }
 
   loadMarkdownDependencies() {
     if (
@@ -105,6 +164,7 @@ export default class QuanticGeneratedAnswerContent extends LightningElement {
           // eslint-disable-next-line @lwc/lwc/no-inner-html
           answerContainer.innerHTML = newHTMLContent;
         }
+        this.processInlineLinks(answerContainer);
       }
     }
     // Fallback to display answer as text if the Marked library failed to load
@@ -114,6 +174,82 @@ export default class QuanticGeneratedAnswerContent extends LightningElement {
     this.dispatchEvent(new CustomEvent('quantic__answercontentupdated'));
   }
 
+  /**
+   * Decorates each inline link with an icon and binds analytics, replacing any previous bindings.
+   * @param {Element|null} answerContainer
+   */
+  processInlineLinks(answerContainer) {
+    if (!answerContainer) {
+      return;
+    }
+    this.cleanUpInlineLinkBindings();
+    /** @type {NodeListOf<HTMLAnchorElement>} */
+    const anchors = answerContainer.querySelectorAll(
+      'a[data-answer-inline-link]'
+    );
+    anchors.forEach((anchor) => {
+      anchor.target = '_blank';
+      anchor.rel = 'noopener';
+      this.bindAnalyticsToInlineLink(anchor);
+      this.appendInlineLinkIcon(anchor);
+    });
+  }
+
+  /**
+   * Appends the external link icon to the given anchor.
+   * @param {HTMLAnchorElement} anchor
+   */
+  appendInlineLinkIcon(anchor) {
+    const icon = document.createElement('span');
+    icon.classList.add(
+      'slds-icon_container',
+      'slds-icon-utility-new_window',
+      'slds-current-color',
+      'slds-m-left_xxx-small',
+      'answer-content__link-icon'
+    );
+    // eslint-disable-next-line @lwc/lwc/no-inner-html
+    icon.innerHTML = INLINE_LINK_ICON;
+    anchor.appendChild(icon);
+  }
+
+  /**
+   * Creates an `InteractiveGeneratedAnswerInlineLink` controller for the given anchor
+   * and binds analytics event listeners to it.
+   * @param {HTMLAnchorElement} anchor
+   */
+  bindAnalyticsToInlineLink(anchor) {
+    if (
+      !this.headless?.buildInteractiveGeneratedAnswerInlineLink ||
+      !this.engine
+    ) {
+      return;
+    }
+    const controller = this.headless.buildInteractiveGeneratedAnswerInlineLink(
+      this.engine,
+      {
+        options: {
+          link: {
+            linkURL: anchor.getAttribute('href') || '',
+            linkText: anchor.textContent?.trim() || '',
+          },
+          answerId: this.answerId,
+        },
+      }
+    );
+    this._inlineLinkBindings.push(
+      LinkUtils.bindAnalyticsToLink(anchor, controller)
+    );
+  }
+
+  /**
+   * Cleans up all inline link bindings.
+   */
+  cleanUpInlineLinkBindings() {
+    this._inlineLinkBindings.forEach((remove) => remove());
+    this._inlineLinkBindings = [];
+  }
+
   get generatedAnswerContentClass() {
     return `generated-answer-content__answer ${this.isStreaming ? 'generated-answer-content__answer--streaming' : ''}`;
   }

package/force-app/main/default/lwc/quanticGeneratedAnswerContent/templates/generatedMarkdownContent.css

@@ -152,3 +152,13 @@ tbody tr td:first-of-type {
 tbody tr td:last-of-type td {
   border-bottom: unset;
 }
+
+.answer-content__link-icon-svg {
+  width: 0.625rem;
+  height: 0.625rem;
+  fill: currentColor;
+}
+
+.answer-content__link-icon {
+  display: inline-flex;
+}

package/force-app/main/default/lwc/quanticUtils/__tests__/accessibilityUtils.test.js

@@ -0,0 +1,214 @@
+import {
+  AriaLiveRegion,
+  isFocusable,
+  getFirstFocusableElement,
+  getLastFocusableElement,
+  isCustomElement,
+  isParentOf,
+} from 'c/quanticUtils';
+
+describe('accessibilityUtils', () => {
+  describe('AriaLiveRegion', () => {
+    let elem;
+
+    beforeEach(() => {
+      elem = {dispatchEvent: jest.fn()};
+    });
+
+    it('should dispatch a register region event on creation', () => {
+      AriaLiveRegion('test-region', elem);
+      expect(elem.dispatchEvent).toHaveBeenCalledTimes(1);
+      const event = elem.dispatchEvent.mock.calls[0][0];
+      expect(event.type).toBe('quantic__registerregion');
+      expect(event.detail).toEqual({
+        regionName: 'test-region',
+        assertive: false,
+      });
+    });
+
+    it('should dispatch a register region event with assertive flag', () => {
+      AriaLiveRegion('test-region', elem, true);
+      const event = elem.dispatchEvent.mock.calls[0][0];
+      expect(event.detail.assertive).toBe(true);
+    });
+
+    it('should dispatch an aria live message event when dispatchMessage is called', () => {
+      const region = AriaLiveRegion('test-region', elem);
+      region.dispatchMessage('hello');
+      expect(elem.dispatchEvent).toHaveBeenCalledTimes(2);
+      const event = elem.dispatchEvent.mock.calls[1][0];
+      expect(event.type).toBe('quantic__arialivemessage');
+      expect(event.detail).toEqual({
+        regionName: 'test-region',
+        assertive: false,
+        message: 'hello',
+      });
+    });
+  });
+
+  describe('isFocusable', () => {
+    function createElement(tag, attrs = {}) {
+      const el = document.createElement(tag);
+      Object.entries(attrs).forEach(([k, v]) => el.setAttribute(k, v));
+      return el;
+    }
+
+    it('should return true for a button', () => {
+      expect(isFocusable(createElement('button'))).toBe(true);
+    });
+
+    it('should return false for a disabled button', () => {
+      expect(isFocusable(createElement('button', {disabled: ''}))).toBe(false);
+    });
+
+    it('should return true for an anchor with href', () => {
+      expect(isFocusable(createElement('a', {href: '#'}))).toBe(true);
+    });
+
+    it('should return false for an anchor without href', () => {
+      expect(isFocusable(createElement('a'))).toBe(false);
+    });
+
+    it('should return true for an input', () => {
+      expect(isFocusable(createElement('input'))).toBe(true);
+    });
+
+    it('should return false for a disabled input', () => {
+      expect(isFocusable(createElement('input', {disabled: ''}))).toBe(false);
+    });
+
+    it('should return true for an element with tabindex >= 0', () => {
+      expect(isFocusable(createElement('div', {tabindex: '0'}))).toBe(true);
+    });
+
+    it('should return false for an element with tabindex -1', () => {
+      expect(isFocusable(createElement('div', {tabindex: '-1'}))).toBe(false);
+    });
+
+    it('should return true for a contentEditable element', () => {
+      expect(isFocusable(createElement('div', {contentEditable: 'true'}))).toBe(
+        true
+      );
+    });
+
+    it('should return false for a plain div', () => {
+      expect(isFocusable(createElement('div'))).toBe(false);
+    });
+
+    it('should return true for an iframe', () => {
+      expect(isFocusable(createElement('iframe'))).toBe(true);
+    });
+
+    it('should return true for a select', () => {
+      expect(isFocusable(createElement('select'))).toBe(true);
+    });
+
+    it('should return true for a textarea', () => {
+      expect(isFocusable(createElement('textarea'))).toBe(true);
+    });
+  });
+
+  describe('isCustomElement', () => {
+    it('should return true for elements with a hyphen in the tag name', () => {
+      const el = document.createElement('my-component');
+      expect(isCustomElement(el)).toBe(true);
+    });
+
+    it('should return false for standard elements', () => {
+      const el = document.createElement('div');
+      expect(isCustomElement(el)).toBe(false);
+    });
+
+    it('should return false for null', () => {
+      expect(isCustomElement(null)).toBe(false);
+    });
+  });
+
+  describe('getFirstFocusableElement', () => {
+    it('should return null for null input', () => {
+      expect(getFirstFocusableElement(null)).toBeNull();
+    });
+
+    it('should return the element itself if it is focusable and has no focusable children', () => {
+      const btn = document.createElement('button');
+      expect(getFirstFocusableElement(btn)).toBe(btn);
+    });
+
+    it('should return the first focusable child', () => {
+      const div = document.createElement('div');
+      const span = document.createElement('span');
+      const btn1 = document.createElement('button');
+      const btn2 = document.createElement('button');
+      div.appendChild(span);
+      div.appendChild(btn1);
+      div.appendChild(btn2);
+      expect(getFirstFocusableElement(div)).toBe(btn1);
+    });
+
+    it('should return null for a custom element without data-focusable', () => {
+      const el = document.createElement('my-component');
+      expect(getFirstFocusableElement(el)).toBeNull();
+    });
+
+    it('should return the custom element if data-focusable is true', () => {
+      const el = document.createElement('my-component');
+      el.dataset.focusable = 'true';
+      expect(getFirstFocusableElement(el)).toBe(el);
+    });
+
+    it('should return null for a text node', () => {
+      const text = document.createTextNode('hello');
+      expect(getFirstFocusableElement(text)).toBeNull();
+    });
+  });
+
+  describe('getLastFocusableElement', () => {
+    it('should return null for null input', () => {
+      expect(getLastFocusableElement(null)).toBeNull();
+    });
+
+    it('should return the last focusable child', () => {
+      const div = document.createElement('div');
+      const btn1 = document.createElement('button');
+      const btn2 = document.createElement('button');
+      div.appendChild(btn1);
+      div.appendChild(btn2);
+      expect(getLastFocusableElement(div)).toBe(btn2);
+    });
+
+    it('should return the element itself if it is focusable and has no focusable children', () => {
+      const input = document.createElement('input');
+      expect(getLastFocusableElement(input)).toBe(input);
+    });
+  });
+
+  describe('isParentOf', () => {
+    it('should return false for null', () => {
+      expect(isParentOf(null, 'MY-COMPONENT')).toBe(false);
+    });
+
+    it('should return true if the element itself matches the target tag', () => {
+      const el = document.createElement('my-component');
+      expect(isParentOf(el, 'MY-COMPONENT')).toBe(true);
+    });
+
+    it('should return true if a descendant matches the target tag', () => {
+      const wrapper = document.createElement('div');
+      const child = document.createElement('my-component');
+      wrapper.appendChild(child);
+      expect(isParentOf(wrapper, 'MY-COMPONENT')).toBe(true);
+    });
+
+    it('should return false if no descendant matches', () => {
+      const wrapper = document.createElement('div');
+      const child = document.createElement('span');
+      wrapper.appendChild(child);
+      expect(isParentOf(wrapper, 'MY-COMPONENT')).toBe(false);
+    });
+
+    it('should return false for a text node', () => {
+      const text = document.createTextNode('hello');
+      expect(isParentOf(text, 'MY-COMPONENT')).toBe(false);
+    });
+  });
+});

package/force-app/main/default/lwc/quanticUtils/__tests__/facetStoreUtils.test.js

@@ -0,0 +1,86 @@
+import {Store} from 'c/quanticUtils';
+
+describe('storeUtils', () => {
+  describe('Store.facetTypes', () => {
+    it('should expose the expected facet type keys', () => {
+      expect(Store.facetTypes).toEqual({
+        FACETS: 'facets',
+        NUMERICFACETS: 'numericFacets',
+        DATEFACETS: 'dateFacets',
+        CATEGORYFACETS: 'categoryFacets',
+      });
+    });
+  });
+
+  describe('Store.initialize', () => {
+    it('should return a store with empty state', () => {
+      const store = Store.initialize();
+      expect(store).toEqual({
+        state: {
+          facets: {},
+          numericFacets: {},
+          dateFacets: {},
+          categoryFacets: {},
+          sort: {},
+        },
+      });
+    });
+  });
+
+  describe('Store.registerFacetToStore', () => {
+    it('should register facet data under the given facet type and id', () => {
+      const store = Store.initialize();
+      const data = {facetId: 'author', label: 'Author'};
+      Store.registerFacetToStore(store, 'facets', data);
+      expect(store.state.facets.author).toEqual(data);
+    });
+
+    it('should not overwrite an existing facet entry', () => {
+      const store = Store.initialize();
+      const data = {facetId: 'author', label: 'Author'};
+      Store.registerFacetToStore(store, 'facets', data);
+      Store.registerFacetToStore(store, 'facets', {
+        facetId: 'author',
+        label: 'Updated',
+      });
+      expect(store.state.facets.author.label).toBe('Author');
+    });
+  });
+
+  describe('Store.registerSortOptionDataToStore', () => {
+    it('should set sort data on the store', () => {
+      const store = Store.initialize();
+      const sortData = [{label: 'Relevance', value: 'relevance'}];
+      Store.registerSortOptionDataToStore(store, sortData);
+      expect(store.state.sort).toBe(sortData);
+    });
+  });
+
+  describe('Store.getFromStore', () => {
+    it('should return facet data for the given type', () => {
+      const store = Store.initialize();
+      const data = {facetId: 'source', label: 'Source'};
+      Store.registerFacetToStore(store, 'facets', data);
+      expect(Store.getFromStore(store, 'facets')).toEqual({source: data});
+    });
+
+    it('should return an empty object when no facets are registered', () => {
+      const store = Store.initialize();
+      expect(Store.getFromStore(store, 'facets')).toEqual({});
+    });
+  });
+
+  describe('Store.getSortOptionsFromStore', () => {
+    it('should return the sort options', () => {
+      const store = Store.initialize();
+      const sortData = [{label: 'Date', value: 'date'}];
+      Store.registerSortOptionDataToStore(store, sortData);
+      expect(Store.getSortOptionsFromStore(store)).toBe(sortData);
+    });
+
+    it('should return an empty object when no sort options are registered', () => {
+      const store = Store.initialize();
+      expect(Store.getSortOptionsFromStore(store)).toEqual({});
+    });
+  });
+});

package/force-app/main/default/lwc/quanticUtils/__tests__/markdownUtils.test.js

@@ -67,5 +67,43 @@ describe('c/markdownUtils', () => {
       const resultCode = transformMarkdownToHtml(textCode, marked);
       expect(removeLineBreaks(resultCode)).toEqual('<p><code>code</code></p>');
     });
+
+    it('should transform markdown link to HTML <a> with data-answer-inline-link attribute', () => {
+      const text = '[Google](https://google.com)';
+      const result = transformMarkdownToHtml(text, marked);
+      expect(removeLineBreaks(result)).toEqual(
+        '<p><a href="https://google.com" data-answer-inline-link="true">Google</a></p>'
+      );
+    });
+
+    it('should transform markdown link with title to HTML <a> with title attribute', () => {
+      const text = '[Google](https://google.com "Search Engine")';
+      const result = transformMarkdownToHtml(text, marked);
+      expect(removeLineBreaks(result)).toEqual(
+        '<p><a href="https://google.com" title="Search Engine" data-answer-inline-link="true">Google</a></p>'
+      );
+    });
+
+    it('should escape special characters in link href', () => {
+      const text = '[Link](https://example.com?param="value"&other=test)';
+      const result = transformMarkdownToHtml(text, marked);
+      expect(removeLineBreaks(result)).toEqual(
+        '<p><a href="https://example.com?param=&quot;value&quot;&amp;other=test" data-answer-inline-link="true">Link</a></p>'
+      );
+    });
+
+    it('should escape special characters in link title', () => {
+      const text = '[Link](https://example.com "Title with <script> & quotes")';
+      const result = transformMarkdownToHtml(text, marked);
+      expect(removeLineBreaks(result)).toEqual(
+        '<p><a href="https://example.com" title="Title with &amp;lt;script&amp;gt; &amp;amp; quotes" data-answer-inline-link="true">Link</a></p>'
+      );
+    });
+
+    it('should render link text as span when href is missing', () => {
+      const text = '[Link]()';
+      const result = transformMarkdownToHtml(text, marked);
+      expect(removeLineBreaks(result)).toEqual('<p><span>Link</span></p>');
+    });
   });
 });