@coveo/quantic 3.39.0 → 3.39.1

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

@@ -0,0 +1,214 @@
+import {
+  AriaLiveRegion,
+  isFocusable,
+  getFirstFocusableElement,
+  getLastFocusableElement,
+  isCustomElement,
+  isParentOf,
+} from 'c/quanticUtils';
+
+describe('accessibilityUtils', () => {
+  describe('AriaLiveRegion', () => {
+    let elem;
+
+    beforeEach(() => {
+      elem = {dispatchEvent: jest.fn()};
+    });
+
+    it('should dispatch a register region event on creation', () => {
+      AriaLiveRegion('test-region', elem);
+      expect(elem.dispatchEvent).toHaveBeenCalledTimes(1);
+      const event = elem.dispatchEvent.mock.calls[0][0];
+      expect(event.type).toBe('quantic__registerregion');
+      expect(event.detail).toEqual({
+        regionName: 'test-region',
+        assertive: false,
+      });
+    });
+
+    it('should dispatch a register region event with assertive flag', () => {
+      AriaLiveRegion('test-region', elem, true);
+      const event = elem.dispatchEvent.mock.calls[0][0];
+      expect(event.detail.assertive).toBe(true);
+    });
+
+    it('should dispatch an aria live message event when dispatchMessage is called', () => {
+      const region = AriaLiveRegion('test-region', elem);
+      region.dispatchMessage('hello');
+      expect(elem.dispatchEvent).toHaveBeenCalledTimes(2);
+      const event = elem.dispatchEvent.mock.calls[1][0];
+      expect(event.type).toBe('quantic__arialivemessage');
+      expect(event.detail).toEqual({
+        regionName: 'test-region',
+        assertive: false,
+        message: 'hello',
+      });
+    });
+  });
+
+  describe('isFocusable', () => {
+    function createElement(tag, attrs = {}) {
+      const el = document.createElement(tag);
+      Object.entries(attrs).forEach(([k, v]) => el.setAttribute(k, v));
+      return el;
+    }
+
+    it('should return true for a button', () => {
+      expect(isFocusable(createElement('button'))).toBe(true);
+    });
+
+    it('should return false for a disabled button', () => {
+      expect(isFocusable(createElement('button', {disabled: ''}))).toBe(false);
+    });
+
+    it('should return true for an anchor with href', () => {
+      expect(isFocusable(createElement('a', {href: '#'}))).toBe(true);
+    });
+
+    it('should return false for an anchor without href', () => {
+      expect(isFocusable(createElement('a'))).toBe(false);
+    });
+
+    it('should return true for an input', () => {
+      expect(isFocusable(createElement('input'))).toBe(true);
+    });
+
+    it('should return false for a disabled input', () => {
+      expect(isFocusable(createElement('input', {disabled: ''}))).toBe(false);
+    });
+
+    it('should return true for an element with tabindex >= 0', () => {
+      expect(isFocusable(createElement('div', {tabindex: '0'}))).toBe(true);
+    });
+
+    it('should return false for an element with tabindex -1', () => {
+      expect(isFocusable(createElement('div', {tabindex: '-1'}))).toBe(false);
+    });
+
+    it('should return true for a contentEditable element', () => {
+      expect(isFocusable(createElement('div', {contentEditable: 'true'}))).toBe(
+        true
+      );
+    });
+
+    it('should return false for a plain div', () => {
+      expect(isFocusable(createElement('div'))).toBe(false);
+    });
+
+    it('should return true for an iframe', () => {
+      expect(isFocusable(createElement('iframe'))).toBe(true);
+    });
+
+    it('should return true for a select', () => {
+      expect(isFocusable(createElement('select'))).toBe(true);
+    });
+
+    it('should return true for a textarea', () => {
+      expect(isFocusable(createElement('textarea'))).toBe(true);
+    });
+  });
+
+  describe('isCustomElement', () => {
+    it('should return true for elements with a hyphen in the tag name', () => {
+      const el = document.createElement('my-component');
+      expect(isCustomElement(el)).toBe(true);
+    });
+
+    it('should return false for standard elements', () => {
+      const el = document.createElement('div');
+      expect(isCustomElement(el)).toBe(false);
+    });
+
+    it('should return false for null', () => {
+      expect(isCustomElement(null)).toBe(false);
+    });
+  });
+
+  describe('getFirstFocusableElement', () => {
+    it('should return null for null input', () => {
+      expect(getFirstFocusableElement(null)).toBeNull();
+    });
+
+    it('should return the element itself if it is focusable and has no focusable children', () => {
+      const btn = document.createElement('button');
+      expect(getFirstFocusableElement(btn)).toBe(btn);
+    });
+
+    it('should return the first focusable child', () => {
+      const div = document.createElement('div');
+      const span = document.createElement('span');
+      const btn1 = document.createElement('button');
+      const btn2 = document.createElement('button');
+      div.appendChild(span);
+      div.appendChild(btn1);
+      div.appendChild(btn2);
+      expect(getFirstFocusableElement(div)).toBe(btn1);
+    });
+
+    it('should return null for a custom element without data-focusable', () => {
+      const el = document.createElement('my-component');
+      expect(getFirstFocusableElement(el)).toBeNull();
+    });
+
+    it('should return the custom element if data-focusable is true', () => {
+      const el = document.createElement('my-component');
+      el.dataset.focusable = 'true';
+      expect(getFirstFocusableElement(el)).toBe(el);
+    });
+
+    it('should return null for a text node', () => {
+      const text = document.createTextNode('hello');
+      expect(getFirstFocusableElement(text)).toBeNull();
+    });
+  });
+
+  describe('getLastFocusableElement', () => {
+    it('should return null for null input', () => {
+      expect(getLastFocusableElement(null)).toBeNull();
+    });
+
+    it('should return the last focusable child', () => {
+      const div = document.createElement('div');
+      const btn1 = document.createElement('button');
+      const btn2 = document.createElement('button');
+      div.appendChild(btn1);
+      div.appendChild(btn2);
+      expect(getLastFocusableElement(div)).toBe(btn2);
+    });
+
+    it('should return the element itself if it is focusable and has no focusable children', () => {
+      const input = document.createElement('input');
+      expect(getLastFocusableElement(input)).toBe(input);
+    });
+  });
+
+  describe('isParentOf', () => {
+    it('should return false for null', () => {
+      expect(isParentOf(null, 'MY-COMPONENT')).toBe(false);
+    });
+
+    it('should return true if the element itself matches the target tag', () => {
+      const el = document.createElement('my-component');
+      expect(isParentOf(el, 'MY-COMPONENT')).toBe(true);
+    });
+
+    it('should return true if a descendant matches the target tag', () => {
+      const wrapper = document.createElement('div');
+      const child = document.createElement('my-component');
+      wrapper.appendChild(child);
+      expect(isParentOf(wrapper, 'MY-COMPONENT')).toBe(true);
+    });
+
+    it('should return false if no descendant matches', () => {
+      const wrapper = document.createElement('div');
+      const child = document.createElement('span');
+      wrapper.appendChild(child);
+      expect(isParentOf(wrapper, 'MY-COMPONENT')).toBe(false);
+    });
+
+    it('should return false for a text node', () => {
+      const text = document.createTextNode('hello');
+      expect(isParentOf(text, 'MY-COMPONENT')).toBe(false);
+    });
+  });
+});

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

