@coveo/quantic 3.40.0 → 3.42.0

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

@@ -0,0 +1,379 @@
+// @ts-ignore
+import QuanticGeneratedAnswerBody from 'c/quanticGeneratedAnswerBody';
+import {buildCreateTestComponent, cleanup, flushPromises} from 'c/testUtils';
+
+jest.mock('c/quanticHeadlessLoader');
+jest.mock('c/quanticUtils', () => ({
+  loadMarkdownDependencies: jest.fn(() => Promise.resolve()),
+  transformMarkdownToHtml: jest.fn((answer) => answer),
+  LinkUtils: {
+    bindAnalyticsToLink: jest.fn(() => jest.fn()),
+  },
+  generateTextFragmentUrl: jest.fn((uri) => uri),
+}));
+jest.mock(
+  '@salesforce/label/c.quantic_CouldNotGenerateAnAnswer',
+  () => ({default: 'Could not generate an answer.'}),
+  {virtual: true}
+);
+jest.mock(
+  '@salesforce/label/c.quantic_GenericErrorTitle',
+  () => ({
+    default:
+      'Something went wrong while generating the answer. Please try again later.',
+  }),
+  {virtual: true}
+);
+jest.mock(
+  '@salesforce/label/c.quantic_GeneratedAnswerErrorTurnLimitReached',
+  () => ({
+    default:
+      'Conversation turn limit reached. Please start a new conversation.',
+  }),
+  {virtual: true}
+);
+jest.mock(
+  '@salesforce/label/c.quantic_ThisAnswerWasHelpful',
+  () => ({default: 'This answer was helpful'}),
+  {virtual: true}
+);
+jest.mock(
+  '@salesforce/label/c.quantic_ThisAnswerWasNotHelpful',
+  () => ({default: 'This answer was not helpful'}),
+  {virtual: true}
+);
+
+const defaultOptions = {
+  engineId: 'example-engine',
+  generatedAnswer: {
+    answerId: 'answer-1',
+    question: 'What is the meaning of life?',
+    answer: 'Example generated answer',
+    answerContentFormat: 'text/plain',
+    citations: [],
+    isStreaming: false,
+    liked: false,
+    disliked: false,
+    cannotAnswer: false,
+  },
+};
+
+const selectors = {
+  body: '[data-testid="generated-answer-body"]',
+  actions: '[data-testid="generated-answer-body__actions"]',
+  citations: 'c-quantic-source-citations',
+  feedback: 'c-quantic-feedback',
+  copy: 'c-quantic-generated-answer-copy-to-clipboard',
+  error: '[data-testid="generated-answer-body__error"]',
+  noAnswer: '[data-testid="generated-answer-body__no-answer-message"]',
+  content: 'c-quantic-generated-answer-content',
+  streamOfThought: 'c-quantic-generated-answer-stream-of-thought',
+};
+
+const createTestComponent = buildCreateTestComponent(
+  QuanticGeneratedAnswerBody,
+  'c-quantic-generated-answer-body',
+  defaultOptions
+);
+
+describe('c-quantic-generated-answer-body', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it('should pass the answer, answerContentFormat, engineId, and answerId properties to the QuanticGeneratedAnswerContent component', async () => {
+    const element = createTestComponent();
+    await flushPromises();
+
+    const content = element.shadowRoot.querySelector(selectors.content);
+
+    expect(content.answer).toBe(defaultOptions.generatedAnswer.answer);
+    expect(content.answerContentFormat).toBe(
+      defaultOptions.generatedAnswer.answerContentFormat
+    );
+    expect(content.engineId).toBe(defaultOptions.engineId);
+    expect(content.answerId).toBe(defaultOptions.generatedAnswer.answerId);
+  });
+
+  it('should pass agentSteps and isStreaming to the QuanticGeneratedAnswerStreamOfThought component', async () => {
+    const generationSteps = [{id: 'step-1'}, {id: 'step-2'}];
+    const element = createTestComponent({
+      ...defaultOptions,
+      generatedAnswer: {
+        ...defaultOptions.generatedAnswer,
+        // @ts-ignore
+        generationSteps,
+        isStreaming: true,
+      },
+    });
+    await flushPromises();
+
+    const streamOfThought = element.shadowRoot.querySelector(
+      selectors.streamOfThought
+    );
+
+    expect(streamOfThought).not.toBeNull();
+    expect(streamOfThought.agentSteps).toEqual(generationSteps);
+    expect(streamOfThought.isStreaming).toBe(true);
+  });
+
+  it('should pass an empty agentSteps array to QuanticGeneratedAnswerStreamOfThought when generationSteps is undefined', async () => {
+    const element = createTestComponent();
+    await flushPromises();
+
+    const streamOfThought = element.shadowRoot.querySelector(
+      selectors.streamOfThought
+    );
+
+    expect(streamOfThought).not.toBeNull();
+    expect(streamOfThought.agentSteps).toEqual([]);
+  });
+
+  it('should send the answerId within event details when dispatching the #quantic__generatedanswerlike event', async () => {
+    const element = createTestComponent();
+    const handler = jest.fn();
+    element.addEventListener('quantic__generatedanswerlike', handler);
+    await flushPromises();
+
+    const feedback = element.shadowRoot.querySelector(selectors.feedback);
+    feedback.dispatchEvent(new CustomEvent('quantic__like'));
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler.mock.calls[0][0].detail).toEqual({answerId: 'answer-1'});
+  });
+
+  it('should send the answerId within event details when dispatching the #quantic__generatedanswerdislike event', async () => {
+    const element = createTestComponent();
+    const handler = jest.fn();
+    element.addEventListener('quantic__generatedanswerdislike', handler);
+    await flushPromises();
+
+    const feedback = element.shadowRoot.querySelector(selectors.feedback);
+    feedback.dispatchEvent(new CustomEvent('quantic__dislike'));
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler.mock.calls[0][0].detail).toEqual({answerId: 'answer-1'});
+  });
+
+  it('should pass the answerId to the copy-to-clipboard component', async () => {
+    const element = createTestComponent();
+    await flushPromises();
+
+    const copy = element.shadowRoot.querySelector(selectors.copy);
+
+    expect(copy.answerId).toBe('answer-1');
+  });
+
+  it('should send the answerId within event details when dispatching the #quantic__citationhover event', async () => {
+    const element = createTestComponent({
+      ...defaultOptions,
+      generatedAnswer: {
+        ...defaultOptions.generatedAnswer,
+        // @ts-ignore
+        citations: [{id: 'citation-1', title: 'Citation'}],
+      },
+    });
+    const handler = jest.fn();
+    element.addEventListener('quantic__citationhover', handler);
+    await flushPromises();
+
+    const citations = element.shadowRoot.querySelector(
+      'c-quantic-source-citations'
+    );
+    citations.citationHoverHandler('citation-1', 1200);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler.mock.calls[0][0].detail).toEqual({
+      answerId: 'answer-1',
+      citationId: 'citation-1',
+      citationHoverTimeMs: 1200,
+    });
+  });
+
+  describe('when an answer has not been generated', () => {
+    it('should render the no-answer message when the answer cannot be generated', async () => {
+      const element = createTestComponent({
+        ...defaultOptions,
+        generatedAnswer: {
+          ...defaultOptions.generatedAnswer,
+          cannotAnswer: true,
+        },
+      });
+      await flushPromises();
+
+      const noAnswer = element.shadowRoot.querySelector(selectors.noAnswer);
+
+      expect(noAnswer).not.toBeNull();
+    });
+  });
+
+  describe('when an error occurs', () => {
+    it('should render the generic error message when a non-retryable error occurs', async () => {
+      const element = createTestComponent({
+        ...defaultOptions,
+        generatedAnswer: {
+          ...defaultOptions.generatedAnswer,
+          answer: '',
+          // @ts-ignore
+          error: {code: 500},
+        },
+      });
+      await flushPromises();
+
+      const error = element.shadowRoot.querySelector(selectors.error);
+
+      expect(error).not.toBeNull();
+      expect(error.textContent).toContain(
+        'Something went wrong while generating the answer. Please try again later.'
+      );
+    });
+
+    it('should render the turn limit reached error message when the SSE turn limit is exceeded', async () => {
+      const element = createTestComponent({
+        ...defaultOptions,
+        generatedAnswer: {
+          ...defaultOptions.generatedAnswer,
+          answer: '',
+          // @ts-ignore
+          error: {
+            code: 429,
+            isSseTurnLimitReachedError: () => true,
+          },
+        },
+      });
+      await flushPromises();
+
+      const error = element.shadowRoot.querySelector(selectors.error);
+
+      expect(error).not.toBeNull();
+      expect(error.textContent).toContain(
+        'Conversation turn limit reached. Please start a new conversation.'
+      );
+    });
+
+    it('should render the error message even when the answer is not empty', async () => {
+      const element = createTestComponent({
+        ...defaultOptions,
+        generatedAnswer: {
+          ...defaultOptions.generatedAnswer,
+          answer: 'Partial answer content',
+          // @ts-ignore
+          error: {code: 500},
+        },
+      });
+      await flushPromises();
+
+      const error = element.shadowRoot.querySelector(selectors.error);
+      const content = element.shadowRoot.querySelector(selectors.content);
+
+      expect(error).not.toBeNull();
+      expect(content).toBeNull();
+    });
+  });
+
+  describe('rendering of actions', () => {
+    it('should display actions when the answer is not empty and done streaming', async () => {
+      const element = createTestComponent();
+      await flushPromises();
+
+      const actions = element.shadowRoot.querySelector(selectors.actions);
+
+      expect(actions).not.toBeNull();
+    });
+
+    it('should not display actions while the answer is streaming', async () => {
+      const element = createTestComponent({
+        ...defaultOptions,
+        generatedAnswer: {
+          ...defaultOptions.generatedAnswer,
+          isStreaming: true,
+        },
+      });
+      await flushPromises();
+
+      const actions = element.shadowRoot.querySelector(selectors.actions);
+
+      expect(actions).toBeNull();
+    });
+
+    it('should not display actions when there is no answer', async () => {
+      const element = createTestComponent({
+        ...defaultOptions,
+        generatedAnswer: {
+          ...defaultOptions.generatedAnswer,
+          answer: '',
+        },
+      });
+      await flushPromises();
+
+      const actions = element.shadowRoot.querySelector(selectors.actions);
+
+      expect(actions).toBeNull();
+    });
+  });
+
+  describe('rendering of citations', () => {
+    it('should display citations when citations are not empty', async () => {
+      const element = createTestComponent({
+        ...defaultOptions,
+        generatedAnswer: {
+          ...defaultOptions.generatedAnswer,
+          // @ts-ignore
+          citations: [{id: 'citation-1', title: 'Citation'}],
+        },
+      });
+      await flushPromises();
+
+      const citations = element.shadowRoot.querySelector(selectors.citations);
+
+      expect(citations).not.toBeNull();
+      expect(citations.answerId).toBe(defaultOptions.generatedAnswer.answerId);
+    });
+
+    it('should not display citations when citations are empty', async () => {
+      const element = createTestComponent();
+      await flushPromises();
+
+      const citations = element.shadowRoot.querySelector(selectors.citations);
+
+      expect(citations).toBeNull();
+    });
+
+    it('should not display citations while the answer is streaming', async () => {
+      const element = createTestComponent({
+        ...defaultOptions,
+        generatedAnswer: {
+          ...defaultOptions.generatedAnswer,
+          // @ts-ignore
+          citations: [{id: 'citation-1', title: 'Citation'}],
+          isStreaming: true,
+        },
+      });
+      await flushPromises();
+
+      const citations = element.shadowRoot.querySelector(selectors.citations);
+
+      expect(citations).toBeNull();
+    });
+  });
+
+  describe('when generatedAnswer is null', () => {
+    it('should render without errors', async () => {
+      const element = createTestComponent({
+        ...defaultOptions,
+        generatedAnswer: null,
+      });
+      await flushPromises();
+
+      const error = element.shadowRoot.querySelector(selectors.error);
+      const noAnswer = element.shadowRoot.querySelector(selectors.noAnswer);
+      const actions = element.shadowRoot.querySelector(selectors.actions);
+      const citations = element.shadowRoot.querySelector(selectors.citations);
+
+      expect(error).toBeNull();
+      expect(noAnswer).toBeNull();
+      expect(actions).toBeNull();
+      expect(citations).toBeNull();
+    });
+  });
+});

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

