@coveo/quantic 3.39.1 → 3.41.0

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

@@ -0,0 +1,163 @@
+import analyzingQuestion from '@salesforce/label/c.quantic_AgentGenerationStepAnalyzingQuestion';
+import analyzingQuestionCompleted from '@salesforce/label/c.quantic_AgentGenerationStepAnalyzingQuestionCompleted';
+import search from '@salesforce/label/c.quantic_AgentGenerationStepSearch';
+import searchCompleted from '@salesforce/label/c.quantic_AgentGenerationStepSearchCompleted';
+import analyzingResults from '@salesforce/label/c.quantic_AgentGenerationStepAnalyzingResults';
+import analyzingResultsCompleted from '@salesforce/label/c.quantic_AgentGenerationStepAnalyzingResultsCompleted';
+import answering from '@salesforce/label/c.quantic_AgentGenerationStepAnswering';
+import answeringCompleted from '@salesforce/label/c.quantic_AgentGenerationStepAnsweringCompleted';
+import collapseButton from '@salesforce/label/c.quantic_CollapseButton';
+import loadingLabel from '@salesforce/label/c.quantic_Loading';
+import {LightningElement, api} from 'lwc';
+// @ts-ignore
+import streamOfThoughtTemplate from './templates/streamOfThought.html';
+// @ts-ignore
+import collapsedSummaryTemplate from './templates/collapsedSummary.html';
+
+/** @typedef {import("coveo").GenerationStep} GenerationStep */
+/** @typedef {'thinking-before-search'|'searching'|'thinking-after-search'|'answering'} ResolvedStepName */
+/**
+ * @typedef {Object} ResolvedStep
+ * @property {ResolvedStepName} name
+ * @property {'active'|'completed'} status
+ */
+
+/** @type {Record<string, {active: string, completed: string}>} */
+const STEP_LABEL_KEYS = {
+  'thinking-before-search': {
+    active: analyzingQuestion,
+    completed: analyzingQuestionCompleted,
+  },
+  searching: {
+    active: search,
+    completed: searchCompleted,
+  },
+  'thinking-after-search': {
+    active: analyzingResults,
+    completed: analyzingResultsCompleted,
+  },
+  answering: {
+    active: answering,
+    completed: answeringCompleted,
+  },
+};
+
+/**
+ * Maps an array of raw generation steps to resolved steps with a normalized type.
+ * @param {GenerationStep[]} steps
+ * @returns {ResolvedStep[]}
+ */
+export function resolveSteps(steps) {
+  let searchWasPerformed = false;
+  return steps.map((step) => {
+    /** @type {ResolvedStepName} */
+    let name;
+    if (step.name === 'searching') {
+      searchWasPerformed = true;
+      name = 'searching';
+    } else if (step.name === 'answering') {
+      name = 'answering';
+    } else {
+      name = searchWasPerformed
+        ? 'thinking-after-search'
+        : 'thinking-before-search';
+    }
+    return {name, status: step.status};
+  });
+}
+
+/**
+ * The `QuanticGeneratedAnswerStreamOfThought` component displays a timeline of agent reasoning
+ * steps during answer generation, showing real-time progress and completion status.
+ * @category Internal
+ * @example
+ * <c-quantic-generated-answer-stream-of-thought agent-steps={agentSteps} is-streaming={isStreaming}></c-quantic-generated-answer-stream-of-thought>
+ */
+export default class QuanticGeneratedAnswerStreamOfThought extends LightningElement {
+  /**
+   * Array of raw generation steps from the headless engine state.
+   * @api
+   * @type {GenerationStep[]}
+   * @default []
+   */
+  @api agentSteps = [];
+
+  /**
+   * Whether answer generation is currently active.
+   * @api
+   * @type {boolean}
+   * @default false
+   */
+  @api
+  get isStreaming() {
+    return this._isStreaming;
+  }
+  set isStreaming(value) {
+    this._isStreaming = value;
+    this._expanded = value;
+  }
+
+  /** @type {boolean} */
+  _isStreaming = false;
+  /** @type {boolean} */
+  _expanded = true;
+
+  labels = {
+    collapse: collapseButton,
+    loading: loadingLabel,
+  };
+
+  handleToggle = () => {
+    this._expanded = !this._expanded;
+  };
+
+  /** @returns {Array<{key: number, isActive: boolean, label: string}>} */
+  get stepsToDisplay() {
+    return this.steps.map((step, index) => {
+      const labelKey = STEP_LABEL_KEYS[step.name][step.status];
+      return {
+        key: index,
+        name: step.name,
+        isActive: step.status === 'active',
+        label: labelKey,
+      };
+    });
+  }
+
+  /** @returns {ResolvedStep[]} */
+  get steps() {
+    return resolveSteps(this.agentSteps ?? []);
+  }
+
+  /** @returns {boolean} */
+  get hasSteps() {
+    return this.steps.length > 0;
+  }
+
+  /** @returns {boolean} */
+  get isCollapsible() {
+    return this.steps.length > 1;
+  }
+
+  /** @returns {boolean} */
+  get shouldShowCollapsedSummary() {
+    return !this._isStreaming && !this._expanded && this.isCollapsible;
+  }
+
+  /** @returns {boolean} */
+  get shouldShowCollapseButton() {
+    return !this._isStreaming && this._expanded && this.isCollapsible;
+  }
+
+  /** @returns {string} */
+  get collapsedSummaryLabel() {
+    const lastStep = this.steps[this.steps.length - 1];
+    const labelKey = STEP_LABEL_KEYS[lastStep.name].completed;
+    return labelKey;
+  }
+
+  render() {
+    if (this.shouldShowCollapsedSummary) return collapsedSummaryTemplate;
+    return streamOfThoughtTemplate;
+  }
+}