@@ -0,0 +1,86 @@
+import {Store} from 'c/quanticUtils';
+
+describe('storeUtils', () => {
+  describe('Store.facetTypes', () => {
+    it('should expose the expected facet type keys', () => {
+      expect(Store.facetTypes).toEqual({
+        FACETS: 'facets',
+        NUMERICFACETS: 'numericFacets',
+        DATEFACETS: 'dateFacets',
+        CATEGORYFACETS: 'categoryFacets',
+      });
+    });
+  });
+
+  describe('Store.initialize', () => {
+    it('should return a store with empty state', () => {
+      const store = Store.initialize();
+      expect(store).toEqual({
+        state: {
+          facets: {},
+          numericFacets: {},
+          dateFacets: {},
+          categoryFacets: {},
+          sort: {},
+        },
+      });
+    });
+  });
+
+  describe('Store.registerFacetToStore', () => {
+    it('should register facet data under the given facet type and id', () => {
+      const store = Store.initialize();
+      const data = {facetId: 'author', label: 'Author'};
+      Store.registerFacetToStore(store, 'facets', data);
+      expect(store.state.facets.author).toEqual(data);
+    });
+
+    it('should not overwrite an existing facet entry', () => {
+      const store = Store.initialize();
+      const data = {facetId: 'author', label: 'Author'};
+      Store.registerFacetToStore(store, 'facets', data);
+      Store.registerFacetToStore(store, 'facets', {
+        facetId: 'author',
+        label: 'Updated',
+      });
+      expect(store.state.facets.author.label).toBe('Author');
+    });
+  });
+
+  describe('Store.registerSortOptionDataToStore', () => {
+    it('should set sort data on the store', () => {
+      const store = Store.initialize();
+      const sortData = [{label: 'Relevance', value: 'relevance'}];
+      Store.registerSortOptionDataToStore(store, sortData);
+      expect(store.state.sort).toBe(sortData);
+    });
+  });
+
+  describe('Store.getFromStore', () => {
+    it('should return facet data for the given type', () => {
+      const store = Store.initialize();
+      const data = {facetId: 'source', label: 'Source'};
+      Store.registerFacetToStore(store, 'facets', data);
+      expect(Store.getFromStore(store, 'facets')).toEqual({source: data});
+    });
+
+    it('should return an empty object when no facets are registered', () => {
+      const store = Store.initialize();
+      expect(Store.getFromStore(store, 'facets')).toEqual({});
+    });
+  });
+
+  describe('Store.getSortOptionsFromStore', () => {
+    it('should return the sort options', () => {
+      const store = Store.initialize();
+      const sortData = [{label: 'Date', value: 'date'}];
+      Store.registerSortOptionDataToStore(store, sortData);
+      expect(Store.getSortOptionsFromStore(store)).toBe(sortData);
+    });
+
+    it('should return an empty object when no sort options are registered', () => {
+      const store = Store.initialize();
+      expect(Store.getSortOptionsFromStore(store)).toEqual({});
+    });
+  });
+});

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

