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

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

@@ -0,0 +1,75 @@
+@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;
+  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);
+  transform-origin: center;
+  inset: 0;
+}
+
+.tooltip-content[data-placement^=top] .tooltip-arrow {
+  bottom: calc(var(--tooltip-arrow-size) / -2);
+}
+
+.tooltip-content[data-placement^=bottom] .tooltip-arrow {
+  top: calc(var(--tooltip-arrow-size) / -2);
+}
+
+.tooltip-content[data-placement^=left] .tooltip-arrow {
+  right: calc(var(--tooltip-arrow-size) / -2);
+}
+
+.tooltip-content[data-placement^=right] .tooltip-arrow {
+  left: calc(var(--tooltip-arrow-size) / -2);
+}

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

@@ -0,0 +1,272 @@
+import { Host, Mixin, h } from "@stencil/core";
+import { anchoredMixin } from "../../../mixins/anchored.mixin";
+import { OFFSET } from "./constants/Offset";
+import { getOffset } from "../../../utils/helpers/overlays/getOffset";
+/**
+ * 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: getOffset(this.floatingOptions?.hideArrow, this.floatingOptions.offset, OFFSET),
+            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: '7ba6db9103d172c519e4f9bd3e8743ba506057f1', class: "tooltip" }, h("div", { key: 'bea4019c3c4d0d1ac605e3c7d5e35564c8173c9e', 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: 'f598c2b54709269fcb1d3335d86400cc3ab4a177', class: "tooltip-arrow", part: "arrow", ref: el => (this.arrowElement = el) })), h("slot", { key: '2a18a5c6839c21ec3c0a9f82b6117bded3c08b26' }))));
+    }
+    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/constants/Offset.js

@@ -0,0 +1 @@
+export const OFFSET = 4;

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,25 @@
+@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.bds-typography--disabled-cursor {
+  cursor: not-allowed;
+}
+
 .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

@@ -17,12 +17,12 @@ import { FILENAME, getAttributesByTag, VARIANT_CONFIG } from "./utils/bds-typogr
  * @attr {string} state - The state of the typography. Only available for the `helper` and `label` variants. Options: default, error, disabled, hover, active, focus, visited
  * @attr {string} align - The text alignment. Options: start, center, end, inherit
  * @attr {string} size - The size of the typography. For `display` variant all options are available (`xl`, `lg`, `md`, `sm`), while for `link` variant only `md` and `sm` are available.
- * @attr {boolean} is-required - Shows a required indicator when used with `label` variant.
+ * @attr {boolean} required - Shows a required indicator when used with `label` variant.
  * @attr {boolean} ellipsis - Truncates text with an ellipsis when it overflows.
  * @attr {number} max-lines - Maximum number of lines to show before truncating with ellipsis.
  * @attr {string} href - URL when the typography is an `a` element and a `link` variant.
  * @attr {string} target - Specifies where to open the link. Options: _self, _blank, _top, _parent
- * @attr {boolean} is-downloadable - Makes the `link` download a file.
+ * @attr {boolean} downloadable - Makes the `link` download a file.
  * @attr {string} filename - Suggested filename when downloading a file from the `link`.
  * @attr {string} html-for - The for attribute when rendered as a label
  * @attr {string} tooltip-text - Text to display inside the tooltip when hovering the info icon. Only applicable for `heading`, `subheading`, and `label` variants.
@@ -33,12 +33,12 @@ import { FILENAME, getAttributesByTag, VARIANT_CONFIG } from "./utils/bds-typogr
  * @property {string} state - The state of the typography. Only available for the `helper` and `label` variants. Options: default, error, disabled, hover, active, focus, visited
  * @property {string} align - The text alignment. Options: start, center, end, inherit
  * @property {string} size - The size of the typography. For `display` variant all options are available (`xl`, `lg`, `md`, `sm`), while for `link` variant only `md` and `sm` are available.
- * @property {boolean} isRequired - Shows a required indicator when used with `label` variant.
+ * @property {boolean} required - Shows a required indicator when used with `label` variant.
  * @property {boolean} ellipsis - Truncates text with an ellipsis when it overflows.
  * @property {number} maxLines - Maximum number of lines to show before truncating with ellipsis.
  * @property {string} href - URL when the typography is an `a` element and a `link` variant.
  * @property {string} target - Specifies where to open the link. Options: _self, _blank, _top, _parent
- * @property {boolean} isDownloadable - Makes the `link` download a file.
+ * @property {boolean} downloadable - Makes the `link` download a file.
  * @property {string} filename - Suggested filename when downloading a file from the `link`.
  * @property {string} htmlFor - The for attribute when rendered as a label
  * @property {string} tooltipText - Text to display inside the tooltip when hovering the info icon. Only applicable for `heading`, `subheading`, and `label` variants.
@@ -49,12 +49,12 @@ import { FILENAME, getAttributesByTag, VARIANT_CONFIG } from "./utils/bds-typogr
  * @default 'start' - Default align value
  * @default 'md' - Default size value
  * @default 'default' - Default state value
- * @default false - Default isRequired state
+ * @default false - Default required state
  * @default false - Default ellipsis state
  * @default 1 - Default maxLines value
  * @default '' - Default href value
  * @default '' - Default target value
- * @default false - Default isDownloadable state
+ * @default false - Default downloadable state
  * @default 'download' - Default filename value
  * @default '' - Default tooltipText value
  */
