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

package/dist/collection/components/overlays/bds-tooltip/bds-tooltip.css

@@ -0,0 +1,86 @@
+@charset "UTF-8";
+/**
+* Common SCSS placeholder selectors shared across form and layout components.
+* This file is injected globally via `injectGlobalPaths` in `stencil.config.ts`,
+* so all component stylesheets can `@extend` these placeholders without an explicit import.
+*
+* NOTE: Placeholders must only use raw CSS values — `$boreal-*` token variables
+* are not available at this level util use style-guidelines.
+*/
+/**
+ * TODO: Refactor to use styleguidelines this work as first draft
+ **/
+/**
+* This file contains mixins and functions for common interactions styles such as focus rings and transitions.
+* These are used across multiple components to ensure consistency in interaction feedback.
+*/
+:root {
+  --tooltip-arrow-size: var(--boreal-spacing-s);
+  --tooltip-width: 320px;
+}
+
+.tooltip-content {
+  position: fixed;
+  margin: 0;
+  border: 0;
+  overflow: visible;
+  border-radius: var(--boreal-radius-xs2);
+  background: var(--boreal-ui-black);
+  color: var(--boreal-text-inverse);
+  padding: var(--boreal-spacing-2xs) var(--boreal-spacing-s);
+  font-size: var(--boreal-typography-font-size-xs);
+  line-height: var(--boreal-typography-line-height-xs);
+  font-family: var(--boreal-typography-font-family-primary);
+  border: var(--boreal-spacing-2xs) solid var(--boreal-ui-black);
+  font-weight: var(--boreal-typography-font-weight-regular);
+}
+.tooltip-content--multiline {
+  white-space: normal;
+  max-width: var(--tooltip-width, 320px);
+  word-break: break-word;
+  text-align: center;
+}
+
+.tooltip-arrow {
+  position: absolute;
+  width: var(--tooltip-arrow-size);
+  height: var(--tooltip-arrow-size);
+  pointer-events: none;
+  z-index: -1;
+}
+.tooltip-arrow::before {
+  content: "";
+  position: absolute;
+  width: var(--tooltip-arrow-size);
+  height: var(--tooltip-arrow-size);
+  background: var(--boreal-ui-black);
+  transform: rotate(45deg);
+}
+
+.tooltip-content[data-placement^=top] .tooltip-arrow {
+  bottom: calc(var(--tooltip-arrow-size) / -2);
+}
+.tooltip-content[data-placement^=top] .tooltip-arrow::before {
+  top: 0;
+}
+
+.tooltip-content[data-placement^=bottom] .tooltip-arrow {
+  top: calc(var(--tooltip-arrow-size) / -2);
+}
+.tooltip-content[data-placement^=bottom] .tooltip-arrow::before {
+  top: 0;
+}
+
+.tooltip-content[data-placement^=left] .tooltip-arrow {
+  right: calc(var(--tooltip-arrow-size) / -2);
+}
+.tooltip-content[data-placement^=left] .tooltip-arrow::before {
+  left: 0;
+}
+
+.tooltip-content[data-placement^=right] .tooltip-arrow {
+  left: calc(var(--tooltip-arrow-size) / -2);
+}
+.tooltip-content[data-placement^=right] .tooltip-arrow::before {
+  left: 0;
+}

package/dist/collection/components/overlays/bds-tooltip/bds-tooltip.js

