@coveo/quantic 3.30.3-pre.f339e5b2e0 → 3.30.3-pre.f8584fa862

package/force-app/main/default/lwc/quanticUtils/markdownUtils.js

@@ -7,6 +7,9 @@ import {loadScript} from 'lightning/platformResourceLoader';
  * Transforms a single line of text that may contain HTML to plain text.
  * @param {string} textWithHtml A single line of text that may contain HTML
  * @returns {string} The value as plain text
+ * @example
+ * toInlinePlainText('<p>Hello <strong>World</strong></p>');
+ * // Returns: 'Hello World'
  */
 const toInlinePlainText = (textWithHtml) => {
   const withoutHtmlTags = textWithHtml.replace(/<[^>]*>/g, ' ');
@@ -21,7 +24,7 @@ const unclosedElement = /(\*{1,3}|`)($|\w[\w\s]*$)/;
 /**
  * Complete unclosed elements such as bold, italic, and code.
  * @param {string} text
- * @returns {string}
+ * @returns {string} The corrected text content.
  */
 const completeUnclosedElement = (text) => {
   const match = unclosedElement.exec(text);
@@ -41,6 +44,11 @@ const completeUnclosedElement = (text) => {
   return text;
 };
 
+/**
+ * Escape HTML special characters in a string.
+ * @param {*} text
+ * @returns {string} The escaped HTML string.
+ */
 const escapeHtml = (text) => {
   return text
     .replace(/&/g, '&amp;')
@@ -50,6 +58,12 @@ const escapeHtml = (text) => {
     .replace(/'/g, '&#39;');
 };
 
+/**
+ * Custom Marked renderer to override the default rendering of certain elements.
+ * @type {object}
+ * @property {Function} code
+ * @returns {string} The code block element to render.
+ */
 const customRenderer = {
   code(code) {
     return `<pre><code>${escapeHtml(code)}</code></pre>`;
@@ -59,6 +73,7 @@ const customRenderer = {
    * Custom Marked renderer to replace heading elements with div elements.
    * @param {string} text
    * @param {string} level
+   * @return {string} The heading element to render.
    */
   heading(text, level) {
     const plainText = toInlinePlainText(text);
@@ -69,7 +84,7 @@ const customRenderer = {
   /**
    * Returns escaped HTML.
    * @param {string} text
-   * @returns
+   * @returns {string} The escaped HTML string.
    */
   html(text) {
     return escapeHtml(text);
@@ -119,7 +134,7 @@ const transformMarkdownToHtml = (text, marked) => {
 
 /**
  * Load the libraries Marked and DOMPurify.
- * @param  element
+ * @param element
  * @returns {Promise<any>}
  */
 const loadMarkdownDependencies = (element) => {

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

@@ -37,6 +37,9 @@ export * from './markdownUtils';
 export * from './facetDependenciesUtils';
 export * from './citationAnchoringUtils';
 
+/**
+ * Utility class for debouncing function calls.
+ */
 export class Debouncer {
   _timeout;
 
@@ -90,14 +93,18 @@ export class Deferred {
   }
 }
 
+/**
+ * Utility class for working with search results and binding analytics events.
+ */
 export class ResultUtils {
   /**
-   * Binds the logging of document
-   * @returns An unbind function for the events
+   * Binds analytics logging events to result elements.
    * @param {import("coveo").SearchEngine} engine An instance of an Headless Engine
    * @param {import("coveo").Result} result The result object
    * @param {import("lwc").ShadowRootTheGoodPart} resultElement Parent result element
+   * @param {Function} controllerBuilder Function to build the interactive result controller.
    * @param {string} selector Optional. Css selector that selects all links to the document. Default: "a" tags with the clickUri as "href" parameter.
+   * @returns An unbind function for the events
    */
   static bindClickEventsOnResult(
     engine,
@@ -137,12 +144,15 @@ export class ResultUtils {
   }
 }
 
+/**
+ * Utility class for link operations and analytics binding.
+ */
 export class LinkUtils {
   /**
    * Binds the logging of a link
-   * @returns An unbind function for the events
    * @param {HTMLAnchorElement} link the link element
    * @param {{select:function, beginDelayedSelect: function, cancelPendingSelect: function  }} actions
+   * @returns An unbind function for the events
    */
   static bindAnalyticsToLink(link, actions) {
     const eventsMap = {
@@ -165,6 +175,9 @@ export class LinkUtils {
   }
 }
 
+/**
+ * Utility class for internationalization and localization.
+ */
 export class I18nUtils {
   static getTextWithDecorator(text, startTag, endTag) {
     return `${startTag}${text}${endTag}`;
@@ -178,6 +191,13 @@ export class I18nUtils {
     return new Intl.PluralRules(LOCALE).select(count) === 'one';
   }
 
+  /**
+   * Gets the label name with count.
+   * @param {string} labelName
+   * @param {number} count
+   * @returns {string} The label name with count.
+   * @example `labelName_zero`, `labelName_plural` or `labelName`
+   */
   static getLabelNameWithCount(labelName, count) {
     if (count === 0) {
       return `${labelName}_zero`;
@@ -187,6 +207,16 @@ export class I18nUtils {
     return labelName;
   }
 
+  /**
+   * Formats a string with the given arguments.
+   * @param {*} stringToFormat
+   * @param  {...any} formattingArguments
+   * @returns {string} The formatted string.
+   * @throws {Error} If string format is not a string.
+   * @example
+   * I18nUtils.format('Hello {{0}}, you have {{1}} new messages', 'John', 5);
+   * returns 'Hello John, you have 5 new messages'
+   */
   static format(stringToFormat, ...formattingArguments) {
     if (typeof stringToFormat !== 'string')
       throw new Error("'stringToFormat' must be a String");
@@ -197,6 +227,11 @@ export class I18nUtils {
     );
   }
 
+  /**
+   * Gets the short date pattern for the current locale.
+   * @returns {string} The short date pattern.
+   * @example `M/d/yyyy` for `en-US`, `d/M/yyyy` for `fr-FR`, etc.
+   */
   static getShortDatePattern() {
     const date = new Date(2000, 2, 4); // month is zero-based
     const dateAsString = I18nUtils.formatDate(date);
@@ -215,11 +250,13 @@ export class I18nUtils {
   }
 
   /**
+   * Formats the date in the current locale.
    * @param {Date} date
+   * @returns {string} The formatted date.
    */
   static formatDate(date) {
-    const result = new Intl.DateTimeFormat(LOCALE).format(date);
-    return result;
+    const formattedDate = new Intl.DateTimeFormat(LOCALE).format(date);
+    return formattedDate;
   }
 
   /**
@@ -227,15 +264,24 @@ export class I18nUtils {
    * @returns {string}
    */
   static escapeHTML(html) {
-    var escape = document.createElement('textarea');
+    const escape = document.createElement('textarea');
     escape.textContent = html;
     // eslint-disable-next-line @lwc/lwc/no-inner-html
     return escape.innerHTML;
   }
 }
 
+/**
+ * Storage key for standalone search box configuration.
+ * @constant {string}
+ */
 export const STANDALONE_SEARCH_BOX_STORAGE_KEY = 'coveo-standalone-search-box';
 
+/**
+ * Key codes for common keyboard interactions.
+ * @readonly
+ * @enum {string}
+ */
 export const keys = {
   ESC: 'Escape',
   TAB: 'Tab',
@@ -259,15 +305,24 @@ export function setItemInLocalStorage(key, item) {
 /**
  * Replace char found in pattern with \\$&
  * @param {string} value
+ * @return {string}
  */
 export function regexEncode(value) {
   return value.replace(/[-[\]/{}()*+?.\\^$|]/g, '\\$&');
 }
-
+/**
+ * Parses an XML string into a DOM Document.
+ * @param {string} string
+ * @returns {Document}
+ */
 export function parseXML(string) {
   return new window.DOMParser().parseFromString(string, 'text/xml');
 }
 
+/**
+ * Utility class for time-based calculations and formatting.
+ * Provides methods to convert between different time units and format durations.
+ */
 export class TimeSpan {
   constructor(time, isMilliseconds = true) {
     if (isMilliseconds) {
@@ -344,6 +399,10 @@ export class TimeSpan {
   }
 }
 
+/**
+ * Utility class for date operations and formatting.
+ * Handles conversion between different date formats and provides parsing utilities.
+ */
 export class DateUtils {
   /**
    * Converts a date string from the Coveo Search API format to the ISO-8601 format.
@@ -391,6 +450,7 @@ export class DateUtils {
    * @param {number} hours The local hours to set on the date.
    * @param {number} minutes The local minutes to set on the date.
    * @param {number} seconds The local seconds to set on the date.
+   * @throws {Error} If specified time is invalid.
    * @returns {Date} The parsed date.
    */
   static fromLocalIsoDate(dateString, hours, minutes, seconds) {
@@ -418,6 +478,11 @@ export class DateUtils {
     return new Date(`${withoutTime}T${time}`);
   }
 
+  /**
+   * Trims the time portion from an ISO 8601 date string.
+   * @param {string} dateString
+   * @returns {string}
+   */
   static trimIsoTime(dateString) {
     const timeIdx = dateString.indexOf('T');
     return timeIdx !== -1 ? dateString.substring(0, timeIdx) : dateString;
@@ -425,6 +490,7 @@ export class DateUtils {
 
   /**
    * @param {number} timestamp
+   * @returns {boolean}
    */
   static isValidTimestamp(timestamp) {
     let isValid = true;
@@ -439,8 +505,6 @@ export class DateUtils {
 
   /**
    * Parses a given timestamp into detailed date components.
-   *
-   * @function
    * @param {number} timestamp - The timestamp in milliseconds since January 1, 1970 (epoch time).
    * @returns {Object} An object containing the following date details:
    *   - {number} year - The four-digit year (e.g., 2024).
@@ -497,6 +561,10 @@ export function fromSearchApiDate(dateString) {
   return DateUtils.fromSearchApiDate(dateString);
 }
 
+/**
+ * Formats relative date ranges into human-readable strings.
+ * Supports past and future date ranges with proper pluralization.
+ */
 export class RelativeDateFormatter {
   constructor() {
     this.singularIndex = 0;
@@ -519,10 +587,15 @@ export class RelativeDateFormatter {
   }
 
   /**
-   *
-   * @param {RelativeDate} begin
-   * @param {RelativeDate} end
-   * @returns {string}
+   * Formats a relative date range into a human-readable string.
+   * @param {RelativeDate} begin The beginning of the relative date range.
+   * @param {RelativeDate} end The end of the relative date range.
+   * @returns {string} The formatted human-readable date range.
+   * @throws {Error} If the provided relative date range is invalid.
+   * @example
+   * begin = { period: 'past', unit: 'day', amount: 2 };
+   * end = { period: 'now', unit: 'day', amount: 1 };
+   * Output: "2 days ago - 1 day ago"
    */
   formatRange(begin, end) {
     const isPastRange = begin.period === 'past' && end.period === 'now';
@@ -546,6 +619,10 @@ export class RelativeDateFormatter {
   }
 }
 
+/**
+ * Utility class for managing a simple in-memory store.
+ * Supports registering and retrieving facet and sort option data.
+ */
 export class Store {
   static facetTypes = {
     FACETS: 'facets',
@@ -565,9 +642,11 @@ export class Store {
     };
   }
   /**
+   * Registers a facet to the store if it does not already exist.
    * @param {Record<String, unknown>} store
    * @param {string} facetType
    * @param {{ label?: string; facetId: any; format?: Function;}} data
+   * @return {void}
    */
   static registerFacetToStore(store, facetType, data) {
     if (store?.state[facetType][data.facetId]) {
@@ -577,23 +656,29 @@ export class Store {
   }
 
   /**
+   * Registers sort option data to the store.
    * @param {Record<String, any>} store
    * @param {Array<{label: string; value: string; criterion: SortCriterion;}>} data
+   * @return {void}
    */
   static registerSortOptionDataToStore(store, data) {
     store.state.sort = data;
   }
 
   /**
+   * Gets facet data from the store.
    * @param {Record<String, unknown>} store
    * @param {string} facetType
+   * @return {Object} The facet data.
    */
   static getFromStore(store, facetType) {
     return store.state[facetType];
   }
 
   /**
+   * Gets sort options from the store.
    * @param {Record<String, Object>} store
+   * @return {Array} The sort options.
    */
   static getSortOptionsFromStore(store) {
     return store.state.sort;
@@ -612,7 +697,7 @@ export class Store {
  * @param {string} regionName
  * @param {Object} elem
  * @param {boolean} assertive
- * @returns {AriaLiveUtils}
+ * @returns {AriaLiveUtils} Object with methods to dispatch messages and register the region.
  */
 export function AriaLiveRegion(regionName, elem, assertive = false) {
   function dispatchMessage(message) {
@@ -763,6 +848,7 @@ export function isCustomElement(element) {
 /**
  * Returns the last focusable element in an HTML slot.
  * @param {HTMLElement & {assignedElements?: () => Array<HTMLElement> | null}} slotElement
+ * @returns {HTMLElement | null}
  */
 function getLastFocusableElementFromSlot(slotElement) {
   if (!slotElement && slotElement.assignedElements) {
@@ -782,6 +868,7 @@ function getLastFocusableElementFromSlot(slotElement) {
 /**
  * Returns the first focusable element in an HTML slot.
  * @param {HTMLElement & {assignedElements?: () => Array<HTMLElement> | null}} slotElement
+ * @return {HTMLElement | null}
  */
 function getFirstFocusableElementFromSlot(slotElement) {
   if (!slotElement && slotElement.assignedElements) {
@@ -802,6 +889,7 @@ function getFirstFocusableElementFromSlot(slotElement) {
  * Checks whether an element is indeed the targetElement or one of its parents.
  * @param {HTMLElement} element
  * @param {string} targetElement
+ * @returns {boolean}
  */
 export function isParentOf(element, targetElement) {
   if (!element || element.nodeType === Node.TEXT_NODE) {
@@ -827,6 +915,7 @@ export function isParentOf(element, targetElement) {
  * Copies text to clipboard using the Clipboard API.
  * https://developer.mozilla.org/en-US/docs/Web/API/Clipboard
  * @param {string} text
+ * @return {Promise<void>}
  */
 export async function copyToClipboard(text) {
   try {
@@ -839,6 +928,7 @@ export async function copyToClipboard(text) {
 /**
  * Copies text to clipboard using the DOM.
  * @param {string} text
+ * @return {void}
  */
 export function copyToClipboardFallback(text) {
   const el = document.createElement('textarea');
@@ -853,6 +943,7 @@ export function copyToClipboardFallback(text) {
  * Read the value of a given key from an object.
  * @param {object} object
  * @param {string} key
+ * @return {object | undefined} The value of the key.
  */
 export function readFromObject(object, key) {
   const firstPeriodIndex = key.indexOf('.');
@@ -898,9 +989,9 @@ export function getElementPadding(element) {
 }
 
 /**
- * Returns the absolute width of an element.
+ * Returns the absolute height of an element.
  * @param {Element} element
- * @returns {number}
+ * @returns {number} The absolute height of the element including padding.
  */
 export function getAbsoluteHeight(element) {
   if (!element) {
@@ -916,7 +1007,7 @@ export function getAbsoluteHeight(element) {
 /**
  * Returns the absolute width of an element.
  * @param {Element} element
- * @returns {number}
+ * @returns {number} The absolute width of the element including padding.
  */
 export function getAbsoluteWidth(element) {
   if (!element) {