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

package/dist/collection/components/forms/bds-flag/bds-flag.js

@@ -0,0 +1,454 @@
+import { getAssetPath, h, Host } from "@stencil/core";
+import { validatePropValue } from "../../../utils/index";
+import { Shape, AlignFlag, FlagIdentifier } from "./types";
+import { allCountries, FLAG_BASE_URL, GLOBAL } from "./constants";
+import { getNameFlag } from "./helpers/getNameFlag";
+/**
+ * Flag component used to display a country flag together with its corresponding label.
+ *
+ * @summary Renders a flag icon based on a country identifier and optionally displays
+ * the country name, short name, or call sign. Supports custom flag sources, different
+ * shapes, and flag alignment on either side of the label.
+ *
+ * @attr {boolean} label - When true, displays a textual label next to the flag.
+ * @attr {boolean} short-name - When true, displays the abbreviated country name (ISO2/ISO3) instead of the full name.
+ * @attr {boolean} call-sign - When true, displays the country calling code next to the label.
+ * @attr {string} country - Country value used to resolve the flag and label.
+ * @attr {AlignFlag} align-flag - Controls whether the flag is rendered on the left or right side.
+ * @attr {FlagIdentifier} identifier - Defines which country field is used to resolve the value.
+ * @attr {Shape} shape - Visual shape of the rendered flag.
+ * @attr {ICountry[]} custom-flags - Additional custom flag definitions that can override defaults.
+ *
+ * @property {boolean} label - Whether the country label should be displayed. Defaults to false.
+ * @property {boolean} shortName - Whether to display the abbreviated country name. Defaults to false.
+ * @property {boolean} callSign - Whether to display the country calling code. Defaults to false.
+ * @property {string} country - Country value used to find the matching flag entry. Defaults to ''.
+ * @property {AlignFlag} alignFlag - Position of the flag relative to the label. Defaults to `AlignFlag.LEFT`.
+ * @property {FlagIdentifier} identifier - Identifier used to resolve the country value. Defaults to `FlagIdentifier.CODE`.
+ * @property {Shape} shape - Shape variant used for the flag. Defaults to `Shape.RECTANGLE`.
+ * @property {ICountry[]} customFlags - List of custom flag definitions merged with the default catalog. Defaults to `[]`.
+ */
+export class BdsFlag {
+    constructor() {
+        /**
+         * Determines whether the flag is displayed on the left or right side of the label.
+         * @default AlignFlag.LEFT
+         */
+        this.alignFlag = AlignFlag.LEFT;
+        /**
+         * Whether the country calling code should be displayed next to the label.
+         * @default false
+         */
+        this.callSign = false;
+        /**
+         * Country value used to resolve the matching flag entry.
+         *
+         * The expected value depends on the configured `identifier`.
+         * @default ''
+         */
+        this.country = '';
+        /**
+         * Custom flag definitions merged with the default country catalog.
+         *
+         * Custom entries can override default asset sources when the same `iso2` is used.
+         * @default []
+         */
+        this.customFlags = [];
+        /**
+         * Defines which field should be used to identify the country.
+         * For example, code, iso2, or iso3.
+         * @default FlagIdentifier.CODE
+         */
+        this.identifier = FlagIdentifier.CODE;
+        /**
+         * Whether the country name label should be displayed next to the flag.
+         * @default false
+         */
+        this.label = false;
+        /**
+         * Visual shape used to render the flag.
+         * @default Shape.RECTANGLE
+         */
+        this.shape = Shape.RECTANGLE;
+        /**
+         * Whether the abbreviated country name (ISO2/ISO3) should be displayed instead of the full name.
+         * @default false
+         */
+        this.shortName = false;
+    }
+    checkPropValues() {
+        validatePropValue(Object.values(AlignFlag), AlignFlag.LEFT, this.el, 'alignFlag');
+        validatePropValue(Object.values(FlagIdentifier), FlagIdentifier.CODE, this.el, 'identifier');
+        validatePropValue(Object.values(Shape), Shape.RECTANGLE, this.el, 'shape');
+    }
+    componentWillLoad() {
+        this.checkPropValues();
+    }
+    /**
+     * Resolves the URL for a flag asset.
+     *
+     * If a matching custom flag entry exists and provides `flag_4x3`, that source is used.
+     * Otherwise, the asset URL is resolved from `FLAG_BASE_URL`. When `FLAG_BASE_URL` is an
+     * absolute URL (e.g. a CDN base), it is used directly. When it is a relative path, the
+     * asset is resolved through Stencil's `getAssetPath` and prefixed with the current origin.
+     *
+     * @param flag - Lowercase ISO2 flag code.
+     * @returns The absolute URL for the flag image.
+     */
+    flagUrl(flag) {
+        const custom = this.customFlags?.find(c => c.iso2.toLowerCase() === flag);
+        if (custom?.flag_4x3 !== undefined)
+            return custom.flag_4x3;
+        if (FLAG_BASE_URL.startsWith('http')) {
+            return `${FLAG_BASE_URL}${flag}.svg`;
+        }
+        return `${window.location.origin}${getAssetPath(`${FLAG_BASE_URL}${flag}.svg`)}`;
+    }
+    /**
+     * Resolves the current country configuration from the default and custom catalogs.
+     *
+     * The lookup field is determined by `identifier`. When `identifier` is `CODE`,
+     * the search is performed against the `country` field. For `ISO3`, the input
+     * is normalized to uppercase; otherwise it is normalized to lowercase.
+     *
+     * @returns The matching country object, or an empty fallback object when no match is found.
+     */
+    getCountry() {
+        const localCountries = [...allCountries, ...this.customFlags, GLOBAL];
+        const searchBy = (this.identifier === FlagIdentifier.CODE ? 'country' : this.identifier);
+        const value = this.identifier === FlagIdentifier.ISO3 ? this.country.toUpperCase() : this.country.toLowerCase();
+        const country = localCountries.find((auxCountry) => auxCountry[searchBy] === value);
+        return country || { country: '', iso2: '', iso3: '', name: '' };
+    }
+    /**
+     * Returns the formatted label text for the current country based on display configuration.
+     * @returns The label string to render and use as the aria-label value.
+     */
+    getCountryName() {
+        const { iso3, name, country, iso2 } = this.getCountry();
+        const result = this.getNameInternal(iso3, iso2, name, country);
+        return result;
+    }
+    /**
+     * Returns the normalized ISO2 code used to resolve the flag asset.
+     * @returns The lowercase ISO2 code for the current country.
+     */
+    getFlag() {
+        const flag = this.getCountry().iso2;
+        return flag.toLowerCase();
+    }
+    /**
+     * Delegates label generation to the shared flag naming utility.
+     * @param iso3 - ISO3 country code.
+     * @param iso2 - ISO2 country code.
+     * @param name - Full country name.
+     * @param country - Internal country code value.
+     * @returns The formatted label according to the current component configuration.
+     */
+    getNameInternal(iso3, iso2, name, country) {
+        return getNameFlag(iso3, iso2, name, country, this.identifier, this.label, this.shortName, this.callSign, this.alignFlag);
+    }
+    /**
+     * Determines if the current flag is the global flag based on the resolved country entry.
+     * @returns `true` if the current flag is the global flag, `false` otherwise.
+     */
+    get isGlobal() {
+        return this.getFlag() === 'global';
+    }
+    /**
+     * Returns the CSS class map for the Host element, reflecting the current alignment.
+     * @returns Class map applied to the Host element.
+     */
+    get flagClass() {
+        return {
+            'bds-flag': true,
+            'bds-flag--reverse': this.alignFlag === AlignFlag.RIGHT,
+        };
+    }
+    /**
+     * Returns the CSS class map for the inner flag span, reflecting shape and global state.
+     * @returns Class map applied to the flag image span.
+     */
+    get flagContentClass() {
+        return {
+            'bds-flag__flag--country': true,
+            [`bds-flag__flag--${this.shape}`]: true,
+            'bds-flag__flag--global': this.isGlobal,
+        };
+    }
+    render() {
+        const flag = this.getFlag();
+        const countryName = this.getCountryName();
+        const flagContentClass = this.flagContentClass;
+        const flagClass = this.flagClass;
+        const flagStyle = !this.isGlobal ? { backgroundImage: `url(${this.flagUrl(flag)})` } : {};
+        return (h(Host, { key: 'c8f41b293eb2cfb1313aaa5c1ecbd4de3bf2e27c', class: flagClass, "aria-label": countryName, role: "img" }, flag && h("span", { key: '21f885fe3f7de150dd3766d3c942a6131d420a26', class: flagContentClass, style: flagStyle, "aria-hidden": "true" }), h("span", { key: '08b819e1754ea9675306060ef1b8bcfa94546b09', class: "bds-flag__country", "aria-hidden": "true" }, countryName)));
+    }
+    static get is() { return "bds-flag"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["bds-flag.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["bds-flag.css"]
+        };
+    }
+    static get assetsDirs() { return ["./constants"]; }
+    static get properties() {
+        return {
+            "alignFlag": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "IFlag['alignFlag']",
+                    "resolved": "\"left\" | \"right\"",
+                    "references": {
+                        "IFlag": {
+                            "location": "import",
+                            "path": "./interfaces/IFlag",
+                            "id": "src/components/forms/bds-flag/interfaces/IFlag.ts::IFlag",
+                            "referenceLocation": "IFlag"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "AlignFlag.LEFT"
+                        }],
+                    "text": "Determines whether the flag is displayed on the left or right side of the label."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "align-flag",
+                "defaultValue": "AlignFlag.LEFT"
+            },
+            "callSign": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "IFlag['callSign']",
+                    "resolved": "boolean",
+                    "references": {
+                        "IFlag": {
+                            "location": "import",
+                            "path": "./interfaces/IFlag",
+                            "id": "src/components/forms/bds-flag/interfaces/IFlag.ts::IFlag",
+                            "referenceLocation": "IFlag"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Whether the country calling code should be displayed next to the label."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "call-sign",
+                "defaultValue": "false"
+            },
+            "country": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "IFlag['country']",
+                    "resolved": "string",
+                    "references": {
+                        "IFlag": {
+                            "location": "import",
+                            "path": "./interfaces/IFlag",
+                            "id": "src/components/forms/bds-flag/interfaces/IFlag.ts::IFlag",
+                            "referenceLocation": "IFlag"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "''"
+                        }],
+                    "text": "Country value used to resolve the matching flag entry.\n\nThe expected value depends on the configured `identifier`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "country",
+                "defaultValue": "''"
+            },
+            "customFlags": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "IFlag['customFlags']",
+                    "resolved": "ICountry[]",
+                    "references": {
+                        "IFlag": {
+                            "location": "import",
+                            "path": "./interfaces/IFlag",
+                            "id": "src/components/forms/bds-flag/interfaces/IFlag.ts::IFlag",
+                            "referenceLocation": "IFlag"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "[]"
+                        }],
+                    "text": "Custom flag definitions merged with the default country catalog.\n\nCustom entries can override default asset sources when the same `iso2` is used."
+                },
+                "getter": false,
+                "setter": false,
+                "defaultValue": "[]"
+            },
+            "identifier": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "IFlag['identifier']",
+                    "resolved": "\"code\" | \"iso2\" | \"iso3\"",
+                    "references": {
+                        "IFlag": {
+                            "location": "import",
+                            "path": "./interfaces/IFlag",
+                            "id": "src/components/forms/bds-flag/interfaces/IFlag.ts::IFlag",
+                            "referenceLocation": "IFlag"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "FlagIdentifier.CODE"
+                        }],
+                    "text": "Defines which field should be used to identify the country.\nFor example, code, iso2, or iso3."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "identifier",
+                "defaultValue": "FlagIdentifier.CODE"
+            },
+            "label": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "IFlag['label']",
+                    "resolved": "boolean",
+                    "references": {
+                        "IFlag": {
+                            "location": "import",
+                            "path": "./interfaces/IFlag",
+                            "id": "src/components/forms/bds-flag/interfaces/IFlag.ts::IFlag",
+                            "referenceLocation": "IFlag"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Whether the country name label should be displayed next to the flag."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "label",
+                "defaultValue": "false"
+            },
+            "shape": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "IFlag['shape']",
+                    "resolved": "\"circle\" | \"rectangle\" | \"square\"",
+                    "references": {
+                        "IFlag": {
+                            "location": "import",
+                            "path": "./interfaces/IFlag",
+                            "id": "src/components/forms/bds-flag/interfaces/IFlag.ts::IFlag",
+                            "referenceLocation": "IFlag"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "Shape.RECTANGLE"
+                        }],
+                    "text": "Visual shape used to render the flag."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "shape",
+                "defaultValue": "Shape.RECTANGLE"
+            },
+            "shortName": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "IFlag['shortName']",
+                    "resolved": "boolean",
+                    "references": {
+                        "IFlag": {
+                            "location": "import",
+                            "path": "./interfaces/IFlag",
+                            "id": "src/components/forms/bds-flag/interfaces/IFlag.ts::IFlag",
+                            "referenceLocation": "IFlag"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": "Whether the abbreviated country name (ISO2/ISO3) should be displayed instead of the full name."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "short-name",
+                "defaultValue": "false"
+            }
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "alignFlag",
+                "methodName": "checkPropValues"
+            }, {
+                "propName": "identifier",
+                "methodName": "checkPropValues"
+            }, {
+                "propName": "shape",
+                "methodName": "checkPropValues"
+            }];
+    }
+}