@govbr-ds/webcomponents 2.1.0 → 2.1.2

package/dist/collection/components/switch/switch.js

@@ -0,0 +1,715 @@
+/*!
+ * Construído por SERPRO
+ * © https://serpro.gov.br/ - MIT License.
+ */
+import { Host, h, } from "@stencil/core";
+import { redispatchNativeFormEvent } from "../../shared/utils/event";
+import { getCheckableFormValue, getCheckableRestoreState, getFormValidationState, isFormControlDisabled, safeSetFormValue, syncNativeFormValidity, } from "../../shared/utils/form";
+import { generateUniqueId } from "../../shared/utils/id";
+import { hasAssignedSlotContent, hasDefaultLightDomContent } from "../../shared/utils/slot";
+import { resolveFormValidator, runFormValidator } from "../../shared/utils/validator";
+/**
+ * ## 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/switch?tab=designer).
+ *
+ * @category Formulários
+ * @status stable
+ * @slot default - Slot para o rótulo do switch, com prioridade sobre a propriedade label.
+ * @slot feedback - Mensagem de validação, normalmente um `br-message`.
+ *
+ * @part container - Contêiner visual do switch.
+ * @part input - Elemento input nativo com role switch.
+ * @part label - Rótulo do switch.
+ * @part data - Elemento com textos de estado ligado/desligado.
+ * @part feedback - Contêiner da mensagem de validação.
+ */
+export class Switch {
+    constructor() {
+        // Propriedade interna para verificar a presença de conteúdo no slot default
+        this._slotDefault = false;
+        this.formDisabled = false;
+        this.hasFeedbackSlot = false;
+        this.manualValidationMessage = '';
+        this.validatorMessage = null;
+        this.isValidating = false;
+        /**
+         * Desativa o switch, tornando-o não interativo.
+         */
+        this.disabled = false;
+        /**
+         * Se verdadeiro, o switch é obrigatório e deve ser ativado antes que o formulário possa ser enviado.
+         */
+        this.required = false;
+        /**
+         * Define o estado de seleção do checkbox.
+         * Se definido como verdadeiro, o checkbox estará marcado. Caso contrário, estará desmarcado.
+         */
+        this.checked = false;
+        /**
+         * Identificador único; gerado automaticamente quando omitido.
+         */
+        this.customId = generateUniqueId();
+        /**
+         * Posição do rótulo em relação ao switch.
+         */
+        this.labelPosition = 'left';
+        /**
+         * Adiciona um ícone ao switch para indicar a mudança de estado.
+         * @deprecated Use `showIcon`.
+         */
+        this.hasIcon = false;
+        /** Ajusta a área de interação: `small` é compacto, `medium` é o padrão e `large` é mais espaçado. */
+        this.density = 'medium';
+        this.validationRunId = 0;
+        this.initialChecked = false;
+        this.handleCheckedInput = (event) => {
+            if (this.isDisabled()) {
+                return;
+            }
+            this.checked = event.target.checked;
+            this.checkedChange.emit(this.checked);
+            redispatchNativeFormEvent(this.el, event, 'input');
+        };
+        this.handleCheckedChange = (event) => {
+            redispatchNativeFormEvent(this.el, event, 'change');
+            void this.validate();
+        };
+        this.handleClick = (event) => {
+            if (this.isDisabled()) {
+                event.preventDefault();
+            }
+            event.stopPropagation();
+        };
+    }
+    formDisabledCallback(disabled) {
+        this.formDisabled = disabled;
+    }
+    formResetCallback() {
+        if (this.nativeInput) {
+            this.nativeInput.setCustomValidity('');
+        }
+        this.manualValidationMessage = '';
+        this.validatorMessage = null;
+        this.validationRunId++;
+        this.checked = this.initialChecked;
+        this.syncFormState();
+    }
+    formStateRestoreCallback(state) {
+        this.checked = state === 'checked';
+        this.syncFormState();
+    }
+    checkedChanged() {
+        this.syncFormState();
+    }
+    componentWillLoad() {
+        this._hasSlotContentDefault();
+        this.initialChecked = this.checked;
+        this.syncFormState();
+    }
+    componentDidLoad() {
+        this.hasFeedbackSlot = this.el.querySelector('[slot="feedback"]') !== null;
+        this.updateValidity();
+    }
+    componentDidUpdate() {
+        this.updateValidity();
+    }
+    /**
+     * Retorna `true` se o valor do switch for válido, caso contrário `false`.
+     * Se o switch for inválido, dispara um evento 'invalid'.
+     */
+    async checkValidity() {
+        return this.elementInternals?.checkValidity?.() ?? true;
+    }
+    /**
+     * Retorna `true` se o valor do componente for válido, caso contrário `false`.
+     * Se for inválido, exibe a mensagem de erro padrão do navegador.
+     */
+    async reportValidity() {
+        return this.elementInternals?.reportValidity?.() ?? true;
+    }
+    /**
+     * Define uma mensagem de validação customizada para o switch.
+     * Se a mensagem for uma string vazia, o erro customizado é limpo.
+     */
+    async setCustomValidity(message) {
+        this.manualValidationMessage = message;
+        if (this.nativeInput) {
+            this.nativeInput.setCustomValidity(message);
+            this.updateValidity();
+        }
+    }
+    /** Executa o validator do switch e retorna se o valor atual é válido. */
+    async validate() {
+        const validator = resolveFormValidator(this.validator);
+        if (!validator || this.isDisabled())
+            return this.checkValidity();
+        const runId = ++this.validationRunId;
+        this.isValidating = true;
+        this.validatorMessage = null;
+        this.updateValidity();
+        this.brSwitchValidationChange.emit({ validating: true, valid: null, message: null });
+        const message = await runFormValidator(validator, this.checked);
+        if (runId !== this.validationRunId)
+            return false;
+        this.validatorMessage = message;
+        this.isValidating = false;
+        this.updateValidity();
+        const valid = message === null && (await this.checkValidity());
+        this.brSwitchValidationChange.emit({ validating: false, valid, message });
+        return valid;
+    }
+    /** Retorna um snapshot serializável da Constraint Validation API. */
+    async getValidationState() {
+        return getFormValidationState(this.elementInternals);
+    }
+    /**
+     * Inverte o valor da prop `checked`
+     * @deprecated Atualize a propriedade `checked` diretamente.
+     */
+    async toggleChecked() {
+        if (this.isDisabled()) {
+            return;
+        }
+        this.checked = !this.checked;
+        // Event emission and formValue sync is handled by @Watch('checked')
+    }
+    syncFormState() {
+        safeSetFormValue(this.elementInternals, getCheckableFormValue(this.checked, this.value), getCheckableRestoreState(this.checked));
+        this.updateValidity();
+    }
+    isDisabled() {
+        return isFormControlDisabled(this.disabled, this.formDisabled);
+    }
+    updateValidity() {
+        if (this.nativeInput)
+            this.nativeInput.setCustomValidity(this.manualValidationMessage || this.validatorMessage || '');
+        syncNativeFormValidity(this.elementInternals, this.nativeInput);
+    }
+    _hasSlotContentDefault() {
+        this._slotDefault = hasDefaultLightDomContent(this.el);
+    }
+    /**
+     * Determina o texto a ser usado para acessibilidade quando não há label visível
+     */
+    getAccessibilityLabel() {
+        const hostAriaLabel = this.el.getAttribute('aria-label');
+        if (hostAriaLabel && hostAriaLabel.trim() !== '') {
+            return hostAriaLabel;
+        }
+        if (this.label && this.label.trim() !== '') {
+            return this.label;
+        }
+        if (typeof this.labelOn === 'string' &&
+            this.labelOn.trim() !== '' &&
+            typeof this.labelOff === 'string' &&
+            this.labelOff.trim() !== '') {
+            return `Alternar entre ${this.labelOff} e ${this.labelOn}`;
+        }
+        return 'Alternar seleção';
+    }
+    /**
+     * Verifica se o componente tem texto visível (via slot ou label)
+     */
+    hasVisibleText() {
+        return this._slotDefault || (this.label !== undefined && this.label !== null && this.label.trim() !== '');
+    }
+    getCssClassMap() {
+        return {
+            'br-switch': true,
+            icon: this.showIcon ?? this.hasIcon,
+            top: this.labelPosition === 'top',
+            right: this.labelPosition === 'right',
+            large: this.density === 'large',
+            small: this.density === 'small',
+            disabled: this.isDisabled(),
+        };
+    }
+    render() {
+        const hasVisibleText = this.hasVisibleText();
+        return (h(Host, { key: '4dd9e91f5d826b858d781b367f868ee29f47bb61', "aria-disabled": this.isDisabled() ? 'true' : null }, h("div", { key: '931d05d4b685a1dbab3b4240b8824ab755092046', class: this.getCssClassMap(), part: "container" }, h("input", { key: '3afd320438b534d364d2f74b385166f4da1570ff', part: "input", ref: (el) => (this.nativeInput = el), id: this.customId, type: "checkbox", name: this.name, checked: this.checked, disabled: this.isDisabled(), required: this.required, role: "switch", "aria-checked": this.checked ? 'true' : 'false', "aria-busy": this.isValidating ? 'true' : null, "aria-describedby": this.hasFeedbackSlot || this.manualValidationMessage || this.validatorMessage
+                ? `${this.customId}-feedback`
+                : null, "aria-errormessage": this.manualValidationMessage || this.validatorMessage || this.hasFeedbackSlot
+                ? `${this.customId}-feedback`
+                : null, onInput: this.handleCheckedInput, onChange: this.handleCheckedChange, onClick: this.handleClick, ...(!hasVisibleText ? { 'aria-label': this.getAccessibilityLabel() } : {}) }), h("label", { key: '591be3df7b30eddbb067238654159e38078fa3ff', part: "label", htmlFor: this.customId }, this._slotDefault ? h("slot", null) : this.label || ''), this.labelOn && this.labelOff && (h("div", { key: '3d7d008ac48f25b65509b0acda2c7854378b91d6', class: "switch-data", "data-enabled": this.labelOn, "data-disabled": this.labelOff, "aria-hidden": "true", part: "data" }))), h("div", { key: '44be45c093d338c06afe8e4259a0f73e15517307', id: `${this.customId}-feedback`, part: "feedback", hidden: !this.hasFeedbackSlot && !this.manualValidationMessage && !this.validatorMessage }, h("slot", { key: '9523f6a34a279ebd19b9a92b48fa6259ba9f0254', name: "feedback", onSlotchange: (event) => (this.hasFeedbackSlot = hasAssignedSlotContent(event.currentTarget)) }), !this.hasFeedbackSlot && (this.manualValidationMessage || this.validatorMessage) ? (h("br-message", { state: "danger", message: this.manualValidationMessage || this.validatorMessage })) : null)));
+    }
+    static get is() { return "br-switch"; }
+    static get encapsulation() { return "shadow"; }
+    static get delegatesFocus() { return true; }
+    static get formAssociated() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["switch.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["switch.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "disabled": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Desativa o switch, tornando-o n\u00E3o interativo."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "disabled",
+                "defaultValue": "false"
+            },
+            "required": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Se verdadeiro, o switch \u00E9 obrigat\u00F3rio e deve ser ativado antes que o formul\u00E1rio possa ser enviado."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "required",
+                "defaultValue": "false"
+            },
+            "validator": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "SwitchValidator",
+                    "resolved": "(value: boolean) => string | Promise<string>",
+                    "references": {
+                        "SwitchValidator": {
+                            "location": "import",
+                            "path": "./switch.types",
+                            "id": "src/components/switch/switch.types.ts::SwitchValidator",
+                            "referenceLocation": "SwitchValidator"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Regra s\u00EDncrona ou ass\u00EDncrona aplicada ao estado booleano do switch."
+                },
+                "getter": false,
+                "setter": false
+            },
+            "checked": {
+                "type": "boolean",
+                "mutable": true,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Define o estado de sele\u00E7\u00E3o do checkbox.\nSe definido como verdadeiro, o checkbox estar\u00E1 marcado. Caso contr\u00E1rio, estar\u00E1 desmarcado."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "checked",
+                "defaultValue": "false"
+            },
+            "customId": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Identificador \u00FAnico; gerado automaticamente quando omitido."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "custom-id",
+                "defaultValue": "generateUniqueId()"
+            },
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Texto descritivo.\nCaso um slot seja utilizado para fornecer um texto alternativo, o valor desta propriedade ser\u00E1 ignorado."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "label"
+            },
+            "labelPosition": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'right' | 'left' | 'top'",
+                    "resolved": "\"left\" | \"right\" | \"top\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Posi\u00E7\u00E3o do r\u00F3tulo em rela\u00E7\u00E3o ao switch."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "label-position",
+                "defaultValue": "'left'"
+            },
+            "labelOn": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Texto exibido quando o switch est\u00E1 ativado."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "label-on"
+            },
+            "labelOff": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Texto exibido quando o switch est\u00E1 desativado."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "label-off"
+            },
+            "hasIcon": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `showIcon`."
+                        }],
+                    "text": "Adiciona um \u00EDcone ao switch para indicar a mudan\u00E7a de estado."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "has-icon",
+                "defaultValue": "false"
+            },
+            "showIcon": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Exibe o \u00EDcone de estado. Quando informada, tem preced\u00EAncia sobre `hasIcon`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "show-icon"
+            },
+            "name": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Define o nome do switch, que \u00E9 utilizado para agrupar switches em formul\u00E1rios e identificar o campo.\nO valor \u00E9 obrigat\u00F3rio e deve ser fornecido para garantir o correto funcionamento em formul\u00E1rios."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "name"
+            },
+            "value": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Define o valor associado ao switch quando ele faz parte de um formul\u00E1rio nativo (`<form>`).\nEsse valor \u00E9 enviado com o formul\u00E1rio quando o switch est\u00E1 selecionado.\n**Nota:** Esta propriedade n\u00E3o deve ser utilizada para determinar se o switch est\u00E1 selecionado; para verificar o estado de sele\u00E7\u00E3o, use a propriedade `checked`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "value"
+            },
+            "density": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'large' | 'medium' | 'small'",
+                    "resolved": "\"large\" | \"medium\" | \"small\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Ajusta a \u00E1rea de intera\u00E7\u00E3o: `small` \u00E9 compacto, `medium` \u00E9 o padr\u00E3o e `large` \u00E9 mais espa\u00E7ado."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "density",
+                "defaultValue": "'medium'"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "_slotDefault": {},
+            "formDisabled": {},
+            "hasFeedbackSlot": {},
+            "manualValidationMessage": {},
+            "validatorMessage": {},
+            "isValidating": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "checkedChange",
+                "name": "checkedChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Use `input`/`change` e leia `event.target.checked`."
+                        }],
+                    "text": "Disparado depois que o valor do `checked` foi alterado."
+                },
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                }
+            }, {
+                "method": "brSwitchValidationChange",
+                "name": "brSwitchValidationChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Emitido ao iniciar e concluir a valida\u00E7\u00E3o customizada."
+                },
+                "complexType": {
+                    "original": "FormValidationChangeDetail",
+                    "resolved": "FormValidationChangeDetail",
+                    "references": {
+                        "FormValidationChangeDetail": {
+                            "location": "import",
+                            "path": "../../shared/utils/validator",
+                            "id": "src/shared/utils/validator.ts::FormValidationChangeDetail",
+                            "referenceLocation": "FormValidationChangeDetail"
+                        }
+                    }
+                }
+            }];
+    }
+    static get methods() {
+        return {
+            "checkValidity": {
+                "complexType": {
+                    "signature": "() => Promise<boolean>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<boolean>"
+                },
+                "docs": {
+                    "text": "Retorna `true` se o valor do switch for v\u00E1lido, caso contr\u00E1rio `false`.\nSe o switch for inv\u00E1lido, dispara um evento 'invalid'.",
+                    "tags": []
+                }
+            },
+            "reportValidity": {
+                "complexType": {
+                    "signature": "() => Promise<boolean>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<boolean>"
+                },
+                "docs": {
+                    "text": "Retorna `true` se o valor do componente for v\u00E1lido, caso contr\u00E1rio `false`.\nSe for inv\u00E1lido, exibe a mensagem de erro padr\u00E3o do navegador.",
+                    "tags": []
+                }
+            },
+            "setCustomValidity": {
+                "complexType": {
+                    "signature": "(message: string) => Promise<void>",
+                    "parameters": [{
+                            "name": "message",
+                            "type": "string",
+                            "docs": ""
+                        }],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Define uma mensagem de valida\u00E7\u00E3o customizada para o switch.\nSe a mensagem for uma string vazia, o erro customizado \u00E9 limpo.",
+                    "tags": []
+                }
+            },
+            "validate": {
+                "complexType": {
+                    "signature": "() => Promise<boolean>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<boolean>"
+                },
+                "docs": {
+                    "text": "Executa o validator do switch e retorna se o valor atual \u00E9 v\u00E1lido.",
+                    "tags": []
+                }
+            },
+            "getValidationState": {
+                "complexType": {
+                    "signature": "() => Promise<FormValidationState>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        },
+                        "FormValidationState": {
+                            "location": "import",
+                            "path": "../../shared/utils/form",
+                            "id": "src/shared/utils/form.ts::FormValidationState",
+                            "referenceLocation": "FormValidationState"
+                        }
+                    },
+                    "return": "Promise<FormValidationState>"
+                },
+                "docs": {
+                    "text": "Retorna um snapshot serializ\u00E1vel da Constraint Validation API.",
+                    "tags": []
+                }
+            },
+            "toggleChecked": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Inverte o valor da prop `checked`",
+                    "tags": [{
+                            "name": "deprecated",
+                            "text": "Atualize a propriedade `checked` diretamente."
+                        }]
+                }
+            }
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "checked",
+                "methodName": "checkedChanged"
+            }];
+    }
+    static get attachInternalsMemberName() { return "elementInternals"; }
+}