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

package/dist/collection/mixins/floating.mixin.js

@@ -72,6 +72,16 @@ export const floatingMixin = (Base) => {
         get hooks() {
             return {};
         }
+        /**
+         * Default options for the floating mixin.
+         * Override this getter in the component to customize placement,
+         * offset, strategy, flip, shift, and arrow.
+         *
+         * @returns FloatingMixinOptions — default options for the mixin
+         */
+        get options() {
+            return {};
+        }
         /**
          * Called before the element is shown.
          * Aggregates both the component `hooks` and `floatingOptions` controls.

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,6 @@
 export * from './form-associated.mixin';
 export * from './floating.mixin';
 export * from './anchored.mixin';
+export * from './backdrop.mixin';
+export * from './menu-behavior.mixin';
+export * from './links.mixin';

package/dist/collection/mixins/links.mixin.js

@@ -0,0 +1,153 @@
+import { KEYBOARD } from "../utils/constants/common/Keys";
+/**
+ * Creates a mixin that adds link-related properties and behaviors to a base class.
+ * It provides computed attributes for links, handles keyboard interactions, and sanitizes URLs to ensure security.
+ * It allows components to easily handle link attributes and execute link events.
+ *
+ * This mixin includes:
+ *  - `href`: The URL the link points to.
+ *  - `newTab`: Whether the link should open in a new tab.
+ *  - `downloadable`: Whether the link should be treated as a download.
+ *  - `filename`: The filename to use when downloading.
+ *  - `getLinkAttributes`: A computed property that returns the appropriate attributes for the link based on its state and props.
+ *  - `handleLinkKeyDown`: A method to handle keyboard interactions for accessibility.
+ *  - `handleLinkClick`: A method to manage click behavior, including external links and downloads.
+ *  - `sanitizeUrl`: A utility method to sanitize URLs and prevent XSS vulnerabilities.
+ *
+ * @typeParam T - The base constructor type to extend.
+ * @param {T} Base - The base component class to be extended.
+ * @returns {WithLinks} - A class with injected link behaviors.
+ *
+ * @example
+ * ```tsx
+ *  import { Component, h } from '@stencil/core';
+ *  import { WithLinks } from '@/mixins/links.mixin';
+ *
+ * @Component({
+ *  tag: 'my-link',
+ *  styleUrl: 'my-link.scss',
+ *  })
+ *  class MyLink extends Mixin(WithLinks) {
+ *    @Element() el!: HTMLElement;
+ *    @Prop() href: string = '';
+ *    @Prop() newTab: boolean = false;
+ *    @Prop() downloadable: boolean = false;
+ *    @Prop() filename: string = '';
+ *    @Prop() disabled: boolean = false;
+ *
+ *    private handleKeyDown = (e: KeyboardEvent) => {
+ *      if (this.disabled) return;
+ *      this.handleLinkKeyDown(e);
+ *    };
+ *
+ *   render() {
+ *    return (
+ *      <Host
+ *      {...this.getLinkAttributes}
+ *      onKeyDown={this.handleKeyDown} >
+ *      <slot />
+ *      </Host>
+ *    );
+ *    }
+ * } ```
+ *
+ */
+export const WithLinks = (Base) => {
+    class WithLinks extends Base {
+        constructor() {
+            super(...arguments);
+            this.href = '';
+            this.newTab = false;
+            this.download = '';
+        }
+        get isLink() {
+            return this.href !== '' || this.download !== '';
+        }
+        /**
+         * Computes the appropriate link attributes based on the component's props and state.
+         * It handles external links, new tab behavior, and download attributes while ensuring accessibility.
+         * @returns {LinksAttrs} - The computed link attributes.
+         * */
+        get linkAttributes() {
+            const attributes = {};
+            if (!this.isLink)
+                return attributes;
+            const sanitizedHref = this.sanitizeUrl(this.href);
+            attributes.href = sanitizedHref;
+            attributes.target = this.newTab ? '_blank' : '_self';
+            attributes.rel =
+                this._isExternalLink(sanitizedHref) || this.newTab || this.download !== '' ? 'noopener noreferrer' : '';
+            attributes.download = this.download !== '' ? this.download : undefined;
+            if (this.el.tagName.toLowerCase() !== 'a') {
+                attributes.role = 'link';
+                attributes.tabindex = '0';
+            }
+            return attributes;
+        }
+        _isExternalLink(url) {
+            const isExternal = /^https?:\/\//.test(url) && !url.includes(window.location.hostname);
+            return isExternal;
+        }
+        /** Keydown handler to allow keyboard interaction with the link */
+        handleLinkKeyDown(event) {
+            if (!this.isLink)
+                return;
+            if (this.el.tagName.toLowerCase() !== 'a' &&
+                (event.key === KEYBOARD.Enter.key || event.key === KEYBOARD.Space.key)) {
+                event.preventDefault();
+                this.handleLinkClick(new MouseEvent('click', { bubbles: true, cancelable: true }));
+            }
+        }
+        /** Click handler to manage link behavior, including external links and downloads */
+        handleLinkClick(event) {
+            if (!this.isLink) {
+                event.preventDefault();
+                return;
+            }
+            const attributes = this.linkAttributes;
+            if (attributes.download !== '' && attributes.download !== undefined) {
+                event.preventDefault();
+                const logger = document.createElement('a');
+                logger.href = attributes.download || '';
+                logger.download = attributes.download;
+                logger.style.display = 'none';
+                document.body.appendChild(logger);
+                console.log('Initiating download:', logger.href);
+                logger.click();
+                document.body.removeChild(logger);
+            }
+            if (this.el.tagName.toLowerCase() !== 'a') {
+                if (attributes.target === '_blank') {
+                    window.open(attributes.href, '_blank', attributes.rel);
+                }
+                else {
+                    window.location.href = attributes.href || '';
+                }
+                event.preventDefault();
+            }
+        }
+        /** Sanitizes the URL to prevent XSS vulnerabilities. It removes dangerous protocols and ensures valid URLs.
+         * @param {string} url - The URL to sanitize.
+         * @returns {string} - The sanitized URL, or an empty string if the URL is deemed unsafe.
+         * @example
+         * const safeUrl = sanitizeUrl('https://example.com'); // returns 'https://example.com'
+         * const unsafeUrl = sanitizeUrl('javascript:alert(1)'); // returns ''
+         */
+        sanitizeUrl(url) {
+            const sanitized = url.trim().toLowerCase();
+            if (sanitized.startsWith('javascript:') || sanitized.startsWith('data:') || sanitized.includes('\0')) {
+                return '';
+            }
+            if (!sanitized.startsWith('http://') &&
+                !sanitized.startsWith('https://') &&
+                !sanitized.startsWith('mailto:') &&
+                !sanitized.startsWith('tel:') &&
+                !sanitized.startsWith('/') &&
+                !sanitized.startsWith('#')) {
+                return sanitized.startsWith('://') ? '' : `https://${url}`;
+            }
+            return url;
+        }
+    }
+    return WithLinks;
+};

package/dist/collection/mixins/menu-behavior.mixin.js

@@ -0,0 +1,113 @@
+import { handleMenuKeyNavigation, resolveMenuItemRole, resolveAriaSelected, resolveTabIndex, KEYBOARD, preventNavigationKeys, } from "../utils/index";
+/**
+ * A Mixin that provides menu item behaviors, including ARIA roles,
+ * focus management, and keyboard navigation logic.
+ * This mixin is designed to be used with Stencil components that represent items within a menu or listbox,
+ * allowing them to automatically adapt their behavior based on the context of their parent container.
+ *
+ * The mixin includes:
+ * - Dynamic ARIA role resolution based on the nearest parent menu or listbox.
+ * - Computation of aria-selected and tabIndex attributes for accessibility.
+ * - A method to handle keyboard navigation (Arrow keys, Enter, Space) within the menu context.
+ *
+ *
+ * @typeParam B - The base constructor type.
+ * @param {B} Base - The base component class to be extended.
+ * @returns {MenuBehaviorMixin} - A class with injected menu behaviors.
+ *
+ * @example
+ * ```tsx
+ * import { Component, h } from '@stencil/core';
+ * import { MenuItemBehavior } from '@/mixins/menu-behavior.mixin';
+ *
+ * @Component({
+ *  tag: 'my-menu-item',
+ *  styleUrl: 'my-menu-item.scss',
+ * })
+ * export class MyMenuItem extends Mixin(MenuItemBehavior) {
+ *   @Element() el!: HTMLElement;
+ *   @Prop() disabled: boolean = false;
+ *   @Prop() selected: boolean = false;
+ *
+ *   private handleKeyDown = (e: KeyboardEvent) => {
+ *     if (this.disabled) return;
+ *     this.handleKeyDownLogic(e, () => this.handleSelection());
+ *   };
+ *
+ *  render() {
+ *   return (
+ *    <Host
+ *      role={this.menuItemRole}
+ *      aria-selected={this.ariaSelected}
+ *      tabIndex={ this.itemTabIndex}
+ *      onKeyDown={this.handleKeyDown} >
+ *      <slot />
+ *    </Host>
+ *   );
+ *  }
+ * } ```
+ *
+ *
+ */
+export const MenuItemBehavior = (Base) => {
+    class MenuBehaviorMixin extends Base {
+        constructor() {
+            super(...arguments);
+            this.disabled = false;
+            this.selected = false;
+            this.activeItem = false;
+        }
+        /**
+         * Detects the ARIA role of the nearest parent menu or listbox.
+         * @returns {MenuRole | null} - 'menu', 'listbox', or null if not found.
+         */
+        get parentRole() {
+            const parent = this.el.closest('[role="menu"], [role="listbox"]');
+            return parent !== null ? parent.getAttribute('role') : null;
+        }
+        /**
+         * Resolves the specific item role ('menuitem' or 'option').
+         * Defaults to 'menuitem' if no parent is detected.
+         * @returns {MenuItemRole}
+         */
+        get menuItemRole() {
+            return resolveMenuItemRole(this.parentRole || 'menu');
+        }
+        /**
+         * Returns the 'aria-selected' value as a string for listbox options.
+         * @returns {string | null}
+         */
+        get ariaSelected() {
+            return resolveAriaSelected(this.menuItemRole, this.selected);
+        }
+        /**
+         * Calculates the tabIndex for the item.
+         * @returns {number} 0 for focusable menu items, -1 otherwise.
+         */
+        get itemTabIndex() {
+            return resolveTabIndex(this.menuItemRole, this.disabled, this.selected, this.activeItem);
+        }
+        /**
+         * Processes keyboard events for arrow navigation and activation.
+         * @param {KeyboardEvent} e - The native keyboard event.
+         * @param {() => void} onActivate - Function to execute when Enter or Space is pressed.
+         * @example
+         * // Inside a component's keydown listener:
+         * this.handleKeyDownLogic(event, () => this.emitSelection());
+         */
+        handleKeyDownLogic(e, onActivate) {
+            preventNavigationKeys(e);
+            if (e.key === KEYBOARD.Enter.key || e.key === KEYBOARD.Space.key) {
+                onActivate();
+                return;
+            }
+            const parent = this.el.closest("[role='menu'], [role='listbox']");
+            if (parent === null)
+                return;
+            const items = Array.from(parent.querySelectorAll(`${this.el.tagName.toLocaleLowerCase()}:not([disabled]):not([variant="label"])`));
+            const currentIndex = items.indexOf(this.el);
+            handleMenuKeyNavigation(e, items, currentIndex);
+        }
+    }
+    return MenuBehaviorMixin;
+};