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

package/dist/collection/mixins/form-associated.mixin.js

@@ -1,94 +1,28 @@
 /**
  * Shared base mixin for Form-Associated Custom Elements in Boreal DS.
  *
- * Provides:
- * - `name`, `disabled`, and `required` form props
- * - `formDisabledCallback` with universal disabled sync behavior
+ * Provides `formDisabledCallback` — the only behavior that is identical across
+ * all FACE components. It writes to the component's `isDisabled` state, which
+ * each component must declare as `@State() private isDisabled: boolean = false`.
  *
- * Each component must declare `@AttachInternals() internals!: ElementInternals`
- * directly on its class body — Stencil's compiler requires this decorator to be
- * statically visible on the component class, not inside a mixin factory.
+ * Each component must declare directly on its class body:
+ * - `@AttachInternals() internals!: ElementInternals`
+ * - `@Prop({ reflect: true }) readonly name!: string`
+ * - `@Prop({ reflect: true }) readonly disabled: boolean = false`
+ * - `@Prop({ reflect: true }) readonly required: boolean = false`
+ * - `@State() private isDisabled: boolean = false`
+ * - `@Watch('disabled') onDisabledChange(next: boolean) { this.isDisabled = next; }`
+ *
+ * Stencil's compiler requires `@Prop` and `@State` decorators to be statically
+ * visible on the component class — they cannot be inherited from a mixin.
  *
  * Components must also implement `IFormControl<T>` for value registration,
  * reset, state restoration, and 2-way binding event emission.
  */
 export const formAssociatedMixin = (Base) => {
     class FormAssociated extends Base {
-        constructor() {
-            /** Disables the control. Synced automatically from a parent `<fieldset>` or `<form>` via `formDisabledCallback`. */
-            this.disabled = false;
-            /** Marks the control as required for form submission. */
-            this.required = false;
-            super();
-        }
-        /**
-         * Sync component disabled state with parent form disabled state.
-         */
         formDisabledCallback(disabled) {
-            this.disabled = disabled;
-        }
-        static get properties() {
-            return {
-                "name": {
-                    "type": "string",
-                    "mutable": false,
-                    "complexType": {
-                        "original": "string",
-                        "resolved": "string",
-                        "references": {}
-                    },
-                    "required": true,
-                    "optional": false,
-                    "docs": {
-                        "tags": [],
-                        "text": "Name of the form control, submitted as a key in the form data."
-                    },
-                    "getter": false,
-                    "setter": false,
-                    "reflect": true,
-                    "attribute": "name"
-                },
-                "disabled": {
-                    "type": "boolean",
-                    "mutable": true,
-                    "complexType": {
-                        "original": "boolean",
-                        "resolved": "boolean",
-                        "references": {}
-                    },
-                    "required": false,
-                    "optional": false,
-                    "docs": {
-                        "tags": [],
-                        "text": "Disables the control. Synced automatically from a parent `<fieldset>` or `<form>` via `formDisabledCallback`."
-                    },
-                    "getter": false,
-                    "setter": false,
-                    "reflect": true,
-                    "attribute": "disabled",
-                    "defaultValue": "false"
-                },
-                "required": {
-                    "type": "boolean",
-                    "mutable": false,
-                    "complexType": {
-                        "original": "boolean",
-                        "resolved": "boolean",
-                        "references": {}
-                    },
-                    "required": false,
-                    "optional": false,
-                    "docs": {
-                        "tags": [],
-                        "text": "Marks the control as required for form submission."
-                    },
-                    "getter": false,
-                    "setter": false,
-                    "reflect": true,
-                    "attribute": "required",
-                    "defaultValue": "false"
-                }
-            };
+            this.isDisabled = disabled;
         }
     }
     return FormAssociated;

package/dist/collection/mixins/index.js

@@ -1,3 +1,4 @@
 export * from './form-associated.mixin';
 export * from './floating.mixin';
 export * from './anchored.mixin';
+export * from './backdrop.mixin';

package/dist/collection/services/floating/index.js

@@ -0,0 +1,3 @@
+export * from './positioning.service';
+export * from './interfaces';
+export * from './types';

package/dist/collection/services/floating/interfaces/Anchored.js

@@ -0,0 +1 @@
+export {};

package/dist/collection/services/floating/interfaces/Backdrop.js

@@ -0,0 +1 @@
+export {};

package/dist/collection/services/floating/interfaces/index.js

@@ -0,0 +1,5 @@
+export * from './Floating';
+export * from './Props';
+export * from './Anchored';
+export * from './Positioning';
+export * from './Backdrop';

package/dist/collection/services/floating/types/index.js

@@ -0,0 +1 @@
+export * from './Arrow';

package/dist/collection/services/index.js

@@ -0,0 +1,2 @@
+export * from './floating';
+export * from './logger';

package/dist/collection/services/logger/index.js

@@ -0,0 +1 @@
+export * from './Logger';

package/dist/collection/types/position.js

@@ -9,3 +9,9 @@ export const POSITION = {
     LEFT: 'left',
     RIGHT: 'right',
 };
+export const POPOVER_POSITION = {
+    TOP: 'top-start',
+    BOTTOM: 'bottom-start',
+    LEFT: 'left',
+    RIGHT: 'right',
+};

package/dist/collection/utils/__test__/backdrop-mock.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/__test__/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/__test__/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/__test__/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/__test__/index.js

@@ -0,0 +1,6 @@
+export * from './constants';
+export * from './fixtures';
+export * from './popover-mock';
+export * from './backdrop-mock';
+export * from './helpers';
+export * from './mocks';

package/dist/collection/utils/__test__/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/__test__/mocks/index.js

@@ -0,0 +1 @@
+export * from './ElementInternals';

package/dist/collection/utils/__test__/popover-mock.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();
+    });
+}