package/force-app/main/default/lwc/quanticGeneratedAnswerStreamOfThought/quanticGeneratedAnswerStreamOfThought.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/quanticGeneratedAnswerStreamOfThought/templates/collapsedSummary.css

@@ -0,0 +1 @@
+@import '../quanticGeneratedAnswerStreamOfThought.css';

package/force-app/main/default/lwc/quanticGeneratedAnswerStreamOfThought/templates/collapsedSummary.html

@@ -0,0 +1,32 @@
+<template>
+  <button
+    data-testid="collapsed-summary"
+    class="stream-of-thought__collapsed-summary slds-grid slds-grid_vertical-align-center slds-p-around_none slds-m-vertical_xxx-small"
+    type="button"
+    aria-expanded={_expanded}
+    onclick={handleToggle}
+  >
+    <span
+      class="slds-m-right_x-small slds-grid slds-grid_align-center"
+      data-testid="checkmark"
+    >
+      <lightning-icon
+        icon-name="utility:check"
+        size="xx-small"
+        variant="success"
+        aria-hidden="true"
+      ></lightning-icon>
+    </span>
+    <span
+      class="slds-text-body_small slds-text-color_weak slds-m-right_x-small"
+      data-testid="collapsed-summary-label"
+      >{collapsedSummaryLabel}</span
+    >
+    <lightning-icon
+      data-testid="chevron-down"
+      icon-name="utility:chevrondown"
+      size="xx-small"
+      aria-hidden="true"
+    ></lightning-icon>
+  </button>
+</template>

package/force-app/main/default/lwc/quanticGeneratedAnswerStreamOfThought/templates/streamOfThought.css

@@ -0,0 +1 @@
+@import '../quanticGeneratedAnswerStreamOfThought.css';

package/force-app/main/default/lwc/quanticGeneratedAnswerStreamOfThought/templates/streamOfThought.html

