@telesign/boreal-web-components 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/collection/utils/menu/menu-item.utils.js

@@ -0,0 +1,81 @@
+import { KEYBOARD } from "../constants";
+/**
+ * Resolves the appropriate ARIA role for a menu item.
+ * @param {MenuRole} role - The role of the parent menu container ('menu' or 'listbox').
+ * @returns {MenuItemRole} - Returns 'menuitem' if parent is 'menu', otherwise 'option'.
+ * @example
+ * const itemRole = resolveMenuItemRole('menu'); // returns 'menuitem'
+ */
+export function resolveMenuItemRole(role) {
+    return role === 'menu' ? 'menuitem' : 'option';
+}
+/**
+ * Determines the aria-selected value based on the item's role and state.
+ * @param {MenuItemRole} role - The role of the item ('menuitem' or 'option').
+ * @param {boolean} selected - The current selection state of the item.
+ * @returns {string | null} - Returns the string representation of the boolean if role is 'option', otherwise null.
+ * @example
+ * const attr = resolveAriaSelected('option', true); // returns 'true'
+ * const attrNull = resolveAriaSelected('menuitem', true); // returns null
+ */
+export function resolveAriaSelected(role, selected) {
+    return role === 'option' ? String(selected) : null;
+}
+/**
+ * Resolves the tabIndex attribute for keyboard navigation.
+ * @param {MenuItemRole} role - The role of the item.
+ * @param {boolean} disabled - Whether the item is currently disabled.
+ * @param {boolean} selected - Whether the item is currently selected.
+ * @param {boolean} active - Whether the item is currently active.
+ * @returns {number} - Returns 0 for focusable menu items, or -1 for disabled/options.
+ * @example
+ * const index = resolveTabIndex('menuitem', false); // returns 0
+ * const indexDisabled = resolveTabIndex('menuitem', true); // returns -1
+ */
+export function resolveTabIndex(role, disabled, selected, active) {
+    if (disabled)
+        return -1;
+    if (role === 'option')
+        return selected || active ? 0 : -1;
+    if (role === 'menuitem')
+        return active ? 0 : -1;
+    return -1;
+}
+/**
+ * Manages focus and activation through keyboard events.
+ * @param {KeyboardEvent} event - The keyboard event object from the listener.
+ * @param {HTMLElement[]} items - An array of focusable HTML elements within the menu.
+ * @param {number} currentIndex - The index of the currently focused item.
+ * @returns {void}
+ * @example
+ * handleMenuKeyNavigation(event, menuItems, 2);
+ */
+export function handleMenuKeyNavigation(event, items, currentIndex) {
+    if (items.length === 0 || currentIndex === -1)
+        return;
+    let nextIndex = -1;
+    switch (event.key) {
+        case KEYBOARD.ArrowDown.key:
+            nextIndex = (currentIndex + 1) % items.length;
+            break;
+        case KEYBOARD.ArrowUp.key:
+            nextIndex = (currentIndex - 1 + items.length) % items.length;
+            break;
+        default:
+            return;
+    }
+    items[nextIndex].focus();
+}
+/** Prevents default browser behavior for specific navigation keys.
+ * @param {KeyboardEvent} e - The keyboard event to evaluate.
+ * @returns {void}
+ * @example
+ * // Inside a keydown listener:
+ * preventNavigationKeys(event);
+ */
+export function preventNavigationKeys(e) {
+    const navigationKeys = [KEYBOARD.ArrowDown.key, KEYBOARD.ArrowUp.key, KEYBOARD.Enter.key, KEYBOARD.Space.key];
+    if (navigationKeys.includes(e.key)) {
+        e.preventDefault();
+    }
+}

package/dist/collection/utils/testing/constants.js

@@ -0,0 +1,2 @@
+// Example utility file for common test constants.
+export const TEST_CONSTANT = 'This is a test constant used in many tests.';

package/dist/collection/utils/testing/fixtures.js

@@ -0,0 +1,6 @@
+// Example utility file for common test fixtures.
+export const TEST_FIXTURE = {
+    first: 'John',
+    middle: 'F.',
+    last: 'Doe',
+};

package/dist/collection/utils/testing/helpers.js

@@ -0,0 +1,16 @@
+/**
+ * Returns inner element of hydrated component
+ */
+export const getInner = (root) => root?.firstElementChild;
+/**
+ * Verify if exist an element and throw an error if it doesn't exist.
+ *
+ * @param condition The element or condition to evaluate.
+ * @param message Custom error message.
+ * @throws {Error} If the condition is false, null, or undefined.
+ */
+export function assertExists(condition, message) {
+    if (condition === null || condition === undefined) {
+        throw new Error(message);
+    }
+}

package/dist/collection/utils/testing/index.js

@@ -0,0 +1,4 @@
+export * from './constants';
+export * from './fixtures';
+export * from './helpers';
+export * from './mocks';

package/dist/collection/utils/testing/mocks/backdrop.js