@@ -0,0 +1,152 @@
+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 like from '@salesforce/label/c.quantic_Like';
+import dislike from '@salesforce/label/c.quantic_Dislike';
+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,
+    like,
+    dislike,
+  };
+
+  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 agentSteps() {
+    return this.generatedAnswer?.generationSteps || [];
+  }
+
+  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,59 @@
+<template>
+  <section data-testid="generated-answer-body" class="generated-answer__body">
+    <div class="slds-var-m-bottom_small">
+      <c-quantic-generated-answer-stream-of-thought
+        agent-steps={agentSteps}
+        is-streaming={isStreaming}
+      ></c-quantic-generated-answer-stream-of-thought>
+    </div>
+    <c-quantic-generated-answer-content
+      engine-id={engineId}
+      answer-id={answerId}
+      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}
+            answer-id={answerId}
+          ></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.like}
+            dislike-icon-name="utility:dislike"
+            dislike-label={labels.dislike}
+            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/quanticGeneratedAnswerCopyToClipboard/__tests__/quanticGeneratedAnswerCopyToClipboard.test.js

@@ -34,6 +34,7 @@ const selectors = {
 
 const defaultOptions = {
   answer: 'Example generated answer',
+  answerId: 'example-answer-id',
   size: defaultSize,
 };
 
@@ -109,7 +110,7 @@ describe('c-quantic-generated-answer-copy-to-clipboard', () => {
     expect(copyButton.iconSize).toBe(defaultSize);
   });
 
-  it('should copy the answer and dispatch the #quantic__generatedanswercopy event', async () => {
+  it('should copy the answer and dispatch the #quantic__generatedanswercopy event with the answerId', async () => {
     const element = createTestComponent();
     const handler = jest.fn();
     element.addEventListener('quantic__generatedanswercopy', handler);
@@ -121,5 +122,8 @@ describe('c-quantic-generated-answer-copy-to-clipboard', () => {
 
     expect(copyToClipboard).toHaveBeenCalledWith(defaultOptions.answer);
     expect(handler).toHaveBeenCalledTimes(1);
+    expect(handler.mock.calls[0][0].detail).toEqual({
+      answerId: defaultOptions.answerId,
+    });
   });
 });

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

@@ -15,6 +15,12 @@ export default class QuanticGeneratedAnswerCopyToClipboard extends LightningElem
    * @type {string}
    */
   @api answer = '';
+  /**
+   * The unique identifier of the generated answer.
+   * @api
+   * @type {string}
+   */
+  @api answerId;
 
   /**
    * The size of the copy icon.
@@ -41,11 +47,12 @@ export default class QuanticGeneratedAnswerCopyToClipboard extends LightningElem
   isSelected = false;
   tooltip = this.labels.copy;
 
-  dispatchCopyToClipboardEvent(option) {
+  dispatchCopyToClipboardEvent() {
     this.dispatchEvent(
       new CustomEvent('quantic__generatedanswercopy', {
-        detail: option,
+        detail: {answerId: this.answerId},
         bubbles: true,
+        composed: true,
       })
     );
   }