@@ -0,0 +1,270 @@
+import { Host, Mixin, h } from "@stencil/core";
+import { anchoredMixin } from "../../../mixins/anchored.mixin";
+/**
+ * Tooltip component that displays a short label anchored to a trigger element on hover.
+ *
+ * @summary Displays a floating tooltip anchored to a trigger element on mouseenter/mouseleave,
+ * with configurable placement, optional arrow, and multiline support.
+ *
+ * @slot - Default slot for the tooltip text content.
+ *
+ * @attr {boolean} disabled - When true, prevents the tooltip from being shown.
+ * @attr {boolean} multiline - When true, allows the tooltip content to wrap across multiple lines.
+ * @attr {Partial<FloatingTooltipProp>} floating-options - Configuration object for floating behavior.
+ *
+ * @csspart arrow - The arrow element pointing toward the trigger.
+ * @csspart tooltip-content - The inner content wrapper inside the tooltip.
+ *
+ * @cssprop data-placement - Reflects the resolved placement on the tooltip container element.
+ * @cssprop data-hidearrow - Reflects the hideArrow option on the tooltip container element.
+ * @cssprop data-multiline - Reflects the multiline prop on the tooltip container element.
+ */
+export class BdsTooltip extends Mixin(anchoredMixin) {
+    constructor() {
+        /**
+         * If true, allows multiline content in the tooltip.
+         * @default false
+         */
+        this.multiline = false;
+        /**
+         * If true, disables the tooltip.
+         * @default false
+         */
+        this.disabled = false;
+        /**
+         * Override default options for the floating mixin.
+         * This can be overridden by passing a different object to the `floatingOptions` prop.
+         */
+        this.floatingOptions = {};
+        this.isVisible = false;
+        super();
+    }
+    /**
+     * Returns the resolved options for the floating mixin, merging `floatingOptions`
+     * prop values with their defaults.
+     *
+     * @returns {FloatingMixinOptions} Resolved configuration used by the anchored mixin
+     * to position the tooltip.
+     * @override anchoredMixin.options
+     *
+     * @example
+     * // floatingOptions = { placement: 'top', hideArrow: true }
+     * this.options
+     * return { placement: 'top', offset: 8, arrow: undefined, strategy: 'fixed' }
+     */
+    get options() {
+        return {
+            placement: this.floatingOptions.placement ?? 'bottom',
+            offset: this.floatingOptions.offset ?? 8,
+            arrow: this.floatingOptions.hideArrow ? undefined : this.arrowElement,
+            strategy: 'fixed',
+        };
+    }
+    /**
+     * Returns the lifecycle hooks consumed by the anchored mixin to control
+     * tooltip visibility and positioning.
+     * @override anchoredMixin.hooks
+     *
+     * @returns {AnchoredHooks} Object containing the three hook callbacks:
+     * - `onPositionUpdate` — called after each positioning calculation.
+     * - `onBeforeShow` — called before the tooltip becomes visible; returning false cancels the show.
+     * - `onBeforeHide` — called before the tooltip is hidden; returning false cancels the hide.
+     */
+    get hooks() {
+        return {
+            onPositionUpdate: result => this.handlePosition(result),
+            onBeforeShow: () => this.validateShow(),
+            onBeforeHide: (el) => this.validateHide(el),
+            subscribeToTrigger: (el) => this.subscribe(el),
+        };
+    }
+    get canShowArrow() {
+        return !this.floatingOptions.hideArrow || false;
+    }
+    get getPlacement() {
+        return this.floatingOptions.placement || 'bottom';
+    }
+    /**
+     * Guard called by `onBeforeShow` to determine whether the tooltip is allowed to show.
+     *
+     * @returns {boolean} `true` if the tooltip is not disabled and may be shown; `false` otherwise.
+     */
+    validateShow() {
+        return !this.disabled;
+    }
+    /**
+     * Guard called by `onBeforeHide` to determine whether the tooltip is allowed to hide.
+     * When `stayOnHover` is enabled, hides are cancelled if the pointer is moving
+     * into the floating content element itself.
+     *
+     * @param target - The element the pointer is moving toward (relatedTarget of the mouseleave event).
+     * @returns {boolean} `true` if the tooltip should hide; `false` if the hide should be cancelled.
+     */
+    validateHide(target) {
+        if (this.floatingOptions.stayOnHover && target !== undefined && target.isConnected) {
+            const goingToFloating = this.floatingContent.contains(target) || this.floatingContent === target;
+            if (goingToFloating)
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Callback for `onPositionUpdate`. Applies the resolved placement as a
+     * `data-placement` attribute on the floating content element and delegates
+     * arrow positioning to `setArrowPosition`.
+     *
+     * @param result - The positioning result produced by the floating middleware.
+     */
+    handlePosition(result) {
+        this.floatingContent.setAttribute('data-placement', result.placement);
+        this.setArrowPosition(result);
+    }
+    /**
+     * Applies the arrow element's `x` and `y` coordinates calculated by the
+     * floating middleware. Skips the update when the arrow element is not
+     * connected to the DOM or when middleware data is absent.
+     *
+     * @param result - The positioning result that may contain `middlewareData.arrow`
+     * with the computed `x` and `y` offsets for the arrow element.
+     */
+    setArrowPosition(result) {
+        if (result.middlewareData?.arrow && !this.disabled && this.arrowElement?.isConnected) {
+            const { x: arrowX, y: arrowY } = result.middlewareData.arrow;
+            Object.assign(this.arrowElement.style, {
+                left: arrowX != null ? `${arrowX}px` : '',
+                top: arrowY != null ? `${arrowY}px` : '',
+            });
+        }
+    }
+    get hasMultiline() {
+        return this.multiline !== undefined && this.multiline;
+    }
+    get tooltipStyles() {
+        return {
+            'tooltip-content': true,
+            'tooltip-content--multiline': this.hasMultiline,
+        };
+    }
+    subscribe(trigger) {
+        if (trigger === undefined)
+            return;
+        trigger.setAttribute('part', 'tooltip-trigger');
+        trigger.setAttribute('ariaDescribedBy', 'tooltip-content');
+        trigger.addEventListener('mouseenter', () => this.show());
+        trigger.addEventListener('mouseleave', (e) => this.hide(e.target));
+    }
+    render() {
+        const classes = this.tooltipStyles;
+        return (h(Host, { key: '65758ffb473363eadce15b09704224a95304dbf2', class: "tooltip" }, h("div", { key: 'd488e67b2da3c788ccf8eb9b9eeb273b9d1c58be', id: "tooltip-content", part: "tooltip-content", class: classes, popover: "manual", role: "tooltip", "aria-hidden": this.isVisible ? 'false' : 'true', "data-placement": this.getPlacement, "data-multiline": this.multiline, "data-hidearrow": this.canShowArrow, ref: el => (this.floatingContent = el) }, this.canShowArrow && (h("div", { key: 'de86ff5432b49a2e31d94c6c8e16f33327ef5baa', class: "tooltip-arrow", part: "arrow", ref: el => (this.arrowElement = el) })), h("slot", { key: '8428151ba6b9b835f721be33cc61b1bacdba7494' }))));
+    }
+    static get is() { return "bds-tooltip"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["bds-tooltip.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["bds-tooltip.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "multiline": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITooltip['multiline']",
+                    "resolved": "boolean",
+                    "references": {
+                        "ITooltip": {
+                            "location": "import",
+                            "path": "./types/ITooltip",
+                            "id": "src/components/overlays/bds-tooltip/types/ITooltip.ts::ITooltip",
+                            "referenceLocation": "ITooltip"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "If true, allows multiline content in the tooltip."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "multiline",
+                "defaultValue": "false"
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITooltip['disabled']",
+                    "resolved": "boolean",
+                    "references": {
+                        "ITooltip": {
+                            "location": "import",
+                            "path": "./types/ITooltip",
+                            "id": "src/components/overlays/bds-tooltip/types/ITooltip.ts::ITooltip",
+                            "referenceLocation": "ITooltip"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "If true, disables the tooltip."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            },
+            "floatingOptions": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "Partial<FloatingTooltipProp>",
+                    "resolved": "FloatingTooltipProp",
+                    "references": {
+                        "Partial": {
+                            "location": "global",
+                            "id": "global::Partial"
+                        },
+                        "FloatingTooltipProp": {
+                            "location": "import",
+                            "path": "@/services",
+                            "id": "src/services/index.ts::FloatingTooltipProp",
+                            "referenceLocation": "FloatingTooltipProp"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Override default options for the floating mixin.\nThis can be overridden by passing a different object to the `floatingOptions` prop."
+                },
+                "getter": false,
+                "setter": false,
+                "defaultValue": "{}"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "isVisible": {}
+        };
+    }
+    static get elementRef() { return "el"; }
+}

package/dist/collection/components/overlays/bds-tooltip/types/ITooltip.js

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

package/dist/collection/components/titles-text/bds-typography/bds-typography.css

@@ -1,4 +1,21 @@
+@charset "UTF-8";
+/**
+* Common SCSS placeholder selectors shared across form and layout components.
+* This file is injected globally via `injectGlobalPaths` in `stencil.config.ts`,
+* so all component stylesheets can `@extend` these placeholders without an explicit import.
+*
+* NOTE: Placeholders must only use raw CSS values — `$boreal-*` token variables
+* are not available at this level util use style-guidelines.
+*/
+/**
+ * TODO: Refactor to use styleguidelines this work as first draft
+ **/
+/**
+* This file contains mixins and functions for common interactions styles such as focus rings and transitions.
+* These are used across multiple components to ensure consistency in interaction feedback.
+*/
 .bds-typography {
+  display: flex;
   box-sizing: border-box;
   font-family: var(--boreal-typography-font-family-primary);
   font-weight: var(--boreal-typography-font-weight-regular);

package/dist/collection/components/titles-text/bds-typography/bds-typography.js

@@ -1,7 +1,7 @@
 import { Host, h } from "@stencil/core";
 import { ALIGNMENT } from "../../../types/alignment";
 import { SIZES } from "../../../types/size";
-import { STATES } from "../../../types/states";
+import { COMPONENT_STATES } from "../../../types/states";
 import { inheritAriaAttributes } from "../../../utils/a11y/index";
 import { TAG_ELEMENT, VARIANT_TYPOGRAPHY } from "./types/enum";
 import { FILENAME, getAttributesByTag, VARIANT_CONFIG } from "./utils/bds-typography-utils";
@@ -66,7 +66,7 @@ export class BdsTypography {
         /** Typography size token. */
         this.size = SIZES.M;
         /** Visual state (if supported by variant). */
-        this.state = STATES.DEFAULT;
+        this.state = COMPONENT_STATES.DEFAULT;
         /** Additional custom CSS class. */
         this.customClass = '';
         /** HTML tag used for rendering. */
@@ -122,7 +122,7 @@ export class BdsTypography {
         const isInteractiveTag = ['a', 'label'].includes(this.getTagName);
         return {
             'aria-required': this.isRequired && isRequired,
-            'aria-disabled': this.state === STATES.DISABLED && isInteractiveTag,
+            'aria-disabled': this.state === COMPONENT_STATES.DISABLED && isInteractiveTag,
         };
     }
     getVariantStateStyles() {
@@ -147,7 +147,7 @@ export class BdsTypography {
         };
         const classes = this.getVariantStateStyles();
         const { canUseTooltip = null, isRequired = null } = this.getVariantConfig();
-        return (h(Host, { key: 'e816237127a0bec2f223c3c11c405830b3bc530f', class: "bds-typography" }, h(TagName, { key: '5428ad8d55990feae5190e19c6372445f76d504b', class: classes, style: { webkitLineClamp: this.maxLines }, ...attributes }, h("slot", { key: '5f5b95afd7799c988607174d45dfdffe018438a8' }), this.isRequired && isRequired && (h("em", { key: '5d57fc3a0aed14887df9fb03f2b279204e99861c', class: "bds-typography__required-indicator", "aria-hidden": "true" }, "*")), this.tooltipText && canUseTooltip && h("em", { key: '9b89f3e48de66ebcd27755d9ec19ef261b73250e', class: "bds-typography__info-icon bds-icon-info-circle" }))));
+        return (h(Host, { key: '98e236475142f2be85fcc227cd507d6cb8648928', class: "bds-typography" }, h(TagName, { key: 'eed74e216dc0832b5f4808ba72e1374198f60e1a', class: classes, style: { webkitLineClamp: this.maxLines }, ...attributes }, h("slot", { key: 'cc073f2d2a3840970c62296379514884564c3473' }), this.isRequired && isRequired && (h("em", { key: '299a88d69856603b6e73af9567fa91b1a1e7434f', class: "bds-typography__required-indicator", "aria-hidden": "true" }, "*")), this.tooltipText && canUseTooltip && (h("span", { key: 'c8fa478a8fbd4a70d0869b4c9d523a8a0e9803bf' }, h("em", { key: '0f6869a6dd7ab04b19acee773e54687dbd070af0', class: "bds-typography__info-icon bds-icon-info-circle", "aria-label": this.tooltipText }), h("bds-tooltip", { key: 'ec2dfc33b119bc3f60ec52e8bd10fdb16ea5cc2a' }, this.tooltipText))))));
     }
     static get is() { return "bds-typography"; }
     static get originalStyleUrls() {
@@ -241,7 +241,7 @@ export class BdsTypography {
                 "setter": false,
                 "reflect": true,
                 "attribute": "state",
-                "defaultValue": "STATES.DEFAULT"
+                "defaultValue": "COMPONENT_STATES.DEFAULT"
             },
             "customClass": {
                 "type": "string",

package/dist/collection/components/titles-text/bds-typography/utils/bds-typography-utils.js

@@ -1,4 +1,4 @@
-import { STATES } from "../../../../types/states";
+import { COMPONENT_STATES } from "../../../../types/states";
 import { SIZES } from "../../../../types/size";
 /*
  * LINK consts
@@ -9,17 +9,17 @@ export const FILENAME = 'download';
  */
 export const VARIANT_CONFIG = {
     link: {
-        states: [STATES.DISABLED /* STATES.VISITED, STATES.HOVER, STATES.ACTIVE, STATES.FOCUS */],
+        states: [COMPONENT_STATES.DISABLED /* STATES.VISITED, STATES.HOVER, STATES.ACTIVE, STATES.FOCUS */],
         size: [SIZES.S, SIZES.M],
     },
     label: {
-        states: [STATES.DISABLED],
+        states: [COMPONENT_STATES.DISABLED],
         isRequired: true,
         canUseTooltip: true,
     },
     heading: { canUseTooltip: true },
     subheading: { canUseTooltip: true },
-    helper: { states: [STATES.ERROR] },
+    helper: { states: [COMPONENT_STATES.ERROR] },
     display: { size: [SIZES.XS, SIZES.S, SIZES.M, SIZES.L, SIZES.XL] },
 };
 /*
@@ -28,7 +28,7 @@ export const VARIANT_CONFIG = {
 export const getAttributesByTag = (comp, tagName) => {
     const ATTR_MAP = {
         a: {
-            href: comp.state !== STATES.DISABLED ? comp.sanitizedHref : null,
+            href: comp.state !== COMPONENT_STATES.DISABLED ? comp.sanitizedHref : null,
             target: comp.target,
             download: comp.isDownloadable ? comp.filename : null,
             rel: comp.target === '_blank' ? 'noopener noreferrer' : undefined,

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

@@ -2,8 +2,7 @@ import { PositioningEngine } from "../services/floating/positioning.service";
 import { floatingMixin } from "./floating.mixin";
 import { Logger } from "../services/logger/Logger";
 import { autoUpdate } from "@floating-ui/dom";
-import { KEYBOARD } from "../utils/constants/common/Keys";
-import { EVENTS } from "../utils/constants/common/Events";
+import { EVENTS, KEYBOARD } from "../utils/constants/index";
 /**
  * Positioning and trigger mixin for anchor-based floating elements.
  *
@@ -79,6 +78,9 @@ import { EVENTS } from "../utils/constants/common/Events";
  */
 export const anchoredMixin = (Base) => {
     class Anchored extends floatingMixin(Base) {
+        constructor() {
+            super();
+        }
         /**
          * Default positioning options.
          * Override this getter in the component to customize placement,
@@ -87,6 +89,9 @@ export const anchoredMixin = (Base) => {
         get options() {
             return { placement: 'bottom', offset: 8, strategy: 'fixed' };
         }
+        get hooks() {
+            return {};
+        }
         /**
          * Shows the floating element using the Popover API
          * and starts position auto-update relative to `triggerSlot`.
@@ -109,7 +114,7 @@ export const anchoredMixin = (Base) => {
          * @returns `false` if `triggerSlot` is not set, otherwise delegates to super
          */
         onBeforeShow(target) {
-            if (this.triggerSlot === null) {
+            if (this.triggerSlot === null || this.triggerSlot === undefined) {
                 this.logger.error('AnchoredMixin.show', 'triggerSlot is required');
                 return false;
             }
@@ -196,7 +201,10 @@ export const anchoredMixin = (Base) => {
                 void this.updatePosition(triggerElement, floatingElement, options, onPositionUpdate);
             };
             sync(); // run once immediately
-            this.cleanupAutoUpdate = autoUpdate(triggerElement, floatingElement, sync);
+            this.cleanupAutoUpdate = autoUpdate(triggerElement, floatingElement, sync, {
+                elementResize: true,
+                layoutShift: true,
+            });
         }
         /**
          * Stops automatic position synchronization and clears the cleanup reference.
@@ -240,6 +248,24 @@ export const anchoredMixin = (Base) => {
             }
             this.stopAutoUpdate();
         }
+        subscribeToTrigger(trigger) {
+            if (this.hooks.subscribeToTrigger !== undefined)
+                this.hooks.subscribeToTrigger(trigger);
+        }
+        onBeforeLoad() {
+            const parent = this.el.parentElement;
+            if (parent === null)
+                return;
+            const trigger = parent.querySelector('[bds-tooltip], [bds-popover]') || parent;
+            if (trigger.isConnected) {
+                this.triggerSlot = trigger;
+                this.subscribeToTrigger(trigger);
+            }
+        }
+        componentDidLoad() {
+            this.onBeforeLoad();
+            this.hooks.onBeforeLoad?.(this.el);
+        }
         /**
          * Initializes the positioning engine, logger, and binds lifecycle methods
          * so they can be safely passed as event listener callbacks.
@@ -267,6 +293,7 @@ export const anchoredMixin = (Base) => {
             this.stopAutoUpdate();
             this.hide();
         }
+        static get elementRef() { return "el"; }
     }
     return Anchored;
 };