package/dist/collection/utils/constants/common/Aria.js

@@ -0,0 +1,10 @@
+/**
+ * Centralized list of `aria-label` values used by interactive elements.
+ * Add new entries to the `ARIA_LABELS` object to keep labels consistent
+ * and prevent typos across the design system.
+ */
+export const ARIA_LABELS = {
+    Clear: 'Clear',
+    ShowPassword: 'Show password',
+    HidePassword: 'Hide password',
+};

package/dist/collection/utils/constants/common/Events.js

@@ -7,4 +7,5 @@ export const EVENTS = {
     Focus: 'focus',
     Blur: 'blur',
     Click: 'click',
+    BdsClick: 'bdsClick',
 };

package/dist/collection/utils/constants/common/Icons.js

@@ -0,0 +1,16 @@
+/**
+ * Centralized list of icon font-class names used by design-system components.
+ * Add new entries to the `ICONS` object to keep class names consistent
+ * and prevent typos across the design system.
+ */
+export const ICONS = {
+    Close: 'bds-icon-close',
+    ChevronDown: 'bds-icon-chevron-down',
+    InfoCircle: 'bds-icon-info-circle',
+    InfoCircleFill: 'bds-icon-info-circle-fill',
+    CheckCircleFill: 'bds-icon-check-circle-fill',
+    WarningTriangleFill: 'bds-icon-info-major-triangle-up-fill',
+    AlertCircleFill: 'bds-icon-alert-circle-fill',
+    SightOn: 'bds-icon-sight-on',
+    SightOff: 'bds-icon-sight-off',
+};

package/dist/collection/utils/constants/common/index.js

@@ -0,0 +1,4 @@
+export * from './Aria';
+export * from './Events';
+export * from './Icons';
+export * from './Keys';

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

@@ -0,0 +1 @@
+export * from './common';

package/dist/collection/utils/form/internals.js

@@ -22,7 +22,7 @@
  * ```
  */
 export function setFormValue(internals, value) {
-    internals.setFormValue(value);
+    internals.setFormValue?.(value);
 }
 /**
  * Runs an array of validators against the host element and reports the combined
@@ -74,6 +74,6 @@ export function runValidators(internals, validators, el) {
         }
     }
     const valid = Object.keys(flags).length === 0;
-    internals.setValidity(valid ? {} : flags, firstMessage);
+    internals.setValidity?.(valid ? {} : flags, firstMessage);
     return valid;
 }

package/dist/collection/utils/helpers/common/BaseAttributes.js

@@ -1,17 +1,10 @@
 /**
- * Ensure the given component instance has an auto-generated id if one wasn't provided.
- * Designed to be called from `componentWillLoad` on a Stencil component.
+ * Generates a stable random ID for internal ARIA linkage.
+ * Used by components to wire labels, descriptions, and controls
+ * without exposing the ID as a public prop.
+ *
+ * @param prefix - Component-specific prefix for readability in DevTools.
  */
-export function createId(component) {
-    if (!component.idComponent)
-        component.idComponent = `bds-${Math.random().toString(36).substr(2, 9)}`;
-}
-/**
- * Components can spread the result into their host.
- */
-export function getBaseAttributes(component) {
-    createId(component);
-    return {
-        id: component.idComponent,
-    };
+export function createId(prefix = 'bds') {
+    return `${prefix}-${Math.random().toString(36).substr(2, 9)}`;
 }

package/dist/collection/utils/helpers/common/index.js

@@ -0,0 +1 @@
+export * from './BaseAttributes';

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

@@ -0,0 +1,2 @@
+export * from './common';
+export * from './validateProps';

package/dist/collection/utils/index.js

@@ -1,3 +1,6 @@
 export * from './a11y';
 export * from './dom';
 export * from './form';
+export * from './helpers';
+export * from './__test__';
+export * from './constants';