@coveo/quantic 3.39.1 → 3.41.0

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

@@ -0,0 +1,148 @@
+import couldNotGenerateAnAnswer from '@salesforce/label/c.quantic_CouldNotGenerateAnAnswer';
+import generatedAnswerErrorTurnLimitReached from '@salesforce/label/c.quantic_GeneratedAnswerErrorTurnLimitReached';
+import genericErrorTitle from '@salesforce/label/c.quantic_GenericErrorTitle';
+import thisAnswerWasHelpful from '@salesforce/label/c.quantic_ThisAnswerWasHelpful';
+import thisAnswerWasNotHelpful from '@salesforce/label/c.quantic_ThisAnswerWasNotHelpful';
+import {LightningElement, api} from 'lwc';
+// @ts-ignore
+import answerTemplate from './templates/answer.html';
+// @ts-ignore
+import cannotAnswerTemplate from './templates/cannotAnswer.html';
+// @ts-ignore
+import errorTemplate from './templates/error.html';
+
+/** @typedef {import("@coveo/headless").GeneratedAnswerBase} GeneratedAnswerBase */
+
+const FEEDBACK_NEUTRAL_STATE = 'neutral';
+const FEEDBACK_LIKED_STATE = 'liked';
+const FEEDBACK_DISLIKED_STATE = 'disliked';
+
+/**
+ * The `QuanticGeneratedAnswerBody` component renders a single generated answer unit.
+ * @category Internal
+ * @fires CustomEvent#quantic__generatedanswerlike
+ * @fires CustomEvent#quantic__generatedanswerdislike
+ * @fires CustomEvent#quantic__generatedanswercopy
+ * @fires CustomEvent#quantic__citationhover
+ */
+export default class QuanticGeneratedAnswerBody extends LightningElement {
+  /**
+   * The ID of the engine instance the component registers to.
+   * @api
+   * @type {string}
+   */
+  @api engineId;
+  /**
+   * The generated answer object to render.
+   * @api
+   * @type {GeneratedAnswerBase}
+   */
+  @api generatedAnswer;
+  /**
+   * Whether to disable citation anchoring.
+   * @api
+   * @type {boolean}
+   */
+  @api disableCitationAnchoring = false;
+
+  labels = {
+    couldNotGenerateAnAnswer,
+    generatedAnswerErrorTurnLimitReached,
+    genericErrorTitle,
+    thisAnswerWasHelpful,
+    thisAnswerWasNotHelpful,
+  };
+
+  get answer() {
+    return this.generatedAnswer?.answer;
+  }
+
+  get citations() {
+    return this.generatedAnswer?.citations || [];
+  }
+
+  get answerId() {
+    return this.generatedAnswer?.answerId;
+  }
+
+  get answerContentFormat() {
+    return this.generatedAnswer?.answerContentFormat;
+  }
+
+  get isStreaming() {
+    return !!this.generatedAnswer?.isStreaming;
+  }
+
+  get hasError() {
+    return !!this.generatedAnswer?.error?.code;
+  }
+
+  get cannotAnswer() {
+    return !!this.generatedAnswer?.cannotAnswer;
+  }
+
+  get errorMessage() {
+    if (this.generatedAnswer?.error?.isSseTurnLimitReachedError?.()) {
+      return this.labels.generatedAnswerErrorTurnLimitReached;
+    }
+    return this.labels.genericErrorTitle;
+  }
+
+  get computedFeedbackState() {
+    if (this.generatedAnswer?.liked) {
+      return FEEDBACK_LIKED_STATE;
+    }
+    if (this.generatedAnswer?.disliked) {
+      return FEEDBACK_DISLIKED_STATE;
+    }
+    return FEEDBACK_NEUTRAL_STATE;
+  }
+
+  get shouldShowCitations() {
+    return this.citations.length > 0 && !this.isStreaming;
+  }
+
+  get shouldShowActions() {
+    return Boolean(this.answer) && !this.isStreaming;
+  }
+
+  handleLike(event) {
+    event.stopPropagation();
+    this.dispatchAnswerInteractionEvent('quantic__generatedanswerlike');
+  }
+
+  handleDislike(event) {
+    event.stopPropagation();
+    this.dispatchAnswerInteractionEvent('quantic__generatedanswerdislike');
+  }
+
+  handleCitationHover = (citationId, citationHoverTimeMs) => {
+    this.dispatchAnswerInteractionEvent('quantic__citationhover', {
+      citationId,
+      citationHoverTimeMs,
+    });
+  };
+
+  dispatchAnswerInteractionEvent(eventName, payload = {}) {
+    this.dispatchEvent(
+      new CustomEvent(eventName, {
+        detail: {
+          answerId: this.answerId,
+          ...payload,
+        },
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
+  render() {
+    if (this.hasError) {
+      return errorTemplate;
+    }
+    if (this.cannotAnswer) {
+      return cannotAnswerTemplate;
+    }
+    return answerTemplate;
+  }
+}

package/force-app/main/default/lwc/quanticGeneratedAnswerBody/quanticGeneratedAnswerBody.js-meta.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
+    <apiVersion>65.0</apiVersion>
+    <isExposed>false</isExposed>
+</LightningComponentBundle>

package/force-app/main/default/lwc/quanticGeneratedAnswerBody/templates/answer.css

@@ -0,0 +1,3 @@
+.generated-answer__body {
+  overflow-wrap: break-word;
+}

package/force-app/main/default/lwc/quanticGeneratedAnswerBody/templates/answer.html

@@ -0,0 +1,53 @@
+<template>
+  <section
+    data-testid="generated-answer-body"
+    class="generated-answer__body"
+  >
+    <c-quantic-generated-answer-content
+      answer-content-format={answerContentFormat}
+      answer={answer}
+      is-streaming={isStreaming}
+    >
+    </c-quantic-generated-answer-content>
+    <div class="slds-grid slds-grid_vertical">
+      <template lwc:if={shouldShowCitations}>
+        <div class="slds-size_1-of-1 slds-var-m-top_x-small">
+          <c-quantic-source-citations
+            data-testid="generated-answer-body__citations"
+            engine-id={engineId}
+            citations={citations}
+            citation-hover-handler={handleCitationHover}
+            disable-citation-anchoring={disableCitationAnchoring}
+          ></c-quantic-source-citations>
+        </div>
+      </template>
+      <template lwc:if={shouldShowActions}>
+        <div
+          data-testid="generated-answer-body__actions"
+          class="slds-size_1-of-1 slds-grid slds-grid_vertical-align-center slds-var-m-top_x-small slds-grid_align-start"
+        >
+            <c-quantic-feedback
+              state={computedFeedbackState}
+              onquantic__like={handleLike}
+              onquantic__dislike={handleDislike}
+              like-icon-name="utility:like"
+              like-label={labels.thisAnswerWasHelpful}
+              dislike-icon-name="utility:dislike"
+              dislike-label={labels.thisAnswerWasNotHelpful}
+              size="x-small"
+              question=""
+              hide-explain-why-button
+              hide-labels
+            ></c-quantic-feedback>
+            <c-quantic-generated-answer-copy-to-clipboard
+              data-testid="generated-answer-body__copy-to-clipboard"
+              answer={answer}
+              answer-id={answerId}
+              size="x-small"
+              class="slds-var-m-horizontal_xx-small"
+            ></c-quantic-generated-answer-copy-to-clipboard>
+        </div>
+      </template>
+    </div>
+  </section>
+</template>

package/force-app/main/default/lwc/quanticGeneratedAnswerBody/templates/cannotAnswer.html

@@ -0,0 +1,7 @@
+<template>
+  <section
+    data-testid="generated-answer-body__no-answer-message"
+  >
+    <div>{labels.couldNotGenerateAnAnswer}</div>
+  </section>
+</template>

package/force-app/main/default/lwc/quanticGeneratedAnswerBody/templates/error.html

@@ -0,0 +1,7 @@
+<template>
+  <section
+    data-testid="generated-answer-body__error"
+  >
+    <p>{errorMessage}</p>
+  </section>
+</template>

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

@@ -1,8 +1,11 @@
+/* eslint-disable no-import-assign */
 // @ts-ignore
 import QuanticGeneratedAnswerContent from 'c/quanticGeneratedAnswerContent';
 import {createElement} from 'lwc';
 import {loadMarkdownDependencies} from 'c/quanticUtils';
+import * as mockHeadlessLoader from 'c/quanticHeadlessLoader';
 
+jest.mock('c/quanticHeadlessLoader');
 jest.mock('c/quanticUtils', () => ({
   loadMarkdownDependencies: jest.fn(
     () =>
@@ -11,6 +14,9 @@ jest.mock('c/quanticUtils', () => ({
       })
   ),
   transformMarkdownToHtml: jest.fn((value) => value),
+  LinkUtils: {
+    bindAnalyticsToLink: jest.fn(() => jest.fn()),
+  },
 }));
 
 const mockMarkedUse = jest.fn();
@@ -23,14 +29,47 @@ global.marked = {
 const SELECTORS = {
   textAnswerContainer: 'span.generated-answer-content__answer',
   markdownAnswerContainer: 'div.generated-answer-content__answer',
+  inlineLink: 'a[data-answer-inline-link]',
+  inlineLinkIconContainer: 'span.slds-icon_container',
+  inlineLinkIconSvg: 'svg.slds-icon',
 };
 
+const exampleEngineId = 'example-engine-id';
+const exampleAnswerId = 'example-answer-id';
+
 const defaultOptions = {
   isStreaming: false,
   answerContentFormat: 'text/plain',
   answer: '',
 };
 
+const exampleEngine = {id: 'dummy-engine'};
+let isInitialized = false;
+
+const mockBuildInteractiveGeneratedAnswerInlineLink = jest.fn(() => ({
+  select: jest.fn(),
+  beginDelayedSelect: jest.fn(),
+  cancelPendingSelect: jest.fn(),
+}));
+
+function prepareHeadlessState() {
+  // @ts-ignore
+  mockHeadlessLoader.getHeadlessBundle = () => ({
+    buildInteractiveGeneratedAnswerInlineLink:
+      mockBuildInteractiveGeneratedAnswerInlineLink,
+  });
+}
+
+function mockSuccessfulHeadlessInitialization() {
+  // @ts-ignore
+  mockHeadlessLoader.initializeWithHeadless = (element, _, initialize) => {
+    if (element instanceof QuanticGeneratedAnswerContent && !isInitialized) {
+      isInitialized = true;
+      initialize(exampleEngine);
+    }
+  };
+}
+
 function createTestComponent(options = defaultOptions) {
   const element = createElement('c-quantic-generated-answer-content', {
     is: QuanticGeneratedAnswerContent,
@@ -43,6 +82,20 @@ function createTestComponent(options = defaultOptions) {
   return element;
 }
 
+/**
+ * Builds an HTML string containing anchor tags with the data-answer-inline-link
+ * attribute, which is what the component's processInlineLinks method targets.
+ * @param {Array<{href: string, text: string}>} links
+ * @returns {string}
+ */
+function buildAnswerWithInlineLinks(links) {
+  return links
+    .map(
+      ({href, text}) => `<a href="${href}" data-answer-inline-link>${text}</a>`
+    )
+    .join(' ');
+}
+
 // Helper function to wait until the microtask queue is empty.
 function flushPromises() {
   // eslint-disable-next-line @lwc/lwc/no-async-operation
@@ -56,6 +109,7 @@ describe('c-quantic-generated-answer-content', () => {
       document.body.removeChild(document.body.firstChild);
     }
     jest.clearAllMocks();
+    isInitialized = false;
   }
 
   afterEach(() => {
@@ -148,4 +202,219 @@ describe('c-quantic-generated-answer-content', () => {
       expect(loadMarkdownDependencies).toHaveBeenCalled();
     });
   });
+
+  describe('inline links in a markdown answer', () => {
+    const exampleLinks = [
+      {href: 'https://example.com/1', text: 'Link one'},
+      {href: 'https://example.com/2', text: 'Link two'},
+    ];
+
+    beforeEach(() => {
+      mockSuccessfulHeadlessInitialization();
+      prepareHeadlessState();
+    });
+
+    describe('when the answer contains anchors with data-answer-inline-link', () => {
+      it('should set target="_blank" and append an icon span to each inline link anchor', async () => {
+        const {LinkUtils} = jest.requireMock('c/quanticUtils');
+        LinkUtils.bindAnalyticsToLink.mockReturnValue(jest.fn());
+
+        const element = createTestComponent({
+          ...defaultOptions,
+          engineId: exampleEngineId,
+          answerId: exampleAnswerId,
+          answerContentFormat: 'text/markdown',
+          answer: buildAnswerWithInlineLinks(exampleLinks),
+        });
+        await flushPromises();
+
+        const answerContainer = element.shadowRoot.querySelector(
+          SELECTORS.markdownAnswerContainer
+        );
+        const anchors = answerContainer.querySelectorAll(SELECTORS.inlineLink);
+
+        expect(anchors).toHaveLength(exampleLinks.length);
+        anchors.forEach((anchor) => {
+          expect(anchor.target).toBe('_blank');
+        });
+        anchors.forEach((anchor) => {
+          const iconSpan = anchor.querySelector(
+            SELECTORS.inlineLinkIconContainer
+          );
+          expect(iconSpan).not.toBeNull();
+          expect(iconSpan.classList).toContain('slds-icon-utility-new_window');
+          expect(iconSpan.classList).toContain('slds-current-color');
+          expect(
+            iconSpan.querySelector(SELECTORS.inlineLinkIconSvg)
+          ).not.toBeNull();
+        });
+      });
+
+      it('should call buildInteractiveGeneratedAnswerInlineLink with the correct parameters for each inline link', async () => {
+        const {LinkUtils} = jest.requireMock('c/quanticUtils');
+        LinkUtils.bindAnalyticsToLink.mockReturnValue(jest.fn());
+
+        createTestComponent({
+          ...defaultOptions,
+          engineId: exampleEngineId,
+          answerId: exampleAnswerId,
+          answerContentFormat: 'text/markdown',
+          answer: buildAnswerWithInlineLinks(exampleLinks),
+        });
+        await flushPromises();
+
+        expect(
+          mockBuildInteractiveGeneratedAnswerInlineLink
+        ).toHaveBeenCalledTimes(exampleLinks.length);
+        expect(LinkUtils.bindAnalyticsToLink).toHaveBeenCalledTimes(
+          exampleLinks.length
+        );
+
+        exampleLinks.forEach((anchor, index) => {
+          expect(
+            mockBuildInteractiveGeneratedAnswerInlineLink
+          ).toHaveBeenNthCalledWith(index + 1, exampleEngine, {
+            options: {
+              link: {
+                linkURL: anchor.href,
+                linkText: anchor.text,
+              },
+              answerId: exampleAnswerId,
+            },
+          });
+        });
+      });
+
+      it('should call LinkUtils.bindAnalyticsToLink for each inline link with the anchor and its controller', async () => {
+        const {LinkUtils} = jest.requireMock('c/quanticUtils');
+        const mockUnbind = jest.fn();
+        LinkUtils.bindAnalyticsToLink.mockReturnValue(mockUnbind);
+
+        const element = createTestComponent({
+          ...defaultOptions,
+          engineId: exampleEngineId,
+          answerId: exampleAnswerId,
+          answerContentFormat: 'text/markdown',
+          answer: buildAnswerWithInlineLinks(exampleLinks),
+        });
+        await flushPromises();
+
+        expect(LinkUtils.bindAnalyticsToLink).toHaveBeenCalledTimes(
+          exampleLinks.length
+        );
+
+        const answerContainer = element.shadowRoot.querySelector(
+          SELECTORS.markdownAnswerContainer
+        );
+        const anchors = Array.from(
+          answerContainer.querySelectorAll(SELECTORS.inlineLink)
+        );
+
+        anchors.forEach((anchor, index) => {
+          expect(LinkUtils.bindAnalyticsToLink).toHaveBeenNthCalledWith(
+            index + 1,
+            anchor,
+            expect.objectContaining({
+              select: expect.any(Function),
+              beginDelayedSelect: expect.any(Function),
+              cancelPendingSelect: expect.any(Function),
+            })
+          );
+        });
+      });
+    });
+
+    describe('when the answer does not contain anchors with data-answer-inline-link', () => {
+      it('should not call buildInteractiveGeneratedAnswerInlineLink and LinkUtils.bindAnalyticsToLink', async () => {
+        const {LinkUtils} = jest.requireMock('c/quanticUtils');
+
+        createTestComponent({
+          ...defaultOptions,
+          engineId: exampleEngineId,
+          answerId: exampleAnswerId,
+          answerContentFormat: 'text/markdown',
+          answer: '<p>No inline links here</p>',
+        });
+        await flushPromises();
+
+        expect(
+          mockBuildInteractiveGeneratedAnswerInlineLink
+        ).not.toHaveBeenCalled();
+        expect(LinkUtils.bindAnalyticsToLink).not.toHaveBeenCalled();
+      });
+    });
+
+    describe('when the headless bundle does not expose buildInteractiveGeneratedAnswerInlineLink', () => {
+      it('should not throw and should not call LinkUtils.bindAnalyticsToLink', async () => {
+        // @ts-ignore
+        mockHeadlessLoader.getHeadlessBundle = () => ({});
+        const {LinkUtils} = jest.requireMock('c/quanticUtils');
+
+        expect(() => {
+          createTestComponent({
+            ...defaultOptions,
+            engineId: exampleEngineId,
+            answerId: exampleAnswerId,
+            answerContentFormat: 'text/markdown',
+            answer: buildAnswerWithInlineLinks(exampleLinks),
+          });
+        }).not.toThrow();
+
+        await flushPromises();
+
+        expect(LinkUtils.bindAnalyticsToLink).not.toHaveBeenCalled();
+      });
+    });
+
+    describe('when the answer is updated', () => {
+      it('should clean up previous inline link bindings before processing the new answer', async () => {
+        const {LinkUtils} = jest.requireMock('c/quanticUtils');
+        const mockUnbind = jest.fn();
+        LinkUtils.bindAnalyticsToLink.mockReturnValue(mockUnbind);
+
+        const element = createTestComponent({
+          ...defaultOptions,
+          engineId: exampleEngineId,
+          answerId: exampleAnswerId,
+          answerContentFormat: 'text/markdown',
+          answer: buildAnswerWithInlineLinks(exampleLinks),
+        });
+        await flushPromises();
+
+        expect(mockUnbind).not.toHaveBeenCalled();
+
+        const updatedLinks = [
+          {href: 'https://example.com/3', text: 'Link three'},
+        ];
+        element.answer = buildAnswerWithInlineLinks(updatedLinks);
+        await flushPromises();
+
+        expect(mockUnbind).toHaveBeenCalledTimes(exampleLinks.length);
+      });
+    });
+
+    describe('when the component is disconnected', () => {
+      it('should call the unbind function for each inline link binding', async () => {
+        const {LinkUtils} = jest.requireMock('c/quanticUtils');
+        const mockUnbind = jest.fn();
+        LinkUtils.bindAnalyticsToLink.mockReturnValue(mockUnbind);
+
+        const element = createTestComponent({
+          ...defaultOptions,
+          engineId: exampleEngineId,
+          answerId: exampleAnswerId,
+          answerContentFormat: 'text/markdown',
+          answer: buildAnswerWithInlineLinks(exampleLinks),
+        });
+        await flushPromises();
+
+        expect(mockUnbind).not.toHaveBeenCalled();
+
+        document.body.removeChild(element);
+        await flushPromises();
+
+        expect(mockUnbind).toHaveBeenCalledTimes(exampleLinks.length);
+      });
+    });
+  });
 });