@govbr-ds/webcomponents 2.1.0 → 2.1.2

package/dist/collection/components/link/link.js

@@ -0,0 +1,699 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+import { Host, h } from "@stencil/core";
+import { handleNavigationClick } from "../../shared/utils/navigation";
+/**
+ * ## Design System
+ *
+ * Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o [Design System do GovBR](https://www.gov.br/ds/components/link?tab=designer).
+ *
+ * @category Navegação
+ * @status stable
+ * @slot default - Conteúdo do link (texto, ícones ou outros elementos).
+ * @part anchor - Parte exposta para o elemento âncora interno, usada para estilos customizados via `::part(anchor)`.
+ */
+export class Link {
+    constructor() {
+        /**
+         * URL de destino do link.
+         */
+        this.href = '#';
+        /**
+         * Controla como o componente integra a navegação mantendo `href` real no elemento navegável.
+         * - `native` (padrão): preserva o comportamento do navegador, conforme HTML/W3C.
+         * - `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navegação nativa para a SPA assumir.
+         * Cliques com modificadores, botão do meio ou `target` diferente de `_self` permanecem nativos.
+         */
+        this.navigationMode = 'native';
+        /**
+         * @deprecated Use `navigationMode="event"` e o evento `brNavigate`.
+         */
+        this.isSpaLinkBehavior = false;
+        /**
+         * Desativa o link, tornando-o não interativo.
+         * Quando `true`: remove o `href` (um `<a>` sem `href` sai da ordem de
+         * tabulação e não recebe foco, nem por clique), marca `aria-disabled="true"`
+         * e bloqueia o clique (sem navegação nem emissão de `brNavigate`).
+         * Se o link estiver focado no momento da desativação, o foco é removido.
+         * Útil para componentes como `br-pagination` e `br-wizard`.
+         */
+        this.disabled = false;
+        /**
+         * Exibe o link com o mesmo visual do componente `br-button`.
+         */
+        this.button = false;
+        /** Valor canônico de `aria-expanded`. */
+        this.ariaExpanded = null;
+        /** Valor canônico de `aria-selected`. */
+        this.ariaSelected = null;
+        /** Valor canônico de `aria-haspopup`. */
+        this.ariaHasPopup = null;
+        /** Valor canônico de `aria-current`. */
+        this.ariaCurrent = null;
+        /** Valor canônico de `aria-label`. */
+        this.ariaLabel = null;
+        /** Valor canônico de `aria-describedby`. */
+        this.ariaDescribedBy = null;
+        this.handleClick = (event) => {
+            if (this.disabled) {
+                event.preventDefault();
+                return;
+            }
+            if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+                return;
+            }
+            if (this.isSpaLinkBehavior && this.navigationMode === 'native') {
+                event.preventDefault();
+                const spaEvent = this.brSpaNavigate.emit({ event, href: this.href });
+                if (!spaEvent.defaultPrevented && typeof window !== 'undefined')
+                    window.history?.pushState(null, '', this.href);
+                return;
+            }
+            handleNavigationClick({
+                event,
+                href: this.href,
+                target: this.target,
+                navigationMode: this.navigationMode,
+                brNavigate: this.brNavigate,
+            });
+        };
+        this.getAnchorAttrs = () => {
+            const attrs = {};
+            if (this.linkRole)
+                attrs.role = this.linkRole;
+            const ariaExpanded = this.ariaExpanded ?? this.linkAriaExpanded;
+            const ariaSelected = this.ariaSelected ?? this.linkAriaSelected;
+            const ariaHasPopup = this.ariaHasPopup ?? this.linkAriaHaspopup;
+            const ariaCurrent = this.ariaCurrent ?? this.linkAriaCurrent;
+            const ariaLabel = this.ariaLabel ?? this.linkAriaLabel;
+            const ariaDescribedBy = this.ariaDescribedBy ?? this.linkAriaDescribedby;
+            if (ariaExpanded !== undefined)
+                attrs['aria-expanded'] = ariaExpanded;
+            if (ariaSelected !== undefined)
+                attrs['aria-selected'] = ariaSelected;
+            if (ariaHasPopup !== undefined)
+                attrs['aria-haspopup'] = ariaHasPopup;
+            if (ariaCurrent !== undefined && ariaCurrent !== null)
+                attrs['aria-current'] = ariaCurrent;
+            if (ariaLabel !== undefined)
+                attrs['aria-label'] = ariaLabel;
+            if (ariaDescribedBy !== undefined)
+                attrs['aria-describedby'] = ariaDescribedBy;
+            return attrs;
+        };
+        this.getRel = () => {
+            if (this.target === '_blank') {
+                // Garante noopener e noreferrer mesmo com rel customizado (mitiga tabnabbing).
+                const parts = new Set([...(this.rel ?? '').split(' ').filter(Boolean), 'noopener', 'noreferrer']);
+                return [...parts].join(' ');
+            }
+            return this.rel;
+        };
+    }
+    handleDisabledChange(isDisabled) {
+        // Remove o foco se o link for desativado enquanto focado: tabindex/href
+        // removidos não retiram um foco já aplicado.
+        if (isDisabled) {
+            this.el.shadowRoot?.querySelector('a')?.blur();
+        }
+    }
+    render() {
+        return (h(Host, { key: '3a2d7f49bfafc65412524d38a964a713ee1fe526' }, h("a", { key: 'eddc87987df0418b5fdde03b39cadbc2db73762b', part: "anchor", class: { 'br-button': this.button }, href: this.disabled ? undefined : this.href, target: this.target, rel: this.getRel(), download: this.download, hreflang: this.hreflang, referrerPolicy: this.referrerPolicy, type: this.type, "aria-disabled": this.disabled ? 'true' : null, onClick: this.handleClick, ...this.getAnchorAttrs() }, h("slot", { key: '74ece0d935b97cb91fd9d8df789f709dc3c5068d' }))));
+    }
+    static get is() { return "br-link"; }
+    static get encapsulation() { return "shadow"; }
+    static get delegatesFocus() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["link.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["link.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "href": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "URL de destino do link."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "href",
+                "defaultValue": "'#'"
+            },
+            "target": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'_self' | '_blank' | '_parent' | '_top'",
+                    "resolved": "\"_blank\" | \"_parent\" | \"_self\" | \"_top\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Define como o link ser\u00E1 aberto.\n- `_self`: abre no mesmo contexto de navega\u00E7\u00E3o\n- `_blank`: abre em nova aba ou janela\n- `_parent`: abre no contexto pai\n- `_top`: abre no contexto de n\u00EDvel superior"
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "target"
+            },
+            "rel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Rela\u00E7\u00E3o entre o documento atual e o destino (`rel`).\nQuando `target=\"_blank\"`, `noopener` e `noreferrer` s\u00E3o sempre inclu\u00EDdos\n(mesmo que `rel` seja definido) para mitigar tabnabbing e vazamento de `window.opener`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "rel"
+            },
+            "download": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Nome sugerido para download. Uma string vazia preserva o nome definido pelo servidor."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "download"
+            },
+            "hreflang": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Idioma do recurso apontado pelo link."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "hreflang"
+            },
+            "referrerPolicy": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ReferrerPolicy",
+                    "resolved": "\"\" | \"no-referrer\" | \"no-referrer-when-downgrade\" | \"origin\" | \"origin-when-cross-origin\" | \"same-origin\" | \"strict-origin\" | \"strict-origin-when-cross-origin\" | \"unsafe-url\"",
+                    "references": {
+                        "ReferrerPolicy": {
+                            "location": "global",
+                            "id": "global::ReferrerPolicy"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Pol\u00EDtica de referrer usada ao buscar o destino."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "referrer-policy"
+            },
+            "type": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Tipo MIME informativo do recurso apontado."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "type"
+            },
+            "navigationMode": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "BrNavigationMode",
+                    "resolved": "\"event\" | \"native\"",
+                    "references": {
+                        "BrNavigationMode": {
+                            "location": "import",
+                            "path": "../global.types",
+                            "id": "src/components/global.types.ts::BrNavigationMode",
+                            "referenceLocation": "BrNavigationMode"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Controla como o componente integra a navega\u00E7\u00E3o mantendo `href` real no elemento naveg\u00E1vel.\n- `native` (padr\u00E3o): preserva o comportamento do navegador, conforme HTML/W3C.\n- `event`: emite `brNavigate`; se o evento for cancelado, bloqueia a navega\u00E7\u00E3o nativa para a SPA assumir.\nCliques com modificadores, bot\u00E3o do meio ou `target` diferente de `_self` permanecem nativos."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "navigation-mode",
+                "defaultValue": "'native'"
+            },
+            "isSpaLinkBehavior": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `navigationMode=\"event\"` e o evento `brNavigate`."
+                        }],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "is-spa-link-behavior",
+                "defaultValue": "false"
+            },
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Desativa o link, tornando-o n\u00E3o interativo.\nQuando `true`: remove o `href` (um `<a>` sem `href` sai da ordem de\ntabula\u00E7\u00E3o e n\u00E3o recebe foco, nem por clique), marca `aria-disabled=\"true\"`\ne bloqueia o clique (sem navega\u00E7\u00E3o nem emiss\u00E3o de `brNavigate`).\nSe o link estiver focado no momento da desativa\u00E7\u00E3o, o foco \u00E9 removido.\n\u00DAtil para componentes como `br-pagination` e `br-wizard`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            },
+            "button": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Exibe o link com o mesmo visual do componente `br-button`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "button",
+                "defaultValue": "false"
+            },
+            "linkRole": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Encaminhamento de `role` para o elemento \u00E2ncora interno."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "link-role"
+            },
+            "linkAriaExpanded": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `ariaExpanded`."
+                        }],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "link-aria-expanded"
+            },
+            "ariaExpanded": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Valor can\u00F4nico de `aria-expanded`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "aria-expanded",
+                "defaultValue": "null"
+            },
+            "linkAriaSelected": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `ariaSelected`."
+                        }],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "link-aria-selected"
+            },
+            "ariaSelected": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Valor can\u00F4nico de `aria-selected`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "aria-selected",
+                "defaultValue": "null"
+            },
+            "linkAriaHaspopup": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `ariaHasPopup`."
+                        }],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "link-aria-haspopup"
+            },
+            "ariaHasPopup": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Valor can\u00F4nico de `aria-haspopup`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "aria-haspopup",
+                "defaultValue": "null"
+            },
+            "linkAriaCurrent": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `ariaCurrent`."
+                        }],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "link-aria-current"
+            },
+            "ariaCurrent": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Valor can\u00F4nico de `aria-current`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "aria-current",
+                "defaultValue": "null"
+            },
+            "linkAriaLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `ariaLabel`."
+                        }],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "link-aria-label"
+            },
+            "ariaLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Valor can\u00F4nico de `aria-label`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "aria-label",
+                "defaultValue": "null"
+            },
+            "linkAriaDescribedby": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `ariaDescribedBy`."
+                        }],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "link-aria-describedby"
+            },
+            "ariaDescribedBy": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Valor can\u00F4nico de `aria-describedby`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "aria-describedby",
+                "defaultValue": "null"
+            }
+        };
+    }
+    static get events() {
+        return [{
+                "method": "brNavigate",
+                "name": "brNavigate",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Evento cancel\u00E1vel emitido em `navigation-mode=\"event\"` para cliques prim\u00E1rios sem modificadores em links `_self`.\nChame `event.preventDefault()` no listener para impedir a navega\u00E7\u00E3o nativa e entregar `event.detail.href` ao roteador da SPA."
+                },
+                "complexType": {
+                    "original": "BrNavigateDetail",
+                    "resolved": "BrNavigateDetail",
+                    "references": {
+                        "BrNavigateDetail": {
+                            "location": "import",
+                            "path": "../global.types",
+                            "id": "src/components/global.types.ts::BrNavigateDetail",
+                            "referenceLocation": "BrNavigateDetail"
+                        }
+                    }
+                }
+            }, {
+                "method": "brSpaNavigate",
+                "name": "brSpaNavigate",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `brNavigate`."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "BrNavigateDetail",
+                    "resolved": "BrNavigateDetail",
+                    "references": {
+                        "BrNavigateDetail": {
+                            "location": "import",
+                            "path": "../global.types",
+                            "id": "src/components/global.types.ts::BrNavigateDetail",
+                            "referenceLocation": "BrNavigateDetail"
+                        }
+                    }
+                }
+            }];
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "disabled",
+                "methodName": "handleDisabledChange"
+            }];
+    }
+}