@@ -0,0 +1,65 @@
+<template>
+  <template lwc:if={hasSteps}>
+    <div class="slds-grid slds-grid_vertical">
+      <template for:each={stepsToDisplay} for:item="step">
+        <div
+          key={step.key}
+          data-testid="step-item"
+          data-step-name={step.name}
+          class="slds-grid slds-grid_vertical-align-center slds-m-vertical_xxx-small"
+        >
+          <template lwc:if={step.isActive}>
+            <span
+              class="slds-is-relative slds-m-right_x-small slds-grid slds-grid_align-center stream-of-thought__spinner-container"
+              aria-hidden="true"
+              data-testid="spinner"
+            >
+              <lightning-spinner
+                alternative-text={labels.loading}
+                size="xx-small"
+              ></lightning-spinner>
+            </span>
+          </template>
+          <template lwc:else>
+            <span
+              class="slds-m-right_x-small slds-grid slds-grid_align-center"
+              data-testid="checkmark"
+            >
+              <lightning-icon
+                icon-name="utility:check"
+                size="xx-small"
+                variant="success"
+                aria-hidden="true"
+              ></lightning-icon>
+            </span>
+          </template>
+          <span
+            class="slds-text-body_small slds-text-color_weak"
+            data-testid="step-label"
+            >{step.label}</span
+          >
+        </div>
+      </template>
+      <template lwc:if={shouldShowCollapseButton}>
+        <button
+          data-testid="collapse-button"
+          class="stream-of-thought__collapse-button slds-grid slds-grid_vertical-align-center slds-p-around_none"
+          type="button"
+          aria-expanded={_expanded}
+          onclick={handleToggle}
+        >
+          <span
+            class="slds-text-body_small slds-text-color_weak slds-m-right_xx-small"
+            >{labels.collapse}</span
+          >
+          <lightning-icon
+            data-testid="chevron-up"
+            icon-name="utility:chevronup"
+            size="xx-small"
+            aria-hidden="true"
+          ></lightning-icon>
+        </button>
+      </template>
+    </div>
+  </template>
+</template>

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

