@coveo/quantic 3.34.2 → 3.35.0

package/README.md

@@ -110,15 +110,15 @@ https://your-salesforce-lws-disabled-scratch-org-instance.force.com/examples
 Once the community has been deployed, you can deploy the `main` or `example` components to a specific org only when needed by running the corresponding commands:
 
 ```bash
-pnpm run deploy:main --target-org Quantic__LWS_enabled
-pnpm run deploy:examples --target-org Quantic__LWS_enabled
+pnpm run deploy:main Quantic__LWS_enabled
+pnpm run deploy:examples Quantic__LWS_enabled
 ```
 
 You can replace Quantic\_\_LWS_enabled with your target org alias. For example:
 
 ```bash
-pnpm run deploy:main --target-org MyCustomOrg
-pnpm run deploy:examples --target-org MyCustomOrg
+pnpm run deploy:main MyCustomOrg
+pnpm run deploy:examples MyCustomOrg
 ```
 
 ### Run Playwright for Quantic Components

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

@@ -5,7 +5,6 @@ import {
 // @ts-ignore
 import {createElement} from 'lwc';
 import QuanticCitation from '../quanticCitation';
-import {debounce} from '../quanticCitation';
 
 const functionsMocks = {
   eventHandler: jest.fn((event) => event),
@@ -113,67 +112,6 @@ describe('c-quantic-citation', () => {
     cleanup();
   });
 
-  describe('debounce function', () => {
-    let mockFnToDebounce;
-    const DEBOUNCE_DELAY = 200;
-
-    beforeEach(() => {
-      jest.useFakeTimers();
-      mockFnToDebounce = jest.fn();
-    });
-
-    afterEach(() => {
-      jest.useRealTimers();
-    });
-
-    // Ensures that rapid calls result in only one execution
-    test('should execute once after the delay and use the arguments from the last call', () => {
-      const debouncedFn = debounce(mockFnToDebounce, DEBOUNCE_DELAY);
-
-      debouncedFn('first');
-      expect(mockFnToDebounce).not.toHaveBeenCalled();
-
-      jest.advanceTimersByTime(DEBOUNCE_DELAY - 100);
-      debouncedFn('middle');
-
-      jest.advanceTimersByTime(DEBOUNCE_DELAY - 100);
-      debouncedFn('last');
-
-      expect(mockFnToDebounce).not.toHaveBeenCalled();
-      jest.advanceTimersByTime(DEBOUNCE_DELAY);
-
-      expect(mockFnToDebounce).toHaveBeenCalledTimes(1);
-      expect(mockFnToDebounce).toHaveBeenCalledWith('last');
-    });
-
-    // Ensures calls separated by more than the delay execute independently.
-    test('should execute multiple times if calls are spaced outside the delay', () => {
-      const debouncedFn = debounce(mockFnToDebounce, DEBOUNCE_DELAY);
-
-      debouncedFn(100);
-      jest.advanceTimersByTime(DEBOUNCE_DELAY);
-      expect(mockFnToDebounce).toHaveBeenCalledTimes(1);
-      expect(mockFnToDebounce).toHaveBeenCalledWith(100);
-
-      debouncedFn(200, {data: 'second'});
-      jest.advanceTimersByTime(DEBOUNCE_DELAY);
-      expect(mockFnToDebounce).toHaveBeenCalledTimes(2);
-      expect(mockFnToDebounce).toHaveBeenCalledWith(200, {data: 'second'});
-    });
-
-    // Ensures that the execution can be canceled before the delay expires.
-    test('should not execute the function if cancel is called before the delay', () => {
-      const debouncedFn = debounce(mockFnToDebounce, DEBOUNCE_DELAY);
-
-      debouncedFn('should not run');
-      jest.advanceTimersByTime(DEBOUNCE_DELAY / 2);
-      debouncedFn.cancel();
-
-      jest.advanceTimersByTime(DEBOUNCE_DELAY * 2);
-      expect(mockFnToDebounce).not.toHaveBeenCalled();
-    });
-  });
-
   it('should properly display the citation', async () => {
     const element = createTestComponent();
     await flushPromises();
@@ -222,7 +160,7 @@ describe('c-quantic-citation', () => {
       jest.useRealTimers();
     });
 
-    it('should display the citation tooltip', async () => {
+    it('should display the citation tooltip after 200ms delay', async () => {
       const element = createTestComponent();
       await flushPromises();
 
@@ -236,18 +174,17 @@ describe('c-quantic-citation', () => {
       expect(citationLink).not.toBeNull();
       expect(citationTooltip).not.toBeNull();
 
-      // Spy on the tooltip's showTooltip method to verify it gets called
       const showTooltipSpy = jest.spyOn(citationTooltip, 'showTooltip');
 
       await citationLink.dispatchEvent(
         new CustomEvent('mouseenter', {bubbles: true})
       );
+      expect(showTooltipSpy).toHaveBeenCalledTimes(0);
       jest.advanceTimersByTime(200);
-
       expect(showTooltipSpy).toHaveBeenCalledTimes(1);
     });
 
-    it('should dispatch a citation hover event after hovering over the the citation for more than 1200ms, 200ms debounce duration before hover + 1000ms minimum hover duration', async () => {
+    it('should dispatch a citation hover event after hovering over the the citation for more than 1200ms, 200ms delay before hover + 1000ms minimum hover duration', async () => {
       const element = createTestComponent();
       await flushPromises();
       setupEventDispatchTest('quantic__citationhover');
@@ -260,16 +197,19 @@ describe('c-quantic-citation', () => {
       await citationLink.dispatchEvent(
         new CustomEvent('mouseenter', {bubbles: true})
       );
+      // Wait for show delay - this triggers the tooltip to show and sets hoverStartTimestamp
+      jest.advanceTimersByTime(200);
+      // Now wait for minimum hover time
       jest.advanceTimersByTime(1000);
       await citationLink.dispatchEvent(
         new CustomEvent('mouseleave', {bubbles: true})
       );
-      // Additional 200ms delay for the new hide tooltip logic
+      // Additional 200ms delay for the hide tooltip logic
       jest.advanceTimersByTime(200);
 
       expect(functionsMocks.eventHandler).toHaveBeenCalledTimes(1);
       expect(functionsMocks.eventHandler).toHaveBeenCalledWith({
-        citationHoverTimeMs: 1200,
+        citationHoverTimeMs: 1100,
       });
     });
 
@@ -313,32 +253,32 @@ describe('c-quantic-citation', () => {
 
         const hideTooltipSpy = jest.spyOn(citationTooltip, 'hideTooltip');
 
-        // Hover over the citation
+        // Hover over the citation - tooltip shows after 200ms delay
         await citationLink.dispatchEvent(
           new CustomEvent('mouseenter', {bubbles: true})
         );
         jest.advanceTimersByTime(200);
 
-        // Move cursor to tooltip in less than 200ms
+        // Move cursor to tooltip quickly (before hide delay expires)
         await citationLink.dispatchEvent(
           new CustomEvent('mouseleave', {bubbles: true})
         );
-        jest.advanceTimersByTime(100);
+
         await citationTooltip.dispatchEvent(
           new CustomEvent('mouseenter', {bubbles: true})
         );
 
-        // Move cursor back to citation in less than 200ms
+        // Move cursor back to citation quickly (before hide delay expires)
         await citationTooltip.dispatchEvent(
           new CustomEvent('mouseleave', {bubbles: true})
         );
-        jest.advanceTimersByTime(100);
+
         await citationLink.dispatchEvent(
           new CustomEvent('mouseenter', {bubbles: true})
         );
 
-        // Advance time beyond 200ms to see if tooltip is hidden
-        jest.advanceTimersByTime(300);
+        // Advance time beyond 100ms to see if tooltip is hidden
+        jest.advanceTimersByTime(200);
 
         expect(hideTooltipSpy).toHaveBeenCalledTimes(0);
       });

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

@@ -5,28 +5,10 @@ import {LightningElement, api} from 'lwc';
 /** @typedef {import("coveo").InteractiveCitation} InteractiveCitation */
 
 const minimumTooltipDisplayDurationMs = 1000;
-const tooltipHideDelayMs = 200;
+const tooltipDelayMsShow = 200;
+const tooltipDelayMsHide = 100;
 const supportedFileTypesForTextFragment = ['html', 'SalesforceItem'];
 
-/**
- * Debounce function that delays invoking func until after wait milliseconds
- * have elapsed since the last time the debounced function was invoked.
- * Includes a cancel method to clear any pending timeout.
- * @param {Function} fn - The function to debounce
- * @param {number} delay - The number of milliseconds to delay
- * @returns {Function} The debounced function with cancel method
- */
-export function debounce(fn, delay) {
-  let timeout;
-  const debounced = (...args) => {
-    clearTimeout(timeout);
-    // eslint-disable-next-line @lwc/lwc/no-async-operation
-    timeout = setTimeout(() => fn(...args), delay);
-  };
-  debounced.cancel = () => clearTimeout(timeout);
-  return debounced;
-}
-
 /**
  * The `QuanticCitation` component renders an individual citation.
  * @fires CustomEvent#quantic__citationhover
@@ -69,8 +51,14 @@ export default class QuanticCitation extends NavigationMixin(LightningElement) {
   salesforceRecordUrl;
   /** @type {boolean} */
   isHrefWithTextFragment = false;
+  /** @type {boolean} */
+  isCitationHovered = false;
+  /** @type {boolean} */
+  isTooltipHovered = false;
   /** @type {Object} */
-  hideTooltipDebounced;
+  showTimer = null;
+  /** @type {Object} */
+  hideTimer = null;
 
   connectedCallback() {
     const fileType = this.citation?.fields?.filetype;
@@ -78,15 +66,6 @@ export default class QuanticCitation extends NavigationMixin(LightningElement) {
       !this.disableCitationAnchoring &&
       supportedFileTypesForTextFragment.includes(fileType) &&
       !!this.text;
-
-    // Initialize the debounced hide tooltip function
-    this.hideTooltipDebounced = debounce(() => {
-      if (this.tooltipIsDisplayed) {
-        this.dispatchCitationHoverEvent();
-      }
-      this.tooltipIsDisplayed = false;
-      this.tooltipComponent?.hideTooltip();
-    }, tooltipHideDelayMs);
   }
 
   renderedCallback() {
@@ -111,30 +90,77 @@ export default class QuanticCitation extends NavigationMixin(LightningElement) {
   disconnectedCallback() {
     this.removeBindings?.();
     clearTimeout(this.timeout);
-    this.hideTooltipDebounced?.cancel();
+    this.cancelShow();
+    this.cancelHide();
   }
 
   handleCitationMouseEnter() {
-    this.showTooltip();
+    this.isCitationHovered = true;
+    this.updateTooltipHideShow();
   }
 
   handleCitationMouseLeave() {
-    this.hideTooltipDebounced();
+    this.isCitationHovered = false;
+    this.updateTooltipHideShow();
   }
 
   handleTooltipMouseEnter() {
-    this.hideTooltipDebounced.cancel();
+    this.isTooltipHovered = true;
+    this.updateTooltipHideShow();
   }
 
   handleTooltipMouseLeave() {
-    this.hideTooltipDebounced();
+    this.isTooltipHovered = false;
+    this.updateTooltipHideShow();
+  }
+
+  isHovering() {
+    return this.isCitationHovered || this.isTooltipHovered;
+  }
+
+  updateTooltipHideShow() {
+    if (this.isHovering()) {
+      this.cancelHide();
+      this.scheduleShow();
+    } else {
+      this.cancelShow();
+      this.scheduleHide();
+    }
+  }
+
+  scheduleShow() {
+    if (this.showTimer !== null) return;
+
+    // eslint-disable-next-line @lwc/lwc/no-async-operation
+    this.showTimer = setTimeout(() => {
+      this.showTimer = null;
+      if (this.isHovering()) this.showTooltip();
+    }, tooltipDelayMsShow);
+  }
+
+  scheduleHide() {
+    if (this.hideTimer !== null) return;
+
+    // eslint-disable-next-line @lwc/lwc/no-async-operation
+    this.hideTimer = setTimeout(() => {
+      this.hideTimer = null;
+      if (!this.isHovering()) this.hideTooltip();
+    }, tooltipDelayMsHide);
+  }
+
+  cancelShow() {
+    if (this.showTimer === null) return;
+    clearTimeout(this.showTimer);
+    this.showTimer = null;
+  }
+
+  cancelHide() {
+    if (this.hideTimer === null) return;
+    clearTimeout(this.hideTimer);
+    this.hideTimer = null;
   }
 
-  /**
-   * Shows the tooltip immediately and cancels any pending hide.
-   */
   showTooltip() {
-    this.hideTooltipDebounced.cancel();
     if (!this.tooltipIsDisplayed) {
       this.hoverStartTimestamp = Date.now();
       this.tooltipIsDisplayed = true;
@@ -142,6 +168,14 @@ export default class QuanticCitation extends NavigationMixin(LightningElement) {
     }
   }
 
+  hideTooltip() {
+    if (this.tooltipIsDisplayed) {
+      this.dispatchCitationHoverEvent();
+      this.tooltipIsDisplayed = false;
+      this.tooltipComponent?.hideTooltip();
+    }
+  }
+
   /**
    * Dispatches the citation hover analytics event if minimum display duration was met.
    */