@coveo/quantic 3.39.1 → 3.41.0

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

@@ -1,6 +1,12 @@
+import {
+  registerComponentForInit,
+  initializeWithHeadless,
+  getHeadlessBundle,
+} from 'c/quanticHeadlessLoader';
 import {
   transformMarkdownToHtml,
   loadMarkdownDependencies,
+  LinkUtils,
 } from 'c/quanticUtils';
 import {LightningElement, api} from 'lwc';
 // @ts-ignore
@@ -8,6 +14,21 @@ import generatedMarkdownContentTemplate from './templates/generatedMarkdownConte
 // @ts-ignore
 import generatedTextContentTemplate from './templates/generatedTextContent.html';
 
+/** @typedef {import("coveo").SearchEngine} SearchEngine */
+/** @typedef {import("coveo").InsightEngine} InsightEngine */
+
+const INLINE_LINK_ICON = `
+  <svg
+    class="slds-icon answer-content__link-icon-svg"
+    aria-hidden="true"
+    focusable="false"
+    viewBox="0 0 52 52"
+  >
+    <path d="M48.5 2h-15c-.8 0-1.5.7-1.5 1.5v3c0 .8.7 1.5 1.5 1.5h6.4L22.1 25.8c-.6.6-.6 1.5 0 2.1l2.1 2.1c.6.6 1.5.6 2.1 0L44 12.3v6.2c0 .8.7 1.5 1.5 1.5h3c.8 0 1.5-.7 1.5-1.5v-15c0-.8-.7-1.5-1.5-1.5z"></path>
+    <path d="M38 28.5V46H8V16h17.5c.8 0 1.5-.7 1.5-1.5v-3c0-.8-.7-1.5-1.5-1.5H6c-2.2 0-4 1.8-4 4v34c0 2.2 1.8 4 4 4h34c2.2 0 4-1.8 4-4V28.5c0-.8-.7-1.5-1.5-1.5h-3c-.8 0-1.5.7-1.5 1.5z"></path>
+  </svg>
+`;
+
 /**
  * The `QuanticGeneratedAnswerContent` component displays the generated answer content.
  * @category Internal
@@ -16,6 +37,18 @@ import generatedTextContentTemplate from './templates/generatedTextContent.html'
  * <c-quantic-generated-answer-content answer-content-format={answerContentFormat} answer={answer} is-streaming={isStreaming}></c-quantic-generated-answer-content>
  */
 export default class QuanticGeneratedAnswerContent extends LightningElement {
+  /**
+   * The ID of the engine instance the component registers to.
+   * @api
+   * @type {string}
+   */
+  @api engineId;
+  /**
+   * The unique identifier of the generated answer.
+   * @api
+   * @type {string}
+   */
+  @api answerId;
   /**
    * If the answer is streaming, it will render a blinking cursor at the end of the answer.
    * @api
@@ -65,6 +98,32 @@ export default class QuanticGeneratedAnswerContent extends LightningElement {
   /** @type {'text/plain' | 'text/markdown'} */
   _answerContentFormat = 'text/plain';
   _markdownDependenciesLoaded = false;
+  /** @type {Array<function>} */
+  _inlineLinkBindings = [];
+  /** @type {AnyHeadless} */
+  headless;
+  /** @type {SearchEngine | InsightEngine} */
+  engine;
+
+  connectedCallback() {
+    registerComponentForInit(this, this.engineId);
+  }
+
+  renderedCallback() {
+    initializeWithHeadless(this, this.engineId, this.initialize);
+  }
+
+  /**
+   * @param {SearchEngine | InsightEngine} engine
+   */
+  initialize = (engine) => {
+    this.headless = getHeadlessBundle(this.engineId);
+    this.engine = engine;
+  };
+
+  disconnectedCallback() {
+    this.cleanUpInlineLinkBindings();
+  }
 
   loadMarkdownDependencies() {
     if (
@@ -105,6 +164,7 @@ export default class QuanticGeneratedAnswerContent extends LightningElement {
           // eslint-disable-next-line @lwc/lwc/no-inner-html
           answerContainer.innerHTML = newHTMLContent;
         }
+        this.processInlineLinks(answerContainer);
       }
     }
     // Fallback to display answer as text if the Marked library failed to load
@@ -114,6 +174,82 @@ export default class QuanticGeneratedAnswerContent extends LightningElement {
     this.dispatchEvent(new CustomEvent('quantic__answercontentupdated'));
   }
 
+  /**
+   * Decorates each inline link with an icon and binds analytics, replacing any previous bindings.
+   * @param {Element|null} answerContainer
+   */
+  processInlineLinks(answerContainer) {
+    if (!answerContainer) {
+      return;
+    }
+    this.cleanUpInlineLinkBindings();
+    /** @type {NodeListOf<HTMLAnchorElement>} */
+    const anchors = answerContainer.querySelectorAll(
+      'a[data-answer-inline-link]'
+    );
+    anchors.forEach((anchor) => {
+      anchor.target = '_blank';
+      anchor.rel = 'noopener';
+      this.bindAnalyticsToInlineLink(anchor);
+      this.appendInlineLinkIcon(anchor);
+    });
+  }
+
+  /**
+   * Appends the external link icon to the given anchor.
+   * @param {HTMLAnchorElement} anchor
+   */
+  appendInlineLinkIcon(anchor) {
+    const icon = document.createElement('span');
+    icon.classList.add(
+      'slds-icon_container',
+      'slds-icon-utility-new_window',
+      'slds-current-color',
+      'slds-m-left_xxx-small',
+      'answer-content__link-icon'
+    );
+    // eslint-disable-next-line @lwc/lwc/no-inner-html
+    icon.innerHTML = INLINE_LINK_ICON;
+    anchor.appendChild(icon);
+  }
+
+  /**
+   * Creates an `InteractiveGeneratedAnswerInlineLink` controller for the given anchor
+   * and binds analytics event listeners to it.
+   * @param {HTMLAnchorElement} anchor
+   */
+  bindAnalyticsToInlineLink(anchor) {
+    if (
+      !this.headless?.buildInteractiveGeneratedAnswerInlineLink ||
+      !this.engine
+    ) {
+      return;
+    }
+    const controller = this.headless.buildInteractiveGeneratedAnswerInlineLink(
+      this.engine,
+      {
+        options: {
+          link: {
+            linkURL: anchor.getAttribute('href') || '',
+            linkText: anchor.textContent?.trim() || '',
+          },
+          answerId: this.answerId,
+        },
+      }
+    );
+    this._inlineLinkBindings.push(
+      LinkUtils.bindAnalyticsToLink(anchor, controller)
+    );
+  }
+
+  /**
+   * Cleans up all inline link bindings.
+   */
+  cleanUpInlineLinkBindings() {
+    this._inlineLinkBindings.forEach((remove) => remove());
+    this._inlineLinkBindings = [];
+  }
+
   get generatedAnswerContentClass() {
     return `generated-answer-content__answer ${this.isStreaming ? 'generated-answer-content__answer--streaming' : ''}`;
   }

package/force-app/main/default/lwc/quanticGeneratedAnswerContent/templates/generatedMarkdownContent.css

@@ -152,3 +152,13 @@ tbody tr td:first-of-type {
 tbody tr td:last-of-type td {
   border-bottom: unset;
 }
+
+.answer-content__link-icon-svg {
+  width: 0.625rem;
+  height: 0.625rem;
+  fill: currentColor;
+}
+
+.answer-content__link-icon {
+  display: inline-flex;
+}

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;
+}