@@ -0,0 +1,285 @@
+// @ts-ignore
+import QuanticGeneratedAnswerThread from '../quanticGeneratedAnswerThread';
+import {buildCreateTestComponent, cleanup, flushPromises} from 'c/testUtils';
+
+jest.mock('c/quanticUtils', () => ({
+  I18nUtils: {
+    format: jest.fn((label, count) => `Show ${count} previous questions`),
+  },
+}));
+jest.mock('c/quanticHeadlessLoader');
+
+jest.mock(
+  '@salesforce/label/c.quantic_ShowPreviousQuestions_plural',
+  () => ({default: 'Show {{0}} previous questions'}),
+  {virtual: true}
+);
+
+const selectors = {
+  generatedAnswerBody: 'c-quantic-generated-answer-body',
+  threadItem: 'c-quantic-thread-item',
+  showPreviousButton: '[data-testid="show-previous-button"]',
+  showPreviousDot: '[data-testid="show-previous-dot"]',
+};
+
+function buildGeneratedAnswer(overrides = {}) {
+  return {
+    answerId: `answer-${Math.random()}`,
+    question: 'What is Coveo?',
+    answer: 'Coveo is a search platform.',
+    citations: [],
+    isStreaming: false,
+    liked: false,
+    disliked: false,
+    ...overrides,
+  };
+}
+
+const createTestComponent = buildCreateTestComponent(
+  QuanticGeneratedAnswerThread,
+  'c-quantic-generated-answer-thread',
+  {
+    engineId: 'test-engine',
+    generatedAnswers: [],
+  }
+);
+
+describe('c-quantic-generated-answer-thread', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  describe('with a single answer', () => {
+    it('renders a single generated answer body without thread items', async () => {
+      const answers = [buildGeneratedAnswer()];
+      const element = createTestComponent({generatedAnswers: answers});
+      await flushPromises();
+
+      const body = element.shadowRoot.querySelectorAll(
+        selectors.generatedAnswerBody
+      );
+      expect(body).toHaveLength(1);
+
+      const threadItems = element.shadowRoot.querySelectorAll(
+        selectors.threadItem
+      );
+      expect(threadItems).toHaveLength(0);
+    });
+
+    it('does not render the show previous button', async () => {
+      const answers = [buildGeneratedAnswer()];
+      const element = createTestComponent({generatedAnswers: answers});
+      await flushPromises();
+
+      const button = element.shadowRoot.querySelector(
+        selectors.showPreviousButton
+      );
+      expect(button).toBeNull();
+    });
+  });
+
+  describe('with two answers', () => {
+    it('renders both answers in thread items', async () => {
+      const answers = [
+        buildGeneratedAnswer({answerId: 'a1', question: 'Q1'}),
+        buildGeneratedAnswer({answerId: 'a2', question: 'Q2'}),
+      ];
+      const element = createTestComponent({generatedAnswers: answers});
+      await flushPromises();
+
+      const threadItems = element.shadowRoot.querySelectorAll(
+        selectors.threadItem
+      );
+      expect(threadItems).toHaveLength(2);
+    });
+
+    it('does not render the show previous button', async () => {
+      const answers = [
+        buildGeneratedAnswer({answerId: 'a1'}),
+        buildGeneratedAnswer({answerId: 'a2'}),
+      ];
+      const element = createTestComponent({generatedAnswers: answers});
+      await flushPromises();
+
+      const button = element.shadowRoot.querySelector(
+        selectors.showPreviousButton
+      );
+      expect(button).toBeNull();
+    });
+
+    it('sets the last thread item as non-collapsible', async () => {
+      const answers = [
+        buildGeneratedAnswer({answerId: 'a1'}),
+        buildGeneratedAnswer({answerId: 'a2'}),
+      ];
+      const element = createTestComponent({generatedAnswers: answers});
+      await flushPromises();
+
+      const threadItems = element.shadowRoot.querySelectorAll(
+        selectors.threadItem
+      );
+      const lastItem = threadItems[threadItems.length - 1];
+      expect(lastItem.disableCollapse).toBe(true);
+      expect(lastItem.hideLine).toBe(true);
+    });
+
+    it('sets the first thread item as collapsible and collapsed', async () => {
+      const answers = [
+        buildGeneratedAnswer({answerId: 'a1'}),
+        buildGeneratedAnswer({answerId: 'a2'}),
+      ];
+      const element = createTestComponent({generatedAnswers: answers});
+      await flushPromises();
+
+      const threadItems = element.shadowRoot.querySelectorAll(
+        selectors.threadItem
+      );
+      const firstItem = threadItems[0];
+      expect(firstItem.disableCollapse).toBe(false);
+      expect(firstItem.isExpanded).toBe(false);
+      expect(firstItem.hideLine).toBe(false);
+    });
+  });
+
+  describe('with three or more answers', () => {
+    it('initially shows only the show previous button and the last answer', async () => {
+      const answers = [
+        buildGeneratedAnswer({answerId: 'a1', question: 'Q1'}),
+        buildGeneratedAnswer({answerId: 'a2', question: 'Q2'}),
+        buildGeneratedAnswer({answerId: 'a3', question: 'Q3'}),
+      ];
+      const element = createTestComponent({generatedAnswers: answers});
+      await flushPromises();
+
+      const button = element.shadowRoot.querySelector(
+        selectors.showPreviousButton
+      );
+      const dot = element.shadowRoot.querySelector(selectors.showPreviousDot);
+      expect(button).not.toBeNull();
+      expect(dot).not.toBeNull();
+
+      const threadItems = element.shadowRoot.querySelectorAll(
+        selectors.threadItem
+      );
+      expect(threadItems).toHaveLength(1);
+    });
+
+    it('reveals all previous answers when the show previous button is clicked', async () => {
+      const answers = [
+        buildGeneratedAnswer({answerId: 'a1', question: 'Q1'}),
+        buildGeneratedAnswer({answerId: 'a2', question: 'Q2'}),
+        buildGeneratedAnswer({answerId: 'a3', question: 'Q3'}),
+      ];
+      const element = createTestComponent({generatedAnswers: answers});
+      await flushPromises();
+
+      const button = element.shadowRoot.querySelector(
+        selectors.showPreviousButton
+      );
+      button.click();
+      await flushPromises();
+
+      const threadItems = element.shadowRoot.querySelectorAll(
+        selectors.threadItem
+      );
+      expect(threadItems).toHaveLength(3);
+
+      const showButton = element.shadowRoot.querySelector(
+        selectors.showPreviousButton
+      );
+      expect(showButton).toBeNull();
+    });
+
+    it('sets previous answers as collapsible and collapsed after expansion', async () => {
+      const answers = [
+        buildGeneratedAnswer({answerId: 'a1', question: 'Q1'}),
+        buildGeneratedAnswer({answerId: 'a2', question: 'Q2'}),
+        buildGeneratedAnswer({answerId: 'a3', question: 'Q3'}),
+      ];
+      const element = createTestComponent({generatedAnswers: answers});
+      await flushPromises();
+
+      element.shadowRoot.querySelector(selectors.showPreviousButton).click();
+      await flushPromises();
+
+      const threadItems = element.shadowRoot.querySelectorAll(
+        selectors.threadItem
+      );
+      const firstItem = threadItems[0];
+      const secondItem = threadItems[1];
+
+      expect(firstItem.disableCollapse).toBe(false);
+      expect(firstItem.isExpanded).toBe(false);
+      expect(secondItem.disableCollapse).toBe(false);
+      expect(secondItem.isExpanded).toBe(false);
+    });
+
+    it('keeps the last answer expanded and non-collapsible after expansion', async () => {
+      const answers = [
+        buildGeneratedAnswer({answerId: 'a1', question: 'Q1'}),
+        buildGeneratedAnswer({answerId: 'a2', question: 'Q2'}),
+        buildGeneratedAnswer({answerId: 'a3', question: 'Q3'}),
+      ];
+      const element = createTestComponent({generatedAnswers: answers});
+      await flushPromises();
+
+      element.shadowRoot.querySelector(selectors.showPreviousButton).click();
+      await flushPromises();
+
+      const threadItems = element.shadowRoot.querySelectorAll(
+        selectors.threadItem
+      );
+      const lastItem = threadItems[threadItems.length - 1];
+      expect(lastItem.disableCollapse).toBe(true);
+      expect(lastItem.hideLine).toBe(true);
+    });
+
+    it('re-collapses when a new follow-up answer is added', async () => {
+      const answers = [
+        buildGeneratedAnswer({answerId: 'a1', question: 'Q1'}),
+        buildGeneratedAnswer({answerId: 'a2', question: 'Q2'}),
+        buildGeneratedAnswer({answerId: 'a3', question: 'Q3'}),
+      ];
+      const element = createTestComponent({generatedAnswers: answers});
+      await flushPromises();
+
+      element.shadowRoot.querySelector(selectors.showPreviousButton).click();
+      await flushPromises();
+
+      expect(
+        element.shadowRoot.querySelector(selectors.showPreviousButton)
+      ).toBeNull();
+
+      element.generatedAnswers = [
+        ...answers,
+        buildGeneratedAnswer({answerId: 'a4', question: 'Q4'}),
+      ];
+      await flushPromises();
+
+      expect(
+        element.shadowRoot.querySelector(selectors.showPreviousButton)
+      ).not.toBeNull();
+      expect(
+        element.shadowRoot.querySelectorAll(selectors.threadItem)
+      ).toHaveLength(1);
+    });
+  });
+
+  describe('engine-id and citation anchoring passthrough', () => {
+    it('passes engineId and disableCitationAnchoring to generated answer body', async () => {
+      const answers = [buildGeneratedAnswer()];
+      const element = createTestComponent({
+        generatedAnswers: answers,
+        engineId: 'custom-engine',
+        disableCitationAnchoring: true,
+      });
+      await flushPromises();
+
+      const body = element.shadowRoot.querySelector(
+        selectors.generatedAnswerBody
+      );
+      expect(body.engineId).toBe('custom-engine');
+      expect(body.disableCitationAnchoring).toBe(true);
+    });
+  });
+});