@@ -80,7 +80,7 @@ export class BdsTypography {
         /** Tooltip text (variant must support it). */
         this.tooltipText = '';
         /** Marks the field as required. */
-        this.isRequired = false;
+        this.required = false;
         /** For attribute when rendered as a label. */
         this.htmlFor = undefined;
         /** Link href when rendered as anchor. */
@@ -88,7 +88,7 @@ export class BdsTypography {
         /** Anchor target. */
         this.target = null;
         /** Enables download behavior for anchor. */
-        this.isDownloadable = false;
+        this.downloadable = false;
         /** Suggested download filename. */
         this.filename = FILENAME;
         /** Sanitized href for security. */
@@ -118,10 +118,10 @@ export class BdsTypography {
         return VARIANT_CONFIG[this.variant] ?? {};
     }
     getAccessibilityTags() {
-        const { isRequired = null } = this.getVariantConfig();
+        const { required = false } = this.getVariantConfig();
         const isInteractiveTag = ['a', 'label'].includes(this.getTagName);
         return {
-            'aria-required': this.isRequired && isRequired,
+            'aria-required': this.required && required,
             'aria-disabled': this.state === COMPONENT_STATES.DISABLED && isInteractiveTag,
         };
     }
@@ -132,7 +132,7 @@ export class BdsTypography {
             [`bds-typography--align-${this.align}`]: true,
             [`bds-typography--${this.state}`]: !!(config?.states && config?.states.includes(this.state)),
             [`bds-typography--size-${this.size}`]: !!(config?.size && config?.size.includes(this.size)),
-            'bds-typography--required': !!(config?.isRequired && this.isRequired),
+            'bds-typography--required': !!(config?.required && this.required),
             'bds-typography--ellipsis': this.ellipsis && this.maxLines <= 1,
             'bds-typography--ellipsis-multiline': this.ellipsis && this.maxLines > 1,
             [this.customClass]: this.customClass !== '',
@@ -146,8 +146,9 @@ export class BdsTypography {
             ...this.getAccessibilityTags(),
         };
         const classes = this.getVariantStateStyles();
-        const { canUseTooltip = null, isRequired = null } = this.getVariantConfig();
-        return (h(Host, { key: '80c41f5a33f3089005b9cdf2c7db51e07272b5df', class: "bds-typography" }, h(TagName, { key: '623e0a57bf2341ecaeba7e670d01a06f891f4423', class: classes, style: { webkitLineClamp: this.maxLines }, ...attributes }, h("slot", { key: 'fa7fa6e7f6cbe6133a1c52bf2f219b2927847a88' }), this.isRequired && isRequired && (h("em", { key: 'aa339d8fbf758491db17ac9c471327a0466bf3dc', class: "bds-typography__required-indicator", "aria-hidden": "true" }, "*")), this.tooltipText && canUseTooltip && h("em", { key: '98a6c58192b585fbbe01a93c031e9ae3c20cf3ca', class: "bds-typography__info-icon bds-icon-info-circle" }))));
+        const { canUseTooltip = null, required = null } = this.getVariantConfig();
+        const isDisabledState = this.state === COMPONENT_STATES.DISABLED;
+        return (h(Host, { key: 'a9b61038ed68ce72e8a96845ac3c082a6b635053', class: `bds-typography ${isDisabledState ? 'bds-typography--disabled-cursor' : ''}` }, h(TagName, { key: '3966152c29dd0af270676ab7af0aaf811b48624a', class: classes, style: { webkitLineClamp: this.maxLines }, ...attributes }, h("slot", { key: 'fe090f9278feac140d0d4b979912b332da5d6ec8' }), this.required && required && (h("em", { key: 'ccfd67dda34d927778ccf59a40cae185952f2495', class: "bds-typography__required-indicator", "aria-hidden": "true" }, "*")), this.tooltipText && canUseTooltip && (h("span", { key: '720ef78bd2e638e0d0be56918483fe227a011f5e' }, h("em", { key: '5e064aaed2633b33677e12774dead52ee0871f4a', class: "bds-typography__info-icon bds-icon-info-circle", "aria-label": this.tooltipText }, h("bds-tooltip", { key: '9ec65063f105cec050f01348a64e7b9f5fa8e968' }, this.tooltipText)))))));
     }
     static get is() { return "bds-typography"; }
     static get originalStyleUrls() {
@@ -398,11 +399,11 @@ export class BdsTypography {
                 "attribute": "tooltip-text",
                 "defaultValue": "''"
             },
-            "isRequired": {
+            "required": {
                 "type": "boolean",
                 "mutable": false,
                 "complexType": {
-                    "original": "ITypography['isRequired']",
+                    "original": "ITypography['required']",
                     "resolved": "boolean",
                     "references": {
                         "ITypography": {
@@ -422,7 +423,7 @@ export class BdsTypography {
                 "getter": false,
                 "setter": false,
                 "reflect": true,
-                "attribute": "is-required",
+                "attribute": "required",
                 "defaultValue": "false"
             },
             "htmlFor": {
@@ -506,11 +507,11 @@ export class BdsTypography {
                 "attribute": "target",
                 "defaultValue": "null"
             },
-            "isDownloadable": {
+            "downloadable": {
                 "type": "boolean",
                 "mutable": false,
                 "complexType": {
-                    "original": "ITypography['isDownloadable']",
+                    "original": "ITypography['downloadable']",
                     "resolved": "boolean",
                     "references": {
                         "ITypography": {
@@ -530,7 +531,7 @@ export class BdsTypography {
                 "getter": false,
                 "setter": false,
                 "reflect": false,
-                "attribute": "is-downloadable",
+                "attribute": "downloadable",
                 "defaultValue": "false"
             },
             "filename": {

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

@@ -14,7 +14,7 @@ export const VARIANT_CONFIG = {
     },
     label: {
         states: [COMPONENT_STATES.DISABLED],
-        isRequired: true,
+        required: true,
         canUseTooltip: true,
     },
     heading: { canUseTooltip: true },
@@ -30,7 +30,7 @@ export const getAttributesByTag = (comp, tagName) => {
         a: {
             href: comp.state !== COMPONENT_STATES.DISABLED ? comp.sanitizedHref : null,
             target: comp.target,
-            download: comp.isDownloadable ? comp.filename : null,
+            download: comp.downloadable ? comp.filename : null,
             rel: comp.target === '_blank' ? 'noopener noreferrer' : undefined,
         },
         label: {