@telesign/boreal-web-components 0.1.0-alpha.0

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

@@ -0,0 +1,577 @@
+import { Host, h } from "@stencil/core";
+import { ALIGNMENT } from "../../../types/alignment";
+import { SIZES } from "../../../types/size";
+import { 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";
+/**
+ * Typography component for displaying text with various styles, sizes, and interactive features.
+ *
+ * @summary A comprehensive typography component that supports multiple text variants, sizes, alignments, states, and link functionality.
+ *
+ * @slot - The text displayed in the typography.
+ *
+ * @attr {string} variant - The variant of the typography for styling the text. Options: label, display, heading, subheading, helper, link, code, caption
+ * @attr {string} element - Defines the HTML element. For `heading` variant, the text size adjusts to the HTML heading level (`h1` through `h6`).
+ * @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} 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 {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.
+ * @attr {string} custom-class - Additional custom CSS class
+ *
+ * @property {string} variant - The variant of the typography for styling the text. Options: label, display, heading, subheading, helper, link, code, caption
+ * @property {string} element - Defines the HTML element. For `heading` variant, the text size adjusts to the HTML heading level (`h1` through `h6`).
+ * @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} 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 {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.
+ * @property {string} customClass - Additional custom CSS class
+ *
+ * @default 'display' - Default variant value
+ * @default 'p' - Default element value
+ * @default 'start' - Default align value
+ * @default 'md' - Default size value
+ * @default 'default' - Default state value
+ * @default false - Default isRequired 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 'download' - Default filename value
+ * @default '' - Default tooltipText value
+ */
+export class BdsTypography {
+    constructor() {
+        this.inheritedAttributes = {};
+        /** Typography visual variant. */
+        this.variant = VARIANT_TYPOGRAPHY.DISPLAY;
+        /** Typography size token. */
+        this.size = SIZES.M;
+        /** Visual state (if supported by variant). */
+        this.state = STATES.DEFAULT;
+        /** Additional custom CSS class. */
+        this.customClass = '';
+        /** HTML tag used for rendering. */
+        this.element = TAG_ELEMENT.P;
+        /** Text alignment. */
+        this.align = ALIGNMENT.START;
+        /** Enables text ellipsis. */
+        this.ellipsis = false;
+        /** Max lines when ellipsis is enabled. */
+        this.maxLines = 1;
+        /** Tooltip text (variant must support it). */
+        this.tooltipText = '';
+        /** Marks the field as required. */
+        this.isRequired = false;
+        /** For attribute when rendered as a label. */
+        this.htmlFor = undefined;
+        /** Link href when rendered as anchor. */
+        this.href = null;
+        /** Anchor target. */
+        this.target = null;
+        /** Enables download behavior for anchor. */
+        this.isDownloadable = false;
+        /** Suggested download filename. */
+        this.filename = FILENAME;
+        /** Sanitized href for security. */
+        this.sanitizedHref = '';
+    }
+    async updateSanitizedHref() {
+        if (this.getTagName === 'a' && this.href !== null) {
+            const { sanitizeUrl } = await import('@braintree/sanitize-url');
+            this.sanitizedHref = sanitizeUrl(this.href);
+        }
+        else
+            this.sanitizedHref = '';
+    }
+    async componentWillLoad() {
+        if (this.getTagName === TAG_ELEMENT.A && this.href !== null)
+            await this.updateSanitizedHref();
+        this.inheritedAttributes = {
+            ...inheritAriaAttributes(this.el),
+        };
+    }
+    get getTagName() {
+        if (this.variant === VARIANT_TYPOGRAPHY.LINK)
+            return TAG_ELEMENT.A;
+        return this.element.toLowerCase();
+    }
+    getVariantConfig() {
+        return VARIANT_CONFIG[this.variant] ?? {};
+    }
+    getAccessibilityTags() {
+        const { isRequired = null } = this.getVariantConfig();
+        const isInteractiveTag = ['a', 'label'].includes(this.getTagName);
+        return {
+            'aria-required': this.isRequired && isRequired,
+            'aria-disabled': this.state === STATES.DISABLED && isInteractiveTag,
+        };
+    }
+    getVariantStateStyles() {
+        const config = this.getVariantConfig();
+        return {
+            [`bds-typography--${this.variant}`]: true,
+            [`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--ellipsis': this.ellipsis && this.maxLines <= 1,
+            'bds-typography--ellipsis-multiline': this.ellipsis && this.maxLines > 1,
+            [this.customClass]: this.customClass !== '',
+        };
+    }
+    render() {
+        const TagName = this.getTagName;
+        const attributes = {
+            ...getAttributesByTag(this, TagName),
+            ...this.inheritedAttributes,
+            ...this.getAccessibilityTags(),
+        };
+        const classes = this.getVariantStateStyles();
+        const { canUseTooltip = null, isRequired = null } = this.getVariantConfig();
+        return (h(Host, { key: '6091692b1cb6bf1d3295f0834c8d25425633d65a', class: "bds-typography" }, h(TagName, { key: '0cc91c35fa1cc36c99101a79fae0c8b5cf44de43', class: classes, style: { webkitLineClamp: this.maxLines }, ...attributes }, h("slot", { key: '973848fba8211cb5ef869e0e48fb1806bd5efdec' }), this.isRequired && isRequired && (h("em", { key: 'dd89574e9dedd55905ae4c7bcd57604f26fbd03b', class: "bds-typography__required-indicator", "aria-hidden": "true" }, "*")), this.tooltipText && canUseTooltip && h("em", { key: '473b0de17bd095b97d54d24d2f3aa75f8a8e4922', class: "bds-typography__info-icon bds-icon-info-circle" }))));
+    }
+    static get is() { return "bds-typography"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["bds-typography.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["bds-typography.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "variant": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['variant']",
+                    "resolved": "\"caption\" | \"code\" | \"display\" | \"heading\" | \"helper\" | \"label\" | \"link\" | \"subheading\"",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Typography visual variant."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "variant",
+                "defaultValue": "VARIANT_TYPOGRAPHY.DISPLAY"
+            },
+            "size": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['size']",
+                    "resolved": "\"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\"",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Typography size token."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "size",
+                "defaultValue": "SIZES.M"
+            },
+            "state": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['state']",
+                    "resolved": "\"active\" | \"default\" | \"disabled\" | \"error\" | \"focus\" | \"hover\" | \"visited\"",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Visual state (if supported by variant)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "state",
+                "defaultValue": "STATES.DEFAULT"
+            },
+            "customClass": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Additional custom CSS class."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "custom-class",
+                "defaultValue": "''"
+            },
+            "element": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['element']",
+                    "resolved": "\"a\" | \"div\" | \"h1\" | \"h2\" | \"h3\" | \"h4\" | \"h5\" | \"h6\" | \"label\" | \"p\" | \"span\"",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "HTML tag used for rendering."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "element",
+                "defaultValue": "TAG_ELEMENT.P"
+            },
+            "align": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['align']",
+                    "resolved": "\"center\" | \"end\" | \"inherit\" | \"start\"",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Text alignment."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "align",
+                "defaultValue": "ALIGNMENT.START"
+            },
+            "ellipsis": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['ellipsis']",
+                    "resolved": "boolean",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Enables text ellipsis."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "ellipsis",
+                "defaultValue": "false"
+            },
+            "maxLines": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['maxLines']",
+                    "resolved": "number",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Max lines when ellipsis is enabled."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "max-lines",
+                "defaultValue": "1"
+            },
+            "tooltipText": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['tooltipText']",
+                    "resolved": "string",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Tooltip text (variant must support it)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "tooltip-text",
+                "defaultValue": "''"
+            },
+            "isRequired": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['isRequired']",
+                    "resolved": "boolean",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Marks the field as required."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "is-required",
+                "defaultValue": "false"
+            },
+            "htmlFor": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['htmlFor']",
+                    "resolved": "string",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "For attribute when rendered as a label."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "html-for",
+                "defaultValue": "undefined"
+            },
+            "href": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['href']",
+                    "resolved": "string",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Link href when rendered as anchor."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "href",
+                "defaultValue": "null"
+            },
+            "target": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['target']",
+                    "resolved": "\"\" | \"_blank\" | \"_parent\" | \"_self\" | \"_top\"",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Anchor target."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "target",
+                "defaultValue": "null"
+            },
+            "isDownloadable": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['isDownloadable']",
+                    "resolved": "boolean",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Enables download behavior for anchor."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "is-downloadable",
+                "defaultValue": "false"
+            },
+            "filename": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ITypography['filename']",
+                    "resolved": "string",
+                    "references": {
+                        "ITypography": {
+                            "location": "import",
+                            "path": "./types/ITypography",
+                            "id": "src/components/titles-text/bds-typography/types/ITypography.ts::ITypography",
+                            "referenceLocation": "ITypography"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Suggested download filename."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "filename",
+                "defaultValue": "FILENAME"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "sanitizedHref": {}
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "href",
+                "methodName": "updateSanitizedHref"
+            }];
+    }
+}

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

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

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

@@ -0,0 +1,23 @@
+export const VARIANT_TYPOGRAPHY = {
+    DISPLAY: 'display',
+    HEADING: 'heading',
+    SUBHEADING: 'subheading',
+    LABEL: 'label',
+    HELPER: 'helper',
+    LINK: 'link',
+    CODE: 'code',
+    CAPTION: 'caption',
+};
+export const TAG_ELEMENT = {
+    P: 'p',
+    H1: 'h1',
+    H2: 'h2',
+    H3: 'h3',
+    H4: 'h4',
+    H5: 'h5',
+    H6: 'h6',
+    SPAN: 'span',
+    DIV: 'div',
+    A: 'a',
+    LABEL: 'label',
+};

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

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

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

@@ -0,0 +1,41 @@
+import { STATES } from "../../../../types/states";
+import { SIZES } from "../../../../types/size";
+/*
+ * LINK consts
+ */
+export const FILENAME = 'download';
+/*
+ * Variant map to apply size, state, etc, styles based on variant type
+ */
+export const VARIANT_CONFIG = {
+    link: {
+        states: [STATES.DISABLED /* STATES.VISITED, STATES.HOVER, STATES.ACTIVE, STATES.FOCUS */],
+        size: [SIZES.S, SIZES.M],
+    },
+    label: {
+        states: [STATES.DISABLED],
+        isRequired: true,
+        canUseTooltip: true,
+    },
+    heading: { canUseTooltip: true },
+    subheading: { canUseTooltip: true },
+    helper: { states: [STATES.ERROR] },
+    display: { size: [SIZES.XS, SIZES.S, SIZES.M, SIZES.L, SIZES.XL] },
+};
+/*
+ * ATTRIBUTE MAP
+ */
+export const getAttributesByTag = (comp, tagName) => {
+    const ATTR_MAP = {
+        a: {
+            href: comp.state !== STATES.DISABLED ? comp.sanitizedHref : null,
+            target: comp.target,
+            download: comp.isDownloadable ? comp.filename : null,
+            rel: comp.target === '_blank' ? 'noopener noreferrer' : undefined,
+        },
+        label: {
+            htmlFor: comp.htmlFor,
+        },
+    };
+    return ATTR_MAP[tagName] || {};
+};