@coveo/quantic 3.40.0 → 3.41.0

package/force-app/main/default/labels/CustomLabels.labels-meta.xml

@@ -455,6 +455,13 @@
     <protected>false</protected>
     <shortDescription>Collapse [component label]</shortDescription>
   </labels>
+  <labels>
+    <fullName>quantic_CollapseButton</fullName>
+    <value>Collapse</value>
+    <language>en_US</language>
+    <protected>false</protected>
+    <shortDescription>Collapse</shortDescription>
+  </labels>
   <labels>
     <fullName>quantic_Expand</fullName>
     <value>Expand {{0}}</value>
@@ -1288,6 +1295,13 @@
     <protected>false</protected>
     <shortDescription>Something went wrong and we couldn't generate an answer.</shortDescription>
   </labels>
+  <labels>
+    <fullName>quantic_GeneratedAnswerErrorTurnLimitReached</fullName>
+    <value>Conversation turn limit reached. Please start a new conversation.</value>
+    <language>en_US</language>
+    <protected>false</protected>
+    <shortDescription>Generated answer conversation turn limit reached error.</shortDescription>
+  </labels>
   <labels>
     <fullName>quantic_ShowingResultsFor</fullName>
     <value>Showing results for {{0}}</value>
@@ -1638,4 +1652,67 @@
     <protected>false</protected>
     <shortDescription>Submit follow-up</shortDescription>
   </labels>
+  <labels>
+    <fullName>quantic_ShowPreviousQuestions_plural</fullName>
+    <value>Show {{0}} previous questions</value>
+    <language>en_US</language>
+    <protected>false</protected>
+    <shortDescription>Show previous questions (plural)</shortDescription>
+  </labels>
+  <labels>
+    <fullName>quantic_AgentGenerationStepAnalyzingQuestion</fullName>
+    <value>Analyzing your question…</value>
+    <language>en_US</language>
+    <protected>false</protected>
+    <shortDescription>Analyzing your question</shortDescription>
+  </labels>
+  <labels>
+    <fullName>quantic_AgentGenerationStepAnalyzingQuestionCompleted</fullName>
+    <value>Question analyzed</value>
+    <language>en_US</language>
+    <protected>false</protected>
+    <shortDescription>Question analyzed</shortDescription>
+  </labels>
+  <labels>
+    <fullName>quantic_AgentGenerationStepSearch</fullName>
+    <value>Searching knowledge base…</value>
+    <language>en_US</language>
+    <protected>false</protected>
+    <shortDescription>Searching knowledge base…</shortDescription>
+  </labels>
+  <labels>
+    <fullName>quantic_AgentGenerationStepSearchCompleted</fullName>
+    <value>Knowledge base searched</value>
+    <language>en_US</language>
+    <protected>false</protected>
+    <shortDescription>Knowledge base searched</shortDescription>
+  </labels>
+  <labels>
+    <fullName>quantic_AgentGenerationStepAnalyzingResults</fullName>
+    <value>Analyzing results…</value>
+    <language>en_US</language>
+    <protected>false</protected>
+    <shortDescription>Analyzing results…</shortDescription>
+  </labels>
+  <labels>
+    <fullName>quantic_AgentGenerationStepAnalyzingResultsCompleted</fullName>
+    <value>Results analyzed</value>
+    <language>en_US</language>
+    <protected>false</protected>
+    <shortDescription>Results analyzed</shortDescription>
+  </labels>
+  <labels>
+    <fullName>quantic_AgentGenerationStepAnswering</fullName>
+    <value>Generating answer…</value>
+    <language>en_US</language>
+    <protected>false</protected>
+    <shortDescription>Generating answer…</shortDescription>
+  </labels>
+  <labels>
+    <fullName>quantic_AgentGenerationStepAnsweringCompleted</fullName>
+    <value>Answer generated</value>
+    <language>en_US</language>
+    <protected>false</protected>
+    <shortDescription>Answer generated</shortDescription>
+  </labels>
 </CustomLabels>

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

@@ -0,0 +1,341 @@
+// @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',
+};
+
+const createTestComponent = buildCreateTestComponent(
+  QuanticGeneratedAnswerBody,
+  'c-quantic-generated-answer-body',
+  defaultOptions
+);
+
+describe('c-quantic-generated-answer-body', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it('should pass answer and answerContentFormat 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
+    );
+  });
+
+  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();
+    });
+
+    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,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>