@coveo/quantic 3.44.2 → 3.44.3

package/README.md

@@ -66,6 +66,15 @@ To access the links to the created communities, check the generated `.env` file
 
 Or you can run the individual commands below.
 
+### Playground Components and Solution Examples
+
+Quantic has two separate folders for example components, each serving a different purpose, use the following rules when adding an example component:
+
+- **`force-app/playgroundComponents`** contains the components used to build the Quantic Examples community playground and to support Playwright end-to-end tests. Add a component here when it demonstrates an individual Quantic component, exposes its configurable properties for experimentation, or provides test coverage for the component.
+- **`force-app/solutionExamples`** contains real-world reference implementations that demonstrate how to combine Quantic components to solve a broader Salesforce use case. Examples include `exampleInsightPanel`, `exampleRelevantGenerativeAnswering`, `examplePageViewTracker` and more. Add a component here when it demonstrates an integration or reusable solution pattern rather than an individual component playground.
+
+Both folders are deployed by `pnpm run deploy:examples`.
+
 #### Create a Default Scratch Org
 
 - Make sure you are in the `packages/quantic` root folder.
@@ -130,19 +139,19 @@ pnpm run deploy:examples MyCustomOrg
 To run Playwright tests, run:
 
 ```bash
-pnpm run e2e:playwright
+pnpm run e2e:pre-provisioned
 ```
 
 To run Playwright tests only for the scratch org where LWS is enabled, run:
 
 ```bash
-pnpm run e2e:playwright:lws-enabled
+pnpm run e2e:pre-provisioned:lws-enabled
 ```
 
 To run Playwright tests only for the scratch org where LWS is disabled, run:
 
 ```bash
-pnpm run e2e:playwright:lws-disabled
+pnpm run e2e:pre-provisioned:lws-disabled
 ```
 
 ### Run LWC unit tests for Quantic Components

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