@@ -0,0 +1,19 @@
+/**
+ * A backdrop mock used to test backdrop based components
+ */
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export function setupBackdropMocks() {
+    beforeAll(() => {
+        /**
+         * jsdom does not fully support HTMLDialogElement.
+         * Methods like `showModal` and `close` are not implemented,
+         * which causes tests to fail when using `<dialog>`.
+         * This mock works around the jsdom limitation.
+         *
+         * See: https://github.com/jestjs/jest/issues/13010
+         */
+        HTMLElement.prototype.showModal = jest.fn();
+        HTMLElement.prototype.close = jest.fn();
+    });
+}

package/dist/collection/utils/testing/mocks/console.js

@@ -0,0 +1,30 @@
+/**
+ * Registers `beforeEach`/`afterEach` hooks that silence `console.warn` for the
+ * enclosing `describe` block. Call at the top of any `describe` that expects
+ * prop-validation warnings but does not need to assert on them.
+ *
+ * For tests that need to assert on the warning call, create the spy manually
+ * inside the individual `it` block instead.
+ */
+export function suppressConsoleWarn() {
+    beforeEach(() => {
+        jest.spyOn(console, 'warn').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+}
+/**
+ * Registers `beforeEach`/`afterEach` hooks that silence `console.error` for the
+ * enclosing `describe` block. Use in components that rely on `ElementInternals`
+ * (FACE components) to suppress the Stencil mock-doc noise:
+ * "Property X was accessed on ElementInternals, but this property is not implemented."
+ */
+export function suppressConsoleError() {
+    beforeEach(() => {
+        jest.spyOn(console, 'error').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        jest.restoreAllMocks();
+    });
+}

package/dist/collection/utils/testing/mocks/elementInternals.js

@@ -0,0 +1,64 @@
+/**
+ * @file Mock implementation of ElementInternals for testing purposes.
+ * simulates the behavior of ElementInternals in a testing environment, allowing components
+ * that rely on form association and validation to be tested without a real browser environment.
+ */
+/**
+ * Mock class that simulates the behavior of ElementInternals for Stencil components.
+ * Allows handling validity states and form association in tests.
+ */
+export class ElementInternals {
+    constructor() {
+        /** Reference to the associated form element */
+        this.form = null;
+        this.setFormValue = jest.fn();
+        this.setValidity = jest.fn();
+        this.checkValidity = jest.fn(() => true);
+        this.reportValidity = jest.fn(() => true);
+        /**
+         * Simulate form submission by dispatching a submit event on the associated form
+         * This should be do it because in testing evironment doesn't exist requesSubmit method on form element,
+         * so we need to simulate it to test the submit behavior of the button component.
+         * */
+        this.requestSubmit = jest.fn(function () {
+            if (this.form !== null) {
+                this.form.dispatchEvent(new Event('submit', { cancelable: true, bubbles: true }));
+            }
+        });
+    }
+}
+/**
+ * Initializes the necessary mocks in the global environment
+ * to ensure that components relying on ElementInternals can function correctly during tests.
+ * This includes defining the attachInternals method on HTMLElement and simulating form submission methods.
+ */
+export function attachInternals() {
+    const window = globalThis.window;
+    const MockElementInternals = ElementInternals;
+    /** Initialize global ElementInternals mock if not already defined */
+    if (window.ElementInternals === undefined) {
+        window.ElementInternals = MockElementInternals;
+    }
+    /** Define attachInternals on HTMLElement prototype to enable form association in tests */
+    Object.defineProperty(HTMLElement.prototype, 'attachInternals', {
+        value: function () {
+            const internals = new MockElementInternals();
+            internals.form = this.closest('form');
+            return internals;
+        },
+        writable: true,
+        configurable: true,
+    });
+    /** Define requestSubmit on HTMLFormElement to simulate form submission */
+    if (typeof HTMLFormElement !== 'undefined' && typeof HTMLFormElement.prototype.requestSubmit === 'undefined') {
+        HTMLFormElement.prototype.requestSubmit = function () {
+            this.dispatchEvent(new Event('submit', { cancelable: true, bubbles: true }));
+        };
+    }
+    /** Define reset on HTMLFormElement to simulate form reset */
+    if (typeof HTMLFormElement !== 'undefined' && typeof HTMLFormElement.prototype.reset === 'undefined') {
+        HTMLFormElement.prototype.reset = function () {
+            this.dispatchEvent(new Event('reset', { cancelable: true, bubbles: true }));
+        };
+    }
+}

package/dist/collection/utils/testing/mocks/index.js

@@ -0,0 +1,4 @@
+export * from './elementInternals';
+export * from './console';
+export * from './backdrop';
+export * from './popover';

package/dist/collection/utils/testing/mocks/popover.js

@@ -0,0 +1,19 @@
+export function setupPopoverMocks() {
+    const mockResizeObserver = jest.fn().mockImplementation(() => ({
+        observe: jest.fn(),
+        unobserve: jest.fn(),
+        disconnect: jest.fn(),
+    }));
+    beforeEach(() => {
+        HTMLElement.prototype.showPopover = jest.fn();
+        HTMLElement.prototype.hidePopover = jest.fn();
+        HTMLElement.prototype.togglePopover = jest.fn();
+    });
+    beforeAll(() => {
+        global.ResizeObserver = mockResizeObserver;
+    });
+    afterEach(() => {
+        mockResizeObserver.mockClear();
+        jest.restoreAllMocks();
+    });
+}