@coveo/quantic 3.10.0 → 3.11.0

package/README.md

@@ -55,8 +55,8 @@ Or you can run the individual commands below.
 - Make sure you are in the `packages/quantic` root folder.
 - Run this command to create the default scratch org. `npm run scratch:create`.
 - In VS Code, press Command + Shift P, enter sfdx, and select SFDX: Create a Default Scratch Org.
-- You can also run this command from the command line. `sf org create scratch --set-default --definition-file config/project-scratch-def.json --alias "LWC"`
-- `LWC` is an alias for the scratch org that you can use in other Salesforce CLI commands. You can create any alias that you like.
+- You can also run this command from the command line. `sf org create scratch --set-default --definition-file config/lws-enabled-scratch-def.json --alias Quantic__LWS_enabled`
+- `Quantic__LWS_enabled` is an alias for the scratch org that you can use in other Salesforce CLI commands. You can create any alias that you like.
 
 #### Deploy the Quantic code
 
@@ -64,39 +64,55 @@ Or you can run the individual commands below.
 
 ## Testing
 
-### Deploy the Quantic Examples Community
+### Deploy the Quantic Examples Communities
 
-Example components are available as a Salesforce community (Digital Experience) allowing you to experiment with Quantic components.
+Example components are available as Salesforce communities (Digital Experiences), allowing you to experiment with Quantic components in two separate environments: one with Lightning Web Security (LWS) enabled and one with LWS disabled.
 
-To setup the community in the `LWC` scratch org, run:
+To set up both communities in scratch orgs, run:
 
 ```bash
 npm run setup:examples
 ```
 
-This script creates, configures, and deploys everything required to have fully working examples. The community URL is provided at the end of the script output, as in the following example:
+This script creates, configures, and deploys everything required to have fully working examples in **two scratch orgs**:
+
+- An org with **LWS enabled**.
+- An org with **LWS disabled**.
+
+At the end of the script, the URLs for the two communities are provided, as in the following example:
 
 ```
-...
 
-The 'Quantic Examples' community is ready, you can access it at the following URL:
-https://your-salesforce-scratch-org-instance.force.com/examples
+The 'Quantic Examples' community (LWS enabled) is ready, you can access it at the following URL:
+https://your-salesforce-lws-enabled-scratch-org-instance.force.com/examples
+
+The 'Quantic Examples' community (LWS disabled) is ready, you can access it at the following URL:
+https://your-salesforce-lws-disabled-scratch-org-instance.force.com/examples
 
 To open Cypress, run:
 npm run e2e:watch
 ```
 
-Once the community has been deployed, you can deploy the `main` or `example` components only when needed. To do so, run:
+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
+npm run deploy:main --target-org Quantic__LWS_enabled
+npm run deploy:examples --target-org Quantic__LWS_enabled
+```
+
+You can replace Quantic\_\_LWS_enabled with your target org alias. For example:
 
 ```bash
-npm run deploy:main
-npm run deploy:examples
+npm run deploy:main --target-org MyCustomOrg
+npm run deploy:examples --target-org MyCustomOrg
 ```
 
 ### Run Cypress for Quantic Components
 
 **Note** Before attempting to run [Cypress](https://docs.cypress.io) tests, make sure the `Quantic Examples` community is deployed as described in the previous section.
 
+**Note** Cypress tests run on the org with **LWS enabled**, aliased as `Quantic__LWS_enabled`.
+
 To learn how to add tests, see [adding tests](./docs/adding-tests.md).
 
 - All the tests will need to be under folder `cypress/integration`.
@@ -119,6 +135,30 @@ To get the [detailed report](./docs/detailed-reporting.md), run:
 npm run e2e:detailed
 ```
 