@@ -21,7 +21,7 @@ export default class QuanticCitation extends NavigationMixin(LightningElement) {
   /**
    * The citation item information.
    * @api
-   * @type {{title: string, index: number, text: string, uri: string, clickUri: string, fields: object}}
+   * @type {{title: string, index: number, text: string, uri: string, clickUri: string, fields: object, filetype: string}}
    */
   @api citation;
   /**
@@ -78,7 +78,7 @@ export default class QuanticCitation extends NavigationMixin(LightningElement) {
   hideTimer = null;
 
   connectedCallback() {
-    const fileType = this.citation?.fields?.filetype;
+    const fileType = this.citation.filetype ?? this.citation.fields?.filetype;
     this.isHrefWithTextFragment =
       !this.disableCitationAnchoring &&
       supportedFileTypesForTextFragment.includes(fileType) &&

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

@@ -52,8 +52,8 @@ const headlessBundles = {
 
 /**
  * Loads the Bueno library dependency.
- * @param element The Lightning element to use to load dependencies.
- * @returns {Promise}
+ * @param element The Lightning element used to load the dependency.
+ * @returns {Promise<void>} A promise that resolves when Bueno is available.
  */
 const getBueno = (element) => {
   if (window.Bueno) {
@@ -63,11 +63,20 @@ const getBueno = (element) => {
 };
 
 /**
- * Initiates dependency loading promises.
- * @param element The Lightning element to use to load dependencies.
- * @returns {Promise<AnyHeadless>}
+ * Loads the dependencies for an engine use case and returns its Headless bundle.
+ * @param element The Lightning element used to load dependencies.
+ * @param {string} [headlessUseCase=HeadlessBundleNames.search] The Headless use case whose bundle should be loaded.
+ * @returns {Promise<AnyHeadless>} A promise that resolves to the loaded Headless bundle.
+ * @throws {Error} If a dependency cannot be loaded.
  */
 const loadDependencies = async (element, headlessUseCase) => {
+  if (
+    headlessUseCase &&
+    !Object.prototype.hasOwnProperty.call(headlessBundles, headlessUseCase)
+  ) {
+    throw new Error(`Unsupported Headless use case: ${headlessUseCase}`);
+  }
+
   const bundleInfo = headlessUseCase
     ? headlessBundles[headlessUseCase]
     : headlessBundles.search;
@@ -83,17 +92,23 @@ const loadDependencies = async (element, headlessUseCase) => {
 };
 
 /**
- * Sets callback to execute when all components are registered with the specified engine.
- * @param {Function} callback
- * @param {string} engineId
+ * Registers a callback to run after the Headless engine has been initialized.
+ * @param {(engine: AnyEngine) => void} callback The callback to invoke with the initialized engine
+ * @throws {Error} If no engine is registered for the specified engine ID.
  */
 const setInitializedCallback = (callback, engineId) => {
-  window.coveoHeadless[engineId].initializedCallback = callback;
+  const engine = window.coveoHeadless?.[engineId];
+  if (!engine) {
+    throw new Error(
+      `Engine has not been registered for engine ID: ${engineId}`
+    );
+  }
+  engine.initializedCallback = callback;
 };
 
 /**
  * Cancels the delayed search query.
- * @param {string} engineId The id of the engine.
+ * @param {string} engineId The ID of the engine.
  */
 const cancelInitializedCallback = (engineId) => {
   if (debouncers[engineId]) {
@@ -103,20 +118,34 @@ const cancelInitializedCallback = (engineId) => {
 };
 
 /**
- * Dispatches search request.
- * @param {string} engineId The id of the engine.
+ * Executes the initialization callback with the engine once the debounce delay expires.
+ * @param {string} engineId The ID of the engine.
+ * @returns {Promise<void>}
  */
 const executeInitializedCallback = async (engineId) => {
-  if (window.coveoHeadless[engineId]) {
-    window.coveoHeadless[engineId].initializedCallback(
-      await window.coveoHeadless[engineId].enginePromise
+  const engine = window.coveoHeadless?.[engineId];
+  if (!engine?.initializedCallback) {
+    return;
+  }
+
+  try {
+    await engine.initializedCallback(await engine.enginePromise);
+  } catch (error) {
+    console.error(
+      `Fatal error: unable to execute the initialization callback for engine ID: ${engineId}`,
+      error
+    );
+    throw new Error(
+      `Fatal error: unable to execute the initialization callback for engine ID: ${engineId}`,
+      // @ts-ignore Error constructor cause options are supported at runtime.
+      {cause: error}
     );
   }
 };
 
 /**
- * Starts the debounced initial search request.
- * @param {string} engineId The id of the engine.
+ * Schedules the engine's initialization callback after a short debounce period.
+ * @param {string} engineId The ID of the engine.
  */
 const debounceInitializedCallback = (engineId) => {
   if (!debouncers[engineId]) {
@@ -129,28 +158,30 @@ const debounceInitializedCallback = (engineId) => {
 };
 
 /**
- * Returns true if registered components are initialized, false otherwise.
- * @param {string} engineId The id of the engine.
+ * Checks whether every component registered for an engine has initialized.
+ * @param {string} engineId The ID of the engine.
+ * @returns {boolean}
  */
 const areAllComponentsInitialized = (engineId) =>
-  !window.coveoHeadless[engineId].components.find(
-    (component) => component.initialized === false
-  );
+  window.coveoHeadless?.[engineId]?.components?.every(
+    (component) => component.initialized === true
+  ) ?? false;
 
 /**
- * Returns the registered component object if it exists.
- * @param element The Lightning Element component with which to load dependencies.
- * @param {string} engineId The id of the engine.
+ * Finds a component registered for an engine.
+ * @param element The component to find.
+ * @param {string} engineId The ID of the engine.
+ * @returns {Object | undefined} The registered component, if found.
  */
 const getRegisteredComponent = (element, engineId) =>
-  window.coveoHeadless[engineId].components.find(
+  window.coveoHeadless?.[engineId]?.components?.find(
     (component) => component.element === element
   );
 
 /**
  * Instantiates the coveoHeadless window object and the engine attribute for the provided ID.
- * @param element The Lightning element to use to load dependencies.
- * @param {string} engineId The id of the engine.
+ * @param element The Lightning element associated with the engine.
+ * @param {string} engineId The ID of the engine.
  */
 const instantiateWindowEngineObject = (element, engineId) => {
   const newWindowEngineObject = {
@@ -170,50 +201,67 @@ const instantiateWindowEngineObject = (element, engineId) => {
 };
 
 /**
- * Loads dependencies and returns an initialized Headless engine.
- * @param {string} engineId The id of the engine.
+ * Creates and returns the Headless engine for an engine ID.
+ * @param {string} engineId The ID of the engine.
+ * @returns {Promise<AnyHeadless>} A promise that resolves to the initialized Headless engine.
+ * @throws {Error} If the engine state or options is invalid, or engine construction fails.
  */
 async function initEngine(engineId) {
   try {
-    if (window.coveoHeadless[engineId].bindings.engine) {
+    const engineState = window.coveoHeadless?.[engineId];
+    if (!engineState) {
+      throw new Error(
+        `Engine has not been registered for engine ID: ${engineId}`
+      );
+    }
+    if (engineState.bindings.engine) {
       throw new Error(`Engine already instantiated for engine ID: ${engineId}`);
     }
-    if (!window.coveoHeadless[engineId].options) {
+    if (!engineState.options) {
       throw new Error('Engine options have not been set.');
     }
 
-    const options = await window.coveoHeadless[engineId].options.promise;
-    return window.coveoHeadless[engineId].engineConstructor(options);
+    const options = await engineState.options.promise;
+    return engineState.engineConstructor(options);
   } catch (error) {
-    throw new Error(
-      'Fatal error: unable to initialize Coveo Headless: ' + error
-    );
+    // @ts-ignore Error constructor cause options are supported at runtime.
+    throw new Error('Fatal error: unable to initialize Coveo Headless', {
+      cause: error,
+    });
   }
 }
 
 /**
- * Initialize coveoHeadless Store object
+ * Initializes the Quantic store for an engine when one is not already available.
  * @param {string} engineId The ID of the engine.
+ * @throws {Error} If the engine state cannot be accessed or the store cannot be initialized.
  */
 const initQuanticStore = (engineId) => {
   try {
-    if (!window.coveoHeadless[engineId].bindings.store) {
-      window.coveoHeadless[engineId].bindings.store = Store.initialize();
+    const engineState = window.coveoHeadless?.[engineId];
+    if (!engineState) {
+      throw new Error(
+        `Engine has not been registered for engine ID: ${engineId}`
+      );
+    }
+    if (!engineState.bindings.store) {
+      engineState.bindings.store = Store.initialize();
     }
   } catch (error) {
-    throw new Error(
-      'Fatal error: unable to initialize Quantic store: ' + error
-    );
+    // @ts-ignore Error constructor cause options are supported at runtime.
+    throw new Error('Fatal error: unable to initialize Quantic store', {
+      cause: error,
+    });
   }
 };
 
 /**
  * Sets the options passed to engine constructor for given engine ID.
  * @param options The Headless options for the specified engine ID.
- * @param {(options: unknown) => unknown} engineConstructor Th engine constructor.
- * @param {string} engineId The id of the engine.
+ * @param {(options: unknown) => unknown} engineConstructor The Headless engine constructor.
+ * @param {string} engineId The ID of the engine.
  * @param element The Lightning element to use to load dependencies.
- * @param headlessBundle The headless bundle associated to the engine.
+ * @param headlessBundle The Headless bundle associated with the engine.
  */
 function setEngineOptions(
   options,
@@ -239,7 +287,7 @@ function setEngineOptions(
 /**
  * Registers a component for future initialization.
  * @param element The Lightning element to use to load dependencies.
- * @param {string} engineId The id of the engine.
+ * @param {string} engineId The ID of the engine.
  */
 function registerComponentForInit(element, engineId) {
   cancelInitializedCallback(engineId);
@@ -257,7 +305,8 @@ function registerComponentForInit(element, engineId) {
 /**
  * Sets registered component to initialized.
  * @param element The Lightning element to use to load dependencies.
- * @param {string} engineId The id of the engine.
+ * @param {string} engineId The ID of the engine.
+ * @throws {Error} If the component was not registered for the engine.
  */
 function setComponentInitialized(element, engineId) {
   const component = window.coveoHeadless?.[engineId]
@@ -280,43 +329,62 @@ function setComponentInitialized(element, engineId) {
 
 /**
  * Returns headless engine promise.
- * @param {string} engineId The id of the engine.
+ * @param {string} engineId The ID of the engine.
+ * @returns {Promise<AnyHeadless>} A promise that resolves to the Headless engine.
+ * @throws {Error} If engine initialization fails.
  */
 function getHeadlessEnginePromise(engineId) {
-  if (!window.coveoHeadless[engineId].enginePromise) {
-    window.coveoHeadless[engineId].enginePromise = initEngine(engineId).then(
-      (engine) => {
-        window.coveoHeadless[engineId].bindings.engine = engine;
-        return engine;
-      }
+  const engineState = window.coveoHeadless?.[engineId];
+  if (!engineState) {
+    throw new Error(
+      `Engine has not been registered for engine ID: ${engineId}`
     );
   }
-  return window.coveoHeadless[engineId].enginePromise;
+  if (!engineState.enginePromise) {
+    engineState.enginePromise = initEngine(engineId).then((engine) => {
+      engineState.bindings.engine = engine;
+      return engine;
+    });
+  }
+  return engineState.enginePromise;
 }
 
 /**
  * Returns bindings object for specified engineId.
- * @param {string} engineId The id of the engine.
+ * @param {string} engineId The ID of the engine.
+ * @returns {Object | undefined} The engine bindings, if registered.
  */
 function getHeadlessBindings(engineId) {
   return window.coveoHeadless?.[engineId]?.bindings;
 }
 
 /**
- * Returns store object for specified engineId.
- * @param {string} engineId The engine ID.
+ * Returns the Quantic store associated with an engine.
+ * @param {string} engineId The ID of the engine.
+ * @returns {Object | undefined} The store, if initialized.
  */
 function getQuanticStore(engineId) {
   return window.coveoHeadless?.[engineId]?.bindings?.store;
 }
+
 /**
  * Initializes a component with Coveo Headless.
- * @param element The LightningElement component to initialize.
- * @param {string} engineId The id of the engine.
- * @param {Function} initialize The component's initialization function.
+ * Failures while initializing the Quantic store, Headless engine, or component
+ * callback are logged and reported through the component error UI.
+ * @param element The component to initialize.
+ * @param {string} engineId The ID of the engine.
+ * @param {(engine: AnyEngine) => void} initialize The component initialization callback function.
+ * @returns {Promise<void>} A promise that resolves after initialization handling completes.
+ * @throws {Error} If the component was not registered before initialization.
  */
 async function initializeWithHeadless(element, engineId, initialize) {
-  if (getRegisteredComponent(element, engineId).initialized) {
+  const component = getRegisteredComponent(element, engineId);
+  if (!component) {
+    throw new Error(
+      'Fatal Error: Component was not registered before initialization'
+    );
+  }
+  if (component.initialized) {
     return;
   }
   try {
@@ -345,8 +413,8 @@ async function initializeWithHeadless(element, engineId, initialize) {
 }
 
 /**
- * Removed the headless engine instance from the window object.
- * @param {string} engineId
+ * Removes the headless engine instance from the window object.
+ * @param {string} engineId The ID of the engine to remove.
  */
 function destroyEngine(engineId) {
   if (window.coveoHeadless?.[engineId]) {
@@ -355,10 +423,10 @@ function destroyEngine(engineId) {
 }
 
 /**
- * Register a facet in the store.
- * @param {string} engineId The engine ID.
- * @param {string} facetType
- * @param {{ label: string; facetId: string; format?: function, element?: HTMLElement, metadata?: object}} data
+ * Registers facet data in the engine's store.
+ * @param {string} engineId The ID of the engine.
+ * @param {string} facetType The store facet collection to update.
+ * @param {{label: string, facetId: string, format?: Function, element?: HTMLElement, metadata?: object}} data The facet data to register.
  */
 function registerToStore(engineId, facetType, data) {
   const store = getQuanticStore(engineId);
@@ -370,9 +438,9 @@ function registerToStore(engineId, facetType, data) {
 }
 
 /**
- * Register the sort options in the store.
- * @param {string} engineId The engine ID.
- * @param {Array<{label: string; value: string; criterion: SortCriterion;}>} data
+ * Registers sort options in the engine's store.
+ * @param {string} engineId The ID of the engine.
+ * @param {Array<{label: string, value: string, criterion: SortCriterion}>} data The sort options to register.
  */
 function registerSortOptionsToStore(engineId, data) {
   const store = getQuanticStore(engineId);
@@ -384,9 +452,10 @@ function registerSortOptionsToStore(engineId, data) {
 }
 
 /**
- * Get facet data from store.
- * @param {string} engineId The engine ID.
- * @param {string} facetType
+ * Gets facet data from the engine's store.
+ * @param {string} engineId The ID of the engine.
+ * @param {string} facetType The store facet collection to read.
+ * @returns {Object | undefined} The facet data, if available.
  */
 function getFromStore(engineId, facetType) {
   const store = getQuanticStore(engineId);
@@ -399,8 +468,9 @@ function getFromStore(engineId, facetType) {
 }
 
 /**
- * Get all facet data from store.
- * @param {string} engineId The engine ID.
+ * Gets all facet data from the engine's store.
+ * @param {string} engineId The ID of the engine.
+ * @returns {Object} All available facet data grouped by facet type.
  */
 function getAllFacetsFromStore(engineId) {
   return Object.values(Store.facetTypes).reduce(
@@ -413,8 +483,9 @@ function getAllFacetsFromStore(engineId) {
 }
 
 /**
- * Gets all sort options data from store.
- * @param {string} engineId The engine ID.
+ * Gets all sort option data from the engine's store.
+ * @param {string} engineId The ID of the engine.
+ * @returns {Array<{label: string, value: string, criterion: SortCriterion}> | undefined} The sort options, if available.
  */
 function getAllSortOptionsFromStore(engineId) {
   const store = getQuanticStore(engineId);
@@ -427,19 +498,19 @@ function getAllSortOptionsFromStore(engineId) {
 }
 
 /**
- * Get the headless bundle associated to the specified engine.
- * @param {string} engineId The engine ID.
- * @returns The headless bundle associated to the specified engine.
+ * Gets the Headless bundle associated with an engine.
+ * @param {string} engineId The ID of the engine.
+ * @returns {AnyHeadless} The configured Headless bundle, or the default search bundle.
  */
 function getHeadlessBundle(engineId) {
-  return window.coveoHeadless[engineId]?.bundle ?? CoveoHeadless;
+  return window.coveoHeadless?.[engineId]?.bundle ?? CoveoHeadless;
 }
 
 /**
- * Gets whether the specified engine is using the expected bundle.
- * @param {string} engineId - The engine ID.
- * @param {string} expectedBundleName - The expected headless bundle name.
- * @returns
+ * Checks whether an engine uses the expected Headless bundle.
+ * @param {string} engineId The ID of the engine.
+ * @param {string} expectedBundleName The name of the expected Headless bundle.
+ * @returns {boolean} Whether the engine uses the expected bundle.
  */
 function isHeadlessBundle(engineId, expectedBundleName) {
   let expectedBundle;