package/force-app/main/default/lwc/quanticGeneratedAnswerThread/quanticGeneratedAnswerThread.css

@@ -0,0 +1,47 @@
+.generated-answer-thread__dot-column,
+.generated-answer-thread__line-column {
+  width: 10px;
+}
+
+.generated-answer-thread__dot {
+  height: 8px;
+  width: 8px;
+  border-radius: 50%;
+  background-color: var(--lwc-colorBorder, #dddbda);
+}
+
+.generated-answer-thread__connector {
+  position: relative;
+  width: 1px;
+  height: 100%;
+  min-height: 12px;
+  background-color: var(--lwc-colorBorder, #dddbda);
+}
+
+.generated-answer-thread__connector::before,
+.generated-answer-thread__connector::after {
+  content: '';
+  position: absolute;
+  left: 0;
+  width: 1px;
+  height: 8px;
+  background-color: var(--lwc-colorBorder, #dddbda);
+}
+
+.generated-answer-thread__connector::before {
+  top: -8px;
+}
+
+.generated-answer-thread__connector::after {
+  bottom: -8px;
+}
+
+.generated-answer-thread__show-previous-button {
+  width: fit-content;
+  border-radius: var(--slds-g-radius-border-2, 4px);
+  cursor: pointer;
+}
+
+.generated-answer-thread__show-previous-button:hover {
+  background-color: var(--lwc-colorBackgroundRowHover, #f3f2f2);
+}

package/force-app/main/default/lwc/quanticGeneratedAnswerThread/quanticGeneratedAnswerThread.html

@@ -0,0 +1,67 @@
+<template>
+  <template lwc:if={isSingleAnswer}>
+    <c-quantic-generated-answer-body
+      engine-id={engineId}
+      generated-answer={headAnswer}
+      disable-citation-anchoring={disableCitationAnchoring}
+    ></c-quantic-generated-answer-body>
+  </template>
+
+  <template lwc:else>
+    <ul class="generated-answer-thread">
+      <template lwc:if={shouldCollapseOlderAnswers}>
+        <li class="generated-answer-thread__show-previous">
+          <div class="slds-grid slds-grid_vertical-align-center">
+            <div
+              class="slds-grid slds-grid_align-center slds-grid_vertical-align-center slds-shrink-none slds-m-right_x-small generated-answer-thread__dot-column"
+            >
+              <span
+                class="generated-answer-thread__dot"
+                data-testid="show-previous-dot"
+              ></span>
+            </div>
+            <div>
+              <button
+                type="button"
+                class="slds-button_reset slds-p-horizontal_x-small slds-p-vertical_xx-small generated-answer-thread__show-previous-button"
+                data-testid="show-previous-button"
+                onclick={handleShowAllClick}
+              >
+                {showPreviousQuestionsLabel}
+              </button>
+            </div>
+          </div>
+          <div class="slds-grid">
+            <div
+              class="slds-grid slds-grid_align-center slds-shrink-none generated-answer-thread__line-column slds-m-right_x-small"
+            >
+              <span class="generated-answer-thread__connector"></span>
+            </div>
+          </div>
+        </li>
+      </template>
+
+      <template for:each={previousAnswers} for:item="answer">
+        <c-quantic-thread-item key={answer.answerId} title={answer.question}>
+          <c-quantic-generated-answer-body
+            engine-id={engineId}
+            generated-answer={answer}
+            disable-citation-anchoring={disableCitationAnchoring}
+          ></c-quantic-generated-answer-body>
+        </c-quantic-thread-item>
+      </template>
+
+      <c-quantic-thread-item
+        title={lastAnswer.question}
+        hide-line
+        disable-collapse
+      >
+        <c-quantic-generated-answer-body
+          engine-id={engineId}
+          generated-answer={lastAnswer}
+          disable-citation-anchoring={disableCitationAnchoring}
+        ></c-quantic-generated-answer-body>
+      </c-quantic-thread-item>
+    </ul>
+  </template>
+</template>