@@ -0,0 +1,225 @@
+/**
+ * AriaLiveUtils
+ * @typedef {Object} AriaLiveUtils
+ * @property {Function} dispatchMessage
+ * @property {Function} registerRegion
+ */
+
+/**
+ * AriaLiveRegion Create an AriaLiveRegion to be able to send events to dispatch messages for assistive technologies.
+ * @param {string} regionName
+ * @param {Object} elem
+ * @param {boolean} assertive
+ * @returns {AriaLiveUtils} Object with methods to dispatch messages and register the region.
+ */
+export function AriaLiveRegion(regionName, elem, assertive = false) {
+  function dispatchMessage(message) {
+    const ariaLiveMessageEvent = new CustomEvent('quantic__arialivemessage', {
+      bubbles: true,
+      composed: true,
+      detail: {
+        regionName,
+        assertive,
+        message,
+      },
+    });
+    elem.dispatchEvent(ariaLiveMessageEvent);
+  }
+
+  function registerRegion() {
+    const registerRegionEvent = new CustomEvent('quantic__registerregion', {
+      bubbles: true,
+      composed: true,
+      detail: {
+        regionName,
+        assertive,
+      },
+    });
+    elem.dispatchEvent(registerRegionEvent);
+  }
+
+  registerRegion();
+
+  return {
+    dispatchMessage,
+    registerRegion,
+  };
+}
+
+/**
+ * Checks whether an element is focusable.
+ * @param {HTMLElement | Element}  element
+ * @returns {boolean}
+ */
+export function isFocusable(element) {
+  // Source: https://stackoverflow.com/a/30753870
+  if (element.getAttribute('tabindex') === '-1') {
+    return false;
+  }
+  if (
+    element.hasAttribute('tabindex') ||
+    element.getAttribute('contentEditable') === 'true'
+  ) {
+    return true;
+  }
+  switch (element.tagName) {
+    case 'A':
+    case 'AREA':
+      return element.hasAttribute('href');
+    case 'INPUT':
+    case 'SELECT':
+    case 'TEXTAREA':
+    case 'BUTTON':
+      return !element.hasAttribute('disabled');
+    case 'IFRAME':
+      return true;
+    default:
+      return false;
+  }
+}
+
+/**
+ * Returns the last focusable element of for an HTML element.
+ * This function would NOT work with shadow root.
+ * @param {HTMLElement & {assignedElements?: () => Array<HTMLElement>} | null} element
+ * @returns {HTMLElement | null}
+ */
+export function getLastFocusableElement(element) {
+  if (!element || element.nodeType === Node.TEXT_NODE) return null;
+
+  if (isCustomElement(element)) {
+    if (element.dataset?.focusable?.toString() === 'true') {
+      return element;
+    }
+    return null;
+  }
+
+  if (element.tagName === 'SLOT' && element.assignedElements().length) {
+    return getLastFocusableElementFromSlot(element);
+  }
+
+  /** @type {Array} */
+  const childNodes = Array.from(element.childNodes);
+  const focusableElements = childNodes
+    .map((item) => getLastFocusableElement(item))
+    .filter((item) => !!item);
+
+  if (focusableElements.length) {
+    return focusableElements[focusableElements.length - 1];
+  } else if (isFocusable(element)) {
+    return element;
+  }
+  return null;
+}
+
+/**
+ * Returns the First focusable element of for an HTML element.
+ * This function would NOT work with shadow root.
+ * @param {HTMLElement & {assignedElements?: () => Array<HTMLElement>} | null} element
+ * @returns {HTMLElement | null}
+ */
+export function getFirstFocusableElement(element) {
+  if (!element || element.nodeType === Node.TEXT_NODE) return null;
+
+  if (isCustomElement(element)) {
+    if (element.dataset?.focusable?.toString() === 'true') {
+      return element;
+    }
+    return null;
+  }
+
+  if (element.tagName === 'SLOT' && element.assignedElements().length) {
+    return getFirstFocusableElementFromSlot(element);
+  }
+
+  /** @type {Array} */
+  const childNodes = Array.from(element.childNodes);
+  const focusableElements = childNodes
+    .map((item) => getFirstFocusableElement(item))
+    .filter((item) => !!item);
+
+  if (focusableElements.length) {
+    return focusableElements[0];
+  } else if (isFocusable(element)) {
+    return element;
+  }
+  return null;
+}
+
+/**
+ * Checks whether an element is a custom element.
+ * @param {HTMLElement | null} element
+ * @returns {boolean}
+ */
+export function isCustomElement(element) {
+  if (element && element.tagName.includes('-')) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * 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) {
+    return null;
+  }
+  const assignedElements = Array.from(slotElement.assignedElements());
+  const focusableElements = assignedElements
+    .map((item) => getLastFocusableElement(item))
+    .filter((item) => !!item);
+
+  if (focusableElements.length) {
+    return focusableElements[focusableElements.length - 1];
+  }
+  return null;
+}
+
+/**
+ * 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) {
+    return null;
+  }
+  const assignedElements = Array.from(slotElement.assignedElements());
+  const focusableElements = assignedElements
+    .map((item) => getFirstFocusableElement(item))
+    .filter((item) => !!item);
+
+  if (focusableElements.length) {
+    return focusableElements[0];
+  }
+  return null;
+}
+
+/**
+ * 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) {
+    return false;
+  }
+
+  if (isCustomElement(element)) {
+    if (element.tagName === targetElement) {
+      return true;
+    }
+    return false;
+  }
+  /** @type {Array} */
+  const childNodes = Array.from(element.childNodes);
+  if (childNodes.length === 0) return false;
+  return childNodes.reduce(
+    (acc, val) => acc || isParentOf(val, targetElement),
+    false
+  );
+}

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

@@ -0,0 +1,65 @@
+/** @typedef {import("coveo").SortCriterion} SortCriterion */
+
+/**
+ * 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',
+    NUMERICFACETS: 'numericFacets',
+    DATEFACETS: 'dateFacets',
+    CATEGORYFACETS: 'categoryFacets',
+  };
+  static initialize() {
+    return {
+      state: {
+        facets: {},
+        numericFacets: {},
+        dateFacets: {},
+        categoryFacets: {},
+        sort: {},
+      },
+    };
+  }
+  /**
+   * 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
+   */
+  static registerFacetToStore(store, facetType, data) {
+    if (store?.state[facetType][data.facetId]) {
+      return;
+    }
+    store.state[facetType][data.facetId] = data;
+  }
+
+  /**
+   * Registers sort option data to the store.
+   * @param {Record<String, any>} store
+   * @param {Array<{label: string; value: string; criterion: SortCriterion;}>} data
+   */
+  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;
+  }
+}