+### Run Playwright for Quantic Components
+
+**Note** Before attempting to run [Playwright](https://playwright.dev/) tests, make sure the `Quantic Examples` community is deployed as described in the previous section in both orgs, the one where LWS is enabled and the one where it is disabled.
+
+**Note** For more information on how to add tests, please refer to our [Quantic Testing Strategy](https://github.com/coveo/ui-kit/blob/master/packages/quantic/decisions/0001-testing-strategy.md), which provides detailed guidelines on testing Quantic components.
+
+To run Playwright tests, run:
+
+```bash
+npm run e2e:playwright:
+```
+
+To run Playwright tests only for the scratch org where LWS is enabled, run:
+
+```bash
+npm run e2e:playwright:lws-enabled
+```
+
+To run Playwright tests only for the scratch org where LWS is disabled, run:
+
+```bash
+npm run e2e:playwright:lws-disabled
+```
+
 ### Run LWC unit tests for Quantic Components
 
 To run LWC unit tests directly in your console, run:

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

@@ -1603,4 +1603,11 @@
     <protected>false</protected>
     <shortDescription>User actions</shortDescription>
   </labels>
+  <labels>
+    <fullName>quantic_CloseNotification</fullName>
+    <value>Close notification</value>
+    <language>en_US</language>
+    <protected>false</protected>
+    <shortDescription>Close notification</shortDescription>
+  </labels>
 </CustomLabels>

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

@@ -20,17 +20,30 @@ const exampleEngine = {
   id: 'mock engine',
 };
 
+const mockSearchStatusState = {
+  hasResults: true,
+  hasError: false,
+};
+
 const functionsMocks = {
   buildNotifyTrigger: jest.fn(() => ({
     state: notificationsState,
     subscribe: functionsMocks.subscribe,
   })),
   dispatchMessage: jest.fn(() => {}),
-  subscribe: jest.fn((cb) => {
-    cb();
+  buildSearchStatus: jest.fn(() => ({
+    state: mockSearchStatusState,
+    subscribe: jest.fn((callback) => {
+      functionsMocks.subscribe.callback = callback;
+      return functionsMocks.unsubscribeSearchStatus;
+    }),
+  })),
+  subscribe: jest.fn((callback) => {
+    callback();
     return functionsMocks.unsubscribe;
   }),
   unsubscribe: jest.fn(() => {}),
+  unsubscribeSearchStatus: jest.fn(() => {}),
 };
 
 // @ts-ignore
@@ -43,6 +56,7 @@ AriaLiveRegion.mockImplementation(() => {
 const selectors = {
   notifications: '[data-test="notification"]',
   initializationError: 'c-quantic-component-error',
+  notificationCloseButton: 'lightning-button-icon',
 };
 
 const defaultOptions = {
@@ -68,6 +82,7 @@ function prepareHeadlessState() {
   mockHeadlessLoader.getHeadlessBundle = () => {
     return {
       buildNotifyTrigger: functionsMocks.buildNotifyTrigger,
+      buildSearchStatus: functionsMocks.buildSearchStatus,
     };
   };
 }
@@ -145,7 +160,7 @@ describe('c-quantic-notifications', () => {
   });
 
   describe('component initialization', () => {
-    it('should build the controller with the proper paramters', async () => {
+    it('should build the notifyTrigger and searchStatus controllers with the proper parameters', async () => {
       createTestComponent();
       await flushPromises();
 
@@ -153,9 +168,13 @@ describe('c-quantic-notifications', () => {
       expect(functionsMocks.buildNotifyTrigger).toHaveBeenCalledWith(
         exampleEngine
       );
+      expect(functionsMocks.buildSearchStatus).toHaveBeenCalledTimes(1);
+      expect(functionsMocks.buildSearchStatus).toHaveBeenCalledWith(
+        exampleEngine
+      );
     });
 
-    it('should subscribe to the headless state changes', async () => {
+    it('should subscribe to the headless notify trigger state changes', async () => {
       createTestComponent();
       await flushPromises();
 
@@ -223,5 +242,94 @@ describe('c-quantic-notifications', () => {
         expect(notifications.length).toEqual(0);
       });
     });
+
+    describe('when there is an error following a search', () => {
+      it('should not render the notifications component', async () => {
+        const element = createTestComponent();
+        mockSearchStatusState.hasError = true;
+        functionsMocks.subscribe.callback();
+        await flushPromises();
+
+        const notifications = element.shadowRoot.querySelectorAll(
+          selectors.notifications
+        );
+
+        expect(notifications.length).toEqual(0);
+      });
+    });
+  });
+
+  describe('when clicking on a notification close button', () => {
+    it('should properly dismiss that notification', async () => {
+      const element = createTestComponent();
+      await flushPromises();
+
+      const notificationsBeforeClose = element.shadowRoot.querySelectorAll(
+        selectors.notifications
+      );
+
+      const firstNotificationCloseButton =
+        notificationsBeforeClose[0].querySelector(
+          selectors.notificationCloseButton
+        );
+      firstNotificationCloseButton.click();
+      await flushPromises();
+
+      const notificationsAfterClose = element.shadowRoot.querySelectorAll(
+        selectors.notifications
+      );
+
+      expect(notificationsAfterClose.length).toEqual(
+        exampleNotifications.length - 1
+      );
+      expect(notificationsAfterClose[0].textContent).toEqual(
+        exampleNotifications[1]
+      );
+    });
+
+    describe('when triggering another search with the same query', () => {
+      it('should reset the visibility of the notifications', async () => {
+        const element = createTestComponent();
+        await flushPromises();
+
+        const notificationsBeforeClose = element.shadowRoot.querySelectorAll(
+          selectors.notifications
+        );
+
+        expect(notificationsBeforeClose.length).toEqual(
+          exampleNotifications.length
+        );
+
+        const firstNotificationCloseButton =
+          notificationsBeforeClose[0].querySelector(
+            selectors.notificationCloseButton
+          );
+        firstNotificationCloseButton.click();
+        await flushPromises();
+
+        const notificationsAfterClose = element.shadowRoot.querySelectorAll(
+          selectors.notifications
+        );
+
+        expect(notificationsAfterClose.length).toEqual(
+          exampleNotifications.length - 1
+        );
+
+        mockSearchStatusState.hasError = false;
+        functionsMocks.subscribe.callback();
+        await flushPromises();
+
+        const notificationsAfterSearch = element.shadowRoot.querySelectorAll(
+          selectors.notifications
+        );
+
+        expect(notificationsAfterSearch.length).toEqual(
+          exampleNotifications.length
+        );
+        notificationsAfterSearch.forEach((notification, index) => {
+          expect(notification.textContent).toEqual(exampleNotifications[index]);
+        });
+      });
+    });
   });
 });

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

@@ -1,7 +1,15 @@
+:host {
+  --slds-c-toast-sizing-min-width: 100%;
+}
+
 .notification {
   background-color: var(---lwc-colorBackgroundAlt, white);
   border: 1px solid var(--lwc-colorBackgroundToast, rgb(116, 116, 116));
   margin-right: 0;
   margin-left: 0;
   width: 100%;
+}
+
+.notification-container {
+  z-index: 2;
 }

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

@@ -5,15 +5,28 @@
   </template>
   <template lwc:else>
     <template for:each={notifications} for:item="notification">
-      <div key={notification.id} data-test="notification" class="slds-notify_container slds-is-relative">
-        <div data-cy="notification" class="slds-notify slds-notify_toast notification" role="status">
-          <lightning-icon icon-name="utility:info_alt" alternative-text="info" title="info"
-            size="small"></lightning-icon>
-          <div class="slds-notify__content slds-var-m-left_small">
-            {notification.value}
+      <template lwc:if={notification.visible}>
+        <div key={notification.id} data-test="notification" class="slds-notify_container slds-is-relative notification-container">
+          <div data-cy="notification" class="slds-notify slds-notify_toast notification" role="status">
+            <lightning-icon icon-name="utility:info_alt" alternative-text="info" title="info"
+              size="small"></lightning-icon>
+            <div class="slds-notify__content slds-var-m-left_small">
+              {notification.value}
+            </div>
+            <div class="slds-notify__close">
+              <lightning-button-icon
+                icon-name="utility:close"
+                alternative-text={labels.closeNotification}
+                size="small"
+                variant="bare"
+                title={labels.closeNotification}
+                onclick={handleNotificationClose}
+                data-id={notification.id}
+              ></lightning-button-icon>
+            </div>
           </div>
         </div>
-      </div>
+      </template>
     </template>
   </template>
 </template>

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

@@ -3,12 +3,13 @@ import {
   initializeWithHeadless,
   getHeadlessBundle,
 } from 'c/quanticHeadlessLoader';
+import closeNotification from '@salesforce/label/c.quantic_CloseNotification';
 import {AriaLiveRegion} from 'c/quanticUtils';
 import {LightningElement, api} from 'lwc';
 
 /** @typedef {import("coveo").SearchEngine} SearchEngine */
+/** @typedef {import("coveo").SearchStatus} SearchStatus */
 /** @typedef {import("coveo").NotifyTrigger} NotifyTrigger */
-/** @typedef {import("coveo").NotifyTriggerState} NotifyTriggerState */
 
 /**
  * The `QuanticNotifications` component is responsible for displaying notifications generated by the Coveo Search API (see [Trigger](https://docs.coveo.com/en/1458)).
@@ -27,12 +28,22 @@ export default class QuanticNotifications extends LightningElement {
 
   /** @type {NotifyTrigger} */
   notifyTrigger;
-  /** @type {NotifyTriggerState} */
-  notifyTriggerState;
   /** @type {boolean} */
   hasInitializationError = false;
   /** @type {import('c/quanticUtils').AriaLiveUtils} */
   ariaLiveNotificationsRegion;
+  /** @type {Array} */
+  notifications = [];
+  /** @type {Function} */
+  unsubscribe;
+  /** @type {Function} */
+  unsubscribeSearchStatus;
+  /** @type {SearchStatus} */
+  searchStatus;
+
+  labels = {
+    closeNotification,
+  };
 
   connectedCallback() {
     registerComponentForInit(this, this.engineId);
@@ -48,32 +59,60 @@ export default class QuanticNotifications extends LightningElement {
   initialize = (engine) => {
     this.headless = getHeadlessBundle(this.engineId);
     this.notifyTrigger = this.headless.buildNotifyTrigger(engine);
+    this.searchStatus = this.headless.buildSearchStatus(engine);
     this.ariaLiveNotificationsRegion = AriaLiveRegion('notifications', this);
     this.unsubscribe = this.notifyTrigger.subscribe(() => this.updateState());
+    this.unsubscribeSearchStatus = this.searchStatus.subscribe(() =>
+      this.handleSearchStatusChange()
+    );
   };
 
   disconnectedCallback() {
     this.unsubscribe?.();
+    this.unsubscribeSearchStatus?.();
   }
 
   updateState() {
-    this.notifyTriggerState = this.notifyTrigger.state;
-    this.ariaLiveNotificationsRegion.dispatchMessage(
-      this.notifyTriggerState?.notifications.reduce(
-        (value, notification, index) => {
-          return `${value} Notification ${index + 1}: ${notification}`;
-        },
-        ''
-      )
-    );
-  }
-
-  get notifications() {
-    return (
-      this.notifyTriggerState?.notifications.map((notification, index) => ({
+    this.notifications =
+      this.notifyTrigger?.state?.notifications.map((notification, index) => ({
         value: notification,
         id: index,
-      })) ?? []
+        visible: true,
+      })) ?? [];
+
+    this.dispatchAriaLiveNotificationsRegionMessage();
+  }
+
+  handleSearchStatusChange() {
+    if (!this.searchStatus?.state.isLoading) {
+      if (this.searchStatus?.state?.hasError) {
+        this.notifications = [];
+      } else {
+        this.notifications =
+          this.notifications?.map((notification) => ({
+            ...notification,
+            visible: true,
+          })) ?? [];
+        this.dispatchAriaLiveNotificationsRegionMessage();
+      }
+    }
+  }
+
+  handleNotificationClose(event) {
+    const currentNotificationId = event.currentTarget.dataset.id;
+    this.notifications = this.notifications.map((notification) => {
+      if (notification.id.toString() === currentNotificationId) {
+        return {...notification, visible: false};
+      }
+      return notification;
+    });
+  }
+
+  dispatchAriaLiveNotificationsRegionMessage() {
+    this.ariaLiveNotificationsRegion.dispatchMessage(
+      this.notifications.reduce((value, notification) => {
+        return `${value} Notification ${notification.id + 1}: ${notification.value}`;
+      }, '')
     );
   }
 

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

@@ -119,6 +119,24 @@ describe('c-quantic-user-actions-toggle', () => {
     cleanup();
   });
 
+  describe('controller initialization', () => {
+    it('should build the controller with the right parameters', async () => {
+      createTestComponent();
+      await flushPromises();
+
+      expect(functionsMocks.buildUserActions).toHaveBeenCalledTimes(1);
+      expect(functionsMocks.buildUserActions).toHaveBeenCalledWith(
+        exampleEngine,
+        {
+          options: {
+            ticketCreationDate: exampleTicketCreationDateTime,
+            excludedCustomActions: exampleExcludedCustomActions,
+          },
+        }
+      );
+    });
+  });
+
   it('should display the user actions toggle button', async () => {
     const element = createTestComponent();
     await flushPromises();

package/force-app/main/default/lwc/quanticUserActionsToggle/e2e/data.ts

@@ -0,0 +1,32 @@
+const followingSessionsActions = [
+  {
+    name: 'CUSTOM',
+    value:
+      '{"event_type":"example","event_value":"exampleCustomAction","origin_level_1":"default"}',
+    time: new Date('2024-09-01T15:30:00Z').valueOf(),
+  },
+];
+
+const ticketCreationSessionActions = [
+  {
+    name: 'CUSTOM',
+    value:
+      '{"event_type":"errors","event_value":"One","origin_level_1":"default","origin_level_2":"default"}',
+    time: new Date('2024-08-30T00:10:00Z').valueOf(),
+  },
+];
+
+const precedingSessionsActions = [
+  {
+    name: 'CUSTOM',
+    value:
+      '{"event_type":"example","event_value":"exampleCustomAction","origin_level_1":"default"}',
+    time: new Date('2024-08-29T15:40:00Z').valueOf(),
+  },
+];
+
+export const exampleUserActionsData = [
+  ...followingSessionsActions,
+  ...ticketCreationSessionActions,
+  ...precedingSessionsActions,
+];

package/force-app/main/default/lwc/quanticUserActionsToggle/e2e/fixture.ts

@@ -0,0 +1,32 @@
+import {quanticBase} from '../../../../../../playwright/fixtures/baseFixture';
+import {UserActionsToggleObject} from './pageObject';
+import {exampleUserActionsData} from './data';
+
+const pageUrl = 's/quantic-user-actions-toggle';
+
+interface UserActionsToggleOptions {
+  userId: string;
+  ticketCreationDateTime: string;
+}
+type QuanticUserActionsToggleE2EFixtures = {
+  userActionsToggle: UserActionsToggleObject;
+  options: UserActionsToggleOptions;
+};
+
+export const testInsight =
+  quanticBase.extend<QuanticUserActionsToggleE2EFixtures>({
+    options: {
+      userId: 'someone@company.com',
+      ticketCreationDateTime: '2024-01-01T00:00:00Z',
+    },
+    userActionsToggle: async ({page, options, configuration}, use) => {
+      await page.goto(pageUrl);
+      configuration.configure({...options});
+      const userActionsToggleObject = new UserActionsToggleObject(page);
+      userActionsToggleObject.mockUserActions(exampleUserActionsData);
+      await userActionsToggleObject.waitForUserActionsResponse(options.userId);
+      await use(userActionsToggleObject);
+    },
+  });
+
+export {expect} from '@playwright/test';

package/force-app/main/default/lwc/quanticUserActionsToggle/e2e/pageObject.ts

@@ -0,0 +1,71 @@
+import {Locator, Page, Request, Response} from '@playwright/test';
+import {isUaCustomEvent} from '../../../../../../playwright/utils/requests';
+
+const userActionsRequestRegex =
+  /\/rest\/organizations\/.*\/machinelearning\/user\/actions$/;
+
+export class UserActionsToggleObject {
+  constructor(public page: Page) {
+    this.page = page;
+  }
+
+  get userActionsToggleButton(): Locator {
+    return this.page.getByRole('button', {name: /User actions/i});
+  }
+
+  get userActionsModal(): Locator {
+    return this.page.locator(
+      'c-quantic-user-actions-toggle > c-quantic-modal > div'
+    );
+  }
+
+  get userActionsModalCloseButton(): Locator {
+    return this.page
+      .locator('c-quantic-user-actions-toggle > c-quantic-modal')
+      .getByRole('button', {name: 'Close'});
+  }
+
+  async mockUserActions(
+    userActions: Array<{name: string; value: string; time: number}>
+  ) {
+    await this.page.route(userActionsRequestRegex, async (route) => {
+      const body = {value: userActions};
+
+      await route.fulfill({
+        body: JSON.stringify(body),
+        status: 200,
+        headers: {
+          'content-type': 'text/html',
+        },
+      });
+    });
+  }
+
+  async waitForUserActionsResponse(userId: string): Promise<Response> {
+    return this.page.waitForResponse((response) => {
+      const request = response.request();
+      if (request.url().match(userActionsRequestRegex)) {
+        const requestBody = request.postDataJSON?.();
+        return requestBody?.objectId === userId;
+      }
+      return false;
+    });
+  }
+
+  async waitForOpenUserActionsUaAnalytics(): Promise<Request> {
+    const uaRequest = this.page.waitForRequest((request) => {
+      if (isUaCustomEvent(request)) {
+        const requestBody = request.postDataJSON?.();
+        const expectedFields = {
+          eventType: 'User Actions',
+          eventValue: 'openUserActions',
+        };
+        return Object.keys(expectedFields).every(
+          (key) => requestBody?.[key] === expectedFields[key]
+        );
+      }
+      return false;
+    });
+    return uaRequest;
+  }
+}

package/force-app/main/default/lwc/quanticUserActionsToggle/e2e/quanticUserActionsToggle.e2e.ts

@@ -0,0 +1,39 @@
+import {testInsight, expect} from './fixture';
+
+const exampleUserId = 'exampleUserId';
+const exampleTicketCreateDateTime = encodeURIComponent('2024-08-30');
+
+testInsight.use({
+  options: {
+    userId: exampleUserId,
+    ticketCreationDateTime: exampleTicketCreateDateTime,
+  },
+});
+
+testInsight.describe('quantic user actions toggle', () => {
+  testInsight.describe('when opening the user action modal', () => {
+    testInsight(
+      'should open the user actions timeline and log analytics',
+      async ({userActionsToggle}) => {
+        await expect(userActionsToggle.userActionsModal).not.toBeVisible();
+        const uaPromise = userActionsToggle.waitForOpenUserActionsUaAnalytics();
+        await userActionsToggle.userActionsToggleButton.click();
+        await expect(userActionsToggle.userActionsModal).toBeVisible();
+        await uaPromise;
+      }
+    );
+  });
+
+  testInsight.describe('when closing the user action modal', () => {
+    testInsight(
+      'should close the user actions timeline',
+      async ({userActionsToggle}) => {
+        await expect(userActionsToggle.userActionsModal).not.toBeVisible();
+        await userActionsToggle.userActionsToggleButton.click();
+        await expect(userActionsToggle.userActionsModal).toBeVisible();
+        await userActionsToggle.userActionsModalCloseButton.click();
+        await expect(userActionsToggle.userActionsModal).not.toBeVisible();
+      }
+    );
+  });
+});