@coveo/quantic 3.40.0 → 3.41.0

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

@@ -0,0 +1,348 @@
+import {resolveSteps} from '../quanticGeneratedAnswerStreamOfThought.js';
+import {buildCreateTestComponent, cleanup, flushPromises} from 'c/testUtils';
+import QuanticGeneratedAnswerStreamOfThought from '../quanticGeneratedAnswerStreamOfThought';
+
+const selectors = {
+  stepItem: '[data-testid="step-item"]',
+  spinner: '[data-testid="spinner"]',
+  checkmark: '[data-testid="checkmark"]',
+  stepLabel: '[data-testid="step-label"]',
+  collapseButton: '[data-testid="collapse-button"]',
+  collapsedSummary: '[data-testid="collapsed-summary"]',
+  collapsedSummaryLabel: '[data-testid="collapsed-summary-label"]',
+  chevronUp: '[data-testid="chevron-up"]',
+  chevronDown: '[data-testid="chevron-down"]',
+};
+
+const createTestComponent = buildCreateTestComponent(
+  QuanticGeneratedAnswerStreamOfThought,
+  'c-quantic-generated-answer-stream-of-thought',
+  {agentSteps: [], isStreaming: false}
+);
+
+describe('#resolveSteps', () => {
+  it('should return empty array for empty input', () => {
+    expect(resolveSteps([])).toEqual([]);
+  });
+
+  it('should resolve a full sequence correctly', () => {
+    expect(
+      resolveSteps([
+        {name: 'thinking', status: 'completed', startedAt: 0},
+        {name: 'searching', status: 'completed', startedAt: 10},
+        {name: 'thinking', status: 'completed', startedAt: 20},
+        {name: 'answering', status: 'active', startedAt: 30},
+      ])
+    ).toEqual([
+      {name: 'thinking-before-search', status: 'completed'},
+      {name: 'searching', status: 'completed'},
+      {name: 'thinking-after-search', status: 'completed'},
+      {name: 'answering', status: 'active'},
+    ]);
+  });
+
+  it('should handle repeated searching steps', () => {
+    expect(
+      resolveSteps([
+        {name: 'thinking', status: 'completed', startedAt: 0},
+        {name: 'searching', status: 'completed', startedAt: 10},
+        {name: 'thinking', status: 'completed', startedAt: 20},
+        {name: 'searching', status: 'completed', startedAt: 30},
+        {name: 'thinking', status: 'active', startedAt: 40},
+      ])
+    ).toEqual([
+      {name: 'thinking-before-search', status: 'completed'},
+      {name: 'searching', status: 'completed'},
+      {name: 'thinking-after-search', status: 'completed'},
+      {name: 'searching', status: 'completed'},
+      {name: 'thinking-after-search', status: 'active'},
+    ]);
+  });
+});
+
+describe('quantic generated answer stream of thought component', () => {
+  afterEach(() => {
+    cleanup();
+  });
+  describe('during streaming', () => {
+    it('should render nothing when there are no steps', async () => {
+      const element = createTestComponent({
+        agentSteps: [],
+        isStreaming: true,
+      });
+      await flushPromises();
+
+      expect(element.shadowRoot.firstChild).toBeNull();
+    });
+
+    it('should show all steps progressively', async () => {
+      const element = createTestComponent({
+        agentSteps: [
+          {name: 'thinking', status: 'completed'},
+          {name: 'searching', status: 'active'},
+        ],
+        isStreaming: true,
+      });
+      await flushPromises();
+
+      const stepItems = element.shadowRoot.querySelectorAll(selectors.stepItem);
+      expect(stepItems).toHaveLength(2);
+    });
+
+    it('should render steps in the correct order', async () => {
+      const element = createTestComponent({
+        agentSteps: [
+          {name: 'thinking', status: 'completed', startedAt: 0},
+          {name: 'searching', status: 'completed', startedAt: 10},
+          {name: 'thinking', status: 'completed', startedAt: 20},
+          {name: 'searching', status: 'completed', startedAt: 30},
+          {name: 'thinking', status: 'completed', startedAt: 40},
+          {name: 'answering', status: 'active', startedAt: 30},
+        ],
+        isStreaming: true,
+      });
+      await flushPromises();
+
+      const stepItems = element.shadowRoot.querySelectorAll(selectors.stepItem);
+      const names = Array.from(stepItems).map((el) =>
+        el.getAttribute('data-step-name')
+      );
+      expect(names).toEqual([
+        'thinking-before-search',
+        'searching',
+        'thinking-after-search',
+        'searching',
+        'thinking-after-search',
+        'answering',
+      ]);
+    });
+
+    it('should show checkmarks for completed steps and spinners for active steps', async () => {
+      const element = createTestComponent({
+        agentSteps: [
+          {name: 'thinking', status: 'completed'},
+          {name: 'searching', status: 'active'},
+        ],
+        isStreaming: true,
+      });
+      await flushPromises();
+
+      const checkmarks = element.shadowRoot.querySelectorAll(
+        selectors.checkmark
+      );
+      const spinners = element.shadowRoot.querySelectorAll(selectors.spinner);
+      expect(checkmarks).toHaveLength(1);
+      expect(spinners).toHaveLength(1);
+    });
+
+    it('should not show a collapse button', async () => {
+      const element = createTestComponent({
+        agentSteps: [{name: 'thinking', status: 'active'}],
+        isStreaming: true,
+      });
+      await flushPromises();
+
+      const collapseButton = element.shadowRoot.querySelector(
+        selectors.collapseButton
+      );
+      const collapsedSummary = element.shadowRoot.querySelector(
+        selectors.collapsedSummary
+      );
+
+      expect(collapseButton).toBeNull();
+      expect(collapsedSummary).toBeNull();
+    });
+  });
+
+  describe('after streaming completes', () => {
+    const multipleSteps = [
+      {name: 'thinking', status: 'completed'},
+      {name: 'searching', status: 'completed'},
+      {name: 'thinking', status: 'completed'},
+      {name: 'answering', status: 'active'},
+    ];
+
+    it('should auto-collapse to show only the last step', async () => {
+      const element = createTestComponent({
+        agentSteps: multipleSteps,
+        isStreaming: true,
+      });
+      await flushPromises();
+      let collapsedSummary = element.shadowRoot.querySelector(
+        selectors.collapsedSummary
+      );
+      let stepItems = element.shadowRoot.querySelectorAll(selectors.stepItem);
+
+      expect(collapsedSummary).toBeNull();
+      expect(stepItems).toHaveLength(multipleSteps.length);
+
+      element.isStreaming = false;
+      element.agentSteps = [
+        {name: 'thinking', status: 'completed'},
+        {name: 'searching', status: 'completed'},
+        {name: 'thinking', status: 'completed'},
+        {name: 'answering', status: 'completed'},
+      ];
+      await flushPromises();
+
+      collapsedSummary = element.shadowRoot.querySelector(
+        selectors.collapsedSummary
+      );
+      stepItems = element.shadowRoot.querySelectorAll(selectors.stepItem);
+      const summaryLabel = element.shadowRoot.querySelector(
+        selectors.collapsedSummaryLabel
+      );
+      const checkmark = collapsedSummary.querySelector(selectors.checkmark);
+
+      expect(collapsedSummary).not.toBeNull();
+      expect(summaryLabel).not.toBeNull();
+      expect(checkmark).not.toBeNull();
+      expect(stepItems).toHaveLength(0);
+    });
+
+    it('should have aria-expanded set to false when collapsed', async () => {
+      const element = createTestComponent({
+        agentSteps: multipleSteps,
+        isStreaming: false,
+      });
+      await flushPromises();
+
+      const collapsedSummary = element.shadowRoot.querySelector(
+        selectors.collapsedSummary
+      );
+
+      expect(collapsedSummary).not.toBeNull();
+      expect(collapsedSummary.getAttribute('aria-expanded')).toBe('false');
+    });
+
+    it('should render nothing when there are no steps and not streaming', async () => {
+      const element = createTestComponent({
+        agentSteps: [],
+        isStreaming: false,
+      });
+      await flushPromises();
+
+      expect(element.shadowRoot.firstChild).toBeNull();
+    });
+  });
+
+  describe('expand/collapse interaction', () => {
+    const multipleSteps = [
+      {name: 'thinking', status: 'completed'},
+      {name: 'searching', status: 'completed'},
+      {name: 'thinking', status: 'completed'},
+      {name: 'answering', status: 'completed'},
+    ];
+
+    it('should expand to show all steps and collapse button when collapsed summary row is clicked', async () => {
+      const element = createTestComponent({
+        agentSteps: multipleSteps,
+        isStreaming: false,
+      });
+      await flushPromises();
+
+      const collapsedSummary = element.shadowRoot.querySelector(
+        selectors.collapsedSummary
+      );
+      expect(collapsedSummary).not.toBeNull();
+
+      collapsedSummary.click();
+      await flushPromises();
+
+      const stepItems = element.shadowRoot.querySelectorAll(selectors.stepItem);
+      const collapseButton = element.shadowRoot.querySelector(
+        selectors.collapseButton
+      );
+      expect(stepItems).toHaveLength(multipleSteps.length);
+      expect(collapseButton).not.toBeNull();
+    });
+
+    it('should collapse back when collapse button is clicked', async () => {
+      const element = createTestComponent({
+        agentSteps: multipleSteps,
+        isStreaming: false,
+      });
+      await flushPromises();
+
+      const collapsedSummary = element.shadowRoot.querySelector(
+        selectors.collapsedSummary
+      );
+      collapsedSummary.click();
+      await flushPromises();
+
+      const collapseButton = element.shadowRoot.querySelector(
+        selectors.collapseButton
+      );
+      expect(collapseButton).not.toBeNull();
+
+      collapseButton.click();
+      await flushPromises();
+
+      expect(
+        element.shadowRoot.querySelector(selectors.collapsedSummary)
+      ).not.toBeNull();
+      expect(
+        element.shadowRoot.querySelectorAll(selectors.stepItem)
+      ).toHaveLength(0);
+      expect(
+        element.shadowRoot.querySelector(selectors.collapseButton)
+      ).toBeNull();
+    });
+
+    it('should set aria-expanded to true when expanded', async () => {
+      const element = createTestComponent({
+        agentSteps: multipleSteps,
+        isStreaming: false,
+      });
+      await flushPromises();
+
+      const collapsedSummary = element.shadowRoot.querySelector(
+        selectors.collapsedSummary
+      );
+      collapsedSummary.click();
+      await flushPromises();
+
+      const collapseButton = element.shadowRoot.querySelector(
+        selectors.collapseButton
+      );
+      expect(collapseButton).not.toBeNull();
+      expect(collapseButton.getAttribute('aria-expanded')).toBe('true');
+    });
+
+    it('should set aria-expanded to false when collapsed', async () => {
+      const element = createTestComponent({
+        agentSteps: multipleSteps,
+        isStreaming: false,
+      });
+      await flushPromises();
+
+      const collapsedSummary = element.shadowRoot.querySelector(
+        selectors.collapsedSummary
+      );
+      expect(collapsedSummary).not.toBeNull();
+      expect(collapsedSummary.getAttribute('aria-expanded')).toBe('false');
+    });
+  });
+
+  describe('single answering step', () => {
+    it('should show the step without a collapse button when only answering exists', async () => {
+      const element = createTestComponent({
+        agentSteps: [{name: 'answering', status: 'completed'}],
+        isStreaming: false,
+      });
+      await flushPromises();
+
+      const stepItems = element.shadowRoot.querySelectorAll(selectors.stepItem);
+      const collapseButton = element.shadowRoot.querySelector(
+        selectors.collapseButton
+      );
+      const collapsedSummary = element.shadowRoot.querySelector(
+        selectors.collapsedSummary
+      );
+
+      expect(stepItems).toHaveLength(1);
+      expect(collapseButton).toBeNull();
+      expect(collapsedSummary).toBeNull();
+    });
+  });
+});

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

@@ -0,0 +1,17 @@
+.stream-of-thought__collapsed-summary,
+.stream-of-thought__collapse-button {
+  border: none;
+  background: transparent;
+}
+
+.stream-of-thought__collapsed-summary:focus-visible,
+.stream-of-thought__collapse-button:focus-visible {
+  border-radius: var(--slds-g-sizing-border-4, 0.25rem);
+  outline: 2px solid var(--lwc-brandPrimary, #1b96ff);
+  outline-offset: 2px;
+}
+
+.stream-of-thought__spinner-container {
+  width: 0.8rem;
+  height: 0.8rem;
+}

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>